agent-templates 0.2.1 → 0.3.0

package/CLAUDE.md

@@ -48,12 +48,13 @@ patterns/three-agent-architect-builder-reviewer/
     ├── INSTALL.md                     # how to drop the scaffold into a target repo
     ├── claude-md-snippet.md           # block to append to the target repo's CLAUDE.md
     └── .claude/
-        ├── settings.json              # PreToolUse write guard wiring
+        ├── settings.json              # PreToolUse write guard + deterministic-script allowlist
         ├── hooks/
         │   └── guard-main-session-writes.mjs
         ├── scripts/
         │   ├── publish-tickets.mjs
-        │   └── milestone-dag.mjs
+        │   ├── milestone-dag.mjs
+        │   └── deliver-ticket.mjs
         ├── workflows/
         │   ├── run-milestone.js
         │   ├── start-all.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-templates",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Catalog of multi-agent development architecture patterns - design write-ups plus drop-in scaffolding (agents, slash commands, workflows, templates).",
   "license": "MIT",
   "author": "Horace Hou",

package/patterns/three-agent-architect-builder-reviewer/README.md

@@ -152,6 +152,8 @@ Install steps and usage modes: [scaffold/INSTALL.md](scaffold/INSTALL.md). Front
 | 2026-07-17 | Gate 1 made concrete: `/start-milestone` = the human start signal → tickets auto-published as tracker issues (`publish-tickets.mjs`, adapted from fx-eye-tracking `create-issues.mjs`; `[<id>]` title prefix as dedupe key; smoke-tested dry-run/no-CLI/usage paths) → deterministic milestone runner (`run-milestone.js` Workflow script: stage order, reviewer freshness, bounce cap, merge policy in code). Added `templates/ticket.template.md` (adapted from fx ticket discipline). Recorded the Bash guard boundary as a known pitfall. Clarified `ultracode`: a session setting (`xhigh` + automatic workflow orchestration), not a model effort level — role efforts unchanged. | Maintainer direction (Horace Hou), 2026-07-17. fx-eye-tracking conventions read the same day (read-only). Workflow tool, `.claude/workflows/`, and `ultracode` semantics verified against live docs (workflows, claude-directory, model-config — record in `scaffold/INSTALL.md`). | Horace Hou (direction) / Claude Fable 5 (write-up) |
 | 2026-07-18 | **`/start-all` shipped** (catalog issue #20; maintainer-decided semantics: failed module blocks dependents, independent branches continue in `autonomous`, any non-CLEAR stops everything in `supervised`, no cost cap, resume via closed-issue filtering): deterministic DAG script (`milestone-dag.mjs`, ticket `blocked_by` as ground truth, cycles/dangling refs are hard errors) + `start-all` workflow composing `run-milestone` per module + `/start-all` command. 19 new E2E checks (DAG fixtures incl. cycle; module-policy scenarios via stubbed child workflows). Per-ticket stages unchanged. | Maintainer answers on issue #20, 2026-07-18. | Horace Hou (decisions) / Claude Fable 5 (build) |
 | 2026-07-18 | **First field bug fixed** (catalog issue #21, reported from Ruihang2017/Groundwork through the upstream feedback channel): CRLF-rewritten workflow scripts are rejected by the Workflow tool on Windows. Fix: repo-wide `.gitattributes` (`eol=lf`), working tree renormalized (67 files), `adopt.mjs` installs all text as LF, E2E `\r` guards added. Recorded as the pattern's first true `[internal]` pitfall observation. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
+| 2026-07-19 | **Delivery made deterministic** (catalog issue #26, field report: harness safety classifiers blocked the agent-run deliver stage 3/3 after journaled CLEARs): new `.claude/scripts/deliver-ticket.mjs` — clean-tree guard, `--no-ff` merge (idempotent on re-runs, conflicts abort clean), push, tracker close with post-close verification (`--issue` or `[<id>]` title-prefix lookup), deterministic DoD, `DELIVER-SUMMARY-JSON` contract; run-milestone's deliver agent reduced to executing that one command and relaying its summary; `settings.json` gained explicit allow rules for the three deterministic scripts. E2E: new suite-deliver (12 scenarios on real temp git repos + fake CLIs). The tracker close only happens after merge AND push actually landed — a closed issue is what resume filtering treats as delivered, so closing on a failed delivery would silently drop the ticket. One DoD item relocated: the post-merge test run executes deterministically when `testCmd` is supplied (workflow arg, forwarded as `--test-cmd`; `/start-all` passes it through) and otherwise stays with `/verify-delivery` — builder and reviewer both already ran tests on the branch. Per-ticket stages before deliver, and the model/effort table, unchanged. | Field report (Horace Hou via Groundwork), 2026-07-18; fix direction proposed in the issue itself. | Horace Hou (report) / Claude Fable 5 (fix) |
+| 2026-07-19 | **Field bug #3 fixed** (catalog issue #27, reported from Ruihang2017/Groundwork2): `/start-all` step 3 never stated that `modules[].tickets` elements must be `{id, path, issue}` objects joined from two sources (DAG plan order + per-module `PUBLISH-SUMMARY-JSON`) — the DAG JSON alone emits bare id strings, which run-milestone's validator rejects. Command doc now names the exact shape and the join; `/start-milestone` already documented it. (The issue's other defect — stringified Workflow `args` — was already fixed under #23 / v0.2.1.) | Field report (Horace Hou via Groundwork2), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
 | 2026-07-18 | **Field bug #2 fixed** (catalog issue #23, same reporter channel): (a) #21's install-time LF fix did not survive target-side git checkouts — `adopt.mjs` now installs/appends a target-repo `.gitattributes` pinning `.claude/workflows/*.js` + `.claude/scripts/*.mjs` to `eol=lf` (marker-checked, append-once); (b) Workflow `args` can arrive JSON-stringified — all three workflow scripts gained the `typeof args === 'string' ? JSON.parse(args) : (args \|\| {})` shim. Both recorded as §4 pitfalls; E2E extended (stringified-args runner + start-all scenarios; `.gitattributes` install/append/idempotency). Per-ticket stages and model/effort table unchanged. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
 | 2026-07-17 | **Catalog site**: claymorphic GitHub Pages page generated from pattern data (`scripts/build-site.mjs` — parses pattern README metadata/§1/§3 + package.json; live npm-version fetch with build-time fallback; deployed via `gh-pages` branch). Style spec + generated-not-handwritten rationale in catalog issue #17. | Maintainer direction (Horace Hou) with reference designs, 2026-07-17. | Horace Hou (direction) / Claude Fable 5 (build) |
 | 2026-07-17 | **Released**: catalog published to public npm as `agent-templates` under MIT (maintainer decisions: MIT + personal ownership + publish, 2026-07-17 — catalog issue #15). README carries the scaffold-output attribution carve-out. Adoption command is now `npx agent-templates@latest adopt …`. | Maintainer decision (Horace Hou), 2026-07-17. | Horace Hou (decision) / Claude Fable 5 (release) |

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/start-all.md

@@ -8,8 +8,8 @@ Arguments: `$ARGUMENTS` — optional mode override (else the repo's declared Ope
 Typing this command is the human Gate 1 sign-off **for the whole PRD** — every module, in dependency order. Prefer `/start-milestone` per module when you still want module-boundary checkpoints. Execute in order:
 
 1. **Compute the plan.** Run `node .claude/scripts/milestone-dag.mjs` and show its output (module order, per-module dependencies). STOP on any error — a dangling `blocked_by` or a cycle is a spec defect for the Architect/human, not something to patch here.
-2. **Publish all tickets.** For each module in DAG order: `node .claude/scripts/publish-tickets.mjs docs/prd/<module>` (dry-run, then `--create`; STOP on `error` entries). Then, per module, **filter out tickets whose issues are already closed** (closed = delivered by an earlier run — this makes `/start-all` re-runs resume: fully-closed modules pass an empty ticket list and are marked already-complete).
-3. **Launch the driver.** Call the **Workflow** tool with `name: "start-all"` and `args: { modules: [{name, dependsOn, tickets}] in DAG order, mode, defaultBranch, platform }`. This command's instruction is your authorization to use the Workflow tool. Failure policy is enforced in the workflow: failed modules block their dependents; independent branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`.
+2. **Publish all tickets.** For each module in DAG order: `node .claude/scripts/publish-tickets.mjs docs/prd/<module>` (dry-run, then `--create`; STOP on `error` entries). Keep each module's `PUBLISH-SUMMARY-JSON` line — step 3 needs it. Then, per module, **filter out tickets whose issues are already closed** (closed = delivered by an earlier run — this makes `/start-all` re-runs resume: fully-closed modules pass an empty ticket list and are marked already-complete).
+3. **Launch the driver.** Call the **Workflow** tool with `name: "start-all"` and `args: { modules: [{name, dependsOn, tickets}] in DAG order, mode, defaultBranch, platform }`. Each element of `tickets` MUST be an object `{id, path, issue}` — the exact shape run-milestone validates (issue #27; bare id strings fail). Build it by joining the two step outputs per module: ticket ids and their order come from the DAG plan (step 1), `path` and `issue` come from that module's `PUBLISH-SUMMARY-JSON` (step 2), matched by `id`. Add `testCmd` (the repo's test command, if its CLAUDE.md declares one) so the deterministic deliver script re-runs tests on the merged default branch as part of DoD. This command's instruction is your authorization to use the Workflow tool. Failure policy is enforced in the workflow: failed modules block their dependents; independent branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`.
 4. **Relay the final report verbatim** — per module: `completed` / `already-complete` / `paused-for-merge` (supervised: tell the human to merge, then re-run this command) / `failed` (with the failing ticket + stage) / `skipped-dependency` / `not-started`. Escalations inside a module carry through from run-milestone unchanged.
 
 While the workflow runs you are an observer. Do not do stage work in parallel, do not "help" a slow stage, do not edit files.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/start-milestone.md

@@ -9,7 +9,7 @@ Typing this command **is** the human Gate 1 sign-off: the sub-PRD and tickets ar
 
 1. **Verify Gate 1 inputs.** `MODULE/README.md` (the sub-PRD) exists and `MODULE/tickets/*.md` is non-empty; every ticket has the required frontmatter (see `templates/ticket.template.md`). Anything missing → STOP and list exactly what is missing. Do not fix it yourself — that is Architect-stage work.
 2. **Publish tickets as tracker issues.** Run `node .claude/scripts/publish-tickets.mjs MODULE` (dry-run) and show the mapping. If the summary contains `error` entries → STOP and report them. Otherwise re-run with `--create` (idempotent — the `[<id>]` title prefix dedupes, so re-running is safe), and again STOP on any `error` entries.
-3. **Launch the pipeline.** Parse the final `PUBLISH-SUMMARY-JSON` line into `tickets: [{id, path, issue}]`. **Filter out tickets whose issue is already closed** (check via `gh`/`glab` — closed means delivered by an earlier run; this filter is what makes re-runs after supervised pauses or crashes safe). Determine the Operating mode, then call the **Workflow** tool with `name: "run-milestone"` and `args: { tickets, mode, defaultBranch, platform }`. This command's instruction is your authorization to use the Workflow tool.
+3. **Launch the pipeline.** Parse the final `PUBLISH-SUMMARY-JSON` line into `tickets: [{id, path, issue}]`. **Filter out tickets whose issue is already closed** (check via `gh`/`glab` — closed means delivered by an earlier run; this filter is what makes re-runs after supervised pauses or crashes safe). Determine the Operating mode, then call the **Workflow** tool with `name: "run-milestone"` and `args: { tickets, mode, defaultBranch, platform }` — plus `testCmd` (the repo's test command, if its CLAUDE.md declares one) so the deterministic deliver script re-runs tests on the merged default branch as part of DoD. This command's instruction is your authorization to use the Workflow tool.
 4. **Relay the final report verbatim** — per ticket: `delivered` · `awaiting-human-merge` · `escalated` (stage `review`, `reviewer-failed`, or `bounce-fix-build`) · `failed` · `delivery-incomplete`, plus `notStarted` when the run stopped early. Escalated and failed items go to the human; do not fix them inline (the write guard will hold you to that). In `supervised` mode the run stops after each CLEAR verdict — tell the human to merge, then re-run this command to continue.
 
 While the workflow runs you are an observer. Do not do stage work in parallel, do not "help" a slow stage, do not edit files.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/scripts/deliver-ticket.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// deliver-ticket.mjs — the ONLY sanctioned delivery path for the three-agent
+// pattern (catalog issue #26). Delivery used to be a generic LLM agent prompted
+// to merge + close + verify; harness safety classifiers repeatedly blocked that
+// agent even after a journaled CLEAR (3/3 in one field session), stranding
+// CLEAR-verdict tickets. Like issue creation (publish-tickets.mjs), delivery is
+// now deterministic: the merge policy stays mechanically checkable and the only
+// permission surface is this one command.
+//
+// Usage:
+//   node .claude/scripts/deliver-ticket.mjs --id <ticket-id> --branch <branch>
+//        [--default-branch main] [--issue <n>] [--platform gh|glab]
+//        [--test-cmd "<command>"]
+//
+// Does, in order (every step lands in the summary):
+//   1. refuses to run on a dirty working tree
+//   2. checks out <default-branch>; merges <branch> with --no-ff (an
+//      already-merged branch is recognized and succeeds idempotently);
+//      a conflict aborts the merge and leaves the tree clean
+//   3. pushes <default-branch> to origin (required only when origin exists)
+//   4. closes the tracker issue (--issue <n>, else looked up by the "[<id>]"
+//      title prefix) and VERIFIES it is actually closed afterwards
+//   5. deterministic DoD: plan file exists (docs/plans/<id>.md), merged,
+//      pushed, issue closed, plus --test-cmd green when supplied (post-merge
+//      test runs otherwise stay with /verify-delivery)
+//
+// Last line of stdout is machine-readable for run-milestone:
+//   DELIVER-SUMMARY-JSON: {"id","branch","merged","issueClosed","dodPassed","checks":{...},"notes"}
+// Exit codes: 0 = definitive summary printed (flags may still be false);
+//             1 = bad invocation or unexpected internal error.
+
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const argv = process.argv.slice(2)
+const opt = (name) => {
+  const i = argv.indexOf('--' + name)
+  if (i === -1) return ''
+  const v = argv[i + 1]
+  return v && !v.startsWith('--') ? v : ''
+}
+
+const ID = opt('id')
+const BRANCH = opt('branch')
+const DEFAULT_BRANCH = opt('default-branch') || 'main'
+const ISSUE_ARG = opt('issue')
+const PLATFORM = opt('platform') || 'gh'
+const TEST_CMD = opt('test-cmd')
+
+if (!ID || !BRANCH) {
+  console.error('usage: node deliver-ticket.mjs --id <ticket-id> --branch <branch> [--default-branch main] [--issue <n>] [--platform gh|glab] [--test-cmd "<command>"]')
+  process.exit(1)
+}
+if (!/^[A-Za-z0-9._-]+$/.test(ID)) {
+  console.error(`invalid --id (allowed: letters, digits, . _ -): ${ID}`)
+  process.exit(1)
+}
+if (!/^[A-Za-z0-9/._-]+$/.test(BRANCH) || !/^[A-Za-z0-9/._-]+$/.test(DEFAULT_BRANCH)) {
+  console.error('invalid --branch / --default-branch (allowed: letters, digits, / . _ -)')
+  process.exit(1)
+}
+if (BRANCH === DEFAULT_BRANCH) {
+  console.error(`--branch must differ from --default-branch (got ${BRANCH} for both) — nothing to deliver`)
+  process.exit(1)
+}
+if (PLATFORM !== 'gh' && PLATFORM !== 'glab') {
+  console.error(`unknown platform: ${PLATFORM} (expected gh or glab)`)
+  process.exit(1)
+}
+
+const run = (bin, args, opts = {}) => execFileSync(bin, args, { encoding: 'utf8', ...opts })
+const git = (args, opts = {}) => run('git', args, opts)
+const errText = (e) => String((e && (e.stderr || e.stdout || e.message)) || e).trim()
+const firstLine = (s) => String(s).trim().split('\n')[0]
+const lastLine = (s) => String(s).trim().split('\n').filter(Boolean).pop() || ''
+const tryGit = (args) => {
+  try { return { ok: true, out: git(args, { stdio: ['ignore', 'pipe', 'pipe'] }) } } catch (e) { return { ok: false, out: errText(e) } }
+}
+
+// GH_BIN / GLAB_BIN env overrides (same mechanism as publish-tickets.mjs) for
+// non-PATH binaries and test doubles, e.g. GH_BIN="node tools/fake-gh.mjs".
+const cli = (args, opts = {}) => {
+  const raw = PLATFORM === 'gh' ? process.env.GH_BIN || 'gh' : process.env.GLAB_BIN || 'glab'
+  const parts = raw.split(' ')
+  return run(parts[0], [...parts.slice(1), ...args], opts)
+}
+
+const checks = { planExists: false, alreadyMerged: false, merged: false, pushRequired: false, pushed: false, issueClosed: false, testsPassed: null }
+const notes = []
+const note = (line) => { notes.push(line); console.log('  (note) ' + line) }
+
+const finish = (code) => {
+  const dodPassed =
+    checks.planExists &&
+    checks.merged &&
+    checks.issueClosed &&
+    (!checks.pushRequired || checks.pushed) &&
+    (TEST_CMD ? checks.testsPassed === true : true)
+  const summary = { id: ID, branch: BRANCH, merged: checks.merged, issueClosed: checks.issueClosed, dodPassed, checks, notes: notes.join('; ') }
+  console.log('DELIVER-SUMMARY-JSON: ' + JSON.stringify(summary))
+  process.exit(code)
+}
+
+try {
+  // 0. operate from the repo root regardless of cwd (plan path + command shape)
+  process.chdir(git(['rev-parse', '--show-toplevel']).trim())
+
+  // 1. clean tree — merging over uncommitted work is never sanctioned
+  if (git(['status', '--porcelain']).trim()) {
+    note('working tree not clean — refusing to merge')
+    finish(0)
+  }
+
+  // 2. refs must exist
+  for (const ref of [BRANCH, DEFAULT_BRANCH]) {
+    if (!tryGit(['rev-parse', '--verify', '--quiet', ref]).ok) {
+      note(`ref not found: ${ref}`)
+      finish(0)
+    }
+  }
+
+  // 3. merge --no-ff into the default branch (idempotent on re-runs)
+  git(['checkout', DEFAULT_BRANCH], { stdio: ['ignore', 'pipe', 'pipe'] })
+  if (tryGit(['merge-base', '--is-ancestor', BRANCH, 'HEAD']).ok) {
+    checks.alreadyMerged = true
+    checks.merged = true
+    console.log(`= merged  ${BRANCH} is already contained in ${DEFAULT_BRANCH}`)
+  } else {
+    const m = tryGit(['merge', '--no-ff', '--no-edit', '-m', `merge: [${ID}] ${BRANCH} -> ${DEFAULT_BRANCH} (pipeline CLEAR)`, BRANCH])
+    if (m.ok) {
+      checks.merged = true
+      console.log(`+ merged  ${BRANCH} -> ${DEFAULT_BRANCH} (--no-ff)`)
+    } else {
+      tryGit(['merge', '--abort'])
+      note(`merge failed (aborted, tree left clean): ${firstLine(m.out)}`)
+    }
+  }
+
+  // 4. push (only meaningful when an origin remote exists)
+  checks.pushRequired = tryGit(['remote', 'get-url', 'origin']).ok
+  if (checks.merged && checks.pushRequired) {
+    const p = tryGit(['push', 'origin', DEFAULT_BRANCH])
+    if (p.ok) {
+      checks.pushed = true
+      console.log(`+ pushed  ${DEFAULT_BRANCH} -> origin`)
+    } else {
+      note(`push failed: ${lastLine(p.out)}`)
+    }
+  }
+
+  // 5. close the tracker issue and verify the transition (never assume auto-close).
+  // ONLY after the work actually landed: a closed issue is what resume filtering
+  // treats as "delivered by an earlier run", so closing on a failed merge/push
+  // would silently drop the ticket from every future run.
+  const landed = checks.merged && (!checks.pushRequired || checks.pushed)
+  let issueNum = ISSUE_ARG ? Number(ISSUE_ARG) : null
+  if (issueNum !== null && (!Number.isInteger(issueNum) || issueNum < 1)) {
+    note(`invalid --issue value: ${ISSUE_ARG}`)
+    issueNum = null
+  }
+  if (!landed) {
+    note('skipping tracker close — merge/push did not complete, ticket is NOT delivered')
+  } else {
+    if (!issueNum) {
+      // fall back to the "[<id>]" title-prefix convention (publish-tickets.mjs key)
+      try {
+        if (PLATFORM === 'gh') {
+          const list = JSON.parse(cli(['issue', 'list', '--state', 'all', '--limit', '1000', '--json', 'number,title']))
+          const hit = list.find((i) => String(i.title).startsWith(`[${ID}]`))
+          if (hit) issueNum = hit.number
+        } else {
+          const text = cli(['issue', 'list', '--all'])
+          const line = text.split('\n').find((l) => l.includes(`[${ID}]`))
+          const m = line && line.match(/#(\d+)\b/)
+          if (m) issueNum = Number(m[1])
+        }
+      } catch (e) {
+        note(`issue lookup failed: ${firstLine(errText(e))}`)
+      }
+    }
+    if (!issueNum) {
+      note(`no tracker issue found for [${ID}]`)
+    } else {
+      try {
+        cli(['issue', 'close', String(issueNum), ...(PLATFORM === 'gh' ? ['--comment', `Delivered: ${BRANCH} merged to ${DEFAULT_BRANCH} (run-milestone, CLEAR verdict).`] : [])])
+      } catch (e) {
+        note(`issue close command failed: ${firstLine(errText(e))}`) // verification below still decides
+      }
+      try {
+        if (PLATFORM === 'gh') {
+          const view = JSON.parse(cli(['issue', 'view', String(issueNum), '--json', 'state']))
+          checks.issueClosed = String(view.state).toUpperCase() === 'CLOSED'
+        } else {
+          // text scrape (older glab has no JSON): only trust a "closed" in the header lines
+          checks.issueClosed = cli(['issue', 'view', String(issueNum)]).split('\n').slice(0, 5).some((l) => /\bclosed\b/i.test(l))
+        }
+        console.log((checks.issueClosed ? '+ closed  ' : '  (note) NOT closed: ') + `issue #${issueNum}`)
+        if (!checks.issueClosed) notes.push(`issue #${issueNum} still open after close attempt`)
+      } catch (e) {
+        note(`issue state verification failed: ${firstLine(errText(e))}`)
+      }
+    }
+  }
+
+  // 6. deterministic DoD inputs
+  checks.planExists = existsSync(join('docs', 'plans', `${ID}.md`))
+  if (!checks.planExists) note(`plan file missing: docs/plans/${ID}.md`)
+  if (TEST_CMD) {
+    const t = spawnSync(TEST_CMD, { shell: true, encoding: 'utf8' })
+    checks.testsPassed = t.status === 0
+    if (!checks.testsPassed) note(`--test-cmd failed (exit ${t.status}): ${String(t.stdout || t.stderr || '').trim().split('\n').slice(-3).join(' | ')}`)
+  }
+
+  finish(0)
+} catch (e) {
+  note(`unexpected error: ${firstLine(errText(e))}`)
+  finish(1)
+}

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/settings.json

@@ -1,4 +1,11 @@
 {
+  "permissions": {
+    "allow": [
+      "Bash(node .claude/scripts/milestone-dag.mjs:*)",
+      "Bash(node .claude/scripts/publish-tickets.mjs:*)",
+      "Bash(node .claude/scripts/deliver-ticket.mjs:*)"
+    ]
+  },
   "hooks": {
     "PreToolUse": [
       {

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/run-milestone.js

@@ -13,7 +13,9 @@ export const meta = {
 //   defaultBranch: 'main',        // optional, default 'main'
 //   maxBounces: 2,                // optional, default 2
 //   continueOnFailure: false,     // optional; default fail-fast (tickets may depend on earlier ones)
-//   platform: 'gh' | 'glab'       // tracker CLI for the deliver step, default 'gh'
+//   platform: 'gh' | 'glab',      // tracker CLI for the deliver step, default 'gh'
+//   testCmd: 'npm test'           // optional; forwarded to deliver-ticket.mjs --test-cmd so the
+//                                 // deterministic DoD re-runs tests on the merged default branch
 // }
 //
 // Guarantees encoded below (each one exists because prose alone failed before):
@@ -36,10 +38,17 @@ for (const t of cfg.tickets) {
   if (!t || typeof t.id !== 'string' || !t.id || typeof t.path !== 'string' || !t.path) {
     throw new Error('every ticket needs a non-empty string id and path; got: ' + JSON.stringify(t))
   }
+  // the id is composed into branch names and the deliver command — keep it boring
+  if (!/^[A-Za-z0-9._-]+$/.test(t.id)) {
+    throw new Error('ticket id must match [A-Za-z0-9._-]+; got: ' + t.id)
+  }
 }
 if (cfg.mode !== 'supervised' && cfg.mode !== 'autonomous') {
   throw new Error("args.mode must be 'supervised' or 'autonomous'")
 }
+if (cfg.testCmd !== undefined && (typeof cfg.testCmd !== 'string' || !cfg.testCmd || cfg.testCmd.includes('"'))) {
+  throw new Error('args.testCmd must be a non-empty string without double quotes when provided')
+}
 if (!Number.isInteger(cfg.maxBounces) || cfg.maxBounces < 0) {
   throw new Error('args.maxBounces must be an integer >= 0')
 }
@@ -194,15 +203,21 @@ for (const t of cfg.tickets) {
     continue
   }
 
-  log('[' + t.id + '] deliver: merge + close issue + DoD')
+  log('[' + t.id + '] deliver: merge + close issue + DoD (deterministic script)')
+  // Delivery is a deterministic script, not agent judgment (catalog issue #26):
+  // harness safety classifiers blocked agent-run merges even after a journaled
+  // CLEAR. The agent below only executes the sanctioned command and relays its
+  // machine-readable summary — same discipline as publish-tickets.mjs for issues.
+  const deliverCmd = 'node .claude/scripts/deliver-ticket.mjs --id ' + t.id + ' --branch ' + branch +
+    ' --default-branch ' + cfg.defaultBranch + ' --platform ' + cfg.platform + (t.issue ? ' --issue ' + t.issue : '') +
+    (cfg.testCmd ? ' --test-cmd "' + cfg.testCmd + '"' : '')
   const delivery = await agent(
     'Delivery step (autonomous mode — pre-authorized by the human Gate 1 start signal). ' +
-    'Merge branch ' + branch + ' into ' + cfg.defaultBranch + ' with --no-ff and push. ' +
-    'Close tracker issue ' + (t.issue ? '#' + t.issue : 'for ticket ' + t.id + ' (find it by its "[' + t.id + ']" title prefix)') +
-    ' via ' + cfg.platform + ' and verify it is ACTUALLY closed afterwards. ' +
-    'Then run the Definition-of-Done checks from .claude/commands/verify-delivery.md for ticket ' + t.id +
-    ' (plan exists; tests green on the merged ' + cfg.defaultBranch + ' — run them yourself; CLEAR verdict recorded; merged to ' + cfg.defaultBranch + '; issue closed; writeback done). ' +
-    'Never report an item you did not check. Return merged, issueClosed, dodPassed, notes.',
+    'Delivery is DETERMINISTIC: from the repo root, run EXACTLY this command and let it do all git and tracker work: ' +
+    deliverCmd + ' — the script is the only sanctioned delivery path; do not merge, push, close issues, or retry pieces yourself. ' +
+    'Parse the DELIVER-SUMMARY-JSON line it prints last and return merged, issueClosed, dodPassed EXACTLY as reported there, ' +
+    'with notes = its notes field plus anything unusual you observed. ' +
+    'If the command cannot run or prints no DELIVER-SUMMARY-JSON, return all three as false with the output tail in notes.',
     { label: 'deliver:' + t.id, phase: P, schema: DELIVERY }
   )
   // Delivered requires ALL THREE flags — a hallucinated dodPassed alone must not count.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/start-all.js

@@ -13,7 +13,8 @@ export const meta = {
 //     // so an [] tickets list means "module already complete" (resume semantics)
 //   mode: 'supervised' | 'autonomous',
 //   defaultBranch: 'main',      // optional
-//   platform: 'gh' | 'glab'     // optional, default 'gh'
+//   platform: 'gh' | 'glab',    // optional, default 'gh'
+//   testCmd: 'npm test'         // optional; passed through to run-milestone (deliver DoD test run)
 // }
 //
 // Failure policy (maintainer decisions, catalog issue #20, 2026-07-18):
@@ -38,6 +39,9 @@ if (cfg.mode !== 'supervised' && cfg.mode !== 'autonomous') {
   throw new Error("args.mode must be 'supervised' or 'autonomous'")
 }
 if (cfg.platform !== 'gh' && cfg.platform !== 'glab') throw new Error("args.platform must be 'gh' or 'glab'")
+if (cfg.testCmd !== undefined && (typeof cfg.testCmd !== 'string' || !cfg.testCmd || cfg.testCmd.includes('"'))) {
+  throw new Error('args.testCmd must be a non-empty string without double quotes when provided')
+}
 
 const state = {} // name -> 'completed' | 'failed' | 'skipped' | 'paused'
 const results = []
@@ -75,6 +79,7 @@ for (const m of cfg.modules) {
       mode: cfg.mode,
       defaultBranch: cfg.defaultBranch,
       platform: cfg.platform,
+      ...(cfg.testCmd ? { testCmd: cfg.testCmd } : {}),
     })
   } catch (e) {
     err = e && e.message ? e.message : String(e)

package/patterns/three-agent-architect-builder-reviewer/scaffold/INSTALL.md

@@ -8,10 +8,10 @@ From a checkout of the catalog: `node scripts/adopt.mjs three-agent-architect-bu
 
 ## Steps
 
-1. Copy `.claude/` from this scaffold into the target repo root. If the target already has `.claude/settings.json`, merge the `hooks.PreToolUse` entry instead of overwriting.
+1. Copy `.claude/` from this scaffold into the target repo root. If the target already has `.claude/settings.json`, merge the `hooks.PreToolUse` entry and the `permissions.allow` list instead of overwriting.
 2. Install the catalog's **universal templates** (shared by all patterns — source of truth is the catalog root, not this scaffold): `templates/ticket.template.md` → the target repo's `templates/`; the platform half of `templates/tracker/` → `.github/` (ISSUE_TEMPLATE/ + PULL_REQUEST_TEMPLATE.md) or `.gitlab/` (issue_templates/ + merge_request_templates/). Then fill the PR/MR template's **Constraint check** section with the target repo's CLAUDE.md non-negotiables. Hand-written issues and pipeline PRs now share one format that triage can convert and reviewers can verify.
 3. The write-guard hook needs Node.js ≥ 18 on PATH. It denies main-session Edit/Write with a dispatch instruction; subagent writes pass. Override switch for human-approved out-of-pipeline edits: create `.claude/allow-main-writes`, delete it afterwards — and add that path to `.gitignore`.
-4. The tracker steps (`publish-tickets.mjs`, the deliver stage, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides).
+4. The tracker steps (`publish-tickets.mjs`, `deliver-ticket.mjs`, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides). Delivery (merge `--no-ff` + push + verified issue close + deterministic DoD) is `deliver-ticket.mjs` — never an agent improvising git/tracker writes; `settings.json` carries explicit allow rules for the three deterministic scripts so unattended runs do not stall waiting for interactive approval (catalog issue #26).
 5. Append the content of `claude-md-snippet.md` to the target repo's `CLAUDE.md`, and set the **Operating mode** line (`supervised` for a fresh adoption; `autonomous` is the target).
 6. Ensure the docs layout the pipeline assumes exists: `docs/PRD.md`, `docs/prd/<module>/README.md` (the sub-PRD — `/start-milestone` hard-requires it), `docs/prd/<module>/tickets/` (author tickets from `templates/ticket.template.md`), `docs/adr/`, and an empty `docs/plans/`.
 7. Check the pattern entry's expiry (README metadata table). If expired, re-verify the model/effort table against current official docs before adopting — do not copy an expired recommendation into a new project.