wize-dev-kit 0.4.1 → 0.6.0

package/src/method-skills/4-implementation/wize-sprint-planning/workflow.md

@@ -8,92 +8,79 @@ status: ready
 
 # Sprint Planning
 
-**Goal.** Pick what enters this sprint. Capacity-honest, priority-honest, risk-honest. The sprint is a commitment about a small slice of the future, not a wish list.
+**Goal.** Pick what enters this sprint. Capacity-honest, priority-honest, risk-honest.
 
-Maria Hill chairs. Tony advises on slicing. Hawkeye flags risk on stories. Shuri commits to the load.
+Maria Hill chairs. Tony advises on slicing. Hawkeye flags risk. Shuri commits to the load.
 
 ## Inputs
 
 - Story backlog: `.wize/solutioning/stories/`
-- Velocity history: `.wize/implementation/sprint-status.md` (previous sprints) — when present.
+- Previous sprint state: `.wize/implementation/sprint-status.yaml`
 - `.wize/implementation/tea/risk-profile.md`
-- Open `tea-gate` outcomes from last sprint.
-- Team availability for the next interval (vacations, on-call rotation, planned meetings).
+- Team availability for the next interval.
 
 ## Output
 
-- New sprint block appended to `.wize/implementation/sprint-status.md`.
-- Story files updated `priority: 1` for chosen stories.
-
-## Rules
-
-1. **Capacity = min(history velocity, declared availability).** Not the average of optimistic estimates.
-2. **High-risk stories** (linked to `R-x` HIGH in risk profile) get TEA design done in the planning meeting, not at story start.
-3. **Stretch goals** are explicit, named, not silent. If a stretch ships, great. If not, the sprint isn't a failure.
-4. **Don't carry over without reason.** A carried-over story gets a one-line "why" in the sprint log.
+- Updated `.wize/implementation/sprint-status.yaml`.
+- Story files updated with `priority: 1` for chosen stories.
 
 ## Steps
 
