humanish 0.88.2 → 0.89.1

package/docs/contracts/study-analysis.md

@@ -0,0 +1,150 @@
+# Study analysis
+
+Study analysis is an optional interpretation of retained participant evidence.
+It is separate from the participant's account, recorded outcome, and the run's
+deterministic review verdict. Opening an Observer never starts a provider request.
+
+## Invocation
+
+```bash
+humanish analyze --run latest --max-cost 3 --dry-run --json
+humanish analyze --run latest --max-cost 3 --json
+humanish observe --run latest
+humanish analyze list --run latest --json
+humanish analyze show --run latest --json
+```
+
+The source must be a verified, completed live run. A dry-run contract bundle is
+not a participant study. Here, `analyze --dry-run` means checking an existing
+study's input and admission estimate without credentials, a provider request,
+or a new analysis artifact.
+
+The default model is `gpt-6-astra`, with high reasoning effort. A request sends selected retained text and
+captures to OpenAI, without tools, redirects, provider-side response storage, or
+automatic retries. `--question` adds a reviewer question; it never changes the
+participant assignment. `--max-cost` is required, including for dry-run
+admission. It bounds a conservative estimate, not an exact provider bill.
+`--timeout-ms` and `--max-output-tokens` bound the request. An exceeded admission
+estimate retains valid findings and usage but returns a partial result and a
+nonzero command exit, including when that version is reused.
+
+The defaults allow five minutes and 16,384 output tokens, including reasoning.
+The analysis checks the assigned requirements against the retained end state;
+an unverified essential result remains unknown even if the participant reported
+success. Findings keep reported concerns and observed recovery distinct across
+participants. Other supported models can be selected explicitly, but evidence
+reference validation does not certify their interpretation of small visual details.
+
+Analysis distinguishes participant actions from harness setup and accounting.
+Runtime credentials or model usage do not establish that a participant made an
+external call while performing their task. Observations with an action basis
+must cite an action-bearing source; invalid source bases are rejected with the
+attempt's status and known usage retained.
+
+Identical source input, configuration, and prompt version reuse a current valid
+analysis. `--rerun` creates another immutable version. Failed attempts do not
+hide earlier valid findings. Ctrl-C cancels the request; usage remains unknown
+when the provider did not report it. Cancellation cannot undo an already accepted
+provider request.
+
+Decoded participant context, evidence text, and the reviewer question are checked
+for known sensitive-text patterns before dispatch. JSON escaping cannot bypass
+that check. Image bytes are not treated as text for pattern matching.
+
+Only one analysis command can own a run's `.analysis-lock` directory. Interrupted
+locks are not stolen using stored PIDs. After confirming the owning command has
+stopped, an operator can remove the empty lock directory and retry.
+
+## Evidence and findings
+
+The packet currently admits up to 16 participants, 800 evidence items, 40 PNG
+captures, 160 KiB of text and 20 MiB of images. Individual source files, image
+dimensions and result sizes have separate limits. Selection follows retained
+source order; it is not a statistically representative sample. Selection
+omissions and unreadable or invalid capture files make declared coverage
+incomplete. Coverage records file availability and selection; it does not
+certify visual legibility, correct interpretation, or exhaustive issue discovery.
+
+The standard review covers session summary, apparent intent, observed outcome,
+friction, dead ends, recovery, and participant feedback. Findings are ordered by
+observed task impact, replication among exposed participants, and recovery.
+Impact and confidence remain separate. There is no numeric frustration or
+universal priority score.
+
+Every observation cites packet-local evidence IDs. The model cannot choose a
+filesystem path or fetch another resource. Validation checks participant
+membership, unique counts, quote fidelity, evidence type and reference
+integrity. Visual claims require retained captures; screenshot-free evidence
+opens its original event. These checks do not prove that every interpretation
+is correct or every consequential issue was found.
+
+Elapsed replay time starts at the first retained capture. It is not a video
+offset. Nonvisual events retain event identity without invented frame offsets.
+
+## Durable records
+
+The frozen `humanish.observer-data.v1` schema is unchanged. A companion
+`humanish.study-analysis.v1` artifact records source/config/input hashes,
+participant context, evidence manifest, coverage, provider/model/prompt version,
+status, usage and validated findings:
+
+```text
+.humanish/runs/<run>/
+  analysis/<analysis>/analysis.json
+  analysis/<analysis>/corrections/<correction>/correction.json
+  analysis-attempts/<analysis>/receipt.json
+  observer/study-analysis.json
+```
+
+Version and correction directories are claimed exclusively; publication is
+atomic. Source evidence is not rewritten. Minimal execution receipts retain
+model, budget, status and known usage even if source changes prevent report
+publication. They contain no question, participant text, images, or findings.
+`analyze list --json` includes these receipts.
+
+Analysis and execution-history directories each admit 256 entries, including
+interrupted writes; correction history admits 256 entries per analysis. A new
+attempt requires readable inventories with room for its records before dispatch.
+Valid reuse remains available at capacity. The command does not remove old
+versions automatically. A present correction that cannot be read or validated
+blocks sharing and feedback promotion until the history can be checked.
+
+States distinguish no analysis, complete with no findings, complete with
+findings, partial, failed, cancelled, stale and invalid. A copied or modified
+source cannot silently inherit a current analysis. Saved HTML and the HTTP
+companion project validated records; generic HTTP serving of producer-owned raw
+analysis/correction JSON, execution receipts, atomic write temporaries and locks
+is disabled. Existing adapter captures and logs retain their contained routes.
+
+## Human review and sharing
+
+```bash
+humanish analyze correct --run latest --analysis <id> --finding F1 \
+  --status confirmed --reason "The cited captures reproduce the blocker."
+humanish analyze correct --run latest --analysis <id> --finding F1 \
+  --status amended --reason "The claim was too broad." --claim "A narrower supported claim."
+humanish feedback issue --run latest --analysis <id> --finding F1 --repo owner/repo
+```
+
+Corrections append against exact analysis and finding hashes. Confirming one
+version does not approve a later claim. Dismissed findings cannot become feedback
+drafts; amendments preserve the original and record the replacement. Feedback
+drafts include source/version/evidence references and remain explicitly
+independent of participant-authored candidates. No command above posts to GitHub.
+Each analysis has room for 256 correction inventory entries, including interrupted
+writes. A full or unsafe inventory refuses a new correction before creating its
+entry; prior records remain unchanged. Analysis and correction commands share the
+run lock so concurrent writers cannot overrun that bound.
+
+The existing sharing gate scans source and derived text. Export and feedback
+also check the exact in-memory analysis snapshot they include. Sensitive derived
+text blocks sharing and is quarantined from Observer, while independently
+verified source recordings remain viewable. Filesystem containment failures
+still fail closed. Valid failed/cancelled history alone does not downgrade
+sharing.
+
+Redacted bundle export omits analysis, corrections and execution receipts and
+records that omission in derivation provenance. Changed source bytes require
+new analysis; old hashes and review approvals cannot survive redaction. Ordinary
+legacy evidence under `analysis/` remains part of the recording and follows the
+normal redaction and sharing checks.

