@arbiterforge/ca-pi 0.18.4 → 0.19.0

package/plugins/ca-pi/includes/author-tdd-workflow.md

@@ -1,27 +1,38 @@
-# Author TDD workflow — non-negotiable, fixed order
+# Author verification workflow
 
-Canonical for the author agents (`backend-author`, `frontend-author`, `infra-author`). Loaded via each agent's
-Required Reading; the agent bodies do not restate it. This is the worker's execution order for
-one task — the tdd skill's phase gates govern the lane above it.
-Apply `<plugin-root>/includes/verification-boundary.md` throughout.
+Use the caller's scoped obligations and selected verification approach from
+`<plugin-root>/routines/tdd/SKILL.md`. Keep each obligation tied to its source and
+proving check. Apply `<plugin-root>/includes/verification-boundary.md` for local
+checks and exact-head hosted CI.
 
-Use the Phase 1 checklist for the owning route. For a bug-origin `/fix`, carry the
-current expectation, cited evidence, supported cause, and regression oracle into
-the existing obligation ledger; confirm the original caller's repair authority and
-source freshness through the fix owner. Do not fabricate a feature artifact. For
-`/feature`, keep the approved spec and its criteria; for `/refactor`, keep its
-approved surface and parity contract. An ADR remains a user-attributed decision
-through `/adr`, never an author shortcut.
+| Route | Required evidence |
+|---|---|
+| /fix | Observe genuine target RED before repair, then fresh GREEN for the same named regression with unchanged assertions. Reuse an adequate current bug-origin RED. |
+| /feature | Keep the agreed spec and criteria. Prefer test-first work; existing implementation may use current criterion-focused checks and meaningful negative controls. Report the observed sequence accurately. |
+| /refactor | Keep the approved surface and parity contract. Establish passing characterization before restructuring and preserve baseline assertions throughout implementation. |
 
-Fixed order. Do not skip or reorder.
+For a bug-origin fix, carry the current expectation, cited evidence, supported
+cause and regression oracle into the existing obligation ledger. Check the
+original caller's repair authority and source freshness through the fix owner.
+Do not fabricate a feature artifact. An ADR remains a user-attributed decision
+through `/adr`.
 
-1. **Map failing tests** — bind each Phase 1 obligation to a test ID. For `/fix`, assess an existing failing test against target red using the current regression oracle and evidence. Name the existing test ID in the ledger and reuse that named existing target-red test when its oracle is adequate and the assertion matches the defect. Do not duplicate a test because of its age or because it predates repair. Add tests only for uncovered obligations.
-2. **Confirm tests are red for the right reason** — run the test command from `tech-stack.md`; the target failure must match the obligation. Record unrelated existing failures in the baseline; an unrelated failure is not target red. An import or setup error is not target red. Preserve and report their identities and outputs. Required commit gates remain blocked while required checks fail. Do not skip tests, suppress failures, or waive gates to proceed.
-3. **Write minimum implementation** — only enough code to make the failing tests pass; no extra scope
-4. **Run impact-bounded local suite** — rerun the same named target test for fresh green on the repaired source, with its assertions unchanged between red and green. Rerun fresh affected-contract tests on that source and record their results; exhaustive and cross-platform proof runs in exact-head hosted CI before merge
-5. **Run lint and type-check** — both clean
-6. **Stage for commit** — only after steps 1–5 complete
+Name the existing target test and reuse it when its assertion matches the defect;
+add tests for uncovered obligations. An import, setup or unrelated failure is not
+target RED. Retain unrelated baseline failures and their outputs. A material
+fixture or setup change requires renewed target RED on the broken source before
+claiming RED-to-GREEN. Preserve the regression's assertions between those runs.
 
-For a repair, observe target red on the broken source before minimum implementation. If a material fixture or setup change occurs after that observation, the earlier red no longer qualifies: repeat target red on the broken implementation with the changed fixture or setup before continuing the repair. Keep the test's assertions unchanged between red and green.
+For intermittent or timing defects, prefer a faithful deterministic seam.
+Otherwise declare a finite repeated-trial bound and failure oracle before running
+it. Report the sample limits; do not claim deterministic proof from a passing
+sample or retry until GREEN.
 
-For an intermittent or timing defect, use a faithful deterministic seam when one exists. Otherwise define a finite repeated-trial oracle with its trial bound and pass/fail rule before running it. Record the stochastic sample limit; do not claim deterministic proof from a passing sample or retry until green. A failing trial must still match the target mechanism, and fresh green remains bounded by the stated oracle.
+Implement only the assigned scope. Run its proving checks and affected existing
+contracts on the resulting source, then applicable coverage, lint and type checks.
+Preserve failures and actual user stops; never skip tests, suppress failures or
+waive required checks to obtain a pass.
+
+Return changed paths, obligation evidence, actual commands/cwd/results and pending
+checks to the caller. Stage only when that action is assigned and authorized;
+committing and publication retain their own owners and permissions.

package/plugins/ca-pi/includes/fresh-verification.md

@@ -1,14 +1,16 @@
-# Fresh-run verification
+# Current verification evidence
 