-### 1. Look back (3 min)
-
-Last sprint: what shipped, what slipped, what surprised. Don't relitigate; observe.
-
-### 2. Refresh capacity
-
-- Person-days available this sprint = sum(working days) × (1 - meetings load).
-- Subtract on-call burden, oncall handoff time, planned reviews.
-
-### 3. Pull stories (in priority order)
-
-Default selection algorithm:
-- Always pull continuation stories (in-flight from last sprint) first.
-- Then highest-priority stories that fit the capacity.
-- Then risk-driven: high-risk stories (R-HIGH) preferred over more low-risk ones when capacity is tight.
-
-For each pulled story, confirm INVEST still holds; re-slice if needed.
-
-### 4. Reserve buffer
-
-10–15% buffer for unknowns (bug fixes, support escalations). Don't fill the sprint to 100% — you'll always pay.
-
-### 5. Walk the gate plan
-
-For each story pulled, what's the TEA gate cadence? Most stories: design at start, trace + review + gate at end. High-risk: include NFR re-check at epic close.
-
-### 6. Commit (verbal + written)
-
-Each engineer reads back the stories they're owning. Hill writes them into the sprint block. Sprint starts.
-
-## Sprint block template (appended to `sprint-status.md`)
-
-```markdown
-## Sprint 7 — 2026-06-12 → 2026-06-25
-
-**Capacity:** 24 person-days (3 engineers × 10 days × 0.8 utilization)
-**Carry-over:** E01-S05 (90% done; Shuri); E03-S01 (TEA review pending)
-**Pulled:**
-- E01-S06 — M — owner: Shuri — gate cadence: design+gate
-- E02-S02 — L — owner: Shuri — gate cadence: design+trace+review+gate (R-3)
-- E03-S02 — M — owner: Aaliyah — gate cadence: design+trace+review+gate (R-1)
-- E04-S01 — S — owner: Shuri — gate cadence: smoke (quick-dev pattern)
-- E02-S03 — S — stretch
-
-**Out (deferred to Sprint 8):**
-- E03-S03 — reason: depends on E03-S02 ADR
-- E05-S01 — reason: out of NFR-cost budget; revisit
-
-**Risks flagged:**
-- E02-S02 — auth refresh story; high-risk; TEA design done at planning.
+1. **Look back** — what shipped, what slipped, what surprised.
+2. **Refresh capacity** — person-days × utilization − overhead.
+3. **Pull stories** — continuation first, then priority, then risk.
+4. **Reserve 10–15% buffer** for unknowns.
+5. **Walk the gate plan** — design/trace/review/gate per story.
+6. **Commit** — verbal + written into YAML.
+
+## Status state machine
+
+- Epic: `backlog` → `in-progress` → `done`
+- Story: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
+- Retrospective: `optional` ↔ `done`
+
+## Sprint block template
+
+```yaml
+# generated: YYYY-MM-DD
+# last_updated: YYYY-MM-DD
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: file-system
+# story_location: .wize/solutioning/stories
+
+generated: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+project: {project_name}
+project_key: {project_key}
+tracking_system: file-system
+story_location: .wize/solutioning/stories
+
+development_status:
+  epic-1: backlog
+  1-1-story-one: backlog
+  1-2-story-two: backlog
+  epic-1-retrospective: optional
 ```
 
-## Anti-patterns Hill rejects
+## Anti-patterns
 
-- **"Optimistic" velocity that ignores history.** Use observed velocity.
-- **Stories pulled without owners.** Don't aspire; commit.
-- **Stretch goals so big they're really plan.** Stretch = optional, not "we hope we can."
-- **Pulling a story when its dependency hasn't shipped.** It will sit blocked.
-- **No buffer.** Real sprints have surprises.
+- Optimistic velocity.
+- Stories without owners.
+- Stretch goals that are really plan.
+- Pulling blocked dependencies.
+- Zero buffer.
 
 ## Hand-off
 
-> Sprint 7 committed at `.wize/implementation/sprint-status.md`. Shuri owns most; Aaliyah picks up E03-S02. Hawkeye, NFR gate due on E03 at sprint end. Wizer, retro on the 25th.
+> Sprint committed at `.wize/implementation/sprint-status.yaml`. Stories in `ready-for-dev` are now eligible for the dev loop.
+>
+> **Recommended next loop:**
+>
+> ```
+> /loop /wize-dev-story
+> ```
+>
+> `/loop /wize-dev-story` drives one story at a time: TDD red-green-refactor, AC IDs in commits, `tea-design.md` contract, knowledge update on the 5 baseline axes, and a clean gate at the end. `/loop` keeps it going across the sprint's `ready-for-dev` queue until the user pauses.
+>
+> Next: `/wize-sprint-status` (Maria Hill) to acompanhar o progresso.

package/src/method-skills/4-implementation/wize-sprint-status/workflow.md

@@ -8,103 +8,50 @@ status: ready
 
 # Sprint Status
 
-**Goal.** Keep a snapshot of in-flight work that the team and stakeholders can read in 60 seconds. Sprint status is read by everyone, written by Hill (or delegated to Wizer); the source of truth is the file, not Slack.
-
-Update **daily** during a sprint, or after any state change (story moves, blocker appears, gate fails).
+**Goal.** Read `.wize/implementation/sprint-status.yaml` in 60 seconds and say what to do next.
 
 ## Inputs
 
-- `.wize/solutioning/stories/` (current statuses)
-- `.wize/implementation/tea/{epic}/{story}/gate.md` (gate outcomes)
-- The team (verbal stand-up or async update)
+- `.wize/implementation/sprint-status.yaml`
+- `.wize/implementation/tea/{epic}/{story}/gate.md`
 
 ## Output
 
-- Updated entry in `.wize/implementation/sprint-status.md`.
+- Updated sprint-status.yaml (if statuses changed).
+- One recommended next workflow.
 
 ## Steps
 
-### 1. Per story, name a status
-
-| Status | Meaning |
-|---|---|
-| `pulled` | Committed for this sprint, not started yet |
-| `in-progress` | Engineer actively working it (or paused < 1 day) |
-| `paused` | Started, paused > 1 day, reason listed |
-| `blocked` | Cannot proceed; depends on a named external resolution |
-| `in-review` | PR open; Hawkeye running design → trace → review |
-| `gate-PASS` / `gate-CONCERNS` / `gate-FAIL` | TEA gate outcome |
-| `shipped` | Merged to main + deployed (when applicable) |
-
-### 2. Blockers up front
-
-Blockers always appear in the top section. Each gets:
-- Owner (the person who can unblock it).
-- Specific ask (the action they should take).
-- Deadline.
-
-If a blocker sits longer than 2 days, Hill escalates. Stalled blockers are how sprints fail silently.
-
-### 3. Trend
-
-Daily, write a one-line trend: *"On track."* / *"At risk for E03-S02 due to vendor outage."* / *"Slipping; will defer E04-S01 to next sprint."*
-
-### 4. Capture decisions
-
-If something material was decided during the sprint that affects the plan (story sliced, scope dropped, ADR opened), append a one-line entry.
-
-## File template
+1. **Load YAML.** Parse `development_status`.
+2. **Classify** each key: epic, story, retrospective.
+3. **Count** statuses.
+4. **Detect risks:**
+   - Story `in-progress` older than 2 days with no update.
+   - Blocked story without owner/deadline.
+   - Epic `in-progress` with no stories.
+5. **Recommend next step** (in priority order):
+   1. Story `in-progress` → `/wize-dev-story`
+   2. Story `review` → `/wize-tea-review`
+   3. Story `ready-for-dev` → `/wize-dev-story`
+   4. Story `backlog` → `/wize-create-story`
+   5. Retrospective `optional` → `/wize-retrospective`
+   6. All done → congratulate team.
+
+## Summary output
 
 ```markdown
