mimetic-cli 0.1.2 → 0.1.4

package/docs/contracts/policy.md

@@ -0,0 +1,273 @@
+# Policy Contract
+
+Date: 2026-06-02
+
+Status: v0 draft contract for credential, network, spend, redaction, and
+assisted-run boundaries.
+
+## Purpose
+
+Policy defines what a run may access, what it may persist, and what it may
+promote into public feedback. It keeps the public CLI useful without requiring
+private infrastructure, maintainer GitHub credentials, provider account access,
+or real product data.
+
+Policy records env var names, capability classes, decisions, and redaction
+status. It never records credential values.
+
+## Boundary Principles
+
+- Credential classes are separate; access to one class does not imply access to
+  another.
+- Dry-run and smoke proof should work with no provider spend.
+- Network and provider spend require explicit opt-in.
+- Public feedback requires redaction status `passed`.
+- Assisted runs are useful evidence, but they are non-comparable to autonomous
+  runs unless the assistance is modeled as an explicit actor event.
+- Maintainer GitHub credentials are not required for the public CLI feedback
+  path.
+
+## Credential Classes
+
+| Class | Examples | May Be Recorded | Must Not Be Recorded |
+| --- | --- | --- | --- |
+| Executor auth | local Codex login, local shell authority, E2B desktop token, browser automation session | class name, env var name, present/missing status, authority level | tokens, cookies, session ids, raw home config, private command history |
+| Product auth | target app test account, synthetic browser state, local fixture login | synthetic fixture id, auth state class, redaction status | real emails, passwords, customer accounts, patient accounts, production cookies |
+| Provider auth | model provider key, desktop provider key, package registry token | env var name, provider class, present/missing status, spend policy | API key values, auth-bearing stream URLs, billing account identifiers |
+| Maintainer auth | GitHub token, npm publish authority, repository admin rights | required/not-required, requested authority, explicit maintainer approval status | tokens, OAuth payloads, private org metadata, mutation authority by implication |
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.policy.v1
+kind: credentials
+credentials:
+  executor:
+    required: false
+    envNames: []
+    valuesPersisted: false
+  product:
+    required: false
+    fixture: synthetic-login-state
+    valuesPersisted: false
+  provider:
+    required: false
+    envNames:
+      - OPENAI_API_KEY
+      - E2B_API_KEY
+    availability: names_only
+    valuesPersisted: false
+  maintainer:
+    required: false
+    githubMutation: disabled
+    valuesPersisted: false
+```
+
+## Network Policy
+
+Network policy describes where a run may connect. It is not a hidden allowlist
+for credentials.
+
+| Mode | Meaning | Default For |
+| --- | --- | --- |
+| `no_network` | No external network calls. | contract docs, local unit tests |
+| `local_only` | Localhost and loopback only. | Observer, local fixtures |
+| `public_oss` | Public GitHub clone/fetch of owner/repo slugs only. | disposable OSS smoke |
+| `provider_substrate` | Explicit provider substrate such as hosted desktop streams. | live OSS lab with keys |
+| `custom_allowlist` | Adapter-declared public hosts. | target-specific adapters |
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.policy.v1
+kind: network
+mode: public_oss
+allowedHosts:
+  - github.com
+allowedRepoSlugs:
+  - developit/mitt
+denied:
+  - private remotes
+  - SSH remotes
+  - auth-bearing URLs
+  - target repo mutation
+```
+
+## Spend Policy
+
+Spend policy names when provider costs may be incurred.
+
+| Mode | Meaning |
+| --- | --- |
+| `no_spend` | No provider calls that can bill. |
+| `dry_run_only` | Only local contract proof; no live substrate. |
+| `explicit_live_provider` | Provider calls allowed because required env var names are present and operator intent is explicit. |
+| `maintainer_approved` | Reserved for publish, billing, or high-risk mutation workflows. |
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.policy.v1
+kind: spend
+mode: explicit_live_provider
+providerClasses:
+  - model
+  - desktop_substrate
+operatorIntent:
+  command: mimetic lab oss --json --no-open
+  explicit: true
+budget:
+  limit: unspecified
+  note: Operator-provided keys were present; values were not recorded.
+```
+
+## Redaction Policy
+
+Redaction gates public output. A run may keep ignored local artifacts for
+operator inspection, but public feedback cannot promote them unless the
+redaction result is `passed`.
+
+Required redaction gates:
+
+- run bundle verification;
+- Observer public-safety note;
+- feedback draft creation;
+- issue Markdown or issue URL rendering;
+- PR or issue comments that summarize local live evidence.
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.policy.v1
+kind: redaction
+status: passed
+deny:
+  - pii
+  - phi
+  - secrets
+  - tokens
+  - raw_private_transcripts
+  - private_screenshots
+  - auth-bearing URLs
+allow:
+  - synthetic_personas
+  - synthetic_fixtures
+  - env_var_names
+  - local ignored artifact paths
+promotion:
+  publicFeedbackAllowed: true
+```
+
+If redaction is `failed` or `unknown`, the public CLI must fail closed and tell
+the operator which class of material blocked promotion without printing the
+material itself.
+
+## GitHub Authority
+
+The default public CLI does not need a GitHub token.
+
+Allowed by default:
+
+- render local feedback drafts;
+- print public-safe issue Markdown;
+- print prefilled issue URLs;
+- include exact proof commands;
+- include redacted local artifact pointers.
+
+Not allowed by default:
+
+- create issues through the GitHub API;
+- update Projects;
+- resolve review threads;
+- merge PRs;
+- publish packages;
+- use maintainer tokens from the environment.
+
+Maintainer automation can be built later as a separate, token-explicit,
+dry-run-first tool. It must not be required for ordinary Mimetic feedback.
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.policy.v1
+kind: maintainer-authority
+github:
+  publicCliRequiresToken: false
+  defaultAction: print_issue_draft
+  apiMutation: disabled
+  tokenValuePersisted: false
+```
+
+## Assisted Runs
+
+An assisted run is any run where a human or outside tool performs work that the
+declared actor could not perform autonomously inside the declared substrate.
+
+Examples:
+
+- human manually logs in to a target account;
+- human edits the target repo during the run;
+- human copies hidden browser state into a fixture;
+- human clicks through product UI while the actor only observes;
+- operator restarts a provider substrate lane and continues the same run;
+- support staff or private upstream context resolves the blocker.
+
+Assisted runs can produce useful observations, but they are non-comparable to
+autonomous baselines. They must not be used as green regression proof unless the
+assistance is explicitly modeled as an actor event and the review says what was
+assisted.
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.policy.v1
+kind: run-comparability
+assistance:
+  status: assisted
+  comparableToAutonomousBaseline: false
+  reason: Human supplied setup that the actor could not perform.
+review:
+  verdictAllowed: blocked
+  publicFeedbackAllowed: true
+  notes: Assisted observation may become a spec issue, not a green proof.
+```
+
+## Policy Decision Envelope
+
+Policy checks should produce small, public-safe decisions that can be copied
+into run bundles, reviews, or feedback drafts.
+
+```yaml
+schema: mimetic.policy-decision.v1
+ok: true
+checkedAt: "2026-06-02T10:00:00.000Z"
+policies:
+  credentials:
+    ok: true
+    message: Required env var names are documented; values were not persisted.
+  network:
+    ok: true
+    message: Public OSS clone mode only.
+  spend:
+    ok: true
+    message: No provider spend in dry-run proof.
+  redaction:
+    ok: true
+    message: Redaction passed before feedback promotion.
+  comparability:
+    ok: true
+    message: Run is autonomous and comparable to dry-run baseline.
+```
+
+## Stop Conditions
+
+Stop before public promotion when:
+
+- a credential value appears in a prompt, artifact, issue, or PR body;
+- a stream URL includes auth material;
+- redaction is not `passed`;
+- a run used human assistance but is being treated as autonomous proof;
+- maintainer GitHub credentials would be required for the default public path;
+- provider spend is implied but not explicit;
+- network access exceeds the declared mode;
+- a fixture requires real personal, customer, patient, or private source data.

