brainclaw 1.26.2 → 1.28.0

package/docs/concepts/execution-contract.md

@@ -0,0 +1,166 @@
+# Execution contract and capability snapshot
+
+Every worker-backed Loop turn now carries an immutable `ExecutionContract v1`.
+It answers a narrower question than the Loop protocol: **what exact work may
+this selected worker launch, under which capabilities and evidence rules?** The
+Loop Engine still owns phases, gates, iteration and convergence. The contract
+freezes one physical attempt at the dispatch boundary.
+
+This is shared infrastructure for all five `LoopKind` values. It is neither a
+review-loop feature nor a new workflow engine:
+
+| Loop kind | Examples of contracted worker phases |
+|---|---|
+| `review` | `findings`, `author_response`, `followup_review` |
+| `ideation` | `critique` |
+| `implementation` | `execute` |
+| `research` | `investigate`, `synthesize` |
+| `debug` | `reproduce`, `hypothesize`, `isolate`, `fix` |
+
+Engine and manual phases do not launch workers and therefore do not create an
+execution contract.
+
+## What is frozen
+
+`ExecutionContract v1` contains:
+
+- loop, turn, logical attempt epoch, Assignment and AgentRun identity;
+- LoopKind, phase and iteration;
+- completion mode and explicitly typed expected artifacts;
+- a `CapabilityRequirement`;
+- workspace scope, checkout isolation and write policy;
+- dispatch and launch-grant durations;
+- evidence requirements (`turn_id`, `run_id`, nonce and artifact-hash policy);
+- the minimum contract and AttemptAuthority protocol versions a reader must
+  understand.
+
+The logical attempt epoch belongs to immutable identity. It is distinct from
+the mutable launch-grant epoch, which may increase when an armed generation is
+revoked and safely re-armed before crossing.
+
+Canonical JSON recursively sorts object keys, removes `undefined`, preserves
+array order and normalizes strings to Unicode NFC. Its SHA-256 is the immutable
+contract identity. A policy change therefore changes the hash; equivalent
+Unicode and object-key ordering do not.
+
+## Requirement is not observation
+
+`CapabilityRequirement` says what the attempt needs. Before reservation,
+Brainclaw resolves the selected agent's declared profile into a separate,
+persisted `CapabilitySnapshot`:
+
+```text
+CapabilityRequirement + selected agent profile
+                 |
+                 v
+        deterministic resolver
+                 |
+       accepted snapshot or reasons
+```
+
+The resolver checks role, integration surfaces, execution surface and model.
+Current profiles do not attest an exact tool catalog, so a named
+`required_tools` list fails closed with `tool_catalog_unattested`; Brainclaw
+does not infer tool availability from generic MCP or skill support.
+
+For worker-backed turns, the resolved snapshot also freezes a
+`HarnessCapabilityBinding`: adapter id/version plus requested and selected model
+string. A CLI model selector is marked `unattested` unless the harness can
+actually attest account-specific availability; it is never mislabeled as an
+exact capability merely because `--model` exists. The adapter cannot change on
+replay or after a feature-flag flip. Runtime model and adapter observations are
+stored separately on AgentRun and compared with the contract-bound snapshot.
+See [Harness adapters](./harness-adapters.md).
+
+Default roles follow the work performed by each worker phase: review findings
+and follow-up plus ideation critique require `review`; research requires
+`consult`; review author response, implementation and debug require `execute`.
+A caller can provide a stricter explicit requirement when a protocol needs one.
+
+## Persistence and authority
+
+No new store or event journal was introduced.
+
+| Record | Persisted contract data | Role |
+|---|---|---|
+| `TurnReservation` | full contract, hash/reference, capability snapshot | authoritative immutable attempt record |
+| `Assignment` | hash/reference + snapshot | business projection |
+| `AgentRun` | hash/reference + snapshot + optional monotone anomaly fence | runtime projection |
+
+The Assignment and AgentRun are created or validated before the launch fence
+crosses. Recovery enriches a legacy projection only when its new fields are
+absent; a present, divergent hash or snapshot is a projection conflict. A
+pre-v1 reservation remains readable and adoptable without fabricating a
+historical contract (`contract_status: legacy_uncontracted`). New records
+always persist the complete triplet. A partial triplet fails closed because it
+cannot prove which contract and capability observation belong together.
+
+Compatibility is symmetric at the projection boundary. A legacy-shaped caller
+may replay a record that already contains P1 fields without erasing or
+conflicting with them; a P1 caller may enrich an older projection whose fields
+are absent; two present but divergent values remain a hard conflict.
+
+## Launch acceptance
+
+The safe order for every worker-backed protocol is:
+
+```text
+validate loop/slot/claim
+  -> resolve CapabilitySnapshot
+  -> build + hash ExecutionContract
+  -> reserve / commit / arm
+  -> project Assignment + AgentRun + bindings
+  -> cross launch fence exactly once
+```
+
+An adapter that can attest an accepted contract before crossing passes both the
+contract and capability-snapshot hashes to `prepareTurnExecution`; a mismatch
+is rejected before reservation and the caller may reselect a worker. The normal
+CLI path crosses the exactly-once launch fence immediately before spawn. The
+contract variables take precedence over any environment supplied by the invoke
+template. A small child bootstrap then reads the environment it actually
+received, compares it with the immutable reference and:
+
+1. writes a JSON `ack` containing the effective hashes and an
+   `accepted`/`rejected` status before invoking the worker;
+2. exposes the hashes as `BRAINCLAW_EXECUTION_CONTRACT_HASH` and
+   `BRAINCLAW_CAPABILITY_SNAPSHOT_HASH`;
+3. echoes them into the mechanical `completed` or `failed` sentinel; and
+4. asks the worker to echo them in `LANE-RESULT.json`.
+
+The dispatcher validates the acknowledgement, and harvest/reconciliation
+validate terminal evidence against the authoritative reservation reference. A
+missing or different hash after `launch.status=crossed` is a
+`post_crossing_anomaly`: convergence is withheld and `respawn:false` is
+propagated. The first observation is persisted on AgentRun as a monotone fence;
+the bootstrap ack remains a durable fallback signal. Later correct-looking
+lane or sentinel data cannot erase the anomaly. The process may already be
+running, so Brainclaw never converts this condition into a manual fallback or
+a second launch for the generation.
+
+Manual execution uses the same environment, child bootstrap, ack and terminal
+sentinels. The bootstrap creates the generation-keyed ack exclusively, so
+re-running a copied command cannot start the same generation twice. Once an
+automatic spawn has been attempted, a missing handshake or spawn error is
+treated as an uncertain post-crossing anomaly: Brainclaw does not offer a
+manual fallback command for that contracted generation. Contracted manual
+commands are currently emitted only by Brainclaw's native adapter; an opaque
+custom adapter cannot self-declare its command safe.
+
+## Version and rollback behavior
+
+Contract and protocol readers reject a `minimum_reader_version` above the
+version they implement. Contract fields on TurnReservation, Assignment and
+AgentRun are optional only for dual-reading records written before v1. A fully
+legacy reservation continues under its historical evidence rules; new work is
+contracted; partial or unknown future contracts fail closed instead of being
+silently misinterpreted. The projection compatibility rules above make a
+producer rollback non-destructive for already-enriched records.
+
+Reference implementation:
+
+- [`src/core/execution-contract.ts`](../../src/core/execution-contract.ts)
+- [`src/core/loops/turn-execution.ts`](../../src/core/loops/turn-execution.ts)
+- [`src/core/loops/attempt-reservation.ts`](../../src/core/loops/attempt-reservation.ts)
+- [`tests/unit/execution-contract.test.ts`](../../tests/unit/execution-contract.test.ts)
+- [`tests/unit/loops-p0c-conformance.test.ts`](../../tests/unit/loops-p0c-conformance.test.ts)

