pincer-workflow 0.1.0 → 0.2.1

package/README.md

@@ -7,6 +7,10 @@ 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.
+
 ## Install
 
 ```bash
@@ -14,20 +18,75 @@ cd your-project
 npx pincer-workflow init     # asks which platform(s) you use
 ```
 
-Then follow the chain — identical on every platform:
+Then follow the chain — the same five steps on every platform:
 
 ```
 /pincer-plan <brief>  →  /pincer-narrow  →  /pincer-code  →  /pincer-evaluate  →  /pincer-release
 ```
 
-Per-platform notes printed by `init`:
+`/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 same commands carry the `/prompts:` prefix Codex gives every
+custom prompt: `/prompts:pincer-plan <brief>` → `/prompts:pincer-narrow` →
+`/prompts:pincer-code` → `/prompts:pincer-evaluate` → `/prompts:pincer-release`,
+and `/prompts: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
+
+`AGENTS.md` loads natively, so the rules apply with no setup. Codex reads
+custom prompts only from `~/.codex/prompts/` (there is no repo-local location)
+and does not create that directory itself, so install the prompts once:
+
+```bash
+mkdir -p ~/.codex/prompts && cp .codex/prompts/*.md ~/.codex/prompts/
+codex
+```
+
+Then `/prompts:pincer-plan <brief>` and the rest of the chain are available in
+every Codex session. The playbooks refer to each other by their short names
+(`/pincer-narrow` etc.) — read those as `/prompts:pincer-narrow` in Codex.
+Re-run the copy after `npx pincer-workflow@latest update` or after editing a
+playbook; `update` prints the reminder.
+
+Codex has no PreToolUse hooks, so the guardrail posture lives in
+`~/.codex/config.toml` instead — `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
+`/prompts:pincer-status` flags any ticket marked done without a receipt.
+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`.
+
+## Claude Code plugin (alternative)
+
+Claude users can install PINCER as a plugin instead — commands arrive
+namespaced (`/pincer:plan` … `/pincer:release`) and update automatically
+through the marketplace:
+
+```
+/plugin marketplace add orchestratedbyalex/pincer-workflow
+/plugin install pincer@pincer-workflow
+```
 
-- **Claude Code** — works immediately; commands, subagents, permission deny
-  rules, and a destructive-command hook install to `.claude/`.
-- **Codex CLI** — rules load natively from `AGENTS.md`; copy the prompts once:
-  `cp .codex/prompts/*.md ~/.codex/prompts/` (posture notes in `.codex/README.md`).
-- **Copilot (VS Code)** — enable `"chat.promptFiles": true`, then run
-  `/pincer-plan` in chat; `.github/copilot-instructions.md` is wired to `AGENTS.md`.
+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).
 
 ## Update
 
