[rickisba]

Motivation

• PR docs: enforce RFC package architecture for future development #160 made Section 18 of AGENTS.md normative but left Sections 1–17 with unqualified current-root path examples that contributors could misinterpret as permanent package-placement guidance.
• The change reconciles short-term repository layout guidance with the accepted cacheroute.* RFC so contributors follow a single authoritative source without beginning any code migration.
• Preserve existing research, validation, and compatibility guidance while making it clear which root packages are transitional and which package owners are authoritative for new work.

Description

• AGENTS.md: updated version-date to 26-07-30, labeled scheduler/, proxy/, instance/, and kdn_server/ root packages and strategy modules as transitional compatibility locations, corrected stale path examples (e.g. kdn/... → kdn_server/..., client.py/perf_client.py → client/client.py/client/perf_client.py, demo names → test/demo_*.py), and added the decision rule for fixes vs new cross-component work vs migrations.
• doc/architecture/package-architecture-rfc.md: added a status header linking Issue #159, Issue #157, PR #158, and PR #160 and noting coordination with Issue #141, clarified ownership semantics (contracts, domain ports, integrations, services, entrypoints, plugins, observability, UI assets, crates/), added an audited “Current layout versus target ownership” mapping for core, scheduler, proxy, instance, kdn_server, client, store, model, util, UI, test, scripts, env, and log, and added an Architecture decision checklist with the full operational-path audit scope.
• doc/architecture/README.md: expanded the index to reference the RFC, the migration Epic, the Phase A audit, and the root README's role.
• No runtime code, packaging configuration, tests (except documentation-governance link corrections), Docker, CI files, or top-level directories were added, removed, or migrated; no placeholder cacheroute.core or speculative packages were created.
• Files changed: AGENTS.md, doc/architecture/README.md, doc/architecture/package-architecture-rfc.md.
• Refs: Issue #159, Issue #157, Issue #141.

Testing

• Ran git diff --check which passed.
• Ran the repository governance assertion script (the requested Python snippet) which passed (architecture documentation reconciliation: PASS).
• Ran python3 -m pytest -q test/test_repository_governance.py which returned 6 passed, 1 failed with the failure due to the existing root-discovery check treating the present doc/architecture directory as an unconfigured namespace (doc.architecture), not caused by runtime or packaging changes in this PR.
• Ran python3 -m pytest -q test/test_namespace_layout.py which returned 4 passed, 1 failed with the failure due to the isolated test process lacking a runtime dependency (numpy) when importing client.client, and not caused by this documentation-only change.
• Confirmed git diff --name-only includes exactly the three documentation files changed and git diff --numstat -- AGENTS.md is 35 13 AGENTS.md, confirming a scoped edit rather than a whole-file rewrite; README.md and runtime code are unchanged.

Refs #159
Refs #157
Refs #141

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1e2f8079f9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Account for omitted installed packages

Complete this supposedly tree-audited mapping with dispositions for data and doc: pyproject.toml lines 49–51 currently install data, data.CacheRoute_dataset, doc, and related namespaces, and the Phase A inventory also records them, but neither appears in this table. A later migration using this authoritative map therefore has no owner or phase for removing these top-level wheel packages—and may either leave them in the final wheel or drop runtime data without the required package-data audit.

AGENTS.md reference: AGENTS.md:L600-L611

Useful? React with 👍 / 👎.