cc-os/plugins/os-doc-hygiene/openspec/changes/archive/2026-06-24-add-check/design.md

Design: Check

Context

The deterministic core (build step #2) and the token estimator are in place: scanner.py emits the intermediate { project_root, scope_globs, excluded_dirs, files_scanned, shortlist, signals } artifact; state_store.py owns lifecycle timestamps, atomic writes, and report rollover; validate_report.py owns the frozen schema validation, including the single-source derive_safety_tier(...) function and KIND_TABLE; token_estimator.py exposes default_estimator().estimate_for_report(text). This change builds the first AI pass on top of them — the check skill — plus the /hygiene command that the SessionStart reminder already advertises.

Constraints that shape this design:

• Invariant #6 (deterministic-first): scan, state, patch-apply, and token-estimate are scripts. The model does only classification and prose distillation. raw_tokens comes from the local estimator, never a model.
• Invariant #10 (safety_tier is derived): safety_tier is computed only by derive_safety_tier(op_type, is_destructive, is_reversible) — never model-assigned.
• Invariant #11 (op_type is a property of the chosen op): op_type is deterministic iff the op carries an exact_edit; a single subtype may map to either op-type depending on the chosen op.
• Invariant #4 (report rollover): exactly one report.json + report.md pair survives each write; write_report deletes the prior pair before writing the new one.
• Invariant #8 (mtime/content guard): the cleaner verifies a file's current hash matches the entry's expected_sha256 before applying a cached edit.

Goals / Non-Goals

Goals:

• A /hygiene command surface: check (scan + classify + report) and status (read-only timestamps), with clean / sweep reserved.
• A hygiene-check skill orchestrating scan → Sonnet classify → deterministic finalize → validate → write + stamp last_check.
• A standalone, model-free report_builder.py finalize pass that owns the four fields the model must not author (expected_sha256, safety_tier, is_destructive/is_reversible for deterministic ops, raw_tokens).
• Hermetic classifier golden examples + a unit harness that never calls a live model.

Non-Goals:

• The clean skill, patch-applier, mtime-guard application, and sweep (Phase 4).
• token_estimate weighting (injection_frequency, weighted_tokens, rollup) — v2 bonus; this change populates only raw_tokens.
• The live model-classification regression harness (separate, manually invoked).

Decisions

D1. A deterministic finalize pass between classify and write — report_builder.py

This is the decision that shapes everything. Four per-entry fields cannot be model-authored without violating a frozen invariant or being physically impossible:

• exact_edit.expected_sha256 — the sha256 of real file bytes; the model never sees the bytes, and inventing a hash is meaningless.
• safety_tier — invariant #10: derived only by derive_safety_tier(...), never model-assigned.
• is_destructive / is_reversible for deterministic ops — fixed by exact_edit.kind via KIND_TABLE in validate_report.py.
• token_estimate.raw_tokens — invariant #6: from the local token estimator, never a model.

Therefore check MUST include a deterministic step between model classification and StateStore.write_report. A new standalone script scripts/report_builder.py is that step: a model-free assembler. Input: the scanner artifact plus the model's slim per-file classification proposals. Output: a full schema-valid machine report plus a deterministic human-report skeleton. For each proposal it reads the anchored span, computes expected_sha256, looks up (is_destructive, is_reversible) from kind, calls derive_safety_tier(...) imported from validate_report.py (single source of truth — no re-implementation), calls token_estimator.default_estimator().estimate_for_report(span_text), stamps per-entry generated_at at each file's hash instant, and assembles scan / shortlist / entries. Alternative considered: have the skill assemble the report inline in the SKILL.md workflow — rejected: the four guardrail fields then have no enforced, unit-testable home, and the model could leak into a field it must not author.

D2. Command surface — a single commands/hygiene.md dispatching on $ARGUMENTS

One command file. Frontmatter is minimal (name: hygiene; a description naming /hygiene check to scan and /hygiene status for timestamps). Routes:

• check [--scope <glob-or-path>] [--category <class|subtype>] → invoke the hygiene-check skill.
• status → read-only: StateStore.get_last_check / get_last_clean / get_last_reminded plus whether a report exists. No scan, no model. status lives inline in the command (a few python3 calls), not in a separate skill.
• clean / sweep → reserved: "not yet implemented (Phase 4)".
• no/unknown args → usage + current status.

Alternative considered: a separate status skill — rejected: status is a few read-only timestamp reads, not judgment; a skill would be ceremony.

D3. Check skill flow — scan, classify, finalize, validate, write, stamp

skills/hygiene-check/SKILL.md frontmatter mirrors the commit skill (name: hygiene-check; a description). Like the commit skill, the SKILL.md workflow runs deterministic scripts via Bash, dispatches a Sonnet subagent for judgment-only classification, then runs deterministic scripts to assemble/validate/write — the sanctioned mechanism inside a skill workflow (D9). Flow (D = deterministic script, M = model):

1. (D) Scan — python3 scripts/scanner.py (auto-resolves root, default **/*.md, default excludes incl. .dochygiene/). --scope applies a --globs/path filter. Capture the artifact { project_root, scope_globs, excluded_dirs, files_scanned, shortlist, signals }.

2. (D) Select candidates — real candidates = signal-bearing paths (the keys of signals). Zero-signal shortlisted files are presumptively cleared: they stay in shortlist, produce no entries, and are not read by the model. --category filters only at the entry stage.

3. (M) Classify each signal-bearing candidate (Sonnet subagent). The subagent reads each candidate file plus its scanner signals and returns a slim proposal per file (judgment only, no computed fields):

   • category { class, subtype } from the closed enum (STALE_SUBTYPES/BLOAT_SUBTYPES) justified by cited signals (PRD taxonomy).
   • signals passed through verbatim (scanner names: broken_reference, version_skew, edit_recency_vs_churn, stale_name_location, archive_to_live_ratio, frontmatter_marker) with an optional one-line gloss in detail.
   • op (a human sentence); op_type deterministic | generative (a property of the chosen op, invariant #11).
   • If deterministic: an exact_edit skeleton — kind (closed enum) + anchor.{start_line,end_line} where required + kind-specific fields (dest_path / key,value / match,replacement / canonical_ref). The model does not supply expected_sha256, is_destructive, is_reversible, or safety_tier.
   • If generative: no exact_edit; instead a non-persisted reducible_range {start_line,end_line} so the assembler counts raw_tokens on the real text.
   • Plus confidence.

   Decision rules (subtype → kind → tier): destructive deletion of unique content → delete-range (→confirm); content-preserving relocation → move-to-archive (→auto); freeze a completed doc → insert-frontmatter (→auto); exact duplicate preserved elsewhere → dedupe with canonical_ref (→auto); known-target link fix → replace-text (→auto); prose condensation/splitting → generative (→confirm).

4. (D) Finalize via report_builder.py — per proposal: read the file; compute expected_sha256 over current bytes (anchor-bearing kinds only); set (is_destructive, is_reversible) from KIND_TABLE[kind]; safety_tier = derive_safety_tier(op_type, is_destructive, is_reversible) imported from validate_report.py; extract the span (anchor range / reducible_range / whole file for move-to-archive) and token_estimate = estimator.estimate_for_report(span_text) (v1 raw_tokens only, weighting null); assemble the envelope schema_version "1.0", tool_version from plugin.json, per-entry generated_at = that file's hash instant, envelope generated_at = the run instant (which also becomes last_check). Also emit the deterministic human-report skeleton (the mechanical parts); the optional per-entry "why" gloss is model-written.

5. (D) Validate BEFORE writing — run validate_report.py on a scratch path (scratchpad, NOT .dochygiene/). write_report deletes the prior pair first, so validating after the write would destroy the last good report (invariant #4). Only on exit 0 proceed.

6. (D) Write + rollover — StateStore.write_report(json_blob, md_blob) (atomic, keeps exactly one report pair, invariant #4).

7. (D) Stamp — StateStore.set_last_check(generated_at) using the same run instant from step 4.

8. Surface the human-report summary plus the two report paths.

Model routing: classification = Sonnet; escalate a single file to Opus only on low confidence for hard distinctions (stale-vs-bloat; delete-range/destructive vs generative rewrite of the same contradicted/superseded content). Steps 1, 2, 4, 5, 6, 7 use no model (invariant #6).

D4. Failure handling

• Validation fail (exit 1): do NOT write_report (the prior pair is preserved). Map violations to entries[i], re-prompt the subagent to fix only the offending proposals or drop an unfixable entry and re-validate. Never write an invalid report.
• Validator usage error (exit 2): an internal bug; stop.
• Empty shortlist / no signal-bearing files: write a report with empty entries (still valid) and still set_last_check.
• Malformed proposal JSON: the assembler rejects it before computing; re-prompt.

D5. Scoping

--scope narrows the scanner (--globs or a path-prefix filter on the shortlist). --category filters which entries are produced — the scanner is category-agnostic, so the filter is applied after classification. Both are recorded in the human-report header.

D6. Reports — fixed paths, one pair, human skeleton

StateStore hard-codes the paths: machine .dochygiene/report.json, human .dochygiene/report.md, both written via StateStore.write_report; rollover keeps exactly one pair (invariant #4); .dochygiene/ is gitignored. The human report skeleton groups by Stale / Bloat / Cleared with per-entry path, category, op, tier, ~tokens, signal; the header shows timestamp, scope, files scanned, and candidate/cleared counts. The structural parts are script-built; only the optional per-entry "why" gloss is model-written.

D7. Classifier golden examples — distinct from schema fixtures, hermetic harness

Classifier goldens are distinct from examples/golden/valid_report.json / invalid_report.json (those are schema-shape fixtures for validate_report.py only). Classifier goldens are the Layer-2 reversion-protection layer: input doc-tree → expected classification. Layout examples/golden/classifier/<n>-<name>/, each with input/ (a small static fixture tree, stable sha256s), expected.json (a full schema-valid machine report = the expected classification), and an optional notes.md. 3–5 cases, each mapping a subtype to a distinct exact_edit.kind to cover the kind table + tier derivation:

• orphaned → stale/orphaned/deterministic/delete-range/confirm
• superseded → stale/superseded/deterministic/move-to-archive/auto
• completed-in-place → stale/completed-in-place/deterministic/insert-frontmatter/auto
• duplicated → stale/duplicated/deterministic/dedupe/auto
• distill → bloat/distill/generative/(none)/confirm

The harness MUST be hermetic (no live model call in pytest): tests/test_classifier_golden.py asserts only deterministic/stable parts — (1) scanner.py on input/ emits the expected signals on the right paths; (2) validate_report.py on each expected.json → exit 0; (3) a stable-field match against a captured/committed check output (category.class, category.subtype, op_type, the derived safety_tier, exact_edit.kind). The live model-classification regression (running an actual check against input/ and diffing) is a separate, manually/agent-invoked harness — NOT part of the unit suite. Op-prose and exact anchor line numbers are advisory (flag a mismatch for human review, not a hard fail). Adding or changing classifier goldens is human-gated per the META-RULE.

Risks / Trade-offs

• [insert-frontmatter has no content guard — DEFERRED hole] → insert-frontmatter has has_anchor = False, so it carries no expected_sha256; invariant #8's content guard cannot protect it at clean time. This is a known deferred hole — Phase 4 (clean) MUST handle insert-frontmatter application explicitly (e.g. re-derive frontmatter presence at apply time rather than trusting a cached hash). Recorded here and in CLAUDE.md so it is not silently inherited.
• [Guard is a content hash despite the "mtime guard" naming] → The guard compares expected_sha256, not mtime. Per-entry generated_at is that file's hash instant (distinct from the envelope generated_at / last_check stamp). The naming is historical; the mechanism is content-hash.
• [Zero-signal files are unread] → Zero-signal shortlisted files are presumptively cleared and never read by the model (a cost decision). This is a known v1 recall limit — a file with a real problem but no scanner signal is missed. Documented.
• [tool_version source mismatch] → tool_version is read from plugin.json (currently 0.0.1), while valid_report.json shows 0.1.0. Read from plugin.json and flag the mismatch; do not hardcode.
• [Generative raw_tokens needs a span to count] → A generative op has no exact_edit, so the model returns a non-persisted reducible_range; the assembler counts raw_tokens over that span. The range is not written to the report.

Migration Plan

Additive only — no existing behavior changes. Deploy order follows the task order: report_builder.py + its tests first (it is the guardrail all entries flow through), commands/hygiene.md in parallel, then the hygiene-check skill (depends on the builder and the command), then the classifier goldens + hermetic harness, then the CONTEXT.md updates. Rollback is removing the new script, command, skill, and fixtures; the deterministic core and estimator are untouched.

Open Questions (resolved — recorded as decisions)

1. report_builder.py is standalone, importing derive_safety_tier + KIND_TABLE from validate_report.py (no re-implementation).
2. Entry signals = scanner signals verbatim + an optional model gloss in detail (the validator does not constrain signal names; verbatim pass-through is a convention for trust).
3. insert-frontmatter has has_anchor = False → no expected_sha256 → no #8 content guard at clean time: a deferred hole, Phase 4 must handle it.
4. The guard is a content hash (expected_sha256) despite the "mtime guard" naming; per-entry generated_at = that file's hash instant (distinct from the envelope/last_check stamp).
5. Zero-signal files are unread (a cost decision) — a known v1 recall limit, documented.
6. Generative raw_tokens: the model returns a non-persisted reducible_range; the assembler counts that span.
7. Validate-before-rollover is a hard sequencing constraint (validate on a scratch path before write_report deletes the prior pair).
8. tool_version from plugin.json (currently 0.0.1; valid_report.json shows 0.1.0 — read from plugin.json, flag the mismatch).
9. A subagent + Bash inside a skill is sanctioned per the commit-skill precedent.