humanish 0.0.1 → 0.15.0

package/docs/contracts/policy.md

@@ -0,0 +1,305 @@
+# 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: humanish.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 |
+| `authorized_private` | Token-backed clone/fetch of repos the maintainer is already authorized to access, with repo labels redacted by default. | local maintainer dogfood only |
+| `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: humanish.policy.v1
+kind: network
+mode: public_oss
+allowedHosts:
+  - github.com
+allowedRepoSlugs:
+  - CorentinTh/it-tools
+  - drawdb-io/drawdb
+denied:
+  - private remotes
+  - SSH remotes
+  - auth-bearing URLs
+  - target repo mutation
+```
+
+Private maintainer dogfood must use `authorized_private` plus a redaction gate.
+The repo name, screenshots, logs, source snippets, branch names, issue names,
+and stream URLs remain local-only. Public receipts may include only redacted
+labels, ignored artifact paths, and verifier status.
+
+## 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: humanish.policy.v1
+kind: spend
+mode: explicit_live_provider
+providerClasses:
+  - model
+  - desktop_substrate
+operatorIntent:
+  command: humanish lab run 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`.
+
+### Enforcement scope
+
+Be precise about what the automated gate does. `humanish verify` runs a
+public-safety scan that detects secret/key/token shapes and known local-path
+shapes, and fails closed on a match. It does **not** detect free-form PII/PHI
+(names, emails, phone numbers, dates of birth, MRNs, medical detail); avoiding
+those depends on using synthetic data and on reviewer judgment. Accordingly,
+`redaction: passed` means the automated secret/path scan found no matches, not a
+certification that the artifact is free of every class in the policy below. A
+first-class PII/PHI detector is planned (issue #108) and would move the listed
+PII classes from author-responsibility to enforced.
+
+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.
+
+`humanish verify` separates bundle validity from public promotion with
+`shareSafety`:
+
+| Status | Meaning |
+| --- | --- |
+| `share_ready` | The bundle passed verification and has no known local-only evidence posture. Feedback commands may render public issue drafts. |
+| `local_only` | The bundle passed verification and is useful local evidence, but should not be shared as-is. Current example: full-fidelity raw screenshots. |
+| `blocked` | Verification or public-safety checks failed. The bundle must not be promoted. |
+
+Feedback commands fail closed unless `shareSafety.status` is `share_ready`.
+This keeps the default raw-screenshot capture useful for local review without
+letting agents mistake "verify passed" for "safe to post publicly."
+
+Synthetic fixture:
+
+```yaml
+schema: humanish.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 Humanish feedback.
+
+Synthetic fixture:
+
+```yaml
+schema: humanish.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: humanish.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: humanish.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,358 @@
+# 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: humanish.run-bundle.v1
+runId: "<core run id>"
+mode: "dry-run|live"
+simCount: 1
+createdAt: "<ISO timestamp>"
+cwd: "[target-cwd]"
+artifactRoot: ".humanish/runs/<run-id>"
+source:
+  packageName: "<public package name or null>"
+  humanishSource: "present|missing"
+  git:
+    schema: humanish.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: humanish.review.v1
+  verdict: "contract_proof_only|pass|fail|blocked|timed_out"
+adapterScore:
+  schema: humanish.adapter-score.v1
+  namespace: "<adapter namespace>"
+  status: "pass|partial|fail"
+  score: 0
+  summary: "<public-safe adapter score summary>"
+  data: {}
+feedbackCandidates:
+  - schema: humanish.feedback-candidate.v1
+    id: "<stable candidate id>"
+    failure_owner: "harness|target-app|actor|environment|unknown"
+    evidence:
+      - path: "<relative run artifact path>"
+        kind: "review|state|log|trace|screenshot|filesystem"
+adapterArtifacts:
+  - schema: humanish.adapter-artifact.v1
+    namespace: "<adapter namespace>"
+    label: "<human-readable artifact label>"
+    path: "<relative run artifact path>"
+    kind: "state|review|log|trace|screenshot|filesystem|summary"
+    note: "<public-safe note>"
+```
+
+Persisted `run.json` files must not contain absolute local target paths. Runtime
+commands may return the caller's working directory in process-local JSON
+responses, but durable run bundles use the public-safe `[target-cwd]` marker.
+
+## Subject Provenance
+
+`subject` is an optional, additive top-level field: structured provenance for
+what the computer-use backend actually drove (code pin plus state story). It
+is absent on pre-existing bundles and on bundles from backends that have not
+adopted it. The field shape, its three sources (`clone`, `app-url`,
+`local-tree`), and the `humanish verify` checks that guard it are the schema doc's
+job, not this one: see the `subject` entry under
+[`schemas.md`](schemas.md#contract-schema-index). In short, `clone` carries a
+`repo`/`commit` pin, `local-tree` carries an `archiveSha256`/`dirty` pin
+instead (a dirty working tree cannot be commit-pinned), and `app-url` carries
+no code pin at all. No path, basename, or other host-machine string ever
+enters this field; identity is digests, a sha, a boolean, and counts.
+
+## Adapter Score
+
+`adapterScore` is optional and namespaced. It lets a downstream adapter summarize
+its own product-specific rubric without adding product nouns to core schemas.
+Core validates only `schema`, `namespace`, `status`, `score`, `summary`, and
+that optional `data` is a record.
+
+Terminal-product runs record `adapterScore` additively. Browser/computer-use
+runs treat `status: fail` as product-red: the route result returns `ok: false`,
+the persisted `review.verdict` becomes `fail` when it was pass-like, and a
+generic adapter gap is appended. The bundle remains valid evidence for
+`humanish verify` because the failure is an observed product-acceptance outcome,
+not corrupt evidence.
+
+## Adapter Artifacts
+
+`adapterArtifacts` is optional and namespaced. It lets a downstream adapter
+attach product/state proof outputs to the Humanish bundle without making the
+payload shape a core concept. Core validates only:
+
+- `schema: humanish.adapter-artifact.v1`;
+- non-empty `namespace`, `label`, `path`, and `note`;
+- local relative paths only, with no absolute paths, traversal, or URLs;
+- supported generic artifact kinds.
+
+Adapters that use browser/shared-world hooks may write files under the ignored
+run directory and return relative references through `deriveArtifacts`. Core
+stores those references, Observer links them, and `humanish verify` fails closed
+when any referenced file is missing. The adapter owns the artifact payload schema
+under its namespace.
+
+## Lane Grouping Metadata
+
+Multi-lane browser/shared-world routes may carry optional lane grouping metadata:
+
+```yaml
+actors:
+  - type: openai-computer-use
+    lanes:
+      - id: lane-01
+        actorType: viewer
+        surface: intake
+        caseGroup: case-001
+```
+
+For repeated lanes, authors can use compact roster groups. The parser expands
+each group into deterministic `lanes[]` before the engine runs:
+
+```yaml
+actors:
+  - type: openai-computer-use
+    roster:
+      - id: viewer
+        count: 3
+        actorType: viewer
+        surface: review-queue
+        caseGroup: case-001
+        persona: curious-reviewer
+        device: desktop
+```
+
+The generated lane ids are `<group.id>-01`, `<group.id>-02`, and so on. `roster`
+is mutually exclusive with explicit `lanes`, homogeneous `count`, and
+`laneFocus`; it is an authoring convenience, not a second runtime shape.
+
+These fields are adapter-owned labels, not core enums. They let downstream
+projects express "N actors of M app-defined types across S surfaces" without
+teaching Humanish private product nouns. Values must be public-safe tokens and
+are projected into:
+
+- the preflight lane plan;
+- shared-world `laneWindows[]` and `outcomes[]`;
+- Observer `laneGroups[]`;
+- human-readable Observer stream labels.
+
+`actorType` is deliberately separate from `actors[0].type`. The latter selects
+the Humanish execution actor, such as `openai-computer-use` or `scripted-browser`.
+The former is the app-defined simulated user bucket, such as `viewer`,
+`maintainer`, or a downstream adapter's own role label.
+
+## Completion And Meaningful-Use Verdicts
+
+Each live stream may include `completion` when the harness has enough evidence
+to judge the lane. Completion state is deliberately compact and public-safe:
+it records actor/app/nested-Observer status, terminal tails that have already
+passed redaction, and optional setup-quality evidence.
+
+`completion.meaningfulUse` is the first-class scored verdict for meta-lab
+lanes where a coding agent is asked to set up Humanish inside another project.
+It is a rubric over already-redacted evidence, not a raw transcript dump.
+
+```yaml
+completion:
+  status: "running|passed|failed|blocked|timed_out"
+  reason: "<public-safe lane summary>"
+  actorStatus: "not_started|running|passed|failed|blocked|timed_out|suspended|unknown"
+  appStatus: "not_started|running|blocked|failed|missing|unknown"
+  nestedObserverPresent: true
+  nestedVerifyPassed: true
+  visualStatus: "not_started|visible|blocked|unknown"
+  meaningfulUse:
+    schema: humanish.meaningful-use-score.v1
+    status: "pass|partial|fail"
+    score: 0
+    summary: "<public-safe score explanation>"
+    hardFailures:
+      - "<hard failure that prevents green proof>"
+    components:
+      - id: "setup-correctness"
+        label: "Setup correctness"
+        status: "pass|partial|fail"
+        score: 0
+        detail: "<public-safe detail>"
+```
+
+The current OSS meta-lab rubric totals 100 points:
+
+- setup correctness: 15;
+- filesystem evidence: 10;
+- nested Humanish evidence: 20;
+- actor activity: 15;
+- product surface: 15;
+- feedback quality: 25.
+
+A score of 80 or higher is `pass` only when no hard failure is present and
+every rubric component passes. Scores from 45 through 79, or scores of 80 or
+higher with any non-passing component, are `partial`. Scores below 45,
+failed/timed-out bootstraps, missing nested Humanish proof, required actor
+failure, or completed lanes without a running visible product surface are
+`fail`.
+
+## Relative Artifact Layout
+
+For run id `example-2026-06-02t10-00-00-000z-proof`, the core layout is:
+
+```text
+.humanish/runs/example-2026-06-02t10-00-00-000z-proof/run.json
+.humanish/runs/example-2026-06-02t10-00-00-000z-proof/review.json
+.humanish/runs/example-2026-06-02t10-00-00-000z-proof/review.md
+.humanish/runs/example-2026-06-02t10-00-00-000z-proof/observer/observer-data.json
+.humanish/runs/example-2026-06-02t10-00-00-000z-proof/events.ndjson
+.humanish/runs/latest.json
+```
+
+Absolute paths, traversal segments, remotes, hosted logs, and private artifact
+URLs are not part of the core layout.
+
+## Filesystem Evidence
+
+Filesystem setup evidence is first-class when a lane asks an actor to install
+or configure Humanish inside another project. It is not a repo dump.
+
+The durable artifact kind is `filesystem`. The current schema is:
+
+```yaml
+schema: humanish.setup-quality.v1
+status: "passed|needs_review|blocked"
+redaction:
+  status: "passed"
+  rawPreviews: "included|suppressed"
+checks:
+  - id: "humanish-config"
+    ok: true
+tree:
+  - path: "humanish/config.ts"
+    type: "file"
+previews:
+  - path: "humanish/config.ts"
+    language: "typescript"
+studyQuality:
+  schema: humanish.study-quality.v1
+  rating: "none|ceremonial|useful|high_leverage"
+  checks:
+    - id: "coverage-customized"
+      ok: true
+  signals:
+    appUrlProofBlocked: false
+    appUrlProofMentioned: true
+    actorInsightCaptured: true
+    coverageCustomized: true
+    personaCustomized: true
+    scenarioCustomized: true
+packageScripts:
+  humanish: "humanish watch"
+humanish:
+  configPresent: true
+  personaCount: 1
+  scenarioCount: 1
+  packageScriptPresent: true
+  gitignoreContainsRuntimeIgnore: true
+```
+
+For public OSS runs, previews may include allowlisted setup files such as
+`package.json`, `.gitignore`, `humanish/config.ts`, and
+`humanish/labs/*.yaml` / `humanish/personas/*.yaml` /
+`humanish/scenarios/*.yaml`. For token-backed or private maintainer runs, raw
+previews are suppressed by default. Generated state, `.git`, `.env*`, `.npmrc`,
+browser profiles, `node_modules`, `.humanish/`, and arbitrary source files are
+not included. `studyQuality` is deliberately structural: it stores booleans,
+checks, and a rating so private runs can preserve the useful quality signal
+without committing raw private persona, scenario, or coverage text.
+
+## Latest And History
+
+The latest pointer is a small local index:
+
+```yaml
+schema: humanish.latest-run.v1
+runId: "<run-id>"
+path: ".humanish/runs/<run-id>"
+updatedAt: "<ISO timestamp>"
+```
+
+History entries use:
+
+```yaml
+schema: humanish.run-history-entry.v1
+runId: "<run-id>"
+createdAt: "<ISO timestamp>"
+mode: "dry-run|live"
+path: ".humanish/runs/<run-id>"
+```
+
+The latest pointer may move. Run bundle directories should not.
+
+## Verify Result Share Safety
+
+`humanish.verify-result.v1` includes a machine-readable `shareSafety` block in
+addition to `ok`, `checks[]`, and `warnings[]`:
+
+```yaml
+schema: humanish.verify-result.v1
+ok: true
+shareSafety:
+  status: "share_ready|local_only|blocked"
+  reasons:
+    - code: "RAW_SCREENSHOTS"
+      message: "Full-fidelity screenshots are present ..."
+```
+
+`ok: true` means the bundle is valid evidence. It does not necessarily mean the
+bundle is safe to promote into a public issue. Public promotion should branch on
+`shareSafety.status`:
+
+- `share_ready`: feedback draft commands may render public issue payloads;
+- `local_only`: keep the run local or generate a redacted replacement bundle;
+- `blocked`: fix the verification or public-safety failure first.
+
+## 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
+```