docs(catalog): converge doc tooling with canonical ways + retire operations mode#535
Merged
Conversation
The doc catalog mixed two axes onto one slot. "Operations" was added as a fifth Diátaxis mode (letter O), but operations is an audience facet — it answers who reads a page and which subsystem, which the domain axis already captures. The four canonical modes are a closed 2x2 of reader posture; there is no fifth quadrant. The 11 self-host pages are how-tos, reference, and explanation that happen to be about running the platform. Retiring O exposed a deeper flaw: the old id <digit>.<LETTER>.<serial> baked mode (a mutable attribute) into the middle of the identity and scoped serials to (domain, mode), so re-classifying a page forced its part number to change. A handle that mutates when you re-shelve the part is not a handle. Adopt octet-style DD.NNN.P: identity is DD.NNN (domain band + domain-scoped serial, assigned once), and the Diataxis pole P trails as a classifier that must agree with mode: but is not part of the key. Domain-scoped serials let the linter treat any collision as a real clash. - re-tag 11 self-host pages to true Diataxis mode (domain unchanged) - drop operations from doclint.py MODE_LETTER; add check_duplicate_ids - renumber all 49 catalog ids to DD.NNN.P (ids derived from domain+mode) - update cli/mcp/fuse/schema generators to emit new ids - amend ADR-908: identity-vs-classifier rationale + 2026-06-16 correction
…ed guard Re-vendor the catalog linter from the agent-ways canonical tools and adopt the gitignore-aware retired-range guard, closing the gap between this repo (the reference implementation) and the framework model it seeded. - re-vendor docs/scripts/doclint.py verbatim from canonical (901aaa1): check_retired_refs enumerates via `git ls-files` (honors .gitignore, rglob fallback off-git) instead of walking the tree, so gitignored corpora and scratch are excluded while authored docs stay enforced - re-vendor docs/scripts/doc; keep the single local citation (ADR-908, since ADR-302 resolves to the multimodal-ingestion ADR in this repo's graph) - enable legacy.retired:true — enforce ADR-900's vacated 1-99 range - gitignore raw audit/scan byproducts (ways/**/*-raw.json) - add .claude/ways/kg/documentation way — discloses the typed-graph model, DD.NNN.P scheme, tooling, and gotchas on docs/ edits - ADR-908: note this repo seeded canonical's documentation model; warn against adding ADR-302 as a false local graph edge Lint 0/0 (docs + ADRs enforced). Upstream fix: agent-ways PR #131.
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
1 participant
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.
Brings the documentation catalog into structural conformance with the
canonicalized agent-ways documentation model. Two commits:
retire operations mode; adopt DD.NNN.P catalog ids(prior)operations/Opseudo-mode — the four Diátaxis modes are a closed 2×2; operations is an audience facet carried bydomain, not a fifth mode.DD.NNN.Pids: identity isDD.NNN(assigned once); the Diátaxis polePtrails as a classifier, so re-shelving a page never churns its number.converge doc tooling with canonical ways; enable retired guard(this session)docs/scripts/doclint.pyverbatim from canonical (agent-ways901aaa1, PR bug: kg vocab config fails with authentication error #131):check_retired_refsenumerates viagit ls-files --cached --others --exclude-standard(honors.gitignore, rglob fallback off-git) instead of walking the tree — gitignored corpora/scratch excluded, authored docs still enforced.docs/scripts/doc; one deliberate local delta — the catalog citation staysADR-908(hereADR-302resolves to the multimodal-ingestion ADR).legacy: {retired: true}— enforce ADR-900's vacated 1–99 range.ways/**/*-raw.json)..claude/ways/kg/documentationway — discloses the typed-graph model,DD.NNN.Pscheme, tooling, and gotchas ondocs/edits.ADR-302as a false local graph edge.Structural conformance (verified)
doclint.py --check --enforce-adrs→ 0 errors, 0 warnings (49 catalog pages + 120 ADRs).ADR-042in a tracked ADR fails--check.Upstream collaboration: the gitignore-aware scan fix was negotiated into canonical (agent-ways PR #131) rather than forked locally.