package/docs/goals/current.md

@@ -1,9 +1,9 @@
 # Current Goals
 
-Status date: 2026-09-13. Published baseline: `0.88.2`.
+Status date: 2026-09-15. Release baseline: `0.89.1`.
 
 This page guides work on current merged source. Published behavior is described
-in the [release notes](../release/0.88.2-sequential-study-budgets.md).
+in the [release notes](../release/0.89.1-analysis-finished-notice.md).
 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.
 
@@ -88,7 +88,7 @@ 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.88.2`)
+## Current Program Truth (source `0.89.1`)
 
 | Surface | Available in merged source | Remaining boundary |
 | --- | --- | --- |
@@ -99,6 +99,7 @@ substitute for it.
 | 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, 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 | Explicit `analyze`, bounded evidence selection, versioned findings, exact source links and append-only corrections within the Observer study shell | Model interpretation needs review; bounded selection and source truncation limit coverage; opening Observer never dispatches analysis |
 | TUI and serving | Detached starts, run stopping, reclamation, Observer attachment, loopback serving and run library | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups |
 | Off-app communication | In-sandbox email/SMS catch and digest-only thread evidence | This does not establish real-provider delivery |
 | Mobile and media | Hosted viewport/emulation, desktop geometry checks, bounded dwell and declared camera feed | Physical-device and touch fidelity remain unproven; unsupported microphone declarations are rejected |

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.88.2` (2026-09-13). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
+Package/source version in this tree: `0.89.1` (2026-09-15). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until
@@ -47,6 +47,14 @@ If a change does not improve one of those loops, it probably belongs elsewhere.
 
 ## Current State
 
+The [0.89.1 release note](../release/0.89.1-analysis-finished-notice.md)
+clarifies that an analysis with limitations has finished.
+
+The [0.89.0 release note](../release/0.89.0-study-findings.md) describes explicit
+analysis of completed studies, versioned findings and review corrections, exact
+evidence links, and Participants / Findings within one Observer shell. Analysis
+remains separate from participant feedback and recorded outcomes.
+
 The [0.88.2 release note](../release/0.88.2-sequential-study-budgets.md)
 describes model-spend thresholds on sequential shared-world studies, blocked
 later participants, and explicit unknown-usage accounting.
@@ -86,7 +94,9 @@ pnpm humanish -- verify --run latest --json
 Implemented:
 
 - `commander` CLI with stable command help;
-- `init`, `doctor`, `run`, `watch`, `verify`, `review`, `runs`, and `feedback`;
+- `init`, `doctor`, `run`, `watch`, `verify`, `review`, `runs`, `analyze`, and `feedback`;
+- opt-in study analysis with bounded provider admission, immutable findings,
+  source-bound corrections and evidence-linked Observer review;
 - synthetic run bundles;
 - public-safety verification with machine-readable `shareSafety.status`
   (`share_ready`, `local_only`, or `blocked`);

