docs: the orientation documents froze on 2026-08-04, and CRAF'd had no contract - #302
Merged
Polichinel merged 1 commit intoAug 30, 2026
Conversation
…o contract /review-base-docs found the mechanical layer healthy — validate_docs.sh passes, every doc a test can reach is accurate — and the human layer stale in exactly the places nothing reads. Five findings, four fixed here. **The CRAF'd manager had an intent contract in no form at all.** No CIC file and no class docstring, while its line-for-line twin has a 189-line contract. ADR-006 mandates one for orchestration and state-owning classes; the CIC README names both categories. The partner package was cloned and the contract was not. It is written as a DELTA, deliberately. Two 189-line documents describing one behaviour is not redundancy, it is two things that can disagree — which is C-75 verbatim, where this directory's files asserted opposite things about the same call for weeks. The new file states purpose, what it inherits, and a table of what differs. If the managers ever diverge behaviourally, C-33's extraction trigger has fired and the form should be revisited with the code. Registering it in _CIC_SUBJECT made the collaborator guard fire immediately: the document named the sibling CLASS in backticks, which crafd.py never references. The guard was right and the backticks were wrong — a markdown link to a sibling DOCUMENT is not a claim that the class reaches for a collaborator. Fixed by saying what was meant, not by exempting the file. **Both orientation documents omitted delivery/findability.py**, which shipped 2026-08-18. README and role_and_seams.md — the two files a new contributor opens first — both last touched 2026-08-04. Now listed in both, and a new guard asserts delivery/ stays complete in both. Mutation-proven: deleting the line reddens it. Scoped to delivery/ because it is the one directory both docs enumerate exhaustively; firing on the README's deliberate contract/wire/ abbreviation would be crying wolf (ADR-014 §3). **The sibling CIC was four days stale** — reviewed 2026-08-21, class changed 2026-08-25. It covered findability and TornRunError but not observed_through, the #297 boundary stamp. That gap was mine. Recorded, review date moved. **CLONING.md's "sixteen lines differ" is now fourteen** — the third time that number went stale, in the paragraph that warns it will. Removed rather than corrected; the diff command beside it is the source of truth and a number next to it is a liability. Two audit findings NOT fixed, and one of them was my error: - **ADR-004 does have trigger conditions.** The audit reported none; it has five. What it does not have is an owner. Reading them produced a better finding: at least three have FIRED — downstream systems depend on this repo, breaking changes now incur real coordination cost (views-models#403 took eight days; #439 is open), and ADR-013 §10 pins bytes across time. Recorded on the ADR with evidence. Writing the successor is an architectural decision, not a docs fix. - **pyproject's python range stays wrong.** Narrowing >=3.11,<3.15 to <3.12 is one line and correct, but it invalidates poetry.lock and forces a full re-resolve that would move pyarrow off the 16.1.0 the ADR-013 §10 fixtures pin (C-72). Attempted, measured, reverted. #295 owns it; the README now states the truth, which was the safe half. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Polichinel
deleted the
docs/story4-orientation-docs-and-the-crafd-contract
branch
August 30, 2026 15:03
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.
Story 4 of the sprint. Acts on
/review-base-docs.The audit's shape: mechanically healthy, humanly stale.
validate_docs.shpasses and every doc a test can reach is accurate. What drifted is precisely what no test read.Fixed
CRAF'd had an intent contract in no form — no CIC file, no class docstring — while its line-for-line twin has 189 lines of one. ADR-006 mandates one for orchestration and state-owning classes.
Written as a delta, not a copy. Two long documents describing one behaviour is not redundancy, it is two things that can disagree — C-75 verbatim, where this same directory's files asserted opposite things about one call for weeks.
Registering it made the collaborator guard fire immediately: my document named the sibling class in backticks, which
crafd.pynever references. The guard was right. A markdown link to a sibling document isn't a claim the class reaches for a collaborator — fixed by saying what I meant, not by exempting the file.Both orientation documents omitted
delivery/findability.py(shipped 2026-08-18). README androle_and_seams.md— the two files a newcomer opens first — both froze on 2026-08-04. Now listed in both, plus a guard that keepsdelivery/complete in both. Mutation-proven: deleting the line reddens it. Scoped todelivery/because it's the one directory both enumerate exhaustively.The sibling CIC was 4 days stale — missing
observed_throughfrom #297. That gap was mine.CLONING.md's "sixteen lines differ" is now fourteen — third time that number went stale, in the paragraph warning it would. Removed rather than corrected; the
diffcommand beside it is the source of truth.Not fixed — including one audit error of mine
ADR-004 does have triggers. My audit said none; it has five. Reading them gave a better finding: at least three have fired — downstream systems depend on this repo, breaking changes now cost real coordination (views-models#403 took 8 days, #439 open), ADR-013 §10 pins bytes across time. Recorded on the ADR with evidence. Writing the successor is an architectural decision, not a docs fix. What it genuinely lacks is an owner.
pyproject's python range stays wrong (#295). Narrowing it is one correct line that invalidates
poetry.lockand forces a re-resolve which would movepyarrowoff the 16.1.0 the §10 fixtures pin (C-72). Attempted, measured, reverted. The README now states the truth — the safe half.Verification
510 passed, 3 skipped, 40 xfailed.
validate_docs.shexit 0. ruff clean. New guard mutation-proven.🤖 Generated with Claude Code