frizz 0.0.1 → 0.2.0

package/runtime/cc-worker/skills/gh/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: gh
+description: The gh-CLI playbook for a frizz worker signed into GitHub (invoke as frizz:gh). Load this whenever your effort touches GitHub — reading or triaging an issue or PR, reviewing a diff, checking CI/release status, or searching issues/PRs — to use `gh` eagerly and correctly: the read-vs-write boundary (never comment/label/close/merge unless the human asks), optional toon use for large JSON, concrete read recipes, and active Monitor/background-Bash CI/PR watches. Only meaningful when you are signed in (`gh auth status --active` exit 0); the session-seed hook injects a pointer here when you are.
+version: 0.1.1
+metadata:
+  internal: true
+---
+
+# frizz:gh — the gh-CLI playbook
+
+You are a **frizz worker** and you are **signed into the `gh` CLI in a GitHub repo** (the session-seed hook confirmed `gh auth status --active` before pointing you here). `gh` is the fastest path to issue / PR / CI / release context — reach for it before guessing, and prefer it over scraping the web UI or reasoning from memory.
+
+This skill is the full playbook the injected `⟦gh available⟧` block summarizes: the **read-vs-write boundary**, optional **toon** use for large JSON, concrete **read recipes**, and how to keep a **CI/PR watch** active until the next actionable event.
+
+## The one hard rule — READ freely, WRITE only when asked
+
+`gh` can mutate the repo, and your token has the scopes to do it. **Do not.** Unless the human **explicitly asks in this session**, you are strictly read-only:
+
+- **NEVER** comment, review, approve, request-changes, label, assign, milestone, edit, close, reopen, merge, or push — no state change of any kind on GitHub.
+- Your deliverable is your **final message** (a findings write-up, a review, a recommendation) — NOT a GitHub post. Producing the review in-session is the job; posting it is a separate action the human authorizes.
+- If posting would genuinely help, don't just do it — **ask** with a two-option ` ```question ` block ("A. Post this review to the PR / B. Keep it in-session only", Recommendation), then rest. When the destructive edge is real (a force-merge, a close), that's a ` ```question danger ` gate.
+- When the human HAS asked you to write, do exactly the scoped thing and report the resulting URL — nothing extra.
+
+There is no server-side enforcement of this; the boundary is yours to hold.
+
+## toon — pipe LARGE, FLAT gh JSON through the shim
+
+`toon` (Token-Oriented Object Notation) losslessly re-encodes JSON ~30–40% smaller for LLM context. Use it only when a `gh … --json` result you're reading into YOUR context is **large and flat** (a list page: `gh issue list`, `gh pr list`, `gh search`, `gh api` list endpoints) and `command -v toon` succeeds. It is optional: do not install it or assume a home-directory-specific location.
+
+```bash
+if command -v toon >/dev/null 2>&1; then
+  gh issue list -R OWNER/REPO --json number,title,url,updatedAt --limit 50 | toon
+else
+  gh issue list -R OWNER/REPO --json number,title,url,updatedAt --limit 50
+fi
+```
+
+**Skip toon** for tiny payloads (a handful of fields, one item) and for **deeply-nested** JSON (`reactionGroups`, review threads, nested files) — nesting defeats tabularization, so the savings collapse to noise and you add a parse tax for yourself. A single `gh pr view N --json …` is small — read it raw.
+
+## Read recipes
+
+Always scope with `-R OWNER/REPO` so a command is dir-independent, and prefer `--json <fields>` (+ `-q <jq>`) so you pull exactly what you need.
+
+**Issues**
+```bash
+gh issue view N -R OWNER/REPO --comments                          # full thread, human-readable
+gh issue view N -R OWNER/REPO --json title,body,labels,state,url  # structured
+gh issue list -R OWNER/REPO --search "sort:updated-desc" --json number,title,url,updatedAt --limit 30
+gh issue list -R OWNER/REPO --search "sort:reactions-desc is:open" --json number,title,url --limit 30
+```
+
+**PRs + diffs**
+```bash
+gh pr view N -R OWNER/REPO --json title,body,state,labels,files,additions,deletions,url
+gh pr diff N -R OWNER/REPO                # the unified diff — pipe through toon only if HUGE and you just need shape
+gh pr checks N -R OWNER/REPO              # CI check rollup for the PR
+gh pr view N -R OWNER/REPO --comments     # review threads + conversation
+```
+Read the changed files **in context**, not just the hunks — `gh pr diff` shows what changed, but correctness lives in the surrounding code.
+
+**Reading ONE review (what a `pr-watch` wake hands you)**
+
+A wake permalink ending `#pullrequestreview-<id>` is a **review**, and a review's `body` is routinely
+**empty** — review apps (pullfrog, coderabbit) and humans doing an inline pass put every word in the
+review's *inline comments*. Reading the body and concluding the review is empty is the wrong turn here.
+One endpoint answers it in one call:
+
+```bash
+gh api --paginate repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID/comments \
+  --jq '.[] | "\(.path):\(.line // .original_line // "file")\n\(.body)\n"'
+```
+
+Do **not** sweep `…/pulls/N/comments` and filter by `pull_request_review_id` — it pulls the whole PR's
+history to find a handful of lines. Add the review's own body only if you need it
+(`gh api repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID --jq .body`). A `#issuecomment-<id>` permalink is
+the other shape and *does* carry its substance in its body:
+`gh api repos/OWNER/REPO/issues/comments/ID --jq .body`.
+
+**`--paginate` is the default for any list endpoint.** `gh api` returns **30** items per page and caps
+`per_page` at **100**, silently — a truncated page reads exactly like "that's all there is," so a
+missing `--paginate` becomes a wrong answer rather than an error.
+
+**CI / runs / releases**
+```bash
+gh run list -R OWNER/REPO --branch BRANCH --limit 10
+gh run view RUN_ID -R OWNER/REPO --log-failed        # just the failing step logs
+gh release view -R OWNER/REPO                         # latest release
+```
+
+**Search (across issues/PRs)**
+```bash
+gh search issues -R OWNER/REPO "crash on startup" --state open --json number,title,url --limit 30
+gh search prs --repo OWNER/REPO "author:@me" --json number,title,url --limit 30
+```
+Use search to find duplicates, related work, and prior art before you conclude something is novel.
+
+**Raw API** for anything the porcelain doesn't cover:
+```bash
+gh api repos/OWNER/REPO/commits/SHA/check-runs --jq '.check_runs[] | {name, conclusion}'
+gh api "repos/OWNER/REPO/issues?state=open&labels=bug&per_page=50" | { command -v toon >/dev/null 2>&1 && toon || cat; }
+```
+
+## Keep GitHub automation active
+
+CI, automated review, releases, merge queues, and already-authorized merge progression are work you
+can observe with `gh`; they do not earn an `awaiting` fence. Keep a live operation attached to the
+thread and continue when it reports.
+
+### Select monitor tooling explicitly
+
+Before launching any CI/review monitor, inspect project-local `AGENTS.md`, active skills, repository
+docs, `package.json` scripts, and declared monitor tooling. Prefer an explicit project-local monitor
+only if it documents terminal semantics for this gate. Validate its absolute command and terminal
+event/exit contract before launch. If declared tooling is missing, invalid, or has no terminal
+semantics, stop and report that configuration error; never silently shadow it with a Frizz script, and
+never execute a monitor merely because its filename looks plausible.
+
+When no project monitor is declared, the bundled fallback scripts are
+`<this-skill-dir>/scripts/ci-watch.mjs` and `review-watch.mjs`. They are generated byte-for-byte from
+Frizz's canonical `monitors/` source and require only Node plus logged-in `gh`. Their stdout is
+`frizz.github-monitor/v1` NDJSON: `status` means keep waiting; `terminal` is a verdict. They join
+exact-head workflow runs with PR checks, keeping `ACTION_REQUIRED` pending, and baseline every review
+and comment so any new one wakes — bot or human, with no actor
+filter. A GitHub/auth error is terminal exit 3; SIGINT/SIGTERM produces terminal
+`cancelled` and exit 130. A `--once` pending/baseline snapshot is deliberately non-terminal exit 0.
+For CI, retries are collapsed only within the same workflow name and event; distinct exact-head events
+such as `push` and `pull_request` both contribute to the aggregate verdict.
+
+- One-shot completion: launch `Bash` with `run_in_background: true`, for example
+  `gh run watch RUN_ID -R OWNER/REPO --exit-status` or a repo watcher that exits when all PR checks
+  settle. The completion task-notification re-invokes you. Diagnose/fix on red; continue the authorized
+  release/merge path on green.
+- State transitions: use native `Monitor` with a quiet loop that prints only changes or the terminal
+  event. It is the Claude adapter for the selected script; do not make a sub-agent the monitor
+  abstraction.
+  Finite monitors run up to one hour; `persistent: true` runs until `TaskStop` or the Claude session
+  ends. Stop a watch once its gate is obsolete.
+- A background Bash launch exposes an output-file path. Use `Read` on that path only for diagnostics;
+  `TaskOutput` is deprecated. Do not fake waiting with `echo waiting` or sleep-only Bash calls.
+
+Both mechanisms are session-bound. If the next check deliberately belongs at a named wall-clock
+instant, park with a durable `timer:` fence. If a specific external human reviewer/approver is the
+only remaining gate, park with `human: <actor + exact action>`. For a GitHub PR, pair it with
+`pr-watch: OWNER/REPO#NUMBER`: frizz baselines current reviews/comments and wakes on ANY new
+activity after the fence — bot or human — durably across restarts. Otherwise optionally pair a timer for
+a scheduled recheck. The dashboard operator's own go/no-go remains a ` ```question ` block. `pr:` / `ci:` /
+`session:` awaiting hints are legacy compatibility only — do not emit them for new automated waits.
+
+## Fitting gh work into your thread type
+
+- **Investigating an issue** (a research thread): reproduce → trace to `file:line` (cite every load-bearing claim) → recommend the smallest correct fix; read the full thread and linked issues/PRs with `gh` for context. Don't implement — stop at the recommendation. Handback = findings in your final message.
+- **Reviewing a PR** (an audit thread): read the diff AND the files in context, verify correctness/edges/tests, check CI (`gh pr checks`), then produce a review (blocking issues vs nits, each citing `file:line`) as your final message. Approve/merge only if explicitly asked.
+
+In both cases: read-only on GitHub unless told otherwise, and the review/findings live in your session, not in a GitHub post.

