@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/agent-guard.py

@@ -2,18 +2,41 @@
 """Decision core for agent-guard.sh (see that file for the hook contract).
 
 Reads the PreToolUse payload JSON on stdin and prints exactly one decision:
-  BLOCK_ATTRIB | BLOCK_FORCE | OK
+  BLOCK_ATTRIB | BLOCK_FORCE | BLOCK_UNATTENDED<TAB>reason | BLOCK_PARSE | OK
 
 Never executes the command. shlex.split only tokenizes shell-like text; a
-`$(...)` in the command is a literal token, never a subshell. Any error prints
-OK (fail-open) so a guard bug cannot break a legitimate tool call.
+`$(...)` in the command is a literal token, never a subshell. The processes it
+does start are read-only `git rev-parse` / `git diff --name-only` calls on a
+path, with argv and no shell.
+
+Attended (MULTI_AGENT_UNATTENDED unset): the attribution and force-push rules
+only, and any error prints OK (fail-open) so a guard bug cannot break a
+legitimate tool call. Unattended: unattended_policy.py is consulted as well,
+and an error prints BLOCK_PARSE (fail-closed).
 """
 import json
 import os
 import re
 import shlex
+import signal
 import sys
 
+# An internal deadline well under the hook timeout: if the guard cannot decide
+# in this long, it prints the blocking verdict when unattended (fail-closed) and
+# the allow verdict when attended (a guard bug must not break legitimate work).
+# MA_GUARD_DEADLINE_SECONDS may lower it, never raise it: a longer deadline
+# would let the hook timeout decide instead of the guard.
+DEADLINE_SECONDS = 5
+
+
+def deadline_seconds(env=None) -> float:
+    env = os.environ if env is None else env
+    try:
+        v = float(env.get("MA_GUARD_DEADLINE_SECONDS", ""))
+    except ValueError:
+        return DEADLINE_SECONDS
+    return v if 0 < v < DEADLINE_SECONDS else DEADLINE_SECONDS
+
 # --- Rule data (extend here; this is the hookify-style rule surface) ----------
 PROTECTED = {"main", "master", "develop"}
 REMOTES = {"origin", "upstream"}
@@ -126,9 +149,80 @@ def segments(cmd: str) -> list:
     return [(seg, tokenize(seg)) for seg in SEPARATORS.split(cmd)]
 
 
