358 lines
20 KiB
Markdown
358 lines
20 KiB
Markdown
# 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, an `entries` array, and a `promotion_candidates` 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. The
|
|
`promotion_candidates` array SHALL be present (possibly empty) on every
|
|
report and SHALL list, per candidate, the classifier-judged entry it applies
|
|
to, the recommended `conventions.json` entry name, and its one-line pitch.
|
|
|
|
#### 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`, `entries`, and `promotion_candidates`
|
|
|
|
#### 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
|
|
|
|
#### Scenario: promotion_candidates is always present, possibly empty
|
|
- **WHEN** a check run has no classifier-judged entry with an applicable unadopted convention
|
|
- **THEN** `promotion_candidates` is written as an empty array, not omitted
|
|
|
|
### 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 `derive_safety_tier(op_type,
|
|
is_destructive, is_reversible, lifecycle=None)` and SHALL NOT be assigned by
|
|
the model; the report records the computed value. This function remains the
|
|
single source of truth for tier derivation across the whole report schema,
|
|
including lifecycle ops — no second tier-deriving function or code path is
|
|
introduced.
|
|
|
|
For non-lifecycle ops, 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).
|
|
|
|
For `delete` and `extract-then-delete` ops, the function SHALL additionally
|
|
consult the `lifecycle` argument and SHALL return `auto` only when ALL of the
|
|
following hold: the lifecycle evidence is scanner-proven (a satisfied
|
|
`served_when_path`, or a temporary-tier retain-recent/age computation) AND
|
|
the path is tracked AND the worktree at that path is clean at the time of
|
|
derivation. Every other combination for a lifecycle op — a classifier-judged
|
|
`served_when`, a dirty worktree, or an untracked path — SHALL derive to
|
|
`confirm`, regardless of `is_destructive`/`is_reversible` inputs. The
|
|
function SHALL NEVER return `auto` for a `generative` op, for any
|
|
non-lifecycle destructive or irreversible op, or for any lifecycle op whose
|
|
evidence is classifier-judged or whose git state is not tracked+clean, so
|
|
the model cannot violate invariant #7.
|
|
|
|
`auto`-tier ops SHALL run without a prompt; `confirm`-tier ops SHALL be
|
|
escalated for approval; `delete`/`extract-then-delete` `auto` verdicts SHALL
|
|
additionally be re-verified against live git state at apply time per the
|
|
`lifecycle-deletion` spec before being applied without a prompt.
|
|
|
|
#### 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** `derive_safety_tier(op_type, is_destructive, is_reversible, lifecycle)` is evaluated for any input where `op_type` = `generative`, or (for a non-lifecycle op) `is_destructive` = true, or `is_reversible` = false
|
|
- **THEN** the result is `confirm`, never `auto`
|
|
|
|
#### Scenario: A lifecycle delete with scanner-proven evidence and tracked+clean state derives to auto
|
|
- **WHEN** a `delete` entry's `lifecycle` argument shows a satisfied `served_when_path` and the path is tracked and clean
|
|
- **THEN** the derived `safety_tier` is `auto`
|
|
|
|
#### Scenario: A lifecycle delete with classifier-judged evidence always derives to confirm
|
|
- **WHEN** a `delete` or `extract-then-delete` entry's `lifecycle` argument carries `served_when` (classifier-judged)
|
|
- **THEN** the derived `safety_tier` is `confirm`, regardless of tracked/clean state
|
|
|
|
#### Scenario: A lifecycle delete on a dirty or untracked path derives to confirm
|
|
- **WHEN** a `delete` entry's evidence is scanner-proven but the path is dirty or untracked
|
|
- **THEN** the derived `safety_tier` is `confirm`
|
|
|
|
### Requirement: Lifecycle Signal Fields on Shortlist and Entries
|
|
|
|
A shortlist entry or report entry carrying a lifecycle signal SHALL include a
|
|
`lifecycle` object with `rule_ref` (identifying which rulebook rule matched),
|
|
`lifetime` (`keep`, `temporary`, or `delete-once-served`), and exactly one of
|
|
`served_when_path` (deterministic) or `served_when` (classifier-judged, free
|
|
text), mirroring the rulebook rule's own fields. A directory-rule aggregate
|
|
entry SHALL carry the same `lifecycle` object shape as a file entry, with its
|
|
`path` set to the matched directory.
|
|
|
|
#### Scenario: A file-rule match carries the lifecycle object
|
|
|
|
- **WHEN** a file matches a `temporary`-lifetime file rule
|
|
- **THEN** its shortlist/report entry includes a `lifecycle` object with `rule_ref`, `lifetime: "temporary"`, and no `served_when`/`served_when_path` (temporary entries are keyed on age, not a served signal)
|
|
|
|
#### Scenario: A delete-once-served match carries exactly one served field
|
|
|
|
- **WHEN** a file matches a `delete-once-served` rule using `served_when_path`
|
|
- **THEN** its `lifecycle` object includes `served_when_path` and omits `served_when`, never both
|
|
|
|
#### Scenario: A directory-rule aggregate entry carries the same shape
|
|
|
|
- **WHEN** a directory rule produces one aggregate shortlist entry
|
|
- **THEN** that entry's `lifecycle` object has the same fields as a file entry's, with `path` set to the directory
|
|
|
|
### Requirement: Promotion-Candidates Section Schema
|
|
|
|
The top-level `promotion_candidates` array SHALL contain, per candidate, the
|
|
`path` of the classifier-judged entry it applies to, the recommended
|
|
`conventions.json` entry `name`, and the convention's one-line `pitch`. This
|
|
array SHALL be computed only by the deterministic finalize pass (never the
|
|
model) and SHALL be empty, not omitted, when no candidate applies.
|
|
|
|
#### Scenario: A promotion candidate references its source entry and convention
|
|
|
|
- **WHEN** an entry with `served_when` has an applicable unadopted convention
|
|
- **THEN** the `promotion_candidates` array includes an object with that entry's `path`, the convention `name`, and its `pitch`
|
|
|
|
#### Scenario: promotion_candidates is model-free
|
|
|
|
- **WHEN** the finalize pass computes `promotion_candidates`
|
|
- **THEN** it does so without any subagent dispatch, using only `conventions.json` and the report's own lifecycle entries
|
|
|
|
### 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`,
|
|
`dedupe`, `delete`, and `extract-then-delete` — one per deterministic op
|
|
family the PRD and the lifecycle-aware design name. 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, except where noted below that lifecycle kinds'
|
|
tier also depends on runtime git state and evidence quality (see the
|
|
Safety-Tier Is Derived Deterministically requirement):
|
|
|
|
- `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`.)
|
|
- `delete` SHALL carry a full-file (or, for a directory-rule aggregate entry,
|
|
whole-directory) `anchor` and a `lifecycle` object (`rule_ref`, `lifetime`,
|
|
and exactly one of `served_when_path` or `served_when`); it is destructive
|
|
(git history is the only recovery path) and its `is_reversible`
|
|
characterization is inherently git-history-dependent rather than fixed —
|
|
see the Safety-Tier requirement for how its tier is actually derived.
|
|
- `extract-then-delete` SHALL carry the same `lifecycle` object as `delete`
|
|
plus an `extraction_target` classification (`repo-durable` or `cross-repo`)
|
|
and, for `repo-durable`, a target document reference; it has the same
|
|
destructive/tier characterization as `delete`, gated additionally on the
|
|
extraction step succeeding before the delete half applies.
|
|
|
|
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`, `delete`, `extract-then-delete`
|
|
- **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`
|
|
|
|
#### Scenario: delete and extract-then-delete require the lifecycle object
|
|
- **WHEN** an `exact_edit` has `kind` = `delete` or `kind` = `extract-then-delete`
|
|
- **THEN** it includes a `lifecycle` object with `rule_ref`, `lifetime`, and exactly one of `served_when_path` or `served_when`; omitting the `lifecycle` object or supplying both `served_when_path` and `served_when` makes the report invalid
|
|
|
|
#### Scenario: extract-then-delete requires an extraction_target
|
|
|
|
- **WHEN** an `exact_edit` has `kind` = `extract-then-delete`
|
|
- **THEN** it includes `extraction_target` set to `repo-durable` or `cross-repo`, with a target document reference required when `repo-durable`
|
|
|
|
### 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
|