package/runtime/cc-worker/skills/gh/scripts/ci-watch.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { classifyChecks, gh, latestWorkflowRuns, parseArgs, report, sleep } from "./github-watch.mjs"
+
+const usage = "Usage: ci-watch.mjs --repo OWNER/REPO --pr NUMBER [--interval SECONDS] [--once]"
+
+async function main() {
+  let options
+  try { options = parseArgs(process.argv.slice(2), usage) } catch (error) {
+    process.stderr.write(`ci-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+    report("terminal", { kind: "ci", state: "error", error: error instanceof Error ? error.message : String(error) })
+    process.exitCode = 3
+    return
+  }
+  if (options.help) return console.log(usage)
+  let emittedTerminal = false
+  const terminal = (state, exitCode) => {
+    if (emittedTerminal) return
+    emittedTerminal = true
+    report("terminal", { kind: "ci", repo: options.repo, pr: options.pr, state })
+    process.exitCode = exitCode
+  }
+  const cancelled = () => { terminal("cancelled", 130); process.exit(130) }
+  process.once("SIGINT", cancelled)
+  process.once("SIGTERM", cancelled)
+  let previous
+  for (;;) {
+    try {
+      const pr = JSON.parse(await gh(["pr", "view", String(options.pr), "--repo", options.repo, "--json", "headRefOid"]))
+      const checks = JSON.parse(await gh(["pr", "checks", String(options.pr), "--repo", options.repo, "--json", "name,state,bucket,workflow,link"]))
+      const runs = pr.headRefOid ? JSON.parse(await gh(["run", "list", "--repo", options.repo, "--commit", pr.headRefOid, "--limit", "100", "--json", "name,workflowName,status,conclusion,databaseId,event,createdAt"])) : []
+      const workflows = latestWorkflowRuns(runs).map((run) => ({
+        name: run.name,
+        state: String(run.status).toUpperCase() === "COMPLETED" ? run.conclusion : run.status,
+        workflow: run.event,
+        link: run.databaseId ? `https://github.com/${options.repo}/actions/runs/${run.databaseId}` : undefined,
+      }))
+      const result = classifyChecks([...checks, ...workflows])
+      const signature = JSON.stringify(result)
+      if (signature !== previous) {
+        if (result.state === "pending") report("status", { kind: "ci", repo: options.repo, pr: options.pr, ...result })
+        else { emittedTerminal = true; report("terminal", { kind: "ci", repo: options.repo, pr: options.pr, ...result }) }
+      }
+      previous = signature
+      if (result.state === "passed") process.exitCode = 0
+      if (result.state === "failed") process.exitCode = 2
+      if (result.state !== "pending" || options.once) return
+    } catch (error) {
+      process.stderr.write(`ci-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+      terminal("error", 3)
+      return
+    }
+    await sleep(options.interval * 1000)
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`ci-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+  report("terminal", { kind: "ci", state: "error", error: error instanceof Error ? error.message : String(error) })
+  process.exitCode = 3
+})

