Megaplan

# Megaplan

> **Before you invoke megaplan, run the `megaplan-prep` skill.** It's the front door for every run: it sizes the work (one plan vs. an epic), shapes the brief, and picks the profile (intelligence tier), robustness level, and thinking depth. Do not run `<launcher> init` without it.

**Scope:** This skill covers tooling — how to invoke and drive megaplan. For the decisions that come *before* invocation (scoping, brief, profile, robustness, depth), consult the **megaplan-prep** skill. If anything here contradicts megaplan-prep on decision-making content, megaplan-prep wins.

Route every step through the Arnold CLI's Megaplan subcommands. Never call agents directly.
Before the first CLI call, resolve a working launcher and reuse it for the whole run. Do not assume the removed `megaplan` entrypoint is on `PATH`; command presence alone is not enough. Prove the launcher works by successfully running a harmless CLI call with it first. In the instructions below, treat `<launcher>` as that verified command.
Launcher resolution order:
1. Try `python -m arnold_pipelines.megaplan config show`.
2. If that fails, try `./.venv/bin/python -m arnold_pipelines.megaplan config show`.
3. If that fails, try `uv run python -m arnold_pipelines.megaplan config show`.
4. If those fail, stop and report that the Arnold Megaplan module launcher is unavailable.
5. Do not use the removed `megaplan` module or console entrypoint; the repo-root `megaplan.py` file is a clean-break guard.
## Triage
Decision-making (scoping, profile, robustness, depth, brief structure) lives in the **megaplan-prep** skill — consult it before running `<launcher> init`. **Always run megaplan, even for tiny work** — `bare` robustness is the floor, never skip the harness. The few seconds of overhead pay back in the captured brief, plan, and outcome record.
## Modes
Megaplan has two output modes, picked with `--mode` at `init`:
- **`--mode code`** (default): the run produces a code diff. Execute workers emit per-task file changes. Use for features, refactors, bug fixes, migrations — anything whose deliverable is source code.
- **`--mode metaplan`** (alias: `--mode doc`): the run produces a single document artifact at `--output <relative/path>` (e.g. `docs/design.md`). The prep, execute, and review phases use authoring-specific prompts; the execute schema uses `sections_written` instead of file changes; auditing reasons about section delivery. Use for design docs, architecture specs, research notes, RFCs, proposals, post-mortems, migration plans — anything whose deliverable is prose, not code. This is the "design-first / preplan" workflow; `prep` is the visible repository-investigation *phase* inside every run (both modes have it), not a separate mode.

`--from-doc <relative/path>` works with either mode. The path must be relative to `--project-dir`, must stay inside that directory, and must point to an existing file. When present, `init` imports any `## Settled Decisions` section from that prior doc artifact and stores the source path for later planning and execution context.

All other flags (`--robustness`, `--auto-approve`, `--phase-model`, subagent mode, overrides, step editing) behave identically in both modes. The workflow phases are the same: `prep → plan → critique → gate → revise → finalize → execute → review`.

A common pattern is two runs: first `--mode metaplan` to produce a rigorous design document, then `--mode code --from-doc docs/design.md` on a new idea that references that document to implement it.

**`--mode` and `--output` go together.** `init` rejects `--output` without `--mode metaplan` (error `invalid_args`), and rejects `--mode metaplan` without `--output`. Don't try to pass one without the other.
## Working tree default
Default to building on top of any existing uncommitted changes in the working tree, not stashing or resetting them. The plan author should treat the dirty tree as in-progress context the new work composes with. Only deviate when the existing changes directly contradict what the new plan needs to do — and then flag the conflict explicitly rather than silently overwriting.

