# AGENTS.md

Agent instructions for `humanish`.

## Public Boundary

Assume this repository is public.

Hard rule: never commit, paste, preserve, or generate PII, PHI, secrets, keys,
tokens, raw private transcripts, private screenshots, private customer data,
private patient data, or private source snippets.

- Use synthetic personas, synthetic emails, synthetic screenshots, and redacted
  proof examples only.
- Do not copy `.env*`, credential files, hosted logs with identifiers, or
  artifact bundles that may contain sensitive user data.
- Do not let private upstream context leak into docs, examples, issue
  bodies, fixtures, tests, Observer screenshots, or generated run bundles.
- If an artifact might contain PII, PHI, credentials, or private operational
  context, summarize the shape and keep the raw artifact outside this repo.
- Public usefulness beats private convenience. When in doubt, redact,
  synthesize, or stop and ask.
- The repository owner's own projects, products, and domains are never named
  here — in code, labs, templates, docs, tests, or issue/PR text — without
  their explicit sign-off. A publicly deployed site is still a private
  project; deployment visibility does not make its name public material.
  Examples use neutral fictional products, and attestation fields in committed
  labs use placeholder owners/domains with a "replace with your own" note.
  (Named public third-party OSS subjects with kept receipts are the one
  established exception.)

## Mission

- Build a reusable CLI and harness standard for persona simulation.
- Keep reusable substrate in core code and product truth in adapters.
- Make product feedback loops cheap: run manifests, scenario profiles, actor
  traces, Observer views, review packets, and proof artifacts.
- Treat run bundles as the source of truth and Observer as the projection.

## Architecture Principles

- Adapter-first, not config sprawl: product-specific apps, ports, env
  allowlists, routes, scenarios, milestones, and review vocabulary belong in
  adapters.
- Core owns generic primitives: manifests, artifact layout, source packaging,
  actor orchestration, lifecycle events, Observer rendering, run review, and
  history indexing.
- CLI JSON envelopes must be truthful. Unsupported capabilities fail closed
  with structured errors.
- Proof artifacts are API surface. Treat paths, schemas, and review packets as
  durable contracts.
- Prefer fixtures and contract tests over prose claims.

## Development Rules

- Keep `main` clean. Use scoped branches or worktrees for feature work.
- Make small commits with explicit scope.
- When the repository owner explicitly grants autonomous shipping authority for
  a Humanish goal, do not stop at a PR handoff. Push the branch, open the PR,
  watch checks/reviews, address failures, merge when green, fast-forward main,
  and clean up the worktree/branch trail.
- Before substantial work, read [`docs/ramp/README.md`](docs/ramp/README.md)
  and [`docs/goals/current.md`](docs/goals/current.md).
- Do not commit generated proof artifacts, local env files, E2B/runtime caches,
  `.npmrc`, packed tarballs, or provider credentials.
- Before extracting from any source project, classify the code as core, CLI
  shell, Observer, adapter contract, or example adapter.
- Before publishing, run the release gates in
  [`docs/release/open-source-readiness.md`](docs/release/open-source-readiness.md).

## When Docs And Reality Disagree

Docs in this repo describe; tests and parsers enforce. Nothing written here
outranks what you can verify: when a doc conflicts with the code, a test, or
what a command actually prints, name the conflict in your hand-off or an issue
instead of resolving it in the doc's favor — a stale sentence followed
faithfully is how a harness rots. Accuracy outranks any rule in this file.

## Acceptance Bar

- A change is not done until it has command-level proof.
- Harness changes need tests or fixture artifacts that prove the contract.
- Adapter changes need at least one safe dry-run path and one realistic path
  where credentials allow it.
- Any "live-proven" claim in a PR body must cite a kept receipt — a
  `docs/goals/<goal>/receipts/` entry or a retained run id. Narrative alone is
  not proof.
- Provider-API test fixtures must derive from captured live wire shapes, never
  hand-authored from memory. A fixture written from memory can encode the same
  wrong field name as the code and pass in lockstep — that is how the 0.6.1
  parser bug shipped with green tests.
- End substantial work with what changed, what was checked, and what remains
  uncertain.