package/runtime/cc-worker/skills/gh/scripts/github-watch.mjs

@@ -0,0 +1,130 @@
+import { spawn } from "node:child_process"
+
+export const PROTOCOL = "frizz.github-monitor/v1"
+const SUCCESS = new Set(["SUCCESS", "SKIPPED", "NEUTRAL"])
+const FAILURE = new Set(["FAILURE", "ERROR", "CANCELLED", "TIMED_OUT", "STARTUP_FAILURE"])
+export const GH_TIMEOUT_MS = 30_000
+const GH_ATTEMPTS = 3
+
+export function classifyChecks(checks) {
+  if (!Array.isArray(checks) || checks.length === 0) return { state: "pending", checks: [] }
+  let failed = false
+  let pending = false
+  for (const check of checks) {
+    const state = String(check?.state ?? check?.bucket ?? "").toUpperCase()
+    // A fork-gated workflow is reported as ACTION_REQUIRED after its skipped run completes. It is
+    // not CI success: continue watching for an approved replacement run instead of waking green.
+    if (state.includes("ACTION_REQUIRED") || state === "PENDING" || state === "QUEUED" || state === "IN_PROGRESS" || state === "WAITING") pending = true
+    else if (FAILURE.has(state) || state.includes("FAIL")) failed = true
+    else if (!SUCCESS.has(state) && state !== "PASS") pending = true
+  }
+  return { state: failed ? "failed" : pending ? "pending" : "passed", checks }
+}
+
+// Every review and comment counts, whoever filed it. Most PR review now arrives from an app —
+// Pullfrog, Copilot, CodeRabbit, Greptile — and the reviewers that post their findings as a
+// conversation comment are exactly what an actor-type filter used to throw away.
+export function reviewActivity(raw) {
+  const pr = raw?.data?.repository?.pullRequest
+  const nodes = [...(pr?.reviews?.nodes ?? []), ...(pr?.comments?.nodes ?? [])]
+  return new Set(nodes.map((node) => String(node?.id ?? "")).filter(Boolean))
+}
+
+export function latestWorkflowRuns(runs) {
+  const latest = new Map()
+  for (const run of runs ?? []) {
+    const key = `${run.workflowName ?? run.name ?? "unknown"}\u0000${run.event ?? ""}`
+    const old = latest.get(key)
+    const stamp = String(run.createdAt ?? "")
+    const oldStamp = String(old?.createdAt ?? "")
+    const id = Number(run.databaseId ?? 0)
+    const oldId = Number(old?.databaseId ?? 0)
+    if (!old || stamp > oldStamp || (stamp === oldStamp && id > oldId)) latest.set(key, run)
+  }
+  return [...latest.values()]
+}
+
+function ghOnce(args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    const child = spawn("gh", args, {
+      env: { ...process.env, GH_PAGER: "cat", GH_PROMPT_DISABLED: "1" },
+      stdio: ["ignore", "pipe", "pipe"],
+      // A separate process group lets POSIX hosts terminate a hung credential helper too. Windows
+      // uses ChildProcess.kill below; both paths remain Node-only and need no `timeout` utility.
+      detached: process.platform !== "win32",
+    })
+    let stdout = ""
+    let stderr = ""
+    const fail = (error) => {
+      if (settled) return
+      settled = true
+      reject(error)
+    }
+    const kill = (signal) => {
+      if (process.platform !== "win32" && child.pid) {
+        try { process.kill(-child.pid, signal); return } catch { /* child may already be gone */ }
+      }
+      child.kill(signal)
+    }
+    const timeout = setTimeout(() => {
+      kill("SIGTERM")
+      // Some broken credential helpers ignore SIGTERM. Do not let one wedged gh process hold a
+      // monitor forever; a second, portable child-process kill keeps the watch bounded.
+      setTimeout(() => kill("SIGKILL"), 1_000).unref()
+      fail(new Error(`gh timed out after ${timeoutMs / 1000} seconds`))
+    }, timeoutMs)
+    child.stdout.on("data", (chunk) => { stdout += chunk })
+    child.stderr.on("data", (chunk) => { stderr += chunk })
+    child.once("error", (error) => { clearTimeout(timeout); fail(error) })
+    child.once("close", (status) => {
+      clearTimeout(timeout)
+      if (settled) return
+      settled = true
+      if (status !== 0) reject(new Error(stderr.trim() || `gh exited ${status ?? "without a status"}`))
+      else resolve(stdout)
+    })
+  })
+}
+
+export async function gh(args, { attempts = GH_ATTEMPTS, timeoutMs = GH_TIMEOUT_MS } = {}) {
+  if (!Number.isInteger(attempts) || attempts < 1) throw new Error("gh attempts must be a positive integer")
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1) throw new Error("gh timeout must be positive")
+  let lastError
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try { return await ghOnce(args, timeoutMs) } catch (error) { lastError = error }
+    // A short bounded backoff covers transient GitHub and credential-helper failures. The final
+    // failure remains a terminal monitor error rather than an unbounded retry loop.
+    if (attempt + 1 < attempts) await sleep(250 * 2 ** attempt)
+  }
+  throw lastError
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export function parseArgs(argv, usage) {
+  const out = { interval: 60, once: false }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === "--help") return { help: true }
+    if (arg === "--once") out.once = true
+    else if (arg === "--repo" || arg === "--pr" || arg === "--interval") out[arg.slice(2)] = argv[++i]
+    else throw new Error(`Unknown argument: ${arg}\n${usage}`)
+  }
+  if (!out.repo || !out.pr) throw new Error(usage)
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(out.repo)) throw new Error("--repo must be OWNER/REPO")
+  if (!/^\d+$/.test(String(out.pr)) || Number(out.pr) < 1) throw new Error("--pr must be a positive number")
+  out.interval = Number(out.interval)
+  if (!Number.isFinite(out.interval) || out.interval < 5) throw new Error("--interval must be at least 5 seconds")
+  return out
+}
+
+// Every stdout line is one schema-versioned NDJSON event. A monitor may emit many status events
+// but exactly one terminal event when it reaches a terminal verdict. Exit codes: passed/new activity
+// 0, CI failure 2, invocation/GitHub error 3. `--once` may end after a non-terminal snapshot with 0.
+export function report(type, value) {
+  if (type !== "status" && type !== "terminal") throw new Error(`invalid monitor event type: ${type}`)
+  process.stdout.write(`${JSON.stringify({ protocol: PROTOCOL, type, at: new Date().toISOString(), ...value })}\n`)
+}

