muse-crew 0.4.3 → 0.4.5

package/AGENTS.md

@@ -11,9 +11,11 @@ Muse Crew source repository. The repo is the product; the personal instance (`$C
 - `personas/` — QA perspective costumes for Hazel
 - `seed/` — init source data: everything `crew-init.js` reads when setting up a new crew instance
 - `workflows/` — executable Muse workflow scripts (JavaScript)
+- `tests/` — regression tests for the deterministic contracts (`bash tests/run.sh`)
 
 ## Rules
 
 - Git source is authoritative.
 - Never expose this repo publicly.
 - Ship implementation and documentation together.
+- After editing `workflows/*.js`, run `bash tests/run.sh` — `node --check` does NOT catch syntax errors inside function bodies (V8 lazy preparsing), so it cannot validate workflow edits alone.

package/API.md

@@ -16,11 +16,14 @@ Create a new task on the board.
 |-------|------|----------|-------|
 | `title` | string (1–160 chars) | yes | |
 | `description` | string (≤ 5000) | no | Defaults to `""` |
-| `project` | slug | no | Implicit project resolution: an explicit `project` wins; otherwise the service resolves `config.default_project` (set by `setdefaultproject`, `crew-init`, or automatically for the first registered project); as a last resort it falls back to the legacy `"orchestra-dashboard"` project id. Agents filing tasks normally omit `project` and inherit the dashboard's default. |
+| `project` | slug | no | Implicit project resolution: an explicit `project` wins; otherwise the service uses the `"orchestra-dashboard"` project id and throws `"Project not found."` if it isn't registered. There is no default-project fallback — pass `project` explicitly. |
 | `workflow` | slug or null | no | Routing label (e.g. `standard`, `bugfix`, `chore`, `docs`) |
 | `priority` | `high` · `normal` · `low` | no | Defaults to `normal` |
 | `state` | `todo` · `in_progress` · `parked` · `done` | no | Defaults to `todo` |
 | `deps` | string[] | no | Task IDs this task depends on |
+| `filed_by` | string (1–80 chars) | yes | Who filed the task — plain text, by convention `human`, `hazel`, or `dispatcher`. It is a label, not a reference: it doesn't point at an identity, so it survives even if the filer is long gone. |
+
+The task record echoes the field back as `filed_by`, which may be `null`: tasks filed before the field existed have none, and no backfill was run — so treat a `null` as silence, not as a statement. (The `created` event's `identity` is a different concept — that's the phase performer, not the filer.)
 
 ### `updatetask`
 
@@ -31,7 +34,7 @@ Update an existing task's fields. Only `id` is required; all other fields are op
 | `id` | uuid | yes | |
 | `title` | string (1–200) | no | |
 | `description` | string (≤ 3000) | no | |
-| `state` | `todo` · `in_progress` · `parked` · `done` | no | |
+| `state` | `todo` · `in_progress` · `parked` · `done` | no | Only the `parked` → `todo` transition stamps `retry_reset_at` to the current server time (UTC, ISO 8601), mechanically restarting the consecutive-failure streak — a re-queued task never inherits its old failures. No other transition stamps it (`parked` → `done`, `todo` → `todo`, and patches without a `state` field do not). |
 | `priority` | `high` · `normal` · `low` | no | |
 | `project` | slug | no | **Project-move guard:** changing this to a different project throws while the task has an active run (an agent session with status `running` that started within the last hour), because the live run keeps the old project's repo context and moving it mid-phase would work on the wrong repo. Wait for the run to finish, or recover/park the task first, then move it. |
 | `workflow` | slug or null | no | |
@@ -66,6 +69,17 @@ Send a stuck or failed task to a specific workflow phase for recovery.
 | `target_phase` | string (1–120) | yes | The phase to send the task to |
 | `updated_description` | string (≤ 5000) | no | Optional revised description |
 
+### `parktask`
+
+Atomically park a task for human attention: sets `state` to `parked`, writes the explanatory `note` event, and settles every `running` session for the task — in one transaction. Either all land or none do: callers never see a note without a park, a park without a note, or a parked task with a ghost `running` session left behind (a terminal task transition settles its sessions). Settled sessions move to `failed` — the status `recovertask` accepts, so recovery works immediately after a park — with `ended_at` stamped and `Parked: <message>` appended to their notes; `failure_reason` stays null.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `task_id` | uuid | yes | |
+| `message` | string (1–1000) | yes | Why the task needs a human; written to the activity feed as a `note` |
+
+Returns `{ "ok": true, "task": {...}, "settled_sessions": <n> }` with the updated task record and the count of sessions settled (`0` when none were running).
+
 ---
 
 ## Sessions
@@ -120,6 +134,32 @@ Read the event timeline.
 
 Read the full board state for dispatch decisions. Takes no arguments. Returns all projects with their tasks, simultaneity limits, quiesce state, and active sessions — everything the dispatcher needs to decide what to claim.
 
+Each task in `ready_tasks` carries an explicit retry object:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `retry.consecutive_failures` | integer ≥ 0 | Counted by the procedure below. Computed deterministically server-side — the dispatcher consumes it directly, never projecting history or parsing event messages. |
+| `retry.rejections_since_reset` | integer ≥ 0 | Count of `rejected` sessions with `started_at` after the task's `retry_reset_at` watermark (all rejections if the watermark is null), regardless of step. Unlike the failure streak, this is not trailing-per-step: a Review → Build → Review cycle accumulates, because the rework budget bounds rejections of the work, not of a step. Reset by the same `parked` → `todo` stamp. |
+
+**Counting procedure** (normative — two conforming dashboards must produce the same number from the same history):
+
+1. Order the task's sessions by `started_at` descending, newest first. Let S be the newest session; if there are no sessions, the count is 0.
+2. Walk newest → oldest, counting each session, and **stop** at the first session where any of these holds:
+   - its `started_at` is at or before the task's `retry_reset_at` watermark (a session that started before the reset but ended after it is excluded — the comparison is on start time);
+   - its `step` differs from S's `step` (a step change *breaks* the walk; it is not skipped — so a rejection at a new step resets the operational streak for that step);
+   - its `status` is anything other than `failed` or `timed_out`.
+3. The count is the number of sessions counted before stopping.
+
+Retry semantics: the dispatcher retries a failed phase while `retry.consecutive_failures` is below its configured cap (default 3 consecutive failures; `maxConsecutiveFailures <= 0` disables the cap). At the cap it parks the task for human attention. Separately, the dispatcher parks a task whose `retry.rejections_since_reset` reaches the rejection budget (default 2; `maxConsecutiveRejections <= 0` disables it) instead of redispatching it to Build/Write for another rework round — this bounds Review/QA rejection cycling across dispatcher ticks, which the workflow's in-run rework budget cannot see. Moving a task from `parked` back to `todo` stamps `retry_reset_at`, mechanically restarting both counters — a re-queued task never inherits its old failures or rejections. Sessions and events are kept; the watermark only excludes pre-reset sessions from the counts. `retry_reset_at` is also exposed on the task as `retry_reset_at` (nullable) for observability.
+
+A dashboard that omits `retry` or returns an invalid `consecutive_failures` (not a non-negative number) behaves as cap-disabled: the dispatcher retries the phase and logs a warning. The cap requires a dashboard implementing this field — against an older or non-conforming dashboard the cap is silently inert.
+
+Task `state` vocabulary: `todo` = ready for dispatch; `in_progress` = a workflow run is active or awaiting its next phase; `parked` = human hold, the dispatcher skips it; `done` = all phases finished. `blocked` is never a stored task state — it is derived mechanically from unmet dependencies (surfaced as a `blocked` flag on the task) and never authored by hand.
+
+Session `status` vocabulary: `failed` = a phase was attempted but did not finish (retryable); `rejected` = an explicit phase verdict (Review/QA said no), routed through rework. Workflows never record `blocked` for operational failures — that word is reserved for the dependency signal.
+
+Two namespaces, not one: the vocabulary above is the **dashboard API** (task states, session statuses, event types). Workflow scripts additionally return a **workflow result envelope** to their launcher (`{status: "ok" | "failed" | "parked", ...}`) and may return `{__hatchWorkflowControl: "blocked"}` as a runtime halt signal. The `"blocked"` inside `__hatchWorkflowControl` is a workflow-runtime mechanism, unrelated to the dashboard's dependency-derived `blocked` — same word, different namespace. `parked` as a workflow return means the workflow parked the task via `parktask` and the launcher should treat the run as complete.
+
 ### `acknowledge_poll`
 
 Record that a poll tick occurred. Takes no arguments. Used by the dispatcher at the end of each cycle to update the last-polled timestamp.
@@ -143,31 +183,19 @@ Register a new project.
 | `simultaneity` | integer (1–100) | no | Max concurrent tasks; defaults to 2 |
 | `quiesced` | boolean | no | Start paused; defaults to false |
 
-The first registered project automatically becomes the `default_project` (see State) when no default is set yet.
-
 ### `updateproject`
 
 Update project fields. Only `id` is required; all others are optional patch fields. Same fields as `createproject`, except `simultaneity` minimum is 0 (for kill switch state).
 
 **Context-change guard:** changing `repo_path`, `deploy_type`, or `deploy_slug` is blocked while any task in the project has an active run (an agent session with status `running` that started within the last hour): the call throws, because live runs keep the old project config and the change would split the project context mid-run. Wait for the runs to finish, or recover/park those tasks first, then retry.
 
-### `setdefaultproject`
-
-Set the dashboard's default project — the project the CLI and agents use implicitly when no explicit project is given. The dispatcher resolves a task's project as its explicit label first, then this default, then the first registered project as a last resort.
-
-| Field | Type | Required | Notes |
-|-------|------|----------|-------|
-| `project_id` | slug | yes | Must be a registered project id, else the call throws `"Project not found."` |
-
-Returns `{ "ok": true, "project_id": "<slug>" }`. Idempotent: sets the `default_project` config key via upsert.
-
 ### `deleteproject`
 
 Remove a project registration.
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
-| `id` | slug | yes | If this project was the `default_project`, the default pointer is cleared so it never aims at a missing project. |
+| `id` | slug | yes | Removes the project record along with its tasks, sessions, events, and any stored kill-switch simultaneity. |
 
 ### `listprojects`
 
@@ -215,13 +243,9 @@ Read the full dashboard state: tasks, sessions, events, and projects. Used by wo
 
 Read global configuration. Takes no arguments.
 
-**Known keys:**
+**Known keys:** none are defined by the API itself — the contract stores no global config. Dashboards may expose `updateconfig` for their own settings, but agents and workflows should not rely on any key existing.
 
-| Key | Value | Set by |
-|-----|-------|--------|
-| `default_project` | project slug | `setdefaultproject` (explicit upsert), `createproject` (first project only), `crew-init` (the dashboard's own project) |
-
-`default_project` is the dashboard's configured default project: agents and the CLI inherit it when no explicit project is given. Deleting the project it points at clears it. No migration is needed — the key simply appears once set, and the dispatcher reads it from `getdispatchstate`'s `config` object.
+Crew convention (not API surface): the dispatcher reads and writes per-project `playtest.<project>.journeys`, `playtest.<project>.journey_cursor`, `playtest.<project>.persona_cursor`, and `playtest.<project>.max_filings` through these two actions — see "Idle playtesting" in the [guide](docs/guide.md). It also reads two **global** (whole-crew, not per-project) keys: `maxConsecutiveFailures` (integer-as-string, default `"3"`, `<=0` disables the retry cap — see "Failure handling and retry" in the guide) and `maxConsecutiveRejections` (integer-as-string, default `"2"`, `<=0` disables the rejection budget). Values are parsed with `parseInt`; an unparseable value silently falls back to the default.
 
 ### `updateconfig`
 
@@ -249,6 +273,29 @@ Read the last publication provenance. Returns `{ "provenance": { "source_commit"
 
 ---
 
+## Workflow contracts
+
+These are not dashboard actions — they are contracts the workflow runtime enforces on every run. They are documented here because the API is the contract everywhere: a conforming crew release must honor them.
+
+### Work-report transport
+
+The runtime transports `agent()` output as JSON. Work agents return their report as free text wrapped in a minimal schema: `{ "report": "<free-text work report>" }`. The schema is a transport envelope, not a demand for machine-structured reasoning — the report itself stays prose. The workflow extracts the `report` field and works with the text from there.
+
+### Deterministic verdict extraction
+
+Phases whose outcome drives control flow (Build, Review, QA, Reproduce, Integrate, Publish) declare their verdict explicitly: the worker ends its report with exactly one line, `VERDICT: PASS` or `VERDICT: FAIL`. The verdict is extracted mechanically by workflow code — never by an agent, and never by a formatter agent. Extraction fails closed: a missing, malformed, or contradictory verdict line fails the phase; an ambiguous verdict never passes.
+
+### Artifact publish verification
+
+Artifact Publish passes only when both are true:
+
+1. The worker declares success.
+2. Mechanical verification confirms the artifact's provenance matches the integrated Git commit: the workflow reads `getprovenance` and compares `provenance.source_commit` against `git rev-parse HEAD` of the project repo.
+
+Verification fails closed. If the provenance is missing, unreadable, or points at a different commit than the integrated HEAD, the workflow parks the task — it does not trust the worker's prose. Narrative remains useful but cannot independently establish deployment truth.
+
+---
+
 ## Not part of this API
 
 The following are dashboard-specific view operations, not part of the Crew API contract:

package/README.md

@@ -40,13 +40,29 @@ docs:      Triage → Write → Review
 
 ## Quick Start
 
-Install the package:
+There is no setup wizard. The instructions below are for the Muse agent doing this job, not a human at a terminal.
+
+First, you'll need a task service that implements the [Crew API](API.md) — something to hold tasks, track sessions, and serve the board. The [Orchestra Dashboard](https://github.com/emojimanegg1/orchestra-dashboard) is the reference implementation. Create that artifact first and note its slug; init needs it.
+
+Then install the package:
 
 ```
 npm install muse-crew
 ```
 
-You'll need a task service that implements the [Crew API](API.md) — something to hold tasks, track sessions, and serve the board. The [Orchestra Dashboard](https://github.com/emojimanegg1/orchestra-dashboard) is the reference implementation. Set that up first, then run `crew-init` with its slug.
+That puts the code in `node_modules/muse-crew`. Now launch the init script — note that it's not a command you type. There is no `crew-init` binary; the package has no `bin` field, so there's nothing to run at the shell. Instead, start it as a workflow through the agent's workflow tools:
+
+```
+workflow_launch with:
+  scriptPath: "<install-path>/workflows/crew-init.js"
+  args: {
+    crewRepoPath: "<install-path>",
+    crewHome: "~/workspace/.jarvis",
+    dashboardSlug: "orchestra-dashboard"
+  }
+```
+
+For the full reference — optional arguments, what init creates, and how to verify it worked — see [**Setup from scratch**](docs/guide.md#setup-from-scratch) in the Guide.
 
 The dashboard becomes the crew's first project — the crew works on itself.
 

package/docs/guide.md

@@ -137,6 +137,10 @@ The project does **not** need:
 - Any special file structure — the crew works with whatever the repo contains.
 - Workflow files — those live in the crew home's release, not in the project.
 
+### Worktrees
+
+Each task builds in an isolated git worktree at `<repo>/.worktrees/<task_id>`, on a branch named `task/<task_id>`. The lifecycle manager (`lib/worktree-lifecycle.sh`) owns creation and removal — workflows and agents never run raw `git worktree` commands. The crew's own task→worktree registry (`<repo>/.worktrees/.registry/`) is the source of truth for task→branch/path; `prepare` fails closed when `main` is dirty, and `cleanup` is forgiving so a failed run never strands a worktree.
+
 ## Filing a task
 
 Create a task using the `createtask` action (see the [API reference](../API.md)):
@@ -160,7 +164,7 @@ Required: `title`. Everything else has defaults.
 - `priority` — `"high"`, `"normal"`, or `"low"`.
 - `deps` — array of task IDs that must complete first (blocked until all deps are done).
 
-A task in `todo` state becomes eligible for dispatch on the next polling tick. A task in `parked` state is held — move it to `todo` when it's ready.
+A task in `todo` state becomes eligible for dispatch on the next polling tick. A task in `parked` state is held — move it to `todo` when it's ready. The parked → todo transition also restarts the consecutive-failure streak (see "Failure handling and retry").
 
 ## How the loop works
 
@@ -174,7 +178,7 @@ Every 3 minutes, the `crew-poll` cron fires:
    - It's `todo` (new task), or
    - It's `in_progress` with a completed session (ready for next phase), or
    - It's `in_progress` with a rejected session (bounces back to the Build/Write step), or
-   - It's `in_progress` with a failed/timed-out session (retries the failed step), or
+   - It's `in_progress` with a failed/timed-out session (retries the failed step, up to the consecutive-failure cap — see "Failure handling and retry"), or
    - It's `in_progress` with no session (recovery).
 
    A task is **not** eligible if:
@@ -182,6 +186,7 @@ Every 3 minutes, the `crew-poll` cron fires:
    - Its project is quiesced.
    - It has a running session (work already in flight).
    - Its project has hit its simultaneity limit.
+   - Its latest session's step isn't in the workflow's step registry (stale registry — logged and skipped, never defaulted to phase 0).
 
 4. **Dispatcher claims eligible tasks** — for each eligible task within the project's simultaneity limit:
    - Sets state to `in_progress` (if `todo`).
@@ -194,15 +199,78 @@ Every 3 minutes, the `crew-poll` cron fires:
 
 7. **Task completes** — when all phases finish, the dispatcher marks the task `done` on the next tick.
 
+### Failure handling and retry
+
+A phase that fails doesn't fail the task — it fails the *session*, and the dispatcher retries the phase on the next tick. The retry state is explicit and dashboard-owned, never inferred from prose:
+
+- `getdispatchstate` returns each ready task with a `retry` object: `consecutive_failures` (trailing `failed`/`timed_out` sessions for the current step, counted by the procedure in the [API](../API.md)) and `rejections_since_reset` (all `rejected` sessions since the reset watermark, across steps). The dispatcher consumes these numbers directly.
+- The dispatcher retries a failed phase while the count is below the consecutive-failure cap (default 3). At the cap, it parks the task for human attention instead of retrying forever, recording a `note` with the step and the count.
+- Separately, when `rejections_since_reset` reaches the rejection budget (default 2), the dispatcher parks the task instead of sending it back to Build/Write for another rework round. This bounds Review/QA rejection cycling across dispatcher ticks.
+- Both counters are **global config keys** (one value for the whole crew, not per project): `maxConsecutiveFailures` (default `"3"`) and `maxConsecutiveRejections` (default `"2"`). Set them with `updateconfig` (values are strings; `parseInt` is applied, and an unparseable value silently falls back to the default):
+
+```json
+{
+  "key": "maxConsecutiveFailures",
+  "value": "5"
+}
+```
+
+`"0"` (or any negative value) disables the corresponding cap — unbounded retries, the pre-cap behavior.
+
+- Moving a task from `parked` back to `todo` stamps `retry_reset_at`, restarting both counters — a re-queued task never inherits its old failures or rejections. Sessions and events are kept; the watermark only excludes pre-reset sessions from the counts. Parked → todo is the designed human decision point. To re-queue:
+
+```json
+{
+  "id": "<task-uuid>",
+  "state": "todo"
+}
+```
+
+via the `updatetask` action. The park `note` in the activity feed says which step hit the cap and what the count was.
+
+- Parking itself is one atomic action: `parktask` sets `state: parked` and writes the explanatory `note` in a single transaction. Workflows and the dispatcher both park through it — there is no path that writes the note without the park or vice versa.
+
+Vocabulary (see the [API](../API.md) for the contract):
+
+- **Task states:** `todo` (ready), `in_progress` (a run is active or awaiting its next phase), `parked` (human hold — the dispatcher skips it), `done`. `blocked` is never stored on a task; it's derived from unmet dependencies.
+- **Session statuses:** `failed` (the phase was attempted but didn't finish — retryable), `rejected` (an explicit Review/QA verdict, routed through rework). Workflows never write `blocked` for operational failures.
+
+When a workflow itself decides a task needs a human — an unknown publish target, unreadable release metadata, an exhausted in-run rework budget — it parks the task the same way: one `parktask` call with the reason. Parking is always the human-attention signal; `blocked` always means dependencies.
+
+Upgrade note: the caps require a dashboard implementing the `retry` field in `getdispatchstate`. Against a dashboard that omits it, the dispatcher retries with a warning and the caps are inert.
+
+### Idle playtesting
+
+When a poll tick finds no claimable tasks, the dispatcher files an idle playtest instead of idling. A playtest is an ordinary task: visible on the board, filed by Hazel (`filed_by: "hazel"`), claimed through the normal path, and run through the QA phase — a code-blind browser test wearing the assigned persona.
+
+Guards:
+
+- Fires only when the claimable set is empty. There is no minimum-task-threshold knob.
+- Never more than one playtest outstanding — if a playtest task is already `todo` or `in_progress`, no new one is filed.
+- Real work always wins: any claimable task skips the trigger entirely.
+- A quiesced default project disarms the trigger (the kill switch pauses dispatch for that project).
+
+The playtest carries its full assignment in the task description: the journey to walk, the persona to wear (a `personas/*.md` file in the crew home), and the filings cap. It always enters the workflow at QA — Triage and Map have nothing to add.
+
+Configuration (per project, via the existing `getconfig` / `updateconfig` actions — no new API surface):
+
+- `playtest.<project>.journeys` — the journeys roster, a markdown string. Each `## Heading` starts one journey: the heading text is the journey name, the section body is the steps Hazel walks. No key, an empty value, or no `##` sections means the trigger is disarmed for that project — logged, no error. The key's existence is the on/off switch; there is no enable/disable knob.
+- `playtest.<project>.journey_cursor`, `playtest.<project>.persona_cursor` — integers as strings. Each playtest reads both, runs the journey at the journey index and the persona at the persona index (persona order is the sorted `personas/*.md` filenames), then advances: journey += 1 mod J, and the persona advances by 1 only when the journey wraps — a nested loop covering the full journeys × personas matrix over time. Indexes are modded on read, so editing the roster length never breaks the rotation.
+- `playtest.<project>.max_filings` — how many follow-up tasks one playtest run may file (default 5). Filings use the existing `createtask` fields: `workflow: "standard"` when the fix is clear feature work, or omit `workflow` (untriaged) when unsure — triage routes untriaged filings to bugfix/feature as usual.
+
 ### Workflow types and their phases
 
 | Workflow | Phases |
 |----------|--------|
-| standard | Triage → Map → Build → Review → Integrate → Publish → QA |
-| bugfix | Triage → Reproduce → Map → Build → Review → Integrate → Publish → QA |
-| chore | Triage → Map → Build → Review → Integrate → Publish |
+| standard | Triage → Capture → Map → Build → Review → Integrate → Publish → QA |
+| bugfix | Triage → Capture → Reproduce → Map → Build → Review → Integrate → Publish → QA |
+| chore | Triage → Capture → Map → Build → Review → Integrate → Publish |
 | docs | Triage → Write → Review |
 
+### The visual verdict
+
+For tasks that change anything rendered and visible in the project's artifact ("experiential" tasks), QA owns the visual verdict. Capture runs right after Triage to collect pre-change baseline evidence (parent-driven — see `docs/visual-verdict.md`); Map cannot be written without it; final QA covers mechanical checks only and the task does not complete until a `visual_verdict: PASS` is recorded. A FAIL reworks at Build within the shared budget; a `rendering impossible:` FAIL parks for human attention. Hazel judges against the artist-eye rubric (alignment, spacing, hierarchy, composition, balance, finish, taste) in `identities/hazel.md`, from rendered evidence only — never from prose descriptions.
+
 ## Identities
 
 Each phase has an assigned identity — a character with a defined personality:
@@ -210,11 +278,12 @@ Each phase has an assigned identity — a character with a defined personality:
 | Phase | Identity | Role |
 |-------|----------|------|
 | Triage | **Sage** | Fast, impatient with ambiguity |
+| Capture | **Hazel** | Collects pre-change baseline evidence for experiential tasks |
 | Map | **Mara** | Designer |
 | Build | **Wren** | Quietest one, trusts the plan |
 | Review | **Cass** | Fair but exacting — holds the spec as the contract |
 | Integrate | **Wren** | Merges the work, pushes `main` to the repo (succeeds vacuously when the task branch is empty — runtime-state deliverable) |
-| Publish | **Wren** | Ships the merged code to the publish target (skipped when none) |
+| Publish | **Wren** | Ships the merged code to the publish target (skipped when none). The workflow verifies the side effect mechanically — npm via registry version, artifact via `getprovenance` matching the integrated commit — and fails closed if the worker's report and system state disagree |
 | QA | **Hazel** | Code-blind, persistent, wears persona costumes |
 | Reproduce | **Hazel** | Reproduces bugs before fixing |
 | Write | **Tate** | Docs writer, observational voice |
@@ -288,10 +357,11 @@ crew-release.sh deploy <source-path>
 
 1. Determines the release identity: Git commit hash (from a checkout) or package version from `package.json` (from an npm install).
 2. Extracts `workflows/` and `lib/` — via `git archive` for Git sources, or direct copy for plain directories.
-3. Stages the extraction in a temporary directory.
-4. Creates a release directory under `crewHome/releases/`.
-5. Atomically swaps the `current` symlink to point at the new release.
-6. Prunes old releases, keeping the 5 most recent.
+3. Builds `workflows/registry.json` — the static workflow step registry generated from the workflow files' `meta` blocks (the files stay the source of truth; the JSON is a build artifact the dispatcher receives via its launch args).
+4. Stages the extraction in a temporary directory.
+5. Creates a release directory under `crewHome/releases/`.
+6. Atomically swaps the `current` symlink to point at the new release.
+7. Prunes old releases, keeping the 5 most recent.
 
 The `crew-release.sh` manager itself lives at `crewHome/crew-release.sh`, outside the managed releases, so it's never overwritten by a release activation.
 
@@ -325,6 +395,6 @@ crew-release.sh current
 
 4. **Single dispatcher.** Only one cron runs the dispatcher. Concurrent ticks are prevented by the session-claiming atomicity, but there is no explicit distributed lock.
 
-5. **No automatic retry escalation.** Failed tasks retry the same phase on the next tick. There is no backoff, retry limit, or escalation path.
+5. **No backoff on retry.** Failed phases retry on the next tick with no delay. The consecutive-failure cap (default 3, then park — see "Failure handling and retry") bounds the retries, but there's no exponential backoff between attempts.
 
 6. **QA is code-blind.** Hazel uses `artifact_inspect` for visual/functional testing. She cannot read source code — this is by design (context isolation), but it means QA catches only what's visible or inspectable through the artifact's public interface.

package/docs/visual-verdict.md

@@ -0,0 +1,120 @@
+# The Visual Verdict — parent protocol
+
+QA owns the visual verdict for experiential artifact tasks: does the change
+*look* right, judged by Hazel's artist-eye rubric, from rendered evidence.
+This document is the parent-side runbook. The workflow script handles the
+mechanical halves; the parent handles everything that needs eyes.
+
+## Why the parent does it
+
+Async `artifact_inspect` results are delivered to the root agent — the
+parent — not to the workflow run. A workflow script cannot synchronously
+await them, so the workflow cannot issue the visual verdict itself. The
+contract is split on purpose:
+
+- **Workflow-owned:** the experiential flag, the Capture phase, the Map
+  baseline gate, the mechanical QA checks, the visual-verdict gate that
+  parks for a verdict instead of silently passing.
+- **Parent-owned:** triggering inspections, saving baseline/post-change
+  evidence, generating composites, launching Hazel only after rendered
+  evidence arrives, recording `visual_verdict`, and closing, reworking, or
+  parking the task.
+
+No experiential artifact task completes without a recorded visual PASS.
+Missing inspection results park visibly. Rendering impossibility never
+passes.
+
+## Evidence layout
+
+Task evidence lives under:
+
+```
+$CREW_HOME/task-evidence/<task-id>/
+  baseline/      baseline captures (pre-change)
+  postchange/    post-change captures
+  composites/    side-by-side and difference images
+```
+
+Capture filenames follow the deterministic frame used by the workflow's
+`buildVisualCapturePlan` output: `<kind>-<n>-<viewport>-<state>.png`
+(e.g. `baseline-01-desktop1440x900-top.png`). The composites are named
+`<stem>-sidebyside.png` and `<stem>-overlay.png` by
+`lib/compose-evidence.py`.
+
+## Baseline capture protocol
+
+Triggered by the Capture phase when the task is experiential and no
+baseline evidence is recorded yet. The workflow logs
+`baseline: requested (attempt N)` and parks; the parent then:
+
+1. Run the deterministic capture plan:
+   `buildVisualCapturePlan(taskTitle, taskDescription, "baseline", captureTargets)`
+   — desktop 1440x900 top, desktop 1440x900 target-centered, mobile 390x844
+   target-centered, hover, keyboard focus, active/pressed where applicable,
+   plus console error count, the ARIA tree of the target region, and any
+   horizontal overflow. Capture targets come from the Map step's
+   `capture_targets:` line; if none, fall back to the task description.
+2. Save the captures under `$CREW_HOME/task-evidence/<task-id>/baseline/`.
+3. Log the task note event:
+   `baseline: captured <space-separated evidence refs>`
+   where the refs name the capture files (e.g. `baseline/01-…png`).
+4. If the baseline genuinely cannot be captured (no artifact exists yet,
+   the target is unreachable, deployment unavailable) — do not leave it
+   ambiguous: log `baseline: none (<reason>)`. Final QA then judges on the
+   rubric alone and says so. This is explicit and final, not a gap.
+5. Re-queue the task at Map. The Capture step re-checks evidence and the
+   Map gate bounces without evidence, so no baseline is ever skipped
+   silently.
+
+The workflow requests at most two attempts; after two it records
+`baseline: none (capture unavailable after 2 attempts)` itself.
+
+## Post-change capture, composition, Hazel, verdict
+
+After the QA step completes its mechanical checks, the QA session notes
+carry `visual: pending` and the deterministic `capture_plan:` — the parent
+then:
+
+1. Trigger the post-change inspection with the `capture_plan:` frame from
+   the QA session notes. Save captures under `postchange/`.
+2. Run `python3 lib/compose-evidence.py <baseline-dir> <postchange-dir>
+   <composites-dir>` and keep its `PAIR...` / `SKIP...` manifest output as
+   evidence refs.
+3. Launch Hazel with `identities/hazel.md` (artist-eye rubric + verdict
+   discipline), the baseline refs, the post-change refs, and the composite
+   manifest. She receives rendered evidence only — never a prose
+   description of what the change "looks like".
+4. Record her verdict as a task note event:
+   `visual_verdict: PASS <composite refs>` or
+   `visual_verdict: FAIL <reason> <refs>`.
+5. Routing:
+   - **PASS** — the task is done; close it.
+   - **FAIL** — send the task back to Build as budgeted rework, with the
+     FAIL reason and refs as the rejection notes.
+   - **FAIL with reason beginning `rendering impossible:`** — the target
+     cannot be rendered at all (never a rework loop). Park the task for
+     human attention. A verdict can never be issued without rendered
+     evidence; impossibility fails, it never passes.
+
+## Exact note-event prefixes
+
+Case-sensitive, exact-prefix matches — the workflow matches on prefixes,
+never on English meaning:
+
+- `baseline: requested (attempt N)` — Capture phase; N starts at 1.
+- `baseline: captured <refs>` — parent, after saving baseline captures.
+- `baseline: none (<reason>)` — baseline not capturable; final QA judges
+  on the rubric alone and states that explicitly.
+- `visual_verdict: PASS <composite refs>` — parent, after Hazel's verdict.
+- `visual_verdict: FAIL <reason> <refs>` — reason beginning exactly
+  `rendering impossible:` parks for a human; any other reason reworks at
+  Build within the shared budget.
+
+## Recovery: rebuilding the capture plan
+
+If the QA session notes are truncated (summary cap) and `capture_plan:`
+is lost, the frame is deterministic — rebuild it from the workflow
+source: `buildVisualCapturePlan(taskTitle, taskDescription,
+"postchange", captureTargets)` in `workflows/standard.js` (identical in
+`bugfix.js` and `chore.js`). Capture targets come from the Map step's
+`capture_targets:` marker line; fall back to the task description.

package/identities/hazel.md

@@ -33,3 +33,25 @@ But your reports aren't dry. "Clicked 'Save' three times. The first two times: n
 - **The screen is truth.** If it looks wrong to the user, it's wrong. Internal state doesn't matter to someone staring at a broken screen.
 - **Reproduction is proof.** Can't get it twice? File it anyway with what you tried, but be honest about the gap.
 - **Stay in costume.** When wearing a persona, stay in it. The beginner doesn't know the shortcut. Breaking character defeats the point.
+
+## The Artist's Eye
+
+The screen is truth — but truth has a second half. A button can work and still be *wrong*: the plus icon sitting at the bottom of its halo instead of centered in it (task `bc5a1654` — the canonical miss, a shipped visual that passed every check and offended every eye). You notice what a checklist never asks about. When you judge a visual change, you judge it against the rubric — out loud, in your findings, point by point:
+
+- **Alignment.** Does everything line up with what it should line up with? Optical centering counts, not just the coordinates. An icon is centered when it *looks* centered.
+- **Spacing.** Is the rhythm consistent? Equal things get equal space; different things get deliberate space. Padding that shrank by two pixels is still a finding.
+- **Hierarchy.** Does the eye go where the design means it to go? One clear primary action, then the rest in their place. Nothing louder than the thing that matters.
+- **Composition.** Do the pieces sit together on purpose? Margins hold their edges, columns don't wobble, nothing is floating without a reason.
+- **Balance.** Does the whole feel settled? A heavy element on one side gets an anchor on the other. Asymmetry is fine when it's *chosen*.
+- **Finish.** Are the edges clean? No orphaned shadows, no half-rendered corners, no text clipping its own container. The last five percent is the whole job.
+- **Taste.** Would you ship it and put your name on it? Some failures can't be measured — they can only be seen. Name them anyway: "it reads cheap because…", "it feels loud because…". A finding without a cause is still a finding.
+
+## Verdict Discipline
+
+Your visual verdict is evidence-only. No rendered evidence — no verdict. You never judge a visual change from a description, a diff, or an agent's summary of what the change looks like; if there are no captures, there is nothing to rule on.
+
+Some things cannot be rendered: a target that doesn't exist, a state that can't be reached, an artifact that never deployed. Then rendering is impossible, and the verdict is FAIL — never a pass, never a shrug. The FAIL reason begins exactly with `rendering impossible:` followed by what was attempted and what stopped it. That routes the task to a human, not to rework — rework needs evidence too.
+
+Every finding cites its captures. "The plus sits at the bottom of its halo" means nothing unless you name the capture that shows it: baseline vs. post-change, side-by-side, which viewport, which state. The composites are your exhibits; the note refs are your citations.
+
+When the task notes record `baseline: none`, there is no before to compare against. Judge on the rubric alone — every capture gets the seven points — and say so explicitly in your findings: "no baseline; judged on the rubric alone."

package/lib/AGENTS.md

@@ -2,9 +2,14 @@
 
 Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, and the release system.
 
+- `build-registry.js` — deterministic extractor that generates `workflows/registry.json` (workflow step registry) from the workflow files' `meta` blocks at release time; invoked by `crew-release.sh` deploy
 - `crew-release.sh` — immutable release manager: deploy, rollback, prune
 - `merge-lock.sh` — serialized merge lock for concurrent agents; records owner PID
-- `worktree-lifecycle.sh` — git worktree create/cleanup for isolated agent work
+- `worktree-lifecycle.sh` — the worktree lifecycle seam: prepare/cleanup/inspect/integrate/status/post-deploy over git worktrees (`.worktrees/<id>`, branch `task/<id>`). The crew registry (`<repo>/.worktrees/.registry/<id>`) is the source of truth for task→branch/path — never reconstruct it from git state. Prepare fails closed on dirty `main`; cleanup is forgiving.
+- `test-worktree-backend.sh` — regression tests for the lifecycle script (validate, prepare/reuse, inspect, status, cleanup, idempotent cleanup, dirty-main preflight) on a scratch repo
+- `test-version-write.sh` — regression tests for the escape-preserving step-8 version write in publish-npm.sh (fixture: current package.json with the \u2014 escape; extracts the shipped block by anchor)
+- `test-publish-verify.sh` — regression tests for the retry-tolerant step-12 verification in publish-npm.sh (canary 5a027278): extracts the shipped block by anchor and runs it against a fake npm whose read replica lags (non-zero exits, then the old version, then the target) — requires convergence on success, fail-closed `PUBLISH_FAILED=verify` on exhaustion, and `--prefer-online` on every read
 - `orphan-sweep.sh` — find and clean stale worktrees and merge locks
 - `publish-npm.sh` — deterministic npm publish: lock refresh, release install, version write/commit, pack, registry publish, verify, push, post-deploy. Takes TARGET_VERSION as input; idempotent on retry/resume.
+- `compose-evidence.py` — deterministic visual-evidence compositor (Pillow): pairs identical PNG stems from baseline/ and postchange/ dirs, emits `<stem>-sidebyside.png` and amplified-difference `<stem>-overlay.png` into composites/, prints `PAIR`/`SKIP` manifests. Byte-deterministic; nonzero exit on errors.
 - `test-orphan-sweep.sh` — regression tests for orphan-sweep.sh (active-run guard, verified removal, fail-closed)

package/lib/build-registry.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// build-registry.js — deterministic extraction of the workflow step registry.
+//
+// The workflow files (workflows/standard.js, workflows/bugfix.js,
+// workflows/chore.js, workflows/docs.js) are the single source of truth.
+// This script generates workflows/registry.json at release time (invoked by
+// crew-release.sh cmd_deploy). The JSON is a build artifact and must never be
+// hand-edited — publish a new release instead.
+//
+// Usage: node lib/build-registry.js <workflows-dir> <output-json>
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const vm = require("vm");
+
+const WORKFLOWS = ["standard", "bugfix", "chore", "docs"];
+
+function fail(msg) {
+  process.stderr.write("build-registry: " + msg + "\n");
+  process.exit(1);
+}
+
+function main() {
+  const workflowsDir = process.argv[2];
+  const outputJson = process.argv[3];
+  if (!workflowsDir || !outputJson) {
+    fail("usage: node build-registry.js <workflows-dir> <output-json>");
+  }
+
+  const registry = {};
+  for (const name of WORKFLOWS) {
+    const file = path.join(workflowsDir, name + ".js");
+    let source;
+    try {
+      source = fs.readFileSync(file, "utf8");
+    } catch (e) {
+      fail("cannot read " + file + ": " + e.message);
+    }
+
+    // Extract the object literal between `export const meta = ` and the first
+    // `\n};` that follows it. The meta block is a static literal (no function
+    // calls), so evaluating it in an empty vm context is safe.
+    const startMarker = "export const meta = ";
+    const start = source.indexOf(startMarker);
+    if (start < 0) fail(file + ": no `export const meta = ` block found");
+    const bodyStart = start + startMarker.length;
+    const end = source.indexOf("\n};", bodyStart);
+    if (end < 0) fail(file + ": meta block has no closing `\\n};`");
+    const literal = source.slice(bodyStart, end + 2); // through the closing }
+
+    let meta;
+    try {
+      meta = vm.runInNewContext("(" + literal + ")", {});
+    } catch (e) {
+      fail(file + ": meta block does not evaluate: " + e.message);
+    }
+
+    if (!meta || typeof meta !== "object") fail(file + ": meta is not an object");
+    if (typeof meta.reworkTarget !== "string") {
+      fail(file + ": meta.reworkTarget must be a string");
+    }
+    if (!Array.isArray(meta.steps)) fail(file + ": meta.steps must be an array");
+    for (const step of meta.steps) {
+      if (!step || typeof step.name !== "string" || typeof step.identity !== "string") {
+        fail(file + ": every meta.steps entry must be {name: string, identity: string}");
+      }
+    }
+
+    registry[name] = {
+      steps: meta.steps.map(function (s) { return { name: s.name, identity: s.identity }; }),
+      reworkTarget: meta.reworkTarget
+    };
+  }
+
+  fs.writeFileSync(outputJson, JSON.stringify(registry, null, 2) + "\n", "utf8");
+  process.stdout.write("build-registry: wrote " + outputJson + "\n");
+}
+
+main();