mimetic-cli 0.1.2 → 0.1.3

package/docs/contracts/schemas.md

@@ -0,0 +1,511 @@
+# Contract Schema Index
+
+Date: 2026-06-02
+
+Status: v0 draft schema map for agent-ready contract work.
+
+## Purpose
+
+This document names the core Mimetic contracts before more implementation
+lands. It is intentionally public-safe: examples use synthetic ids, local
+relative artifact paths, env var names without values, and redacted evidence
+notes.
+
+Core contracts are reusable. Adapter contracts describe a target app, CLI, or
+workflow without leaking private upstream truth into core.
+
+## Ownership Rule
+
+| Layer | Owns | Does not own |
+| --- | --- | --- |
+| Core | Schema versions, run ids, artifact layout, lifecycle events, actor/substrate status, evidence shape, review, verification, redaction, feedback mechanics, latest/history indexes. | Product routes, real customer data, private screenshots, private transcripts, credential values, target-specific acceptance language. |
+| Adapter | Product routes, scenario/persona choices, app topology, env var names, network allowlists, coverage vocabulary, milestones, fixture data, target-specific proof expectations. | Generic run bundle schema, public-safety gates, provider secret values, raw private artifacts, GitHub mutation authority. |
+
+## Contract Index
+
+| Contract | Schema | Public-safe fixture |
+| --- | --- | --- |
+| Run bundle | `mimetic.run-bundle.v1` | `synthetic-run-bundle` |
+| Adapter | `mimetic.adapter.v1` | `synthetic-cli-adapter` |
+| Persona | `mimetic.persona.v1` | `synthetic-maintainer` |
+| Scenario | `mimetic.scenario.v1` | `first-run-smoke` |
+| Actor | `mimetic.actor.v1` | `synthetic-dry-run-actor` |
+| Substrate | `mimetic.substrate.v1` | `local-filesystem-substrate` |
+| Evidence stream | `mimetic.evidence-stream.v1` | `cli-stream-proof` |
+| Review | `mimetic.review.v1` | `contract-proof-review` |
+| Verification | `mimetic.verify-result.v1` | `five-check-verify` |
+| Policy | `mimetic.policy.v1` | `public-safety-policy` |
+| Feedback | `mimetic.feedback.v1` | `public-safe-feedback` |
+
+## Run Bundle
+
+Run bundles are the canonical evidence record. Observer data, review Markdown,
+feedback drafts, and issue text are projections from the bundle.
+
+Core-owned fields:
+
+- `schema`
+- `runId`
+- `mode`
+- `simCount`
+- `createdAt`
+- `artifactRoot`
+- `source.git`
+- `lifecycle`
+- `simulations`
+- `streams`
+- `events`
+- `redaction`
+- `artifacts`
+- `review`
+- `feedbackCandidates`
+
+Adapter-owned fields:
+
+- `source.packageName`
+- `source.mimeticSource`
+- `persona`
+- `scenario`
+- target-specific stream labels and public-safe summaries
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.run-bundle.v1
+runId: synthetic-run-bundle-2026-06-02t10-00-00-000z-proof
+mode: dry-run
+simCount: 1
+createdAt: "2026-06-02T10:00:00.000Z"
+artifactRoot: .mimetic/runs/synthetic-run-bundle-2026-06-02t10-00-00-000z-proof
+source:
+  packageName: fixture-app
+  mimeticSource: present
+  git:
+    schema: mimetic.git-state.v1
+    status: clean
+    capturedAt: "2026-06-02T10:00:00.000Z"
+    head:
+      shortSha: null
+      refState: unknown
+    changes:
+      staged: 0
+      unstaged: 0
+      untracked: 0
+      total: 0
+    note: public-safe synthetic fixture
+persona:
+  id: synthetic-maintainer
+  name: Synthetic Maintainer
+  source: mimetic/personas/synthetic-maintainer.yaml
+  sourceDigest: synthetic
+scenario:
+  id: first-run-smoke
+  title: First-run smoke
+  goal: Prove setup and verification without private data.
+  source: mimetic/scenarios/first-run-smoke.yaml
+  sourceDigest: synthetic
+lifecycle:
+  - at: "2026-06-02T10:00:00.000Z"
+    event: run.created
+    message: Created synthetic contract fixture.
+redaction:
+  status: passed
+  notes: Synthetic fixture only.
+artifacts:
+  run: run.json
+  reviewJson: review.json
+  reviewMarkdown: review.md
+  observerData: observer/observer-data.json
+  events: events.ndjson
+review:
+  schema: mimetic.review.v1
+  verdict: contract_proof_only
+  summary: Synthetic contract fixture generated.
+  gaps: []
+feedbackCandidates: []
+```
+
+## Adapter
+
+Adapters describe target-specific affordances without changing core contracts.
+
+Core-owned fields:
+
+- `schema`
+- `id`
+- normalized route/reference shape
+- public-safety validation of adapter references
+
+Adapter-owned fields:
+
+- `name`
+- `routes`
+- route descriptions
+- target-specific commands, paths, milestones, and vocabulary
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.adapter.v1
+id: synthetic-cli-adapter
+name: Synthetic CLI Adapter
+routes:
+  - id: help
+    path: synthetic-cli --help
+    description: Public-safe command discovery.
+  - id: dry-run
+    path: synthetic-cli run --dry-run --json
+    description: Generate a synthetic run bundle.
+```
+
+## Persona And Scenario
+
+Personas and scenarios define trial intent. They are adapter-owned source
+documents that core copies into run bundles by digest and id.
+
+Core-owned fields:
+
+- schema naming rules
+- id/source/sourceDigest references inside run bundles
+- redaction gates before persona/scenario text can appear in public feedback
+
+Adapter-owned fields:
+
+- persona traits
+- scenario goals
+- steps and expectations
+- accessibility or workflow constraints
+
+Synthetic fixture:
+
+```yaml
+persona:
+  schema: mimetic.persona.v1
+  id: synthetic-maintainer
+  name: Synthetic Maintainer
+  summary: Privacy-safe maintainer evaluating first-run clarity.
+  constraints:
+    - Do not use real personal data.
+    - Treat credentials as env var names only.
+scenario:
+  schema: mimetic.scenario.v1
+  id: first-run-smoke
+  title: First-run smoke
+  persona: synthetic-maintainer
+  goal: Prove setup, dry-run evidence, verification, and feedback drafting.
+  mode: dry-run
+  steps:
+    - name: Inspect help
+      expectation: Help explains setup and verification commands.
+    - name: Verify bundle
+      expectation: Verification passes without private data.
+```
+
+## Actor
+
+Actors execute or simulate the trial. Core records actor status; adapters
+choose which actor fits the target and authority level.
+
+Core-owned fields:
+
+- `schema`
+- `id`
+- `kind`
+- `status`
+- `startedAt`
+- `endedAt`
+- `durationMs`
+- `exitCode`
+- `reason`
+- redacted artifact pointers
+
+Adapter-owned fields:
+
+- actor prompt
+- target command
+- lane focus
+- product-specific acceptance notes
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.actor.v1
+id: synthetic-dry-run-actor
+kind: scripted
+status: passed
+startedAt: "2026-06-02T10:00:00.000Z"
+endedAt: "2026-06-02T10:00:01.000Z"
+durationMs: 1000
+exitCode: 0
+reason: Synthetic dry-run fixture completed.
+artifacts:
+  - path: actor.json
+    kind: trace
+    redaction: passed
+```
+
+## Substrate
+
+Substrates are the execution environments that run actors or render evidence.
+
+Core-owned fields:
+
+- `schema`
+- `kind`
+- `status`
+- lifecycle state
+- safe capability names
+- cleanup result
+
+Adapter-owned fields:
+
+- target start command
+- allowed env var names
+- allowed hosts
+- viewport needs
+- repo-specific setup commands
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.substrate.v1
+id: local-filesystem-substrate
+kind: local-filesystem
+status: ready
+capabilities:
+  - read committed source
+  - write ignored run artifacts
+cleanup:
+  status: not_required
+credentials:
+  envNames: []
+  valuesPersisted: false
+```
+
+## Evidence Streams
+
+Evidence streams normalize UI, browser, terminal, TUI, code-agent UI, artifact,
+and summary lanes for Observer and review.
+
+Core-owned fields:
+
+- `id`
+- `simId`
+- `kind`
+- `status`
+- `transport`
+- `updatedAt`
+- `completion`
+- `artifacts`
+- redacted terminal tail
+
+Adapter-owned fields:
+
+- stream label
+- route or command name
+- current step text
+- public-safe summaries
+- target-specific trace artifacts
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.evidence-stream.v1
+id: cli-stream-proof
+simId: sim-01
+kind: terminal
+label: CLI proof
+status: passed
+transport: snapshot
+updatedAt: "2026-06-02T10:00:01.000Z"
+terminal:
+  title: Synthetic terminal
+  format: plain
+  stdin: disabled
+  tail: "synthetic-cli verify passed"
+completion:
+  checkedAt: "2026-06-02T10:00:01.000Z"
+  exitCode: 0
+  reason: Synthetic command passed.
+  status: passed
+artifacts:
+  - label: review
+    path: review.md
+    kind: review
+```
+
+## Review
+
+Review summarizes whether evidence supports the claim. It does not replace
+verification or maintainer acceptance.
+
+Core-owned fields:
+
+- `schema`
+- `verdict`
+- `summary`
+- `gaps`
+
+Adapter-owned fields:
+
+- vocabulary labels
+- milestone names
+- product-specific gap language
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.review.v1
+verdict: contract_proof_only
+summary: Synthetic dry-run proves bundle shape, not product behavior.
+gaps:
+  - Live product behavior was not exercised.
+```
+
+## Verification
+
+Verification checks bundles and evidence pointers. It fails closed when schema,
+redaction, or artifacts are missing.
+
+Core-owned fields:
+
+- `schema`
+- `ok`
+- `run`
+- `bundlePath`
+- check names
+- check booleans
+- machine-readable error codes
+
+Adapter-owned fields:
+
+- optional target-specific checks
+- acceptance proof commands
+- coverage-specific check names
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.verify-result.v1
+ok: true
+run: synthetic-run-bundle-2026-06-02t10-00-00-000z-proof
+bundlePath: .mimetic/runs/synthetic-run-bundle-2026-06-02t10-00-00-000z-proof/run.json
+checks:
+  - name: run.json exists
+    ok: true
+    message: run.json present
+  - name: redaction passed
+    ok: true
+    message: redaction status must be passed
+```
+
+## Policy
+
+Policy names boundaries before an actor runs or feedback is promoted.
+
+Core-owned fields:
+
+- `schema`
+- policy kind
+- default action
+- validation outcome
+- redaction status
+- no-secret-value persistence rules
+
+Adapter-owned fields:
+
+- allowed env var names
+- allowed public hosts
+- app-specific credential manifest
+- network allowlist
+- scenario-specific authority
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.policy.v1
+kind: public-safety
+default: deny_sensitive_material
+deny:
+  - pii
+  - phi
+  - secrets
+  - tokens
+  - raw_private_transcripts
+  - private_screenshots
+allow:
+  - synthetic_personas
+  - synthetic_fixtures
+  - env_var_names
+credentialManifest:
+  - envName: OPENAI_API_KEY
+    valuePersisted: false
+network:
+  default: local_only
+  allowedHosts:
+    - localhost
+```
+
+## Feedback
+
+Feedback turns verified evidence into public-safe issue draft material. The
+default public CLI prints issue text or a prefilled URL; it does not mutate
+GitHub.
+
+Core-owned fields:
+
+- `schema`
+- run/source/evidence pointers
+- redaction status
+- idempotency key
+- proposed next state
+- failure owner enum
+- public issue eligibility gates
+
+Adapter-owned fields:
+
+- adapter id
+- scenario id
+- persona id
+- expected/actual language
+- target-specific reproduction steps
+- acceptance proof commands
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.feedback.v1
+run_id: synthetic-run-bundle-2026-06-02t10-00-00-000z-proof
+adapter_id: synthetic-cli-adapter
+scenario_id: first-run-smoke
+persona_id: synthetic-maintainer
+actor: synthetic-dry-run
+substrate: local-filesystem
+failure_owner: harness
+summary: Synthetic user needed clearer verification instructions.
+expected: Verification command is visible and public-safe.
+actual: Dry-run review noted missing live behavior proof.
+source_bundle: .mimetic/runs/synthetic-run-bundle-2026-06-02t10-00-00-000z-proof/run.json
+evidence:
+  - path: .mimetic/runs/synthetic-run-bundle-2026-06-02t10-00-00-000z-proof/review.md
+    kind: review
+    note: Public-safe synthetic review.
+redaction:
+  status: passed
+  notes: Synthetic fixture only.
+idempotency_key: synthetic-cli-adapter:first-run-smoke:verification-instructions
+proposed_next_state: watch
+acceptance_proof:
+  - pnpm mimetic -- verify --run latest --json
+```
+
+## Contract Stop Conditions
+
+Do not promote a contract fixture when:
+
+- it needs private artifact data to make sense;
+- it contains credential values instead of env var names;
+- it embeds raw hosted stream URLs or auth-bearing links;
+- it uses product-specific private nouns in a core-owned schema;
+- it implies GitHub mutation without explicit maintainer authority;
+- it cannot be proven with `git diff --check` and public-surface scanning.

package/docs/goals/current.md

@@ -0,0 +1,163 @@
+# Current Goals
+
+Status date: 2026-06-02
+
+This page is the current public-safe operating goal for `mimetic-cli`. Keep it
+short enough to reread before a coding session and concrete enough that future
+agents can choose useful work without private context.
+
+## North Star
+
+Mimetic should be the open-source CLI that lets a maintainer ask:
+
+> What happens when realistic synthetic personas try to use this app, CLI, or
+> agent-facing workflow?
+
+The answer should be observable, verifiable, public-safe, and easy to turn into
+actionable feedback.
+
+## Definition Of Awesome
+
+A world-class Mimetic run should eventually provide:
+
+- one human-friendly command that starts simulations and opens Observer;
+- multiple synthetic personas with different goals, patience, and skill levels;
+- UI, CLI, TUI, and code-agent lanes in one mission-control Observer;
+- real evidence: screenshots, terminal transcripts, lifecycle events, traces,
+  artifacts, and verifier output;
+- clear pass, fail, blocked, and gap states;
+- public-safe feedback issue drafts that do not mutate GitHub by default;
+- adapter contracts that let projects customize behavior without forking core;
+- release gates that prevent PII, PHI, secrets, private artifacts, and stale
+  internal residue from reaching the public repo or package.
+
+## Current Objective
+
+Make the public package and repo credible enough that an external maintainer can:
+
+1. install the skill;
+2. install `mimetic-cli`;
+3. run `mimetic init`;
+4. run `mimetic watch`;
+5. inspect Observer evidence;
+6. verify the bundle;
+7. produce a public-safe feedback draft;
+8. understand the next live-adapter path without reading chat history.
+
+## Near-Term Goals
+
+### 1. Public Readiness
+
+Keep the repository clean and public-safe.
+
+Acceptance:
+
+```bash
+pnpm release:check
+git diff --check
+```
+
+Fresh clone release checks should pass before public visibility changes.
+
+### 2. Future-Agent Ramp
+
+Maintain a durable ramp that tells future contributors and coding agents where
+to start, what exists, what remains, and what proof is required.
+
+Acceptance:
+
+- [`docs/ramp/README.md`](../ramp/README.md) stays current;
+- this page stays current;
+- README links both;
+- release package includes both docs directories.
+
+### 3. Fresh-Agent Install Proof
+
+Prove the skill and package setup flow from a disposable target app with no chat
+context.
+
+Target proof:
+
+```bash
+npm i -D mimetic-cli
+npx mimetic init --yes
+npx mimetic watch --json --no-open
+npx mimetic verify --run latest --json
+npx mimetic feedback issue --run latest --repo owner/repo --format markdown
+```
+
+The proof target must use synthetic personas and no real user data.
+
+### 4. Live Browser Adapter
+
+Graduate from synthetic UI lanes to a real browser journey against a local app.
+
+Minimum acceptance:
+
+- local app target detection;
+- browser launch;
+- route/state capture;
+- screenshot artifact;
+- run bundle references screenshot evidence;
+- Observer renders the screenshot;
+- `verify` fails closed if required evidence is missing.
+
+### 5. Live Terminal And Codex Lanes
+
+Make local PTY and Codex-style lanes reliable enough that Observer can show
+running, passed, failed, blocked, and timed-out states without human inference.
+
+Minimum acceptance:
+
+- sanitized transcript persistence;
+- explicit completion reason;
+- verifier checks redaction status;
+- Observer polling reflects lane completion;
+- no raw private transcript or credential values.
+
+### 6. OSS Lab Health Readback
+
+Make `mimetic lab oss` report nested lane health back into the top-level
+Observer instead of relying on a human watching the desktops.
+
+Minimum acceptance:
+
+- each lane records setup status;
+- each lane records nested Observer URL or absence;
+- each lane records nested verification status or blocker;
+- top-level Observer updates lane verdicts from evidence.
+
+## Non-Goals
+
+Do not make these default behavior:
+
+- live provider spend;
+- GitHub API mutation;
+- hosted queues, databases, or webhooks;
+- production deploys;
+- real customer/user/patient data;
+- private screenshots or raw transcripts;
+- private upstream artifacts.
+
+Maintainer-only tooling can exist later, but it must be opt-in, token-explicit,
+and dry-run-first.
+
+## Drift Alarms
+
+Stop and correct course if:
+
+- docs start depending on chat memory;
+- Observer gets prettier without stronger evidence;
+- feedback drafts imply product proof from synthetic contract proof;
+- tests pass while generated artifacts are not inspectable;
+- live labs require private infrastructure to look impressive;
+- package docs link to files that are not shipped;
+- public-safety gates become optional.
+
+## Best Next Work
+
+The next most useful engineering slice is fresh-agent install proof against a
+disposable public app fixture, followed by the first real browser adapter.
+
+That sequence keeps the package honest: first prove a new maintainer can start,
+then prove Mimetic can observe real product behavior.