91 lines
4.6 KiB
Markdown
91 lines
4.6 KiB
Markdown
|
# Tasks: Add Report Schema
|
||
|
|
|
||
|
|
## 1. Top-Level Report Structure
|
||
|
|
|
||
|
|
- [x] 1.1 Specify the report envelope: `schema_version`, `tool_version`,
|
||
|
|
`generated_at` (ISO-8601), and `scan` metadata (scope globs, files
|
||
|
|
scanned count, excluded dirs).
|
||
|
|
- [x] 1.2 Specify the `shortlist` field (candidate paths the scanner surfaced)
|
||
|
|
and its relationship to `entries`.
|
||
|
|
- [x] 1.3 Specify the `entries` array as the per-file results.
|
||
|
|
|
||
|
|
## 2. Per-File Entry Fields
|
||
|
|
|
||
|
|
- [x] 2.1 Specify required entry fields: `path`, `category`, `signals`, `op`,
|
||
|
|
`op_type`, `is_destructive`, `is_reversible`, `safety_tier`,
|
||
|
|
`token_estimate`.
|
||
|
|
- [x] 2.2 Specify the optional `exact_edit` field and when it MUST be present
|
||
|
|
(deterministic ops) and absent (generative ops).
|
||
|
|
- [x] 2.3 Freeze the `exact_edit.kind` closed enum: `delete-range`,
|
||
|
|
`move-to-archive`, `insert-frontmatter` (freeze-stamp), `replace-text`
|
||
|
|
(known-target link fix), `dedupe` (exact-dup removal). For each kind specify
|
||
|
|
its required sub-fields and inherent `(is_destructive, is_reversible)`
|
||
|
|
characterization, and that a validator rejects an unknown `kind` or a kind
|
||
|
|
missing a required sub-field. Cross-check the derivation: `delete-range`
|
||
|
|
(destructive — info kept nowhere else) → `confirm`; `move-to-archive`,
|
||
|
|
`insert-frontmatter`, `replace-text`, and `dedupe` (reversible,
|
||
|
|
non-destructive — `dedupe`'s removed span is preserved at `canonical_ref`)
|
||
|
|
→ `auto`.
|
||
|
|
- [x] 2.4 Specify `op_type`↔`op` consistency validation: `op_type` is a property
|
||
|
|
of the chosen op (not a free field, not a subtype lookup); `exact_edit`
|
||
|
|
present iff `op_type == deterministic`, validated deterministically.
|
||
|
|
|
||
|
|
## 3. Category Taxonomy
|
||
|
|
|
||
|
|
- [x] 3.1 Fix the stale sub-types: `contradicted`, `orphaned`, `superseded`,
|
||
|
|
`provisional`, `completed-in-place`, `duplicated`.
|
||
|
|
- [x] 3.2 Fix the bloat sub-types: `distill`, `split`, `freeze`.
|
||
|
|
- [x] 3.3 Specify `category` as `{ class: stale | bloat, subtype: <enum> }`.
|
||
|
|
|
||
|
|
## 4. Op-Type and Safety-Tier Semantics
|
||
|
|
|
||
|
|
- [x] 4.1 Specify `op_type` enum (`deterministic` | `generative`) and meaning.
|
||
|
|
- [x] 4.2 Specify `safety_tier` enum (`auto` | `confirm`) and meaning.
|
||
|
|
- [x] 4.3 Specify the `is_destructive` / `is_reversible` op-characterization
|
||
|
|
inputs the classifier supplies for the derivation.
|
||
|
|
- [x] 4.4 Specify the `safety_tier` **derivation rule**:
|
||
|
|
`safety_tier(op_type, is_destructive, is_reversible)` — generative ⟹
|
||
|
|
confirm; destructive or irreversible ⟹ confirm; only deterministic +
|
||
|
|
reversible + objective ⟹ auto. Tier is computed, never model-assigned, and
|
||
|
|
can never emit `auto` for a generative or destructive op (invariant #7).
|
||
|
|
|
||
|
|
## 5. Token Estimate
|
||
|
|
|
||
|
|
- [x] 5.1 Specify per-entry `token_estimate` shape: `raw_tokens` required in v1
|
||
|
|
(deterministic local-tokenizer count, no API call).
|
||
|
|
- [x] 5.2 Mark `injection_frequency` and `weighted_tokens` as v2-optional /
|
||
|
|
nullable fields; injection-frequency weighting + bottom-up rollup to
|
||
|
|
category and total is the v2 bonus per the PRD build order.
|
||
|
|
|
||
|
|
## 6. Frozen-Contract Guarantee
|
||
|
|
|
||
|
|
- [x] 6.1 Freeze and version the schema (`schema_version`): specify that any
|
||
|
|
change to a field, enum value, or documented semantic requires updating
|
||
|
|
`invariants.md` with explicit human approval.
|
||
|
|
- [x] 6.2 Reference `invariants.md` as the authoritative enforcement mechanism
|
||
|
|
for the freeze (it carries the schema-freeze and `safety_tier` derivation
|
||
|
|
invariants). Do NOT author classifier golden examples in this change — the
|
||
|
|
classifier (the AI `check` pass) does not exist yet, so classifier golden
|
||
|
|
examples are deferred to after the `check` change.
|
||
|
|
|
||
|
|
## 7. Schema-Shape Verification
|
||
|
|
|
||
|
|
> These are schema-shape fixtures, valid to author now. They are NOT classifier
|
||
|
|
> golden examples (deferred to the `check` change) — an implementer must not
|
||
|
|
> conflate the two.
|
||
|
|
|
||
|
|
- [x] 7.1 Write a schema-validator script that checks a machine report against
|
||
|
|
this frozen schema (envelope fields, closed category enum, closed
|
||
|
|
`exact_edit.kind` enum with per-kind required sub-fields, `op_type`↔
|
||
|
|
`exact_edit` biconditional, and `safety_tier` equals the derivation output).
|
||
|
|
- [x] 7.2 Author one **valid** schema fixture (a well-formed machine report) under
|
||
|
|
`examples/golden/` and confirm the validator accepts it.
|
||
|
|
- [x] 7.3 Author one **invalid** schema fixture (e.g. unknown `exact_edit.kind`,
|
||
|
|
or a `safety_tier` disagreeing with the derivation) under `examples/golden/`
|
||
|
|
and confirm the validator rejects it.
|
||
|
|
|
||
|
|
## 8. Validation
|
||
|
|
|
||
|
|
- [x] 8.1 Run `openspec validate add-report-schema --strict` and confirm it
|
||
|
|
passes.
|