cc-os/plugins/os-doc-hygiene/openspec/changes/archive/2026-06-18-add-report-schema/tasks.md

Tasks: Add Report Schema

1. Top-Level Report Structure

• 1.1 Specify the report envelope: schema_version, tool_version, generated_at (ISO-8601), and scan metadata (scope globs, files scanned count, excluded dirs).
• 1.2 Specify the shortlist field (candidate paths the scanner surfaced) and its relationship to entries.
• 1.3 Specify the entries array as the per-file results.

2. Per-File Entry Fields

• 2.1 Specify required entry fields: path, category, signals, op, op_type, is_destructive, is_reversible, safety_tier, token_estimate.
• 2.2 Specify the optional exact_edit field and when it MUST be present (deterministic ops) and absent (generative ops).
• 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.
• 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

• 3.1 Fix the stale sub-types: contradicted, orphaned, superseded, provisional, completed-in-place, duplicated.
• 3.2 Fix the bloat sub-types: distill, split, freeze.
• 3.3 Specify category as { class: stale | bloat, subtype: <enum> }.

4. Op-Type and Safety-Tier Semantics

• 4.1 Specify op_type enum (deterministic | generative) and meaning.
• 4.2 Specify safety_tier enum (auto | confirm) and meaning.
• 4.3 Specify the is_destructive / is_reversible op-characterization inputs the classifier supplies for the derivation.
• 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

• 5.1 Specify per-entry token_estimate shape: raw_tokens required in v1 (deterministic local-tokenizer count, no API call).
• 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

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

• 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).
• 7.2 Author one valid schema fixture (a well-formed machine report) under examples/golden/ and confirm the validator accepts it.
• 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

• 8.1 Run openspec validate add-report-schema --strict and confirm it passes.