agentic-team 0.0.0-stage → 6.2.0

package/template/commands/verifier.md

@@ -0,0 +1,53 @@
+Verify that implemented milestones match their requirements. PM role only.
+
+**Usage:**
+- `/orchestra:verifier` — verify all `done` milestones
+- `/orchestra:verifier 1,2,3` — verify only specified milestone numbers
+
+1. Read `.orchestra/roles/product-manager.md` to activate PM.
+2. Scan `.orchestra/milestones/` using Glob + Read tools (NOT bash scripts) — collect milestones to verify:
+   - No arguments: all milestones with `status: done`
+   - With numbers: only milestones matching those numbers (e.g., `1` matches `M1-*`)
+3. For each milestone, read:
+   - `prd.md` — product requirements and acceptance criteria
+   - `rfc.md` — technical design decisions (if exists)
+   - `milestone.md` — summary and acceptance criteria
+   - `grooming.md` — scope decisions and phase breakdown
+   - All `phases/*.md` — phase acceptance criteria
+4. For each milestone, read execution context:
+   - `decisions.md` — why specific approaches were chosen, and which were later closed
+   - `journal.md` — rejected alternatives, useful when a requirement shows as "deviated"
+   - `context.md` — `## Phases` section (which phases completed, which failed)
+5. For each milestone, read the actual implementation:
+   - Run `git log --oneline` filtered to commits from that milestone's phases
+   - Run `git diff` for those commits, piped through `.orchestra/scripts/compact-diff.awk`, to see what changed
+   - Read the current state of modified files — diff shows changes, but current code shows completeness
+6. Compare requirements vs implementation. For each requirement/acceptance criterion:
+   - **met** — implementation satisfies the requirement
+   - **partial** — partially implemented, missing aspects noted
+   - **missed** — not implemented at all
+   - **deviated** — implemented differently than specified
+6. Report:
+
+```
+## Verification: M1-user-auth
+
+### Requirements Coverage
+- ✅ met: JWT authentication endpoint (phase-1, commit abc123)
+- ⚠️ partial: Rate limiting — implemented but no Redis backing (phase-2)
+- ❌ missed: Password reset flow — not in any commit
+- 🔀 deviated: Token refresh — RFC said rotating tokens, implemented static expiry
+
+### Summary
+4 requirements: 1 met, 1 partial, 1 missed, 1 deviated
+
+### Severity
+- 🔴 critical: Password reset flow missing (core auth feature)
+- 🟡 moderate: Rate limiting without Redis (works but won't scale)
+- 🟡 moderate: Token refresh deviation (security concern)
+```
+
+8. After reporting all milestones, if there are critical or moderate gaps:
+   - List gaps grouped by severity
+   - Suggest: "Use `/orchestra:pm` to plan fix milestones for these gaps."
+   - Do NOT create milestones directly — PM decides scope and priority