package/docs/release/0.89.0-study-findings.md

@@ -0,0 +1,79 @@
+# Humanish 0.89.0: evidence-linked study findings
+
+Completed studies can now produce ranked findings with links to the participant
+events and captures that support them. Observer keeps Participants and Findings
+inside the same study shell, with the recording grid, original participant
+feedback and playback controls available throughout the review.
+
+## Analyze a completed study
+
+```bash
+npm install humanish@0.89.0
+npx humanish analyze --run latest --max-cost 3 --dry-run --json
+npx humanish analyze --run latest --max-cost 3 --json
+npx humanish observe --run latest
+```
+
+Select a verified, completed live run. The first analysis command checks admission
+without credentials or a provider request; the second requires `OPENAI_API_KEY`
+and sends selected text and captures to OpenAI. The required cost ceiling bounds
+a conservative estimate, not the provider's invoice. Opening Observer never
+starts analysis.
+
+The standard analysis covers session summary, apparent intent, observed outcome,
+friction, dead ends and recovery. Findings explain task impact, affected and
+exposed participants, evidence and limitations. Participant reports, recorded
+completion conditions and independent analysis remain separate. Missing evidence
+can leave an outcome unknown even when the participant reported success.
+
+Identical source input, configuration and prompt version reuse a saved analysis.
+`--rerun` requests a new immutable version; `--question` adds a reviewer question.
+The default is `gpt-6-astra` with high reasoning, a five-minute timeout and 16,384
+output tokens including reasoning. Each attempt makes one stateless request,
+without tools or automatic retries, and retains known usage or explicit
+uncertainty.
+
+## Review findings against the recording
+
+Participants and Findings share the study library, header and available width.
+Ranked findings expand in place and open their exact source event. A screenshot
+shown only as context is labeled accordingly; nonvisual evidence opens its
+original event without inventing a frame. Playback links, return navigation and
+phone controls retain their source context. The scrubber thumb and track now
+share the same centerline, with component geometry checks at multiple sizes.
+
+Use `analyze list` and `analyze show` to inspect history. `analyze correct` appends
+a confirmed, dismissed or amended review against the exact analysis and finding
+hashes. Original claims and evidence remain intact. Full correction history
+refuses another write before existing records become unreadable; analysis and
+correction writers share the run lock.
+
+Feedback drafting and export validate the included analysis snapshot and retain
+the existing sharing gates. Redacted bundle derivatives omit analyses tied to
+the original source bytes. A local-only HTML export remains portable and clearly
+labeled. Feedback commands print drafts; they do not post to GitHub.
+
+## Compatibility and verification
+
+The Observer data v1 contract is unchanged. Older recordings remain readable,
+and absent, failed, stale or invalid analysis does not erase participant evidence.
+The CLI also explains empty participant-feedback candidates and the available
+run-summary drafting path.
+
+[The feature implementation and verification](https://github.com/danielgwilson/humanish/pull/773)
+cover analysis validation and storage, sharing boundaries, the existing Observer
+flows, mobile layout, component geometry and fresh-package review/export paths.
+Final source-first model review covered five exposed regression cases and two
+untouched controlled task families, with a separate hostile-evidence challenge.
+That is bounded validation, not a general accuracy benchmark. One conservative
+outcome required an explicit task-scope reconciliation; one accurate positive
+recovery item did not motivate a product change.
+
+Evidence selection follows source order and has size/count limits; upstream
+truncation also constrains what can be established. Schema and reference checks
+do not certify interpretation or exhaustive issue discovery. Review the cited
+evidence before acting. Browser proof uses Chromium desktop and phone emulation;
+physical-device and cross-browser behavior remain separate verification work.
+
+See the [study-analysis contract](../contracts/study-analysis.md) for limits,
+artifact layout, cancellation, corrections and sharing behavior.

package/docs/release/0.89.1-analysis-finished-notice.md

@@ -0,0 +1,24 @@
+# Humanish 0.89.1: finished analysis notice
+
+Observer now labels a partial analysis result **“Analysis finished with
+limitations.”** The previous notice described findings as covering evidence
+“included so far,” which could make a finished analysis appear to be running.
+
+A partial result can contain validated findings after evidence selection limits
+or an exceeded admission estimate. Review the recorded coverage, limitations and
+usage when interpreting that result. The analysis status and saved evidence keep
+their existing meaning.
+
+## Update an existing recording
+
+```bash
+npm install humanish@0.89.1
+npx humanish observe --run latest
+```
+
+This renders the existing study with the updated Observer. An already exported
+HTML file is a saved snapshot; export it again to get the new wording. Reuse the
+appropriate sharing options for that run. No new analysis request is needed.
+
+The [0.89.0 release note](0.89.0-study-findings.md) describes the underlying study
+findings feature and its verification limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.88.2",
+  "version": "0.89.1",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [
@@ -93,7 +93,8 @@
     "commander": "^14.0.3",
     "playwright-core": "^1.60.0",
     "pngjs": "^7.0.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",