Ty
84d7681c6f
- add tools/check_coverage.py and .audit/coverage ledger (schema + settings pilot) - add coverage gap worklist and source-doc migration TODOs - add session handoff; redirect stale resume points in AGENTS.md, docs/README.md, reconciliation record - add rows: CAPTURE-41, CAPTURE-141, METADATA-66, PUBLISH-31, SETTINGS-51
58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
# Coverage ledger
|
|
|
|
Provenance for every requirement in `docs/REQUIREMENTS.md`. One row per source atom.
|
|
Kept under `.audit/` on purpose, so it is not part of the `docs/` structure contract.
|
|
|
|
`tools/check_coverage.py` reads every `*.md` in this directory except this file.
|
|
|
|
## Row format
|
|
|
|
```
|
|
| Source | Atom | Requirement | Disposition | PoR ID | Rationale |
|
|
```
|
|
|
|
- **Source** — where the atom came from, prefixed by kind: `tag:TEST-SPEC`, `tag:OPENAPI`,
|
|
`prd`, `cur:CREATE`, `issue:#5`, `audit:14`.
|
|
- **Atom** — the stable key inside that source, e.g. `H-1`, `settings-PUT-reject`.
|
|
- **Requirement** — a short restatement, enough to recognise it.
|
|
- **Disposition** — one of the values below.
|
|
- **PoR ID** — the `docs/REQUIREMENTS.md` ID(s), comma-separated. `—` when none.
|
|
- **Rationale** — required for everything that is not plain `ported`.
|
|
|
|
## Dispositions
|
|
|
|
| Value | Meaning | PoR ID | Rationale |
|
|
|---|---|---|---|
|
|
| `ported` | fully represented by the cited row(s) | required | optional |
|
|
| `duplicate` | same rule as another atom | optional | required |
|
|
| `new` | PoR row with no source atom; a reconciliation decision | required | required |
|
|
| `superseded` | replaced by a later source or decision | optional | required |
|
|
| `deferred` | intentionally out of current scope | optional | required |
|
|
| `dropped` | deliberately discarded | `—` | required |
|
|
| `gap` | not represented, not deliberately dropped: an open hole | `—` | required |
|
|
|
|
`gap` is the finding. It is the thing this ledger exists to surface.
|
|
|
|
## Checks
|
|
|
|
Forward (always):
|
|
|
|
1. Every row has six well-formed columns and a known disposition.
|
|
2. A `(Source, Atom)` pair is unique across the ledger.
|
|
3. `ported` and `new` cite at least one defined requirement ID; every cited ID resolves.
|
|
4. `dropped` and `gap` carry no ID and a non-empty rationale.
|
|
5. Every non-`ported` row carries a non-empty rationale.
|
|
|
|
Reverse (`--strict` only, once coverage is complete):
|
|
|
|
6. Every ID in `docs/REQUIREMENTS.md` is claimed by at least one atom, or is `new`.
|
|
7. No `gap` rows remain.
|
|
|
|
## Run
|
|
|
|
```
|
|
python tools/check_coverage.py
|
|
python tools/check_coverage.py --strict
|
|
python tools/check_coverage.py --ledger-dir <path> # for negative tests
|
|
```
|