@taprootio/trellis 0.1.0

package/src/prompts.mjs

@@ -0,0 +1,189 @@
+// Trellis MCP prompts + resources (zero-dependency, transport-agnostic).
+//
+// TRL0006: the work-task / code-review / pr-draft loops as MCP **prompts**, and
+// the spec / conventions / config / playbooks / PR-template as MCP **resources**.
+// Like the tool ops in src/mcp.mjs, every builder takes an explicit repoRoot and
+// reads the repo's OWN files at request time — stateless and repoRoot-keyed, so
+// one server instance serves any repo and the prompts never drift from the
+// Markdown playbooks they mirror. The SDK + transport wiring live in
+// scripts/trellis-mcp.mjs; keeping these functions dependency-free means the whole
+// surface is unit-testable with `node --test` and no transport.
+//
+// Reading conventions from the repo (not baking a stack into the prompt text) is
+// the TRL0006 Risk made concrete: a prompt for repo A carries A's playbooks and
+// vocabulary; for repo B, B's.
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "./backlog.mjs";
+import { TrellisError } from "./mcp.mjs";
+
+// --------------------------------------------------------------- resources
+// The catalog. `rel` is the repo-relative file each `trellis://` uri serves; the
+// content is always read live from repoRoot, so a repo's own copy wins.
+export const RESOURCES = [
+  {
+    uri: "trellis://spec", name: "spec", title: "Backlog spec",
+    description: "The canonical Backlog Spec (SPEC.md).",
+    rel: "SPEC.md", mimeType: "text/markdown",
+  },
+  {
+    uri: "trellis://conventions", name: "conventions", title: "Repo conventions (AGENTS.md)",
+    description: "The repo's AGENTS.md — the canonical conventions every loop grounds in first.",
+    rel: "AGENTS.md", mimeType: "text/markdown",
+  },
+  {
+    uri: "trellis://config", name: "config", title: "Backlog config",
+    description: "backlog.config.json — the per-repo vocabulary (id prefix, milestones, priorities, effort).",
+    rel: "trellis/backlog.config.json", mimeType: "application/json",
+  },
+  {
+    uri: "trellis://playbook/conventions", name: "playbook-conventions", title: "Conventions contract",
+    description: "The per-repo conventions contract — the named seam points the universal loop reads from a repo's AGENTS.md.",
+    rel: "trellis/playbooks/conventions.md", mimeType: "text/markdown",
+  },
+  {
+    uri: "trellis://playbook/work-task", name: "playbook-work-task", title: "Playbook: work a task",
+    description: "The work-a-task loop, as Markdown.",
+    rel: "trellis/playbooks/work-task.md", mimeType: "text/markdown",
+  },
+  {
+    uri: "trellis://playbook/code-review", name: "playbook-code-review", title: "Playbook: code review",
+    description: "The code-review loop and its JSON output standard, as Markdown.",
+    rel: "trellis/playbooks/code-review.md", mimeType: "text/markdown",
+  },
+  {
+    uri: "trellis://playbook/pr-draft", name: "playbook-pr-draft", title: "Playbook: draft a PR",
+    description: "The PR title/description draft loop, as Markdown.",
+    rel: "trellis/playbooks/pr-draft.md", mimeType: "text/markdown",
+  },
+  {
+    uri: "trellis://template/pull-request", name: "template-pull-request", title: "PR template",
+    description: "The repository pull-request template the pr-draft loop fills.",
+    rel: ".github/pull_request_template.md", mimeType: "text/markdown",
+  },
+];
+
+function resourceByUri(uri) {
+  const r = RESOURCES.find((x) => x.uri === uri);
+  if (!r) throw new TrellisError(`unknown resource: ${uri}`, "not_found");
+  return r;
+}
+
+// list_resources — the catalog, each flagged `available` iff its file exists in
+// this repo. (SPEC.md, for one, is absent in onboarded repos until packaging
+// bundles a canonical copy — TRL0010.)
+export function listResources(repoRoot) {
+  return RESOURCES.map(({ uri, name, title, description, mimeType, rel }) => ({
+    uri, name, title, description, mimeType,
+    available: existsSync(join(repoRoot, rel)),
+  }));
+}
+
+// read_resource — the file behind a trellis:// uri. Throws `not_found` when the
+// uri is unknown OR the file is absent in this repo, rather than faking content.
+export function readResource(repoRoot, uri) {
+  const r = resourceByUri(uri);
+  const abs = join(repoRoot, r.rel);
+  if (!existsSync(abs)) {
+    throw new TrellisError(`resource ${uri} is unavailable in this repo (no ${r.rel})`, "not_found");
+  }
+  return { uri: r.uri, mimeType: r.mimeType, text: readFileSync(abs, "utf8") };
+}
+
+// ----------------------------------------------------------------- prompts
+// Each prompt embeds the repo's own playbook body (`playbook`) verbatim, behind a
+// repo-parameterized preamble. `arguments` is the MCP prompt-argument list.
+export const PROMPTS = [
+  {
+    name: "work-task", title: "Work a task",
+    description: "Take a Trellis task from active/ to ready-for-review by following the work-a-task loop.",
+    playbook: "trellis/playbooks/work-task.md",
+    arguments: [{ name: "id", description: "task id to work, using this repo's configured id prefix and width", required: true }],
+  },
+  {
+    name: "code-review", title: "Code review",
+    description: "Review the current branch's work against the repo's conventions and emit the canonical JSON findings.",
+    playbook: "trellis/playbooks/code-review.md",
+    arguments: [],
+  },
+  {
+    name: "pr-draft", title: "Draft a PR",
+    description: "Draft a copy-ready PR title and description that conform to the repo's PR template.",
+    playbook: "trellis/playbooks/pr-draft.md",
+    arguments: [],
+  },
+];
+
+function promptByName(name) {
+  const p = PROMPTS.find((x) => x.name === name);
+  if (!p) throw new TrellisError(`unknown prompt: ${name}`, "not_found");
+  return p;
+}
+
+// Ground every prompt in this repo's conventions, with the id vocabulary read
+// live from backlog.config.json (never baked into the prompt text). On a config
+// error we still point at AGENTS.md rather than emitting a wrong vocabulary.
+function conventionsPreamble(cfg, cfgErrors) {
+  const vocab = cfgErrors.length
+    ? "the repo's `backlog.config.json` governs its vocabulary"
+    : `ids are \`${cfg.idPrefix}\` + ${cfg.idWidth} digits; milestones are ${cfg.milestones.join(" → ")}; priorities are ${cfg.priorities.join(", ")}`;
+  return "Ground in this repo's own conventions first: read its `AGENTS.md` (the "
+    + "`trellis://conventions` resource) and the `SPEC.md` / docs it points at. The "
+    + `repo's conventions govern — ${vocab}.`;
+}
+
+// Validate the work-task `id` argument against this repo's id format (when the
+// config is loadable), so a malformed id fails fast with a clear message.
+function requireId(raw, cfg, cfgErrors) {
+  if (typeof raw !== "string" || !raw.trim()) throw new TrellisError("`id` is required", "invalid_request");
+  const id = raw.trim();
+  if (/[\r\n]/.test(id)) throw new TrellisError("`id` must be a single line", "invalid_request");
+  if (!cfgErrors.length) {
+    const re = new RegExp(`^${cfg.idPrefix}\\d{${cfg.idWidth}}$`);
+    if (!re.test(id)) throw new TrellisError(`invalid task id: ${id} (expected ${cfg.idPrefix} + ${cfg.idWidth} digits)`, "invalid_request");
+  }
+  return id;
+}
+
+// The per-prompt instruction that bridges the preamble to the embedded playbook.
+function instruction(name, args, cfg, cfgErrors) {
+  if (name === "work-task") {
+    const id = requireId(args.id, cfg, cfgErrors);
+    return `Then work task **${id}** end-to-end by following the loop below exactly — do not improvise the order, and honor its two pauses (refinement sign-off, then plan confirmation) before any branch or file edit.`;
+  }
+  if (name === "code-review") {
+    return "Then review the current branch's work by following the process below, and finish with the canonical JSON findings array exactly as the output standard specifies.";
+  }
+  return "Then draft the PR title and description by following the loop below, emitting the single copy-ready Markdown block it specifies.";
+}
+
+// build_prompt — assemble one prompt's messages for this repo: a conventions
+// preamble + a per-prompt instruction + the repo's playbook body, embedded
+// verbatim so the prompt is self-contained on clients that don't resolve resource
+// links. Throws `not_found` if the backing playbook is missing in this repo.
+export function buildPrompt(repoRoot, name, args = {}) {
+  const p = promptByName(name);
+  const { cfg, errors: cfgErrors } = loadConfig(repoRoot);
+
+  const abs = join(repoRoot, p.playbook);
+  if (!existsSync(abs)) {
+    throw new TrellisError(`prompt ${name} needs ${p.playbook}, which is missing in this repo`, "not_found");
+  }
+  const playbook = readFileSync(abs, "utf8").replace(/\n*$/, "\n");
+
+  const text = [
+    conventionsPreamble(cfg, cfgErrors),
+    "",
+    instruction(name, args, cfg, cfgErrors),
+    "",
+    "--- playbook ---",
+    "",
+    playbook,
+  ].join("\n");
+
+  return {
+    description: p.description,
+    messages: [{ role: "user", content: { type: "text", text } }],
+  };
+}