-The shared proof-by-fresh-evidence discipline. Used by `subagent-driven-development` Phase 5 (per
-accepted task, against the task's verification command) and `commit-gate` Phase 5 (the whole change,
-against the spec's acceptance criterion). Each caller supplies its own target; this is the common rule.
+Verify the caller's actual task or acceptance criterion before claiming completion.
+Read the command, cwd, relevant source and input identities, output and exit code.
+A result is reusable across execution, commit and PR preparation when those inputs
+still match and the observed behavior proves the required claim.
 
-A green suite proves the tests pass — not that the change does what was asked. Before accepting or
-committing:
-
-- **Run the proving command FRESH**, in a clean invocation, in this phase. Do not accept a logged
-  result from an earlier phase, and never trust a subagent's self-report.
-- **Read the actual output AND the exit code.** A non-zero exit, or output that does not demonstrate
-  the obligation/acceptance criterion, fails the gate and returns the work for correction.
-- A self-reported "it works" is never evidence — proof is.
+- Reuse inspected current results, including an earlier phase's result. A phase
+  transition, bookkeeping edit or new receipt ID alone requires no rerun.
+- Run the missing or affected check when evidence is absent, its inputs changed,
+  its scope is insufficient, or its outcome is unresolved. A passing general suite
+  cannot replace a missing criterion-specific check.
+- Inspect delegated command output and its source binding before relying on it.
+  A self-report without accessible evidence is insufficient.
+- Keep a relevant failure or contradictory later result visible until resolved.
+  Correct the affected work and rerun its check; preserve unrelated valid results.

package/plugins/ca-pi/includes/harvest.md

@@ -43,14 +43,14 @@ as a **GitHub issue**, not the board.
      the board BUT record one audit line (`harvest declined: N candidates from <origin>`)
      to `triage.log` (append-only — use Edit/`>>`, never Write) so the decline is
      recoverable, not invisible.
-   - **Autonomous (`/sprint`):** SMARTS-score the batch, auto-promote, and append each
+   - **Autonomous (`/sprint`):** promote in-scope follow-ups and append each
      promotion (id + `(from origin)`) to `sprint-log.md` — append-only, so use Edit/`>>`,
      never Write (H-05 blocks a Write to it). A blocking decision is never auto-promoted
      — it escalates and STOPs.
 4. **Apply.** On confirm, route each:
    - **work → `open-tasks.md`** — a queued, ID-less `- [ ] <desc>  (from <origin>)` via
-     `/ca-task add -- "<desc>" --from <origin>` (the `--` lets a desc start with `-`;
-     add `--boundaries a,b` when the extractor supplied them).
+     `/ca-task add --from <origin> -- "<desc>"`. Put optional
+     `--boundaries a,b` before `--`; the terminator lets a description start with `-`.
    - **non-blocking decision → `open-questions.md`** "Deferred decisions" (a
      non-`CONFIRM-NN` bullet with the back-ref).
    - **blocking decision → ESCALATE**, never the Deferred-decisions section: `promote`

package/plugins/ca-pi/includes/reference-map.md

@@ -19,4 +19,4 @@ then route to the owning skill or agent. This map answers *what to read before t
 | Out-of-scope finding | — | inline `[NEEDS-TRIAGE]` marker (never an ADR); promoted to `open-tasks.md` by the harvest at the workflow's terminal step |
 | Following up on workflow residue / a backlog task | `open-tasks.md` (schema), `<plugin-root>/includes/harvest.md` | `/ca-task` writer; harvest (`extract_*` → `promote`) at a terminal step |
 | Generating a user-facing deliverable (UI, report, PR/CHANGELOG prose, slide, chart) | `<plugin-root>/includes/anti-slop-design/INDEX.md` (then `core` + the medium leaf) | `design-quality-reviewer` agent |
-| Provenance drift surfaced outside a commit (merge, external edit, SessionStart drift line) | `.codearbiter/.provenance/` + `.codearbiter/code-map.md` | `context-check` skill (`/ca-context-check`) |
+| Provenance drift or requested refresh of initialized context | Selected documents + `.codearbiter/.provenance/` + `.codearbiter/code-map.md` | `context-check` skill (`/ca-context-check`); reuse the selected scope and existing authorization |

package/plugins/ca-pi/includes/routing-table.md

@@ -21,8 +21,8 @@ reached the same way.
 
 | Invocation cue | Primary route | Also dispatch | Hard gate |
 |---|---|---|---|
-| New feature | `/feature` Step 0 triage → full lane `brainstorming` → `writing-plans` → `executing-plans` → `tdd`, or logged small lane straight to `tdd` | `backend-`/`frontend-`/`infra-author` | No spec, no code; no code before `tdd` Phase 1; small lane only on all triage criteria, logged to `triage.log` |
-| Autonomous sprint | `/sprint` → `SPRINT.md` (brainstorm → plan → `subagent-driven-development`) | per-task impl authors + reviewers | One interactive spec gate; hard gates never auto-decided; every auto-decision logged |
+| New feature | `/feature` Step 0 triage → full lane `brainstorming` → `writing-plans` → `executing-plans` → `tdd`, or logged small lane straight to `tdd` | `backend-`/`frontend-`/`infra-author` | Maintain useful full-lane spec/plan and applicable tests; small lane requires its listed criteria and triage log, not another permission question |
+| Autonomous sprint | `/sprint` → `SPRINT.md` (brainstorm → plan → `subagent-driven-development`) | implementation or useful delegated authors; reviews by actual risk | No duplicate artifact approval; real host/security and unresolved material decisions remain stops; meaningful auto-decisions logged |
 | Bug fix | `/fix` → `tdd` (bug variant) | impl author | Failing regression test before any fix code |
 | Docs edit / dep bump / revert | `/chore` (type-scaled gates) | `dependency-reviewer` for deps | No behavioral code; suite green for deps/revert; exits via `commit-gate` |
 | Exploratory throwaway spike | `/spike` (self-contained command) → `spike/<slug>` branch | — | Never merges or PRs; `commit-gate`-exempt (nothing on the branch can land); exits to a findings note or `/feature` |
@@ -53,5 +53,5 @@ reached the same way.
 | Local runtime work (run, watch, exercise this repo's own app) | `mode --ops` → narrows the persona per `includes/ops-mode.md`, no skill/agent dispatch | — | Advisory only, no hook becomes mode-aware; permitted only when the operation starts, observes, or exercises and leaves no change in tracked files or git history — anything that mutates tracked files, the index, git history, or published state still routes normally |
 | Promote a workflow's un-actioned follow-ups | `includes/harvest.md` (run at a terminal step) → `/ca-task` (work) / `open-questions.md` (decision) | — | Batch-confirm interactive; SMARTS-logged auto under `/sprint`; dedup by `(from <origin>)`; a blocking decision escalates, never demoted |
 | Zero-onboarding dry-run of the reviewer fleet | `/ca-preview` (no skill; reuses `includes/review-matrix.md` to predict reviewers) | — | Read-only; writes nothing, stages nothing, `git status` unchanged; no `/ca-init` or `.codearbiter/` required; empty diff exits clean |
-| Manual drift audit of provenance-tracked docs (bypass / merge / external edit case) | `context-check` at `<plugin-root>/routines/context-check/SKILL.md` (explicit `/ca-status drift` or `/ca-context-check`) | — | Read-only unless user selects re-scout or re-baseline; MUST NOT commit on its own; not the daily loop — commit-gate auto-heal is the routine path |
+| Context drift audit or requested scoped/full refresh of initialized context | `context-check` at `<plugin-root>/routines/context-check/SKILL.md` (explicit `/ca-status drift` or `/ca-context-check`) | — | Audits are read-only; a direct refresh request selects its scope without another per-document approval. Preserve unselected content and initialized state; MUST NOT commit on its own. Commit-gate auto-heal owns routine maintenance. |
 | Deep on-demand codebase audit | `tribunal` at `<plugin-root>/routines/tribunal/SKILL.md` (explicit `/ca-tribunal` retained) | `tribunal-lens-reviewer` per active lens (+ optional `map-structure`/`map-deps` on large repos) | Read-only until the filing gate; runs only after the user acknowledges the token estimate; never blocks a merge/commit; nothing filed or sent without explicit authorization |

package/plugins/ca-pi/includes/sprint-authority.md

@@ -1,4 +1,9 @@
-# Sprint approval and delegated method authority
+# Historical sprint approval and delegated method authority
+
+This is an explicit historical attestation and recovery reference, not the normal sprint
+workflow. Load it only for a requested attestation claim or an already-observed transaction
+that needs recovery. Ordinary planning, method changes and execution use `SPRINT.md` under
+the existing authorization; do not arm this protocol to obtain permission for them.
 
 This private extension adds no registered command, skill or agent. Check that the verified installed
 native capability lists `sprint-approval-context`, `sprint-approve` and `smarts-apply`; a schema name

package/plugins/ca-pi/includes/verification-boundary.md

@@ -1,10 +1,12 @@
 # Local and hosted verification boundary
 
 Use **impact-bounded local verification** for the contributor loop. Before a
-commit or pull request, run the smallest fresh set that directly proves the
+commit or pull request, establish the smallest applicable set that directly proves the
 changed obligations and affected contracts, plus applicable lint/type-check,
 coverage, generated-artifact parity, staged secret scanning, and specialized
-security, dependency, migration, release, ADR, or deployment gates. A failing
+security, dependency, migration, release, ADR, or deployment gates. Reuse inspected
+results while their relevant source, inputs, command and obligations still match;
+run missing or affected checks. A phase transition alone does not require a rerun. A failing
 local check blocks. Do not require a repository-wide or cross-platform suite on
 the contributor's machine merely to create a commit or open a pull request.
 
@@ -25,3 +27,10 @@ gates. It never waives focused regression proof, coverage thresholds, lint or
 type-check failures, security and secret controls, dependency review, migration
 review, release invariants, ADR lifecycle proof, deployment review, or exact-head
 merge protection.
+
+Use the host relevant to the change for a needed live check. Do not require users
+to install, configure, or switch hosts to complete ordinary work. Cross-adapter
+compatibility belongs to maintainer CI; additional live-host trials require an
+explicit acceptance requirement. If the available host denies a needed action,
+report that limitation once and continue independent authorized work. Do not retry
+an unchanged denial or seek another host merely to obtain a passing result.

package/plugins/ca-pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.18.4",
+  "version": "0.19.0",
   "private": true,
   "license": "AGPL-3.0-only",
   "type": "module",

package/plugins/ca-pi/routines/INDEX.md

@@ -12,25 +12,25 @@ not both merely to repeat the same procedure. This index lists what each skill O
 
 | Skill | Routed to by | Owns |
 |---|---|---|
-| [tdd](tdd/SKILL.md) | `/feature` (after spec approval), `/fix`, `/refactor` | The test-first gate: six phases — obligation scan → red → green → obligation verify → coverage → lint. No implementation before Phase 1; no path to `commit-gate` until all six gates are green. |
+| [tdd](tdd/SKILL.md) | `/feature` (with its selected spec), `/fix`, `/refactor` | Scoped verification: regression-first fixes, behavioral feature checks, characterization baselines, coverage and lint; return observed evidence to the commit owner. |
 | [commit-gate](commit-gate/SKILL.md) | `/commit` | The commit gate: nine phases — permission, branch, classification, impact-bounded local verification under the shared [verification boundary](../includes/verification-boundary.md), behavioral proof, diff review, selective stage, message, commit. No commit while an applicable check is red, the behavior unproven, or secrets/cruft present; exhaustive exact-head proof remains a hosted-CI merge gate. |
 | [decision-variance](decision-variance/SKILL.md) | Architectural reconciliation or variance report; explicit `/reconcile` retained | One SMARTS arbitration owner; report-only is non-mutating. Analysis card loads on demand; only explicit user choices enter the append-only log. |
 | [debug](debug/SKILL.md) | Diagnosis intent or `/debug` | Investigate-then-decide root-cause analysis: five phases. Investigation only, no code change here; returns one evidence-backed result: confirmed_code_defect, confirmed_noncode_cause, design_question, no_action, or unresolved. Follow-up action retains caller authority; no default task or ADR write. |
 | [refactor](refactor/SKILL.md) | Behavior-preserving restructure intent or `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 for coverage backfill or new test seams. |
-| [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from existing source via parallel scouts; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it `<!--INITIALIZED-->`. |
+| [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from bounded source inspection and optional agents; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it `<!--INITIALIZED-->`. |
 | [decompose](decompose/SKILL.md) | greenfield startup, `/decompose` | Six-layer senior-architect interview, compaction-resilient via per-layer disk drafts + DRAFT ADRs; populates `.codearbiter/` and locks it initialized. |
-| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Caller-scoped feature or coherent sprint specification. Initial approval is user-owned; delegated choices require existing authority. Uses the selected artifact format, preserves recorded intent, and returns or forwards to the caller's required planning step before execution. |
-| [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Decomposes the exact approved spec, or a ready draft through the initial sprint-only pair preflight. Retains same-format criterion/task coverage, paths and verification; combined drafts return for one real spec-and-plan reply before execution. Ordinary sequential binding remains unchanged. |
-| [executing-plans](executing-plans/SKILL.md) | `/feature` | Attended coordinator: uses authored HTML checkpoint membership or bounded legacy batches, delegates to `subagent-driven-development`, and retains the user checkpoint. A display batch never changes an HTML acceptance scope; sprint does not inherit these pauses. |
-| [subagent-driven-development](subagent-driven-development/SKILL.md) | `/sprint` (engine), `executing-plans` (batch scope) | Fresh subagent per task → spec-compliance then quality review → fresh-run verification; accepts only on proof. A quality failure blocks acceptance; approved sprint recovery owns correction. Security CRITICAL and unresolved `[CONFIRM-NN]` remain stops. |
+| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Caller-scoped feature or coherent sprint specification. Keeps material user decisions explicit without duplicate artifact approval. Preserves the selected format, recorded intent and handoff to a maintained plan. |
+| [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Maintains the selected spec's criterion/task coverage, dependencies and relevant checks in the same format. Typed draft binding requires no special sprint approval or future reviewer adapter. |
+| [executing-plans](executing-plans/SKILL.md) | `/feature` | Assistive feature coordinator: uses authored HTML checkpoint membership or meaningful legacy batches, delegates useful work, and reports results. Pauses for explicit user-requested checkpoints or actual decisions, not routine status reporting. |
+| [subagent-driven-development](subagent-driven-development/SKILL.md) | `/sprint` (engine), `executing-plans` (batch scope) | Work from real task dependencies; implement or delegate coherently, run relevant checks, record DONE separately from verified evidence, and retry affected failures. Real user stops, security controls and unresolved material decisions still apply. |
 | [dispatching-parallel-agents](dispatching-parallel-agents/SKILL.md) | `subagent-driven-development`, `/sprint`, parallel `/review` | Reusable fan-out primitive: bound concurrency, collect, dedupe, funnel through `finding-triage`→`verdict-aggregator`. Results unused until the read-only funnel runs. |
 | [finishing-a-development-branch](finishing-a-development-branch/SKILL.md) | PR intent or `/feature` / `/sprint` terminal handoff |Select watch/cleanup before creation preflight. Own PR opening after the current-head gates; sprint opens only. Merge/discard require explicit authority and their own proof. |
-| [using-git-worktrees](using-git-worktrees/SKILL.md) | `subagent-driven-development`, `dispatching-parallel-agents` (opt-in) | OPTIONAL per-unit filesystem isolation for parallel work; integrates accepted units back onto the caller's working branch for its single `commit-gate` + finish. Never the default path. |
+| [using-git-worktrees](using-git-worktrees/SKILL.md) | `subagent-driven-development`, `dispatching-parallel-agents` (opt-in) | OPTIONAL per-unit filesystem isolation for parallel work; integrates completed units onto the caller's working branch for independent commit-gate checks. Never the default path. |
 | [secret-handling](secret-handling/SKILL.md) | changed code reads/writes/passes a secret | The secret-source gate: identify → source → sinks/persistence. Secrets only from the approved store in `security-controls.md`; never in source, log, error, telemetry, image, or LLM prompt. Dispatches `auth-crypto-reviewer`. |
 | [crypto-compliance](crypto-compliance/SKILL.md) | changed code uses crypto/hashing/signing/TLS/random | The banned-primitive gate: one scan. Rejects broken primitives, disabled TLS verification, home-rolled crypto; approved list lives in `security-controls.md`. Dispatches `auth-crypto-reviewer`. |
 | [decision-lifecycle](decision-lifecycle/SKILL.md) | Record a decided ADR / inspect ADR health (`/adr`, `/adr-status`) | One owner; select read-only status before authoring prerequisites. User-attributed writing loads its reference on demand. Full-stem identity; Accepted/Planned is not delivery proof. |
 | [release](release/SKILL.md) | `/release` | Lean declared-policy release, three phases: derive the next identity from Conventional Commits under `version-policy` + roll the changelog; cut the annotated tag and qualify declared assets through either a protected hosted `release-build` or a provenance-bound retained exact-head CI cohort; publish that tag and only those assets on explicit authorization, then verify the remote inventory. SemVer remains the default. No tag on a red suite; no direct-to-main/force-push; nothing published unbidden; a release commit routes through `commit-gate`. |
 | [security-architecture](security-architecture/SKILL.md) | Requested threat model or `/threat-model` |Read-only STRIDE analysis of a sensitive design. Lesser gaps remain constraints; critical unmitigated threats stop the pass. No ordinary-change auto-entry. |
-| [context-check](context-check/SKILL.md) | Drift-audit intent, `/status drift`, or `/context-check` |Report provenance drift; re-scout or re-baseline selected documents only. No staging or commits; routine auto-heal remains with commit-gate. |
+| [context-check](context-check/SKILL.md) | Context refresh, drift-audit intent, `/status drift`, or `/context-check` | Report drift or refresh selected documents under existing authorization. No staging or commits; routine auto-heal remains with commit-gate. |
 | [post-merge-cleanup](post-merge-cleanup/SKILL.md) | Merged-branch cleanup intent, `/ca-pr --cleanup`, or `/ca-cleanup` |Prove fetched containment, classify residue, confirm each discard, and transition fast-forward-only. Preserve unique work, stashes and remote branches. |
 | [tribunal](tribunal/SKILL.md) | Deliberate deep-audit intent or `/ca-tribunal` |Cost-approved deep audit with persisted findings and resumable triage. Separate approval for issue filing and telemetry; never a required gate. |

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

@@ -1,209 +1,72 @@
 ---
 name: brainstorming
-description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it turns a one-line idea into a concrete spec with testable criteria, ready for initial combined sprint review or explicit sequential approval. Five gated phases — frame, shape, refine, write, review-and-approve. No implementation before an approved spec; the caller retains required planning, execution and delivery ordering. Each acceptance criterion becomes one tdd Phase 1 obligation.
+description: Refine feature and sprint intent into a useful specification. Capture scope, observable criteria and material choices without repeated artifact approval ceremonies.
 disable-model-invocation: true
 ---
 
 # brainstorming
 
-## Structured-artifact boundary
-
-For new full-lane work or an existing HTML spec/plan, load
-`<plugin-root>/includes/artifacts.md` before artifact I/O. Before Phase 1, call
-`_select_authoring_route` with the trusted project root, slug, invoking workflow,
-and selected lane; use only its returned mode, format, and paths. For a selected
-HTML route it checks the
-installed capability before writing; missing or invalid HTML capability is a
-STOP and the workflow must not fall back to Markdown. Its typed
-ID, binding, readiness, receipt, contextual-read and scope-state rules replace
-legacy Markdown parsing and direct status-cell edits for that pipeline. Keep all
-other workflow gates, including human checkpoints, unchanged. Existing `.md`
-artifacts remain on their legacy path. New full-lane specs use the installed
-structured-artifact engine and default to canonical `.html`. HTML `--farm`
-dispatch remains blocked.
-
-
-Refine the idea before it touches code. Routed to by `/feature` and `/sprint` as their specification step.
-
-## Caller scope and authority
-
-Read the active caller's workflow, selected lane, scope and existing delegation before refining.
-Initial sprint planning is not an approved sprint: this skill does not grant its own delegation.
-A full-lane feature requires `writing-plans` after spec approval. Initial HTML sprint planning instead
-returns a ready draft identity for the combined spec/plan review before either is approved; a
-subordinate specification step returns its result to the existing caller. Preserve direct handoffs when they
-satisfy that caller's ordering, not an unconditional terminal route to implementation.
-
-A sprint may contain several related features under one coherent goal. Keep their boundaries and
-criteria explicit without converting the sprint into repeated feature interviews. Parameter and
-method choices follow safety-core; material product decisions and missing authority are not inferred.
-No new registered surface, runtime state or copied procedure is needed for this call contract.
-
-## Pre-flight
-
-Read these, or STOP and surface the gap — never guess scope or stack:
-
-- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value), domain vocabulary, and what the project is NOT building.
-- `<project-root>/.codearbiter/tech-stack.md` — the stack the feature must fit; rule out incompatible designs early.
-- `<project-root>/.codearbiter/open-questions.md` — existing `[CONFIRM-NN]` items; new ones number sequentially from here.
-
-**Recorded intent — fail-soft, exempt from the read-or-STOP rule above (ADR-0025).** Also
-consult, when present: the `decisions/` index (titles via `decision-log.md` or the filename
-listing — load a full ADR body only when its subject touches this feature) and
-`plans/02-phased-build-plan.md`'s section headings (plus `plans/01-architecture-breakdown.md`
-when the feature touches component boundaries or integrations). Index-first, never a bulk read.
-A missing file or directory here is NOT a gap to surface and never a STOP: record
-`intent: silent — no decomposition record` in the running notes and proceed.
-
-Scope-sized and light. NOT decompose's whole-project six-layer interview — five phases for the
-caller's feature or coherent sprint. Depth scales with that scope, not the ceremony. The deliberately
-inline small-feature lane remains owned by `/feature`; do not manufacture an HTML pair for it.
-
-## Phase 1 — Frame the problem · gate: BLOCK
-
-Take the one-line idea and pin its boundaries before designing or asking anything:
-
-- State the problem in one sentence — the concrete pain, not the proposed solution.
-- Name the user or caller who feels it, and what "done" looks like to them.
-- Name what this feature explicitly does NOT do — the boundary that keeps scope honest.
-- Check the framing against `CONTEXT.md`: it never contradicts the NOT-building list or redefines domain vocabulary. A contradiction is a conflict — surface it, do not reconcile it silently.
-- Check the framing against the recorded intent (pre-flight, when present): an idea that resurrects a capability `plans/02` records as deferred, or that duplicates a backlog item, is a fork to ask — lead with the recorded deferral rationale and your recommendation; never proceed on it silently (ADR-0025).
-- **Respect the caller's unit of work.** For a feature, split unrelated independently shippable
-  concerns before refining them; record the selected piece and its exclusions. For a sprint, retain
-  related features within the stated sprint goal and identify their separable criteria and dependencies
-  for planning. Do not force one new user interview per feature or silently absorb unrelated work.
-  Ask only when the intended scope or necessary product decision remains unresolved.
-
-Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`; the unit is
-the caller's selected feature or coherent sprint, with unrelated scope explicitly excluded.
-
-## Phase 2 — Shape the approach · gate: BLOCK
-
-Before drilling into details, establish WHICH design the details belong to:
-
-- Propose the genuine candidate approaches — usually two or three — each with its real trade-off stated (`X gives you A but costs B`). Recommend exactly one, with the reasoning that picks it. The user rules on material product decisions during initial feature or sprint planning; within an already-approved sprint, its existing delegated decision rules apply and the choice is logged. A recommendation made before approval does not authorize execution.
-- **Never manufacture alternatives.** When only one sane approach exists, say so and say why — a padded list of straw options is noise wearing the costume of rigor, and it trains the reader to skim the one section that matters.
-- **Check each candidate against accepted ADRs** (the pre-flight index; ADR-0025). A contradicting candidate is surfaced WITH the ADR citation, never silently dropped — and it may not be recommended except paired with a supersession fork via `/adr`. When the contradicting candidate is the only sane approach, that IS the fork: present it (the user rules under `/feature`; under `/sprint` this surfaces at the interactive Phase 1 gate, where the user is present to rule).
-- Apply the isolation lens to the recommended shape while it is still soft: can each part be understood without reading its internals, and can its internals change without breaking its consumers? A design that fails this here fails it again in review, after the code exists.
-- Apply the YAGNI lens: strike anything the Phase 1 problem statement does not demand. A capability the caller never asked for is scope creep with a head start.
-
-Gate: one approach selected under the caller's existing authority and recorded with its trade-off;
-nothing in it exceeds the stated problem. Selection during initial planning is not execution authority.
-
-## Phase 3 — Socratic refinement loop · gate: BLOCK
-
-Turn the chosen approach concrete. The discipline is decide-or-ask, never drift:
-
-- **Choose methods; ask missing decisions.** Select reversible parameters and implementation methods
-  within safety-core's decision-authority limits; multiple reasonable methods alone do not require a
-  user choice. Record material decisions in the running notes and the spec's **Decided parameters**.
-  Use the existing delegated decision rules only where the approved sprint covers the choice. A
-  missing product decision, unresolved `[CONFIRM-NN]`, scope expansion or irreversible operation is
-  not a method choice: ask the actual question with its recommendation and counter-consideration.
-- **Batch what is independent.** Forks whose answers do not depend on each other are asked together, not serialized into rounds. One round of three real questions beats three rounds of one.
-- Run every answer through three lenses:
-  - **Vague language** — make the required outcome observable: "fast", "secure" and "scalable"
-    need acceptance boundaries. Only unresolved product requirements or missing user-owned decisions
-    become `[CONFIRM-NN]`; a reversible implementation detail deliberately left to planning within
-    the agreed constraints is not an unanswered user question. Do not invent unknowns to fill a template.
-  - **Hidden complexity** — name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`.
-  - **Trade-off forcing** — identify the actual choice and its counter-consideration. Apply the caller's existing authority: ask material user-owned decisions, or choose and log an authorized delegated method. Never hide a choice or widen delegation.
-- **The loop has a breaker.** When refinement stops converging, stop repeating the same question or
-  hypothesis. Reuse an applicable recorded ruling; within delegation, diagnose and choose a different
-  evidence-supported method. A genuine unresolved user decision or rule conflict is surfaced once
-  through its owner, never guessed or treated as permission. Do not manufacture `[CONFIRM-NN]` for
-  the agent's internal choice of method.
-- **Closure is a checklist, not a feeling.** The reasons to stop asking that do not count, each with why:
-  - *"The feature is simple enough."* — Simplicity shortens the spec; it does not waive it. The five-sentence spec still names its criteria.
-  - *"I've asked enough questions."* — Question fatigue is not an exit condition. The exit is the Phase 5 review passing.
-  - *"The user seems eager to move on."* — Eagerness is a signal to compress the asking (decide more parameters, batch harder), never to skip an unresolved fork.
-  - *"We can settle it during implementation."* — Missing acceptance requirements cannot be deferred
-    as implementation freedom. Record genuine user-owned unknowns; retain method selection within
-    the existing planning and delegated-execution contract.
-
-Record every genuinely-unresolved user-owned requirement or decision as `[CONFIRM-NN]` in `<project-root>/.codearbiter/open-questions.md`, numbered sequentially. A finding that belongs to a different feature or a future scope gets an inline `[NEEDS-TRIAGE]` marker in the notes — never route it to a ticket.
-
-**Before closing this loop, check the criteria decided so far against their own stated intent, not merely against each other** (#566: `writing-plans` Phase 4 proves BIJECTION between a plan's tasks and the `AC-NN` ledger — every criterion has a task, every task has a criterion — and that proves the two AGREE, never that the ledger itself is COMPLETE. A criterion missed by both sides passes that check cleanly; catching the miss belongs here, at the source, before Phase 4 writes anything to freeze it in place.) Assemble a scratch file outside the working tree (`mktemp`) shaped like the spec sections Phase 4 is about to write — a `## Scope` heading over the Phase 1 framing, and an `## Acceptance criteria` heading over every criterion decided in this phase's running notes so far — and, when this feature traces to a GitHub issue, its body into a second scratch file (`gh issue view <N> --json body -q .body > <scratch-file>`; omitted when there is no linked issue). Run `"$PY" "<plugin-root>/hooks/_intentlib.py" uncovered-intent <scope-and-criteria-file> [--issue-body <scratch-file>]`. A non-empty result names an in-scope bullet or an issue acceptance checkbox no criterion's text cites — add the missing criterion now, or record it as a `[CONFIRM-NN]` if it is genuinely undecided, never carry it forward uncited. This mechanical pass is the CHEAP half; it catches only an uncited bullet or checkbox.
-
-Then ask the half it cannot mechanize, explicitly, as its own step: **if every criterion decided so far passed and nothing else changed, what would still be broken?** A real answer names a criterion the ledger is still missing even though every scope bullet and checkbox is technically cited — a bullet reading "fix all three contaminated skills" against criteria for two of the three passes the citation check above cleanly, and only this question catches it. Finding nothing broken is a reportable result, stated in one line, never a silent skip.
-
-Gate: every vague term made concrete; every material choice resolved under the caller's authority or recorded as a genuine `[CONFIRM-NN]`; every parameter decision recorded in the running notes that seed Phase 4's **Decided parameters** section; no unresolved user-owned acceptance requirement outside a `[CONFIRM-NN]`; the `uncovered_intent` backstop returns empty or every finding is resolved; and the negative question above has been asked and answered, not merely named. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP.
-
-## Phase 4 — Write the spec · gate: BLOCK
-
-Create or revise the agreed spec at the route-selected spec path, in its selected format.
-New full-lane work uses `<project-root>/.codearbiter/specs/<slug>.html` through the installed
-structured-artifact engine; do not write HTML or its embedded model directly. An existing `.md`
-spec stays on its exact legacy path; never create a counterpart or implicitly convert it.
-The spec holds:
-
-- **Problem** — the Phase 1 framing in final form.
-- **Approach** — the Phase 2 choice and the trade-off that picked it, in two or three sentences.
-- **Scope** — what is in, and the explicit out-of-scope boundary.
-- **Decided parameters** — the parameter-level choices made in Phase 3, each in one line, so the approval reads them instead of discovering them in code review.
-- **Acceptance criteria** — a numbered list, each criterion concrete and testable: a specific input, the observable output, the boundary or failure behavior. Each criterion is verifiable by one or more focused tests. "It works well" is not a criterion. These become `tdd` Phase 1 obligations — one obligation per criterion, so an untestable criterion is a defect to fix here, not in `tdd`.
-- **Open questions** — every `[CONFIRM-NN]` raised, cross-referenced to `open-questions.md`.
-- **Governs** *(optional)* — a spec-header line `**Governs:** <comma-separated globs>` that enrolls the approved spec in file-scoped just-in-time context injection: on a Read of any file matching one of the listed globs, a pointer to this spec is surfaced to the agent (tier 3 of the file→knowledge map). Adding the line is sufficient to enroll; no other change required.
-
-Gate: the spec file exists on disk under `specs/`, with at least one acceptance criterion and every criterion individually testable.
-
-## Phase 5 — Review, approval & handoff · gate: STOP
-
-The spec earns its approval; it is not waved through. Two passes over the FILE as written, then the stop:
-
-1. **Mechanical self-review** — one pass, correct through the selected format's owning writer, no re-review: no placeholder text (`TBD`, `???`, an unfilled section); no criterion that contradicts the scope; nothing that crosses the `CONTEXT.md` NOT-building boundary; no criterion that contradicts an accepted ADR or `plans/01`'s recorded component boundaries (ADR-0025); every criterion still testable by one or more focused tests after the edits; the vague-language lens applied to the spec's own prose.
-2. **Adversarial pass** — build the strongest case AGAINST the design before the user reads it: the failure mode most likely to be real, the criterion most likely to be wrong, the assumption that would invalidate the approach if false. Present what survives WITH the spec at approval — the user rules on a challenged design, not a defended one. Finding nothing is a reportable result, stated in one line, not a silent skip.
-3. **Approval:**
-   - **Under `/feature`** — present the spec and the adversarial findings, and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it.
-   - **Initial `/sprint` planning** — prepare the ready draft spec and adversarial findings for
-     explicit user approval with its complete draft plan at the caller's one initial review gate.
-     For HTML, return the current draft identity to `writing-plans` in `draft_for_pair` mode;
-     the combined `arm-sprint` / `sprint-approve` path in `<plugin-root>/includes/artifacts.md`
-     observes the exact returned reply and binds/approves both documents atomically. Do not separately approve
-     the spec, synthesize a SMARTS receipt, or execute draft tasks. Do not reinterpret one generic reply
-     as approval of either artifact or delegation. Autonomy begins only after the
-     caller's spec AND plan approval requirement is met. A legacy Markdown caller retains its
-     recorded approval mechanism; there is no implicit conversion.
-
-   - **Within an already-approved sprint** — use its existing delegation only for an in-scope choice.
-     For HTML, a supported policy-owned adapter must supply the actual event and engine receipt;
-     follow `<plugin-root>/includes/artifacts.md`. A SMARTS score or log entry is not an approval receipt.
-     The private `smarts-apply` producer covers only existing plan-method steps under an explicit
-     paired user grant; it cannot approve a specification amendment or widen its protected scope.
-     Use only a qualified production producer for the requested authority and host; do not invent a capture event
-     or reuse inspection-only evidence. A missing producer is not delegation: retain the pending state and use
-     only the existing supported authority path. The native engine's presence does not qualify a host adapter.
-     Blocking `[CONFIRM-NN]` decisions are never auto-approved in either phase.
-
-**Continuation follows the caller.** For a full-lane feature or sprint with approved spec authority,
-return the approved spec identity and review outcome to its planning step; for initial HTML sprint
-review, return the ready draft identity without execution authority. Either may forward directly to
-`writing-plans` (`<plugin-root>/routines/writing-plans/SKILL.md`) when that is the caller's declared
-next step. Do not skip required plan creation, binding or approval by jumping to `tdd`. A subordinate
-invocation returns to the named checkpoint in its caller instead of launching another full workflow.
-The inline small feature route belongs to `/feature` and can reach `tdd` without invoking this full-lane
-specification procedure. Neither path grants commit, PR, merge or publication authority.
-
-Gate: both review passes completed against the authoritative file, adversarial findings presented,
-and no unresolved blocking `[CONFIRM-NN]`. Require actual approval verified before execution.
-Only initial combined HTML review may return a ready unapproved draft to its constrained planner.
-The next operation obeys the active caller's sequence and authority.
-
-## Hard rules
-
-- MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved.
-- MUST preserve the caller's feature or coherent sprint boundary; unrelated scope is split or excluded, not silently absorbed.
-- MUST NOT manufacture alternatives in Phase 2 — when one sane approach exists, say so and why.
-- MUST NOT write an acceptance criterion that cannot be verified by one or more focused tests.
-- MUST record material parameter choices; ask genuine missing user decisions in full, not internal method-selection questions already covered by delegation.
-- MUST stop a non-converging refinement strategy; reuse recorded rulings or authorized diagnosis rather than repeat an answered question. Genuine conflicts still route to their owner.
-- MUST run the `uncovered_intent` mechanical backstop and ask the negative-judgment question ("if every criterion passed and nothing else changed, what would still be broken?") before closing Phase 3 — bijective coverage in `writing-plans` proves the plan and the ledger agree with each other, never that the ledger is complete (#566).
-- MUST run the Phase 5 mechanical self-review and adversarial pass against the file as written, and present the adversarial findings at approval.
-- MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface it and record it in `open-questions.md`.
-- MUST NOT auto-approve a spec carrying a blocking `[CONFIRM-NN]`, even under `/sprint` — it escalates to the user.
-- MUST NOT contradict the NOT-building list or redefine domain vocabulary in `CONTEXT.md` — a contradiction is a conflict to surface, not reconcile.
-- MUST NOT run decompose's six-layer whole-project interview or force a coherent sprint through repeated one-feature interviews.
-- MUST NOT use SMARTS to approve the initial sprint; record delegated decisions in the existing audit trail and verify actual authority for the selected artifact format.
-- MUST, at exit, run the follow-up harvest (`<plugin-root>/includes/harvest.md`) in the active caller's mode:
-  batch-confirm interactive work; use autonomous promotion only under existing delegation. A blocking
-  decision is never promoted into authority or silently demoted to a follow-up.
+Refine the agreed outcome before implementation. This is intent clarification and specification authoring, not a second permission system. The feature or sprint request is the initial authorization; ask about consequential choices not already answered, not whether an artifact may exist.
+
+## Format and caller
+
+For artifact I/O, load `<plugin-root>/includes/artifacts.md` and select the source with `_select_authoring_route`. Retain that source identity through specification authoring.
+
+The calling feature or sprint owns scope and the next step. A sprint may include several related features under one coherent goal. A small inline feature remains the caller's mini-spec lane. Specification authoring itself does not grant commit, publication, override, provider spending, or irreversible-operation authority.
+
+Use relevant CONTEXT.md, tech-stack.md and security-controls.md when present. Read an existing open-questions document and relevant ADR/plan headings index-first. Missing optional historical indices are not blockers. Preserve real decisions while distinguishing an accepted decision from implemented or released behavior.
+
+## Recorded intent and consequential conflicts
+
+Use an index-first recorded-intent read to avoid asking about settled choices.
+This pre-flight is exempt from the read-or-STOP rule when optional project
+history is absent: **intent: silent — no decomposition record**. Do not
+manufacture a plan or an approval to fill that gap.
+
+If a proposed solution resurrects a capability `plans/02` records as deferred,
+identify the original reason and any stated re-evaluation trigger, then fork to ask
+only when the *outcome* would materially change. An explicit current owner steer
+can settle that fork; an ordinary implementation detail cannot silently reverse
+a recorded deferral.
+
+A candidate that contradicts an accepted ADR must be **surfaced WITH the ADR
+citation, never silently dropped**. A recommended outcome change is paired with
+a supersession fork via `/adr` instead of pretending the old decision never
+existed. If the contradiction is the only sane approach, that IS the fork:
+show the choice and consequence to the owner once, respecting an already
+recorded superseding instruction. A referenced ADR is not a new permission
+token for safe, in-scope investigation or implementation.
+
+## Phase 1 - Frame
+
+State the problem, observable result, intended scope and explicit exclusions. Respect what the user already requested. If a record conflicts with new intent, identify the material decision and which work it affects; do not automatically create another approval round for ordinary method choices.
+
+## Phase 2 - Select a viable approach
+
+Consider genuine trade-offs where they matter, recommend a suitable approach and explain why. Do not manufacture straw alternatives. Reversible implementation methods remain agent-owned within the agreed outcome. Ask for a user ruling on an unresolved, consequential product choice, not on every viable implementation detail.
+
+Review applicable ADRs and explicit exclusions. A real conflicting architecture decision goes to its owner. Mentioning a protected file does not by itself restart the entire feature interview.
+
+## Phase 3 - Make acceptance observable
+
+Turn intended scope into specific criteria: input or trigger, expected behavior, and relevant failure/boundary condition. Check integration risks and ask: **if every criterion passed, what would still be broken?** For meaningful behavior changes, plan one or more focused tests against the actual obligation; do not create tests solely to clear an artifact gate. For complex or issue-backed work, a bounded `_intentlib.py uncovered-intent` inspection can catch uncited requirements. It is not a mandatory permission gate for every small change.
+
+Choose sensible defaults and record material parameters. Do not create CONFIRM placeholders for normal method choices. A consequential unresolved requirement warrants one clear user question; independent work may proceed if that decision affects only part of the plan. Do not repeatedly ask the same question merely because an artifact was revised.
+
+## Phase 4 - Write the spec
+
+Create or update the route-selected spec with: problem, chosen approach and rationale, included/excluded scope, meaningful parameters, observable acceptance criteria, and actual open decisions. For HTML use typed `create` and `apply`, stable criterion IDs, current CAS, and symbol-scoped readback; never edit embedded HTML/JSON directly. Existing Markdown remains on the legacy path without automatic conversion. Do not invent a command, test, source, approval or result.
+
+Drafts may be incomplete. `validate` with `gate: ready` identifies missing coverage and structure. Diagnostics help complete the plan; they are not a reason to prohibit independent authorized investigation. A conflicting write or structural failure still prevents claiming the artifact was saved. A ready spec is not proof of implementation.
+
+## Phase 5 - Self-review and handoff
+
+Read back the saved specification. Check consistency, alignment with the user's request, exclusions, and ability to verify: no criterion that contradicts an accepted ADR without an explicitly resolved, source-visible owner decision. Identify a plausible failure mode or say none was found. Proportion the review to risk rather than mandating an adversarial committee.
+
+For full-lane feature or sprint work, return the selected spec identity, normative digest, criteria, and genuinely open decisions directly to `writing-plans` (`<plugin-root>/routines/writing-plans/SKILL.md`). The caller maintains its ordering; do not skip a useful plan to reach implementation. An existing spec should resume at its actual unfinished step, not restart an interview.
+
+**Do not demand separate spec approval or `arm-sprint`/`sprint-approve` merely to progress.** An explicitly requested human review pause and real user-owned decisions still apply. Historical paired approval, producer capture or SMARTS grant remains historical; do not fabricate a receipt. In-scope method updates during work are typed plan maintenance, not another permission interview.
+
+## Hard boundaries
+
+Never broaden the requested outcome, ignore a genuine host denial or user stop, manufacture verification evidence, silently change representation, or claim a saved/verified state without observing it. Preserve source integrity and independently applicable security controls. Avoid interviews for already-answered or agent-owned choices.