@arbiterforge/ca-pi 0.10.13 → 0.14.6

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

@@ -0,0 +1,166 @@
+# Typed HTML specifications and plans
+
+Load inside the existing brainstorming, planning, TDD, execution or resume
+workflow for new full-lane work or an existing HTML pair.
+This leaf adds no slash command, agent, skill registration or persistent model
+tool.
+
+**Default authoring boundary:** new full feature and sprint spec/plan pairs
+default to canonical `.html`. Check the installed capability before writing; a
+missing, invalid, mismatched or unqualified capability is a STOP and
+the workflow must not fall back to Markdown or create any fallback artifact.
+Report `CAPABILITY_MISSING` and direct the user to repair or reinstall the pinned
+artifact payload before retrying. An existing `.md` exact pair remains Markdown
+and continues on the legacy path without automatic conversion. The feature
+small lane remains an inline mini-spec and creates no artifact. HTML `--farm`
+dispatch remains disabled and outside this rollout.
+
+## Internal execution contract
+
+The normal qualified package's installation-owned `release.json` pins the native
+executable bytes. The stdlib
+`hooks/_artifactlib.py` bridge selects only that verified installed payload,
+never PATH, an environment-selected binary or a path supplied by the project.
+The existing host's governed execution mechanism and permissions remain
+applicable. An absent payload or denied invocation is a capability gap to
+surface, not permission to bypass the gate.
+
+Use one operation with JSON on stdin:
+
+```text
+ca-artifact <operation> --root <project-root> --request -
+```
+
+Requests carry `protocol: codearbiter.artifact-api/0.1.0`. Query `schema` for the
+needed operation or record fragment only; do not preload complete schemas. Return
+stdout is a single bounded JSON envelope. Nonzero exits are failures except the
+structured `validate` response explicitly reporting `valid: false` (also a gate
+failure). Logs/stderr are not artifact content.
+
+## Authoring and approval
+
+New full-lane specs and plans use `.codearbiter/specs/<slug>.html` and
+`.codearbiter/plans/<slug>.html`. Create a draft, then use typed `apply` changes;
+do not write or regex-edit HTML or its embedded JSON. `record.add` allocates a
+stable ID when omitted. Keep criterion IDs from the spec in plan references;
+never assign a second criterion ledger. Use `record.update` and explicit
+retirement reasons. There is no generic status/approval update.
+
+Drafts may be incomplete. `validate` with `gate: ready` is required before review.
+It checks types, references, scope coverage, contracts and task definitions—not
+semantic truth. Retain the existing negative-intent question, adversarial review,
+ADR compatibility review, open-question handling, harvest and user/SMARTS gates.
+One criterion may need multiple tests. Never invent a condition, oracle, source,
+command, result, approval or reviewer to satisfy a required field.
+
+The existing user, SMARTS, reviewer, or verification boundary must first persist
+its actual policy-owned workflow event as canonical JSON in the reserved
+content-addressed authority-source store. Interactive prompt approval currently
+has production host seams in Claude Code and Codex. Pi 0.84.1 exposes no
+pre-model event carrying the user's exact prompt, so under Pi do not arm this
+adapter; the workflow remains blocked until a Pi-native authority adapter is
+implemented. On Claude Code or Codex, arm the exact current artifact immediately
+before asking the approval question:
+
+```sh
+python "<plugin-root>/hooks/_approvallib.py" arm --root "<project-root>" --artifact-id <artifact-id>
+```
+
+Present the returned `reply` value verbatim and require that exact reply. The
+`UserPromptSubmit` hook rechecks the armed identity, records the host-observed
+prompt as the policy-owned source, captures its receipt, and applies approval.
+An ordinary `yes`, a changed artifact, a wrong token, or a model-authored event
+does not confer authority. On the next turn, verify `validate` at the `approved`
+gate before continuing. If the user declines or the artifact changes, cancel the
+exact pending request before arming another one:
+
+```sh
+python "<plugin-root>/hooks/_approvallib.py" cancel --root "<project-root>" --artifact-id <artifact-id>
+```
+
+Cancellation records no authority. Other workflow authorities must use their
+corresponding host-owned adapters; never call `capture` with request-authored
+`authority_kind`, verdict, actor, or source-text labels, and never create an
+authority source merely to satisfy an artifact transition.
+`capture` does not change approval state. `approve` checks the resulting receipt
+against current ready content. A missing or changed receipt, captured event, or
+still-present policy source returns `AUTHORITY_UNVERIFIED`. Receipt format 0.1.0
+remains readable for inspection after upgrade but is not authority-bearing; the
+applicable policy boundary must produce a fresh 0.2.0 attestation before further
+approval, dispatch, acceptance, commit proof, or finalization. This is the
+repository's cooperative same-user attestation model, not cryptographic identity
+proof or protection from an unrestricted same-user filesystem writer.
+
+Create a plan as `draft_preview`, consume existing criterion IDs, then `plan-bind`
+to the approved spec. Approve the plan through the applicable existing workflow.
+A normative change invalidates its approval. Rebinding is explicit and preserves
+history; it does not waive coverage or permit silent reinterpretation.
+
+## Reading and dispatch
+
+Use `index`, then `outline`, then symbol-scoped `read`. Exact reads are explicitly
+context-incomplete. Execution uses contextual pages; follow every `next_cursor`
+until `context_complete: true`, and retain the final context ticket. Cursors bind
+both documents and contributing receipts/events. No partial record is silently
+returned. A stale cursor/ticket requires a fresh read.
+
+These cursors and tickets name engine-written, content-addressed cooperative
+delivery receipts. They are not authentication secrets and do not claim
+resistance to an unrestricted same-user filesystem writer. A digest without its
+corresponding engine-written receipt is rejected.
+
+`eligible` is authoritative for task selection on the HTML path.
+`task-start` checks current spec/plan approval, binding, prerequisites, source
+snapshot, dependency evidence and the complete context ticket. Within a checkpoint,
+a predecessor in `REVIEW` can provisionally unblock its dependent after fresh
+verification and spec review. Across checkpoints, dependencies require accepted
+scope evidence. Provisional progress never counts as completion.
+
+The orchestrator executes the declared verification through its existing governed
+execution tool, captures actual named-test outcomes and output hashes, and obtains
+a separate spec review. `task-review` records those receipts. After every task in
+the scope reaches `REVIEW`, reverify against one current source snapshot, review
+the combined scope, and use `accept-scope` once. Do not accept tasks individually.
+
+`IN_PROGRESS` after interruption requires reconciliation, not automatic completion.
+`REVIEW` requires fresh evidence. Source changes stale proof; state/branding updates
+do not stale their own verification. `task-block` invalidates downstream provisional
+states. `scope-reconcile` records a reviewed new baseline after plan edits.
+
+## Mutation and recovery
+
+Every artifact mutation supplies the revision AND model hash last read, plus a
+unique operation ID. On conflict, reread and reconsider—never overwrite forcefully.
+A response lost after replacement is not evidence that nothing changed. Retry the
+same operation ID with identical input, or use `recover` on an uncertain transaction.
+Replaying a completed operation returns its original completion fields and a
+transaction marked as replayed; use `identity` for the current document identity.
+An older journal may return `refresh_required: true` instead. A rolled-back
+operation is not success. Keep journal-compatible tooling when restoring code.
+A transaction that was rolled back returns `OPERATION_ROLLED_BACK`.
+
+`repair-preview` identifies an inconsistent generated view. `repair-apply` requires
+both original-byte and candidate hashes and retains original bytes; it never
+infers semantic edits from human-modified HTML. Export writes a standalone copy
+outside canonical directories. Rebranding accepts only validated local assets.
+
+## Legacy transition and blocked capabilities
+
+Legacy Markdown remains readable through the old workflow. Conversion is explicit:
+`migration-preview` receives typed spec/plan models and a complete nonoverlapping
+line-disposition map for each original file. Review the models and mappings, then
+`migration-apply` binds to the exact preview digest and records the review. Both
+new artifacts are drafts. Original approval/status prose is not transferred.
+Cutover is recoverable as a pair; completed cutovers use `migration-rollback`, which
+refuses any intervening candidate edit. Original bytes remain in transaction history.
+
+**HTML farm dispatch remains disabled and out of scope.** The
+engine can derive an immutable base-bound projection, verify it before canary,
+permit only `meta.model`/`meta.apiBaseUrl` enrichment, and seal exact execution
+bytes plus caller-supplied provider-selection assertions. Those assertions are
+auditable correspondence, not authenticated provenance. The shared built dispatcher enforces the checks
+before side effects. Keep the HTML `--farm` path disabled until real authority
+adapters, native packaged payloads and the fresh frontier/low-tier qualification
+matrix all pass; the June 2026 run earns no current credit. Existing legacy farm
+behavior is unchanged. Enabling normal premium-path HTML authoring does not count
+as farm qualification or authorize farm dispatch.

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