package/templates/.github/pull_request_template.md

@@ -0,0 +1,31 @@
+<!--
+Title format: <ID>: imperative summary (<= 72 chars), where <ID> is this repo's
+backlog id (its configured prefix + number, per backlog.config.json).
+For a branch spanning several items, lead with the primary id and name the rest
+in the body. Generate a conforming title + description with the shortcut at
+trellis/playbooks/pr-draft.md.
+Attribution: follow the repo's attribution policy (AGENTS.md). Default: none — no
+Co-Authored-By trailers or "Generated with" footers.
+-->
+
+## Summary
+
+<!-- 1–3 sentences: what this PR does and why. -->
+
+## Task
+
+<!-- Link the backlog item(s) by id. Note any that are closed out here. -->
+
+## Changes
+
+<!-- The notable changes, grouped if helpful. Describe what shipped, not a file list. -->
+
+## Verification
+
+- [ ] the backlog `check` passes (the repo's check command — see AGENTS.md)
+- [ ] Touched docs / spec updated
+<!-- Add the commands you ran and their result. -->
+
+## Follow-ups
+
+<!-- New backlog items spun off, or "none". -->

package/templates/trellis/branch-protection.md

@@ -0,0 +1,116 @@
+# Enabling branch protection
+
+The Trellis spec (§10, "CI and branch protection") makes a gated default branch
+part of being Trellis-conformant: the default branch is **protected**, changes
+land via pull/merge request, and the generator's **`--check` is a required status
+check**. The CI workflow (`.github/workflows/backlog.yml`) provides the check; this
+recipe turns it into an enforced gate. Branch protection is a host-repo setting, not
+committed code, so it is enabled once per repo by an admin — it does not travel in
+a commit the way the workflow does.
+
+## The required-check context: `backlog`
+
+The check you require is identified by a **stable context name**. In the Trellis
+workflow that name is **`backlog`** — the job:
+
+```yaml
+# .github/workflows/backlog.yml
+name: Backlog Hygiene     # ← the WORKFLOW's display name (not the check context)
+jobs:
+  backlog:
+    name: backlog         # ← the JOB name == the required status check context
+```
+
+Require the check named **`backlog`**, not `Backlog Hygiene`. The job carries an
+explicit `name: backlog` so the context is pinned: renaming the workflow's display
+name cannot move it, and a rename of the job is a visible edit to this line rather
+than a silent gate-disabling drift (the risk §10's stable-context guidance
+guards against). If you change the job name, update the required check to match.
+
+## GitHub
+
+### With `gh` (scriptable)
+
+From a clone of the repo, with the [`gh`](https://cli.github.com/) CLI
+authenticated and admin on the repo. `gh` substitutes `{owner}`/`{repo}` from the
+current repository; replace `main` if your default branch differs:
+
+```bash
+gh api --method PUT repos/{owner}/{repo}/branches/main/protection --input - <<'JSON'
+{
+  "required_status_checks": { "strict": true, "contexts": ["backlog"] },
+  "required_pull_request_reviews": { "required_approving_review_count": 1 },
+  "enforce_admins": true,
+  "restrictions": null
+}
+JSON
+```
+
+- `required_status_checks.contexts: ["backlog"]` — the gate. `strict: true` also
+  requires the branch to be up to date before merging; drop it if you don't want
+  that.
+- `required_pull_request_reviews` — requires changes to land via PR. Set
+  `required_approving_review_count: 0` to require a PR without a mandatory
+  approval, or raise it for more reviewers.
+- `enforce_admins: true` — applies the rule to admins too; relax if you need an
+  admin escape hatch.
+- `restrictions: null` — no push allow-list. All four top-level keys must be
+  present (a key may be `null`); this is the minimal conformant payload.
+
+### In the UI
+
+**Settings → Branches → Add branch ruleset** (or **Add rule** under the classic
+"Branch protection rules"), targeting the default branch:
+
+1. **Require a pull request before merging** (optionally require approvals).
+2. **Require status checks to pass before merging** → search for and select
+   **`backlog`**. Optionally enable "Require branches to be up to date."
+3. Save.
+
+> The `backlog` check only appears in the picker after the workflow has run at
+> least once on the repo. Push the scaffold (or open a first PR) so the check
+> registers, then add it to the rule.
+
+## Other forges
+
+The same two requirements — a protected default branch and a required check —
+map onto every major forge. The "check" is whichever CI job runs `trellis check`
+(named `backlog` here); on forges without GitHub-style named contexts, the gate is
+"the pipeline/build must succeed."
+
+### GitLab
+
+- **Protected branch** — *Settings → Repository → Protected branches*: protect the
+  default branch, set **Allowed to push and merge → No one** (force changes
+  through merge requests) and **Allowed to merge** to the appropriate role.
+- **Required check** — *Settings → Merge requests*: enable **Pipelines must
+  succeed** so an MR can't merge unless its pipeline (the job running
+  `trellis check`) passes; optionally require approvals. Scriptable via
+  `PUT /projects/:id` with `only_allow_merge_if_pipeline_succeeds: true` and
+  `POST /projects/:id/protected_branches`.
+
+### Bitbucket
+
+- **Protected branch** — *Repository settings → Branch restrictions*: add a
+  restriction on the default branch — **Prevent changes without a pull request**
+  (and prevent direct pushes).
+- **Required check** — in the same restriction, add the merge check **require
+  passing builds** (minimum 1). The Pipelines step that runs `trellis check`
+  reports its build status via the Build Status API; require a minimum number of
+  approvals if desired.
+
+### Azure DevOps
+
+- **Protected branch** — *Repos → Branches → ⋯ on the default branch → Branch
+  policies*. Adding any policy blocks direct pushes; add **Require a minimum
+  number of reviewers** to force PRs.
+- **Required check** — add a **Build validation** policy that references the
+  pipeline running `trellis check` (set it Required). If the pipeline reports via
+  the Status API instead, use a **Status checks** policy referencing that context.
+
+## Verify the gate
+
+Open a throwaway PR that intentionally drifts the index — e.g. edit a generated
+file between its `BEGIN/END GENERATED` markers, or add an item without
+regenerating — and confirm the `backlog` check fails and the merge button is
+blocked until it passes. Close the PR without merging.

package/templates/trellis/playbooks/code-review.md

@@ -0,0 +1,64 @@
+# Playbook: code review
+
+A ready-to-use shortcut for reviewing work in a Trellis repo. Point any AI
+assistant at this file, or invoke the equivalent `code-review` MCP prompt (served
+from this file by the Trellis MCP server). The
+*what to check* defers to the repo's own conventions (AGENTS.md / SPEC.md), so
+this stays tech-agnostic — the **process** and the **output format** are the
+standard.
+
+## Process
+
+1. **Ground in the repo's conventions first.** Read AGENTS.md (canonical) and any
+   SPEC.md / docs the change touches. You cannot judge work against rules you
+   have not read. Seam points named in code font (`check`, `gates`) read their
+   value from AGENTS.md — see [`conventions.md`](conventions.md).
+2. **Identify the task.** Determine the backlog id this work belongs to — the
+   repo's configured id (branch name, commits, the added/moved file under
+   the backlog root, default `trellis/`). Review against its stated intent, not
+   just the diff in isolation.
+3. **Verify closeout** when the work claims to finish a task: the item moved to
+   `completed/tasks/` with `status: completed` + `completed_on`, the generated
+   artifacts are current (the repo's `check` command passes — e.g.
+   `npm run backlog:check`; see AGENTS.md), and links hold. Flag any miss as a
+   `blocker`.
+4. **Review thoroughly, twice.** First pass for the obvious; second pass for what
+   you rationalized away — data and control flow across seams, behavior under
+   failure / edge / hostile input, and what *should* have changed but didn't
+   (missing tests, a stale doc, an un-updated snapshot).
+5. **Run the gates you can** — the repo's `check` command and its `gates`
+   (tests/lint; e.g. `npm run backlog:check` + `node --test`; see AGENTS.md).
+   A failing gate is a `blocker`.
+
+## Output format (the standard)
+
+Put any discussion first, then end with **exactly one** fenced `json` block
+containing a single array and nothing after it, so it pastes into PR/issue
+tooling in one click. The array is always last, even when empty.
+
+Each finding is an object:
+
+- `file` — repo-relative path to the file that needs to change.
+- `line` — line number where the change applies.
+- `severity` — one of `"blocker"`, `"warning"`, `"nit"`.
+- `suggestion` — concise fix, including the exact change to make.
+
+```json
+[
+  {
+    "file": "src/backlog.mjs",
+    "line": 153,
+    "severity": "blocker",
+    "suggestion": "Validate completed/removed items too — the loop only iterates active, so a completed task with status: active passes --check."
+  },
+  {
+    "file": "src/backlog.mjs",
+    "line": 55,
+    "severity": "warning",
+    "suggestion": "Reject non-numeric config effort values; `[\"Tiny\"]` currently passes."
+  }
+]
+```
+
+Use `[]` when there are no findings. `severity` lets the author triage every
+`blocker` before any `nit` without re-reading the list.

package/templates/trellis/playbooks/conventions.md

@@ -0,0 +1,56 @@
+# The per-repo conventions contract
+
+The work-a-task, code-review, and pr-draft playbooks are **universal** — they
+describe the *shape* of the loop (refine → plan → branch → work → review → close)
+and the *output standards*, and nothing about any one repo's stack. Everything
+that is repo-specific — which command regenerates the backlog, how branches are
+named, which gates must stay green — is read at runtime from the repo's own
+`AGENTS.md`.
+
+This file defines that seam: the **named points** a playbook refers to, and the
+rule for where their values live. The *definition* here is universal and travels
+unchanged into every Trellis repo; the *values* are per-repo and live in each
+repo's `AGENTS.md` "Loop contract" block (scaffolded by `trellis init`). A
+playbook step names a seam point as its instruction ("regenerate the backlog");
+any concrete command it shows is a tagged example of *one* repo's value, never
+the command a different repo should run.
+
+## Seam points
+
+| seam point | what the loop needs | this repo's value lives in |
+| --- | --- | --- |
+| `regenerate` | the command that revalidates items and rewrites the generated index + `backlog.json` after any item add/move/edit | `AGENTS.md` |
+| `check` | the read-only gate the loop keeps green locally and CI enforces (validate + verify-no-drift, non-zero on failure) | `AGENTS.md` |
+| `branch-naming` | the pattern for a task branch, e.g. `<initials>/<id-lowercase>/<slug>` | `AGENTS.md` |
+| `gates` | any other gates a change must keep green before review (tests, lint, build) | `AGENTS.md` |
+| `attribution` | the commit/PR attribution policy (Trellis convention: none) | `AGENTS.md` |
+
+Two more inputs the loop reads, defined elsewhere and referenced here for
+completeness:
+
+- **id vocabulary** (id prefix/width, milestones, priorities, effort) — from
+  `trellis/backlog.config.json` (SPEC.md §7), not restated per playbook.
+- **tasks layout** (`<tasksDir>/{active,completed/tasks,removed}/`, default
+  `trellis/`, plus the generated artifacts) — the in-root structure and the
+  `trellis/backlog.config.json` config home are fixed by the spec (SPEC.md §2);
+  only the root path is configurable via `tasksDir`.
+
+## How a repo declares its values
+
+`trellis init` writes a "Loop contract" block into the onboarded repo's
+`AGENTS.md` with that repo's values (e.g. `npx @taprootio/trellis generate` /
+`npx @taprootio/trellis check`, a branch pattern, the attribution policy). A repo edits those values to
+match its own tooling; the playbooks need no change to follow them, because they
+only ever name the seam point.
+
+Trellis itself is the reference instance — its `AGENTS.md` Loop contract block
+holds the concrete values the playbooks' `e.g.` examples are drawn from.
+
+## How a playbook uses a seam point
+
+> Rewrite the task file, then **regenerate the backlog** (the repo's `regenerate`
+> command — e.g. `npm run backlog:readme`; see AGENTS.md) and commit it.
+
+The instruction is "regenerate the backlog"; `npm run backlog:readme` is Trellis's
+value, tagged as such. In an onboarded repo the same step resolves to that repo's
+`regenerate` value with no edit to the playbook.

package/templates/trellis/playbooks/pr-draft.md

@@ -0,0 +1,39 @@
+# Playbook: draft a PR title and description
+
+A ready-to-use shortcut for generating a **copy-ready** PR title and description
+that conform to [`.github/pull_request_template.md`](../../.github/pull_request_template.md).
+Point any AI assistant at this file, or invoke the equivalent `pr-draft` MCP
+prompt (served from this file by the Trellis MCP server) so any tool can run it.
+
+## What the assistant should gather first
+
+- Commits on the branch: `git log --oneline <base>..HEAD` (base is usually `main`).
+- The change surface: `git diff --stat <base>...HEAD`.
+- The PR template: `.github/pull_request_template.md`.
+- The referenced task file(s) under the backlog root (default `trellis/`).
+
+## Prompt
+
+> Generate a pull-request **title** and **description** for the current branch,
+> based only on its actual commits and diff (do not invent changes).
+>
+> - **Title:** `<ID>: <imperative summary>`, ≤ 72 characters, where `<ID>` is the
+>   repo's backlog id (its configured prefix + number). Lead with the primary
+>   backlog id; if the branch spans several items, name the primary and mention
+>   the others in the body.
+> - **Description:** fill every section of `.github/pull_request_template.md`
+>   (Summary, Task, Changes, Verification, Follow-ups). Tick a checklist item
+>   only when the evidence supports it; otherwise leave it unchecked and say why.
+> - **Attribution:** follow the repo's `attribution` policy (AGENTS.md); the
+>   default is none — no `Co-Authored-By:` trailers or AI "Generated with …"
+>   footers in the title or description.
+> - **Output:** a single fenced `markdown` block whose first line is the title as
+>   `# <ID>: …`, followed by the completed template body — so it copies in one
+>   click.
+
+## Output shape
+
+One copy-ready Markdown block:
+
+- first line: `# <ID>: <summary>` (the title)
+- then the filled template (Summary, Task, Changes, Verification, Follow-ups)

