ftown-bridge 0.18.2 → 0.19.1

package/skills/factory/factory-template/skills/design.md

@@ -0,0 +1,259 @@
+# DESIGN stage — turn a groomed PRD into a frozen, implementable design.
+
+The worker protocol in `_protocol.md` is binding; follow its lifecycle. This skill only
+tells you what to produce between `fts start` and your outcome command.
+
+Your job: read the real codebase, then write ONE artifact — `TICKET_DIR/design.md` — that
+an implement agent (a weaker model) can execute with zero questions. You freeze the
+interfaces and map every acceptance criterion (AC) to a test. You do NOT write product
+code. You do NOT change the PRD.
+
+## Inputs
+
+- `TICKET_DIR/prd.md` — the groomed spec. Its ACs are your contract with the pipeline.
+- The repository at `REPO_ROOT` — the source of truth for existing patterns. Read it.
+- (Only if bounced back from implement) a reject reason attached to the ticket history.
+  Get it with `fts show --db "$FTS_DB" "$TICKET_ID" --json`. Every item in it MUST be
+  addressed in this revision (see "Bounce-back handling").
+
+## Procedure
+
+### 1. Recon the codebase (do this before designing — spend real effort here)
+
+You cannot extend patterns you have not read. Produce these findings and keep them; the
+implement stage will reuse them, so record them verbatim in `design.md`.
+
+1. Read `prd.md` fully. Name the ONE concern this ticket touches (e.g. "HTTP route",
+   "background job", "ORM model", "CLI command").
+2. Locate entry points: find where that concern already lives. Use search, not guessing:
+   ```bash
+   ls "$REPO_ROOT"
+   # then search for the concern by name/behavior, e.g.:
+   semble search "<concern, described>" "$REPO_ROOT"   # or: grep -rn "<symbol>" "$REPO_ROOT/src"
+   ```
+3. Find the nearest SIBLING: an existing file that does the same KIND of thing the ticket
+   asks for. Read it top to bottom. This sibling defines your naming, layout, error
+   handling, and imports. You will copy its shape.
+4. Find the test convention: open the sibling's test file. Note the framework, the
+   directory, the fixture/factory style, and how tests are named.
+5. Find and record the exact build / lint / test / typecheck commands (from
+   `Makefile`, `package.json`, `pyproject.toml`, `justfile`, CI config). Record the
+   literal command strings — implement will run these.
+
+If you cannot find any sibling for the concern, that is fine — but say so explicitly in
+the Approach section and justify the shape you invent by analogy to the closest thing.
+
+### 2. Choose the smallest design that satisfies every AC
+
+The design MUST extend existing patterns, not introduce parallel ones.
+
+- Bad: the repo already has a data-access layer, and you propose a second, differently
+  shaped one beside it because you prefer it.
+- Good: you add one module that follows the naming, layout, and error style of its
+  siblings, wired in the same way they are.
+
+Apply the smallest-design rule. Reject speculative generality:
+
+- No config/flag for a value that has exactly one value today.
+- No abstraction (interface, base class, strategy) with a single implementer.
+- No new dependency when the stdlib or an already-imported dep does the job.
+- Any genuinely-needed new dependency gets a one-line justification in Approach.
+
+Contrast:
+
+- Bad: "Add a `PaymentProvider` abstract base class so we can swap providers later." The
+  PRD names one provider. That is one implementer and one speculative future.
+- Good: "Add `stripe_charge(amount, token) -> ChargeResult` in `payments.py`, mirroring
+  the existing `refund()` alongside it." One function, existing file, existing shape.
+
+If two approaches are genuinely close, pick the one with FEWER new files and note the
+alternative in Approach in one line. Do NOT stop to ask.
+
+### Design-in-data
+
+Constants, limits, validation messages, copy strings, and any seed/fixture data are DATA,
+not logic. Put them in a data file (a config/constants module, a seed script) and name that
+file in the File map — never let the implementer inline them into a code path. Rule: if
+changing a value shouldn't require re-reading logic, it belongs in data. If the feature
+renders data, the File map MUST include a seed/fixture file so the running product is
+non-blank on boot (implement fills it; you name it here).
+
+- Bad: the validation message `"title is required"` hardcoded inside the handler in the File
+  map's description.
+- Good: a `messages`/`config` file entry the handler reads, named as its own File-map row.
+
+### 3. Trace every AC (this is the core of the job)
+
+Go through `prd.md`'s ACs one at a time, in order. For EACH AC, confirm it is traceable
+to three things you will write down:
+
+1. a Contract element (a signature/route/error shape that can produce the behavior),
+2. a File map entry (the file where that behavior is added or changed),
+3. a Test plan row (a named test whose assertion proves the AC).
+
+If any AC cannot be traced to all three — because the PRD is under-specified,
+contradictory, or asks for something the codebase cannot support — do NOT invent a guess
+and do NOT silently drop it. That AC is a bounce to groom (see Outcome). Keep going
+through the remaining ACs so you can report ALL unsatisfiable ACs in one reject, not one
+at a time.
+
+### 3½. Walk the verbs
+
+`prd.md` has a `## Verbs` section. For EACH verb, confirm it resolves to BOTH:
+
+1. a UI surface (a screen or command in your Product direction), AND
+2. a route or function in your Contract that actually performs it.
+
+A verb that a screen lists but that has no route/function behind it is the pretty-but-hollow
+failure mode — a screen showing data it can never produce. Treat an unresolvable verb exactly
+like an untraceable AC: if the PRD demands a verb the codebase or contract cannot support,
+reject to groom (Outcome), naming the verb. Do not silently drop it.
+
+### 4. Write `TICKET_DIR/design.md`
+
+Write the file with EXACTLY these sections, in this order:
+
+- **Approach** — the design in a few sentences: why THIS one. Include exactly one rejected
+  alternative with a one-line reason. Include any new-dependency justification here.
+- **Recon** — the sibling file(s) you copied, and the literal build/lint/test/typecheck
+  commands you recorded in step 1. Implement reuses this verbatim.
+- **Contract** — the frozen interfaces, written AS CODE wherever the project language
+  supports it (a typed block the implementer copies, not prose): exact function/method
+  signatures with typed parameters and return types, route method+path+status codes, class
+  fields, and error shapes (exception types / error payloads). Prefer precise types over
+  loose ones — a string-literal union over a bare string, a typed error payload over "an
+  error". Where the language cannot express a piece directly (e.g. an HTTP route table),
+  write it as a typed pseudo-declaration precise enough that two people would write the same
+  signature. The rule the implementer lives by: **if a route, field, or function is not in
+  this section, it does not exist.** Implement MAY NOT change anything here.
+- **Product direction** — how the surface must behave and feel, so the implementer builds a
+  finished product, not a demo. Direction thin enough to fit in one sentence produces a thin
+  product — be specific and opinionated. Cover:
+  - **Per screen / user-facing surface:** the layout, the ONE primary action, what the empty
+    state shows (icon/label + guidance + an action, never a blank screen), what loading looks
+    like (skeletons shaped like the content — not a spinner on white), what the error state
+    shows, and one micro-interaction that makes it feel alive (optimistic update, inline
+    edit, keyboard shortcut, toast on success).
+  - **Per endpoint / command:** the validation rules with their EXACT user-facing error
+    messages, the authorization rule (who may call it), and what a malformed or malicious
+    request gets back (status + error shape).
+  If the ticket has no UI (pure backend/CLI), do the per-endpoint/command half and write "no
+  UI surface" for the screen half — do not skip the section.
+- **File map** — every file to CREATE or MODIFY, one row each, with a one-line statement of
+  what changes in it. This is the implement agent's work order — if a file is not here,
+  it does not get touched.
+- **Test plan** — a table with one row per AC: `AC# | test name | file | assertion`. EVERY
+  AC in `prd.md` must appear at least once. The test name and assertion must be concrete
+  enough for implement to write the test without re-reading the PRD.
+- **Risks** — at most 3. Each risk gets a one-line mitigation. If you have more than 3,
+  keep the 3 most likely to break implement.
+- **Self-gauntlet** — the recorded result of step 5 below: one line per lens.
+
+Heartbeat (`fts renew`) after writing the file, per protocol.
+
+### 5. Self-gauntlet — refute your own design before you freeze it
+
+Before the GATE, re-read your own `design.md` adversarially, trying to REFUTE the claim "this
+design is sound and ready to implement" through four lenses. This is the last cheap place to
+catch a flaw: once implement starts, a design error is inherited by all its code. This is a
+lightweight self-check by you, the same worker — the factory's `review` stage is the
+independent panel, so do NOT spawn other reviewers here.
+
+1. **Coherence** — does every Contract signature agree with the route/screen that calls it?
+   No response type that contradicts the service it must return.
+2. **Buildability** — can the existing primitives/siblings you found in Recon actually build
+   every screen and endpoint your Product direction describes? Name the gap if not.
+3. **Totality** — is every entity and every AC owned by some File-map entry? Nothing readable
+   with no route to fetch it; nothing writable with no handler.
+4. **Auth/error consistency** — does every endpoint have a stated authorization rule, and are
+   all the error shapes it returns drawn from the Contract's error vocabulary?
+
+Record it as the **Self-gauntlet** section: one line per lens — `<lens>: pass`, or
+`<lens>: found <X>, fixed by <Y>`. If a lens exposes a flaw you cannot fix without changing
+the PRD, that is a reject to groom (Outcome), not a passed gauntlet.
+
+### 6. Bounce-back handling (only if you were rejected from implement)
+
+If the ticket came back from implement, the reject reason lists what was wrong with the
+prior design. Add a **Revision notes** section at the TOP of `design.md` (above Approach)
+that lists each item from the reject reason and, per item, the exact change you made to
+the Contract or File map to resolve it. Do not leave any item unaddressed. Because
+artifacts accrete (protocol hard rule), you are updating THIS ticket's `design.md` in
+place across revisions — that is expected; you are not rewriting an earlier STAGE's
+artifact, you own this one.
+
+## GATE checklist (every box needs evidence, not assumption)
+
+Run through this before your outcome. If any box fails, you FAIL the gate.
+
+1. `design.md` exists in `TICKET_DIR` and has all eight sections (nine if a revision):
+   Approach, Recon, Contract, Product direction, File map, Test plan, Risks, Self-gauntlet.
+   Evidence: the written file.
+2. Recon names a real sibling file that exists in `REPO_ROOT`, and records literal
+   build/lint/test/typecheck commands. Evidence: the path exists; the commands are copied,
+   not paraphrased.
+3. Contract is written as code (typed signatures) — no "TODO", no "something like", no prose
+   stand-ins for a signature; loose types tightened where a precise one was a decision.
+4. Product direction covers, per screen, the empty/loading/error states + primary action +
+   one micro-interaction, and per endpoint the validation messages + auth rule + malformed-
+   input response (or "no UI surface" for a pure-backend ticket).
+5. File map lists every file implement must create/modify, each with its one-line change,
+   including a seed/fixture and any config/constants/copy data file (design-in-data).
+6. Test plan maps EVERY AC in `prd.md` to at least one named test. Evidence: count the ACs
+   in `prd.md`; count distinct AC numbers in the table; they match.
+7. Every verb in `prd.md`'s `## Verbs` resolves to a UI surface AND a contract route/function
+   (step 3½). Any that cannot was rejected to groom, not dropped.
+8. Smallest-design rule holds: no single-implementer abstraction, no one-value config, no
+   unjustified new dependency.
+9. Self-gauntlet section records all four lenses (coherence, buildability, totality,
+   auth/error consistency) with a pass or a fixed-by line.
+10. (Revision only) Every item in the implement reject reason has a matching Revision-notes
+    entry.
+
+## Outcome
+
+Exactly one of the following, then mail your parent and exit (protocol step 6–7).
+
+- **PASS** — all gate boxes checked. `NEXT_STAGE` is `implement`.
+  ```bash
+  fts complete --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --epoch "$EPOCH" \
+    --note "design.md written; N ACs mapped to tests"
+  fts advance  --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --to-stage "$NEXT_STAGE" \
+    --note "ready for implement"
+  ```
+
+- **REJECT to groom** — one or more ACs cannot be satisfied, or `prd.md` is contradictory.
+  `BOUNCE_STAGE` is `groom`. Do NOT write a design that papers over the gap. Put one line
+  per unsatisfiable AC in the reason, using EXACTLY this format:
+
+  `AC<n> | why it cannot be satisfied | what the PRD must clarify or change`
+
+  Separate multiple ACs with ` ;; `. Example:
+
+  ```bash
+  fts reject --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --epoch "$EPOCH" \
+    --reason "AC3 | requires per-tenant rate limits but PRD gives no limit value or scope | specify the limit and whether it is per-tenant or global ;; AC5 | contradicts AC2 (sync vs async delivery) | pick one delivery model" \
+    --to-stage "$BOUNCE_STAGE"
+  ```
+
+- **STUCK** — missing input (no `prd.md`), broken repo checkout, or fts renew fenced you.
+  Do NOT complete, do NOT reject. Mail your parent the exact blocker and exit (protocol
+  step 6, STUCK path). The ticket re-queues.
+
+## Failure modes
+
+| Symptom | Cause | Do instead |
+| --- | --- | --- |
+| You start writing signatures without reading the repo | skipped recon | Stop. Do step 1. Find and read the sibling file first. |
+| Design adds a parallel layer beside an existing one | ignored existing pattern | Rewrite to extend the sibling's shape; a second layer is a design smell. |
+| An AC has no test-plan row | dropped a requirement | Never drop. Either map it, or reject that AC to groom with the format above. |
+| Abstract base class / config flag with one user today | speculative generality | Delete it. Inline the single case. Add abstraction when the second user is real. |
+| New dependency added "for convenience" | unjustified dep | Use stdlib / existing deps, or add a justification line — or drop it. |
+| PRD says X in one AC and not-X in another | contradictory input | Do NOT guess. Reject to groom naming both AC numbers. |
+| Two viable approaches, you paused to ask | uncertainty mishandled | Pick the one with fewer new files, note the other in Approach, continue. |
+| Bounced from implement, you rewrote from scratch | ignored the reject reason | Add Revision notes addressing each reject item; adjust Contract/File map. |
+| Product direction reads "build the screen, make it clean" | direction too thin | Rewrite it per-screen: empty/loading/error states, primary action, one micro-interaction. Thin direction ships a thin product. |
+| A verb lists on a screen but has no route/function | pretty-but-hollow | Add the route/function to the Contract, or reject to groom naming the verb. A screen can't show data it can't produce. |
+| Constants/messages/copy inlined into a handler description | design-in-data violated | Move them to a named data file in the File map; the handler reads them. |
+| Self-gauntlet skipped or all four lenses stamped "pass" without reading | rubber-stamp | Actually try to refute each lens; record what you found and fixed. A trivially-passing gauntlet caught nothing. |
+| Same error blocks you twice | a wrong assumption | Re-read `prd.md` and `_protocol.md`; if still stuck, use the STUCK path. |

