Make the documents say what the product is now - #702
Merged
Conversation
Five places still described a product two releases old, and each was the file a reader would trust for exactly that fact. PRODUCTION-READINESS-SSOT.md was a list of v0.8.2 release blockers. Those are gone, so the file whose job is to be current taught the state of a release two versions back. Replaced with what the product claims and what enforces each claim; the old one is archived beside it rather than deleted, because its reasoning is what produced the product. SECURITY.md said CommitLore is pre-1.0. It is 1.0.1, and the sentence mattered -- it was in "supported versions", where a reader decides whether their release gets fixes. SPEC said guard "blocks re-proposal". Guard flags; it does not block, and at precision 44.8% / recall 22.0% an empty result is not a guarantee. ADR-0020 already said advisory and the table contradicted it. The README hero said an agent "must not revive a decision the repository already reversed". That is what the product is for, not what it enforces -- the same overclaim as the guard line, in the first thing anyone reads. Replaced with what it does: hand the agent the decisions before it edits. COMPATIBILITY.md explained why the hook records a version and pointed at #693 as open. #696 closed it -- installs now record a version-free path under `<data-root>/current` -- and the doc still told users the old design. Rewritten, including the part that has not changed: hooks installed before it stay pinned, and the installer cannot reach them. Limit: the file a reader trusts for a fact must hold the current fact Blast: system Undo: easy Certainty: firm Provenance: authored Record-Id: r-v102doc
CommitLore — record lintTrailers: clean — 5 commits in Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR. |
The documentation pass changed the hero from "an agent must not revive a decision the repository already reversed" on the same reasoning that removed SPEC saying guard blocks re-proposal. ADR-0022 is enforced by a dogfooding test, which went red, and it was right to. The two sentences are different kinds. "guard blocks re-proposal" is a claim about what the software does, and at recall 22.0 percent it is false. "an agent must not revive a decision the repository already reversed" is a statement of the norm this product serves -- the problem, not the guarantee. Both contain an absolute, which is what made them look alike. Only one is about the tool. Hero restored and the distinction recorded in ADR-0022, because the next pass over these files will read the same two sentences and see the same shape. Limit: a norm the product serves is not a capability the product claims Blast: system Undo: easy Certainty: firm Provenance: authored Record-Id: r-adr22nm
Four handoffs sat beside the current one, all written before v1.0.0. A reader opening docs/handoff finds five files and no way to tell which describes now -- the same failure the production-readiness SSOT had, in a directory instead of a file. Archived rather than deleted. Each records why a decision was made, and that reasoning outlives the state it described. The index says what each was about and what replaced it, so the answer costs one file rather than four. It also points at the SSOT for what the product claims: a handoff describes a moment and will go stale by design, which is exactly why they accumulate. Limit: a directory of handoffs needs one that is current and a name for the rest Blast: local Undo: easy Certainty: firm Provenance: authored Record-Id: r-hoffarc
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.
SSOT closeout step 3. Five places described a product two releases old, and each
was the file a reader would trust for exactly that fact.
docs/PRODUCTION-READINESS-SSOT.mdSECURITY.mdspec/SPEC.mdREADME.mdherodocs/COMPATIBILITY.md<data-root>/currentnowThe two that were more than staleness
Guard. "Blocks" and "flags" are different promises, and the table contradicted
the ADR that governs it. At 22% recall an empty guard result is not a guarantee
that nothing was re-proposed, which is exactly what "blocks" invites a reader to
believe.
The hook explanation. It told users the old design and pointed at an issue
that had closed. The rewrite keeps the part that did not change: hooks
installed before v1.0.2 stay pinned to their release, and the installer cannot
reach them — it has no way to know which repositories have hooks.
doctornamesthe repair.
Archived, not deleted
docs/archive-PRODUCTION-READINESS-SSOT-v0.8.1.md. Its reasoning is whatproduced the product; what made it wrong is that it was the current document.
38 tests passing across
readmeandspec-contract. Documentation only — nocode, no artifact change.