@@ -35,7 +94,7 @@ Per-platform notes printed by `init`:
 npx pincer-workflow@latest update
 ```
 
-Files you never touched are refreshed in place. Files you edited are left
+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.1 corrects the Codex install step: `~/.codex/prompts/` must be created first, and the commands are invoked as `/prompts:pincer-*`.) 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).
@@ -45,11 +104,14 @@ alone — the new version lands next to them as `<file>.new` for a manual merge.
 | 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 (canonical — adapters are generated from them) |
+| `.claude/commands/` | The five playbooks plus `/pincer-status` (canonical — adapters are generated from them) |
 | `.claude/agents/` | `codebase-explorer` and `code-quality-reviewer` subagents, with inline fallbacks for platforms without subagents |
-| `.claude/hooks/` + `settings.json` | Mechanical guardrails: `.env` files unreadable, destructive commands blocked |
-| `.codex/` · `.github/` | Generated Codex and Copilot adapters + platform wiring |
+| `scripts/pincer-ticket.sh` | The ticket state machine: `start` (enforces dependency order) → `verify` (runs the ticket's check, stamps a receipt only on green) → `done` (refuses without a matching receipt or with unticked criteria) |
+| `scripts/pincer-status.sh` | Read-only state report: PRD, every ticket with clock-based elapsed time, blocked tickets, build time vs budget, next command |
+| `.claude/hooks/` + `settings.json` | Mechanical guardrails: `.env` files unreadable, destructive commands blocked, ticket state fields writable only through the script |
+| `.codex/` · `.github/` | Generated Codex and Copilot adapters + platform wiring (`.codex/README.md` covers the Codex install and posture) |
 | `scripts/sync-prompts.sh` | Regenerates the adapters after you edit a playbook |
+| `scripts/build-plugin.sh` | Regenerates the Claude Code plugin (`plugin/`) from the template |
 | `docs/dry-run-checklist.md` | The workflow's own test — audited by `/pincer-release` |
 
 ## Design principles
@@ -58,7 +120,11 @@ alone — the new version lands next to them as `<file>.new` for a manual merge.
   every scope, and every merge; autonomy runs only between gates, bounded by a
   timebox and one revision loop.
 - **Nothing is done while its verification fails** — every ticket carries a
-  runnable check.
+  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.
+- **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.
 - **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,

package/bin/pincer.js

@@ -21,12 +21,12 @@ const VERSION = createRequire(import.meta.url)('../package.json').version;
 const MANIFEST = '.pincer.json';
 
 const PLATFORM_ROOTS = {
-  common: ['AGENTS.md', 'docs/dry-run-checklist.md', 'scripts/sync-prompts.sh'],
+  common: ['AGENTS.md', 'docs/dry-run-checklist.md', 'scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh'],
   claude: ['CLAUDE.md', '.claude'],
   codex: ['.codex'],
   copilot: ['.github'],
 };
-const EXECUTABLES = ['scripts/sync-prompts.sh', '.claude/hooks/block-dangerous.sh'];
+const EXECUTABLES = ['scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', '.claude/hooks/block-dangerous.sh', '.claude/hooks/ticket-guard.sh'];
 const GITIGNORE_LINES = ['.env', '.env.*', '!.env.example'];
 
 const sha = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
@@ -123,18 +123,24 @@ function report({ written, skipped, conflicted }) {
   }
 }
 
+// Codex loads custom prompts from ~/.codex/prompts/ only and never creates that
+// directory itself — a bare `cp` there fails with "Not a directory" on a fresh machine.
+const CODEX_INSTALL = 'mkdir -p ~/.codex/prompts && cp .codex/prompts/*.md ~/.codex/prompts/';
+
 function nextSteps(platforms) {
   console.log('\nNext steps:');
   if (platforms.includes('claude')) {
     console.log('  Claude Code   start `claude` in this repo and run /pincer-plan <brief>');
   }
   if (platforms.includes('codex')) {
-    console.log('  Codex CLI     cp .codex/prompts/*.md ~/.codex/prompts/   (once; posture notes in .codex/README.md)');
+    console.log(`  Codex CLI     ${CODEX_INSTALL}`);
+    console.log('                (once; Codex has no repo-local prompts) then `codex` and /prompts:pincer-plan <brief> — posture notes in .codex/README.md');
   }
   if (platforms.includes('copilot')) {
     console.log('  Copilot       enable "chat.promptFiles": true in VS Code settings, then /pincer-plan in chat');
   }
   console.log('  All rules live in AGENTS.md — fill in its Conventions section once you know the stack.');
+  console.log('  Any session     scripts/pincer-status.sh shows where the workflow stands (also /pincer-status)');
 }
 
 async function askPlatforms() {
@@ -180,7 +186,7 @@ async function cmdUpdate() {
   console.log(`\nUpdating PINCER ${manifest.version} -> ${VERSION} for: ${manifest.platforms.join(', ')}\n`);
   report(install(dir, manifest.platforms, manifest.files));
   if (manifest.platforms.includes('codex')) {
-    console.log('\n  Codex uses global prompts — re-run: cp .codex/prompts/*.md ~/.codex/prompts/');
+    console.log(`\n  Codex uses global prompts — re-run: ${CODEX_INSTALL}`);
   }
 }
 
@@ -237,6 +243,6 @@ Usage:
   npx pincer-workflow update
   npx pincer-workflow doctor
 
-Docs: https://github.com/lexanderg/pincer-workflow`);
+Docs: https://github.com/orchestratedbyalex/pincer-workflow`);
   process.exit(cmd ? 1 : 0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pincer-workflow",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "PINCER — a PRD-driven agentic delivery workflow for Claude Code, Codex CLI, and GitHub Copilot. Plan · Investigate · Narrow · Code · Evaluate · Release.",
   "bin": {
     "pincer": "bin/pincer.js"
@@ -14,7 +14,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/smoke.test.js"
+    "test": "node test/smoke.test.js && node test/ticket.test.js"
   },
   "keywords": [
     "claude-code",
@@ -30,6 +30,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lexanderg/pincer-workflow.git"
+    "url": "git+https://github.com/orchestratedbyalex/pincer-workflow.git"
   }
 }

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

