humanish 0.107.0 → 0.109.0

package/docs/release/public-readiness-standard.md

@@ -1,210 +0,0 @@
-# Public Readiness Standard
-
-Status: researched working standard for public repository and npm release hygiene.
-
-This document separates real public-release risk from preference cleanup. The
-goal is to keep `humanish` safe, useful, and professional without deleting the
-durable context future contributors and agents need.
-
-## Sources Reviewed
-
-- [GitHub Docs: Removing sensitive data from a repository](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)
-- [GitHub Docs: Setting your commit email address](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address)
-- [GitHub Docs: Email addresses reference](https://docs.github.com/en/account-and-profile/reference/email-addresses-reference)
-- [GitHub Docs: About secret scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning)
-- [GitHub Docs: About push protection](https://docs.github.com/en/code-security/concepts/secret-security/about-push-protection)
-- [npm Docs: package.json files field](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#files)
-- [npm Docs: npm publish package contents](https://docs.npmjs.com/cli/v9/commands/npm-publish#files-included-in-package)
-- [npm Docs: Trusted publishing for npm packages](https://docs.npmjs.com/trusted-publishers/)
-- [OpenSSF Scorecard](https://scorecard.dev/)
-- [OpenSSF Source Code Management Platform Configuration Best Practices](https://best.openssf.org/SCM-BestPractices/)
-- [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
-
-## Decision Model
-
-Use four categories.
-
-### 1. Public Blockers
-
-These must be removed from the current tree, package payload, generated docs,
-screenshots, logs, and reachable history before the repo is public.
-
-- Secrets: API keys, provider tokens, npm/GitHub tokens, private keys, cookies,
-  session URLs, database URLs with credentials, `.env` values, auth-bearing
-  request headers, and raw credential material.
-- PHI, patient data, customer data, private user identifiers, private emails,
-  phone numbers, addresses, account IDs, billing IDs, raw transcripts, and raw
-  screenshots from private systems.
-- Private source snippets, internal-only product names, private roadmaps,
-  incident details, or operational data that would expose a non-public system or
-  customer relationship.
-- Built package output, source maps, docs, fixtures, or image assets that contain
-  any of the above.
-
-If a real secret was exposed, revoke or rotate it first. GitHub explicitly warns
-that history rewriting has side effects and may not be warranted once the secret
-is revoked. Rewrite history only when sensitive data remains materially risky
-after revocation, or when privacy, legal, contractual, or proprietary-source
-obligations require removal.
-
-### 2. Release-Gate Hygiene
-
-These should fail CI or release checks until fixed, but they are not all reasons
-to rewrite history.
-
-- Package payload is not inspected with `npm pack --dry-run`.
-- Scanner only checks tracked source and misses built `dist`, source maps, docs
-  packaged by `files`, or generated assets.
-- Binary public assets are not approved by path and checksum.
-- Docs link to files that are not shipped or not reachable from the public repo.
-- Runtime artifacts are included: `.humanish/`, run bundles, transcripts,
-  disposable clones, `.firecrawl/`, `.e2b/`, logs, tarballs, caches.
-- GitHub Actions use broad default permissions where read-only is enough.
-- Publish workflow uses long-lived npm tokens when OIDC trusted publishing is
-  available.
-- Secret scanning, push protection, or equivalent local scanners are absent from
-  the operating checklist.
-
-### 3. Acceptable Public Metadata
-
-These are acceptable when intentional and public-safe. They should not trigger
-panic cleanup or history rewrite by default.
-
-- Maintainer name, GitHub username, public repo owner, public issue links, and
-  public repository URLs.
-- A maintainer-approved public commit email. GitHub allows either a noreply
-  address or any configured email for commits. Noreply is a privacy preference,
-  not a universal public-release requirement.
-- Env var names without values, such as `OPENAI_API_KEY` or `E2B_API_KEY`.
-- Synthetic personas, synthetic screenshots, synthetic app data, and redacted
-  proof examples.
-- Public-safe ramp, goal, architecture, and roadmap docs that help future
-  contributors continue the project.
-
-### 4. Professionalism Cleanup
-
-These do not usually justify history rewrite, but they matter for an open-source
-repo people will judge quickly.
-
-- Chat residue, private-process phrasing, or emotional notes that do not help a
-  public maintainer.
-- Overly specific local machine paths or private workspace names, even when not
-  security-sensitive.
-- Broken links, stale commands, claims of product proof where only contract proof
-  exists, and docs that depend on private chat memory.
-- Screenshots that are technically synthetic but look sloppy, confusing, or
-  embarrassing.
-
-Professionalism cleanup should preserve useful context. Deleting all ramp or
-goal docs is worse than rewriting them into a public-safe form.
-
-## Commit Email Policy
-
-Noreply commit emails are preferred for privacy and consistency.
-
-Allowed commit metadata:
-
-- GitHub's two documented personal-account noreply forms:
-  `ID+USERNAME@users.noreply.github.com` and
-  `USERNAME@users.noreply.github.com`. The username-only form remains valid for
-  accounts using GitHub's pre-July 18, 2017 privacy form.
-- `github-actions[bot]@users.noreply.github.com` for GitHub Actions commits.
-- `noreply@github.com` for GitHub-generated commits.
-- Explicitly approved public maintainer emails.
-
-Blocked commit metadata:
-
-- Unknown personal emails.
-- Contractor, employee, patient, customer, vendor, or private-domain emails that
-  are not intentionally public for this project.
-- Any email that appears in logs, transcripts, screenshots, or docs as private
-  user/customer data rather than maintainer metadata.
-
-Do not force-rewrite `main` solely because a known maintainer-approved public
-email appears in a commit. Document the approval and update the scanner
-allowlist instead.
-
-## NPM Package Surface
-
-The npm package is its own public surface. The release gate must inspect:
-
-- `npm pack --dry-run --json` output;
-- compiled `dist`;
-- source maps;
-- all files matched by `package.json.files`;
-- always-included files such as `package.json`, `README.md`, and `LICENSE`;
-- docs, skills, screenshots, and other assets shipped for npm-page display.
-
-The package should use the `files` field as an allowlist, but that is not enough.
-The scanner must union tracked source files with the actual npm dry-run payload.
-
-Public binary assets are allowed only when:
-
-- the asset is intentionally public;
-- the asset is synthetic or redacted;
-- the path is allowlisted;
-- the SHA-256 checksum is pinned in the scanner.
-
-## GitHub And Supply Chain Posture
-
-Minimum public-repo posture:
-
-- branch protection or rulesets for `main`;
-- required CI before merge;
-- workflow permissions narrowed to read-only unless a job needs more;
-- no long-lived npm token in Actions for publish;
-- npm trusted publishing via OIDC where possible;
-- secret scanning and push protection enabled where available;
-- `SECURITY.md`, `CONTRIBUTING.md`, `LICENSE`, and clear issue flow;
-- periodic OpenSSF Scorecard or equivalent review.
-
-Nice-to-have after public launch:
-
-- dependency update automation;
-- CodeQL or comparable SAST;
-- release provenance and staged publishing where practical;
-- signed releases when the release process matures.
-
-## humanish Application
-
-For `humanish`, the honest standard is:
-
-- Keep `docs/ramp/` and `docs/goals/` if they are public-safe. They are essential
-  project memory for future coding agents and contributors.
-- Keep the package docs and skill docs focused on public install, public-safe
-  examples, and synthetic proof.
-- Do not commit `.humanish/`, `.firecrawl/`, screenshots from private systems,
-  raw run bundles, private transcripts, local env files, or packed tarballs.
-- Treat `dist` and source maps as public and scan them.
-- Treat the README screenshot as public and checksum-gated.
-- Allow a maintainer-approved public email in commit metadata; do not classify it
-  as a secret.
-- Rewrite history only for actual sensitive data, private source, or private
-  identity/customer data that remains materially risky.
-
-## Practical Checklist
-
-Before making the repository public or cutting a public package:
-
-```bash
-pnpm install --frozen-lockfile
-pnpm release:check
-git diff --check
-npm pack --dry-run --json
-```
-
-Also verify in GitHub:
-
-- `main` branch protection/ruleset is active;
-- secret scanning and push protection are enabled where available;
-- publish workflow uses OIDC trusted publishing;
-- failed workflow logs do not contain real secrets or private data;
-- visible issues, PRs, labels, and project metadata do not expose private context.
-
-If a check fails, classify it before reacting:
-
-1. Secret/PHI/private source? Rotate/revoke first, then consider history rewrite.
-2. Package leak or private artifact? Remove from package/tree and rerun gates.
-3. Unknown private identity metadata? Approve, redact, or rewrite based on risk.
-4. Public maintainer metadata? Usually allowlist and document.
-5. Sloppy public docs? Rewrite, do not delete useful project memory.

package/docs/roadmap/world-class-open-source-v0.md

@@ -1,311 +0,0 @@
-# World-Class Open-Source V0 Roadmap
-
-Date: 2026-06-01
-
-Status: HISTORICAL (banner added 2026-06-11). This was the staged v0 build
-plan; it is kept as delivery history and is not maintained. Several "Non-Goals
-For V0" have since shipped as explicit opt-ins (the OpenAI computer-use actor,
-live E2B desktop labs), and the lab schema is now `humanish.lab.v2`. For the
-live goal state read [`docs/goals/current.md`](../goals/current.md).
-
-## Target Outcome
-
-A maintainer can install `humanish` into a normal JavaScript app, let their
-coding agent run setup, and get a public-safe persona simulation harness with:
-
-- committed `humanish/` source plane;
-- ignored `.humanish/` runtime plane;
-- `commander` CLI;
-- safe `init`;
-- synthetic dry-run bundle;
-- verifier;
-- observer;
-- public-safe feedback issue draft;
-- clear docs and agent skill.
-
-## Stage 0: Repo Plan And Issue Queue
-
-Status: complete enough to start implementation.
-
-Proof:
-
-- GitHub project `humanish`;
-- seeded issues;
-- future-public boundary docs;
-- feedback issue-draft doctrine.
-- layout/install/goal docs;
-- implementation tickets for the install path.
-
-Primary issue queue:
-
-- [#13 package: scaffold npm package and Commander humanish binary](https://github.com/danielgwilson/humanish/issues/13)
-- [#14 init: scaffold committed humanish source and ignored .humanish runtime layout](https://github.com/danielgwilson/humanish/issues/14)
-- [#16 fixtures: create target app fixture for init, dry-run, verify, and observer proof](https://github.com/danielgwilson/humanish/issues/16)
-- [#7 cli: scaffold doctor, run --dry-run, review, verify, runs, and watch](https://github.com/danielgwilson/humanish/issues/7)
-- [#6 core: run IDs, artifact paths, git state, history, and lifecycle primitives](https://github.com/danielgwilson/humanish/issues/6)
-- [#10 observer: static mission-control viewer over fixture bundle](https://github.com/danielgwilson/humanish/issues/10)
-- [#5 feedback: specify public issue-draft CLI command](https://github.com/danielgwilson/humanish/issues/5)
-- [#15 skill: package agent setup guidance for installing Humanish](https://github.com/danielgwilson/humanish/issues/15)
-- [#17 release: open-source readiness, package metadata, license, and publish dry-run](https://github.com/danielgwilson/humanish/issues/17)
-
-## Stage 1: Package Scaffold
-
-Build the minimum npm package:
-
-- `package.json`;
-- TypeScript config;
-- `src/cli.ts`;
-- `commander`;
-- test runner;
-- lint/typecheck/check scripts;
-- binary name `humanish`;
-- stable JSON command envelope.
-
-Proof:
-
-```bash
-pnpm install
-pnpm check
-pnpm humanish -- --help
-```
-
-## Stage 2: Project Layout And Init
-
-Implement `humanish init`:
-
-- creates committed `humanish/`;
-- creates ignored `.humanish/`;
-- writes starter synthetic personas/scenarios/policies;
-- patches `package.json` scripts;
-- updates `.gitignore`;
-- supports `--dry-run`, `--yes`, and `--json`.
-
-Proof:
-
-```bash
-pnpm test
-pnpm humanish -- init --dry-run --json
-```
-
-Fixture proof should run against a temporary app fixture, not this repo only.
-
-## Stage 3: Run Bundle And Verify
-
-Implement a synthetic dry-run bundle:
-
-- run id;
-- manifest;
-- scenario/persona selection;
-- lifecycle events;
-- review skeleton;
-- redaction result;
-- artifact paths;
-- source/git state.
-
-Implement `humanish verify` over that bundle.
-
-Proof:
-
-```bash
-pnpm humanish -- run --dry-run --json
-pnpm humanish -- verify --run latest --json
-```
-
-## Stage 4: Observer
-
-Status: upgraded from static report to mission-control substrate for synthetic
-stream contracts.
-
-Implemented:
-
-- normalized `observer/observer-data.json` view model;
-- `events.ndjson` event stream contract;
-- stream-shaped sim lanes for UI, CLI, TUI, and Codex UI;
-- localhost watch server with no-store polling;
-- mission-control grid and focus mode;
-- terminal/TUI transcript stage;
-- evidence rail for events, artifacts, and gaps;
-- public-safe Codex UI stream contract with no raw provider payloads.
-
-Still next:
-
-- real browser actor adapter;
-- real PTY capture;
-- native Codex app-server adapter;
-- screenshot/trace gallery from real products;
-- reviewer acceptance gates over live product behavior.
-
-Proof:
-
-```bash
-pnpm humanish -- watch
-```
-
-If browser verification is added, use screenshots of the observer as proof.
-
-## Stage 5: Feedback Issue Draft
-
-Status: implemented for the synthetic dry-run bundle path.
-
-Implement:
-
-```bash
-humanish feedback draft --run latest --json
-humanish feedback issue --run latest --repo owner/repo --format markdown
-humanish feedback issue-url --run latest --repo owner/repo
-```
-
-Rules:
-
-- no GitHub API mutation;
-- no tokens;
-- no Projects;
-- redaction must pass;
-- dry-run-only claims are labeled as contract proof, not product proof;
-- issue body includes `humanish_feedback` block.
-
-Proof:
-
-```bash
-pnpm humanish -- feedback issue --run latest --repo example/app --format markdown
-```
-
-## Stage 6: Agent Skill
-
-Status: implemented as an installer-visible skills.sh skill under
-`skills/humanish/SKILL.md`.
-
-Create a shareable skill package that teaches agents to install and configure
-Humanish in target repos.
-
-It should cover:
-
-- `npm i -D humanish`;
-- `npx humanish init`;
-- committed vs ignored layout;
-- public-safety rules;
-- creating personas;
-- creating scenarios;
-- adding E2B/OpenAI env var names without values;
-- running doctor/run/watch/verify/feedback issue;
-- troubleshooting.
-
-Proof:
-
-```bash
-DISABLE_TELEMETRY=1 npx skills add . --list
-```
-
-Future proof: fresh-agent fixture follows the skill and reaches dry-run +
-issue draft.
-
-## Stage 6.5: Release Readiness
-
-Status: public package candidate, blocked only on explicit publish approval.
-
-Readiness lives in
-[`docs/release/open-source-readiness.md`](../release/open-source-readiness.md).
-The package has MIT metadata and public npm package shape. `npm publish`
-remains a human release action.
-
-## Stage 6.75: Self-Dogfood Config
-
-Status: implemented for dry-run contract proof.
-
-The repository now includes committed `humanish/` source files so Humanish can run
-against `humanish` itself. This makes `doctor` green on the repo, lets
-dry-run bundles read and digest `humanish/personas/synthetic-new-user.yaml` and
-`humanish/scenarios/first-run-smoke.yaml`, and keeps the live Codex TUI actor gap
-explicit. The live Codex TUI dogfood path and noninteractive `codex-exec`
-fanout hardening are tracked in
-[#28](https://github.com/danielgwilson/humanish/issues/28).
-
-## Stage 6.8: One-Command Watch UX
-
-Status: implemented for synthetic contract-proof stream lanes.
-
-`humanish watch` now creates a fresh four-lane synthetic run, renders Observer,
-starts a localhost watch server, opens the served Observer in the browser, and
-keeps the shell attached. The CI-safe form is `humanish watch --json --no-open`.
-`--sims <n>` remains the explicit scale control, and `--run <id>` watches
-existing evidence.
-
-## Stage 6.8: Lab Manifests
-
-Status: implemented as the generic source shape for reusable runs.
-
-Humanish now resolves `.yaml` lab manifests from committed `humanish/labs/`,
-ignored `.humanish/labs/`, ignored `.humanish/local/labs/`, or an explicit
-`.yaml` path. The human path is `humanish watch <lab>`; the agent/CI path is
-`humanish lab run <lab> --json --no-open`; discovery is `humanish lab list` and
-`humanish lab inspect <lab>`.
-
-Private or maintainer-only dogfood belongs in ignored lab manifests plus
-explicit `--env-file`; the public package should not hardcode private target
-names or require broad inherited job env.
-
-## Stage 6.9: Maintainer OSS Meta-Lab
-
-Status: implemented as repo-owned `humanish/labs/oss.yaml` plus compatibility
-aliases, with a retained disposable smoke harness.
-
-`humanish watch oss` opens the top-level Observer for authorized-repo meta-sims.
-Each lane is assigned a GitHub `owner/repo` slug from `--repos` or repeated
-`--repo` values and carries a headed E2B desktop for setting up Humanish inside
-that repo, starting the target app where feasible, and keeping the nested
-Observer visible.
-Default public targets should be apps, CLIs, or agent-facing tools with
-observable user surfaces. Frameworks, starters, and utility libraries are
-acceptable only when the explicit scenario is developer-experience testing.
-When live keys are present, Humanish launches E2B desktops, uploads the locally
-packed Humanish package, starts visible bootstrap terminals, clones each assigned
-repo inside the desktop, runs nested Humanish setup/proof commands, opens
-desktop/mobile app windows plus the nested Observer in the sandbox browser, and
-starts a nonblocking Codex actor attempt. Attached watch mode overlays live E2B
-stream URLs only in memory; durable run artifacts keep screenshots/status, not
-auth-bearing URLs. Private repos are maintainer-only, require an authorized
-runtime GitHub token, and redact repo labels in durable artifacts by default.
-
-`humanish lab run oss-smoke` keeps the earlier clone/discard proof loop: shallow
-clone lightweight public GitHub repositories into ignored `.humanish/tmp`, apply
-Humanish setup in disposable clones, run the four-lane synthetic Observer proof,
-verify it, record git-status evidence, write an ignored
-`.humanish/lab/oss/<run-id>/` report, and remove clones by default.
-
-Proof:
-
-```bash
-pnpm humanish -- watch oss --detach --open --repos CorentinTh/it-tools,drawdb-io/drawdb
-pnpm humanish -- lab run oss --dry-run --json --no-open --repos CorentinTh/it-tools,drawdb-io/drawdb
-pnpm humanish -- lab run oss-smoke --limit 1 --json
-```
-
-Next substrate work: upgrade nested app-url render proof into provider-backed
-browser personas that drive the target app and add richer process/filesystem
-telemetry for Codex actor health.
-
-## Stage 7: Local Browser And First Real Adapter
-
-Only after the package and dry-run path are stable:
-
-- local app target detection;
-- Playwright/browser substrate;
-- first scripted browser scenario;
-- browser-app adapter fixture.
-
-Proof:
-
-- real browser screenshots in `.humanish/runs`;
-- observer renders screenshots;
-- `verify` validates bundle.
-
-## Non-Goals For V0
-
-- live E2B as required first-run behavior;
-- OpenAI computer-use actor;
-- live GitHub mutation;
-- hosted queues/databases/webhooks;
-- provider spend as required first-run behavior;
-- production deploys;
-- real user/persona data;
-- private upstream artifacts.