humanish 0.105.0 → 0.106.0

package/docs/contracts/study-analysis.md

@@ -57,7 +57,7 @@ humanish analyze --run latest --provider codex --dry-run --json
 humanish analyze --run latest --provider codex --json
 ```
 
-This branch is qualified on Linux x64 with Codex CLI `0.154.0`, a file-backed
+This branch is qualified on Linux x64 and Apple Silicon macOS with the Codex CLI releases listed for each host in `src/actors/codex/qualified-versions.ts`, a file-backed
 ChatGPT account login, and `gpt-6-astra` with low reasoning effort. The participant conversation
 is never reused. Selected text and screenshots still go to remote inference;
 this is account authentication, not local inference. No API-key, alternate model
@@ -134,7 +134,7 @@ New packets declare `captureVersion: 2`, bound into their input digest. They
 include captures attached to `screenshot` and scripted `ui_action` events,
 preserving the original action IDs and evidence basis. Error notices that refer
 to an earlier capture retain that context without creating another frame.
-Scripted lanes use their recorded `ui.intent` goal when no participant assignment
+Scripted participants use their recorded `ui.intent` goal when no participant assignment
 exists. Missing assignments and declared captures without supported trace
 references are explicit omissions. Artifacts without `captureVersion` continue
 to validate against the original capture mapping; previously saved selections

package/docs/contracts/study-costs.md

@@ -31,18 +31,18 @@ Observer and terminal run summaries label this narrower scope.
 The new `costs` object appears on totals, each lab and each day. `costsByRun`
 contains the same accounting per selected run with stable warning codes.
 
-| Field | Meaning |
-| --- | --- |
-| `estimatedTotalUsd` | Sum of the retained run and analysis estimates |
-| `runEstimatedUsd` | Participant/desktop estimate; may be a known subtotal |
-| `analysisEstimatedUsd` | Sum of all distinct retained analysis estimates |
-| `incompleteRunEstimates` | Runs with partial or unknown participant/desktop accounting |
-| `analysisAttempts` | Distinct retained execution IDs, including unresolved claims |
-| `analysisDispatchedAttempts` | Attempts whose final accounting confirms transport |
-| `analysisNotDispatchedAttempts` | Attempts whose final accounting confirms no transport |
-| `analysisUnpricedAttempts` | Dispatched or potentially dispatched attempts without a complete price |
-| `analysisUnresolvedAttempts` | Claims without usable final accounting; a subset of unpriced attempts |
-| `analysisHistoryUncertainRuns` | Runs with absent, legacy report-only, unreadable or conflicting history |
+| Field                           | Meaning                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------- |
+| `estimatedTotalUsd`             | Sum of the retained run and analysis estimates                          |
+| `runEstimatedUsd`               | Participant/desktop estimate; may be a known subtotal                   |
+| `analysisEstimatedUsd`          | Sum of all distinct retained analysis estimates                         |
+| `incompleteRunEstimates`        | Runs with partial or unknown participant/desktop accounting             |
+| `analysisAttempts`              | Distinct retained execution IDs, including unresolved claims            |
+| `analysisDispatchedAttempts`    | Attempts whose final accounting confirms transport                      |
+| `analysisNotDispatchedAttempts` | Attempts whose final accounting confirms no transport                   |
+| `analysisUnpricedAttempts`      | Dispatched or potentially dispatched attempts without a complete price  |
+| `analysisUnresolvedAttempts`    | Claims without usable final accounting; a subset of unpriced attempts   |
+| `analysisHistoryUncertainRuns`  | Runs with absent, legacy report-only, unreadable or conflicting history |
 
 The three amount fields are `null` when nothing in that component has an
 estimate. Known zero is retained only when supported: for example, final

package/docs/decisions/0001-run-bundle-is-the-source-of-truth.md

@@ -0,0 +1,36 @@
+# 0001: The run bundle is the source of truth
+
+Accepted.
+
+## Context
+
+Several surfaces read a finished or running study: the Observer, `humanish tui`, `serve`,
+`export`, feedback drafts and study analysis. Each of them wants a smaller, faster view than the
+full bundle, and a view that can drift from the evidence would let a surface show a result the
+evidence does not support.
+
+## Decision
+
+`.humanish/runs/<runId>/run.json` (`humanish.run-bundle.v1`) and the artifact files it lists are
+the evidence. Everything else is a projection rebuilt from them:
+
+- `observer/observer-data.json` is regenerated by `export` and by every Observer render.
+- `status.json` (`humanish.run-status.v1`) is a liveness index. When it disagrees with `run.json`,
+  `run.json` wins. `verify` reads it, with the sandbox and reclaim receipts, only to say a run
+  did not finish (`RUN_NOT_FINISHED`). That warning changes no check and no grade.
+- Analysis findings cite turns and artifacts in the bundle.
+
+## Consequences
+
+- Bundle schema fields are a public contract. `docs/contracts/run-bundle.md` documents them, and
+  renaming one needs a new schema version.
+- A projection can be deleted and rebuilt without losing evidence.
+- Surfaces cannot add facts of their own; a new fact goes into the bundle first.
+
+## Enforced by
+
+- `verifyRun` in `src/verify/verify.ts`, which grades only the bundle and its artifacts. It reads
+  `status.json` only for the `RUN_NOT_FINISHED` warning (`src/verify/liveness.ts`), which never
+  changes `ok`. `tests/verify/run-not-finished.test.ts` checks that the result is the same, apart
+  from that warning, when `status.json` contradicts the bundle or is gone.
+- `tests/observer/data-contract.test.ts` for the Observer projection.

package/docs/decisions/0002-observer-is-one-self-contained-file.md

@@ -0,0 +1,30 @@
+# 0002: The Observer is one self-contained HTML file
+
+Accepted.
+
+## Context
+
+Run bundles are archived, exported and shared, and people open them later, offline or from a
+static host. A viewer that needs a running server, a CDN or a network call stops working in
+exactly those cases.
+
+## Decision
+
+The `observer/` workspace builds with Vite into a single HTML file with fonts inlined and no
+network references. The root build copies it to `dist/observer-app.html`. `renderObserverHtml`
+is the one path every surface (observe, watch, serve, labs) uses; it injects the run's
+`humanish.observer-data.v1` snapshot into that file. There is no second renderer and no feature
+flag; rolling back means pinning an older package version.
+
+## Consequences
+
+- An Observer page opens from disk, and an exported bundle carries its own viewer.
+- Every dependency the Observer adds ships inside each rendered page, so page weight is a cost
+  reviewers check.
+- Live views (`watch`, `serve`) use the same file and poll for new snapshots.
+
+## Enforced by
+
+- The observer workspace tests (single file, inlined fonts, no network references).
+- `tests/observer/artifact.test.ts` for the artifact path and the cold auto-build.
+- `tests/observer/data-contract.test.ts` for the data schema.

package/docs/decisions/0003-contained-paths-and-cleanup-authority.md

@@ -0,0 +1,35 @@
+# 0003: Managed paths bind to physical identities; cleanup uses create-time receipts
+
+Accepted in 0.15.1 (#280), extended in 0.36.0 (`humanish reclaim`).
+
+## Context
+
+Before 0.15.1, run storage and output paths followed whatever the filesystem said at write time,
+so a link or a traversal-shaped id could redirect a write outside `.humanish/`. `humanish cleanup`
+also read provider ids from `run.json`, a file that can be edited or shared, and acted on them.
+Separately, an account-wide provider operation once destroyed unrelated infrastructure.
+
+## Decision
+
+- Managed run, Observer, feedback, lab, actor-output, git-metadata and source-archive paths bind
+  to validated physical filesystem identities. Traversal-shaped ids, unsafe links, special files
+  and root retargeting are rejected before any write.
+- Provider ids in `run.json` are evidence. Nothing mutates a provider resource because of them.
+- The process that creates a resource cleans it up with the handle it holds. After a crash,
+  `humanish reclaim` kills sandboxes by the exact ids journaled at create time in the run's
+  `sandbox-receipts.ndjson`, and reports each outcome.
+- No route lists an account's resources to find or verify its own.
+
+## Consequences
+
+- A shared operator key is safe to use: humanish reaches only resources it created.
+- An exported bundle does not carry cleanup authority; `export` omits the receipt journal.
+- Unverified git metadata (arbitrary `gitdir:` redirects) is reported as unavailable instead of
+  followed.
+
+## Enforced by
+
+- `src/run/paths.ts` and `src/run/contained-output.ts`, with `tests/run/path-containment.test.ts`.
+- `src/run/git-workspace.ts`, with `tests/run/git-state.test.ts`.
+- `src/run/reclaim.ts`, with `tests/run/reclaim.test.ts`.
+- Invariant 7 in [invariants and defaults](../principles/invariants-and-defaults.md).

package/docs/decisions/0004-participant-desktops-stay-in-the-route.md

@@ -0,0 +1,31 @@
+# 0004: Participant desktops stay in the computer-use route
+
+Accepted.
+
+## Context
+
+A participant runs on a `ParticipantDesktop`: the hosted E2B desktop, the local VM, or the
+in-process executor. The structure review planned to move the interface to `src/substrates/`
+beside the provider primitives. A later review graded the unmoved interface as a deviation from
+that plan.
+
+## Decision
+
+The interface and its three implementations stay in `src/routes/computer-use/`. Each
+implementation combines provider primitives from `src/substrates/` (the E2B sandbox, local VMs,
+the `Shell`) with route concerns: subject provisioning, comms and the participant plan. Moving
+only the interface to `src/substrates/` would split one concept across two folders, so
+`src/substrates/` holds only the primitives.
+
+## Consequences
+
+- A reader finds the desktop contract and its implementations in one folder, beside the runner
+  that calls them.
+- `src/substrates/` stays free of route types; it does not import from `src/routes/`.
+- Shared-world seats reach the same desktops through computer-use's participant runner.
+
+## Enforced by
+
+- No check enforces the placement. The interface's doc comment in
+  `src/routes/computer-use/participant-desktop.ts` states it, and the computer-use row of
+  ARCHITECTURE.md's code map links here.

package/docs/decisions/README.md

@@ -0,0 +1,16 @@
+# Decisions
+
+Short records of decisions that shape the codebase. Each states the context, the decision, what
+it costs, and the code or test that enforces it. A new record is warranted when a choice would
+otherwise be re-litigated or explained again in a long comment.
+
+| #                                                      | Decision                                                                     |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| [0001](0001-run-bundle-is-the-source-of-truth.md)      | The run bundle is the source of truth                                        |
+| [0002](0002-observer-is-one-self-contained-file.md)    | The Observer is one self-contained HTML file                                 |
+| [0003](0003-contained-paths-and-cleanup-authority.md)  | Managed paths bind to physical identities; cleanup uses create-time receipts |
+| [0004](0004-participant-desktops-stay-in-the-route.md) | Participant desktops stay in the computer-use route                          |
+
+Safety rules and route defaults (separate worlds, all declared participants running at once, local
+full-fidelity screenshots, dry run by default, loopback serving) are recorded with their
+overrides in [invariants and defaults](../principles/invariants-and-defaults.md).

package/docs/goals/current.md

@@ -1,31 +1,7 @@
 # Current Goals
 
-Status date: 2026-09-28. Source baseline: `0.105.0`.
-
-This page guides work on current source. Version `0.105.0` preserves optional rich
-persona backgrounds, diagnoses dropped context and retains the compiled persona
-brief for inspection in Participants; see the
-[release note](../release/0.105.0-participant-backgrounds.md).
-Version `0.104.3` exposes the documented
-loopback SMTP catch for operator-hosted apps and fails startup if its port is busy; see the
-[release note](../release/0.104.3-local-smtp-catch.md). Version `0.104.2` preserves video
-capture timestamp precision through encoding; see its
-[release note](../release/0.104.2-recording-timestamps.md). Version `0.104.1` bounds the recording
-mix buffer to remove the reproduced initial video gap; see its
-[release note](../release/0.104.1-recording-startup.md).
-Version `0.104.0` connects local browser
-participants to captured email inboxes; see its
-[release note](../release/0.104.0-local-captured-inboxes.md).
-Version `0.103.2` retains adjacent ending views for outcome review within the
-existing capture budget; see its
-[release note](../release/0.103.2-analysis-ending-context.md).
-Version `0.103.1` fixes capture
-redistribution after image-byte reservations; its
-[release note](../release/0.103.1-analysis-capture-allocation.md) describes the
-bounded allocation correction, separate from the 0.103.2 ending-context fix.
-Version `0.103.0` adds optional desktop
-video and audio; its [release note](../release/0.103.0-desktop-recording.md)
-records the supported routes, playback behavior and local-only evidence limits.
+This page guides work on current source. [CHANGELOG.md](../../CHANGELOG.md) lists what each
+version changed.
 The [September 9 history](https://github.com/danielgwilson/humanish/blob/main/docs/goals/current-history-2026-09-09.md)
 preserves the former status log; its queues do not supersede this page.
 
@@ -110,31 +86,31 @@ requires decision-equivalent retained evidence and a real deletion branch.
 No first-party deletion branch has met that gate. Public demonstrations do not
 substitute for it.
 
-## Current Program Truth (source `0.105.0`)
-
-| Surface | Available in source | Remaining boundary |
-| --- | --- | --- |
-| Study authoring | YAML labs, lane/roster composition, model settings and study/per-lane caps | Route support varies; declarations are not promises of engine parity |
-| Actors | Seven first-party descriptors; computer-use, scripted-browser and terminal-product dispatch | No supported public out-of-tree actor-registration API |
-| Subjects | `this-repo`, `clone`, `app-url`, `local-app`, `terminal-product`, `desktop-cli`, `local-tree` | `this-repo` is dry-run-only; `local-app` needs a caller-supplied executor/provider |
-| Task protocol | Hidden criteria and per-task outcomes on supported per-lane CUA paths, including local-agent and desktop-cli | Shared-world, terminal-product, scripted and synthetic routes reject `tasks` before execution |
-| Shared state | Sequential and concurrent single-origin shared-world studies with retained evidence | Multi-origin implementation remains gated; concurrent state change does not establish per-action causation |
-| Observer | Live/recorded views, shared grid and participant playback, participant assignments, action-specific links, saved moments, zoom, comparison and phone-width review | Sparse captures cannot prove every action's effect; visual comparison alone is not a controlled experiment |
-| Review and feedback | Verification grades, feedback drafts, portable HTML, redacted bundle derivatives and computer-use completion-source labels | Sharing requires the appropriate grade; participant reports and condition matches still need task adjudication |
-| Study findings | Default post-run analysis on supported live routes with a separate disclosed $3 admission estimate limit and opt-out; explicit `analyze`, fairer evidence selection, concern review and versioned findings with exact source links; explicit restricted Codex account analysis on qualified Linux x64 and Apple Silicon Mac profiles | Account dollars/output-token caps are unavailable; Keychain/other CLI profiles are unqualified. Model interpretation needs review; selection limits coverage; opening Observer never dispatches analysis |
-| TUI and serving | Detached starts, run stopping, reclamation, Observer attachment, loopback serving, run library and AgentMail setup, authentication and lab configuration | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups |
-| Off-app communication | Recipient-scoped local capture and fresh real AgentMail receiving, supported inline raster images, bounded collection and host-owned recovery | Real mail uses isolated participant surfaces and remains local-only for publication. Hosted mail/model processing, bounded fidelity and interrupted-run recovery are explicit; real receiving through local-agent, borrowed inboxes and SMS are unsupported |
-| Local browsers | Shared study loop on Linux x64/Docker/KVM and M3-or-newer Mac/Lima; pinned runtime download, Codex account participants and automatic analysis | Explicit local labs support recipient-scoped captured inboxes; real receiving on local desktops, automatic onboarding, larger cohorts and sleep/wake remain unqualified |
-| Mobile and media | Hosted viewport/emulation, desktop geometry checks, bounded dwell and declared camera feed; optional camera and speech passed two-person Linux and Mac conversations with validated analysis; hosted audio-only uses the same worker; optional screen/mixed-audio MP4 capture shipped with Linux/E2B and Mac acceptance | Hosted camera+speech is unsupported; English recognition and robotic voice have fidelity limits; raw AV recording is shipped but local-only, excluded from HTML export and analysis (screenshots/text only); the reproduced recording-mix startup video gap is corrected; variable guest capture stalls, initial device/transport availability and cold audio-source delivery remain limits (#854); forced TURN, larger-cohort capacity, physical-device and touch fidelity remain unqualified |
+## Current Program Truth
+
+| Surface               | Available in source                                                                                                                                                                                                                                                                                                                  | Remaining boundary                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Study authoring       | YAML labs, `lanes[]`/roster composition, model settings and study/per-participant caps                                                                                                                                                                                                                                               | Route support varies; declarations are not promises of engine parity                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Actors                | Seven first-party descriptors; computer-use, scripted-browser and terminal-product dispatch                                                                                                                                                                                                                                          | No supported public out-of-tree actor-registration API                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Subjects              | `this-repo`, `clone`, `app-url`, `local-app`, `terminal-product`, `desktop-cli`, `local-tree`                                                                                                                                                                                                                                        | `this-repo` is dry-run-only; `local-app` needs a caller-supplied executor/provider                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Task protocol         | Hidden criteria and per-task outcomes on supported separate-world CUA paths, including local-agent and desktop-cli                                                                                                                                                                                                                   | Shared-world, terminal-product, scripted and synthetic routes reject `tasks` before execution                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Shared state          | Concurrent single-origin shared-world studies with retained evidence (the sequential route was removed in 0.106.0)                                                                                                                                                                                                                   | Multi-origin implementation remains gated; concurrent state change does not establish per-action causation                                                                                                                                                                                                                                                                                                                                                                                     |
+| Observer              | Live/recorded views, shared grid and participant playback, participant assignments, action-specific links, saved moments, zoom, comparison and phone-width review                                                                                                                                                                    | Sparse captures cannot prove every action's effect; visual comparison alone is not a controlled experiment                                                                                                                                                                                                                                                                                                                                                                                     |
+| Review and feedback   | Verification grades, feedback drafts, portable HTML, redacted bundle derivatives and computer-use completion-source labels                                                                                                                                                                                                           | Sharing requires the appropriate grade; participant reports and condition matches still need task adjudication                                                                                                                                                                                                                                                                                                                                                                                 |
+| Study findings        | Default post-run analysis on supported live routes with a separate disclosed $3 admission estimate limit and opt-out; explicit `analyze`, fairer evidence selection, concern review and versioned findings with exact source links; explicit restricted Codex account analysis on qualified Linux x64 and Apple Silicon Mac profiles | Account dollars/output-token caps are unavailable; Keychain/other CLI profiles are unqualified. Model interpretation needs review; selection limits coverage; opening Observer never dispatches analysis                                                                                                                                                                                                                                                                                       |
+| TUI and serving       | Detached starts, run stopping, reclamation, Observer attachment, loopback serving, run library and AgentMail setup, authentication and lab configuration                                                                                                                                                                             | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups                                                                                                                                                                                                                                                                                                                                                                                |
+| Off-app communication | Recipient-scoped local capture and fresh real AgentMail receiving, supported inline raster images, bounded collection and host-owned recovery                                                                                                                                                                                        | Real mail uses isolated participant surfaces and remains local-only for publication. Hosted mail/model processing, bounded fidelity and interrupted-run recovery are explicit; real receiving through local-agent, borrowed inboxes and SMS are unsupported                                                                                                                                                                                                                                    |
+| Local browsers        | Shared study loop on Linux x64/Docker/KVM and M3-or-newer Mac/Lima; pinned runtime download, Codex account participants and automatic analysis                                                                                                                                                                                       | Explicit local labs support recipient-scoped captured inboxes; real receiving on local desktops, automatic onboarding, larger cohorts and sleep/wake remain unqualified                                                                                                                                                                                                                                                                                                                        |
+| Mobile and media      | Hosted viewport/emulation, desktop geometry checks, bounded dwell and declared camera feed; optional camera and speech passed two-person Linux and Mac conversations with validated analysis; hosted audio-only uses the same worker; optional screen/mixed-audio MP4 capture shipped with Linux/E2B and Mac acceptance              | Hosted camera+speech is unsupported; English recognition and robotic voice have fidelity limits; raw AV recording is shipped but local-only, excluded from HTML export and analysis (screenshots/text only); the reproduced recording-mix startup video gap is corrected; variable guest capture stalls, initial device/transport availability and cold audio-source delivery remain limits (#854); forced TURN, larger-cohort capacity, physical-device and touch fidelity remain unqualified |
 
 Use the [task support matrix](../architecture/task-protocol-support.md),
-[actor registry](https://github.com/danielgwilson/humanish/blob/main/src/actor-registry.ts)
+[actor registry](https://github.com/danielgwilson/humanish/blob/main/src/actors/registry.ts)
 and [CLI reference](https://humanish.dev/docs/cli) when choosing a concrete path.
 Source and tests establish observed behavior. Resolve conflicts with requirements
 explicitly; neither stale status prose nor a passing test makes a bug correct.
 
 The library-assisted `local-app` route now includes a
-[runnable npm example](../architecture/examples/state-driven-local-app/README.md).
+[runnable npm example](../../examples/participant/README.md).
 Its deterministic provider demonstrates the integration with a real loopback
 app; it does not establish persona effectiveness or independent adoption.
 
@@ -142,8 +118,7 @@ The [local browser runtime](../architecture/local-browser-runtime.md)
 runs isolated Linux browser participants through the same scheduler, recordings
 and automatic analysis as hosted studies. It uses Docker-owned resources and
 ordinary TAP/NAT networking. Continue managed-local work from this complete study
-path; the earlier offline owner/service qualification experiments are historical
-fixtures, not an installation architecture or a prerequisite queue. Explicit
+path. Explicit
 Linux local labs now use the installed CLI/TUI, with a verified runtime download
 before the first live run. Mac browser support is also shipped. Captured inbox integration reuses the existing
 catch and evidence contracts; local provider-backed receiving remains unsupported.
@@ -154,9 +129,6 @@ retain their behavior.
 
 ## Gates And Deferred Work
 
-- Live OSS meta-lab execution remains disabled until repository-derived
-  instructions have an isolated credential boundary. Its dry-run and separate
-  disposable smoke harness do not open that gate.
 - [Multi-origin shared-world work](https://github.com/danielgwilson/humanish/issues/239)
   needs a real adopter's cross-origin requirement and a reviewed implementation
   packet. It has a ratified core-design direction, but the implementation gate is still closed.
@@ -193,7 +165,7 @@ and the [public-readiness standard](../release/public-readiness-standard.md).
 
 ## Proof Before Shipping
 
-Use the [verification guidance](../../AGENTS.md#verification): check the changed
+Use the [verification guidance](../principles/engineering.md#verification): check the changed
 behavior and material risks, then stop unless new evidence warrants more work.
 Required CI remains the merge gate. For a release, run the full release gates
 from a clean contributor worktree:

package/docs/principles/actor-fidelity.md

@@ -1,8 +1,7 @@
 # Actor Fidelity: whose behavior is this evidence about?
 
 Status: research digest + design position. Sources are public papers and open-source
-harnesses; every claim below carries its citation so it can be argued with rather
-than inherited.
+harnesses; every claim below carries its citation so a reader can check it.
 
 ## The question
 
@@ -12,12 +11,12 @@ the browser address bar to get past a step. The run finished green.
 Whether that is a defect depends entirely on a question the harness never asked:
 **who is this study's user?**
 
-- If the declared users are **people**, it is a defect — and a costly one. The actor
+- If the declared users are **people**, it is a costly defect. The actor
   routed around the friction the study existed to measure, so a passing run proves
   nothing about the human experience. Worse, it is silent: nothing in the bundle
   distinguishes that run from one where a person clicked through.
-- If the declared users are **agents** — as they are for an agent-facing CLI, API, or
-  MCP surface — the same act is faithful. It is the user population behaving normally,
+- If the declared users are **agents**, as they are for an agent-facing CLI, API, or
+  MCP surface, the same act is faithful. It is the user population behaving normally,
   and the fact that the agent had to reach for that affordance is itself a product
   finding about how legible the surface is to its actual users.
 
@@ -31,9 +30,9 @@ operable.
 ### Direct URL navigation is a human affordance
 
 WebLINX built its action space from 2,337 real human demonstrations; `load(url)`
-appears in 2,324 of them — 99.4%, roughly 1.6 times per session
+appears in 2,324 of them (99.4%, roughly 1.6 times per session)
 ([arXiv 2402.05930](https://arxiv.org/abs/2402.05930)). Treating address-bar
-navigation as non-human would make a human-declared lane *less* faithful, not more.
+navigation as non-human would make a human-declared participant _less_ faithful.
 The anomalous class is script execution and developer tooling, not URL entry.
 BrowserGym already factors these apart: its `nav` subset is exactly
 `{goto, go_back, go_forward}`, separate from everything else
@@ -46,14 +45,14 @@ BrowserGym already factors these apart: its `nav` subset is exactly
 - When a constraint conflicts with the task goal, obedience falls to 9.6–45.8%, and
   models usually do not register the conflict ("Control Illusion").
 - Rule-file effects are largely content-independent: random rules tie with curated
-  ones, and shuffling changes little — measured specifically on agent skills and
-  persona definitions ([arXiv 2604.11088](https://arxiv.org/abs/2604.11088)). A
+  ones, and shuffling changes little. This was measured specifically on agent skills
+  and persona definitions ([arXiv 2604.11088](https://arxiv.org/abs/2604.11088)). A
   modality rule can therefore appear to work while doing nothing.
-- Persona adherence decays over a long trajectory rather than holding
+- Persona adherence decays over a long trajectory
   ([arXiv 2512.12775](https://arxiv.org/abs/2512.12775)).
 
-The one large-scale prompt-level modality constraint in the literature —
-Online-Mind2Web instructing agents not to use search — was not trusted by its own
+The one large-scale prompt-level modality constraint in the literature,
+Online-Mind2Web instructing agents not to use search, was not trusted by its own
 authors, who published the measured constrained-vs-unconstrained delta (26% vs 31%)
 instead of asserting the instruction took effect
 ([arXiv 2504.01382](https://arxiv.org/abs/2504.01382)). That is the discipline this
@@ -67,8 +66,8 @@ measured attempts went the wrong way. A findings-informed realism persona prompt
 lowered overall simulator fidelity (User-Sim Index 70.9 → 64.6) and worsened outcome
 calibration (0.18 → 0.29): "moving some behaviors closer to humans can move others
 further away" ([arXiv 2603.11245](https://arxiv.org/abs/2603.11245)). Explicitly
-licensing persona-faithful failure fixed the *marginal* rate five-fold but left the
-*conditional* structure nearly unchanged — it taught the simulator to disengage
+licensing persona-faithful failure fixed the _marginal_ rate five-fold but left the
+_conditional_ structure nearly unchanged: it taught the simulator to disengage
 uniformly rather than to disengage when a real user would
 ([arXiv 2606.20708](https://arxiv.org/abs/2606.20708)). By contrast, a narrow,
 countable instruction did produce a measured improvement
@@ -81,9 +80,8 @@ criterion to the actor invites optimization of the stated metric. Pre-action
 self-checks are worse than neutral: deliberation before acting degrades constraint
 adherence in most models measured ([arXiv 2505.11423](https://arxiv.org/abs/2505.11423)),
 and chain-of-thought is an unreliable report of what actually drove an action
-([arXiv 2505.05410](https://arxiv.org/abs/2505.05410)) — an actor that takes a
-shortcut and then narrates a plausible justification for it is the expected output,
-not an edge case.
+([arXiv 2505.05410](https://arxiv.org/abs/2505.05410)). An actor that takes a
+shortcut and then narrates a plausible justification for it is the expected output.
 
 What does hold, in the same literature: periodic re-injection of a short persona
 contract (large, cheap, replicated), and grounding a persona in specifics rather
@@ -96,8 +94,8 @@ WebArena's URL evaluator scores on the final page URL, so a single `goto` to the
 reference URL earns full credit ([arXiv 2307.13854](https://arxiv.org/abs/2307.13854)).
 τ-bench states the general form: a state-based reward is necessary but not
 sufficient, since it cannot see whether policy was followed
-([arXiv 2406.12045](https://arxiv.org/abs/2406.12045)). And the gradient is real —
-calling site APIs instead of driving the UI roughly doubles WebArena scores
+([arXiv 2406.12045](https://arxiv.org/abs/2406.12045)). The gradient exists: calling
+site APIs instead of driving the UI roughly doubles WebArena scores
 ([arXiv 2410.16464](https://arxiv.org/abs/2410.16464)). Any harness that scores only
 outcomes should expect actors to find that gradient, and should not be surprised when
 a green run proves nothing.
@@ -108,22 +106,22 @@ a green run proves nothing.
 
 1. **Declared population is a property of a persona, not of a lab.** One study program
    can legitimately run agents and people against the same surface; the comparison
-   between them is a finding, not a contradiction. Prior art runs both populations
+   between them is itself a finding. Prior art runs both populations
    through one instrument and reports the difference
    ([SusBench](https://arxiv.org/abs/2510.11035); MAS-Bench's GUI/shortcut split,
    [arXiv 2509.06477](https://arxiv.org/abs/2509.06477)).
 
 2. **Record which affordance class each action used.** Recording is the layer that
    makes every other claim checkable, including whether the persona prompt worked at
-   all. It is also the only honest answer to a defect whose verdict depends on a
-   declaration the harness cannot verify.
+   all. When a defect's verdict depends on a declaration the harness cannot verify,
+   recording what happened is the claim the harness can support.
 
 3. **Do not bake a verdict.** Whether an affordance invalidates a study is product
    semantics, and product semantics belong to the adopter's scorer
    (`review.scorer.ref`). The harness emits facts; the adopter decides what they mean.
 
 4. **Prompt guidance ships as a nudge whose take-rate is reported, never as the
-   mechanism.** The evidence above is what that sentence is standing on.
+   mechanism.** The evidence above supports it.
 
 5. **Hold simulator settings fixed when estimating a persona effect.** Model and
    reasoning effort influence behavior, so changing them alongside the persona
@@ -138,7 +136,7 @@ a green run proves nothing.
    receipt or adherence. Repeated decision controls can establish a narrow effect;
    correspondence with real people requires relevant human evidence.
 
-6. **Fail closed only on harness integrity, never on product semantics** — a lane that
+6. **Fail closed only on harness integrity, never on product semantics.** A participant that
    cannot report what it did is a broken instrument, which is a different thing from
    an actor that behaved unexpectedly.
 
@@ -146,33 +144,32 @@ a green run proves nothing.
 
 Fidelity here is scoped to **affordance and decision** level: which routes an actor
 took, and whether they belong to the declared population. It is not a claim of
-behavioral realism. At the kinematic level — pointer paths, timing, motor noise — the
+behavioral realism. At the kinematic level (pointer paths, timing, motor noise), the
 gap between agents and people is total and trivially detectable
 ([arXiv 2604.09574](https://arxiv.org/abs/2604.09574)). Any claim beyond the
 affordance/decision level would be dishonest, and this project does not make one.
 
-Two further limits worth stating plainly. Restricting script execution and developer
-tooling for *fidelity* reasons has no precedent — where such restrictions exist
-elsewhere, the stated motive is code-execution safety — so this is new ground rather
-than an inherited convention. And nobody has yet measured whether affordance-class
-recording changes what adopters decide; that is the experiment this layer makes
-possible, not a result it can assume.
+Two further limits apply. Restricting script execution and developer tooling for
+_fidelity_ reasons has no precedent. Where such restrictions exist elsewhere, the stated
+motive is code-execution safety, so this project has no convention to inherit here.
+And nobody has yet measured whether affordance-class recording changes what adopters
+decide. This layer makes that experiment possible; it does not assume the result.
 
 ## Vocabulary
 
 Terms are borrowed rather than coined, so results stay comparable with the
 surrounding literature:
 
-| Term | Source | Meaning here |
-| --- | --- | --- |
-| action space / action set | WebArena, BrowserGym, OSWorld | the set of actions an actor can express |
-| `nav` subset | BrowserGym | `goto`, `go_back`, `go_forward` — direct navigation, a human affordance |
-| naturalistic actions | AndroidWorld | the human-modality subset, contrasted with exposed function-calling APIs |
-| shortcut action | MAS-Bench | a non-UI route to the same outcome (API, deep link, script) |
-| algorithmic fidelity | Argyle et al., *Out of One, Many* | how well a conditioned model emulates a specific population |
-| Agent Experience (AX) | Biilmann (Netlify) | the experience of a product whose users are agents |
+| Term                      | Source                            | Meaning here                                                             |
+| ------------------------- | --------------------------------- | ------------------------------------------------------------------------ |
+| action space / action set | WebArena, BrowserGym, OSWorld     | the set of actions an actor can express                                  |
+| `nav` subset              | BrowserGym                        | `goto`, `go_back`, `go_forward`: direct navigation, a human affordance   |
+| naturalistic actions      | AndroidWorld                      | the human-modality subset, contrasted with exposed function-calling APIs |
+| shortcut action           | MAS-Bench                         | a non-UI route to the same outcome (API, deep link, script)              |
+| algorithmic fidelity      | Argyle et al., _Out of One, Many_ | how well a conditioned model emulates a specific population              |
+| Agent Experience (AX)     | Biilmann (Netlify)                | the experience of a product whose users are agents                       |
 
 Three collisions to avoid: "agent usability testing" already means an agent
-*simulating* a human, which is the opposite of the agent-population case; `cheat()` in
+_simulating_ a human, which is the opposite of the agent-population case; `cheat()` in
 BrowserGym means the reference solution, not misbehavior; and "reward hacking" refers
 to attacking a grader, which is a different failure from routing around a UI.

package/docs/principles/engineering.md

@@ -0,0 +1,81 @@
+# Engineering principles
+
+These are the judgment calls behind the rules in [AGENTS.md](../../AGENTS.md). Read them
+before adding a service, mode, dependency or new boundary.
+
+## Engineering Judgment
+
+Public OSS quality includes clear, idiomatic code, straightforward setup and
+low maintenance cost, alongside correctness, privacy and security.
+
+- **KISS:** use familiar patterns, existing repo code and maintained upstream
+  components. Judge total complexity: dependencies, services, configuration,
+  deployment and failure handling as well as source lines.
+- **YAGNI:** implement the requested behavior. Explicit near-term requirements
+  constrain today's design: defer their implementation, not compatibility. Avoid
+  choices that force an overhaul to deliver an already-required follow-up.
+  Speculative future uses do not justify frameworks.
+- **DRY:** share policy and behavior that must stay consistent. Similar-looking
+  code alone does not justify an abstraction; modest duplication can be clearer.
+- Deliver one working end-to-end path early, then harden it. An experiment is
+  not a release, and its qualification fixture need not become the architecture.
+- Before adding a service, protocol, mode or framework, explain the concrete
+  need and why an existing approach is insufficient. A sentence in the current
+  plan or PR is enough; routine changes need no separate design document.
+- Apply security controls at the relevant trust boundary for a credible failure
+  mode. Reuse established controls; public visibility alone does not justify
+  new runtime restrictions. Simplicity does not waive isolation or authorization.
+- Prefer removing an unnecessary mechanism to adding more documentation and
+  tests around it. Existing work is not a reason to retain a poor design.
+- If prerequisites keep expanding without an end-to-end result, reassess and
+  narrow the approach. Surface material scope or architecture changes promptly;
+  do not repeatedly ask permission for ordinary work already authorized.
+- Keep code, comments and updates concise. Explain surprising decisions and
+  tradeoffs; avoid redundant narration, invented jargon and repeated history.
+
+## Architecture
+
+- Product-specific routes, ports, scenarios and vocabulary belong in adapters.
+  Core owns shared execution, lifecycle, evidence and review behavior. Preserve
+  common interfaces across providers; avoid parallel copies of the study loop.
+- CLI results must be truthful. Reject unsupported execution before side effects;
+  preserve useful evidence and explain recoverable interruptions.
+- Documented bundle schemas and supported artifact paths are contracts.
+  Experimental receipts and internal diagnostics are not automatically APIs.
+- Tests establish observed behavior, not necessarily intended behavior. Resolve
+  code/test/doc conflicts against the current requirement and report the mismatch;
+  neither stale prose nor a passing test makes a bug correct.
+
+## Working And Resuming
+
+- Read the [ramp](../ramp/README.md), current task and relevant component
+  instructions. Read detailed contracts for the boundary being changed, not every
+  historical roadmap. Consult the invariants for security/evidence changes and the
+  release procedure before publishing.
+- Keep `main` clean; use a scoped worktree/branch. Make reviewable commits.
+- Existing explicit authority governs directly assigned work. Machine-readiness
+  metadata gates automated queue pickup, not every interactive task. Do not
+  treat an old plan as authorization to resume paused or rejected work.
+- When granted autonomous shipping authority, push, open the PR, address reviews
+  and required checks, merge when green, fast-forward main and clean up the task
+  worktree/branch. Follow [release gates](../release/open-source-readiness.md)
+  when a release is authorized; do not add new approval steps on your own.
+- Stay on `0.x` until the maintainer explicitly chooses 1.0. The next minor
+  after `0.99.0` is `0.100.0`; routine shipping authority does not authorize 1.0.
+- Keep one current task handoff: requested outcome, what actually works, next
+  complete user-visible result, explicit constraints and rejected/deferred paths.
+  Link detailed evidence; mark superseded plans historical.
+
+## Verification
+
+- Use evidence appropriate to the changed behavior and material risk. Docs may
+  need link/command review; runtime changes need meaningful execution checks.
+  Required CI and release gates remain mandatory.
+- Test behavior and real failure modes, not incidental implementation structure
+  unless that structure enforces a required boundary. Provider-API fixtures must
+  derive from captured live wire shapes, never guesses that merely mirror code.
+- Once applicable checks pass, broaden or repeat them only for a new change,
+  failure or unresolved material risk. Do not rebuild upstream validation suites
+  when a focused integration check answers the question.
+- Claims of live execution need retained evidence; dry runs do not establish live
+  behavior. State what changed, what was checked and any material uncertainty.