Documentation governance: establish the CacheRoute developer and maintenance handbook

[rickisba]

Context

CacheRoute is accumulating canonical contracts, domain models, compatibility paths, architectural decisions, runtime flows, configuration surfaces, and migration rules across:

• the root README;
• AGENTS.md;
• component READMEs;
• architecture RFCs;
• research documents;
• GitHub Issues and PRs;
• public Python modules and their tests.

The information is individually useful but increasingly difficult to discover as one coherent development reference.

A developer currently needs to reconstruct the repository from several sources before answering basic questions such as:

• Which package owns a concept?
• Is a path current, transitional, historical, or only planned?
• Which import path is stable?
• What fields, defaults, enums, and wire values are available?
• How is a model intended to be constructed?
• Which compatibility behavior must be preserved?
• Which tests prove that behavior?
• Which document is authoritative when two documents discuss the same topic?

The root README must remain a high-level project overview, so this information must not be copied into a large README section.

This Issue establishes a stable developer and maintenance handbook and makes handbook maintenance part of the repository's Agent governance.

Refs #137
Refs #157
Refs #159
Refs #178
Refs #179

Decision

Create one stable handbook entry point:

doc/developer-handbook/README.md

The handbook is a multi-file maintained manual, not one indefinitely growing Markdown file.

Use this structure:

doc/developer-handbook/
├── README.md
├── architecture-and-evolution.md
├── package-and-module-map.md
├── public-api-and-data-models.md
├── runtime-flows.md
├── configuration-and-interfaces.md
├── compatibility-and-migrations.md
├── development-and-validation.md
├── documentation-governance.md
└── glossary.md

This is documentation structure only. It does not create a functional repository-root directory or Python package.

Handbook role

The handbook is the stable discovery and maintenance entry point for developers and Agents.

It must:

• explain the repository in a consistent order;
• distinguish historical, current/transitional, target/approved, proposed, and deprecated structures;
• provide concise API and data-model reference;
• show minimal usable examples;
• link to detailed authoritative documents;
• identify tests proving each important boundary;
• explain how future changes must update the documentation.

It must not duplicate every detailed component document.

Each subject must have one detailed source of truth. The handbook summarizes that subject and links to its detailed owner.

Documentation authority map

The handbook README must contain a source-of-truth table covering at least:

• high-level project introduction: root README;
• package architecture and dependency direction: doc/architecture/package-architecture-rfc.md;
• maintained observability design: doc/architecture/observability-v1.md, once merged;
• developer navigation and public API usage: doc/developer-handbook/;
• component operation and compatibility behavior: current component README;
• deployment and environment setup: env/README.md and focused environment documents;
• temporary investigation and unresolved questions: doc/research/;
• historical milestones: doc/blog/;
• accepted but not yet implemented design: the relevant GitHub Issue until promoted to maintained architecture documentation.

Research notes must be labeled non-authoritative when a maintained architecture document exists.

Required handbook content

1. Handbook landing page

doc/developer-handbook/README.md must provide:

• intended readers;
• how to use the handbook;
• current release/development context;
• chapter index;
• source-of-truth matrix;
• quick links for common maintenance tasks;
• status legend;
• update expectations.

Use a stable relative URL so GitHub, local checkouts, and future documentation sites can reference the same path.

2. Architecture and evolution

architecture-and-evolution.md must describe:

• the historical root-component architecture;
• the current transitional repository;
• the accepted target src/cacheroute architecture;
• completed architecture phases;
• current active phase;
• approved future sequence;
• why compatibility paths still exist;
• which proposed paths are not yet implemented.

Every structure must be explicitly marked as one of:

• Historical
• Current
• Transitional
• Target / Accepted
• Proposed
• Deprecated

Do not present a target path as already implemented.

3. Package and module map

package-and-module-map.md must contain a table with at least:

• concept or responsibility;
• canonical package/module;
• current transitional implementation, where applicable;
• dependency direction;
• public or internal status;
• detailed design link;
• relevant governance test;
• migration status.

Cover all approved canonical responsibilities:

• contracts;
• runtime;
• topology;
• knowledge;
• cache;
• routing;
• observability;
• integrations;
• services;
• plugins;
• entrypoints;
• compat.

Also document important current root packages:

• scheduler;
• proxy;
• instance;
• kdn_server;
• client;
• core;
• store;
• model;
• UI;
• util.

