cohorte 1.0.0

package/core/commands/review.md

@@ -0,0 +1,68 @@
+---
+description: Dispatch the read-only review agent to audit the feature against its frozen spec.
+argument-hint: <feature_id>
+---
+
+You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
+
+> Read `PIPELINE.md` §`vcs.default_branch` (diff base) and the `surfaces`/`contract` fields.
+>
+> Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
+> installed globally — read whichever exists.
+>
+> **Kanban** (SCHEMA.md §Kanban): move card `#$ARGUMENTS` → **Review**. No-op silently if no board.
+
+## 1. Gather the inputs for stateless reviewers
+
+- Confirm `specs/$ARGUMENTS.md` exists.
+- Compute the diff, and let **git do the grouping** (deterministic — don't reason it out file by file):
+  per surface, `git diff <default_branch> --name-only -- <surface.path>` is exactly that surface's changed
+  files; the **`shared` remainder** (contract file + anything outside every surface) is
+  `git diff <default_branch> --name-only -- . $(for p in <each surface.path>; do printf ':(exclude)%s ' "$p"; done)`.
+  Attach the remainder to the most relevant surface's reviewer and say so in its dispatch. A surface whose
+  `git diff` comes back empty gets no reviewer.
+
+## 2. Dispatch review agents — one per touched surface, IN PARALLEL
+
+Spawn ONE `review` agent per surface that has changed files, in a **single message** (one Task call
+each, like `/build`) so they run concurrently — NEVER serially: review wall-clock must be the
+slowest surface, not the sum. A diff touching a single surface ⇒ a single reviewer. For each:
+
+> `subagent_type: review` — "Review feature `$ARGUMENTS` — **scope: the `<surface.key>` surface
+> only**. Read `PIPELINE.md` first (its flags + §Conventions/§Testing for `<surface.key>`). Spec:
+> `specs/$ARGUMENTS.md` (source of truth). Contract: `<contract.path>/$ARGUMENTS.<ext>`. Changed
+> files in your scope (diff vs `<default_branch>`): <list, with the `--stat` counts>. Review the
+> diff hunks + immediate context — not whole files. Check spec conformance first, then correctness,
+> security, conventions, RBAC/mobile-first _if the profile enables them_, and TDD coverage. Emit
+> the REVIEW REPORT per `.claude/templates/review-feedback.md` — every finding self-sufficient
+> (`file:line` · severity · type · concrete fix)."
+
+Note the epoch (`date +%s`) just before dispatching — §3's metrics lines need the wall-clock.
+
+## 3. Merge & relay the verdict
+
+Merge the returned reports into **one** REVIEW REPORT (same template): findings concatenated and
+re-ordered by severity, counts summed, duplicates collapsed, verdict = the worst returned
+(`BLOCK` > `REVISE` > `SHIP`). Append one line per reviewer to `.claude/pipeline-metrics.jsonl`
+(gitignored): `{"ts":"<ISO>","feature":"$ARGUMENTS","phase":"review","surface":"<key>","seconds":<wall-clock>,"result":"<verdict>:<finding count>"}`.
+Print the report **and stage it to `specs/reports/$ARGUMENTS.md`** (overwrite) — a gitignored buffer so
+a `/fix` after a `/clear` can still read the findings; the `specs/reports/` subfolder is skipped by the
+non-recursive `specs/*.md` glob, so it's never mistaken for a spec (no phantom card, no bogus stage). Then:
+
+- **SHIP** → a SHIP verdict *is* the pipeline's statement that the feature meets its Definition of
+  Done, so **tick the DoD**: in `specs/$ARGUMENTS.md` §`Acceptance criteria / DoD`, flip each `- [ ]`
+  → `- [x]` for the criteria the pipeline has actually verified — spec conformance + `ui_language`
+  copy (this review), tests · lint · typecheck (a green `/build`), mobile-first + runtime flows (a
+  prior `/smoke`). **Leave `- [ ]` (and say which) any item whose verifying stage didn't run this
+  cycle** — e.g. no `/smoke` ⇒ the mobile-first / runtime item stays open. Ticking is the lead's job
+  (the reviewer is read-only). **Then stamp the freshness gate** so `/ship` can refuse to ship code
+  edited after this verdict: compute `BASE=$(git merge-base <default_branch> HEAD)` and write into the
+  spec front-matter `reviewed_base: $BASE` plus
+  `reviewed_digest: $(git diff $BASE -- . ':(exclude)specs/' | sha256sum | cut -c1-16)` — the fingerprint
+  of exactly the source you just reviewed (specs excluded, so DoD ticks + the ship status flip don't
+  trip it). Then tell the human they can `/ship` — _the handoff is fully on disk, so `/clear` first is safe._
+- **REVISE / BLOCK**, or any finding of any severity → tell the human to run **`/fix $ARGUMENTS`** —
+  it appends the report to the spec's `## Remediation` and re-dispatches ONLY the surfaces with
+  findings. The full path (`/spec` Mode B then `/build`) remains for findings that change the
+  contract in ways that ripple into clean surfaces. _The report is staged to `specs/reports/$ARGUMENTS.md`,
+  so you can `/clear` before `/fix` — it reads the findings back from disk._

package/core/commands/ship.md

@@ -0,0 +1,68 @@
+---
+description: At a SHIP verdict, dispatch the release agent to commit, push, and open the PR (with your confirmation).
+argument-hint: <feature_id>
+---
+
+You are the **lead**. Ship feature **$ARGUMENTS**. This is the outward-facing gate.
+
+> Read `PIPELINE.md` §`vcs` (host, remote, default_branch, feature_branch_prefix).
+>
+> **Kanban** (SCHEMA.md §Kanban) is mirrored in **explicit steps** below, not as an afterthought:
+> §1 moves the card → **Ship**; §4 moves it → **Shipped** and writes the PR number. No-op silently if
+> no board. Do not skip §4's move — a shipped feature whose card is stuck in an earlier column is the
+> bug this ordering prevents.
+
+## 1. Pre-flight (confirm before doing anything irreversible)
+
+- Confirm the latest `/review` returned **SHIP** (no CRITICAL, no security). If not reviewed, or the
+  verdict was REVISE/BLOCK, stop and say so.
+- **Freshness gate** — the reviewed code must be exactly what ships. If the spec front-matter carries
+  `reviewed_base` + `reviewed_digest`, recompute
+  `git diff <reviewed_base> -- . ':(exclude)specs/' | sha256sum | cut -c1-16` and compare to
+  `reviewed_digest`. **Match** ⇒ source unchanged since the SHIP verdict, proceed. **Mismatch** ⇒ source
+  (or the contract) was edited after review — the verdict is **stale**: stop and tell the human to re-run
+  `/review $ARGUMENTS` before shipping. Missing fields (spec predates the gate) ⇒ skip, don't block.
+- **DoD gate (verify, don't tick — `/review` owns the ticking).** Read `specs/$ARGUMENTS.md`
+  §`Acceptance criteria / DoD`; if any item is still `- [ ]`, list the open ones and ask the human to
+  confirm shipping anyway (they may be deferred on purpose — e.g. a UI item on a backend-only feature).
+  All `- [x]` ⇒ proceed silently.
+- Show `git status` + `git diff --stat`; confirm the branch is `<feature_branch_prefix>$ARGUMENTS`.
+- **Ask the human to confirm** they want to commit, push, and open the PR. Wait for yes.
+- After the yes: **move card `#$ARGUMENTS` → the `ship` column** (SCHEMA.md §Kanban "Move a card"). No-op if no board.
+
+## 2. Mark the spec shipped (BEFORE dispatch, so it ships in the same commit)
+
+Once the human confirms, edit `specs/$ARGUMENTS.md` front-matter `status: → shipped` — **before**
+dispatching the release agent, so the status flip is part of the tree it commits (otherwise it lands
+uncommitted after the PR opens). Only flip after the human's "yes"; if they decline, leave it.
+
+## 3. Dispatch the `release` agent
+
+Spawn one agent (`subagent_type: release`): "Release feature `$ARGUMENTS` on branch
+`<feature_branch_prefix>$ARGUMENTS`. Read `PIPELINE.md` §vcs first. Spec: `specs/$ARGUMENTS.md` (already
+`status: shipped` — stage it). Write conventional commit(s), push (no force), open the PR (use `gh` if
+`host: github` + available; else emit the compare URL + drafted PR body from `.claude/templates/pr-body.md`).
+Stage **all** the feature's changes including `specs/$ARGUMENTS.md`. Never edit source, never force-push,
+never run migrations."
+
+## 4. Relay + move the card to Shipped (do not skip)
+
+Print the release agent's report: commit SHA(s), pushed branch, PR URL (or compare URL + drafted body).
+Confirm `specs/$ARGUMENTS.md` was committed as `status: shipped` (part of the release commit).
+
+**Move the card to Shipped — required, and verify it actually moved.** Move card `#$ARGUMENTS` → the
+`shipped` column (SCHEMA.md §Kanban "Move a card") and **append the PR number** so the line reads
+`- [ ] <title> #$ARGUMENTS — PR #<num>`. Take `<num>` from the PR URL (`…/pull/13` ⇒ `13`); **always write
+it when a PR was created** (the `gh` path) — it is what the dashboard turns into a PR link. If only a
+compare URL was emitted (no PR yet), move the card without a number. Then **re-read the board** and confirm
+the card sits under the `shipped` heading with no stale copy left under its previous column. No board ⇒
+skip silently.
+
+## 5. After the PR — CI gate + teardown
+
+- If `host: github` and `gh` is available, watch the PR's checks (`gh pr checks <url> --watch`) and
+  report the result — the human merges only on green. A red check ⇒ back to `/fix $ARGUMENTS`.
+- Once the human confirms the PR is **merged**: if `isolation.enabled`, propose the teardown —
+  `scripts/remove-feature.sh $ARGUMENTS` (add `--drop-db` to also drop the feature db; kept by
+  default). It removes the worktree, deletes the merged branch, frees the slot. Never run it before
+  the merge is confirmed, and only with the human's go-ahead (the gate will ask anyway).

package/core/commands/smoke.md

@@ -0,0 +1,55 @@
+---
+description: Exercise the built feature end-to-end in its worktree — infra up, migrations, contract endpoints, key UI flows, visual check vs design — before /review.
+argument-hint: <feature_id>
+---
+
+You are the **lead**. Smoke-test feature **$ARGUMENTS** — actually run it. `/review` audits the code
+read-only; nobody has executed it yet. You verify it *works*, you never fix it here (failures go
+through `/fix`). Observe honestly: report what happened, not what should have happened.
+
+> Read `PIPELINE.md` §`pipeline-profile`: `commands` (migrate/dev), `isolation` (worktree, slot
+> ports, db), `contract`, `design`, `surfaces`, and the spec `specs/$ARGUMENTS.md` (§5 contract,
+> §9 acceptance).
+>
+> **Kanban** (SCHEMA.md §Kanban): move card `#$ARGUMENTS` → **Review**. No-op silently if no board.
+
+## 1. Bring the feature up
+
+- Work in the feature's checkout: with `isolation.enabled`, the sibling worktree
+  (`../<slug>-$ARGUMENTS`, its slot's ports + db from `.worktrees/slots.tsv`); otherwise the main
+  checkout on the feature branch.
+- Infra as needed: the compose stack if one is declared (the gate will ask — that's expected),
+  then `commands.migrate`, then `commands.dev` **in the background**. Wait for ready (poll the
+  ports), don't assume.
+
+## 2. Exercise the contract (the real server, not the tests)
+
+- Hit a representative set of spec §5 endpoints with `curl`: every route domain, every auth level,
+  at least one error case per class (validation `422`, unauthenticated `401`, wrong-role `403`,
+  conflict `409`). Compare status + response envelope against the contract.
+- If `rbac.enabled`: verify at least one denial per role boundary the spec declares.
+- A mismatch is a FAIL entry with the exact command, expected, and actual — precise enough for a
+  stateless `/fix` agent.
+
+## 3. Exercise the UI (only if a touched surface has `uses_design`)
+
+- Drive the spec §8 flows against the running app, **mobile viewport first** (375px), then desktop.
+- If a browser/screenshot tool is available (a project driver, playwright, an agent browser), capture
+  each §8 screen and compare against the feature's design pages: each `design_files` entry is a full
+  `https://claude.ai/design/p/<projectId>?file=<file>` link — extract its `<projectId>` (the `/p/…`
+  segment) + `<file>` (the `?file=` query) and fetch read-only via `DesignSync get_file(<projectId>,
+  <file>)`. Compare layout, states (empty/loading/error/suppressed…), copy language. Note deviations.
+- No browser tooling available ⇒ **say so and skip the visual diff** — never claim a visual check
+  you didn't perform.
+
+## 4. SMOKE REPORT
+
+- One line per check: ✅/❌ · what was exercised · (on ❌) command → expected vs actual.
+- **Stage the full report to `specs/reports/$ARGUMENTS.md`** (overwrite) — the same gitignored buffer
+  `/review` uses (subfolder ⇒ skipped by the non-recursive `specs/*.md` glob), so a `/fix` after a
+  `/clear` still has the failures.
+- Verdict **PASS** (all green) → tell the human to run `/review $ARGUMENTS`.
+  Verdict **FAIL** → the failures are findings: feed them to `/fix $ARGUMENTS`, re-run `/smoke`
+  after. _Either way the handoff is on disk — `/clear` before the next command is safe._
+- Append one metrics line to `.claude/pipeline-metrics.jsonl` (see `/build` §4, `phase: "smoke"`).
+- Tear down what you started (kill the dev server); leave shared infra as you found it.

package/core/commands/spec.md

@@ -0,0 +1,67 @@
+---
+description: Interactively capture a frozen feature spec (or apply a review return) into specs/<id>.md.
+argument-hint: [paste brainstorm return OR review report]
+---
+
+You run the **spec** step in the main thread — interactive, with the human. Pasted input below:
+
+**$ARGUMENTS**
+
+> Read `PIPELINE.md` first: `contract` (mechanism/path — so §5 names the right schema types),
+> `design.enabled` (whether §8 matters), and §Conventions. Use `specs/_template.md` as the section list.
+>
+> Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
+> installed globally — read whichever exists.
+>
+> **Kanban** (SCHEMA.md §Kanban): when the spec opens, move card `#<feature_id>` → **Spec**; on freeze
+> (`status: frozen`, Mode A) → **Ready to build**. No-op silently if no board is configured.
+
+Detect the mode from the pasted content:
+
+## Mode A — new spec (input is a brainstorm return, or empty)
+
+1. If empty, ask the human to paste the brainstorm return (or describe the feature) and wait.
+2. Derive a `feature_id` (kebab-case slug). Confirm it.
+3. Walk the human through each section of `specs/_template.md`, **section by section**, with focused
+   questions. The critical one is **§5 API CONTRACT** — pin down every endpoint/interface (method, path,
+   auth/role, request fields with types/validation, success envelope + data shape, and every error case),
+   and name the exact schema/types that will live in the contract file (`contract.path/<id>.<ext>` in the
+   profile's `mechanism`). Don't move on until frontend and backend could each build from it with zero
+   further questions. _If `contract.enabled` is false, capture the interface precisely in prose instead._
+4. Fill **§8 Design brief** (only if `design.enabled` / the feature has UI) so it's self-contained for the
+   design step: screens, states, components, responsive notes.
+4b. **New-surface heads-up.** If the feature clearly introduces an area no existing `surfaces[].path`
+   owns (a new service/app/top-level module), note it in the spec (a line in the relevant task section:
+   `> needs new surface: <proposed key/path>`). Don't render agents here — `/build` §1.5 auto-reconciles
+   it. This is just so the human isn't surprised when `/build` proposes a new agent.
+5. When the human validates, **freeze**: write `specs/<id>.md` (`status: frozen`, front-matter filled).
+   Create the file — do not ask the human to. **Postcondition:** `grep -q '^status: frozen' specs/<id>.md`
+   — if it fails the freeze didn't land; fix it before pointing the human at `/build`.
+6. Emit the **spec return** — the §8 design brief rendered via `.claude/templates/design-brief.md`.
+   _Only if `design.enabled` / the feature has UI; skip entirely for a backend-only feature._
+   - **Write it to `specs/design/<id>.md`** (a standalone `.md`, versioned with the spec). Create the
+     file — do not ask the human to. Keep it in the `specs/design/` subfolder, **not** `specs/<id>....md`:
+     the `specs/*.md` glob that drives the kanban backfill and `/doctor` is non-recursive, so a brief in
+     the subfolder never gets mistaken for a spec (no phantom card, no bogus stage). This is a derived
+     artifact that mirrors §8 — overwrite it on every freeze so it never drifts from the spec.
+   - Then print the same content in a copy-paste block and tell the human: paste it into the design tool
+     (if any — typically a fresh design project for this feature) or just open `specs/design/<id>.md`,
+     then run `/build <id>` and hand its design gate the resulting page link(s) — a full
+     `https://claude.ai/design/p/<projectId>?file=<file>` link carries its own project + page, no profile
+     change needed. (They can also paste the links into the spec's `design_files`
+     themselves.) _The frozen spec + `specs/design/<id>.md` are the whole handoff — `/clear` before
+     `/build` is safe._
+
+## Mode B — review return (input is a REVIEW REPORT)
+
+1. Read the report — pasted as input, or (if the context was cleared) read from `specs/reports/<id>.md`,
+   where `/review` stages its last report. Identify `feature_id` from its header; open `specs/<id>.md`.
+2. Append each finding to the spec's **`## Remediation`**, one per line:
+   `- [ ] <severity> · <file:line> · <spec-violation|quality|security> · <concrete fix>`
+   (Keep prior items; add the new round under a dated/numbered subheading.)
+3. If a finding implies the **contract** must change, update §5 and flag it so the lead re-authors the
+   contract file.
+4. Set `status: in-review`. Tell the human to run `/build <id>` to re-dispatch fresh agents.
+   _The spec is the whole handoff — `/clear` before `/build` is safe._
+
+In both modes the spec is the single source of truth; agents are stateless and read only it + the diff.

package/core/commands/update-pipeline.md

@@ -0,0 +1,96 @@
+---
+description: Refresh the pipeline core (global ~/.claude, or a repo's bundled .claude) to the latest published cohorte version, then reconcile this repo's generated files to it — /init-pipeline stays one-time.
+argument-hint: [path-to-local-checkout]
+---
+
+You are the **pipeline updater**. Refresh the installed pipeline core to the latest version of the pipeline
+repo. The installer's `--update` mode never touches generated files: `PIPELINE.md`, rendered surface agents,
+`gate-config.json`, `settings.json`, and the filled `~/.claude/cohorte.config.yaml` are all preserved.
+YOU then bring those generated files up to the new core yourself (§3.5) — additively, never clobbering
+the human's choices — so `/init-pipeline` never needs re-running for an upgrade.
+
+## 1. Detect the install scope + current version
+
+- **Global** install ⇒ `~/.claude/pipeline/VERSION` exists. **Bundled** ⇒ this repo's
+  `.claude/pipeline/VERSION` exists. (Both can exist; prefer the bundled one when running inside such a
+  repo, and update both if the human wants.)
+- **Never migrate a repo between bundled and global mode on your own.** Updating means refreshing the
+  core *in its current mode*. Only migrate (e.g. delete a bundled core in favor of the global one) if
+  the human explicitly asks — and confirm before deleting anything, since it rewrites the repo's
+  committed `.claude/` and the `pipeline.json` pointer teammates rely on.
+- Read the VERSION file(s) — a semver like `0.1.0`, possibly suffixed `(abc1234)` for from-main
+  installs, or a bare commit hash on old cores. If missing, note "unknown (pre-versioning)".
+
+## 2. Run the update
+
+- If `$ARGUMENTS` is a path to a local checkout of the pipeline repo (contains `core/` + `install.sh`),
+  run from there — useful when iterating on the pipeline itself:
+
+  ```sh
+  sh <path>/install.sh --update --global     # global core
+  sh <path>/install.sh --update              # bundled core of the current repo
+  ```
+
+- Otherwise use the published npm package (preferred — installs the latest tagged release):
+
+  ```sh
+  npx cohorte@latest update --global   # global core
+  npx cohorte@latest update            # bundled core of the current repo
+  ```
+
+- If npm/npx is unavailable, fall back to piping the installer from the repo's latest `main`:
+
+  ```sh
+  curl -fsSL https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/install.sh | sh -s -- --update --global
+  # bundled:  … | sh -s -- --update
+  ```
+
+  (The piped installer clones the repo itself; `-s --` forwards the flags.)
+
+## 3. Report old → new
+
+Re-read the VERSION file(s) and print `old → new`. If unchanged, say the core was already up to date.
+For a bundled repo, note that `.claude/pipeline.json`'s `core_version` was bumped and should be committed.
+
+Then print **What's new**: read the installed `<core>/pipeline/CHANGELOG.md` and show the entries
+between the old and new versions (most recent first). File absent ⇒ the old core predates 0.1.14 —
+skip silently.
+
+## 3.5 Reconcile this repo's generated files
+
+Only when the current repo has a `PIPELINE.md`: run the **Reconcile procedure** from the installed
+`pipeline/SCHEMA.md` §Reconcile — top up the profile's machine block with new fields at their defaults
+(one batched question set for any genuinely new human decision, e.g. choosing a `retrieval` provider),
+re-render the surface agents from the current `implementer.template.md`, additively patch
+`settings.json`/`gate-config.json`, and run any newly-added capability's wiring (e.g. Serena's
+project-scope `claude mcp add`). Even when no capability is new, **re-run the retrieval provider's
+health check** (SCHEMA.md §Code retrieval: CLI resolvable from PATH, `.mcp.json` entry present —
+upgrading a bare `serena` entry to the PATH-proof launcher form, `.serena/` gitignored, server
+actually connected) and repair whatever fails — wiring that worked at
+init can rot (PATH changes, uninstalls, hand-edits). Report what was reconciled; if nothing was
+missing, say so. This is why `/init-pipeline` never needs re-running for a core upgrade.
+
+Two of the §Reconcile steps matter specifically here:
+
+- **Global config seed** (§Reconcile step 5): if `~/.claude/cohorte.config.yaml` is absent, seed it
+  from the template so the kanban + shared-vault config has a home. Never clobber an existing filled
+  file. Report what was seeded.
+- **Kanban sync** (§Reconcile step 6): resolve this project's board from `kanban.boards[<PIPELINE
+  name>]`. **Not linked** → offer to link/create a board (confirm the vault + `<folder>/Tasks.md`,
+  write the `boards` entry, create the board file per §Kanban). **Linked** → verify the board file
+  exists (recreate if the human confirms) and its columns match `kanban.columns` (repair drift). Either
+  way, run the §Kanban **full sync/backfill** from `specs/*.md` — this is what adds every
+  already-developed feature to the board and repositions cards to match each spec's `status`. Report
+  cards added / moved / already-correct. Skip silently if `kanban.enabled` is false and the human
+  doesn't want to turn it on.
+
+## 4. Tell the human the follow-ups
+
+- **Restart / reload the Claude Code session** so it picks up updated commands, agents, and any
+  newly-registered MCP server.
+- **Other repos using the global core:** their core is already fresh, but reconcile is per-repo — run
+  `/update-pipeline` inside each (it will skip the already-done core update and just reconcile).
+- **Commit** the reconciled files (`PIPELINE.md`, `.claude/`, `.mcp.json` if added) so teammates get them.
+- The kanban config is global and user-scoped
+  (`~/.claude/cohorte.config.yaml`) — never committed. The core update never touches it; only the
+  reconcile above seeds the file and writes kanban board links (into that global file, not the repo).

package/core/hooks/gate.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""PreToolUse gate — generic, profile-driven.
+
+Forces a confirmation prompt (or hard-denies) on dangerous Bash commands,
+inspecting the FULL command string so chained forms like
+`cd apps/api && node ace migration:run` are caught — something prefix-based
+permission rules in settings.json miss.
+
+Patterns come from `.claude/gate-config.json` (generated by /init-pipeline from
+the PIPELINE.md `gate` block):
+
+    { "deny": ["node ace migration:fresh", ...],
+      "ask":  ["git commit", "git push", "node ace migration:run", ...] }
+
+A pattern matches a command segment when the segment *contains* the pattern
+(after normalizing whitespace). `deny` wins over `ask`. If the config is missing
+or unreadable, the hook stays silent (exit 0) and lets settings.json decide.
+
+Protocol: reads the PreToolUse payload on stdin; emits a JSON permissionDecision
+of "deny" or "ask" on a match; otherwise exits 0 silently.
+"""
+
+import json
+import os
+import re
+import subprocess
+import sys
+
+SPLIT = re.compile(r"&&|\|\||[;|\n]")
+WS = re.compile(r"\s+")
+
+
+def load_config() -> dict:
+    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    path = os.path.join(root, ".claude", "gate-config.json")
+    empty = {"deny": [], "ask": [], "ask_on_default_branch": [], "default_branch": "main"}
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            cfg = json.load(fh)
+    except Exception:
+        return empty
+    return {
+        "deny": list(cfg.get("deny", [])),
+        "ask": list(cfg.get("ask", [])),
+        # Patterns gated ONLY on the default branch — allowed freely on feature branches.
+        "ask_on_default_branch": list(cfg.get("ask_on_default_branch", [])),
+        "default_branch": cfg.get("default_branch", "main") or "main",
+    }
+
+
+def norm(s: str) -> str:
+    return WS.sub(" ", s.strip())
+
+
+def current_branch():
+    """The checked-out branch of CLAUDE_PROJECT_DIR, or None (not a repo / detached / git absent)."""
+    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=root, capture_output=True, text=True, timeout=3,
+        )
+        if out.returncode == 0:
+            return out.stdout.strip() or None
+    except Exception:
+        pass
+    return None
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return 0  # malformed input → don't block
+
+    if payload.get("tool_name") != "Bash":
+        return 0
+
+    command = (payload.get("tool_input") or {}).get("command", "") or ""
+    cfg = load_config()
+    deny, ask, branch_gated = cfg["deny"], cfg["ask"], cfg["ask_on_default_branch"]
+    default = cfg["default_branch"]
+    if not deny and not ask and not branch_gated:
+        return 0
+
+    # Branch-conditional patterns (e.g. git/docker) are gated only on the default branch;
+    # on a feature branch they run freely. Unknown branch (no repo / detached / no git) ⇒
+    # be conservative and gate. Resolve the branch once, lazily.
+    on_default = False
+    if branch_gated:
+        branch = current_branch()
+        on_default = branch is None or branch == default
+
+    for raw in SPLIT.split(command):
+        seg = norm(raw)
+        if not seg:
+            continue
+        for pat in deny:
+            if norm(pat) in seg:
+                return decide("deny", f"`{pat}` is forbidden by the project's PIPELINE.md gate.")
+        for pat in ask:
+            if norm(pat) in seg:
+                return decide("ask", f"`{pat}` is a gated command — confirm first (PIPELINE.md gate).")
+        if on_default:
+            for pat in branch_gated:
+                if norm(pat) in seg:
+                    return decide("ask", f"`{pat}` is gated on the default branch `{default}` — confirm "
+                                         f"(PIPELINE.md gate). It runs freely on feature branches.")
+
+    return 0
+
+
+def decide(decision: str, reason: str) -> int:
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": decision,
+                    "permissionDecisionReason": reason,
+                }
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/core/templates/agent-handoff.md

@@ -0,0 +1,34 @@
+# HANDOFF — <surface> · `<feature_id>`
+
+Branch: <feature_branch_prefix><feature_id>
+Commit/diff base: <default_branch...HEAD or "uncommitted working tree">
+
+## Summary
+
+<2–4 lines: what you built and the approach>
+
+## Files touched
+
+- `path/to/file` — <what & why>
+
+## Migrations / schema (if any)
+
+- `<name>` — <additive change> · run with <PIPELINE.md commands.migrate>
+
+## Tests
+
+- Added: <test files>
+- Run: <this surface's test_cmd> · result: <pass/fail + counts>
+
+## Contract adherence
+
+- [ ] Implemented exactly to the frozen contract (`<contract.path>/<feature_id>.<ext>`)
+- Mismatches / assumptions: <none, or describe — DO NOT edit the contract; report instead>
+
+## Remediation addressed (fix loops only)
+
+- <which `## Remediation` items you fixed, by file:line>
+
+## TODO / not done
+
+- <anything deferred, blocked, or out of scope>

package/core/templates/brainstorm-return.md

@@ -0,0 +1,36 @@
+# BRAINSTORM RETURN — <feature title>
+
+> Paste this into `/spec`.
+
+**One-liner:** <what we're building, in one sentence>
+
+## Problem & value
+
+<the problem, who has it, why it matters>
+
+## Scope
+
+- **In:** <…>
+- **Out (non-goals):** <…>
+
+## Roles affected
+
+> Only if the profile has `rbac.enabled` — list the roles from `PIPELINE.md` §rbac and what each does;
+> explicitly note the lowest-privilege experience. Omit this section if there is no RBAC.
+
+<which roles do what>
+
+## Rough shape
+
+- **Data:** <entities / fields touched>
+- **Screens:** <key screens/flows — mobile-first if the project has UI>
+- **Interface (rough):** <endpoints / methods we'll need — refined into the contract in /spec>
+
+## Risks & open questions
+
+- <risk / unknown>
+- <open question for /spec to resolve>
+
+## Panel dissent (what was contested)
+
+<the strongest disagreement the panel surfaced — so /spec doesn't paper over it>

package/core/templates/design-brief.md

@@ -0,0 +1,35 @@
+# DESIGN BRIEF — <feature title> (`<feature_id>`)
+
+> The "spec return". Paste into the design tool (see `PIPELINE.md` §design). This is §8 of the frozen
+> spec, standalone — `/spec` writes it to `specs/design/<feature_id>.md` on freeze. Omit entirely if
+> the project has no UI.
+
+**Goal:** <one line — what the user accomplishes>
+
+**Design system:** use the existing UI kit (`PIPELINE.md` §design → `ui_kit_path`). Mobile-first.
+
+## Screens / views
+
+For each: purpose, who sees it (role, if RBAC), and the key elements.
+
+- **<screen name>** — <purpose> · roles: <…>
+  - Elements: <…>
+  - States: empty · loading · error · success
+
+## Flows
+
+<step-by-step of the main user journey, and any role-specific variation>
+
+## Responsive
+
+- Mobile (base): <layout>
+- Tablet (`md:`): <changes>
+- Desktop (`lg:`): <changes>
+
+## Data shown
+
+<what fields/values appear on screen — must match the contract in spec §5>
+
+## Notes / constraints
+
+<accessibility · copy in the profile's `ui_language` · edge cases · theming constraints>

package/core/templates/pr-body.md

@@ -0,0 +1,29 @@
+## <type>(<scope>): <feature title>
+
+**feature_id:** `<feature_id>` · closes/relates: <issue if any>
+
+### What & why
+
+<2–4 lines: what this ships and the value, from the spec goal>
+
+### Contract
+
+<the interface + contract types added/changed — from spec §5 (omit if contract.enabled is false)>
+
+### Changes
+
+> One bullet per surface (from `PIPELINE.md` §surfaces), plus the shared contract.
+
+- **<surface.key>:** <what changed>
+- **Shared:** `<contract.path>/<feature_id>.<ext>`
+
+### Tests
+
+- <per surface: test runner · coverage>
+- <PIPELINE.md commands.lint · typecheck · test> — green
+
+### Review
+
+Verdict: **SHIP** · remediation rounds: <n>
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)