pan-wizard 3.10.0 → 3.12.0

package/pan-wizard-core/bin/lib/squads.cjs

@@ -0,0 +1,152 @@
+/**
+ * Squads — agent groupings for the bot-army model (ADR-0032).
+ *
+ * A squad is a named, tool-scoped, model-tiered grouping of existing PAN
+ * agents under the pan-conductor coordinator. This module is a registry +
+ * resolver only — it modifies no agent and changes no execution path. The
+ * army campaign command (ADR-0033) consumes it; until then it is inert.
+ */
+
+'use strict';
+
+const { output, error } = require('./core.cjs');
+
+/**
+ * Coordinator + worker/utility agents that are NOT squad members.
+ * - coordinator: the top of the hierarchy (Tier 0).
+ * - workers: cheap narrow-job agents (Tier 2) + standalone utility agents
+ *   invoked directly by commands, not delegated through a squad.
+ */
+const COORDINATOR = 'pan-conductor';
+const WORKERS = Object.freeze([
+  'pan-document_code',     // Haiku-tier codebase mapper
+  'pan-distiller',         // Haiku-tier code-bloat optimizer
+  'pan-optimizer',         // optimization loop
+  'pan-experiment-runner', // self-improvement loop
+  'pan-knowledge',         // retrieval/Q&A
+  'pan-counterfactual',    // what-if worktree replay
+  'pan-previewer',         // foresight synthesis
+]);
+
+/**
+ * The four squads, keyed by lifecycle role. `tier` is a PAN model tier
+ * (resolve-model maps it to a provider model); `access` is the least-privilege
+ * tool contract the conductor grants when delegating to the squad.
+ */
+const SQUADS = Object.freeze({
+  architecture: Object.freeze({
+    label: 'Architecture',
+    tier: 'reasoning',
+    access: 'read-only',
+    summary: 'Designs the system before code — contract-first.',
+    agents: Object.freeze([
+      'pan-roadmapper', 'pan-planner', 'pan-plan-checker',
+      'pan-project-researcher', 'pan-phase-researcher', 'pan-research-synthesizer',
+    ]),
+  }),
+  build: Object.freeze({
+    label: 'Build',
+    tier: 'reasoning',
+    access: 'read-write-bash',
+    summary: 'Turns design and contracts into committed code.',
+    agents: Object.freeze(['pan-executor']),
+  }),
+  quality: Object.freeze({
+    label: 'Quality',
+    tier: 'mid',
+    access: 'read-only',
+    summary: 'Adversarially breaks what Build makes before users do.',
+    agents: Object.freeze([
+      'pan-reviewer', 'pan-hardener', 'pan-meta-reviewer',
+      'pan-verifier', 'pan-integration-checker', 'pan-debugger',
+    ]),
+  }),
+  release: Object.freeze({
+    label: 'Release',
+    tier: 'mid',
+    access: 'always-ask',
+    summary: 'Ships safely behind a human gate; rolls back fast.',
+    agents: Object.freeze(['pan-release']),
+  }),
+});
+
+const SQUAD_NAMES = Object.freeze(Object.keys(SQUADS));
+
+/** @returns {Array<{name, label, tier, access, summary, agent_count}>} */
+function listSquads() {
+  return SQUAD_NAMES.map(name => {
+    const s = SQUADS[name];
+    return { name, label: s.label, tier: s.tier, access: s.access, summary: s.summary, agent_count: s.agents.length };
+  });
+}
+
+/** @returns {object|null} the squad record (with name) or null if unknown. */
+function getSquad(name) {
+  const s = SQUADS[name];
+  return s ? { name, ...s, agents: [...s.agents] } : null;
+}
+
+/** Reverse lookup: which squad owns an agent? @returns {string|null} */
+function squadForAgent(agent) {
+  for (const name of SQUAD_NAMES) {
+    if (SQUADS[name].agents.includes(agent)) return name;
+  }
+  return null;
+}
+
+/**
+ * Validate the roster against the set of real agents.
+ * @param {string[]} knownAgents - agent names that exist on disk
+ * @returns {{ ok: boolean, missing: string[], unassigned: string[] }}
+ *   missing    = squad members with no agent file
+ *   unassigned = real agents that are neither coordinator, worker, nor squad member
+ */
+function validateRoster(knownAgents) {
+  const known = new Set(knownAgents);
+  const missing = [];
+  for (const name of SQUAD_NAMES) {
+    for (const a of SQUADS[name].agents) {
+      if (!known.has(a)) missing.push(a);
+    }
+  }
+  const assigned = new Set([COORDINATOR, ...WORKERS]);
+  for (const name of SQUAD_NAMES) for (const a of SQUADS[name].agents) assigned.add(a);
+  const unassigned = knownAgents.filter(a => !assigned.has(a));
+  return { ok: missing.length === 0 && unassigned.length === 0, missing, unassigned };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+function cmdSquadList(raw) {
+  const squads = listSquads();
+  const human = squads
+    .map(s => `${s.label.padEnd(13)} ${s.tier.padEnd(10)} ${s.access.padEnd(16)} ${s.agent_count} agents`)
+    .join('\n');
+  output({ squads, coordinator: COORDINATOR, workers: [...WORKERS] }, raw, human);
+}
+
+function cmdSquadShow(name, raw) {
+  const s = getSquad(name);
+  if (!s) {
+    return error(`Unknown squad "${name}". Available: ${SQUAD_NAMES.join(', ')}`);
+  }
+  const human = [
+    `${s.label} squad — ${s.tier} tier · ${s.access}`,
+    s.summary,
+    s.agents.length ? 'Agents: ' + s.agents.join(', ') : 'Agents: (none — git-tool driven)',
+  ].join('\n');
+  output(s, raw, human);
+}
+
+module.exports = {
+  SQUADS,
+  SQUAD_NAMES,
+  COORDINATOR,
+  WORKERS,
+  listSquads,
+  getSquad,
+  squadForAgent,
+  validateRoster,
+  cmdSquadList,
+  cmdSquadShow,
+};

package/pan-wizard-core/bin/lib/worktree.cjs

@@ -0,0 +1,123 @@
+/**
+ * Worktree — branch-per-agent isolation for the bot army (ADR-0033).
+ *
+ * The Build squad parallelizes by giving each builder its own git worktree
+ * on its own `army/<task>` branch, so concurrent agents never touch the same
+ * working tree or the same file. Generalizes the worktree primitive proven in
+ * whatif.cjs; the army campaign command drives it. Zero deps, synchronous,
+ * cross-platform (delegates to execGit).
+ */
+
+'use strict';
+
+const path = require('path');
+const { execGit, isGitRepo, toPosix, generateSlugInternal, output, error } = require('./core.cjs');
+
+const ARMY_BRANCH_PREFIX = 'army/';
+
+/**
+ * Create an isolated worktree + branch for one army task.
+ * @param {string} cwd - main project root
+ * @param {string} task - free-text task name (slugified for branch/path)
+ * @param {Object} [opts] - { base: ref (default 'HEAD'), worktree_root }
+ * @returns {{worktree_path, branch, base}|{error}}
+ */
+function createTaskWorktree(cwd, task, opts) {
+  if (!task || !String(task).trim()) return { error: 'task name required' };
+  if (!isGitRepo(cwd)) return { error: 'Not a git repo — branch-per-agent requires git worktree support' };
+
+  const slug = generateSlugInternal(String(task)).slice(0, 40);
+  const branch = `${ARMY_BRANCH_PREFIX}${slug}`;
+  const worktreeRoot = opts?.worktree_root
+    || path.join(path.dirname(path.resolve(cwd)), `pan-army-${slug}`);
+  const base = opts?.base || 'HEAD';
+
+  const result = execGit(cwd, ['worktree', 'add', '-b', branch, worktreeRoot, base]);
+  if (result.exitCode !== 0) {
+    return { error: `git worktree add failed: ${result.stderr}` };
+  }
+  return { worktree_path: toPosix(worktreeRoot), branch, base };
+}
+
+/**
+ * Remove an army worktree + its branch. Best-effort; warnings surfaced.
+ * @returns {{removed: true, warnings: string[]}|{error}}
+ */
+function removeTaskWorktree(cwd, worktreePath, branch, opts) {
+  if (!isGitRepo(cwd)) return { error: 'Not a git repo' };
+  const warnings = [];
+  const rmArgs = ['worktree', 'remove'];
+  if (opts?.force === true) rmArgs.push('--force');
+  rmArgs.push(worktreePath);
+  const rm = execGit(cwd, rmArgs);
+  if (rm.exitCode !== 0) warnings.push(`worktree remove: ${rm.stderr.trim()}`);
+
+  if (branch) {
+    // Only delete branches we created (army/ prefix), and only if not checked out.
+    if (branch.startsWith(ARMY_BRANCH_PREFIX)) {
+      const del = execGit(cwd, ['branch', '-D', branch]);
+      if (del.exitCode !== 0) warnings.push(`branch -D ${branch}: ${del.stderr.trim()}`);
+    } else {
+      warnings.push(`refused to delete non-army branch ${branch}`);
+    }
+  }
+  return { removed: true, warnings };
+}
+
+/**
+ * List the army worktrees currently registered (army/ branches only).
+ * Parses `git worktree list --porcelain`.
+ * @returns {Array<{worktree, branch}>}
+ */
+function listArmyWorktrees(cwd) {
+  if (!isGitRepo(cwd)) return [];
+  const r = execGit(cwd, ['worktree', 'list', '--porcelain']);
+  if (r.exitCode !== 0) return [];
+  const out = [];
+  let current = {};
+  for (const line of r.stdout.split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) {
+      current = { worktree: toPosix(line.slice('worktree '.length).trim()) };
+    } else if (line.startsWith('branch ')) {
+      const ref = line.slice('branch '.length).trim().replace('refs/heads/', '');
+      current.branch = ref;
+      if (ref.startsWith(ARMY_BRANCH_PREFIX)) out.push({ ...current });
+    } else if (line === '') {
+      current = {};
+    }
+  }
+  return out;
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+function cmdWorktreeList(cwd, raw) {
+  const trees = listArmyWorktrees(cwd);
+  const human = trees.length
+    ? trees.map(t => `${t.branch}  →  ${t.worktree}`).join('\n')
+    : 'No army worktrees';
+  output({ worktrees: trees, count: trees.length }, raw, human);
+}
+
+function cmdWorktreeCreate(cwd, task, raw, opts) {
+  const r = createTaskWorktree(cwd, task, opts);
+  if (r.error) return error(r.error);
+  output(r, raw, `${r.branch} → ${r.worktree_path}`);
+}
+
+function cmdWorktreeRemove(cwd, worktreePath, branch, raw, opts) {
+  if (!worktreePath) return error('worktree path required');
+  const r = removeTaskWorktree(cwd, worktreePath, branch, opts);
+  if (r.error) return error(r.error);
+  output(r, raw, r.warnings.length ? r.warnings.join('\n') : 'removed');
+}
+
+module.exports = {
+  ARMY_BRANCH_PREFIX,
+  createTaskWorktree,
+  removeTaskWorktree,
+  listArmyWorktrees,
+  cmdWorktreeList,
+  cmdWorktreeCreate,
+  cmdWorktreeRemove,
+};

package/pan-wizard-core/bin/pan-tools.cjs

@@ -147,6 +147,7 @@
  * Pre-Flight & Dashboard:
  *   preflight [phase|batch]            Validate execution prerequisites
  *   dashboard                          Aggregated project status overview
+ *   hud [--out f] [--open] [--stdout]  Single-page HTML army + project dashboard
  *
  * Session Learnings:
  *   learnings extract                  Extract patterns from session data
@@ -856,6 +857,16 @@ async function main() {
       break;
     }
 
+    case 'hud': {
+      const hud = require('./lib/hud.cjs');
+      hud.cmdHud(cwd, {
+        out: getArgValue(args, '--out'),
+        open: args.includes('--open'),
+        stdout: args.includes('--stdout'),
+      }, raw);
+      break;
+    }
+
     case 'learnings': {
       const subcommand = args[1];
       if (subcommand === 'extract') {
@@ -1049,6 +1060,63 @@ async function main() {
       break;
     }
 
+    case 'squad': {
+      const squads = require('./lib/squads.cjs');
+      const subcommand = args[1];
+      if (subcommand === 'list' || !subcommand) {
+        squads.cmdSquadList(raw);
+      } else if (subcommand === 'show') {
+        squads.cmdSquadShow(args[2], raw);
+      } else {
+        error('Unknown squad subcommand. Available: list, show');
+      }
+      break;
+    }
+
+    case 'worktree': {
+      const worktree = require('./lib/worktree.cjs');
+      const subcommand = args[1];
+      if (subcommand === 'list' || !subcommand) {
+        worktree.cmdWorktreeList(cwd, raw);
+      } else if (subcommand === 'create') {
+        worktree.cmdWorktreeCreate(cwd, args[2], raw, { base: getArgValue(args, '--base') });
+      } else if (subcommand === 'remove') {
+        worktree.cmdWorktreeRemove(cwd, args[2], getArgValue(args, '--branch'), raw, { force: args.includes('--force') });
+      } else {
+        error('Unknown worktree subcommand. Available: list, create, remove');
+      }
+      break;
+    }
+
+    case 'campaign': {
+      const campaign = require('./lib/campaign.cjs');
+      const subcommand = args[1];
+      if (subcommand === 'schedule') {
+        const budget = getArgValue(args, '--daily-budget');
+        campaign.cmdCampaignSchedule(cwd, {
+          goal: getArgValue(args, '--goal'),
+          source: getArgValue(args, '--source'),
+          cadence: getArgValue(args, '--cadence', 'daily'),
+          daily_budget: budget != null ? Number(budget) : undefined,
+          enabled: args.includes('--disable') ? false : undefined,
+          paused: args.includes('--pause') ? true : (args.includes('--resume') ? false : undefined),
+        }, raw);
+      } else if (subcommand === 'status' || !subcommand) {
+        campaign.cmdCampaignStatus(cwd, raw);
+      } else if (subcommand === 'due') {
+        campaign.cmdCampaignDue(cwd, raw);
+      } else if (subcommand === 'record-run') {
+        const r = campaign.recordRun(cwd, {
+          items_landed: Number(getArgValue(args, '--items', 0)),
+          points_used: Number(getArgValue(args, '--points', 0)),
+        });
+        if (r.error) { error(r.error); } else { output(r, raw, `recorded · next ${r.next_due}`); }
+      } else {
+        error('Unknown campaign subcommand. Available: schedule, status, due, record-run');
+      }
+      break;
+    }
+
     case 'bus': {
       const subcommand = args[1];
       if (subcommand === 'publish') {

package/pan-wizard-core/learnings/universal/autonomous-loop.md

@@ -0,0 +1,56 @@
+---
+topic: autonomous-loop
+last_updated: 2026-06-12T00:00:00.000Z
+patterns:
+  - id: P-310
+    summary: Autonomous build loops should fan out research and verify in parallel but keep implement/build a single serial step, then seal with one clean build at loop end
+    promoted_at: 2026-06-12T00:00:00.000Z
+    source_experiments: [montyhall-focus-loop]
+---
+
+# Autonomous Loop (AI-derived)
+
+> Hand-promoted from a downstream `/focus-loop` campaign command (MontyHall compiler project) and generalized in ADR-0031. Patterns are **advisory** — orchestrators weight them against current context.
+
+## P-310 — Parallel-research → single-serial-build → parallel-verify, then clean-seal
+
+**Evidence:** A backlog-driven autonomous loop that landed many items per run converged on this shape (the "cc#67/cc#68" discipline): research and verification are read-only and parallelize cheaply via the Workflow tool, but the implement/build step mutates shared state and must be a *single* serial actor. Per-item incremental commits twice produced cross-item orphans — a symbol defined only in an uncommitted file, or a combined state that didn't build clean — which only a from-scratch build at loop end caught.
+
+**Rule:** For any pick → build → verify → commit → repeat loop:
+
+1. **Fan out research in parallel** (read-only agents): map the substrate, scope the honest-partial boundary, probe for support. Mutate nothing.
+2. **Implement/build is exactly ONE serial actor** — never inside a `parallel()`. If the project's build trees corrupt under concurrency, enforce at-most-one-builder across the whole loop (a per-project opt-in, not a universal law).
+3. **Fan out verify in parallel** (read-only) over the already-built tree: correctness / security / honesty lenses.
+4. **Commit-quality gates:** a *staging-miss guard* (no implementer-touched file left unstaged — never `git add -A`, never a hand-picked subset) and an *orphan audit* (HEAD references no symbol defined only in an uncommitted file).
+5. **Clean-build seal once at loop end:** per-item builds are incremental for speed; a single from-scratch build + full verification after the last item catches cross-item orphans the incremental builds hid.
+6. **Rank the backlog from the CURRENT document** (value/effort), never a frozen ID list, so the order never goes stale; honest-partial aggressively and strike only what landed.
+
+**Applies in:** `/pan:focus-auto` (`--source backlog`, `--parallel-research`/`--parallel-verify`/`--clean-seal`; ADR-0031), any Workflow-orchestrated build campaign, hierarchical exec (`pan-conductor`).
+
+## P-330 — Scale agents into a coordinated army with squads, worktree isolation, and a human-gated ship
+
+**Evidence:** The bot-army model (ADR-0032/0033) showed the durable shape for running a whole-project goal across many agents: a delegation-only coordinator (never codes) fans work to role-scoped *squads* (architecture/build/quality/release), the build squad parallelizes by giving each agent its own branch + git worktree (so concurrent builders never touch the same file), quality is adversarial and read-only, and the path to a protected branch is a human-approved gate, not a bot merge.
+
+**Rule:** When scaling beyond a single agent:
+
+1. **Coordinator delegates, never codes** — its tools are delegation-only; it plans, decomposes, and routes to squads, then aggregates tight summaries.
+2. **Group agents into role-scoped squads with least-privilege tools** — design read-only, build read/write, quality read-only/adversarial, release always-ask. Resolve the roster from data, not hardcoded prompt lists.
+3. **Parallelize by isolation, not by hope** — one branch + worktree per concurrent builder; never two agents in one tree. Serialize builds only where the build tree corrupts under concurrency (a per-project opt-in).
+4. **The mutating boundary is human-gated** — merging to a protected branch is `always-ask`; recovery is revert / previous tag, never force-push or history rewrite.
+5. **The harness scales with the army, not after it** — depth caps, spawn/budget ceilings, and an abort kill-switch checked before every spawn are mandatory; a longer loop must not relax a single cap. Power and safety are the same investment.
+
+**Applies in:** `/pan:army` (ADR-0033), `pan-conductor` campaign mode, `squads.cjs` / `worktree.cjs`, any multi-agent delivery.
+
+## P-340 — Schedule autonomy as a due-check the host fires, not a daemon you embed
+
+**Evidence:** Making the army run over days (ADR-0034) surfaced the right boundary for a prompt-driven tool that lives inside a host session: it cannot wake itself while the session is closed, and pretending to (an embedded scheduler/daemon spawning agents in the background) is both a false promise and a security surface. The durable design split ownership — PAN owns the schedule *descriptor* and the *decision whether a run is due*; the host scheduler owns *firing* it.
+
+**Rule:** For "run X automatically over time" in a session-bound agent:
+
+1. **Persist a schedule descriptor, not a timer** — cadence, next-due, per-day budget, enabled/paused — in project state.
+2. **Expose a cheap, side-effect-free `due` check** the external trigger polls; make the *reason* explicit (`not_yet` / `paused` / `budget_exhausted_today` / `due`) so skips are auditable.
+3. **Let the host fire it** — cron / routines / a session loop / a next-open nudge — rather than embedding a background daemon.
+4. **Resume from persisted state**, advancing next-due and accruing per-day spend on each run; cap the day, not just the run.
+5. **Never let a schedule lower an irreversible-action gate** — scheduled or not, the human approves the merge. Autonomy extends up to the irreversible step, never through it.
+
+**Applies in:** `campaign.cjs` + `/pan:army --schedule` (ADR-0034), any cron/`/loop`-driven PAN automation, the self-improvement loop on a cadence.