@enderfga/claw-orchestrator 5.1.0 → 6.0.0

package/skills/references/ultra.md

@@ -20,8 +20,8 @@ Runs in background — poll with `ultraplan_status`.
 ```typescript
 const plan = manager.ultraplanStart('Add OAuth2 support with Google and GitHub providers', {
   cwd: '/path/to/project',
-  model: 'opus',           // default
-  timeout: 1800000,        // 30 min default
+  model: 'opus', // default
+  timeout: 1800000, // 30 min default
 });
 
 console.log(`Plan ID: ${plan.id}`);
@@ -35,18 +35,18 @@ if (status?.status === 'completed') {
 
 ### Tools
 
-| Tool | Description |
-|------|-------------|
-| `ultraplan_start` | Start planning session (background) |
-| `ultraplan_status` | Get status and plan text |
+| Tool               | Description                         |
+| ------------------ | ----------------------------------- |
+| `ultraplan_start`  | Start planning session (background) |
+| `ultraplan_status` | Get status and plan text            |
 
 ### Configuration
 
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `model` | `opus` | Model to use for planning |
-| `cwd` | `process.cwd()` | Project directory to explore |
-| `timeout` | 1,800,000 ms (30 min) | Maximum planning time |
+| Parameter | Default               | Description                  |
+| --------- | --------------------- | ---------------------------- |
+| `model`   | `opus`                | Model to use for planning    |
+| `cwd`     | `process.cwd()`       | Project directory to explore |
+| `timeout` | 1,800,000 ms (30 min) | Maximum planning time        |
 
 Results remain queryable for 30 minutes after completion.
 
@@ -65,36 +65,36 @@ A fleet of specialized bug-hunting agents that review your codebase in parallel,
 
 ### Available Review Angles (20)
 
-| Agent | Focus |
-|-------|-------|
-| SecurityReviewer | Injection, auth flaws, data exposure, OWASP top 10 |
-| LogicReviewer | Off-by-one, race conditions, null handling, edge cases |
+| Agent               | Focus                                                    |
+| ------------------- | -------------------------------------------------------- |
+| SecurityReviewer    | Injection, auth flaws, data exposure, OWASP top 10       |
+| LogicReviewer       | Off-by-one, race conditions, null handling, edge cases   |
 | PerformanceReviewer | O(n^2) loops, memory leaks, missing caching, N+1 queries |
-| APIReviewer | Inconsistent interfaces, missing validation, error gaps |
-| TestReviewer | Untested paths, missing edge case tests, flaky patterns |
-| TypeReviewer | `any` casts, unsafe assertions, missing null checks |
-| ConcurrencyReviewer | Race conditions, deadlocks, async error handling |
-| ErrorReviewer | Swallowed errors, missing try/catch, crash paths |
-| DependencyReviewer | Outdated packages, CVEs, unnecessary deps |
-| ReadabilityReviewer | Unclear naming, complex functions, dead code |
-| DataReviewer | Data validation, schema mismatches, encoding |
-| ConfigReviewer | Hardcoded values, missing env vars, insecure defaults |
-| ScalabilityReviewer | Single points of failure, unbounded growth |
-| DocReviewer | Outdated docs, missing API docs, misleading comments |
-| A11yReviewer | ARIA labels, keyboard nav, color contrast |
-| I18nReviewer | Hardcoded strings, locale handling, RTL support |
-| NetworkReviewer | Missing timeouts, retry logic, connection pooling |
-| AuthReviewer | Token handling, CSRF, permission checks |
-| CryptoReviewer | Weak algorithms, key management, RNG |
-| MemoryReviewer | Memory leaks, circular references, stream handling |
+| APIReviewer         | Inconsistent interfaces, missing validation, error gaps  |
+| TestReviewer        | Untested paths, missing edge case tests, flaky patterns  |
+| TypeReviewer        | `any` casts, unsafe assertions, missing null checks      |
+| ConcurrencyReviewer | Race conditions, deadlocks, async error handling         |
+| ErrorReviewer       | Swallowed errors, missing try/catch, crash paths         |
+| DependencyReviewer  | Outdated packages, CVEs, unnecessary deps                |
+| ReadabilityReviewer | Unclear naming, complex functions, dead code             |
+| DataReviewer        | Data validation, schema mismatches, encoding             |
+| ConfigReviewer      | Hardcoded values, missing env vars, insecure defaults    |
+| ScalabilityReviewer | Single points of failure, unbounded growth               |
+| DocReviewer         | Outdated docs, missing API docs, misleading comments     |
+| A11yReviewer        | ARIA labels, keyboard nav, color contrast                |
+| I18nReviewer        | Hardcoded strings, locale handling, RTL support          |
+| NetworkReviewer     | Missing timeouts, retry logic, connection pooling        |
+| AuthReviewer        | Token handling, CSRF, permission checks                  |
+| CryptoReviewer      | Weak algorithms, key management, RNG                     |
+| MemoryReviewer      | Memory leaks, circular references, stream handling       |
 
 ### Usage
 
 ```typescript
 const review = manager.ultrareviewStart('/path/to/project', {
-  agentCount: 10,            // use 10 of the 20 angles
-  maxDurationMinutes: 15,    // 15 min timeout per agent
-  model: 'sonnet',           // model for all reviewers
+  agentCount: 10, // use 10 of the 20 angles
+  maxDurationMinutes: 15, // 15 min timeout per agent
+  model: 'sonnet', // model for all reviewers
   focus: 'Find security and performance bugs',
 });
 