@@ -10,40 +10,59 @@ user confirms the starting point, run continuously and report progress between t
 
 **Initial request:** $ARGUMENTS
 
+Ticket state lives in the ticket file's frontmatter and is written **only** by
+`scripts/pincer-ticket.sh` (`start` → `verify` → `done`). `verify` runs the ticket's
+Verification block and stamps a receipt only on a green exit; `done` refuses without a
+receipt that matches the current check, or with unticked acceptance criteria. Never edit
+`status`, `started`, `verified`, or `finished` by hand — on Claude Code a hook blocks it.
+
+## Before the loop
+
+Run `scripts/pincer-status.sh`. It lists every ticket's state, what is blocked, elapsed
+build time from the clock, and the next action. If a ticket is `in_progress`, you are
+resuming: read it, check `git status` / `git diff` for uncommitted work, and continue
+from wherever the receipt says you are. Confirm the starting point with the user, then go.
+
 ## Loop (per ticket, in dependency order)
 
-1. **Read the ticket** and the files it references. Announce: "Starting T-{NN}: {title}."
+1. **Start:** `scripts/pincer-ticket.sh start T-{NN}` — refuses while a `depends_on` ticket
+   isn't done, and stamps the start time. Read the ticket and the files it references.
+   Announce: "Starting T-{NN}: {title}."
 2. **Implement.** Follow the conventions in `CLAUDE.md` and the PRD's architecture and
    visual direction. Installing a dependency not named in the PRD's architecture is a
    stop-and-ask: verify it's the real package on the registry (linked repo, downloads —
-   hallucinated names get typosquatted), say why it earns its place, and wait for a yes. For an S ticket, implement directly. For an M ticket touching
-   isolated files, you may dispatch a subagent with a clean prompt: paste the full ticket
-   body, the relevant conventions, and nothing else.
-3. **Verify.** Run the ticket's verification command(s). If they fail, fix before moving
-   on — never mark a ticket done on a red check. Report actual output, not assumptions.
+   hallucinated names get typosquatted), say why it earns its place, and wait for a yes.
+   For an S ticket, implement directly. For an M ticket touching isolated files, you may
+   dispatch a subagent with a clean prompt: paste the full ticket body, the relevant
+   conventions, and nothing else.
+3. **Verify:** `scripts/pincer-ticket.sh verify T-{NN}` — runs the Verification block and
+   writes the receipt only if it exits 0. Red → fix and re-run; report the actual output,
+   not assumptions. Green output is the definition of done, not your confidence.
 4. **Self-review the diff** before committing: silent failures (empty catches,
    un-awaited promises), leftover debug code, drift from the ticket's acceptance criteria.
    Then a security sweep of the same diff:
    - No secret values: run
-     `git diff --cached | grep -iE '(api[_-]?key|secret|token|password)[[:space:]]*[:=]'`
+     `git diff | grep -iE '(api[_-]?key|secret|token|password)[[:space:]]*[:=]'`
      and treat any hit that isn't a `process.env` reference or a name in
      `.env.example` as a blocker.
    - External input touched by this diff is validated server-side, and untrusted
      content (user input, LLM output) is escaped where rendered — per the
      Security defaults in `CLAUDE.md`.
    - No error path leaks internals (stack traces, key names with values) to the client.
-5. **Commit** with message `T-{NN}: {title}` and mark the ticket done: set
-   `status: done` in its frontmatter and tick every verified acceptance-criteria
-   checkbox (`- [ ]` → `- [x]`) in the same edit. A ticket is never `done` with
-   unticked criteria — if a criterion was cut, that's a scope change to record,
-   not a box to skip.
-6. Give a one-line progress update ("T-02 done, 3 remaining, ~40 min elapsed") and continue.
+   If the review changed code, run `verify` again — the receipt must match the code you commit.
+5. **Close the ticket:** tick every verified acceptance-criteria checkbox (`- [ ]` → `- [x]`;
+   editing the checkboxes is allowed), then `scripts/pincer-ticket.sh done T-{NN}`. A
+   criterion that was cut is a scope change to record in the PRD, not a box to skip.
+   Commit code and ticket file together: `git add -A && git commit -m "T-{NN}: {title}"`.
+6. Give a one-line progress update using the elapsed figure from
+   `scripts/pincer-status.sh` ("T-02 done, 3 remaining, 38m elapsed of 75m") and continue.
 
 ## Timebox rules
 
