pan-wizard 2.8.1 → 2.9.0

package/README.md

@@ -47,7 +47,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 └─────────────────────┬───────────────────────────────────────┘
                       │ invokes
 ┌─────────────────────▼───────────────────────────────────────┐
-│  COMMANDS (40 .md files + 4 CLI operations)                 │
+│  COMMANDS (42 .md files + 4 CLI operations)                 │
 │  Thin orchestrators that spawn agents and route results     │
 └─────────────────────┬───────────────────────────────────────┘
                       │ spawns
@@ -149,7 +149,7 @@ node bin/install.js --claude --local
 Installs to `./.claude/` for testing modifications before contributing.
 
 ```bash
-npm test                # 1649 unit tests
+npm test                # 1736 unit tests
 npm run test:scenarios  # Scenario tests (install + integration)
 npm run test:all        # All tests (unit + scenario)
 ```
@@ -580,6 +580,8 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:focus-auto` | Continuous scan→plan→exec loop with purpose-driven categories and 5-layer safety harness |
 | `/pan:focus-sync` | Detect and report stale documentation counts |
 | `/pan:focus-design` | 10-phase strategic feature investigation pipeline |
+| `/pan:focus-drift-walking` | Walk project tree, detect doc-code drift, score severity, auto-repair |
+| `/pan:focus-doc-audit` | Multi-dimensional document audit with 8-dimension quality scoring |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
 

package/bin/install.js

@@ -1501,8 +1501,11 @@ function install(isGlobal, runtime = 'claude') {
       console.error(`  ${yellow}✗${reset} package.json write failed: ${e.message}`);
       failures.push('package.json');
     }
+  }
 
+  if (!isCodex && !isOpencode) {
     // Copy hooks from dist/ (bundled with dependencies)
+    // Hooks are only supported by Claude Code, Gemini, and Copilot CLI
     // Template paths for the target runtime (replaces '.claude' with correct config dir)
     try {
       const hooksSrc = path.join(src, 'hooks', 'dist');
@@ -1549,6 +1552,26 @@ function install(isGlobal, runtime = 'claude') {
   // Report any backed-up local patches
   reportLocalPatches(targetDir, runtime);
 
+  // Post-install self-check: verify critical files exist before declaring success
+  const selfCheckIssues = [];
+  const panToolsPath = path.join(targetDir, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+  if (!fs.existsSync(panToolsPath)) selfCheckIssues.push('pan-tools.cjs missing');
+  const manifestFullPath = path.join(targetDir, MANIFEST_NAME);
+  if (fs.existsSync(manifestFullPath)) {
+    try {
+      const mfst = JSON.parse(fs.readFileSync(manifestFullPath, 'utf8'));
+      const fileCount = Object.keys(mfst.files || {}).length;
+      if (fileCount < 50) selfCheckIssues.push(`manifest has only ${fileCount} files (expected 150+)`);
+    } catch { selfCheckIssues.push('manifest unreadable'); }
+  } else {
+    selfCheckIssues.push('manifest missing');
+  }
+  if (selfCheckIssues.length > 0) {
+    console.error(`\n  ${yellow}⚠ Post-install check found issues:${reset}`);
+    for (const issue of selfCheckIssues) console.error(`    - ${issue}`);
+    console.error(`  Run ${cyan}pan-tools validate deployment${reset} for full diagnostics.\n`);
+  }
+
   if (isCodex) {
     return { settingsPath: null, settings: null, statuslineCommand: null, runtime };
   }

package/commands/pan/focus-design.md

@@ -569,36 +569,255 @@ Every error condition must specify:
 
 ## Phase 5: Architecture Decision Record
 
-Create a formal ADR:
+> *An ADR is the institutional memory of WHY. Make it comprehensive enough that a developer joining 12 months from now can understand the full decision landscape without asking anyone.*
+
+### 5.0 ADR Numbering
+- Read existing ADRs in `docs/decisions/` to determine the next sequential number
+- Format: `ADR-NNNN-<kebab-case-feature-name>.md` (e.g., `ADR-0019-webhook-support.md`)
+
+### 5.1 ADR Structure (MANDATORY — all sections required)
+
+The ADR MUST contain ALL of the following sections. Do NOT produce a skeleton with placeholder text — every section must have substantive, project-specific content drawn from the preceding phases.
 
 ```markdown