## Start
Run `<launcher> config show` before `init`. If `raw_config.execution.auto_approve` is explicitly present, do not ask the execution-mode question and honor that configured override, including configured `false`. If that raw key is absent, ask execution mode (auto-approve or review) before `init`. In the same config check, respect `execution.robustness` as a settable override when it is configured; otherwise pick robustness yourself per the **megaplan-prep** skill.
```bash
<launcher> init --project-dir "$PROJECT_DIR" [--auto-approve] [--robustness bare|light|full|thorough|extreme] [--mode code|metaplan] [--output docs/foo.md] [--from-doc docs/prior.md] [--north-star path/to/NORTHSTAR.md] "$IDEA"
```
Legacy robustness names (`tiny|standard|robust|superrobust`) are still accepted on the CLI and in stored config — they map to `bare|full|thorough|extreme` respectively — but new plans should use the canonical names.
For metaplan-mode runs, pass `--mode metaplan --output <relative/path>` (the path is where the final document artifact is written, relative to the project dir). Everything else is identical to code mode.
Pass `--from-doc <relative/path>` when the new run should inherit decisions from a prior doc artifact. The path must be relative to the project dir, must exist as a file, and can be used with either `--mode code` or `--mode metaplan`. When the source doc contains a `## Settled Decisions` section, megaplan imports those decisions and automatically promotes them into success criteria for the new plan: `load_bearing: true` decisions become `must` criteria and `load_bearing: false` decisions become `info` criteria.

Pass `--north-star <path>` when the plan needs durable end-state intent beyond the local brief. `init` snapshots the UTF-8 markdown/text file into the plan under `anchors/north_star/plan.md`; later source edits do not affect the active plan. First iteration supports only the `north_star` anchor type. Decision-heavy prompts get full `## Anchor Context: North Star` blocks; review-family prompts get short `## Anchor Check: North Star` reminders; execution and feedback prompts get no anchor context.
## Settled Decisions Section Format
When authoring a doc artifact that makes design decisions, use either of these canonical markdown shapes (the parser accepts both):

Bold-dash inline shape (preferred for short decisions):
```md
## Settled Decisions

- **SD-001** \u2014 Keep the current storage model. _load_bearing: true_
  Rationale: External integrations depend on it.
- **SD-002** \u2014 Default model is claude-sonnet-4-6. _load_bearing: false_
  Rationale: Balance of speed and capability.
```

