pincer-workflow 0.6.0 → 1.0.0

package/README.md

@@ -1,136 +1,187 @@
-# PINCER — PRD-Driven Agentic Delivery Workflow
+# PINCER — a harness builder for AI coding agents
 
-**P**lan · **I**nvestigate · **N**arrow · **C**ode · **E**valuate · **R**elease
-
-A lean, PRD-first workflow for AI coding agents — Claude Code, Codex CLI, and
-GitHub Copilot. One idea goes from brief to reviewed, verified code through five
-commands, and every step leaves an auditable artifact: a PRD, tickets, one
-commit per ticket, review notes, and a pass/fail release audit.
-
-**Website:** [orchestratedbyalex.github.io/pincer-workflow](https://orchestratedbyalex.github.io/pincer-workflow/) —
-a twelve-sheet walkthrough of the workflow: why it exists, each command, the
-safety guardrails, and installation.
+PINCER looks at your project, interviews you, and writes the agreement under which an
+AI coding agent works there: which stages run, where the artifacts live, who accepts.
+Then it runs the pipeline that agreement describes, with one floor that never bends:
+a ticket is done only on a script-stamped passing check, and accepted only when a
+named person said so, in their words. It works on Claude Code, Codex CLI and GitHub
+Copilot from one kit, and it has no dependencies.
 
 ## Install
 
+PINCER 1.0 is available as a package attached to the [GitHub release](https://github.com/orchestratedbyalex/pincer-workflow/releases/tag/v1.0.0).
+npm's `latest` is still 0.7.0 pending publication. Download `pincer-workflow-1.0.0.tgz`
+into your project and install that exact release:
+
 ```bash
-cd your-project
-npx pincer-workflow init     # asks which platform(s) you use
+npx ./pincer-workflow-1.0.0.tgz init --platform all
 ```
 
-Then follow the chain — the same five steps on every platform:
+Node.js 22+, git and bash are required. PINCER uses your coding tool's own
+authentication; it does not require a provider API key.
+
+Then start your agent in the repository and run the blueprint:
 
 ```
-/pincer-plan <brief>  →  /pincer-narrow  →  /pincer-code  →  /pincer-evaluate  →  /pincer-release
+/pincer-blueprint                 # Claude Code and Copilot
+$pincer-blueprint                 # Codex CLI
 ```
 
-`/pincer-status` shows where the workflow stands at any point (PRD, tickets,
-receipts, elapsed time, next command) — run it first in a new session.
-
-On Codex CLI the commands are skills, invoked by mention rather than slash:
-`$pincer-plan <brief>` → `$pincer-narrow` → `$pincer-code` → `$pincer-evaluate`
-→ `$pincer-release`, and `$pincer-status`.
-
-### Claude Code
-
-Works immediately: the commands, the two subagents, the `.env` deny rules and
-the destructive-command and ticket-guard hooks install to `.claude/`. Start
-`claude` in the repo and run `/pincer-plan <brief>`.
-
-### Codex CLI
-
-Works immediately as well: `AGENTS.md` loads natively, and the six commands
-install as skills under `.agents/skills/`, which Codex discovers from the repo
-(no copying into your home directory — Codex removed custom prompts and
-`~/.codex/prompts/` in early 2026). Start `codex` in the repo, then type
-`$pincer-plan <brief>`; `$` opens the skill picker and `/skills` lists what
-loaded. Inside the Codex skills every cross-reference already reads
-`$pincer-narrow`, `$pincer-status` and so on.
+Until the blueprint has run there is no agreement, and every other stage refuses with
+`no agreement yet: run /pincer-blueprint`. `scripts/pincer-status.sh` works in any
+shell from the first minute and always ends with the next command.
+
+## The journey
+
+**Blueprint** reads the repository first (git history, CI, deploy configuration, tests,
+the forge when `gh` is available) and says whether the project is greenfield or
+brownfield, and why; you confirm. Then it interviews you, one question at a time,
+through the six sections of a harness agreement: Systems, Current pipeline, Handoff
+artifacts, Simplify, Responsibility, Repo. Every answer it could pre-fill is shown as
+"I see X; is that right?", and `open` is always an allowed answer. It proposes the
+roster of review agents from your answers, writes `harness.json` and the agreement at
+the top of `AGENTS.md`, generates the project's copies of the stages you kept, and
+names the first real job. The first run through the pipeline is the trace you revisit
+the agreement with.
+
+The stages the agreement keeps, and what the interview can bend:
+
+| Stage | Command | Default role | What the interview can bend |
+|---|---|---|---|
+| blueprint | `/pincer-blueprint` | the interview above | nothing; always on |
+| plan | `/pincer-plan` | brief to a written spec with stable `R-NN` IDs | off for small changes; the spec can be a forge issue instead of a file |
+| narrow | `/pincer-narrow` | spec to tickets with runnable checks | tickets as local files or as forge issues; one ticket per change |
+| code | `/pincer-code` | build tickets in order, one commit each, verify, done | branch per ticket or commit to main; PR or no PR; implementer agent or the main session |
+| evaluate | `/pincer-evaluate` | review the diff with the roster, run the checks, save evidence | review in the PR instead of a local report; evidence on or off; the roster |
+| release | `/pincer-release` | read-only audit, then acceptance recorded | audit a merged PR and a deploy instead of a clean tree; who accepts |
+| status | `/pincer-status` | where the work stands, the next command | nothing; always on |
+
+Each stage is a short skill with the same six sections (Reads, Steps, Checks, Writes,
+Without subagents, When this stage is off). It reads `harness.json` first and refuses
+when the agreement switched it off. The project copies under `.claude/skills/` are
+yours to edit; the Codex skills and Copilot prompts are generated from them.
+
+## The floor
+
+- `scripts/pincer-ticket.sh verify T-NN` runs the ticket's Verification block and
+  stamps a receipt only on exit 0. `done` refuses without a receipt for the current
+  check, or with an unticked criterion.
+- `scripts/pincer-ticket.sh accept T-NN --by "<name>" --words "<their words>"` records
+  the acceptance of a done ticket: a person named in the agreement, quoted. The agent
+  runs it only after the person said so.
+- The eight lifecycle fields of a ticket are written only by that script. On Claude
+  Code a hook enforces it; on Codex and Copilot it is a standing rule, and status flags
+  a missing, failed or stale receipt and every done ticket without acceptance.
+- Evidence, when the agreement keeps it, is a validated manifest under the evidence
+  home that release reads instead of trusting chat.
+- Nothing is restored from git to clear a warning. A failed check is fixed and run
+  again; a hand-edited ticket is repaired by the person, then verified again.
+
+`docs/engine.md` in the installed kit is the full contract: fields, receipts, exit
+codes, the gate, the manifest, generation, recovery.
 
-Pincer does not currently install a Codex hook adapter, so its Codex guardrail
-posture uses `~/.codex/config.toml` — `approval_policy = "on-request"` and
-`sandbox_mode = "workspace-write"`; never run with approvals disabled. The
-ticket scripts (`scripts/pincer-ticket.sh`, `scripts/pincer-status.sh`) are
-plain bash and work unchanged; the rule in `AGENTS.md` against hand-editing
-ticket state carries the weight the hook carries on Claude Code, and
-`$pincer-status` flags missing, failed, or stale ticket readiness.
-Full notes in `.codex/README.md`.
-
-### GitHub Copilot (VS Code)
-
-Enable `"chat.promptFiles": true` in VS Code settings, then run `/pincer-plan`
-in chat. `.github/copilot-instructions.md` is wired to `AGENTS.md`.
+## What you get
 
-## Claude Code plugin (alternative)
+| Path | What it is |
+|---|---|
+| `AGENTS.md` | the agreement between two markers, then the standing rules and your conventions |
+| `harness.json` | the machine-readable agreement, written by the blueprint, read by every stage |
+| `scripts/pincer-ticket.sh` | `start`, `verify`, `done`, `accept`: the only writer of ticket lifecycle fields |
+| `scripts/pincer-status.sh` | the report, `--json`, and the stage gate `--stage <name>` |
+| `scripts/pincer-blueprint.cjs` | `recon`, `write`, `generate` |
+| `scripts/pincer-evidence.cjs` | `validate` and `digest` for evidence manifests |
+| `scripts/sync-prompts.sh` | regenerates the project copies, Codex skills and Copilot prompts |
+| `scripts/pincer/` | the dependency-free Node core behind the four entry points |
+| `.claude/pincer/library/` | the library: every stage skill, prompt, format and agent |
+| `.claude/skills/pincer-<stage>/` | the project's editable copy of each stage that is on |
+| `.claude/commands/`, `.agents/skills/`, `.github/prompts/` | the thin commands, the Codex skills, the Copilot prompts, generated |
+| `.claude/agents/` | the review agents the roster names, with the model of their tier |
+| `.codex/agents/` | the same agents as Codex agent files, generated when Codex is installed |
+| `.claude/pincer/library/models.json` | the tier table: the model each platform runs a tier on |
+| `docs/engine.md`, `docs/release-checklist.md` | the engine contract and the fifteen-item release audit |
+| `specs/`, `tickets/`, `evidence/` | the default homes, all overridable in `harness.json` |
+
+Secrets never enter the kit: `init` adds `.env`, `.env.*` and `!.env.example` to
+`.gitignore`, and the standing rules in `AGENTS.md` say the rest.
+
+## Platforms
+
+| | Claude Code | Codex CLI | GitHub Copilot |
+|---|---|---|---|
+| Agreement | `AGENTS.md` via the `CLAUDE.md` import | `AGENTS.md` natively | pointed at by `.github/copilot-instructions.md` |
+| Stages | `.claude/skills/` plus `/pincer-*` commands | `.agents/skills/`, invoked as `$pincer-*` | `.github/prompts/`, invoked as `/pincer-*` with prompt files enabled |
+| Agents | subagents | subagents from `.codex/agents/` | the Claude agent files, read by VS Code |
+| Floor | script plus hook | script plus status warning | script plus status warning |
+
+The hook exists only on Claude Code. On the other platforms the rule in `AGENTS.md`
+carries the weight, `scripts/pincer-status.sh` reports what the rule would have
+stopped, and the posture notes in `.codex/README.md` apply. Node 22 or newer, git and
+bash are needed everywhere; `gh` only for the forge-facing steps the agreement chose.
+
+## Model tiers
+
+The agreement says which tier each stage and each roster agent runs on: `strong`,
+`standard`, `fast`, or `inherit` for the session's model, with an optional effort
+(`low`, `medium`, `high`). The blueprint proposes the tiers right after the roster
+(reviewers strong, the implementer and the explorer standard, every stage as run) and
+writes what you confirm under `models` in `harness.json`; nothing moves to a stronger
+tier unless you said so. One table in the library, `.claude/pincer/library/models.json`,
+maps a tier to each platform's model name, and the generator writes the platform's own
+field: Claude Code agent and skill frontmatter, Codex agent files, the Copilot prompt
+files. `harness.json` never names a vendor's model; a project that must pin one sets
+`models.map.<platform>.<tier>`. When a vendor ships a new model the table changes by one
+row and `npx pincer-workflow update` carries it into every project; `doctor` shows what
+each installed platform will run.
 
-Claude users can install PINCER as a plugin instead — commands arrive
-namespaced (`/pincer:plan` … `/pincer:release`) and update automatically
-through the marketplace. The plugin's structured hook parser requires Node.js 22+:
+## Update
 
-```
-/plugin marketplace add orchestratedbyalex/pincer-workflow
-/plugin install pincer@pincer-workflow
+```bash
+npx ./pincer-workflow-1.0.0.tgz update   # edited files get a .new sidecar
+npx ./pincer-workflow-1.0.0.tgz doctor   # checks the install and agreement
 ```
 
-Pick one channel per project: the plugin makes the commands, subagents, and
-the guardrail hook available everywhere, while `npx pincer-workflow init`
-installs everything project-locally *plus* the repo-side files (`AGENTS.md`
-rules, `.env` deny rules in `.claude/settings.json`, the adapters for Codex
-and Copilot). Installing both gives you duplicate commands. Plugin users who
-want the repo-side rules too can copy `AGENTS.md` from the
-[template](template/AGENTS.md).
+With an agreement in place, `update` also refreshes the library and regenerates the
+project copies you did not edit; an edited copy stays and gets the new version beside
+it as `<file>.new`.
 
-## Update
+## Trying it locally before release
 
 ```bash
-npx pincer-workflow@latest update
+npm pack                                           # in this repository: pincer-workflow-1.0.0.tgz
+cp pincer-workflow-1.0.0.tgz ../some-project/ && cd ../some-project
+npx ./pincer-workflow-1.0.0.tgz init --platform all   # the ./ matters: npx treats a bare path as a command
+scripts/pincer-status.sh                           # prints "no agreement yet" and "Next: /pincer-blueprint"
 ```
 
-Files you never touched are refreshed in place. (Installs older than v0.2.0 gain the ticket state machine, the status report and the ticket-guard hook on update; `.claude/settings.json` conflicts if you edited it — merge the new hook entry from the `.new` file. v0.2.2 replaces the Codex adapter: the commands are now skills in `.agents/skills/` invoked as `$pincer-*`, since Codex no longer loads `~/.codex/prompts/` — you can delete the copies there. v0.2.3 ships the playbooks, rubrics and templates under `.claude/` on every platform, which Codex- and Copilot-only installs were missing. v0.3.0 makes trust revocable: every verification attempt is recorded, `done` re-runs the check, tickets carry `prd:`, the release audit is read-only, and `.pincer.json` moves to schema 2 — an install from 0.2.x is treated as an untrusted baseline, so on the first update every changed file arrives as a `.new` proposal once; hooks now need Node 18+. v0.4.0 carries requirement IDs and `Proves:` checks from the PRD to evaluation, adds `profile: small|standard`, and saves candidate evidence under `.prd/evidence/`; the update is additive, but an existing `NOTES.md` without an `evidence:` manifest reads as stale until `/pincer-evaluate` is re-run. v0.4.1 is playbook wording only: the code playbook gains one recovery exception (a tree back at the evaluated candidate is restored by the user and nothing is committed), evaluate records one check per command, and plan asks only the open part of a partly answered question. v0.5.0 adds the runtime: `scripts/pincer-runtime.cjs` with its modules under `scripts/pincer-runtime/` now implements the ticket lifecycle, status, migration and evidence export, and `pincer-ticket.sh` / `pincer-status.sh` delegate to it, so every command needs Node.js 18+; unmigrated projects keep their receipts and behavior. Run `node scripts/pincer-runtime.cjs migrate --preview --prd .prd/prd-vN.md` to see what migration would change; after `--apply`, `verify` records attempts with captured logs under the ignored `.pincer/runtime/` and writes no receipt into the ticket, `done` consumes the current passing attempt against the current source, and `/pincer-evaluate` exports evidence schema 2 from runtime attempts. `docs/runtime-contracts.md` is the contract; `pincer doctor` tells you when a migration is available and never migrates on its own. The next version keeps several changes side by side: `register` writes a change record (schema 2) that retains every earlier change, the worktree selects the change it works on (`change select`), the user's approval is recorded against the reviewed agreement (`change authorize`), the lifecycle is explicit (`change activate|pause|resume|complete|reopen|cancel|supersede`), and `resume` prints where to continue from files alone. A v0.5.0 binding converts with the same `migrate --preview` / `--apply`; the converted change is planned with no authorization, its old attempts and evaluation are history until verified again, and the old free-text authorization never authorizes execution. Selection and local attempts are per worktree; records are tracked and shared through git; completed means ready for evaluation, not released. The next version also raises the floor to Node.js 22+, because 18 and 20 are past end of life. It separately fixes a defect that was never version-specific: a command whose output exceeded one pipe buffer (65,536 bytes) lost the tail when the process exited and still exited 0, on every version including 22 and 24. Every write is now synchronous, so piped `--json` is complete. Updating the kit inside a migrated project changes tracked runtime files, so every done ticket's attempt reads `SOURCE_CHANGED` until it is verified again; update between changes, not mid-ticket. An update from 0.4.x leaves the retired `scripts/pincer-ticket-lib.sh` on disk; `pincer doctor` names it and it is safe to delete.) Files you edited are left
-alone — the new version lands next to them as `<file>.new` for a manual merge.
-`npx pincer-workflow doctor` checks the health of an install (hook executable,
-`.gitignore` covering `.env*`, no unmerged `*.new` files, version current).
-
-## What you get
+## Status of the older channels
 
-| Piece | Purpose |
-| --- | --- |
-| `AGENTS.md` | Project rules, single cross-platform source (workflow order, security defaults, secrets, untrusted-content and dependency rules) |
-| `.claude/commands/` | The five playbooks plus `/pincer-status` (canonical — adapters are generated from them; ships on every platform together with `agents/` and `references/`) |
-| `.claude/agents/` | `codebase-explorer` and `code-quality-reviewer` subagents, with inline fallbacks for platforms without subagents |
-| `scripts/pincer-runtime.cjs` + `scripts/pincer-runtime/` | The runtime (Node.js 22+, no dependencies): one implementation of the ticket lifecycle, readiness, status (`--json` too), change records with lifecycle, agreements, authorization and decisions (`change list|show|select|activate|pause|resume|complete|reopen|cancel|supersede|revise|authorize|decide`), the read-only `resume` report, source identity, verification attempts with sanitized captured logs, migration with backups, candidate checks and evidence export; `docs/runtime-contracts.md` is its contract. Local attempts and the worktree's selection live in the ignored `.pincer/runtime/`, change records in `.prd/changes/`, evaluation locators in `.prd/evidence/changes/`; all are written only by the runtime |
-| `scripts/pincer-ticket.sh` | Wrapper for the lifecycle: `start` (enforces dependency order) → `verify` (runs the ticket's check; before migration it stamps a receipt only on green, after migration it records an attempt bound to the current source) → `done` (refuses without a current pass or with unticked criteria; after migration it consumes the attempt without re-running the check) |
-| `scripts/pincer-status.sh` | Wrapper for the read-only state report: current PRD and profile, `Runtime` mode, associated tickets, wall-clock elapsed time while work is active or against an explicit budget, evidence verdict and `Provenance`, warnings with reason codes, and next command |
-| `scripts/pincer-evidence.cjs` | Read-only validator for candidate evidence (schema 1 authored, schema 2 exported from runtime attempts): `/pincer-evaluate` writes `.prd/evidence/prd-vN/<candidate>/manifest.json` plus logs and screenshots; status and release validate schema, references, candidate association, required results, provenance, file containment and SHA-256 digests. Legacy `NOTES.md` without a manifest is readable but never release-ready; an older runtime does not enforce this contract |
-| `docs/runtime-contracts.md` | The runtime contract: modes (legacy, migrated, changes), commands and exit codes, supported grammar, change records, selection, lifecycle, agreements and authorization, command gates, identities, source manifest, attempts, transactions, capture limits, reason codes, evidence schema 2, the evaluation locator, the resume report, migration and rollback, worktrees |
-| `.claude/hooks/` + `settings.json` | Claude guardrails for documented destructive command forms and for writes to ticket state, `.pincer/`, `.prd/changes/` and `.prd/evidence/changes/`; Node.js 22+ parses hook payloads structurally |
-| `.agents/skills/` · `.codex/` · `.github/` | Generated Codex skills and Copilot prompt files + platform wiring (`.codex/README.md` covers the Codex posture) |
-| `scripts/sync-prompts.sh` | Regenerates the adapters after you edit a playbook |
-| `scripts/build-plugin.sh` (maintainers of this repository only — not installed into your project) | Regenerates the Claude Code plugin (`plugin/`) from the template |
-| `docs/release-checklist.md` | General, read-only candidate audit used by `/pincer-release` |
-| `docs/dry-run-checklist.md` | Separate manual platform trial for the Pincer kit |
+- The Claude Code plugin channel is paused; the kit installs with `npx` on every platform.
+- The wiki under `docs/wiki/` is frozen at 0.7 and kept for history.
+- PRD v8 is superseded by the harness-builder design; its open tickets are marked so.
+- The GitHub Pages site describes 1.0. See [CHANGELOG.md](CHANGELOG.md) before upgrading from 0.7.
 
 ## Design principles
 
-- **Approval gates scale with decision cost** — a human owns architecture, scope,
-  and merge decisions; unchanged authorization persists across resume and routine
-  verification, while explicit budgets shape the depth of work.
-- **Nothing is done while its verification fails** — every ticket carries a
-  runnable check, and "done" is a state only a passing run of that check can
-  unlock: the receipt is stamped by the script, never typed by the agent.
+- **A person owns the decisions** — scope, direction, acceptance, anything that leaves
+  the machine (pushing, merging) and the rules; the agent does the work and writes
+  down the technical decisions it takes.
+- **Nothing is done while its verification fails** — every ticket carries a runnable
+  check, and "done" is a state only a passing run of that check can unlock: the
+  receipt is stamped by the script, never typed by the agent.
+- **Accepted means a named person said so** — acceptance is recorded with the
+  person's name and their words, per ticket, and release passes only with it.
 - **State lives in files, not in the conversation** — a new session runs
-  `/pincer-status` and knows exactly where to resume; elapsed time comes from
-  timestamps, not from the model's sense of time.
-- **Evidence is saved, not narrated** — requirements carry stable IDs from the
-  PRD through tickets to evaluation, and the evaluation writes a validated
-  manifest under `.prd/evidence/` that release reads instead of trusting chat.
-- **Scope is a first-class artifact** — cuts are recorded, never silent.
-- **Security is threaded through every stage** — designed in at Plan, specified
-  as reject-path criteria at Narrow, enforced by a pre-commit sweep at Code,
-  audited mechanically at Evaluate and Release.
-- **Layered guardrails** — Claude hooks cover documented high-risk command and
-  ticket-state forms, while sandbox and approval controls remain the security
-  boundary. Other platforms use their native controls plus `/pincer-release`.
+  `/pincer-status` and knows exactly where to resume.
+- **Evidence is saved, not narrated** — requirements carry stable IDs from the spec
+  to the tickets, and the evaluation writes a validated manifest that release reads.
+- **Scope is a first-class artifact** — cuts are recorded in the spec, never silent;
+  stages switched off carry their reason in the agreement.
+- **Security is threaded through every stage** — designed in at plan, specified as
+  reject-path criteria at narrow, swept before every commit at code, audited at
+  evaluate and release.
+- **Layered guardrails** — the Claude Code hooks cover documented high-risk command
+  and ticket-state forms while sandbox and approval controls remain the security
+  boundary; other platforms use their native controls plus the standing rules.
 
 ## License