FACTORY-HYGIENE #39: hot-file-path detector

docs/FACTORY-HYGIENE.md

@@ -81,6 +81,7 @@ is never destructive; retiring one requires an ADR in
 | 36 | Incorrectly-scoped gap-finder (retrospective) | Every 5-10 rounds (proposed — Aaron 2026-04-20 late) | TBD — candidate skill (queued in BACKLOG P1 alongside row 35); may collapse into a single "scope-hygiene" skill pending row-consolidation research | factory | Retrospective sweep for items whose scope tag is **present but wrong** — factory-level rules tagged `project: zeta`, Zeta-specific rules tagged factory, over-broad / under-broad declarations. Distinct from row 35 (missing tag) — this is *tag-exists-but-incorrect*. Trigger examples: Aaron's 2026-04-20 catch of "cheap-but-zeta-specific governance" in the skill-edit-gating-tiers research doc (factory-scope governance mislabeled as Zeta-specific). Flags candidates to HUMAN-BACKLOG as `scope-correction` rows. | Audit doc per round + HB row per mis-scoped item | `feedback_factory_default_scope_unless_db_specific.md` + `project_factory_reuse_beyond_zeta_constraint.md` + `user_absorb_time_filter_always_wanted.md` |
 | 37 | WIP-limit discipline (Kanban) | Round open + per-persona session-open (always-on, not triggered) | All agents (self-administered) + Architect for cross-persona visibility | factory | Per-persona in-flight work cap (suggested 3: proposals / findings / drafts not yet landed); cross-persona cap (suggested 7 under architect-bottleneck review queue per GOVERNANCE §11). Over-cap flags to HUMAN-BACKLOG as `wip-pressure` rows. Always-on discipline per `docs/FACTORY-METHODOLOGIES.md` pull-vs-always-on criterion (this row is always-on, therefore not a skill). Cap numbers are *suggestions*; tune after 5-10 rounds of observation per Six Sigma Measure → Improve loop. | Inline self-report + HUMAN-BACKLOG row if over-cap + Architect notebook tally column | `user_kanban_six_sigma_process_preference.md` + `docs/FACTORY-METHODOLOGIES.md` + `docs/research/kanban-six-sigma-factory-process.md` + GOVERNANCE.md §11 |
 | 38 | Harness-surface cadenced audit | Every 5-10 rounds per populated harness (same cadence as skill-tune-up and agent-QOL). Stubs don't tick. | Per populated harness: Claude owned by Architect (Kenji) **interim** until a dedicated harness-guide role is decided; plugin-provided `claude-code-guide` agent (Anthropic official plugin cache, not a local `.claude/agents/` file) is a reference resource consulted during audit, not the audit runner. Codex / Cursor / GitHub Copilot / Antigravity / Amazon Q / Kiro — TBD when populated (either dedicated guide per harness or a shared multi-harness guide). | factory | Audit each populated harness's platform surfaces for new features, cut features, behavioural changes. For Claude: model / Code CLI / Desktop app / Agent SDK / API. For Codex / Cursor / Copilot / Antigravity / Amazon Q / Kiro: per-harness equivalents inventoried at first-populated audit. Primary feature-comparison axis per harness is skill-authoring + eval-driven feedback loop (the Claude-Code feature that made it Aaron's primary choice — `memory/user_skill_creator_killer_feature_feedback_loop.md`). Update `docs/HARNESS-SURFACES.md` living inventory with adoption statuses (adopted / watched / untested / rejected / stub). When audit surfaces drift, either adopt (ADR if Tier-3), retire the workaround the new feature obsoletes, or record explicit rejection in `docs/WONT-DO.md`. Integration-point tests per harness are owned by a *different* harness per the capability-boundary rule (a harness cannot honestly self-verify its own factory integration from within itself). Triggering incidents: 2026-04-20 AutoMemory miss (Anthropic's Q1-2026 feature mis-attributed as factory-native) + 2026-04-20 multi-harness expansion (Aaron: factory supports multiple harnesses; each tests the others'). | `docs/HARNESS-SURFACES.md` audit log row per cycle per populated harness; ADRs under `docs/DECISIONS/` for Tier-3 adoptions; `docs/research/meta-wins-log.md` entry when a pre-existing factory assumption is found to have been wrong | `feedback_claude_surface_cadence_research.md` + `feedback_multi_harness_support_each_tests_own_integration.md` + `user_skill_creator_killer_feature_feedback_loop.md` + `reference_automemory_anthropic_feature.md` + `reference_autodream_feature.md` |
+| 39 | Hot-file-path detector | Round-cadence (every round close) or every 5-10 rounds — whichever catches churn drift before the next merge-tangle. Proposed 2026-04-21. | TBD — candidate capability skill `hot-file-detector` (queued in BACKLOG P1); Architect runs inline until the skill lands. | factory (ships to adopters as a command-line recipe) | `git log --since="60 days ago" --name-only --pretty=format: \| grep -v '^$' \| sort \| uniq -c \| sort -rn \| head -25` — git history *is* the index. Heuristic threshold: >20 changes in 60d on a single monolithic doc = investigate; >30 = refactor candidate (tune after 5-10 rounds). Per-file decision is one of four: `refactor-split` (per-row, per-round, per-section), `consolidate-reduce` (merge with a sibling), `accept-as-append-only` (legitimately append-only → split into per-round files rather than trimming), or `observe`. Pair with merge-tangle fingerprints from `docs/research/parallel-worktree-safety-2026-04-22.md` §9 — a hot file is worse if also in a recent conflict list. Triggering incident: PR #31 5-file merge-tangle (2026-04-21) where `docs/ROUND-HISTORY.md` at 33 changes / 60d was the #1 conflict source, and `docs/BACKLOG.md` at 26 already has an in-flight split ADR. | Audit doc per cycle listing top-N hot paths + per-file decision; BACKLOG rows for refactor-split candidates; ADRs for structural changes. | `feedback_hot_file_path_detector_hygiene.md` + `docs/DECISIONS/2026-04-22-backlog-per-row-file-restructure.md` (same pattern) |
 
 ## Ships to project-under-construction