@attalabs/vinaya 0.26.0 → 0.27.0

package/dist/checks/bin/check-dispatch-readiness.js

@@ -306,7 +306,7 @@ function issueListByLabelArgs(owner, repo, label) {
     "--state",
     "all",
     "--json",
-    "number,title,body,state,labels,milestone",
+    "number,title,body,state,labels,milestone,stateReason",
     "--limit",
     "200"
   ];
@@ -652,14 +652,19 @@ function resolveTaskIssueRef(title, labels) {
 var INTENTS_HEADING = /^#{1,6}\s*Tranche intents\s*$/im;
 var NEXT_HEADING = /^#{1,6}\s+\S/m;
 var INTENT_BULLET = /^-\s+([a-z0-9][a-z0-9-]*)\s*:\s*(.+)$/i;
-function intentGoalForSlug(description, slug) {
-  const text = stripCode(description, { inlineSpans: "keep" });
+function intentsSection(text) {
   const start = text.match(INTENTS_HEADING);
   if (!start || start.index === undefined)
-    return "";
+    return null;
   const rest = text.slice(start.index + start[0].length);
   const next = rest.match(NEXT_HEADING);
-  const section = rest.slice(0, next && next.index !== undefined ? next.index : rest.length);
+  return rest.slice(0, next && next.index !== undefined ? next.index : rest.length);
+}
+function intentGoalForSlug(description, slug) {
+  const text = stripCode(description, { inlineSpans: "keep" });
+  const section = intentsSection(text);
+  if (section === null)
+    return "";
   for (const line of section.split(`
 `)) {
     const trimmed = line.trim();
@@ -1951,6 +1956,7 @@ function parseInlineFieldList(section) {
 // ../../packages/aeg-core/src/verdict-extraction.ts
 var HEAD_SHA_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Judged head:\s*([0-9a-f]{7,40})(?![A-Za-z0-9])/im;
 var OBJECTIVES_VERSION_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Objectives version:\s*([0-9a-f]{64})(?![A-Za-z0-9])/im;
+var RULING_ORDINAL_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Ruling ordinal:\s*(\d+)(?!\d)/im;
 function firstFiveLines(comment) {
   return comment.split(`
 `).slice(0, 5).join(`
@@ -1964,6 +1970,15 @@ function extractObjectivesVersion(comment) {
   const m = firstFiveLines(comment).match(OBJECTIVES_VERSION_PATTERN);
   return m ? m[1].toLowerCase() : null;
 }
+function firstSevenLines(comment) {
+  return comment.split(`
+`).slice(0, 7).join(`
+`);
+}
+function extractRulingOrdinal(comment) {
+  const m = firstSevenLines(comment).match(RULING_ORDINAL_PATTERN);
+  return m ? Number.parseInt(m[1], 10) : null;
+}
 function extractVerdict(comments, valuePattern, missingLabel) {
   const candidates = comments.filter((c) => valuePattern.test(c));
   if (candidates.length === 0) {
@@ -1971,6 +1986,7 @@ function extractVerdict(comments, valuePattern, missingLabel) {
       value: `no ${missingLabel} pass was run before merge — DANGLING, see below`,
       headSha: null,
       objectivesVersion: null,
+      rulingOrdinal: null,
       danglingNote: `no ${missingLabel} verdict comment found on this PR`
     };
   }
@@ -1981,6 +1997,7 @@ function extractVerdict(comments, valuePattern, missingLabel) {
       value: `the most recent ${missingLabel} comment's VERDICT line is not within its first five lines — DANGLING, see below`,
       headSha: null,
       objectivesVersion: null,
+      rulingOrdinal: null,
       danglingNote: `the most recent ${missingLabel} verdict comment carries a VERDICT-shaped line outside the first-five-line read window`
     };
   }
@@ -1988,6 +2005,7 @@ function extractVerdict(comments, valuePattern, missingLabel) {
     value: m[1].toUpperCase().replace(/[_-]/g, " "),
     headSha: extractHeadSha(latest),
     objectivesVersion: extractObjectivesVersion(latest),
+    rulingOrdinal: extractRulingOrdinal(latest),
     danglingNote: null
   };
 }
@@ -2349,6 +2367,9 @@ import { createHash as createHash2 } from "node:crypto";
 var HEADING_RE = /^##[ \t]*Objectives[ \t]*$/im;
 var NEXT_HEADING_RE = /^##[ \t]/m;
 var OBJECTIVE_LINE_RE = /^O(\d+)\.[ \t]*(.*)$/;
+function maskedForHeadingSearch(body) {
+  return maskDetailsBlocks(maskCode(body));
+}
 function hasBacktickedPath(text) {
   let i = 0;
   while (i < text.length) {
@@ -2371,16 +2392,22 @@ function stripObjectiveBackticks(text) {
 function wordCount(text) {
   return text.split(/\s+/).filter((w) => /[a-z]/i.test(w)).length;
 }
-function objectivesSectionText(body) {
-  const heading = HEADING_RE.exec(body);
+function objectivesSectionBounds(body) {
+  const masked = maskedForHeadingSearch(body);
+  const heading = HEADING_RE.exec(masked);
   if (!heading)
     return null;
-  const afterHeading = body.slice(heading.index + heading[0].length);
+  const start = heading.index + heading[0].length;
+  const afterHeading = masked.slice(start);
   const next = NEXT_HEADING_RE.exec(afterHeading);
-  return next ? afterHeading.slice(0, next.index) : afterHeading;
+  return { start, end: next ? start + next.index : body.length };
+}
+function objectivesSectionText(body) {
+  const bounds = objectivesSectionBounds(body);
+  return bounds === null ? null : body.slice(bounds.start, bounds.end);
 }
 function hasObjectivesHeading(body) {
-  return HEADING_RE.test(body);
+  return HEADING_RE.test(maskedForHeadingSearch(body));
 }
 function objectivesOf(body) {
   const section = objectivesSectionText(body);
@@ -2440,6 +2467,15 @@ function isIssueNotFoundError(err) {
 `);
   return /could not resolve to an (?:issue|pull request)|\b404\b|not found/i.test(haystack);
 }
+function resolveObjectivesSource(prBody, issue, cutoverIssue) {
+  if (issue !== null && issue < cutoverIssue)
+    return { kind: "none" };
+  if (issue !== null)
+    return { kind: "issue", issue };
+  if (hasObjectivesHeading(prBody))
+    return { kind: "body" };
+  return { kind: "none" };
+}
 
 // ../../packages/aeg-core/src/premise-check.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -2941,17 +2977,40 @@ function checkBriefSections(prBody, readTier, options = {}) {
   ];
   return { errors: results.flatMap((r) => r.errors) };
 }
-var AEG_BRIEF_V1_MARKER = "<!-- aeg:brief:v1 -->";
-function contentAfterTwoLines(body) {
-  const first = body.indexOf(`
-`);
-  if (first === -1)
-    return "";
-  const second = body.indexOf(`
-`, first + 1);
-  if (second === -1)
-    return "";
-  return body.slice(second + 1);
+function contentAfterNLines(body, n) {
+  let idx = -1;
+  for (let i = 0;i < n; i++) {
+    idx = body.indexOf(`
+`, idx + 1);
+    if (idx === -1)
+      return "";
+  }
+  return body.slice(idx + 1);
+}
+var BRIEF_MARKER_LINE_RE = /^<!-- aeg:brief:v(\d+) -->$/;
+function parseBriefMarkerVersion(firstLine) {
+  const m = BRIEF_MARKER_LINE_RE.exec(firstLine.trim());
+  if (!m)
+    return null;
+  const version = Number.parseInt(m[1], 10);
+  return Number.isInteger(version) && version >= 1 ? version : null;
+}
+function frozenBriefContent(body, version) {
+  return contentAfterNLines(body, version === 1 ? 2 : 3);
+}
+function resolveNewestFrozenBrief(comments, allowlist) {
+  let best = null;
+  for (const c of comments) {
+    if (!isPrincipal(c.author, allowlist))
+      continue;
+    const version = parseBriefMarkerVersion(c.body.split(`
+`)[0] ?? "");
+    if (version === null)
+      continue;
+    if (best === null || version > best.version)
+      best = { ...c, version };
+  }
+  return best === null ? null : { ...best, content: frozenBriefContent(best.body, best.version) };
 }
 // ../../packages/aeg-core/src/doctrine-portability.ts
 var DEFAULT_SHIPS_PREFIX = "aeg-root/";
@@ -3678,6 +3737,11 @@ function isBoundToObjectives(extraction, currentVersion) {
     return true;
   return extraction.objectivesVersion === currentVersion;
 }
+function isBoundToRulings(extraction, currentOrdinal) {
+  if (extraction.rulingOrdinal === null)
+    return currentOrdinal === 0;
+  return extraction.rulingOrdinal === currentOrdinal;
+}
 function checkReviewGate(input) {
   const principalAllowlist = input.principalAllowlist ?? PRINCIPAL_ALLOWLIST;
   const waived = isWaiverLabelActorVerified({
@@ -3706,7 +3770,9 @@ function checkReviewGate(input) {
   const securityBound = isBoundToPatch(security, input.headSha, input.patchIdOf);
   const codeReviewObjectivesBound = isBoundToObjectives(codeReview, input.objectivesVersion);
   const securityObjectivesBound = isBoundToObjectives(security, input.objectivesVersion);
-  if (codeReviewClean && codeReviewBound && codeReviewObjectivesBound && securityClean && securityBound && securityObjectivesBound && mechanicalChecksClean) {
+  const codeReviewRulingsBound = isBoundToRulings(codeReview, input.rulingOrdinal);
+  const securityRulingsBound = isBoundToRulings(security, input.rulingOrdinal);
+  if (codeReviewClean && codeReviewBound && codeReviewObjectivesBound && codeReviewRulingsBound && securityClean && securityBound && securityObjectivesBound && securityRulingsBound && mechanicalChecksClean) {
     return {
       verdict: "pass",
       reason: `code-reviewer verdict is a clean APPROVE and security-review verdict is a clean PASS, both covering head ${input.headSha}, and every reported mechanical check is green.`,
@@ -3720,6 +3786,8 @@ function checkReviewGate(input) {
     problems.push(`the newest code-review verdict covers ${codeReview.headSha ?? "no recorded commit"}, head is ${input.headSha}`);
   } else if (!codeReviewObjectivesBound) {
     problems.push(`the newest code-review verdict was cast against objectives version ${codeReview.objectivesVersion ?? "none"}, the Issue's list is now ${input.objectivesVersion}`);
+  } else if (!codeReviewRulingsBound) {
+    problems.push(`the newest code-review verdict was cast against ruling ordinal ${codeReview.rulingOrdinal ?? "none"}, a newer ruling (ruling ${input.rulingOrdinal}) is now posted on this PR`);
   }
   if (!securityClean) {
     problems.push(`security-review verdict is not a clean PASS (found: ${security.value})`);
@@ -3727,6 +3795,8 @@ function checkReviewGate(input) {
     problems.push(`the newest security-review verdict covers ${security.headSha ?? "no recorded commit"}, head is ${input.headSha}`);
   } else if (!securityObjectivesBound) {
     problems.push(`the newest security-review verdict was cast against objectives version ${security.objectivesVersion ?? "none"}, the Issue's list is now ${input.objectivesVersion}`);
+  } else if (!securityRulingsBound) {
+    problems.push(`the newest security-review verdict was cast against ruling ordinal ${security.rulingOrdinal ?? "none"}, a newer ruling (ruling ${input.rulingOrdinal}) is now posted on this PR`);
   }
   if (!mechanicalChecksClean) {
     problems.push(reportedMechanicalChecks.length === 0 ? "no mechanical checks have reported for this head yet" : `mechanical check(s) not green: ${reportedMechanicalChecks.filter((c) => c.bucket !== "pass").map((c) => `${c.name} (${c.bucket})`).join(", ")}`);
@@ -3743,6 +3813,24 @@ var DEFAULT_RELEASE_ACTOR = "github-actions[bot]";
 function isChangesetsReleasePr(branch, author, expectedAuthor) {
   return branch === CHANGESET_RELEASE_BRANCH && author === expectedAuthor;
 }
+// ../../packages/aeg-core/src/ruling-ordinal.ts
+var RULING_MARKER_ORDINAL = /^<!-- aeg:principal:ruling:\d+-(\d+) -->$/;
+function newestPrincipalRulingOrdinal(comments, allowlist) {
+  let best = 0;
+  for (const c of comments) {
+    if (!isPrincipal(c.author, allowlist))
+      continue;
+    const firstLine = (c.body.split(`
+`)[0] ?? "").trim();
+    const m = RULING_MARKER_ORDINAL.exec(firstLine);
+    if (!m)
+      continue;
+    const k = Number.parseInt(m[1], 10);
+    if (k > best)
+      best = k;
+  }
+  return best;
+}
 // ../../packages/aeg-core/src/markdown-table.ts
 function splitRow(line) {
   const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
@@ -5097,14 +5185,41 @@ var COMMANDS = [
   },
   {
     name: "task dispatch",
-    description: "Render, pin, and post the brief on the Issue as the frozen original; start the developer",
+    description: "Deprecated — render, pin, and post the brief on the Issue as the frozen original; start the developer",
     flags: [
       { flag: "--agent <claude|codex|gemini>", description: "Start the developer through dispatchRole once posted" }
     ],
     details: [
       "Renders the brief from the Issue and the tree (the same assembly `brief render` uses) and posts it once as an Issue comment whose first line is `<!-- aeg:brief:v1 -->` and whose second line is `Brief hash: <sha256>` — the hash covers only the body below those two lines, so any reader recomputes it. Refuses outright, naming the existing comment's URL, when a `v1` comment already exists on the Issue — the brief is frozen by design, never overwritten or silently reissued.",
       "With `--agent`, starts the Developer through `dispatchRole` when `apps/cli/src/lib/dispatch.ts` exports it; otherwise prints the rendered brief and the manual dispatch instruction and exits `0` — a soft dependency, never a hard block.",
-      "Principal-only, with or without `--agent`: refuses before any render, forge read, or post when the authenticated `gh` identity is not on the Principal allowlist (or cannot be resolved at all) — dispatching is the `todo → in-flight` transition, not a general-purpose comment poster."
+      "Principal-only, with or without `--agent`: refuses before any render, forge read, or post when the authenticated `gh` identity is not on the Principal allowlist (or cannot be resolved at all) — dispatching is the `todo → in-flight` transition, not a general-purpose comment poster.",
+      "Deprecated in favor of `task brief` (preparation only) and `task run` (the full unattended loop) — kept for a documented compatibility window while callers migrate."
+    ],
+    status: "shipped"
+  },
+  {
+    name: "task brief",
+    description: "Render and freeze the brief as the Issue's original comment — preparation only, starts nobody",
+    details: [
+      "The preparation half of `task dispatch`, extracted so it is callable on its own: resolves the task's Issue, renders the brief, refuses on any gap, refuses when a frozen brief already exists, and posts it once as the same `aeg:brief:v1` Issue comment `task dispatch` posts. Starts no agent under any circumstances — there is no `--agent` flag here at all.",
+      "Successor to `task dispatch` for the preparation step; the full unattended run (preparation, then the developer, then the review loop) is `task run`."
+    ],
+    status: "shipped"
+  },
+  {
+    name: "task run",
+    description: "One command from a planned Issue to a reviewed pull request — exactly one developer started",
+    flags: [
+      {
+        flag: "--agent <claude|codex|gemini>",
+        description: "Vendor for the developer and both reviewers this run dispatches"
+      }
+    ],
+    details: [
+      "Composes `task brief`'s own preparation (`prepareTask`) with `dev-review-loop` (`devReviewLoop`) — nothing else. Preparation starts no agent; the loop's own round 1 reads the frozen brief off the Issue and is the only place a developer is ever dispatched from a fresh task, so exactly one developer is started by construction.",
+      "A brief already frozen on the Issue is reused, never re-posted — the second `task dispatch`/`task brief` call this composes around does not fail the whole run, it just skips straight to running the loop. A task whose Issue refuses preparation (a missing brief section, an unmet dispatch gate) is refused before any agent starts, with nothing posted.",
+      "Refuses when the frozen brief's developer branch already has an open pull request — the old `task dispatch` followed by `task run` cannot start two developers this way.",
+      "Exit and printed summary distinguish a published, reviewed pull request (exit `0`, the PR URL) from a pause (exit `1`, with the exact `vinaya dev-review-loop --resume <pr>` command to continue), a usage/argv error (exit `2`), and any other failure (exit `3`) — never sharing `1` with a pause, so an unattended host tells them apart from the exit code alone. A run that pauses is resumed with the loop's own existing `--resume <pr>` flag, never a flag on this command."
     ],
     status: "shipped"
   },
@@ -5312,6 +5427,15 @@ var COMMANDS = [
     ],
     status: "shipped"
   },
+  {
+    name: "milestone status",
+    description: "Print each of a Milestone's declared tranche intents with its derived lifecycle and issue counts",
+    flags: [{ flag: "--json", description: "Enveloped JSON output (schema: 1)" }],
+    details: [
+      "Read-only — writes nothing. For each `- <slug>: …` line in the Milestone's `### Tranche intents` section, prints the tranche's lifecycle (`planned`/`active`/`complete`) and its labeled Issues' counts (merged, open, not planned), all derived from the forge. Refuses if `<n>` isn't a real Milestone in this repo, or if the forge is unreachable."
+    ],
+    status: "shipped"
+  },
   {
     name: "review status",
     description: "Print the review loop's own state for a PR, and its branch's distance from the base",

package/dist/checks/bin/check-doc-coverage-push.js

@@ -304,7 +304,7 @@ function issueListByLabelArgs(owner, repo, label) {
     "--state",
     "all",
     "--json",
-    "number,title,body,state,labels,milestone",
+    "number,title,body,state,labels,milestone,stateReason",
     "--limit",
     "200"
   ];
@@ -650,14 +650,19 @@ function resolveTaskIssueRef(title, labels) {
 var INTENTS_HEADING = /^#{1,6}\s*Tranche intents\s*$/im;
 var NEXT_HEADING = /^#{1,6}\s+\S/m;
 var INTENT_BULLET = /^-\s+([a-z0-9][a-z0-9-]*)\s*:\s*(.+)$/i;
-function intentGoalForSlug(description, slug) {
-  const text = stripCode(description, { inlineSpans: "keep" });
+function intentsSection(text) {
   const start = text.match(INTENTS_HEADING);
   if (!start || start.index === undefined)
-    return "";
+    return null;
   const rest = text.slice(start.index + start[0].length);
   const next = rest.match(NEXT_HEADING);
-  const section = rest.slice(0, next && next.index !== undefined ? next.index : rest.length);
+  return rest.slice(0, next && next.index !== undefined ? next.index : rest.length);
+}
+function intentGoalForSlug(description, slug) {
+  const text = stripCode(description, { inlineSpans: "keep" });
+  const section = intentsSection(text);
+  if (section === null)
+    return "";
   for (const line of section.split(`
 `)) {
     const trimmed = line.trim();
@@ -1949,6 +1954,7 @@ function parseInlineFieldList(section) {
 // ../../packages/aeg-core/src/verdict-extraction.ts
 var HEAD_SHA_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Judged head:\s*([0-9a-f]{7,40})(?![A-Za-z0-9])/im;
 var OBJECTIVES_VERSION_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Objectives version:\s*([0-9a-f]{64})(?![A-Za-z0-9])/im;
+var RULING_ORDINAL_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Ruling ordinal:\s*(\d+)(?!\d)/im;
 function firstFiveLines(comment) {
   return comment.split(`
 `).slice(0, 5).join(`
@@ -1962,6 +1968,15 @@ function extractObjectivesVersion(comment) {
   const m = firstFiveLines(comment).match(OBJECTIVES_VERSION_PATTERN);
   return m ? m[1].toLowerCase() : null;
 }
+function firstSevenLines(comment) {
+  return comment.split(`
+`).slice(0, 7).join(`
+`);
+}
+function extractRulingOrdinal(comment) {
+  const m = firstSevenLines(comment).match(RULING_ORDINAL_PATTERN);
+  return m ? Number.parseInt(m[1], 10) : null;
+}
 function extractVerdict(comments, valuePattern, missingLabel) {
   const candidates = comments.filter((c) => valuePattern.test(c));
   if (candidates.length === 0) {
@@ -1969,6 +1984,7 @@ function extractVerdict(comments, valuePattern, missingLabel) {
       value: `no ${missingLabel} pass was run before merge — DANGLING, see below`,
       headSha: null,
       objectivesVersion: null,
+      rulingOrdinal: null,
       danglingNote: `no ${missingLabel} verdict comment found on this PR`
     };
   }
@@ -1979,6 +1995,7 @@ function extractVerdict(comments, valuePattern, missingLabel) {
       value: `the most recent ${missingLabel} comment's VERDICT line is not within its first five lines — DANGLING, see below`,
       headSha: null,
       objectivesVersion: null,
+      rulingOrdinal: null,
       danglingNote: `the most recent ${missingLabel} verdict comment carries a VERDICT-shaped line outside the first-five-line read window`
     };
   }
@@ -1986,6 +2003,7 @@ function extractVerdict(comments, valuePattern, missingLabel) {
     value: m[1].toUpperCase().replace(/[_-]/g, " "),
     headSha: extractHeadSha(latest),
     objectivesVersion: extractObjectivesVersion(latest),
+    rulingOrdinal: extractRulingOrdinal(latest),
     danglingNote: null
   };
 }
@@ -2347,6 +2365,9 @@ import { createHash as createHash2 } from "node:crypto";
 var HEADING_RE = /^##[ \t]*Objectives[ \t]*$/im;
 var NEXT_HEADING_RE = /^##[ \t]/m;
 var OBJECTIVE_LINE_RE = /^O(\d+)\.[ \t]*(.*)$/;
+function maskedForHeadingSearch(body) {
+  return maskDetailsBlocks(maskCode(body));
+}
 function hasBacktickedPath(text) {
   let i = 0;
   while (i < text.length) {
@@ -2369,16 +2390,22 @@ function stripObjectiveBackticks(text) {
 function wordCount(text) {
   return text.split(/\s+/).filter((w) => /[a-z]/i.test(w)).length;
 }
-function objectivesSectionText(body) {
-  const heading = HEADING_RE.exec(body);
+function objectivesSectionBounds(body) {
+  const masked = maskedForHeadingSearch(body);
+  const heading = HEADING_RE.exec(masked);
   if (!heading)
     return null;
-  const afterHeading = body.slice(heading.index + heading[0].length);
+  const start = heading.index + heading[0].length;
+  const afterHeading = masked.slice(start);
   const next = NEXT_HEADING_RE.exec(afterHeading);
-  return next ? afterHeading.slice(0, next.index) : afterHeading;
+  return { start, end: next ? start + next.index : body.length };
+}
+function objectivesSectionText(body) {
+  const bounds = objectivesSectionBounds(body);
+  return bounds === null ? null : body.slice(bounds.start, bounds.end);
 }
 function hasObjectivesHeading(body) {
-  return HEADING_RE.test(body);
+  return HEADING_RE.test(maskedForHeadingSearch(body));
 }
 function objectivesOf(body) {
   const section = objectivesSectionText(body);
@@ -2438,6 +2465,15 @@ function isIssueNotFoundError(err) {
 `);
   return /could not resolve to an (?:issue|pull request)|\b404\b|not found/i.test(haystack);
 }
+function resolveObjectivesSource(prBody, issue, cutoverIssue) {
+  if (issue !== null && issue < cutoverIssue)
+    return { kind: "none" };
+  if (issue !== null)
+    return { kind: "issue", issue };
+  if (hasObjectivesHeading(prBody))
+    return { kind: "body" };
+  return { kind: "none" };
+}
 
 // ../../packages/aeg-core/src/premise-check.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -2939,17 +2975,40 @@ function checkBriefSections(prBody, readTier, options = {}) {
   ];
   return { errors: results.flatMap((r) => r.errors) };
 }
-var AEG_BRIEF_V1_MARKER = "<!-- aeg:brief:v1 -->";
-function contentAfterTwoLines(body) {
-  const first = body.indexOf(`
-`);
-  if (first === -1)
-    return "";
-  const second = body.indexOf(`
-`, first + 1);
-  if (second === -1)
-    return "";
-  return body.slice(second + 1);
+function contentAfterNLines(body, n) {
+  let idx = -1;
+  for (let i = 0;i < n; i++) {
+    idx = body.indexOf(`
+`, idx + 1);
+    if (idx === -1)
+      return "";
+  }
+  return body.slice(idx + 1);
+}
+var BRIEF_MARKER_LINE_RE = /^<!-- aeg:brief:v(\d+) -->$/;
+function parseBriefMarkerVersion(firstLine) {
+  const m = BRIEF_MARKER_LINE_RE.exec(firstLine.trim());
+  if (!m)
+    return null;
+  const version = Number.parseInt(m[1], 10);
+  return Number.isInteger(version) && version >= 1 ? version : null;
+}
+function frozenBriefContent(body, version) {
+  return contentAfterNLines(body, version === 1 ? 2 : 3);
+}
+function resolveNewestFrozenBrief(comments, allowlist) {
+  let best = null;
+  for (const c of comments) {
+    if (!isPrincipal(c.author, allowlist))
+      continue;
+    const version = parseBriefMarkerVersion(c.body.split(`
+`)[0] ?? "");
+    if (version === null)
+      continue;
+    if (best === null || version > best.version)
+      best = { ...c, version };
+  }
+  return best === null ? null : { ...best, content: frozenBriefContent(best.body, best.version) };
 }
 // ../../packages/aeg-core/src/doctrine-portability.ts
 var DEFAULT_SHIPS_PREFIX = "aeg-root/";
@@ -3676,6 +3735,11 @@ function isBoundToObjectives(extraction, currentVersion) {
     return true;
   return extraction.objectivesVersion === currentVersion;
 }
+function isBoundToRulings(extraction, currentOrdinal) {
+  if (extraction.rulingOrdinal === null)
+    return currentOrdinal === 0;
+  return extraction.rulingOrdinal === currentOrdinal;
+}
 function checkReviewGate(input) {
   const principalAllowlist = input.principalAllowlist ?? PRINCIPAL_ALLOWLIST;
   const waived = isWaiverLabelActorVerified({
@@ -3704,7 +3768,9 @@ function checkReviewGate(input) {
   const securityBound = isBoundToPatch(security, input.headSha, input.patchIdOf);
   const codeReviewObjectivesBound = isBoundToObjectives(codeReview, input.objectivesVersion);
   const securityObjectivesBound = isBoundToObjectives(security, input.objectivesVersion);
-  if (codeReviewClean && codeReviewBound && codeReviewObjectivesBound && securityClean && securityBound && securityObjectivesBound && mechanicalChecksClean) {
+  const codeReviewRulingsBound = isBoundToRulings(codeReview, input.rulingOrdinal);
+  const securityRulingsBound = isBoundToRulings(security, input.rulingOrdinal);
+  if (codeReviewClean && codeReviewBound && codeReviewObjectivesBound && codeReviewRulingsBound && securityClean && securityBound && securityObjectivesBound && securityRulingsBound && mechanicalChecksClean) {
     return {
       verdict: "pass",
       reason: `code-reviewer verdict is a clean APPROVE and security-review verdict is a clean PASS, both covering head ${input.headSha}, and every reported mechanical check is green.`,
@@ -3718,6 +3784,8 @@ function checkReviewGate(input) {
     problems.push(`the newest code-review verdict covers ${codeReview.headSha ?? "no recorded commit"}, head is ${input.headSha}`);
   } else if (!codeReviewObjectivesBound) {
     problems.push(`the newest code-review verdict was cast against objectives version ${codeReview.objectivesVersion ?? "none"}, the Issue's list is now ${input.objectivesVersion}`);
+  } else if (!codeReviewRulingsBound) {
+    problems.push(`the newest code-review verdict was cast against ruling ordinal ${codeReview.rulingOrdinal ?? "none"}, a newer ruling (ruling ${input.rulingOrdinal}) is now posted on this PR`);
   }
   if (!securityClean) {
     problems.push(`security-review verdict is not a clean PASS (found: ${security.value})`);
@@ -3725,6 +3793,8 @@ function checkReviewGate(input) {
     problems.push(`the newest security-review verdict covers ${security.headSha ?? "no recorded commit"}, head is ${input.headSha}`);
   } else if (!securityObjectivesBound) {
     problems.push(`the newest security-review verdict was cast against objectives version ${security.objectivesVersion ?? "none"}, the Issue's list is now ${input.objectivesVersion}`);
+  } else if (!securityRulingsBound) {
+    problems.push(`the newest security-review verdict was cast against ruling ordinal ${security.rulingOrdinal ?? "none"}, a newer ruling (ruling ${input.rulingOrdinal}) is now posted on this PR`);
   }
   if (!mechanicalChecksClean) {
     problems.push(reportedMechanicalChecks.length === 0 ? "no mechanical checks have reported for this head yet" : `mechanical check(s) not green: ${reportedMechanicalChecks.filter((c) => c.bucket !== "pass").map((c) => `${c.name} (${c.bucket})`).join(", ")}`);
@@ -3741,6 +3811,24 @@ var DEFAULT_RELEASE_ACTOR = "github-actions[bot]";
 function isChangesetsReleasePr(branch, author, expectedAuthor) {
   return branch === CHANGESET_RELEASE_BRANCH && author === expectedAuthor;
 }
+// ../../packages/aeg-core/src/ruling-ordinal.ts
+var RULING_MARKER_ORDINAL = /^<!-- aeg:principal:ruling:\d+-(\d+) -->$/;
+function newestPrincipalRulingOrdinal(comments, allowlist) {
+  let best = 0;
+  for (const c of comments) {
+    if (!isPrincipal(c.author, allowlist))
+      continue;
+    const firstLine = (c.body.split(`
+`)[0] ?? "").trim();
+    const m = RULING_MARKER_ORDINAL.exec(firstLine);
+    if (!m)
+      continue;
+    const k = Number.parseInt(m[1], 10);
+    if (k > best)
+      best = k;
+  }
+  return best;
+}
 // ../../packages/aeg-core/src/markdown-table.ts
 function splitRow(line) {
   const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
@@ -5408,14 +5496,41 @@ var COMMANDS = [
   },
   {
     name: "task dispatch",
-    description: "Render, pin, and post the brief on the Issue as the frozen original; start the developer",
+    description: "Deprecated — render, pin, and post the brief on the Issue as the frozen original; start the developer",
     flags: [
       { flag: "--agent <claude|codex|gemini>", description: "Start the developer through dispatchRole once posted" }
     ],
     details: [
       "Renders the brief from the Issue and the tree (the same assembly `brief render` uses) and posts it once as an Issue comment whose first line is `<!-- aeg:brief:v1 -->` and whose second line is `Brief hash: <sha256>` — the hash covers only the body below those two lines, so any reader recomputes it. Refuses outright, naming the existing comment's URL, when a `v1` comment already exists on the Issue — the brief is frozen by design, never overwritten or silently reissued.",
       "With `--agent`, starts the Developer through `dispatchRole` when `apps/cli/src/lib/dispatch.ts` exports it; otherwise prints the rendered brief and the manual dispatch instruction and exits `0` — a soft dependency, never a hard block.",
-      "Principal-only, with or without `--agent`: refuses before any render, forge read, or post when the authenticated `gh` identity is not on the Principal allowlist (or cannot be resolved at all) — dispatching is the `todo → in-flight` transition, not a general-purpose comment poster."
+      "Principal-only, with or without `--agent`: refuses before any render, forge read, or post when the authenticated `gh` identity is not on the Principal allowlist (or cannot be resolved at all) — dispatching is the `todo → in-flight` transition, not a general-purpose comment poster.",
+      "Deprecated in favor of `task brief` (preparation only) and `task run` (the full unattended loop) — kept for a documented compatibility window while callers migrate."
+    ],
+    status: "shipped"
+  },
+  {
+    name: "task brief",
+    description: "Render and freeze the brief as the Issue's original comment — preparation only, starts nobody",
+    details: [
+      "The preparation half of `task dispatch`, extracted so it is callable on its own: resolves the task's Issue, renders the brief, refuses on any gap, refuses when a frozen brief already exists, and posts it once as the same `aeg:brief:v1` Issue comment `task dispatch` posts. Starts no agent under any circumstances — there is no `--agent` flag here at all.",
+      "Successor to `task dispatch` for the preparation step; the full unattended run (preparation, then the developer, then the review loop) is `task run`."
+    ],
+    status: "shipped"
+  },
+  {
+    name: "task run",
+    description: "One command from a planned Issue to a reviewed pull request — exactly one developer started",
+    flags: [
+      {
+        flag: "--agent <claude|codex|gemini>",
+        description: "Vendor for the developer and both reviewers this run dispatches"
+      }
+    ],
+    details: [
+      "Composes `task brief`'s own preparation (`prepareTask`) with `dev-review-loop` (`devReviewLoop`) — nothing else. Preparation starts no agent; the loop's own round 1 reads the frozen brief off the Issue and is the only place a developer is ever dispatched from a fresh task, so exactly one developer is started by construction.",
+      "A brief already frozen on the Issue is reused, never re-posted — the second `task dispatch`/`task brief` call this composes around does not fail the whole run, it just skips straight to running the loop. A task whose Issue refuses preparation (a missing brief section, an unmet dispatch gate) is refused before any agent starts, with nothing posted.",
+      "Refuses when the frozen brief's developer branch already has an open pull request — the old `task dispatch` followed by `task run` cannot start two developers this way.",
+      "Exit and printed summary distinguish a published, reviewed pull request (exit `0`, the PR URL) from a pause (exit `1`, with the exact `vinaya dev-review-loop --resume <pr>` command to continue), a usage/argv error (exit `2`), and any other failure (exit `3`) — never sharing `1` with a pause, so an unattended host tells them apart from the exit code alone. A run that pauses is resumed with the loop's own existing `--resume <pr>` flag, never a flag on this command."
     ],
     status: "shipped"
   },
@@ -5623,6 +5738,15 @@ var COMMANDS = [
     ],
     status: "shipped"
   },
+  {
+    name: "milestone status",
+    description: "Print each of a Milestone's declared tranche intents with its derived lifecycle and issue counts",
+    flags: [{ flag: "--json", description: "Enveloped JSON output (schema: 1)" }],
+    details: [
+      "Read-only — writes nothing. For each `- <slug>: …` line in the Milestone's `### Tranche intents` section, prints the tranche's lifecycle (`planned`/`active`/`complete`) and its labeled Issues' counts (merged, open, not planned), all derived from the forge. Refuses if `<n>` isn't a real Milestone in this repo, or if the forge is unreachable."
+    ],
+    status: "shipped"
+  },
   {
     name: "review status",
     description: "Print the review loop's own state for a PR, and its branch's distance from the base",