-- Track elapsed time against the ~75-minute build budget. If you're at risk of running
-  out, stop and propose a scope cut: which remaining tickets to drop or shrink. Cutting
-  scope deliberately beats an unfinished mess — record the cut in the PRD's Out of Scope.
+- The budget is ~75 minutes of build time, measured by `scripts/pincer-status.sh` from
+  the first ticket's start stamp — never estimated. If the remaining tickets won't fit,
+  stop and propose a scope cut: which remaining tickets to drop or shrink. Cutting scope
+  deliberately beats an unfinished mess — record the cut in the PRD's Out of Scope.
 - If a ticket reveals the plan was wrong, stop and say so rather than silently diverging.
   Update the ticket/PRD, then continue.
 

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

@@ -10,7 +10,10 @@ run the pipeline, then present results.
 
 ## Steps
 
-1. Get the full diff of the session: `git log --oneline` and `git diff <first-commit>..HEAD`.
+1. Run `scripts/pincer-status.sh`. Every ticket should be `done` with a 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 session: `git log --oneline` and `git diff <first-commit>..HEAD`.
 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

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

@@ -13,14 +13,19 @@ build window.
 
 ## Steps
 
-1. Read the PRD (`$ARGUMENTS` or the latest `.prd/prd-v*.md`). If its status isn't
-   `draft`, ask which PRD to use.
+1. Run `scripts/pincer-status.sh`. If tickets already exist, ask before adding to them —
+   new tickets continue the numbering, existing ones are never renumbered. 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: sized S or M, never L. Split anything larger.
    - Ticket 1 is always the walking skeleton: project scaffold + a thin end-to-end slice
      that runs. Everything after builds on a working base.
    - Order by dependency; note blockers explicitly ("depends on T-01").
-   - Every ticket gets a verification command or check the builder can actually run.
+   - 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").
    - 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,
@@ -34,7 +39,9 @@ build window.
      is preceded by a characterization ticket — a test that pins the current
      behavior before any ticket is allowed to change it.
 3. Write each ticket to `tickets/T-{NN}-{slug}.md` using
-   `.claude/references/ticket-template.md`.
+   `.claude/references/ticket-template.md`, with `status: open`. The other state fields
+   (`started`, `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.
 
 **Gate (medium):** Ask for approval of the breakdown and build order. Adjust if pushed back.

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

@@ -11,6 +11,10 @@ timebox (~2 hours total), so discovery is brief and the PRD is lean. The PRD fee
 
 **Initial request:** $ARGUMENTS
 
+First run `scripts/pincer-status.sh`. If a PRD already exists, say so and ask whether
+this is a new version of it (`.prd/prd-v{N+1}.md` — old versions are never overwritten)
+or a fresh start; if tickets are in progress, stop and point at `/pincer-code` instead.
+
 ## Phase 1: Discovery (~5 min)
 
 1. If `$ARGUMENTS` contains the brief, extract what you can before asking anything.

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

@@ -13,12 +13,16 @@ report pass/fail, never fix anything — fixes belong to the stage commands.
 ## Steps
 
 1. Read `docs/dry-run-checklist.md` — it is the source of truth for what to check.
-2. Determine which stages have run, from the artifacts present (`.prd/`, `tickets/`,
-   git log, `NOTES.md`). If `$ARGUMENTS` names a stage, check only up to that stage.
+2. Run `scripts/pincer-status.sh` to determine which stages have run (it reads `.prd/`,
+   `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`.
-   - Ticket verification commands: run at least two, report actual output.
+   - Receipts: every done ticket carries `verified:` (a status warning means one was
+     marked done by hand). Re-run at least two checks with
+     `scripts/pincer-ticket.sh verify T-{NN}` — on a done ticket it re-checks without
+     touching the receipt — and report actual output.
 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.

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

@@ -0,0 +1,21 @@
+---
+description: "Where the workflow stands — PRD, tickets, receipts, elapsed time, next action"
+argument-hint: "[none]"
+---
+
+# /pincer-status — Where are we?
+
+You are orienting in a repo that uses PINCER, typically after a context reset or at the
+start of a session. Read-only: change nothing.
+
+## Steps
+
+1. Run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`, `tickets/`,
+   `NOTES.md`) and prints the PRD state, every ticket with its state and clock-based
+   elapsed time, what is blocked, build time against the budget, any warnings (a ticket
+   marked done without a verification receipt), and the next command to run.
+2. Report in three lines: where the workflow is, what is in progress or blocked, and the
+   next command. Quote the `Next` line as-is.
+3. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
+   `/pincer-code T-{NN}`. If the script printed a warning, surface it — a done ticket
+   without a receipt was marked by hand and needs `scripts/pincer-ticket.sh verify T-{NN}`.