package/docs/contracts/run-bundle.md

@@ -0,0 +1,110 @@
+# Run Bundle Contract
+
+Date: 2026-06-02
+
+Status: v0 draft contract for bundle identity, layout, source state, history,
+lifecycle, and timing primitives.
+
+## Purpose
+
+A run bundle is the durable evidence packet for one harness run. It should be
+reviewable by a person, parseable by a tool, and safe to use as the source for
+feedback drafts and future public issues.
+
+## Minimum Bundle Shape
+
+```yaml
+schema: mimetic.run-bundle.v1
+runId: "<core run id>"
+mode: "dry-run|live"
+simCount: 1
+createdAt: "<ISO timestamp>"
+cwd: "<local cwd; public issue drafts must not copy this>"
+artifactRoot: ".mimetic/runs/<run-id>"
+source:
+  packageName: "<public package name or null>"
+  mimeticSource: "present|missing"
+  git:
+    schema: mimetic.git-state.v1
+    status: "clean|dirty|missing|unavailable"
+    capturedAt: "<ISO timestamp>"
+    head:
+      shortSha: "<short sha or null>"
+      refState: "attached|detached|unborn|unknown"
+    changes:
+      staged: 0
+      unstaged: 0
+      untracked: 0
+      total: 0
+    note: "<public-safe note>"
+lifecycle:
+  - at: "<ISO timestamp>"
+    event: "run.created"
+    message: "<public-safe message>"
+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|pass|fail|blocked|timed_out"
+```
+
+## Relative Artifact Layout
+
+For run id `example-2026-06-02t10-00-00-000z-proof`, the core layout is:
+
+```text
+.mimetic/runs/example-2026-06-02t10-00-00-000z-proof/run.json
+.mimetic/runs/example-2026-06-02t10-00-00-000z-proof/review.json
+.mimetic/runs/example-2026-06-02t10-00-00-000z-proof/review.md
+.mimetic/runs/example-2026-06-02t10-00-00-000z-proof/observer/observer-data.json
+.mimetic/runs/example-2026-06-02t10-00-00-000z-proof/events.ndjson
+.mimetic/runs/latest.json
+```
+
+Absolute paths, traversal segments, remotes, hosted logs, and private artifact
+URLs are not part of the core layout.
+
+## Latest And History
+
+The latest pointer is a small local index:
+
+```yaml
+schema: mimetic.latest-run.v1
+runId: "<run-id>"
+path: ".mimetic/runs/<run-id>"
+updatedAt: "<ISO timestamp>"
+```
+
+History entries use:
+
+```yaml
+schema: mimetic.run-history-entry.v1
+runId: "<run-id>"
+createdAt: "<ISO timestamp>"
+mode: "dry-run|live"
+path: ".mimetic/runs/<run-id>"
+```
+
+The latest pointer may move. Run bundle directories should not.
+
+## Contract Fixture Proof
+
+The core fixture proves:
+
+- deterministic run ids from explicit inputs;
+- stable relative artifact paths;
+- latest/history/lifecycle/timing records;
+- git status counts without branch names, remotes, file names, file paths, or
+  absolute directories;
+- no environment-specific nouns in `src/core`.
+
+Proof commands:
+
+```bash
+pnpm test
+pnpm typecheck
+```