Docs/catch up planning vocabulary - #145
Merged
Merged
Conversation
A lookback prompted by the observation that development had outrun introspection. It had — in the doc layer specifically. CLAUDE.md is the file every agent session reads first, and it contained **zero** mentions of `task ac`, `audit finding`, criterion states, `tracked`, or `settled`. An agent following it would hand-edit markdown for exactly the fields the tool now owns, which is the practice all of this work retired. Worse, it documented `task complete` as an unconditional verb — it now REFUSES a task with an unexplained unmet criterion, so an agent scripting against the old contract would hit an exit 11 the guide gave no warning about. Both surfaces and both vocabularies are now in it. ARCHITECTURE.md gains the two patterns that are genuinely architectural rather than incidental: a word meaning the same thing in two places is spelled once (the shared resolution pool, the overlap-not-subset modelling, the delegation of glyphs), and a state the tool cannot write is a state nobody can be held to. ADR-0007 records the vocabulary decision itself. It had been settled properly — with alternatives weighed and written down — but only inside a completed task's body, which is not where anyone looks for a load-bearing format decision. It covers the checkbox-plus-suffix representation, the shared pool, `tracked` replacing `landed`, and the two write-time invariants, with the rejected alternatives. Also closes a gap the lookback found in the code: the TUI's completion refusal was claimed in a commit message and asserted by nothing. The shared seed repo's tasks carry no acceptance criteria, so no test ever exercised the path. It now has one, with its own fixture so the seed stays untouched, covering the refusal, the error flash, and the file being left alone. Coverage was checked and is not the problem: 82–90% across domain, core, store, cli, tui, theme, and wire.
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.
No description provided.