agentic-team 0.0.0-stage → 6.1.0

package/template/hooks/enforce-role.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# PreToolUse guard: a session that declared a role stays inside it.
+#
+# `.claude/rules/role-boundaries.orchestra.md` says the PM writes only under
+# `.orchestra/milestones/` and never opens a branch or a pull request. That
+# was prose, and a PM opened a pull request anyway. A rule nothing checks is
+# advice.
+#
+# The hook could not know the role — a slash command is a markdown prompt and
+# exports nothing. So the role command has the agent run one Bash line,
+# `true # orchestra-role=product-manager`, and this hook, which sees every
+# Bash call together with the session id Claude Code hands it, records the
+# pair under `.orchestra/.sessions/`. Every later call in that session is
+# judged against the recorded role. Two terminals are two sessions, so the
+# PM's marker never applies to lead.
+#
+# No marker means no role — discussion mode — and nothing is blocked.
+#
+# Reads the tool call on stdin. Exit 0 allows, exit 2 blocks.
+set -euo pipefail
+
+input="$(cat)"
+
+verdict="$(printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" node -e '
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const { execFileSync } = require("node:child_process");
+
+  let s = "";
+  process.stdin.on("data", (d) => (s += d)).on("end", () => {
+    let call;
+    try {
+      call = JSON.parse(s);
+    } catch {
+      // Optional by design: an unparseable call is not ours to judge.
+      return;
+    }
+    const session = String(call.session_id || "").replace(/[^A-Za-z0-9._-]/g, "");
+    if (!session) return;
+    const tool = call.tool_name || "";
+    const input = call.tool_input || {};
+
+    let root;
+    try {
+      root = execFileSync("git", ["-C", process.env.CLAUDE_PROJECT_DIR, "rev-parse", "--show-toplevel"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      return;
+    }
+    if (!root) return;
+    // Both sides through realpath: on macOS a temp dir is /var/… while git
+    // answers /private/var/…, and path.relative between them says "outside".
+    const real = (p) => { try { return fs.realpathSync(p); } catch { return p; } };
+    root = real(root);
+    const projectDir = real(process.env.CLAUDE_PROJECT_DIR);
+    // A path that does not exist yet — a file about to be written — is
+    // resolved through its nearest existing ancestor, so an absolute path
+    // spelled with the unresolved prefix still lands inside the repo.
+    const relTo = (p) => {
+      let abs = path.resolve(projectDir, p);
+      let head = abs;
+      let tail = "";
+      while (!fs.existsSync(head) && path.dirname(head) !== head) {
+        tail = path.join(path.basename(head), tail);
+        head = path.dirname(head);
+      }
+      abs = path.join(real(head), tail);
+      return path.relative(root, abs);
+    };
+
+    const dir = path.join(root, ".orchestra", ".sessions");
+    const marker = path.join(dir, session);
+
+    // The declaration. Recorded, then allowed through.
+    if (tool === "Bash") {
+      const m = /orchestra-role=(product-manager|orchestrator|lead)\b/.exec(input.command || "");
+      if (m) {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(marker, m[1]);
+        return;
+      }
+    }
+
+    let role;
+    try {
+      role = fs.readFileSync(marker, "utf8").trim();
+    } catch {
+      return;
+    }
+    if (role !== "product-manager") return;
+
+    // ── The PM ───────────────────────────────────────────────────────────
+    // Writes milestones. Commits them to main and pushes. Nothing else.
+    const deny = (why) => {
+      process.stdout.write(`Outside the PM'"'"'s scope: ${why}\n`);
+    };
+
+    if (tool === "Write" || tool === "Edit") {
+      const file = input.file_path || input.path || "";
+      if (!file) return;
+      const rel = relTo(file);
+      if (rel.startsWith("..")) return deny(`${file} is outside the repository`);
+      if (!rel.startsWith(".orchestra/milestones/")) {
+        return deny(`the PM writes only under .orchestra/milestones/ — ${rel} is not there. Say what needs changing and which command can do it.`);
+      }
+      return;
+    }
+
+    if (tool === "Workflow") {
+      return deny("the PM never runs a workflow. A code review is lead'"'"'s, on the pull request; a plan review is the milestone-reviewer agent.");
+    }
+    if (tool === "Agent") {
+      const type = input.subagent_type || "";
+      if (type !== "milestone-reviewer" && type !== "tracker") {
+        return deny(`the PM launches only milestone-reviewer and tracker — not ${type || "a general-purpose agent"}. Reviewing code, building, and scouting are lead'"'"'s.`);
+      }
+      return;
+    }
+    if (/clickup_(create|update)_task$/.test(tool)) {
+      const status = String(input.status ?? "").trim();
+      if (!status) return;
+      // The tracker agent runs inside the PM'"'"'s session and lands a new task
+      // in backlog — the one status write the PM side is allowed. Read the
+      // board'"'"'s own name for it from config, compared case-insensitively.
+      let backlog = "backlog";
+      try {
+        const cfg = fs.readFileSync(path.join(root, ".orchestra", "config.yml"), "utf8");
+        const m = /^\s*backlog:\s*["'"'"']?([^"'"'"'#\n]+)/m.exec(cfg);
+        if (m) backlog = m[1].trim();
+      } catch {
+        // No config: the default name is the only name we know.
+      }
+      if (status.toLowerCase() === backlog.toLowerCase()) return;
+      return deny(`the PM never sets a task'"'"'s status — export lands it in backlog, lead advances it, the human moves it. Drop status: ${JSON.stringify(status)}.`);
+    }
+
+    if (tool !== "Bash") return;
+    const cmd = input.command || "";
+
+    if (/\bgh\s+pr\s+(create|merge|edit|close|ready|checkout)\b/.test(cmd)) {
+      return deny("the PM never opens, edits or merges a pull request. Milestone files go to main directly; code is lead'"'"'s.");
+    }
+    if (/\bgit\s+(checkout|switch)\s+(-b|-c|--create|-B)\b/.test(cmd)) {
+      return deny("the PM never creates a branch. Milestone files are committed to main.");
+    }
+    if (/\bgit\s+(merge|rebase|cherry-pick|reset\s+--hard)\b/.test(cmd)) {
+      return deny("the PM never rewrites history or merges.");
+    }
+    if (/\bgit\s+push\b.*(\s--force\b|\s-f\b|\s--force-with-lease\b)/.test(cmd)) {
+      return deny("the PM never force-pushes.");
+    }
+    if (/\bgit\s+commit\b[^&|;]*\s(?:-[a-zA-Z]*a[a-zA-Z]*|--all)\b/.test(cmd)) {
+      return deny("`git commit -a` stages everything. Add .orchestra/milestones/ explicitly, then commit.");
+    }
+    const add = /\bgit\s+add\s+(.+?)(?:\s*(?:&&|\|\||;|$))/.exec(cmd);
+    if (add) {
+      const args = add[1].split(/\s+/).filter((a) => a && !a.startsWith("-"));
+      const outside = args.filter((a) => {
+        const rel = relTo(a.replace(/^["'"'"']|["'"'"']$/g, ""));
+        return !rel.startsWith(".orchestra/milestones");
+      });
+      if (args.length === 0 || outside.length) {
+        return deny(`the PM stages only .orchestra/milestones/ — not ${outside.join(", ") || "-A / ."}.`);
+      }
+    }
+  });
+')"
+
+if [ -n "$verdict" ]; then
+  printf '%s\n' "$verdict" >&2
+  exit 2
+fi
+exit 0

package/template/hooks/protect-system-files.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# PreToolUse guard: never edit installed Orchestra system files in place.
+#
+# `.claude/rules/role-boundaries.orchestra.md` lists files no project role
+# owns. The check is not "which role is running": a slash command is a
+# markdown prompt and cannot export anything a hook could read, so any guard
+# built on that premise would never fire. The reliable question is *which repo
+# this is*, and then *did Orchestra put this file here*.
+#
+# The second half used to be a list of globs, which was wrong in both
+# directions. It blocked `.orchestra/config.yml`, which the installer merges
+# rather than overwrites and which `/orchestra:setup` is documented to write.
+# It blocked every `.claude/skills/*/SKILL.md`, including the ones
+# docs/skills.md tells the user to create, and including a stack's own
+# `apps/<name>/.claude/` pack. And a relative file_path matched none of the
+# patterns, so it sailed straight through.
+#
+# `.orchestra/.installed.json` records what was installed, so the question has
+# an answer instead of an approximation.
+#
+# Reads the tool call on stdin. Exit 0 allows, exit 2 blocks.
+set -euo pipefail
+
+input="$(cat)"
+
+blocked="$(printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" node -e '
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const { execFileSync } = require("node:child_process");
+
+  let s = "";
+  process.stdin.on("data", (d) => (s += d)).on("end", () => {
+    let file;
+    try {
+      const i = JSON.parse(s).tool_input || {};
+      file = i.file_path || i.path || "";
+    } catch {
+      // Optional by design: an unparseable call is not ours to judge.
+      return;
+    }
+    if (!file) return;
+
+    // A relative path used to match no pattern at all, which made the guard
+    // depend on how the caller happened to spell it.
+    const abs = path.resolve(process.env.CLAUDE_PROJECT_DIR, file);
+
+    let root;
+    try {
+      root = execFileSync("git", ["-C", path.dirname(abs), "rev-parse", "--show-toplevel"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      // Not in a repository: nothing here is an installed copy.
+      return;
+    }
+    if (!root) return;
+
+    // The orchestrator repo is where these files are source. That is a fact
+    // about the tree, not about who is asking.
+    if (fs.existsSync(path.join(root, "bin/build-template.js"))) return;
+
+    // git reports the real path and path.resolve does not, so on any system
+    // where the tree sits under a symlink — /var on macOS, a linked worktree
+    // — the two disagree and every comparison below silently misses.
+    let existing = path.dirname(abs);
+    while (!fs.existsSync(existing) && existing !== path.dirname(existing)) {
+      existing = path.dirname(existing);
+    }
+    const real = path.join(fs.realpathSync(existing), path.relative(existing, abs));
+    const rel = path.relative(fs.realpathSync(root), real).split(path.sep).join("/");
+    if (rel.startsWith("..")) return;
+
+    // config.yml is merged on upgrade, so an edit survives; setup writes its
+    // verification keys, which .orchestra/README.md documents.
+    if (rel === ".orchestra/config.yml") return;
+
+    const manifestPath = path.join(root, ".orchestra/.installed.json");
+    if (fs.existsSync(manifestPath)) {
+      let files = null;
+      try {
+        files = JSON.parse(fs.readFileSync(manifestPath, "utf8")).files;
+      } catch {
+        // Fall through to the patterns below rather than allowing everything.
+      }
+      if (Array.isArray(files)) {
+        if (files.includes(rel)) process.stdout.write(abs);
+        return;
+      }
+    }
+
+    // Installed before the manifest existed. Approximate, and deliberately
+    // narrower than the old list: skills and roles are left out because
+    // without a manifest a users own cannot be told from a shipped one, and
+    // blocking theirs is the worse mistake.
+    const legacy = [
+      /^\.orchestra\/stacks\//,
+      /^\.orchestra\/README\.md$/,
+      /^\.claude\/agents\//,
+      /^\.claude\/rules\/.*\.orchestra\.md$/,
+      /^\.claude\/commands\/orchestra\//,
+    ];
+    if (legacy.some((re) => re.test(rel))) process.stdout.write(abs);
+  });
+' 2>/dev/null || true)"
+
+[ -n "$blocked" ] || exit 0
+
+cat >&2 <<MSG
+Blocked: ${blocked}
+
+This is an installed Orchestra system file — .orchestra/.installed.json says
+Orchestra put it there. Editing it here is lost work: the next upgrade
+overwrites it, and the next project meets the same problem you were about to
+fix.
+
+Change it in the orchestrator repo and reinstall. If it is genuinely
+project-specific, it belongs in the app's own CLAUDE.md, a project skill of
+your own, or .orchestra/config.yml — none of which is overwritten.
+
+See .claude/rules/role-boundaries.orchestra.md.
+MSG
+exit 2

package/template/hooks/review-rounds.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# PreToolUse guard: a phase gets at most `thresholds.stuck_retry_limit`
+# review rounds, then a person decides.
+#
+# The cap was prose in lead.md, and a run went nine rounds on one phase
+# because the user's "loop until no high or medium remains" read as
+# overriding it. Each round found a new hole in the previous round's fix, so
+# nothing inside the loop could end it. Counting is the one part a machine
+# can do, so it is done here.
+#
+# A reviewer launch names its phase on a line
+# `Phase: <milestone directory>/<phase file name>`, and that file must exist
+# under .orchestra/milestones/ — a second spelling of the same phase would
+# start a fresh count. Lead must name it; any other session may leave it
+# out, uncounted, so a one-off review in discussion mode is never refused.
+#
+# The count lives in .orchestra/.sessions/review-rounds.json, keyed by phase
+# rather than by session, so a restarted lead does not start from zero, and
+# the installer keeps it across upgrades. Past the cap the launch is refused
+# until the prompt quotes the user's approval on a line
+# `Extra round approved by the user: …` — each launch past it carries its own
+# line, so one approval buys one round. Nothing
+# can check that the quote is real; it is honest by convention, like the
+# escape-hatch comments the policy check reads.
+#
+# Reads the tool call on stdin. Exit 0 allows, exit 2 blocks.
+set -euo pipefail
+
+input="$(cat)"
+
+verdict="$(printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" node -e '
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const { execFileSync } = require("node:child_process");
+
+  let s = "";
+  process.stdin.on("data", (d) => (s += d)).on("end", () => {
+    let call;
+    try {
+      call = JSON.parse(s);
+    } catch {
+      // Optional by design: an unparseable call is not ours to judge.
+      return;
+    }
+    if (call.tool_name !== "Agent") return;
+    const input = call.tool_input || {};
+    if (input.subagent_type !== "reviewer") return;
+    const prompt = String(input.prompt || "");
+
+    // The installer writes into the directory it ran in, which can be an app
+    // inside a larger repository, so the project directory comes first.
+    let root = process.env.CLAUDE_PROJECT_DIR;
+    if (!fs.existsSync(path.join(root, ".orchestra"))) {
+      try {
+        root = execFileSync("git", ["-C", root, "rev-parse", "--show-toplevel"], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+      } catch {
+        return;
+      }
+    }
+    const milestones = path.join(root, ".orchestra", "milestones");
+    // Not an Orchestra project here: nothing to count against.
+    if (!root || !fs.existsSync(milestones)) return;
+    const dir = path.join(root, ".orchestra", ".sessions");
+
+    const phase = /^[ \t]*Phase:[ \t]*(\S[^\n]*?)[ \t]*$/m.exec(prompt);
+    if (!phase) {
+      const session = String(call.session_id || "").replace(/[^A-Za-z0-9._-]/g, "");
+      let role = "";
+      try {
+        role = session ? fs.readFileSync(path.join(dir, session), "utf8").trim() : "";
+      } catch {
+        // No marker: not a lead session, so an uncounted review is allowed.
+      }
+      if (role === "lead") {
+        process.stdout.write("A reviewer launch from lead names its phase on a line `Phase: <milestone directory>/<phase file name>`, so its review rounds can be counted.\n");
+      }
+      return;
+    }
+    const key = phase[1];
+    // Exactly two segments, matched by listing rather than by existsSync: a
+    // trailing slash, a third segment or a change of case on a
+    // case-insensitive disk would each name the same file under a new key.
+    const parts = key.split("/");
+    const listed = (d, name) => {
+      try {
+        return fs.readdirSync(d).includes(name);
+      } catch {
+        return false;
+      }
+    };
+    if (parts.length !== 2 || !listed(milestones, parts[0]) || !listed(path.join(milestones, parts[0], "phases"), `${parts[1]}.md`)) {
+      process.stdout.write(`Phase: ${key} names no file .orchestra/milestones/<milestone>/phases/<phase>.md. Spell it as the directory and the file name, e.g. Phase: M2-design-system/phase-3 — another spelling would start a fresh count.\n`);
+      return;
+    }
+
+    let cap = 3;
+    try {
+      const cfg = fs.readFileSync(path.join(root, ".orchestra", "config.yml"), "utf8");
+      const m = /^\s*stuck_retry_limit:\s*(\d+)/m.exec(cfg);
+      if (m) cap = Number(m[1]);
+    } catch {
+      // No config: the documented default is the only cap we know.
+    }
+
+    // Parallel phases launch reviewers at once. Without the lock two reads
+    // see the same count and one increment is lost; without the rename a
+    // reader can meet a half-written file and start every phase from zero.
+    fs.mkdirSync(dir, { recursive: true });
+    const lock = path.join(dir, "review-rounds.lock");
+    const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    const deadline = Date.now() + 5000;
+    for (;;) {
+      try {
+        fs.mkdirSync(lock);
+        break;
+      } catch (e) {
+        if (e.code !== "EEXIST") throw e;
+        try {
+          // A launch holds the lock for milliseconds, so one older than this
+          // was left by a crash; shorter than the wait, so it clears in time.
+          if (Date.now() - fs.statSync(lock).mtimeMs > 3000) fs.rmdirSync(lock);
+        } catch {
+          // Another launch released or cleared it first; try again.
+        }
+        if (Date.now() > deadline) {
+          process.stdout.write("The review-round count is locked by another launch. Launch the reviewer again.\n");
+          return;
+        }
+        sleep(25);
+      }
+    }
+    try {
+      const file = path.join(dir, "review-rounds.json");
+      let counts = {};
+      try {
+        counts = JSON.parse(fs.readFileSync(file, "utf8"));
+      } catch {
+        // First reviewer launch in this project, or a file someone deleted:
+        // both mean no rounds recorded yet.
+      }
+      const done = counts[key] || 0;
+      const approved = /^[ \t]*Extra round approved by the user:[ \t]*\S/m.test(prompt);
+      if (done >= cap && !approved) {
+        process.stdout.write(
+          `Review round ${done + 1} for ${key} is past thresholds.stuck_retry_limit (${cap}). ` +
+          "Stop and give the user the open Blocking and Important findings. Under --auto, set the task blocked with a comment naming them. " +
+          "If the user approves another round, quote them on a line `Extra round approved by the user: …`.\n",
+        );
+        return;
+      }
+      counts[key] = done + 1;
+      const tmp = `${file}.${process.pid}`;
+      fs.writeFileSync(tmp, `${JSON.stringify(counts, null, 2)}\n`);
+      fs.renameSync(tmp, file);
+    } finally {
+      try {
+        fs.rmdirSync(lock);
+      } catch {
+        // Already cleared as stale by a waiter; there is nothing left to release.
+      }
+    }
+  });
+')"
+
+if [ -n "$verdict" ]; then
+  printf '%s\n' "$verdict" >&2
+  exit 2
+fi
+exit 0

package/template/rules/acceptance-check.orchestra.md

@@ -0,0 +1,11 @@
+# Acceptance Check
+
+After implementation, check whether you built **the right thing** — not just whether it works.
+
+1. Re-read the phase file's acceptance criteria
+2. For EACH criterion: "Does my implementation satisfy this?"
+3. If YES → proceed
+4. If NO → fix it
+5. If UNCERTAIN → flag: "Unverified: {criterion} — {reason}"
+
+This catches "code works but doesn't do what was asked."

package/template/rules/analytics-kpi.orchestra.md

@@ -0,0 +1,56 @@
+# Analytics & KPIs
+
+**Mandatory.** A milestone that cannot state how its success is measured is
+not ready to build.
+
+## KPIs come before code
+
+Every milestone declares, in `milestone.md`, before implementation starts:
+
+- **The metric** — one primary number this work is meant to move
+- **The baseline** — what it is today, or explicitly "unknown, this
+  establishes it"
+- **The target** — the number that would make this worth having built
+- **How it is read** — the query, dashboard, or event that produces it
+
+If you cannot fill these in, the milestone is a guess. Say so to the user
+rather than building it and finding out later.
+
+A metric that cannot go down is not a KPI. "Number of features shipped"
+measures activity, not outcome.
+
+## Events
+
+Instrument the user's action, at the point it happens. An event fired from
+a wrapper three layers away eventually fires for the wrong reason.
+
+- **Naming** is consistent and boring: `object_action` — `checkout_started`,
+  `signup_completed`. Pick the convention once, never mix styles.
+- **Typed and centralised.** Event names and payload shapes live in one
+  schema module per app, and instrumentation imports from it. A string
+  literal at a call site is how analytics quietly rots.
+- **No PII in properties.** No email, no name, no free-text the user typed.
+  Identify with a stable anonymous id.
+- **Respect consent.** Where consent is required, no event leaves the device
+  until it is given. This is not a preference.
+
+## Every screen and every failure
+
+- Each screen or route reports a view event.
+- Each critical flow reports start, success, **and failure** — with a reason
+  code. A funnel that only records success cannot tell you why people left,
+  which is the only thing you actually wanted to know.
+
+## Verifying
+
+Instrumentation is code, so it is tested like code: assert the event fires
+once, with the right name and shape. An analytics call is exactly the kind
+of third-party seam the testing rule exists to cover.
+
+Before a milestone closes, confirm the events actually arrived. Untested
+instrumentation is usually broken instrumentation.
+
+## Defaults
+
+PostHog. A default, not a mandate — substitute freely, but the capability
+is required. Configure under `observability` in `.orchestra/config.yml`.

package/template/rules/code-standards.orchestra.md

@@ -0,0 +1,34 @@
+# Code Standards
+
+**SOLID** — Single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion. Open/closed and dependency inversion earn their place once a second real consumer needs the seam — see DRY below. Built before that consumer exists, they are over-engineering wearing a principle's name.
+
+**KISS** — Keep it simple. Don't over-engineer.
+
+**YAGNI** — Don't build what you don't need right now.
+
+**DRY** — Don't repeat yourself. Extract after second duplication, not before. The same rule covers an interface, a seam, or an injection point built for open/closed or dependency inversion: add it when a second real caller needs it, never for a hypothetical one.
+
+**Before writing code, stop at the first rung that holds:**
+1. Does this need to exist? → no: skip it (YAGNI)
+2. Already in this codebase? → reuse it
+3. Stdlib does it? → use it
+4. Native platform feature? → use it
+5. Installed dependency? → use it directly
+6. One line? → one line
+7. Only then: the minimum that works
+
+This governs volume, never correctness. Validation, error handling, security
+and accessibility are never on this ladder — they apply at every rung,
+covered by their own rules (`security.orchestra.md`,
+`observability.orchestra.md`, the `accessibility` skill), regardless of how
+small the change looks. Rung 5 does not skip the wrapper
+`testing-standards.orchestra.md` requires for anything calling a third-party
+library (`src/integrations/<provider>/`) — that wrapper exists for the seam
+test, not for swapability, and the ladder governs what sits on top of it,
+never whether it exists.
+
+**Zero-tolerance rules:**
+- No workarounds — if the right solution is hard, do it right. Flag effort in report or context.md.
+- No unused code — delete dead imports, functions, files. Don't comment out.
+- No breaking changes without migration — update every consumer.
+- Current library versions only — verify before using, don't assume from memory.

package/template/rules/comments.orchestra.md

@@ -0,0 +1,77 @@
+# Comments
+
+Default to no comment.
+
+A comment explains *why*, never *what*. The "what" is the job of naming: if
+a comment is needed to say what the code does, rename or extract instead.
+The test — would a reviewer ask *why* here? Then comment. Would they only
+ask *what*? Then rename.
+
+Write one only for:
+
+- a workaround or constraint imposed from outside — bundler, driver, API
+  quirk — linking the upstream issue when one exists
+- a non-obvious invariant the reader cannot derive locally
+- a deliberate trade-off, including "do not simplify this to X" where X
+  looks tempting and is wrong
+
+When a comment is warranted, write the single most accurate sentence you
+can, and stop. It has to close the question, not open new ones: name the
+consequence or the rejected alternative, not the restated rule. If a reader
+would still ask *why* after reading it, the sentence is not finished.
+
+Never: restating the next line, section banners, commented-out code, a
+comment duplicating a test name. Put it above the line it guards, not
+trailing a long line.
+
+## Some comments are read by the gate
+
+Two checks in `scripts/policy-check.mjs` clear on a comment — `await-in-loop`
+on one above the loop, `swallowed-error` on one inside the catch. Those are
+not prose for a reviewer; they are the escape hatch, and deleting one as
+noise turns the gate red.
+
+They are also exactly the *why* this rule asks for: which of the sequential
+cases this loop is, why failure on this path is acceptable. `// ok` clears
+the check and tells the next reader nothing — that is a review finding, not
+a pass.
+
+`.claude/rules/security.orchestra.md` asks for the same shape beside a
+security setting: the value taken and where it came from.
+
+## A TODO is a tech debt that skipped the tracker
+
+`.claude/rules/tracker-authority.orchestra.md` gives a workaround a home: a
+`tech_debt` task naming what should have been done instead. A TODO is that
+task written where nobody will find it.
+
+So a TODO carries the task — `TODO(#123)`, `TODO(CU-86abc)`, or a link — and
+the task carries the reason. With `tracker.provider: none` there is no task,
+so there is no TODO: do the work, or report it in the phase result as left
+undone.
+
+## Doc comments
+
+JSDoc, KDoc, Swift `///` — one rule for all three. Not mandatory. Add one
+only when it says something the signature cannot.
+
+Never restate the signature: no `@param value - the value`, no `@returns
+the result`, no "this function does X" above a function named X.
+`@deprecated` always earns its place — name the replacement.
+
+## While editing
+
+Delete a restating comment on a line you are already changing. Leave the
+rest — `.claude/rules/phase-limits.orchestra.md` applies, and a comment
+sweep is not the phase.
+
+## What is enforced
+
+Only what can be decided precisely. A restating comment cannot be — a
+machine cannot tell "increment the counter" from a reason — so it stays a
+review item above.
+
+| Check | Fails on |
+|---|---|
+| `commented-out-code` | a `//` line that parses as a statement |
+| `todo-without-task` | `TODO`, `FIXME`, `HACK`, `XXX` with no task id or link |

package/template/rules/commit-format.orchestra.md

@@ -0,0 +1,20 @@
+# Commit Format
+
+All commits MUST use conventional commit format.
+
+**Format:** `<type>(<scope>): <description>`
+
+**Types:** feat, fix, refactor, perf, test, chore, docs, style, ci, build, revert
+
+**Rules:**
+- Each phase produces exactly ONE commit
+- Subject line max 72 characters
+- Body explains WHY, not WHAT
+- Breaking changes add `!` after type: `feat!(scope): description`
+- No `Co-Authored-By` trailers — never add co-author lines
+
+**The one exception is a squashed task pull request.** Its subject is
+`#<task-id> - <subject>`, because that is where the tracker's link lives and a
+task PR collapses several conventional commits into one. The `commit-msg` hook
+accepts that shape and nothing else outside the convention — see
+`.claude/rules/pull-request.orchestra.md`.