# doc-check Specification ## Purpose TBD - created by archiving change add-check. Update Purpose after archive. ## Requirements ### Requirement: `/hygiene` Command Surface The plugin SHALL provide a single `/hygiene` command that dispatches on its arguments. `/os-doc-hygiene:check [--scope ] [--category ]` SHALL invoke the `check` skill. `/os-doc-hygiene:status` SHALL read and report the lifecycle timestamps (`last_check`, `last_clean`, `last_reminded`) and whether a report exists, using no scan and no model. `/os-doc-hygiene:clean` and `/os-doc-hygiene:sweep` SHALL be reserved and SHALL report that they are not yet implemented (Phase 4). No arguments or unknown arguments SHALL print usage plus the current status. #### Scenario: Check dispatches to the skill - **WHEN** the user runs `/os-doc-hygiene:check` - **THEN** the command invokes the `check` skill, passing through any `--scope` or `--category` flag #### Scenario: Status is read-only - **WHEN** the user runs `/os-doc-hygiene:status` - **THEN** the command reports `last_check`, `last_clean`, `last_reminded`, and whether a report exists, without running a scan or any model #### Scenario: Clean and sweep are reserved - **WHEN** the user runs `/os-doc-hygiene:clean` or `/os-doc-hygiene:sweep` - **THEN** the command reports that the subcommand is not yet implemented (Phase 4) and does not mutate anything #### Scenario: Unknown arguments print usage - **WHEN** the user runs `/hygiene` with no arguments or an unrecognized subcommand - **THEN** the command prints usage and the current status ### Requirement: Check Skill Orchestrates Scan, Classification, and Report Writing The `check` skill SHALL orchestrate the check pipeline: run the deterministic scanner, dispatch a Sonnet subagent for judgment-only classification of the signal-bearing candidates, run the deterministic finalize pass, validate, write the report pair, and stamp `last_check`. The skill SHALL run all non-judgment steps as deterministic scripts with no model (invariant #6). Zero-signal shortlisted files SHALL be treated as presumptively cleared: they SHALL remain in the shortlist, produce no entries, and SHALL NOT be read by the model. A `--scope` argument SHALL narrow the scanner; a `--category` argument SHALL filter which entries are produced after classification; both SHALL be recorded in the human-report header. #### Scenario: Skill runs the full pipeline - **WHEN** the `check` skill runs - **THEN** it scans (deterministic), classifies signal-bearing candidates (Sonnet), finalizes (deterministic), validates (deterministic), writes the report pair (deterministic), and stamps `last_check` (deterministic) #### Scenario: Zero-signal files are not read by the model - **WHEN** a shortlisted file carries no scanner signals - **THEN** it remains in the shortlist, produces no entry, and is not read by the classification model #### Scenario: Scope and category are recorded and applied - **WHEN** the user passes `--scope docs/**/*.md` and `--category bloat` - **THEN** the scanner is narrowed by the scope, only `bloat` entries are produced after classification, and both the scope and the category are recorded in the human-report header ### Requirement: Classification Subagent Returns Judgment-Only Proposals The Sonnet classification subagent SHALL return, per signal-bearing candidate, a slim proposal containing only judgment fields: `category` (`class` and `subtype` from the closed enum, justified by cited signals), the scanner `signals` passed through verbatim with an optional one-line gloss in `detail`, `op` (a human sentence), `op_type` (`deterministic` or `generative`, a property of the chosen op per invariant #11), and `confidence`. When `op_type` is `deterministic`, the proposal SHALL carry an `exact_edit` skeleton (`kind` plus the kind's required sub-fields and `anchor` where required) and SHALL NOT carry `expected_sha256`, `is_destructive`, `is_reversible`, or `safety_tier`. When `op_type` is `generative`, the proposal SHALL carry no `exact_edit` and instead a non-persisted `reducible_range` so the finalize pass can count `raw_tokens` over the real span. Low-confidence hard distinctions (stale-vs-bloat; destructive-deletion-vs-generative-rewrite) MAY be escalated to Opus. #### Scenario: Deterministic proposal carries only the exact-edit skeleton - **WHEN** the subagent classifies a file as a deterministic op - **THEN** the proposal includes the `exact_edit` skeleton (`kind`, required sub-fields, `anchor` where required) and omits `expected_sha256`, `is_destructive`, `is_reversible`, and `safety_tier` #### Scenario: Generative proposal carries a reducible range, not an exact edit - **WHEN** the subagent classifies a file as a generative op - **THEN** the proposal carries no `exact_edit` and instead a non-persisted `reducible_range` for the finalize pass to count tokens over #### Scenario: Signals are passed through verbatim - **WHEN** the subagent emits a proposal - **THEN** its `signals` are the scanner's signal names verbatim, with any added wording confined to the optional `detail` gloss ### Requirement: Deterministic Finalize Pass Owns the Non-Model Fields A standalone, model-free finalize pass (`report_builder.py`) SHALL sit between model classification and the report write, and SHALL author the four per-entry fields that the model must not author. For each proposal it SHALL compute `exact_edit.expected_sha256` over the file's current bytes for anchor-bearing kinds, SHALL set `(is_destructive, is_reversible)` from `KIND_TABLE[kind]`, SHALL compute `safety_tier` by calling `derive_safety_tier(op_type, is_destructive, is_reversible)` imported from `validate_report.py` (the single source of truth, invariant #10), and SHALL source `token_estimate.raw_tokens` from the local token estimator (`default_estimator().estimate_for_report(span_text)`, invariant #6). It SHALL stamp each entry's `generated_at` at that file's hash instant and set the envelope `generated_at` to the run instant. The model SHALL NOT supply any of these four fields. #### Scenario: The finalize pass computes the content hash and derives the tier - **WHEN** the finalize pass processes a deterministic proposal with `kind` = `move-to-archive` - **THEN** it computes `expected_sha256` over the file's current bytes, sets `is_destructive` = false and `is_reversible` = true from `KIND_TABLE`, and derives `safety_tier` = `auto` via `derive_safety_tier` #### Scenario: raw_tokens comes from the local estimator, never the model - **WHEN** the finalize pass sets a `token_estimate` - **THEN** `raw_tokens` is the local estimator's count of the span (no model, no API call), with the weighting fields null in v1 #### Scenario: The model cannot author the derived fields - **WHEN** a proposal arrives from the classification subagent - **THEN** `expected_sha256`, `safety_tier`, and (for deterministic ops) `is_destructive`/`is_reversible` are absent from the proposal and are authored only by the finalize pass ### Requirement: Validate Before Rollover The check SHALL validate the assembled report with `validate_report.py` on a scratch path (not under `.dochygiene/`) and SHALL write the report pair only on validator exit 0. Because `StateStore.write_report` deletes the prior report pair before writing the new one (invariant #4), validation SHALL NOT run against `.dochygiene/`, so a validation failure never destroys the last good report. On a validation failure (exit 1) the check SHALL NOT write the report; on an empty shortlist or no signal-bearing files the check SHALL still write a valid empty-`entries` report and stamp `last_check`. #### Scenario: Invalid report is never written - **WHEN** the assembled report fails validation (exit 1) - **THEN** the check does not call `write_report`, the prior report pair is preserved, and the offending entries are re-prompted or dropped before re-validating #### Scenario: Validation runs on a scratch path - **WHEN** the check validates the assembled report - **THEN** validation runs against a scratch path outside `.dochygiene/`, so the last good report in `.dochygiene/` is never deleted by a failed run #### Scenario: Empty shortlist still produces a valid report and stamp - **WHEN** the scanner returns no signal-bearing files - **THEN** the check writes a valid report with empty `entries` and stamps `last_check` ### Requirement: Report Pair Is Written and last_check Stamped On a successful check, the skill SHALL write exactly one machine report (`.dochygiene/report.json`) and one human report (`.dochygiene/report.md`) via `StateStore.write_report` (atomic, rollover-bounded to one pair per invariant #4), and SHALL stamp `last_check` to the same run instant used as the envelope `generated_at`. The human report SHALL be a deterministic skeleton grouping entries by Stale, Bloat, and Cleared with per-entry path, category, op, tier, token count, and signal, and a header showing the timestamp, scope, files scanned, and candidate/cleared counts; only an optional per-entry "why" gloss MAY be model-written. #### Scenario: One report pair survives the write - **WHEN** the check completes successfully - **THEN** exactly one `report.json` and one `report.md` exist in `.dochygiene/`, and any prior pair has been rolled over #### Scenario: last_check matches the envelope timestamp - **WHEN** the check writes the report - **THEN** `last_check` is stamped to the same run instant recorded as the envelope `generated_at` ### Requirement: Classifier Golden Examples Are Hermetic and Human-Gated Classifier golden examples SHALL live under `examples/golden/classifier/-/` (an `input/` fixture tree with stable hashes, an `expected.json` schema-valid report, and an optional `notes.md`), distinct from the schema-shape fixtures (`valid_report.json` / `invalid_report.json`). The golden unit harness SHALL be hermetic — it SHALL NOT call a live model — and SHALL assert only deterministic, stable parts: that the scanner emits the expected signals on the right paths, that each `expected.json` validates (exit 0), and that the stable fields (`category.class`, `category.subtype`, `op_type`, derived `safety_tier`, `exact_edit.kind`) match a captured/committed check output. Op-prose and exact anchor line numbers SHALL be advisory (flagged for review, not hard-failed). The live model-classification regression SHALL be a separate, manually or agent-invoked harness, not part of the unit suite. Adding or changing classifier goldens SHALL be human-gated per the META-RULE. #### Scenario: Golden harness makes no live model call - **WHEN** the classifier golden unit tests run - **THEN** they assert scanner signals, `expected.json` validity, and stable-field matches against a committed capture, with no live model invocation #### Scenario: Classifier goldens are distinct from schema fixtures - **WHEN** a contributor looks for the schema-shape fixtures versus the classifier goldens - **THEN** the schema fixtures (`valid_report.json` / `invalid_report.json`) and the classifier goldens (`examples/golden/classifier/`) are separate, and `examples/golden/CONTEXT.md` documents the distinction #### Scenario: Changing a golden requires human approval - **WHEN** a contributor adds or changes a classifier golden example - **THEN** the change is gated on explicit human approval per the META-RULE before it takes effect