Register hand-maintained docs convention as referenced sources (0.4.11)#41
Merged
Merged
Conversation
dotagent now KNOWS about a richer hand-maintained documentation
structure (features, ops, deep dependency registries) and surfaces
it in the rendered adapters — without ever generating or overwriting
the content.
### Hard boundary (enforced by tests)
- All new paths declared as KIND_FILE (never KIND_GENERATED).
- All required=False (project opts in by creating the files).
- `regenerate_derived_files()` is asserted to NEVER write to any of
these paths, on a fixture with sentinel content verified unchanged.
- See docs/HAND_MAINTAINED_DOCS_CONVENTION.md for the spec verbatim.
### Schema additions (canonical_structure.py)
- Two new categories: CAT_FEATURE_DOCS (📑) and CAT_OPS (🔧).
- Project-root + single-repo tiers gain 15 new schema entries:
- docs/feature_master.md (entry-point index)
- docs/feature_master/FM-<id>-<slug>.md (templated per-feature)
- docs/db-impact-map-{master,tenant,vector}.md
- docs/redis-key-registry-{tenant,global,events}.md
- docs/bug-registry-{infrastructure,agents,orchestrator}.md
- docs/ARCHITECTURE.md (uppercase — coexists with architecture.md)
- docs/ops/ + service-registry, server-dependencies, tuning, tls-and-env
- Every entry's when_to_read text starts with HAND-MAINTAINED · so the
AI sees ownership at-a-glance.
### Manifest renderer (render/manifest.py)
- CAT_FEATURE_DOCS placed near top of nav (right after Business intent).
- CAT_OPS placed near Configuration.
- New _CATEGORY_PREFACE dict supports prefatory paragraphs for specific
category sections. Used for both new categories:
· Feature docs: explicit "Entry point for any feature work" pointer
directing the AI to feature_master.md → FM-###-<slug>.md, then
follow file-path refs into the deep registries.
· Ops: explicit "hand-maintained" reminder.
### Source registration (config.py)
- DEFAULT_CONFIG.sources.extra now lists all 15 hand-maintained paths
with appropriate `kind` (bug_registry / db_impact_map / redis_keys
/ architecture / generic) so the indexer picks them up if they exist.
- Silently skipped on projects that don't use this convention — no
spurious "missing source" warnings.
### Coexistence
- docs/service-registry.md (lowercase) remains GENERATED from git.yaml.
- docs/ops/service-registry.md is HAND-MAINTAINED process registry.
- Different paths, different concepts, no overlap.
- Single-file conventions (bug-registry.md, redis-keys.md, etc.) still
work — sharded variants are additive.
### Tests (67 new)
- tests/render/test_hand_maintained_docs.py:
· Every path is in schema with KIND_FILE for BOTH tiers
· No hand-maintained path can be KIND_GENERATED
· Every path renders in manifest, in correct category
· HAND-MAINTAINED marker preserved in render
· Feature docs section header + entry-point preface present
· regenerate_derived_files() never writes to these paths
(sentinel-content verification)
· DEFAULT_CONFIG.sources.extra registers all paths
### Doc
- docs/HAND_MAINTAINED_DOCS_CONVENTION.md — full spec, structure
table, dotagent's WILL/WILL NOT list, coexistence matrix,
verbatim source request preserved at bottom for posterity.
Full suite: 703 passed, 2 skipped.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Register a hand-maintained documentation structure as referenced sources. dotagent now KNOWS about feature docs / deep dependency registries / ops references and surfaces them in CLAUDE.md — without ever generating or overwriting them.
Hard boundary
Test
test_regenerate_derived_files_never_writes_hand_maintainedwrites sentinel content to every hand-maintained path, runs the full derived-files orchestrator, then asserts none of the paths appear in the write set AND sentinel content on disk is byte-for-byte unchanged.Structure registered
Rendered output
"📑 Feature documentation (hand-maintained)" section near top of CLAUDE.md (right after Business intent), prefaced with explicit entry-point pointer:
Every hand-maintained entry's description is prefixed
HAND-MAINTAINED ·. Dedicated "🔧 Operations" section fordocs/ops/*.Coexistence
docs/service-registry.mdgit.yamldocs/ops/service-registry.mdDifferent paths, different concepts. Single-file conventions still work; sharded variants are additive.
Test plan
tests/render/test_hand_maintained_docs.py— 67 tests (schema kind / category / render / marker / preface / write-boundary / config registration)Docs
docs/HAND_MAINTAINED_DOCS_CONVENTION.md— full spec, WILL/WILL NOT list, coexistence matrix, verbatim source request.Version
0.4.10 → 0.4.11Generated by Claude Code