14 KiB

Raw Blame History

Spec: report-schema

Purpose

Defines the machine report schema — the frozen contract that the check skill produces and every downstream component (clean, sweep, token-estimator, schema-validator) consumes. All field shapes, enum values, and derivation semantics are fixed here; any change requires updating invariants.md with explicit human approval.

Requirements

Requirement: Top-Level Report Envelope

The machine report SHALL be a single JSON object containing schema_version, tool_version, generated_at (ISO-8601 UTC), a scan metadata object, a shortlist array, and an entries array. The scan object SHALL include project_root, scope_globs, excluded_dirs, and files_scanned. The generated_at timestamp SHALL be the check time that the clean step uses for its mtime guard.

Scenario: Check writes a well-formed report

WHEN the check skill completes a scan and classification pass
THEN it writes one JSON object with schema_version, tool_version, generated_at, scan, shortlist, and entries

Scenario: Clean reads the check timestamp

WHEN the clean skill loads a report
THEN it reads generated_at and uses it as the reference time for the per-op mtime guard

Requirement: Shortlist Precedes Entries

The shortlist SHALL contain the project-root-relative paths the deterministic scanner surfaced as candidates. Every entries[].path SHALL be a member of shortlist. The scanner produces shortlist; the AI pass produces entries.

Scenario: Entry path is a shortlist member

WHEN the AI pass adds an entry for a file
THEN that file's path already appears in shortlist

Scenario: A shortlisted file may be cleared

WHEN the AI pass judges a shortlisted file as not stale and not bloated
THEN the path remains in shortlist but produces no entry in entries

Requirement: Per-File Entry Fields

Each entry SHALL contain path, category, signals, op, op_type, is_destructive, is_reversible, safety_tier, and token_estimate. The op_type SHALL be one of deterministic or generative. The is_destructive and is_reversible fields SHALL be booleans that objectively characterize the chosen op. An op SHALL be considered destructive if and only if it removes or overwrites information that is not preserved elsewhere in the repository; text-level line removal is not by itself destructive when the information survives (for example a dedupe whose removed span is preserved verbatim at canonical_ref is non-destructive). The safety_tier SHALL be one of auto or confirm and SHALL be derived (see the Op-Type and Safety-Tier Semantics requirement), not assigned by the model. The signals field SHALL list the objective scanner facts that support the classification.

Scenario: Entry carries the full classification

WHEN the AI pass classifies a candidate file
THEN the entry includes path, category, signals, op, op_type, is_destructive, is_reversible, safety_tier, and token_estimate

Scenario: Op-type and safety-tier are constrained enums

WHEN an entry is written
THEN op_type is deterministic or generative and safety_tier is auto or confirm

Scenario: Op characterization inputs are present for derivation

WHEN an entry is written
THEN is_destructive and is_reversible are present as booleans so safety_tier can be computed deterministically from them

Requirement: Category Taxonomy Is a Closed Enum

The category field SHALL be an object with class and subtype. The class SHALL be stale or bloat. When class is stale, subtype SHALL be one of contradicted, orphaned, superseded, provisional, completed-in-place, or duplicated. When class is bloat, subtype SHALL be one of distill, split, or freeze. No other classes or subtypes are permitted.

Scenario: Stale file is categorized with a stale subtype

WHEN a doc references a file that no longer exists
THEN its entry has category.class = stale and category.subtype = orphaned

Scenario: Bloated file is categorized with a bloat subtype

WHEN a doc is a long resolved-problem narrative that should be condensed
THEN its entry has category.class = bloat and category.subtype = distill

Scenario: Unknown subtype is rejected

WHEN a report contains a category.subtype outside the closed enum
THEN the report is invalid

Requirement: Op-Type Is a Property of the Chosen Op