package/runtime/cc-worker/skills/gh/scripts/review-watch.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { gh, parseArgs, report, reviewActivity, sleep } from "./github-watch.mjs"
+
+const usage = "Usage: review-watch.mjs --repo OWNER/REPO --pr NUMBER [--interval SECONDS] [--once]"
+const QUERY = `query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviews(last:50){nodes{id}} comments(last:50){nodes{id}}}}}`
+
+async function main() {
+  let options
+  try { options = parseArgs(process.argv.slice(2), usage) } catch (error) {
+    process.stderr.write(`review-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+    report("terminal", { kind: "review", state: "error", error: error instanceof Error ? error.message : String(error) })
+    process.exitCode = 3
+    return
+  }
+  if (options.help) return console.log(usage)
+  const [owner, repo] = options.repo.split("/")
+  if (!owner || !repo) throw new Error("--repo must be OWNER/REPO")
+  let emittedTerminal = false
+  const terminal = (state, exitCode, extra = {}) => {
+    if (emittedTerminal) return
+    emittedTerminal = true
+    report("terminal", { kind: "review", repo: options.repo, pr: options.pr, state, ...extra })
+    process.exitCode = exitCode
+  }
+  const cancelled = () => { terminal("cancelled", 130); process.exit(130) }
+  process.once("SIGINT", cancelled)
+  process.once("SIGTERM", cancelled)
+  let baseline
+  for (;;) {
+    try {
+      const raw = JSON.parse(await gh(["api", "graphql", "-f", `query=${QUERY}`, "-F", `owner=${owner}`, "-F", `repo=${repo}`, "-F", `number=${options.pr}`]))
+      const current = reviewActivity(raw)
+      if (!baseline) {
+        baseline = current
+        report("status", { kind: "review", repo: options.repo, pr: options.pr, state: "armed", seen: current.size })
+      } else {
+        const added = [...current].filter((id) => !baseline.has(id))
+        if (added.length) { terminal("new-activity", 0, { ids: added }); return }
+      }
+      if (options.once) return
+    } catch (error) {
+      process.stderr.write(`review-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+      terminal("error", 3)
+      return
+    }
+    await sleep(options.interval * 1000)
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`review-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+  report("terminal", { kind: "review", state: "error", error: error instanceof Error ? error.message : String(error) })
+  process.exitCode = 3
+})

package/runtime/cc-worker/skills/handoff/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: handoff
+description: The full frizz end-of-turn signal reference for a frizz worker (invoke as frizz:handoff) — every `awaiting` hint kind, the `question` fence tags (`danger`, `multi`), `done` body formatting, and worked examples of each. Your system-prompt contract carries the rules you need for the common case; load this when you are emitting an unusual fence, need a worked example of a tagged question card, or are unsure which fence a situation calls for.
+---
+
+# frizz handoff reference
+
+Your system prompt states the fence rules. This is the elaboration: the exact shapes, the tags, and
+worked examples. Nothing here overrides the contract.
+
+**Before you use any of it: is the turn actually over?** Every shape below is for a turn that has
+genuinely ended. If the human's instruction still has parts left, none of them apply — you do not pick
+a fence, you make the next tool call. Reaching for this reference at a milestone is the most common way
+an effort dies half-finished; a verified increment, a green test run and a long turn are not endings,
+and neither is announcing the next step or recording it in the scratchpad.
+
+## Which fence?
+
+| Situation | Fence |
+|---|---|
+| Ordinary handoff, turn has no other final state | **bare rest** (no fence) |
+| Effort's real work is complete — code merged, plan/doc written, commissioned report finished | `done` |
+| Waiting on a named third-party human, a wall-clock instant, or a PR's review | `awaiting` |
+| You need the operator's input or approval | `question` |
+| Mid-conversation (still working, or answering and continuing) | none |
+
+Automatable waits — CI, releases, deploys, merge progression — are **never** `awaiting`. Dispatch a
+sub-agent to own the wait, or use a `timer:` when the next check belongs at a later wall-clock time.
+
+## `done`
+
+Body is a bullet list, one `- ` item per completed task, each naming what shipped and where. The card
+renders inline markdown: backtick every path/identifier/command, and make references real links.
+
+```done
+- Fixed the cache collision in [`src/resolver.ts`](https://github.com/acme/app/pull/391) — the lookup now keys on the normalized id.
+- Added a regression test for the collision case; `npm test` green.
+- Self-review folded in; `npm run lint` clean.
+```
+
+Do not write a narrative paragraph. Do not fence `done` on work that is not landed.
+
+## `awaiting` — the three hint kinds
+
+Lead the body with one or more `kind: value` lines, then prose naming the exact wake condition.
+
+`pr-watch: owner/repo#NUMBER` — frizz polls the PR and resumes you on ANY new activity after the fence:
+a review, an approval, or a comment, from a **human or a bot alike** (review agents that post findings
+as a conversation comment count exactly like a human reviewer). Baselined at the fence and durable
+across a server/worker restart. Your thread **stays in the queue** as a visible "PR is up, watching it"
+handoff — it does not hide in Held, because a PR whose reviews may never arrive must not silently
+vanish. The human can Snooze it; new activity bumps it back.
+
+```awaiting
+pr-watch: acme/app#391
+PR is open and CI is green. Watching for review — I'll address comments or merge on approval.
+```
+
+**One line watches one PR, and a fence may carry several.** The scheduler evaluates every hint in the
+body, so repeat the line per PR — across any mix of repos — and activity on ANY of them wakes you. A
+set of open PRs is NOT a reason to fall back to a periodic `timer:` sweep, which trades instant wakes
+for a poll that can sit a day behind a review. The body keeps its first **8** hint lines and silently
+drops the rest, so past 8 watch the 8 that matter and cover the tail with a `timer:`.
+
+```awaiting
+pr-watch: withastro/astro#17487
+pr-watch: vitejs/vite#23019
+pr-watch: strapi/strapi#26864
+All three adoption PRs are open and green, in their maintainers' hands. Whichever gets a review first
+wakes me and I'll address it.
+```
+
+`human: <actor + exact review/approval>` — a third party whose action cannot be supplied in this frizz
+conversation. **Parks you in the dimmed Held band.** A bot, automated reviewer, CI gate, or merge queue
+is NOT a human wait. Pair with `pr-watch:` when a machine-readable PR exists (the `human:` supplies the
+Held park, the `pr-watch:` supplies the cursor), or with `timer:` when none does.
+
+```awaiting
+human: dependabot maintainer review on dependabot/dependabot-core#15524
+pr-watch: dependabot/dependabot-core#15524
+The implementation and actionable checks are complete; address requested changes when review lands.
+```
+
+`timer: <ISO-8601 instant>` — the durable frizz scheduler resumes you at that instant, across process
+exits and restarts. The prose says exactly what to re-check.
+
+```awaiting
+timer: 2026-07-15T17:00:00Z
+Re-check whether the external maintainer review arrived and reclassify any new failure.
+```
+
+`pr:` / `ci:` / `session:` remain parser compatibility for existing transcripts only. Never emit them.
+
+### Re-entering a wait after a follow-up
+
+Every human follow-up clears the previous fence. Never answer that you are "already parked" and never
+rely on the old fence, scratchpad, or thread status: re-check the blocker, then either re-emit a fresh
+`awaiting` with a current hint, or arm the active wait if it turns out to be automatable.
+
+## `question` — the tags
+
+Plain — an open question:
+
+```question
+Should the settings store use SQLite or a JSON file?
+
+- A. SQLite — transactional, matches how sessions are already stored (recommended: consistency)
+- B. JSON file — zero deps, human-editable, racy under concurrent writes
+```
+
+A GO/NO-GO gate has NO tag of its own — it is a plain `question` with two options, the go and the
+decline. (There used to be an `approval` tag rendering one Approve button that SENT on click; it was
+dropped 2026-07-26 because it couldn't express the decline and it bypassed the staging every other
+block uses. A legacy `approval` token still parses — as a plain question — so old transcripts render,
+but never write one.)
+
+```question
+Ready to create CONTRIBUTING.md with the draft above?
+
+- A. Approve as-is (recommended)
+- B. Hold — tell me what to change first
+```
+
+`danger` — reserve for the genuinely hard-to-undo (force-merge, deletion, history rewrite,
+prod rollback). Renders in red. A routine ship is a plain question:
+
+```question danger
+Force-merge PR #391 over the failing flaky check and delete the `legacy-api` branch?
+
+- A. Do it — the failure is the known-flaky timeout
+- B. Hold — I'll wait for a green run
+```
+
+`multi` — select-several triage. Options render as checkboxes; the answer returns the chosen letters:
+
+```question multi
+Which of these findings should I fix in this pass?
+
+- A. Null-deref in parse() — crashes on empty input
+- B. Off-by-one in slice() — drops the last row
+- C. Flaky timeout in the retry test — passes on rerun
+```
+
+### Rules that apply to every question
+
+- Open the message with 2-4 sentences of status before the blocks.
+- One block per independent question — never bundle.
+- Lettered options, one markdown list item each, with a one-line tradeoff.
+- Mark exactly one option `recommended` **on that option's line**, and put it first as `A`. Use
+  `(recommended: one-line why)` to carry the rationale into the chip's tooltip. Do not use a separate
+  `Recommendation:` line.
+- Answerable COLD, in the human's own vocabulary — see the next section.
+- A question IS the handback: no second fence.
+- Before you write one, re-read the stop criterion. A question about work you were dispatched to do,
+  or a fix you already recommend, is not a question.
+
+### Write it in the human's own vocabulary
+
+The reader has their original prompt and nothing else — not your plan, not your scratchpad, not the
+transcript, not the names you settled on while working. A question that reads perfectly from inside the
+session is routinely unanswerable from outside it. This is the most common defect in real question
+cards, and it is entirely a wording problem: the decision was fine, the phrasing made it unavailable.
+
+- **Translate the nomenclature you coined mid-effort.** Anything you named while working is invisible to
+  the reader: phase / lane / tier / mode names, step or section numbers, "the C path", "the second
+  variant", "the reconciler", "option 3 from earlier", "as in §2 of the plan". They will not go read your
+  transcript to decode it, so say what the thing does instead of what you called it.
+- **Minimize code identifiers; default to plain behavior.** File paths, function / type / component
+  names, flags, env vars, table and column names usually cost the reader more than they give — lead with
+  the behavior. Spend an identifier where it genuinely earns its place: the human already uses it, or the
+  decision is literally about that name (they asked you to rename it, or to pick a flag's spelling). One
+  well-chosen identifier is fine; a card assembled out of them is the failure mode.
+- **Carry every decision input inside the block.** What happens today, each option's user-visible
+  consequence, the cost of guessing wrong, and any number that matters. "As discussed above", a pointer
+  to a file, or a reference to an earlier turn all point at something the reader cannot see from the card.
+- **Define a load-bearing new term, or drop it.** If one unfamiliar word genuinely cannot be avoided,
+  define it in the same sentence. Otherwise it is decoration, and it costs you the answer.
+
+Bad — every noun here was invented during the effort, so the reader has no way into it:
+
+```question
+Should the queue lane keep the tier-2 fallback from step 3, or move to the unified resolver?
+
+- A. Keep the tier-2 fallback (recommended)
+- B. Move to the unified resolver
+```
+
+Good — same decision, stated in terms the human already owns:
+
+```question
+When you've read everything in a thread, should it stay in the "needs attention" group until you archive it, or drop out on its own?
+
+- A. Drop out once it's read (recommended: keeps the group to threads that still need you)
+- B. Stay until archived — nothing ever disappears without you acting on it
+```
+
+(That question line is deliberately unwrapped. Inside a fence a single newline is a HARD break —
+`breaks: true` in the web markdown renderer — so hard-wrapping the sentence at your editor's column
+renders a ragged break mid-question in the card. Keep the question, and each option, on one line.)
+
+Test it before you send: read the block with your session forgotten, as if it were the only thing you
+had ever seen about this work. Any word that only means something because of what you just did is a word
+to reword.
+
+## Never use the interactive question tool
+
+`AskUserQuestion` (or any blocking prompt tool) would hang your session invisibly under the dashboard.
+It is removed from your tool set at spawn; if you somehow reach it, a hook denies it. Use a `question`
+fence.