package/template/.claude/hooks/ticket-guard.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# PreToolUse guard for ticket state. A ticket's state fields — status
+# (in_progress / done), started, verified, finished — are written only by
+# scripts/pincer-ticket.sh, whose `done` needs a passing verification receipt.
+# This hook makes that script the only door on Claude Code: editing tools may
+# not write those fields into tickets/T-*.md, and Bash may not sed/echo them in.
+# Creating a ticket with `status: open` and ticking acceptance boxes stay allowed.
+# Exit 2 blocks the tool call; stderr goes back to the agent.
+#
+# A guard against carelessness, not an adversary: the agent could still route
+# around it, but it can no longer do so by accident or habit.
+
+input=$(cat)
+
+field() { # dotted path into the hook JSON, e.g. tool_input.file_path
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$input" | jq -r ".$1 // empty" 2>/dev/null
+  elif command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$input" | python3 -c '
+import json, sys
+d = json.load(sys.stdin)
+for k in sys.argv[1].split("."):
+    d = d.get(k, "") if isinstance(d, dict) else ""
+print(d if isinstance(d, str) else json.dumps(d))' "$1" 2>/dev/null
+  else # crude fallback: last path segment, first match, no unescaping
+    printf '%s' "$input" | grep -oE "\"${1##*.}\"[[:space:]]*:[[:space:]]*\"([^\"\\\\]|\\\\.)*\"" | head -1 | sed -E 's/^"[^"]*"[[:space:]]*:[[:space:]]*"//; s/"$//'
+  fi
+}
+
+tool=$(field tool_name)
+# `status: open` is fine; these are the fields only the script may write.
+PROTECTED='(^|\\n|[[:space:]])(status:[[:space:]]*(in_progress|done)|started:|verified:|finished:)'
+TICKET='(^|/)tickets/T-[0-9]+[^/]*\.md$'
+
+block() {
+  echo "Blocked by PINCER ticket guard: $1 Use pincer-ticket.sh (path in the /pincer-code playbook): 'verify T-NN' writes the receipt when the check passes, 'done T-NN' flips the status. Ticking acceptance boxes and editing the body are fine." >&2
+  exit 2
+}
+
+case "$tool" in
+  Edit|Write|MultiEdit)
+    file=$(field tool_input.file_path)
+    printf '%s' "$file" | grep -qE "$TICKET" || exit 0
+    case "$tool" in
+      Edit)  new=$(field tool_input.new_string) ;;
+      Write) new=$(field tool_input.content) ;;
+      *)     new=$(field tool_input.edits) ;;
+    esac
+    [ -n "$new" ] || new=$input
+    if printf '%s' "$new" | grep -qE "$PROTECTED"; then
+      block "ticket state fields (status in_progress/done, started, verified, finished) are never written by hand."
+    fi
+    ;;
+  Bash)
+    cmd=$(field tool_input.command)
+    [ -n "$cmd" ] || cmd=$input
+    printf '%s' "$cmd" | grep -q 'pincer-ticket.sh' && exit 0
+    if printf '%s' "$cmd" | grep -qE 'tickets/|T-[0-9][0-9]' &&
+       printf '%s' "$cmd" | grep -qE 'status:[[:space:]]*(in_progress|done)|started:|verified:|finished:' &&
+       printf '%s' "$cmd" | grep -qE '(sed|perl)[[:space:]]+(-[a-zA-Z]*i|-i)|>|tee[[:space:]]|python|node|ruby'; then
+      block "that command writes ticket state fields from the shell."
+    fi
+    ;;
+esac
+
+exit 0

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

