Wayfinder map: calibrate assessment inventory & rulebook refinements (os-doc-hygiene) #49

New Issue

Closed

opened 2026-07-15 16:00:52 +00:00 by jared · 0 comments

jared commented

2026-07-15 16:00:52 +00:00

Owner

Destination

A locked design — lifecycle-spec.md deltas + ADR amendments — for persisting the full :calibrate assessment inventory and related rulebook refinements: keep verdicts as rules, the nominations key, canonical file ordering, container-glob breadth guidance, and the extract-index pointer convention. The map ends when nothing is left to decide; implementation is handed off to an OpenSpec change.

Notes

Domain: plugins/os-doc-hygiene (existing pipeline is Python — extend in kind). Skills: /grilling + /domain-modeling for HITL tickets; /os-adr:find before design decisions; /os-adr:create for amendments. Standing preference for this effort: ticket bodies and resolution reports must carry worked examples (real paths, before/after globs) so the human answers minimal questions. Follows map #31 (lifecycle-aware doc hygiene); its locked spec is plugins/os-doc-hygiene/lifecycle-spec.md. Blocking is expressed as a "Blocked by #N" line in ticket bodies (tea/Forgejo, no native dependencies).

Decisions so far

Assessment inventory is operational, not merely informational — future :calibrate runs read it; also a human discussion surface
Keep verdicts persist as keep rules; exact-path singleton keeps allowed — matched = managed does the skipping; class-not-path test relaxed for keep tier only
Residual assessments live in a nominations key in .dochygiene-rules.json; rejects block exact repeats only — same file, second key; variants reach the judge with rejection context; consults resurface, never filter
Canonical rules-file ordering is writer-enforced, not hook-enforced — grouped by lifetime tier, glob-sorted within; no post-command hook
Narrow autoresearch/*/ to conventional prefixes — done: classic-/ + improve-/; motivating example for #55
Draft the container-glob breadth guidance (rule-quality test amendment) — enumerate sibling prefixes as separate rules, never widen to the container; container globs only for wholly machine-owned dirs; includes two corrective judge.md edits (its step 2 + example taught the anti-pattern)
Design the nominations key schema and intake filter — nominations key with consults/rejected sub-keys (settled answers stay plain rules); deterministic Step 3.5 intake filter drops exact repeats + injects related-rejection context to the judge; human Step 5 declines persist as rejections; singleton keeps leave by hand-deletion only; writer-enforced ordering
Design the extract-index pointer convention — per-directory extracted.md written by the :clean extract op (vault extractions only); entry = vault link + value description + provenance line; protected by one global **/extracted.md → keep rule; judge tests: cited→KEEP, generalizes+standalone→EXTRACT, unclear→consult; conventions.json graduation ruled out (fog closed)
Decide eval/test coverage for the nominations intake filter and consult loop — deterministic seams (intake filter, canonical writer) get unit tests; model-facing seams (judge nominations-memory context, consult resurfacing) get worked examples + production IRL audits, no new harnesses — both are human-gated downstream
Assemble the spec deltas + ADR amendments — locked design assembled in the working tree 2026-07-15: lifecycle-spec.md deltas (extract index, nominations memory, canonical ordering, nomination intake filter, keep-tier relaxation, enumerate-siblings test, test-coverage decisions), ADR-0038/0039 amendments, global **/extracted.md keep rule, judge.md corrective edits + the two worked examples; implementation hands off to an OpenSpec change — the map is complete.

Not yet specified

