humanish 0.0.1 → 0.15.0

package/docs/principles/self-driving-harness.md

@@ -0,0 +1,129 @@
+# Self-Driving Harness Principles
+
+Date: 2026-06-01
+
+Status: initial repo doctrine for `humanish`.
+
+## Thesis
+
+`humanish` should be a closed-loop product simulation system, not just a
+CLI that launches agents.
+
+The operating loop is:
+
+```text
+persona scenario run
+-> durable evidence bundle
+-> review and verification
+-> structured feedback
+-> GitHub issue or project queue
+-> scoped implementation
+-> rerun and compare
+```
+
+The hard part is not getting an agent to do something. The hard part is making
+the result verifiable, repeatable, safe to file, and useful to the next
+agent with no chat context.
+
+## Public Boundary
+
+This repo must be designed as if it will become public.
+
+No PII, PHI, secrets, keys, tokens, raw private transcripts, real patient data,
+real customer data, or private product artifacts belong here. Examples,
+fixtures, screenshots, personas, run bundles, issue bodies, and docs must be
+synthetic or redacted.
+
+## Principles
+
+### 1. Model, Harness, Environment
+
+Reliable agentic work is the composition of model, harness, and environment.
+`humanish` owns the harness layer: replay, invariants, observability,
+policy, artifacts, review, and feedback routing.
+
+### 2. Verifiability Defines Throughput
+
+Autonomy stalls when outcomes cannot be classified as red, yellow, or green.
+Every claim a run makes should point to retrievable evidence: bundle files,
+screenshots, terminal transcripts, state proofs, event streams, review packets,
+or issue links.
+
+### 3. Run Bundles Are Source Of Truth
+
+The observer is a projection. The GitHub Project is a cockpit. The issue queue
+is a work surface. The run bundle is the canonical evidence record.
+
+### 4. Coverage Is The Product
+
+Serious adapters need discovery maps and coverage matrices. Hidden
+undercoverage is worse than visible gaps. A partial matrix with named gaps is
+more useful than three green happy paths pretending to prove the whole product.
+
+### 5. Product Trial Beats Tracker Truth
+
+Tracker fields, issue comments, PR summaries, and author receipts are not
+acceptance. A product claim needs a product trial or a precise explanation of
+why the run is only contract proof.
+
+### 6. Staged Autonomy Beats Binary Replacement
+
+Authority should progress through stages:
+
+```text
+observe -> draft feedback -> draft issue -> draft spec -> draft PR -> steward PR -> release assist
+```
+
+Each stage requires stricter proof, narrower write scope, and clearer stop
+conditions.
+
+### 7. Idempotent Closed Loops Beat Heroic Retries
+
+Every run and feedback issue-draft path needs idempotency keys, duplicate
+prevention, explicit terminal states, cleanup proof, and safe re-run behavior.
+Retries without loop closure create queue debt.
+
+### 8. Feedback Is A First-Class Artifact
+
+Friction found by a persona or agent should not be buried in prose. It should
+be structured, evidence-linked, dedupable, public-safe, and reviewable. For an
+open-source CLI, the default output should be an issue draft and filing
+instructions, not live GitHub mutation.
+
+### 9. Product Nouns Belong In Adapters
+
+Core owns schema, lifecycle, actors, substrates, evidence streams, history,
+review, verification, redaction, and feedback mechanics. Adapters own product
+routes, personas, app topology, milestones, vocabulary, environment allowlists,
+and product-specific proof.
+
+### 10. Credential Boundaries Are Architecture
+
+Executor auth, product auth, provider auth, spend policy, network policy, and
+repo/GitHub authority are separate boundaries. A run must name what was
+available and prove that sensitive values were not persisted.
+
+### 11. Dry-Run Is Contract Proof
+
+Dry-run proves scenario selection, bundle shape, review generation, and CLI
+semantics. It does not prove product behavior. Review output must preserve that
+distinction.
+
+### 12. Green Requires Reviewer Acceptance
+
+The builder of a harness is not the final judge of the harness. `review` can
+summarize, `verify` can validate contracts, but acceptance requires a reviewer
+or reviewer-like gate that checks coverage, evidence, and product relevance.
+
+## Anti-Patterns
+
+- Treating the best model as a substitute for harness quality.
+- Using screenshots as vibes without state or transcript evidence.
+- Letting product-specific nouns leak into generic core.
+- Generating GitHub issue drafts from vague summaries without bundle links.
+- Closing issues because a PR exists, not because product proof exists.
+- Giving autonomous agents broad write authority before observe/draft stages
+  are reliable.
+- Letting project fields become canonical state.
+- Retrying failed issue submission paths until duplicates appear.
+- Storing private data in examples because it was convenient during extraction.

package/docs/product/open-source-install-experience.md

@@ -0,0 +1,229 @@
+# Open-Source Install Experience
+
+Date: 2026-06-01
+
+Status: product target for the first world-class `humanish` implementation.
+
+## Product Promise
+
+Drop Humanish into an app and let a coding agent set up realistic persona
+simulations, run them safely, watch them in a polished observer, and turn
+friction into public-safe issue drafts.
+
+The first experience should feel like a mature one-command simulation harness,
+but with an open-source-safe package shape:
+
+```bash
+npm i -D humanish
+npx humanish init
+npm run humanish:doctor
+npm run humanish:watch
+npm run humanish:verify
+npx humanish feedback issue --run latest --repo example/app --format markdown
+```
+
+## Two-Part Distribution
+
+### NPM Package
+
+The npm package owns executable behavior:
+
+- binary: `humanish`;
+- CLI framework: `commander`;
+- commands: `init`, `doctor`, `run`, `watch`, `review`, `verify`,
+  `lab`, `feedback`;
+- schemas and validators;
+- synthetic starter templates;
+- observer static assets;
+- artifact and run-bundle utilities;
+- redaction and public issue-draft generation.
+
+### Agent Skill
+
+The agent skill owns installation guidance and repo adaptation:
+
+```bash
+npx skills add danielgwilson/humanish --skill humanish
+```
+
+Installable repo skill: [`skills/humanish/SKILL.md`](../../skills/humanish/SKILL.md).
+
+The skill should teach the user's coding agent how to:
+
+- install `humanish`;
+- run `humanish init`;
+- inspect the target app's routes and dev command;
+- create synthetic personas and scenarios;
+- create public-safe `humanish/labs/*.yaml` lab manifests;
+- keep private/local labs under ignored `.humanish/labs/*.yaml` or
+  `.humanish/local/labs/*.yaml`;
+- configure local app targets;
+- document E2B and OpenAI env var names without storing values;
+- use `--env-file <path>` for explicit local env hydration without persisting
+  values into artifacts;
+- run `doctor`, `watch`, `verify`, and `feedback issue`;
+- avoid PII, PHI, secrets, real customer data, and private artifacts.
+
+The skill should not hide critical behavior in chat memory. It should point to
+repo-owned `humanish/` files and package-owned docs.
+
+## Project File Formats
+
+New projects should get a boring, legible format stack:
+
+- `.yaml` for human-authored Humanish source such as personas, scenarios,
+  policies, labs, and review vocabulary;
+- `.ts` for executable integration such as `humanish/config.ts` and adapters;
+- `.json` and `.ndjson` for generated run artifacts, Observer data, review
+  output, event streams, and synthetic fixtures.
+
+Use `.yml` only where an outside ecosystem convention already expects it, for
+example GitHub Actions workflows. Do not scaffold `.yml` for Humanish source and
+do not use TOML unless a future scalar global-config case clearly needs it.
+
+## First-Run Principles
+
+- No keys required for the first wow moment.
+- No live GitHub mutation.
+- No hosted queues or private infrastructure.
+- No real customer/user/patient data.
+- No generated personas from tickets, logs, transcripts, screenshots, or
+  production analytics.
+- Safe dry-run should produce a valid synthetic run bundle and observer view.
+- The user should see what changed in git.
+
+## Lab Manifest Shape
+
+Labs are the public-safe way to name a reusable simulation run. A starter app
+gets a committed synthetic lab:
+
+```yaml
+schema: humanish.lab.v2
+id: first-run
+title: First-run synthetic Observer
+description: Public-safe starter lab that generates a synthetic run bundle and Observer without provider spend.
+subject:
+  source: this-repo
+actors:
+  - type: synthetic-persona
+    count: 4
+scenario:
+  mode: dry-run
+defaults:
+  open: true
+```
+
+Resolution order:
+
+1. `humanish/labs/<id>.yaml` for committed, reproducible labs.
+2. `.humanish/labs/<id>.yaml` for ignored local labs.
+3. `.humanish/local/labs/<id>.yaml` for ignored machine-specific overlays.
+4. explicit `.yaml` path, for example
+   `.humanish/labs/local-dogfood.yaml`.
+
+Private repo targets, local env references, and maintainer dogfood variants
+belong in ignored lab manifests and should be invoked with explicit
+`--env-file`; do not make them package defaults.
+
+## `humanish init`
+
+`humanish init` should:
+
+1. Detect package manager and app framework when possible.
+2. Create committed starter files under `humanish/`.
+3. Create ignored runtime state under `.humanish/`.
+4. Add `.humanish/` and secret/local overlays to `.gitignore`.
+5. Patch `package.json` scripts only after showing the intended diff or when
+   `--yes` is passed.
+6. Create only synthetic public-safe personas and scenarios.
+7. Write credential references as env var names only.
+8. Run a dry-run verification if dependencies are available.
+
+Suggested scripts:
+
+```json
+{
+  "scripts": {
+    "humanish": "humanish",
+    "humanish:doctor": "humanish doctor",
+  "humanish:run": "humanish run --dry-run",
+  "humanish:watch": "humanish watch",
+  "humanish:lab:list": "humanish lab list",
+  "humanish:watch:ci": "humanish watch --json --no-open",
+  "humanish:verify": "humanish verify"
+  }
+}
+```
+
+## Command Ladder
+
+| Command | Purpose | First version should |
+| --- | --- | --- |
+| `humanish init` | Set up project-owned harness files | Scaffold committed `humanish/`, ignored `.humanish/`, package scripts |
+| `humanish doctor` | Explain readiness | Check config, gitignore, app target, browser, env var names, redaction policy |
+| `humanish run --dry-run` | Prove contract without app/browser/keys | Write synthetic run bundle |
+| `humanish verify` | Validate bundle and public-safety gates | Fail closed on schema/evidence/redaction errors |
+| `humanish review` | Build review packet from evidence | Summarize verdicts without inventing product proof |
+| `humanish watch` | Run sims and watch the observer | Create a fresh four-lane bundle, render Observer, open it, and keep the shell attached |
+| `humanish watch [lab]` | Run a named lab and watch it | Resolve committed or ignored `.yaml` lab manifests, then open/follow Observer |
+| `humanish watch --json --no-open` | Agent/CI proof path | Create the same bundle and Observer artifacts without browser open or attached watch server |
+| `humanish lab list` | Discover available labs | List committed labs and ignored local labs with origin labels |
+| `humanish lab inspect <lab>` | Read a lab manifest | Print the parsed lab config, origin, path, and warnings without executing |
+| `humanish lab preflight <lab>` | Check lab readiness before spend | Validate routing and optionally probe declared targets from a hosted desktop without launching actors |
+| `humanish lab run <lab>` | Run a lab manifest | Human or JSON execution path for synthetic, OSS meta, and smoke labs |
+| `humanish lab run oss` | Maintainer dogfood example | Open the Observer-of-Observers with headed desktop lanes assigned by `--repos`, target app windows, nested Observers, runtime-only stream URLs, and redacted durable evidence for token-backed runs |
+| `humanish lab run oss-smoke` | Maintainer smoke example | Shallow clone lightweight GitHub repos, run setup/proof/verify, report, and remove clones |
+| `humanish feedback issue` | Produce public-safe issue draft | Print Markdown or prefilled issue URL, no GitHub API mutation |
+
+## Live Capability Ladder
+
+Live execution should be staged after the dry-run path is boring:
+
+1. Synthetic dry-run bundle.
+2. Local app reachability and browser smoke.
+3. Scripted browser scenario.
+4. Observer over real screenshots/traces.
+5. Computer-use / OpenAI actor.
+6. E2B substrate.
+7. Multi-persona matrix.
+8. Optional maintainer-only issue sync tooling.
+
+Do not make E2B, OpenAI, or GitHub credentials part of the first successful
+run.
+
+For step 3, app-specific browser scenarios are authored as `.yaml` source under
+`humanish/scenarios/*.yaml`:
+
+```yaml
+schema: humanish.scenario.v1
+id: core-browser-flow
+title: Core browser flow
+persona: synthetic-new-user
+goal: Reach the first meaningful product state with synthetic data.
+mode: browser
+browser:
+  startPath: /
+  steps:
+    - id: open-home
+      label: Open the app
+      action: goto
+      path: /
+      expect:
+        text: "Get started"
+    - id: submit-primary-action
+      label: Submit the primary action
+      action: click
+      selector: "button[type='submit']"
+      expect:
+        stateChanged: true
+```
+
+`humanish run --app-url <loopback-url>` uses the first executable browser
+scenario it finds. If no executable browser steps exist, Humanish falls back to
+the built-in two-step browser persona proof and says so in warnings/review.
+
+Live E2B desktop labs are an optional advanced path. Target projects that need
+them should install `@e2b/desktop` explicitly instead of receiving that
+substrate as part of the default Humanish package install. When a GitHub token is
+present, repo labels are redacted in durable artifacts by default; live stream
+auth URLs are used only by the attached watch server and are not persisted.

package/docs/ramp/README.md

@@ -0,0 +1,200 @@
+# Humanish Ramp
+
+Status: public-safe contributor and agent ramp.
+
+Use this page when you are starting cold on `humanish`. It is meant to be
+useful without chat history, private notes, local machine paths, or maintainer
+context.
+
+## First Read
+
+Read these in order:
+
+1. [`AGENTS.md`](../../AGENTS.md) for public boundary and engineering rules.
+2. [`docs/principles/invariants-and-defaults.md`](../principles/invariants-and-defaults.md) — the constitution: which rules are invariants and which are overridable defaults.
+3. [`README.md`](../../README.md) for install, commands, and package shape.
+4. [`docs/goals/current.md`](../goals/current.md) for the active product goal.
+5. [`docs/goals/proof-roadmap/goal.md`](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/goal.md) for the ratified proof architecture (repo-only; not shipped in the npm package, hence the absolute link).
+6. [`docs/product/open-source-install-experience.md`](../product/open-source-install-experience.md) for first-run UX.
+7. [`docs/roadmap/world-class-open-source-v0.md`](../roadmap/world-class-open-source-v0.md) for staged delivery history (historical; see its status banner).
+8. [`docs/architecture/observer.md`](../architecture/observer.md) for Observer architecture.
+9. [`docs/contracts/run-bundle.md`](../contracts/run-bundle.md) and [`docs/contracts/policy.md`](../contracts/policy.md) for proof contracts.
+10. [`docs/release/public-readiness-standard.md`](../release/public-readiness-standard.md) before deciding what must be scrubbed.
+11. [`docs/release/open-source-readiness.md`](../release/open-source-readiness.md) before touching public packaging or repository visibility.
+
+## Mental Model
+
+Humanish is a persona simulation harness for apps, CLIs, and agent-facing product
+flows.
+
+- `humanish/` is committed source: personas, scenarios, policy, adapters, and
+  lab manifests.
+- `.humanish/` is ignored runtime state: runs, Observer output, transcripts,
+  reviews, temporary clones, and local evidence.
+- Humanish source uses `.yaml` for human-authored simulation intent, `.ts` for
+  executable integration, and JSON/NDJSON for generated artifacts.
+- A run bundle is the source of truth.
+- The Observer is the projection that makes that truth reviewable.
+- Feedback commands turn verified evidence into public-safe issue drafts.
+
+If a change does not improve one of those loops, it probably belongs elsewhere.
+
+## Current State
+
+Humanish has a working public package shape and a safe first-run path:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm release:check
+pnpm humanish -- watch --json --no-open
+pnpm humanish -- verify --run latest --json
+```
+
+Implemented:
+
+- `commander` CLI with stable command help;
+- `init`, `doctor`, `run`, `watch`, `verify`, `review`, `runs`, and `feedback`;
+- synthetic run bundles;
+- public-safety verification with machine-readable `shareSafety.status`
+  (`share_ready`, `local_only`, or `blocked`);
+- mission-control Observer over UI, CLI, TUI, and Codex UI stream contracts;
+- public-safe feedback issue drafts without GitHub API mutation, gated on
+  `share_ready` evidence;
+- skills.sh-compatible agent skill;
+- first-class lab manifest resolution through `humanish/labs/*.yaml` and
+  ignored `.humanish/labs/*.yaml` overlays — `humanish.lab.v2` compositions
+  (`src/lab-config.ts`), one engine, no hardcoded lab kinds;
+- a pluggable actor registry with four registered actors
+  (`src/actor-registry.ts`); on the computer-use routes `actors[0].type` is a
+  real dispatch key;
+- a computer-use route and clone subject provider: `subject.source: app-url`
+  drives a lab-owner loopback app in a hosted desktop, and `subject.source:
+  clone` + `serve` clones, installs, and serves a real app in-sandbox from
+  config before the actor drives it (`src/cua-actor-lab.ts`);
+- experimental maintainer OSS meta-lab and disposable OSS smoke harness;
+- OSS dogfood setup-quality filesystem artifacts rendered from the Observer Files
+  tab with private-run previews suppressed by default.
+
+Still not good enough:
+
+- live `--app-url` browser proof now supports app-specific executable
+  `browser.steps` in `humanish/scenarios/*.yaml`, with headed provider-backed
+  public proof against two app/tool targets;
+- live PTY and Codex UI lanes need stronger completion health;
+- OSS lab lanes can report nested Observer health, target app readiness, actor
+  evidence, setup-quality filesystem checks, and nested browser step summaries
+  when a target app starts, but need repeated fresh-agent trials across more
+  disposable public apps;
+- Observer evidence has real screenshots/traces for browser app proof; richer
+  multi-step product journeys and broader multi-persona matrices remain the next
+  gap.
+
+## First Commands
+
+From a clean checkout:
+
+```bash
+git status --short --branch
+pnpm install --frozen-lockfile
+pnpm release:check
+pnpm humanish -- watch --json --no-open
+pnpm humanish -- runs --json
+pnpm humanish -- lab list
+```
+
+For local product feel:
+
+```bash
+pnpm humanish -- watch
+```
+
+For public OSS dogfood without credentials:
+
+```bash
+pnpm humanish -- lab run oss --dry-run --json --no-open
+pnpm humanish -- lab run oss-smoke --limit 1 --json
+```
+
+For private/local dogfood, author an ignored lab manifest under
+`.humanish/labs/` or `.humanish/local/labs/`, then invoke it explicitly with an
+ignored env file:
+
+```bash
+pnpm humanish -- watch .humanish/labs/local-dogfood.yaml --env-file .humanish/local/provider.env
+```
+
+## How To Pick Work
+
+Start from [`docs/goals/current.md`](../goals/current.md).
+
+Prefer work that makes Humanish more believable to a new maintainer:
+
+- a command becomes easier to run;
+- a run bundle becomes more truthful;
+- Observer evidence becomes more inspectable;
+- verification catches a real bad state;
+- feedback drafts become more actionable;
+- public-safety gates catch a class of leak or stale residue.
+
+If no GitHub issue exists for substantial work, draft one with the repo issue
+template before building. Use labels to communicate authority, area, risk, and
+required proof.
+
+## Quality Bar
+
+Do not close a change on narrative alone.
+
+Useful proof includes:
+
+- `pnpm release:check`;
+- focused unit or contract tests;
+- a generated run bundle under ignored `.humanish/`;
+- Observer screenshots or health output;
+- `humanish verify` results;
+- public-surface scan output;
+- fresh clone checks for packaging or release work.
+
+A green subset is not the same thing as complete coverage. If something is not
+covered, name it as a gap.
+
+## Public Boundary
+
+Assume this repository is public even when local or remote visibility says it is
+private.
+
+Never commit or paste:
+
+- PII or PHI;
+- secrets, keys, tokens, cookies, or raw env files;
+- raw private transcripts;
+- private screenshots;
+- private customer or patient data;
+- local machine paths;
+- private upstream code or operational details.
+
+Use synthetic examples, redacted evidence, and env var names without values.
+
+## Embarrassment Filter
+
+Before committing, ask:
+
+- Would this make sense to someone who found the repo through npm?
+- Would I be comfortable with this file quoted in a public issue?
+- Does this depend on private chat memory?
+- Does it mention removed docs, private machine paths, or internal-only names?
+- Does it claim product proof when it only proves a contract?
+
+If the answer is uncomfortable, rewrite it, synthesize it, or keep it out of the
+repo.
+
+## Hand-Off Format
+
+End substantial work with:
+
+- what changed;
+- what proof passed;
+- what remains uncertain;
+- the next best issue or command.
+
+Future agents should be able to continue from the repo, not from the previous
+chat transcript.