op_type SHALL describe the operation the classifier selected and SHALL be consistent with it: it SHALL NOT be a free field, and it SHALL NOT be looked up from category.subtype (a single subtype may map to either a deterministic or a generative op depending on the chosen op). An entry SHALL include exact_edit when, and only when, op_type is deterministic. An entry with op_type = generative SHALL NOT include exact_edit. This biconditional SHALL be validated deterministically; an entry that violates it is invalid.

Scenario: Same subtype admits either op-type

WHEN a contradicted block is recommended for deterministic deletion in one entry and generative rewrite in another
THEN both entries are valid, each with op_type consistent with its chosen op rather than derived from the shared subtype

Scenario: Op-type and exact-edit consistency is validated

WHEN an entry has op_type = generative but also carries an exact_edit (or op_type = deterministic but omits exact_edit)
THEN the entry is invalid

Requirement: Safety-Tier Is Derived Deterministically

deterministic ops SHALL be exact edits the check pre-computes and the cleaner applies with no model. generative ops SHALL be prose transformations requiring a model at clean time. The safety_tier SHALL be computed by a deterministic script function safety_tier(op_type, is_destructive, is_reversible) and SHALL NOT be assigned by the model; the report records the computed value. The function SHALL return confirm when op_type is generative, OR when is_destructive is true, OR when is_reversible is false; and SHALL return auto only when the op is deterministic AND non-destructive AND reversible (hence objective). The function SHALL NEVER return auto for a generative op or for any destructive or irreversible op, so the model cannot violate invariant #7. auto-tier ops SHALL run without a prompt; confirm-tier ops SHALL be escalated for approval.

Scenario: Deterministic reversible op derives to auto

WHEN an entry has op_type = deterministic, is_destructive = false, and is_reversible = true
THEN the derived safety_tier is auto and the cleaner applies the exact_edit mechanically without a prompt

Scenario: Destructive op derives to confirm

WHEN an op removes information not preserved elsewhere (is_destructive = true, e.g. a delete-range)
THEN the derived safety_tier is confirm regardless of op_type

Scenario: Generative op derives to confirm

WHEN an entry has op_type = generative
THEN the derived safety_tier is confirm and the op is delegated to a Sonnet subagent at clean time

Scenario: Function can never emit auto for a generative or destructive op

WHEN safety_tier(op_type, is_destructive, is_reversible) is evaluated for any input where op_type = generative, or is_destructive = true, or is_reversible = false
THEN the result is confirm, never auto

Requirement: Exact-Edit Presence Tied to Op-Type

An entry SHALL include an exact_edit object when, and only when, op_type is deterministic. The exact_edit SHALL be mechanically applicable and SHALL carry a content fingerprint (expected_sha256) so the cleaner's mtime guard can refuse to apply it to a file changed since generated_at. Entries with op_type = generative SHALL omit exact_edit.

Scenario: Deterministic entry includes exact edit

WHEN an entry has op_type = deterministic
THEN it includes an exact_edit with the edit operation and expected_sha256

Scenario: Generative entry omits exact edit

WHEN an entry has op_type = generative
THEN it has no exact_edit field and the edit is produced at clean time

Scenario: mtime guard refuses a stale edit

WHEN a file's current content hash differs from the entry's expected_sha256
THEN the cleaner skips the cached edit and recommends re-analysis

Requirement: Exact-Edit Kind Is a Closed Enum

Every exact_edit SHALL carry a kind drawn from the closed set delete-range, move-to-archive, insert-frontmatter, replace-text, and dedupe — one per deterministic op family the PRD names. No other kind is permitted. Each kind SHALL carry its required sub-fields and SHALL have a fixed inherent (is_destructive, is_reversible) characterization that feeds the safety_tier derivation:

