agent-templates 0.1.0

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/build-ticket.md

@@ -0,0 +1,12 @@
+---
+description: Run the Builder stage on a planned ticket (three-agent pattern)
+argument-hint: <ticket-id>
+---
+
+Launch the **builder** subagent for ticket $ARGUMENTS, pointing it at the ticket file and its plan at `docs/plans/$ARGUMENTS.md` (adjust the path if the plan lives elsewhere).
+
+Refuse to start if the plan file does not exist — `/plan-ticket` runs first.
+
+When the builder returns, show its diff summary, actual test output, and Deviations note, then STOP. Do not merge; clearance requires `/review-ticket` in a fresh context.
+
+Hard rule: this stage runs in the **builder** subagent, never inline in this session — no matter how small the change looks. If the subagent cannot be launched or fails, report that and stop — do not absorb its role.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/nightly-issues.md

@@ -0,0 +1,14 @@
+---
+description: Nightly issue sweep — triage open issues, auto-fix the fixable ones through the three-agent pipeline, post the morning report (designed for headless `claude -p "/nightly-issues"`)
+argument-hint: [max-issues]
+---
+
+Arguments: `$ARGUMENTS` — optional first argument caps how many issues to process tonight (default 5).
+
+Execute in order:
+
+1. **Collect.** List open issues with the platform CLI (`gh issue list --state open --json number,title,body,labels,createdAt,url` / glab equivalent). Exclude issues labeled `nightly:escalated`, `triage:invalid`, or `needs-human`, and any issue titled `Nightly report ...`. For each remaining issue set `isNew` = created within the last 24 hours. Compute `reportDate` = today's local date (YYYY-MM-DD).
+2. **Launch the sweep.** Call the **Workflow** tool with `name: "nightly-issues"` and `args: { issues, maxIssues, defaultBranch, platform, reportDate }`. This command's instruction is your authorization to use the Workflow tool. The workflow triages (read-only), runs fixable issues through the run-milestone pipeline autonomously, and posts all tracker writes in one report step.
+3. **Final output** (this is the headless run's stdout): the report issue URL, then one line per processed issue — `#N · <classification or pipeline status> · <one-line reason>` — plus how many eligible issues were left for the next night.
+
+Operator notes: scheduling, permissions, and the morning-email mechanics are documented in the scaffold's INSTALL.md § Nightly sweep. You are an observer while the workflow runs — no stage work, no file edits, no tracker writes outside the workflow.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/plan-ticket.md

@@ -0,0 +1,10 @@
+---
+description: Run the Architect stage on a ticket (three-agent pattern)
+argument-hint: <ticket-id or path to ticket file>
+---
+
+Launch the **architect** subagent on ticket: $ARGUMENTS
+
+Pass it only the ticket reference — no prior conversation content. When it returns, show the plan path and its summary, then STOP. Implementation is the Builder's stage (`/build-ticket`), not this session's next step.
+
+Hard rule: this stage runs in the **architect** subagent, never inline in this session. If the subagent cannot be launched or fails, report that and stop — do not absorb its role.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/review-ticket.md

@@ -0,0 +1,14 @@
+---
+description: Run the Reviewer stage on a built ticket (three-agent pattern) — requires a fresh context
+argument-hint: <ticket-id> [branch-or-PR-ref]
+---
+
+Arguments: `$ARGUMENTS` — the first is the ticket id (TICKET below); the optional second is the diff reference (branch or PR; default: the ticket's `ticket/<id>` branch).
+
+Contamination check first: if this session contains the Builder's implementation conversation for TICKET, STOP and tell the user to run `/review-ticket` from a fresh session. (A reviewer subagent launched from a session that only orchestrated — passing artifacts, never transcripts — is acceptable: Mode A in the scaffold's INSTALL.md.)
+
+Launch the **reviewer** subagent for TICKET. Give it ONLY: the ticket path, the plan path (`docs/plans/<ticket-id>.md`), and the diff reference. Never include the Builder's transcript or self-assessment.
+
+Relay the verdict verbatim — CLEAR, or BOUNCE with its numbered findings. On BOUNCE, findings go back to the Builder; after 2 bounce cycles, escalate to a human instead of looping.
+
+Hard rule: this stage runs in the **reviewer** subagent, never inline in this session. If the subagent cannot be launched or fails, report that and stop — do not absorb its role. After a merge, `/verify-delivery` still runs — a CLEAR verdict does not close the ticket by itself.

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

@@ -0,0 +1,15 @@
+---
+description: Gate 1 start signal — publish the module's tickets as tracker issues, then run the milestone pipeline (three-agent pattern)
+argument-hint: <module dir, e.g. docs/prd/01-foo> [supervised|autonomous]
+---
+
+Arguments: `$ARGUMENTS` — the first is the module directory (MODULE below); the optional second overrides the repo's declared Operating mode (CLAUDE.md).
+
+Typing this command **is** the human Gate 1 sign-off: the sub-PRD and tickets are final, and tracker issue **creation** is authorized by this sign-off. Execute in order:
+
+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.
+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/commands/verify-delivery.md

@@ -0,0 +1,20 @@
+---
+description: Post-merge Definition-of-Done check for a ticket (three-agent pattern) — verifies delivery instead of assuming it
+argument-hint: <ticket-id>
+---
+
+Verify — do not assume — that ticket $ARGUMENTS is actually delivered. Check every item yourself this session and print a pass/fail table:
+
+1. **Plan** exists at `docs/plans/$ARGUMENTS.md`.
+2. **Reviewer verdict** is CLEAR, attached to the MR/PR.
+3. **Tests green on the merged default branch** — run the suite yourself this session; never accept reported results.
+4. **MR/PR merged** into the **default branch** (not a side branch).
+5. **Tracker issue closed** — check via `glab issue view` / `gh issue view`. Auto-close via `Closes #N` fires only under specific conditions (GitLab: default-branch merge with the closing pattern in the MR description) — never trust it blindly; this exact gap has shipped before (MRs merged, issues left open).
+6. **Writeback** — any Deviations noted by the Builder are reflected back into the ticket/sub-PRD.
+
+Report every failed item plainly. If the MR is merged but the issue is still open, the repair is the exact close command (`glab issue close <N>` / `gh issue close <N>`) — behavior depends on the repo's declared operating mode (CLAUDE.md, "Operating mode"):
+
+- `supervised`: show the command and run it only after explicit human OK.
+- `autonomous`: run the repair, report what was repaired, and escalate to a human only if the repair fails or the gap is not mechanically repairable.
+
+Never mark an item passed that you did not check this session.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/hooks/guard-main-session-writes.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Three-agent pattern guard: the ORCHESTRATOR (main session) never writes.
+//
+// PreToolUse hook on Edit|Write|MultiEdit|NotebookEdit (wired in .claude/settings.json).
+// Per https://code.claude.com/docs/en/hooks.md (verified 2026-07-17): hooks fire for
+// subagent tool calls too, and the input carries `agent_id`/`agent_type` ONLY when the
+// call comes from a subagent — their absence identifies the main session.
+//
+// Behavior:
+//   - subagent call (architect writes the plan, builder writes code) -> no objection
+//   - main-session call -> deny, with the dispatch instruction fed back to the model
+//   - override switch for a human-approved out-of-pipeline edit: create the file
+//     .claude/allow-main-writes (and delete it afterwards to re-arm the guard)
+//
+// Only the main session is constrained here; each subagent is governed by its own
+// tools/disallowedTools frontmatter (e.g. the reviewer has no Write/Edit at all).
+
+import { existsSync } from "node:fs";
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+
+let input = {};
+try {
+  input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+} catch {
+  process.exit(0); // unparsable input: stay out of the way rather than block blindly
+}
+
+const isSubagent = typeof input.agent_id === "string" && input.agent_id.length > 0;
+const overrideSwitch = new URL("../allow-main-writes", import.meta.url);
+
+if (isSubagent || existsSync(overrideSwitch)) {
+  process.exit(0); // no objection; normal permission flow applies
+}
+
+const target =
+  input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? "(unknown target)";
+
+console.log(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason:
+        `Three-agent pattern: the main session orchestrates only and never writes ` +
+        `(blocked ${input.tool_name} on ${target}). Dispatch the work to its stage instead: ` +
+        `/plan-ticket (architect) or /build-ticket (builder). For a human-approved ` +
+        `out-of-pipeline edit, create .claude/allow-main-writes and retry — then delete it.`,
+    },
+  })
+);
+process.exit(0);

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/scripts/publish-tickets.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// publish-tickets.mjs — the ONLY sanctioned issue-creation path for the three-agent
+// pattern. Agents never hand-create issues (fabrication risk); this script is
+// deterministic and idempotent. Adapted from fx-eye-tracking scripts/create-issues.mjs
+// (read 2026-07-17), extended with gh support and a machine-readable summary.
+//
+// Usage:
+//   node .claude/scripts/publish-tickets.mjs <module-dir> [--create] [--platform gh|glab]
+//
+//   <module-dir>   e.g. docs/prd/01-foo — scans <module-dir>/tickets/*.md
+//   --create       actually create issues (default: dry-run preview)
+//   --platform     tracker CLI; default: autodetect from the origin remote host
+//
+// Mapping (one issue per ticket file):
+//   title  = "[<id>] <title>"            <- the [<id>] prefix is the idempotency key
+//   body   = file content minus frontmatter (the ticket FILE stays the content source of truth)
+//   labels = module:<module>, size:<size>, agent:<agent> (each only if present)
+//
+// Idempotency: the existing-issue list is fetched ONCE per run (list endpoints are
+// strongly consistent, unlike per-ticket search) and matched client-side by the
+// "[<id>]" title prefix. In --create mode a failed fetch aborts BEFORE creating
+// anything. Note: the gh path lists up to 1000 issues; beyond that, split modules.
+//
+// Last line of stdout is machine-readable for /start-milestone:
+//   PUBLISH-SUMMARY-JSON: [{"id","path","title","issue","error"?}]
+// Exit codes: 0 = ok (invalid tickets are reported in the summary, not fatal);
+//             1 = bad invocation, missing CLI in --create mode, fetch failure in
+//                 --create mode, or any create failure (summary still printed).
+
+import { execFileSync } from 'node:child_process'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const argv = process.argv.slice(2)
+const CREATE = argv.includes('--create')
+
+const platformIx = argv.indexOf('--platform')
+let PLATFORM = ''
+if (platformIx !== -1) {
+  PLATFORM = argv[platformIx + 1] || ''
+  if (!PLATFORM || PLATFORM.startsWith('--')) {
+    console.error('missing or invalid --platform value (expected gh or glab)')
+    process.exit(1)
+  }
+}
+const moduleDir = argv.find((a, i) => !a.startsWith('--') && (platformIx === -1 || i !== platformIx + 1))
+
+if (!moduleDir) {
+  console.error('usage: node publish-tickets.mjs <module-dir> [--create] [--platform gh|glab]')
+  process.exit(1)
+}
+const ticketsDir = join(moduleDir, 'tickets')
+let ticketsDirOk = false
+try { ticketsDirOk = statSync(ticketsDir).isDirectory() } catch {}
+if (!ticketsDirOk) {
+  console.error(`no tickets directory: ${ticketsDir}`)
+  process.exit(1)
+}
+
+const run = (bin, args, opts = {}) => execFileSync(bin, args, { encoding: 'utf8', ...opts })
+
+// GH_BIN / GLAB_BIN env overrides (precedent: fx-eye-tracking's GLAB_BIN) for
+// non-PATH binaries and test doubles. The value may include leading args, e.g.
+// GH_BIN="node tools/fake-gh.mjs" (no spaces in the path itself).
+const cli = (platform, 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)
+}
+
+let detectedFrom = ''
+if (!PLATFORM) {
+  try {
+    const origin = run('git', ['remote', 'get-url', 'origin'], { stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    const host = (origin.match(/(?:@|:\/\/)([^/:]+)[/:]/) || [])[1] || ''
+    PLATFORM = /(^|\.)gitlab\./.test(host) || host.includes('gitlab') ? 'glab' : 'gh'
+    detectedFrom = host || origin
+  } catch {
+    PLATFORM = 'gh'
+    detectedFrom = 'no origin remote'
+  }
+}
+if (PLATFORM !== 'gh' && PLATFORM !== 'glab') {
+  console.error(`unknown platform: ${PLATFORM} (expected gh or glab)`)
+  process.exit(1)
+}
+console.log(`platform: ${PLATFORM}${detectedFrom ? ` (autodetected from ${detectedFrom}; override with --platform)` : ''}`)
+
+let cliOk = false
+try {
+  cli(PLATFORM, ['auth', 'status'], { stdio: ['ignore', 'ignore', 'ignore'] })
+  cliOk = true
+} catch {}
+if (CREATE && !cliOk) {
+  console.error(`x ${PLATFORM} not found or not authenticated — install it and run \`${PLATFORM} auth login\`.`)
+  process.exit(1)
+}
+if (!cliOk) {
+  console.log(`(note) ${PLATFORM} unavailable — dry-run previews without checking which issues already exist.`)
+}
+
+// Fetch the existing-issue list ONCE; match "[<id>]" prefixes client-side.
+// Returns [{number, title}] or null when unavailable.
+const fetchExistingIssues = () => {
+  if (!cliOk) return null
+  try {
+    if (PLATFORM === 'gh') {
+      const out = cli('gh', ['issue', 'list', '--state', 'all', '--limit', '1000', '--json', 'number,title'])
+      return JSON.parse(out).map((i) => ({ number: i.number, title: i.title }))
+    }
+    try {
+      const out = cli('glab', ['issue', 'list', '--all', '--output', 'json'])
+      return JSON.parse(out).map((i) => ({ number: i.iid ?? i.id, title: i.title }))
+    } catch {
+      // older glab without --output json: parse per LINE so the number always
+      // belongs to the line whose title matches (never "first #N in the blob")
+      const out = cli('glab', ['issue', 'list', '--all'])
+      return out
+        .split('\n')
+        .map((l) => l.match(/^#(\d+)\s+(.*)$/))
+        .filter(Boolean)
+        .map((m) => ({ number: Number(m[1]), title: m[2] }))
+    }
+  } catch {
+    return null
+  }
+}
+
+const existingIssues = fetchExistingIssues()
+if (CREATE && existingIssues === null) {
+  console.error('x could not fetch the existing-issue list — refusing to create without a reliable existence check.')
+  process.exit(1)
+}
+// Returns an issue number, null (not found), or 'ambiguous' (mentions of "[<id>]"
+// exist but none is a clean title prefix — creating would risk a duplicate, guessing
+// would risk closing the wrong issue later, so the ticket is skipped with an error).
+const findExisting = (id) => {
+  if (!existingIssues) return null
+  const marker = `[${id}]`
+  const hits = existingIssues.filter((i) => String(i.title).includes(marker))
+  const exact = hits.find((i) => String(i.title).trim().startsWith(marker))
+  if (exact) return exact.number
+  if (hits.length > 0) return 'ambiguous'
+  return null
+}
+
+const field = (fm, name) => {
+  const m = fm.match(new RegExp(`^${name}\\s*:\\s*(.+)$`, 'm'))
+  if (!m) return ''
+  // strip one pair of surrounding YAML quotes (and unescape \" inside them) so
+  // quoted titles don't leak quote characters into issue titles
+  const v = m[1].trim()
+  const stripped = v.replace(/^(['"])(.*)\1$/s, '$2')
+  return stripped === v ? v : stripped.replace(/\\"/g, '"')
+}
+
+const createIssue = (issueTitle, body, labels) => {
+  const attempt = (withLabels) => {
+    if (PLATFORM === 'gh') {
+      const args = ['issue', 'create', '--title', issueTitle, '--body-file', '-']
+      if (withLabels) for (const l of labels) args.push('--label', l)
+      return cli('gh', args, { input: body }).trim()
+    }
+    const args = ['issue', 'create', '--title', issueTitle, '--description', body]
+    if (withLabels && labels.length) args.push('--label', labels.join(','))
+    return cli('glab', args).trim()
+  }
+  try {
+    return attempt(true)
+  } catch (e) {
+    if (!labels.length) throw e
+    console.error(`  (warn) create with labels failed — retrying without labels (create them in the tracker to keep labeling)`)
+    return attempt(false)
+  }
+}
+
+const summary = []
+const seenIds = new Set()
+let created = 0
+let skipped = 0
+let planned = 0
+let invalid = 0
+let createFailed = 0
+
+for (const f of readdirSync(ticketsDir).filter((n) => n.endsWith('.md')).sort()) {
+  const path = join(ticketsDir, f).replaceAll('\\', '/')
+  const text = readFileSync(path, 'utf8').replace(/^/, '') // strip BOM (PowerShell 5.1 utf8 writes one)
+  const fmMatch = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
+  if (!fmMatch) {
+    console.log(`  skip (no frontmatter): ${path}`)
+    summary.push({ id: null, path, title: null, issue: null, error: 'no-frontmatter' })
+    invalid++
+    continue
+  }
+  const fm = fmMatch[1]
+  const id = field(fm, 'id')
+  const title = field(fm, 'title')
+  if (!id || !title) {
+    console.log(`  skip (missing id/title): ${path}`)
+    summary.push({ id: id || null, path, title: null, issue: null, error: 'missing-id-title' })
+    invalid++
+    continue
+  }
+  if (seenIds.has(id)) {
+    console.log(`  skip (duplicate id ${id}): ${path}`)
+    summary.push({ id, path, title: null, issue: null, error: 'duplicate-id' })
+    invalid++
+    continue
+  }
+  seenIds.add(id)
+
+  const issueTitle = `[${id}] ${title}`
+  const body = text.slice(fmMatch[0].length).trimStart()
+  const labels = [
+    field(fm, 'module') && `module:${field(fm, 'module')}`,
+    field(fm, 'size') && `size:${field(fm, 'size')}`,
+    field(fm, 'agent') && `agent:${field(fm, 'agent')}`,
+  ].filter(Boolean)
+
+  const existing = findExisting(id)
+  if (existing === 'ambiguous') {
+    console.error(`x skip ${id}: issues mention "[${id}]" but none has it as a clean title prefix — resolve by hand`)
+    summary.push({ id, path, title: issueTitle, issue: null, error: 'ambiguous-existing' })
+    invalid++
+    continue
+  }
+  if (existing) {
+    console.log(`= skip ${id}: issue #${existing} already exists`)
+    summary.push({ id, path, title: issueTitle, issue: existing })
+    skipped++
+    continue
+  }
+
+  if (!CREATE) {
+    console.log(`+ would create ${id}: "${issueTitle}"  labels=[${labels.join(',')}]`)
+    summary.push({ id, path, title: issueTitle, issue: null })
+    planned++
+    continue
+  }
+
+  try {
+    const out = createIssue(issueTitle, body, labels)
+    const lastLine = out.split('\n').filter(Boolean).pop() || ''
+    const num = (lastLine.match(/\/issues\/(\d+)\s*$/) || out.match(/#(\d+)/) || [])[1]
+    console.log(`+ created ${id}: ${lastLine}`)
+    summary.push({ id, path, title: issueTitle, issue: num ? Number(num) : null })
+    created++
+  } catch (e) {
+    const msg = String(e && e.message ? e.message : e).split('\n')[0]
+    console.error(`x create failed for ${id}: ${msg}`)
+    summary.push({ id, path, title: issueTitle, issue: null, error: `create-failed: ${msg}` })
+    createFailed++
+  }
+}
+
+const invalidNote = invalid ? `, invalid: ${invalid}` : ''
+console.log(
+  CREATE
+    ? `CREATED: ${created}, already existed: ${skipped}, failed: ${createFailed}${invalidNote}.`
+    : `DRY-RUN: ${planned} would be created, ${skipped} already exist${invalidNote}. Re-run with --create after Gate 1 sign-off.`
+)
+console.log('PUBLISH-SUMMARY-JSON: ' + JSON.stringify(summary))
+process.exit(createFailed ? 1 : 0)

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

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/guard-main-session-writes.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/nightly-issues.js

@@ -0,0 +1,139 @@
+export const meta = {
+  name: 'nightly-issues',
+  description: 'Nightly sweep: triage open issues, run fixable ones through the three-agent pipeline, post the morning report',
+  phases: [{ title: 'Triage' }, { title: 'Fix' }, { title: 'Report' }],
+}
+
+// Deterministic nightly orchestrator. The command (/nightly-issues) collects the
+// issue list and date (Date is unavailable in workflow scripts) and passes:
+//
+// args:
+// {
+//   issues: [{ number, title, body, labels: [..], isNew: bool, url }],
+//   maxIssues: 5,                 // optional cost cap per night
+//   defaultBranch: 'main',        // optional
+//   platform: 'gh' | 'glab',      // default 'gh'
+//   reportDate: 'YYYY-MM-DD',     // required — stamped by the caller
+// }
+//
+// Design: triage never touches the tracker; the pipeline (child run-milestone
+// workflow) does the fixing with continueOnFailure=true (issues are independent,
+// unlike milestone tickets); a single report step does ALL tracker writes at the
+// end — comments, labels, and the "Nightly report <date>" issue the human reads
+// over morning email (tracker notifications).
+
+const cfg = Object.assign({ maxIssues: 5, defaultBranch: 'main', platform: 'gh' }, args)
+if (!Array.isArray(cfg.issues)) throw new Error('args.issues must be an array (may be empty)')
+if (typeof cfg.reportDate !== 'string' || !cfg.reportDate) throw new Error('args.reportDate is required (the caller stamps the date)')
+if (!Number.isInteger(cfg.maxIssues) || cfg.maxIssues < 1) throw new Error('args.maxIssues must be an integer >= 1')
+if (cfg.platform !== 'gh' && cfg.platform !== 'glab') throw new Error("args.platform must be 'gh' or 'glab'")
+
+const SKIP_LABELS = ['nightly:escalated', 'triage:invalid', 'needs-human']
+const eligible = cfg.issues.filter(function (i) {
+  return i && Number.isInteger(i.number) && !(i.labels || []).some(function (l) { return SKIP_LABELS.includes(l) })
+})
+const candidates = eligible.slice(0, cfg.maxIssues)
+if (eligible.length > candidates.length) {
+  log('cap: processing ' + candidates.length + '/' + eligible.length + ' eligible issues (maxIssues=' + cfg.maxIssues + '); the rest wait for the next night')
+}
+
+const TRIAGE = {
+  type: 'object',
+  properties: {
+    classification: { enum: ['fixable', 'invalid', 'needs-human'] },
+    reason: { type: 'string' },
+    ticketPath: { type: 'string' },
+  },
+  required: ['classification', 'reason'],
+}
+const REPORT = {
+  type: 'object',
+  properties: { reportUrl: { type: 'string' }, notes: { type: 'string' } },
+  required: ['reportUrl'],
+}
+
+// ---- Phase 1: triage (parallel, read-only + ticket synthesis) ----
+const triaged = await parallel(candidates.map(function (issue) {
+  return function () {
+    return agent(
+      'Triage this tracker issue per your role definition.\n' +
+      'Issue #' + issue.number + ': ' + issue.title + '\n' +
+      'Labels: ' + JSON.stringify(issue.labels || []) + '\n' +
+      'Body:\n' + (issue.body || '(empty)') + '\n\n' +
+      'If fixable, the ticket file MUST be docs/prd/99-nightly/tickets/ISS-' + issue.number + '-<slug>.md with id ISS-' + issue.number + '.',
+      { agentType: 'triage', label: 'triage:#' + issue.number, phase: 'Triage', schema: TRIAGE }
+    ).then(function (t) {
+      return { issue: issue, triage: t || { classification: 'needs-human', reason: 'triage agent returned nothing' } }
+    })
+  }
+}))
+const outcomes = triaged.filter(Boolean)
+
+const fixable = outcomes.filter(function (o) { return o.triage.classification === 'fixable' && o.triage.ticketPath })
+for (const o of outcomes) {
+  if (o.triage.classification === 'fixable' && !o.triage.ticketPath) {
+    o.triage.classification = 'needs-human'
+    o.triage.reason = 'classified fixable but returned no ticket path — ' + o.triage.reason
+  }
+}
+log('triage: ' + fixable.length + ' fixable, ' +
+  outcomes.filter(function (o) { return o.triage.classification === 'invalid' }).length + ' invalid, ' +
+  outcomes.filter(function (o) { return o.triage.classification === 'needs-human' }).length + ' needs-human')
+
+// ---- Phase 2: fix via the milestone runner (child workflow, one nesting level) ----
+let pipeline_results = []
+if (fixable.length > 0) {
+  const tickets = fixable.map(function (o) {
+    return { id: 'ISS-' + o.issue.number, path: o.triage.ticketPath, issue: o.issue.number }
+  })
+  try {
+    const child = await workflow('run-milestone', {
+      tickets: tickets,
+      mode: 'autonomous',
+      defaultBranch: cfg.defaultBranch,
+      platform: cfg.platform,
+      continueOnFailure: true, // nightly issues are independent; one failure must not strand the rest
+    })
+    pipeline_results = (child && child.results) || []
+  } catch (e) {
+    log('pipeline failed to run: ' + (e && e.message ? e.message : String(e)))
+    pipeline_results = tickets.map(function (t) { return { id: t.id, status: 'failed', stage: 'pipeline', detail: 'milestone runner did not run' } })
+  }
+}
+const resultFor = function (issueNumber) {
+  return pipeline_results.find(function (r) { return r.id === 'ISS-' + issueNumber }) || null
+}
+
+// ---- Phase 3: report (the ONLY tracker-writing step) ----
+const digest = outcomes.map(function (o) {
+  const r = resultFor(o.issue.number)
+  return {
+    number: o.issue.number,
+    title: o.issue.title,
+    isNew: Boolean(o.issue.isNew),
+    classification: o.triage.classification,
+    reason: o.triage.reason,
+    pipeline: r ? { status: r.status, stage: r.stage || null, bounces: r.bounces || 0, detail: r.detail || null } : null,
+  }
+})
+
+const report = await agent(
+  'You are the nightly report step — the only step allowed to write to the tracker (' + cfg.platform + ' CLI via Bash). ' +
+  'Process this digest of tonight\'s sweep (JSON): ' + JSON.stringify({ date: cfg.reportDate, digest: digest, notProcessed: eligible.length - candidates.length }) + '\n' +
+  'Do, in order:\n' +
+  '1. Per issue: post ONE comment stating the outcome — fixed (link the merge) / attempted-but-not-solved (why, findings) / needs-human (why) / invalid (why). Base every statement on the digest; fabricate nothing.\n' +
+  '2. Labels: add `triage:invalid` to invalid issues (do NOT close them — the human decides in the morning); add `nightly:escalated` to attempted-but-not-solved and pipeline-failed issues; add `needs-human` to needs-human issues.\n' +
+  '3. For issues whose pipeline status is `delivered`: verify the issue is actually closed; close it if the deliver step missed it.\n' +
+  '4. Create a tracker issue titled exactly "Nightly report ' + cfg.reportDate + '" (search first; if it already exists, comment on it instead of duplicating) with sections: New overnight · Fixed & closed · Attempted, not solved · Needs human · Invalid (ignore) · Not processed (cap). Use issue references (#N) so the tracker links them.\n' +
+  'Return reportUrl and notes (anything that went wrong).',
+  { label: 'report:' + cfg.reportDate, phase: 'Report', schema: REPORT }
+)
+
+return {
+  date: cfg.reportDate,
+  processed: digest,
+  notProcessed: eligible.length - candidates.length,
+  fixed: digest.filter(function (d) { return d.pipeline && d.pipeline.status === 'delivered' }).length,
+  reportUrl: report ? report.reportUrl : null,
+  reportNotes: report ? report.notes : 'report step returned nothing',
+}