cc-os/plugins/os-doc-hygiene/openspec/specs/doc-check/spec.md

# 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. `/hygiene check [--scope <glob-or-path>] [--category <class|subtype>]`
SHALL invoke the `hygiene-check` skill. `/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. `/hygiene clean` and `/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 `/hygiene check`
- **THEN** the command invokes the `hygiene-check` skill, passing through any `--scope` or `--category` flag

#### Scenario: Status is read-only

- **WHEN** the user runs `/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 `/hygiene clean` or `/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 `hygiene-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 `hygiene-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/<n>-<name>/`
(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