YAML-ish shape (preferred when decisions need more fields):
```md
## Settled Decisions
- id: SD-001
  load_bearing: true
  decision: Keep the current storage model
  rationale: External integrations depend on it.
```
Use one list item per decision. Keep the `SD-NNN` convention (`SD-` prefix plus a number), store `load_bearing` as `true` or `false`, and indent continuation lines by two spaces beneath the list-item marker.
Report the plan name, execution mode, robustness, mode (and `--output` path when metaplan mode), current state, and next step.
## Workflow
Run the loop in this order:
1. `prep`
2. `plan`
3. `critique`
4. `gate`
5. `revise` when gate recommends iteration
6. `finalize`
7. `execute`
8. `review`
Use `next_step` and `valid_next` for CLI routing. After `gate`, follow `orchestrator_guidance` instead of manually interpreting gate signals. When a response includes `next_step_runtime`, use its `duration_hint` and `recommended_next_check_seconds` to calibrate timing.
At `--robustness bare`, the loop is: `plan` → `finalize` → `execute`. There is no prep, no critique, no gate, and no review.
At `--robustness light`, the loop is: `plan` → `critique` → `revise` → `finalize` → `execute`. There is no prep, no gate, and no review.
At `--robustness full`, the loop is: `prep` → `plan` → `critique` → `gate` → ...
At `--robustness thorough`, the loop is also `prep` → `plan` → `critique` → `gate` → ... but uses 8 critique checks instead of 4 and enables parallel critique.
At `--robustness extreme`, the loop is the same as thorough but also enables parallel review.
## Step Rules
- `plan`: inspect the repository first; produce the plan plus `questions`, `assumptions`, and `success_criteria`. Each criterion is `{"criterion": "...", "priority": "must|should|info"}`. `must` = hard gate (reviewer blocks), `should` = quality target (reviewer flags but doesn't block), `info` = human reference (reviewer skips).
- `prep`: make repository investigation explicit before planning. Respect `skip: true` when the task is already concrete enough.
- `critique`: surface concrete flags with concern, evidence, category, and severity; reuse open flag IDs; call out scope creep. Also validate that success criteria priorities are well-calibrated — `must` criteria should be verifiable yes/no, subjective goals should be `should`.
- `gate`: read the response, warnings, and `orchestrator_guidance`. (Skipped at light robustness.)
- `revise`: show the delta, flags addressed, and flags remaining. At light robustness, routes to `finalize`; otherwise loops back through `critique` and `gate`.
- `review`: judge success against the success criteria and the user's intent, not plan elegance. Only block on `must` criteria failures. `should` failures are flagged but don't require rework. `info` criteria are waived.
## Gate Principle
The gate response tells the orchestrator what to do next. Follow `orchestrator_guidance` unless you have a concrete reason to disagree after investigating the repository or plan artifacts yourself.
Investigate before disagreeing: read the current plan and critique artifacts, check the project code to verify whether a flagged issue is real, or use `<launcher> status --plan <name>` / `<launcher> audit --plan <name>`.
If you disagree with the guidance, explain why briefly and use an override. Do not manually reinterpret score trajectory, flag quality, or loop state when the gate already did that work for you.
## Execute
- After a successful gate, run `<launcher> finalize` to produce the execution-ready briefing document.
- In auto-approve mode, run `<launcher> execute --confirm-destructive` after finalize.
- In review mode, pause at the finalize-to-execute checkpoint and wait for explicit approval before running:
```bash
<launcher> execute --confirm-destructive --user-approved
```
## Long-Running Execution
For plans with multiple batches, use per-batch mode to drive execution incrementally:
```bash
<launcher> execute --plan <name> --confirm-destructive --user-approved --batch 1
<launcher> execute --plan <name> --confirm-destructive --user-approved --batch 2
# ... continue until all batches complete
```
Between batches, poll progress:
```bash
<launcher> progress --plan <name>
```
Use `<launcher> status --plan <name>` for the full plan state, including active-step timing and any `next_step_runtime` guidance from the latest response.
Per-batch mode uses global batch numbering (1-indexed, computed from ALL tasks). Each `--batch N` call:
- Validates that batches 1..N-1 are complete
- Executes only batch N's tasks
- Writes `execution_batch_N.json` as evidence
- On the final batch, produces aggregate `execution.json` and transitions to `executed`
Timeout recovery: re-run the same `--batch N`. The harness checks prerequisite completion and merges only untracked tasks.
Note: `progress` shows completed state only (between-batch granularity). With per-batch mode, each batch is a separate CLI call, so the orchestrator has full visibility.
## Overrides
- `<launcher> override add-note --plan <name> --note "..."`
- `<launcher> override force-proceed --plan <name> --reason "..."`
- `<launcher> override replan --plan <name> --reason "..." [--note "..."]`
- `<launcher> override abort --plan <name> --reason "..."`
`force-proceed` is available from `critiqued` (routes to finalize, not execute). `replan` is available from `gated`, `finalized`, or `critiqued`. `add-note` is safe from any active state.
## Replan
Use `replan` when the orchestrator itself needs to edit the plan directly instead of asking the revise worker to do it.
```bash
<launcher> override replan --plan <name> --reason "expanding scope" --note "Also clean up the display layer"
```
After `replan`, read the returned plan file, edit it directly, then run `<launcher> critique`.
## Step Editing
Use `step` when you need to insert, remove, or reorder step sections (`## Step N:` or `### Step N:`) without hand-editing the markdown.
```bash
<launcher> step add --plan <name> --after S3 "Add regression coverage for the parser"
<launcher> step remove --plan <name> S4
<launcher> step move --plan <name> S4 --after S2
```
Each edit writes a new same-iteration plan artifact, preserves the latest plan meta questions/success criteria/assumptions, and resets the plan to `planned` so it re-enters critique.
## Sessions And Autonomy
- Agents default to persistent sessions.
- `--fresh`: start a new persistent session.
- `--ephemeral`: one-off call with no saved session.
- `--persist`: explicit persistent mode.
- Keep moving and show results at each step.
- Only pause at finalize to execute in review mode.
## Configuration
View current defaults with `<launcher> config show`. Override with `<launcher> config set <key> <value>`. Reset with `<launcher> config reset`.
When routing or behavior depends on config, check `<launcher> config show` and respect user overrides instead of assuming defaults.
Settable execution keys: `execution.auto_approve`, `execution.robustness`.
## Profiles
A profile is a named preset that maps each workflow phase to an agent/model spec. Pass `--profile <name>` to any command that accepts `--phase-model` (`init`, `loop-init`, `tiebreaker`, etc.) to apply the preset.
See **megaplan-prep** for profile selection. Inspect available profiles with `<launcher> config profiles list`.
Resolution order, later overrides earlier within the same name: built-in (`megaplan/profiles/*.toml`) → user (`~/.config/megaplan/profiles.toml`, or `$XDG_CONFIG_HOME/megaplan/profiles.toml`) → project (`<project_dir>/.megaplan/profiles.toml`).
Inspect with `<launcher> config profiles list` and `<launcher> config profiles show <name>`.
File format: TOML with a `[profiles.<name>]` table. Keys are phase names (`plan`, `prep`, `critique`, `revise`, `gate`, `finalize`, `execute`, `loop_plan`, `loop_execute`, `review`, `tiebreaker_researcher`, `tiebreaker_challenger`); values are agent specs like `"claude"`, `"codex"`, `"omp:fireworks/kimi-k2p6"`, `"omp:zai/glm-5.2"`. Example:
```toml
[profiles.my-mix]
plan     = "claude"
critique = "codex"
execute  = "omp:fireworks/kimi-k2p6"
review   = "codex"
```
`--phase-model` overrides on the CLI stack on top of any profile.

### Fallback chains (v1)

Phase spec values can also be **TOML string arrays** to declare an ordered fallback chain. The first element is the selected spec; subsequent elements are only tried when the preceding spec fails with a retryable availability or infrastructure error and the next spec crosses a provider-family boundary. Example:

```toml
[profiles.safe-mix]
plan   = ["claude", "codex"]
review = ["codex:gpt-5.5", "claude:sonnet"]
```

**This is the only v1 entry point for fallback chains.** Comma-separated strings, CLI fallback-list flags, and YAML chain editing syntax are not supported in v1 and are deferred to later versions.

Internally, multi-spec phase values are persisted in `state.json` using the compact `__fallback_json__:<json-array>` encoding. This encoding is an implementation detail of the persistence bridge — you never write it by hand. The harness decodes it transparently; every downstream consumer sees the selected spec (first element) as the legacy scalar value.

**Fallback advancement rules (v1):**
- **Allowed:** Fallback advances to the next spec only on retryable **availability** or **infrastructure** failures (connection errors, timeouts, crashes, service unavailable, internal errors).
- **Blocked:** Fallback does **not** advance for malformed output, schema failures, test/evidence failures, blocked results, gate/review rejection, semantic failures, auth errors, quota exhaustion, rate limits, bad requests, unsupported models, or context-window errors.
- **Cross-provider requirement:** The next spec must belong to a different provider family than the failing spec (e.g., `claude` → `codex`, or `omp:deepseek` → `omp:fireworks`). Same-provider advancement is rejected.
- **execute / loop_execute:** Fallback chains are preserved in state but advancement beyond the first spec is **blocked** in v1 — the harness raises `ExecuteFallbackUnsafe` if a retryable failure would trigger a second attempt. This protects against duplicate side effects (file mutations, checkpoints, merges).

When an explicit fallback chain is configured for a phase, ambient runtime fallback (e.g., automatic provider retry) is **suppressed** — only the declared chain controls advancement.
## Bakeoff
See the **bakeoff** skill for methodology and the **megaplan-prep** skill for when bake-offs earn their cost. This section covers the CLI mechanics once you've decided to run one.

`<launcher> bakeoff run` runs the same idea through multiple profiles concurrently, each in its own git worktree, each driven autonomously by `<launcher> auto`. Use it when the user wants to compare profiles head-to-head on the same task (e.g., "run this with kimi and the default profile side-by-side").
Supports `--mode code` (default) and `--mode doc` / `--mode metaplan` (alias). For doc-mode bake-offs, `--output <relative/path>` is required and is threaded into each profile's `<launcher> init`; merge brings the chosen profile's doc artifact back to main instead of applying a code patch. Joke mode is not yet supported.
Requires a clean main worktree by default — pass `--allow-dirty` when there are unrelated uncommitted changes you want to keep on main. Those changes stay on main and are NOT copied into the worktrees, since worktrees branch off the current commit's SHA.
The idea must be a file (`--idea-file <path>`), not an inline string. Write the idea to a file first.
Bakeoff is inherently autonomous (it spawns `<launcher> auto`), so the execution-mode question doesn't apply to bakeoff runs. `--robustness` is forwarded to each profile's `init`. When a project-layer `.megaplan/profiles.toml` exists, it's automatically copied into each worktree so project-only profiles resolve.
Lifecycle:
- `<launcher> bakeoff run --idea-file <path> --profiles <p1> <p2> [--mode code|doc|metaplan] [--output <relative/path>] [--exp-id <id>] [--detach] [--robustness <level>] [--allow-dirty]` — kicks off N concurrent profile runs. Without `--detach` it streams a live status table every 5s and blocks until all profiles finish; with `--detach` it returns immediately and the user polls via `status`. `--output` is required with `--mode doc|metaplan` and rejected with `--mode code`.
- `<launcher> bakeoff status [--exp <id>]` — current state of each profile (running / completed / crashed).
- `<launcher> bakeoff tail [--exp <id>]` — tail the per-profile auto logs.
- `<launcher> bakeoff compare --exp <id> [--judge <model>]` — collect metrics across profiles; with `--judge`, an LLM judge ranks the outputs.
- `<launcher> bakeoff pick --exp <id> --profile <name> --rationale "..."` — record the human-selected winner.
- `<launcher> bakeoff merge --exp <id>` — merge the chosen profile's worktree back to main.
- `<launcher> bakeoff resume --exp <id>` — resume unfinished profile runs.
- `<launcher> bakeoff abandon --exp <id>` — discard worktrees but keep audit data.
## Cloud Mode
`<launcher> cloud` runs a plan inside a provider-managed container with a persistent workspace volume, so the run survives the user's terminal session. Suggest it for long-running plans that would outlast a local session, multi-repo work, or when the user wants an isolated persistent sandbox. The supported remote path is `provider: ssh` against the Hetzner agentbox; `provider: local` remains for local iteration and CI smoke tests.

Quick subcommand reference: `init`, `build`, `deploy`, `chain`, `status`, `attach`, `logs`, `exec`, `resume`, `down`, `destroy`. Typical flow: `<launcher> cloud init` → edit `cloud.yaml` → export secrets → `<launcher> cloud deploy` → `<launcher> cloud chain <chain.yaml>`.

For the full reference — `cloud.yaml` fields, the `extra_repos[]` + `chain_session` multi-tenancy model, the operator loop, and the gotchas that wedge fresh runs (committed `chain_state.json`, profile-alias gap, secret-upload behavior, "internal_error" masking credit failures) — see the **megaplan-cloud** skill. Read it before launching the first cloud chain in a new project; the gotchas section will save hours.
## Tickets
`<launcher> ticket new` creates a repo-scoped issue ticket. Use it when:
- During epic/plan work you notice an out-of-scope problem, bug, or rough edge
- A user explicitly asks you to capture something for later attention
- You want to log an observation that doesn't block the current task but should be tracked

The command prints only a ULID to stdout on success. Tickets live as `.megaplan/tickets/{ulid}-{slug}.md` files and are auto-discovered by the planner for future epics. Link them to epics with `<launcher> ticket link <ticket> <epic> --resolves` so they auto-address when the epic completes.

## Briefs
`<launcher> brief` creates canonical source artifacts for work you intend to run.
Use it when:
- You are turning an idea into a durable single-plan input
- You are scaffolding an epic's `chain.yaml` and milestone idea files
- You want the source document committed before `<launcher> init` snapshots it into plan state

Briefs live as committed files under `.megaplan/initiatives/{slug}/`. Single-plan
ideas live at `.megaplan/initiatives/{slug}/briefs/{slug}.md`; epics live at
`.megaplan/initiatives/{epic-slug}/chain.yaml` with milestone briefs under the
initiative's `briefs/` directory. This is ticket-like in storage and ergonomics, but not in lifecycle:
briefs feed `<launcher> init` / `<launcher> chain start`; tickets are open problem
notes that can be discovered, linked, and auto-addressed by epics.

Briefs and tickets share the local artifact substrate: common `.megaplan/<kind>/`
path handling, slug normalization, optional frontmatter parsing, keyword
filtering, and snippets. Use `<launcher> brief list`, `<launcher> brief show`, and
`<launcher> brief search` for the brief side of that common read surface.

For epics, `<launcher> brief epic` also scaffolds `NORTHSTAR.md` beside
`chain.yaml` and declares it through `anchors.north_star`. Edit it before
`chain start`. Chain runs require this top-level North Star by default. Use it
for the durable destination and milestone briefs for local scope. Opt out only
with `--no-require-anchor --missing-anchor-ack "<reason>"` or matching
`driver.require_anchor: false` plus `driver.missing_anchor_ack` in the spec.

`<launcher> init --idea-file <path>` reads the file and snapshots its text; it does
not move arbitrary files into the retired `.megaplan/briefs/` tree. If the idea file is a markdown
artifact with YAML frontmatter, `init` snapshots only the markdown body. Use
`<launcher> brief new --init` to create the canonical source file first and then
initialize from it.

Inspect captured anchors with:

```bash
<launcher> anchors show --plan <name> [--json]
```

## Feedback
See **megaplan-prep** for when to add the feedback phase (`--with-feedback`). This section covers the CLI mechanics once you've decided to use it.

`<launcher> feedback --plan <name>` scaffolds a `feedback.md` file in the plan directory and opens it in `$EDITOR` (or `$VISUAL`). The file has one section per workflow stage — `prep`, `plan`, `critique`, `revise`, `gate`, `tiebreaker`, `finalize`, `execute`, `review` — plus an `Overall` section. Each section has a `rating:` (integer 0–10) and a free-form `comment:` field; leave any field blank to skip it.

This is **user feedback**, owned by the human after a run finishes — megaplan only scaffolds the template and parses it back on load, it never overwrites edits. Old plans without a `feedback.md` simply have no feedback attached; running `<launcher> feedback --plan <name>` on an older plan scaffolds the template on demand (backwards compatible).

Use `<launcher> feedback show --plan <name>` to print the parsed summary, and `--no-edit` to just scaffold the template and print the path without launching an editor. Parsed feedback is exposed on the in-memory `Plan` record as `Plan.feedback` (a dict shaped `{"overall": {...}, "stages": {stage: {...}}}`), so downstream tooling can read it the same way as any other artifact. When `--actor`/`MEGAPLAN_ACTOR_ID` is set, parsed feedback is also written to the `plans.feedback` jsonb column so the DB and file backends stay in sync.

### Filling feedback with subagents
Recommended process when an agent (rather than the human) is producing the initial assessment:

1. **Scaffold**: run `<launcher> feedback --plan <name> --no-edit` to create the empty `feedback.md`. Note the plan directory it prints — that is where the per-stage artifacts live (`plan_v*.md`, `critique*.json`, `gate.json`, `tiebreaker_*.json`, `finalize.json`, `execution*.json`, `review.json`, etc.).
2. **Per-stage assessment**: dispatch one read-only subagent per stage that actually ran (skip stages with no artifacts). Brief each subagent narrowly — give it the plan idea, the stage name, and the artifact filenames for that stage only. Ask it to return a 0–10 rating plus a 1–3 sentence comment grounded in what the artifacts show (what worked, what was weak, what was missed). Run these in parallel; they have no dependencies on each other.
3. **Synthesize Overall**: after the per-stage results come back, *you* (the orchestrating agent, not a subagent) read the per-stage ratings and comments together with the final outcome (`final.md`, `review.json`, any `latest_failure`) and decide an Overall rating and comment. The Overall is a judgment call about whether the run delivered the goal, not an average of stage ratings.
4. **Write**: edit `feedback.md` with the ratings and comments. Leave a stage blank if it didn't run or you can't form a defensible opinion — empty is better than guessed. Run `<launcher> feedback show --plan <name>` to confirm the parser picked everything up.

Keep comments grounded in specific artifact evidence ("critique flagged X but reviewer didn't catch the regression in Y") rather than vibes. The point of feedback is signal for future runs, not a participation score.

### Searching feedback across plans
`<launcher> feedback search` queries every plan with non-empty feedback across both backends — local `feedback.md` files in this project tree plus, when an actor is configured, the `plans.feedback` jsonb column in the DB. Duplicates between backends are de-duped by (plan name, project_dir). Use this to answer "which profile actually scored well on this repo?" or "where did the executor get a 6 or below?". Filters:
- `--profile <substr>` — substring match on the plan's profile (e.g. `--profile claude` matches `all-claude`, `claude-led`, etc.).
- `--repo <substr>` — substring match on the plan's `project_dir` / repo path.
- `--min-rating N` / `--max-rating N` — bounds on the Overall rating.
- `--stage <name>` — only plans that recorded a rating for that stage (`plan`, `critique`, `execute`, …).
- `--has-comment` — only plans whose Overall comment is non-empty.
- `--all` — scan every megaplan project root on this machine, not just the current tree.
- `--json` — emit raw rows instead of a table.

Default output is a compact table (plan, profile, overall rating, backend, repo, plus the first line of the Overall comment). Combine with `<launcher> feedback show --plan <name>` to drill into a specific match.
## Observability
Plans started after this layer landed write an append-only `events.ndjson` event journal to their plan dir. Four CLI surfaces read from it; reach for them whenever a run is in flight or you need to reconstruct what happened. See the **megaplan-observe** skill for the full failure-mode catalog and worked invocation chains.

- `<launcher> introspect --plan <name>` — single structured-JSON snapshot. Always check this first when something looks stuck; the `active_phase.liveness` enum (`progressing | quiet | stalled | timeout-imminent`) and `block_details.recoverable_via` together tell you whether to wait, intervene, or override. Also surfaces `outstanding_flags_count`, useful when a plan is sitting on unresolved critique signals.
- `<launcher> trace --plan <name> [--follow] [--format json|pretty|narrative] [--phase <p>] [--since <duration>]` — stream events. `narrative` format is the agent-facing affordance; `--follow` tails as the plan progresses; `--phase` and `--since` filter. Prints `trace: no events.ndjson for plan <name>` cleanly when a plan predates the journal.
- `<launcher> doctor [--plan <name> | --repo]` — diagnostic. `--repo` catches rubric/binary drift (skill profile names vs `profiles list`) and editable-install dirtiness *before* `<launcher> init`, so reach for it after a branch switch / pull / fresh checkout. `--plan` reports lock, phase liveness, LLM liveness, cost-vs-cap, orphan subprocesses, and outstanding flags.
- `<launcher> record-tag --plan <name> --tag <name> --note "..."` — annotate a moment in the journal so later trace/introspect calls can find it. All three args are required.

Stale-timestamp inference, opaque blocked state, and "model thinking vs TCP wedged" are the three confusions this layer is designed to kill — if you find yourself running `lsof`, `ps`, or doing manual `ls -lat` time math on a plan dir, you should be running `introspect` or `trace` instead.
## Commands
```bash
<launcher> status --plan <name>
<launcher> progress --plan <name>
<launcher> audit --plan <name>
<launcher> list
<launcher> prep --plan <name>
<launcher> plan --plan <name>
<launcher> critique --plan <name>
<launcher> revise --plan <name>
<launcher> gate --plan <name>
<launcher> finalize --plan <name>
<launcher> execute --plan <name> --confirm-destructive [--batch N]
<launcher> review --plan <name>
<launcher> step add --plan <name> [--after S<N>] "description"
<launcher> step remove --plan <name> S<N>
<launcher> step move --plan <name> S<N> --after S<M>
<launcher> override add-note --plan <name> --note "..."
<launcher> override force-proceed --plan <name> --reason "..."
<launcher> override replan --plan <name> --reason "..." [--note "..."]
<launcher> override abort --plan <name> --reason "..."
<launcher> config show
<launcher> config set <key> <value>
<launcher> config reset
<launcher> config profiles list
<launcher> config profiles show <name>
<launcher> bakeoff run --idea-file <path> --profiles <p1> <p2> [--mode code|doc|metaplan] [--output <relative/path>] [--exp-id <id>] [--detach] [--robustness <level>] [--allow-dirty]
<launcher> bakeoff status [--exp <id>]
<launcher> bakeoff tail [--exp <id>]
<launcher> bakeoff compare --exp <id> [--judge <model>]
<launcher> bakeoff pick --exp <id> --profile <name> --rationale "..."
<launcher> bakeoff merge --exp <id>
<launcher> bakeoff resume --exp <id>
<launcher> bakeoff abandon --exp <id>
<launcher> brief new <slug> [-b <body> | --from <path> | -] [--force] [--init]
<launcher> brief epic <slug> --milestone LABEL=TITLE [--base-branch <branch>] [--force]
<launcher> brief list [--json]
<launcher> brief show <id-or-path> [--json]
<launcher> brief search [KW ...] [--all] [--sort path|title|length] [--desc] [--limit N] [--json]
<launcher> ticket new "title" -b "body"
<launcher> ticket list [--status <s>] [--tags <t>] [--json]
<launcher> ticket show <id> [--json]
<launcher> ticket edit <id> [--title <t>] [--body <b>] [--status <s>]
<launcher> ticket link <ticket> <epic> [--resolves]
<launcher> ticket unlink <ticket> <epic>
<launcher> ticket addressed <id> [--note <n>]
<launcher> ticket dismiss <id> --reason "..."
<launcher> ticket reopen <id>
<launcher> feedback show --plan <name> [--no-edit]
<launcher> feedback search [--profile <s>] [--repo <s>] [--min-rating N] [--max-rating N] [--stage <name>] [--has-comment] [--all] [--json]
<launcher> introspect --plan <name> [--json]
<launcher> trace --plan <name> [--follow] [--format json|pretty|narrative] [--phase <p>] [--since <duration>]
<launcher> doctor [--plan <name> | --repo]
<launcher> record-tag --plan <name> --tag <name> --note "..."
```