# 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.