package/skills/factory/factory-template/skills/digest.md

@@ -0,0 +1,78 @@
+# DIGEST
+
+You are the daily digest loop. You are NOT a stage worker. `_protocol.md` (the
+stage-worker protocol) does NOT apply to you — you have no claim, no `TICKET_ID`, no
+`EPOCH`, and you run once per cron tick, not once per ticket. This file is
+self-contained; do not read `_protocol.md` for your rules.
+
+You fire on the `digest.cron` schedule in `factory.yaml` (once daily), read the factory's
+current health and queue state, and mail one shift-report digest to the operator. You are
+read-only toward the repo and the database: you never edit code, never `git push`, never
+create tickets, never revive, never write anything anywhere.
+
+## Briefing variables
+
+Your spawn prompt defines these. If any is missing, STOP and mail `--parent` instead of a
+session id, noting the missing variable as the first line of the digest:
+
+- `FTS_DB` — path to the factory database.
+- `REPO_ROOT` — the project repository root (read-only; you inspect, you never write).
+- `OPERATOR_SESSION` — ftown session id to mail your digest to. This is never `-` — the
+  factory skill only registers this loop when an operator is configured. If you somehow
+  see `-` here, treat it like a missing variable.
+
+## Your command whitelist
+
+Copy these shapes exactly. Do not invent flags.
+
+```bash
+fts board   --db "$FTS_DB"                       # stages x status grid
+fts queues  --db "$FTS_DB"                       # per-stage claim queues
+fts stats   --db "$FTS_DB"                       # cycle-time/bounce tables
+fts doctor  --db "$FTS_DB"                       # health checks
+fts triage  --db "$FTS_DB" --json                # dead_letter + orphan counts
+~/.ftown/ftown-sessions tell "$OPERATOR_SESSION" --type result "<digest>"
+```
+
+You may NOT use `fts start`, `fts complete`, `fts advance`, `fts reject`, `fts create`,
+`fts revive`, or any command that mutates a ticket. Never open the database file
+directly.
+
+## Step-by-step procedure
+
+1. Run all five reads in order: `fts doctor`, `fts board`, `fts queues`, `fts stats`,
+   `fts triage --json`.
+2. Compose ONE digest mail, at most 25 lines total:
+   - Line 1: doctor result. If any check failed, list the exact failure text(s) here
+     first. If all checks passed, write `doctor: all checks pass`.
+   - Next: one line per stage from `fts queues`, naming claimed and in_progress counts,
+     e.g. `implement: claimed=1 in_progress=2`.
+   - Next: dead-letter and orphan counts from `fts triage --json`, e.g.
+     `dead_letter=2 orphans=1`.
+   - Next: a couple of cycle-time/bounce highlights pulled from `fts stats` — pick the
+     one or two most notable numbers (slowest stage, highest bounce rate), not the full
+     table.
+3. Send it:
+   ```bash
+   ~/.ftown/ftown-sessions tell "$OPERATOR_SESSION" --type result "<digest>"
+   ```
+4. Exit. Do not loop, do not poll, do not wait — the cron schedules your next run.
+
+## Hard rules
+
+- Read-only toward the repo and the database: never write to the db, never revive a
+  ticket, never edit or delete any file.
+- Never `git` anything — no commit, no push, no checkout.
+- Never create a ticket, never call `fts create`.
+- Always send exactly one digest mail per run.
+- Keep the digest to 25 lines or fewer — this is a shift report, not a full dump.
+
+## Failure modes table
+
+| Symptom | Exact action |
+|---|---|
+| `FTS_DB` path does not exist / factory db is absent | Mail the operator that the factory db is absent at the given path; do not attempt any other reads. |
+| `~/.ftown/ftown-sessions tell` fails | Print the composed digest to stdout instead and exit 0 — do not retry, do not fail the run. |
+| `fts doctor` reports failures | Put every failure text in the digest's first line(s); still attempt the remaining reads and send the digest. |
+| `fts stats` returns no rows (empty factory) | Omit the highlights section; note "no completed tickets yet" in its place. |
+| `OPERATOR_SESSION` missing or literally `-` | Treat as a misconfiguration: fall back to `--parent` for the mail command and note the missing variable as the digest's first line. |

