@magnusekdahl/parallix 1.0.0

package/README.md

@@ -0,0 +1,196 @@
+# Parallix
+
+**Parallix is a CLI for a local-first, human-in-the-loop developer workflow that runs several supported AI coding agents against one repository as isolated, resumable, reviewable missions — instead of one agent improvising in your working tree.**
+
+It is built for solo maintainers and small-team leads who already drive AI coding agents such as Claude Code, Codex, OpenCode/Qwen, and Vibe/Mistral and have hit the real problems: two agents fighting over one checkout, a run dying when a provider hits its usage cap, no clean way to resume a long task where it stopped, and the agent that wrote the code also being the one that declares it done.
+
+It wraps your AI coding workflow without replacing it: Parallix turns each piece of work into a *mission* with its own branch and its own git worktree, fails over to another agent family when one hits its usage limit, checkpoints long runs so they resume deterministically, and forces a second coding agent review step plus your own repo-configured verification gates before anything is integrated. A human still chooses the task, launches each phase, reads the review, and decides whether the work should land.
+
+**Why not just use Claude Code, Codex, or OpenCode directly?** Those are the agents — Parallix is the harness around them. It does not replace your agent or your model. It coordinates several of them as one multi-agent coding workflow with isolation, automatic failover, deterministic checkpoints, and a forced review pass that a single agent session does not give you.
+
+**The first concrete thing you can do** is install the px CLI, create one Backlog.md-style task, and draft it:
+
+```sh
+npm pack && npm install -g ./magnusekdahl-parallix-*.tgz
+px draft task-001
+```
+
+`px draft` does not accept free-text slugs like `my-first-task`, and it does not create the task for you. It expects an existing Backlog.md-style task key such as `task-001`.
+
+Everything below is the longer version, with the proof and the caveats kept honest.
+
+## Why Parallix?
+
+Running AI coding agents one session at a time hits a ceiling fast:
+
+- **One working tree, many agents.** Point two agents at the same checkout and they fight over the index, the branch, and uncommitted files. You either serialize them — one idle while the other runs — or hand-manage `git worktree` and branch names yourself.
+- **Runs die on usage caps.** An agent prints "usage limit reached", the run stops, and you babysit it: restart later, or hand-switch to a different model.
+- **Long tasks lose their place.** A crashed or context-exhausted agent leaves you reconstructing what was already done by re-reading diffs.
+- **The author grades its own homework.** The agent that wrote the change also declares it done. Nobody independent looks before it lands.
+
+Parallix is a mission-based development workflow that addresses each of these directly, with the mechanics living in tested code rather than in prompts. It is not another agent or model — it is the operator-owned layer around the agents you already use.
+
+## What it does
+
+Each capability below is tied to a use case in [`docs/use-cases.md`](docs/use-cases.md), with the confidence level (Confirmed / Partial) carried through honestly.
+
+- **Run several AI coding agents on one repo without clobbering each other** *(UC-1 — Confirmed mechanic).* Every mission gets its own `mission/<slug>` branch and its own sibling git worktree (`../<repo>-<slug>`) automatically, so N agents make progress independently and each lands by squash-merge.
+- **Fail over automatically when an agent hits its usage limit** *(UC-2 — Confirmed).* Per-family limit messages are pattern-detected; the agent family is written to a timed blocklist and the run retries with the next eligible, unblocked family. Only when all are exhausted does it fail loudly. Agent usage limits stop a single session; they don't have to stop the mission.
+- **Resume a long mission deterministically** *(UC-3 — Confirmed).* Every checkpoint runs the gate, commits a checkpoint document with a literal `Next action:` line, and pushes it — so a later session or a different agent resumes from a written instruction, not a guess.
+- **Force a second, preferentially-different coding agent review before merge** *(UC-4 — Partial).* Review is a separate step whose reviewer selection excludes the implementer to prefer a different agent family, and a self-approval is code-blocked at the provider. It falls back to the same family when no other agent is runnable, so this forces a second review *attempt* — it does not guarantee a different reviewer.
+- **Publish work to a Forgejo reviewer surface without making Forgejo your branch authority** *(Confirmed mechanic).* When the review provider is enabled, Parallix syncs the local baseline to a dedicated `review` remote and opens or updates the PR there; if Forgejo is disabled, the branch/worktree flow still runs locally.
+- **Use a repo-local Graphify knowledge graph for smaller codebase context pulls** *(Confirmed mechanic, optional, unproven payoff).* In repositories where the operator has already installed the Graphify skill, the workflow keeps `graphify-out/` isolated per worktree and refreshes it during review/integration, while the installed agent guidance steers codebase questions toward `graphify query` / `path` / `explain` before full reports or raw grep. That should reduce context bloat, but this repo does not currently claim a measured token-usage reduction.
+- **Keep your existing verification gate instead of agent self-reporting** *(UC-5 — Confirmed).* The gate is a configured shell command with a no-op default: declare your existing `make` / `npm` / script command in `workflow.config.json` and it runs verbatim; declare nothing and verification is a documented no-op pass, not an invented gate.
+- **See which agent family actually pays off across every repo one runtime drives** *(UC-6 — Partial).* A single operator-owned `stats.csv` accumulates per-agent telemetry across repositories. Token-cost comparison is complete today only for the families with structured telemetry (codex, claude); two families record honest zeros by design.
+
+## The core workflow
+
+A mission moves through a fixed lifecycle, one branch and one worktree at a time:
+
+```
+backlog → draft → active → review → approved → done
+            │        │        │         │
+         worktree  agent     second   squash-
+         + branch   run +    review +  merge +
+                  checkpoints  gates   cleanup
+```
+
+In practice: a human drafts a mission, Parallix creates the branch and worktree, an agent runs and writes checkpoints, a verification gate runs, a second (preferentially different) agent reviews the diff, and only then is the work integrated back to your primary branch by squash-merge. Blocking review findings loop back to `active` on the same branch and PR.
+
+## Quick start
+
+The current install path is a **local npm tarball** built from this repository. A **scoped npm package** (`@magnusekdahl/parallix`) will be available after publication (see [Current status](#current-status)).
+
+```sh
+# Build and install from the local tarball
+npm pack
+npm install -g ./magnusekdahl-parallix-*.tgz
+
+# Confirm which px is on PATH
+px --version
+```
+
+Optional but useful: add `px shell-init` to your shell rc so mission transitions can `cd` your terminal into the next worktree:
+
+```sh
+echo 'eval "$(px shell-init bash)"' >> ~/.bashrc
+```
+
+**Post-publish install:** Once published to the npm registry, Parallix can be installed with a single command:
+
+```sh
+npm install -g @magnusekdahl/parallix
+```
+
+`px setup` is an optional convenience wizard that writes `workflow.config.json` and appends workflow entries to `.gitignore`. Parallix runs on built-in defaults without it — `px setup` becomes useful when you want to configure your verification command, customize the mission layout, or bootstrap the Forgejo review surface (repo, token files, and `review` remote). Forgejo is the PR viewer and publication surface here, not the authority for local branch ancestry or integration.
+
+Before `px draft`, create a task first. If you already use Backlog.md, create it there. If you do not, create the markdown file yourself under `backlog/tasks/`:
+
+```md
+backlog/tasks/task-001 - my-first-task.md
+---
+id: TASK-001
+title: my first task
+status: backlog
+assignee: []
+labels: ["user_value"]
+dependencies: []
+---
+```
+
+Then draft and run it with the actual workflow command:
+
+```sh
+px draft task-001
+px active task-001
+```
+
+Optional but useful: install the Graphify skill once per supported agent family if you want graph-backed codebase navigation in long missions and reviews. This is not a hard requirement like having a task file for `px draft`; when Graphify is not installed, Parallix skips graph updates and continues the workflow. The operator setup is documented separately because it is a workstation capability, not a minimum install step.
+
+## Example
+
+A realistic human-in-the-loop pass — mission → worktree → agent run → checkpoint → review → integrate:
+
+```sh
+# Start from a real Backlog task key. Draft creates branch mission/task-042
+# and a sibling worktree ../myrepo-task-042
+px draft task-042
+
+# Run the implementer in that isolated worktree. If the chosen family
+# hits its usage cap mid-run, Parallix blocks it and retries on
+# the next eligible family. Each checkpoint commits a doc with a
+# literal "Next action:" line, so the work is resumable.
+px active task-042
+
+# A second, preferentially-different agent reviews <main>..HEAD.
+# If Forgejo review is enabled, the PR is published to the dedicated
+# review surface; a self-approval by the implementing agent is blocked.
+px review task-042
+
+# Land it: runs configured integration gates, squash-merges to
+# the primary branch, updates board state, removes the branch
+# and worktree.
+px integrate task-042
+```
+
+The verification gate that runs at each checkpoint is whatever you declare in `workflow.config.json` (this repo declares `npm test`), so the workflow adopts your existing CI rather than replacing it.
+
+## Use cases
+
+The full evidence-backed inventory is in [`docs/use-cases.md`](docs/use-cases.md). The README focuses on the three claims that are best supported by the current code and retrospective data:
+
+1. **Parallel multi-agent execution (UC-1).** The isolated worktree-per-mission model is the *specific* mechanic an internal retrospective measured as the only configuration to beat a human baseline. Depending on whether you frame output as direct user-value missions or total completed missions in an already-productized setup, the observed gain ranges from roughly **+57%** to about **+1,280%**.
+2. **Usage-limit auto-failover (UC-2).** Family-specific limit detection → timed blocklist → retry-next-eligible is a tested control loop, not a retry button.
+3. **Second review gate (UC-4, Partial).** A self-approval is code-blocked and reviewer selection excludes the implementer family — forcing a second review *attempt* by a preferentially different agent, with an honest same-family fallback.
+
+## What Parallix is not
+
+- **Not a model and not an AI coding agent.** It does not generate code itself. It coordinates the agents and models you already use (Claude Code, Codex, OpenCode/Qwen, and Vibe/Mistral).
+- **Not an IDE or an editor plugin.** It is a CLI workflow harness around Git and your existing toolchain — there is no UI, no autocomplete, no inline suggestions.
+- **Not a magic autonomous engineer.** This is a human-in-the-loop workflow. Nothing merges itself, and the safe operating model is that a human decides what to queue, when to run `px active`, how to respond to review findings, and whether `px integrate` should happen at all.
+- **Not a guaranteed throughput multiplier.** The observed gain varies with context. In the data we have, it ranges from roughly **+57%** on strict user-value output to about **+1,280%** on total completed-mission throughput in a later productized setup. Those are both real observations, but they are different mission-output measures and should be labeled that way.
+
+## Current status
+
+**Alpha, local-first, and best suited to operators comfortable with Git and CLI workflows.**
+
+- **Distribution:** Local `npm pack` + global install is the current install path. The scoped package `@magnusekdahl/parallix` will be available on the public npm registry after the operator publishes (ADR 0044, ADR 0046). No Homebrew, no Docker image, no standalone binary, and no CI/release automation today.
+- **Review surface:** Forgejo is supported as the hosted PR viewer/publication surface, but the workflow remains local-first and can run without Forgejo when that provider is disabled.
+- **Versioning:** `CHANGELOG.md` is the versioning authority; PATCH bumps are the release discipline.
+- **Telemetry:** structured token/usage telemetry exists for the codex and claude families; the local-Qwen and mistral paths record honest zeros by design rather than fabricated numbers.
+- **Graphify:** the knowledge-graph path is supported for codex, claude, and qwen/opencode after one-time operator setup. It is optional, not a workflow prerequisite. The credible claim today is better-scoped context retrieval, not a proven token-savings benchmark.
+- **Review coverage** is best-effort, not guaranteed — see UC-4's caveats in [`docs/use-cases.md`](docs/use-cases.md).
+
+This is a tool for a local-first developer workflow on one machine, driven by an operator who reads the caveats.
+
+## Documentation
+
+- [`docs/use-cases.md`](docs/use-cases.md) — evidence-backed use-case inventory with confidence levels and red-team analysis (primary source of truth for what Parallix actually does today).
+- [`docs/authority-reference.md`](docs/authority-reference.md) — the internal operator reference: workflow modes, the authority model, agent selection, the layered validation model, checkpoint model, state mapping, command aliases, stats, persistent operator data, and the full public-distribution story.
+- [`docs/forgejo-setup.md`](docs/forgejo-setup.md) — how the Forgejo review surface, tokens, and `review` remote are bootstrapped.
+- [`docs/operator-setup.md`](docs/operator-setup.md) — one-time Graphify skill installation for codex, claude, and qwen/opencode.
+- [`docs/readme-rewrite-benchmark.md`](docs/readme-rewrite-benchmark.md) — how comparable developer-tool READMEs are structured, and the decisions behind this one.
+- [`AGENTS.md`](AGENTS.md) — hard rules, restricted actions, and verification entrypoints.
+- `docs/adr/` — architecture decision records, including ADR 0044 (distribution model).
+
+## Development
+
+```sh
+npm test     # FORCE_COLOR=0 node --test test/*.test.js
+```
+
+The test suite is the verification gate this repo declares in `workflow.config.json`. Run it before integrating any change. Contributions follow the same mission lifecycle the tool itself runs: branch, worktree, checkpoints, a second review, and a passing gate before integration.
+
+If you are developing Parallix itself from a checkout, the repo-root dispatcher is:
+
+```sh
+node index.js <command>
+```
+
+## License
+
+Copyright (C) 2026 Magnus Ekdahl.
+
+Parallix is free software: you can redistribute it and/or modify it under the terms of the **GNU Affero General Public License** as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See [`LICENSE`](LICENSE) for the full text.
+
+The AGPL covers Parallix itself and any modified or network-hosted fork of it. Running `px` as a tool inside your own repository does **not** make your project a derivative work — your code remains entirely yours under whatever terms you choose.

package/config/agents.json

@@ -0,0 +1,25 @@
+{
+  "_comment": "Per-step agent eligibility policy. Modify to change which agents are eligible for each workflow step.",
+  "_weights_comment": "Weights are relative integers (not percentages). Agent is selected by weighted random draw from eligible-and-supported set. Omit weights to use equal probability.",
+  "steps": {
+    "draft": {
+      "eligible": ["codex", "qwen", "mistral"],
+      "selection": "random"
+    },
+    "active": {
+      "eligible": ["codex", "claude",  "qwen", "mistral"],
+      "selection": "random"
+    },
+    "conflict-resolution": {
+      "eligible": ["claude", "codex", "mistral"],
+      "selection": "random"
+    },
+    "review": {
+      "eligible": ["codex", "claude", "qwen", "mistral"],
+      "selection": "random"
+    }
+  },
+  "overrides": {
+    "_comment": "CLI parameters are the preferred override mechanism: use --agent <family> with 'draft', --implementer <family> with 'active', or --implementer/--reviewer with 'review'. The WORKFLOW_AGENT env var remains available as a fallback for backward compatibility."
+  }
+}

package/config/agents.local.json.template

@@ -0,0 +1,8 @@
+{
+  "_comment": "Example only. The effective operator blocklist is <PARALLIX_HOME>/agents.local.json. On first use, legacy workflow/config, repo-root, and main-worktree files migrate in that order without deletion. Automatic usage-limit blocks are written to PARALLIX_HOME and apply across target repositories. Use `YYYY-MM-DD HH` for `until`.",
+  "blocklist": {
+    "gemini": { "until": "2026-05-01 12" },
+    "claude": { "until": "2026-05-02 09" },
+    "glm": { "until": "2026-04-30 18" }
+  }
+}

package/config/state-map.json

@@ -0,0 +1,4 @@
+{
+  "ready": "refined",
+  "approved": "ready-for-integration"
+}

package/config/state-map.json.template

@@ -0,0 +1,31 @@
+{
+  "_comment": "Maps virtual workflow states to your board's actual state names. Remove this _comment key before use.",
+
+  "_virtual_states": "draft → ready → active → review → approved → done",
+
+  "_examples": {
+    "3-state board (Backlog.md defaults: To Do / In Progress / Done)": {
+      "draft": "To Do",
+      "ready": "To Do",
+      "active": "In Progress",
+      "review": "In Progress",
+      "approved": "In Progress",
+      "done": "Done"
+    },
+    "4-state board (backlog / in-progress / review / done)": {
+      "draft": "backlog",
+      "ready": "backlog",
+      "active": "in-progress",
+      "review": "review",
+      "approved": "review",
+      "done": "done"
+    },
+    "Backlog.md defaults (no mapping needed — identity)": {}
+  },
+
+  "_instructions": [
+    "1. Copy only the block that matches your board into a new workflow/config/state-map.json.",
+    "2. Remove the _comment, _virtual_states, _examples, and _instructions keys.",
+    "3. If your board uses the default Backlog.md state names (draft, active, done, etc.), no state-map.json is needed."
+  ]
+}

package/config/workflow.config.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/magnus/parallix/workflow.config.schema.json",
+  "title": "Workflow (parallix) optional override config",
+  "description": "Optional per-repository override for the workflow runtime. The tool ships code-owned defaults and runs with no config file; create workflow.config.json only to override a default. Every section and field is optional and is merged over the built-in defaults. Run `px config` to print the effective configuration.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "product": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "targetUser": { "type": "string" }
+      }
+    },
+    "adapters": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "tasks": {
+          "type": "object",
+          "description": "Task tracker and on-disk task storage.",
+          "additionalProperties": true,
+          "properties": {
+            "provider": { "type": "string", "description": "Task tracker provider, e.g. backlog-md." },
+            "stateMap": { "type": "string", "description": "Repo-relative path to the virtual-to-actual Backlog state map." },
+            "storage": {
+              "description": "Task storage directory (string) or an object with tasksDir/completedDir.",
+              "oneOf": [
+                { "type": "string" },
+                {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "properties": {
+                    "tasksDir": { "type": "string" },
+                    "completedDir": { "type": "string" }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "missions": {
+          "type": "object",
+          "description": "Mission document layout and branch/worktree conventions.",
+          "additionalProperties": true,
+          "properties": {
+            "baseDir": { "type": "string", "description": "Base directory for mission documents." },
+            "branchPrefix": { "type": "string", "description": "Branch name prefix for missions, e.g. mission/." },
+            "worktreePattern": { "type": "string", "description": "Worktree path pattern, e.g. ../<repo>-<slug>." },
+            "primaryBranch": { "type": "string", "description": "Primary branch override if not auto-detected." }
+          }
+        },
+        "verification": {
+          "type": "object",
+          "description": "Repository gate command.",
+          "additionalProperties": true,
+          "properties": {
+            "command": { "type": "string", "description": "Gate command; supports {{area}} substitution." },
+            "defaultArea": { "type": "string", "description": "Default verification area." }
+          }
+        },
+        "stats": {
+          "type": "object",
+          "description": "Repository mission statistics data.",
+          "additionalProperties": true,
+          "properties": {
+            "path": { "type": "string", "description": "Repo-relative path to the workflow stats CSV." }
+          }
+        },
+        "review": {
+          "type": "object",
+          "description": "Review surface. An unset provider keeps the lifecycle running without a mirrored review provider; set provider to 'forgejo' (with baseUrl, remote, repo) to enable Forgejo, or 'none' to run without one.",
+          "additionalProperties": true,
+          "properties": {
+            "provider": { "type": ["string", "null"], "enum": ["forgejo", "none", null] },
+            "baseUrl": { "type": "string" },
+            "remote": { "type": "string" },
+            "repo": { "type": "string" }
+          }
+        },
+        "agents": {
+          "type": "object",
+          "description": "Agent adapter settings. Agent launcher commands are resolved from PATH and configured via operator-local environment, not this file.",
+          "additionalProperties": true,
+          "properties": {
+            "models": {
+              "type": "object",
+              "description": "Optional per-agent-family LLM model override, keyed by agent family name (e.g. codex, claude, gemini, glm, mistral, qwen). Each value is the model identifier passed to that agent's CLI. A family that is not listed sends no model parameter, so the agent uses its own default. There is no 'default' key.",
+              "additionalProperties": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/docs/adr/0031-ai-agent-instruction-boundary-and-command-floor.md

@@ -0,0 +1,114 @@
+# ADR 0031: AI Agent Instruction Boundary and Bounded Command Floor
+
+**Status:** Accepted
+**Date:** 2026-03-31
+
+## Context
+
+ADR 0023 established the repo's AI SDLC authority stack:
+
+- `AGENTS.md` as the repo-wide authority
+- locked `MISSION.md` as the execution contract
+- prompt files under `docs/agent-prompts/` as mode-specific workflow guidance
+- mission branches and worktrees as the execution boundary
+
+ADR 0026 then added Backlog as the current-state and recovery surface.
+
+That architecture created a new security question: agents now intentionally read large volumes of repo text, Backlog task text, and Forgejo review text. Some of that text is authoritative, but much of it is merely informative and can be stale, misleading, or adversarial.
+
+The current repo also exposes an execution-surface asymmetry:
+
+- repo policy is explicit about a safe local command floor and hard production boundaries
+- Claude's repo-visible allowlist additionally permits `python -c` and `python3 -c`, which are broader than the explicitly enumerated floor and provide a generic scripting escape hatch if untrusted text is followed too literally
+
+The threat-model mission behind this ADR concluded that the main practical risk is not a single "malicious file." It is instruction laundering across mixed-trust text surfaces: PR comments, task descriptions, docs, and checkpoint artifacts being treated as if they could override the mission contract.
+
+## Decision
+
+Adopt an explicit instruction-boundary rule for the repo AI SDLC:
+
+1. The only repo-visible instruction-bearing artifacts for execution are:
+   - `AGENTS.md`
+   - relevant subdirectory `AGENTS.md`
+   - the locked `MISSION.md` for the current mission
+   - the mode prompt explicitly loaded for the current session
+   - direct human instructions in the current session
+2. Other consumed text is untrusted data unless the human explicitly promotes it into mission scope:
+   - Backlog descriptions, notes, and references
+   - Forgejo PR descriptions, comments, and review comments
+   - general docs, checkpoint artifacts, and code comments
+   - tool and MCP output
+3. Repo-managed command permissions should stay reviewable and as close as practical to the explicitly documented safe local command floor, but the repo may keep broader autonomy affordances when the operator cost of removing them is too high.
+4. The repo explicitly accepts the residual risk of keeping `python -c` and `python3 -c` in Claude's repo-visible allowlist. This is a conscious autonomy tradeoff, not an accidental gap.
+
+## Consequences
+
+### Positive
+
+- The most important trust boundary becomes explicit rather than implied.
+- Prompt injection through PR comments, task notes, and docs is easier to reason about because those surfaces are now formally classified as data.
+- The trust-boundary rule is explicit even when the runtime command surface remains somewhat broader for autonomy reasons.
+- Future workflow docs can be reviewed against a clear question: "is this authoritative instruction, or merely informative text?"
+
+### Negative
+
+- Agents still need to read untrusted text to operate, so this does not remove the attack surface.
+- Claude's generic local scripting path remains available, so prompt-injection blast radius is not minimized as aggressively as it could be.
+- Codex/Gemini still depend more on runtime/wrapper controls than repo-visible deny rules, so enforcement symmetry remains imperfect.
+
+## Alternatives Considered
+
+### Keep the current implicit boundary and rely on agent judgment
+
+Positive:
+
+- No workflow or config churn.
+
+Negative:
+
+- Leaves instruction laundering under-specified.
+- Makes review of workflow-security changes less objective.
+
+### Ban agents from reading PR comments, Backlog notes, or general docs
+
+Positive:
+
+- Reduces direct prompt-injection exposure.
+
+Negative:
+
+- Breaks normal execution and review workflows.
+- Discards information the repo explicitly depends on.
+
+### Remove `python -c` and `python3 -c` from Claude's repo-visible allowlist
+
+Positive:
+
+- Narrows the most generic local scripting path exposed in repo-visible config.
+- Better aligns Claude's allowlist with the explicit command floor.
+
+Negative:
+
+- Reduces normal agent autonomy for legitimate repo-local transforms.
+- In this repo/runtime, that operator friction is judged worse than the marginal security gain.
+
+### Keep `python -c` and treat it as an accepted risk
+
+Positive:
+
+- Preserves maximum local scripting flexibility.
+- Preserves the repo's autonomy-by-default operating model for legitimate local work.
+
+Negative:
+
+- Leaves a generic arbitrary-execution path in the allowlist that is broader than the documented floor.
+- Increases the blast radius of command suggestion laundering.
+
+Decision: chosen.
+
+## Links
+
+- [ADR 0023](0023-ai-sdlc-configuration.md)
+- [ADR 0026](0026-ai-task-state-and-agent-recovery-surface.md)
+- [AI agent threat model](../security/ai-agent-threat-model.md)
+- [Mission](../missions/2026/ai-agent-prompt-injection-threat-model-and-mitigation-design/MISSION.md)

package/docs/adr/0032-mission-refinement-state-and-usage-budget-signals.md

@@ -0,0 +1,135 @@
+# ADR 0032: Mission Refinement State and Usage-Budget Signals
+
+**Status:** Accepted
+**Date:** 2026-04-03
+**Supersedes:** ADR 0026 in part (mission lifecycle specifics only)
+
+## Context
+
+ADR 0026 adopted Backlog.md as the repo's current-state and recovery surface and fixed the first mission lifecycle at:
+
+- `backlog`
+- `active`
+- `review`
+- `approved`
+- `done`
+
+This ADR is not a duplicate of ADR 0026.
+
+- ADR 0026 decided that Backlog.md is the repo's current-state and recovery surface.
+- ADR 0032 decides how mission selection and pre-activation readiness work inside that current-state model.
+
+That rollout solved the "what is current right now?" problem, but later workflow use exposed a selection gap:
+
+- `backlog` was doing too much work as a state
+- draft stubs, incomplete mission ideas, and genuinely shovel-ready missions were all mixed together
+- the workflow had no explicit place to park a mission that already had a proper `MISSION.md` and passed docs verification, but was not yet chosen for execution
+- mission selection still lacked a lightweight, shared way to express whether a mission fit inside the practical AI usage budget of the current workflow
+
+The result was unnecessary ambiguity during pickup decisions. A mission could look well-specified in practice while still reading as generic `backlog`, and agents had no canonical place to record whether the mission should be activated as-is, split first, or deferred because it would likely overrun current AI-session and review budget.
+
+## Decision
+
+Adopt a six-state target mission lifecycle for the workflow:
+
+- `backlog`
+- `ready`
+- `active`
+- `review`
+- `approved`
+- `done`
+
+State meanings:
+
+- `backlog`: idea stub, queued mission, or incomplete draft; a proper execution-ready mission contract does not yet exist
+- `ready`: a proper `MISSION.md` exists, follows the repo mission shape, includes `## Refinement Signals`, and passes `./scripts/verify-local.sh docs`; the mission is shovel-ready and waiting for deliberate pickup (backlog.md actual state: `refined`)
+- `active`: execution is underway in the mission worktree
+- `review`: external review is underway and the review surface already exists
+- `approved`: implementation and review are complete; only human/main-checkout merge follow-through remains (backlog.md actual state: `ready-for-integration`)
+- `done`: the mission is integrated or otherwise conclusively closed
+
+Also adopt one explicit place for selection metadata:
+
+- store refinement metadata in `MISSION.md` under `## Refinement Signals`, immediately after `## Why Now`
+- do not create custom Backlog task fields for this metadata; Backlog status plus notes/references remain the current-state layer
+
+`## Refinement Signals` must contain:
+
+- `Estimated agent % usage limit`: one of `0-25%`, `25-50%`, `50-75%`, `75-100%`, `100%+`
+- `Confidence`: `High`, `Medium`, or `Low`
+- `Selection note`: `activate as-is`, `split first`, or `defer`, with one short reason
+- `Main drivers`: the 2-4 factors driving the estimate
+
+Interpretation rule for `% usage limit`:
+
+- it is an approximate share of a meaningful AI-assisted execution budget under the current repo workflow
+- it may reflect scope breadth, trust-tier sensitivity, validation burden, review/handoff overhead, context churn, and cross-surface coupling
+- it is a selection aid, not a delivery promise or pseudo-scientific schedule estimate
+
+Default activation guidance:
+
+- `0-25%` or `25-50%`: normally safe to activate as-is when confidence is not low
+- `50-75%`: split first unless the mission is unusually high leverage and already sharply bounded
+- `75-100%` or `100%+`: defer or split before activation under normal conditions
+- if confidence is `Low`, keep refining instead of treating the estimate as reliable enough for pickup
+
+Current rollout blocker:
+
+- the repo config carries `refined`, and first-class `refined` support is now live in the Backlog MCP toolchain.
+- this ADR therefore changes the workflow contract immediately, and the live task-state implementation is fully supported.
+
+## Consequences
+
+### Positive
+
+- The workflow now distinguishes "not ready yet" from "ready, but not yet started."
+- Mission comparison becomes more deliberate because shovel-ready candidates can be compared without immediately activating them.
+- The `% usage limit` signal is lightweight enough to aid selection without creating a second planning system.
+- `MISSION.md` remains the detailed execution contract while Backlog stays the current-state surface.
+
+### Negative
+
+- The lifecycle gains one more state conceptually, so operators must learn one more transition.
+- Some older workflow docs and historical artifacts will continue to mention the earlier five-state model.
+- `% usage limit` still depends on judgment and may drift if agents stop recording the main drivers behind the estimate.
+
+## Alternatives Considered
+
+### Keep the five-state lifecycle and treat "shovel-ready" as a note inside `backlog`
+
+Positive:
+
+- No lifecycle change.
+- No Backlog config update required.
+
+Negative:
+
+- Keeps draft stubs and execution-ready missions mixed together.
+- Makes pickup decisions depend on deeper reading and tribal interpretation.
+
+### Add custom metadata directly to Backlog tasks
+
+Positive:
+
+- Puts all selection data on the board surface.
+
+Negative:
+
+- Turns Backlog into a second mission-template system.
+- Pushes schema/tooling churn into the current-state layer instead of keeping detailed reasoning in `MISSION.md`.
+
+### Use numeric scoring or story points instead of usage-limit bands
+
+Positive:
+
+- Feels more precise for ranking.
+
+Negative:
+
+- Encourages false precision.
+- Creates higher calibration cost than the workflow can realistically sustain.
+
+## Links
+
+- [ADR 0026](0026-ai-task-state-and-agent-recovery-surface.md)
+- [Mission](../missions/2026/task-024-mission-complexity-estimation/MISSION.md)