muse-crew 0.8.1 → 0.9.0

package/API.md

@@ -391,6 +391,7 @@ Register a new project.
 | `simultaneity` | integer (1–100) | no | Max concurrent tasks; defaults to 2 |
 | `quiesced` | boolean | no | Start paused; defaults to false |
 | `visual_protocol` | boolean or null | no | Tri-state: `null` = inherit crew default (off), `true` = enable for this project, `false` = explicit off. Defaults to null. |
+| `environment_type` | `artifact` · `terminal` · null | no | User-facing surface for experiential QA routing: `artifact` = a rendered web UI (Hazel drives it with the see-act browser loop), `terminal` = a CLI (Hazel drives it herself, keeping transcripts). `null` = unclassified: no experiential QA. `deploy_type` names the deployment target, but `deploy_type: "artifact"` remains a legacy artifact-surface signal so pre-field projects keep today's experiential QA (the migration does not backfill the column); on conflicting config artifact wins. Defaults to null. |
 
 ### `updateproject`
 
@@ -400,6 +401,8 @@ Update project fields. Only `id` is required; all others are optional patch fiel
 
 **`visual_protocol`:** accepted values are `true`, `false`, `null`; anything else is a validation error. `null` clears the override and returns the project to inherit. It is **not** covered by the context-change guard: the dispatcher reads the value once into launch args at dispatch time, so changing it mid-run only affects future launches. Effective value rule: `null` (inherit) and `false` (explicit off) both resolve to off — the visual protocol only runs when the project record carries `true`. The dispatcher passes the resolved boolean to launched workflows as the `visual_protocol` launch arg; workflows receive a plain boolean and never see the tri-state.
 