-# ADR-NNNN: [Feature Name]
+# ADR-NNNN: [Descriptive Title — not just feature name but what was decided]
 
 ## Status
-Proposed
+Proposed | Accepted | Superseded by ADR-NNNN | Amended by ADR-NNNN
+
+## Date
+YYYY-MM-DD
 
 ## Context
-[Problem context — what forces are at play?]
+
+### Problem Statement
+[1-2 paragraphs: What problem exists? Why does it matter? What is the cost of inaction?
+Pull directly from Phase 0.1 — do not paraphrase into vague generalities.]
+
+### Forces & Constraints
+[Enumerate the specific technical, business, regulatory, and organizational forces
+that constrain the solution space. These come from Phase 0 + Phase 1 discoveries.]
+
+- **[Force 1]:** [Specific constraint and why it matters]
+- **[Force 2]:** [Specific constraint and why it matters]
+- **[Force 3]:** [Specific constraint and why it matters]
+
+### Current State
+[What exists today? Reference actual files, modules, endpoints discovered in Phase 0.8.
+If enhancing an existing feature, include the Before/After delta from Phase 0.2.5.]
+
+### Requirements Traceability
+[Map to the spec that triggered this ADR. List the success criteria from Phase 0.4.]
+
+| Requirement | Source | ADR Section |
+|-------------|--------|-------------|
+| [SC-1 from Phase 0.4] | [spec file or user request] | Decision §X |
+| [SC-2 from Phase 0.4] | [spec file or user request] | Decision §Y |
 
 ## Decision
-[What was decided and why]
+
+### Summary
+[1-2 sentences: The decision in plain language. A busy reader should understand
+the choice from this paragraph alone.]
+
+### Detailed Design Decisions
+[Number each sub-decision. For each, state WHAT was decided and WHY.
+Pull from Phase 4 design synthesis — every design choice documented there
+must appear here with rationale.]
+
+#### 1. [Sub-decision title]
+**Decided:** [What]
+**Rationale:** [Why — reference forces from Context, competitive findings from Phase 2,
+or architectural constraints from Phase 3.5]
+**Alternatives rejected:** [Brief — full analysis in Options Considered]
+
+#### 2. [Sub-decision title]
+**Decided:** [What]
+**Rationale:** [Why]
+**Alternatives rejected:** [Brief]
+
+[Continue for all significant decisions — typically 3-8 sub-decisions]
+
+### Architecture & Integration
+[How does this fit into the existing system? Include the dependency map from Phase 1.4
+and the layer violation check from Phase 3.5.2. Show which modules are touched.]
+
+```
+[Dependency diagram or integration flow from Phase 1.4 / 3.5.6]
+```
+
+### Interface Contract
+[The output schema or API contract from Phase 3.5.3 — exact format, not just description.
+Include request/response examples for APIs, CLI input/output for commands,
+or data schema for storage changes.]
 
 ## Consequences
+
 ### Positive