package/template/hooks/audit-context.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# Two hook registrations share this one file — PreCompact writes, SessionStart
+# reads — because the finding they pass between them has to live somewhere in
+# between, and that somewhere is the only thing the two halves share: audit()
+# itself runs on PreCompact alone. A mechanical check that a milestone's
+# context.md is internally consistent, run right where a human stops watching
+# and a lead session risks losing the thread.
+#
+# PreCompact cannot block compaction — it is not in Claude Code's exit-code-2
+# table — and whether its own additionalContext reaches the model afterward
+# is undocumented. So this hook never tries to stop or steer compaction: on
+# PreCompact it only writes findings to a per-session scratch file.
+# SessionStart's "compact" matcher is documented and fires right after
+# compaction lands, so that is where the findings actually reach the model —
+# this is advisory, never a block, and it never writes to context.md itself:
+# status stays lead's to advance and the human's to move, per
+# tracker-authority.orchestra.md.
+#
+# The scratch file is keyed by session_id, the same way enforce-role.sh keys
+# its role marker: two terminals are two sessions, and a single shared file
+# would let one session's compaction findings surface on the other's
+# SessionStart — a real cross-session leak in the two-terminal model this
+# project runs by design.
+#
+# Reads the hook call on stdin. Always exits 0.
+set -euo pipefail
+
+input="$(cat)"
+
+printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" node -e '
+  const fs = require("node:fs");
+  const path = require("node:path");
+
+  // Advisory findings are stale past this; a run that never reached
+  // SessionStart (crash, a long gap before the next prompt) should not
+  // surface an old result as if it just happened. Not project-configurable
+  // like thresholds.stuck_retry_limit: this is a display window for
+  // informational text, not a gate anything can fail.
+  const STALE_MS = 10 * 60 * 1000;
+
+  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 root = process.env.CLAUDE_PROJECT_DIR;
+    const auditPath = path.join(root, ".orchestra", ".sessions", `${session}.context-audit.json`);
+    const milestonesDir = path.join(root, ".orchestra", "milestones");
+
+    function audit() {
+      const findings = [];
+      const open = [];
+      let entries = [];
+      try {
+        entries = fs.readdirSync(milestonesDir, { withFileTypes: true });
+      } catch {
+        return { findings, open };
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        let text;
+        try {
+          text = fs.readFileSync(path.join(milestonesDir, entry.name, "context.md"), "utf8");
+        } catch {
+          continue;
+        }
+        // Anchored to a line start (not a stray "### Phases" or a mention
+        // inside prose) via lookaround rather than the "m" flag, which would
+        // also redefine "$" to mean end-of-line and cut the capture short at
+        // the very first line break instead of the next real section.
+        const section = /(?:^|\r?\n)## Phases\r?\n([\s\S]*?)(?=\r?\n## |$)/.exec(text);
+        const body = section ? section[1] : "";
+        for (const line of body.split(/\r?\n/)) {
+          const m = /^-\s*(\S+):\s*(done|in-progress|failed|pending|blocked)\b/i.exec(line.trim());
+          if (!m) continue;
+          const [, phase, statusRaw] = m;
+          const status = statusRaw.toLowerCase();
+          if (status === "done" && !/commit:\s*\S+/.test(line)) {
+            findings.push(`${entry.name}/${phase}: marked done with no commit hash`);
+          } else if (status !== "done") {
+            open.push(`${entry.name}/${phase}: ${status}`);
+          }
+        }
+      }
+      // decisions.md: one source for what a valid line is — the script that
+      // writes it — rather than a second parser here that drifts from it.
+      const script = path.join(root, ".orchestra", "scripts", "context.mjs");
+      if (fs.existsSync(script)) {
+        try {
+          require("node:child_process").execFileSync(process.execPath, [script, "check"], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+          });
+        } catch (e) {
+          for (const f of String(e.stdout || "").split("\n").filter(Boolean)) findings.push(f);
+        }
+      }
+      return { findings, open };
+    }
+
+    if (call.hook_event_name === "PreCompact") {
+      const result = audit();
+      result.at = new Date().toISOString();
+      try {
+        const sessionsDir = path.dirname(auditPath);
+        fs.mkdirSync(sessionsDir, { recursive: true });
+        // The installer writes this once at setup time, but this hook must
+        // not depend on that having happened — the directory it just
+        // created above needs its own ignore rule, not an assumption that
+        // setup already put one there.
+        const ignorePath = path.join(sessionsDir, ".gitignore");
+        if (!fs.existsSync(ignorePath)) fs.writeFileSync(ignorePath, "*\n!.gitignore\n");
+        fs.writeFileSync(auditPath, JSON.stringify(result));
+      } catch {
+        // Advisory only: a write failure here is not worth surfacing.
+      }
+      return;
+    }
+
+    // The "compact" filter lives in settings.json'"'"'s matcher for this
+    // registration, not here: the exact stdin field naming that trigger is
+    // undocumented, so this branch trusts the registration to have already
+    // scoped it rather than re-checking a field name that might be wrong.
+    if (call.hook_event_name === "SessionStart") {
+      let result;
+      try {
+        result = JSON.parse(fs.readFileSync(auditPath, "utf8"));
+      } catch {
+        return;
+      }
+      // A missing or unparseable timestamp must read as stale, not as
+      // "not old enough to discard" — Date.parse(undefined) is NaN, and
+      // NaN > STALE_MS is false, which would otherwise treat a corrupted
+      // write as always-fresh.
+      const at = result.at ? Date.parse(result.at) : Number.NaN;
+      if (Number.isNaN(at) || Date.now() - at > STALE_MS) return;
+
+      const lines = [];
+      if (result.findings && result.findings.length) {
+        lines.push("Context audit after compaction — the milestone record has unresolved defects:");
+        for (const f of result.findings) lines.push(`  - ${f}`);
+      }
+      if (result.open && result.open.length) {
+        lines.push("Open phases across milestones:");
+        for (const o of result.open) lines.push(`  - ${o}`);
+      }
+      if (!lines.length) return;
+
+      // Native Claude Code reads SessionStart'"'"'s stdout as plain text, not the
+      // hookSpecificOutput JSON form other hosts (Codex, Qoder) need for it —
+      // confirmed against a production implementation (ponytail'"'"'s
+      // hooks/ponytail-runtime.js), since the official docs never showed a
+      // literal example either way.
+      process.stdout.write(lines.join("\n"));
+    }
+  });
+'
+exit 0

package/template/hooks/enforce-role.sh

@@ -0,0 +1,193 @@
+#!/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.
+#
+# Lead is held to one rule: phase work starts inside a milestone agent.
+#
+# 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;
+    }
+    // ── Lead ─────────────────────────────────────────────────────────────
+    // Phase work runs inside a milestone agent, so each milestone'"'"'s context is
+    // dropped when it ends. One run kept two milestones in the lead session
+    // instead: 738 calls, context up to 925k tokens. A call from a sub-agent
+    // carries agent_id; one from the lead session itself does not.
+    if (role === "lead") {
+      if (tool !== "Agent" || call.agent_id) return;
+      const type = input.subagent_type || "";
+      if (!/^(engineer-\w+|reviewer|re-reviewer)$/.test(type)) return;
+      if (/^engineer-/.test(type) && /^\s*Hotfix:/.test(String(input.prompt || ""))) return;
+      process.stdout.write(
+        `Lead runs phase work inside a milestone agent, not in its own session — launch a general-purpose agent with the Milestone Agent or Single-Phase Agent prompt in .claude/agents/lead.md, and let it start ${type}. A hotfix engineer'"'"'s prompt starts with a line "Hotfix: <description>".\n`,
+      );
+      return;
+    }
+
+    if (role !== "product-manager") return;
+
+    // ── The PM ───────────────────────────────────────────────────────────
+    // Writes milestones. Commits them to delivery.base_branch 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 delivery.base_branch 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 delivery.base_branch.");
+    }
+    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 agentic-team 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 agentic-team 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