pan-wizard 3.35.0 → 3.37.0

package/scripts/test-surface.cjs

@@ -19,7 +19,9 @@
  * Modes:
  *   node scripts/test-surface.cjs            summary
  *   node scripts/test-surface.cjs --write    write tests/fixtures/surface.json (the committed registry)
- *   node scripts/test-surface.cjs --check    exit 1 when the committed registry differs from the code
+ *   node scripts/test-surface.cjs --check    exit 1 when the committed registry differs from the code, or
+ *                                            a command, agent, verb or config key has no user (liveness, L1)
+ *   node scripts/test-surface.cjs --liveness who uses each command, agent, verb, subcommand and config key
  *   node scripts/test-surface.cjs --map      which test files reference each surface row; lists the misses
  *   node scripts/test-surface.cjs --scaffold <dir>   one todo stub per unreferenced row (for a suite rebuilt from scratch)
  *
@@ -297,6 +299,153 @@ function scaffold(missingRows, outDir) {
 
 function readJson(p) { return JSON.parse(fs.readFileSync(p, 'utf8')); }
 
+// ─── Liveness (program L1) ──────────────────────────────────────────────────
+//
+// The map above asks "does a test name it?". Liveness asks "does anything USE it?":
+//   - every shipped command and agent is named by a harness scenario, so some behavioural
+//     run exercises it as a user would;
+//   - every pan-tools verb and subcommand has a caller in what PAN ships: a prompt
+//     (commands, agents, workflows, references, templates), a native workflow's prompt
+//     (bin/install-lib.cjs), or an MCP tool or resource (the bridge registry);
+//   - every config default has a reader: code under the core, hooks, installer or MCP
+//     bridge that reads the key, or a shipped prompt that runs `config-get <key>`.
+// An orphan either gains a user or sits in tests/fixtures/liveness-allowlist.json with a
+// reason; `--check` fails on an orphan without one, and on an entry no longer needed.
+
+const LIVENESS_ALLOWLIST_REL = path.join('tests', 'fixtures', 'liveness-allowlist.json');
+const PROMPT_DIRS = Object.freeze(['commands/pan', 'agents', 'pan-wizard-core/workflows', 'pan-wizard-core/references', 'pan-wizard-core/templates']);
+const NATIVE_WORKFLOW_SOURCES = Object.freeze(['bin/install-lib.cjs']);
+const READER_DIRS = Object.freeze(['pan-wizard-core/bin', 'pan-wizard-core/mcp', 'pan-wizard-core/opencode', 'hooks', 'bin']);
+const SCENARIO_DIR = 'harness/scenarios';
+
+/** Every file under rel (recursively) whose name matches re, as posix paths; skips dist/ and node_modules/. */
+function walkFiles(root, rel, re) {
+  const out = [];
+  const walk = (r) => {
+    let ents;
+    try { ents = fs.readdirSync(path.join(root, r), { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const p = path.posix.join(r, e.name);
+      if (e.isDirectory()) { if (e.name !== 'dist' && e.name !== 'node_modules') walk(p); } else if (re.test(e.name)) out.push(p);
+    }
+  };
+  walk(rel);
+  return out.sort();
+}
+
+/**
+ * The verbs and `verb sub` pairs a text invokes: the script path (`pan-tools.cjs <verb>`),
+ * a backticked `pan-tools <verb>`, or `pan-tools <verb>` as a shell command (opening a
+ * line, or after `|`, `;`, `&` or `(`), then the verb and an optional subcommand. Prose
+ * that mentions pan-tools is not a call.
+ */
+function pantoolsCalls(text) {
+  const out = new Set();
+  const re = /(?:pan-tools\.cjs["']?|`pan-tools|(?:^|[|;&(])[ \t]*pan-tools)[ \t]+([a-z][a-z0-9-]*)(?:[ \t]+([a-z][a-z0-9-]*))?/gm;
+  let m;
+  while ((m = re.exec(text))) { out.add(m[1]); if (m[2]) out.add(`${m[1]} ${m[2]}`); }
+  return out;
+}
+
+/** The text a liveness check reads, from the tree. Tests pass a hand-built object instead. */
+function loadLivenessInputs(root = ROOT) {
+  const read = (rel) => fs.readFileSync(path.join(root, rel), 'utf8');
+  const prompts = PROMPT_DIRS.flatMap((d) => walkFiles(root, d, /\.(md|js)$/)).map((file) => ({ file, src: read(file) }));
+  const native = NATIVE_WORKFLOW_SOURCES.filter((f) => fs.existsSync(path.join(root, f))).map((file) => ({ file, src: read(file) }));
+  const registry = require(path.join(root, SOURCES.mcpRegistry));
+  const mcp = [...(registry.TOOLS || []), ...(registry.RESOURCES || [])].map((t) => ({ name: t.name || t.uri, verb: t.verb, sub: (t.args && t.args[0]) || null }));
+  const scenarios = walkFiles(root, SCENARIO_DIR, /\.json$/).map((file) => ({ file, src: read(file) }));
+  const configSrc = path.posix.normalize(SOURCES.config);
+  const readers = READER_DIRS.flatMap((d) => walkFiles(root, d, /\.(c?js|mjs)$/)).map((file) => ({ file, src: read(file), isConfig: file === configSrc }));
+  return { prompts, native, mcp, scenarios, readers };
+}
+
+/** The body of buildConfigDefaults in config.cjs: where defaults are written, which is not a read. */
+function stripDefaultsBuilder(src) {
+  const start = src.indexOf('function buildConfigDefaults');
+  if (start === -1) return src;
+  const open = src.indexOf('{', start);
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}' && --depth === 0) return src.slice(0, start) + src.slice(i + 1);
+  }
+  return src;
+}
+
+/**
+ * Who uses each piece of the surface. Pure over `surface` (extractSurface) and `inputs`
+ * (loadLivenessInputs). Returns one row per command, agent, verb, subcommand and config
+ * key: `{id, kind, users: string[]}`; a row with no users is an orphan.
+ */
+function liveness(surface, inputs) {
+  const rows = [];
+  const scen = inputs.scenarios;
+  const named = (re) => scen.filter((s) => re.test(s.src)).map((s) => s.file);
+  for (const f of surface.content['commands/pan'] || []) {
+    const name = f.replace(/\.md$/, '');
+    // /pan:<name> (Claude, Gemini), /pan-<name> or pan-<name> as a skill (Codex, Copilot, OpenCode), or the file itself.
+    rows.push({ id: `command:${name}`, kind: 'command', users: named(new RegExp(`(?:/pan[:-]|commands/pan/|\\bpan-)${esc(name)}(?![a-z0-9-])`)) });
+  }
+  for (const f of surface.content.agents || []) {
+    const name = f.replace(/\.md$/, '');
+    rows.push({ id: `agent:${name}`, kind: 'agent', users: named(new RegExp(`(?<![a-z0-9-])${esc(name)}(?![a-z0-9-])`)) });
+  }
+  const callers = new Map();
+  const add = (key, who) => { if (!callers.has(key)) callers.set(key, new Set()); callers.get(key).add(who); };
+  for (const t of [...inputs.prompts, ...inputs.native]) for (const c of pantoolsCalls(t.src)) add(c, t.file);
+  // A registry entry with no verb (one served by the bridge itself) calls nothing.
+  for (const t of inputs.mcp.filter((x) => x.verb)) { add(t.verb, `mcp:${t.name}`); if (t.sub) add(`${t.verb} ${t.sub}`, `mcp:${t.name}`); }
+  for (const v of surface.verbs) {
+    const direct = callers.get(v) || new Set();
+    // A verb is alive when it is called, bare or through any of its subcommands.
+    const viaSub = [...callers.entries()].filter(([k]) => k.startsWith(`${v} `)).flatMap(([, s]) => [...s]);
+    rows.push({ id: `caller:verb:${v}`, kind: 'verb', users: [...new Set([...direct, ...viaSub])].sort() });
+  }
+  for (const s of surface.subcommands) rows.push({ id: `caller:sub:${s}`, kind: 'sub', users: [...(callers.get(s) || [])].sort() });
+  const readerText = inputs.readers.map((r) => ({ file: r.file, src: r.isConfig ? stripDefaultsBuilder(r.src) : r.src }));
+  const promptText = [...inputs.prompts, ...inputs.native];
+  for (const key of surface.config_keys) {
+    const last = esc(key.split('.').pop());
+    const codeRe = new RegExp(`['"\`]${esc(key)}['"\`]|\\.${last}\\b|\\[['"]${last}['"]\\]|['"]${last}['"]`);
+    // A prompt reads a key with `config-get <key>`, or names the full dotted key in backticks
+    // for the agent to check in the config or the init payload (`workflow.x: true`).
+    const promptRe = new RegExp(`config-get[ \\t]+["']?${esc(key)}\\b|\`${esc(key)}[\`:= ]`);
+    const users = [...readerText.filter((r) => codeRe.test(r.src)).map((r) => r.file), ...promptText.filter((p) => promptRe.test(p.src)).map((p) => p.file)];
+    rows.push({ id: `reader:config:${key}`, kind: 'config', users: [...new Set(users)].sort() });
+  }
+  return rows;
+}
+
+/**
+ * Orphans not allowlisted, and allowlist entries that are wrong (no reason, no such row, or
+ * a row that has users now). `--check` fails when either list is non-empty.
+ */
+function livenessProblems(rows, allowlist) {
+  const allow = new Map(allowlist.map((a) => [a.id, a]));
+  const problems = [];
+  for (const a of allowlist) {
+    if (!a.reason || !String(a.reason).trim()) problems.push(`liveness allowlist entry ${a.id} has no reason`);
+    const row = rows.find((r) => r.id === a.id);
+    if (!row) problems.push(`liveness allowlist entry ${a.id} names nothing that exists — remove it`);
+    else if (row.users.length) problems.push(`liveness allowlist entry ${a.id} has a user now (${row.users[0]}) — remove the entry`);
+  }
+  const hint = { command: 'name it in a harness scenario', agent: 'name it in a harness scenario', verb: 'call it from a shipped prompt', sub: 'call it from a shipped prompt', config: 'read it in code, or drop the default' };
+  for (const r of rows) if (!r.users.length && !allow.has(r.id)) problems.push(`orphan ${r.id} — ${hint[r.kind]}, or allowlist it in ${LIVENESS_ALLOWLIST_REL} with a reason`);
+  return problems;
+}
+
+/** What `--check` decides: registry drift plus liveness problems. Pure. */
+function checkReport(committed, surface, inputs, allowlist) {
+  const drift = diffSurface(committed, surface);
+  const live = livenessProblems(liveness(surface, inputs), allowlist);
+  return { drift, live, ok: !drift.added.length && !drift.removed.length && !live.length };
+}
+
+function readLivenessAllowlist(root = ROOT) {
+  try { return readJson(path.join(root, LIVENESS_ALLOWLIST_REL)); } catch { return []; }
+}
+
 // ─── CLI ────────────────────────────────────────────────────────────────────
 
 function main(argv) {
@@ -310,13 +459,32 @@ function main(argv) {
   if (argv.includes('--check')) {
     let committed;
     try { committed = readJson(registryPath); } catch { console.error(`no committed registry at ${REGISTRY_REL} — run --write`); return 1; }
-    const d = diffSurface(committed, surface);
-    if (!d.added.length && !d.removed.length) { console.log('surface registry matches the code'); return 0; }
-    console.error(`surface registry is stale — run \`node scripts/test-surface.cjs --write\` and commit it`);
-    for (const x of d.added) console.error(`  + ${x}`);
-    for (const x of d.removed) console.error(`  - ${x}`);
+    const { drift: d, live, ok: surfaceOk } = checkReport(committed, surface, loadLivenessInputs(ROOT), readLivenessAllowlist(ROOT));
+    // H6: the prompt-rule rows. A rule that is neither grandfathered nor claimed by a
+    // scenario's covers (or allowlisted with a reason) fails, as does a stale registry.
+    const rules = require('./prompt-rules.cjs').checkRegistry(ROOT);
+    const ok = surfaceOk && !rules.stale && !rules.unclaimed.length && !rules.dangling.length;
+    if (ok) { console.log('surface registry matches the code; every command, agent, verb and config key is alive; every new prompt rule is claimed'); return 0; }
+    if (rules.stale) console.error('prompt-rule registry is stale — run `node scripts/prompt-rules.cjs --write` and commit it');
+    for (const u of rules.unclaimed) console.error(`  unclaimed prompt rule ${u.id}: "${u.text.slice(0, 80)}"`);
+    for (const x of rules.dangling) console.error(`  scenario ${x.scenario} covers ${x.id}, which is no rule`);
+    if (d.added.length || d.removed.length) {
+      console.error(`surface registry is stale — run \`node scripts/test-surface.cjs --write\` and commit it`);
+      for (const x of d.added) console.error(`  + ${x}`);
+      for (const x of d.removed) console.error(`  - ${x}`);
+    }
+    if (live.length) {
+      console.error('liveness: orphans without a user or an allowlist reason');
+      for (const x of live) console.error(`  ${x}`);
+    }
     return 1;
   }
+  if (argv.includes('--liveness')) {
+    const rows = liveness(surface, loadLivenessInputs(ROOT));
+    for (const r of rows) console.log(`${r.users.length ? 'ok    ' : 'ORPHAN'} ${r.id.padEnd(48)} ${r.users.slice(0, 2).join(', ')}${r.users.length > 2 ? ` +${r.users.length - 2}` : ''}`);
+    console.log(`liveness rows: ${rows.length} · orphans: ${rows.filter((r) => !r.users.length).length}`);
+    return 0;
+  }
   const rows = mapSurface(surfaceRows(surface), loadTestSources(ROOT));
   const missing = rows.filter((r) => !r.hits.length);
   if (argv.includes('--scaffold')) {
@@ -339,4 +507,5 @@ module.exports = {
   ROOT, REGISTRY_REL, ALLOWLIST_REL, SOURCES, EXTRA_HOOK_ROWS,
   parseTopLevelCommands, parseGroupSubcommands, parseCaseArms, parseInstallerFlags, flattenKeys, hookMatrix,
   extractSurface, surfaceRows, referencePattern, mapSurface, listTestFiles, loadTestSources, diffSurface, scaffold,
+  LIVENESS_ALLOWLIST_REL, pantoolsCalls, loadLivenessInputs, stripDefaultsBuilder, liveness, livenessProblems, checkReport, readLivenessAllowlist,
 };

package/agents/pan-research-synthesizer.md

@@ -1,246 +0,0 @@
----
-name: pan-research-synthesizer
-description: Synthesizes research outputs from parallel researcher agents into summary.md. Spawned by /pan:new-project or /pan:milestone-new after 4 researcher agents complete.
-tools: Read, Write, Bash
-color: purple
-effort: medium
----
-
-<role>
-You are a PAN research synthesizer. You read the outputs from 4 parallel researcher agents and synthesize them into a cohesive summary.md.
-
-You are spawned by:
-
-- `/pan:new-project` or `/pan:milestone-new` orchestrator (after STACK, FEATURES, ARCHITECTURE, PITFALLS research completes)
-
-Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications.
-
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
-
-**Core responsibilities:**
-- Read all 4 research files (stack.md, features.md, architecture.md, pitfalls.md)
-- Synthesize findings into executive summary
-- Derive roadmap implications from combined research
-- Identify confidence levels and gaps
-- Write summary.md
-- Commit ALL research files (researchers write but don't commit — you commit everything)
-
-**CRITICAL: Write output files directly with the Write tool.** Never create
-helper scripts, temp files, or scratch artifacts inside `.planning/` — your
-commit step commits everything in research/, so any litter ships into the
-project history. If you must use Bash for anything transient, do it outside
-`.planning/` and clean up before committing.
-</role>
-
-<downstream_consumer>
-Your summary.md is consumed by the pan-roadmapper agent which uses it to:
-
-| Section | How Roadmapper Uses It |
-|---------|------------------------|
-| Executive Summary | Quick understanding of domain |
-| Key Findings | Technology and feature decisions |
-| Implications for Roadmap | Phase structure suggestions |
-| Research Flags | Which phases need deeper research |
-| Gaps to Address | What to flag for validation |
-
-**Be opinionated.** The roadmapper needs clear recommendations, not wishy-washy summaries.
-</downstream_consumer>
-
-<execution_flow>
-
-## Step 1: Read Research Files
-
-Read all 4 research files:
-
-```bash
-cat .planning/research/stack.md
-cat .planning/research/features.md
-cat .planning/research/architecture.md
-cat .planning/research/pitfalls.md
-
-# The commit step loads the planning config through pan-tools
-```
-
-Parse each file to extract:
-- **stack.md:** Recommended technologies, versions, rationale
-- **features.md:** Table stakes, differentiators, anti-features
-- **architecture.md:** Patterns, component boundaries, data flow
-- **pitfalls.md:** Critical/moderate/minor pitfalls, phase warnings
-
-## Step 2: Synthesize Executive Summary
-
-Write 2-3 paragraphs that answer:
-- What type of product is this and how do experts build it?
-- What's the recommended approach based on research?
-- What are the key risks and how to mitigate them?
-
-Someone reading only this section should understand the research conclusions.
-
-## Step 3: Extract Key Findings
-
-For each research file, pull out the most important points:
-
-**From stack.md:**
-- Core technologies with one-line rationale each
-- Any critical version requirements
-
-**From features.md:**
-- Must-have features (table stakes)
-- Should-have features (differentiators)
-- What to defer to v2+
-
-**From architecture.md:**
-- Major components and their responsibilities
-- Key patterns to follow
-
-**From pitfalls.md:**
-- Top 3-5 pitfalls with prevention strategies
-
-## Step 4: Derive Roadmap Implications
-
-This is the most important section. Based on combined research:
-
-**Suggest phase structure:**
-- What should come first based on dependencies?
-- What groupings make sense based on architecture?
-- Which features belong together?
-
-**For each suggested phase, include:**
-- Rationale (why this order)
-- What it delivers
-- Which features from features.md
-- Which pitfalls it must avoid
-
-**Add research flags:**
-- Which phases likely need `/pan:research-phase` during planning?
-- Which phases have well-documented patterns (skip research)?
-
-## Step 5: Assess Confidence
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | [level] | [based on source quality from stack.md] |
-| Features | [level] | [based on source quality from features.md] |
-| Architecture | [level] | [based on source quality from architecture.md] |
-| Pitfalls | [level] | [based on source quality from pitfalls.md] |
-
-Identify gaps that couldn't be resolved and need attention during planning.
-
-## Step 6: Write summary.md
-
-Use template: ~/.claude/pan-wizard-core/templates/research-project/summary.md
-
-Write to `.planning/research/summary.md`
-
-## Step 7: Commit All Research
-
-The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
-
-```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: complete project research" --files .planning/research/
-```
-
-## Step 8: Return Summary
-
-Return brief confirmation with key points for the orchestrator.
-
-</execution_flow>
-
-<output_format>
-
-Use template: ~/.claude/pan-wizard-core/templates/research-project/summary.md
-
-Key sections:
-- Executive Summary (2-3 paragraphs)
-- Key Findings (summaries from each research file)
-- Implications for Roadmap (phase suggestions with rationale)
-- Confidence Assessment (honest evaluation)
-- Sources (aggregated from research files)
-
-</output_format>
-
-<structured_returns>
-
-## Synthesis Complete
-
-When summary.md is written and committed:
-
-```markdown
-## SYNTHESIS COMPLETE
-
-**Files synthesized:**
-- .planning/research/stack.md
-- .planning/research/features.md
-- .planning/research/architecture.md
-- .planning/research/pitfalls.md
-
-**Output:** .planning/research/summary.md
-
-### Executive Summary
-
-[2-3 sentence distillation]
-
-### Roadmap Implications
-
-Suggested phases: [N]
-
-1. **[Phase name]** — [one-liner rationale]
-2. **[Phase name]** — [one-liner rationale]
-3. **[Phase name]** — [one-liner rationale]
-
-### Research Flags
-
-Needs research: Phase [X], Phase [Y]
-Standard patterns: Phase [Z]
-
-### Confidence
-
-Overall: [HIGH/MEDIUM/LOW]
-Gaps: [list any gaps]
-
-### Ready for Requirements
-
-summary.md committed. Orchestrator can proceed to requirements definition.
-```
-
-## Synthesis Blocked
-
-When unable to proceed:
-
-```markdown
-## SYNTHESIS BLOCKED
-
-**Blocked by:** [issue]
-
-**Missing files:**
-- [list any missing research files]
-
-**Awaiting:** [what's needed]
-```
-
-</structured_returns>
-
-<success_criteria>
-
-Synthesis is complete when:
-
-- [ ] All 4 research files read
-- [ ] Executive summary captures key conclusions
-- [ ] Key findings extracted from each file
-- [ ] Roadmap implications include phase suggestions
-- [ ] Research flags identify which phases need deeper research
-- [ ] Confidence assessed honestly
-- [ ] Gaps identified for later attention
-- [ ] summary.md follows template format
-- [ ] File committed to git
-- [ ] Structured return provided to orchestrator
-
-Quality indicators:
-
-- **Synthesized, not concatenated:** Findings are integrated, not just copied
-- **Opinionated:** Clear recommendations emerge from combined research
-- **Actionable:** Roadmapper can structure phases based on implications
-- **Honest:** Confidence levels reflect actual source quality
-
-</success_criteria>