pan-wizard 3.35.0 → 3.37.0

package/docs/specs/focus_design_v2_featureai.md

@@ -0,0 +1,197 @@
+# Feature Spec: focus-design v2 — Autonomous Investigation & Best-in-Industry Enhancement
+
+**Generated by:** /pan:focus-design --full
+**Date:** 2026-03-04
+**ADR:** ADR-0017
+**Status:** Proposed
+
+---
+
+## Problem & Evidence
+
+PAN's `/pan:focus-design` is already the most comprehensive AI feature specification workflow in the ecosystem — no competitor combines strategic analysis (Blue Ocean, Wardley, Moat), security threat modeling, ADR generation, test planning, AND multi-mode scaling. However, competitive analysis reveals three critical gaps that prevent it from being best-in-industry:
+
+1. **No autonomous codebase investigation** before spec creation (Cline's `/deep-planning` leads here with silent grep/read before asking)
+2. **No impact analysis** showing what existing modules are affected (nobody does this — opportunity to lead)
+3. **Clarification questions are generic templates**, not grounded in discovered code patterns (Cline's informed questions are the benchmark)
+
+Additionally, the older `/featureAI` command (730 lines) contains stale hardcoded counts and should be deprecated.
+
+### Demand Evidence
+
+| Evidence Type | Source | Finding |
+|--------------|--------|---------|
+| User-stated | This conversation | "Full review of the focus-design.md agent, what to make sure it is the best one in the industry" |
+| Competitor parity | Cline `/deep-planning` | Autonomous silent codebase investigation — called "game changer" in community |
+| Competitor parity | Amazon Kiro | Requirements → Design → Tasks three-phase spec workflow |
+| Competitor parity | Windsurf megaplan | Structured clarification before plan generation |
+| Community critique | Martin Fowler / Scott Logic | SDD tools create specs but don't ground them in code reality |
+
+---
+
+## Competitive Position
+
+### What PAN focus-design Already Leads In (No Other Tool Has ALL Of These)
+
+1. **Strategic Analysis Pipeline** — Blue Ocean + Wardley + Moat scoring
+2. **Security Threat Modeling** — STRIDE-lite + path safety + output sanitization
+3. **ADR Generation** — Formal architecture decision records
+4. **Test Pyramid Enforcement** — Unit >= 5, integration >= 5, E2E >= 2
+5. **4-Mode Scaling** — full/internal/outward/spike for different scope sizes
+6. **5-Runtime Support** — Claude Code, OpenCode, Gemini CLI, Codex, Copilot CLI
+7. **Zero Dependencies** — Pure markdown command file
+
+### What Competitors Lead In (Gaps to Close)
+
+| Gap | Leader | PAN v2 Response |
+|-----|--------|----------------|
+| Autonomous codebase investigation | Cline `/deep-planning` | New Phase 0.8 |
+| Informed clarification questions | Cline | New Phase 1.5 |
+| Before/After state specification | Copilot Workspace (defunct) | New Phase 0.2.5 |
+| Structured requirements elicitation | Windsurf megaplan, Kiro | Enhanced Phase 0.4 |
+| Living spec maintenance | Windsurf plan.md | Deferred to v2 (integrate with focus-sync) |
+
+### What Nobody Does Yet (PAN v2 Will Lead)
+
+1. **Impact Analysis** — Surface blast radius before any design work begins
+2. **Dynamic Competitor Selection** — Domain-aware competitor research, not hardcoded 6 tools
+3. **Investigation + Strategic Analysis + Security** — The full trilogy in a single pipeline
+
+---
+
+## Design: 10 Changes
+
+### Change 1: Phase 0.8 — Autonomous Codebase Investigation (NEW)
+
+Insert between Phase 0 and Phase 1. Three sub-phases:
+- **0.8.1 Silent Discovery**: Grep for imports, search for similar functionality, read 2-3 existing implementations, discover test patterns, identify integration points
+- **0.8.2 Impact Analysis**: Table of affected modules with risk levels
+- **0.8.3 Informed Context**: Use discoveries to ground all subsequent phases
+
+### Change 2: Phase 0.2.5 — Before/After State Specification
+
+For feature enhancements: explicitly document current behavior, desired behavior, and delta. Adopted from Copilot Workspace's topic→current→desired pattern.
+
+### Change 3: Phase 0.4 — Structured Acceptance Criteria
+
+Replace freeform success criteria with table format including verification method and pass condition. At least 2 criteria must be automatically verifiable.
+
+### Change 4: Remove All Hardcoded Counts
+
+Replace "31 commands", "604+ tests", "14 modules", "32 commands" with dynamic language ("all existing commands and agents", "existing tests").
+
+### Change 5: Scope Calibration Guidance
+
+Auto-mode-selection table: bug fix → spike, new command → internal, user-facing feature → full, strategic question → outward.
+
+### Change 6: Dynamic Competitor Selection (Phase 2.1)
+
+Replace hardcoded 6-tool table with domain-aware guidance. Default set of 8 AI coding tools + instruction to use domain-relevant tools for non-AI features.
+
+### Change 7: Phase 1.5 — Informed Clarification Questions (NEW)
+
+2-4 questions that MUST reference specific files, line numbers, or patterns discovered in Phase 0.8. Never generic. Only in --full mode.
+
+### Change 8: MCP/context7 Tools in Frontmatter
+
+Add `mcp__context7__resolve-library-id` and `mcp__context7__get-library-docs` to allowed-tools.
+
+### Change 9: Updated Convention Enforcement Checklist
+
+Replace generic checklist with PAN-specific function names: `readStateSafe()`, `output()`, `error()`, `toPosix()`, `fileAccessible()`, `getArgValue()`, `cmd<Module><Action>()` naming.
+
+### Change 10: Enhanced Phase 10 Report Summary
+
+Add investigation depth, competitive position, informed questions asked, and machine-checkable acceptance criteria count to the final report.
+
+---
+
+## Strategic Assessment
+
+### Blue Ocean Framework
+
+| Action | Decisions |
+|--------|-----------|
+| **ELIMINATE** | Hardcoded competitor lists, hardcoded counts, generic questions |
+| **REDUCE** | Template verbosity in spike mode, boilerplate in Phase 0 |
+| **RAISE** | Investigation depth, question quality, impact awareness |
+| **CREATE** | Impact analysis, informed clarification, scope calibration |
+
+### Wardley Position
+
+Currently at Product maturity (structured pipeline, modes, artifacts). Enhancement moves investigation capability from Genesis to Custom-Built level, matching Cline while maintaining PAN's unique Product-level strategic analysis.
+
+### Moat Score: 27/30
+
+| Moat | Score |
+|------|-------|
+| Context Engineering | 5/5 |
+| Cross-Platform | 5/5 |
+| Developer Experience | 4/5 |
+| Zero Dependencies | 5/5 |
+| State Persistence | 4/5 |
+| Verification Quality | 4/5 |
+
+### Cognitive Load: neutral (0)
+
+No new commands — enhancement to existing. Two new concepts (impact analysis, informed questions) are embedded in the workflow, not exposed as new user-facing abstractions.
+
+### Recommendation
+
+**Build.** focus-design is already the industry's most comprehensive spec workflow. Adding investigation depth closes the only gap competitors exploit while maintaining PAN's unique strategic analysis, security modeling, and multi-runtime advantages. Zero code changes needed.
+
+---
+
+## Feature Ladder
+
+| Version | Scope | Effort |
+|---------|-------|--------|
+| **v0 (MVP)** | Fix stale counts + Phase 0.8 investigation + impact analysis + informed questions + MCP tools | S |
+| **v1 (Complete)** | + Before/After state + structured AC + scope calibration + dynamic competitors + convention updates | M |
+| **v2 (Enhanced)** | + Spec-code drift detection (focus-sync integration) + spec evolution tracking | L |
+
+---
+
+## Implementation Tasks
+
+| Order | Task | Files | Estimate |
+|-------|------|-------|----------|
+| 1 | Add Phase 0.8 (Investigation + Impact Analysis) | commands/pan/focus-design.md | S |
+| 2 | Add Phase 1.5 (Informed Clarification) + Before/After State | commands/pan/focus-design.md | S |
+| 3 | Fix stale content (counts, conventions, competitors, tools) | commands/pan/focus-design.md | S |
+| 4 | Add scope calibration + structured AC + enhanced report | commands/pan/focus-design.md | S |
+| 5 | Propagate to all runtimes | 3 runtime-specific copies | XS |
+| 6 | Deprecate /featureAI | .claude/commands/featureAI.md | XS |
+
+Tasks 1-4 are independent. Task 5 depends on 1-4. Task 6 depends on 5.
+
+---
+
+## Security Assessment
+
+- **Attack surface:** Minimal — reads project files (trusted), writes to docs/ (controlled), web search results (untrusted, synthesized not embedded)
+- **Path safety:** Not needed — no user-supplied path arguments
+- **Output sanitization:** Specs use relative paths, no env vars, no stack traces
+- **Web content:** Competitive research via WebSearch — synthesize findings, don't embed raw HTML
+
+---
+
+## Adoption
+
+- **Discovery:** Existing command — no discovery needed
+- **Learning curve:** Zero — same invocation, better output
+- **Workflow change:** None — drop-in enhancement
+- **Aha moment:** First time focus-design references an actual code pattern in a clarification question
+
+---
+
+## Documents
+
+- Spec: `docs/specs/focus_design_v2_featureai.md` (this file)
+- ADR: `docs/decisions/ADR-0017-enhanced-focus-design.md`
+
+---
+
+## Next Step
+
+Implement Tasks 1-4 to update `commands/pan/focus-design.md`, then propagate to runtimes.

package/docs/specs/focus_sync_v2_featureai.md

@@ -0,0 +1,202 @@
+# Feature Specification: Enhanced Documentation Sync (focus-sync v2)
+
+**Mode:** `--internal` | **Date:** 2026-03-04 | **Status:** Proposed
+
+---
+
+## Problem Statement
+
+PAN Wizard has 14+ documentation files containing cross-referenced counts, command lists, feature descriptions, and version numbers that must stay synchronized. The current `focus sync` command only checks README.md for 3 entity count patterns (commands, agents, modules). An end-to-end audit revealed 20+ staleness issues across 8 files that focus-sync completely misses: stale test counts, old command names from the v1.0.0 rename, wrong runtime prefixes, missing command entries in tables, and placeholder URLs.
+
+## Demand Evidence
+
+| Evidence Type | Source | Finding |
+|---|---|---|
+| User-stated pain | This conversation | User explicitly requested end-to-end doc review |
+| Repeated manual work | Sessions 22-26 | Every session included manual doc sync |
+| Demonstrated miss | v2.3.0 focus-auto | 37->38 count stale in 3 files after adding a command |
+
+## Scope
+
+### In Scope
+- Enhance `checkDocStaleness()` to scan all doc files
+- Add old command name detection using v1.0.0 rename map
+- Add command table completeness checking
+- Add version cross-reference (package.json vs CHANGELOG)
+- Add COMMAND_RENAME_MAP to constants.cjs
+
+### Out of Scope
+- Auto-fix (stays in command .md orchestrator)
+- Content/style rewriting
+- New agents or hooks
+
+## Success Criteria
+
+```
+SC-1: focus sync detects count staleness in ALL doc files, not just README
+SC-2: focus sync detects old command names from v1.0.0 rename
+SC-3: focus sync reports commands missing from listing tables
+SC-4: focus sync verifies package.json version matches CHANGELOG
+SC-5: Zero regressions in existing test suite
+```
+
+## Current Implementation
+
+`checkDocStaleness()` in focus.cjs (lines 397-431):
+1. Counts actual commands, agents, modules from disk
+2. Reads only README.md
+3. Uses `checkCount()` regex: `(\d+)\s+{entity}`
+4. Returns `{ stale, current, actuals }`
+
+## Enhanced Implementation Design
+
+### New checks added to `checkDocStaleness()`:
+
+| Check | Description | Files Scanned |
+|-------|-------------|---------------|
+| Multi-file counts | Existing count regex applied to all docs | README, ARCHITECTURE, DEVELOPMENT, CONTRIBUTING, USER-GUIDE, CLI-REFERENCE |
+| Old name detection | Scan for COMMAND_RENAME_MAP keys | All docs/*.md |
+| Command table completeness | Parse tables with `/pan:` entries | README, USER-GUIDE |
+| Version consistency | Compare package.json vs CHANGELOG header | package.json, CHANGELOG.md |
+| Workflow count | Count workflow .md files, check against docs | ARCHITECTURE.md |
+| Test count | Match `N tests` patterns | DEVELOPMENT.md |
+
+### New constant: COMMAND_RENAME_MAP
+
+```js
+const COMMAND_RENAME_MAP = {
+  'execute-phase': 'exec-phase',
+  'verify-work': 'verify-phase',
+  'list-phase-assumptions': 'assumptions',
+  'add-tests': 'phase-tests',
+  'context-budget': 'phase-budget',
+  'pause-work': 'pause',
+  'resume-work': 'resume',
+  'set-profile': 'profile',
+  'new-milestone': 'milestone-new',
+  'complete-milestone': 'milestone-done',
+  'audit-milestone': 'milestone-audit',
+  'plan-milestone-gaps': 'milestone-gaps',
+  'cleanup': 'milestone-cleanup',
+  'add-todo': 'todo-add',
+  'check-todos': 'todo-check',
+  'join-discord': 'discord',
+  'reapply-patches': 'patches',
+};
+```
+
+### Enhanced output contract (additive):
+
+```json
+{
+  "actuals": {
+    "commands": 38,
+    "agents": 11,
+    "modules": 15,
+    "workflows": 30,
+    "version": "2.3.0"
+  },
+  "stale": [
+    { "file": "docs/DEVELOPMENT.md", "entity": "commands", "documented": 37, "actual": 38 }
+  ],
+  "current": [
+    { "file": "README.md", "entity": "commands", "count": 38 }
+  ],
+  "old_names": [
+    { "file": "docs/EXAMPLES.md", "old_name": "resume-work", "current_name": "resume" }
+  ],
+  "missing_commands": [
+    { "file": "docs/USER-GUIDE.md", "command": "focus-auto" }
+  ],
+  "version_match": true,
+  "stale_count": 5,
+  "old_name_count": 4,
+  "missing_count": 1,
+  "needs_sync": true,
+  "check_only": true
+}
+```
+
+## Document Gap Audit (2026-03-04)
+
+### Category A: Stale Counts
+
+| # | File | Entity | Documented | Actual |
+|---|------|--------|------------|--------|
+| A1 | DEVELOPMENT.md:13 | commands | 37 | 38 |
+| A2 | DEVELOPMENT.md:46 | tests | 1277 | 1314 |
+| A3 | DEVELOPMENT.md:57 | tests | 1277 | 1314 |
+| A4 | DEVELOPMENT.md:249 | tests (release) | 1180 | 1314 |
+| A5 | CONTRIBUTING.md:65 | commands | 37 | 38 |
+
+### Category B: Missing Entries
+
+| # | File | Missing |
+|---|------|---------|
+| B1 | DEVELOPMENT.md | focus-auto not mentioned |
+
+### Category C: Incorrect References
+
+| # | File | Issue | Fix |
+|---|------|-------|-----|
+| C1 | FAQ.md:13 | Copilot CLI prefix `/pan:*` | `/pan-*` |
+| C2 | FAQ.md:13 | Copilot CLI config `~/.github/` | `~/.copilot/` |
+| C3 | FAQ.md:67-77 | Missing --gemini and --copilot uninstall | Add entries |
+| C4 | HOOKS.md:153-160 | Copilot CLI missing from hook support table | Add row |
+| C5 | EXAMPLES.md:483-486 | Old command names in Quick Reference | Update 4 names |
+| C7 | FAQ.md:106 | `verify-work` (old name) | `verify-phase` |
+| C8 | TROUBLESHOOTING.md:839 | `your-org/pan-wizard` placeholder | `oharms/PanWizard` |
+| C9 | EXAMPLES.md:51 | discuss-phase output → "state.md" | "context.md" |
+| C10 | EXAMPLES.md:73 | Wrong plan path format | Correct to phases/XX-name/ format |
+
+### Category D: Structural Issues
+
+| # | File | Issue |
+|---|------|-------|
+| D1 | DEVELOPMENT.md:104 | Test example uses `it()` not `test()` |
+| D2 | COMPARISON.md:4 | "Last verified: February 2026" |
+| D3 | INTERNALS.md:206-214 | Model profile table inconsistent with AGENTS.md |
+
+## Implementation Tasks
+
+### Task 1: Fix all known doc gaps (P0 + P1)
+- Files: FAQ.md, EXAMPLES.md, TROUBLESHOOTING.md, DEVELOPMENT.md, CONTRIBUTING.md, HOOKS.md, INTERNALS.md, COMPARISON.md
+- Effort: S | Priority: P0
+
+### Task 2: Add COMMAND_RENAME_MAP to constants.cjs
+- Files: pan-wizard-core/bin/lib/constants.cjs
+- Effort: XS | Priority: P1
+
+### Task 3: Enhance checkDocStaleness() in focus.cjs
+- Files: pan-wizard-core/bin/lib/focus.cjs
+- Effort: S-M | Priority: P1
+- Depends on: Task 2
+
+### Task 4: Add tests for enhanced sync
+- Files: tests/focus.test.cjs
+- Effort: S | Priority: P1
+- Depends on: Task 3
+
+### Task 5: Update focus-sync.md command file
+- Files: .claude/commands/pan/focus-sync.md, commands/pan/focus-sync.md
+- Effort: XS | Priority: P2
+- Depends on: Task 3
+
+## Test Plan
+
+### Unit tests (8+)
+- checkOldNames: finds old names, ignores partial matches, handles multiple
+- checkCommandTableCompleteness: detects missing, handles full table
+- checkVersionConsistency: match, mismatch, missing files
+- Multi-file checkCount: stale in DEVELOPMENT, current in README
+
+### Integration tests (5+)
+- cmdFocusSync returns old_names field
+- cmdFocusSync returns missing_commands field
+- cmdFocusSync returns version_match field
+- Full output shape validation
+- Backward compatibility (existing stale/current fields unchanged)
+
+### E2E tests (2+)
+- Run focus sync on PAN Wizard's own codebase
+- Verify all check categories present in output