pincer-workflow 0.7.0 → 1.0.0

package/template/.claude/commands/pincer-evaluate.md

@@ -1,176 +0,0 @@
----
-description: "Final quality pass over everything built — high-confidence findings only"
-argument-hint: "[none]"
----
-
-# /pincer-evaluate — Final Quality Pass
-
-You are reviewing all work built this session against the PRD and tickets. Autonomous —
-run the pipeline, then present results.
-
-## Steps
-
-1. Run `scripts/pincer-status.sh`. Review only tickets associated with the selected
-   PRD. Every such ticket should be `done` with a current receipt; if one
-   is still open or in progress, stop and ask whether it was cut (then it goes in the
-   PRD's Out of Scope) or should be finished first via `/pincer-code`. Then get the full
-   diff of the change: identify the actual base commit before this change from
-   its ticket commits and recorded context. If it cannot be established, resolve
-   that uncertainty before claiming a complete review. Record full commit IDs for
-   `base` and `candidate` (`git rev-parse HEAD`), then review `git diff <base>..<candidate>`.
-   The candidate is the clean, committed tree that already includes the implementation,
-   the ticket closures, on a project with change records the `change complete` commit
-   (the `Runtime` line reads `… · completed ·`; `check` and `evidence export` refuse an
-   active, paused or unauthorized change), and the PRD `status: built` commit:
-   `git status --short` must be empty before review. If anything is uncommitted or the PRD is not yet built, return
-   to `/pincer-code`; do not review a dirty tree.
-2. Dispatch a `code-quality-reviewer` agent with: the diff, the PRD's Success Criteria and
-   Scope sections, and the list of tickets. If the diff is large, split by area and
-   dispatch two in parallel. (No subagents on this platform? Review the diff yourself
-   in a separate pass, applying `.claude/agents/code-quality-reviewer.md` as the rubric.)
-   Keep the reviewer's report — or its explicit no-findings statement — for step 9,
-   where it is saved as an artifact; a review that left no record cannot be audited.
-3. Yourself, in parallel, check spec compliance. On a change with strict coverage
-   (`Coverage strict …` in status) start from `node scripts/pincer-runtime.cjs coverage`:
-   its structure must be complete, and its scenario rows are the obligations — the
-   export derives every disposition from the map and the outcomes, so you do not
-   author `requirements`; your judgment is recorded as `adequacy` (whether the
-   declared checks and reviews really establish their scenarios) and in
-   `coverage_review`. Otherwise, for every requirement `R-NN` in the
-   PRD record one disposition: `delivered` (evidence on this candidate), `blocked`
-   (required behavior failed or was left unverified — this blocks PASS; do not relabel
-   it a known limitation to pass), or `deferred` (only with explicit user authorization;
-   record the scope decision in the PRD's Out of Scope and evaluate the revised
-   candidate). Compare what was built against every ticket's acceptance criteria and
-   the PRD scope, and list any gaps. Whether the requirement map is complete and each
-   check is semantically adequate is your judgment as reviewer — record that judgment
-   in the evaluation; the kit is not a mechanical traceability engine and does not
-   validate requirement-revision impact.
-4. If the project has a UI, look at it — don't only read the code. Start it, open it in
-   the browser (screenshot via Chrome DevTools MCP if available), and check it against
-   the PRD's Visual Direction and Success Criteria. Note anything visibly broken or off.
-5. Run a mechanical security audit:
-   - Inspect the relevant history with a secret scanner that redacts values, when one is
-     available. Otherwise review likely locations without copying candidate values into
-     output. Report file, line, and remediation only; a secret committed then deleted is
-     still leaked.
-   - `.gitignore` covers `.env*` (except `.env.example`), and `git ls-files | grep -i env`
-     shows only `.env.example`.
-   - `npm audit --omit=dev` (or the ecosystem's equivalent) — report high/critical only.
-   - If there's an HTTP API: hit one endpoint with invalid input (empty, oversized)
-     and confirm a clean 4xx with a generic message, no stack trace.
-6. Filter the agent's findings: report only issues you'd flag in a real PR review —
-   concrete bugs, silent failures, misleading code. Drop nitpicks and style opinions.
-7. Present findings as a short list with `file:line` references, ordered by severity.
-   Security findings always rank above style-adjacent ones. For each, say whether you
-   recommend fixing now through a ticket or recording it as a known issue.
-8. Fix findings clearly within the authorized PRD through a new ticket associated with
-   that PRD. Use `pincer-ticket.sh` to start, verify, and close it, then make a scoped
-   `T-{NN}: {title}` commit. Ask only when a fix changes scope, architecture, or another
-   material decision; never make an ad-hoc `review: fixes` commit. Every fix commit
-   produces a new candidate: re-record `candidate`, re-run the checks against it, and
-   write fresh evidence in step 9 — never reuse a manifest from a previous candidate.
-9. Persist evidence for the candidate under `.prd/evidence/prd-vN/<candidate>/`.
-   Strict coverage: run every declared command check as
-   `node scripts/pincer-runtime.cjs check C-NN --candidate <sha>` (no command, no
-   timeout: the map's declaration is the only source, and a supplied command is
-   `CHECK_UNDECLARED`); record each declared review or visual obligation in the
-   draft with its `result` and an artifact saved under the candidate's evidence
-   directory (a required one that is not passed with an artifact is
-   `REVIEW_MISSING`); write `adequacy: { verdict: "adequate" | "inadequate", note }`;
-   list every declared check once and no `requirements` (they are derived). The
-   export writes the inventory and map snapshots under `coverage/`, derives the
-   scenario and requirement rows and `delivery` (original versus agreed scope) and
-   validates them against the committed candidate; an `inadequate` judgment or a
-   failed required check is recorded honestly and blocks readiness. Migrated
-   project without strict coverage (the `Runtime` status line names a change): run
-   each executable check through the runtime on the clean candidate view —
-   `node scripts/pincer-runtime.cjs check C-NN --candidate <sha> -- <command>` (one
-   command per check, the command line as run; `npm test` stays one aggregate check) —
-   then write the authored fields to a draft outside the evidence directory, for
-   example `.pincer/drafts/<sha>.json`: `environment.tools` and `environment.limitations`,
-   `coverage_review`, `requirements`, review and visual checks with their saved
-   artifacts, `visual_review`, and a stub `{"id": "C-NN", "kind": "command",
-   "required": true|false}` for each executable check. Then run
-   `node scripts/pincer-runtime.cjs evidence export --candidate <sha> --base <base> --prd .prd/prd-vN.md --draft <file>`.
-   The export writes `checks/C-NN.log` from the captured logs, fills `command`,
-   `result`, `provenance: runtime` and `attempt` from the attempts, labels review and
-   visual checks `provenance: authored`, computes the digests and writes an evidence
-   schema 2 manifest; it refuses a dirty tree, a HEAD that is not the candidate, a stub
-   without an attempt, and a `passed` or `failed` command result written by hand. On a
-   project with change records the export also appends the evaluation to the change's
-   locator `.prd/evidence/changes/<id>.json` (the identity of this change's
-   evaluation; root `NOTES.md` stays the human summary and may be overwritten by a
-   later change's evaluation without losing this one) — commit the locator with the
-   evidence. A tool that cannot run is recorded as an authored command check with
-   `result: unverified` and a note, as before. Legacy project (no change binding):
-   author the schema 1 manifest as follows.
-   - `checks/C-NN.log` — the command and a redacted summary or safe log of each
-     executable check. Never secrets, never an environment dump. Record
-     one check per command: `command` holds the command line as run, never prose
-     describing a session, and a manual smoke run is recorded as the command lines
-     that were run (separate entries when they establish independent outcomes).
-     Independently assessed commands — the tracked `.env` check, the secret scan,
-     the dependency audit — are separate `checks` entries with their own `result`
-     and log, so only the tool that could not run is `unverified`. A test runner
-     such as `npm test` stays one aggregate check; do not split every subprocess or
-     assertion. Visual and review checks keep their kinds and get no artificial
-     shell command. Note a redaction rather than inventing a substitute command.
-   - `visual/<scenario>.png` — each visual capture from step 4, with its scenario,
-     viewport and observed result recorded in the manifest. When nothing renders,
-     record `visual_review: {applicable: false, reason}` and say why.
-   - `review/code-quality.md` — the reviewer's findings from step 2 with their
-     dispositions, or its explicit no-findings statement, recorded as a check of
-     kind `review` and referenced by the requirements it covers.
-   - `manifest.json` — evidence schema 1 (field list in the header of
-     `scripts/pincer-evidence.cjs`): selected PRD, full `base` and `candidate` IDs,
-     `created`, `environment` with tool limitations, `coverage_review` (your judgment
-     from step 3), one `requirements` entry per `R-NN` with its disposition, tickets
-     and check IDs, one `checks` entry per check with `kind`, `required`, `result`,
-     `command`, timestamp and artifact paths, and `artifacts` with digests from
-     `node scripts/pincer-evidence.cjs digest <file>...`.
-   A tool you cannot run yields a check with `result: unverified` and a note — never a
-   fabricated artifact. A deferred requirement carries `authorized_by` naming the
-   user's explicit authorization. Then run
-   `node scripts/pincer-evidence.cjs validate .prd/evidence/prd-vN/<candidate>/manifest.json --candidate <candidate> --prd .prd/prd-vN.md`
-   and correct the manifest until it prints `ok`; the same validator runs in status
-   and release. It checks the record's consistency, not that the commands ran.
-10. Close out: write a brief `NOTES.md` at the repo root with frontmatter:
-   ```yaml
-   ---
-   prd: .prd/prd-vN.md
-   base: <full reviewed base commit ID>
-   candidate: <full reviewed candidate commit ID>
-   evidence: .prd/evidence/prd-vN/<candidate>/manifest.json
-   ---
-   ```
-   Then commit NOTES.md, the manifest, its listed artifacts and (change records) the
-   evaluation locator — and nothing else —
-   as `evaluate: PRD vN candidate <short sha>`. Status accepts this later commit only
-   when its diff from the candidate is limited to `NOTES.md`, the candidate's evidence
-   directories and evaluation locators; changes to source, tests, configuration,
-   tickets, the PRD or the change record (a lifecycle transition after the
-   candidate) require reevaluation. Legacy notes without these references
-   do not establish readiness. Then describe what was built, what was cut
-   and why, known issues, and what you'd do next with more time. Then a **Handover**
-   section, written for the stranger who inherits this repo in six months: how to get
-   oriented (which file to read first), what each dependency is for and why it earned
-   its place, and what breaks first as the code ages (the riskiest assumption, the
-   least-tested path). This is the first document a reviewer of this repo should read;
-   summarize the requirement dispositions from the manifest in it.
-11. Suggest `/pincer-release` as the final step: "Run `/pincer-release` for a pass/fail audit of the
-   whole workflow's artifacts."
-
-## Authorization rule (shared by plan, narrow, code and evaluate)
-
-Reuse explicit authorization for the same scope and decisions; ask only about a
-material choice not already authorized, and prepare the concrete proposal before
-asking. A decision the user delegated (for example "pick the architecture") does not
-need another approval when you exercise it, but a newly discovered consequential
-choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover, and on a project with change records as
-a `change authorize` record (the user's words as the excerpt, or a `--delegated`
-disposition with its basis). An agent-written record or a status
-field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — read the `resume` report; an authorization
-it reports as `current` needs no repeat approval, and any other verdict is asked.

package/template/.claude/commands/pincer-narrow.md

@@ -1,146 +0,0 @@
----
-description: "Turn the approved PRD into local, AI-ready ticket files"
-argument-hint: "Path to PRD (optional — defaults to the latest in .prd/)"
----
-
-# /pincer-narrow — PRD to Local Tickets
-
-You are decomposing the PRD into coherent, independently verifiable tickets stored as
-local markdown files (no external tracker needed). Ticket count and size follow the
-change's dependencies and risk, plus any budget the user supplied. There is no hard
-one-to-two-ticket cap for small PRDs and no default timebox: cohesion and dependencies
-decide the count. A breakdown that follows the PRD needs no second approval; a newly
-discovered consequential choice is surfaced before implementation.
-
-**Initial request:** $ARGUMENTS
-
-## Steps
-
-1. Run `scripts/pincer-status.sh`. If tickets already exist for another PRD, leave them
-   as history. New tickets continue the numbering and existing ones are never renumbered.
-   If tickets already exist for this PRD, extend them only when the current request already
-   authorizes that work; otherwise present the concrete addition before asking. Then read the
-   PRD (`$ARGUMENTS` or the latest `.prd/prd-v*.md`). If its status isn't `draft`, ask
-   which PRD to use.
-2. Decompose into tickets. Rules:
-   - Each ticket is one coherent unit. Use S, M, or L as relative scope indicators and
-     split work when that improves dependency order, verification, or ownership.
-   - For greenfield work, use a walking skeleton when it reduces integration risk. For
-     brownfield work, begin with the smallest protected vertical change; add a
-     characterization ticket before changing load-bearing code that lacks coverage.
-   - Order by dependency; note blockers explicitly ("depends on T-01").
-   - Build the requirement map: for every `R-NN` in the PRD and each of its
-     scenarios, name the ticket that owns the implementation and the executable
-     check that exercises it, or an explicit review method when no executable check
-     exists. Record the IDs in each ticket's Context as `Implements: R-NN, R-MM`
-     (a navigation aid). Enabling work that implements no requirement states its purpose
-     in the ticket Objective. Resolve missing coverage and conflicting criteria with
-     the user before implementation; do not start with an unmapped required scenario. On a change with change records, author the map once as
-     `.prd/coverage/<change id>.json` (coverage map schema 1, "Coverage map" in
-     `docs/runtime-contracts.md`). Start from
-     `node scripts/pincer-runtime.cjs coverage scaffold --change <change id>`: it prints
-     a read-only draft listing every live scenario exactly once with its requirement,
-     every ticket with its objective, its own `Implements:` claim and its Verification
-     text, and an `Unresolved` list of what is still unauthored. It writes nothing,
-     adopts nothing and decides nothing — it removes the transcription, not the
-     judgment, so a ticket's claim is material to check rather than a link, and no check
-     command, ticket role or scope disposition is ever invented. The draft is not a map:
-     it carries no `schema` key and `coverage adopt` refuses it. You author the real map
-     yourself, working through the draft's unresolved entries:
-     one `scenarios` row per `S-NN` naming its
-     implementing tickets and declared checks, every ticket of the change in
-     `tickets` as `implements` or `enables` (with a rationale), each check declared
-     once in `checks` with its kind, `required` flag and, for a command, the exact
-     command line and timeout, and a `scope` entry (`deferred` or `removed`) for a
-     scenario this change will not deliver, naming the decision that records the
-     user's choice. The map is authored work you edit by hand; the runtime never
-     rewrites it, and it validates it against the PRD's definitions.
-   - Every ticket gets a runnable command in its Verification block — a fenced `bash`
-     block that exits 0 only when the ticket is done. `scripts/pincer-ticket.sh verify`
-     runs it verbatim and stamps the receipt that `done` requires, so it must be
-     non-interactive and self-contained (no "check by hand"). An optional
-     `timeout: <seconds>` frontmatter field (default 600) bounds the run; it is part of
-     the check identity, so changing it invalidates earlier passes.
-   - Each Verification section opens with `Proves:` — what the check establishes and
-     which regression it detects. A check for an executable change must exercise
-     observable behavior (including relevant rejection paths and, in brownfield work,
-     preservation of existing behavior) and fail when the behavior is wrong, not only
-     when an identifier is renamed. Reuse adequate focused tests. A build, a syntax
-     check, or an identifier grep alone is not proof; static assertions are primary
-     evidence only for static contracts such as generated files, and `Proves:` says so.
-   - Adequacy is a judgment about what the command observes, never a word match: do
-     not call a command sufficient because it contains `grep`, `test`, or a runner
-     name, nor insufficient for lacking them. Manual visual judgment is recorded
-     separately in evaluation; a tool the check needs but cannot run yields an
-     explicit `unverified` result, never fabricated evidence or a silent waiver.
-   - If the brief or stack implies automated tests, at least one ticket's verification
-     command must be the test runner (e.g. `npm test`) — manual checks alone don't count.
-   - Any ticket whose surface accepts external input (HTTP endpoint, form, file,
-     LLM output) gets an acceptance criterion for the reject path — what invalid
-     input produces (e.g. "empty goal → 400 with a clear message"), not only the
-     happy path.
-   - A greenfield setup ticket includes `.gitignore` covering `.env*` (except
-     `.env.example`) and an `.env.example` naming any required secrets before any
-     secret can exist in the repo. In brownfield repositories, preserve and verify
-     the existing ignore and environment conventions.
-3. Write each ticket to `tickets/T-{NN}-{slug}.md` using
-   `.claude/references/ticket-template.md`, with `status: open` and an explicit
-   `prd: .prd/prd-vN.md` naming the selected PRD. Never infer this association from
-   numbering or old notes. The other state fields
-   (`started`, `last_check`, `verified`, `finished`) are added later by `scripts/pincer-ticket.sh` —
-   never write them yourself.
-4. Present the ticket list (number, title, size, dependencies) as a table, followed
-   by the requirement map as a second table (requirement · scenario · ticket · check
-   or review method). Whether the map is complete and each check is adequate is your
-   judgment as the author; say so rather than presenting the table as mechanical proof.
-
-Present the concrete breakdown and build order as a report, not a question. Reuse
-existing authorization for the same scope and order.
-
-5. Finalize. A breakdown that follows the PRD is already authorized by the PRD: do not
-   ask whether to proceed. Update the selected PRD frontmatter to `status: ticketed`,
-   inspect existing staged changes, stage that PRD and the explicit new ticket paths,
-   review `git diff --cached`, and commit only those paths. Ask first — and finalize
-   once it is resolved — only when step 4 surfaced a newly discovered consequential
-   choice or a scope change the PRD does not cover. Then register the change when the
-   `Runtime` status line says `legacy` and no ticket of this PRD carries legacy
-   receipts, or `changes` (the project already keeps change records):
-   `node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md` writes the change
-   record `.prd/changes/prd-vN.json` (retaining every earlier change); stage
-   `.prd/changes/` and `.gitignore` (registration adds `.pincer/` to it) and commit them
-   as `Register PRD vN`. Then record the user's actual approval against the agreement
-   the record binds — `node scripts/pincer-runtime.cjs change show prd-vN --json`
-   prints the agreement digest — with
-   `node scripts/pincer-runtime.cjs change authorize prd-vN --agreement <digest> --reference "<where the user said it>" --excerpt "<the user's approval, quoted>"`,
-   select it for this worktree (`node scripts/pincer-runtime.cjs change select prd-vN`)
-   and commit `.prd/changes/` as `Authorize PRD vN`. When the map was authored, adopt
-   strict coverage explicitly: `node scripts/pincer-runtime.cjs coverage adopt --preview --change prd-vN`
-   shows the inventory, the map digest and the agreement it records (it refuses an
-   incomplete map, naming the scenario or ticket); `--apply` writes the schema 3
-   record with a backup and grants nothing — record the user's approval of that
-   agreement with `change authorize` (the same instruction, if it named this
-   breakdown; a delegated disposition needs its basis) and commit `.prd/coverage/`
-   and `.prd/changes/` as `Adopt strict coverage for PRD vN`. A scenario the user
-   deferred or removed is a decision: `change decide --summary "<the choice>"`,
-   `--resolve D-NN` with the user's words naming the scenario, the `scope` entry in
-   the map, then `change authorize … --decision D-NN`. Never record a disposition
-   the user did not state; `coverage` reports `SCOPE_UNAUTHORIZED` until it is. The excerpt records the user's own
-   words; running the command proves nothing by itself, and a registration, a PRD
-   status or a passing check never becomes an authorization. A project whose tickets
-   carry legacy receipts, or that still holds a v0.5.0 binding (`Runtime  change <id> ·
-   revision …`), is migrated from `/pincer-code` after a preview, never here. Finish with:
-   "Tickets ready in `tickets/`. Run `/pincer-code` to start implementing."
-
-## Authorization rule (shared by plan, narrow, code and evaluate)
-
-Reuse explicit authorization for the same scope and decisions; ask only about a
-material choice not already authorized, and prepare the concrete proposal before
-asking. A decision the user delegated (for example "pick the architecture") does not
-need another approval when you exercise it, but a newly discovered consequential
-choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover, and on a project with change records as
-a `change authorize` record (the user's words as the excerpt, or a `--delegated`
-disposition with its basis). An agent-written record or a status
-field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — read the `resume` report; an authorization
-it reports as `current` needs no repeat approval, and any other verdict is asked.

package/template/.claude/commands/pincer-plan.md

@@ -1,132 +0,0 @@
----
-description: "Create a PRD through brief discovery, codebase scan, and an architecture gate"
-argument-hint: "Brief description of the task/feature (paste the full brief if you have one)"
----
-
-# /pincer-plan — PRD Creation
-
-You are turning a task brief into a reviewable PRD. Scale discovery and detail to
-the change's uncertainty, risk, and any time budget the user supplied. The PRD feeds
-`/pincer-narrow` next.
-
-Choose the planning profile and record why it fits: `profile: small` for bounded
-scope, low risk, known behavior and straightforward verification; otherwise
-`standard` (the default). Few changed lines alone do not qualify — migrations,
-authorization boundaries, uncertain requirements and broad effects need proper
-investigation even for a tiny patch. Honor an explicit budget the user supplied;
-there is no default timebox, and a budget never silently cuts requirements —
-record any cut in Out of Scope.
-
-**Initial request:** $ARGUMENTS
-
-First run `scripts/pincer-status.sh`. If a PRD already exists, preserve it and select
-the next unused numeric version for this change. Use the brief and repository state to
-distinguish a revision from a new change; ask only if that distinction changes scope or
-architecture. If tickets for the current PRD are in progress, resume `/pincer-code`
-unless the user explicitly authorized a separate change.
-
-## Phase 1: Discovery
-
-1. If `$ARGUMENTS` contains the brief, extract what you can before asking anything.
-   Never ask a question the brief already answers. Preserve or link the original
-   brief in the PRD, and record the desired outcome, assumptions and exclusions.
-   If the user supplied a PRD, review it: keep its meaning and existing requirement
-   IDs; do not silently replace either. Where its structure needs adapting to the
-   template, record a mapping table (`their section or ID → R-NN`) inside the PRD.
-2. Ask only the questions whose answers would change the architecture or scope.
-   Batch them (max 3–4 at once). A question the brief partly answers is
-   asked only for its open part, naming the settled part; when the brief settles
-   every material decision, including acceptance behavior, ask no discovery
-   question and record the brief's answers. Do not add a question to fill the budget.
-   Typical ones:
-   - What does "done" look like — what will be run, demoed, or reviewed at the end?
-     A named test runner settles the verification choice, not every acceptance
-     behavior; ask about the demo or manual check only if that is still open.
-   - Any required stack, or is it my choice?
-   - What is explicitly out of scope?
-3. If the project has a frontend, ask one design question: "What should this feel like,
-   and what should it NOT look like?" Capture the answer for the Visual Direction section.
-   The same rule applies: when the brief already supplies design direction, record it
-   and ask only about what it leaves open.
-
-Summarize your understanding in 3–5 sentences. Existing authorization in the request or
-session carries forward; ask only about an unresolved choice that materially changes the result.
-
-## Phase 2: Codebase scan (conditional)
-
-If the repo already contains source code, launch 1–2 `codebase-explorer` agents in parallel
-(one for architecture/structure, one for patterns relevant to the feature). Read the 2–3 most
-load-bearing files they identify yourself — don't rely solely on agent summaries. If the
-repo is empty, skip and say so. (No subagents on this platform? Do the exploration
-yourself, inline, following the rules in `.claude/agents/codebase-explorer.md`.)
-
-**Brownfield scaling:** if the existing code is substantial or load-bearing (production
-traffic, other consumers, no green test suite), this phase grows and Phase 4 shrinks —
-a wrong map costs more than a thin PRD. Additionally establish: which paths the change
-touches are load-bearing, what test coverage protects them (run the suite, don't assume),
-and the blast radius + rollback story for the change. Record these in the PRD's
-Architecture section. Greenfield speed assumptions do not transfer to brownfield work.
-
-## Phase 3: Architecture
-
-Propose the architecture: components, data flow, integration points, and key decisions.
-- Recommend one approach; mention an alternative only when the trade-off is real.
-- Name the trust boundaries in one or two sentences: which inputs are untrusted
-  (user input, LLM output, third-party responses), where each is validated, and
-  which secrets exist and where they live (server-side only). This becomes the
-  PRD's Security section when the project handles secrets or external input.
-- Verify versions of key dependencies with `npm view <pkg> version` (or the ecosystem's
-  equivalent) before naming them — don't trust training data.
-- Verify the contract of any external API the plan builds on (one live request or the
-  current official docs) before designing around it — endpoint shapes remembered from
-  training data are guesses.
-- Respect any explicit delivery budget. Record deliberate cuts in Out of Scope.
-
-Prepare the full draft before seeking any approval still required. The user should review a
-concrete scope and architecture; do not repeat an approval already given for the same decision.
-
-## Phase 4: Write the PRD
-
-1. Load `.claude/references/prd-template.md` and write all core sections.
-   In Requirements, assign stable `R-NN` IDs within the selected PRD: a revision
-   keeps existing IDs and adds new ones, never renumbers. Every requirement has
-   observable acceptance scenarios, the relevant failure paths, and the existing
-   behavior it must preserve, each written as a bold `- **S-NN:** …` item under its
-   requirement heading (the template's grammar; the runtime parses exactly these
-   definitions into the inventory that strict coverage tracks, and a requirement
-   without a scenario is invalid there) — `/pincer-narrow` maps each scenario to a
-   ticket and a check in the coverage map, and `/pincer-evaluate` dispositions every
-   ID. A supplied PRD keeps its own uppercase IDs (`REQ-1`, `AC-3`); only its
-   definition syntax is adapted, and the mapping table records what changed.
-2. Include optional sections when risk or the product context warrants them.
-3. Save to the next unused `.prd/prd-v{N}.md` (create `.prd/` if needed), with `N`
-   matching the filename and frontmatter:
-   ```yaml
-   ---
-   version: {N}
-   status: draft
-   date: {today}
-   profile: small   # only when small; omit for standard
-   ---
-   ```
-4. If `.git/` doesn't exist, run `git init`. Commit the PRD and only the intended setup
-   paths after inspecting existing staged work; planning should be visible in history
-   without absorbing unrelated brownfield changes.
-
-Present the saved draft and obtain approval only when the same scope/architecture was not
-already authorized. Finish with: "PRD saved to `.prd/prd-v{N}.md`. Run `/pincer-narrow`
-to break it into work items."
-
-## Authorization rule (shared by plan, narrow, code and evaluate)
-
-Reuse explicit authorization for the same scope and decisions; ask only about a
-material choice not already authorized, and prepare the concrete proposal before
-asking. A decision the user delegated (for example "pick the architecture") does not
-need another approval when you exercise it, but a newly discovered consequential
-choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover, and on a project with change records as
-a `change authorize` record (the user's words as the excerpt, or a `--delegated`
-disposition with its basis). An agent-written record or a status
-field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — read the `resume` report; an authorization
-it reports as `current` needs no repeat approval, and any other verdict is asked.

package/template/.claude/commands/pincer-release.md

@@ -1,80 +0,0 @@
----
-description: "Audit the repo against the workflow checklist — pass/fail per item, no fixes"
-argument-hint: "Stage to check (optional: plan | narrow | code | evaluate — defaults to all completed stages)"
----
-
-# /pincer-release — Workflow Audit
-
-You are auditing the current repo state against `docs/release-checklist.md`. Read-only:
-report pass/fail, never fix anything — fixes belong to the stage commands. Release does
-not repair tickets, rewrite evidence, change PRD state, or publish. A check that mutates
-the candidate invalidates the audit: if `git status --short` is not empty afterwards,
-the verdict is FAIL and names the mutation. The verdict is reported to the user; a
-durable runtime-owned release record is later work.
-
-**Requested stage:** $ARGUMENTS
-
-## Steps
-
-1. Read `docs/release-checklist.md` — it is the source of truth for product-candidate
-   readiness. `docs/dry-run-checklist.md` is a separate manual platform trial and must
-   not impose toy-project or Pincer-kit assumptions on this audit.
-2. Run `scripts/pincer-status.sh` to determine the selected PRD and which stages have run
-   (it reads `.prd/`, associated `tickets/`, `NOTES.md`; add `git log`). If `$ARGUMENTS`
-   names a stage, check only up
-   to that stage.
-3. Check every applicable item mechanically where possible:
-   - File existence and frontmatter: read the files.
-   - Commit format and story: `git log --oneline`.
-   - Receipts: every done ticket is ready — on a legacy project current `last_check`
-     and `verified` receipts, on a migrated project a current passing attempt
-     (`node scripts/pincer-runtime.cjs ready` exits 0); any status warning fails the
-     audit. Do not call `pincer-ticket.sh` from Release:
-     it writes receipts and would invalidate the evaluated candidate. Release never
-     runs `verify`, `check` or `done`; `status`, `ready` and the project gate are its
-     only commands.
-   - Evidence: `scripts/pincer-status.sh` runs the shared validator
-     (`scripts/pincer-evidence.cjs`) against the manifest `NOTES.md` names. The `Notes`
-     line must read `current` and the `Evidence` line `ok`; any other text fails the
-     audit with that diagnostic. Do not re-implement evidence checks and do not accept
-     screenshots described in chat: read the manifest's `checks`, requirement
-     dispositions and `visual_review`. Validation establishes that the record is
-     consistent, not that the commands ran — say so if asked.
-   - Provenance: status prints a `Provenance` line for the evaluated candidate:
-     `runtime (schema 2)` with local attempts consistent, or `legacy (schema 1, authored
-     command results)`. A newer local attempt that failed, timed out, was interrupted or
-     is still running for the same check and source inputs fails the audit (`ready`
-     exits 1 and names the check). A fresh clone reports `local verification history
-     unavailable; saved candidate evidence validated only`: state that limit in the
-     verdict rather than claiming local verification.
-   - Change records (the `Runtime` line reads `changes`): the selected change is
-     `completed`, its authorization is `current` for the current agreement, and its
-     evaluation locator `.prd/evidence/changes/<id>.json` names the evaluated
-     candidate; `node scripts/pincer-runtime.cjs ready` reports `SELECTION_REQUIRED`,
-     `LIFECYCLE_BLOCKED`, `DECISION_REQUIRED`, `AUTHORIZATION_REQUIRED` or
-     `AGREEMENT_CHANGED` as failures. Release selects, activates and completes nothing;
-     historical evidence of a cancelled or superseded change is inspectable but never
-     release-ready.
-   - Strict coverage (the status line reads `Coverage strict …`): read
-     `node scripts/pincer-runtime.cjs coverage` — structure complete, every in-scope
-     scenario `delivered` on the evaluated candidate, deferrals and removals backed by
-     their decision and user authorization, `delivery` reported as original versus
-     agreed scope (never conflate them), adequacy `adequate`; the manifest is schema 3
-     and the `Provenance` line reads `runtime (schema 3)`. `ready` names
-     `COVERAGE_INCOMPLETE`, `SCOPE_UNAUTHORIZED`, `OBLIGATION_MISSING`,
-     `REVIEW_MISSING` and `ADEQUACY_REQUIRED` as failures. A change labeled
-     `Coverage unverified` did not adopt strict coverage: audit it under the rules
-     above and say so; never imply strict coverage was established.
-   - Every file the manifest lists is tracked, and `git status --short` is empty before
-     and after the audit.
-   - Run the repository's candidate-wide release gate directly (`npm test`, or the
-     equivalent declared by the project) and report its actual output. Any failure
-     blocks PASS. Confirm `git status --short` remains clean afterward.
-4. For judgment items (tickets genuinely S/M, history reads as a story), give your
-   verdict AND one sentence of evidence — never a bare pass.
-5. Present a table: checklist item | pass/fail/skipped | evidence. Order by stage.
-6. End with a one-line verdict naming the candidate: "PASS — candidate {sha}: workflow
-   artifacts complete" or "FAIL — candidate {sha}: {n} items failed; fix via {command}".
-   Fixes go through a new ticket, a new candidate and a new evaluation. For each failure, name the command
-   file (`.claude/commands/*.md`) whose instructions should be tightened if the
-   failure is a workflow bug rather than a run mistake.

package/template/.claude/references/prd-template.md

@@ -1,108 +0,0 @@
-# PRD Template
-
-Used by `/pincer-plan` Phase 4. Core sections are always included. Add optional detail
-when uncertainty, product context, or risk warrants it; a small fix may remain compact.
-
-## Profile
-
-The frontmatter field `profile: small | standard` sets the planning weight; a PRD
-without it is `standard`. `small` means bounded scope, low risk, known behavior and
-straightforward verification. Few changed lines alone do not qualify: migrations,
-authorization boundaries, uncertain requirements and broad effects stay `standard`
-even for a tiny patch. The PRD records in one or two sentences why the profile fits.
-
-A small PRD keeps Problem (with the outcome), Scope, Requirements with scenarios,
-Success Criteria (its verification), risks and exclusions, and omits empty sections
-and repetition. Interface examples may clarify a contract; implementation code must
-not substitute for requirements in any profile.
-
----
-
-## Core Sections (always include)
-
-### 1. Problem
-What problem does this solve? Who has it? (2–4 sentences.) Preserve or link the
-original brief (quote it in an appendix or name where it lives) so the source of
-every requirement stays reviewable.
-
-### 2. Solution
-One-paragraph summary of what we're building: the desired outcome, the assumptions
-it rests on, and what it deliberately excludes.
-
-### 3. Scope
-
-| This PRD covers | This PRD does NOT cover |
-| --- | --- |
-| ... | ... |
-
-### 4. Requirements
-One entry per requirement with a stable ID. IDs are assigned once within this PRD
-and never renumbered: a revision keeps existing IDs and adds new ones. Tickets
-name the IDs they implement and evaluation dispositions every ID.
-
-#### R-01 — short title
-- **S-01:** an observable acceptance scenario (given / when / then, or a command
-  and its expected output). One bold `S-NN` item per scenario, defined under its
-  requirement heading; every requirement has at least one.
-- **S-02:** Failure path: what invalid input or the relevant failure produces.
-- **S-03:** Preserve: existing behavior this must not change (brownfield).
-
-Scenario IDs are stable like requirement IDs. The runtime reads exactly this
-grammar (a `##`..`####` heading `R-NN — title`, bold `- **S-NN:** text` items
-under it, continuation lines indented); mentions in prose, tables and fenced
-examples define nothing. On a change with strict coverage the parsed inventory is
-what the coverage map and the evaluation must cover completely.
-
-When the user supplied a PRD, keep its meaning and its existing requirement IDs.
-If its structure needs adapting to this template, add a `Requirement mapping`
-table under this section (`their section or ID → R-NN`) instead of rewriting it.
-
-### 5. Architecture
-
-#### Structure
-```
-directory tree showing new/modified files
-```
-
-#### Key components
-What each component does, owns, and depends on.
-
-#### Data flow
-Input → processing → output.
-
-### 6. Success Criteria
-
-| Criterion | How to verify |
-| --- | --- |
-| ... | a command to run or a thing to observe |
-
-### 7. Out of Scope
-Explicit list. Anything cut for time during `/pincer-code` gets appended here with a reason.
-
----
-
-## Optional Sections (include when relevant)
-
-### Visual Direction
-Only if there's a frontend. 4–6 lines: tone (3 concrete words), theme (light/dark + why),
-typography pairing, colour direction (dominant + accent), and what to avoid.
-
-### Security & Trust Boundaries
-Include whenever the project handles secrets or external input (which is almost always).
-3–5 lines: which inputs are untrusted and where each is validated, which secrets exist
-and where they live (server-side only, named in `.env.example`), and what the client
-sees on failure (generic message — details stay in server logs).
-
-### Dependencies & Risks
-Include when something outside our control or a migration/rollback concern could sink delivery.
-
----
-
-## Formatting Rules
-
-- Save as `.prd/prd-v{N}.md` with YAML frontmatter (`version`, `status`, `date`,
-  and `profile` when small).
-- Status lifecycle: `draft → ticketed → built`.
-- Diagrams as ASCII or markdown tables only.
-- No implementation code and no exact line numbers — those belong in tickets.
-- The Scope table always has both columns filled.