@@ -5,7 +5,7 @@ Used by `/pincer-narrow` for every file in `tickets/`. Filename: `T-{NN}-{slug}.
 ```markdown
 ---
 ticket: T-{NN}
-status: open        # open | done
+status: open        # open | in_progress | done
 size: S             # S (≤15 min) | M (≤30 min)
 depends_on: []      # e.g. [T-01]
 ---
@@ -35,6 +35,12 @@ One sentence: what to build and why.
 ```
 
 Rules:
+- `status` and the stamps `started`, `verified`, `finished` are written only by
+  `scripts/pincer-ticket.sh` (`start` / `verify` / `done`). `verify` runs the
+  Verification block verbatim and writes a receipt only on exit 0; `done`
+  requires that receipt to match the current block. Never write these by hand.
+- The Verification block is a fenced `bash` block that exits 0 only when the
+  ticket is done — non-interactive, no "check by hand".
 - Every ticket must be verifiable without human judgment where possible.
 - If the ticket's surface accepts external input (HTTP, form, file, LLM output),
   Requirements must state the validation and the rejection behavior, and

package/template/.claude/settings.json

@@ -17,6 +17,15 @@
             "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ticket-guard.sh"
+          }
+        ]
       }
     ]
   }

package/template/.codex/README.md

@@ -5,11 +5,20 @@ with no setup. The workflow commands need one install step, because Codex
 loads custom prompts from your home directory, not the repo:
 
 ```bash