+**`environment_type`:** accepted values are `artifact`, `terminal`, `null`; anything else is a validation error. Like `visual_protocol`, it is **not** covered by the context-change guard: project config is captured at dispatch time, so a change affects future launches. `null` means unclassified — experiential QA does not run (today's generic behavior). See `docs/terminal-ux.md` / `docs/artifact-ux.md` — one shared UX bar per surface, resolved from `environment_type` by `lib/ux-doctrine.js`; every phase prompt reads the resolved page, never a hardcoded filename. The dashboard registers itself with `environment_type: "artifact"` at crew-init.
+
 ### `deleteproject`
 
 Remove a project registration.

package/docs/artifact-ux.md

@@ -0,0 +1,110 @@
+# Artifact UX — the shared bar for rendered projects
+
+For projects whose user-facing surface is a rendered artifact
+(`environment_type: "artifact"`), **the screen is the UI**. The user sees
+pixels: pages, components, layout, copy, visual states. This page is the
+crew-wide standard for that experience — the artifact sibling of
+`docs/terminal-ux.md`, resolved from the same project config by
+`lib/ux-doctrine.js`. Every phase reads the same page:
+
+- **Sage** (Triage) uses it to decide whether a task is experiential —
+  anything this page covers is user-observable.
+- **Mara** (Map) specs against it: exact screens, flows, and visual
+  states, plus the capture targets for the post-change visual capture.
+- **Wren** (Build) builds to it: the rendered result is what ships, and
+  it ships in the commit.
+- **Cass** (Review) reviews against it and rejects when the bar is not
+  met.
+- **Hazel** (QA) drives the artifact herself and renders the verdict
+  against it, point by point.
+- **Tate** (Docs) writes the public contract from it: the documented
+  behavior must match what the user sees.
+
+The experiential nature doesn't change across surfaces. It's still codeless
+UX judged with taste — a different instrument, the same bar.
+
+## The bar
+
+Judge every artifact change against these, out loud and 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.
+- **Correctness.** Does it render what the task required? No broken
+  layout, overflow, missing or wrong content, stale data. Console errors
+  are defect signals. Loading, error, or blank frames never pass.
+- **Overall feel.** Would you ship it and put your name on it? Some
+  failures can't be measured — they can only be seen. "It reads cheap
+  because…", "it feels loud because…". Name them anyway.
+
+## Evidence
+
+Artifact evidence is **screenshots**, read by the agent who took them.
+Hazel drives the deployed artifact with the see-act browser driver
+(`aria|shot|click|scroll|type`, desktop and mobile viewports), archives
+every frame attempt-scoped (`<phase-dir>/<nn>-<action>-<viewport>.png`),
+and ties each step to its frame in the OODA log. Image tools
+(`crop|zoom|label|nup` via `lib/edit-image.py`, `compose` via
+`lib/render-html.js`) supplement raw frames — derivatives never replace
+the source frame.
+
+The mechanics — OODA log schema, append-only attempts, verdict ledger,
+screenshot archival — are shared across surfaces and live in
+`docs/ooda-report.md`. They are not repeated here.
+
+Discipline, same as the terminal loop:
+
+- **Code-blind.** Hazel drives the artifact; she never reads its source.
+  Public docs are not source — she reads them as a user would.
+- **Read before judging.** An unread frame is not evidence.
+- **Beginner and designer journeys.** Stumble like a new user, then look
+  like a designer. One perspective is never enough.
+- **Append-only attempts.** Reruns are new attempts — never overwrite.
+- **NOT_POSSIBLE, never fabricated.** If the browser will not drive,
+  log exit 3 with NOT POSSIBLE and return unknown — never invent a
+  frame. Unknown is neither PASS nor FAIL.
+- **Every finding cites its evidence.** Baseline vs. post-change, which
+  viewport, which state. A claim without its capture is an unverified
+  claim.
+- **No baseline, rubric alone.** When the task notes record
+  `baseline: none`, judge on the rubric alone and say so explicitly.
+
+## Non-negotiables
+
+1. The deployed artifact is what's judged. Hazel drives the built
+   artifact served locally — never source, never a description, never a
+   diff.
+2. A PASS without visual evidence is never terminal. If the visual loop
+   could not run, the task parks fail-closed
+   (`qa-visual-loop-unavailable`) — never done.
+3. Verdicts are evidence-only. `rendering impossible:` begins the FAIL
+   reason when inspection was impossible — that routes to a human, not
+   to rework.
+4. Public-affecting changes ship public docs in the same commit. QA
+   fails when they're missing or stale.
+
+## Where this page lives in the loop
+
+- Triage: experiential flag against this page.
+- Capture: pre-change baseline screenshots of the affected views.
+- Map: spec declares screens, flows, visual states, and
+  `capture_targets:`.
+- Build: build to the bar — the rendered result ships in the commit.
+- Review: review against the bar — reject when it's not met.
+- QA: the visual loop (≤8 steps, desktop + mobile), screenshots,
+  OODA report, verdict against this page point by point.
+- Docs: the public contract matches what the user sees.

package/docs/guide.md

@@ -327,13 +327,13 @@ Fail-closed rules: an upgrade never mutates the crew repo (repo source always me
 
 ### 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.
+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 shared bar in `docs/artifact-ux.md` (the artist-eye rubric: alignment, spacing, hierarchy, composition, balance, finish, taste), from rendered evidence only — never from prose descriptions. Every phase reads the doctrine page resolved from the project's `environment_type` (`docs/artifact-ux.md` for artifact surfaces, `docs/terminal-ux.md` for terminal surfaces — resolved mechanically by `lib/ux-doctrine.js`, never hardcoded per-prompt).
 
 ### Reproduce at the bug's layer
 
 Bugfix tasks reproduce at the layer where the bug lives — not always in the browser. During Triage, Sage classifies the bug's layer with a machine-read marker line (`layer: artifact`, `layer: engine`, or `layer: docs`):
 
-- **artifact** — user-facing behavior of the rendered artifact (something a user sees or clicks). Reproduced with the experiential see-act browser loop, as today.
+- **artifact** — user-facing behavior of the rendered artifact (something a user sees or clicks). Reproduced with the experiential see-act browser loop, as today — on terminal-surface projects (`environment_type: terminal`) the reproducer drives the CLI herself instead, keeping attempt-scoped transcripts under the shared bar in `docs/terminal-ux.md`.
 - **engine** — the crew's own machinery: workflows, lib scripts, shell scripts, tests, scheduler. Reproduced deterministically with shell commands in the repo checkout — run the failing script, re-run the failing test suite (`bash tests/run.sh`), query crew state via the API.
 - **docs** — a documentation gap or error. Reproduced by reading the file and confirming the gap is actually there.
 

package/docs/ooda-report.md

@@ -1,11 +1,12 @@
 # OODA Report
 
-The experiential report produced by the Reproduce and QA phases' see-act loop
-(2026-09-14; hardened 2026-09-15). When an agent drives the browser one step
-at a time — observing each frame, deciding the next action — the complete
-record of that session is the **OODA report**: the ordered
-Observe/Orient/Decide/Act trace, the archived frames, and a machine-readable
-terminal verdict.
+The experiential report produced by the Reproduce and QA phases'
+experiential loop (2026-09-14; hardened 2026-09-15; terminal loop added
+2026-09-17). When an agent drives the product's user-facing surface one
+step at a time — observing each frame or transcript, deciding the next
+action — the complete record of that session is the **OODA report**: the
+ordered Observe/Orient/Decide/Act trace, the archived evidence, and a
+machine-readable terminal verdict.
 
 ## Location
 
@@ -27,14 +28,15 @@ One JSON object per line, appended after every browser action via
 `lib/append-ooda-step.js`:
 
 ```json
-{"step":1,"attempt":"1","action":"aria","args":{},"exit":0,"screenshot":null,"observation":"Login button found in header.","ts":"..."}
-{"step":2,"attempt":"1","action":"shot","args":{},"exit":0,"screenshot":"/abs/.../001-shot-desktop.png","observation":"Header renders, no console errors.","ts":"..."}
+{"step":1,"attempt":"1","action":"aria","args":{},"exit":0,"screenshot":null,"transcript":null,"observation":"Login button found in header.","ts":"..."}
+{"step":2,"attempt":"1","action":"shot","args":{},"exit":0,"screenshot":"/abs/.../001-shot-desktop.png","transcript":null,"observation":"Header renders, no console errors.","ts":"..."}
 ```
 
 Schema: `step` (positive int), `attempt` (the attempt/run identity —
 `"1"`, `"2"` for successive QA loops, `"repro-1"` for a reproduce run),
-`action`, `args` (object), `exit` (the see-act exit code), `screenshot`
-(absolute path or null), `observation` (the agent's 1–2 sentences: what was
+`action`, `args` (object), `exit` (the driver exit code), `screenshot`
+(absolute path or null), `transcript` (absolute path or null —
+terminal-action steps), `observation` (the agent's 1–2 sentences: what was
 seen and what it implies — this is the payload, not the filename), `ts`
 (optional, agent-supplied).
 
@@ -53,6 +55,15 @@ Every frame-producing action (`shot|crop|zoom|label|nup|compose`) requires
 `--screenshot`: the frame the agent looked at must be the frame it logs. A
 captured-but-unlogged frame is invisible to everyone after the agent.
 
+The `terminal` action (terminal-surface driver: one CLI invocation per
+step) requires `--transcript`: the archived stdout/stderr/exit-code
+transcript the agent read. Screenshots are never evidence for terminal
+work — the writer rejects `--screenshot` on `terminal` steps. A step whose
+CLI would not run logs `--exit 3` with NOT POSSIBLE in the observation and
+a machine-readable `terminal_loop_unavailable` signal (see
+`lib/read-ooda-verdict.js`) so the closeout parks fail-closed instead of
+stamping done.
+
 The writer validates and fails loudly (exit 2) on bad input. The agent never
 hand-writes JSON — it supplies fields as flags.
 

package/docs/terminal-ux.md

@@ -0,0 +1,110 @@
+# Terminal UX — the shared bar for CLI projects
+
+For projects whose user-facing surface is a command-line interface
+(`environment_type: "terminal"`), **the terminal is the UI**. There is no
+screen to look at, but there is still a user — and that user's whole
+experience is the command's output, its help, its errors, its exits. This
+page is the crew-wide standard for that experience. Every phase reads the
+same page:
+
+- **Sage** (Triage) uses it to decide whether a task is experiential —
+  anything this page covers is user-observable.
+- **Mara** (Map) specs against it: exact commands, expected
+  stdout/stderr, exit codes, help text, error messages.
+- **Wren** (Build) builds to it: `--help` text, error messages, and exit
+  codes are user-facing and ship in the commit.
+- **Cass** (Review) reviews against it and rejects when the bar is not
+  met.
+- **Hazel** (QA) tests against it and renders the verdict against it,
+  point by point.
+- **Tate** (Docs) writes the public terminal contract from it: the
+  documented commands must match the shipped behavior.
+
+The experiential nature doesn't change across surfaces. It's still codeless
+UX judged with taste — a different instrument, the same bar.
+
+## The bar
+
+Judge every terminal change against these, out loud and point by point:
+
+- **Discoverability.** Can a new user find the command? `--help` exists,
+  lists what the tool does, and names every command/flag without jargon.
+  A user who has never seen this CLI reaches the right command on the
+  first or second try.
+- **Help accuracy.** `--help` (and any man/docs page) describes what the
+  command *actually does* — flags, defaults, examples. Help that lies is
+  a defect, not a nit.
+- **Defaults.** Sensible out of the box. A user who runs the command with
+  no flags gets the reasonable thing, not the dangerous thing or nothing.
+- **Happy path.** The intended use works end to end and its output is
+  legible: clear structure, no noise, the result is obvious.
+- **Malformed input.** Bad flags, missing args, nonexistent files, empty
+  input, contradictory flags — every one of these is a designed moment,
+  not an accident. The user did something wrong; the tool's job is to
+  notice gracefully.
+- **Error quality.** Every failure must do three things: exit non-zero,
+  say what went wrong in plain language, and tell the user the fix. A
+  raw stack trace shown to a user is a defect — file it as one.
+- **Exit behavior.** Zero means success, non-zero means failure, and the
+  codes are stable and documented. A script consuming this tool can trust
+  the exit code. Piping (stdout vs stderr separation) is correct.
+- **Output clarity.** stdout is the answer, stderr is the commentary.
+  Progress, warnings, and diagnostics go to stderr; data goes to stdout.
+  No chatter on stdout that breaks `| jq`.
+- **State effects.** The command says what it changed and leaves nothing
+  surprising behind: no stray files, no half-written state on failure,
+  dry-run/confirm flags where destruction is possible.
+- **Repeatability.** Run it twice with the same input: same output
+  (modulo timestamps). Idempotent where idempotence is promised.
+- **Overall feel.** Would you ship it and put your name on it? Some
+  failures can't be measured — they can only be felt. "The output reads
+  cheap because…", "the error is hostile because…". Name them anyway.
+
+## Evidence
+
+Terminal evidence is **transcripts**, not screenshots. For each CLI
+invocation Hazel preserves: the exact command and arguments, stdout,
+stderr, the exit code, and her observation/conclusion. Transcripts are
+archived attempt-scoped (`<phase-dir>/<nn>-<slug>.txt`, numbered 01, 02,
+…), one command per transcript, and the OODA log (`ooda-log.jsonl`) ties
+each step to its transcript via `--action terminal --transcript`.
+
+Discipline, same as the visual loop:
+
+- **Code-blind.** Hazel runs the CLI; she never reads its source.
+- **Read before judging.** An unread transcript is not evidence.
+- **Beginner and adversarial journeys.** Run it right (the happy path),
+  then run it wrong on purpose.
+- **Append-only attempts.** Reruns are new attempts — never overwrite.
+- **NOT_POSSIBLE, never fabricated.** If the CLI will not run, log
+  exit 3 with NOT POSSIBLE and return unknown — never invent a
+  transcript. Unknown is neither PASS nor FAIL.
+- **No screenshots for terminal work.** Screenshots are not terminal
+  evidence; `append-ooda-step.js` rejects them on terminal steps.
+
+## Non-negotiables
+
+1. `--help` is a user interface, not a comment. It must be accurate,
+   complete, and current — it ships in the same commit as the behavior
+   it describes.
+2. Errors are designed. Every error path exits non-zero, speaks plain
+   language, and points at the fix. Stack traces are never the user
+   interface.
+3. The documented contract matches the shipped behavior. When Tate's
+   docs say the command does X, the command does X — the docs gate fails
+   QA when they disagree.
+4. A PASS without terminal evidence is never terminal. If the terminal
+   loop could not run, the task parks fail-closed
+   (`qa-terminal-loop-unavailable`) — never done.
+
+## Where this page lives in the loop
+
+- Triage: experiential flag + `terminal_targets:` marker.
+- Capture: pre-change baseline transcripts of the terminal targets.
+- Map: spec declares exact commands, stdout/stderr, exit codes,
+  help text, error messages.
+- Build: build to the bar — help, errors, exits ship in the commit.
+- Review: review against the bar — reject when it's not met.
+- QA: the terminal loop (≤8 commands, right then wrong), transcripts,
+  OODA report, verdict against this page point by point.
+- Docs: the public terminal contract matches shipped behavior.

package/docs/upgrade-paths.md

@@ -0,0 +1,105 @@
+# Upgrade paths
+
+The crew upgrades itself and its projects through four paths. Each is a
+crew task filed against a project — never a side channel — and each fails
+closed: when the machine cannot verify what it is upgrading from or to,
+it parks and says so.
+
+## 1. Dashboard (the watcher leg)
+
+The dashboard is the crew's first project: a git repo with an artifact
+publish target. `lib/update-watch.js` polls the dashboard repo's remote
+and files a chore task when the remote HEAD moves:
+
+1. **Remote check.** `git ls-remote` on the dashboard remote gives the
+   candidate sha. Unparseable output skips the run — never a partial file.
+2. **Trusted base.** The watcher keeps `state.dashboard[projectId]
+   .last_filed_sha` — the commit the live artifact was deployed from.
+   The filed task upgrades `recorded -> remote`, and its journey runs
+   `git merge-base --is-ancestor <old> <new>` mechanically.
+3. **Enrollment.** The base is established once, by a human (or by
+   crew-init on first install, which enrolls the checked-out HEAD):
+   `node <crewHome>/current/lib/update-watch.js --crew-home <crewHome>
+   --record-dashboard-sha <40-hex-sha>`.
+   The sha is verified to exist as a commit in the project's repo
+   (`git cat-file -e`) — never guessed. Moving an existing base refuses
+   without `--force`: a human decision.
+4. **Unknown base.** When no base is recorded, the old sha is `unknown`.
+   The watcher still files the task (so the move is visible) but the
+   task description carries enrollment guidance: the agent must park —
+   the ancestor check cannot run against "unknown". Fail closed by
+   design.
+5. **Rewritten history.** If the old sha is not an ancestor of the new
+   sha (force-push / history rewrite), the task parks and says so.
+   Never upgrade across a rewritten history blind.
+6. **Compatibility anchor (`.crew-version`).** The dashboard repo carries
+   a `.crew-version` file at its root containing the strict semver of
+   the crew release it needs. The watcher reads it at the filed ref
+   (never the working tree). When the declared crew is newer than the
+   running crew, the dashboard leg files the crew upgrade **first**
+   (dashboard-led ordering) and the dashboard task notes that it must
+   follow. A declared crew older than the running crew is a downgrade —
+   never filed automatically; a human decides.
+
+The dashboard task's Publish phase carries the artifact update through
+the normal publish path — no side channels.
+
+## 2. Crew (the npm leg)
+
+The crew's own release line upgrades through the `upgrade` workflow
+(see `seed/workflows/upgrade.md`). The watcher's crew leg compares the
+running release (`crew-release.sh current`, e.g. `pkg-0.8.1`) against
+`npm view muse-crew` and files an upgrade task with the pinned first
+line `source: npm@<x.y.z>` on the `muse-crew` project. Idempotency:
+`state.crew.last_filed_version` is written at file time, so a re-run
+does not re-file the same version.
+
+The upgrade workflow: Triage validates the `source:` line (`repo`, or
+`npm@<x.y.z>` — anything else parks fail-closed); Deploy runs the
+stable `$CREW_HOME/crew-release.sh deploy` — against the repo HEAD for
+repo source, or a staging dir under `$CREW_HOME/.upgrade-staging/
+<version>` (public npm install only) for npm source — single command,
+no merge lock; Verify checks mechanically that `crew-release.sh
+current` equals the target and the workflow registry parses. Handover is
+automatic: the next poll tick launches through the `current` symlink —
+the new release. In-flight runs finish on the old release via per-task
+lib pinning.
+
+Safety: never mutate the crew repo, never publish to npm from the
+upgrade path, never touch the scheduler. Any non-zero deploy exit parks
+fail-closed with the exact output — no retry, no auto-rollback
+(`crew-release.sh rollback` is the human recovery path).
+
+## 3. Self (crew-to-crew)
+
+The crew pointed at its own codebase — the `muse-crew` project
+registered with the crew's own repo path — develops and upgrades itself
+through its own dispatch loop. This is the self-improvement proof:
+a human (or the crew's own filed task) files an `upgrade`-workflow task
+with `source: repo` on the `muse-crew` project, and the crew deploys,
+verifies, and hands over to the new release through the same loop that
+will run on it. The crew-to-crew trigger is the proof that the loop is
+self-hosting; the mechanism is identical to path 2, only the trigger
+originates inside the loop.
+
+## 4. External (consumer projects)
+
+Projects that consume the crew as an npm dependency (a `muse-crew`
+project whose repo is not the crew's own) upgrade through the npm
+source path: `source: npm@<x.y.z>` stages a public npm install into
+`$CREW_HOME/.upgrade-staging/<version>` and deploys from there — the
+crew repo is never mutated. External consumers pin their crew the same
+way rooms do: the per-task RUN_LIB pin includes `crew-api.js` and
+`schema.sql`, so in-flight runs finish on the release they started with.
+
+## Enrollment quick reference
+
+```
+# Establish the trusted dashboard base (once per crew home):
+node $CREW_HOME/current/lib/update-watch.js --crew-home $CREW_HOME \
+  --record-dashboard-sha <40-hex-sha>
+
+# Move an existing base (human decision only):
+node $CREW_HOME/current/lib/update-watch.js --crew-home $CREW_HOME \
+  --record-dashboard-sha <40-hex-sha> --force
+```

package/identities/hazel.md

@@ -8,7 +8,7 @@ You use software the way someone who didn't build it uses it. You click things,
 
 ## Craft
 
-Hunting is empirical. You open the product, do things with it, and pay attention. Your evidence is screenshots, reproduction steps, and a clear description of what happened versus what should have happened. That's the toolkit, and it's enough.
+Hunting is empirical. You open the product, do things with it, and pay attention. Your evidence is what the user experienced — screenshots for a rendered surface, transcripts for a terminal one — plus reproduction steps and a clear description of what happened versus what should have happened. That's the toolkit, and it's enough.
 
 You think like a user, not a developer. A user doesn't know what a 204 is. A user knows the button didn't work. The moment you know *why* something works the way it does, you start making excuses for it — and excuses are the enemy of good QA.
 
@@ -30,13 +30,13 @@ But your reports aren't dry. "Clicked 'Save' three times. The first two times: n
 
 ## Values
 
-- **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.
+- **The surface is truth.** If it's wrong to the user, it's wrong — a broken screen or a hostile error message, it makes no difference. Internal state doesn't matter to someone facing a broken surface.
 - **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:
+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 shared bar at `docs/artifact-ux.md` — 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.
@@ -46,12 +46,25 @@ The screen is truth — but truth has a second half. A button can work and still
 - **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.
 
+## The Terminal Ear
+
+For a terminal surface, the transcript is truth. A command can exit zero and still be *wrong*: an error message that says `Error: EINVAL` instead of telling the user what they did wrong (the canonical miss — a failure the tool understood and the user never could). You notice what a checklist never asks about. When you judge a terminal change, you judge it against the shared bar at `docs/terminal-ux.md` — out loud, in your findings, point by point:
+
+- **Discoverability.** Would a new user find the command? Is `--help` where they'd look for it?
+- **Help accuracy.** Does the help describe what the command *actually* does — flags, defaults, examples?
+- **Defaults.** Does the bare command do the reasonable thing?
+- **Error quality.** Every failure: non-zero exit, plain language, the fix. A raw stack trace shown to a user is a defect — file it as one.
+- **Output clarity.** stdout is the answer, stderr is the commentary. No chatter on stdout that breaks a pipe.
+- **Exit behavior.** Codes stable, documented, trustworthy for scripts.
+- **State effects.** Nothing surprising left behind; destruction announces itself.
+- **Feel.** Would you ship it and put your name on it? "The output reads cheap because…", "the error is hostile because…". Name it.
+
 ## 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.
+Your experiential verdict is evidence-only. No captured evidence — no verdict. You never judge an experiential change from a description, a diff, or an agent's summary of what the change does; if there are no captures or transcripts, 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.
+Some things cannot be exercised: a target that doesn't exist, a state that can't be reached, an artifact that never deployed, a CLI that will not run. Then inspection is impossible, and the verdict is FAIL — never a pass, never a shrug. The FAIL reason begins exactly with `rendering impossible:` (visual surface) or `execution impossible:` (terminal surface) 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.
+Every finding cites its evidence. "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 error says nothing useful" means nothing unless you name the transcript step that shows it: baseline vs. post-change, which command, which step number. The composites and transcripts 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."
+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, every transcript gets the terminal bar — and say so explicitly in your findings: "no baseline; judged on the rubric alone."

package/lib/AGENTS.md

@@ -21,6 +21,7 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `append-ooda-step.js` — deterministic writer for the OODA report log (2026-09-14, attempt identity 2026-09-15): `node append-ooda-step.js --log <path> --attempt <id> --step <n> --action <a> --exit <code> [--args <json>] [--screenshot <path>] [--observation <text>]` appends one JSON line to `<phase-dir>/ooda-log.jsonl` (`{step, attempt, action, args, exit, screenshot|null, observation}`). `--attempt` is required; steps must be strictly monotonic within an attempt (a rerun is a new attempt at step 1 — attempts accumulate, never overwrite). Actions: browser (`aria|shot|click|scroll|type`) and image (`crop|zoom|label|nup|compose` — the last five log evidence derivatives made with `lib/edit-image.py` / `lib/render-html.js`; frame-producing actions require `--screenshot`). Corrupt logs or sequence gaps fail loudly (exit 2). No wall-clock reads, no randomness.
 - `write-ooda-verdict.js` — deterministic writer for the OODA terminal verdict (2026-09-14, append-only ledger 2026-09-15): `node write-ooda-verdict.js --dir <phase-dir> --attempt <id> --verdict <PASS|FAIL|NOT_POSSIBLE> --summary <text> --expected <text> --actual <text> --missing <json-array> [--reason <text>]` writes `<phase-dir>/verdict.json` (the latest verdict) and appends one JSON line to `<phase-dir>/verdicts.jsonl` — the append-only ledger: every attempt's verdict is preserved with a mechanical `seq`, never overwritten; corrupt or non-contiguous ledgers fail loudly. `--reason` is REQUIRED and must be non-empty for `FAIL` and `NOT_POSSIBLE` — a reason-less negative verdict fails with exit 2 before anything is written (2026-09-15). Exit 2 on bad input. See `docs/ooda-report.md`.
 - `read-ooda-verdict.js` — deterministic cross-checker for the OODA terminal verdict (2026-09-15): `node read-ooda-verdict.js --dir <phase-dir> --expect <PASS|FAIL>` reads `<dir>/verdict.json`, prints one JSON line to stdout, exits 0 with `{ok:true, verdict, reason, summary, expected, actual, attempt}` when the record agrees with the prose expectation and a FAIL carries a non-empty reason, or exits 2 with `{ok:false, code}` — `missing|corrupt|contradiction|no_reason`. No wall-clock reads, no randomness. The bugfix QA closeout runs it against the prose `VERDICT:` line before any rework routing: a failed cross-check records the phase as failed for retry, never routes to rework.
+- `ux-doctrine.js` — UX-surface doctrine page resolution (2026-09-17): the canonical map from `environment_type` to the crew's shared UX bar (`artifact` → `docs/artifact-ux.md`, `terminal` → `docs/terminal-ux.md`; null/unknown → no page). Pure and deterministic: `doctrinePage(env)`, `doctrinePath(crewHome, env)`, `doctrinePageExists(crewHome, env)`; CLI `--page <env>` / `--path <crewHome> <env>`. Workflows mirror the map inline (one line — the workflow runtime's relative-import support is unverified) and tests pin the mirror against this file.
 - `serve-artifact.js` — local server for a built TS space for experiential QA (2026-09-14): serves `<space-dir>/client/dist` statically and dispatches POST `*/actions` to the compiled server actions with a locally-built Ctx. Prints `READY port=<n>` then serves until killed. Read-only w.r.t. the space directory. Fidelity: the served client and action handlers are the artifact's own built code; the Ctx is locally built (privileged handlers run from the space's own `server/dist/privileged.js` when present; blobs are stored in a per-run temp dir and served back at `/__blobs/<key>`); environment is inherited from the caller. It is not the hosted runtime — tasks that cannot be judged under it must report `NOT POSSIBLE: <reason>`.
 - `readback-disk.js` — deterministic publish content sensor (2026-09-16): reads the on-disk tree the artifact is built/served from and emits the machine-readable findings block (`FILE:`/`ADDED:`/`REMOVED:`/`END_FILE`) that `verify-publish.js` judges. The primary sensor — the LLM-inspector path (`build-readback-request.js`) is manual-fallback only since `artifact_inspect` was removed by the platform 2026-09-14.
 - `build-readback-request.js` — builds the LLM-inspector read-back `verbatim_request` from the merge commit's diff (2026-09-14): carries the merged diff as the expected change and asks for an independent read of the artifact's actual source. Retained as the manual fallback; the deterministic `readback-disk.js` is the primary sensor.

package/lib/append-ooda-step.js

@@ -8,7 +8,7 @@
 // Usage:
 //   node append-ooda-step.js --log <path> --attempt <id> --step <n>
 //     --action <a> --exit <code>
-//     [--args <json>] [--screenshot <path>] [--observation <text>] [--ts <iso>]
+//     [--args <json>] [--screenshot <path>] [--transcript <path>] [--observation <text>] [--ts <iso>]
 //
 // --attempt is the attempt/run identity (e.g. "1", "2" for successive QA
 // loops; "repro-1" for a reproduce run). Steps are strictly monotonic PER
@@ -21,11 +21,17 @@
 // tools: crop, zoom, label, nup (edit-image.py) and compose (render-html.js).
 // Every action that produces a frame must carry --screenshot; a captured
 // frame that is not logged is invisible to everyone after the agent.
+// The terminal action (the terminal-surface driver: one CLI invocation per
+// step) must carry --transcript — the archived stdout/stderr/exit-code
+// transcript of that invocation; an unlogged transcript is invisible to
+// everyone after the agent. Screenshots are never invented for terminal
+// work: passing --screenshot with --action terminal fails loudly.
 //
 // The log is <phase-dir>/ooda-log.jsonl, one object per line:
-//   {step, attempt, action, args, exit, screenshot|null, observation, ts?}
-// Together with the archived screenshots and verdicts.jsonl, the log is the
-// task's OODA report — the complete experiential record of the session.
+//   {step, attempt, action, args, exit, screenshot|null, transcript|null, observation, ts?}
+// Together with the archived screenshots/transcripts and verdicts.jsonl,
+// the log is the task's OODA report — the complete experiential record of
+// the session.
 //
 // Exit 0 on success, 2 on bad input. Determinism: no wall-clock reads, no
 // randomness; ts comes only from --ts (the agent's own clock) and is omitted
@@ -38,11 +44,15 @@ const { dirname, resolve } = require("node:path");
 const ACTIONS = {
   aria: 1, shot: 1, click: 1, scroll: 1, type: 1,
   crop: 1, zoom: 1, label: 1, nup: 1, compose: 1,
+  terminal: 1,
 };
 
 // Actions that produce a frame the agent must have looked at.
 const FRAME_ACTIONS = { shot: 1, crop: 1, zoom: 1, label: 1, nup: 1, compose: 1 };
 
+// Actions that produce a transcript the agent must have read.
+const TRANSCRIPT_ACTIONS = { terminal: 1 };
+
 function fail(msg) {
   process.stdout.write(JSON.stringify({ ok: false, error: msg }) + "\n");
   process.exit(2);
@@ -59,6 +69,7 @@ function parseArgs(argv) {
     else if (a === "--exit") out.exit = argv[++i];
     else if (a === "--args") out.args = argv[++i];
     else if (a === "--screenshot") out.screenshot = argv[++i];
+    else if (a === "--transcript") out.transcript = argv[++i];
     else if (a === "--observation") out.observation = argv[++i];
     else if (a === "--ts") out.ts = argv[++i];
     else fail("unknown flag: " + a);
@@ -112,7 +123,7 @@ function main() {
     fail("missing --attempt <id> (the attempt/run identity, e.g. \"1\", \"2\", \"repro-1\")");
   }
   if (args.step === undefined) fail("missing --step <n>");
-  if (!args.action) fail("missing --action <aria|shot|click|scroll|type|crop|zoom|label|nup|compose>");
+  if (!args.action) fail("missing --action <aria|shot|click|scroll|type|crop|zoom|label|nup|compose|terminal>");
   if (args.exit === undefined) fail("missing --exit <code>");
 
   const attempt = String(args.attempt).trim();
@@ -140,6 +151,14 @@ function main() {
     fail("--action " + args.action + " produces a frame: --screenshot is required (log the frame you looked at)");
   }
 
+  if (TRANSCRIPT_ACTIONS[args.action] && !args.transcript) {
+    fail("--action " + args.action + " produces a transcript: --transcript is required (log the transcript you read)");
+  }
+
+  if (args.action === "terminal" && args.screenshot) {
+    fail("--action terminal never takes --screenshot: screenshots are not evidence for terminal work");
+  }
+
   const logPath = resolve(args.log);
   mkdirSync(dirname(logPath), { recursive: true });
 
@@ -156,6 +175,7 @@ function main() {
     args: parsedArgs,
     exit: exit,
     screenshot: args.screenshot ? resolve(args.screenshot) : null,
+    transcript: args.transcript ? resolve(args.transcript) : null,
     observation: args.observation || "",
   };
   if (args.ts) entry.ts = args.ts;