@@ -109,18 +109,18 @@ if (status?.status === 'completed') {
 
 ### Tools
 
-| Tool | Description |
-|------|-------------|
-| `ultrareview_start` | Launch reviewer fleet (background) |
-| `ultrareview_status` | Get status and findings |
+| Tool                 | Description                        |
+| -------------------- | ---------------------------------- |
+| `ultrareview_start`  | Launch reviewer fleet (background) |
+| `ultrareview_status` | Get status and findings            |
 
 ### Configuration
 
-| Parameter | Default | Range | Description |
-|-----------|---------|-------|-------------|
-| `agentCount` | 5 | 1-20 | Number of reviewer agents |
-| `maxDurationMinutes` | 10 | 5-25 | Per-agent timeout |
-| `model` | session default | — | Model for all reviewers |
-| `focus` | bugs + security + quality | — | Review focus description |
+| Parameter            | Default                   | Range | Description               |
+| -------------------- | ------------------------- | ----- | ------------------------- |
+| `agentCount`         | 5                         | 1-20  | Number of reviewer agents |
+| `maxDurationMinutes` | 10                        | 5-25  | Per-agent timeout         |
+| `model`              | session default           | —     | Model for all reviewers   |
+| `focus`              | bugs + security + quality | —     | Review focus description  |
 
 The council runs with `maxRounds: 2` — one round to find bugs, one to cross-review. Results remain queryable for 30 minutes.

package/skills/references/ultraapp.md

@@ -32,30 +32,58 @@ interview ─► queued ─► building ─► build-complete ─► deploying
                                                                structural)
 ```
 
-| Mode | Meaning |
-|------|---------|
-| `interview` | AppSpec being filled by Q&A. Chat input goes to the interview Opus. |
-| `queued` | Build accepted, waiting for a slot in the FIFO build queue. |
-| `building` | Council writing code, fix-on-failure driving install/build/test. |
-| `build-complete` | Codebase ready, awaiting `deploy` step. |
-| `deploying` | Container/process being started, router map being updated. |
-| `done` | App live at `/forge/<slug>/`. Chat input now goes to the done-mode classifier. |
-| `failed` | Council didn't reach consensus, or fix-on-failure couldn't get the build green. |
+| Mode             | Meaning                                                                         |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `interview`      | AppSpec being filled by Q&A. Chat input goes to the interview Opus.             |
+| `queued`         | Build accepted, waiting for a slot in the FIFO build queue.                     |
+| `building`       | Council writing code, fix-on-failure driving install/build/test.                |
+| `build-complete` | Codebase ready, awaiting `deploy` step.                                         |
+| `deploying`      | Container/process being started, router map being updated.                      |
+| `done`           | App live at `/forge/<slug>/`. Chat input now goes to the done-mode classifier.  |
+| `failed`         | Council didn't reach consensus, or fix-on-failure couldn't get the build green. |
+
+### The build is a workflow run
+
+Everything from `building` onward is a run on the durable kernel — the same one
+`council_start`, `fanout_start` and `autoloop_start` use. The workflow has three
+nodes:
+
+| Node     | Kind              | Does                                                         |
+| -------- | ----------------- | ------------------------------------------------------------ |
+| `synth`  | `ultraapp_synth`  | The 3-agent council; snapshots consensus into `versions/v1/` |
+| `build`  | `verifier`        | The build contract, with its fix-on-red loop and evidence    |
+| `deploy` | `ultraapp_deploy` | Starts the app, registers the route, runs the §7g gate       |
+
+Three consequences worth knowing:
+
+- The run is listed by `workflow_list` and `clawo workflow list`, and shows up in
+  the dashboard's Runs tab, under the id `ultraapp-<run_id>`.
+- **A crash between stages does not redo the stage before it.** A build that died
+  after the council resumes into the build stage rather than paying for the
+  council twice.
+- The mode column above is a **projection** of that run's state, not a second
+  state machine. `interview` and `queued` are the exception — nothing is running
+  yet, so there is no run to project from.
+
+The interview and the done-mode conversation are deliberately not workflows.
+They are user-driven and open-ended, with no predetermined sequence of steps;
+a workflow expressing them would be a router self-loop or a single node with a
+state machine hidden inside it.
 
 ## Architectural conventions (§1–§7)
 
 Every generated app MUST satisfy these. They're embedded in the council
 super-task prompt verbatim from `src/ultraapp/conventions.ts`.
 
-| § | Topic | Headline rule |
-|---|-------|---------------|
-| 1 | Path-based deploy | Mount at `BASE_PATH=/forge/<slug>/`; in-app links MUST be relative. |
-| 2 | Async file-queue runtime | Exact endpoints: `GET /`, `POST /run`, `GET /status/:jobId`, `GET /result/:jobId`, `GET /health`. File-based job queue under `$DATA_DIR/jobs/<jobId>/`. NO database. Data path from `process.env.DATA_DIR ?? '/data'`. |
-| 3 | BYOK | If `runtime.needsLLM`, API keys live in browser localStorage and are sent direct to the provider. The server MUST NEVER receive the key (enforced by `eslint-plugin-no-server-keys`). |
-| 4 | Dockerfile + smoke test | Single multi-stage Dockerfile, `npm run smoke` drives one full job in < 90s using `examples[0].ref`. |
-| 5 | Council voting protocol | 3 agents in git worktrees, all-YES vote required, max 8 rounds. |
-| 6 | Tech stack | Modern TypeScript / JavaScript framework (Next.js, Vite + Hono, SvelteKit). NO Python, NO pure SSGs. |
-| 7 | **Frontend quality** | **Real styling system + real type hierarchy + four-state coverage on every async surface + drag-and-drop forms + appropriate result presentation + one deliberate theme.** §7g requires every agent to capture Chrome-headless screenshots at 1440×900 AND 375×812 and visually inspect the PNGs before voting YES — source-code review is explicitly insufficient evidence. |
+| §   | Topic                    | Headline rule                                                                                                                                                                                                                                                                                                                                                                |
+| --- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Path-based deploy        | Mount at `BASE_PATH=/forge/<slug>/`; in-app links MUST be relative.                                                                                                                                                                                                                                                                                                          |
+| 2   | Async file-queue runtime | Exact endpoints: `GET /`, `POST /run`, `GET /status/:jobId`, `GET /result/:jobId`, `GET /health`. File-based job queue under `$DATA_DIR/jobs/<jobId>/`. NO database. Data path from `process.env.DATA_DIR ?? '/data'`.                                                                                                                                                       |
+| 3   | BYOK                     | If `runtime.needsLLM`, API keys live in browser localStorage and are sent direct to the provider. The server MUST NEVER receive the key (enforced by `eslint-plugin-no-server-keys`).                                                                                                                                                                                        |
+| 4   | Dockerfile + smoke test  | Single multi-stage Dockerfile, `npm run smoke` drives one full job in < 90s using `examples[0].ref`.                                                                                                                                                                                                                                                                         |
+| 5   | Council voting protocol  | 3 agents in git worktrees, all-YES vote required, max 8 rounds.                                                                                                                                                                                                                                                                                                              |
+| 6   | Tech stack               | Modern TypeScript / JavaScript framework (Next.js, Vite + Hono, SvelteKit). NO Python, NO pure SSGs.                                                                                                                                                                                                                                                                         |
+| 7   | **Frontend quality**     | **Real styling system + real type hierarchy + four-state coverage on every async surface + drag-and-drop forms + appropriate result presentation + one deliberate theme.** §7g requires every agent to capture Chrome-headless screenshots at 1440×900 AND 375×812 and visually inspect the PNGs before voting YES — source-code review is explicitly insufficient evidence. |
 
 ## Runtime modes
 
@@ -64,10 +92,10 @@ clawo serve --ultraapp-runtime host    # default
 clawo serve --ultraapp-runtime docker  # opt-in
 ```
 
