@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/routines/decision-lifecycle/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: decision-lifecycle
+description: Author and track Architecture Decision Records. Routed to when the user invokes /adr to record a new decision or /adr-status to list ADR health. Authors numbered, dated, user-attributed ADRs under .codearbiter/decisions/, maintains supersede chains, and reports status read-only. Never authors an ADR as its own judgment — every ADR carries explicit user attribution.
+---
+
+# decision-lifecycle
+
+Author and track ADRs. Routed to when the user invokes `/adr "<title>"` (author a new ADR) or `/adr-status [--adr N]` (list ADR health, read-only). Every ADR is user-attributed — this skill never records a decision the user did not explicitly make.
+
+The append-only decision-log format (entry fields, supersession protocol) lives in `<plugin-root>/includes/smarts/decision-log-format.md`. Read it before writing a log line; do not restate it here.
+
+**Boundary with `decision-variance`.** This skill owns ADR *authoring* and *status* (`/adr`, `/adr-status`) — recording a decision the user has already made, and reporting ADR health. `decision-variance` owns *arbitration* — detecting variances between artifacts and the scaffold, scoring options via SMARTS, and the decision log itself. The two share the canonical SMARTS reference under `<plugin-root>/includes/smarts/` (`core.md` for scoring, `decision-log-format.md` for the log) and one ADR template (`references/adr-template.md`); they are one domain split by responsibility, not duplicated. When a decision needs *making* (competing options), route to `decision-variance`; when it needs *recording* (already decided), stay here.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess a path:
+
+- `<project-root>/.codearbiter/decisions/` — the ADR directory and existing records. Create it on first `/adr` if absent.
+- For `/adr`: confirm the user explicitly authorized this decision and supplied (or confirmed) its content. An ADR is never authored as the disposition of a routine finding.
+
+## Phase 1 — Index · gate: BLOCK
+
+Scan `<project-root>/.codearbiter/decisions/` for existing `NNNN-*.md` ADR files. Record each by **filename stem** (`0014-githook-shim-dropin-fail-closed`), title, and status. Determine the next sequential number (no gaps) for `/adr`; for `/adr-status` this is the working set.
+
+**The stem is the identifier; the number is only a sort key.** Two ADRs may already share a number — this repository holds two numbered 0014 — so a bare number can name more than one document. Index by stem, and never assume `NNNN` resolves to one file until you have checked.
+
+Gate: the existing ADRs are indexed by stem and, for `/adr`, the next number is fixed and **unused** — a number already taken by an existing stem is not available, even for an unrelated decision.
+
+## Phase 2 — Author (/adr) · gate: STOP
+
+Confirm the decision content with the user — context, the decision itself, alternatives, consequences. MUST NOT fill these from inference. Surface any unknown as an inline `[CONFIRM-NN]` placeholder; do not resolve it by guessing.
+
+**Drop the authoring marker first.** The `pre-write`/`pre-edit` hooks block any write to `.codearbiter/decisions/NNNN-*.md` unless a fresh authoring marker is present — that block is the mechanism enforcing "ADRs only via `/adr`" (ORCHESTRATOR §3), so the sanctioned path must arm it itself. Immediately before writing, create the marker at the path the hooks check (project root = git top level):
+
+```bash
+mkdir -p "$(git rev-parse --show-toplevel)/.codearbiter/.markers"
+touch "$(git rev-parse --show-toplevel)/.codearbiter/.markers/adr-authoring-active"
+```
+
+The marker is honored for 30 minutes. Then write `<project-root>/.codearbiter/decisions/NNNN-<slug>.md` using the canonical ADR template — `<plugin-root>/routines/decision-lifecycle/references/adr-template.md` (the single source of truth for the ADR shape, shared with `decompose`). Author it with `status: proposed`. If this decision supersedes an existing one, set `supersedes:` to that ADR's **full filename stem** — `supersedes: 0014-githook-shim-dropin-fail-closed`, never `supersedes: 0014` — and leave the prior ADR's file untouched (forward-only chain — do not edit it to add a back-reference).
+
+If the new ADR supersedes only *part* of the prior decision, say which part in the body. `supersedes:` names a document, not a clause, so a chain may legitimately fork — two ADRs can each supersede different clauses of one predecessor. That fork is correct and must not be "repaired"; only the prose can carry the scope.
+
+After writing the ADR, append a corresponding entry to the decision log per the format in `<plugin-root>/includes/smarts/decision-log-format.md` — `Decided by:` names the user. Status transitions (`proposed → accepted → superseded | rejected`) require explicit user instruction; never advance status on this skill's own judgment.
+
+**`governs:` makes the decision live.** When an ADR names path globs in `governs:`, the post-write
+hook surfaces a one-line notice on any Write/Edit touching a matching file — "this file is governed
+by ADR-NNNN" — so a recorded decision pushes back at edit time instead of waiting for a checkpoint
+sweep. Offer the field whenever a decision constrains identifiable files; omit it for decisions
+without a file footprint. Globs are fnmatch-style against repo-relative forward-slash paths.
+
+Once the ADR file and its log entry are written (and any user-instructed status edit is applied), remove the marker — it exists only for one authoring pass:
+
+```bash
+rm -f "$(git rev-parse --show-toplevel)/.codearbiter/.markers/adr-authoring-active"
+```
+
+Gate: the ADR file is written with a real `decided-by` user attribution, numbered without a gap, and its log entry is appended. An ADR with no user attribution, or authored as the disposition of a finding, does not pass — STOP.
+
+## Phase 3 — Status (/adr-status) · gate: BLOCK
+
+Read-only. For each ADR (or the `--adr N` target), report: stem, title, status, date, and supersession state — found by scanning forward for any later ADR whose `supersedes:` **resolves to** it.
+
+Resolve a `supersedes:` value like this, and never guess:
+
+- The value is a **stem** → it names that ADR. Done.
+- The value is a **bare number** → collect every stem with that number. Exactly one → it names that ADR. More than one → **ambiguous: report it as an error and resolve nothing.** Zero → a dangling reference; report that too.
+- `none` (or empty) → no predecessor.
+
+`.github/scripts/check_adr_identity.py` enforces this same rule mechanically in CI; if it disagrees with this report, the report is wrong.
+
+If a supersession candidate contradicts an `accepted` ADR with no clear direction, do not pick one — flag it for `/conflict`.
+
+```
+## ADR Status — YYYY-MM-DD
+
+### Active
+- ADR-NNNN-<slug> — <title> — <status> (<date>)
+
+### Superseded
+- ADR-NNNN-<slug> — <title> — superseded by ADR-MMMM-<slug>
+
+### Ambiguous supersession
+- ADR-NNNN-<slug> — supersedes: <value> names <N> ADRs (<stems>) — unresolved
+
+### Unresolved CONFIRM-NN
+- ADR-NNNN-<slug> — [CONFIRM-NN]: <text>
+```
+
+Every ADR is named by its stem, so a shared number never collapses two rows into one. An empty section is marked "None" — not omitted. MAY dispatch `decision-challenger` (`<plugin-root>/agents/decision-challenger.md`) to stress-test an ADR; optional, never forced.
+
+Gate: every indexed ADR appears with its current status and supersession state; no `[CONFIRM-NN]` resolved; no file modified.
+
+## Hard rules
+
+- MUST author an ADR only via `/adr` with explicit user attribution. MUST NOT author an ADR as the disposition of a routine finding — an out-of-scope finding gets an inline `[NEEDS-TRIAGE]` marker instead.
+- MUST NOT record a decision the user did not explicitly make. "Use your best judgment," "I trust you" are declined.
+- MUST NOT resolve a `[CONFIRM-NN]` placeholder by guessing. Surface it and stop.
+- MUST NOT advance an ADR's status without explicit user instruction.
+- MUST NOT edit a prior ADR or a prior decision-log entry to add a back-reference — supersession is a forward-only chain; append a new record whose `supersedes:` names the prior one.
+- **The never-edit rule protects decision CONTENT, not identifiers.** Rewriting what was decided corrupts the record; disambiguating *which document a pointer names* repairs it. Maintainer ruling, 2026-07-25: *"the never edit rule is meant to prevent this situation, not prevent this situation from being fixed."* So a correction that is provably identifier-only — a `supersedes:` value changed from a number to the stem it already meant — is permissible, and nothing else about the file is. Any such correction MUST be a single-line diff that alters not one word of any decision, MUST be visible in its own commit, and still requires the maintainer-armed `adr-authoring-active` marker. MUST NOT touch Context, Decision, Alternatives, Consequences, Risks, `status:`, `date:`, `decided-by:`, or `title:` under this allowance.
+- MUST NOT number an ADR with a gap, and MUST NOT reuse a number an existing stem already holds — a shared number makes every bare reference to it ambiguous.
+- MUST NOT modify any file under `/adr-status` — it is read-only.
+- MUST NOT force the `decision-challenger` agent — its dispatch is MAY only.