delete-range SHALL carry anchor with start_line and end_line; it is destructive and irreversible (derives to confirm).
move-to-archive SHALL carry anchor (start_line, end_line) and dest_path; it is non-destructive and reversible (derives to auto).
insert-frontmatter SHALL carry the frontmatter key and value to inject (for example hygiene: frozen); it is non-destructive and reversible (derives to auto).
replace-text SHALL carry anchor (start_line, end_line), a match string, and a replacement string; it is non-destructive and reversible (derives to auto).
dedupe SHALL carry anchor (start_line, end_line) of the removed duplicate span and a canonical_ref to the kept location; because the removed span is an exact duplicate preserved verbatim at canonical_ref, no information is lost, so it is non-destructive and reversible and derives to auto. (Contrast delete-range, which removes content kept nowhere else, is destructive, and derives to confirm.)

A validator SHALL reject an exact_edit whose kind is outside the closed set or that omits a required sub-field for its kind.

Scenario: Each kind carries its required fields

WHEN an entry has op_type = deterministic with an exact_edit of kind = move-to-archive
THEN the exact_edit includes anchor (start_line, end_line) and dest_path, and the entry is valid

Scenario: Unknown kind is rejected

WHEN an exact_edit has a kind outside the closed set delete-range, move-to-archive, insert-frontmatter, replace-text, dedupe
THEN the report is invalid

Scenario: Missing required sub-field is rejected

WHEN an exact_edit of kind = replace-text omits its match or replacement field
THEN the report is invalid

Scenario: Kind characterization feeds the safety-tier derivation

WHEN an exact_edit has kind = delete-range
THEN the entry's is_destructive is true and is_reversible is false, so the derived safety_tier is confirm

Requirement: Per-Entry Token Estimate

Each entry SHALL include a token_estimate. In v1, only raw_tokens (a local-tokenizer count of the removed or reduced span, with no API call) SHALL be required. The injection_frequency (per-session or on-demand) and weighted_tokens (raw_tokens adjusted by injection frequency) fields SHALL be optional and MAY be null or omitted in v1; populating them (injection-frequency weighting plus bottom-up rollup) is the v2 bonus per the PRD build order. When populated, auto-injected files SHALL be weighted as real per-session savings and on-demand docs SHALL be weighted as theoretical-max savings. Roll-up to category and total SHALL be computed bottom-up from the entries.

Scenario: v1 entry carries only the required raw token count

WHEN a v1 check writes an entry without the weighting fields
THEN token_estimate.raw_tokens is present (a local-tokenizer count, no API call) and injection_frequency and weighted_tokens may be null or omitted

Scenario: Auto-injected file weighted per session

WHEN the weighting fields are populated (v2) and the affected file is auto-injected (for example CLAUDE.md)
THEN injection_frequency = per-session and weighted_tokens reflects real per-session savings

Scenario: On-demand doc weighted as theoretical max

WHEN the weighting fields are populated (v2) and the affected file is read only on demand
THEN injection_frequency = on-demand and weighted_tokens reflects theoretical-max savings

Requirement: Schema Is a Frozen Contract

The report schema SHALL be treated as a frozen contract that every other component consumes. The freeze SHALL be enforced by invariants.md (which carries the schema-freeze and safety_tier derivation invariants); that file is the authoritative enforcement mechanism for this contract. Any change to a field, an enum value, or a documented semantic SHALL require updating invariants.md with explicit human approval before it takes effect. Schema-shape verification SHALL be carried by a schema-validator script and hand-authored schema fixtures (one valid machine report, one invalid) under examples/golden/; these schema-shape fixtures are distinct from classifier golden examples, which are deferred until the check change exists.

Scenario: Schema change requires invariants update

WHEN a contributor proposes adding, renaming, or removing a field or enum value
THEN the change is accompanied by an invariants.md update with human approval before it takes effect

Scenario: Validator accepts a well-formed report and rejects a malformed one

WHEN the schema-validator script runs against the valid and invalid schema fixtures under examples/golden/
THEN it accepts the valid machine report and rejects the invalid one

Scenario: Components rely on the frozen shape

WHEN the clean, sweep, or token-estimator components are built
THEN they consume the report without re-deriving its structure

14 KiB Raw Blame History