@arbiterforge/ca-pi 0.18.4 → 0.20.0

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

@@ -1,494 +1,140 @@
-# 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. The payload ships only through the release
-channels: Claude Code `/plugin marketplace update codearbiter` then
-`/plugin update ca@codearbiter`; Codex the `ca-codex-marketplace` ref; Pi
-`pi install npm:@arbiterforge/ca-pi`. A main-branch checkout never carries it. 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.
-
-## Installed host admission
-
-Before new full-lane or plan authoring, the bridge checks the exact installed
-host's required producers, helpers, reviewer charter where applicable, and
-platform-specific hook registrations. `_select_authoring_route` and
-`_preflight_plan_authoring` require this read-only preflight in addition to the
-native engine capability. `HOST_WORKFLOW_UNAVAILABLE` stops before authoring;
-repair the installed package or use a supported host. Never create a fallback
-artifact, substitute another package, or mint an authority event to proceed.
-
-`ArtifactClient.workflow_preflight()` reports only installed resources. It does
-not prove host trust, enabled hooks, supported host-version behavior, reviewer
-independence, or a completed live workflow. Actual authority producers and their
-existing validation remain required. Pi currently fails this admission check;
-existing Markdown pairs and the inline small feature lane are unchanged.
-
-## 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.
-
-Before requesting review or approval of a plan, use the private
-`_approvallib._preflight_plan_verification(client, identity)` with its current engine identity.
-It checks all task verification definitions through complete bounded engine reads
-and collects the current source-input snapshot, reporting every unsupported
-command and any input-policy failure together. Both ordinary and initial paired
-approval arming enforce this check. No declared command, test discovery, or test
-module is executed or imported. Proposed test files and names may be absent;
-the installed collector still has to support the proposed runner's output format.
-Missing package-script definitions cannot establish a runner contract: declare a
-supported direct runner or supply the reviewed script definition first. Runtime
-executable/workspace binding and fresh named-result evidence remain required.
-
-`verification_inputs.roots` and `exclude_directories` use exact slash-separated
-repository-relative paths. Exclusions are directory paths, not globs or basename
-matches and not relative to an individual root. For root `site`, a generated
-dependency exclusion is `site/node_modules`, not `node_modules`. Review each
-excluded output directory explicitly: the plan's roots and exclusions narrow
-the ship set. In a git work tree `.gitignore` already keeps untracked ignored
-files out of it; outside git nothing is filtered, so exclude generated
-directories explicitly.
-An exclusion outside all selected roots is rejected as ineffective. Overlapping
-roots cannot reinclude an excluded directory. Roots must exist before execution;
-use an existing containing directory for a planned new file so its creation
-changes the snapshot. An oversized included file is reported with its path and
-the 32 MiB per-file limit; revise the explicit policy rather than increasing the
-limit or excluding source/test/governance inputs needed for the task.
-
-Snapshot input identity is ship-set membership. In a git work tree the members
-are the git index entries present on disk, plus untracked non-ignored files
-within the plan's roots, minus its excludes. The one fixed exemption is
-`.codearbiter/gate-events.log`: it is never counted, whatever the plan says, and
-stays tracked as the audit trail; every other `.codearbiter` path still counts.
-Outside git, membership is read from the filesystem (`membership: filesystem`);
-the root must be the top level of its work tree, so a subdirectory root counts as
-outside git. A failed git probe fails closed with `INPUT_MEMBERSHIP_UNAVAILABLE`. An unmerged
-git index (conflicted paths) makes a snapshot fail closed until it is resolved.
-The manifest format is `codearbiter.verification-inputs/0.2.0`; receipts bound to
-a 0.1.0 manifest read as stale. Each evidence object is validated at most once
-per operation and scans are bounded; raw reads are reused only up to a 64 MiB
-per-operation retained-byte budget, past which an object can be read again, but
-validation is never skipped.
-
-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 1.0.0 exposes an `input`
-event, but codeArbiter has no Pi-native authority adapter. Under Pi do not arm this
-adapter; the workflow remains blocked until that 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>
-```
-
-On Claude Code, when the result carries `ask_envelope`, pass it unchanged as the
-entire AskUserQuestion input (no `answers`, `annotations` or other field): the
-user approves by clicking its Approve option, and the host-observed selection is
-applied with origin `claude:AskUserQuestion:<session>`. Otherwise, or if the
-user prefers typing, present the returned `short_reply` (a four-character code
-such as `approve K7MQ`); the full `reply` is also accepted, and you
-require that exact reply: the hook tolerates surrounding whitespace, invisible characters, a code
-fence or quotes and a closing period, but nothing else in the message, and it
-reports a mismatch instead of staying silent. The `UserPromptSubmit` hook
-rechecks the armed identity, records the full armed reply as the host-observed
-policy-owned source, captures its receipt, and applies approval. An ordinary
-`yes`, a changed artifact, a wrong or expired code, a reply inside other text, 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. Legacy `capture` events remain readable for
-inventory but are inspection-only: the engine refuses to wrap them in a current
-receipt. Current authority requires `capture-observation` over a closed producer
-profile and engine-issued evidence context; never create an authority source
-merely to satisfy an artifact transition. `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.
-
-For ordinary sequential planning, create a plan as `draft_preview`, consume existing criterion IDs,
-then `plan-bind` to the approved spec and approve the plan through its existing workflow. Initial
-combined HTML sprint review uses the explicit paired path below instead of separate approvals.
-A normative change invalidates its approval. Rebinding is explicit and preserves
-history; it does not waive coverage or permit silent reinterpretation.
-
-When adversarial review revises a ready initial draft spec after its draft plan exists,
-query both current identities. The installed engine's explicit `plan-bind` request with
-`binding_mode: draft_preview` requires the plan's existing `expected` CAS and the spec's
-`spec_expected` revision/model CAS. It rebinds only that same-ID, same-slug initial pair:
-both artifacts must remain unapproved drafts, tasks pending and unevidenced, prerequisites
-unsatisfied and unevidenced, and scopes empty. Optional typed plan corrections must leave
-both drafts fully ready. The binding remains `draft_preview`; this operation grants no
-approval, delegation, prerequisite satisfaction, execution or acceptance. Revalidate both
-current drafts, repeat the affected review and arm the exact combined approval afterward.
-Inspect the installed operation schema first. An engine without this explicit draft
-request reports a capability gap; never edit HTML, recreate the pair, substitute sequential
-approval or use ordinary approved-source `plan-bind` to repair it.
-
-## Initial sprint pair and delegated methods
-
-Only when preparing initial combined approval, replaying an observed reply, or revising a task's
-method under its existing grant, load `<plugin-root>/includes/sprint-authority.md`. That private
-card owns the `arm-sprint` / `resume-sprint` / `smarts` bridge and the native pair/method operations.
-Do not bulk-load it for ordinary task reads. Scoring is not consent; the initial observed user reply,
-protected scope, real producer, current evidence and existing security/permission gates remain required.
-
-## 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.
-
-Before task selection, inspect the plan's exact prerequisite records. If one is
-unsatisfied, collect and present the facts needed to judge its requirement; a
-verification runner may supply facts but cannot confer prerequisite authority.
-On Claude Code or Codex, arm a genuine user-workflow decision for the exact
-current approved plan and prerequisite:
-
-```sh
-python "<plugin-root>/hooks/_prerequisitelib.py" arm --root "<project-root>" --artifact-id <artifact-id> --prerequisite-id <prerequisite-id>
-```
-
-Show the returned title, requirement, review-packet digest, and `expires_at_utc`
-deadline. The request and its reply code expire together 24 hours after arming.
-Require the returned `short_reply` (`satisfy-prerequisite <code>`) or the full `reply`, with
-the same tolerance and mismatch reporting as approval. The `UserPromptSubmit` hook
-durably records that observed decision before publishing its authority source,
-captures a prerequisite receipt, and applies the existing prerequisite CAS
-operation. Its final nonce is non-secret freshness/correlation data, not a
-credential: possession alone confers no authority, and only the exact prompt
-observed at the trusted host boundary while the reviewed plan remains current
-can satisfy the prerequisite. Wrong nonces or records, stale plan content or
-approval, and expired requests confer no authority. A retry after confirmation reuses the same event,
-receipt, operation ID, and mutation request; it never reconstructs a decision.
-Only an unconfirmed request can be cancelled:
-
-```sh
-python "<plugin-root>/hooks/_prerequisitelib.py" cancel --root "<project-root>" --artifact-id <artifact-id> --prerequisite-id <prerequisite-id>
-```
-
-If the plan changes after confirmation, recover the obsolete request instead of
-deleting its marker. `supersede` first proves the current identity differs. For
-a captured request it also retries the exact operation ID: a committed replay is
-accepted, while only an engine `REVISION_CONFLICT` proves the obsolete mutation
-did not commit and permits the marker to clear. Published source and receipt
-files remain as evidence:
-
-```sh
-python "<plugin-root>/hooks/_prerequisitelib.py" supersede --root "<project-root>" --artifact-id <artifact-id> --prerequisite-id <prerequisite-id>
-```
-
-The adapter fixes `authority_kind: user_workflow` and `verdict: satisfied`;
-there is no caller-selected authority or bulk-satisfaction path. SMARTS prerequisite satisfaction remains unsupported; the plan-method producer below does not
-grant prerequisite, security, backend or publication authority. Pi has no
-prerequisite-capture adapter and must remain blocked. Do not infer eligibility from one satisfied prerequisite:
-rerun `eligible`, and resolve each remaining record independently against the
-new current plan identity.
-
-`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 through the installed production authority adapter; it never
-constructs a successful workflow event itself. Arm an exact task request first.
-Verification and review authority below is supported on Codex and Claude Code.
-On Pi, stop at this boundary rather than treating model-authored results as
-authority; its installed prompt approval seam does not imply verification or
-review support.
-Every distinct `cwd` label in the engine context must be mapped once to an exact
-linked Git worktree root. Mapped worktrees must share the artifact repository's
-Git common directory, and the adapter freezes their filesystem identity, HEAD,
-status digest, effective argv, and executable bytes:
-
-```sh
-python "<plugin-root>/hooks/artifact-authority.py" arm --root "<project-root>" --artifact-id <plan-id> --record-id <task-id> --activity verification --workspace "candidate worktree=<absolute-worktree>" --workspace "baseline-evidence worktree=<absolute-worktree>"
-```
-
-Use only the mappings actually named by that task; missing or extra labels fail
-closed. Run the returned request through one plain governed exec invocation (no
-compound shell expression), then publish only after the host's matching
-`PostToolUse` has corroborated the wrapper's completed request-bound result:
-
-```sh
-python "<plugin-root>/hooks/artifact-authority.py" verify --root "<project-root>" --request-id <request-id>
-python "<plugin-root>/hooks/artifact-authority.py" publish --root "<project-root>" --request-id <request-id>
-```
-
-The verifier launches exact engine-declared argv without a shell, supervises the
-whole process tree, bounds output, requires exact named outcomes, and rejects
-workspace or executable drift. If an attempt is interrupted, use the adapter's
-`recover` operation to retain it as failed or abandoned; never rerun an uncertain
-attempt under the same request.
-
-Named Playwright commands require `test --reporter=json`; each required name must
-equal a unique native `spec.title`. Named Vitest commands require
-`run --reporter=verbose`; use the complete rendered `suite > case` identity after
-the filename, not a leaf-name alias. Named unittest commands require `-v` or
-`--verbose`. A passing row cannot conceal a duplicate, skip, failure or retry.
-Plain exit checks cannot attest named tests.
-
-Named npm commands support inspectable single-runner scripts, a contained
-repository-relative `--prefix`, and arguments forwarded after `--`. A root script
-may delegate once through `npm -w <name> run <script>` or
-`npm --workspace <name> run <script>` when the name resolves uniquely in an array
-of at most 32 explicit, contained workspace directories. The runner binds the root
-manifest and every inspected workspace manifest. Globs, linked directories,
-multiple workspace selectors and recursive npm delegation are unsupported.
-Workspace delegation uses the declared cwd; a non-dot `--prefix` is unsupported
-for this shape.
-Preserve both npm argument boundaries when adding a reporter: for a root
-`test:client` script containing `npm -w @example/client run test`, declare
-`npm run test:client -- -- --reporter=verbose` to forward the reporter to Vitest.
-The original root command still executes the full script. Compound
-scripts and pre/post lifecycle scripts require separately declared direct-runner
-commands; retain every check from the original suite when splitting commands.
-On Windows, only the qualified standard `npm.cmd` layout is adapted: the runner
-pins the wrapper, sibling `node.exe`, sibling `node_modules/npm/bin/npm-cli.js`,
-and script manifest. It deliberately selects that sibling CLI rather than the
-shim's optional global-prefix redirection. Unknown batch wrappers fail closed.
-For workspace delegation, it also pins `npm-prefix.js` and checks that the nested
-wrapper uses the same CLI, the default script shell, and no configured Node
-options. Local executables shadowing nested npm are rejected.
-Direct Node script entrypoints are also pinned. These launch-file bindings do
-not establish transitive dependency closure for deliberately excluded inputs.
-
-New observations use the closed `declared-command/0.3.0` producer profile to
-retain collector and launch-file identities plus an engine-produced normalized
-completion closure. Raw workspace fingerprints must still match before and
-after command execution. Historical `0.1.0` and `0.2.0` bindings retain their
-original contracts and cannot be relabelled as newer evidence.
-
-For `spec_review` or `quality_review`, arm the corresponding activity without
-workspace mappings and dispatch the returned `launch_envelope` unchanged to one
-fresh host subagent. The bounded prompt names the retained, content-addressed
-evidence context instead of embedding its full input manifest. The reviewer
-must read that context and inspect its subject, coverage and source inputs.
-The adapter verifies the context's canonical bytes and digest before launch and
-publication; a missing or changed context blocks authority. Never shorten or
-rewrite the returned envelope yourself.
-The host hooks bind the exact launch call, child start and
-the child's first stop; a pasted or coordinator-authored decision is not review
-authority.
-
-When reviewing completed work that relies on a verification run, linked
-worktrees or supporting evidence, explicitly select the completion path. Add
-`--completion-receipt <exact-published-receipt>` once per task and
-`--supporting-file <absolute-regular-file>` for each supporting document to the
-review `arm` command. A task review selects one verification receipt; a scope
-review selects the exact receipt for every member. Supporting files require a
-receipt selection. The existing review-before-verification path remains
-available; it does not satisfy an explicitly requested completion review.
-
-The native engine validates the selected published verification chain and
-derives the worktree mappings from its qualified observation. It retains the
-selected identities, worktree closure and supporting bytes in the immutable
-context. Supporting material is data for review, not authority. Selection is
-explicit: no newest-receipt search, directory import or attachment execution.
-At most 16 regular files are admitted, each at most 64 KiB and together at most
-256 KiB; links, reparse indirection, duplicate paths and changed content fail
-closed. Read canonical spec and plan artifacts through the native artifact API;
-they cannot be imported as supporting files. The generated prompt directs the reviewer to assess performed work
-against each criterion, step and `done_when` obligation, using selected evidence
-and source references. A consistent plan or an empty diff is insufficient.
-
-Use the returned `completion_sha256` in the native `task-review` or
-`accept-scope` request. The completed review and its exact verification run must
-agree; a definition-only review or a different successful run is rejected.
-The recorded task selection remains required by downstream freshness and scope
-acceptance. Scope review uses validated task completion bindings. If verification
-is rerun, obtain and record its completed task review before selecting that run
-for scope review; do not infer equivalence between receipts.
-
-Creating a completion context for a `0.3.0` verification recomputes the normalized
-worktree closure bound during that verification. Only validated native outputs
-and execution bookkeeping are normalized; their publication must not invalidate
-unchanged source. Historical `0.2.0` verification retains its initial exact raw
-fingerprint comparison. Later freshness checks allow native task-status and
-execution bookkeeping updates in validated canonical artifacts while retaining
-their normative content hashes.
-Changes to task definitions, other HTML or other governance files still affect
-freshness under the normal snapshot policy. The closure covers
-tracked working-tree bytes and non-ignored untracked files, not ignored
-dependencies or outputs. The completion assessment is still an independent
-reviewer's judgment; schema validation does not prove that every file was read
-or every conclusion is correct. Preserve the unchanged launch envelope and
-genuine host capture throughout this path.
-Publish the completed request through the same `publish` command. `task-review`
-records the separate verification and spec-review receipts. After every task in
-the scope reaches `REVIEW`, reverify against one current source snapshot, run the
-combined quality review, and use `accept-scope` once. Do not accept tasks
-individually.
-
-Current Codex native V1 completion reviews retain the full frozen context in
-its immutable, content-addressed file and keep only its closed reference in
-mutable request state. Loading validates the exact context locator, hash,
-canonical bytes and review kind. The native context budget remains 8 MiB;
-mutable request state remains bounded at 1 MiB. Before dispatch, the adapter
-reserves the exact fixed result identities, six times the 64 KiB decision
-budget for canonical JSON escaping, and 32 bounded 256-byte lifecycle slots.
-A request without that capacity is refused before child launch. Historical
-inline requests retain their existing limits and abandonment-only recovery.
-
-An ARMED review that never launched can be abandoned through the adapter:
-
-```sh
-python "<plugin-root>/hooks/artifact-authority.py" recover --root "<project-root>" --request-id <request-id> --disposition abandoned
+# Structured specifications, plans and task state
+
+Load for new full-lane work or an existing HTML spec/plan pair. The plan tracks
+the agreed outcome, implementation and checks; it does **not** create a second
+permission system. Follow real user decisions, host security and Git/release
+authorization independently.
+
+## Format and installed writer
+
+New full feature and sprint spec/plan pairs default to canonical `.html`.
+Check the installation-pinned native capability **before writing**. If it is
+missing, invalid or denied, report the failed operation. It must not fall back to Markdown
+or claim the artifact was saved. New files are
+`.codearbiter/specs/<slug>.html` and `.codearbiter/plans/<slug>.html`.
+An existing `.md` pair remains Markdown in its original format; do not
+silently convert it or create a shadow ledger. Small-lane features stay inline.
+HTML `--farm` dispatch remains disabled.
+
+Use `hooks/_artifactlib.py`, which selects the installation-owned binary by
+its verified manifest, never PATH or a project-selected executable. Native
+`_select_authoring_route` and `_preflight_plan_authoring` select the same-slug
+source/target, check identity and structural validity, then return a draft
+target. They do **not** approve work or launch reviewers. This includes the
+native Pi writer; it does not establish broader installed-host qualification.
+
+## Author and maintain
+
+Use native `create` and typed `apply`, not manual HTML/JSON editing. Keep stable
+spec criterion IDs in the plan; use `record.add`/`record.update` and explicit
+retirement reasons. Bind the exact current spec using `plan-bind`.
+Incomplete drafts are valid working state. `validate` with `gate: ready`
+reports missing coverage or structure, not permission to continue already
+authorized work. Do not invent criteria, decisions or test results to pass
+validation. A changed outcome goes to the actual decision owner; in-scope
+methods and task decomposition can be updated with a reason.
+
+A spec's SMARTS design rationale is stored in its existing `approach` record, bound
+`decisions` records and one `SEC-SMARTS` section, as defined once in
+`<plugin-root>/includes/smarts/core.md` (Design rationale record); a legacy Markdown spec
+uses its one `## SMARTS design rationale` section instead.
+
+Query an operation-specific `schema` only when its request shape is unknown;
+reuse known shapes for subsequent calls instead of querying on every read.
+Do not preload the entire schema. The packaged bridge invokes the verified native
+binary as `ca-artifact <operation> --root <project-root> --request -`
+with one JSON request on stdin; never resolve it from PATH. Requests use
+protocol `codearbiter.artifact-api/0.1.0`; failed writes remain failures.
+
+From the workspace root, pass this block on Python 3's stdin (`python -B -
+'<absolute-installed-plugin-root>' '<plan-id>' '<task-id>'`, using your shell's
+multiline stdin syntax and quoting). Use the host's loaded plugin root, not a
+guessed project path. No helper script or directory outside the workspace is
+needed. The client adds the protocol field; its second argument is the helper
+installation, **not** the plugin root. Add `--schema` only when you need the
+operation's request schema instead of the task packet.
+
+```python
+import json
+import sys
+from pathlib import Path
+
+plugin = Path(sys.argv[1])
+plan_id, task_id = sys.argv[2:4]
+sys.path.insert(0, str(plugin / "hooks"))
+from _artifactlib import ArtifactClient, helper_installation
+
+client = ArtifactClient(Path.cwd(), helper_installation(str(plugin / "hooks/_artifactlib.py")))
+if "--schema" in sys.argv[4:]:
+    print(json.dumps(client.call("schema", {"name": "operation", "operation": "task-context"})))
+else:
+    identity = client.call("identity", {"artifact_id": plan_id})
+    packet = client.call("task-context", {
+        "artifact_id": plan_id, "task": task_id,
+        "model_sha256": identity["model_sha256"],
+    })
+    print(json.dumps(packet))
 ```
 
-The adapter requires no attempt, launch, observation, receipt or prior recovery.
-It retains the request and its evidence, creates no receipt, and prohibits
-dispatching that request again. This also covers bounded legacy requests whose
-inline manifests made them too large for normal dispatch. Launched or captured
-requests remain subject to their existing recovery rules. Arm a new request
-only after the retained request is terminal.
-
-An interrupted or `BLOCKED` HTML task never resumes by editing its status. Arm
-the installed reconciliation adapter for the exact task or scope, present its
-returned `short_reply` (`reconcile <STATE> <code>` for a task, `reconcile <code>`
-for a scope; the full `reply` also works), and let `UserPromptSubmit` capture and apply the observed
-user decision across repositories:
-
-```sh
-python "<plugin-root>/hooks/artifact-reconcile.py" --root "<project-root>" --artifact-id <plan-id> --target-id <task-id> --operation task-reconcile --target-state PENDING --reason "<reviewed reason>" --assessment "<reviewed assessment>"
-python "<plugin-root>/hooks/artifact-reconcile.py" --root "<project-root>" --artifact-id <plan-id> --target-id <checkpoint-id> --operation scope-reconcile --assessment "<reviewed assessment>"
-```
-
-Ambiguous armed requests, changed identities, stale inputs, wrong replies, or a
-foreign Git repository all fail closed. Re-run `eligible` after reconciliation;
-the prompt reply itself is not proof that the lifecycle mutation committed.
-If a mutation response is lost, submit the same exact reply again: the adapter
-replays its durable operation ID and receipt without recapturing authority. A
-request that has not reached mutation can be cancelled with:
-
-```sh
-python "<plugin-root>/hooks/artifact-reconcile.py" --root "<project-root>" --artifact-id <plan-id> --cancel --prompt "<exact returned reply>"
-```
-
-If a crash left a complete pending request before its prompt route was
-registered, use this command instead. It refuses an active route or any
-in-flight mutation:
-
-```sh
-python "<plugin-root>/hooks/artifact-reconcile.py" --root "<project-root>" --artifact-id <plan-id> --cancel-orphan
-```
-
-If a durable mutation attempt exists, neither cancellation path can clear it.
-Replay the exact stored operation and receipt under the reconciliation lock:
-
-```sh
-python "<plugin-root>/hooks/artifact-reconcile.py" --root "<project-root>" --artifact-id <plan-id> --recover
-```
-
-Recovery clears the request only on a committed replay or a closed-set engine
-result proving no commit (`REVISION_CONFLICT` or `OPERATION_ROLLED_BACK`). Other
-errors retain it for investigation. Re-arm only after cancellation or recovery
-succeeds; a committed recovery is not permission to repeat the mutation.
-
-`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.
+## Read the smallest useful context
+
+Use `identity` and `eligible` (advisory scheduling), then `task-context` with
+the current plan `model_sha256` and task ID. Read the task, its referenced
+criteria, dependency states and relevant prerequisite observations. The packet
+has `context_complete: false`; expand only necessary exact symbols via
+`read`/`read-batch` rather than parsing rendered HTML. Recheck identity after
+a changed source or stale cursor. On a packet-size refusal, retrieve complete
+individual records within the supported budget; do not accept truncation.
+If an installed engine lacks `task-context`, use those existing bounded
+symbol reads.
+
+A fact or observable prerequisite is checked with ordinary authorized tools;
+record its outcome through the native `prerequisite` **bounded `observation`**
+with `kind: fact`, source and relevant `task_refs`. A decision reflects an
+actual user choice; ask once if material and unresolved. Keep caller-reported
+facts distinct from host-attested proof, and **no certification code** for
+ordinary work. An unscoped prerequisite has unknown applicability, not
+automatic plan-wide blocking or implicit satisfaction. Continue independent
+tasks.
+
+## Implement and report reality
+
+Start an eligible pending task with `task-start`; no artifact approval,
+context ticket or reviewer receipt is required. A real check belongs in
+`task-check`: observed argv, relative cwd, outcome (pass/fail/skip/unknown),
+summary, source and origin (`tool_result` or `agent_report`). Supply exit code
+only when actually observed; bind `command_index` only to the exact planned
+invocation. Command-level success is not invented named-test proof. A newer
+failure/unknown cannot be hidden by an older pass.
+
+`task-context` reports bounded, declared-path and `shared_inputs` source
+applicability. `scoped_changed` means recheck affected work;
+`scoped_unchanged` is **partial** evidence (`scope_complete: false`), not a
+full dependency graph or verified test. Unsafe or unknown file scope is
+`unassessed`. A presentation edit or new receipt identity alone does not
+require a reviewer rerun.
+
+Use receipt-free `task-review` for implementation ready for review.
+Use `accept-scope` with a reason to record a completed implementation batch
+as `DONE`; **DONE is not independently verified or accepted**. Report actual
+checks, failures and unrun verification separately. Review relevant risks;
+do not spawn a reviewer fleet to clear task bookkeeping.
+
+## Resume safely
+
+On interruption, inspect the worktree, running workers and committed state
+before changing an `IN_PROGRESS` task. Use `task-reconcile` with the actual
+state and reason; never clear a user `BLOCKED` stop without resolution.
+Every mutation needs the current revision, model hash and a durable unique
+operation ID. After a lost response, **retry the identical request and ID**
+or use native `recover`; never start duplicate work or overwrite conflicts.
+A rolled-back transaction is not success. Use `repair-preview`/`repair-apply`
+only for the native generated-view repair contract, not semantic edits.
+
+If saved state or a separately applicable policy genuinely requires strict
+attested proof or older-format recovery, consult only the relevant section of
+`<plugin-root>/includes/artifacts-attestation.md`. The optional reference
+does not authorize ordinary work or replace current host/security rules.
+Never open newer saved state with an incompatible old engine; use a matching
+installed cohort and preserve the journal. After newer edits, forward
+recovery takes precedence over overwriting current work with an old backup.