Do not imply that an unimplemented target package exists.

4. Public API and data-model reference

public-api-and-data-models.md must document each currently supported canonical public module with:

• import path;
• owning package;
• stability level;
• intended use;
• non-goals;
• minimal copyable construction or import example;
• exported classes/functions/enums;
• important fields;
• defaults;
• validation rules;
• enum wire values;
• ID patterns;
• serialization behavior;
• compatibility aliases;
• focused tests.

Initial coverage must include all canonical modules present on the implementation baseline, including as applicable:

• cacheroute.runtime;
• cacheroute.topology;
• cacheroute.cache;
• cacheroute.routing;
• cacheroute.contracts.v1;
• cacheroute.observability;
• cacheroute.observability.v1;
• approved compatibility modules.

A module that has not merged into main must be labeled proposed or in review, not current.

Do not document private helpers as stable API merely because tests import them.

5. Runtime flows

runtime-flows.md must explain current real flows using concise sequence descriptions:

• client to Scheduler to Proxy to Instance to vLLM;
• Scheduler and KDN interaction;
• knowledge registration and lookup;
• text versus KVCache injection;
• cache artifact and operation flow;
• Instance capability registration;
• observability flow and its current limitations;
• Legacy compatibility paths.

For each flow, identify:

• participating components;
• request/model types;
• important IDs;
• current entrypoints;
• observable outputs;
• failure/fallback boundaries;
• tests or demos;
• capabilities not yet implemented.

Do not describe future instrumentation as active behavior.

6. Configuration and interfaces

configuration-and-interfaces.md must catalog stable developer-facing configuration:

• environment variables;
• configuration keys;
• CLI flags;
• service ports;
• HTTP endpoints;
• request/response fields;
• SSE metadata;
• Runtime Profile values;
• injection modes;
• important feature switches.

For each entry include:

• owner;
• type;
• default;
• allowed values;
• scope;
• effect;
• compatibility notes;
• source file;
• validation path.

Do not copy every local constant or function-local variable.

7. Compatibility and migrations

compatibility-and-migrations.md must document:

• old path;
• canonical path;
• shim type;
• object-identity requirement;
• wire-compatibility requirement;
• tests;
• removal condition or milestone;
• known transitional package/wheel behavior.

Cover normal imports, dynamic/module-string references, source-checkout bootstraps, packaging, editable installs, wheel installs, service entrypoints, and Markdown links where relevant.

8. Development and validation

development-and-validation.md must provide:

• supported development setup;
• source-checkout import expectations;
• editable-install expectations;
• wheel-build and isolated-install expectations;
• focused test map by package;
• governance tests;
• full regression groups;
• how to classify environment-blocked tests;
• PR evidence requirements.

Commands must remain individually auditable and use Python 3.

9. Documentation governance

documentation-governance.md must define when a handbook update is mandatory.

A handbook update is required in the same PR when changing any of:

• public import path;
• public class, function, protocol, enum, or constant;
• Pydantic/dataclass field;
• default value;
• validation rule;
• serialization behavior;
• enum wire value;
• ID format;
• request/response/SSE field;
• endpoint;
• CLI option;
• environment variable;
• configuration key;
• package ownership;
• dependency direction;
• compatibility path;
• migration state;
• runtime flow;
• installation or validation command.

A pure internal refactor may omit a handbook update only when the PR explains why no documented behavior changed.

The handbook must not be updated with speculative APIs before their Issue is approved and implementation exists.

10. Glossary

glossary.md must define stable project terminology and variable vocabulary, including:

• Runtime Profile;
• Legacy / v1 / test/mock;
• KDN;
• knowledge ID;
• artifact ID;
• endpoint ID and generation;
• compatibility profile;
• CacheOperationTask and task ID;
• trace, request, correlation, stage, and operation IDs;
• injection mode;
• prediction, desired, observed, measured, actual, inferred, and Legacy-projected values;
• public, canonical, transitional, compatibility, deprecated, and proposed.

The glossary must document externally meaningful fields and identifiers, not function-local variables.

AGENTS.md requirements

Add a focused documentation-governance section to AGENTS.md.

It must instruct every Agent to:

