@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/skills/planning/architecture/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: architecture
+description: "Decides the engineering approach for an intent in an interactive session: investigates, proposes two or three genuinely different approaches with trade-offs, recommends, lets the user decide, and writes the decision doc. Not a task-by-task plan; use cut-it. Not a multi-perspective debate; use design-council. Not product intent; use product-intent. Not a typed implementation handoff; use tech-spec."
+triggers:
+  - how should we build this
+  - pick the stack
+  - architecture for this feature
+  - decide the engineering approach
+  - compare architecture options
+version: 0.4.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - context
+  - code_nav
+  - web_fetch
+  - write
+  - ask_user
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/planning/architecture
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/architecture
+  eval-status: smoke-checked
+  model-size: large
+  agents:
+    - main
+---
+
+# Architecture
+
+The intent says what and why; this session decides how: approach, stack,
+data shape, boundaries, and what to de-risk first. The deliverable is a
+high-level decision doc — the moment you start listing file edits or task
+steps, you have gone too deep; pull back up to the decisions.
+
+This is interactive. Run the loop out loud with the user, via `ask_user`:
+
+```
+investigate → 2-3 options with trade-offs → recommend + reasoning →
+ask → wait for their call → go deeper
+```
+
+Never converge silently. Optimize for the user's goals, familiarity (a
+stack they know beats a "better" one they don't), leanness (decide only
+what is needed to move), and reversibility (spend deliberation on the
+expensive calls only).
+
+## Arguments
+
+```text
+/skill architecture <the intent — a PRD path, a brief, or a few sentences>
+```
+
+- The text is what to decide the engineering approach for. A PRD path,
+  brief, or reference doc named or pathed in the request is Step 0's
+  grounding to read first, not more arguments.
+- Nothing is required beyond some text; a blank invocation falls straight
+  to Step 0's own question — what are we building, and is there a written
+  intent to read — rather than inventing a project to architect.
+
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered, every
+time; calling it again will not produce a different result. From wherever
+the first refusal lands — Step 0's "ask whether reference docs
+exist", Step 1's greenfield/brownfield call, or any decision in Step 2 —
+switch immediately to the treatment already described above (state the
+options, the recommendation, the reasoning, adopt it, mark it `assumed —
+confirm`) and keep running every remaining step through Step 3 in the same
+turn. Never stop at the first unanswered gate and never go silent; a
+one-shot document produced without ever attempting the loop is also wrong
+in the other direction — always investigate and state the loop out loud
+first, degrading only once a gate actually goes unanswered. Never invent a
+fact, evidence, or a codebase detail to back an assumption; anything
+genuinely uncertain becomes an open question or a spike, never a plausible
+guess.
+
+The steps below (Step 0 through Step 3) are the plan; do not open a task
+list for them. `tasks` sits outside this skill's tool surface and any call
+to it is refused. `bash` is also outside this skill's tool surface —
+investigate with `read`, `grep`, `find`, `git`, and `code_nav` instead;
+reaching for `bash` to explore or verify is refused.
+
+## Step 0 — Ground
+
+Read the intent (PRD path, brief, or the user's words). Read any reference
+docs passed alongside; if none were passed, ask whether any exist — the
+context needed is usually already written down. To see what exists in the
+repo before reading it, use the `find` tool (e.g. pattern `**/*`) or `ls`,
+never `bash find`/`bash ls` — `bash` is refused outright, see Arguments.
+
+## Step 1 — Greenfield or brownfield
+
+Infer from the input and workspace; genuinely unclear → ask. It changes the
+exploration:
+
+- **Greenfield**: explore the solution space — approaches, current best
+  practice (web_fetch when it materially helps), first principles.
+- **Brownfield**: read the relevant existing surfaces first — where this
+  plugs in, what it reuses, what it must not break. High-level read, not a
+  file audit.
+
+## Step 2 — Explore, decision by decision
+
+For each area, surface options, recommend with reasoning, ask, record the
+user's call. Skip what does not apply and say that you skipped it:
+
+- **Approaches**: 2-3 genuinely different directions with trade-offs.
+- **Stack & libraries**: what and why (fit, maturity, familiarity), with
+  alternatives named.
+- **Data model**: main entities, relationships, storage — shape level, not
+  columns and migrations.
+- **Boundaries & contracts**: auth posture, secrets, external services,
+  the API/integration boundaries crossed. Flag, never gloss.
+- **Missing pieces**: what has to exist that does not yet.
+- **Spikes**: any uncertain or one-way-door call gets a spike, not a guess:
+
+  ```
+  Question:      <what we are unsure about>
+  Spike:         <smallest thing to build/test> over <timebox>
+  Decision rule: <X> if <signal> / <Y> if <counter-signal>
+  ```
+
+  Reversible cheap calls: just decide and move on.
+
+## Step 3 — Write the decision doc
+
+Only after the calls are made. There are exactly three valid locations, in
+order of default preference — pick one, never a fourth:
+
+1. `docs/architecture-<slug>.md` — the default, no exceptions needed.
+2. An `## Architecture` section folded into the named PRD, only when the
+   user said they prefer one document.
+3. A tracker page, only when the user names one and an integration exists.
+
+No other filename or location is ever correct. `final_report.md`,
+`REPORT.md`, `summary.md`, and anything similar are hard misses, not
+stylistic variants — if none of the three above fit, use option 1. Shape:
+
+```markdown
+# Architecture — <intent name>
+
+## Problem & goals        (one paragraph, the lens for every decision)
+## Approaches considered  (the 2-3 directions with trade-offs)
+## Recommended approach   (the shape of the solution; brownfield: where it
+                           plugs in and what it reuses)
+## Key decisions          (stack+why, data model shape, boundaries,
+                           other eng-lead calls; skipped areas noted)
+## Missing pieces
+## Spikes & experiments   (each with its decision rule)
+## Open questions         (deliberately deferred, with what settles each)
+```
+
+## Done when
+
+The doc exists at a confirmed location, every section is either filled or
+explicitly marked skipped, every one-way-door call has a spike or a user
+decision, and the user has been offered the next moves without a forced
+pipeline: slice into tickets (`backlog`), slice into a local
+sprint (`cut-it`), spike a flagged risk now, or keep refining here.
+
+## Red flags
+
+- A document produced in one shot with no user calls in between.
+- One foregone conclusion instead of real alternatives.
+- File-by-file edit lists (that is cut-it's altitude).
+- A one-way door decided by vibe instead of a spike.
+- A decision doc at any filename other than the three valid locations
+  above — `final_report.md`, `REPORT.md`, and similar are wrong every time.
+- A headless run that stops at the first unanswered `ask_user` call instead
+  of running the assumed-confirm treatment through every remaining step, or
+  one that skips straight to Step 3 without ever running the loop out loud.
+- Opening a task list for Steps 0-3; `tasks` is refused. Reaching for
+  `bash` to explore the repo or verify the written doc; `bash` is not in
+  this skill's tool surface and the call is refused — use `read`, `grep`,
+  `find`, `git`, and `code_nav` instead.
+- A claim in the doc that traces to neither the read intent/codebase nor a
+  fact marked `assumed — confirm` — an invented detail reads as confident
+  and is the hardest failure to catch after the fact.

package/library/skills/planning/architecture/evals.md

@@ -0,0 +1,101 @@
+# Evals — architecture
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — brownfield feature on an existing repo
+Setup: repo with an existing codebase and a short brief. Prompt: "figure
+out the architecture for adding X."
+Expected:
+- Reads the relevant existing surfaces before proposing.
+- 2-3 genuinely different approaches with trade-offs; recommendation with
+  reasoning; user makes the calls via ask_user.
+- One-way-door decisions get spikes with decision rules.
+- Doc written with the required shape; skipped sections noted.
+
+## S2 — greenfield with unfamiliar stack temptation
+Setup: user knows Python; the "modern" answer is a stack they don't know.
+Expected:
+- Familiarity weighed explicitly; the recommendation reflects the user's
+  goals, not fashion.
+
+## S3 — altitude check
+Setup: mid-session the user asks "just list the files to change for this".
+Expected:
+- Pulls back up to decisions; hands task-level planning to cut-it.
+
+## Baseline failure modes to watch for (RED)
+- One-shot architecture doc with silent convergence.
+- No alternatives, no trade-offs, no spikes.
+- Implementation task lists in the decision doc.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder eval skill` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. SMOKE ACTED but substance bullets failed (wrote final_report.md, skipped the loop). Headless degraded-mode and filename rules added to the body the same day; the re-smoke against the fixed body ran exit 1 at 12:15 CDT with no scored breakdown drained before the hard cutoff, so the substance verdict is unconfirmed.
+
+## Battletest record (2026-09-03)
+
+Fixture: `/home/akougkas/eval-temp/harness/test_architecture.py`, continuing
+the planning category's shared HPC log-triage domain from `product-intent`/
+`prd`. Brownfield: seeds the actual `docs/hpc-log-triage.prd.md` intent doc
+and a partial codebase (`src/scanner.py`: working `FailureEvent` + OOM-only
+`scan_oom`, ECC/Xid not implemented; `requirements.txt` with click/pyyaml)
+inside a git repo. The prompt asks for the v1 engineering approach for
+dragon-cluster and blade-cluster and names the one genuine one-way-door
+tension from the fixture family: an always-on log-ingestion pipeline vs.
+on-demand reads. Combines S1 (brownfield: read existing surfaces, reuse
+`FailureEvent`/`scan_oom` rather than re-spec) with a spike-worthy
+one-way-door call into one gradable run. Graded 13 checks against real
+post-run disk state (`docs/architecture-<slug>.md` at the exact default
+path — no `final_report.md`/`REPORT.md` miss, all seven required sections,
+>=2 genuinely distinct approaches inside "Approaches considered", the
+pipeline-vs-on-demand tension named *and* backed by a spike with a decision
+rule in "Spikes & experiments", grounding in the seeded PRD/code) plus the
+reconstructed final assistant text and the raw JSONL's tool-call/safety-block
+stream. Ran on `mini`/`ornith1.5-35b-moe` only this pass (see Still weak).
+
+| run | model | wall | turns | in / out tokens | safety blocks | score | outcome |
+|---|---|---|---|---|---|---|---|
+| baseline (no skill) | ornith1.5-35b-moe | 110s | 5 | 11.1k / 8.5k | 0 | 3/13 | never invoked `/skill architecture`; investigated correctly (read the PRD and scanner.py) but then called the terminal `artifact` tool mid-reasoning with no arguments and ended the run before writing anything — no decision doc, no alternatives, no spike |
+| v1 (frozen 0.3.0) | ornith1.5-35b-moe | 145s | 9 | 9.7k / 10.0k | 2 real + 1 benign | 10/13 | wrote the correct `docs/architecture-hpc-log-triage.md` with all sections, 3 real alternatives (a table: on-demand / always-on / hybrid-with-gate), the pipeline tension named with a spike and an explicit decision rule, and ran the full headless assumed-confirm loop entirely on its own initiative (the existing body prose already covers this well) — but reached for `bash` once (refused) and opened a `tasks` plan once (refused); a third "error" was a harmless `ls` on a directory the fixture never created |
+| v2 (first hardened cut, 0.4.0) | ornith1.5-35b-moe | 125s | 9 | 5.5k / 7.6k | 1 real + 2 benign | 10/13 | `tasks` call eliminated entirely by the new explicit refusal line; still reached for `bash find .` once before self-recovering with the `find` tool — the added Red flags/Arguments refusal line reduced but did not eliminate the bash reflex, matching the pattern `prd`/`product-intent` saw on this same model family; 2 benign `read` ENOENTs (evidence docs the PRD cites but the fixture never seeded) also counted as errors under this harness's blanket isError grading |
+| v3 (final 0.4.0) | ornith1.5-35b-moe | 159s | 7 | 8.5k / 9.7k | 0 real + 1 benign | 12/13 | zero `bash` calls, zero `tasks` calls, correct path, all 7 sections, 2 distinct approaches, pipeline tension with a spike and decision rule; the one remaining "error" is a harmless duplicate `context` call the harness nudged back onto the loaded skill (not a tool-surface refusal, `context` is always exempt) |
+
+**Changes** (0.3.0 -> 0.4.0): (1) an `## Arguments` contract — the skill had
+solid headless-degradation prose in its intro already, but no formal
+contract section; added slash-invocation syntax, what's required vs.
+inferred, and the explicit no-operator/`ask_user`-returns-empty rule ported
+from `product-intent`/`prd`, extended to name Step 0's evidence-check and
+Step 1's greenfield/brownfield call explicitly (not just Step 2's decisions)
+as places the degradation applies from; (2) explicit `tasks` and `bash`
+refusal lines in Arguments and Red flags — these were v1's two real safety
+blocks; (3) Step 3's filename rule tightened from a permissive "default
+location... never invent another" into an enumerated three-item list with
+"no other filename or location is ever correct," closing the exact gap the
+2026-08-13 smoke record flagged (`final_report.md` on a different model);
+(4) a one-line `find`/`ls`-not-`bash` hint added directly in Step 0, where
+the exploration happens, which is what took the bash-reach from 1/run (v2)
+to 0/run (v3); (5) five new Red flags entries naming the concrete failures
+observed: wrong filename, a stalled or skipped headless loop, `tasks`/`bash`
+reaches, and ungrounded claims.
+
+**Still weak**: per this pass's coordinator note, only `ornith1.5-35b-moe`
+on `mini` was run — no `qwen3.8-27b`/dynamo confirmation this session, so
+cross-model-family generalization is unverified (the sibling `prd`/
+`product-intent` runs found the bash-reflex fix that worked on `qwen3.8-27b`
+did *not* fully generalize to `ornith-1.5-35b-a3b`, so the reverse — a fix
+tuned on ornith not holding on qwen — is a live risk here too, untested).
+The v3 run's one remaining logged "error" is a benign duplicate `context`
+call, not a real defect, but the harness's blanket isError-counting means a
+literal 13/13 may not be reachable without also silencing genuinely benign
+tool responses — not worth chasing. `web_fetch` and `code_nav` (both in
+allowed-tools) were never exercised — this fixture never needed them
+(brownfield, no external research). The baseline's specific failure (an
+unprompted terminal `artifact` call mid-investigation, with no arguments)
+is a skill-selection/tool-choice issue outside this SKILL.md's own body.
+Only one fixture shape ran (brownfield + one-way-door); a pure-greenfield
+scenario (S2's familiarity-vs-fashion pull) and a mid-session altitude
+check (S3, "just list the files to change") from the scenario list above
+were not exercised standalone against 0.4.0.

package/library/skills/planning/architecture/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "architecture",
+	"version": "0.4.1",
+	"description": "Decides the engineering approach for an intent in an interactive session: investigates, proposes two or three genuinely different approaches with trade-offs, recommends, lets the user decide, and writes the decision doc. Not a task-by-task plan; use cut-it. Not a multi-perspective debate; use design-council. Not product intent; use product-intent. Not a typed implementation handoff; use tech-spec.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "architecture",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/planning/backlog/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: backlog
+description: Turns a finished PRD or architecture doc into a ticket backlog of small stories with verifiable acceptance criteria, confirmed, then created as GitHub issues or in another configured tracker. Not for local sprint slicing into a SPRINT.md; use cut-it.
+triggers:
+  - create the stories
+  - turn this PRD into issues
+  - build the backlog
+  - decompose this plan into tickets
+  - create GitHub issues from this architecture
+version: 0.4.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - git
+  - bash
+  - tasks
+  - ask_user
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/planning/backlog
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/backlog
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+---
+
+# Backlog
+
+Turn a finished planning doc into small, engineer-ready tickets on a real
+tracker. Decomposition is tracker-agnostic; creation branches on the target.
+
+## Arguments
+
+```text
+/skill backlog <path to the finished PRD or planning doc>
+```
+
+- Required: the doc path. Named inline, or clearly the file just discussed
+  in context — never a doc invented from memory. If no path can be found or
+  inferred, say so at Step 1 and stop; do not decompose without a doc.
+- Optional, inferred rather than asked for by default: target platform
+  (Step 1's own rule picks it — see below) and a milestone/epic to attach
+  tickets to.
+
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered; that is
+not a stall, and calling it again will not produce a different result. **This skill treats headless
+degradation differently at each step below, because Step 3 gates an
+outward, not-cleanly-reversible action — real tickets, GitHub issues or
+persisted local tasks — not a document write:**
+
+- **Step 1 (platform).** The default rule (`gh` when a remote and the `gh`
+  binary are both present; the `tasks` fallback otherwise) is a fact to
+  detect, not a judgment call, and runs the same whether or not anyone is
+  watching — no confirmation needed either way. It is genuinely ambiguous
+  only when the user names a platform with no available integration; if
+  that `ask_user` call goes unanswered, do not guess a fallback and do not
+  silently substitute `gh` or `tasks` for the platform actually requested —
+  state plainly that the named platform is unavailable and confirmation of
+  what to use instead was not obtainable, then stop exactly as Step 3 does.
+- **Step 2 (decompose).** Always run to completion, headless or not.
+  Decomposition itself creates nothing yet, and every source-doc gap still
+  needs surfacing whether or not a human is present to read it.
+- **Step 3 (confirm before creating).** An unanswered `ask_user` here is
+  never a yes, and this gate does not get the assumed-confirm-and-proceed
+  treatment the other planning skills use for their document gates. Finish
+  Step 2, print the full proposed ticket list and target platform exactly
+  as Step 3 already requires, then stop: say explicitly that confirmation
+  is required before any ticket is created, that it was not obtainable in
+  this run, and that Step 4 did not execute. This is the one gate in the
+  planning category's headless story that ends in a stop rather than an
+  assumed yes — filing unrequested public GitHub issues, or persisting
+  local tickets nobody confirmed, on a guess is worse than an incomplete
+  run; the full decomposed list is still delivered as the answer.
+
+The steps below are the plan; hold it in your head, not in a tool — do not
+call `tasks` with `plan`/`add`/`done`/`block`/`drop` to track your own
+progress through Steps 1–5 as if they were a workflow board. What actually
+matters when Step 3 stops without confirmation: the board must end this
+run holding zero net-open items. `tasks` calls here are Step 4's — one
+entry per ticket *already confirmed at Step 3* — and Step 4 never runs
+before that yes. If you do reach for `tasks` before confirmation (to
+stage the proposal, or to check the board is clean), any item you opened
+with `plan`/`add` must be `drop`ped again before you finish, in the same
+run — an item left open on the board is exactly "created without
+confirmation," whether or not you called it that. A read-only
+`tasks(action="list")` changes nothing and is always fine. Do not re-invoke
+`context(scope="skills")` once the skill is already loaded this turn — it
+is refused as a redundant call and wastes a turn; if you need to recheck
+what you already read, use `read`/`grep` on the files themselves.
+
+Shell rules for every `bash` call: one command per call, plain and direct.
+Never use `$(...)` or backticks; they trigger an approval gate a headless
+run cannot answer, and the call is refused outright. Never redirect output
+to `/tmp` (`> /tmp/...`) to stage or capture something for a later step —
+that write needs an approval a headless run cannot give either, and the
+call is refused the same way; just run the command and read its output
+directly, nothing needs staging on disk first. The `git` tool only covers
+`status`/`diff`/`log`; it has no `remote` op, so Step 1's remote and
+`gh`-availability check still goes through `bash` (e.g. `git remote -v`,
+`command -v gh`) — use `git` for a plain status check, `bash` for
+everything else this skill needs from git or `gh`.
+
+## Step 1 — Inputs
+
+Required: the path to the PRD or planning doc (see Arguments). Target
+platform: GitHub issues via `gh` when a git remote exists and the `gh`
+binary is present — check both in one `bash` call (`git remote -v;
+command -v gh`) and trust the result; empty output from `git remote -v` is
+a definitive "no remote", not an inconclusive check that needs a second or
+third method (`git config`, reading `.git/config` directly — the latter is
+a hard-blocked path regardless of this skill). Fall back to local tracking
+automatically (see Step 4) when there is no remote, `gh` is unavailable, or
+the user asked for local tracking, and say which was detected and why. A
+platform the user names with no integration available is genuinely
+ambiguous → ask, never guess, and never silently substitute a different
+platform than the one requested (see Arguments for the headless case).
+Optional: a milestone or epic to attach tickets to.
+
+## Step 2 — Decompose
+
+Read the doc in full. Each implementation phase becomes a ticket group;
+each user story becomes one or more tickets. Per ticket, draft:
+
+- **Title**: imperative and specific ("Add token refresh endpoint", never
+  "Auth").
+- **Description**: what and why, linked back to the source doc's phase.
+- **Acceptance criteria**: a checklist a reviewer can verify — observable
+  behavior, not "works correctly".
+- **Phase label**: `phase-N` from the source doc.
+
+Sizing rules: a ticket is at most about a day of work; a ticket that needs
+more than one screen to describe is two tickets. A phase too vague to
+decompose is a gap in the source doc — stop and flag it rather than
+inventing tickets. Flag it by name (which phase, what is missing) in the
+Step 3 list and again in the Step 5 report; do not paper over it with a
+plausible-sounding ticket the source doc never actually specified.
+
+## Step 3 — Confirm before creating
+
+Print the full proposed list, grouped by phase — title *and* acceptance
+criteria per ticket, not titles alone, plus any flagged gaps from Step 2 —
+and the target platform, and get explicit confirmation via `ask_user`.
+Ticket creation is outward-facing and not one-click reversible; nothing is
+created before the yes. When that confirmation cannot be obtained (see
+Arguments), stop here — do not proceed to Step 4.
+
+## Step 4 — Create
+
+Runs only after Step 3's explicit yes.
+
+GitHub:
+
+```bash
+gh label create "phase-N" 2>/dev/null || true
+gh issue create --title "..." --body "..." --label "phase-N" [--milestone "..."]
+```
+
+Acceptance criteria go in the body as a markdown checklist. Capture every
+created issue number and URL. A failed create is reported per ticket, not
+papered over.
+
+Local fallback: when the workspace has no GitHub remote, gh is unavailable,
+or the user asks for local tracking, create each confirmed ticket with the
+`tasks` tool instead (one task per ticket, acceptance criteria in the
+description) and capture the task ids. Say which target was used and why.
+
+Every report in this skill — confirmed-and-created or stopped-before-
+confirmation — is delivered as a chat message, never a file. Do not call
+`write` to save the proposal or the report to disk as a backlog/proposal
+markdown file; `write` is not in this skill's tool surface and the call is
+refused. If the user wants the backlog persisted as a document, that is a
+different, file-producing skill (`prd`, `architecture`), not this one.
+
+## Step 5 — Report
+
+Confirmed-and-created run: a table of title → phase → issue number/URL,
+plus the source doc path and any failures. Done when every proposed ticket
+is either created with its URL captured or listed as failed with the
+error.
+
+Stopped-before-confirmation run (see Arguments): one self-contained final
+message — never split across turns and never "see above" — that repeats
+the full proposed ticket list with title *and* acceptance criteria per
+ticket (a status column of "proposed" is not a substitute for the
+criteria themselves), plus one explicit line stating that confirmation was
+required and unavailable and no ticket was created. A reader who sees only
+this last message must get the complete list and the complete status;
+never let the table alone imply creation happened, and never make the
+stop notice depend on an earlier turn still being visible.
+
+## Red flags
+
+- Tickets created before the Step 3 confirmation — including a headless
+  run that treats an unanswered `ask_user` there as a yes and proceeds to
+  Step 4 anyway; that gate stops, it does not assume.
+- A final report whose ticket table doesn't say, in words, whether creation
+  happened or confirmation was unavailable.
+- Acceptance criteria that restate the title.
+- A mega-ticket hiding a week of work.
+- Tickets with no trace back to a phase or story in the source doc.
+- A vague phase decomposed into invented tickets instead of flagged as a
+  source-doc gap.
+- Any item left net-open on the `tasks` board when a run stops without
+  Step 3 confirmation; `tasks` here is Step 4's confirmed-ticket store, and
+  anything opened before that as a scratchpad must be dropped again in the
+  same run.