hygiene: row #54 — backlog-refactor cadenced audit (Aaron 2026-04-23)

docs/FACTORY-HYGIENE.md

@@ -94,6 +94,7 @@ is never destructive; retiring one requires an ADR in
 | 49 | Post-setup script stack audit (bun+TS default; bash only under exempt paths or with exception label) | Author-time (every new `tools/**/*.{sh,ps1}` decision-flow walk per `docs/POST-SETUP-SCRIPT-STACK.md`) + cadenced detection every 5-10 rounds (same cadence as skill-tune-up / row #38 / harness-surface audit) + opportunistic on-touch (every time an agent adds or edits a script under `tools/`). | Author of the script (self-check at author-time against the decision-flow doc); Dejan (devops-engineer) on the cadenced detection sweep; Kenji (Architect) on migration-order decisions when multiple violations stack up. | both | **Author-time prevention:** walk the three-question flow in `docs/POST-SETUP-SCRIPT-STACK.md` before writing any new `tools/**/*.{sh,ps1}` — (Q1) pre-setup? → `tools/setup/` bash+PowerShell exempt; (Q2) skill-bundled? → skill-compatibility rules govern, not this row; (Q3) default bun+TypeScript unless an explicit exception (trivial pipeline / thin CLI wrapper / bash scaffolding / sibling-migration guardrail) applies, in which case the script MUST carry a header comment naming the exception. **Cadenced detection:** `tools/hygiene/audit-post-setup-script-stack.sh` lists every shell/PowerShell script under `tools/` and classifies each as `exempt` / `labelled-exception` / `violation`. Exit-2 on any new violation; CI / pre-commit-eligible. **Why both layers:** prevention catches new violations at author-time (cheap); detection catches drift — labels getting stripped on edits, exceptions becoming stale, scripts moving out of exempt paths. Ships to project-under-construction: adopters inherit the canonical-stack rule + the audit script + the decision-flow doc. Aaron 2026-04-22 triggering-directive-chain: *"if post setup backlog bun/ts"* → *"now add someting that will try to prevent that and and hygene it if it happens again"*. | Author-time: commit-message rationale for any new `.sh` under `tools/` outside `tools/setup/`, OR exception-label header in the script, OR BACKLOG row queuing bun+TS migration. Cadenced: audit script output (markdown), appended to `docs/hygiene-history/post-setup-script-stack-history.md` (per-fire schema per row #44); BACKLOG row per unlabeled violation. | `docs/POST-SETUP-SCRIPT-STACK.md` (prevention surface) + `tools/hygiene/audit-post-setup-script-stack.sh` (detection surface) + `memory/project_ui_canonical_reference_bun_ts_backend_cutting_edge_asymmetry` + `memory/project_bun_ts_post_setup_low_confidence_watchlist` |
 | 50 | Missing-prevention-layer meta-audit (every hygiene row carries a prevention classification: prevention-bearing / detection-only-justified / detection-only-gap) | Round cadence (same as rows #22 / #23 / #35 / #36) + opportunistic on-touch (every time a new row is added to `docs/FACTORY-HYGIENE.md` the author classifies it at landing). Not exhaustive; the round-close sweep catches un-classified rows and gap rows. | Architect (Kenji) on round-cadence classification review + gap-closure ROI assessment. All agents (self-administered) on on-touch: every new hygiene row MUST declare its prevention classification at landing; an unclassified row is itself a violation of this row. | factory | Sweep every row in `docs/FACTORY-HYGIENE.md` and classify each as one of: (a) **prevention-bearing** — an author-time / commit-time / trigger-time mechanism (hook, CI check, decision-flow doc, pre-commit lint, skill-gate) blocks or warns the violation BEFORE it materialises; (b) **detection-only-justified** — the class is fundamentally post-hoc (e.g., cadence-history row #44 — a fire-log can only exist AFTER the fire happens; wake-friction row #29 — friction is only observable at wake-time); (c) **detection-only-gap** — no principled reason the row is detection-only; a prevention layer COULD and SHOULD be built. Classification lives in `docs/hygiene-history/prevention-layer-classification.md` (one table row per hygiene row). **Why this row exists:** Aaron 2026-04-22 *"add a hygene for missing prevention layers"* — the factory had been quietly accumulating detection-only rows without asking the complementary question "could we have prevented this at author-time?". Without this meta-audit, the factory's reactive-cost grows silently. Parallels the existing meta-hygiene triangle (row #23 unknown-classes / #43 authored-but-unactivated / #44 cadence-history) by adding a fourth: row #47 is *"of the rows that ARE active and firing, which could have been prevented upstream"*. **Classification:** this is an **intentionality-enforcement** hygiene rule (Aaron 2026-04-22 tick-close: *"we are enforcing intentional decsions"*) — the audit cannot compute whether a row's classification is correct, but it forces every new hygiene row to carry an explicit prevention-vs-detection decision at landing. Declining to classify is itself the violation. See `memory/feedback_enforcing_intentional_decisions_not_correctness.md`. Ships to project-under-construction: adopters inherit the classification discipline + the meta-audit script + the obligation to classify any new hygiene row at landing. | `docs/hygiene-history/prevention-layer-classification.md` (classification matrix, one row per hygiene row) + cadenced audit run landed as `docs/hygiene-history/missing-prevention-layer-audit-YYYY-MM-DD.md` noting gap rows; ROUND-HISTORY row when a gap row gains a prevention layer (detection-only-gap → prevention-bearing transition); BACKLOG row per gap with prevention-design ROI estimate. | `tools/hygiene/audit-missing-prevention-layers.sh` + this row's self-reference (its own prevention layer is the at-landing-classify obligation declared in this Checks/enforces column) |
 | 51 | Cross-platform parity audit (bash / PowerShell / bun+TS twin check across macOS / Windows / Linux / WSL) | Detect-only now (landed 2026-04-22); cadenced detection every 5-10 rounds (same cadence as row #46); opportunistic on-touch every time an agent adds or edits a script under `tools/`. Enforcement deferred until baseline is green AND CI matrix runs `--enforce` on `macos-latest` / `windows-latest` / `ubuntu-latest` (WSL inherits ubuntu-latest for CI). | Dejan (devops-engineer) on cadenced detection; author of the script (self-check at author-time against the rule classes in the audit's decision-record header block). Kenji (Architect) on CI-matrix-enforcement sign-off when baseline is green. | both | `tools/hygiene/audit-cross-platform-parity.sh` classifies every script under `tools/` by rule class: (a) **pre-setup** (`tools/setup/**`) — both `.sh` AND `.ps1` required per Q1 dual-authoring rule (`memory/feedback_preinstall_scripts_forced_shell_meet_developer_where_they_live`); (b) **post-setup permanent-bash** (`thin wrapper over existing CLI` / `trivial find-xargs pipeline` / `stay bash forever`) — `.ps1` twin required per the Windows-twin obligation (`memory/feedback_stay_bash_forever_implies_powershell_twin_obligation.md`); (c) **post-setup transitional** (`bun+TS migration candidate` / `bash scaffolding`) — no twin obligation (long-term plan is one cross-platform bun+TS script); (d) **post-setup bun+TS** (`*.ts` under `tools/`) — no twin needed (cross-platform native via bun). `--summary` prints counts; `--enforce` flips exit 2 on gaps. **Why detect-only first:** baseline at first fire (2026-04-22) was 13 gaps — 12 pre-setup bash without `.ps1` twin (Q1 violation silently accumulating since `tools/setup/` existed) + 1 post-setup permanent-bash (`tools/profile.sh`) without `.ps1` twin. Turning enforcement on before triage would block every CI run. **Why this row exists:** Aaron 2026-04-22 *"missing mac/windows/linux/wsl parity (ubuntu latest) we can deffer but should have the hygene in place for when we want to enforce and it will be more obvious to you in the future that we are cross platform."* Cross-platform-first must be a *visible* factory property (audit exists, runs, prints the gap) before it becomes an enforced gate. Same pattern as FACTORY-HYGIENE rows #23 / #43 / #47. See `memory/feedback_cross_platform_parity_hygiene_deferred_enforcement.md`. **Classification (row #47):** **prevention-bearing** — the audit runs at author-time (opportunistic on-touch) and surfaces the gap before it lands, same as row #46. The audit itself is a detect-only mechanism but detect-only surfaces the obligation at author-time when the author runs it. Ships to project-under-construction: adopters inherit the parity audit + the decision-record-block pattern + the CI-matrix obligation once it's wired. | Audit output in repo root on each fire; cadenced runs appended to `docs/hygiene-history/cross-platform-parity-history.md` (per-fire schema per row #44); BACKLOG row per gap at triage time; ROUND-HISTORY row when a gap resolves. | `tools/hygiene/audit-cross-platform-parity.sh` (detection + decision-record header block) + `memory/feedback_cross_platform_parity_hygiene_deferred_enforcement.md` + `memory/feedback_stay_bash_forever_implies_powershell_twin_obligation.md` + `memory/feedback_preinstall_scripts_forced_shell_meet_developer_where_they_live` + `docs/POST-SETUP-SCRIPT-STACK.md` |
+| 54 | Backlog-refactor cadenced audit (overlap / staleness / priority-drift / knowledge-update sweep of `docs/BACKLOG.md`) | Cadenced detection every 5-10 rounds (same cadence as rows #5 / #23 / #38 / #46 meta-audits) + opportunistic on-touch when a tick adds a new BACKLOG row and the author notices adjacent rows that may overlap. Not exhaustive; bounded passes per firing are acceptable. | Architect (Kenji) on round-cadence sweeps; `backlog-scrum-master` skill if explicitly invoked; all agents (self-administered) on on-touch overlap-spot during authoring. | factory | Read `docs/BACKLOG.md` (or a scoped slice — P0/P1 first if full scan is too large) and apply the following passes: (a) **overlap cluster** — two or more rows describing the same concern from different angles get flagged; decide merge (single consolidated row) or sharpen (two rows with clear non-overlap scope boundaries); (b) **stale retire** — rows where context has died, implementation landed without retire-action, or assumption has been falsified by newer knowledge get explicitly retired with a "retired: <reason>" marker (not silent deletion — signal-preservation still applies); (c) **re-prioritize** — priority labels (P0/P1/P2/P3) re-examined against current knowledge; any row whose priority feels wrong after re-read gets a justified move with a one-line rationale; (d) **knowledge absorb** — rows written before a newer architectural insight landed get rewording / cross-refs to the new substrate (e.g., rows predating AutoDream cadence now cite the policy; rows predating scheduling-authority sharpening now note self-schedulability); (e) **document** — ROUND-HISTORY row per fire with pre-audit and post-audit row counts + what was merged / retired / re-prioritized / updated. **Why this row exists:** the human maintainer 2026-04-23 *"we probalby need some meta iteam to refactor the backlog base on current knowledge and look for overlap, this is hygene we could run from time to time so our backlog is not just a dump"*. The BACKLOG is the triage substrate for every future tick's "what to pick up" decision; without periodic meta-audit it becomes an append-only log rather than a living triage surface. **Classification (row #50):** **detection-only-justified** — accumulated drift (overlap, staleness, priority-drift, knowledge-update-gap) is inherently post-hoc; no author-time check can prevent rows from becoming overlapping with *future* rows not yet written. **Maintainer-scope boundary:** rows with explicit maintainer framing at their priority (e.g., P0 rows the human maintainer explicitly set) stay at that priority; re-prioritization applies within the agent-owned priority space only. Ships to project-under-construction: adopters inherit the cadenced-sweep discipline + the retire-with-marker convention + the ROUND-HISTORY documentation pattern. | ROUND-HISTORY row per fire with pre/post row counts + merged/retired/re-prioritized/updated actions; `docs/hygiene-history/backlog-refactor-history.md` (per-fire schema per row #44 — date, agent, rows touched, actions taken, pre/post counts, next-fire-expected-date). | `docs/BACKLOG.md` (target surface) + governing rule in per-user memory (not in-repo; lives at `~/.claude/projects/<slug>/memory/feedback_backlog_hygiene_cadenced_refactor_look_for_overlap_not_just_dump_2026_04_23.md`) + `.claude/skills/backlog-scrum-master/SKILL.md` (dedicated runner when invoked) + `.claude/skills/reducer/SKILL.md` (Rodney's Razor applied at backlog level) + sibling meta-audit rows #5, #23, #38, #46, #50 |
 | 52 | Tick-history bounded-growth audit (`docs/hygiene-history/loop-tick-history.md` line-count vs threshold) | Detect-only (landed 2026-04-22); cadenced detection once per round-close (same cadence as row #44 cadence-history sweep, since this is the canonical row #44 worked example auditing itself); opportunistic on-touch whenever the tick-history file is read or edited. Archive action itself remains manual for now; deferring automation to the larger BACKLOG row that also covers threshold-revision and append-without-reading refactor. | Dejan (devops-engineer) on cadenced detection; the tick itself (self-administered at tick-close) on the opportunistic on-touch — each tick's end-of-tick sequence can invoke this audit after the append + commit to get a `within bounds: 96/500 lines` visibility signal. | factory | `tools/hygiene/audit-tick-history-bounded-growth.sh` checks the file's line count against a threshold (default 500, overrideable via `--threshold N`) and exits 0 within bounds / 2 over threshold. The threshold is set lower than the stated 5000-line paper bound because the file is read on every tick-close append — a per-tick context cost that scales linearly with file size — and 5000 lines represents too large a context hit on a 1-minute cadence. The audit's header block carries a mini-ADR decision record for the 500-line choice (context / decision / alternatives / supersedes / expires-when). **Why this row exists:** Aaron 2026-04-22 tick-fire interrupt: *"does loop tick history grow unbounded? that's an issue if so you just read it"*. Honest state was stated-bound-no-enforcement: file header named 5000 lines, nothing checked it. This row closes the enforcement gap for the threshold-check half of the full BACKLOG row (archive-action + append-without-reading refactor remain deferred). **Self-referential closure:** the tick-history file IS the canonical row-#44 cadence-history-tracking worked example (named explicitly in row #44's "Durable output" citation). Until this row landed, the most-cadenced surface in the factory — the tick itself — had its fire-log surface unaudited for its own growth. Meta-audit triangle remains intact (existence #23 / activation #43 / fire-history #44), and row #49 adds a fourth: fire-history files themselves need bounded-growth audits because they grow at the cadence of the surface they track. **Classification (row #47):** **prevention-bearing** — the audit surfaces approaching-threshold warnings at 80% so the archive action can be planned, rather than reactive-only at over-threshold. Ships to project-under-construction indirectly: adopters inherit the pattern (fire-log files under their own `docs/hygiene-history/` need the same bounded-growth treatment), not this exact script. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/tick-history-bounded-growth-history.md` (per-fire schema per row #44); BACKLOG row when archival is due (archive-action itself queued as part of the larger tick-history enforcement BACKLOG row); ROUND-HISTORY row when threshold changes or archive action executes. | `tools/hygiene/audit-tick-history-bounded-growth.sh` (detection + mini-ADR header block) + `docs/hygiene-history/loop-tick-history.md` (target surface, canonical row #44 worked example) + BACKLOG row *"Loop-tick-history bounded-growth enforcement"* (larger follow-up: threshold revision + append-without-reading refactor + archive action) |
 
 ## Ships to project-under-construction