1. Read the handbook landing page and the relevant detailed chapter before non-trivial changes.
2. Check whether the change affects a documented public or structural surface.
3. Update the handbook in the same PR when required.
4. Update only the relevant chapter rather than rewriting the full handbook.
5. Preserve one authoritative detailed source and link to it instead of copying large sections.
6. Mark structures accurately as historical, current, transitional, accepted, proposed, or deprecated.
7. Never document an unmerged feature as current.
8. Include handbook impact in the PR summary.
9. State explicitly when no handbook update is necessary.
10. Keep root README changes minimal.

Add a short Agent checklist:

• Public API changed?
• Fields/defaults/wire values changed?
• Config/CLI/environment/endpoint changed?
• Package ownership or dependency direction changed?
• Compatibility or migration state changed?
• Runtime flow changed?
• Validation commands changed?

Any yes requires a handbook update.

Root README

Make only minimal changes to the existing root README:

• add a Developer Handbook link to the existing top navigation;
• add one entry to the existing Documentation table.

Link to:

doc/developer-handbook/README.md

Do not remove, replace, or rewrite the current project introduction, architecture overview, setup guide, deployment content, or component documentation links.

Governance tests

Add documentation governance proving:

1. Every required handbook chapter exists.
2. The handbook landing page links to every required chapter.
3. The root README links to the stable handbook entry.
4. AGENTS.md links to the handbook and contains the mandatory synchronization rule.
5. All local Markdown links resolve.
6. Every canonical package explicitly configured in pyproject.toml is covered by the package/module map.
7. Every canonical module under src/cacheroute with a non-empty explicit __all__ is mentioned in the public API catalog.
8. Historical, current/transitional, target, proposed, and deprecated statuses use the documented vocabulary.
9. No handbook page claims that a currently absent package is implemented.
10. Documentation files remain repository-only and are not added to the wheel.

Prefer focused AST/text governance over introducing a documentation framework.

Keep allowlists narrow and reviewable.

Boundaries

The handbook may link to source files and tests but must not require imports or runtime package loading to render.

All documentation must work in:

• GitHub;
• a source checkout;
• an installed source archive where documentation is present.

No network service is required to read it.

Non-goals

• runtime behavior changes;
• package, module, service, or directory migrations;
• new public APIs;
• changes to request or response behavior;
• observability instrumentation;
• external documentation hosting;
• MkDocs, Sphinx, Docusaurus, or another documentation framework;
• generated API websites;
• documenting every private helper or local variable;
• replacing component READMEs;
• rewriting the root README;
• moving the existing doc hierarchy;
• changing project dependencies;
• changing package discovery;
• installing documentation in the Python wheel.

Required validation

Run and report exact results:

python3 -m compileall -q src test
python3 -m pytest -q test/test_repository_governance.py
python3 -m pytest -q test/test_namespace_layout.py
python3 -m pytest -q test/test_source_checkout_imports.py
python3 -m pytest -q -s test/test_wheel_install.py -m "not network"
git diff --check

Also verify:

• every handbook relative link from GitHub-style Markdown resolves;
• root README introduction is unchanged;
• root README only receives the minimal handbook navigation/table additions;
• AGENTS.md contains no conflicting source-of-truth rule;
• documentation remains absent from wheel top-level packages;
• existing component README links remain valid.

Acceptance criteria

• doc/developer-handbook/README.md is the stable handbook entry point.
• The handbook is split into the approved maintainable chapters.
• Historical, current, transitional, target, proposed, and deprecated structures are clearly distinguishable.
• All currently implemented canonical packages are represented.
• Important transitional root components are represented.
• Stable public imports have minimal usable examples.
• Public fields, defaults, validation rules, enums, wire values, IDs, configuration, CLI, endpoints, and compatibility paths are cataloged.
• Private local variables are not treated as public documentation.
• Every major runtime flow links to its source and validation path.
• Existing detailed documents remain authoritative for their focused subjects.
• AGENTS.md requires same-PR handbook maintenance for relevant changes.
• Root README contains a stable Developer Handbook link with no large architecture rewrite.
• Governance detects missing handbook chapters, broken links, missing package/API coverage, and accidental wheel inclusion.
• Root README introduction remains unchanged.
• Runtime behavior, dependencies, packaging discovery, and public APIs are unchanged.

[rickisba]

Future handbook implementation should represent #182 according to its actual merge state.

Before merge, Scheduler-to-Proxy trace propagation and Proxy-local canonical stages are In review or Proposed. After merge, update only the relevant public-helper, configuration, runtime-flow, compatibility, and validation sections. The root README remains limited to the handbook link required by #180.