docs: publish requirements baseline, ADR process, and a reference gate - #45
Merged
Conversation
…ules The ADR process was only fully described in an uncommitted planning document, so a reader of the repo could not follow it. The status legend also advertised a private staging folder as the official drafting location, and the index pointed at an uncommitted tracker. Numbering is now claimed by adding a row to the index table before any ADR file exists. Because that table is a single file with one row per number, two people claiming the same number produce a merge conflict — uniqueness is serialised by merge rather than by convention. Also records that layer-based numbering closed at 021 and is allocation-order from 022 onward, which has been the de facto behaviour since; and names the areas that do not accept outside proposals, so nobody spends effort on a decision that was never open. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
The amendment stated the pre-commit config held four hooks. That was wrong on the date it was written: two of them had been moved out of the committed config ten days earlier, leaving two. The design pass was working from a stale picture. Corrected in place with a dated errata note rather than a further amendment, because this is an error of fact rather than a change of decision — and a silent edit to a dated amendment would read as history rewriting. The decision, its cascade, and Confirmation #2 are unaffected: append the gitleaks entry, do not overwrite, do not bootstrap the framework. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
Two corrections to conventions this file records. The attribution trailer no longer carries the harness version. It is an implementation detail of the tool rather than useful provenance — the Model line already answers which intelligence produced the commit — and in practice the version was often unobtainable from inside a session, which invited exactly the guessing the convention forbids. Commits already carrying a version stay as they are; history is not rewritten. The ADR section now points at docs/adr/README.md instead of restating the template. That file already defined the project template more accurately, and two copies of a spec is the drift failure this project keeps hitting. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
The docstring cited two files in an uncommitted scratch folder to explain an authoring convention. A reader of the repo cannot resolve either path, and the convention itself is local to the maintainer rather than something a contributor needs. The docstring now describes what the tests do. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
The comment advertised a banned-terms step. The job has six steps and none of them is that; it was never added, or was removed without the comment following. It also omitted three of the four freshness gates that are there. A comment describing checks that do not run is worse than no comment — it reads as coverage the pipeline does not have. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
ADR-001 linked its code sketches as [adr-001-examples.md](adr-001-examples.md). That file was never committed at any path, so the link had rendered as a clickable 404 since ADR-001's first commit — in the first ADR the reading order sends people to. Line 128 even annotated the caveat while keeping the link. The sketches are inlined verbatim under More Information. No decision changes; this content was always meant to be part of the ADR's supporting detail, and a note records that the provider set shown predates D-013-1 and D-013-7 so the comparison still reads as it did when the choice was made. The gate is the point. A path written in this repo must resolve for someone who has only cloned this repo, and two classes break that: links whose target does not exist, and prose references to the private sibling directories work/, plan/ and archive/. Both have happened repeatedly, so it is now enforced rather than remembered — a pre-commit hook for fast feedback and a CI lint step as the gate that cannot be skipped. The check found a second live defect on its first run: docs/manifest-versions.md linked ADR-017-eval-framework.md, which is named ADR-017-evaluation-framework.md. Also fixed here. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
The 36 functional and non-functional requirements the ADRs are written against existed only in an uncommitted planning document, so no reader of this repo could resolve a single FR reference. The ADRs cite 21 of them. Traceability now runs one way. Requirements state what the system must do; ADRs state how, and cite the requirement they satisfy. The requirement text names no ADR. Those citations had accumulated because design decisions were cascaded back into the requirements and left their provenance inline, which inverted the dependency and left references resolving nowhere public. Three requirements were rewritten rather than copied, because they were wrong: * FR-2 said the knowledge graph is extracted by LLM analysis, which FR-10 explicitly denies and the README point-of-view contradicts. It predates the parsing-strategy decision. * FR-3 said scaffold, the word deliberately replaced by source everywhere else, including the repository description. * NFR-4 claimed CI runs both TypeScript and Go evaluation paths. Go is v1.1. Every requirement now carries a v1 or v1.1 marker, so paths and flags named by unbuilt requirements read as declared scope rather than as broken references. A revision history records the changes made during design review and closes at this commit; from here the git history of the file is the record. It notes that FR-22, NFR-2 and NFR-5 moved from v1 to v1.1, each with a narrower capability shipped in their place. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
FR-20 named a directory that does not exist. It claimed the run manifest and structured logs are written under runs/<timestamp>/. They are written into the output directory: <out>/manifest.json and <out>/logs.jsonl, per logging_config and the README. There is no runs/ directory in the repo or at runtime. This was wrong in the original requirement and survived the extraction because that pass checked requirements against each other and against the point-of-view section, but did not verify the paths they name against the code. Every other path claimed by a v1 requirement was checked and does exist. FR-27 is confirmed v1 and restated precisely. All three clauses hold, but the first one holds by a different mechanism than the wording implied: the guard rejects an output directory that is the working directory or an ancestor of it, rather than constraining writes to a fixed path. With FR-20 corrected, the claim that all artefacts land inside the output directory is now accurate. No revision-history entry: that section closes at this document's first commit, and the git history is the record from there. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
The new script was committed unformatted and would have red-failed the CI lint job on ruff format --check. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
CONTRIBUTING opened straight into commit conventions. A reader arriving with an idea had no way to learn that the project is solo-maintained, that some areas are closed to outside proposals, or that architectural changes go through a reservation step before any file is written. They would find that out by having work declined. The section asks for an issue before effort is invested, and says why: scope agreement, not process. It layers with the ADR flow rather than competing with it, since docs/adr/README.md already states that a PR adding an ADR without a reserved number will be declined. CONTRIBUTING is the outer gate; that file is what happens once scope is agreed. Framing is deliberate. Solo-maintained with a stated way in reads as a maintainer with standards; an absence of contributors reads as neglect. The facts are identical, and this project holds that line everywhere else. AI-assistant: Claude Code (Claude Opus 5 via Anthropic) Model: claude-opus-5
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
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.
Publishes the requirements baseline and the ADR contribution process, and adds a CI gate for
unresolvable references. Ten commits, all documentation and one new check script — no behaviour
change.
Why
Requirements and ADR conventions existed only in uncommitted planning documents. A reader with just
this repository could not resolve a single
FR-nreference — and the ADRs cite 21 of them — norfollow the process for proposing an ADR.
What changed
docs/requirements.md(new) — 36 functional and non-functional requirements, each marked[v1]or
[v1.1]so that paths and flags named by unbuilt requirements read as declared scope rather thanbroken references.
Traceability now runs one way: requirements state what the system must do and cite no ADRs; ADRs
state how and cite the requirement they satisfy. The previous FR→ADR citations had accumulated
because design decisions were cascaded back into the requirements source and left their provenance
inline, inverting the dependency.
Four requirements were rewritten rather than copied, because they were wrong:
the README's point-of-view section contradicts it; the text predates the parsing-strategy decision.
the repository description.
runs/<timestamp>/directory that does not exist. The run manifest andstructured logs are written into the output directory.
A revision history records the changes made during design review and closes at the first commit;
from there the file's git history is the record.
docs/adr/README.md— the ADR process, which was only fully described in an uncommitteddocument. Numbering is now claimed by adding a row to the index table before any ADR file exists;
because that table is one file with one row per number, two people claiming the same number produce
a merge conflict, so uniqueness is serialised by merge rather than by convention. Also adds the
status lifecycle, the acceptance criteria a reviewer applies, and the areas that do not accept
outside proposals.
CONTRIBUTING.md— a "Before you start" section. The file previously opened directly on commitconventions, so a reader arriving with an idea would have discovered the reservation requirement and
the closed areas only by having work declined. Also simplifies the AI attribution trailer and points
ADR guidance at
docs/adr/.scripts/check_no_workspace_refs.py(new) — fails on markdown links whose target does not exist,and on references to private sibling directories that are not part of this repository. Wired into
pre-commit and the CI lint job. It found two live defects on its first run, both fixed here:
ADR-001linked its code sketches as a relative link to a file that was never committed at anypath — a clickable 404 since that ADR's first commit. The sketches are now inlined.
docs/manifest-versions.mdlinkedADR-017-eval-framework.md; the file isADR-017-evaluation-framework.md.Also fixed — a wrong hook count in ADR-023's D-023-1 amendment (corrected in place with a dated
errata note; the decision and its Confirmation were never affected), a CI comment describing a lint
step that does not exist, and a test docstring citing paths outside this repository.
Verification
All six CI jobs green: Lint, Unit, Integration (external), both Eval corpora, Cross-corpus Report.
Locally:
ruff check,ruff format --check(209 files),mypy(205 source files), and the newreference gate all clean.