ftown-bridge 0.19.0 → 0.19.2

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

@@ -0,0 +1,316 @@
+# IMPLEMENT stage skill
+
+Purpose: turn the frozen design into working, tested code on a ticket branch, one
+Test-plan row at a time, using strict TDD. You are the IMPLEMENT worker.
+
+**The Worker Protocol (`_protocol.md`) is binding. Read it first. This skill only adds
+detail; it never overrides the protocol.** You come after `design` and before `review`.
+Your `NEXT_STAGE` is `review`. Your `BOUNCE_STAGE` is `design`. You may run on a
+codex-class harness, so follow every command literally and do not improvise.
+
+---
+
+## 1. Inputs
+
+Read these before touching code. They live in `TICKET_DIR`.
+
+- `prd.md` — what the ticket must achieve, in product terms. Background only.
+- `design.md` — your work order. It has three parts that mean different things to you:
+  - **Contract** (signatures, types, error shapes, public API). **IMMUTABLE for you.**
+    You implement it exactly. If it is wrong, you BOUNCE (see step 8). You never edit it.
+  - **File map** — the exact list of files you may create or change. This is your scope.
+    Touch nothing outside it except those files' own test files.
+  - **Test plan** — the ordered list of tests you must write. One row = one TDD cycle.
+- If you arrived here from a bounce (`review` or `qa`), the reject reason lines are in the
+  `fts show --json` history. For a `review` bounce, `TICKET_DIR/review.md` also holds the
+  full findings; for a `qa` bounce, `TICKET_DIR/qa-report.md` holds the failing checks.
+  Treat the reject lines as an additional, mandatory work order (see step 9).
+
+If any of prd.md or design.md is missing, or design.md has no File map or no Test plan:
+that is STUCK. Follow the protocol STUCK path (mail parent, exit). Do not guess.
+
+---
+
+## 2. Start and set variables
+
+1. `fts start` per the protocol. If it fails, STOP and exit — you do not own this ticket.
+2. Read context: `fts show --db "$FTS_DB" "$TICKET_ID" --json`, then read the artifacts above.
+
+---
+
+## 3. Create your isolated worktree
+
+ALL work happens inside a dedicated git worktree on branch `ticket/$TICKET_ID`.
+**Never commit to `main`.** Run exactly:
+
+```bash
+git -C "$REPO_ROOT" worktree add "$REPO_ROOT/.ffactory/worktrees/$TICKET_ID" -b "ticket/$TICKET_ID" main 2>/dev/null \
+  || git -C "$REPO_ROOT" worktree add "$REPO_ROOT/.ffactory/worktrees/$TICKET_ID" "ticket/$TICKET_ID"
+```
+
+The first form creates the branch fresh. The second form runs only after a bounce, when
+the branch already exists, and resumes it. Then set your working directory:
+
+```bash
+WORK="$REPO_ROOT/.ffactory/worktrees/$TICKET_ID"
+cd "$WORK"
+```
+
+Every `git`, test, lint, and typecheck command from now on runs inside `$WORK`.
+**Leave the worktree in place when you exit.** The `review` stage needs it. Do not remove
+it, do not `git worktree remove`.
+
+---
+
+## 4. Discover the project gates ONCE
+
+You must know the exact commands to run tests, lint, and typecheck. Find them one time,
+at the start, and write them down.
+
+1. If `design.md` already lists the test / lint / typecheck commands, reuse those verbatim.
+2. Otherwise inspect, in this order, whichever exist: `pyproject.toml`, `package.json`
+   (scripts), `Makefile`, `justfile`, `.github/workflows/*.yml`, `tox.ini`, `noxfile.py`.
+3. Record the exact commands in `TICKET_DIR/implementation-notes.md` under a `Gates`
+   heading. Example rows: `test: uv run pytest`, `test-one: uv run pytest <path>::<name>`,
+   `lint: uv run ruff check .`, `typecheck: uv run mypy --strict .`.
+
+If you cannot find how to run tests at all, that is STUCK. Do not invent a command.
+
+---
+
+## 5. The TDD loop — one Test-plan row at a time
+
+Do the Test-plan rows in order. For EACH row, run this exact cycle. Never skip a step,
+never batch rows together.
+
+1. **Write the one named failing test** for this row, in its test file, asserting the
+   observable behavior the AC describes.
+2. **Run only that test. Confirm it FAILS for the RIGHT reason** — a real assertion
+   failure, not an import error, syntax error, or "file not found". If it fails for the
+   wrong reason, fix the test scaffolding until the failure is a genuine assertion, THEN
+   continue. A test that errors instead of asserting proves nothing.
+3. **Write the smallest implementation** that makes that test pass. No extra features,
+   no speculative code, no "while I'm here" helpers.
+4. **Run that test again. Confirm it is GREEN.**
+5. **Run the whole affected test file** (not just the one test) to confirm you broke
+   nothing next to it.
+6. **Commit** just this cycle's change:
+
+   ```bash
+   git add -A && git commit -m "feat(ticket/$TICKET_ID): <what this test now covers>"
+   ```
+
+7. **Heartbeat:** `fts renew --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --epoch "$EPOCH"`
+   after EVERY cycle. If renew fails (`ClaimExpired`/`ClaimFenced`/`NotClaimOwner`), STOP
+   immediately per the protocol — mail parent, exit. Do not commit anything more.
+
+Repeat until every Test-plan row is done.
+
+### Forbidden in the loop (these fail review — do not do them)
+
+- Writing implementation code before its test exists.
+- Weakening, deleting, `skip`-ing, or `xfail`-ing a failing test to make the suite green.
+- Asserting on implementation details (private internals, call counts, log strings) instead
+  of the AC's observable behavior.
+- One giant commit at the end. Commit per cycle.
+- Adding files, refactors, renames, or "cleanups" not required by the current row.
+
+Contrast:
+
+- RIGHT: `assert charge(cart) == Money("12.00", "USD")` — checks the AC's stated result.
+- WRONG: `assert cart._apply_tax_called == 1` — checks internals; the AC never mentioned it.
+- RIGHT: test file has `def test_rejects_negative_amount(): with pytest.raises(ValueError): ...`
+- WRONG: deleting `test_rejects_negative_amount` because it is red, then shipping green.
+
+### The product bar — a finished product, not a demo
+
+The design's **Product direction** is a work order, not a suggestion. As you build each row,
+meet this bar:
+
+- **Zero stubs.** No `TODO`, no placeholder screen, no handler that returns fake or empty
+  data "for now". Every state the direction names is really built: an empty list shows the
+  designed empty state, a failed request shows the error state, an unauthorized caller gets
+  the specified rejection. If it renders, it renders finished.
+- **Seed data exists.** If the feature renders data, make sure the dev seed/fixture file the
+  design named in the File map actually contains realistic rows, so the feature is NON-BLANK
+  the moment the app boots. A blank first screen makes finished work look like a stub. Do not
+  invent a new seed mechanism — fill the one the File map points to.
+- **Data, not logic.** Put constants, limits, copy strings, and seed rows in the data file the
+  design named — never inline them into a code path.
+
+Contrast:
+
+- RIGHT: the empty ticket list renders the designed empty state ("No tickets yet — create
+  one"), and the seed file ships three demo tickets so the list is alive on first boot.
+- WRONG: the list handler returns `[]` with a `# TODO: real empty state` and no seed rows, so
+  the first screen is a blank panel.
+
+---
+
+## 6. Contract discipline (immutable)
+
+The design **Contract** — every signature, type, and error shape — is frozen. You match it
+exactly. You never silently change a name, argument, return type, or raised error to make
+your code easier.
+
+If the Contract is genuinely wrong or impossible to implement (contradicts itself, names a
+type that cannot exist, specifies an error that the language cannot raise there): STOP
+implementing and BOUNCE to design (step 8). Do not patch around it.
+
+---
+
+## 7. Scope discipline
+
+Touch ONLY files in the design **File map**, plus those files' own test files. Nothing else.
+
+- A tempting improvement in a neighboring file is FORBIDDEN. Not now, not "quickly".
+- If making this ticket work genuinely requires changing a file outside the File map, that
+  is a design gap → BOUNCE to design (step 8). Do not expand scope on your own authority.
+
+---
+
+## 8. When to bounce to design
+
+Bounce when the frozen input is wrong: an impossible Contract, or a required change outside
+the File map. Do NOT bounce for your own bugs or for tests you can make pass.
+
+Use the protocol `fts reject` with `--to-stage "$BOUNCE_STAGE"` and one of these exact
+reason formats (one line per problem):
+
+- Contract problem:
+  `CONTRACT | <the exact signature/type> | why it cannot work | smallest change that would`
+- Scope/file-map gap:
+  `SCOPE | <file needed but not in map> | why it is required | add it to the File map`
+
+Example:
+`CONTRACT | def parse(x: int) -> Date | int cannot carry a timezone the AC requires | take x: str (ISO-8601)`
+
+Before rejecting: verify the branch is committed clean so the partial work survives the
+bounce. Then reject, mail parent, exit.
+
+---
+
+## 9. Handling a bounce-back (from review or qa)
+
+If you resumed after a rejection, read the reject reason lines from the `fts show --json`
+history. They come in one of two shapes, depending on which stage bounced you:
+
+- From **review** (one line per finding):
+  ```
+  [blocker] file:line | problem | required fix
+  ```
+- From **qa** (one line per failing AC, lines separated by ` ;; `):
+  ```
+  AC<n> | repro: <command/steps> | expected: <...> | got: <...>
+  ```
+
+Address EVERY line. For a review `[blocker]`, make the required fix. For a qa failure, run
+the given repro to reproduce it, then fix the code so the expected result is produced. In
+both cases TDD still applies: first write or fix a test that captures the missed behavior
+(see it RED), then make it GREEN, then commit each fix on its own:
+
+```bash
+git commit -m "fix(ticket/$TICKET_ID): <what was fixed> (addresses <file:line or AC#>)"
+```
+
+**Minimal fix only.** Change exactly what the finding names — nothing more. Do NOT refactor,
+rename, reorganize, or "clean up while I'm here" during a bounce fix. A refactor in the fix
+phase reintroduces the very scope creep review just cleared, and risks breaking code that
+already passed. One finding, one focused fix, one commit.
+
+Do not fix things not listed. After all lines are addressed, rerun the full finish
+sequence (step 10) from the top. Then advance.
+
+---
+
+## 10. Finish sequence
+
+Run all of this inside `$WORK`. Do not skip a step.
+
+1. **Full test suite** — the `test` command from your notes. Must be fully green.
+2. **Lint** — the `lint` command. Must pass clean.
+3. **Typecheck** — the `typecheck` command. Must pass clean.
+4. Paste the summary line of each command's output into `implementation-notes.md`.
+5. **Self-review the whole diff:**
+
+   ```bash
+   git -C "$WORK" diff main...HEAD
+   ```
+
+   Remove any debug prints, commented-out code, `TODO` you introduced, `.only`/focused
+   tests, and stray/temp files. Confirm every changed file is inside the File map.
+6. **Write `TICKET_DIR/implementation-notes.md`** with: branch name (`ticket/$TICKET_ID`);
+   the Gates commands and their pasted output summaries; per-AC / per-Test-plan-row status
+   (done / how it is covered); and a Deviations line that is either `Deviations: none` or a
+   note that you bounced (you would not be finishing if you bounced).
+7. `fts renew` one last time.
+
+---
+
+## 11. GATE checklist — every box needs evidence, not assumption
+
+Do not advance until ALL are true. "Evidence" means you can point to the command output or
+file you just produced.
+
+- [ ] Work is in `$WORK` on branch `ticket/$TICKET_ID`; `main` has zero new commits from you.
+- [ ] Every Test-plan row has a corresponding test that was seen RED then GREEN.
+- [ ] No test was skipped, weakened, or deleted to pass.
+- [ ] Every assertion targets observable AC behavior, not internals.
+- [ ] Full test suite green (summary line pasted in notes).
+- [ ] Lint clean (summary line pasted in notes).
+- [ ] Typecheck clean (summary line pasted in notes).
+- [ ] Every changed file is inside the design File map (or its test file).
+- [ ] No stub shipped: no `TODO`/placeholder screen or handler; every empty/loading/error/
+      unauthorized state named in the design's Product direction is actually built.
+- [ ] If the feature renders data, the seed/fixture file has realistic rows so the running
+      product is non-blank on boot.
+- [ ] Contract implemented exactly as written — no silent deviation.
+- [ ] `git diff main...HEAD` has no debug prints, commented code, or stray files.
+- [ ] `implementation-notes.md` written with branch, gates+outputs, per-AC status, deviations.
+- [ ] Commits are per-cycle with `feat(ticket/$TICKET_ID): ...` messages, no giant commit.
+- [ ] If this was a bounce-back: every reject line addressed by its own commit.
+
+If any box cannot be checked honestly: do NOT advance. Fix it, or bounce (step 8), or take
+the STUCK path.
+
+---
+
+## 12. Outcome protocol
+
+Exactly one of:
+
+- **PASS** — all GATE boxes checked:
+  ```bash
+  fts complete --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --epoch "$EPOCH" --note "implemented; all gates green"
+  fts advance  --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --to-stage "$NEXT_STAGE" --note "ready for review on ticket/$TICKET_ID"
+  ```
+- **REJECT to design** — impossible Contract or needed file outside the File map. Use
+  `fts reject ... --to-stage "$BOUNCE_STAGE"` with a `CONTRACT|...` or `SCOPE|...` reason
+  line (step 8).
+- **STUCK** — missing input, unrunnable environment, contradictory requirements you cannot
+  turn into a bounce. Do NOT complete, do NOT reject. Mail parent the exact blocker, exit;
+  the claim expires and the ticket re-queues.
+
+Then mail the result summary and exit, per the protocol.
+
+**Never `git push`, never open a PR** — later stages do that. **Never run destructive git**
+(`reset --hard`, `push --force`, `branch -D`, `worktree remove`) outside your own branch,
+and never on `main`.
+
+---
+
+## 13. Failure modes
+
+| Symptom | Cause | Do this |
+|---|---|---|
+| Test fails with ImportError / SyntaxError, not an assertion | Test scaffolding wrong; not a real red | Fix scaffolding until failure is a genuine assertion, then continue the cycle |
+| Suite is red and you want it green fast | Temptation to skip/delete a test | FORBIDDEN. Fix the implementation, or bounce if the Contract is impossible |
+| Contract signature makes the AC impossible | Design error | BOUNCE with `CONTRACT \| ... ` (step 8). Do not patch around it |
+| You need to edit a file not in the File map | Scope gap in design | BOUNCE with `SCOPE \| ...` (step 8). Do not touch it silently |
+| `fts renew` returns ClaimExpired/Fenced/NotClaimOwner | You lost the claim | STOP now, write nothing more, mail parent, exit (protocol step 4) |
+| You committed to `main` | Wrong directory | Stop. You are not in `$WORK`. Do NOT amend main; take STUCK, mail parent |
+| Same error beats you twice | An assumption is wrong | Re-read design.md + this skill; do not retry a third time. If still stuck, STUCK path |
+| Can't find test/lint/typecheck command | No recorded gates | STUCK. Do not invent a command |
+| Tempted to add a nice refactor nearby | Scope creep | FORBIDDEN. Only File-map files, only what the current row needs |
+| Tempted to leave a `TODO`/placeholder screen or empty-data handler | Shipping a demo, not a product | Build the state the Product direction names; a stub fails review. Seed the data file so it is non-blank |
+| On a bounce, tempted to refactor while fixing the finding | Fix-phase scope creep | Minimal fix only — change exactly what the finding names, nothing else, one commit |

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

@@ -0,0 +1,220 @@
+# PR stage — verify, sync, and land the branch. Terminal stage of the pipeline.
+
+The worker protocol in `_protocol.md` is binding; follow its lifecycle. This skill only
+tells you what to do between `fts start` and your outcome command.
+
+Your job: confirm QA already passed, rebase the branch onto latest `main`, re-verify green,
+clean up commit history, push, and open the pull request. You do NOT write product code and
+you do NOT fix failing tests yourself — a red suite after rebase is a bounce to implement,
+not something to patch here. This stage is terminal: there is no next stage on success.
+`_protocol.md` forbids `git push` "unless your stage skill explicitly instructs it" — this
+skill IS that instruction, and it applies only because `factory.yaml` sets `allow_push: true`
+for the `pr` stage. If that flag is ever missing for this stage, treat push as forbidden and
+go STUCK.
+
+## Inputs
+
+- `TICKET_DIR/prd.md` — problem statement, goals, acceptance criteria (ACs). Source for the
+  PR body's Summary and AC checklist.
+- `TICKET_DIR/qa-report.md` — must exist; every AC row must be PASS. Your precondition.
+- `TICKET_DIR/implementation-notes.md` — contains the branch name (`ticket/$TICKET_ID`) and
+  the literal build/lint/test/typecheck commands. You run these commands verbatim; do not
+  guess them.
+- The worktree at `$REPO_ROOT/.ffactory/worktrees/$TICKET_ID` — your only writable checkout.
+  Do all git work there, never in `$REPO_ROOT` directly.
+
+## Procedure
+
+### 1. Precondition check
+
+1. Confirm `TICKET_DIR/qa-report.md` exists. If missing: STOP, go STUCK (see Outcome) —
+   the pipeline invariant that `pr` only runs after a passing `qa` was violated.
+2. Read every AC row in `qa-report.md`. If any row is not PASS: STOP, go STUCK with the
+   failing AC numbers in your blocker message. Do NOT push unverified work. Do NOT try to
+   fix it yourself — that is implement's job, and you have no bounce path for a bad
+   qa-report (a bad qa-report means qa itself misbehaved, which is a factory bug, not a
+   normal reject).
+3. Read `implementation-notes.md`. Extract the branch name and the exact test/lint/build
+   commands. `fts renew` after reading.
+
+### 2. Sync with main
+
+1. Inside the worktree:
+   ```bash
+   cd "$REPO_ROOT/.ffactory/worktrees/$TICKET_ID"
+   git fetch origin
+   git rebase origin/main
+   ```
+2. If the rebase completes with no conflicts, go to step 3.
+3. If the rebase stops on conflicts, classify EVERY conflicting file as trivial or
+   non-trivial. Do not average across files — one non-trivial file fails the whole rebase.
+   - **Trivial** (resolve and continue): lockfiles (`package-lock.json`, `uv.lock`,
+     `Cargo.lock`) — regenerate/accept the tool-generated version; import/require statement
+     reordering; two changes on adjacent-but-non-overlapping lines (e.g. main added a new
+     function at the end of a file, your branch edited a function earlier in the same
+     file). Example: main added `def new_helper():` at the bottom of `utils.py`; your
+     branch modified `def existing_helper():` near the top. Same file, no overlapping
+     logic — trivial.
+   - **Non-trivial** (abort): both sides changed the SAME logic — the same function body,
+     the same conditional, the same config key — with different intent. Example: main
+     changed the retry count in `fetch_with_retry()` from 3 to 5; your branch also changed
+     it, to 2, as part of the ticket's fix. That is a genuine semantic conflict; you cannot
+     safely guess which value is correct.
+   - For each trivial conflict: edit the file to the resolved content, `git add <file>`,
+     continue. `fts renew` after each resolved file.
+   - On the FIRST non-trivial conflict: `git rebase --abort` immediately. Do not attempt to
+     resolve it "your best guess" — that is implement's call, not yours. Go to the REJECT
+     outcome below.
+4. After a clean rebase (or after resolving only trivial conflicts), continue to step 3.
+   A green suite from BEFORE the rebase proves nothing now — the code has changed.
+
+### 3. Full verification (mandatory after every rebase, even a conflict-free one)
+
+1. Run every command recorded in `implementation-notes.md` (lint, typecheck, full test
+   suite, build) — the exact strings, not a subset.
+2. `fts renew` after the run.
+3. If ALL commands pass: continue to step 4.
+4. If ANY command fails: STOP. This is a REJECT to implement (see Outcome), NOT something
+   you patch. Do not push a broken rebase result under any circumstance.
+
+### 4. Commit hygiene
+
+1. Run `git log origin/main..HEAD --oneline` to see this branch's commits.
+2. If history is already a small number of coherent commits (roughly one per logical
+   change, clear messages) — continue to step 5.
+3. If history is messy (many "wip"/"fixup"/"address review" commits, or commits that don't
+   individually build): squash it.
+   ```bash
+   git reset --soft "$(git merge-base HEAD origin/main)"
+   git commit -m "feat(ticket/$TICKET_ID): <what this ticket does, one line>"
+   ```
+   Use `fix(ticket/$TICKET_ID): ...`, `test(ticket/$TICKET_ID): ...`, or
+   `chore(ticket/$TICKET_ID): ...` instead of `feat` if that better describes the change.
+   If the ticket genuinely spans distinct concerns (e.g. a schema migration plus the
+   feature that uses it), keep that as more than one commit — each still prefixed
+   `<type>(ticket/$TICKET_ID): ...`. Do not manufacture multiple commits when one suffices.
+4. `fts renew` after squashing.
+
+### 5. Push and open the PR
+
+1. Check whether a PR already exists for this branch (it may, from a prior `pr`-stage
+   attempt that got bounced and came back):
+   ```bash
+   gh pr view "ticket/$TICKET_ID" --json url,state 2>/dev/null
+   ```
+2. First push (no existing PR, no remote branch yet, or you did not rewrite history):
+   ```bash
+   git push -u origin "ticket/$TICKET_ID"
+   ```
+3. If you rewrote history (squash in step 4, or a rebase) AND a remote branch/PR already
+   exists, you MUST use lease-protected force push — never a bare `--force`:
+   ```bash
+   git push --force-with-lease -u origin "ticket/$TICKET_ID"
+   ```
+4. If push fails with an authentication error (`gh` unauthenticated, `Permission denied`,
+   `403`, credential prompt) — STOP, go STUCK with the exact error text. Humans own
+   credentials; never try to route around auth (no token hunting, no config edits).
+5. If no PR exists yet, create one:
+   ```bash
+   fts show --db "$FTS_DB" "$TICKET_ID" --json    # get the ticket title
+   gh pr create --title "<ticket title>" --base main --head "ticket/$TICKET_ID" --body "$(cat <<'EOF'
+   ## Summary
+   <4-6 lines from prd.md's problem statement and goals>
+
+   ## Acceptance criteria
+   - [x] AC1 — <criterion> (verified: qa-report.md, <evidence>)
+   - [x] AC2 — <criterion> (verified: qa-report.md, <evidence>)
+   <one line per AC, all checked, all from qa-report.md>
+
+   ## Testing
+   <the exact lint/typecheck/test/build commands run, and a one-line qa-report summary>
+
+   Factory ticket: TICKET_ID
+   EOF
+   )"
+   ```
+   Replace `TICKET_ID` in the final line with the literal `$TICKET_ID` value. Do NOT pass
+   `--reviewer`, do NOT run `gh pr merge`, do NOT enable auto-merge
+   (`gh pr merge --auto`). This stage opens the PR; it never merges it.
+6. `fts renew` after the PR exists.
+
+### 6. Write the artifact
+
+Write `TICKET_DIR/pr.md` with:
+- the PR URL,
+- the final commit SHA(s) on the branch (`git log origin/main..HEAD --oneline`),
+- rebase notes: whether a rebase happened, which files (if any) had trivial conflicts and
+  how each was resolved, and confirmation the full suite was green after.
+
+`fts renew` after writing.
+
+## GATE checklist (every box needs evidence, not assumption)
+
+1. `qa-report.md` exists and every AC row is PASS. Evidence: you read it and can cite the
+   rows.
+2. Branch is rebased onto current `origin/main` (or already up to date — confirm with
+   `git log origin/main..HEAD` showing no merge-base drift).
+3. The full suite (every command from `implementation-notes.md`) passed AFTER the rebase,
+   not before. Evidence: command output from this run, not a memory of qa stage's run.
+4. Commit history on the branch is a small number of coherent, prefixed commits.
+5. Push succeeded (`git push` exit code, or `gh pr view` shows the branch pushed).
+6. `gh pr create` succeeded and returned a URL, with Summary, AC checklist (all checked,
+   citing qa-report evidence), and Testing sections present in the body.
+7. No auto-merge, no merge, no reviewers requested.
+8. `TICKET_DIR/pr.md` written with URL, commit SHAs, and rebase notes.
+
+If any box fails, you do not have a PASS — go to REJECT or STUCK per the failure's cause.
+
+## Outcome
+
+Exactly one of the following, then mail your parent and exit (protocol step 6–7).
+
+- **PASS** — all gate boxes checked. `NEXT_STAGE` is `-` (terminal): complete only, do not
+  advance.
+  ```bash
+  fts complete --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --epoch "$EPOCH" \
+    --note "PR: <url>"
+  ```
+  Then clean up the worktree, only now that the PR exists:
+  ```bash
+  git -C "$REPO_ROOT" worktree remove "$REPO_ROOT/.ffactory/worktrees/$TICKET_ID"
+  ```
+  If anything earlier failed, skip this removal — leave the worktree for the next attempt
+  or for a human to inspect.
+
+- **REJECT to implement** — rebase hit a non-trivial conflict, OR the full suite failed
+  after a (conflict-free or resolved) rebase. `BOUNCE_STAGE` is `implement`. Use exactly
+  this reason format:
+
+  `REBASE | <conflicting files, or the failing command> | rebase onto latest main and re-verify`
+
+  Example:
+  ```bash
+  fts reject --db "$FTS_DB" --ticket "$TICKET_ID" --worker "$WORKER_ID" --epoch "$EPOCH" \
+    --reason "REBASE | src/billing/retry.py | rebase onto latest main and re-verify" \
+    --to-stage "$BOUNCE_STAGE"
+  ```
+  Before rejecting: if you started a rebase, make sure it is fully aborted
+  (`git rebase --abort`) and the worktree is clean — do not leave a half-rebased tree for
+  the next worker.
+
+- **STUCK** — `qa-report.md` missing or contains a non-PASS AC; `gh` unauthenticated or
+  push rejected by permissions; worktree missing or corrupted; `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 push without checking `qa-report.md` | skipped the precondition | Stop. Never push before confirming every AC row is PASS. |
+| You resolve a same-function conflict "to be safe" | misjudged trivial vs. non-trivial | If both sides touched the same logic, it is non-trivial. Abort the rebase, reject to implement. |
+| You push right after a clean rebase, no test run | assumed pre-rebase green still holds | Always rerun the full suite after ANY rebase, conflict-free or not, before pushing. |
+| You `git push --force` | skipped lease protection | Use `--force-with-lease` whenever history was rewritten and a remote branch may already exist. |
+| You enable auto-merge or merge the PR yourself | exceeded this stage's authority | This stage opens the PR only. Merging is a human decision. |
+| `gh pr create` fails with 401/403 and you try a personal token or `gh auth login` workaround | tried to route around missing credentials | STOP, go STUCK with the exact error. Credentials are a human's job. |
+| You fix a failing test yourself to get green after rebase | overstepped stage scope | This stage verifies; it does not patch product code. Reject to implement instead. |
+| History still has "wip"/"fixup" commits in the PR | skipped commit hygiene | Squash with `git reset --soft $(git merge-base HEAD origin/main)` + one clean commit before pushing. |
+| PR body has no AC checklist or cites nothing from qa-report.md | copied prd.md ACs without evidence | Each AC line must reference qa-report.md's verification for that AC. |
+| You remove the worktree after a failed push | cleaned up despite failure | Only remove the worktree on PASS, after the PR exists. Leave it otherwise. |
+| Same error blocks you twice | a wrong assumption | Re-read `qa-report.md`, `implementation-notes.md`, and `_protocol.md`; if still stuck, use the STUCK path. |