docs(phase2): coverage gate, migration TODOs, session handoff
- 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
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user