@@ -3,12 +3,13 @@
 Canonical for the author agents (`backend-author`, `frontend-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.
 
 Fixed order. Do not skip or reorder.
 
 1. **Write failing tests** — one test per obligation in the Phase 1 checklist
 2. **Confirm tests fail for the right reason** — run the test command from `tech-stack.md`; the failure must match the obligation, not an unrelated error
 3. **Write minimum implementation** — only enough code to make the failing tests pass; no extra scope
-4. **Run full suite** — every test green
+4. **Run impact-bounded local suite** — every affected test green; 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

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

@@ -1,8 +1,31 @@
 # codeArbiter farm — setup and configuration
 
-> **Feature Forge `preview`.** The `--farm` backend ships off by default and is not yet validated on
-> real runs; the premium subagent path is the blessed default. Promotion bar:
-> `<project-root>/.codearbiter/open-questions.md` (CONFIRM-05).
+> **Feature Forge `preview`.** The `--farm` backend ships off by default; the premium subagent path is
+> the blessed default. Historical runs informed the design but count as zero current qualification
+> evidence. Promotion requires the complete fresh-evidence bar below.
+
+## Stable opt-in promotion bar
+
+Qualification starts at zero on 2026-09-16. Runs before that date are historical development evidence
+only and earn no promotion credit. Before promotion, one durable qualification packet must bind all
+evidence to exact farm revisions and show:
+
+- at least five completed farm slices across at least three distinct repositories;
+- at least 50 dispatched implementation tasks;
+- completed evidence from Windows and a POSIX host, spanning at least two selected model identities;
+- at least 85% direct farm completion, no more than 15% premium escalation, and no more than 1.5
+  average attempts per dispatched task;
+- zero circuit-breaker trips, gate escapes, security incidents, supply-chain incidents, or unresolved
+  HIGH findings;
+- the ordinary integrated suite, full review chain, and fresh verification passing for every slice;
+- at least 25% lower premium implementation-token consumption than comparable premium execution,
+  counting escalations and review rather than treating worker tokens as the whole cost.
+
+All qualifying runs must use the then-current farm implementation and provider model set. A material
+farm implementation change or provider/model-set change before promotion invalidates the affected
+evidence and requires it to be rerun. Promotion means **stable opt-in** only: it does not make farm the
+default, remove any external-dispatch trust gate, or enable typed-HTML farm projection. The typed-HTML
+path remains blocked until its own integration and qualification are complete.
 
 `farm.ts` is the pluggable execution backend: Claude writes specs, failing tests, and a `plan.json`;
 the farm runs workers in isolated git worktrees to make each test pass; Claude reviews and merges. Its
@@ -38,7 +61,7 @@ capable of the slice).
    `FARM_MUTATION_TEST_CMD` set and must print a trailing JSON line with a numeric `score`.
 
 Note: `writing-plans --farm` MUST place the task's narrow behavioral test first in `gate.commands` —
-the mutation guard runs `gate.commands[0]` as the per-mutant test (running the full suite per mutant
+the mutation guard runs `gate.commands[0]` as the per-mutant test (running an exhaustive suite per mutant
 would be too slow).
 
 ### Best-of-N sampling and iterative retries

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

@@ -46,8 +46,8 @@ reached the same way.
 | Unsure `/reconcile` vs `/conflict`? | rules contradict and work cannot safely continue → `/conflict`; artifacts drifted, work continues → `/reconcile` | — | When genuinely ambiguous, `/conflict` wins — stopping is recoverable, drifting past a rule conflict is not |
 | New skill needed | `/new-skill` → `skill-author` | — | No skill until the gap is proven uncovered |
 | Subagent raises an out-of-scope finding | inline `[NEEDS-TRIAGE]` marker | — | Never an ADR disposition; never silently dropped |
-| Sitting down to code / repo hygiene cleanup | `/ca-standup` → orchestrator git actions | — | ff-only pull on a clean tree; each branch/worktree delete confirmed individually; stash/dirty/un-pushed report-only; never touch the default branch |
-| Finish an already-merged branch (post-merge cleanup) | `/ca-cleanup` → `post-merge-cleanup` | — | Ancestry of the FETCHED default proven before any delete; unique/unclassifiable artifacts never discarded without a per-item confirmation; `--ff-only` and `branch -d` only; remote branch untouched; never routes to `/ca-override` |
+| Sitting down to code / repo hygiene cleanup | `/ca-standup` → orchestrator git actions | — | ff-only pull on a clean tree; branch deletions confirmed individually, worktree removals may be confirmed as one named enumerated group; stash/dirty/un-pushed report-only; never touch the default branch |
+| Finish an already-merged branch (post-merge cleanup) | `/ca-cleanup` → `post-merge-cleanup` | — | Merge proven against the FETCHED default by ancestry, PR-record squash proof, or a byte-identical fallback; unique/unclassifiable artifacts never discarded without a per-item confirmation; `--ff-only`; `branch -d`, or `-D` only under the restated squash-proof path; remote branch untouched; never routes to `/ca-override` |
 | Add / start / done a backlog task | `/ca-task` → `hooks/taskwrite.py` (the pure `_taskboardlib` transforms) | — | Board written only through the writer; `start` always stamps a date; `done` requires in-progress; never delete to complete |
 | 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 |

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

@@ -0,0 +1,27 @@
+# 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
+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
+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.
+
+GitHub's public-repository **hosted CI** owns exhaustive and cross-platform
+validation. Before merge, bind the pull request's current exact-head commit and
+require its repository merge-readiness aggregate, including every job selected
+by the impact planner. Missing, stale, cancelled, or mismatched hosted evidence
+does not count: **MUST NOT merge** until the exact-head required checks pass.
+
+Hosted CI is not a substitute for evidence that cannot be exercised safely or
+faithfully on a hosted runner, such as a user-authorized live device, private
+environment, or local integration boundary. Run that proof locally when the
+acceptance criterion requires it, record the environment and result, and still
+require hosted CI for the repository checks it owns.
+
+This allocation changes where exhaustive compute runs, not the strength of the
+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.

package/plugins/ca-pi/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@arbiterforge/ca-pi",
+  "version": "0.14.6",
+  "private": true,
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/codearbiter.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

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

@@ -8,14 +8,14 @@ Skill bodies load on routing only. This index is the surface scan; never bulk-re
 | 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. |
-| [commit-gate](commit-gate/SKILL.md) | `/commit` | The commit gate: nine phases — permission, branch, classification, verification, behavioral proof, diff review, selective stage, message, commit. No commit while the suite is red, the behavior unproven, or secrets/cruft present. |
+| [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) | `/reconcile` | SMARTS 6-lens arbitration of project/ADR conflicts; append-only, user-attributed decision log + audit trail. Never decides alone — every choice carries user attribution. |
 | [debug](debug/SKILL.md) | `/debug` | Investigate-then-decide root-cause analysis: five phases. Investigation only, no code change here; forces one named exit — `/fix`, `/adr`, or a no-action close. |
 | [refactor](refactor/SKILL.md) | `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 only when new test seams are needed. |
 | [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-->`. |
 | [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 | Socratic idea→spec: split bundles, shape the approach, then decide parameters / ask forks in full; adversarial self-review before approval; writes `specs/<slug>.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. |
-| [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Decomposes an approved spec into small tasks, each with a path + a verification that maps to a `tdd` obligation; writes `plans/<slug>.md` with bijective criterion↔task coverage. |
+| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: split bundles, shape the approach, then decide parameters / ask forks in full; adversarial self-review before approval; writes new full-lane `specs/<slug>.html` through the installed engine while preserving existing Markdown authority. Its acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. |
+| [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Decomposes an approved spec into small tasks, each with a path + a verification that maps to a `tdd` obligation; writes a same-format plan with bijective criterion↔task coverage (`.html` by default, `.md` for an existing Markdown spec). |
 | [executing-plans](executing-plans/SKILL.md) | `/feature` | Checkpoint coordinator — groups tasks into batches, delegates each to `subagent-driven-development` (fresh author agent per task, full review chain), stops for user acknowledgement between batches. |
 | [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. Hard-stops on `tdd` BLOCK, security CRITICAL, `[CONFIRM-NN]`. |
 | [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. |
@@ -25,7 +25,7 @@ Skill bodies load on routing only. This index is the surface scan; never bulk-re
 | [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`. |
 | [skill-author](skill-author/SKILL.md) | `/new-skill "<gap>"` | The only path to a new skill: five phases — gap evidence, scope, authoring, self-review against the v2 house style, routing integration. No skill written until the gap is proven uncovered; none shipped without gated phases, hard rules, and an `INDEX.md` + routing entry. |
 | [decision-lifecycle](decision-lifecycle/SKILL.md) | `/adr`, `/adr-status` | Lean ADR author + status: author a numbered, dated, user-attributed ADR under `.codearbiter/decisions/`; list/status; forward-only supersede chains. Optional `decision-challenger`. Log-entry format lives in `includes/smarts/decision-log-format.md`. ADRs only via `/adr`, with user attribution. |
-| [release](release/SKILL.md) | `/release` | Lean SemVer release, three phases: derive the bump from Conventional-Commits since the last tag + roll `CHANGELOG.md`; cut the annotated tag + report; publish (push tag + `gh release create`) on explicit authorization. No tag on a red suite; no direct-to-main/force-push; nothing published unbidden; a release commit routes through `commit-gate`. |
+| [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) | `/threat-model` (optional) | OPTIONAL lightweight STRIDE pass for sensitive features: attack surface → STRIDE → findings, governed by `security-controls.md`. MAY dispatch `security-reviewer` / `auth-crypto-reviewer`. Not a routine gate; hard-STOPs only on a critical unmitigated threat. |
 | [context-check](context-check/SKILL.md) | `/context-check` | OPTIONAL manual drift audit: load `.codearbiter/.provenance/` via `load_provenance_dir` + `compute_drift`, report stale docs, then per stale doc: re-scout / re-baseline (`rebaseline`) / defer. Not the daily loop — commit-gate auto-heal owns routine maintenance. |
 | [post-merge-cleanup](post-merge-cleanup/SKILL.md) | `/ca-cleanup` | The already-merged branch transition: fetch, prove `HEAD` is contained in the fetched default (SHA-ancestry, or a squash-merge proven by the merged PR record), classify every dirty/untracked artifact as unique/redundant/superseded, resolve each under its own confirmation, fast-forward the local default ref then `--ff-only` onto it, then `branch -d` the merged local branch. Unique or unclassifiable artifacts are never discarded unbidden; the remote branch is never touched; never routes to `/ca-override`. |

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

@@ -6,6 +6,23 @@ 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` (before `tdd`) and by `/sprint` (the planning front).
 
 ## Pre-flight
@@ -78,13 +95,15 @@ Gate: every vague term made concrete; every fork resolved by the user or recorde
 
 ## Phase 4 — Write the spec · gate: BLOCK
 
-Write the agreed spec to `<project-root>/.codearbiter/specs/<slug>.md`. The slug is derived from the feature. The spec holds:
+Create the agreed spec through the installed structured-artifact engine at
+`<project-root>/.codearbiter/specs/<slug>.html`; do not write the HTML or its
+embedded model directly. The slug is derived from the feature. 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 a single test. "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`.
+- **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.
 
@@ -94,7 +113,7 @@ Gate: the spec file exists on disk under `specs/`, with at least one acceptance
 
 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, fix inline, 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 a single test after the edits; the vague-language lens applied to the spec's own prose.
+1. **Mechanical self-review** — one pass, fix inline, 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.
@@ -109,7 +128,7 @@ Gate: both review passes run against the file on disk, adversarial findings pres
 - MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved.
 - MUST NOT refine a bundle — an idea holding more than one independently shippable concern splits in Phase 1, before any question budget is spent.
 - 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 a single test.
+- MUST NOT write an acceptance criterion that cannot be verified by one or more focused tests.
 - MUST decide parameter-level choices and record them in the spec; MUST ask genuine forks in full, with a recommendation, the first time — never name an open decision without asking it.
 - MUST stop a non-converging refinement loop and force one adjudication — a contradiction or a resurfacing fork is a breaker, not a prompt to circle.
 - 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).

package/plugins/ca-pi/routines/commit-gate/SKILL.md

@@ -12,8 +12,25 @@ The only permitted path to a commit. Bypassing it is a hard-rule violation. Rout
 Read these, or STOP and surface the gap — never guess a command:
 
 - `<project-root>/.codearbiter/tech-stack.md` — test, lint, and secrets-scan invocations. Stop if missing; do not guess.
+- `<plugin-root>/includes/verification-boundary.md` — the required split between focused local proof and exhaustive exact-head hosted CI.
 - A git repository must be present and `git status` available.
 - The `tdd` skill must have cleared all six phases for any new or modified feature code in the staged set. If `tdd` is incomplete, STOP and surface the gap.
+- The discovered authoritative spec/plan pair, when this commit belongs to a
+  `/feature` or `/sprint` pipeline. For HTML, load
+  `<plugin-root>/includes/artifacts.md`; use the engine `identity` and `eligible`
+  results, and treat the exact spec and plan identities plus the acceptance
+  receipts bound in engine state as the commit proof. Require
+  `all_accepted_and_current: true` before this gate can commit completed plan
+  work. The gate must not parse rendered HTML and must not consult a shadow
+  Markdown ledger. Displayed state, checkboxes, hashes, or caller-supplied
+  labels cannot substitute for current engine acceptance.
+
+For that HTML pair, invoke the installed bridge's
+`_preflight_current_acceptance` with the exact `_resolve_workflow_pair` result,
+the repository-bound client, and the spec/plan IDs returned by the engine. Use
+its returned identities and receipts as the proof for this gate. A refusal is a
+BLOCK before staging or committing; never construct an equivalent proof from
+caller metadata.
 
 ## Phase 1 — Permission · gate: BLOCK
 
@@ -49,9 +66,10 @@ Gate: the staged set is type-homogeneous with a single type and scope.
 
 ## Phase 4 — Verification · gate: BLOCK
 
-Read the test, lint, and secrets-scan commands from `tech-stack.md`. Then:
+Read the test, lint, and secrets-scan commands from `tech-stack.md`, then apply
+`<plugin-root>/includes/verification-boundary.md`:
 
-- Run the test command. ALL tests green. Any failure blocks.
+- Run the impact-bounded local tests that directly cover the staged paths and obligations. Any failure blocks. Repository-wide and cross-platform suites belong to exact-head hosted CI before merge, not this commit gate.
 - Run lint, and the type-check if the project is statically typed. Zero errors.
 - Run the secrets scan on ALL staged files, regardless of commit type. Any finding blocks.
 - **Security gates (mandatory routing):** if the staged diff touches crypto/TLS or secret patterns, route it through `crypto-compliance` (`<plugin-root>/routines/crypto-compliance/SKILL.md`) and/or `secret-handling` (`<plugin-root>/routines/secret-handling/SKILL.md`) — they scan against `security-controls.md` and, on pass, record the diff-bound marker `.codearbiter/.markers/security-gate-passed` (via `hooks/security-pass.py`). This is not optional: the PreToolUse commit hook **H-09b/H-10b blocks the commit** until that gate pass is recorded AND covers every sensitive line being committed.
@@ -60,7 +78,7 @@ Read the test, lint, and secrets-scan commands from `tech-stack.md`. Then:
 
 Record each result (PASS / BLOCK) for the report.
 
-Gate: test, lint, secrets scan, and (when crypto/secret is touched) the security gate all PASS. Any failure halts the commit until fixed and re-run.
+Gate: the applicable focused tests, lint/type-check, secrets scan, and specialized gates all PASS. Any failure halts the commit until fixed and re-run. This gate does not claim that exhaustive hosted CI has run; `finishing-a-development-branch` proves that separately before merge.
 
 ## Phase 5 — Behavioral proof · gate: BLOCK
 
@@ -68,7 +86,11 @@ Apply the shared fresh-run discipline in `<plugin-root>/includes/fresh-verificat
 **the spec's acceptance criterion** as the target — prove the behavior against the spec, not against a
 self-report.
 
-- Identify the proving command or observable: the acceptance criterion from `<project-root>/.codearbiter/specs/<slug>.md` (or the task's verification in the plan). If none exists, derive the smallest command that exercises the claimed behavior.
+- Identify the proving command or observable from the selected authoritative
+  pair. For Markdown, use the existing criterion and task-verification text. For
+  HTML, use the exact criterion and task records returned by symbol-scoped
+  engine `read`; never scrape the rendered document. If none exists, derive the
+  smallest command that exercises the claimed behavior.
 - Run it fresh in this phase, read its output and exit code, and confirm the observed behavior matches the spec's acceptance criteria. A mismatch, or an unverifiable claim, blocks.
 
 **Stakes:** a behavioral-proof mismatch means the change does not do what the spec claims — state what would ship broken if this passed ("the retry path never fires; a transient error would hang the caller"), not just "proof mismatch." That gap is exactly what a green-looking suite hides.
@@ -94,7 +116,9 @@ Read the complete staged diff (`git diff --cached`). Flag as blocking:
 - Tests disabled or skipped that were not intentionally disabled.
 - Scope creep — changes outside the agreed feature or fix boundary.
 
-**Board-edit exemption (ADR-0008):** an edit to `open-tasks.md` where `_taskboardlib.classify_board_diff(old, new)` returns a clean transition (done-flip `[~]`→`[x]`, start-flip `[ ]`→`[~]` with its optional minted dotted ID, or a single queued-add `[ ]`) is **expected and RETAINED** — it is not scope creep and MUST NOT be unstaged. Any other `open-tasks.md` change — a reworded or deleted entry, or an arbitrary content edit — does not classify as a transition and still flags as scope creep.
+**Board-edit exemption (ADR-0008):** ADR-0008 governs three transitions riding a commit whose primary purpose is something else — a board edit inside such a commit is **expected and RETAINED** (not scope creep, MUST NOT be unstaged) only when `_taskboardlib.classify_board_diff(old, new)` returns a clean transition (done-flip `[~]`→`[x]`, start-flip `[ ]`→`[~]` with its optional minted dotted ID, or a single queued-add `[ ]`). Any other `open-tasks.md` edit riding an unrelated commit does not classify as one of those transitions and still flags as scope creep — it does not belong to that commit's agreed boundary.
+
+This does not cover a commit whose own Phase 3 classification **is** the board change — e.g. a `docs` chore whose sole content is a `/ca-standup` archival sweep (open-tasks.md removals plus the matching `done-tasks.md` append). There, the boundary was already agreed at Phase 3, so those edits are in-scope by that classification directly; `classify_board_diff` is not consulted and does not need to recognize archival as a fourth transition.
 
 **Provenance re-baseline exemption (ADR-0008):** a `.codearbiter/.provenance/<doc>.json` file written by the Phase 5.5 auto-heal re-baseline is likewise **expected and RETAINED** — it is not scope creep and MUST NOT be unstaged. A heal-proposed doc or code-map edit (the claim-changed path from Phase 5.5) appears in the diff for normal review; treat it as any other finding. This exemption waives the scope-creep flag only; the secrets check is not waived — the automated re-scan in Phase 5.5 covers the provenance file.
 
@@ -142,6 +166,7 @@ Gate: the commit lands and `git status` is clean. Unexpected uncommitted changes
 - MUST NOT commit to `main`, `master`, or any protected branch.
 - MUST NOT run `git add -A`, `git add .`, or any wildcard staging.
 - MUST NOT commit while any test is failing, any lint error stands, or any secret is present.
+- MUST NOT turn exhaustive repository-wide or cross-platform CI into a local prerequisite when the shared `verification-boundary` assigns it to exact-head hosted CI.
 - MUST NOT accept a self-reported "it works" — prove the behavior against the spec with a fresh command run (Phase 5) before committing.
 - MUST NOT skip, disable, or work around any automated gate.
 - MUST NOT commit a staged database migration without a recorded migration-review pass — the H-14 hook blocks it until `migration-reviewer` passes and `hooks/migration-pass.py` records the content-bound marker.

package/plugins/ca-pi/routines/executing-plans/SKILL.md

@@ -6,6 +6,19 @@ disable-model-invocation: true
 
 # executing-plans
 
+## Structured-artifact format boundary
+
+New full-lane workflows default to HTML through the installed engine. Existing
+HTML pairs use the same path. Load
+`<plugin-root>/includes/artifacts.md` before HTML artifact I/O;
+its typed identity, binding, receipt, contextual-read, and scope-state rules
+replace rendered-document parsing and direct status-cell edits. Existing
+authoritative Markdown pairs stay on their exact legacy path without conversion.
+A missing, invalid, or unqualified HTML capability must fail closed rather than
+fall back to new Markdown authority. HTML `--farm` dispatch remains disabled.
+Keep every other workflow gate, including human checkpoints, unchanged.
+
+
 Coordinate the plan in small, user-acknowledged batches. Routed to by `/feature` after
 `writing-plans` has produced a plan. Each batch is executed by `subagent-driven-development` — fresh
 author agent per task, spec-compliance review, quality review, fresh verification — and the user
@@ -15,8 +28,15 @@ checkpoints between batches. The orchestrator never implements; it schedules and
 
 Read these, or STOP and surface the gap — never guess a path, a command, or a task boundary:
 
-- `<project-root>/.codearbiter/plans/<slug>.md` — the approved plan. The ordered task list and each task's verification command are the contract. No plan, no execution.
-- `<project-root>/.codearbiter/specs/<slug>.md` — the spec the plan implements.
+- The discovered authoritative spec/plan pair. Existing Markdown pairs retain
+  their current ledger. For an HTML pair, load
+  `<plugin-root>/includes/artifacts.md`, retain the exact artifact identities
+  and engine-written receipts, and obtain task, scope, dependency, and binding
+  state only through `identity`, `index`, `outline`, symbol-scoped `read`, and
+  `eligible`. The engine `eligible` response is authoritative; the coordinator
+  must not infer authority from rendered text, checkboxes, status words,
+  digests, or caller-supplied labels, and must not read or write a shadow
+  Markdown ledger.
 - `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
 - `<project-root>/.codearbiter/tech-stack.md` — the exact verification, test, and build invocations.
 
@@ -25,10 +45,20 @@ Read these, or STOP and surface the gap — never guess a path, a command, or a
 Group the plan's tasks into small batches. Keep batches tight — three to five tasks is a ceiling, not
 a target. Respect the plan's ordering and dependencies: a task never lands before the task it depends on.
 
-**Resume is the normal re-entry.** A task already `ACCEPTED` in the plan's status column was verified
-before an earlier interruption — exclude it from batching and say so ("resuming: T-01–T-03 already
-ACCEPTED"). Batch only the non-`ACCEPTED` tasks, starting at the first. Never re-execute an `ACCEPTED`
-task, and never restart the pipeline at brainstorming because the session died mid-plan.
+**Resume is the normal re-entry.** For Markdown, a task already `ACCEPTED` in
+the plan's status column was verified before an earlier interruption. For HTML,
+derive the same decision from the current `eligible` result and its exact task
+identities. Exclude accepted tasks from batching and say so ("resuming: T-01–T-03
+already ACCEPTED"). Batch only the remaining tasks, starting at the first. Never
+re-execute an accepted task, and never restart the pipeline at brainstorming
+because the session died mid-plan.
+
+After process recreation on an HTML pair, rediscover the same authoritative pair
+and query `identity` and `eligible` again. An `IN_PROGRESS` task is not proof of
+completion: capture the existing reconciliation authority and apply
+`task-reconcile` before redispatch through `task-start` with a fresh complete
+context ticket. A task in `REVIEW` still requires fresh evidence and the current
+scope review before `accept-scope`; conversation memory cannot advance it.
 
 For each task, confirm the plan names its exact target paths and its verification command. A task
 missing either is underspecified — return it to `writing-plans`, do not improvise the gap.
@@ -48,6 +78,12 @@ Invoke `subagent-driven-development` (`<plugin-root>/routines/subagent-driven-de
 spec slug so it can read its own pre-flight files. Do not implement anything here — the author agents,
 review chain, and verification all run inside that skill.
 
+For HTML, pass the selected spec/plan identities and task IDs, not copied task
+labels or prose. The nested workflow records dispatch with `task-start`, records
+the separate verification and spec-review receipts with `task-review`, and
+records whole-scope acceptance once with `accept-scope`. Preserve every returned
+identity and receipt for the checkpoint and later commit proof.
+
 `subagent-driven-development` returns when every task in the scope is `ACCEPTED` (Phase 3–5 green,
 verification passed on a fresh run). A `tdd` BLOCK, a security CRITICAL finding, or an unresolved
 `[CONFIRM-NN]` surfaced inside that skill halts the loop — surface it to the user and do not proceed.
@@ -71,11 +107,20 @@ Gate: the user has acknowledged the checkpoint. On acknowledgement, loop to Phas
 batch. When the final batch is acknowledged and the plan is fully verified, route to `commit-gate` —
 do not commit from here.
 
+Before claiming that an HTML plan's final batch completed, use the installed
+bridge's `_preflight_current_acceptance` with the exact route returned by
+`_resolve_workflow_pair`, the repository-bound client, and the engine-returned
+spec and plan artifact IDs. Pass no caller status, digest, receipt, or label.
+Retain the returned engine identities and receipt set for `commit-gate`. Any
+refusal leaves the batch incomplete and blocks the handoff.
+
 ## Hard rules
 
 - MUST NOT execute tasks inline — delegate every batch to `subagent-driven-development` with an explicit `scope`.
 - MUST NOT advance past a checkpoint the user has not acknowledged.
-- MUST NOT call `commit-gate` until all batches are acknowledged and every plan task is `ACCEPTED`.
+- MUST NOT call `commit-gate` until all batches are acknowledged and every plan
+  task is accepted; for HTML this means a fresh `eligible` result reports
+  `all_accepted_and_current: true` for the selected plan identity.
 - MUST surface any halt from `subagent-driven-development` (tdd BLOCK, CRITICAL, CONFIRM-NN) to the user — do not swallow it or re-dispatch around it.
 - MUST NOT absorb scope the plan does not name — mark it `[NEEDS-TRIAGE]`.
 - MUST NOT commit; route to `commit-gate` when the plan is fully verified.