Skip to content

docs: publish requirements baseline, ADR process, and a reference gate - #45

Merged
gvsambhu merged 10 commits into
mainfrom
dev/docs-14-requirements-and-standards
Aug 7, 2026
Merged

docs: publish requirements baseline, ADR process, and a reference gate#45
gvsambhu merged 10 commits into
mainfrom
dev/docs-14-requirements-and-standards

Conversation

@gvsambhu

@gvsambhu gvsambhu commented Aug 7, 2026

Copy link
Copy Markdown
Owner

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-n reference — and the ADRs cite 21 of them — nor
follow 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 than
broken 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:

  • FR-2 said the knowledge graph is extracted by LLM analysis. FR-10 explicitly denies this and
    the README's point-of-view section contradicts it; the text 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.
  • FR-20 named a runs/<timestamp>/ directory that does not exist. The run manifest and
    structured 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 uncommitted
document. 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 commit
conventions, 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-001 linked its code sketches as a relative link to a file that was never committed at any
    path — a clickable 404 since that ADR's first commit. The sketches are now inlined.
  • docs/manifest-versions.md linked ADR-017-eval-framework.md; the file is
    ADR-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 new
reference gate all clean.

gvsambhu added 10 commits August 5, 2026 18:55
…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
@gvsambhu
gvsambhu merged commit 35063a6 into main Aug 7, 2026
14 checks passed
@gvsambhu
gvsambhu deleted the dev/docs-14-requirements-and-standards branch August 7, 2026 06:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant