humanish 0.0.1 → 0.15.0

package/docs/architecture/github-feedback-loop.md

@@ -0,0 +1,189 @@
+# Public GitHub Feedback Loop Architecture
+
+Date: 2026-06-01
+
+Status: design note. The v0 dry-run issue draft path is implemented locally;
+live GitHub mutation remains out of scope.
+
+## Goal
+
+Make feedback a first-class CLI path that can safely turn persona simulation
+evidence into a public-safe GitHub issue draft without requiring hosted
+infrastructure or GitHub credentials.
+
+Target loop:
+
+```text
+humanish run
+-> run bundle
+-> humanish review
+-> humanish verify
+-> humanish feedback draft
+-> humanish feedback issue
+-> user files public GitHub issue
+-> maintainer triage / project cockpit
+-> scoped implementation when accepted
+-> rerun
+```
+
+## Public And Privacy Boundary
+
+The GitHub loop must assume repository contents, issue bodies, project fields,
+and future examples may become public.
+
+Never place PII, PHI, secrets, tokens, raw customer data, raw patient data,
+private transcripts, private screenshots, private source snippets, or provider
+payloads into GitHub. Feedback drafting must redact or block unsafe fields
+before printing an issue body or issue URL.
+
+## Command Shape
+
+Likely v0 commands:
+
+```bash
+humanish feedback list --run latest
+humanish feedback draft --run latest --json
+humanish feedback verify --run latest --json
+humanish feedback issue --run latest --repo owner/repo --format markdown
+humanish feedback issue-url --run latest --repo owner/repo
+```
+
+`issue` and `issue-url` should fail closed unless the draft contains:
+
+- run id;
+- adapter id;
+- scenario id;
+- persona id or persona class;
+- actor runtime;
+- substrate;
+- failure owner;
+- observed behavior;
+- expected behavior;
+- evidence pointers;
+- redaction result;
+- duplicate/idempotency key;
+- proposed next state;
+- acceptance proof.
+
+The default public CLI should not create GitHub issues, update Projects, call
+hosted queues, require tokens, or depend on private infrastructure. It should
+produce a high-quality issue draft and clear filing instructions.
+
+## Feedback States
+
+| State | Meaning | GitHub action |
+| --- | --- | --- |
+| `watch` | Useful observation, not yet work | Keep as bundle-local feedback or low-priority issue |
+| `needs_spec` | Real signal, scope unclear | Create issue with spec task |
+| `spec_ready` | Docs/spec work can clarify it | Create issue with docs-only authority |
+| `agent_ready` | Narrow enough for autonomous PR draft | Include readiness block for maintainers |
+| `blocked` | Needs human/operator input | Create or update issue with blocker |
+| `wontfix` | Accounted for and rejected | Keep in review packet; no issue by default |
+
+## Issue Body Contract
+
+Promoted feedback should use this stable body shape:
+
+```yaml
+humanish_feedback:
+  schema: humanish.feedback.v1
+  run_id: "<run-id>"
+  adapter_id: "<adapter-id>"
+  scenario_id: "<scenario-id>"
+  persona_id: "<persona-id-or-class>"
+  actor: "<actor-runtime>"
+  substrate: "<substrate>"
+  failure_owner: "harness|target-app|actor|environment|unknown"
+  source_bundle: "<path-or-url>"
+  evidence:
+    - "<relative artifact pointer>"
+  redaction:
+    status: passed
+    notes: "no sensitive data promoted"
+  idempotency_key: "<stable-key>"
+  proposed_next_state: "watch|needs_spec|spec_ready|agent_ready|blocked"
+```
+
+For maintainer/agent-ready work, the issue can also include:
+
+```yaml
+humanish_swarm:
+  schema: humanish.swarm-readiness.v1
+  status: needs_spec
+  authority: draft_spec
+  blocked_by: []
+  can_parallel_with: []
+  exclusive_files: []
+  allowed_write_paths:
+    - docs/**
+  denied_write_paths:
+    - .env*
+    - .github/workflows/**
+    - infra/**
+  artifact_schema_version: humanish.run-bundle.v1
+  credential_manifest: []
+  network_policy: no_network
+  spend_policy: no_spend
+  idempotency_key: "<issue-or-feedback-key>"
+  proof_commands:
+    - "<exact command>"
+  telemetry_expectations:
+    - "none for docs-only work"
+  stop_conditions:
+    - "required field missing"
+    - "changed files outside allowed_write_paths"
+    - "proof command fails"
+```
+
+The readiness block is authority, not decoration. Labels and Project fields may
+mirror it, but they do not replace it.
+
+## Labels
+
+Initial label taxonomy:
+
+| Label | Meaning |
+| --- | --- |
+| `product-feedback` | Persona/user friction captured as public-safe feedback |
+| `agent-candidate` | May become autonomous work after spec/readiness |
+| `needs-spec` | Requires scope or acceptance criteria before mutation |
+| `agent-ready` | Has valid readiness block and narrow write scope |
+| `proof-required` | Cannot close without run bundle or command proof |
+| `harness` | Harness/core/observer/review work |
+| `adapter` | Product adapter work |
+| `feedback-loop` | Feedback, issue-draft, or queue plumbing |
+| `privacy-boundary` | Public/PII/PHI/secret-safety concern |
+
+## GitHub Projects
+
+Projects are useful for maintainer operating visibility, not canonical truth.
+The public CLI should not require Projects. Canonical state should live in:
+
+- issue body YAML blocks;
+- labels;
+- issue comments;
+- PR bodies;
+- checks;
+- run bundles and proof artifacts.
+
+The first maintainer Project can track broad workstreams and status. It should
+not be the only place a field such as authority, write scope, or proof command
+exists.
+
+## Issue Draft Rules
+
+- Capture generously, execute rigorously.
+- Vague feedback can become `watch`; it cannot become `agent_ready`.
+- A GitHub issue may say `contributes to` broader goals, but should not say
+  `closes` without product proof.
+- The issue draft includes an idempotency key so maintainers can dedupe.
+- Redaction failure blocks issue drafting.
+- Missing evidence blocks issue drafting.
+- Any PII/PHI/secret ambiguity blocks issue drafting.
+
+## Optional Maintainer Tooling
+
+Maintainers may later add repo-local tooling that reads a verified draft and
+uses GitHub APIs to create or update issues. That tooling should be separate
+from the default public CLI, dry-run first, token-explicit, and disabled unless
+the maintainer asks for mutation.

package/docs/architecture/local-codex-tui-actor.md

@@ -0,0 +1,213 @@
+# Local Codex TUI Actor Contract
+
+Date: 2026-06-02
+
+Status: incremental implementation on issue #28. The repo supports one explicit
+local Codex TUI actor with sanitized lifecycle evidence and fail-fast Codex
+workspace-trust preflight. It also supports explicit noninteractive
+`codex-exec` actor fanout for autonomous local dogfood proof. Requested exec
+lanes are not capped by total run count; they run through bounded concurrency
+controlled by `HUMANISH_LOCAL_CODEX_EXEC_MAX_CONCURRENCY` (default 4). TUI
+autonomous completion and TUI live Observer follow remain follow-up work.
+
+## Goal
+
+Let `humanish run` dogfood `humanish` with a real local Codex TUI actor while
+preserving the public-safe harness contract:
+
+```text
+spawn actor
+-> submit bounded prompt
+-> stream sanitized lifecycle events
+-> write run bundle
+-> render Observer while active
+-> verify final bundle
+```
+
+This actor proves the local harness substrate. It must not claim target product
+behavior beyond the commands and artifacts it actually observes.
+
+## Explicit Opt-In
+
+The first live actor must require an explicit flag or env var. Non-dry-run
+without opt-in should continue to fail closed.
+
+Suggested gate:
+
+```bash
+humanish run --actor codex-tui --sims 1 --timeout-ms 240000
+```
+
+or, for noninteractive local autonomy:
+
+```bash
+humanish run --actor codex-exec --sims 4 --timeout-ms 240000
+```
+
+or:
+
+```bash
+HUMANISH_ENABLE_LOCAL_CODEX_TUI=1 humanish run --sims 1
+```
+
+or:
+
+```bash
+HUMANISH_ENABLE_LOCAL_CODEX_EXEC=1 humanish run --sims 1
+```
+
+Provider spend, E2B, GitHub mutation, and external network calls remain off
+unless separately and explicitly requested. When real Codex exec auth is used,
+`HUMANISH_LOCAL_CODEX_EXEC_MAX_CONCURRENCY` is the cost/resource rail; there is
+no arbitrary total lane cap.
+
+For deterministic tests or local substrate debugging, `HUMANISH_CODEX_ACTOR_COMMAND`
+can point at a safe fixture command. Real Codex TUI launch uses a Linux
+`script` PTY wrapper when available because the Codex TUI requires a terminal.
+Humanish answers the minimal terminal cursor/color queries needed for headless
+TUI startup and normalizes terminal control sequences before classifying the
+final actor transcript. Once a final
+`HUMANISH_ACTOR_VERDICT=* HUMANISH_ACTOR_NONCE=<run-nonce>` marker appears,
+Humanish terminates the local actor process and records the marker verdict rather
+than waiting for the TUI session to stay open until timeout. The nonce prevents
+the classifier from accepting an echoed prompt or inspected docs as a final
+actor verdict.
+Real Codex exec launch uses `codex exec --skip-git-repo-check --ignore-rules
+--ephemeral --sandbox read-only --json` so it can complete without an
+interactive TUI trust prompt while still running with read-only local command
+permissions.
+
+## Lifecycle Events
+
+The actor should append deterministic events to `events.ndjson`:
+
+| Event | Required fields |
+| --- | --- |
+| `actor.spawned` | `simId`, `streamId`, command name, cwd, startedAt |
+| `actor.prompt.submitted` | prompt digest, prompt class, no raw prompt if unsafe |
+| `actor.running` | running snapshot available in `run.json` and `observer/observer-data.json` |
+| `actor.observation` | sanitized transcript tail, byte count, redaction status |
+| `actor.artifact` | relative artifact path, kind, digest |
+| `actor.verdict` | `passed`, `failed`, `blocked`, or `timed_out`; reason |
+| `actor.exited` | exit code, signal, durationMs |
+| `actor.timeout` | timeoutMs, last safe observation |
+| `actor.cancelled` | signal and operator reason |
+
+The Observer should be able to render a live terminal stream from those events
+while the actor is active, then render the final transcript and artifacts after
+exit.
+
+For local Codex actors, the run writes a provisional running bundle and
+`observer/observer-data.json` before awaiting actor completion, then refreshes
+those files with final verdicts and artifact links. This lets an existing
+served Observer poll the same local evidence path during the run.
+
+## Runtime State
+
+All generated state stays under ignored `.humanish/`:
+
+```text
+.humanish/runs/<run-id>/
+  run.json
+  review.json
+  review.md
+  events.ndjson
+  actor.json
+  actors/sim-02-codex-exec.json
+  transcripts/codex-tui-sanitized.txt
+  transcripts/codex-exec-sanitized.jsonl
+  transcripts/sim-02-codex-exec-sanitized.jsonl
+  observer/
+    index.html
+    observer-data.json
+```
+
+No raw terminal output is public by default. The transcript artifact must be
+sanitized before it is linked from the bundle.
+
+For TUI runs, `.humanish/runs/latest.json` is published only after a valid
+running bundle, review, and Observer data exist, then refreshed after final
+artifacts exist. This keeps `humanish verify --run latest` from pointing at an
+incomplete TUI run while still allowing live Observer follow on the active run.
+
+## Redaction Rules
+
+Before any transcript tail or event payload is written:
+
+- redact OpenAI, E2B, GitHub, npm, and generic private-key patterns;
+- redact absolute local home/workspace paths when they are not necessary for
+  proof;
+- block the run if redaction cannot prove `status: passed`;
+- record env var names only, never values.
+
+## Initial Prompt Class
+
+The first actor prompt should be bounded to public-safe dogfood work:
+
+- inspect `humanish/` dogfood config;
+- run at most two read-only inspection commands;
+- avoid commands that write runtime artifacts or temp config, including
+  `pnpm humanish`, `humanish watch`, `humanish feedback`, `humanish init`, tests,
+  builds, installs, and commands that write `.humanish/`;
+- inspect existing artifacts and explain the strongest write-required proof as a
+  follow-up when the TUI actor is running in a read-only sandbox;
+- use `passed` when read-only inspection confirms the committed harness and
+  existing evidence contract; write-required follow-ups alone are not blockers;
+- do not commit, push, publish, file issues, or print secrets;
+- summarize blockers using public-safe evidence paths;
+- finish with exactly one final
+  `HUMANISH_ACTOR_VERDICT=<status> HUMANISH_ACTOR_NONCE=<run-nonce>` line, where
+  `<status>` is `passed`, `blocked`, or `failed`.
+
+The raw prompt can live in source only if it contains no private context and no
+credential values.
+
+## Stop Conditions
+
+The actor must stop and mark the lane `blocked` or `failed` if:
+
+- Codex CLI is not installed or not authenticated;
+- a command requests approval in a non-interactive run;
+- redaction fails;
+- output contains a likely secret after redaction;
+- the actor touches files outside allowed runtime paths without explicit scope;
+- timeout is reached.
+
+## Known First-Slice Boundary
+
+The first real local TUI proof in this environment reached Codex's workspace
+trust prompt. The current TUI implementation detects missing exact project-root
+trust before spawn and writes a `blocked` run bundle instead of waiting for the
+TUI timeout. A follow-up PTY probe showed that the Codex TUI still prompts when
+only a trusted ancestor is configured, so Humanish only treats the exact trust
+root as sufficient for autonomous launch.
+
+With exact trust present, Humanish answers Codex's terminal startup query, strips
+TUI control sequences from the captured transcript, and terminates/classifies on
+an explicit nonce-bearing `HUMANISH_ACTOR_VERDICT=*` marker when present. If
+Codex exits cleanly without a marker, the run is still considered process-passed
+but the transcript remains available for review.
+
+The noninteractive `codex-exec` mode is a separate actor contract for autonomous
+local completion. It can run requested bounded read-only lanes with distinct
+focuses across install readability, public safety, Observer evidence, and
+verification/release gates. It does not replace the TUI contract because it does
+not prove PTY rendering, keyboard focus, or visible live TUI observation.
+
+The next implementation slice should decide whether TUI-specific fanout is
+needed beyond the current 1x TUI proof plus bounded-concurrency noninteractive
+`codex-exec` fanout split.
+
+## Acceptance For First Slice
+
+The implementation slice for this spec should prove:
+
+```bash
+pnpm humanish:doctor
+pnpm humanish -- run --actor codex-tui --sims 1 --timeout-ms 240000 --json
+pnpm humanish -- run --actor codex-exec --sims 1 --timeout-ms 240000 --json
+pnpm humanish -- run --actor codex-exec --sims 4 --timeout-ms 240000 --json
+pnpm humanish -- watch --run latest --detach --json --no-open
+pnpm humanish -- verify --run latest --json
+pnpm check
+```

package/docs/architecture/observer.md

@@ -0,0 +1,118 @@
+# Observer Architecture
+
+Date: 2026-06-01
+
+Status: implemented for synthetic stream contracts and local `codex-exec`
+active-run Observer snapshots; broader live actor adapters next.
+
+## Decision
+
+The Observer is a mission-control surface over durable run artifacts, not a
+static report page.
+
+Every run writes immutable local evidence under `.humanish/runs/<run-id>/`:
+
+```text
+.humanish/runs/<run-id>/
+  run.json
+  review.json
+  review.md
+  events.ndjson
+  observer/
+    index.html
+    observer-data.json
+```
+
+`run.json` remains the source bundle. `observer/observer-data.json` is the
+normalized view model consumed by the Observer. `events.ndjson` is the appendable
+event stream contract that live adapters will update while a run is active.
+
+## Stream Model
+
+Streams are the central abstraction. A stream is one watchable persona lane,
+regardless of substrate:
+
+- `ui`: browser/VNC style UI simulation lane;
+- `browser`: browser-specific lane when the app and actor are separate;
+- `terminal`: CLI persona lane with stdout/stderr evidence;
+- `tui`: PTY/ANSI terminal UI lane;
+- `codex-ui`: Codex-style app-server session lane;
+- `artifact`: artifact-only evidence lane;
+- `summary`: run-level synthesis lane.
+
+Each stream points back to a simulation and carries its own transport,
+terminal tail, UI state, artifact links, event timeline, and public-safe
+metadata.
+
+## Live Watch
+
+`humanish watch` now:
+
+1. creates a fresh four-lane synthetic run bundle;
+2. writes `observer-data.json` and `events.ndjson`;
+3. starts a localhost Observer server;
+4. opens the served Observer URL;
+5. keeps the shell attached until Ctrl-C.
+
+The browser polls `observer-data.json` with `no-store` caching. Static
+`file://` opening still works for immutable review, but follow mode is the
+operator path. Agents and CI should use `humanish watch --json --no-open` for
+the same fresh evidence without browser open or a long-running process.
+
+Local `codex-exec` actor runs now publish an initial running `run.json` and
+`observer/observer-data.json` before actor completion, then refresh both after
+sanitized transcripts, traces, and verdict events are available. This gives a
+served Observer a truthful active state to poll while noninteractive local
+actors are still running.
+
+## UI Shape
+
+The Observer shell has:
+
+- top mission-control band with run status and metrics;
+- stream filters for UI, CLI, TUI, and Codex UI lanes;
+- grid mode with one tile per sim stream;
+- focus mode with left stream rail, center stage, and right tabs;
+- terminal/TUI transcript stage;
+- right evidence rail for events, artifacts, and known gaps.
+
+## Codex UI Contract
+
+`codex-ui` streams are normalized session/event projections. Public artifacts
+must not store raw provider payloads, raw prompts, raw private transcripts,
+private screenshots, PHI, PII, secrets, or upstream data.
+
+A host adapter may provide:
+
+- session identity;
+- redacted lifecycle/status;
+- event source or snapshot URL;
+- optional embed URL;
+- normalized event timeline;
+- approval metadata;
+- public-safe artifact links.
+
+If no embed URL exists, the Observer still renders the Codex-style timeline and
+session contract instead of failing the lane.
+
+## Current Gaps
+
+This slice implemented the Observer substrate, synthetic stream contracts, and
+active-run Observer snapshots for local `codex-exec`.
+
+Since shipped (updated 2026-06-11):
+
+- Playwright-backed browser proof with scripted, app-specific
+  `browser.steps` authored in `humanish/scenarios/*.yaml` (`src/run.ts`);
+- native Codex app-server session adapter (`src/codex-app-server.ts`,
+  registered in `src/actor-registry.ts`);
+- E2B desktop substrate lanes on the meta and computer-use routes;
+- computer-use bundles persist a `screenshots/` directory and the Observer
+  renders the frames (`src/cua-actor-lab.ts`).
+
+Intentionally still adapter work:
+
+- local PTY capture;
+- Codex TUI live follow after workspace trust bootstrap;
+- richer screenshot/trace galleries across multi-step product journeys;
+- reviewer acceptance gates over real product behavior.