pan-wizard 3.36.0 → 3.37.0

package/docs/specs/internal_cleanup_code_quality_featureai.md

@@ -0,0 +1,486 @@
+# Feature Specification: Internal Cleanup & Code Quality Hardening
+
+**Mode:** `--internal` (skip competitive intelligence)
+**Date:** 2026-03-03
+**Status:** Ready for Implementation
+
+---
+
+## Phase 0: Problem Framing
+
+### 0.1 Problem Statement
+
+PAN Wizard's 15 core modules (4,770+ LOC), CLI dispatcher (735+ LOC), and installer (2,636 LOC) have accumulated technical debt across 23 development sessions. While the codebase is functionally correct (1,180 tests, 0 failures), a deep audit reveals ~170 issues including: duplicate functions across modules, functions exceeding 50-line complexity budgets, missing argument validation in the dispatcher, inconsistent error handling patterns, dead/unused code, and scattered magic numbers. These issues increase maintenance cost, slow onboarding for contributors, and create surface area for future bugs.
+
+### 0.2 Demand Evidence
+
+| Evidence Type | Source | Finding |
+|--------------|--------|---------|
+| Internal audit | 5 parallel scan agents | 170+ issues found across all modules (0 P0, 4 P1, 26 P2, 62 P3, 49 P4, 29 P5) |
+| Memory file | MEMORY.md | 23 sessions of accumulated patterns documented; stability patterns applied iteratively but never holistically |
+| User request | This conversation | User explicitly asked for "internal cleanup and review and optimisations, scan all code and make sure everything is perfect" |
+| Architecture docs | ARCHITECTURE.md | Cognitive complexity budget defined (50 lines, 3 nesting, 4 params) but 12+ functions exceed it |
+
+### 0.3 Scope Definition
+
+| In Scope | Out of Scope (and why) |
+|----------|------------------------|
+| Dead code removal | New features (this is cleanup only) |
+| Function complexity reduction (>50 LOC) | Installer refactoring to strategy pattern (too large, separate effort) |
+| Duplicate function consolidation | Test file style unification (test vs it, assert vs assert/strict — cosmetic) |
+| Missing argument validation in dispatcher | Performance optimization of file I/O (already fast enough) |
+| Magic number extraction to constants | Documentation rewrites (already synced in prior session) |
+| Unused import cleanup | |
+| Consistent error handling patterns | |
+
+### 0.4 Success Criteria
+
+```
+SC-1: All 15 core modules have zero functions exceeding 50 lines
+SC-2: Zero duplicate functions across modules (getArchivedPhaseDirs consolidated)
+SC-3: All dispatcher argument access has bounds validation (args[idx+1] checked)
+SC-4: Zero dead code (unused imports, unused exports, unreachable branches)
+SC-5: All magic numbers extracted to constants.cjs
+SC-6: No test regressions — 1180/1180 tests still pass
+SC-7: No new runtime dependencies added
+```
+
+### 0.5 Cannibalization Check
+
+| Existing Command/Agent | Overlap? | Impact |
+|-----------------------|----------|--------|
+| `/pan:health --repair` | Partial | Health checks .planning/ integrity, not code quality — no conflict |
+| `/pan:focus-scan` | None | Scans work items, not code quality |
+| Tests | None | Tests verify behavior, this fixes internals |
+
+### 0.6 Cognitive Load Assessment
+
+| Metric | Before | After | Delta |
+|--------|--------|-------|-------|
+| Commands a new user must learn | 41 | 41 | 0 |
+| New concepts introduced | 0 | 0 | 0 |
+| Score | — | — | simplifies (-1) |
+
+---
+
+## Phase 1: Internal Reconnaissance — Audit Results
+
+### 1.1 Consolidated Issue Inventory
+
+**Total issues found: ~170 across 5 parallel audits**
+
+| Module Group | P1 | P2 | P3 | P4 | P5 | Total |
+|-------------|----|----|----|----|----|----|
+| Core 1-5 (constants, core, utils, frontmatter, config) | 1 | 5 | 8 | 12 | 1 | 27 |
+| Core 6-10 (state, init, phase, roadmap, verify) | 0 | 11 | 28 | 9 | 4 | 52 |
+| Core 11-15 (milestone, commands, template, context-budget, focus) | 0 | 6 | 14 | 16 | 7 | 43 |
+| Dispatcher + Tests | 2 | 6 | 6 | 8 | 4 | 26 |
+| Installer | 1 | 7 | 8 | 5 | 1 | 22 |
+| **TOTAL** | **4** | **35** | **64** | **50** | **17** | **170** |
+
+### 1.2 Top Findings by Category
+
+#### A. Dead Code (13 items)
+1. **core.cjs:216** — `execFileSync` re-imported inside `execGit()` (already at top, line 7)
+2. **milestone.cjs:7** — `isSummaryFile` imported but never used in module
+3. **phase.cjs:887** — `phaseName` param in `markPhaseCompleteInRoadmap()` documented as unused
+4. **phase.cjs:990** — `totalPhases` param in `updateStateAfterPhaseComplete()` documented as unused
+5. **pan-tools.cjs:662** — `core.cjs` re-required inside focus/design case block
+
+#### B. Duplicate Functions (3 items)
+1. **core.cjs:388 vs utils.cjs:130** — `getArchivedPhaseDirs()` vs `listArchivedPhaseDirs()` are nearly identical (33 vs 38 LOC)
+2. **config.cjs:372-383 vs 528-534** — Standards section parsing logic duplicated
+3. **commands.cjs:473-485** — `parseDecisions()` inline instead of module-level like similar helpers
+
+#### C. Functions Exceeding 50 Lines (12 items)
+1. **config.cjs:21-106** — `cmdConfigEnsureSection()` — 86 lines
+2. **config.cjs:462-554** — `cmdStandardsPhaseTrack()` — 93 lines
+3. **core.cjs:123-186** — `loadConfig()` — 64 lines
+4. **commands.cjs:320-446** — `cmdCommit()` — 127 lines
+5. **commands.cjs:682-754** — `renderHealthReport()` — 73 lines
+6. **focus.cjs:234-332** — `allocateBudget()` — 99 lines
+7. **frontmatter.cjs:223-295** — `parseMustHavesBlock()` — 73 lines
+8. **phase.cjs:536-587** — `renumberDecimalPhases()` — 52 lines
+9. **phase.cjs:602-667** — `renumberIntegerPhases()` — 66 lines
+10. **verify.cjs:25-119** — `cmdVerifySummary()` — 95 lines
+11. **verify.cjs:738-804** — `checkPhaseContents()` — 67 lines
+12. **verify.cjs:930-996** — `cmdValidateHealth()` — 67 lines
+
+#### D. Missing Argument Validation (11 dispatcher locations)
+- pan-tools.cjs lines 225, 303, 330, 332, 355, 437, 455, 467, 478, 497, 621
+- Pattern: `args[1]` or `args[2]` accessed without undefined check before passing to cmd functions
+
+#### E. Magic Numbers Not in Constants (15+ items)
+- focus.cjs: budget limits 40/60, ratios 0.6/0.8
+- template.cjs: thresholds 2/3/5/6
+- context-budget.cjs: CHARS_PER_TOKEN = 4
+- commands.cjs: DEFAULT_SENSITIVE_PATTERNS array
+- verify.cjs: health status strings ('broken', 'degraded', 'healthy')
+
+#### F. Inconsistent Patterns (20+ items)
+- Error handling: some functions use `error()`, others `output({error: ...})`
+- State mutation: `cmdStateJson()` rebuilds state as a side effect
+- Regex global state: `PHASE_HEADER_RE.lastIndex = 0` reset required in multiple places
+- Flag parsing: 44 separate `indexOf()` calls with no shared helper
+
+### 1.3 Convention Enforcement Checklist
+
+- [x] Function naming: `cmd*` for entry points, camelCase for helpers — **CONSISTENT**
+- [x] File reads: try-catch pattern — **CONSISTENT (zero existsSync in core)**
+- [x] File writes: try-catch wrapping — **CONSISTENT**
+- [x] JSON output via `output()` — **CONSISTENT**
+- [x] Errors via `error()` — **MOSTLY CONSISTENT** (some use `output({error:...})`)
+- [x] Paths through `toPosix()` — **CONSISTENT**
+- [x] Module exports at bottom — **CONSISTENT**
+- [x] CommonJS format — **CONSISTENT**
+- [x] Zero runtime deps — **MAINTAINED**
+- [ ] Functions under 50 lines — **12 VIOLATIONS**
+- [ ] Max 3 nesting levels — **~8 VIOLATIONS**
+- [ ] Max 4 parameters — **~5 VIOLATIONS**
+
+---
+
+## Phase 3: Strategic Analysis
+
+### 3.1 Blue Ocean Four Actions Framework
+
+| Action | Decisions |
+|--------|-----------|
+| **ELIMINATE** | Duplicate functions (getArchivedPhaseDirs x2), dead imports, unused params, re-required modules |
+| **REDUCE** | Function complexity (12 functions over 50 lines), dispatcher arg parsing duplication (44 indexOf calls), magic numbers scattered across 6 modules |
+| **RAISE** | Code consistency (error handling patterns, argument validation, naming), maintainability (extract helpers, reduce nesting) |
+| **CREATE** | `getArgValue()` dispatcher helper, extracted standards parsing helper, consolidated archive search |
+
+### 3.2 Strategic Moat Analysis
+
+| Moat Type | Contribution | Score (0-5) |
+|-----------|-------------|-------------|
+| Context Engineering | No change | 0 |
+| Cross-Platform | Stronger (fewer fragile patterns) | 1 |
+| Developer Experience | No user-facing change | 0 |
+| Zero Dependencies | Maintained | 0 |
+| State Persistence | No change | 0 |
+| Verification Quality | Stronger (fewer internal bugs possible) | 1 |
+| **Maintainability** | **Significantly improved** | **4** |
+
+### 3.3 Strategic Recommendation
+
+**Build.** This is pure internal quality improvement with zero user-facing risk. The codebase is functionally sound (1,180 tests prove it) but 12 functions exceed the project's own 50-line complexity budget, 3 functions are duplicated across modules, and the dispatcher has 11 unvalidated argument accesses. Fixing these reduces maintenance cost, makes the codebase more approachable for contributors, and prevents future bugs from accumulating in complex functions. Delivery should be incremental — dead code first, then duplication, then complexity reduction — each independently testable.
+
+---
+
+## Phase 3.5: Architecture Assessment
+
+### 3.5.1 Feature Type: Core Enhancement
+All changes are internal to existing modules. No new commands, agents, workflows, or hooks.
+
+### 3.5.2 Layer Violation Check
+- [x] No new commands calling core directly
+- [x] No new upward dependencies
+- [x] All changes stay within Layer 4 (Core Library) and dispatcher
+
+### 3.5.3 Breaking Change Assessment
+| Question | Answer |
+|----------|--------|
+| Changes any existing command's output schema? | **No** |
+| Changes file formats? | **No** |
+| Changes directory structure? | **No** |
+| Changes installer output? | **No** |
+
+**Zero breaking changes. All internal refactoring.**
+
+---
+
+## Phase 4: Design Synthesis
+
+### 4.1 Guide-Level Explanation
+
+This is an internal cleanup with no user-facing changes. After completion:
+- The same 41 commands work identically
+- The same 93 CLI subcommands produce identical output
+- The same 1,180 tests pass
+- The codebase is cleaner, more consistent, and easier to maintain
+
+### 4.2 Feature Ladder
+
+| Version | Scope | Value | Effort |
+|---------|-------|-------|--------|
+| **v0 (Wave 1)** | Dead code removal + unused imports | Cleaner codebase, smaller surface area | XS (5 pts) |
+| **v1 (Wave 2)** | Duplicate consolidation + magic numbers to constants | Single source of truth | S (10 pts) |
+| **v2 (Wave 3)** | Complexity reduction (extract helpers from 12 functions) | All functions under 50 lines | M (20 pts) |
+| **v3 (Wave 4)** | Dispatcher hardening + pattern consistency | Robust arg validation | S (10 pts) |
+
+---
+
+## Phase 5: Architecture Decision Record
+
+See `docs/decisions/ADR-0014-internal-cleanup-code-quality.md`
+
+---
+
+## Phase 6: Error Handling Design
+
+### 6.1 Dispatcher Argument Validation
+
+All 11 unvalidated `args[N]` accesses will be protected:
+
+**Pattern (before):**
+```js
+case 'find-phase': {
+  phase.cmdFindPhase(cwd, args[1], raw);
+  break;
+}
+```
+
+**Pattern (after):**
+```js
+case 'find-phase': {
+  if (!args[1]) { error('find-phase requires a phase number'); }
+  phase.cmdFindPhase(cwd, args[1], raw);
+  break;
+}
+```
+
+### 6.2 `getArgValue()` Helper
+
+```js
+function getArgValue(args, flag, defaultVal = null) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return defaultVal;
+  return args[idx + 1];
+}
+```
+
+Eliminates 44 inline `indexOf` + `args[idx+1]` patterns.
+
+---
+
+## Phase 7: Security Review
+
+### 7.1 Findings
+- No command injection vulnerabilities (all shell calls use `execFileSync` with array args)
+- No path traversal vulnerabilities (all paths resolved within project root)
+- No sensitive data exposure (output goes through `toPosix()` and never includes absolute paths)
+- The duplicate `execFileSync` import in core.cjs is benign (performance only)
+
+### 7.2 Assessment
+**No security issues found.** The codebase's security posture is strong. The cleanup items are all maintainability concerns, not security risks.
+
+---
+
+## Phase 8: Implementation Roadmap
+
+### Wave 1: Dead Code Removal (XS — 5 pts, MICRO tier)
+
+#### Task 1.1: Remove duplicate `execFileSync` import in core.cjs
+- **File:** `pan-wizard-core/bin/lib/core.cjs`
+- **Action:** Remove line 216 `const { execFileSync } = require('child_process');` inside `execGit()` — already imported at line 7
+- **Priority:** P2
+- **Effort:** XS (1 pt)
+
+#### Task 1.2: Remove duplicate `core.cjs` require in dispatcher
+- **File:** `pan-wizard-core/bin/pan-tools.cjs`
+- **Action:** Remove line 662 re-require of core.cjs; use top-level import (add `output` to line 168 destructuring)
+- **Priority:** P3
+- **Effort:** XS (1 pt)
+
+#### Task 1.3: Remove unused `isSummaryFile` import from milestone.cjs
+- **File:** `pan-wizard-core/bin/lib/milestone.cjs`
+- **Action:** Remove `isSummaryFile` from line 7 destructuring (verify it's truly unused in module first)
+- **Priority:** P5
+- **Effort:** XS (1 pt)
+
+#### Task 1.4: Clean up unused function parameters
+- **File:** `pan-wizard-core/bin/lib/phase.cjs`
+- **Action:** Remove or document `phaseName` (line 887) and `totalPhases` (line 990) — if tests pass without them, remove; if callers pass them, keep but prefix with `_`
+- **Priority:** P4
+- **Effort:** XS (1 pt)
+
+#### Task 1.5: Remove `classifyItemPriority` from focus.cjs module internals
+- **File:** `pan-wizard-core/bin/lib/focus.cjs`
+- **Action:** Keep export (used by tests), but verify no internal callers — if none, note in comment as test-only export
+- **Priority:** P5
+- **Effort:** XS (1 pt)
+
+---
+
+### Wave 2: Duplication Consolidation + Constants (S — 10 pts, STANDARD tier)
+
+#### Task 2.1: Consolidate getArchivedPhaseDirs / listArchivedPhaseDirs
+- **Files:** `core.cjs`, `utils.cjs`, `commands.cjs`, `phase.cjs`
+- **Action:** Keep `getArchivedPhaseDirs()` in core.cjs (it's the canonical location). Remove `listArchivedPhaseDirs()` from utils.cjs. Update any callers of `listArchivedPhaseDirs` to use `getArchivedPhaseDirs`.
+- **Priority:** P2
+- **Effort:** S (2 pts)
+
+#### Task 2.2: Extract standards section parsing helper
+- **File:** `pan-wizard-core/bin/lib/config.cjs`
+- **Action:** Extract duplicated checkbox parsing (lines 372-383 and 528-534) into `parseStandardsChecklist(content, standardName)` helper
+- **Priority:** P3
+- **Effort:** S (2 pts)
+
+#### Task 2.3: Extract magic numbers to constants.cjs
+- **Files:** `constants.cjs`, `focus.cjs`, `template.cjs`, `context-budget.cjs`, `commands.cjs`, `verify.cjs`
+- **Action:** Extract:
+  - `BUDGET_LIMIT_BUGFIX = 40`, `BUDGET_LIMIT_FULL = 60`
+  - `STABILITY_RATIO = 0.6`, `FEATURE_RATIO = 0.8`
+  - `SIMPLE_TASK_THRESHOLD = 2`, `SIMPLE_FILE_THRESHOLD = 3`, `COMPLEX_TASK_THRESHOLD = 5`, `COMPLEX_FILE_THRESHOLD = 6`
+  - `CHARS_PER_TOKEN = 4`
+  - `HEALTH_STATUS = { HEALTHY: 'healthy', DEGRADED: 'degraded', BROKEN: 'broken' }`
+- **Priority:** P4
+- **Effort:** M (4 pts)
+
+#### Task 2.4: Extract `getArgValue()` helper for dispatcher
+- **File:** `pan-wizard-core/bin/pan-tools.cjs`
+- **Action:** Add `getArgValue(args, flag, defaultVal)` helper at top of file. Replace the most-repeated patterns (start with state/commit/init blocks — ~20 occurrences)
+- **Priority:** P3
+- **Effort:** S (2 pts)
+
+---
+
+### Wave 3: Complexity Reduction (M — 20 pts, STANDARD tier)
+
+#### Task 3.1: Split `cmdCommit()` (127 LOC)
+- **File:** `commands.cjs`
+- **Action:** Extract `validateCommitSafety(stagedFiles, config)` and `buildCommitMessage(msg, type, phaseMeta)` helpers. Target: main function under 50 lines.
+- **Priority:** P2
+- **Effort:** M (4 pts)
+
+#### Task 3.2: Split `allocateBudget()` (99 LOC)
+- **File:** `focus.cjs`
+- **Action:** Extract mode-specific allocation into `allocateForMode(items, mode, budget)` with per-mode functions. Extract batch dedup to `Set`-based tracking.
+- **Priority:** P2
+- **Effort:** M (4 pts)
+
+#### Task 3.3: Split `cmdConfigEnsureSection()` (86 LOC)
+- **File:** `config.cjs`
+- **Action:** Extract `createDefaultConfig(configPath)` and `mergeConfigDefaults(config)` helpers.
+- **Priority:** P3
+- **Effort:** S (2 pts)
+
+#### Task 3.4: Split `cmdStandardsPhaseTrack()` (93 LOC)
+- **File:** `config.cjs`
+- **Action:** Extract `scanPlanForStandards(planContent, standards)` helper.
+- **Priority:** P3
+- **Effort:** S (2 pts)
+
+#### Task 3.5: Split `cmdVerifySummary()` (95 LOC)
+- **File:** `verify.cjs`
+- **Action:** Extract `verifySummaryFrontmatter(fm)`, `verifySummaryContent(content)`, `verifySummaryCommits(content, cwd)` helpers.
+- **Priority:** P3
+- **Effort:** M (4 pts)
+
+#### Task 3.6: Split `renumberIntegerPhases()` (66 LOC)
+- **File:** `phase.cjs`
+- **Action:** Extract sort comparator and rename loop into helpers.
+- **Priority:** P3
+- **Effort:** S (2 pts)
+
+#### Task 3.7: Split remaining oversized functions
+- **Files:** `verify.cjs` (checkPhaseContents, cmdValidateHealth), `frontmatter.cjs` (parseMustHavesBlock), `core.cjs` (loadConfig)
+- **Action:** Extract inner loops and validation logic into focused helpers.
+- **Priority:** P4
+- **Effort:** S (2 pts)
+
+---
+
+### Wave 4: Dispatcher Hardening (S — 10 pts, STANDARD tier)
+
+#### Task 4.1: Add argument validation to 11 dispatcher cases
+- **File:** `pan-wizard-core/bin/pan-tools.cjs`
+- **Action:** Add `if (!args[N]) { error('command requires <arg>'); }` before each unvalidated `args[N]` access at lines 225, 303, 330, 332, 355, 437, 455, 467, 478, 497, 621.
+- **Priority:** P1
+- **Effort:** S (2 pts)
+
+#### Task 4.2: Standardize flag parsing with getArgValue
+- **File:** `pan-wizard-core/bin/pan-tools.cjs`
+- **Action:** Replace remaining `indexOf`+`args[idx+1]` patterns (beyond Task 2.4) with `getArgValue()`.
+- **Priority:** P4
+- **Effort:** S (2 pts)
+
+#### Task 4.3: Add new tests for dispatcher argument validation
+- **File:** `tests/commands.test.cjs` (or new `tests/dispatcher.test.cjs`)
+- **Action:** Test each of the 11 cases with missing required args — should return `{error: ...}` not crash.
+- **Priority:** P2
+- **Effort:** M (4 pts)
+
+#### Task 4.4: Validate getArgValue bounds in existing flag patterns
+- **File:** `pan-wizard-core/bin/pan-tools.cjs`
+- **Action:** Ensure `getArgValue` returns null when flag is last arg (no value follows). Add test for this.
+- **Priority:** P2
+- **Effort:** S (2 pts)
+
+---
+
+### Dependency Graph
+
+```
+Wave 1 (dead code) → Wave 2 (duplication + constants) → Wave 3 (complexity) → Wave 4 (dispatcher)
+   Task 1.1-1.5         Task 2.1-2.4                     Task 3.1-3.7           Task 4.1-4.4
+   (independent)        (2.3 after 1.*)                  (after 2.*)            (4.1 after 2.4)
+```
+
+### Risk Register
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| Refactored function changes behavior | Low | High | Run full test suite after every extraction |
+| Extracted helper has wrong signature | Low | Medium | Write test for helper before extracting |
+| Removed "dead" code is actually used | Low | High | Grep entire codebase before removing |
+| Constants rename breaks existing test expectations | Low | Medium | Use find-and-replace, run tests |
+
+---
+
+## Phase 9: Test Plan
+
+### 9.1 Test Strategy
+Each wave runs the full test suite (1,180 tests) after completion. No test should change expectations — all changes are behavioral no-ops.
+
+### 9.2 New Tests Required
+
+| Wave | New Tests | What They Cover |
+|------|-----------|-----------------|
+| Wave 1 | 0 | Dead code removal — existing tests cover behavior |
+| Wave 2 | 3-5 | `getArgValue()` helper, consolidated `getArchivedPhaseDirs`, `parseStandardsChecklist` |
+| Wave 3 | 5-10 | Each extracted helper function (validateCommitSafety, allocateForMode, etc.) |
+| Wave 4 | 11+ | Missing-arg error paths for each dispatcher case |
+
+### 9.3 Regression Verification
+- [ ] Full suite passes unchanged after each wave
+- [ ] No existing test expectations changed
+- [ ] Test count only increases (new tests for new helpers)
+- [ ] Build hooks compile without error
+
+### 9.4 Assertion Density
+Every new test asserts:
+- Correct return value shape (JSON with expected keys)
+- Correct values for 2+ fields
+- No `error` field on success paths
+- Actionable `error` message on failure paths
+
+---
+
+## Phase 10: Summary
+
+### Problem & Evidence
+PAN Wizard's 15 core modules have accumulated ~170 code quality issues across 23 development sessions. 12 functions exceed the 50-line complexity budget, 3 functions are duplicated across modules, and the dispatcher has 11 unvalidated argument accesses.
+
+### Strategic Assessment
+- **Blue Ocean:** ELIMINATE dead code, REDUCE complexity, RAISE consistency, CREATE shared helpers
+- **Moat Score:** Maintainability +4, Cross-Platform +1, Verification +1
+- **Cognitive Load:** Simplifies (-1) — no new user-facing concepts
+- **Recommendation:** Build. Zero user-facing risk, significant maintenance improvement.
+
+### Implementation Summary
+- **4 waves**, ordered by risk (lowest first)
+- **Wave 1:** Dead code removal (5 tasks, 5 pts, MICRO)
+- **Wave 2:** Duplication + constants (4 tasks, 10 pts, STANDARD)
+- **Wave 3:** Complexity reduction (7 tasks, 20 pts, STANDARD)
+- **Wave 4:** Dispatcher hardening (4 tasks, 10 pts, STANDARD)
+- **Total:** 20 tasks, 45 points, ~19-30 new tests
+- **Zero breaking changes**
+
+### Next Steps
+1. Run `/pan:focus-plan` with this spec as source
+2. Execute wave-by-wave with `/pan:focus-exec`
+3. Run full test suite after each wave
+4. Commit per wave with descriptive messages

package/docs/specs/investigations/README.md

@@ -0,0 +1,31 @@
+# Investigations
+
+Output of the `/investigate` dev command (`.claude/commands/investigate.md`): material the maintainer brings — a news
+dump, an article, a paper, a host tool's release notes — triaged against what PAN Wizard already does, with a
+write-up for every ADD or ENHANCE verdict. Nothing here ships; it is the inbox that feeds
+[the ideas ledger](../market-ideas-ledger.md) once the owner files an item.
+
+- `digests/` — one per run: the full triage, what PAN already has, what to watch, hand-offs to `/reality-check`.
+- `features/` — one per proposed feature; later runs append to the source trail instead of creating duplicates.
+- `sources/` — the raw input of each run, **gitignored**: this repository is public, so third-party text stays local
+  and only the write-ups (in our own words) are tracked.
+
+Statuses: PROPOSED → FILED `MI-nnn` (entered in the ledger) or REJECTED (with the reason).
+
+## Digests
+
+| Date | Source | Result |
+|---|---|---|
+| [`2026-10-10`](digests/2026-10-10.md) | `mattpocock/skills` repository at `49dd158` | ENHANCE 2 · HAVE 7 · WATCH 1 · SKIP 4 |
+| [`2026-10-08`](digests/2026-10-08.md) | VentureBeat AI Weekly newsletter (pasted), incl. multi-harness RL, SIFT, WikiSkill, Agent Memory Repo, Context Language Models | ENHANCE 1 · HAVE 3 · WATCH 3 · SKIP 7 |
+| [`2026-09-28`](digests/2026-09-28.md) | LLM brief (GrokBot llm-watch), incl. Growing Harness and PaMER papers | ENHANCE 2 · HAVE 2 · WATCH 1 · SKIP 7 |
+
+## Feature write-ups
+
+| Feature | Verdict | Priority | Status | Last updated |
+|---|---|---|---|---|
+| [Debugger: a failing command before any hypothesis](features/debugger-red-loop-first.md) | ENHANCE | P2 | FILED `MI-105`, built | `2026-10-10` |
+| [Reviewer: a fixed code-smell baseline](features/reviewer-smell-baseline.md) | ENHANCE | P3 | FILED `MI-106`, built | `2026-10-10` |
+| [Behavioural harness runs on every host CLI](features/harness-cross-host-behaviour.md) | ENHANCE | P2 | FILED `MI-104`, plumbing built | `2026-10-10` |
+| [Failure capture in the trace hook](features/trace-failure-capture.md) | ENHANCE | P2 | FILED `MI-060` (built, ADR-0049) | `2026-09-28` |
+| [Regression gate and rollback for `optimize apply`](features/optimize-apply-regression-gate.md) | ENHANCE | P3 | FILED `MI-061` (revert built; verdict deferred) | `2026-09-28` |

package/docs/specs/investigations/digests/2026-09-28.md

@@ -0,0 +1,47 @@
+# Investigation — 2026-09-28
+
+Source: "LLM brief — Mon 28 Sep" (GrokBot llm-watch, AI-generated digest, 7 items) · local copy `sources/2026-09-28.md` (gitignored) · ADD 0 · ENHANCE 2 · HAVE 2 · WATCH 1 · SKIP 7
+
+## Recommendations
+1. **Failure capture in the trace hook**: ENHANCE, P2, M. The optimise loop's failure signal depends on agents calling `optimize trace log`; they never do, so derive error events from the subagent transcript in the hook. → [write-up](../features/trace-failure-capture.md)
+2. **Regression gate and rollback for `optimize apply`**: ENHANCE, P3, M. Record applies so they can be reverted, and give an advisory success-first before/after verdict. Its verdict half needs recommendation 1. → [write-up](../features/optimize-apply-regression-gate.md)
+
+The brief is mostly open-weight model releases, which PAN does not consume. Its value for PAN is the Growing Harness paper, read through the question of where PAN still leaves routine control to the model.
+
+## Triage
+
+| # | Item | Area | Relevance | Verdict | Ledger |
+|---|---|---|---|---|---|
+| 1 | Holo4 open-weight computer-use agents, cost per task vs a frontier model | other (models) | LOW | SKIP: not a model any of PAN's five runtimes defaults to; no rate row without a provider pricing page | MI-023 |
+| 2 | Naive-N0.5-Flash 309B MoE, 1M context, API announced not live | cost/models | LOW | SKIP: no live API, no pricing page | MI-023 |
+| 3 | JEV-27B System-1 decision head sharing one vLLM engine | other (models) | LOW | SKIP: self-hosted serving technique, outside PAN's layer | — |
+| 4 | Julia-1 CPU/ONNX decision encoder for local routing | cost/models | LOW | SKIP: an ONNX model breaks the zero-runtime-dependency rule; PAN routes deterministically (`resolveComplexityTier`) and escalates by outcome | MI-029 |
+| 5a | Growing Harness: optimiser rewrites the agent program from failures | learnings/optimize | MED | SKIP for shipped PAN: no pass/fail oracle for user work, one task family per program, and rewriting installed code in user projects conflicts with keeping planning gates deterministic (ADR-0029's scope fence, Proposed) | — |
+| 5b | Growing Harness principle: recurring control belongs in code, not context | orchestration | MED | HAVE | MI-002 |
+| 5c | Growing Harness: failures recorded by the runtime and localised | learnings/optimize · hooks | HIGH | ENHANCE → rec. 1 | — |
+| 5d | Growing Harness: success-first held-out gate with rollback | learnings/optimize | MED | ENHANCE → rec. 2 | — |
+| 5e | Growing Harness applied to PAN development: harness scenarios as the gate for workflow edits | harness/evals | MED | WATCH | MI-019 |
+| 6a | PaMER: memory-control signals read from pre-action hidden states | context management | LOW | SKIP: needs model hidden states; PAN's runtimes are hosted models and the hosts own compaction | — |
+| 6b | PaMER: compact recent context plus selectively restored evidence | context management | MED | HAVE | MI-036 |
+| 7 | llama.cpp b11205 CUDA SSM scan | other (tooling) | NONE | SKIP: local inference runtime, outside PAN's layer | — |
+
+## HAVE — already covered
+- **5b, control in code**: the MCP `next-action` state machine is a pure function of a state snapshot (`pan-wizard-core/mcp/orchestrator.cjs:121`, SOURCE); native workflow scripts run fan-out control flow as code on Claude Code (MI-002, `3.28.0`); `pan-tools` verbs do the parsing, counting and state updates the workflows would otherwise ask the model for. The paper's small-model result (success held on WebArena-Verified as the model shrank, while the tool-calling baseline collapsed) is outside evidence for keeping workflow prose thin.
+- **6b, recent context plus restored evidence**: `hooks/pan-state-reinject.js` injects the active phase, last step and next action from `.planning/` on the post-compaction `SessionStart` (Claude, Codex) (MI-036, `3.31.0`, SOURCE). PAN restores durable state from disk rather than predicting what to keep, which the paper's second finding supports.
+
+## WATCH
+- **5e, harness as a held-out gate for PAN's own workflow edits.** Keep a fixed scenario set that workflow changes are not tuned against, and refuse a change that lowers its pass rate. Trigger: model-tier scenarios cheap enough to run at `--repeat 3` or more on every workflow change, or a second workflow regression that tier 0 missed. MI-019 (do not soften the harness) stands either way.
+
+## Hand-offs to /reality-check
+None: no item changes a path, config key, event name or file format PAN writes.
+
+## How far to trust the material
+- The brief is an AI-generated secondary digest. Every figure in it is a lead.
+- **Growing Harness** (arXiv:2609.26760 v2, `2026-09-24`): read in full on `2026-09-28` (primary). Evaluation sets are 50 tasks with 95% interval half-widths around ±11–13 points, so several head-to-head wins overlap. The ablations are single runs. Cost figures exclude the offline optimiser. Benchmarks are homogeneous task families, unlike PAN's work.
+- **PaMER** (arXiv:2609.27286 v1, `2026-09-23`): abstract read (primary). It confirms hidden-state signals and the recent-plus-retrieved design on WorkBuddyBench across several backbones. The brief's specific figures (AUROC values, "Recent2 ~26% tokens", "~73% token cut" on a named model) are **not in the abstract** and were not verified.
+- Items 1–4 and 7: not fetched; each is SKIP on PAN-side grounds that hold whatever the release details are.
+
+## Notes
+- No instruction-like text in the material.
+- The brief's "Watch next" list (drafter models, runtime source release, third-party leaderboard runs) concerns model releases outside PAN's layer; not triaged.
+- Recommendation 1 rests partly on the September field telemetry (zero error events recorded across the D-drive projects), which is in project memory and was not re-measured today. Re-measure before building: count `"type":"error"` lines across the field projects' `.planning/optimization/traces/`.

package/docs/specs/investigations/digests/2026-10-08.md

@@ -0,0 +1,62 @@
+# Investigation — 2026-10-08
+
+Source: VentureBeat "AI Weekly" newsletter (pasted, 11 items) · local copy `sources/2026-10-08.md` (gitignored) · ADD 0 · ENHANCE 1 · HAVE 3 · WATCH 3 · SKIP 7
+
+## Recommendations
+1. **Behavioural harness runs on every host CLI**: ENHANCE, P2, L (M for the first host). PAN measures its workflows' behaviour through Claude Code only. Hugging Face's multi-harness study found the same weights scoring 33–62% depending on the host. Give harness model steps a `runtime` and run the portable chain on Codex, Copilot, Gemini and OpenCode, whose CLIs are all on this machine. → [write-up](../features/harness-cross-host-behaviour.md)
+
+The newsletter's memory and self-improvement stories land on decisions PAN has already made and measured:
+- **Retired memory injection.** MI-095 retired lesson injection after 16 harness reps showed no effect.
+- **Declined host memory.** MI-010 declined host memory until a cross-runtime format is adopted by a runtime PAN targets.
+- **Human-gated optimiser.** The optimiser loop is human-gated with very few candidates (MI-061).
+
+None of the new material overturns those reasons.
+
+## Triage
+
+| # | Item | Area | Relevance | Verdict | Ledger |
+|---|---|---|---|---|---|
+| 1 | EmbeddingGemma 2, a 740M multimodal embedding model | other (models) | LOW | SKIP: embeddings mean a vector store and a model dependency; ADR-0036 D4 and MI-101 (files plus grep held up) | MI-101 |
+| 2 | Mistral Large 4, 1.05T MoE, open weights due end of October | cost/models | LOW | SKIP: not a default of any of PAN's five runtimes; no rate row without that (MI-023 rule) | MI-023 |
+| 3 | Amazon Strands Decider 2B, a scoring model for yes/no and choice decisions | cost/models | LOW | SKIP: a local model breaks the zero-runtime-dependency rule; PAN routes deterministically (`resolveComplexityTier`) and escalates on outcome; same reasoning as Julia-1 in the `2026-09-28` digest | MI-029 |
+| 4 | Cohere North 2: agent budgets, rate limits, cross-session memory | peer/competitor | LOW | HAVE (budgets, memory); rate limits do not apply, since PAN makes no model calls of its own | MI-010 |
+| 5 | SIFT: a code-only pairwise judge ranks candidate agents before costly evals | learnings/optimize · harness | MED | WATCH | MI-061 |
+| 6 | Sponsored message (Ernst & Young) | other | NONE | SKIP: advertisement | — |
+| 7 | WikiSkill: traces compiled into a wiki, then into validated skills | learnings/optimize | MED | WATCH | MI-095 |
+| 8a | Hugging Face: the host harness changes measured capability of the same weights | harness/evals | HIGH | ENHANCE → rec. 1 | — |
+| 8b | Hugging Face: RL training through unmodified harnesses via a capture proxy | other | LOW | SKIP: PAN trains no models | — |
+| 9a | Cognition's Agent Memory Repo, an open memory format | peer/competitor · planning state | MED | WATCH: MI-010's trigger not fired | MI-010 |
+| 9b | Cognition's Dreaming: a daily unattended pass that merges, drops and adds memory | learnings/optimize | MED | SKIP: an automatic writer with no approval step; the owner stopped PAN's automatic writers (MI-095, `2026-10-04`) and ADR-0040 treats unattended writes as a poisoning path | MI-095 |
+| 10 | VB Pulse: 2% chose an agent platform for its model | docs/positioning | LOW | HAVE (positioning) | — |
+| 11a | Context Language Models: the model edits a file mirrored into its own live context | orchestration | MED | SKIP: the hosts own the context window; PAN cannot sync an edited transcript into the next call (as with PaMER, `2026-09-28` 6a) | — |
+| 11b | The same paper's principle: let the model manage its own context through a file | orchestration | MED | HAVE | MI-036, MI-097 |
+
+## HAVE — already covered
+- **4, budgets and memory.** Scheduled campaigns carry `daily_budget` with an `enforce_budget` switch that stops a run for the day (`pan-wizard-core/bin/lib/campaign.cjs:81-118`, SOURCE). Every harness model step is refused without `--max-usd` (ADR-0047 D2). PAN's memory is the cited, expiring entries of MI-093 (`memory.cjs:156-179`, SOURCE). Cohere's per-user and per-group rate tiers have no PAN counterpart because the host makes the calls.
+- **10, positioning.** The survey is n=166, self-selected, with no margin of error, so it is secondary by nature. Its top reasons are flexibility across models and tools (22%), production reliability (20%), ease of development (19%) and control over execution (18%). That matches PAN's position as a runtime-neutral layer with deterministic gates, and the August read that the market converged on PAN's thesis. Use it as colour, not as a claim.
+- **11b, model-managed context through a file.**
+  - Before the host compacts, the context monitor asks the model to checkpoint its position into `state.md` (`hooks/pan-context-monitor.js:32-40`, `:411-418`, SOURCE).
+  - After compaction, the position is re-injected (`hooks/pan-state-reinject.js`, MI-036).
+  - PAN's CLAUDE.md block steers the host's summary with compact instructions (`pan-wizard-core/bin/lib/agents-md.cjs:101`, MI-097).
+
+  The paper's own failure mode supports the line PAN drew: an editable context lets a model plant instructions for itself, which is why PAN keeps the checkpoint to position fields.
+
+## WATCH
+- **5, SIFT.** A judge pays off when there are many candidates to rank. PAN's optimiser applies are rare (one apply run in 14 field projects, MI-061), and a harness A/B compares one or two variants. ADR-0029's scope fence keeps model judges out of lifecycle gates anyway. Trigger: MI-061's (`optimize stats` shows apply runs in three or more projects), or PAN generating several candidate variants per decision. If it fires, note the paper's finding that full files ranked better than diffs as judge input (Spearman 0.68 vs 0.40 over 50 nodes).
+- **7, WikiSkill.** The gains are on math, QA, spreadsheet, office and ALFWorld tasks with small and mid-size models, with skills injected whole into the system prompt. PAN measured lessons on its own coding chain and found no effect (MI-095). It also declined skill preload into agents (ADR-0046 D4). The paper also reports that skills compiled for one model can hurt another (Qwen-4B skills cut Gemini's spreadsheet score from 50.5 to 18.1). That is a caution for anything PAN ships to every model. Trigger: MI-095's (a long-horizon harness run showing an effect), or a harness A/B where a compiled skill changes a fast-tier agent's outcome.
+- **9a, Agent Memory Repo.** Published by Cognition on `2026-10-04`: MIT licence, no version or releases, no named adopter. It installs into other tools as a skill, not as host-native support. MI-010's trigger needs adoption by a runtime PAN targets, so it has not fired; the decline holds. The format is close to PAN's own: a `MEMORY.md` index, files read on demand, and bullet entries with `source` and `added` metadata. It has no expiry, which MI-093's entries do.
+
+## Hand-offs to /reality-check
+None. No item changes a path, config key, event name or file format PAN writes.
+
+## How far to trust the material
+- **The newsletter itself** is secondary. Every item above was checked against its primary source except EmbeddingGemma 2 (search snippets only) and the survey (VentureBeat is its own source). One headline is wrong: Mistral Large 4 has 52B active parameters per Mistral's docs, not 49B. The October 27 weights date appears only in secondary coverage.
+- **Hugging Face multi-harness RL** used one seed per run, no error bars and a single attempt per test cell (250 tasks × 4 harnesses). The authors call the gap between their two RL runs noise. The 29-point spread between harnesses is large next to that, but it comes from one 2.6B model on data-analysis tasks. A frontier model's spread may be smaller, which is why the recommendation is to measure rather than assume.
+- **SIFT** reports one main run plus 3 repeats for its headline, with no confidence intervals. Its strongest judge is stronger than the agent being improved, and two of its cost figures disagree with each other.
+- **WikiSkill** averages 3 runs per result with a paired bootstrap. Its test sets are small (85–280 items) and its validation sets smaller still.
+- **Context Language Models** report no error bars on the main results. Several gains are within plausible run-to-run noise, the FLOPs are theoretical, and the headline 11.4% is relative (about 6 points absolute).
+- **Cognition**: no announcement post was found. The facts come from the spec page, the repository and the Devin docs.
+
+## Notes
+- The material contains no text addressed to the agent. The sponsored message was triaged as an item and nothing more.
+- Version-pinned model names appear above only because this file lives under `docs/specs/`.