@mmerterden/multi-agent-pipeline 20.23.2 → 20.25.0

package/pipeline/lib/tdd-evidence.mjs

@@ -0,0 +1,579 @@
+/**
+ * @file tdd-evidence.mjs  -  proof that a plan todo went RED before it went GREEN.
+ *
+ * Phase 2 tells the dev agent to write a failing test first. Without a record,
+ * "I did TDD" is a claim; with one it is two test runs: a RED run in which a
+ * test the todo names fails, then a GREEN run with no failures. This module
+ * reads those runs from the files test runners already write and turns them
+ * into the `tdd` record plan-todos.sh stores on the todo.
+ *
+ * Inputs it reads, by shape rather than by flag:
+ *
+ *   JUnit XML     a file or a directory of them (Gradle, Surefire, Jest/Vitest
+ *                 junit reporters, pytest --junitxml). Counted per <testcase>;
+ *                 <failure> and <error> are failures. A truncated report is
+ *                 refused rather than counted, because the cases it lost are
+ *                 the ones that were running when it broke.
+ *   *.xcresult    a bundle, read with `xcrun xcresulttool get test-results
+ *                 summary --compact`.
+ *   JSON          that summary exported to a file, so the record needs no Xcode.
+ *   text          anything test-summary.mjs counts; failing names are read
+ *                 from XCTest and Swift Testing lines (xcodebuild, swift test).
+ *
+ * Every parser returns {total, passed, failed, skipped, failing[], passing,
+ * format, source}; total counts skipped tests, failing[] names the failed
+ * ones, passing[] names the passed ones, or is null when the format lists
+ * only failures (the xcresult summary, a log with no per-test lines).
+ *
+ * RED and GREEN must be the same tests. When RED named its failing tests and
+ * the GREEN results name their passing ones, each RED test has to pass in
+ * GREEN; when either side carries no names, GREEN has to run at least as many
+ * tests as RED. Results written before the todo's startedAt are refused for
+ * both runs. `--tests` on results that name no failing test cannot be checked:
+ * enforce refuses it (exit 2, use JUnit XML), warn and off record the RED run
+ * with `red.testsUnverifiable` and warn on stderr.
+ *
+ * Outcomes on a todo: `red` (RED recorded), `verified` (RED then GREEN),
+ * `already-passing` (the behaviour existed; the passing run is both RED and
+ * GREEN, with a reason), `exempt` (docs / chore todo, component task, no test
+ * target, test policy none; with a reason) and `unverified` (completed in warn
+ * mode without the evidence). Phase 3 notes the unverified todos and the
+ * exemptions a todo declared for itself (`--no-tests`, `selfDeclared`).
+ *
+ * CLI (exit 0 ok, 1 the evidence does not hold, 2 usage or unreadable input):
+ *   tdd-evidence.mjs parse <results>
+ *   tdd-evidence.mjs red   --state <f> --todo <id> --results <r> [--tests a,b] [--already-passing <reason>] [--mode off|warn|enforce]
+ *   tdd-evidence.mjs green --state <f> --todo <id> --results <r>
+ *   tdd-evidence.mjs check --state <f> --todo <id> --mode off|warn|enforce [--no-tests <reason>]
+ *   tdd-evidence.mjs unverified --state <f>
+ *
+ * red / green / check print JSON and never write the state: plan-todos.sh owns
+ * that file and merges the record in.
+ *
+ * Zero runtime dependencies (ADR-0004).
+ *
+ * @module pipeline/lib/tdd-evidence
+ */
+
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import { fromXcresultJson, summarize } from "../scripts/test-summary.mjs";
+import { invokedDirectly } from "./invoked-directly.mjs";
+
+export const MODES = ["off", "warn", "enforce"];
+const EXEMPT_TYPES = new Set(["docs", "chore"]);
+const VERIFIED = new Set(["verified", "already-passing"]);
+
+class Unreadable extends Error {}
+class Refused extends Error {}
+
+// ---------------------------------------------------------------------------
+// Parsing
+
+const ENTITIES = { lt: "<", gt: ">", amp: "&", quot: '"', apos: "'" };
+
+function decode(s) {
+  return s.replace(/&(#x[0-9a-f]+|#\d+|lt|gt|amp|quot|apos);/gi, (_, e) => {
+    if (e[0] !== "#") return ENTITIES[e.toLowerCase()];
+    const code = e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+    return String.fromCodePoint(code);
+  });
+}
+
+function attrs(text) {
+  const out = {};
+  for (const m of text.matchAll(/([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+    out[m[1]] = decode(m[2] ?? m[3]);
+  }
+  return out;
+}
+
+const ATTRS = `((?:[^>"'/]|/(?!>)|"[^"]*"|'[^']*')*)`;
+
+/**
+ * Parse one JUnit XML document.
+ *
+ * @param {string} xml
+ * @returns {object|null} null when the text is not a JUnit report.
+ */
+export function parseJunit(xml, source = null) {
+  const text = xml.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, "").replace(/<!--[\s\S]*?-->/g, "");
+  if (!/<testsuites?\b/.test(text)) return null;
+  const where = source ? ` (${source})` : "";
+
+  const opens = [...text.matchAll(new RegExp(`<testsuites?\\b${ATTRS}(/?)>`, "g"))].filter(
+    (m) => m[2] !== "/",
+  ).length;
+  const closes = (text.match(/<\/testsuites?>/g) ?? []).length;
+  const caseTags = (text.match(/<testcase\b/g) ?? []).length;
+  const cases = [
+    ...text.matchAll(new RegExp(`<testcase\\b${ATTRS}(?:/>|>([\\s\\S]*?)</testcase>)`, "g")),
+  ];
+  if (
+    opens !== closes ||
+    cases.length !== caseTags ||
+    cases.some((m) => /<testcase\b/.test(m[2] ?? ""))
+  ) {
+    throw new Unreadable(`malformed JUnit XML${where}: unclosed testsuite or testcase element`);
+  }
+
+  const r = { total: 0, passed: 0, failed: 0, skipped: 0, failing: [], passing: [] };
+  for (const m of cases) {
+    const a = attrs(m[1]);
+    const body = m[2] ?? "";
+    const id = a.classname ? `${a.classname}.${a.name ?? ""}` : (a.name ?? "");
+    r.total++;
+    if (/<(?:failure|error)\b/.test(body)) {
+      r.failed++;
+      r.failing.push(id);
+    } else if (/<skipped\b/.test(body)) r.skipped++;
+    else {
+      r.passed++;
+      r.passing.push(id);
+    }
+  }
+  if (r.total === 0) {
+    const declared = [...text.matchAll(/<testsuite\b[^>]*\btests="(\d+)"/g)].reduce(
+      (n, m) => n + Number(m[1]),
+      0,
+    );
+    if (declared > 0) {
+      throw new Unreadable(
+        `JUnit XML${where}: suites declare ${declared} tests but list no testcase`,
+      );
+    }
+  }
+  return { ...r, format: "junit-xml", source };
+}
+
+function xmlUnder(dir, depth = 0, out = []) {
+  if (depth > 6) return out;
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) xmlUnder(full, depth + 1, out);
+    else if (e.name.endsWith(".xml")) out.push(full);
+  }
+  return out.sort();
+}
+
+function junitDir(dir) {
+  const sum = { total: 0, passed: 0, failed: 0, skipped: 0, failing: [], passing: [] };
+  let read = 0;
+  for (const f of xmlUnder(dir)) {
+    const r = parseJunit(readFileSync(f, "utf8"), f);
+    if (!r) continue;
+    read++;
+    for (const k of ["total", "passed", "failed", "skipped"]) sum[k] += r[k];
+    sum.failing.push(...r.failing);
+    sum.passing.push(...r.passing);
+  }
+  if (read === 0) throw new Unreadable(`no JUnit XML report under ${dir}`);
+  return { ...sum, format: "junit-xml", source: dir };
+}
+
+/**
+ * Read an `xcresulttool get test-results summary` document.
+ *
+ * Counts come from test-summary.mjs so both read the summary the same way;
+ * the failing names come from `testFailures[]`, one per test.
+ */
+export function parseXcresultJson(obj, source = null) {
+  const c = fromXcresultJson(obj, source);
+  if (c.executed === null) throw new Unreadable(`${source ?? "xcresult JSON"}: ${c.reason}`);
+  const failing = [
+    ...new Set(
+      (obj.testFailures ?? []).map((f) =>
+        [f.targetName, f.testIdentifierString ?? f.testName].filter(Boolean).join("/"),
+      ),
+    ),
+  ];
+  return {
+    total: c.passed + c.failed + c.skipped,
+    passed: c.passed,
+    failed: c.failed,
+    skipped: c.skipped,
+    failing,
+    passing: null,
+    format: "xcresult",
+    source,
+  };
+}
+
+function xcresultBundle(bundle, { xcrun = "xcrun", timeoutMs = 60000 } = {}) {
+  const res = spawnSync(
+    xcrun,
+    ["xcresulttool", "get", "test-results", "summary", "--path", bundle, "--compact"],
+    { encoding: "utf8", timeout: timeoutMs },
+  );
+  if (res.error) {
+    throw new Unreadable(`xcrun unavailable: ${res.error.code || res.error.message}`);
+  }
+  if (res.status !== 0) {
+    throw new Unreadable(`xcresulttool exited ${res.status}: ${res.stderr.trim().slice(0, 200)}`);
+  }
+  let obj;
+  try {
+    obj = JSON.parse(res.stdout);
+  } catch {
+    throw new Unreadable("xcresulttool printed no JSON");
+  }
+  return parseXcresultJson(obj, bundle);
+}
+
+function xctestId(name) {
+  const objc = /^-\[(\S+) (\S+)\]$/.exec(name);
+  return objc ? `${objc[1]}/${objc[2]}` : name;
+}
+
+function testLines(text, verdict) {
+  const ids = new Set();
+  for (const m of text.matchAll(new RegExp(`^Test [Cc]ase '([^']+)' ${verdict}\\b`, "gm"))) {
+    ids.add(xctestId(m[1]));
+  }
+  for (const m of text.matchAll(
+    new RegExp(`^\\S+ Test (?!run with )(.+?) ${verdict}(?: after|\\.|$)`, "gm"),
+  )) {
+    ids.add(m[1]);
+  }
+  return [...ids];
+}
+
+/**
+ * Runner text: counts from test-summary.mjs, test names from XCTest and
+ * Swift Testing result lines. Other runners count but name nothing.
+ */
+export function parseText(text, source = null) {
+  const c = summarize(text, { source });
+  if (c.executed === null) throw new Unreadable(c.reason);
+  const failing = testLines(text, "failed");
+  const passed = testLines(text, "passed");
+  const perTest = failing.length > 0 || passed.length > 0 || /^Test [Cc]ase '/m.test(text);
+  return {
+    total: c.executed + c.skipped,
+    passed: c.passed,
+    failed: c.failed,
+    skipped: c.skipped,
+    failing,
+    passing: perTest ? passed : null,
+    format: c.parser,
+    source,
+  };
+}
+
+/**
+ * Read test results from a path, whatever the runner wrote.
+ *
+ * @param {string} path
+ * @param {{xcrun?: string}} [opts]
+ * @throws {Error} when the input cannot be read as test results.
+ */
+export function parseResults(path, opts = {}) {
+  let st;
+  try {
+    st = statSync(path);
+  } catch {
+    throw new Unreadable(`no test results at ${path}`);
+  }
+  if (st.isDirectory()) {
+    return basename(path).endsWith(".xcresult") ? xcresultBundle(path, opts) : junitDir(path);
+  }
+  const text = readFileSync(path, "utf8");
+  if (/^\s*\{/.test(text)) {
+    let obj;
+    try {
+      obj = JSON.parse(text);
+    } catch (err) {
+      throw new Unreadable(`${path}: not valid JSON (${err.message})`);
+    }
+    return parseXcresultJson(obj, path);
+  }
+  return parseJunit(text, path) ?? parseText(text, path);
+}
+
+function newestMtime(path, depth = 0) {
+  const st = statSync(path);
+  let newest = st.mtimeMs;
+  if (st.isDirectory() && depth <= 6) {
+    for (const e of readdirSync(path))
+      newest = Math.max(newest, newestMtime(join(path, e), depth + 1));
+  }
+  return newest;
+}
+
+/**
+ * Refuse results written before the todo started: a run from before the
+ * todo's work is not evidence about it. A directory counts by its newest file.
+ *
+ * @param {string} path
+ * @param {string|undefined} startedAt  the todo's ISO start time
+ */
+export function resultsFresh(path, startedAt) {
+  if (!startedAt) return;
+  const started = Date.parse(startedAt);
+  if (Number.isNaN(started)) return;
+  let written;
+  try {
+    written = newestMtime(path);
+  } catch {
+    throw new Unreadable(`no test results at ${path}`);
+  }
+  if (written < started) {
+    throw new Refused(
+      `${path} was written at ${new Date(written).toISOString()}, older than the todo's start (${startedAt}); run the tests again`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Decisions
+
+const strip = (s) => s.replace(/\(\)$/, "");
+
+/**
+ * Does a failing test id name the test a todo declared? An exact match, or the
+ * declared name as the trailing segment of a qualified id.
+ */
+export function touches(id, name) {
+  const a = strip(id);
+  const b = strip(name);
+  if (!b) return false;
+  if (a === b) return true;
+  if (!a.endsWith(b)) return false;
+  return /[./: #>]$/.test(a.slice(0, a.length - b.length));
+}
+
+/**
+ * The RED record for a todo.
+ *
+ * @param {object} summary  parseResults() output
+ * @param {{tests?: string[], alreadyPassing?: string, mode?: string, now: string}} opts
+ */
+export function redRecord(summary, { tests = [], alreadyPassing = "", mode = "warn", now }) {
+  if (summary.total === 0) throw new Refused("the RED run executed no tests");
+  if (alreadyPassing) {
+    if (summary.failed > 0) {
+      throw new Refused(
+        `already-passing needs a run with no failures; this one has ${summary.failed}`,
+      );
+    }
+    return {
+      red: { at: now, failed: 0, total: summary.total, tests: [] },
+      green: { at: now, failed: 0, total: summary.total },
+      outcome: "already-passing",
+      reason: alreadyPassing,
+    };
+  }
+  if (summary.failed === 0) {
+    throw new Refused(
+      "the RED run has no failing test; a test that passes before the change proves nothing (use --already-passing <reason> when the behaviour already exists)",
+    );
+  }
+  if (tests.length > 0 && summary.failing.length === 0) {
+    if (mode === "enforce") {
+      throw new Unreadable(
+        `--tests ${tests.join(", ")}: the results name no failing test, so the named test cannot be checked; record RED from JUnit XML (or an xcresult / XCTest / Swift Testing log)`,
+      );
+    }
+    return {
+      red: {
+        at: now,
+        failed: summary.failed,
+        total: summary.total,
+        tests: [],
+        testsUnverifiable: true,
+      },
+      outcome: "red",
+    };
+  }
+  let named = summary.failing;
+  if (tests.length > 0) {
+    named = summary.failing.filter((id) => tests.some((t) => touches(id, t)));
+    if (named.length === 0) {
+      throw new Refused(
+        `none of the failing tests is one this todo names (${tests.join(", ")}); failing: ${summary.failing.join(", ")}`,
+      );
+    }
+  }
+  return {
+    red: { at: now, failed: summary.failed, total: summary.total, tests: named },
+    outcome: "red",
+  };
+}
+
+/**
+ * The GREEN record, on top of the todo's RED record.
+ *
+ * @param {object} summary
+ * @param {{prior: object|null, testPolicy?: string, now: string}} opts
+ */
+export function greenRecord(summary, { prior, testPolicy, now }) {
+  if (!prior?.red && testPolicy !== "tests-after") {
+    throw new Refused("no RED run recorded for this todo; record RED first");
+  }
+  if (summary.total === 0) throw new Refused("the GREEN run executed no tests");
+  if (summary.failed > 0) {
+    const names = summary.failing.length ? `: ${summary.failing.join(", ")}` : "";
+    throw new Refused(`the GREEN run still has ${summary.failed} failing test(s)${names}`);
+  }
+  const redTests = prior?.red?.tests ?? [];
+  if (redTests.length > 0 && Array.isArray(summary.passing)) {
+    const missing = redTests.filter((t) => !summary.passing.some((p) => touches(p, t)));
+    if (missing.length > 0) {
+      throw new Refused(
+        `RED test(s) ${missing.join(", ")} not among the passing tests of the GREEN run; GREEN must run them`,
+      );
+    }
+  } else if (prior?.red && summary.total < prior.red.total) {
+    throw new Refused(
+      `the GREEN run ran ${summary.total} test(s), fewer than the ${prior.red.total} RED ran; run at least the RED suite`,
+    );
+  }
+  const base = { ...prior };
+  if (base.outcome !== "already-passing") {
+    base.outcome = "verified";
+    delete base.reason;
+  }
+  return { ...base, green: { at: now, failed: 0, total: summary.total } };
+}
+
+function exemption(todo, { taskType, testPolicy, noTests }) {
+  if (noTests) return { reason: `no test target: ${noTests}`, selfDeclared: true };
+  if (EXEMPT_TYPES.has(todo.type)) return { reason: `todo type ${todo.type}` };
+  if (taskType === "component") {
+    return { reason: "component task: the component skill owns its tests" };
+  }
+  if (testPolicy === "none") return { reason: "project test policy: none" };
+  return null;
+}
+
+/**
+ * Whether `plan-todos.sh complete` may close a todo, and the record it leaves.
+ *
+ * @returns {{action: "allow"|"warn"|"refuse", tdd?: object, message?: string}}
+ */
+export function completion(todo, { mode, taskType, testPolicy, noTests } = {}) {
+  if (mode === "off") return { action: "allow", tdd: todo.tdd };
+  const prior = todo.tdd ?? {};
+  const exempt = exemption(todo, { taskType, testPolicy, noTests });
+  if (exempt) {
+    const tdd = { ...prior, outcome: "exempt", ...exempt };
+    if (!exempt.selfDeclared) delete tdd.selfDeclared;
+    return { action: "allow", tdd };
+  }
+  if (VERIFIED.has(prior.outcome) && prior.green?.failed === 0) {
+    return { action: "allow", tdd: prior };
+  }
+  const reason =
+    !prior.red && testPolicy !== "tests-after" ? "no RED run recorded" : "no GREEN run recorded";
+  const message = `todo ${todo.id}: ${reason} (plan-todos.sh tdd-red / tdd-green)`;
+  if (mode === "enforce") return { action: "refuse", message };
+  return { action: "warn", message, tdd: { ...prior, outcome: "unverified", reason } };
+}
+
+/**
+ * Completed todos the Phase 3 review notes: evidence unverified, or an
+ * exemption the todo declared for itself (`--no-tests`). Exemptions the todo
+ * type, the task type or the test policy grant are not listed.
+ */
+export function unverifiedTodos(state) {
+  return (state?.plan?.todos ?? [])
+    .filter((t) => t.status === "completed")
+    .map((t) => {
+      if (t.tdd?.outcome === "unverified") return { kind: "unverified", t };
+      if (t.tdd?.outcome === "exempt" && t.tdd.selfDeclared === true)
+        return { kind: "self-exempt", t };
+      return null;
+    })
+    .filter(Boolean)
+    .map(({ kind, t }) => ({ id: t.id, task: t.task, kind, reason: t.tdd.reason ?? "" }));
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+function flags(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      out._.push(a);
+      continue;
+    }
+    const v = argv[i + 1];
+    if (v === undefined) throw new Unreadable(`${a} needs a value`);
+    if (Object.hasOwn(out, a.slice(2))) throw new Unreadable(`${a} given more than once`);
+    out[a.slice(2)] = v;
+    i++;
+  }
+  return out;
+}
+
+function loadTodo(f) {
+  if (!f.state || !f.todo) throw new Unreadable("--state and --todo are required");
+  const state = JSON.parse(readFileSync(f.state, "utf8"));
+  const todo = (state.plan?.todos ?? []).find((t) => t.id === f.todo);
+  if (!todo) throw new Unreadable(`todo '${f.todo}' not found`);
+  return { state, todo };
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  const print = (o) => process.stdout.write(`${JSON.stringify(o)}\n`);
+  try {
+    const f = flags(rest);
+    if (cmd === "parse") {
+      if (!f._[0]) throw new Unreadable("parse needs a results path");
+      print(parseResults(f._[0]));
+    } else if (cmd === "red" || cmd === "green") {
+      const { state, todo } = loadTodo(f);
+      if (!f.results) throw new Unreadable("--results is required");
+      const summary = parseResults(f.results);
+      resultsFresh(f.results, todo.startedAt);
+      const record =
+        cmd === "red"
+          ? redRecord(summary, {
+              tests: (f.tests ?? "").split(",").filter(Boolean),
+              alreadyPassing: f["already-passing"] ?? "",
+              mode: f.mode,
+              now,
+            })
+          : greenRecord(summary, { prior: todo.tdd ?? null, testPolicy: state.testPolicy, now });
+      if (record.red?.testsUnverifiable) {
+        process.stderr.write(
+          `tdd-evidence: warning: ${f.results} names no failing test, so --tests ${f.tests} is recorded unchecked (red.testsUnverifiable); JUnit XML names them\n`,
+        );
+      }
+      print(record);
+    } else if (cmd === "check") {
+      const { state, todo } = loadTodo(f);
+      print(
+        completion(todo, {
+          mode: f.mode,
+          taskType: state.taskType,
+          testPolicy: state.testPolicy,
+          noTests: f["no-tests"],
+        }),
+      );
+    } else if (cmd === "unverified") {
+      if (!f.state) throw new Unreadable("--state is required");
+      const state = JSON.parse(readFileSync(f.state, "utf8"));
+      for (const t of unverifiedTodos(state)) {
+        const reason = t.kind === "self-exempt" ? `self-declared exemption: ${t.reason}` : t.reason;
+        process.stdout.write(`${t.id}\t${t.task}\t${reason}\n`);
+      }
+    } else {
+      throw new Unreadable(
+        `unknown subcommand '${cmd ?? ""}' (parse | red | green | check | unverified)`,
+      );
+    }
+    return 0;
+  } catch (err) {
+    process.stderr.write(`tdd-evidence: ${err.message}\n`);
+    return err instanceof Refused ? 1 : 2;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/pipeline/multi-agent-refs/analysis-template-corporate.md

@@ -295,6 +295,8 @@ Every `FG` sentence starts with `Sistem,` in Turkish output and `The system shal
 
 Every `FG` carries both a source `UC` and a source `IG`. An FG with no source IG is either an unrecorded business requirement or an invented feature; both are findings, not rows.
 
+Optional: an `FG` that must wait for another carries `Depends on: FG-NN[, ...]` in its own row, in English whatever the output language; `/multi-agent:analysis-jira` links the stories in that order.
+
 ### 5.(N+4) Servis Detayları
 
 One table per service. Contracts come from the live specification, never from prose (Locked 17: every status code the endpoint returns is listed, with an example body).

package/pipeline/multi-agent-refs/analysis-template.md

@@ -263,7 +263,7 @@ Then <expected outcome>
 
 Locked 30 - the traceability spine. Every business rule is deterministic and testable (same input always yields the same outcome) and carries a stable id `BR-<slug>-NN`.
 
-**The rule statement itself is written in EARS**, not free prose. EARS (Easy Approach to Requirements Syntax, IEEE RE'09) constrains the sentence to a fixed clause order and a small keyword set, which is what removes the ambiguity a prose rule carries. Five patterns, use the one that fits:
+**The rule statement itself is written in EARS**, not free prose. EARS (Easy Approach to Requirements Syntax, IEEE RE'09) constrains the sentence to a fixed clause order and a small keyword set, which removes the ambiguity of a prose rule. Five patterns, use the one that fits:
 
 | Pattern | Shape | Use when |
 |---|---|---|
@@ -273,7 +273,7 @@ Locked 30 - the traceability spine. Every business rule is deterministic and tes
 | Unwanted | `IF <unwanted condition> THEN THE SYSTEM SHALL <behaviour>` | error and edge handling |
 | Optional | `WHERE <feature is included> THE SYSTEM SHALL <behaviour>` | applies only to some configurations |
 
-EARS states the rule; Gherkin states how you check it. Each rule still maps to at least one acceptance criterion written Given / When / Then. Each acceptance criterion is then realized as unit-test scenarios in Section 15.1. Section 15 renders whenever there is evidence for it, and the traceability gate applies to whatever was rendered. Rules come from the spec / Confluence / Jira / annotations, never invented; a rule with no source cites `[label TBD - see Open Questions]` and adds a Section 20 row.
+EARS states the rule; Gherkin states how you check it. Each rule maps to >=1 Given / When / Then acceptance criterion, each realized as unit-test scenarios in Section 15.1. Section 15 renders whenever evidence exists; the traceability gate applies to whatever rendered. Rules come from the spec / Confluence / Jira / annotations, never invented; a rule with no source cites `[label TBD - see Open Questions]` and adds a Section 20 row.
 
 | BR ID | Kural / Rule (deterministic, testable) | Kaynak / Source | Kabul kriteri / Acceptance criterion (Given/When/Then) |
 |---|---|---|---|
@@ -283,6 +283,8 @@ EARS states the rule; Gherkin states how you check it. Each rule still maps to a
 
 Each scenario in 4.1-4.3 cites the matching `BR-<slug>-NN` id (and, when a server code applies, the Section 9.4 code). Plain-prose user stories without Given/When/Then are rejected by the renderer.
 
+Optional: a row may add `Depends on: BR-<slug>-NN` (`features/analysis-jira.md`).
+
 ### 4.5 Mevcut Davranış / Current Behaviour (OPTIONAL)
 
 `redesign: true` only. Locked 36; contract and checks in `analysis/redesign.md`. Evidence and certainty are derived from `repoEvidence`, never graded by the writer.

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -1,7 +1,7 @@
 # Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 <!-- toc -->
-- [1. Command Inventory (64 commands)](#1-command-inventory-64-commands)
+- [1. Command Inventory (66 commands)](#1-command-inventory-66-commands)
 - [2. Canonical Placeholder Vocabulary](#2-canonical-placeholder-vocabulary)
 - [2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator](#26-intentional-structural-divergence---thin-dispatcher-vs-inlined-orchestrator)
 - [2.7 One command, three different meanings: `/multi-agent:model`](#27-one-command-three-different-meanings-multi-agentmodel)
@@ -20,14 +20,14 @@
 
 ---
 
-## 1. Command Inventory (64 commands)
+## 1. Command Inventory (66 commands)
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
 autopilot-on, autopilot-status, bug-bash, build-optimize, channels, complaint-analysis,
-create-jira, design-check, diff-explain, doctor, estimate, feedback, forget,
+create-jira, deps, design-check, diff-explain, doctor, estimate, feedback, forget,
 garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
-language, log, manual-test, model, prune-logs,
+language, log, manual-test, model, postmortem, prune-logs,
 prune-prompts, purge, refactor, research, resume, review,
 review-analysis, review-issue, review-jira, route-off, route-on,
 route-status, routines, save, scaffold, scan, scenario-audit, search,
@@ -40,9 +40,9 @@ Categories:
 
 - **Interactive pickers** (single-purpose, not modes): `jira`, `issue`
 - **Issue generator** (one-shot, no worktree, asks type Task/Bug/Story, hard approval gate before create): `create-jira`
-- **Pipeline entries**: `autopilot` (plus the bare `/multi-agent` in the dispatcher). The phase set is a property of the command, and every mode runs its whole set.
+- **Pipeline entries**: `autopilot`, `deps` (plus the bare `/multi-agent` in the dispatcher). The phase set is a property of the command, and every mode runs its whole set.
 - **Tail path** (the pipeline tail over work already on a branch, no run behind it): `resume`
-- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `research`, `scaffold`, `complaint-analysis`, `bug-bash`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `prune-logs`, `prune-prompts`, `serve`
+- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `research`, `scaffold`, `complaint-analysis`, `bug-bash`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `postmortem`, `prune-logs`, `prune-prompts`, `serve`
 - **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`, `ios-coding-standard`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 - **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
@@ -262,8 +262,8 @@ that quietly no-ops is worse than one that says it cannot act.
 
 | Host | What `model on|off` does | Why |
 |---|---|---|
-| Claude Code | live switch: flips `modelFallback.fableEnabled` and realigns `costBudget.pricingModel` | the only host where the `fable` rung is Fable 5 |
-| Copilot CLI | writes the preference, changes no dispatch | Fable 5 is not offered there; its personas never sat on this rung |
+| Claude Code | live switch: flips `modelFallback.fableEnabled` and realigns `costBudget.pricingModel` | the only host where the `fable` rung is Fable 5.1 |
+| Copilot CLI | writes the preference, changes no dispatch | Fable is not offered there; its personas never sat on this rung |
 | Codex CLI | writes the preference, changes no dispatch, **deliberately** | the `fable` rung on Codex means `gpt-5.6 @ xhigh` - a different model on a different account. A knob named after an Anthropic model must not silently retune a Codex run |
 
 `model-rung.sh` prints which of the three it is on every invocation. The rule it
@@ -440,9 +440,8 @@ what keeps a secret off argv and what writes the audit entry.
   something that is not a timestamp.
 - `sed -E`, never `-r`; `sed -i ''` when editing in place.
 
-Clipboard callers may use `pbpaste` / `pbcopy` directly; the three-way
-`command -v` guard they used to carry was for hosts this package no longer
-installs on.
+Clipboard callers may use `pbpaste` / `pbcopy` directly; a `command -v` guard
+for other clipboard tools would serve hosts this package does not install on.
 
 ---