pincer-workflow 0.7.0 → 1.0.0

package/template/docs/engine.md

@@ -0,0 +1,236 @@
+# The PINCER engine
+
+The contract between the stage skills and the scripts under `scripts/pincer/`. The
+skills are prose for an agent and bend to the agreement; the engine is the part that
+does not bend. It stamps the receipts, records the acceptance, validates the evidence
+and generates the project's copies. Read this when you want to know exactly what a
+script does, or when a session has to recover from a mistake.
+
+## What the engine is
+
+Four entry points over one dependency-free Node core (`scripts/pincer/`, Node 22 or
+newer, CommonJS, `node:` modules only). `scripts/pincer-ticket.sh` moves a ticket
+through its lifecycle and is the only writer of its lifecycle fields.
+`scripts/pincer-status.sh` reports where the work stands and gates the stages.
+`scripts/pincer-evidence.cjs` validates and digests evidence.
+`scripts/pincer-blueprint.cjs` reads the repository (recon), writes the agreement
+(write) and generates the project copies (generate); `scripts/sync-prompts.sh` is
+`generate` under its old name. Every entry point resolves the project root from
+`--root <dir>`, else the nearest directory up from the working directory that holds
+`harness.json`, else the working directory. The engine never talks to the forge; the
+skills do, with `gh`.
+
+## harness.json
+
+The machine-readable agreement at the repository root, written by the blueprint stage
+through `write` and read by every other stage. Schema 1. Unknown keys are kept and
+ignored. `blueprint` and `status` never appear under `stages`: they are always on and
+the validator rejects an entry for them.
+
+| Field | Values | Default |
+|---|---|---|
+| `schema` | `1` | required |
+| `project.kind` | `greenfield`, `brownfield` | required |
+| `project.name`, `project.reason` | text | `""` |
+| `people[]` | `{name, role, accepts}`, at least one with `accepts: true` | required |
+| `systems.forge` | `github`, `none`, `other` | `none` |
+| `systems.remote` | URL without credentials | `""` |
+| `systems.ci` | true, false | `false` |
+| `systems.deploy`, `systems.secrets` | text | `""` |
+| `repo.branches` | `per-ticket`, `main` | `main` |
+| `repo.pr` | true, false | `false` |
+| `repo.merge` | `merge`, `squash`, `rebase` | `merge` |
+| `repo.protection` | text | `""` |
+| `repo.checks` | list of commands | `[]` |
+| `homes.specs`, `homes.tickets`, `homes.evidence` | relative paths inside the repository, no leading `/` or `..` | `specs`, `tickets`, `evidence` |
+| `stages.plan` | `{on, spec: file or forge, gate, reason}` | `on: true, spec: file, gate: ""` |
+| `stages.narrow` | `{on, tickets: file or forge, reason}` | `on: true, tickets: file` |
+| `stages.code` | `{on, implementer, reason}` | `on: true, implementer: false` |
+| `stages.evaluate` | `{on, where: local or pr, evidence, reason}` | `on: true, where: local, evidence: true` |
+| `stages.release` | `{on, audit: tree or pr, reason}` | `on: true, audit: tree` |
+| `roster.plan`, `roster.narrow`, `roster.code`, `roster.evaluate` | lists of agent names from the library | `[]` |
+| `models.stages.<stage>` | a tier or `{tier, effort}`; `plan`, `narrow`, `code`, `evaluate`, `release` | not set |
+| `models.agents.<name>` | a tier or `{tier, effort}`, for a library agent name | not set |
+| `models.map.<platform>.<tier>` | a model name, for `claude`, `codex`, `copilot` and `strong`, `standard`, `fast` | none |
+| `open` | list of text | `[]` |
+| `firstJob` | text | `""` |
+
+A file that fails validation makes every entry point print `harness.json: <problem>`
+and exit 3. A missing file prints `harness.json: no agreement yet: run /pincer-blueprint`
+and exits 3, except for `status`, which reports it and exits 0, and the always-on gates.
+
+## Ticket fields and receipts
+
+A ticket is `<homes.tickets>/T-NN-<slug>.md` with a closed `---` frontmatter of
+unique, unindented `key: value` lines; `#` starts a comment, except in
+`accepted_words`, which is read verbatim. Required keys: `ticket`, `status`, `size`
+(`S`, `M`, `L`), `depends_on` (an inline list such as `[T-01]`). Optional: `spec` (a
+relative `.md` path that must exist), `forge` (free text), `timeout` (seconds, default
+600). The body needs one `## Acceptance Criteria` section with checkboxes and one
+`## Verification` section with one fenced `bash` block.
+
+The eight lifecycle fields are written only by `scripts/pincer-ticket.sh`:
+
+| Field | Written by | Format |
+|---|---|---|
+| `status` | start, done | `open`, `in_progress`, `done` |
+| `started` | start | ISO UTC timestamp, `YYYY-MM-DDTHH:MM:SSZ` |
+| `last_check` | verify | `<timestamp> running|passed|failed|interrupted <hash>` |
+| `verified` | verify, on a pass | `<timestamp> <hash>` |
+| `finished` | done | timestamp |
+| `accepted` | accept | timestamp |
+| `accepted_by` | accept | a name from `people` with `accepts: true` |
+| `accepted_words` | accept | what the person said, verbatim, on one line |
+
+The hash is the first 12 hex characters of sha256 over the Verification block: the
+lines inside the fence joined with newlines plus one trailing newline. Change the
+block and the receipt no longer matches it. `verify` writes `running` first, runs the
+block with `bash -eo pipefail` under the ticket's timeout, then writes `passed`
+(together with `verified`), `failed`, or `interrupted` for a signal or a timeout. A
+ticket is ready when `verified` carries the current hash and the `last_check` for that
+hash is not a failure.
+
+## Commands and exit codes
+
+Exit codes everywhere: 0 ok, 1 refused (the reason on stderr), 2 usage, 3 no
+agreement, stage off or invalid `harness.json`, 130 interrupted.
+
+`scripts/pincer-ticket.sh` runs `node scripts/pincer/cli.cjs ticket <verb> <T-NN>`:
+- `start T-NN`: `open` to `in_progress`, stamps `started`. Refuses when a `depends_on` ticket is not done and ready, when the ticket is already done, and with exit 3 when `harness.json` is missing or `stages.code.on` is false.
+- `verify T-NN`: starts an open ticket, runs the block, stamps the receipt only on exit 0. A failed check exits 1 and prints `FAILED (exit N)`; a block with no runnable command is refused.
+- `done T-NN`: `in_progress` to `done` when the receipt matches the current block, no newer check failed, and every criterion is ticked; stamps `finished`.
+- `accept T-NN --by "<name>" --words "<their words>"`: on a done ticket writes the three acceptance fields together; refuses a name that is not an acceptor and empty words.
+
+`scripts/pincer-status.sh` runs `node scripts/pincer/cli.cjs status`: the report, or
+`--json` for data. `--stage <name>` prints `on` and exits 0, or the reason and exits 3;
+a name that is not a stage exits 2. An invalid `harness.json` still renders the report
+and then exits 3.
+
+`scripts/pincer-evidence.cjs` runs `node scripts/pincer/cli.cjs evidence`:
+`validate <manifest> [--candidate <sha>]` prints `ok <candidate>` or one
+`evidence: <manifest>: <problem>` line each and exits 1; `digest <file>...` prints
+`<sha256>  <file>` per file.
+
+`scripts/pincer-blueprint.cjs` has three verbs:
+- `recon [--json] [--network]` runs `node scripts/pincer/cli.cjs recon`: the kind, the reasons, the facts, the prefill and what it could not see. Offline unless `--network`, which lets it ask `gh`.
+- `write [--answers <file>]` runs `node scripts/pincer/cli.cjs write`: validates the answers (default: `harness.json` itself), writes `harness.json`, renders the agreement between the markers in `AGENTS.md`, runs the generator. Validation problems: one per line, exit 3, nothing written. One agreement marker without the other: exit 1, nothing written.
+- `generate [--harness <file>] [--platform <claude,codex,copilot|all>] [--overwrite]` runs `node scripts/pincer/cli.cjs generate`, also reachable as `scripts/sync-prompts.sh`. See Generation below.
+
+## Stage gate
+
+Every stage skill's first step runs `scripts/pincer-status.sh --stage <name>`.
+`blueprint` and `status` are always on and print `on` even without `harness.json`. The
+other five (`plan`, `narrow`, `code`, `evaluate`, `release`) print `on` when the
+agreement has them on, else the reason (`no agreement yet: run /pincer-blueprint`,
+`stage <name> is off in harness.json`, or the validation problem) with exit 3.
+`scripts/pincer-ticket.sh start` and `verify` apply the same gate for `code`. The hook
+on Claude Code does not read `harness.json`; the gate lives in the scripts, so it holds
+on every platform.
+
+## Acceptance
+
+The floor has two halves: a ticket is `done` only on a receipt, and accepted only when
+a named person said so. `accept` writes `accepted`, `accepted_by` and `accepted_words`
+together, and the validator refuses a ticket carrying one or two of the three. The name
+must be in `people` with `accepts: true`; the words are the person's, quoted as they
+said them, never a paraphrase. Acceptance gates nothing in the lifecycle (the next
+ticket may start), but status warns about every done ticket without it and names the
+next step: `/pincer-release` when that stage is on, else the `accept` command itself.
+Release passes only when every done ticket of the change carries it. The agent runs
+`accept` only after the person said so.
+
+## Evidence manifest schema 1
+
+`<homes.evidence>/<candidate>/manifest.json`, where the directory's basename is the
+candidate's full commit id. Top-level keys, all required and no others: `schema` (1),
+`candidate` and `base` (40 hex characters), `created` (UTC timestamp), `spec` (a path
+that exists), `environment` (`tools` and `limitations`, each a list of short
+strings), `checks`, `visual_review`, `artifacts`. Each check has `id` (`C-NN`), `kind` (`command`, `review`, `visual`),
+`required`, `result` (`passed`, `failed`, `unverified`), `command` (required for a
+command check), `log` (an artifact path) and an optional `note`; a required check
+must be `passed`. `visual_review` has `applicable` and, when false, `reason`.
+`artifacts` maps paths inside the manifest's directory to their sha256, and the
+digests must match the files. The validator checks that the record is consistent, not
+that the commands ran. Status reports `Evidence:` per manifest and release reads the
+same validator.
+
+## Generation and .new sidecars
+
+`generate` reads the library (`.claude/pincer/library/`, the project's own copy) and
+the agreement. For every stage that is on it copies `library/stages/<stage>/` to
+`.claude/skills/pincer-<stage>/` (the project copy: edit this one), writes the thin
+`.claude/commands/pincer-<stage>.md`, and per installed platform the Codex skill
+`.agents/skills/pincer-<stage>/SKILL.md` (`/pincer-x` mentions become `$pincer-x`,
+`$ARGUMENTS` becomes a sentence) and the Copilot prompt
+`.github/prompts/pincer-<stage>.prompt.md`, both derived from the project copy as it
+stands. Agents named by the rosters of the stages that are on are rendered to
+`.claude/agents/<name>.md`: the library copy with its `tier:` line dropped and the
+model and effort of its tier appended; with Codex installed each also gets
+`.codex/agents/<name>.toml` (see Models). The model and effort lines of an agent file
+and of a project copy belong to the generator and the tier belongs in the agreement: a
+file that differs from the library copy only in those lines is the generator's to
+overwrite or remove when no baseline records it; with a baseline in `.pincer.json`, a
+hand-written model line conflicts like any other edit and gets a sidecar.
+
+Baselines live in `.pincer.json` under `generated` when the installer wrote it. A
+target whose hash matches its baseline or the fresh content is overwritten; one that
+matches neither was edited by hand and is kept, with the fresh content beside it as
+`<file>.new`. Derived files carry the comment
+`<!-- Generated by scripts/pincer/cli.cjs generate from <source> ... -->`; a file that
+still carries it is the generator's to overwrite or remove. The files of a stage
+switched off, or of an agent dropped from every active roster, are removed when
+unedited and reported when not. `--overwrite` treats every target as unedited.
+Platforms come from `.pincer.json`, all three without one; `--platform` overrides them
+for one run. Kit maintainers regenerate the shipped copies the same way, with
+`--root template`, `--platform all` and a `--harness` file in which every optional
+stage is off; a test fails when the shipped copies are stale.
+
+## Models
+
+The agreement names a tier per role under `models.stages.<stage>` (the five optional
+stages) and `models.agents.<name>`: `strong`, `standard`, `fast`, `inherit` for the
+session's model, or `""` for not set, each with an optional effort `low`, `medium` or
+`high`. The library's `models.json` maps a tier to each platform's model name: the
+Claude row holds the aliases `opus`, `sonnet`, `haiku`; the Codex and Copilot rows name
+the vendors' current models and change when a vendor ships. `models.map.<platform>.<tier>`
+in the agreement overrides one entry. A library agent file may carry `tier:` as the
+kit's default for that role (`codebase-explorer`: `standard`). Resolution, in
+`scripts/pincer/models.cjs`: the agreement's tier, else the library's, else not set.
+`inherit` and not set write no model field, so the host's own order stands; an effort
+is written whenever set, with or without a model. The always-on stages take no tier:
+their copies are installer-owned and the validator rejects an entry for them.
+
+What the generator writes. Claude Code: `model:` and `effort:` in the agent files and,
+for a stage with a tier, in its project copy and thin command; the model applies to the
+stage's first turn and the session's model resumes on the next prompt. Codex:
+`.codex/agents/<name>.toml` per roster agent, with `model` and
+`model_reasoning_effort`, and one hint line at the top of the stage skill, which has no
+model field. Copilot: `model:` in the prompt file; the agents are the Claude files,
+which VS Code reads and maps itself. A tier the table cannot translate, or a missing
+table, is reported once and the field is left out; doctor prints the resolved mapping
+per installed platform. The host decides last: Claude Code's model allowlist and
+subagent env vars, Copilot org policy and Codex project trust override any file.
+
+| Role | Claude Code | Codex | Copilot (VS Code) |
+|---|---|---|---|
+| agent model | frontmatter, under the host's resolution order | agent file | the Claude file, mapped by VS Code |
+| agent effort | frontmatter | agent file | not available |
+| stage model | first turn of the stage | a hint in the skill | the prompt file |
+| stage effort | frontmatter | the same hint | not available |
+
+## Recovery
+
+- A failed check: fix the cause and run `verify` again. The failed `last_check` stays until a pass replaces it; it is information, not damage.
+- An interrupted check (a signal, the timeout, exit 130): run `verify` again.
+- A ticket that status reports as `invalid`, or whose lifecycle fields were edited by hand: the person repairs the file in their own terminal, then `verify` runs again (and `done` again if it was done). The session reports the problem and never edits those fields itself.
+- A check that changed after it passed: `done` refuses with both hashes; run `verify` again.
+- The rule under all of these: you never restore a ticket file from git (`checkout`, `restore`, `reset --hard`, `stash`) to clear a warning, because that revives an old receipt as if it were new evidence. On Claude Code the hook blocks it; elsewhere it is the standing rule in `AGENTS.md`.
+- `write` refused: fix the answers file and run it again; nothing was written. One agreement marker without the other in `AGENTS.md`: put the missing marker back by hand, then `write`.
+- A `.new` sidecar: compare it with the project copy, take what you want, delete the sidecar. `generate` writes a new one only when the fresh content differs again.
+
+## Platform notes
+
+- Claude Code: `.claude/settings.json` wires two PreToolUse hooks. `block-dangerous.sh` refuses destructive commands. `ticket-guard.sh` refuses edits to the eight lifecycle fields and any shell command that writes, resets or restores a ticket file, allowing only exact calls of the project's own `scripts/pincer-ticket.sh start|verify|done|accept` and the `cli.cjs ticket` form at the same path; a lookalike script elsewhere is refused. It also refuses edits and shell writes to the engine (`scripts/pincer-*`, `scripts/pincer/`) and to the hooks (`.claude/hooks/`, `.claude/settings.json`), which `npx pincer-workflow update` refreshes. The guard matches `T-NN-*.md` under any directory named `tickets`; a `homes.tickets` that does not end in `tickets` loses hook coverage, and the rule in `AGENTS.md` carries the weight alone. The hook does not read `harness.json`. It is a guardrail against documented mistake forms, not a security boundary: the sandbox and the approval controls remain that boundary.
+- Codex: reads `AGENTS.md` natively; the stages are skills under `.agents/skills/`, invoked as `$pincer-<stage>`; the roster agents are `.codex/agents/<name>.toml`, generated from the library, and Codex loads `.codex/` only in a project marked trusted. No hook. Posture in `~/.codex/config.toml`: `approval_policy = "on-request"` and `sandbox_mode = "workspace-write"`; never run with approvals disabled. Status warns about missing, failed or stale receipts and about hand-edited fields.
+- Copilot: `.github/copilot-instructions.md` points at `AGENTS.md`; the stages are prompt files under `.github/prompts/`, invoked as `/pincer-<stage>` with prompt files enabled; the roster agents are the files under `.claude/agents/`, which VS Code reads in the Claude format. No hook; the same rule.
+- Everywhere: Node 22 or newer, git and bash. `gh` only for the forge-facing steps the skills name. The engine runs offline.

package/template/docs/release-checklist.md

@@ -1,38 +1,32 @@
-# PINCER Release Checklist
+# Release checklist
 
-Audit the selected PRD and its evaluated candidate. This checklist applies to product
-changes in greenfield and brownfield repositories. It is read-only: failures return work
-to the owning stage or a new ticket.
+What `/pincer-release` audits before the person accepts. Read-only: every item is
+checked from `scripts/pincer-status.sh` output or from git, and a failure goes back to
+its stage through a new ticket. Pass or fail per item, one sentence of evidence each.
 
-## Change identity and state
+## Tickets
 
-- [ ] `scripts/pincer-status.sh` selects the intended PRD with `status: built` and no warnings
-- [ ] Every ticket associated with that PRD is done and ready: current `last_check` and `verified` evidence before migration, a current passing attempt after it (`node scripts/pincer-runtime.cjs ready` exits 0)
-- [ ] `NOTES.md` names the selected PRD, reviewed base, candidate, and `evidence:` manifest; status reports the notes current and the evidence `ok`
-- [ ] The `Provenance` line names the evidence schema; a schema 2 candidate has no newer nonpassing local attempt for the same check and source inputs, and a fresh clone's `local verification history unavailable` limit is stated, not claimed as verification
-- [ ] Change records only: the selected change is `completed`, its authorization is `current` for the current agreement, `.prd/evidence/changes/<id>.json` names the evaluated candidate, and the audit selected, activated and completed nothing
-- [ ] Every file the evidence manifest lists is tracked; the working tree is clean before and after the audit
-- [ ] Strict coverage only (`Coverage strict …` in status): `node scripts/pincer-runtime.cjs coverage` reports structure complete, every in-scope scenario `delivered` on the evaluated candidate, every deferral or removal backed by its decision and user authorization, `delivery` distinguishing original from agreed scope, and an `adequate` adequacy judgment; `ready` names `COVERAGE_INCOMPLETE`, `SCOPE_UNAUTHORIZED`, `OBLIGATION_MISSING`, `REVIEW_MISSING` or `ADEQUACY_REQUIRED` as failures. A change without the capability is labeled `unverified`: say so, never imply strict coverage
+- [ ] `scripts/pincer-status.sh` prints the agreement line and no `Warnings:` block
+- [ ] every ticket of the change is `done` with `verified` on its status line
+- [ ] no ticket line reads `invalid`
+- [ ] `git log --oneline` shows one `T-NN: <title>` commit per ticket, in dependency order
 
-## Scope and evidence
+## Evidence
 
-- [ ] Every requirement in the PRD has a disposition in the evidence manifest: delivered with passing checks, or deferred with recorded user authorization; none is blocked (strict coverage: the manifest is schema 3, its scenario rows are the inventory's, and the validator reconciled them with the committed candidate)
-- [ ] Ticket dependencies, acceptance criteria, and verification commands match the implemented change
-- [ ] The repository's candidate-wide release gate passes when run directly, without invoking the ticket state writer
-- [ ] Scope cuts and known limitations are explicit in the PRD or evaluation notes
+- [ ] `git status --short` is empty before the audit and after it
+- [ ] every command in `repo.checks` passes when run directly, output quoted
+- [ ] with evidence on: `node scripts/pincer-evidence.cjs validate <manifest> --candidate <sha>` prints `ok <sha>` and every artifact it lists is tracked
+- [ ] with `stages.release.audit` = `pr`: the pull request is merged, its checks are green, and the deploy named in `systems.deploy` was observed
 
 ## Review
 
-- [ ] High-confidence review findings have file and line evidence and a disposition
-- [ ] Fixes made after evaluation use a new ticket, current verification, and a scoped commit
-- [ ] UI changes have visual checks with saved images in the evidence manifest (scenario, viewport, observed result); non-UI changes record `visual_review.applicable: false` with a reason
-- [ ] Security review reports locations and remediation without printing candidate secret values
-- [ ] No secret environment file is tracked; dependency and invalid-input checks run when applicable
+- [ ] the review report exists (a file under the evidence home, or the PR comment) and every finding has a file, a line and a disposition
+- [ ] every fix after evaluate went through its own ticket and `T-NN:` commit, never an ad-hoc commit
+- [ ] no secret environment file is tracked: `git ls-files | grep -i '^\.env'` shows only `.env.example`
 
-## Handover and verdict
+## Acceptance
 
-- [ ] Commit history identifies the plan, ticket work, evaluation, and any review-fix tickets
-- [ ] `NOTES.md` covers what shipped, cuts, limitations, next steps, dependencies, and the riskiest aging assumption
-- [ ] Platform or environment limits are stated without claiming untested support
-- [ ] The audit repaired no ticket, rewrote no evidence, changed no PRD state, and published nothing
-- [ ] Every failed or skipped required item is named before the final PASS or FAIL verdict, which names the candidate
+- [ ] the person saw the result and every ticket's `Done when` lines before being asked
+- [ ] every done ticket shows `accepted by <name>` in status, the name from `people` with `accepts: true`
+- [ ] `accepted_words` holds the person's own words, not a paraphrase
+- [ ] the audit wrote nothing but the acceptances: no `verify`, no `done`, no ticket edits, and `git status --short` is still empty

package/template/scripts/pincer/blueprint.cjs

@@ -0,0 +1,137 @@
+'use strict';
+// PINCER blueprint — the writer (docs/engine.md, "Blueprint"). Reads an answers
+// file in the shape of harness.json, validates it, writes harness.json, renders
+// the agreement from library/agreement.md between the markers in AGENTS.md and
+// runs the generator. Everything outside the markers is left byte for byte.
+const fs = require('node:fs');
+const path = require('node:path');
+const util = require('./util.cjs');
+const harness = require('./harness.cjs');
+const generate = require('./generate.cjs');
+const models = require('./models.cjs');
+
+const AGREEMENT_START = '<!-- pincer:agreement:start -->';
+const AGREEMENT_END = '<!-- pincer:agreement:end -->';
+const AGENTS_FILE = 'AGENTS.md';
+const { LIBRARY, libraryDir } = generate;
+const TEMPLATE_FILE = 'agreement.md';
+const SKELETON_FILE = 'agents-skeleton.md';
+const CODE_GATE = 'passing check per ticket';
+
+// {{slot}} and {{#each list}}…{{/each}} with {{.}} for the item; nothing else.
+function fill(template, view) {
+  const lookup = (key) => {
+    if (!(key in view)) throw new Error(`${TEMPLATE_FILE}: unknown slot {{${key}}}`);
+    return view[key];
+  };
+  const expanded = template.replace(/\{\{#each ([\w.]+)\}\}\n?([\s\S]*?)\{\{\/each\}\}\n?/g, (_, key, block) => {
+    const items = lookup(key);
+    if (!Array.isArray(items)) throw new Error(`${TEMPLATE_FILE}: {{#each ${key}}} needs a list`);
+    return items.map((item) => block.replace(/\{\{\.\}\}/g, String(item))).join('');
+  });
+  return expanded.replace(/\{\{([\w.]+)\}\}/g, (_, key) => {
+    const value = lookup(key);
+    if (Array.isArray(value)) throw new Error(`${TEMPLATE_FILE}: {{${key}}} is a list; use {{#each}}`);
+    return String(value);
+  });
+}
+
+const or = (value, fallback) => (typeof value === 'string' && value.trim() ? value.trim() : fallback);
+const yesNo = (value) => (value ? 'yes' : 'no');
+
+// The one-line pipeline: the stages that run, in order, each gate in bold.
+function pipeline(h) {
+  const who = harness.acceptors(h);
+  const gates = {
+    plan: or(h.stages.plan.gate, 'spec approved'),
+    code: CODE_GATE,
+    evaluate: h.stages.evaluate.evidence === false ? 'review done' : 'evidence saved',
+    release: `accepted by ${who.length ? who.join(', ') : 'a person'}`,
+  };
+  return harness.STAGES.filter((name) => harness.stageOn(h, name))
+    .map((name) => (gates[name] ? `${name} (**${gates[name]}**)` : name))
+    .join(' → ');
+}
+
+// The slots of library/agreement.md from a normalized agreement; the library
+// supplies the agents' default tiers for the Models line.
+function view(h, lib) {
+  const homes = harness.homes(h);
+  const simplify = harness.OPTIONAL_STAGES.filter((name) => !harness.stageOn(h, name))
+    .map((name) => `${name} is off${or(h.stages[name].reason, '') ? ` — ${h.stages[name].reason.trim()}` : ''}.`);
+  const people = h.people.map((p) => `${p.name.trim()}${or(p.role, '') ? ` (${p.role.trim()})` : ''}${p.accepts === true ? ' — accepts results' : ''}`);
+  const forge = { github: 'GitHub', none: 'none', other: 'other' }[h.systems.forge] || h.systems.forge;
+  return {
+    name: or(h.project.name, 'unnamed project'),
+    kind: h.project.kind,
+    kindReason: or(h.project.reason, '') ? ` — ${h.project.reason.trim()}` : '',
+    forge,
+    remote: or(h.systems.remote, 'none'),
+    ci: yesNo(h.systems.ci),
+    deploy: or(h.systems.deploy, 'none'),
+    secrets: or(h.systems.secrets, 'not recorded'),
+    pipeline: pipeline(h),
+    spec: !harness.stageOn(h, 'plan') ? 'none (plan is off)' : h.stages.plan.spec === 'forge' ? 'forge' : `${homes.specs}/`,
+    tickets: h.stages.narrow.tickets === 'forge' ? 'forge' : `${homes.tickets}/`,
+    evidence: !harness.stageOn(h, 'evaluate') ? 'none (evaluate is off)' : h.stages.evaluate.evidence === false ? 'none' : `${homes.evidence}/`,
+    simplify: simplify.length ? simplify : ['Every stage runs; nothing switched off.'],
+    people: people.length ? people : ['nobody named yet'],
+    branches: h.repo.branches === 'per-ticket' ? 'one branch per ticket' : 'commit to main',
+    pr: yesNo(h.repo.pr),
+    merge: h.repo.merge,
+    protection: or(h.repo.protection, 'none'),
+    checks: h.repo.checks.length ? h.repo.checks.join(', ') : 'none',
+    open: h.open.length ? h.open : ['none'],
+    firstJob: or(h.firstJob, 'not named yet'),
+    models: models.agreementLine(models.effective(h, lib)),
+  };
+}
+
+// The agreement text, without the markers; ends with one newline.
+function renderAgreement(h, { library } = {}) {
+  const lib = library || libraryDir(process.cwd());
+  const template = fs.readFileSync(path.join(lib, TEMPLATE_FILE), 'utf8');
+  return `${fill(template, view(harness.normalize(h), lib)).trimEnd()}\n`;
+}
+
+// AGENTS.md with the agreement between the markers. Markers present: the text
+// between them is replaced. No markers: the block goes after a leading title,
+// else at the top. One marker alone is a problem, nothing is changed.
+function splice(text, agreement) {
+  const block = `${AGREEMENT_START}\n${agreement}${AGREEMENT_END}`;
+  const start = text.indexOf(AGREEMENT_START), end = text.indexOf(AGREEMENT_END);
+  if (start === -1 && end === -1) {
+    const title = /^# [^\n]*\n/.exec(text);
+    const head = title ? title[0] : '';
+    const rest = text.slice(head.length).replace(/^\n+/, '');
+    return { text: `${head}${head ? '\n' : ''}${block}\n${rest ? `\n${rest}` : ''}` };
+  }
+  if (start === -1 || end === -1 || end < start) return { problem: `${AGENTS_FILE}: found one agreement marker without the other (${AGREEMENT_START} … ${AGREEMENT_END})` };
+  return { text: `${text.slice(0, start)}${block}${text.slice(end + AGREEMENT_END.length)}` };
+}
+
+function write(root, { answers = harness.HARNESS_FILE, label, library } = {}) {
+  const name = label || answers;
+  const file = path.isAbsolute(answers) ? answers : path.join(root, answers);
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (error) {
+    return { ok: false, exit: 3, problems: [`${name}: cannot read (${error.code === 'ENOENT' ? 'no such file' : error.message})`] };
+  }
+  let doc;
+  try { doc = JSON.parse(raw); } catch (error) { return { ok: false, exit: 3, problems: [`${name}: invalid JSON (${error.message})`] }; }
+  const problems = harness.validate(doc);
+  if (problems.length) return { ok: false, exit: 3, problems: problems.map((p) => `${name}: ${p}`) };
+  const normalized = harness.normalize(doc);
+  const lib = libraryDir(root, library);
+  const agreement = renderAgreement(normalized, { library: lib });
+  const agentsFile = path.join(root, AGENTS_FILE);
+  const current = fs.existsSync(agentsFile) ? fs.readFileSync(agentsFile, 'utf8') : fs.readFileSync(path.join(lib, SKELETON_FILE), 'utf8');
+  const spliced = splice(current, agreement);
+  if (spliced.problem) return { ok: false, exit: 1, problems: [spliced.problem] };
+  util.atomicWrite(path.join(root, harness.HARNESS_FILE), `${JSON.stringify(normalized, null, 2)}\n`);
+  util.atomicWrite(agentsFile, spliced.text);
+  const generated = generate.generate(root, { harness: normalized, library: lib });
+  return { ok: true, harness: normalized, agreement, generated, written: [harness.HARNESS_FILE, AGENTS_FILE] };
+}
+
+module.exports = { AGREEMENT_START, AGREEMENT_END, AGENTS_FILE, LIBRARY, write, renderAgreement, splice, fill, libraryDir };