-- [Benefit 1]
+[Minimum 3 consequences. Each must be specific and measurable, not generic platitudes.
+BAD: "Better user experience" — GOOD: "Reduces statement processing failure rate
+from 80% to <5% for image-based uploads"]
+
+- **[Specific benefit 1]:** [Measurable impact]
+- **[Specific benefit 2]:** [Measurable impact]
+- **[Specific benefit 3]:** [Measurable impact]
+
 ### Negative
-- [Cost 1]
+[Minimum 2 consequences. Be honest about costs and tradeoffs.
+Every negative must include a mitigation strategy or explicit acceptance rationale.]
+
+- **[Specific cost 1]:** [Impact] — *Mitigation:* [how addressed or why accepted]
+- **[Specific cost 2]:** [Impact] — *Mitigation:* [how addressed or why accepted]
+
 ### Neutral
-- [Side effect]
+[Side effects that are neither clearly positive nor negative]
+
+- [Side effect 1]
+- [Side effect 2]
 
 ## Options Considered
-1. [Option A] — [summary]
-2. [Option B — chosen] — [summary]
 
-## Links
-- Related to: [commands, modules, issues]
+> *Document ALL options evaluated, including the chosen one. For each option,
+> provide enough detail that a reader can understand why it was accepted or rejected
+> WITHOUT reading the full spec.*
+
+### Option 1: [Name] — REJECTED
+**Description:** [2-3 sentences: what this approach involves]
+**Pros:** [Bullet list]
+**Cons:** [Bullet list]
+**Rejected because:** [Specific reason tied to forces/constraints in Context]
+
+### Option 2: [Name] — REJECTED
+**Description:** [2-3 sentences]
+**Pros:** [Bullet list]
+**Cons:** [Bullet list]
+**Rejected because:** [Specific reason]
+
+### Option 3: [Name] — CHOSEN
+**Description:** [2-3 sentences]
+**Pros:** [Bullet list]
+**Cons:** [Bullet list — same as Negative consequences]
+**Chosen because:** [Specific reason — ties back to forces, competitive position, strategic analysis]
+
+### Option 4: [Name] — DEFERRED
+**Description:** [2-3 sentences]
+**Deferred because:** [Not rejected — viable for future consideration. State trigger conditions.]
+
+[Include 3-5 options minimum. If fewer than 3 alternatives were genuinely considered,
+explain why the solution space was constrained.]
+
+### Decision Matrix (when 3+ options share comparable tradeoffs)
+| Criterion (from forces) | Weight | Option 1 | Option 2 | Option 3 (chosen) |
+|--------------------------|--------|----------|----------|-------------------|
+| [Force/requirement 1] | High | Poor | Good | Excellent |
+| [Force/requirement 2] | Medium | Good | Poor | Good |
+| [Force/requirement 3] | High | N/A | Good | Excellent |
+| **Weighted Score** | | Low | Medium | **High** |
+
+## Success Criteria
+
+[Copy directly from Phase 0.4 — these are the machine-checkable acceptance criteria
+that determine whether this ADR's decision was correctly implemented.]
+
+| ID | Criterion | Verification Method | Pass Condition |
+|----|-----------|-------------------|----------------|
+| SC-1 | [description] | test / grep / manual | [exact condition] |
+| SC-2 | [description] | test / grep / manual | [exact condition] |
+| SC-3 | No regression | project test command | All existing tests pass |
+
+## Breaking Changes
+
+[From Phase 3.5.5. If no breaking changes, state "None — all changes are additive."]
+
+| Change | Impact | Migration Strategy |
+|--------|--------|--------------------|
+| [What changes] | [Who is affected] | [How to migrate] |
+
+## Security Implications
+
+[From Phase 7. Summarize the threat model and key controls.]
+
+| Threat | Risk Level | Control |
+|--------|-----------|---------|
+| [Threat from STRIDE-lite] | Low/Medium/High | [Mitigation implemented] |
+
+If no security implications: "No new attack surface introduced. [Brief justification.]"
+
+## Performance Implications
+
+[From Phase 3.5.7 performance budget. State the expected performance characteristics
+and any budgets that must be maintained.]
+
+| Operation | Budget | Justification |
+|-----------|--------|---------------|
+| [Key operation 1] | < Xms | [Why this budget] |
+| [Key operation 2] | < Xms | [Why this budget] |
+
+## Implementation Guidance
+
+[From Phase 8. Not the full task list — just enough for an implementer to know
+WHERE to start and what patterns to follow.]
+
+| Order | Task | Files Affected | Effort |
+|-------|------|---------------|--------|
+| 1 | [First task] | [file paths] | XS/S/M/L |
+| 2 | [Second task] | [file paths] | XS/S/M/L |
+
+**Patterns to follow:** [Reference specific existing implementations discovered in Phase 0.8
+that the implementer should use as templates]
+
+## Feature Ladder
+
+[From Phase 4.5. Shows the incremental delivery plan.]
+
+| Version | Scope | Value Delivered |
+|---------|-------|----------------|
+| v0 (MVP) | [smallest useful slice] | [what user can do] |
+| v1 (Complete) | [full feature] | [full value] |
+| v2 (Enhanced) | [future extensions] | [additional value] |
+
+## Links & References
+
+- **Spec:** `docs/specs/<feature>_featureai.md`
+- **Related ADRs:** [list with brief relationship description]
+- **Supersedes:** [ADR number if replacing a previous decision, or "N/A"]
+- **External references:** [Standards, RFCs, competitor docs, regulatory requirements]
+- **Affected components:** [List of files/modules/services from impact analysis]
 ```
 
+### 5.2 ADR Quality Gate (Self-Check Before Writing)
+
+Before writing the ADR file, verify ALL of these:
+
+| Check | Requirement | Source Phase |
+|-------|-------------|-------------|
+| Context has specific forces | Not just "we need X" — enumerate WHY and WHAT CONSTRAINS | Phase 0 + 1 |
+| Decision has numbered sub-decisions | Every design choice from Phase 4 is captured with rationale | Phase 4 |
+| Options >= 3 | At least 3 genuine alternatives evaluated | Phase 2 + 3 |
+| Each option has pros AND cons | No straw-man options set up just to be rejected | Phase 2 + 3 |
+| Consequences are specific | No generic "better UX" — measurable impacts only | Phase 3 + 4 |
+| Negative consequences have mitigations | Every cost is either mitigated or explicitly accepted | Phase 4 |
+| Success criteria are machine-checkable | At least 2 can be verified by automated test | Phase 0.4 |
+| Breaking changes documented or "None" stated | Never omitted silently | Phase 3.5.5 |
+| Security section present | Even if "no new attack surface" — must be explicit | Phase 7 |
+| Performance budget stated | Key operations with time budgets | Phase 3.5.7 |
+| Implementation guidance references real files | Not hypothetical paths — actual discovered locations | Phase 0.8 + 8 |
+| Links trace to spec file | ADR → spec → requirements chain is complete | Phase 10 |
+
+**If any check fails:** Go back to the relevant phase and extract the missing content. Do NOT write placeholder text.
+
+### 5.3 ADR Anti-Patterns (NEVER DO)
+
+- **Skeleton ADR:** `[Problem context — what forces are at play?]` — NEVER use placeholder brackets in the output
+- **Single-option ADR:** Only describing the chosen approach without alternatives — this is a design doc, not an ADR
+- **Consequence-free ADR:** Listing only positives — EVERY decision has real costs
+- **Generic consequences:** "Improves code quality" / "Better maintainability" — be specific or remove
+- **Missing rationale:** "We chose X" without explaining WHY over alternatives
+- **Orphan ADR:** No link to spec, no link to related ADRs, no traceability
+- **Copy-paste from spec:** The ADR is a DECISION record, not a spec summary — focus on WHY, not WHAT
+- **Straw-man options:** Including obviously bad alternatives just to make the chosen option look good
+- **Missing migration strategy:** Documenting breaking changes without explaining how to handle them
+
 ---
 
 ## Phase 6: Error Handling & Diagnostics Design
@@ -753,6 +972,10 @@ Write complete spec to: `docs/specs/<feature_name>_featureai.md`
 ### 10.2 Save ADR
 Write ADR to: `docs/decisions/ADR-NNNN-<feature_name>.md`
 
+**ADR completeness gate:** Before saving, verify the ADR passes ALL checks from Phase 5.2. The ADR file must contain every section defined in Phase 5.1 with substantive content — no placeholder brackets, no skeleton sections, no missing tables. If any section would be empty, go back to the relevant phase and extract the content.
+
+**Minimum ADR size:** A proper ADR for a `--full` mode investigation should be 80-200+ lines. If the ADR is under 60 lines, it is almost certainly missing required sections. For `--internal` mode, minimum 60 lines. For `--outward` mode, minimum 70 lines.
+
 ### 10.3 Report Summary
 Output a complete summary with:
 - **Problem & Evidence** — 1-sentence problem, evidence sources