# Tasks: Add Check

> **Execution shape:** Task 1 is a **human-gate** (already discharged — the
> `report_builder.py` finalize pass is approved). Group 2 (`report_builder.py` +
> tests) and Group 3 (`commands/hygiene.md`) are **independent and run in
> parallel**. Group 4 (the `hygiene-check` skill) is **sequential after Groups 2
> and 3**. Group 5 (classifier goldens + hermetic harness) is **sequential after
> Groups 2 and 4** and is **human-gated** per the META-RULE. Group 6 (CONTEXT.md)
> runs last. Model routing is annotated per group.

## 1. Human-gate — approve the deterministic finalize pass (DONE)

- [x] 1.1 Approve `report_builder.py` as a standalone, model-free finalize pass
      interposed between model classification and `StateStore.write_report`, owning
      the four fields the model must not author (`expected_sha256`, `safety_tier`,
      `is_destructive`/`is_reversible` for deterministic ops, `raw_tokens`).

## 2. `report_builder.py` + tests — parallel with Group 3 (model: Sonnet)

- [ ] 2.1 Implement `scripts/report_builder.py` as a standalone, model-free
      assembler. Input: the scanner artifact + the model's slim per-file
      classification proposals. Output: a full schema-valid machine report + a
      deterministic human-report skeleton. Use an injected clock/filesystem.
- [ ] 2.2 Compute `exact_edit.expected_sha256` over each file's **current bytes**
      for anchor-bearing kinds only; note that `insert-frontmatter`
      (`has_anchor = False`) carries no `expected_sha256` (deferred hole for clean).
- [ ] 2.3 Set `(is_destructive, is_reversible)` from `KIND_TABLE[kind]` and compute
      `safety_tier = derive_safety_tier(op_type, is_destructive, is_reversible)`,
      both **imported** from `validate_report.py` (single source of truth —
      invariant #10; no re-implementation).
- [ ] 2.4 Extract the span (anchor range / `reducible_range` / whole file for
      `move-to-archive`) and source `token_estimate` via
      `token_estimator.default_estimator().estimate_for_report(span_text)` —
      v1 `raw_tokens` only, weighting `null` (invariant #6).
- [ ] 2.5 Assemble the envelope: `schema_version` `"1.0"`, `tool_version` read from
      `plugin.json` (flag a mismatch with `valid_report.json`), per-entry
      `generated_at` = that file's hash instant, envelope `generated_at` = the run
      instant. Emit the deterministic human-report skeleton (mechanical parts only).
- [ ] 2.6 Reject malformed proposal JSON before computing any field.
- [ ] 2.7 **Tests:** assert the sha256, the derived `(is_destructive,
      is_reversible, safety_tier)`, and `raw_tokens` for each kind; assert the
      assembled report round-trips through `validate_report.py` (exit 0); assert the
      generative path counts `raw_tokens` over the non-persisted `reducible_range`;
      injected clock/fs.

## 3. `commands/hygiene.md` — parallel with Group 2 (model: Haiku)

- [ ] 3.1 Author a single `commands/hygiene.md` with minimal frontmatter
      (`name: hygiene`; description naming `/hygiene check` and `/hygiene status`)
      that dispatches on `$ARGUMENTS`.
- [ ] 3.2 Route `check [--scope <glob-or-path>] [--category <class|subtype>]` →
      invoke the `hygiene-check` skill (pass the flags through).
- [ ] 3.3 Implement `status` **inline** (a few `python3` calls): read
      `get_last_check` / `get_last_clean` / `get_last_reminded` and whether a report
      exists. Read-only — no scan, no model.
- [ ] 3.4 Reserve `clean` / `sweep` with a "not yet implemented (Phase 4)" message;
      print usage + current status for no/unknown args.

## 4. `skills/hygiene-check/SKILL.md` — sequential after Groups 2, 3 (model: Sonnet)

- [ ] 4.1 Author `skills/hygiene-check/SKILL.md` with frontmatter mirroring the
      `commit` skill. The subagent points at a **workflow doc**, not SKILL.md
      itself, to avoid recursion (per the `commit`-skill precedent).
- [ ] 4.2 Implement the deterministic steps: scan (`scanner.py`, `--scope` →
      `--globs`/path filter), select signal-bearing candidates (zero-signal files
      presumptively cleared, not read by the model), finalize (`report_builder.py`),
      validate **on a scratch path** (validate-before-rollover, invariant #4), write
      (`write_report`), stamp (`set_last_check` with the same run instant).
- [ ] 4.3 Write the **Sonnet classification subagent prompt**: per signal-bearing
      file, return a slim judgment-only proposal (`category` from the closed enum,
      `signals` verbatim + optional `detail` gloss, `op`, `op_type`, the
      `exact_edit` **skeleton** for deterministic or a non-persisted
      `reducible_range` for generative, `confidence`). The model supplies **no**
      `expected_sha256` / `is_destructive` / `is_reversible` / `safety_tier`.
- [ ] 4.4 Encode the decision rules (subtype → kind → tier) and the Opus-escalation
      rule (low confidence on stale-vs-bloat or destructive-vs-generative).
- [ ] 4.5 Encode failure handling: validation fail (exit 1) → do not write, map
      violations to entries, re-prompt or drop and re-validate; usage error (exit 2)
      → stop; empty shortlist → write empty-`entries` report + stamp; malformed
      proposal → re-prompt. Record `--scope` / `--category` in the report header.

## 5. Classifier goldens + hermetic harness — after Groups 2, 4; HUMAN-GATED (model: Sonnet)

- [ ] 5.1 Create 3–5 static fixture trees under
      `examples/golden/classifier/<n>-<name>/` (`input/` with stable sha256s,
      `expected.json`, optional `notes.md`), each mapping a subtype to a **distinct**
      `exact_edit.kind`: `orphaned`→`delete-range`/`confirm`,
      `superseded`→`move-to-archive`/`auto`,
      `completed-in-place`→`insert-frontmatter`/`auto`, `duplicated`→`dedupe`/`auto`,
      `distill`→generative/`confirm`.
- [ ] 5.2 Implement `tests/test_classifier_golden.py` **hermetically** (no live
      model call): (1) `scanner.py` on `input/` emits the expected signals on the
      right paths; (2) `validate_report.py` on each `expected.json` → exit 0; (3)
      stable-field match against a captured/committed check output (`category.class`,
      `category.subtype`, `op_type`, derived `safety_tier`, `exact_edit.kind`).
      Op-prose and exact anchor line numbers are advisory (flag, do not hard-fail).
- [ ] 5.3 Document the **separate** live model-classification regression harness
      (manually/agent-invoked, NOT part of the unit suite).
- [ ] 5.4 Update `examples/golden/CONTEXT.md` to distinguish classifier goldens from
      the schema-shape fixtures.

## 6. CONTEXT.md updates — last (model: Haiku)

- [ ] 6.1 Author `CONTEXT.md` for `commands/` and `skills/` (progressive
      disclosure).
- [ ] 6.2 Update `scripts/CONTEXT.md` to add `report_builder.py` (its role as the
      deterministic finalize pass and the symbols it imports).

## 7. Validation

- [ ] 7.1 Run `openspec validate add-check --strict` and confirm it passes.