pan-wizard 3.10.0 → 3.12.0

package/commands/pan/army.md

@@ -0,0 +1,169 @@
+---
+name: army
+group: Army
+description: Bot-army campaign — Mission Control (Opus conductor) delegates a whole-project goal to squads (architecture / build / quality / release), each squad working branch-per-agent worktrees under a hard safety harness, gated by CI + a human merge, looping plan→delegate→execute→review→integrate→learn until the goal ships or a stop condition fires.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - Task
+---
+
+# /pan:army — Bot-Army Campaign (mission control → squads → ship)
+
+Run a whole-project delivery as a coordinated bot army (ADR-0032 squads · ADR-0033 campaign). **Mission Control** — the Opus `pan-conductor`, elevated to campaign scope — plans the mission, delegates to **squads** over the Agent toolset, and never writes code itself. Each squad owns its lifecycle role; the Build squad parallelizes by giving every builder its own `army/<task>` branch in an isolated git worktree. Nothing reaches a protected branch without green CI and a human's approval. $ARGUMENTS
+
+The army is the campaign-scale sibling of `/pan:exec-phase --hierarchical` (one phase) and `/pan:focus-auto` (a category/backlog loop). It composes both: the conductor harness bounds it, the focus-auto loop drives it, the squads structure it.
+
+---
+
+## Tiers (from `pan-tools squad list`)
+
+| Tier | Who | Model | Access |
+|------|-----|-------|--------|
+| 0 · Mission Control | `pan-conductor` | Opus 4.8 | delegation-only (Agent toolset) — never codes |
+| 1 · Architecture | roadmapper · planner · plan-checker · researchers | Sonnet (reasoning) | read-only |
+| 1 · Build | `pan-executor` | Sonnet (reasoning) | read / write / bash — one branch+worktree per agent |
+| 1 · Quality | reviewer · hardener · meta · verifier · integration · debugger | Sonnet/Haiku (mid) | read-only, adversarial |
+| 1 · Release | `pan-release` | Sonnet (mid) | always-ask — human gate |
+| 2 · Workers | document_code · distiller | Haiku (fast) | narrow, high-volume jobs |
+
+Resolve the roster at runtime — never hardcode it: `pan-tools squad list` and `pan-tools squad show <name>`.
+
+---
+
+## Concurrency model (LOAD-BEARING)
+
+Read-only stages fan out; the mutating stage stays isolated, never shared:
+
+| Stage | Concurrency |
+|-------|-------------|
+| Research (Architecture, Quality) | **Parallel** — read-only, mutate nothing |
+| Build | **Parallel across agents, but each in its OWN worktree** — `pan-tools worktree create <task>`; two agents never share a tree or a file |
+| Integrate / Release | **Serial, human-gated** — one merge at a time, `always-ask` |
+
+If the project declares `concurrency.serial_build: true` in `.planning/config.json`, builds additionally run one-at-a-time even across worktrees (for build trees that corrupt under concurrency). Off by default.
+
+---
+
+## Safety harness (inherited from pan-conductor — mandatory)
+
+Every cap the conductor enforces applies to the campaign, scaled up:
+
+| Cap | Mechanism |
+|-----|-----------|
+| Nesting depth 2 | Mission Control spawns squad agents; squad agents MUST NOT spawn further |
+| Spawn / budget ceiling | per-cycle spawn cap + `--total-budget`; stop when the next spawn exceeds remaining budget |
+| Abort kill-switch | `.planning/orchestration/abort` present → stop immediately, preserve state |
+| Protected main | no direct push; merge is an `always-ask` human gate |
+| Worktree isolation | branch-per-agent — parallel builders cannot collide |
+| Rollback never rewrite | recovery = `git revert` / previous tag; never force-push |
+
+---
+
+## Arguments
+
+```
+/pan:army "<goal>" [--source scan|backlog] [--max-cycles N] [--total-budget N]
+          [--squads a,b,c] [--no-build-worktrees] [--push] [--clean-seal]
+          [--schedule <cadence>] [--daily-budget N]
+          [--dry-run] [--continue] [--stop] [--status]
+```
+
+| Flag | Default | Effect |
+|------|---------|--------|
+| `--source` | `backlog` | Work selection (delegates to focus-auto): `backlog` = ranked roadmap/requirements items; `scan` = category code-scan. |
+| `--max-cycles` | 5 | Mission items landed before stopping. |
+| `--total-budget` | 300 | Cumulative point ceiling. |
+| `--squads` | all | Restrict to a subset, e.g. `--squads architecture,build,quality`. |
+| `--no-build-worktrees` | off | Build in the main tree instead of branch-per-agent worktrees (small/serial projects). |
+| `--push` | off | Push approved merges to origin (still human-gated). |
+| `--clean-seal` | off | One clean build + full verification after the last item (commands from config). |
+| `--schedule` | off | Arm a self-resuming campaign at this cadence (`hourly`/`daily`/`weekly`/`Nh`/`Nd`) instead of running once — writes the schedule descriptor (ADR-0034). Pair with `--daily-budget`. |
+| `--daily-budget` | 300 | Per-day point ceiling for a scheduled campaign; the day's run stops when reached, resumes next day. |
+| `--dry-run` | off | Plan + squad delegation preview only; STOP. |
+| `--continue` / `--stop` / `--status` | — | Resume / halt / report from `.planning/orchestration/` + focus-auto state. |
+
+---
+
+## Pipeline — the six-phase loop
+
+```
+/pan:army
+  Phase 0  MUSTER   — squad list + roster validate · cache prime · baseline · loop-state · abort-file clear
+  Phase 1  PLAN     — Mission Control (Opus, extended thinking) decomposes the goal into dependency-ordered missions
+  Phase 2  DELEGATE — pick the next item (focus-auto --source) · route to the owning squad over the Agent toolset
+  Phase 3  EXECUTE  — Build squad: one army/<task> worktree per agent (parallel); Architecture/Quality research in parallel (read-only)
+  Phase 4  REVIEW   — Quality squad on the built tree: reviewer + hardener + meta → verdict ladder; a block is a hard gate
+  Phase 5  INTEGRATE— Release squad: prepare squash-merge → CI/verification → ALWAYS-ASK human approval → tag → deploy hand-off
+  Phase 6  LEARN    — summaries return to Mission Control; retro/learn writes patterns to memory (this is "Dreaming")
+  → loop to Phase 2 until a stop condition; --clean-seal once at the end
+```
+
+### Phase 0 — Muster (once)
+1. **Onboarding gate (existing projects).** Run `pan-tools init new-project` to detect state. If `is_brownfield` (existing code) and `needs_codebase_map` (no `.planning/codebase/`), the army cannot plan blind — STOP and route through onboarding first: `/pan:map-codebase` (Architecture squad's `pan-document_code` maps the existing system into `.planning/codebase/`), then `/pan:new-project` to build `roadmap.md` + `requirements.md` *against the existing system*. Re-run `/pan:army` once a backlog exists. If a codebase map + roadmap already exist, continue.
+2. `pan-tools squad list` and validate the roster is healthy.
+3. Prime the cache; capture baseline (`git status` clean of project source; tests green or STOP). On a brownfield repo, the baseline is the current `main` — every `army/<task>` branch forks from it, so the existing code is never edited in place.
+4. Ensure `.planning/orchestration/` exists; clear any stale `abort` file; init loop-state.
+5. `--dry-run` → print the plan + per-squad delegation and STOP.
+
+### Phase 1 — Plan (Mission Control)
+Spawn the conductor in campaign mode (it plans, it does not code). It decomposes the goal into ordered, dependency-aware missions and assigns each to a squad.
+
+### Phase 2–3 — Delegate + Execute
+- Select the next item via `focus-auto --source {source}`.
+- Architecture squad (read-only, parallel) produces the contract for a design-heavy item.
+- Build squad: for each independent task, `pan-tools worktree create "<task>"` → spawn one `pan-executor` per worktree (parallel, isolated). Honor the spawn/budget caps before every spawn.
+
+### Phase 4 — Review (Quality)
+Spawn the Quality squad on the built tree (parallel, read-only). Merge findings into one verdict (`/pan:review-deep` if available). `block` / `review_required` → fix serially, then re-review. Never integrate red.
+
+### Phase 5 — Integrate (Release, human-gated)
+Spawn `pan-release`. It prepares the squash-merge, runs the configured `verification`, and surfaces an **always-ask** approval request. A human approves the merge to the protected branch; release then tags and records the rollback target. `--push` pushes the approved result.
+
+### Phase 6 — Learn (Dreaming)
+Squad summaries return to Mission Control. Run `/pan:retro --write-memory` (and `/pan:learn` if traces exist) so recurring patterns persist into agent memory for the next mission. Strike the landed item; update loop-state. For a scheduled campaign, also `pan-tools campaign record-run --items <n> --points <p>` so the next-due time and the day's spend advance.
+
+---
+
+## Scheduled, self-resuming campaigns (ADR-0034)
+
+PAN is not a daemon — it cannot wake itself while the session is closed. `--schedule` arms a campaign and lets an external trigger drive it; the human merge gate is never relaxed.
+
+- **Arm:** `/pan:army "<goal>" --schedule daily --daily-budget 200` writes `.planning/orchestration/schedule.json` (cadence, daily budget, next-due) instead of running once.
+- **The trigger (you wire one):** a host scheduler (Claude Code routines / cron / scheduled-tasks) or a `/loop` runs `pan-tools campaign due` and, when it reports due, invokes `/pan:army --continue`. On next session open, a due campaign is surfaced as a nudge.
+- **Resume (`--continue`):** read the schedule + `.planning/orchestration/` + focus-auto state. If `campaign due` is true and the day's `--daily-budget` isn't spent, run the next mission(s), then `campaign record-run` (advances next-due, accrues the day's spend). If not due or budget-spent, report next-due and STOP.
+- **Bounded spend:** the per-day budget caps each day's run; the per-run `--total-budget` and the conductor caps still bound each cycle. A scheduled campaign runs the backlog down to staged, reviewed, green PRs over days — and still waits for a human at every merge.
+
+Manage it: `pan-tools campaign status` (active/paused, spent today, next-due), `campaign schedule --pause` / `--resume` / `--disable`.
+
+---
+
+## Completion contract
+The campaign is complete when ANY holds: `--max-cycles` reached · `--total-budget` exhausted · backlog empty · abort file present · context < 25% · a mission cannot pass Quality and can't be cleanly reverted (HARD STOP — preserve state, report). Always run `--clean-seal` (unless omitted) after the last item.
+
+## NEVER DO
+- Let Mission Control write code, or let a squad agent spawn further agents (depth cap).
+- Run two builders in the same worktree, or merge to a protected branch without the human gate.
+- Force-push or rewrite history; recovery is revert / previous tag only.
+- Hardcode the squad roster — read it from `pan-tools squad list`.
+- Integrate a mission that hasn't passed Quality green.
+
+## ALWAYS DO
+- Plan on Opus, delegate over the Agent toolset, keep each squad's return a tight summary.
+- One worktree per Build agent; parallel research/verify; serial human-gated integrate.
+- Check the abort file + spawn/budget caps before every spawn.
+- Finish with the clean-build seal; write learnings back to memory.
+
+## Examples
+```
+/pan:army "ship the v1 reporting module" --source backlog --max-cycles 5
+/pan:army "harden auth across the app" --squads architecture,build,quality --clean-seal
+/pan:army "<goal>" --dry-run            # show the plan + squad delegation, no code
+/pan:army --status                      # campaign progress
+/pan:army --stop                        # graceful halt, state preserved
+```

package/commands/pan/dashboard.md

@@ -0,0 +1,25 @@
+---
+name: pan:dashboard
+group: Observability
+description: Alias for /pan:hud — generate the single-page HTML dashboard of the bot army and project
+argument-hint: "[--out <file>] [--open] [--stdout]"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<objective>
+`/pan:dashboard` is a discoverability alias for **`/pan:hud`** (ADR-0035). It generates the same single-page, self-contained HTML dashboard of the project and its bot army.
+
+Run it exactly like `/pan:hud`:
+
+```
+pan-tools hud [--out <file>] [--open] [--stdout]
+```
+
+See **`/pan:hud`** for the full panel list, flags, JSON result shape, and runtime compatibility. The two commands are interchangeable.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/hud.cjs
+</execution_context>

package/commands/pan/focus-auto.md

@@ -87,14 +87,16 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 ## Arguments
 
 ```
-/pan:focus-auto [--category CAT] [--mode MODE] [--budget N] [--max-cycles N]
-                [--total-budget N] [--continue] [--stop] [--status] [--dry-run]
-                [--deep-review]
+/pan:focus-auto [--source scan|backlog] [--category CAT] [--mode MODE] [--budget N]
+                [--max-cycles N] [--total-budget N] [--continue] [--stop] [--status]
+                [--dry-run] [--deep-review]
+                [--parallel-research] [--parallel-verify] [--clean-seal]
 ```
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--category` | null (all) | cleanup, tests, stability, features, docs, optimize, prompts, security, distill |
+| `--source` | `scan` | Work selection. `scan` = category-scoped code scan (below). `backlog` = rank actionable items from `roadmap.md` / `requirements.md` (ADR-0031). |
+| `--category` | null (all) | cleanup, tests, stability, features, docs, optimize, prompts, security, distill. Applies to `--source scan`. |
 | `--mode` | category-dependent | bugfix, balanced, features, full |
 | `--budget` | category-dependent | Points per cycle (5-100) |
 | `--max-cycles` | 10 | Maximum iterations (1-50) |
@@ -104,6 +106,9 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 | `--status` | — | Show current campaign progress |
 | `--dry-run` | — | Show plan without executing |
 | `--deep-review` | off | After every exec cycle, run inline OWASP security check on changed files. Verdict `block` or `review_required` stops the campaign (6th safety harness). Works with all categories. |
+| `--parallel-research` | off | Fan out the per-item *research* stage via the Workflow tool (read-only agents). No-op fallback to sequential where the host has no Workflow tool. (ADR-0031) |
+| `--parallel-verify` | off | Fan out the per-item *verify* stage via the Workflow tool (read-only). The implement/exec stage always stays a single agent. (ADR-0031) |
+| `--clean-seal` | off | After the loop's last item, run one clean build + full verification (commands from `config.json → build`/`verification`) to catch cross-item orphans. (ADR-0031) |
 
 ## Category Defaults
 
@@ -118,6 +123,29 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 | prompts | P0-P6 | balanced | 100 |
 | security | P0-P2 | bugfix | 40 |
 
+## Backlog source (`--source backlog`, ADR-0031)
+
+When `--source backlog` is set, work is selected from the **curated planning surface** instead of a code scan — for campaigns that work a human-prioritized roadmap rather than whatever grep finds.
+
+1. **Read the backlog once** at Phase 0: actionable items are unchecked rows in `roadmap.md` (phase/plan checkboxes) and unmet `requirements.md` REQ rows. Skip anything struck, completed, or marked blocked.
+2. **Score from the CURRENT document — never a hardcoded ID list.** For each item, derive `RS = (UserValue + TimeCriticality + RiskReduction) / Effort` (1–5 each; Effort from the row's size tag). Sort by wave/priority ascending → RS descending → effort ascending. This re-derives the order from whatever the roadmap says today, so it never goes stale.
+3. **Pop the top survivor each cycle**; re-rank only if a landing changed a dependency. The same budget/cycle/context stops and safety harness apply unchanged.
+4. The backlog ranker reads only PAN's planning files — it embeds **no** project-specific item IDs, test counts, or build commands. A project with no actionable backlog items is a clean stop (`scan returns zero items` equivalent).
+
+## Concurrency model (when `--parallel-research` / `--parallel-verify`, ADR-0031)
+
+The proven shape is **parallel read-only research → exactly ONE serial implement/exec → parallel read-only verify**:
+
+| Stage | Concurrency | Why |
+|-------|-------------|-----|
+| Research | Parallel (Workflow fan-out, read-only) when `--parallel-research` | Reads source/specs; mutates nothing. |
+| Implement / exec | **Single agent, always** | Mutates the tree; never fanned out. |
+| Verify | Parallel (Workflow fan-out, read-only) when `--parallel-verify` | Runs against the already-built tree; mutates nothing. |
+
+**Serial-build constraint:** if `.planning/config.json → concurrency.serial_build` is `true`, the runner additionally guarantees at most one build process at any instant across the whole loop (for projects whose build trees corrupt under concurrency). This is **off by default** — most projects build in parallel safely. PAN does not assume it.
+
+**Commit-quality gates** (advisory, always on): a *staging-miss guard* (no exec-touched file left unstaged) and an *orphan audit* (HEAD must not reference a symbol defined only in an uncommitted file). With `--clean-seal`, a single clean build + full verification runs after the last item to catch cross-item orphans the per-cycle incremental commits hid.
+
 ## Pipeline
 
 ### Phase 0: Initialization

package/commands/pan/hud.md

@@ -0,0 +1,91 @@
+---
+name: pan:hud
+group: Observability
+description: Generate a single-page, self-contained HTML dashboard of the bot army and the project's current state
+argument-hint: "[--out <file>] [--open] [--stdout]"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<objective>
+Render one **self-contained HTML page** — no server, no network, no external CSS or JS — that shows the whole picture of a PAN project and its bot army in their current state.
+
+It is a *view*, not a new source of truth: every panel aggregates state PAN already tracks (`state.md`, the roadmap/phases on disk, the squad registry, the campaign schedule, army worktrees, the cost ledger, `requirements.md`, verification artifacts, and git history). The command writes only the rendered file, so it can never corrupt planning data.
+
+Default output is `.planning/hud.html`. Open it in any browser. Re-run any time for a fresh snapshot.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/hud.cjs
+</execution_context>
+
+<usage>
+
+```
+pan-tools hud [--out <file>] [--open] [--stdout]
+```
+
+**Flags:**
+- `--out <file>` — write to a custom path instead of `.planning/hud.html` (relative paths resolve against the project root).
+- `--open` — best-effort: launch the file in the default browser after writing (cross-platform; silently no-ops if no opener is available).
+- `--stdout` — print the HTML to stdout instead of writing a file (for piping into another tool or a web response).
+
+**JSON result shape** (default, when not `--stdout`):
+```json
+{
+  "path": ".planning/hud.html",
+  "bytes": 18234,
+  "army_active": true,
+  "sections": ["mission", "command-stack", "campaign", "safety-harness", "worktrees", "roadmap", "telemetry", "requirements-quality", "activity"],
+  "opened": false
+}
+```
+
+</usage>
+
+<panels>
+
+The dashboard is composed of up to ten panels. Panels render only when they have data — a plain (non-army) project still gets a complete, useful page.
+
+| Panel | What it shows | Source |
+|-------|---------------|--------|
+| **Mission banner** | Project, core value, status, version/milestone + metric cards (progress, phase, requirements, spend) | `package.json`, `project.md`, `state.md`, phase scan, cost ledger |
+| **Command stack** *(army)* | Mission Control over the four squads with per-squad agent drill-down (active / idle, calls, tokens) | squad registry + cost ledger |
+| **Campaign** *(army)* | Cadence, next-due, daily-budget bar, last run, run history | `schedule.json` |
+| **Safety harness** *(army)* | Merge gate, abort switch (pause), active worktrees, daily budget, concurrency | config + pause file + worktrees + schedule |
+| **Worktrees** *(army)* | Active `army/*` branches and their paths | `git worktree list` |
+| **Roadmap** | Every phase with status + completion | phases on disk |
+| **Telemetry** | Total spend, tokens, cache-hit rate, by-squad breakdown | cost ledger |
+| **Requirements & quality** | Requirements done/open + last verification artifacts | `requirements.md`, phase `*-verification.md` / `*-uat.md` |
+| **Recent activity** | Last commits (the army's committed output) | `git log` |
+
+*(army)* panels appear only when a campaign is scheduled or army worktrees exist — graceful degradation per ADR-0035.
+
+</panels>
+
+<workflow>
+
+**Glance check:** run `/pan:hud --open` to see the project and army at a glance in your browser.
+
+**Share status:** the file is fully self-contained — send `.planning/hud.html` to anyone; it opens with no dependencies.
+
+**During a campaign:** re-run after each cycle to watch squads, budget, worktrees, and committed output evolve. Pair with `/pan:army` and `pan-tools campaign status`.
+
+**Pipe it:** `pan-tools hud --stdout > dashboard.html` or feed the JSON result into another tool.
+
+</workflow>
+
+<runtime_compatibility>
+
+| Runtime | Support |
+|---------|---------|
+| Claude Code | Full |
+| OpenCode | Full |
+| Gemini | Full |
+| Codex | Full |
+| Copilot CLI | Full |
+
+The aggregator and renderer are pure, zero-dependency, runtime-agnostic CommonJS — the dashboard is identical across all five runtimes. `--open` depends on the host OS having a default browser opener.
+
+</runtime_compatibility>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "A lightweight workflow automation and context engineering system for Claude Code, OpenCode, Gemini CLI, Codex, and Copilot CLI.",
   "bin": {
     "pan-wizard": "bin/install.js"

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

@@ -0,0 +1,198 @@
+/**
+ * Campaign — scheduled, self-resuming bot-army campaigns (ADR-0034).
+ *
+ * PAN is not a daemon: this module owns the schedule DESCRIPTOR and the
+ * decision of whether a run is DUE. An external trigger (host scheduler,
+ * cron, /loop, or a human) polls `campaign due` and fires `/pan:army
+ * --continue`. The always-ask human merge gate is never affected by
+ * scheduling. Pure + synchronous; `now` is injected for testability.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { output, error } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+
+const ORCH_DIR = 'orchestration';
+const SCHEDULE_FILE = 'schedule.json';
+const HISTORY_CAP = 50;
+const DAY_MS = 86400000;
+
+function schedulePath(cwd) {
+  return path.join(cwd, PLANNING_DIR, ORCH_DIR, SCHEDULE_FILE);
+}
+
+/**
+ * Parse a cadence string into milliseconds.
+ * @param {string} c - 'hourly' | 'daily' | 'weekly' | 'Nh' | 'Nd'
+ * @returns {number|null} ms, or null if unparseable
+ */
+function parseCadence(c) {
+  if (!c || typeof c !== 'string') return null;
+  const s = c.trim().toLowerCase();
+  if (s === 'hourly') return 3600000;
+  if (s === 'daily') return DAY_MS;
+  if (s === 'weekly') return 7 * DAY_MS;
+  const m = s.match(/^(\d+)\s*([hd])$/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  if (n <= 0) return null;
+  return m[2] === 'h' ? n * 3600000 : n * DAY_MS;
+}
+
+/** @returns {object|null} the schedule descriptor, or null if none/unreadable */
+function readSchedule(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(schedulePath(cwd), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeScheduleFile(cwd, schedule) {
+  const p = schedulePath(cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(schedule, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Arm or update a campaign schedule.
+ * @param {string} cwd
+ * @param {object} opts - { goal, source, cadence, daily_budget, enabled, paused }
+ * @param {Date} now
+ * @returns {object|{error}} the written descriptor
+ */
+function writeSchedule(cwd, opts, now) {
+  const cadence = opts.cadence || 'daily';
+  if (parseCadence(cadence) === null) {
+    return { error: `Invalid cadence "${cadence}". Use hourly | daily | weekly | Nh | Nd.` };
+  }
+  const at = now || new Date();
+  const existing = readSchedule(cwd) || {};
+  const schedule = {
+    goal: opts.goal ?? existing.goal ?? null,
+    source: opts.source ?? existing.source ?? 'backlog',
+    cadence,
+    daily_budget: opts.daily_budget != null ? Number(opts.daily_budget) : (existing.daily_budget ?? 300),
+    enabled: opts.enabled != null ? Boolean(opts.enabled) : (existing.enabled ?? true),
+    paused: opts.paused != null ? Boolean(opts.paused) : (existing.paused ?? false),
+    next_due: existing.next_due ?? at.toISOString(),
+    last_run: existing.last_run ?? null,
+    history: Array.isArray(existing.history) ? existing.history : [],
+  };
+  writeScheduleFile(cwd, schedule);
+  return schedule;
+}
+
+function sameUtcDay(a, b) {
+  return a.getUTCFullYear() === b.getUTCFullYear()
+    && a.getUTCMonth() === b.getUTCMonth()
+    && a.getUTCDate() === b.getUTCDate();
+}
+
+function spentToday(schedule, now) {
+  return (schedule.history || [])
+    .filter(h => { const t = new Date(h.ts); return !isNaN(t) && sameUtcDay(t, now); })
+    .reduce((sum, h) => sum + (Number(h.points_used) || 0), 0);
+}
+
+/**
+ * Is a scheduled run due right now?
+ * @returns {{due: boolean, reason: string, next_due: string|null, spent_today: number}}
+ */
+function isRunDue(schedule, now) {
+  const at = now || new Date();
+  if (!schedule) return { due: false, reason: 'no_schedule', next_due: null, spent_today: 0 };
+  const spent = spentToday(schedule, at);
+  if (!schedule.enabled) return { due: false, reason: 'disabled', next_due: schedule.next_due, spent_today: spent };
+  if (schedule.paused) return { due: false, reason: 'paused', next_due: schedule.next_due, spent_today: spent };
+  if (schedule.daily_budget != null && spent >= schedule.daily_budget) {
+    return { due: false, reason: 'budget_exhausted_today', next_due: schedule.next_due, spent_today: spent };
+  }
+  const due = new Date(schedule.next_due);
+  if (isNaN(due) || at.getTime() >= due.getTime()) {
+    return { due: true, reason: 'due', next_due: schedule.next_due, spent_today: spent };
+  }
+  return { due: false, reason: 'not_yet', next_due: schedule.next_due, spent_today: spent };
+}
+
+/**
+ * Record a completed campaign run and advance next_due.
+ * @returns {object|{error}} updated descriptor
+ */
+function recordRun(cwd, run, now) {
+  const schedule = readSchedule(cwd);
+  if (!schedule) return { error: 'No campaign schedule to record against' };
+  const at = now || new Date();
+  const ts = run?.ts || at.toISOString();
+  schedule.history = (schedule.history || []).concat([{
+    ts,
+    items_landed: Number(run?.items_landed) || 0,
+    points_used: Number(run?.points_used) || 0,
+  }]).slice(-HISTORY_CAP);
+  schedule.last_run = ts;
+  const step = parseCadence(schedule.cadence) || DAY_MS;
+  schedule.next_due = new Date(at.getTime() + step).toISOString();
+  writeScheduleFile(cwd, schedule);
+  return schedule;
+}
+
+/**
+ * Is the retro/learn ("dream") step due? Default: once per calendar day that
+ * had activity — curate memory between missions, not after every cycle.
+ */
+function isDreamDue(schedule, now) {
+  if (!schedule || !schedule.enabled || schedule.paused) return false;
+  const at = now || new Date();
+  if (!schedule.last_run) return false;
+  const last = new Date(schedule.last_run);
+  if (isNaN(last)) return false;
+  return !sameUtcDay(last, at) || (schedule.history || []).length > 0;
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+function cmdCampaignSchedule(cwd, opts, raw) {
+  const r = writeSchedule(cwd, opts, opts.now);
+  if (r.error) return error(r.error);
+  const human = `Campaign scheduled: ${r.cadence} · budget ${r.daily_budget}/day · next ${r.next_due}${r.goal ? ` · goal: ${r.goal}` : ''}`;
+  output(r, raw, human);
+}
+
+function cmdCampaignStatus(cwd, raw) {
+  const schedule = readSchedule(cwd);
+  if (!schedule) return output({ scheduled: false }, raw, 'No campaign scheduled');
+  const at = new Date();
+  const d = isRunDue(schedule, at);
+  const result = {
+    scheduled: true, enabled: schedule.enabled, paused: schedule.paused,
+    cadence: schedule.cadence, daily_budget: schedule.daily_budget,
+    next_due: schedule.next_due, last_run: schedule.last_run,
+    spent_today: d.spent_today, runs: (schedule.history || []).length,
+    due: d.due, reason: d.reason,
+  };
+  const human = `Campaign ${schedule.enabled ? (schedule.paused ? 'paused' : 'active') : 'disabled'} · ${schedule.cadence} · spent ${d.spent_today}/${schedule.daily_budget} today · next ${schedule.next_due} · ${d.due ? 'DUE NOW' : d.reason}`;
+  output(result, raw, human);
+}
+
+function cmdCampaignDue(cwd, raw) {
+  const schedule = readSchedule(cwd);
+  const d = isRunDue(schedule, new Date());
+  // exit-coded so a host scheduler can gate: 0 = due, 1 = not due
+  output({ due: d.due, reason: d.reason, next_due: d.next_due }, raw, d.due ? 'due' : `not due (${d.reason})`);
+}
+
+module.exports = {
+  parseCadence,
+  readSchedule,
+  writeSchedule,
+  isRunDue,
+  recordRun,
+  isDreamDue,
+  cmdCampaignSchedule,
+  cmdCampaignStatus,
+  cmdCampaignDue,
+  SCHEDULE_FILE,
+};

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

@@ -126,6 +126,13 @@ const AUTO_RUN_FILE = 'auto-run.json';
 /** Focus auto-runner categories */
 const FOCUS_CATEGORIES = ['cleanup', 'tests', 'stability', 'features', 'docs', 'optimize', 'prompts', 'security', 'distill'];
 
+/**
+ * Focus auto-runner work sources (ADR-0031):
+ *  - scan:    category-scoped code scan (default; today's behavior)
+ *  - backlog: rank actionable items from roadmap.md / requirements.md
+ */
+const FOCUS_SOURCES = ['scan', 'backlog'];
+
 /** Category → priority index range (indices into PRIORITY_LEVELS) */
 const CATEGORY_PRIORITY_RANGE = {
   cleanup:   { min: 3, max: 5 },  // P3-P5
@@ -681,6 +688,7 @@ module.exports = {
   FOCUS_DIR,
   AUTO_RUN_FILE,
   FOCUS_CATEGORIES,
+  FOCUS_SOURCES,
   DOC_SYNC_FILES,
   COMMAND_RENAME_MAP,
   CATEGORY_PRIORITY_RANGE,

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

@@ -73,6 +73,8 @@ const MODEL_PROFILES = {
   'pan-distiller':            { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
   // v3.7.0 self-improvement loop — observation-only watchdog
   'pan-experiment-runner':    { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  // ADR-0033 bot-army — Release squad
+  'pan-release':              { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
 };
 
 // ─── Effort Profiles (2026-06, adaptive-thinking era) ───────────────────────
@@ -104,6 +106,7 @@ const AGENT_BASE_EFFORT = {
   'pan-previewer':            'high',
   'pan-experiment-runner':    'high',
   'pan-optimizer':            'high',
+  'pan-release':              'high',
   // Research/synthesis/review — moderate depth
   'pan-phase-researcher':     'medium',
   'pan-project-researcher':   'medium',
@@ -279,6 +282,11 @@ function loadConfig(cwd) {
       model_overrides: parsed.model_overrides || {},
       effort_overrides: parsed.effort_overrides || {},
       routing: parsed.routing || { strategy: 'static', provider: 'auto' },
+      // ADR-0031: project build/verification commands. null = not configured
+      // (focus-auto --clean-seal then asks or skips rather than guessing).
+      build: parsed.build || null,
+      verification: parsed.verification || null,
+      concurrency: parsed.concurrency || { serial_build: false },
     };
   } catch { // Config missing or malformed — use defaults
     return {
@@ -290,6 +298,9 @@ function loadConfig(cwd) {
       model_overrides: {},
       effort_overrides: {},
       routing: { strategy: 'static', provider: 'auto' },
+      build: null,
+      verification: null,
+      concurrency: { serial_build: false },
     };
   }
 }

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

@@ -14,7 +14,7 @@ const {
   FOCUS_MODES, FOCUS_TIERS, FOCUS_DIR,
   BUDGET_LIMIT_BUGFIX, BUDGET_LIMIT_FULL, STABILITY_RATIO, FEATURE_RATIO,
   DIMINISHING_RETURNS_THRESHOLD,
-  AUTO_RUN_FILE, FOCUS_CATEGORIES, CATEGORY_PRIORITY_RANGE, CATEGORY_DEFAULTS,
+  AUTO_RUN_FILE, FOCUS_CATEGORIES, FOCUS_SOURCES, CATEGORY_PRIORITY_RANGE, CATEGORY_DEFAULTS,
   DEFAULT_MAX_CYCLES, DEFAULT_TOTAL_BUDGET,
   BUDGET_MIN, BUDGET_MAX, MAX_CYCLES_MIN, MAX_CYCLES_MAX, TOTAL_BUDGET_MIN, TOTAL_BUDGET_MAX,
   AUTORUN_STATUSES, DOC_SYNC_FILES, COMMAND_RENAME_MAP,
@@ -829,6 +829,14 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
     return error(`Category must be one of: ${FOCUS_CATEGORIES.join(', ')}`);
   }
 
+  // ADR-0031: work source — 'scan' (category code-scan, default) or 'backlog'
+  // (rank actionable roadmap.md / requirements.md items). Category applies to
+  // scan mode; backlog mode ranks the whole actionable backlog.
+  const source = getVal('--source', 'scan');
+  if (!FOCUS_SOURCES.includes(source)) {
+    return error(`Source must be one of: ${FOCUS_SOURCES.join(', ')}`);
+  }
+
   const existing = readAutoRun(cwd);
   if (existing && (existing.status === AUTORUN_STATUSES.IN_PROGRESS || existing.status === AUTORUN_STATUSES.INITIALIZED)) {
     return error('Auto-run already in progress. Use --stop to end it, or --continue to resume.');
@@ -848,8 +856,12 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
   const runData = {
     run_id: generateRunId(cwd),
     status: AUTORUN_STATUSES.INITIALIZED,
+    source: source,
     category: category,
     mode: mode,
+    parallel_research: hasFlag('--parallel-research'),
+    parallel_verify: hasFlag('--parallel-verify'),
+    clean_seal: hasFlag('--clean-seal'),
     budget_per_cycle: budget,
     max_cycles: maxCycles,
     total_budget: totalBudget,