-def decide(cmd: str) -> str:
+# `git push` options that take the NEXT token as their value. Without this list
+# `git push -f -o ci.skip origin` reads `ci.skip` as the repository and
+# `origin` as a branch name, and the bare-push check never runs.
+PUSH_VALUE_OPTIONS = {"-o", "--push-option", "--repo", "--receive-pack", "--exec"}
+# Pushes that rewrite or remove every ref, protected ones included.
+PUSH_ALL_REFS = {"--all", "--mirror", "--branches"}
+PUSH_DELETE = {"-d", "--delete", "--prune"}
+# Pushes that can remove or rewrite a protected ref with no force flag: a
+# mirror (force + prune over every ref), a prune, a delete, and a refspec with
+# an empty source (`:main`), which deletes its destination.
+PUSH_GATE = re.compile(r"(^|\s)(-d|--delete|--mirror|--prune)(\s|=|$)|(^|\s)\+?:\S")
+# A destination that names the branch the checkout is on.
+CURRENT_BRANCH_REFS = {"HEAD", "@"}
+SHORT_FORCE = re.compile(r"^-[A-Za-z]*f[A-Za-z]*$")
+
+
+SHELLS = {"sh", "bash", "zsh", "dash", "ksh", "fish"}
+MAX_DEPTH = 3
+
+
+def flatten(cmd: str) -> str:
+    """cmd with every unquoted `(`, `)` and backtick turned into a separator,
+    so a command inside a subshell or a substitution is a segment of its own.
+    Like the separator split, this can only add segments."""
+    out, q, i = [], None, 0
+    while i < len(cmd):
+        c = cmd[i]
+        if q == "'":
+            q = None if c == "'" else q
+        elif c == "\\" and i + 1 < len(cmd):
+            out.append(cmd[i : i + 2])
+            i += 2
+            continue
+        elif q == '"':
+            q = None if c == '"' else q
+        elif c in ("'", '"'):
+            q = c
+        elif c in "()`":
+            out.append(" ; ")
+            i += 1
+            continue
+        out.append(c)
+        i += 1
+    return "".join(out)
+
+
+def _nested_payload(toks: list):
+    """The command line a segment hands to another shell: the `-c` argument
+    of sh/bash/zsh (after any env assignments or wrappers), or the words of
+    `eval`. None when the segment runs no nested line."""
+    i = 0
+    while i < len(toks) and (re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", toks[i]) or os.path.basename(toks[i]) in ("env", "nohup", "command", "builtin", "exec", "nice", "time")):
+        i += 1
+    if i >= len(toks):
+        return None
+    base = os.path.basename(toks[i]).lower()
+    if base == "eval":
+        return " ".join(toks[i + 1 :])
+    if base not in SHELLS:
+        return None
+    has_c = False
+    for t in toks[i + 1 :]:
+        if t.startswith("-") and not t.startswith("--"):
+            has_c = has_c or "c" in t[1:]
+            continue
+        if t.startswith("--"):
+            continue
+        return t if has_c else None
+    return None
+
+
+def decide(cmd: str, depth: int = 0) -> str:
     low = cmd.lower()
-    segs = segments(cmd)
+    segs = segments(flatten(cmd))
 
     # Rule 1: AI attribution inside a git commit.
     commits = re.search(r"git\s+commit", low) or any(
@@ -138,22 +232,124 @@ def decide(cmd: str) -> str:
         return "BLOCK_ATTRIB"
 
     # Rule 2: force-push to a protected branch. Evaluate each push segment on its
-    # own so a neighbouring command's flags cannot implicate it.
+    # own so a neighbouring command's flags cannot implicate it. A `cd` earlier
+    # on the line moves the push into another checkout, whose branch is the one
+    # that counts.
+    cwd = None
     for seg, toks in segs:
+        if toks and toks[0] in ("{", "}"):
+            toks = toks[1:]
+        if toks and toks[0] in ("cd", "pushd"):
+            cwd = _cd_target(toks, cwd)
+            continue
+        payload = _nested_payload(toks)
+        if payload and depth < MAX_DEPTH:
+            verdict = decide(payload, depth + 1)
+            if verdict != "OK":
+                return verdict
+            continue
         if git_subcommand(toks) != "push" and not re.search(r"git\s+push", seg.lower()):
             continue
-        verdict = _decide_push(seg)
+        verdict = _decide_push(seg, toks, cwd)
         if verdict != "OK":
             return verdict
 
     return "OK"
 
 
+def _cd_target(toks: list, cwd):
+    """The directory a `cd` moves to, or "" when it cannot be read literally
+    (`cd`, `cd -`, `cd ~`, `cd "$X"`): a push after it is on an unknown branch.
+    Once unknown, a relative cd stays unknown; only an absolute one resolves."""
+    args = [t for t in toks[1:] if not t.startswith("-")]
+    if not args or any(ch in args[0] for ch in "$`~*?"):
+        return ""
+    if os.path.isabs(args[0]):
+        return os.path.normpath(args[0])
+    if cwd == "":
+        return ""
+    base = cwd if cwd else os.getcwd()
+    return os.path.normpath(os.path.join(base, args[0]))
+
+
+def _branch_of(directory: str) -> str:
+    """The branch checked out in `directory`, read with the same read-only
+    `git rev-parse` the wrapper runs for the cwd. "" when it cannot be read."""
+    if not directory:
+        return ""
+    try:
+        import subprocess
+
+        out = subprocess.run(
+            ["git", "-C", directory, "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def _parse_push(toks: list):
+    """(git_dir, options, positionals) for a tokenized `git ... push ...`.
+
+    git_dir is the directory named by `-C` / `--work-tree` / `--git-dir`, or
+    None. Values of options that take one are consumed, never read as a
+    repository or refspec.
+    """
+    git_dir, i = None, 0
+    while i < len(toks) and os.path.basename(toks[i]).lower() != "git":
+        i += 1
+    i += 1
+    while i < len(toks):
+        t = toks[i]
+        if t in ("-C", "--work-tree", "--git-dir"):
+            if i + 1 < len(toks):
+                val = toks[i + 1]
+                if t == "--git-dir":
+                    val = os.path.dirname(val.rstrip("/")) or "."
+                git_dir = val if git_dir is None or os.path.isabs(val) else os.path.join(git_dir, val)
+            i += 2
+            continue
+        if t.startswith("--work-tree=") or t.startswith("--git-dir="):
+            key, _, val = t.partition("=")
+            if key == "--git-dir":
+                val = os.path.dirname(val.rstrip("/")) or "."
+            git_dir = val
+            i += 1
+            continue
+        if t in GIT_VALUE_OPTIONS:
+            i += 2
+            continue
+        if t.startswith("-"):
+            i += 1
+            continue
+        break
+    # toks[i] is the subcommand
+    opts, positionals = [], []
+    j = i + 1
+    while j < len(toks):
+        t = toks[j]
+        if t in PUSH_VALUE_OPTIONS:
+            opts.append((t, toks[j + 1] if j + 1 < len(toks) else ""))
+            j += 2
+            continue
+        if t.startswith("-"):
+            key, _, val = t.partition("=")
+            opts.append((key, val))
+        else:
+            positionals.append(t)
+        j += 1
+    return git_dir, opts, positionals
+
+
 def _ref_target(arg: str) -> tuple:
-    """(forced, branch) for one push argument.
+    """(forced, branch) for one refspec.
 
     The destination is the part after the last `:`; a leading `+` on it is a
-    force-push; `refs/heads/main` names the same branch as `main`.
+    force-push; `refs/heads/main` names the same branch as `main`. A refspec
+    with no `:` pushes to the branch of the same name.
     """
     dst = arg.rsplit(":", 1)[-1]
     forced = dst.startswith("+") or arg.startswith("+")
@@ -163,51 +359,166 @@ def _ref_target(arg: str) -> tuple:
     return forced, name
 
 
-def _decide_push(cmd: str) -> str:
-    """Verdict for a single `git push ...` command."""
+def _decide_push(cmd: str, toks=None, cwd=None) -> str:
+    """Verdict for a single `git push ...` command.
+
+    `git push [options] [<repository> [<refspec>...]]`: the first positional is
+    always the repository, whatever it is called; everything after it is a
+    refspec. A refspec of HEAD or @, or none at all, targets the branch that is
+    checked out in the directory the push runs in.
+    """
+    if toks is None:
+        toks = tokenize(cmd)
     force_flag = bool(FORCE.search(cmd))
-    if not force_flag and not FORCED_REFSPEC.search(cmd):
+    if not force_flag and not FORCED_REFSPEC.search(cmd) and not PUSH_GATE.search(cmd):
         return "OK"
     try:
-        toks = shlex.split(cmd)
+        shlex.split(cmd)
     except Exception:
         # A force-push we can't tokenize -> can't prove it's safe -> block.
         return "BLOCK_FORCE"
-    # non-flag args after `push`; only a remote (or nothing) means a bare push
-    args, seen = [], False
-    for t in toks:
-        if t == "push":
-            seen = True
-            continue
-        if seen and not t.startswith("-"):
-            args.append(t)
-    targets = [_ref_target(a) for a in args]
+    git_dir, opts, positionals = _parse_push(toks)
+    keys = {k for k, _ in opts}
+    force_flag = any(
+        k in ("--force", "--force-with-lease", "--force-if-includes") or SHORT_FORCE.match(k) for k in keys
+    )
+    repo_opt = any(k == "--repo" for k in keys)
+    refspecs = positionals if repo_opt else positionals[1:]
+    if "--mirror" in keys:
+        return "BLOCK_FORCE"
+    deleting = bool(keys & PUSH_DELETE) or any(r.lstrip("+").startswith(":") for r in refspecs)
+
+    if git_dir is not None:
+        base = cwd if cwd else os.getcwd()
+        current = _branch_of(git_dir if os.path.isabs(git_dir) else os.path.join(base, git_dir))
+    elif cwd is not None:
+        current = _branch_of(cwd)
+    else:
+        current = os.environ.get("CUR_BRANCH", "")
+
+    targets = []
+    for ref in refspecs:
+        forced, name = _ref_target(ref)
+        if name in CURRENT_BRANCH_REFS:
+            name = current or "HEAD"
+        targets.append((forced, name))
+
     if any(forced and name in PROTECTED for forced, name in targets):
         return "BLOCK_FORCE"
-    if force_flag:
-        if any(name in PROTECTED for _, name in targets):
+    if not (force_flag or deleting):
+        return "OK"
+    if keys & PUSH_ALL_REFS:
+        return "BLOCK_FORCE"
+    if any(name in PROTECTED for _, name in targets):
+        return "BLOCK_FORCE"
+    if "--prune" in keys and (not targets or any("*" in name for _, name in targets)):
+        return "BLOCK_FORCE"
+    unresolved = any(name == "HEAD" for _, name in targets)
+    if force_flag and (not targets or unresolved):
+        # The target is the current branch. Block if it's protected OR
+        # undeterminable (fail-closed for a data-loss guard).
+        if current in PROTECTED or current in ("", "HEAD"):
             return "BLOCK_FORCE"
-        nonremote = [a for a in args if a not in REMOTES]
-        if not nonremote:
-            # Bare force-push: the target is the current branch. Block if it's
-            # protected OR undeterminable (fail-closed for a data-loss guard).
-            cur = os.environ.get("CUR_BRANCH", "")
-            if cur in PROTECTED or cur == "":
-                return "BLOCK_FORCE"
-
     return "OK"
 
 
+def unattended() -> bool:
+    """MULTI_AGENT_UNATTENDED=1 in the hook's own environment - the launcher's,
+    never anything the run wrote (lib/unattended.sh ma_unattended)."""
+    return os.environ.get("MULTI_AGENT_UNATTENDED", "") == "1"
+
+
+def git_subcommand_mode() -> None:
+    """`agent-guard.py --git-subcommand`: read a Bash payload (or a raw command
+    on argv) and print each git subcommand it runs, one per line, using the same
+    tokenizer the guard uses. pre-commit-check.sh reads this to detect a commit
+    without a regex. Never executes anything."""
+    if len(sys.argv) > 2:
+        cmd = sys.argv[2]
+    else:
+        try:
+            data = json.load(sys.stdin)
+            cmd = (data.get("tool_input") or {}).get("command", "")
+        except Exception:
+            cmd = ""
+    if not isinstance(cmd, str) or not cmd:
+        return
+    try:
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        import unattended_policy
+
+        for sub in unattended_policy.git_subcommands(cmd):
+            print(sub)
+    except Exception:
+        # Fall back to the git subcommand of the whole token list; a caller that
+        # gets nothing scans anyway, so silence here only costs an extra scan.
+        subs = git_subcommand(tokenize(cmd))
+        if subs:
+            print(subs)
+
+
+def commit_dir_mode() -> None:
+    """`agent-guard.py --commit-dir`: read a Bash payload and print the
+    directory the first commit-writing git command on the line runs in, after
+    any `cd` / `git -C`, resolved from the payload's cwd. Prints nothing when
+    there is no commit or the directory cannot be read literally, so the caller
+    keeps its own cwd. Never executes anything."""
+    try:
+        data = json.load(sys.stdin)
+        cmd = (data.get("tool_input") or {}).get("command", "")
+        base = data.get("cwd") or os.getcwd()
+    except Exception:
+        return
+    if not isinstance(cmd, str) or not cmd:
+        return
+    try:
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        import unattended_policy
+
+        dirs = unattended_policy.git_commit_dirs(cmd, base)
+    except Exception:
+        return
+    if dirs and dirs[0] and os.path.isdir(dirs[0]):
+        print(dirs[0])
+
+
 def main() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] == "--git-subcommand":
+        git_subcommand_mode()
+        return
+    if len(sys.argv) > 1 and sys.argv[1] == "--commit-dir":
+        commit_dir_mode()
+        return
+    strict = unattended()
+
+    def _deadline(_signum, _frame):
+        # os._exit skips the stdio flush, so the verdict is flushed first or
+        # the wrapper reads nothing.
+        print("BLOCK_UNATTENDED\tthe guard hit its internal deadline" if strict else "OK", flush=True)
+        os._exit(0)
+
+    try:
+        signal.signal(signal.SIGALRM, _deadline)
+        signal.setitimer(signal.ITIMER_REAL, deadline_seconds())
+    except (ValueError, AttributeError, OSError):
+        pass
     try:
         data = json.load(sys.stdin)
         cmd = (data.get("tool_input") or {}).get("command", "")
-        if not isinstance(cmd, str) or not cmd:
-            print("OK")
-            return
-        print(decide(cmd))
+        verdict = decide(cmd) if isinstance(cmd, str) and cmd else "OK"
+        if verdict == "OK" and strict:
+            sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+            import unattended_policy
+
+            reason = unattended_policy.check(data)
+            if reason:
+                verdict = "BLOCK_UNATTENDED\t" + reason.replace("\n", " ")
+        print(verdict)
     except Exception:
-        print("OK")
+        # Attended: a guard bug must not break a legitimate tool call.
+        # Unattended: nobody is there to notice a gap, so an input the guard
+        # cannot judge is refused.
+        print("BLOCK_PARSE" if strict else "OK")
 
 
 if __name__ == "__main__":

package/pipeline/scripts/agent-guard.sh

@@ -1,33 +1,52 @@
 #!/usr/bin/env bash
-# agent-guard.sh  -  PreToolUse Bash guard for the multi-agent pipeline.
+# agent-guard.sh  -  PreToolUse guard for the multi-agent pipeline.
 #
-# Turns two prompt-level rules into deterministic, OS-enforced gates:
+# Turns prompt-level rules into deterministic, OS-enforced gates:
 #   1. No AI/assistant attribution in git commit messages (Co-Authored-By: Claude,
 #      "Generated with Claude Code", robot emoji, Anthropic no-reply address).
-#   2. No force-push to a protected branch (main / master / develop).
+#   2. No force-push to a protected branch (main / master / develop), whichever
+#      remote, push options or `git -C` directory the push names.
+#   3. With MULTI_AGENT_UNATTENDED=1 in the hook's environment only: no outward
+#      writes (push, PR, issue, tracker publishers, mutating API calls), no
+#      Keychain reads, no fetch outside the network allowlist, no package
+#      installs or manifest edits, no writes into protected paths
+#      (scripts/unattended_policy.py, schemas/unattended-policy.json).
 #
-# Contract (Claude Code PreToolUse hook):
-#   - Reads the tool-call JSON on stdin: {"tool_input":{"command":"..."}, ...}.
+# Contract (Claude Code PreToolUse hook, matcher Bash and Edit|Write|NotebookEdit):
+#   - Reads the tool-call JSON on stdin: {"tool_name":..., "tool_input":{...}, "cwd":...}.
 #   - Exit 2  -> BLOCK the tool call (reason on stderr, shown to the model).
 #   - Exit 0  -> allow.
 #
-# Safety design (fail-OPEN):
+# Safety design:
 #   - The command string is ONLY parsed/pattern-matched, NEVER executed or eval'd
 #     (the decision core is agent-guard.py; shlex tokenizes without running).
-#   - Any internal error (bad JSON, missing python3/helper, empty input) -> exit 0.
-#     A guard bug must never break a legitimate tool call.
+#   - Attended: any internal error (bad JSON, missing python3/helper, empty
+#     input) -> exit 0. A guard bug must never break a legitimate tool call.
+#   - Unattended: the same errors -> exit 2. Nobody is watching to notice a gap.
 #   - No network, no file writes, no secret values printed.
-#   - The single exec is a read-only `git rev-parse` to learn the current branch.
+#   - The execs are read-only `git rev-parse` / `git diff --name-only` calls.
 
 set -u
 
 HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
 HELPER="$HERE/agent-guard.py"
-[ -f "$HELPER" ] || exit 0
-command -v python3 >/dev/null 2>&1 || exit 0
+
+STRICT=0
+[ "${MULTI_AGENT_UNATTENDED:-}" = "1" ] && STRICT=1
+
+refuse_unjudged() {
+  if [ "$STRICT" = "1" ]; then
+    echo "BLOCKED by agent-guard (unattended): $1, so this tool call cannot be judged and is refused." >&2
+    exit 2
+  fi
+  exit 0
+}
+
+[ -f "$HELPER" ] || refuse_unjudged "agent-guard.py is missing"
+command -v python3 >/dev/null 2>&1 || refuse_unjudged "python3 is not on PATH"
 
 PAYLOAD="$(cat 2>/dev/null || true)"
-[ -z "$PAYLOAD" ] && exit 0
+[ -z "$PAYLOAD" ] && refuse_unjudged "the hook received no payload"
 
 CUR_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
 
@@ -43,6 +62,15 @@ case "$DECISION" in
     echo "BLOCKED by agent-guard: force-push to a protected branch (main/master/develop) is not allowed." >&2
     echo "Rewriting shared history is a data-loss risk. Push a normal commit, or force-push a feature branch." >&2
     exit 2 ;;
-  *)
+  BLOCK_UNATTENDED*)
+    echo "BLOCKED by agent-guard (unattended policy): ${DECISION#BLOCK_UNATTENDED?}." >&2
+    echo "This run has nobody watching it. Outward writes go through pr-request.json and the runner;" >&2
+    echo "see multi-agent-refs/features/unattended-security.md. Record what is needed and continue." >&2
+    exit 2 ;;
+  BLOCK_PARSE)
+    refuse_unjudged "the guard could not parse the tool call" ;;
+  OK)
     exit 0 ;;
+  *)
+    refuse_unjudged "the guard returned no decision" ;;
 esac

package/pipeline/scripts/analysis-story-tree.mjs

@@ -38,6 +38,16 @@
  * after `~/.claude` is deleted, and for a SECOND ANALYST - who is precisely the
  * person positioned to open a duplicate tree.
  *
+ * THE SPEC HAS TO BE CONSISTENT, NOT ONLY CLOSED
+ *
+ * After planning, `spec-consistency-gate.mjs` checks the document against the
+ * planned stories: every requirement in a story and in a Test Plan row, and no
+ * row that waives a binding constitution rule. With the quality gates active
+ * (lib/unattended.mjs, gatesActive) a gap is exit 4, the same refusal as an
+ * open placeholder, and the verdict is recorded in the gate ledger. Attended,
+ * it is an advisory `consistency:` line in the preview and a `consistency`
+ * field in the JSON, and the exit code is what it was.
+ *
  * Usage:
  *   analysis-story-tree.mjs <analysis.md> [--json] [--prefs FILE]
  *
@@ -47,7 +57,18 @@
 import { readFileSync, existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { hostCommand } from "../lib/user-facing.mjs";
+import { resolveConstitution } from "./constitution.mjs";
+import { gateContext, recordQuietly } from "./gate-ledger.mjs";
+import {
+  describe,
+  detail as consistencyDetail,
+  evaluate,
+  LEDGER,
+  storyTasks,
+  summary,
+} from "./spec-consistency-gate.mjs";
 
 const argv = process.argv.slice(2);
 const JSON_OUT = argv.includes("--json");
@@ -364,7 +385,28 @@ export function plan(text, prefs) {
   };
 }
 
-function main() {
+/**
+ * The consistency verdict for this document and its planned stories.
+ *
+ * @returns {object}  a spec-consistency-gate result
+ */
+function consistencyOf(text, nodes) {
+  const constitution = resolveConstitution({
+    repo: dirname(file),
+    feature: frontMatter(text).feature || null,
+  });
+  if (constitution.error) {
+    return { gate: "spec-consistency", verdict: "unreadable", reason: constitution.error };
+  }
+  return evaluate({
+    docs: [{ path: file, text }],
+    tasks: storyTasks(nodes),
+    taskSource: "story-tree",
+    constitution,
+  });
+}
+
+async function main() {
   if (!file) return die("usage: analysis-story-tree.mjs <analysis.md> [--json] [--prefs FILE]", 3);
   if (!existsSync(file)) return die(`analysis-story-tree: no such file: ${file}`, 3);
   const text = readFileSync(file, "utf8");
@@ -378,7 +420,9 @@ function main() {
       `analysis-story-tree: the document is not issue-ready (${open.length} open item(s))\n`,
     );
     for (const m of open.slice(0, 5)) process.stderr.write(`  ${m}\n`);
-    process.stderr.write("  run /multi-agent:analysis-resolve to close them first\n");
+    process.stderr.write(
+      `  run ${hostCommand("analysis-resolve", import.meta.dirname)} to close them first\n`,
+    );
     process.exitCode = 4;
     return;
   }
@@ -401,6 +445,33 @@ function main() {
     return;
   }
 
+  const ctx = gateContext({ repo: process.cwd() });
+  const consistency = consistencyOf(text, result.nodes);
+  if (ctx.active) {
+    await recordQuietly(
+      "spec-consistency",
+      LEDGER[consistency.verdict],
+      {
+        verdict: consistency.verdict,
+        source: "analysis-jira",
+        ...(consistency.reason ? { reason: consistency.reason } : {}),
+      },
+      { repo: process.cwd(), statePath: ctx.statePath },
+    );
+    if (consistency.verdict === "gap" || consistency.verdict === "unreadable") {
+      process.stderr.write(
+        `analysis-story-tree: the document is not issue-ready (spec-consistency: ${summary(consistency)})\n`,
+      );
+      for (const line of describe(consistency).slice(0, 10)) process.stderr.write(`${line}\n`);
+      process.stderr.write(
+        `  add the missing rows to the document, or re-run ${hostCommand("analysis", import.meta.dirname)}, then plan again\n`,
+      );
+      process.exitCode = 4;
+      return;
+    }
+  }
+  result.consistency = ctx.active ? consistency : { ...consistency, advisory: true };
+
   if (JSON_OUT) {
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return;
@@ -417,6 +488,11 @@ function main() {
   );
   if (c.uncovered.length) process.stdout.write(`  not in any story: ${c.uncovered.join(", ")}\n`);
   if (c.invented.length) process.stdout.write(`  cited but undefined: ${c.invented.join(", ")}\n`);
+  const k = result.consistency;
+  process.stdout.write(
+    `consistency: ${k.verdict} (${k.advisory ? "advisory, " : ""}${consistencyDetail(k)})\n`,
+  );
+  for (const line of describe(k)) process.stdout.write(`${line}\n`);
   process.stdout.write(`\n${result.writeCount} issue(s) would be created:\n`);
   for (const s of result.nodes) {
     process.stdout.write(`  ${result.prefsUsed.storyIssueType}  ${s.title}\n`);