-# Sprint status
+## Sprint Status
 
-## Sprint 7 — 2026-06-12 → 2026-06-25
+- Project: {project} ({project_key})
+- Tracking: {tracking_system}
+- Status file: .wize/implementation/sprint-status.yaml
 
-### Day 4 (2026-06-15)
-**Trend:** On track.
+**Stories:** backlog {n} | ready-for-dev {n} | in-progress {n} | review {n} | done {n}
+**Epics:** backlog {n} | in-progress {n} | done {n}
 
-**Blockers:**
-- (none)
-
-**Stories:**
-- E01-S05 — gate-PASS — shipped (carry-over from S6).
-- E01-S06 — in-progress — Shuri.
-- E02-S02 — in-review — PR #418; Hawkeye doing trace.
-- E03-S02 — in-progress — Aaliyah.
-- E04-S01 — pulled — Shuri starts after E01-S06.
-- E02-S03 (stretch) — pulled — Aaliyah picks up if capacity allows.
-
-**Decisions:**
-- E03-S03 sliced into two stories (E03-S03a, E03-S03b) — ADR-009 incoming.
-
-### Day 5 (2026-06-16)
-**Trend:** At risk on E02-S02 (vendor sandbox down; Hawkeye unblocked at 14:00).
-**Blockers:** Resolved.
-**Stories:** (changes from Day 4)
-- E02-S02 — gate-PASS at 16:30; merged.
-- E01-S06 — in-review — PR #419.
-
-## Sprint 6 — 2026-05-29 → 2026-06-11
-{{archived}}
+**Next:** /{next_workflow} ({next_story_id})
 ```
 
-## Daily cadence (lean)
-
-A daily standup, when present, is 5 minutes max:
-
-- "What did I ship since last time?"
-- "What am I shipping next?"
-- "Anything blocking me?"
-
-Hill updates `sprint-status.md` immediately after; Wizer reads it before any other agent's session that day.
-
-## Anti-patterns Hill rejects
-
-- "Status: in progress" for 4 days with no further detail. Either it really is, in which case slice progress, or it's stuck.
-- Blockers without an owner or a deadline.
-- Sprint goals that drift silently (added stories without removing others).
-- Stale entries in the file. Update daily or delegate the update.
-
 ## Hand-off
 
-> `sprint-status.md` updated. Day 5 trend: at-risk-mitigated. Wizer, if asked about state, the file is the answer. Pepper, brief stays valid; no scope move triggered.
+> Status updated. Run the recommended workflow or call `/wize-sprint-planning` to reprioritize.

package/src/orchestrator-skills/wize-onboarding/workflow.md

@@ -2,27 +2,89 @@
 code: wize-onboarding
 name: Onboarding
 owner: wize-orchestrator   # Wizer
-status: stub
+status: ready
 ---
 
 # Onboarding
 
-**Goal.** Post-install triage. Decide greenfield vs brownfield, profile(s), objective, then delegate.
+**Goal.** First-contact triage after `npx wize-dev-kit install`. Decide greenfield vs brownfield, profile, objective, and route to the right persona. Always ask who the user is so the rest of the session feels personal.
+
+Wizer drives. Each branch ends by handing off to a specific workflow with explicit handoff copy.
 
 ## Inputs
-- `.wize/config/project.toml` (just-created)
-- Repo state (git log, presence of `src/`, `package.json` etc.)
+
+- `.wize/config/project.toml` (always present after install)
+- `.wize/config/user.toml` (per-developer)
+- `.wize/implementation/sprint-status.yaml` (when an active sprint exists)
+- `.wize/planning/brief.md` (when Phase 1 started)
+- `.wize/planning/prd.md` (when Phase 2 finished)
+- Optional: chat message describing the user’s goal.
 
 ## Outputs
-- Updates to `.wize/config/project.toml`
-- A first task handed off to the right agent
+
+- A **single handoff message** naming the next workflow to run, with the user’s name.
+- Optional: `.wize/knowledge/onboarding-summary.md` written when state is ambiguous.
 
 ## Steps
-1. **Greet.** "What are we working on?"
-2. **Detect.** Brownfield? Offer `wize-document-project`.
-3. **Profile check.** Confirm Core/+Web/+App and ask if changes needed.
-4. **Objective.** One sentence: what does success look like in 30 days?
-5. **Route.** 
-   - No brief? → call Pepper (`wize-product-brief`).
-   - Has brief? → call Maria Hill (`wize-create-prd`).
-   - Mid-flight? → resume where we left off (`sprint-status.md`).
+
+### 1. Greet the user
+
+Read `name` from `.wize/config/user.toml`. Greet by name. Speak in `communication_language` from `project.toml`. If `name` is blank, ask once and persist it back to `user.toml` before continuing.
+
+> "Welcome, {name}. You are at Wize onboarding for *{project_name}*."
+
+### 2. Detect project state
+
+Inspect, in order:
+
+| Path | Meaning |
+|---|---|
+| `.wize/implementation/sprint-status.yaml` | Active sprint exists. |
+| `.wize/planning/prd.md` | Phase 2 (PRD) is done. |
+| `.wize/planning/brief.md` | Phase 1 (Brief) is done. |
+| `.wize/knowledge/document-project/*.md` | Brownfield baseline exists. |
+| `package.json`, `src/`, etc. | Brownfield signals (vs. greenfield). |
+
+If multiple artifacts exist, treat the **latest** (PRD > brief > baseline) as the current phase.
+
+### 3. State machine
+
+- **S0 — No artifacts** → greenfield or no planning yet.
+- **S1 — Baseline only** → brownfield, no brief.
+- **S2 — Brief exists** → ready for PRD.
+- **S3 — PRD exists** → ready for sprint planning.
+- **S4 — Active sprint** → resume in-flight.
+
+### 4. Branch by state
+
+| State | Action | Hand-off |
+|---|---|---|
+| S0 | Ask: "What are we building?" Confirm: brownfield or greenfield. Offer `/wize-document-project` (brownfield) or `/wize-product-brief` (greenfield). | "Run `/wize-document-project` (Tony + Peggy) to baseline the repo, or `/wize-product-brief` (Pepper) to write a brief." |
+| S1 | Read `document-project/overview.md`; summarize the project in 3 bullets. Offer brief. | "Repo baselined. Run `/wize-product-brief` (Pepper)." |
+| S2 | Read `brief.md` (3 bullets). Offer PRD. | "Brief ready. Run `/wize-create-prd` (Maria Hill)." |
+| S3 | Read `prd.md` summary + `architecture.md` (if present). Offer sprint planning. | "PRD ready. Run `/wize-sprint-planning` (Maria Hill)." |
+| S4 | Read `sprint-status.yaml` and surface: which stories are in progress, last gate. | "Sprint active. Run `/wize-sprint-status` (Maria Hill) for the full picture." |
+
+### 5. Confirm and exit
+
+End every onboarding session with:
+
+> "Onboarding complete. Next: `/wize-<next-workflow>` ({persona})."
+
+Never auto-launch the next workflow. The user must confirm.
+
+## When to skip
+
+- When the user already knows what they want and explicitly invokes another workflow, route directly. Do not force onboarding.
+- When `WIZE_SKIP_ONBOARDING=1` is set, print a 1-line state summary and exit.
+
+## Anti-patterns Wizer rejects
+
+- Launching the next workflow without confirmation.
+- Re-asking the user’s name when it’s already in `user.toml`.
+- Dumping the full project state to the user. Summarize in ≤ 5 bullets.
+- Suggesting `wize-onboarding` from `/wize-help` once onboarding is complete. (Help should bypass onboarding for return users.)
+
+## Hand-off
+
+> "Onboarding done. You are at **{state}**. Next: `/wize-<next-workflow>` ({persona})."

package/src/security-overlay/_shared/allowlist.js

@@ -0,0 +1,154 @@
+'use strict';
+
+// allowlist.js — gate that filters arguments for an external pentest tool
+// before they are passed to child_process.execFile. The list of allowed
+// flags per tool lives in src/security-overlay/data/tool-allowlist.json.
+//
+// Schema (per tool, array of strings):
+//   "-foo"        switch with no value
+//   "-foo:"       switch that consumes the next argv as its value
+//   "-foo=bar"    switch with a fixed value (only the literal "bar" is allowed)
+//   "--flag="     switch that consumes a value joined by '=' (e.g. --level=1)
+//
+// Invariant: args NOT in the allowlist (or args that look like values for
+// flags not in the allowlist) are dropped. Positional args (targets, URLs)
+// pass through unchanged.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class UnknownToolError extends Error {
+  constructor(tool) {
+    super(`Unknown tool "${tool}" — not in tool-allowlist.json. Refusing to invoke.`);
+    this.name = 'UnknownToolError';
+    this.tool = tool;
+  }
+}
+
+const DEFAULT_ALLOWLIST_PATH = path.join(__dirname, '..', 'data', 'tool-allowlist.json');
+
+let _cache = null;
+function _loadDefault() {
+  if (_cache) return _cache;
+  const raw = fs.readFileSync(DEFAULT_ALLOWLIST_PATH, 'utf8');
+  _cache = JSON.parse(raw);
+  return _cache;
+}
+
+function loadAllowlist(filePath) {
+  const fp = filePath || DEFAULT_ALLOWLIST_PATH;
+  return JSON.parse(fs.readFileSync(fp, 'utf8'));
+}
+
+// Heuristic for "is this arg a flag?": starts with '-' and is more than 1 char
+// (a bare "-" is sometimes used as stdin, treat as positional).
+function isFlag(arg) {
+  return typeof arg === 'string' && arg.length > 1 && arg[0] === '-';
+}
+
+// Classify one allowlist token into one of:
+//   { kind: 'switch' }                       — no value
+//   { kind: 'colon',   prefix: '-foo' }      — consumes next argv (e.g. -f path)
+//   { kind: 'equals',  prefix: '--flag=' }   — consumes value joined by '=' (e.g. --level=1)
+//   { kind: 'literal', full: '-foo=bar' }    — only the exact form is allowed
+//
+// When matching an arg, we try in order: literal, then colon (exact prefix
+// match, e.g. arg === '-u'), then equals (arg starts with prefix, e.g.
+// arg === '--level=1'), then switch (exact equality).
+function classify(token) {
+  if (token.endsWith(':')) {
+    return { kind: 'colon', prefix: token.slice(0, -1) };
+  }
+  if (token.endsWith('=') && token.startsWith('--')) {
+    return { kind: 'equals', prefix: token };
+  }
+  if (token.includes('=') && !token.endsWith('=')) {
+    return { kind: 'literal', full: token };
+  }
+  return { kind: 'switch' };
+}
+
+// Given a flag arg, find the first allowlist token that matches it.
+function matchFlag(toolData, arg) {
+  // Literal first (most specific).
+  for (const tok of toolData) {
+    if (classify(tok).kind === 'literal' && arg === tok) return { consumeNext: false };
+  }
+  // Then colon (exact prefix match) — e.g. arg === '-u'.
+  for (const tok of toolData) {
+    if (classify(tok).kind === 'colon' && arg === classify(tok).prefix) return { consumeNext: true };
+  }
+  // Then equals — e.g. arg starts with '--level='.
+  for (const tok of toolData) {
+    if (classify(tok).kind === 'equals' && arg.startsWith(classify(tok).prefix)) return { consumeNext: false };
+  }
+  // Then switch.
+  for (const tok of toolData) {
+    if (classify(tok).kind === 'switch' && tok === arg) return { consumeNext: false };
+  }
+  return null;
+}
+
+// filterArgs(tool, args, allowlist) — keep only args allowed by the tool's
+// allowlist, handling value-bearing flags correctly.
+function filterArgs(tool, args, allowlist) {
+  const data = allowlist || _loadDefault();
+  if (!Object.prototype.hasOwnProperty.call(data, tool)) {
+    throw new UnknownToolError(tool);
+  }
+  const toolData = data[tool];
+
+  const out = [];
+  let i = 0;
+  const list = args || [];
+  while (i < list.length) {
+    const arg = list[i];
+    if (!isFlag(arg)) {
+      // Positional: target, URL, output path.
+      out.push(arg);
+      i++;
+      continue;
+    }
+    const m = matchFlag(toolData, arg);
+    if (!m) {
+      // Unknown flag — drop the flag. We do NOT also drop the next arg,
+      // because a positional after a stripped flag is still a positional
+      // (caller may have intended both to pass). However, common patterns
+      // are value-bearing: e.g. `--script vuln` — if the flag is dropped,
+      // "vuln" is also dropped to avoid leaking. This is the safe default.
+      if (looksLikeValueArg(list[i + 1])) {
+        // Consume the next arg as part of the dropped flag's expected value.
+        i += 2;
+      } else {
+        i++;
+      }
+      continue;
+    }
+    out.push(arg);
+    if (m.consumeNext) {
+      // Value-bearing: the next argv is the value. Pass it through.
+      if (i + 1 < list.length) {
+        out.push(list[i + 1]);
+        i += 2;
+      } else {
+        i++;
+      }
+    } else {
+      i++;
+    }
+  }
+  return out;
+}
+
+// A value arg is one that does NOT start with '-' (or is the bare "-").
+function looksLikeValueArg(arg) {
+  return arg !== undefined && (typeof arg !== 'string' || arg.length === 0 || arg[0] !== '-');
+}
+
+module.exports = {
+  filterArgs,
+  loadAllowlist,
+  UnknownToolError,
+  classify,
+  matchFlag
+};

package/src/security-overlay/_shared/cli-runner.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// cli-runner.js — small helper so each phase script can be invoked
+// either as a module (import + call) or as a CLI (with --securityDir /
+// --scope / --active argv). The invoke-phase helper spawns the script
+// as a Node subprocess; this module bridges that to the per-phase
+// `runX` function exported by each script.
+//
+// Usage from a script:
+//   const { runX } = require('./run-x');
+//   module.exports = { runX };
+//   if (require.main === module) {
+//     require('../../../_shared/cli-runner.js').runFromArgv({
+//       fn: runX,
+//       argMap: { securityDir: 'securityDir', scopePath: 'scopePath', active: 'active' }
+//     });
+//   }
+//
+// argv shape: --securityDir=PATH --scope=PATH --active [script-specific]
+// The function `fn` is called with the parsed object spread.
+
+function parseArgv(argv) {
+  const out = {};
+  for (let i = 0; i < (argv || []).length; i++) {
+    const a = argv[i];
+    if (a === '--active') { out.active = true; continue; }
+    const eq = a.indexOf('=');
+    if (eq > 0) {
+      const key = a.slice(0, eq).replace(/^--/, '');
+      const val = a.slice(eq + 1);
+      out[camel(key)] = val;
+      continue;
+    }
+    if (a.startsWith('--') && i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+      out[camel(a.slice(2))] = argv[i + 1];
+      i++;
+    }
+  }
+  return out;
+}
+
+function camel(s) {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+async function runFromArgv({ fn, argMap = {} }) {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgv(argv);
+  // Map --securityDir -> securityDir, --scope -> scopePath, etc.
+  const opts = {};
+  for (const [cliKey, optKey] of Object.entries(argMap)) {
+    if (cliKey in parsed) opts[optKey] = parsed[cliKey];
+  }
+  // Also accept any unprefixed camelCase keys directly.
+  for (const [k, v] of Object.entries(parsed)) {
+    if (!(k in opts)) opts[k] = v;
+  }
+  if (!('active' in opts)) opts.active = false;
+  // The phase script may also export its own CLI flags (--target for recon).
+  // We forward remaining --flags as a target-agnostic extraArgs-style list.
+  const extras = {};
+  for (const a of argv) {
+    if (a === '--active') continue;
+    const m = a.match(/^--([a-z0-9-]+)/);
+    if (m && !argMap[m[1]] && !argMap[camel(m[1])]) {
+      // Stash any flag the script might want to read itself.
+      extras[m[1]] = a.includes('=') ? a.slice(a.indexOf('=') + 1) : true;
+    }
+  }
+  Object.assign(opts, extras);
+  try {
+    const r = await fn(opts);
+    if (r && typeof r === 'object') {
+      // Print a one-line summary the orchestrator can show in its summary.
+      const summary = r.partialStatus
+        ? `${process.argv[1].split('/').pop().replace(/\.js$/, '')}: partial_status=${r.partialStatus} mode=${r.mode || 'passive'}`
+        : '';
+      if (summary) process.stdout.write(summary + '\n');
+    }
+    process.exit(0);
+  } catch (e) {
+    process.stderr.write(`✖ ${process.argv[1]}: ${e && e.message ? e.message : e}\n`);
+    process.exit(2);
+  }
+}
+
+module.exports = { parseArgv, runFromArgv };