-| Mode | Build | Run | Pros | Cons |
-|------|-------|-----|------|------|
-| `host` | `npm install && npm run build` | `npm start` (detached, `setsid`-equivalent) | Zero extra deps; works anywhere Node works; faster start. | No process isolation; deps installed under the user. |
-| `docker` | `docker build .` | `docker run -d --restart unless-stopped` | Per-app isolation, restart policy, image is the artefact. | Requires a running Docker daemon. |
+| Mode     | Build                          | Run                                         | Pros                                                      | Cons                                                 |
+| -------- | ------------------------------ | ------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------- |
+| `host`   | `npm install && npm run build` | `npm start` (detached, `setsid`-equivalent) | Zero extra deps; works anywhere Node works; faster start. | No process isolation; deps installed under the user. |
+| `docker` | `docker build .`               | `docker run -d --restart unless-stopped`    | Per-app isolation, restart policy, image is the artefact. | Requires a running Docker daemon.                    |
 
 Both modes allocate a backend port in `[19100, 19999]`. The reverse-
 proxy router runs at port `19000` (auto-fallback up to `19099` if
@@ -100,23 +128,23 @@ persists to `~/.claw-orchestrator/host-procs.json`.
 All routes are served by the embedded server (default `:18796`), under
 `Authorization: Bearer <token>` from `~/.openclaw/server-token`.
 
-| Method + path | Purpose |
-|----|----|
-| `GET /ultraapp/list` | All runs with mode + createdAt. |
-| `POST /ultraapp/new` | Body: `{ firstMessage?: string }`. Returns `{ runId }`. |
-| `GET /ultraapp/<id>` | Full snapshot: spec + chat + state. |
-| `POST /ultraapp/<id>/answer` | Body: `{ value, freeform? }`. Submit interview answer. |
-| `POST /ultraapp/<id>/spec-edit` | Body: RFC 6902 patch ops. Edit the spec mid-interview. |
-| `POST /ultraapp/<id>/files` | Multipart upload to `examples/`. |
-| `GET /ultraapp/<id>/events` | SSE stream of build/chat events (mode pill, narrator, council activity). |
-| `POST /ultraapp/<id>/build` | Validate spec strictly + enqueue. |
-| `POST /ultraapp/<id>/build/cancel` | Abort the active build. |
-| `GET /ultraapp/<id>/artifacts` | List `versions/vN/`. |
-| `POST /ultraapp/<id>/start` | Start the deployed container/process for the active version. |
-| `POST /ultraapp/<id>/stop` | Stop without deleting. |
-| `POST /ultraapp/<id>/delete` | Stop + remove all per-run state. |
-| `POST /ultraapp/<id>/feedback` | Body: `{ text }`. Done-mode classifier routes cosmetic / spec-delta / structural. |
-| `POST /ultraapp/<id>/promote-version` | Body: `{ version: "vN" }`. Atomically swap deployed version. |
+| Method + path                         | Purpose                                                                           |
+| ------------------------------------- | --------------------------------------------------------------------------------- |
+| `GET /ultraapp/list`                  | All runs with mode + createdAt.                                                   |
+| `POST /ultraapp/new`                  | Body: `{ firstMessage?: string }`. Returns `{ runId }`.                           |
+| `GET /ultraapp/<id>`                  | Full snapshot: spec + chat + state.                                               |
+| `POST /ultraapp/<id>/answer`          | Body: `{ value, freeform? }`. Submit interview answer.                            |
+| `POST /ultraapp/<id>/spec-edit`       | Body: RFC 6902 patch ops. Edit the spec mid-interview.                            |
+| `POST /ultraapp/<id>/files`           | Multipart upload to `examples/`.                                                  |
+| `GET /ultraapp/<id>/events`           | SSE stream of build/chat events (mode pill, narrator, council activity).          |
+| `POST /ultraapp/<id>/build`           | Validate spec strictly + enqueue.                                                 |
+| `POST /ultraapp/<id>/build/cancel`    | Abort the active build.                                                           |
+| `GET /ultraapp/<id>/artifacts`        | List `versions/vN/`.                                                              |
+| `POST /ultraapp/<id>/start`           | Start the deployed container/process for the active version.                      |
+| `POST /ultraapp/<id>/stop`            | Stop without deleting.                                                            |
+| `POST /ultraapp/<id>/delete`          | Stop + remove all per-run state.                                                  |
+| `POST /ultraapp/<id>/feedback`        | Body: `{ text }`. Done-mode classifier routes cosmetic / spec-delta / structural. |
+| `POST /ultraapp/<id>/promote-version` | Body: `{ version: "vN" }`. Atomically swap deployed version.                      |
 
 ## MCP tools (14)
 
@@ -137,11 +165,11 @@ ultraapp_start_container ultraapp_stop_container ultraapp_delete
 After the run reaches `done`, chat input goes to a per-run Haiku
 classifier. Three classes:
 
-| Class | Routes to | Behaviour |
-|-------|-----------|-----------|
-| `cosmetic` | Patcher | Opus generates a unified diff against the deployed worktree → `applyUnifiedDiff` → validate via fix-on-failure → on success snapshot to `versions/vN+1/`, on any failure restore the snapshot atomically and post the reason to chat. |
-| `spec-delta` | Focused interview | Flips mode back to `interview` with a bootstrap message that names the field(s) being changed. Completion auto-triggers a fresh `startBuild`. |
-| `structural` | Suggestion only | Posts a narrator note: "this sounds like a different app — click + New". |
+| Class        | Routes to         | Behaviour                                                                                                                                                                                                                             |
+| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cosmetic`   | Patcher           | Opus generates a unified diff against the deployed worktree → `applyUnifiedDiff` → validate via fix-on-failure → on success snapshot to `versions/vN+1/`, on any failure restore the snapshot atomically and post the reason to chat. |
+| `spec-delta` | Focused interview | Flips mode back to `interview` with a bootstrap message that names the field(s) being changed. Completion auto-triggers a fresh `startBuild`.                                                                                         |
+| `structural` | Suggestion only   | Posts a narrator note: "this sounds like a different app — click + New".                                                                                                                                                              |
 
 To swap which version is live, use `promote-version` (HTTP) or
 `ultraapp_promote_version` (MCP) — the router map and host-procs map
@@ -190,14 +218,62 @@ open "http://127.0.0.1:18796/dashboard?token=$(cat ~/.openclaw/server-token)"
 curl http://127.0.0.1:19000/forge/<slug>/health
 ```
 
-## Known limitations (v4.0.0)
+## Acceptance contract (6.0.0)
+
+UltraApp is the one mode whose contract is on by default, because it already ran
+most of these commands and because two of its documented gates were not actually
+enforced.
+
+**Build stage**, in the council's worktree:
+
+```
+npm install → npm run build → npm test → [docker build] → npm run smoke
+```
+
+`npm run smoke` is new here. §4 of the architectural conventions has always told
+the council that the smoke test gates build success — it was never in the step
+list, so the claim was false. A codebase without a working `scripts.smoke` now
+fails its build, which is what the brief said all along.
+
+**Deploy stage**, against the live URL: both §7g viewports (1440×900 and
+375×812) are captured by the orchestrator with headless Chrome and stored as run
+evidence.
+
+Evidence lands under the run directory:
+
+```
+~/.claw-orchestrator/ultraapps/<runId>/evidence/
+  build-01/    bundle.json, checks/*.log, diff.patch
+  deploy-01/   bundle.json, shot-desktop.png, shot-mobile.png
+```
+
+### What the visual gate does and does not do
+
+It captures images and stores them, so "did anyone actually look" is now a file
+on disk instead of an agent's claim. It does **not** compare pixels — judging
+the rendering is still a reader's job, and the §7g instructions in the council
+prompt remain the agents' responsibility.
+
+It is **advisory by default**, so a host without Chrome does not lose a working
+app to a missing browser. Set `CLAWO_ULTRAAPP_VISUAL_GATE=strict` to make a
+failed capture block the deploy. Chrome is resolved from `CLAWO_CHROME_BIN`, then
+the usual macOS app paths, then `PATH`.
+
+## Durable build queue (6.0.0)
+
+The build queue is persisted to `<store>/build-queue.json` and restored on
+startup. Its own comment used to say a restart mid-build meant "the build is
+marked failed and the user can rerun"; in practice nothing was marked — the
+pending list vanished along with any queued build the user was waiting on, with
+no record it had been asked for.
+
+A build that was in flight when the process died is **re-queued, not resumed**,
+and goes to the front: each build starts from a fresh council worktree, so
+re-running is safe and continuing a half-built tree is not.
+
+## Known limitations
 
 - The done-mode patcher loop occasionally hangs between
   feedback-classification and the patcher Opus session creation;
   cosmetic changes can be applied manually until the underlying race
   is fixed.
-- The §7g frontend gate currently relies on per-agent honesty about
-  running the screenshot capture; agents that skip the inspection can
-  still pass the smoke gate. A follow-up will plumb a server-side
-  screenshot validator into the council verifier so the gate becomes
-  structurally enforced rather than persona-enforced.

package/skills/references/verification.md

@@ -0,0 +1,187 @@
+# Verification — acceptance contracts and evidence
+
+Before 6.0.0, nothing in this runtime ever checked an agent's work. Every
+"finished" signal was the agent grading itself:
+
+- **Council** terminated when a regex found `[CONSENSUS: YES]` in agent prose.
+- **Autoloop**'s `eval_output` was whatever the Coder passed to a tool call, and
+  the Reviewer that was supposed to catch fabrication had a sandbox containing
+  the iteration's artifacts and no code, so it could not re-derive anything.
+- **UltraApp**'s frontend gate was a sentence in a persona string telling agents
+  to capture screenshots. There was no screenshot code anywhere in the project.
+- The run ledger's `ok` was the engine's report on its own turn.
+
+An **acceptance contract** is the opposite of all of that: a list of checks the
+runtime executes and whose results it reads. A run that declares one cannot reach
+`completed` unless every required check passes.
+
+## The one rule about where contracts come from
+
+**A contract comes from the caller or from a mode default. Never from agent
+output.** If an agent could declare its own checks, we would be back to
+self-grading with more steps. Nothing in the kernel reads a contract out of a
+node's result, and `normalizeContract()` drops anything it does not recognise, so
+a contract that arrived through a tool call carries no fields the executor did
+not model.
+
+Concretely: there is no shell string anywhere. A `command` check is argv.
+
+## Check types
+
+| Type          | What it does                                                                | Passes when                                                               |
+| ------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `command`     | Runs argv in a directory                                                    | Exit code equals `expectExit` (default 0)                                 |
+| `http`        | Polls a URL until the deadline                                              | Status equals `expectStatus` (default 200)                                |
+| `screenshot`  | Captures the page at each viewport with headless Chrome and stores the PNGs | Every viewport produced a non-empty image                                 |
+| `diff_policy` | Compares the change set against the recorded baseline                       | File count, forbidden paths, and required paths all satisfied             |
+| `file`        | Checks a path                                                               | Exists (or is absent when `exists: false`) and matches `matches` if given |
+
+```jsonc
+{
+  "id": "ship-it",
+  "fixOnFailureRounds": 2,
+  "checks": [
+    { "type": "command", "cmd": "npm", "args": ["run", "build"], "timeoutMs": 600000 },
+    { "type": "command", "cmd": "npm", "args": ["test"] },
+    { "type": "command", "cmd": "npm", "args": ["run", "lint"], "required": false },
+    { "type": "diff_policy", "forbidPaths": ["configs", ".github"], "maxFiles": 40 },
+  ],
+}
+```
+
+### `required`
+
+Default true. A failing non-required check is recorded in the evidence bundle but
+does not refute the run — use it for signals you want visible without making them
+blocking.
+
+(The predecessor of this module, `ultraapp/fix-on-failure.ts`, declared a
+`required` field on its steps and never read it: every step was fatal. It is
+honoured now.)
+
+### Timeouts
+
+Every check has one, and the default is 10 minutes. This is not cosmetic — the
+old pipeline had no timeout at all, so a wedged `npm test` hung the build
+forever. A check that overruns is killed (its whole process group, with SIGKILL)
+and recorded as failed with `timedOut: true`.
+
+### What `screenshot` does and does not claim
+
+It captures images and stores them. It does **not** compare pixels, and it is not
+visual regression testing. What changed in 6.0.0 is that the capture is performed
+by the runtime rather than requested of an agent — so "did anyone actually look"
+stops being a claim and starts being a file on disk. Judging the rendering is
+still a human's or an agent's job.
+
+Chrome is resolved from `CLAWO_CHROME_BIN`, then the usual macOS app paths, then
+`PATH`. A host with no browser fails the check immediately rather than paying the
+timeout to find out.
+
+### `diff_policy` and the baseline
+
+`diff_policy` needs to know what the run changed, which needs a baseline. The
+kernel records `git rev-parse HEAD` when a run starts and diffs against that.
+
+The change set is **tracked changes ∪ untracked files**. That union matters: a
+bare `git diff` lists tracked modifications only, so files an agent _created_ are
+invisible to it — which is exactly how `autoloop`'s per-iteration `diff.patch`
+used to miss every new file while `git add -A` committed them anyway.
+
+`requirePaths: ["."]` means "the run must have changed something".
+
+## Evidence bundles
+
+Every verifier attempt writes a directory under the run:
+
+```
+~/.claw-orchestrator/wf/<runId>/evidence/<evidenceId>/
+  bundle.json        verdict, per-check results, changed files, base/head SHA
+  checks/<id>.log    output tail for each failed check
+  diff.patch         the patch the run produced, new files included
+  shot-*.png         screenshots, when a screenshot check ran
+```
+
+Read one with `clawo verify <runId>`, `GET /workflow/<id>/evidence`, or
+`workflow_status` (which returns the id).
+
+Bundle writes are best-effort. The verdict is already decided by the check
+results, so a bundle that fails to land loses the record, never the answer.
+
+## Fix-on-red
+
+`fixOnFailureRounds` spawns a repair session against the failing check and then
+**re-runs the whole check list**. The fixer's own claim to have fixed it is
+ignored; only the re-run decides. Set it to 0 (the default) to disable.
+
+## Per-mode defaults
+
+| Mode                     | Contract          | Notes                                                                                                                                                       |
+| ------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **UltraApp**             | **On by default** | Build: `npm install` → `npm run build` → `npm test` → (`docker build`) → **`npm run smoke`**. Deploy: **both §7g viewports captured** against the live URL. |
+| **Council**              | Caller-declared   | Consensus votes are recorded on the run as advisory and no longer decide completion.                                                                        |
+| **Autoloop**             | Caller-declared   | With a contract, a Reviewer `advance` is held unless the checks pass; passing also fires `on_target_hit`.                                                   |
+| **Fanout / Ultrareview** | Caller-declared   | Per-agent `ok` now reads the engine's terminal verdict rather than "the call did not throw".                                                                |
+| **Plain sessions**       | None              | Use `verify_run` to check work after the fact.                                                                                                              |
+
+Two of UltraApp's defaults close claims the project had been making without
+backing them:
+
+- `conventions.ts` §4 told every council that `npm run smoke` gated build
+  success. It was not in the step list at all. It is now.
+- `ultraapp.md` recorded, as a known limitation since 4.0.0, that the §7g gate
+  "relies on per-agent honesty about running the screenshot capture", with a
+  server-side validator promised as a follow-up. That follow-up is this release.
+
+The visual gate is **advisory by default** so that a host without Chrome does not
+lose a working app to a missing browser. Set
+`CLAWO_ULTRAAPP_VISUAL_GATE=strict` to make a failed capture block the deploy.
+
+## Verifying work that did not come through a workflow
+
+```bash
+# Tool
+verify_run({ cwd: "/repo", contract: { checks: [{ type: "command", cmd: "npm", args: ["test"] }] } })
+```
+
+Use it for a plain `session_send` that edited a repo, or for anything from an
+older version. The contract is yours; nothing is read from agent output.
+
+## Three outcomes, not two
+
+A run ends `verified`, `refuted`, or `unverified`.
+
+`unverified` means **no contract was declared and nothing checked the work**. It
+is not a failure and it is not a pass. The CLI prints it as `—` and the summary
+line says so in words, because collapsing it into either bucket would let an
+unchecked run read as a checked one.
+
+## Related
+
+- [`workflow.md`](./workflow.md) — the kernel that runs verifiers as nodes
+- [`observability.md`](./observability.md) — how verdicts reach the run ledger
+- [`ultraapp.md`](./ultraapp.md) — the default contract in context
+
+## What the guarantee is, precisely
+
+- The checks are run by the runtime, and their exit codes are read by the
+  runtime. No part of the verdict is an agent's report about itself.
+- A run carrying a contract cannot reach `completed` unless every required check
+  passed.
+- If anything that can touch the workspace runs after the checks and the tree's
+  **content** changes, the verdict expires: the outcome drops to `unverified`
+  with the reason recorded. Not `refuted` — no check failed.
+- Outside a git repository the digest is unavailable. Nothing running after the
+  checks means the verdict stands; something running after it means we decline
+  to vouch, and the run says so.
+
+- If an abandoned attempt (a node past its timeout, which cannot be killed) is
+  still running when the run ends, the outcome is `unverified` with the reason
+  recorded. The runtime will not vouch for a tree something may still be writing
+  to.
+
+What it is **not**: a promise that nothing can touch the tree after a run ends.
+A node past its timeout keeps running, and if it outlives the short settle
+window its writes land after the last digest — the run will have said
+`unverified`, but the file is still changed. Give such nodes a timeout they will
+not hit, or make their writes safe to arrive late.