package/templates/trellis/playbooks/work-task.md

@@ -0,0 +1,76 @@
+# Playbook: work a task
+
+A ready-to-use shortcut for taking a Trellis task from the backlog root's
+`active/` (the configured `tasksDir`, default `trellis/`) all the way to "ready
+for your review." Invoke it with a backlog id — the repo's id prefix + number,
+per `backlog.config.json`.
+Point any AI assistant at this file, or invoke the equivalent `work-task` MCP
+prompt (served from this file by the Trellis MCP server — see AGENTS.md §Roadmap).
+
+The loop is fixed — do not improvise the order. There are exactly **two**
+intentional pauses (steps 4 and 5); everything after the confirmed plan runs
+without further check-ins. No file edits happen until you are on the task branch,
+so `main` stays clean.
+
+## The loop
+
+1. **Ground in the repo's conventions.** Read AGENTS.md (canonical) and the
+   SPEC / docs relevant to what the task will touch. The *what* and *how* of this
+   repo live there; this playbook is only the orchestration. Where a step names a
+   seam point in code font (`regenerate`, `check`, `branch-naming`, `gates`,
+   `attribution`), it reads that repo's value from AGENTS.md — see
+   [`conventions.md`](conventions.md) for the contract.
+2. **Read the task.** Open `<ID>.md` under the backlog root's `active/` (the
+   configured `tasksDir`, default `trellis/`) in full — front-matter (milestone,
+   priority, effort, depends_on) and body (Scope, Notes, Risks). If
+   it isn't in `active/`, stop and say where it actually is. Confirm every
+   `depends_on` id is completed; surface any that aren't.
+3. **Verify it against the codebase.** Check the task hasn't drifted: do its
+   assumptions still hold, do referenced files/APIs still exist, is it still the
+   right thing to build and still workable? Note anything stale.
+4. **Propose refinements, then PAUSE.** Surface ambiguities, gaps, drift, and
+   concrete suggestions that would make the task clearer or more workable — then
+   **wait for the user's answers.**
+5. **Plan, with checkpoints, then PAUSE.** Using the agreed refinements, lay out
+   the implementation as ordered steps and call out the natural **commit
+   checkpoints**. **Confirm the plan with the user** before touching anything.
+6. **Start clean, then branch.** Confirm the working tree is clean and `main` is
+   current (`git fetch`, fast-forward `main`); if not, stop and surface it. Create
+   the task branch using the repo's `branch-naming` convention —
+   `<initials>/<id-lowercase>/<slug>` (see AGENTS.md for the repo's pattern and an
+   example). Branch from local `main`, not `origin/main`, so the upstream isn't
+   mis-set. Everything from here lands on the branch, never on `main`.
+7. **Rewrite the task on the branch.** Fold the user's refinements into
+   the task file under the backlog root's `active/` (Scope / Notes / Risks),
+   **regenerate the backlog**
+   (the repo's `regenerate` command — e.g. `npm run backlog:readme`; see
+   AGENTS.md), and commit it as the first checkpoint. This refined file is the
+   source of truth for the rest of the loop.
+8. **Work the task end-to-end.** Implement against the refined Scope, committing
+   at the checkpoints from step 5 and keeping the repo's `gates` green (its `check`
+   command plus tests/lint — e.g. `npm run backlog:check` + `node --test`;
+   see AGENTS.md). When the work lands, close the task out: move it to
+   `completed/tasks/`, set `status: completed` + `completed_on`, regenerate
+   (SPEC §4–§5).
+9. **Request a review.** Run `trellis/playbooks/code-review.md` over the branch and
+   capture its canonical JSON findings. Make it an **independent** pass — ideally a
+   separate agent or session, or at minimum re-ground from scratch — since author
+   self-review tends to rubber-stamp.
+10. **Fix the findings.** Resolve every `blocker` and `warning` (and `nit`s unless
+    waived); re-run the review until the array is `[]` or only waived items
+    remain. Keep the gates green.
+11. **Hand off for review.** Tell the user it's ready: the branch name, what
+    shipped, the review outcome, and the push + PR commands (PR body via
+    `trellis/playbooks/pr-draft.md`). Do **not** push or merge — that's the user's.
+
+## Notes
+
+- The two pauses are the contract: refinement sign-off (step 4) and plan
+  confirmation (step 5). Both happen before any branch or file edit. If you hit a
+  genuine blocker mid-loop, stop and surface it — otherwise keep going.
+- Because branching (step 6) precedes every edit (steps 7–8), the clean-tree
+  requirement always holds and `main` is never dirtied.
+- Branch protection means work never lands on `main` directly; it always goes
+  through a PR with the required backlog check.
+- Commits and PRs follow the repo's `attribution` policy (AGENTS.md); the default
+  is **none** — never add `Co-Authored-By:` trailers or "Generated with …" footers.