Skip to content

docs: introduce LingTai ANATOMY+CONTRACT navigation and interface system - #224

Merged
huangzesen merged 1 commit into
mainfrom
feat/anatomy-contract-system
Aug 3, 2026
Merged

huangzesen merged 1 commit into
mainfrom
feat/anatomy-contract-system

Conversation

@huangzesen

Copy link
Copy Markdown
Collaborator

Summary

Introduces the LingTai kernel's distributed code navigation (ANATOMY) and interface definition (CONTRACT) system into this repo, adapted to its size.

The repo already had three hand-written ANATOMY.md files in an ad-hoc shape. This PR rewrites them to the canonical LingTai convention and completes the paired system: a root contract-of-contract, three governed component contracts, and a mechanical drift checker + architecture-document validation suite.

What changed

  • Root ANATOMY.md — rewritten with YAML frontmatter (related_files + maintenance), navigation model, five-section body, link/pairing semantics, and verified file:line citations throughout.
  • Root CONTRACT.md (NEW) — the contract-of-contract: design principles (artifact-first responses, source_type dispatch, backend port isolation, packaged-skills-as-capability, thin wrappers), Core/Ports/Adapters architecture foundation, governed-component list, child template + pairing/ownership/versioning rules.
  • src/spedas_agent_kit/ANATOMY.md — rewritten to convention; stale workflow citations corrected (search_data_sources 816→824, compare_sources 848→856, plan_observation 870→1170, create_analysis_bundle 1016→1351) and previously-uncited anchors added (_normalize_source_type server.py:1852, _wrap_data_payload :1927, serve() :2796, etc.).
  • src/spedas_agent_kit/CONTRACT.md (NEW) — the package facade contract: the 13 base + 8 compat MCP tool surface, artifact-first {status, file_path, stats} response shape, structured-error contract, source_type dispatch, lazy backend imports.
  • src/spedas_agent_kit/backends/ — ANATOMY.md rewritten; CONTRACT.md (NEW) defines the vendored CDAWeb/PDS/SPICE data-backend Port contract.
  • src/spedas_agent_kit/resources/ — ANATOMY.md + CONTRACT.md (NEW) for the packaged-skills capability: skill catalog, event presets, provenance, schemas, index rendering.
  • scripts/check_anatomy_drift.py (NEW) — adapted from the LingTai kernel drift checker: stdlib-only citation-rot scanner over every ANATOMY.md; report mode + --check gate for CI.
  • tests/test_architecture_documents.py (NEW) — validates frontmatter, repo-relative dup-free related_files, reciprocal ANATOMY/CONTRACT pairing, root CONTRACT listing each governed child exactly once, child root_contract + paired anatomy, and no empty stub sections. Minimal frontmatter parser — no PyYAML dependency.

Validation

  • tests/test_architecture_documents.py: 11 passed.
  • scripts/check_anatomy_drift.py --check: zero drift across 4 ANATOMY files.
  • Existing test_server/test_resources/test_config: untouched by this doc-only change (pre-existing spiceypy env gap unrelated to this PR).

Notes

  • This is docs/governance only — no runtime code behavior changes.
  • Component anatomy line counts (118–134) exceed the nominal ~80 guidance because the mandated verified-citation coverage for this three-backend facade needs room; the kernel's own root anatomy is 299 lines under the root-as-exception rule.

@huangzesen
huangzesen merged commit 5729e85 into main Aug 3, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant