mimetic-cli 0.1.2 → 0.1.4

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

@@ -0,0 +1,129 @@
+# Self-Driving Harness Principles
+
+Date: 2026-06-01
+
+Status: initial repo doctrine for `mimetic-cli`.
+
+## Thesis
+
+`mimetic-cli` 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.
+`mimetic-cli` 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,138 @@
+# Open-Source Install Experience
+
+Date: 2026-06-01
+
+Status: product target for the first world-class `mimetic-cli` implementation.
+
+## Product Promise
+
+Drop Mimetic 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 mimetic-cli
+npx mimetic init
+npm run mimetic:doctor
+npm run mimetic:watch
+npm run mimetic:verify
+npx mimetic feedback issue --run latest --repo example/app --format markdown
+```
+
+## Two-Part Distribution
+
+### NPM Package
+
+The npm package owns executable behavior:
+
+- binary: `mimetic`;
+- CLI framework: `commander`;
+- commands: `init`, `doctor`, `run`, `watch`, `review`, `verify`,
+  `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/mimetic-cli --skill mimetic-cli
+```
+
+Installable repo skill: [`skills/mimetic-cli/SKILL.md`](../../skills/mimetic-cli/SKILL.md).
+
+The skill should teach the user's coding agent how to:
+
+- install `mimetic-cli`;
+- run `mimetic init`;
+- inspect the target app's routes and dev command;
+- create synthetic personas and scenarios;
+- configure local app targets;
+- document E2B and OpenAI env var names without storing values;
+- 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 `mimetic/` files and package-owned docs.
+
+## 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.
+
+## `mimetic init`
+
+`mimetic init` should:
+
+1. Detect package manager and app framework when possible.
+2. Create committed starter files under `mimetic/`.
+3. Create ignored runtime state under `.mimetic/`.
+4. Add `.mimetic/` 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": {
+    "mimetic": "mimetic",
+    "mimetic:doctor": "mimetic doctor",
+    "mimetic:run": "mimetic run --dry-run",
+    "mimetic:watch": "mimetic watch",
+    "mimetic:watch:ci": "mimetic watch --json --no-open",
+    "mimetic:verify": "mimetic verify"
+  }
+}
+```
+
+## Command Ladder
+
+| Command | Purpose | First version should |
+| --- | --- | --- |
+| `mimetic init` | Set up project-owned harness files | Scaffold committed `mimetic/`, ignored `.mimetic/`, package scripts |
+| `mimetic doctor` | Explain readiness | Check config, gitignore, app target, browser, env var names, redaction policy |
+| `mimetic run --dry-run` | Prove contract without app/browser/keys | Write synthetic run bundle |
+| `mimetic verify` | Validate bundle and public-safety gates | Fail closed on schema/evidence/redaction errors |
+| `mimetic review` | Build review packet from evidence | Summarize verdicts without inventing product proof |
+| `mimetic watch` | Run sims and watch the observer | Create a fresh four-lane bundle, render Observer, open it, and keep the shell attached |
+| `mimetic watch --json --no-open` | Agent/CI proof path | Create the same bundle and Observer artifacts without browser open or attached watch server |
+| `mimetic lab oss` | Watch public OSS meta-sims | Open the Observer-of-Observers with headed desktop lanes assigned by `--repos` |
+| `mimetic lab oss-smoke` | Try Mimetic on disposable public OSS clones | Shallow clone lightweight GitHub repos, run setup/proof/verify, report, and remove clones |
+| `mimetic 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.
+
+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 Mimetic package install.

package/docs/ramp/README.md

@@ -0,0 +1,167 @@
+# Mimetic Ramp
+
+Status: public-safe contributor and agent ramp.
+
+Use this page when you are starting cold on `mimetic-cli`. 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. [`README.md`](../../README.md) for install, commands, and package shape.
+3. [`docs/goals/current.md`](../goals/current.md) for the active product goal.
+4. [`docs/product/open-source-install-experience.md`](../product/open-source-install-experience.md) for first-run UX.
+5. [`docs/roadmap/world-class-open-source-v0.md`](../roadmap/world-class-open-source-v0.md) for staged delivery history and remaining work.
+6. [`docs/architecture/observer.md`](../architecture/observer.md) for Observer architecture.
+7. [`docs/contracts/run-bundle.md`](../contracts/run-bundle.md) and [`docs/contracts/policy.md`](../contracts/policy.md) for proof contracts.
+8. [`docs/release/public-readiness-standard.md`](../release/public-readiness-standard.md) before deciding what must be scrubbed.
+9. [`docs/release/open-source-readiness.md`](../release/open-source-readiness.md) before touching public packaging or repository visibility.
+
+## Mental Model
+
+Mimetic is a persona simulation harness for apps, CLIs, and agent-facing product
+flows.
+
+- `mimetic/` is committed source: personas, scenarios, policy, adapters, and
+  project intent.
+- `.mimetic/` is ignored runtime state: runs, Observer output, transcripts,
+  reviews, temporary clones, and local evidence.
+- 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
+
+Mimetic has a working public package shape and a safe first-run path:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm release:check
+pnpm mimetic -- watch --json --no-open
+pnpm mimetic -- 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;
+- mission-control Observer over UI, CLI, TUI, and Codex UI stream contracts;
+- public-safe feedback issue drafts without GitHub API mutation;
+- skills.sh-compatible agent skill;
+- experimental public OSS lab and disposable OSS smoke harness.
+
+Still not good enough:
+
+- live browser/user-journey proof is not yet first-class;
+- live PTY and Codex UI lanes need stronger completion health;
+- OSS lab lanes need automatic nested Observer health readback;
+- the package needs fresh-agent install proof on real disposable public apps;
+- Observer evidence needs real screenshots/traces once browser adapters land.
+
+## First Commands
+
+From a clean checkout:
+
+```bash
+git status --short --branch
+pnpm install --frozen-lockfile
+pnpm release:check
+pnpm mimetic -- watch --json --no-open
+pnpm mimetic -- runs --json
+```
+
+For local product feel:
+
+```bash
+pnpm mimetic -- watch
+```
+
+For public OSS dogfood without credentials:
+
+```bash
+pnpm mimetic -- lab oss --dry-run --json --no-open
+pnpm mimetic -- lab oss-smoke --limit 1 --json
+```
+
+## How To Pick Work
+
+Start from [`docs/goals/current.md`](../goals/current.md).
+
+Prefer work that makes Mimetic 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 `.mimetic/`;
+- Observer screenshots or health output;
+- `mimetic 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.

package/docs/release/open-source-readiness.md

@@ -0,0 +1,171 @@
+# Open-Source Release Readiness
+
+Date: 2026-06-02
+
+Status: public repository candidate after reviewed history cleanup. Actual
+`npm publish` remains a human release action and must not be run by an agent
+without explicit approval in the current context.
+
+Use [`docs/release/public-readiness-standard.md`](public-readiness-standard.md)
+as the public-cleanliness policy. The standard distinguishes real blockers such
+as secrets, PHI, private source, private screenshots, and raw credentials from
+acceptable public metadata such as maintainer-approved public commit email.
+
+## Package State
+
+- Package name: `mimetic-cli`
+- Version: `0.1.3`
+- Binary: `mimetic`
+- License: MIT
+- Repository: `https://github.com/danielgwilson/mimetic-cli`
+- npm access: public via `publishConfig.access`
+- npm contents: compiled `dist`, public docs directories, including ramp and
+  current-goal docs, `skills/`,
+  `README.md`, `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, and
+  `package.json`
+- GitHub Actions publish workflow: `.github/workflows/publish.yml`
+- optional live E2B peer: `@e2b/desktop`
+
+`prepack` runs the TypeScript build so a clean checkout can produce a usable
+tarball with `npm pack` or `npm publish`.
+
+## Skill State
+
+The installable agent skill lives at:
+
+```text
+skills/mimetic-cli/SKILL.md
+```
+
+This matches skills.sh discovery for `skills/<name>/SKILL.md`. The required
+frontmatter fields are present:
+
+```yaml
+name: mimetic-cli
+description: ...
+```
+
+Verification command:
+
+```bash
+DISABLE_TELEMETRY=1 npx skills add . --list
+```
+
+Expected install command after the repository is public:
+
+```bash
+npx skills add danielgwilson/mimetic-cli --skill mimetic-cli
+```
+
+## Public Boundary
+
+Release work must not include PII, PHI, secrets, keys, tokens, raw private
+transcripts, private screenshots, raw customer data, raw patient data, private
+source snippets, or generated run bundles.
+
+Allowed examples are synthetic or redacted only.
+
+## GitHub Visibility Gate
+
+The current tree and reachable Git history are the public surface being
+hardened here. The repository must not be made public until these checks pass
+from a fresh clone:
+
+- only the intended `main` branch is reachable;
+- no stale release tags point at pre-cleanup source;
+- history scans have no private upstream system names, absolute maintainer paths,
+  secret patterns, or generated runtime bundles;
+- reachable commit author and committer emails are GitHub noreply-style
+  addresses or explicitly approved public maintainer emails;
+- GitHub issues, PRs, labels, and project fields have been scanned or rewritten
+  for public-safe language.
+
+GitHub may still retain unreachable object caches or historical Actions logs
+internally. Treat those as residual platform-cache risk and delete old workflow
+runs before public launch if a stricter surface is required.
+
+History-check shape used during this audit:
+
+```bash
+git rev-list --all | xargs -n 32 git grep -n -I -i -e '<private-source-name>' -e '<absolute-local-path-marker>' -e '<workspace-path-marker>'
+git rev-list --all | xargs -n 32 git grep -n -I -E 'sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16}|BEGIN [A-Z ]*PRIVATE KEY|AIza[0-9A-Za-z_-]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}'
+```
+
+## Required Gates
+
+Run these before any public release candidate:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+pnpm public-surface:scan
+pnpm skill:check
+pnpm pack:dry-run
+git diff --check
+```
+
+`pnpm public-surface:scan` scans tracked files plus the npm dry-run payload,
+including built `dist/` output. It fails on common secret tokens, absolute local
+user paths, local workspace paths, unapproved durable commit email metadata,
+known private upstream system names, and binary public assets that are not
+explicitly allowlisted by SHA-256.
+
+## Tarball Inspection
+
+Use:
+
+```bash
+pnpm pack:dry-run
+```
+
+`pnpm pack:dry-run` delegates to `npm pack --dry-run` after `prepack` builds
+`dist`.
+
+The tarball must not include `.env*`, `.mimetic/`, generated run bundles,
+private screenshots, raw transcripts, `.npmrc`, tests, fixtures, internal
+operations notes, local runtime caches, or private operator packets. Public
+`docs/ramp/`, `docs/goals/`, and repo-local `AGENTS.md` files are allowed when
+they are synthetic, durable, and public-safe. Public image assets must remain on
+the scanner allowlist and keep their approved checksum.
+
+## Publish Procedure
+
+Only after maintainer approval:
+
+```bash
+pnpm release:check && npm publish --access public
+```
+
+No agent should run that command without explicit human approval in the current
+thread. That approval must come from the maintainer responsible for the release.
+
+## Trusted Publishing Setup
+
+The npm package page exists. Trusted Publishing should be configured for GitHub
+Actions before cutting the next tag:
+
+- provider: GitHub Actions
+- repository owner: `danielgwilson`
+- repository name: `mimetic-cli`
+- workflow filename: `publish.yml`
+- environment: blank
+- registry: npm public registry
+
+The workflow uses:
+
+- `permissions.id-token: write` for OIDC;
+- `permissions.contents: read`;
+- `actions/checkout@v6`;
+- `actions/setup-node@v6` with Node 24 and npm registry URL;
+- `npm publish --access public`;
+- no long-lived npm token secret.
+
+Future automated release flow after trusted publishing is configured:
+
+```bash
+pnpm release:check
+npm version patch -m "Release %s"
+git push origin main --tags
+```
+
+The publish job is tag-gated and only publishes when running on a `v*` tag.