(empty — the frontier has reached the destination's edge; only open tickets remain)

Out of scope

Implementation of the locked design — handed to an OpenSpec change after the map completes (decided at charting).
Wider rollout / bulk cleaning across projects (unchanged from map #31's boundary).

## Destination A locked design — lifecycle-spec.md deltas + ADR amendments — for persisting the full :calibrate assessment inventory and related rulebook refinements: keep verdicts as rules, the nominations key, canonical file ordering, container-glob breadth guidance, and the extract-index pointer convention. The map ends when nothing is left to decide; implementation is handed off to an OpenSpec change. ## Notes Domain: plugins/os-doc-hygiene (existing pipeline is Python — extend in kind). Skills: /grilling + /domain-modeling for HITL tickets; /os-adr:find before design decisions; /os-adr:create for amendments. Standing preference for this effort: ticket bodies and resolution reports must carry worked examples (real paths, before/after globs) so the human answers minimal questions. Follows map #31 (lifecycle-aware doc hygiene); its locked spec is plugins/os-doc-hygiene/lifecycle-spec.md. Blocking is expressed as a "Blocked by #N" line in ticket bodies (tea/Forgejo, no native dependencies). ## Decisions so far - [Assessment inventory is operational, not merely informational](https://forgejo.swansoncloud.com/jared/cc-os/issues/50) — future :calibrate runs read it; also a human discussion surface - [Keep verdicts persist as keep rules; exact-path singleton keeps allowed](https://forgejo.swansoncloud.com/jared/cc-os/issues/51) — matched = managed does the skipping; class-not-path test relaxed for keep tier only - [Residual assessments live in a nominations key in .dochygiene-rules.json; rejects block exact repeats only](https://forgejo.swansoncloud.com/jared/cc-os/issues/52) — same file, second key; variants reach the judge with rejection context; consults resurface, never filter - [Canonical rules-file ordering is writer-enforced, not hook-enforced](https://forgejo.swansoncloud.com/jared/cc-os/issues/53) — grouped by lifetime tier, glob-sorted within; no post-command hook - [Narrow autoresearch/*/ to conventional prefixes](https://forgejo.swansoncloud.com/jared/cc-os/issues/54) — done: classic-*/ + improve-*/; motivating example for #55 - [Draft the container-glob breadth guidance (rule-quality test amendment)](https://forgejo.swansoncloud.com/jared/cc-os/issues/55) — enumerate sibling prefixes as separate rules, never widen to the container; container globs only for wholly machine-owned dirs; includes two corrective judge.md edits (its step 2 + example taught the anti-pattern) - [Design the nominations key schema and intake filter](https://forgejo.swansoncloud.com/jared/cc-os/issues/56) — `nominations` key with `consults`/`rejected` sub-keys (settled answers stay plain rules); deterministic Step 3.5 intake filter drops exact repeats + injects related-rejection context to the judge; human Step 5 declines persist as rejections; singleton keeps leave by hand-deletion only; writer-enforced ordering - [Design the extract-index pointer convention](https://forgejo.swansoncloud.com/jared/cc-os/issues/57) — per-directory `extracted.md` written by the :clean extract op (vault extractions only); entry = vault link + value description + provenance line; protected by one global `**/extracted.md → keep` rule; judge tests: cited→KEEP, generalizes+standalone→EXTRACT, unclear→consult; conventions.json graduation ruled out (fog closed) - [Decide eval/test coverage for the nominations intake filter and consult loop](https://forgejo.swansoncloud.com/jared/cc-os/issues/59) — deterministic seams (intake filter, canonical writer) get unit tests; model-facing seams (judge nominations-memory context, consult resurfacing) get worked examples + production IRL audits, no new harnesses — both are human-gated downstream - [Assemble the spec deltas + ADR amendments](https://forgejo.swansoncloud.com/jared/cc-os/issues/58) — locked design assembled in the working tree 2026-07-15: lifecycle-spec.md deltas (extract index, nominations memory, canonical ordering, nomination intake filter, keep-tier relaxation, enumerate-siblings test, test-coverage decisions), ADR-0038/0039 amendments, global `**/extracted.md` keep rule, judge.md corrective edits + the two worked examples; implementation hands off to an OpenSpec change — the map is complete. ## Not yet specified (empty — the frontier has reached the destination's edge; only open tickets remain) ## Out of scope - Implementation of the locked design — handed to an OpenSpec change after the map completes (decided at charting). - Wider rollout / bulk cleaning across projects (unchanged from map #31's boundary).