-cp .codex/prompts/*.md ~/.codex/prompts/
+mkdir -p ~/.codex/prompts && cp .codex/prompts/*.md ~/.codex/prompts/
 ```
 
-Then `/pincer-plan`, `/pincer-narrow`, `/pincer-code`, `/pincer-evaluate`,
-and `/pincer-release` are available in any Codex session. These files are
+(`mkdir -p` matters: Codex does not create `~/.codex/prompts/` on its own, and
+`cp` into a missing directory fails with "Not a directory".) Codex exposes custom
+prompts under a `/prompts:` prefix, so the commands are `/prompts:pincer-plan`,
+`/prompts:pincer-narrow`, `/prompts:pincer-code`, `/prompts:pincer-evaluate`,
+`/prompts:pincer-release` and `/prompts:pincer-status` in any Codex session.
+The playbooks refer to each other by their short names (`/pincer-narrow` etc.);
+read those as `/prompts:pincer-narrow` here.
+
+The copy is not tracked by `pincer update`: after `npx pincer-workflow@latest update`
+(or after editing a playbook and re-running `scripts/sync-prompts.sh`), run the
+`mkdir -p … && cp …` line again so `~/.codex/prompts/` matches the repo. These files are
 generated from `.claude/commands/` by `scripts/sync-prompts.sh` — edit the
 source playbooks, not these copies, and re-copy after a re-sync.
 
@@ -23,6 +32,12 @@ approval_policy = "on-request"     # agent asks before escalating
 sandbox_mode   = "workspace-write" # writes confined to the repo; no network by default
 ```
 
+The ticket scripts are plain bash and work here unchanged:
+`scripts/pincer-ticket.sh start|verify|done T-NN` and `scripts/pincer-status.sh`.
+What Codex lacks is the hook that stops an agent hand-editing ticket state, so the
+rule in `AGENTS.md` carries that weight; `/pincer-status` warns about any ticket
+marked done without a receipt.
+
 Never run with approvals disabled. The destructive-command rule in `AGENTS.md`
 (no force-pushes, absolute-path deletes, or `curl | sh` by an agent) applies as
 a standing instruction here; `/pincer-release` audits the git artifacts

package/template/.codex/prompts/pincer-code.md

@@ -8,40 +8,59 @@ user confirms the starting point, run continuously and report progress between t
 
 **Initial request:** $ARGUMENTS
 
+Ticket state lives in the ticket file's frontmatter and is written **only** by
+`scripts/pincer-ticket.sh` (`start` → `verify` → `done`). `verify` runs the ticket's
+Verification block and stamps a receipt only on a green exit; `done` refuses without a
+receipt that matches the current check, or with unticked acceptance criteria. Never edit
+`status`, `started`, `verified`, or `finished` by hand — on Claude Code a hook blocks it.
+
+## Before the loop
+
+Run `scripts/pincer-status.sh`. It lists every ticket's state, what is blocked, elapsed
+build time from the clock, and the next action. If a ticket is `in_progress`, you are
+resuming: read it, check `git status` / `git diff` for uncommitted work, and continue
+from wherever the receipt says you are. Confirm the starting point with the user, then go.
+
 ## Loop (per ticket, in dependency order)
 
-1. **Read the ticket** and the files it references. Announce: "Starting T-{NN}: {title}."
+1. **Start:** `scripts/pincer-ticket.sh start T-{NN}` — refuses while a `depends_on` ticket
+   isn't done, and stamps the start time. Read the ticket and the files it references.
+   Announce: "Starting T-{NN}: {title}."
 2. **Implement.** Follow the conventions in `CLAUDE.md` and the PRD's architecture and
    visual direction. Installing a dependency not named in the PRD's architecture is a
    stop-and-ask: verify it's the real package on the registry (linked repo, downloads —
-   hallucinated names get typosquatted), say why it earns its place, and wait for a yes. For an S ticket, implement directly. For an M ticket touching
-   isolated files, you may dispatch a subagent with a clean prompt: paste the full ticket
-   body, the relevant conventions, and nothing else.
-3. **Verify.** Run the ticket's verification command(s). If they fail, fix before moving
-   on — never mark a ticket done on a red check. Report actual output, not assumptions.
+   hallucinated names get typosquatted), say why it earns its place, and wait for a yes.
+   For an S ticket, implement directly. For an M ticket touching isolated files, you may
+   dispatch a subagent with a clean prompt: paste the full ticket body, the relevant
+   conventions, and nothing else.
+3. **Verify:** `scripts/pincer-ticket.sh verify T-{NN}` — runs the Verification block and
+   writes the receipt only if it exits 0. Red → fix and re-run; report the actual output,
+   not assumptions. Green output is the definition of done, not your confidence.
 4. **Self-review the diff** before committing: silent failures (empty catches,
    un-awaited promises), leftover debug code, drift from the ticket's acceptance criteria.
    Then a security sweep of the same diff:
    - No secret values: run
-     `git diff --cached | grep -iE '(api[_-]?key|secret|token|password)[[:space:]]*[:=]'`
+     `git diff | grep -iE '(api[_-]?key|secret|token|password)[[:space:]]*[:=]'`
      and treat any hit that isn't a `process.env` reference or a name in
      `.env.example` as a blocker.
    - External input touched by this diff is validated server-side, and untrusted
      content (user input, LLM output) is escaped where rendered — per the
      Security defaults in `CLAUDE.md`.
    - No error path leaks internals (stack traces, key names with values) to the client.
-5. **Commit** with message `T-{NN}: {title}` and mark the ticket done: set
-   `status: done` in its frontmatter and tick every verified acceptance-criteria
-   checkbox (`- [ ]` → `- [x]`) in the same edit. A ticket is never `done` with
-   unticked criteria — if a criterion was cut, that's a scope change to record,
-   not a box to skip.
-6. Give a one-line progress update ("T-02 done, 3 remaining, ~40 min elapsed") and continue.
+   If the review changed code, run `verify` again — the receipt must match the code you commit.
+5. **Close the ticket:** tick every verified acceptance-criteria checkbox (`- [ ]` → `- [x]`;
+   editing the checkboxes is allowed), then `scripts/pincer-ticket.sh done T-{NN}`. A
+   criterion that was cut is a scope change to record in the PRD, not a box to skip.
+   Commit code and ticket file together: `git add -A && git commit -m "T-{NN}: {title}"`.
+6. Give a one-line progress update using the elapsed figure from
+   `scripts/pincer-status.sh` ("T-02 done, 3 remaining, 38m elapsed of 75m") and continue.
 
 ## Timebox rules
 
-- Track elapsed time against the ~75-minute build budget. If you're at risk of running
-  out, stop and propose a scope cut: which remaining tickets to drop or shrink. Cutting
-  scope deliberately beats an unfinished mess — record the cut in the PRD's Out of Scope.
+- The budget is ~75 minutes of build time, measured by `scripts/pincer-status.sh` from
+  the first ticket's start stamp — never estimated. If the remaining tickets won't fit,
+  stop and propose a scope cut: which remaining tickets to drop or shrink. Cutting scope
+  deliberately beats an unfinished mess — record the cut in the PRD's Out of Scope.
 - If a ticket reveals the plan was wrong, stop and say so rather than silently diverging.
   Update the ticket/PRD, then continue.