package/plugins/ca-pi/routines/decision-lifecycle/references/adr-template.md

@@ -0,0 +1,74 @@
+# Canonical ADR template
+
+The single source of truth for the shape of an Architecture Decision Record under
+`<project-root>/.codearbiter/decisions/`. Both `decision-lifecycle` (via `/adr`) and
+`decompose` (Layer 4 DRAFT ADRs) author to this exact format, so `/adr-status` and the
+`governs:` post-write hook parse every ADR the same way regardless of who wrote it.
+
+## Filename
+
+`NNNN-<slug>.md` — a zero-padded 4-digit sequential number with no gaps (`0001-…`, `0002-…`),
+numbered across the existing `decisions/` directory.
+
+**The filename stem is the ADR's identifier** — `0014-githook-shim-dropin-fail-closed`, not
+`0014`. The number alone is a sort key, not a name: this repository already holds two ADRs
+numbered 0014, so `supersedes: 0014` named two documents at once until it was disambiguated.
+Reference an ADR by its full stem everywhere a machine reads it.
+
+## File format
+
+```markdown
+---
+status: proposed
+date: YYYY-MM-DD
+title: <title>
+decided-by: <user identifier>
+supersedes: NNNN-<slug> | none
+governs: <optional, comma-separated path globs this decision constrains — e.g. src/auth/*, config/tls/*>
+---
+
+# ADR-NNNN — <title>
+
+## Status
+<Proposed | Accepted | Superseded | Rejected | Draft>
+
+## Context
+<What situation, constraint, or requirement prompted this decision?>
+
+## Decision
+<What was decided. One clear statement.>
+
+## Alternatives considered
+- **<Option A>** — <why not chosen>
+- **<Option B>** — <why not chosen>
+
+## Consequences
+<What becomes easier or harder as a result.>
+
+## Risks
+<What could go wrong; what would prove this decision wrong.>
+```
+
+## Field & status semantics
+
+- **`status:` (frontmatter) is authoritative** — `/adr-status` reads it. The `## Status` body line
+  mirrors it for human readers. Keep the two in agreement.
+- **Status lifecycle:** `proposed → accepted → superseded | rejected`. `decompose` authors Layer 4
+  ADRs as **`status: draft`** during the interview and promotes each to `status: accepted` at its
+  Phase 5 (a frontmatter `status:` edit only — never a body rewrite). Status transitions otherwise
+  require explicit user instruction; never advance status on the skill's own judgment.
+- **`decided-by:`** names the user who made the decision — real attribution, never inferred.
+- **`supersedes:`** names the prior ADR's full filename stem — `supersedes:
+  0014-githook-shim-dropin-fail-closed`, not `supersedes: 0014` — or `none`. A bare number is
+  still accepted for the legacy records that carry one, but ONLY while it names exactly one
+  ADR; once a number is shared it is an error, not a guess, and
+  this repository's own CI fails the build (the identity check is CI-only and is
+  not shipped, so a consumer enforces this rule by review rather than by script). Supersession is a forward-only
+  chain: set it on the new ADR; never edit the prior ADR to add a back-reference.
+- **`supersedes:` cannot say WHICH CLAUSE it supersedes.** A partial supersession — the new ADR
+  replaces some clauses of the prior one and leaves the rest in force — must say so in prose, and
+  a chain may legitimately fork when two ADRs supersede different clauses of one predecessor.
+  The frontmatter records only *which document*; the body records *how much of it*.
+- **`governs:`** (optional) lists fnmatch-style, repo-relative forward-slash path globs. When present,
+  the post-write hook surfaces a "governed by ADR-NNNN" notice on any Write/Edit touching a matching
+  file. Omit it for decisions without a file footprint.

package/plugins/ca-pi/routines/decision-variance/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: decision-variance
+description: Reconcile the project's architectural artifacts against the scaffold and prior decisions, then present each variance as a SMARTS analysis for the user to decide. Routed to when the user asks to arbitrate, reconcile, or consolidate architectural context, requests a variance report, mentions ADR conflicts, or asks which downstream artifacts the current state supports. Never decides alone — every arbitration is user-attributed and logged.
+---
+
+# decision-variance
+
+Reconcile the architectural artifacts against the scaffold; present variances; the user decides. This skill never arbitrates on its own — every recorded decision carries user attribution.
+
+The SMARTS lenses, cell rules, and strength labels are in
+`<plugin-root>/includes/smarts/core.md` — read it before Phase 3. The append-only decision-log
+entry format is in `<plugin-root>/includes/smarts/decision-log-format.md` — read it before
+writing a log line.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess a path or a position:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — project context and the `stage:` maturity value.
+- `<project-root>/.codearbiter/security-controls.md` — only when a variance touches a security boundary (auth, crypto, secrets). Feeds the Securable lens.
+
+Locate the three architectural artifacts by **exact** filename — `01-architecture-breakdown.md`,
+`02-phased-build-plan.md`, `03-task-backlog.md` — first under
+`<project-root>/.codearbiter/plans/`, then the project root, then `docs/`. MUST NOT
+pattern-match similar names (`architecture-draft.md`, `task-list.md`); loose matching arbitrates
+against the wrong document. If any of the three cannot be located, ask the user for the path. Do not
+infer.
+
+## Phase 1 — Locate inputs and detect stale decisions · gate: STOP
+
+Index, in addition to the three artifacts:
+
+- **Existing ADRs** — `<project-root>/.codearbiter/decisions/`. Record each by number, title, status, summary.
+- **The decision log** — `<project-root>/.codearbiter/decisions/decision-log.md`. The persistent, append-only arbitration record. Read it before generating new variances.
+- **The scaffold** — manifests, dependency files, source dirs, config, CI.
+
+If the decision log exists, run the stale check: extract each prior entry's recorded
+artifact-section hash, recompute the current SHA-256 of the cited section (heading inclusive, HTML
+comments stripped), and flag every decision whose hash changed. Surface the flagged set: "These
+prior decisions reference artifact sections that have changed. Re-evaluate, keep as-is, or mark
+superseded?" Per the user's choice — re-evaluate (treat as a new variance), keep (update the
+recorded hash to current), or supersede (prompt for a new decision, append per the supersession
+protocol in `<plugin-root>/includes/smarts/decision-log-format.md`).
+
+Gate: the three artifacts are located, ADRs and the decision log are indexed, and any stale prior
+decisions are surfaced and dispositioned by the user. A first session with no decision log skips the
+stale check and clears.
+
+## Phase 2 — Build the evidence index · gate: BLOCK
+
+For each architectural decision in the three artifacts, record: a decision ID, the artifact source
+(document, section anchor), the stated position, the scaffold evidence (file paths), and exactly one
+variance status:
+
+- `concur` — both have evidence and agree
+- `divergent` — both have evidence and disagree
+- `scaffold-silent` — artifact states a position, scaffold shows nothing
+- `artifact-silent` — scaffold implements it, artifact is silent
+- `both-silent` — neither has evidence (informational only)
+
+A decision that fits none of the project's established categories is recorded `category: UNKNOWN`
+with a note on why it does not fit, then surfaced to the user to map or name. MUST NOT invent a
+category.
+
+Gate: every artifact decision classified to exactly one status, each `divergent` /
+`scaffold-silent` / `artifact-silent` case backed by a concrete citation on both sides where
+evidence exists.
+
+## Phase 3 — Generate the variance report · gate: BLOCK
+
+For every `divergent`, `scaffold-silent`, or `artifact-silent` case, write one entry: the artifact
+position (cited with anchor), the scaffold position (cited with file paths), why it matters (1–3
+sentences), the resolution options (adopt artifact / adopt scaffold / hybrid only if a real synthesis
+exists / defer with reason), a SMARTS analysis of each option, and a recommendation with a strength
+label. `concur` and `both-silent` cases produce no entry — they live in the evidence index only.
+
+The SMARTS table follows `<plugin-root>/includes/smarts/core.md` exactly: six lenses, verdict-first cells (Strong /
+Adequate / Weak / Indifferent), the length cap, no hedging adverbs, evidence specificity. The
+recommendation carries one strength label — strong / moderate / tied.
+
+**Precedent row.** Before writing the tables, scan the existing decision log once: tally which
+lenses prior resolutions turned on (which lens was decisive, which way ties broke) and note
+decisions whose subject overlaps this variance. Under each SMARTS table, append one `Precedent:`
+line citing the 1–3 most similar prior decisions by ID and the observed pattern — e.g.
+`Precedent: D-014 (bundled over external, Available decisive), D-009; this log has broken 3 of 4
+ties toward Maintainable.` No prior decisions, or none relevant → `Precedent: none on record` —
+never invent a pattern from thin history (fewer than 3 relevant entries is "none yet established").
+Precedent informs the recommendation; it never outranks the Phase 4 authority order, and it is
+input to the user's choice, not a substitute for it.
+
+For more than ~10 open variances, group by area and present area-by-area. For a large pass (more
+than ~20 decision categories or ~50 scaffold files), MAY dispatch `scout`
+(`<plugin-root>/agents/scout.md`) to gather evidence and `grader`
+(`<plugin-root>/agents/grader.md`) to produce SMARTS analyses. Inline execution is fine for
+smaller passes.
+
+Gate: every qualifying variance has a conformant SMARTS table and a strength-labeled
+recommendation. No `concur`/`both-silent` noise in the report.
+
+## Phase 4 — Present variances and capture decisions · gate: STOP
+
+Present grouped by area, dependency-ordered within each area, one area at a time. For each variance:
+lead with the variance, present the recommendation (recommend, do not push), wait for the user's
+choice, confirm it back in one sentence, then append the decision to the log per `<plugin-root>/includes/smarts/decision-log-format.md`
+— immediately, never batched in memory.
+
+When two sources at the same authority level conflict (e.g., two `accepted` ADRs that contradict),
+record both `same-level-conflict`, surface both with their sources, treat both as silent until the
+user resolves, and record the resolution naming both sources. MUST NOT pick one on this skill's
+judgment.
+
+The user may pause at any time. Confirm the pause ("N resolved, M remaining; decisions are saved"),
+summarize the unresolved IDs, and exit. Resume reads the log, finds which variances already have
+recorded decisions, and presents only the rest.
+
+The authority order when evidence conflicts: (1) an explicit user decision this session, (2) a
+recorded log decision not yet superseded, (3) an `accepted` ADR, (4) the three artifacts
+(authoritative-by-default, not infallible), (5) scaffold implementation, (6) inferred intent (last
+resort, flagged as inference). Same-level conflicts escalate to the user.
+
+After a session resolves ADR-touching variances, MAY dispatch `decision-challenger`
+(`<plugin-root>/agents/decision-challenger.md`) to stress-test an ADR. Optional, not forced.
+
+Gate: every presented variance is either resolved with a user-attributed log entry or explicitly
+deferred. No variance is recorded against this skill's own judgment.
+
+## Phase 5 — Recommend downstream artifacts · gate: BLOCK
+
+Evaluate which downstream artifacts the current decision state supports. For each candidate report
+readiness (`ready` / `partial` / `blocked`), the reason with specific decision-ID references, the
+missing decision IDs if partial, and a recommendation (produce now / produce after named variances
+resolve / not yet). Present as a menu.
+
+Gate: this skill recommends only — it MUST NOT produce a downstream artifact without explicit user
+direction. An out-of-scope finding gets an inline `[NEEDS-TRIAGE]` marker, not an arbitration entry.
+
+## Hard rules
+
+- MUST NOT record an arbitration decision the user did not explicitly make. "Pick one," "use your best judgment," "I trust you," "we're short on time" are declined — the log requires user attribution to stay auditable. Decline, do not capitulate after repeated requests.
+- MAY treat the user explicitly accepting this skill's recommendation ("accept your recommendation," "record the recommended option") as an explicit decision; the log entry then notes the acceptance in `Decided by:`. Never volunteer this fast-path.
+- MUST match the three artifacts by exact filename; never pattern-match a similar name.
+- MUST run the stale-artifact check when a decision log exists, before generating new variances.
+- MUST NOT invent a decision category — surface an `UNKNOWN` for the user to map or name.
+- MUST NOT edit or rebuild a prior log entry — the log is append-only; supersede by appending a new entry whose `Supersedes:` references the prior one.
+- MUST NOT modify the three artifacts, scaffold, or codebase to "fix" a variance — this skill records and recommends; the user implements.
+- MUST NOT generate a variance entry for a `concur` or `both-silent` case.
+- MUST NOT produce a downstream artifact without explicit user direction.

package/plugins/ca-pi/routines/decompose/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: decompose
+description: The greenfield decomposition interview. Routed to at startup when .codearbiter/CONTEXT.md lacks the <!--INITIALIZED--> body marker and no source code exists, or when the user invokes /decompose. A senior-architect persona drives a six-layer interview, persists every layer to disk so a context reset loses nothing, then populates .codearbiter/ and locks it initialized. No project-state doc is written before the layers are solid; orchestration does not resume until the lock is set.
+---
+
+# decompose
+
+Spec the project before a line of code exists. Routed to at greenfield startup, or by `/decompose`.
+
+## Pre-flight
+
+Run these ordered checks. Each passes silently or hard-stops with a routing action — never guess:
+
+1. Read `<project-root>/.codearbiter/CONTEXT.md`. If it already carries the `<!--INITIALIZED-->` body marker on its own line, STOP — context exists. Route to normal operation.
+2. Scan for meaningful source code: any file outside `.git/`, `.codearbiter/`, `.claude/`, `ORCHESTRATOR.md`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `LICENSE`, `.gitignore`, `.gitmodules`, and standard tooling dotfiles. If any exist, STOP and route to `/create-context`.
+3. Confirm `<project-root>/.codearbiter/` exists and is writable. If not, surface the gap and STOP.
+
+All three pass → proceed to Phase 1. Later phases consume this pass-status; they do not re-run it.
+
+## Phase 1 — Persona adoption · gate: BLOCK
+
+Announce the role switch to the user, verbatim:
+
+> "Switching to decomposition mode. For this session I operate as a senior software architect and technical lead, decomposing your project vision into a complete, unambiguous specification before any code is written. Vague language will be challenged, hidden complexity surfaced, and trade-offs forced. This is a thorough interview — typically 60–110 questions across six layers; every layer persists to disk, so you can stop at any point and resume in a later session. Orchestrator mode resumes when this decomposition is locked."
+
+State the Rules of Engagement, verbatim:
+
+> **Rules of Engagement**
+>
+> - **Pacing:** ONE LAYER AT A TIME. One focused question at a time within a layer (cluster only when tightly coupled). Never advance until the current layer is solid — no hand-wavy answers, no deferred decisions, no unchallenged vague language.
+> - **Three lenses on every answer:**
+>   1. **Vague requirements** — Challenge hand-wavy language. Force concrete nouns, numbers, and verbs. "Manage" is not a verb. "We'll figure that out later" is not acceptable; every "later" becomes a `[CONFIRM-NN]` placeholder.
+>   2. **Hidden complexity** — After each layer, name what the user assumes is easy but is hard: state management, real-time sync, edge cases, data migration, multi-tenancy, role matrices, offline behavior, failure modes — anything that grows non-linearly with scale.
+>   3. **Trade-off forcing** — When a real architectural or product decision exists, frame it: "X gives you A but costs B; Y gives you C but costs D — choose." Record every forced choice as a DRAFT ADR.
+> - **Suggestions calibrated to confidence:** HIGH → recommend one option, one-line justification. MEDIUM → present 2–3 options with trade-offs, ask the deciding question. LOW → flag the gap, explain why it matters, ask the unlocking question. Never skip a gap silently; never suggest an integration without stating why.
+
+No interview question is asked yet — the Layer 1 question is asked at the end of Phase 2, after draft persistence exists, so the first answer lands on disk.
+
+Gate: persona and Rules of Engagement stated. Advance to Phase 2, never directly to Phase 3.
+
+## Phase 2 — Draft persistence (or resume) · gate: BLOCK
+
+The Phase 3 interview accumulates 60–110 Q/A turns across six layers. Without per-layer disk persistence, an auto-compaction event silently destroys earlier reasoning and any DRAFT ADRs. This phase plus the per-layer write rule in Phase 3 plus the disk re-read in Phase 4/5 make the skill compaction-resilient: every layer is durable the moment its gate clears.
+
+Check for an existing draft directory at `<project-root>/.codearbiter/.decompose-draft/`.
+
+**If it exists with `_session.md` and one or more `layer-N-*.md` files — Resume mode:**
+
+- Read `_session.md` and every `layer-*.md` present. Read every `<project-root>/.codearbiter/decisions/*.md` with `status: draft` (prior-session draft ADRs to carry forward).
+- Present a numbered summary: prior-session timestamp, captured layers by name, count of DRAFT ADRs.
+- Ask the user to choose: **(a) Resume** — continue from the next unfinished layer, treating captured layers as solid; **(b) Restart** — delete the draft directory and every `status: draft` ADR, begin fresh; **(c) Abort** — exit the skill, leave draft directory and DRAFT ADRs intact.
+- On Resume: re-establish each captured layer as solid, then enter Phase 3 at the next unfinished layer. On Restart: delete `.decompose-draft/` and every DRAFT ADR, then fresh-init below. On Abort: exit cleanly; never silently delete.
+
+**If no draft directory exists (or after Restart) — fresh init:**
+
+- Create `<project-root>/.codearbiter/.decompose-draft/`.
+- Write `_session.md` recording the ISO-8601 start timestamp, the invoking identity (`git config user.email`), `Status: in-progress`, and a note that this directory is session state, auto-deleted on Phase 6 completion, and that re-invoking `/decompose` after interruption enters Resume mode.
+- Ensure `.codearbiter/.decompose-draft/` is gitignored — append the entry to `<project-root>/.gitignore` if absent.
+
+Then ask the first Layer 1 question to open the interview:
+
+> "Describe your solution vision in your own words. What problem does it solve, and for whom?"
+
+Gate: Phase 3 does not begin until either (a) the draft directory exists with `_session.md` and is otherwise empty (fresh start), or (b) prior layers are replayed and the user explicitly chose Resume.
+
+## Phase 3 — Layered interview · gate: BLOCK
+
+Run the six layers in strict sequence. Never skip a layer. Never advance until the current layer is solid — no open "later" items unless recorded as `[CONFIRM-NN]`, no unchallenged vague language, no forced trade-off left unresolved.
+
+**Per-layer disk write (compaction contract):** when a layer's "advance when" checklist is satisfied, BEFORE the first question of the next layer, write the completed layer's full Q/A record to disk:
+
+| Layer | Draft file |
+|---|---|
+| 1 — Vision & Problem | `.decompose-draft/layer-1-vision.md` |
+| 2 — Users & Flows | `.decompose-draft/layer-2-flows.md` |
+| 3 — Functional Scope | `.decompose-draft/layer-3-functional-scope.md` |
+| 4 — Technical Shape | `.decompose-draft/layer-4-tech-shape.md` |
+| 5 — Integrations & Infrastructure | `.decompose-draft/layer-5-integrations.md` |
+| 6 — Risks & Unknowns | `.decompose-draft/layer-6-risks.md` |
+
+(All under `<project-root>/.codearbiter/`.) Each file holds every question asked, the user's verbatim answer (or a faithful paraphrase), every challenge made under the three lenses, every `[CONFIRM-NN]` raised, and every DRAFT-ADR title generated. These files are the authoritative record — Phases 4 and 5 read from them, not from conversation context. The next layer does not begin until the prior layer's file exists on disk and is non-empty; if a write fails, surface the error and do not advance.
+
+**Layer 4 immediate ADR drafts:** each forced architectural choice in Layer 4 is written at the moment it is made as `<project-root>/.codearbiter/decisions/NNNN-<slug>.md`, numbered sequentially across the existing `decisions/` directory. Do not batch the writes. Author each using the canonical ADR template — `<plugin-root>/routines/decision-lifecycle/references/adr-template.md` (the single source of truth, shared with `decision-lifecycle`) — with frontmatter `status: draft` and `decided-by:` set to the user (or "user" if anonymous). Fill `## Context`, `## Decision`, and `## Consequences` from the forced choice; leave `## Alternatives considered` and `## Risks` populated where the interview surfaced them, or as `<none recorded>`. Phase 5 promotes each to `status: accepted`.
+
+**Layer 1 — Vision & Problem.** Unlock: the specific problem and the evidence it is real (not assumed); the primary user and any conflicting user types (name and resolve the conflict, or flag it); the demo-to-a-skeptic definition of "working"; what this project explicitly is NOT building. Advance when: problem concrete, primary user named, "working" demonstrable, NOT-building list explicit.
+
+**Layer 2 — Users & Flows.** Unlock: the core user journey from first touch to value delivered, in specific steps; every non-human actor at MVP (scheduled jobs, webhooks, callbacks, external triggers); failure-mode UX (concrete, not "we'll show an error"); admin/ops/internal privilege model. Advance when: end-to-end journey specific, non-human actors named, failure UX defined, privilege model sketched.
+
+**Layer 3 — Functional Scope.** Unlock: every capability, challenged individually — what it does (concrete verbs), who initiates it, inputs and outputs; each capability classified MVP / v1 / later; the hardest user-facing problem (the one that invalidates the product if wrong); every "later" forced to closure or recorded as `[CONFIRM-NN]`. Advance when: capability list complete and every item classified; no unresolved "later" except as `[CONFIRM-NN]`.
+
+**Layer 4 — Technical Shape.** Unlock: components and ownership (what each owns, where the boundaries are); core data entities, relationships, cardinality; where state lives and how it changes (write paths); the hardest technical problem; hard constraints (stack, runtime, cloud, compliance, budget, team size and skill); the copyright holder for new-file headers (record in `coding-standards.md`; if undecided, record as `[CONFIRM-NN]`); a forced trade-off for every major architectural decision (e.g. monolith vs. services, sync vs. async); **release intent** — the tag prefix the user wants (e.g. `v`), and whether a `CHANGELOG.md` is kept at all. Each forced choice is written immediately as a `status: draft` ADR per the rule above. Advance when: all components named, all entities sketched, all hard constraints recorded, every major trade-off resolved or deferred as `[CONFIRM-NN]`, release intent captured, AND `layer-4-tech-shape.md` is on disk with one DRAFT ADR per forced choice.
+
+**Release intent is elicited here, but no `.codearbiter/release-targets.md` row is ever written by this skill.** This lane runs before any manifest or tag exists — greenfield has no `package.json` version field, no `Cargo.toml`, no committed tag to anchor a `prefix` against — so there is nothing yet to substantiate a full row (`manifest`, `payload`, an actual declared file `load_targets` could parse). Record the two answers (tag prefix preference; changelog kept y/n) in `layer-4-tech-shape.md` alongside the rest of the layer's Q/A, for `context-creation`'s back-fill (once source exists) or `/release`'s own back-fill lane (once a manifest and tag exist) to substantiate later. Writing a guessed row now, ahead of anything to check it against, is exactly the invented-shape failure both of those later lanes exist to refuse.
+
+**Layer 5 — Integrations & Infrastructure.** Unlock: every external dependency (APIs, services, data sources, auth providers, payment processors, notification services), each named; commodity vs. differentiator for each; actual API contracts, data formats, and auth mechanisms for any system being integrated with; integration risks per dependency (rate limits, reliability and fallback, data ownership and portability, cost at scale). Advance when: all dependencies named, commodity/differentiator classified, integration risks surfaced for each.
+
+**Layer 6 — Risks & Unknowns.** Unlock: the top three build-killing risks, each with probability, impact, mitigation; the lowest-confidence areas; spike candidates (what question each answers, cost of being wrong, time-box); the signals and decision points that would force a major architecture change mid-build. Advance when: top three risks named with mitigations, spike candidates identified, architecture-change triggers named.
+
+Gate: all six layers complete (no open "later" except as `[CONFIRM-NN]`); all six `layer-*-*.md` files on disk and non-empty; at least one `status: draft` ADR present if any Layer 4 trade-off was forced — a Layer 4 with zero forced trade-offs is suspicious and is re-examined before advancing.
+
+## Phase 4 — Synthesis · gate: BLOCK
+
+Begin by re-reading every `layer-*-*.md` and every `status: draft` ADR from disk. Do NOT rely on conversation context — by now an auto-compaction may have erased the original Q/A. The on-disk drafts are authoritative; this re-read makes the phase idempotent across compaction. If any expected layer file is missing, BLOCK and surface the gap rather than synthesizing from incomplete context.
+
+Produce three artifacts and write each to disk under `<project-root>/.codearbiter/plans/` BEFORE asking for review (the user reviews from disk, which survives a session restart):
+
+1. `01-architecture-breakdown.md` — every component with responsibility and connections; a text/ASCII system diagram; every integration with its type (sync/async), protocol, and owner; every open architectural decision flagged with a `[CONFIRM-NN]` marker (numbered sequentially with `open-questions.md`).
+2. `02-phased-build-plan.md` — MVP → v1 → v2 phases; per phase a one-sentence goal, what is included, what is deferred and why (explicit rationale), key risks, and a measurable definition of done.
+3. `03-task-backlog.md` — a flat prioritized task list; each task estimable (1–5 days), assignable to one role (frontend/backend/infra/etc.), phase-grouped (MVP first), with dependencies flagged and spikes time-boxed.
+
+Present all three. Request explicit review:
+
+> "These three artifacts are written to `.codearbiter/plans/`. Open and review each one. Tell me what is wrong, incomplete, or misrepresents your intent. They are on disk now and survive a session restart, but Phase 5 will not run until you confirm they are correct."
+
+Iterate on the on-disk files in place until the user explicitly approves.
+
+Gate: all three artifact files on disk AND the user explicitly approves all three, with no unresolved objections.
+
+## Phase 5 — project-state population · gate: BLOCK
+
+Re-read every input from disk — the three approved artifacts, all six `layer-*-*.md` files, and every `status: draft` ADR. This makes population idempotent across compaction: a user may approve Phase 4, suffer a compaction, re-invoke `/decompose` (Phase 2 enters Resume, Phase 4 sees its artifacts already approved on disk), and Phase 5 proceeds from disk.
+
+Promote each `status: draft` ADR to `status: accepted` — an in-place edit of the frontmatter `status:` line (and its `## Status` body mirror) only; do not duplicate or rewrite the ADR body.
+
+Then write the surviving project-state docs. Every file holds actual content derived from the interview — no template boilerplate left unfilled:
+
+| Source | Destination |
+|---|---|
+| Layer 1 problem + users + NOT-building, with `arbiter: enabled` and `stage:` frontmatter | `CONTEXT.md` |
+| Layer 4 stack + hard constraints + tracker command (e.g. `gh issue create`) | `tech-stack.md` |
+| Layer 4 lint, format, naming + copyright holder | `coding-standards.md` |
+| Layer 4 compliance + crypto + trust-boundary notes (thin — banned-primitive posture only) | `security-controls.md` |
+| Layer 6 unknowns + spike candidates | `open-questions.md` (`[CONFIRM-NN]` format) |
+| Task backlog | `open-tasks.md` |
+| Carried from the `/ca-init` scaffold — confirm present, create empty if absent | `overrides.log` (append-only audit sink, with its audit header), `last-checkpoint` (`0`) |
+| Each Layer 4 forced choice | `decisions/000N-<slug>.md` — already written in Layer 4; Phase 5 only promotes Status to Accepted |
+| The three Phase 4 artifacts | `plans/01-…`, `plans/02-…`, `plans/03-…` — already written and approved; Phase 5 only verifies they exist |
+
+(All under `<project-root>/.codearbiter/`.) Set the `stage:` frontmatter value in `CONTEXT.md` to the maturity number for the MVP phase of the build plan (a single number — there is no promotion ladder).
+
+**Provenance stubs and code-map stub:** once the project-state docs above are on disk, write a provenance stub per derived doc to `.codearbiter/.provenance/<doc>.json` via `_provenancelib.write_stub` (`interview_derived: true`, empty `entries`) — one stub for each scout/source-derived doc (`CONTEXT`, `tech-stack`, `coding-standards`, `security-controls`). Also write a `.codearbiter/code-map.md` stub — a placeholder empty coarse map. WHY: greenfield has no source code yet, so real provenance entries and code-map contents populate on the first commit-gate auto-heal (or `/ca-context-check`) once code exists.
+
+Gate: every project-state doc written with real content; no `status: draft` ADRs remain in `decisions/`; `[CONFIRM-NN]` items are acceptable in `open-questions.md` for genuinely unresolved items; provenance stubs and code-map stub written.
+
+## Phase 6 — Initialization lock & cleanup · gate: BLOCK
+
+1. Write the `<!--INITIALIZED-->` body marker on its own line in `<project-root>/.codearbiter/CONTEXT.md`. A marker embedded in a template instruction comment does not satisfy the gate.
+2. List `<project-root>/.codearbiter/` and show the populated tree to the user.
+3. Confirm each required file is present and non-empty: `CONTEXT.md` (with `arbiter: enabled` + `stage:` frontmatter and `<!--INITIALIZED-->` body), `tech-stack.md`, `coding-standards.md`, `security-controls.md`, `open-questions.md`, `open-tasks.md`, `overrides.log` (append-only audit sink — create with its audit header if the scaffold left it absent), `last-checkpoint`, `decisions/` (at least one ADR, all `status: accepted`, none `status: draft`), and `plans/01-…`, `plans/02-…`, `plans/03-…`.
+4. Delete `<project-root>/.codearbiter/.decompose-draft/` and all its contents. This is mandatory — a leftover draft directory signals a still-in-progress decomposition to Phase 2 of any future `/decompose`.
+5. Announce return to normal operation:
+
+   > "Decomposition complete. Project state is initialized and locked, draft directory removed. Returning to codeArbiter orchestrator mode. Use `/ca-feature` to begin implementation, or any other command. Open questions are recorded in `.codearbiter/open-questions.md`."
+
+Gate: `<!--INITIALIZED-->` present on its own line in `CONTEXT.md`; all required files present and non-empty; no `status: draft` ADRs in `decisions/`; `.decompose-draft/` no longer exists on disk.
+
+## Hard rules
+
+- MUST NOT write any project-state file before all six layers are solid and on disk.
+- MUST NOT scaffold any cut doc — see `<plugin-root>/includes/cut-docs.md` for the canonical never-scaffold list. Maturity is the single `stage:` value in `CONTEXT.md` frontmatter.
+- MUST NOT advance a layer until its draft file exists on disk and is non-empty.
+- MUST NOT advance past a layer holding an unresolved "later" item unless it is recorded as `[CONFIRM-NN]`.
+- MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface the question and record it in `open-questions.md`.
+- MUST NOT synthesize artifacts (Phase 4) or populate context (Phase 5) from conversation context — re-read the on-disk drafts first.
+- MUST NOT proceed past Phase 4 without explicit user approval of all three artifacts.
+- MUST NOT leave any `status: draft` ADR in `decisions/` after Phase 5.
+- MUST NOT close the skill while `.decompose-draft/` still exists, or while `CONTEXT.md` lacks the `<!--INITIALIZED-->` body marker on its own line.
+- MUST NOT silently delete a draft directory on Resume — the user chooses Resume, Restart, or Abort.

package/plugins/ca-pi/routines/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: dispatching-parallel-agents
+description: "The parallel fan-out primitive. Routed to by any skill or command that splits work across independent units and dispatches an agent per unit — subagent-driven-development, /sprint, parallel /review. It owns the dispatch/collect/funnel discipline: bound concurrency, isolate units, collect every result, dedupe overlap, and funnel through finding-triage then checkpoint-aggregator. Raw agent output is never consumed before the funnel runs; an agent that errors drops its unit without corrupting the batch."
+disable-model-invocation: true
+---
+
+# dispatching-parallel-agents
+
+Fan out, collect everything, funnel before consuming. Plumbing other skills dispatch through — it owns the parallel discipline, not domain logic.
+
+## Pre-flight
+
+The caller supplies the work. Confirm it, or STOP and surface the gap — never invent units or pick an agent on a hunch:
+
+- **The unit list** — N discrete, independently-completable units of work, each with its scope and target paths.
+- **The agent kind** — which agent kind to dispatch per unit (e.g. `backend-author`, `frontend-author`, `scout`, `security-reviewer` at `<plugin-root>/agents/<name>.md`). One kind per batch.
+- **The completion contract** — what each agent must return: a structured result, its unit ID, and a pass/fail/error status. Self-reports are claims, not evidence (see Phase 4).
+
+## Phase 1 — Partition · gate: BLOCK
+
+Split the work into units that do not collide. A unit owns a distinct file or path set; two units in one batch MUST NOT mutate the same path.
+
+- **Independent paths** — units touch disjoint files. Dispatch directly. This is the common, fast case.
+- **Shared paths unavoidable** — units must mutate the same file or tree. Do NOT dispatch into the conflict. Route to `using-git-worktrees` (`<plugin-root>/routines/using-git-worktrees/SKILL.md`) to give each unit an isolated working tree, or serialize the colliding units into one sequential unit. A shared-path collision in a parallel batch is a corruption, not a merge.
+
+Tag each unit with its ID, scope, target paths, and the agent kind. Read-only batches (review, scout) skip the collision check — they mutate nothing.
+
+Gate: every unit has a disjoint path set, or its overlap is resolved by worktree isolation or serialization. An unresolved collision does not pass.
+
+## Phase 2 — Dispatch · gate: BLOCK
+
+Dispatch one agent per unit, bounded.
+
+- **Concurrency bound** — dispatch in waves of at most a fixed width (default 4 concurrent agents; the caller MAY override). Do not fan out unbounded; a hundred agents at once starves the batch and corrupts nothing useful.
+- **Fresh and isolated** — each agent gets only its own unit's scope and the completion contract. No agent sees another's working state. No shared mutable context between units in flight.
+- **Hard-stop propagation** — a `tdd` BLOCK, a `commit-gate` failure, a security CRITICAL, or a `[CONFIRM-NN]` inside any unit halts that unit and surfaces immediately; it does not get silently swallowed by the batch.
+
+Gate: every unit is dispatched or explicitly deferred. No unit is dropped silently at dispatch.
+
+## Phase 3 — Collect · gate: BLOCK
+
+Wait for the full wave, then the next, until every unit has terminated. Record each unit's terminal state: `DONE` (returned a result), `ERRORED` (the agent failed), or `DEFERRED` (a hard-stop surfaced).
+
+An `ERRORED` unit drops its own work — its partial output is discarded, never half-applied — and is logged against its unit ID. **One errored unit MUST NOT corrupt or discard the batch.** The remaining units' results stand. Record the error for the funnel; do not retry blindly inside this phase.
+
+Gate: every unit has a terminal state and `DONE` results are captured intact. A still-running or unaccounted unit blocks Phase 4 — partial collection does not pass.
+
+## Phase 4 — Dedupe · gate: BLOCK
+
+Parallel agents over adjacent units produce overlapping findings — the same issue reported by two units, the same fix proposed twice. Collapse them before anything downstream sees the batch.
+
+- Merge findings that name the same defect at the same location into one, keeping the highest severity reported.
+- Reconcile contradictory results across units (two units that disagree on the same fact) into a single surfaced conflict, not a silent pick.
+- Verify any "done" claim that gates real work: re-run the proving command fresh and read its output and exit code. A subagent's self-report is a claim — never trust it as evidence of completion.
+
+Gate: the result set is deduped, contradictions surfaced, and completion claims verified by fresh evidence. Raw, un-deduped agent output MUST NOT reach Phase 5.
+
+## Phase 5 — Funnel · gate: STOP
+
+The batch is consumed only here, through the fixed funnel — never directly by the caller.
+
+1. Dispatch `finding-triage` (`<plugin-root>/agents/finding-triage.md`) over the deduped result set: it classifies severity, marks out-of-scope items with an inline `[NEEDS-TRIAGE]` marker, and discards noise.
+2. Hand the triaged set to `checkpoint-aggregator` (`<plugin-root>/agents/checkpoint-aggregator.md`): it aggregates into the single batch verdict the caller consumes — pass, or a blocking finding list.
+
+The errored and deferred units from Phase 3 ride through the funnel as findings — an `ERRORED` unit is a finding the caller must see, not a silent gap.
+
+Gate: the caller receives only the aggregated verdict. Bypassing the funnel — consuming raw or merely-deduped agent output — is a gate violation. STOP and return the verdict.
+
+## Hard rules
+
+- MUST NOT dispatch two units that mutate the same path in one batch; isolate via `using-git-worktrees` or serialize.
+- MUST NOT fan out unbounded; dispatch within the concurrency bound.
+- MUST NOT let one `ERRORED` unit discard or corrupt the rest of the batch.
+- MUST NOT consume agent output before the `finding-triage` → `checkpoint-aggregator` funnel runs.
+- MUST NOT trust a subagent's self-reported completion; verify with a fresh proving command.
+- MUST NOT silently drop a unit — every unit terminates with a recorded state that rides through the funnel.