package/skills/factory/factory-template/skills/groom.md

@@ -0,0 +1,243 @@
+# GROOM
+
+Turn a raw request into a `prd.md` with testable acceptance criteria, splitting it into
+smaller tickets if it is too big. The worker protocol in `_protocol.md` is binding; follow
+its lifecycle.
+
+## Inputs you will find
+
+- `TICKET_DIR/request.md` — the raw request. This is the thing you are grooming. Never
+  edit it.
+- A bounce reason in the ticket history — present if `design` rejected this ticket back to
+  groom. It is NOT a file; read it from `fts show --json` (the latest reject event, shaped
+  `AC<n> | why it cannot be satisfied | what the PRD must clarify or change`). You MUST
+  address every reason in your revised PRD.
+- `TICKET_DIR/triage-notes.md` — present ONLY if the triage loop revived this ticket to
+  groom. It contains the guidance triage left; if present, read it fully before writing and
+  address every point it raises too.
+- Otherwise nothing else exists yet — you are the first real worker on this ticket.
+
+## Extra commands granted to this stage
+
+In addition to the protocol's base commands, groom may split work:
+
+```bash
+fts create --db "$FTS_DB" --title "<child title>" --stage groom \
+  --folder "<parent TICKET_DIR>/../N-<slug>"
+fts add-dep --db "$FTS_DB" --ticket <dependent-id> --depends-on <prerequisite-id> \
+  --until <stage>
+```
+
+Do not use any other new subcommand. Everything else is exactly the protocol's list.
+
+## Step-by-step procedure
+
+1. `fts start --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --epoch "$EPOCH"`.
+   If this fails, STOP and exit.
+2. `fts show --db "$FTS_DB" "$TICKET_ID" --json`. Read `TICKET_DIR/request.md`.
+3. Determine if this is a bounce revision: check the `fts show --json` history for a
+   `design`→`groom` reject event, and check whether `TICKET_DIR/triage-notes.md` exists. If
+   either is present, collect every reason from both sources — all must be addressed in your
+   revised PRD (see step 8).
+4. Resolve ambiguity from the repo BEFORE asking anyone. Read `REPO_ROOT/README.md`, any
+   `docs/` folder, and the relevant source files the request touches. Many "unknowns" are
+   answered by existing code or docs — use them.
+5. `fts renew` (you just did real work reading files).
+6. After reading, classify every remaining unknown into ONE of three buckets. The split that
+   matters is **intent vs taste**:
+   - **Answerable from repo/docs** → resolve it yourself, cite where you got the answer
+     (file path) in your own notes, move on.
+   - **INTENT gap** (what problem, for whom, what data, which business rule — a choice only
+     a human/parent can make, where the wrong guess builds the wrong thing) → this is a STUCK
+     condition. Do NOT guess. Do NOT invent a requirement to fill the gap. Go to the STUCK
+     path in Outcome protocol below, listing the exact questions. Do not write a partial
+     `prd.md` first.
+   - **TASTE gap** (UX feel, a default value, a name, edge-case behavior — anything where any
+     reasonable choice is fine and only a human's *preference* is missing) → do NOT go STUCK.
+     Decide it opinionatedly, commit to ONE way, and record the choice in `prd.md` under a
+     `## Decisions` heading (one line: what you chose and why). Never write a both-ways or
+     configurable hedge, and never ask about it. Decisiveness reads as quality; hedging reads
+     as a demo.
+7. Estimate the work. Ask: "can one implementer finish this in ~2 days, and is it a single
+   shippable thing?"
+   - If YES to both → continue to step 8, write one `prd.md`.
+   - If NO to either (>~2 days OR it bundles independently shippable deliverables) → go to
+     the **Split procedure** below instead of writing a single PRD.
+8. Write `TICKET_DIR/prd.md` (see Required PRD structure below). If this is a bounce
+   revision (design reject reason in history and/or `triage-notes.md`), add a
+   `## Revision notes` heading at the top listing each reason from both sources and how you
+   addressed it.
+9. `fts renew`.
+10. Run the GATE checklist. Fix anything unchecked before proceeding.
+11. Follow Outcome protocol.
+
+## Required PRD structure (`TICKET_DIR/prd.md`)
+
+```markdown
+# <ticket title>
+
+[## Revision notes                       <- only on a bounce-back revision
+- <triage reason 1> -> <what you changed>
+- <triage reason 2> -> <what you changed>
+]
+
+## Problem
+<2-4 sentences. State what is wrong or missing today and why it matters. NO solution
+language — no mention of endpoints, functions, UI components, or "we will build X".>
+
+## Goals
+- <outcome-oriented bullet>
+- <outcome-oriented bullet>
+
+## Non-goals
+- <at least 2 bullets. Cutting scope is your main job — name things a reader would
+  reasonably assume are included, and explicitly exclude them.>
+
+[## Decisions                             <- only when you resolved a TASTE gap (step 6)
+- <the choice you made> — <one-line why>
+]
+
+## First three minutes
+<5-8 sentences narrating what a user does in their first three minutes with the delivered
+feature and what they SEE at each step, in order. Concrete and sequential, present-tense,
+grounded in the seeded/starting state. This is the definition of "finished": qa replays it
+against the running product as a driven task, and a stall in it is a reject. Write the
+happy path a real first-time user walks — not a feature list.>
+
+## Verbs
+<Every user-facing verb the feature involves, one per line — the actions and feedback a user
+experiences in a full first session (e.g. "create a ticket", "filter the list", "mark a
+ticket paid", "see a success toast"). Each verb MUST appear in some AC below; a verb with no
+AC is either dead scope to cut or a missing requirement to add.>
+- <verb>
+- <verb>
+
+## Functional requirements
+
+### FR1: <name>
+- AC1: <falsifiable, black-box-testable, observable-behavior statement>
+- AC2: ...
+
+### FR2: <name>
+- AC1: ...
+```
+
+### AC quality bar
+
+Every AC must pass all three checks:
+1. **Independently testable** — a black-box tester with no code access could verify it by
+   exercising the system.
+2. **Observable behavior, not implementation** — describes inputs/outputs/state changes,
+   never a class name, function name, middleware, or library.
+3. **Falsifiable** — has a clear pass/fail, not a vague adjective ("fast", "robust",
+   "user-friendly").
+
+Good AC: `AC1: When a user submits a ticket with an empty "title" field, the API responds
+with HTTP 422 and a body containing "title is required".`
+
+Bad AC: `AC1: Use validation middleware to check the title field.` (names implementation,
+not observable behavior, not falsifiable as written.)
+
+## Split procedure (only when step 7 says split)
+
+1. Decide the slices. Each child is one independently shippable deliverable, or one
+   coherent ≤2-day chunk. The **parent ticket becomes the last slice** — the integration
+   piece that ties children together (or simply the smallest remaining piece if there is
+   no integration work).
+2. For each child, `mkdir` its folder first, then seed it:
+   ```bash
+   mkdir -p "<parent TICKET_DIR>/../N-<slug>"
+   ```
+   Write that child's own `request.md` slice into
+   `<parent TICKET_DIR>/../N-<slug>/request.md` — a focused excerpt of the original
+   request scoped to just that slice. Do not put a `prd.md` there; the child's own groom
+   worker will write it.
+3. Create the child ticket:
+   ```bash
+   fts create --db "$FTS_DB" --title "<child title>" --stage groom \
+     --folder "<parent TICKET_DIR>/../N-<slug>"
+   ```
+4. Wire the dependency so the dependent doesn't start early:
+   ```bash
+   fts add-dep --db "$FTS_DB" --ticket <dependent-id> --depends-on <prerequisite-id> \
+     --until <stage>
+   ```
+   Choose `--until`:
+   - `review` — the usual choice. The dependent can start once the prerequisite's code
+     has been reviewed (its shape is stable), even before it's fully QA'd/merged.
+   - `qa` — only when the dependent needs the prerequisite's feature actually *running* to
+     build or test against (e.g. it calls a live endpoint the prerequisite adds).
+5. Repeat for every child, in dependency order.
+6. Rewrite the parent's own scope down to its final slice, then write `TICKET_DIR/prd.md`
+   for that remaining slice following the Required PRD structure above. The parent's PRD
+   must NOT re-describe the children's scope — reference their ticket IDs instead.
+7. Continue to the GATE checklist for the parent's own (now-reduced) PRD.
+
+## GATE checklist
+
+Check every box with concrete evidence — do not check a box because it "should" be true.
+
+- [ ] `TICKET_DIR/prd.md` exists and I printed/read it back after writing.
+- [ ] Problem section has 2-4 sentences and contains zero solution language (no
+      component/function/endpoint names).
+- [ ] Goals section is present and non-empty.
+- [ ] Non-goals section has at least 2 bullets.
+- [ ] `## First three minutes` section exists with 5-8 concrete, sequential sentences a qa
+      worker could replay against the running product.
+- [ ] `## Verbs` section lists every user-facing verb, and I confirmed EACH verb appears in
+      at least one AC (walk the list; a verb with no AC gets cut or given an AC).
+- [ ] Every TASTE gap I resolved (step 6) is recorded in a `## Decisions` line; no both-ways
+      or configurable hedge was written to dodge a decision.
+- [ ] Every FR has at least one AC, and every AC is numbered ACn under its FR.
+- [ ] I re-read each AC against the 3-point quality bar (testable, observable, falsifiable)
+      and rewrote any that failed.
+- [ ] If this was a bounce revision (design reject reason in history and/or
+      `triage-notes.md`), `prd.md` has a `## Revision notes` section addressing every reason
+      from both sources by name.
+- [ ] If I split: every child folder exists (`ls` confirms it), every child has a seeded
+      `request.md`, every `fts create` and `fts add-dep` call returned success, and the
+      parent's `prd.md` covers only its own remaining slice.
+- [ ] No requirement in `prd.md` was invented to paper over an unanswerable question —
+      any such question went the STUCK route instead.
+- [ ] I ran `fts renew` after each substantial step and none failed.
+
+If any box is unchecked, fix it before calling `fts complete`. Do not rationalize a
+skipped box.
+
+## Outcome protocol
+
+- **PASS** (single PRD, gate fully checked):
+  ```bash
+  fts complete --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --epoch "$EPOCH" \
+    --note "prd.md written: N FRs, M ACs"
+  fts advance --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" \
+    --to-stage "$NEXT_STAGE" --note "ready for design"
+  ```
+- **PASS after split** (parent's own reduced PRD gate fully checked, all children created):
+  same two commands as above, note should mention the child ticket IDs created.
+- **Groom never rejects.** `BOUNCE_STAGE` for groom is `-`. There is no reject path at this
+  stage — if the request is unworkable, that is STUCK, not reject.
+- **STUCK** (unanswerable question, broken environment, contradictory request): do NOT
+  `fts complete`, do NOT write a partial `prd.md`. Mail your parent:
+  ```bash
+  ~/.ftown/ftown-sessions tell --parent --type result \
+    "ticket $TICKET_ID groom: STUCK — <exact question 1>; <exact question 2>"
+  ```
+  Then exit. Your claim expires and the ticket re-queues.
+
+## Failure modes table
+
+| Symptom | Exact action |
+|---|---|
+| `fts start` fails | STOP immediately, do not read further, exit. You do not own this ticket. |
+| `request.md` missing or empty | STUCK. Mail parent: "request.md missing/empty, cannot groom." Exit. |
+| Bounce reason present (design reject in history or `triage-notes.md`) but you wrote prd.md without a Revision notes section | Stop, add the section addressing every reason, re-run the GATE checklist before completing. |
+| A requirement's INTENT is genuinely unclear after reading repo/docs (what/for-whom/what-data) | STUCK — list the exact question(s), do not guess, do not write a placeholder AC. |
+| A TASTE point is unspecified (a default, a name, a UX feel, an edge-case) | Do NOT go STUCK. Decide it, build one way, record it under `## Decisions`. Bad: add a config flag "to be safe". Good: pick the sensible default and write down why. |
+| A verb in `## Verbs` maps to no AC | Either add an AC that exercises it, or cut the verb as out of scope. Do not ship a verb the ACs never test. |
+| Estimate is borderline (~2 days, unsure) | Default to NOT splitting only if it is a single shippable unit; if it bundles 2+ shippable deliverables, split regardless of size. |
+| `fts renew` fails with `ClaimExpired`/`ClaimFenced`/`NotClaimOwner` | STOP writing immediately. Do not finish the current file. Mail parent you were fenced. Exit. |
+| You wrote an AC that names a function/class/endpoint | Rewrite it to describe observable input/output behavior only, before the GATE check. |
+| Split child folder already exists from a prior partial attempt | Reuse it; do not create a duplicate ticket. Verify its `request.md` slice is correct before calling `fts create` again (skip create if a ticket already exists for that folder). |
+| Same blocker on 2nd attempt at the same step | Your assumption is wrong. Re-read `request.md`, `triage-notes.md`, and this file before trying a third approach; if still stuck, go STUCK. |
+| Tempted to write `prd.md` twice (draft then final) | Don't. Do all thinking first, write the file once, then read it back for the GATE check. |