package/docs/concepts/harness-adapters.md

@@ -0,0 +1,166 @@
+# Harness adapters
+
+Brainclaw's Loop Engine can launch the same contracted turn through different
+agent harnesses without teaching the engine about Codex, Claude, or their CLI
+output formats. `HarnessAdapter` is the boundary between a logical worker
+attempt and one concrete harness. It is shared by the `review`, `ideation`,
+`implementation`, `research`, and `debug` protocols.
+
+This is an execution seam, not another workflow engine. Loop phases, iteration,
+stop conditions, evidence policy, and convergence remain owned by the Loop
+Engine. Process creation, environment, working directory, timeout,
+cancellation, sentinels, and Windows command handling remain owned by
+`ExecutionAdapter`.
+
+## The execution path
+
+```text
+Loop worker phase
+  -> resolve capability + immutable harness binding
+  -> freeze both in the ExecutionContract capability snapshot
+  -> HarnessAdapter.prepare({ contract, prompt, mode })
+  -> structured InvokeCommand
+  -> ExecutionAdapter.start(...)
+  -> raw transport observation
+  -> HarnessAdapter.parseOutcome(...)
+  -> normalized lane result
+  -> server-owned evidence envelope and protocol gates
+```
+
+The adapter receives the prompt separately because `ExecutionContract v1`
+freezes authority and requirements, not the complete prompt body. It returns a
+structured invocation rather than spawning a process itself. On Windows this
+keeps prompts out of argv and out of shell quoting. A direct child receives the
+prompt through stdin. An ack-wrapped child receives the same bytes through a
+private per-run file redirected to stdin; the wrapper removes that file after
+writing the terminal sentinel. This gives native Windows children a reliable
+EOF without embedding the prompt in a second command string.
+
+## Built-in adapters
+
+| Adapter | Selection | Native output | Compatibility |
+|---|---|---|---|
+| `prompt-only@1` | Default | Existing prompt/sentinel contract | Byte-for-byte invocation compatibility with the previous path |
+| `codex-cli@1` | `BRAINCLAW_NATIVE_HARNESS=1` for a Codex profile | JSONL (`--json`) | Falls closed to a partial result when a successful process emits invalid structured output |
+| `claude-cli@1` | `BRAINCLAW_NATIVE_HARNESS=1` for a Claude profile | JSON (`--output-format json`) | Rejects an unattested requested model before the launch fence |
+
+The feature flag is deliberately opt-in. An unknown or unavailable native
+adapter does not silently become another native adapter. Existing generic
+profiles continue through `prompt-only@1`.
+
+## Platform and opt-in E2E matrix
+
+The adapter contract is cross-platform even though the process boundary is
+different. CI runs the default suite on Linux and Windows; on Windows the
+execution adapter owns shell resolution while the harness still supplies a
+structured argv and a separate prompt body.
+
+| Coverage | Linux | Windows |
+|---|---|---|
+| Unit/contract tests for prompt-only, Codex and Claude adapters | Default CI suite on Node 22 and 24 | Default CI suite on Node 24 |
+| Command boundary | Direct executable + argv/stdin | ExecutionAdapter shell resolution; ack-wrapped stdin uses an ephemeral redirected file, never prompt re-quoting |
+| Repository E2E suite | Dedicated Linux job | Covered by the default platform suite; no separate Windows E2E job |
+| Real Codex/Claude account smoke | Explicit local opt-in | Explicit local opt-in |
+
+The real-account smoke tests are skipped by default because they require an
+installed, authenticated CLI and spend provider quota. Run either one after
+`npm run build:test`:
+
+```powershell
+$env:BRAINCLAW_CODEX_HARNESS_E2E = '1'
+$env:BRAINCLAW_CODEX_E2E_MODEL = 'gpt-5.6-sol' # optional
+node --test dist-test/tests/unit/harness-adapters.test.js
+
+$env:BRAINCLAW_CLAUDE_HARNESS_E2E = '1'
+$env:BRAINCLAW_CLAUDE_E2E_MODEL = 'sonnet' # optional
+node --test dist-test/tests/unit/harness-adapters.test.js
+```
+
+Use the equivalent environment-variable syntax on POSIX shells. These flags
+only enable the two native smoke cases; deterministic adapter, parsing,
+capability, restart and evidence-boundary tests always run.
+
+## Requested, resolved, and observed capabilities
+
+Model identity has three distinct stages:
+
+- **requested** — what the caller asked the harness to run;
+- **resolved** — the exact selector passed to the CLI, frozen with the adapter
+  id and version in `CapabilitySnapshot.resolved.harness` before reservation.
+  Because neither installed CLI exposes an authoritative account-specific
+  model catalogue, an explicit selector is marked `unattested`, not falsely
+  labelled `exact`;
+- **observed** — what the harness reports after execution, stored separately on
+  `AgentRun.runtime_capability_observation`.
+
+Requested and resolved values are immutable attempt inputs. Runtime observation
+never rewrites that snapshot. A different observed model creates a monotone
+execution-contract anomaly: later correct-looking output cannot erase it or
+open a convergence gate. A retry therefore needs a new attempt instead of an
+in-place adapter or model substitution.
+
+## Result and evidence boundary
+
+`parseOutcome` converts harness-specific terminal output into a result claim.
+Normalization may map transport failure, invalid JSON, blocked work, or a
+successful result into the common lane-result vocabulary. It may not create an
+`EvidenceEnvelope`, decide that a phase gate passed, or advance a Loop.
+
+Native adapters append a versioned terminal contract to the worker prompt. The
+final assistant message inside the Codex JSONL or Claude JSON envelope must be
+exactly one strict object (no prose inference):
+
+```json
+{
+  "schema_version": 1,
+  "status": "completed",
+  "summary": "No blocking findings",
+  "body": "Optional details",
+  "artifact_type": "verdict",
+  "review_verdict": "approve"
+}
+```
+
+`review_verdict` is mandatory for review-verdict work. A missing, unknown, or
+narratively implied verdict remains partial/failed and cannot close a review
+Loop. Other Loop kinds use the same result-claim envelope with their own
+server-owned expected artifact type.
+
+Those decisions remain server-controlled. The normal order is:
+
+```text
+transport facts -> harness result claim -> lane-result normalization
+                -> reconciliation -> evidence sealing -> gate evaluation
+```
+
+This separation prevents a harness from turning its own prose or exit status
+into proof. The same rule applies to all five Loop kinds; their different
+artifact contracts are interpreted only after normalization.
+
+## Failure and restart rules
+
+- Missing native binaries and models known to be unsupported are rejected
+  before the launch fence. Other explicit model names are passed unchanged,
+  marked `unattested`, and never get a fallback flag; the CLI must either run
+  that selector or fail the attempt.
+- A persisted adapter id/version must match the adapter used to prepare a
+  restart. A feature-flag change cannot silently move an existing attempt to a
+  different harness.
+- Spawn failures and timeouts are transport diagnostics, not protocol
+  verdicts.
+- Native structured-output parse failures are explicit partial/failed results,
+  never successful fallback to unstructured prose.
+- Observed capability mismatch fences convergence and is recorded once on the
+  AgentRun.
+- When a native worker does not write `LANE-RESULT.json`, targeted harvest can
+  normalize its terminal runtime logs into the same untrusted lane-result
+  ingress. Attempt identity is sourced from the reservation and completion
+  signal; reconciliation still seals evidence and evaluates the protocol gate.
+
+## Reference implementation
+
+- [`src/core/harness-adapters/`](../../src/core/harness-adapters/)
+- [`src/core/execution-adapters.ts`](../../src/core/execution-adapters.ts)
+- [`src/core/execution-contract.ts`](../../src/core/execution-contract.ts)
+- [`src/core/loops/turn-execution.ts`](../../src/core/loops/turn-execution.ts)
+- [`tests/unit/harness-adapters.test.ts`](../../tests/unit/harness-adapters.test.ts)

package/docs/concepts/ideation-loop.md

@@ -209,12 +209,13 @@ bclaw_coordinate(intent='ideate', task='Should we extract the dispatcher into a
 - Opens a loop with one `champion` slot = caller.
 - Stores `task` as a `proposal` artifact (sliced to fit the 4 KB
   artifact body cap).
-- Stops at the proposal phase. The champion drives the loop manually
-  via `bclaw_loop(intent='turn'|'advance')`.
+- Stops at the manual `proposal` phase. The champion drives lifecycle with
+  `bclaw_loop(intent='turn'|'advance')`; `critique`, `revision`, and
+  `synthesis` are worker phases, so a trusted caller uses `turn(dispatch=true)`
+  when it wants Brainclaw to launch them.
 - Returns `{loop_id, proposal_artifact_id, mode: 'single_agent',
   dispatched_critics: 0, current_phase: 'proposal'}`.
-- Surfaces a single-agent warning so the caller knows dispatch is
-  manual.
+- Surfaces a single-agent warning so the caller knows dispatch is not automatic.
 
 This is the right mode when you want the loop's structure (memory
 filter, gate, iteration accounting) but want to drive each turn