@attalabs/vinaya 0.22.0 → 0.24.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/review-gate.ts

@@ -0,0 +1,378 @@
+/**
+ * Required pre-merge review gate (aeg-review-gate-v1 task 1, #474). Blocks a
+ * PR from merging unless a clean code-reviewer `APPROVE` verdict
+ * AND a clean security-review `PASS` verdict both exist on the PR — the same
+ * `extractCodeReviewVerdict`/`extractSecurityReviewVerdict` detection
+ * (`verdict-extraction.ts`) the post-merge Archivist automation already runs,
+ * now gated pre-merge and blocking instead of post-merge and advisory-only.
+ *
+ * Verdict comments are ONLY counted when their author is on the same
+ * `PRINCIPAL_ALLOWLIST` the waiver actor-check trusts (security finding,
+ * PR #806): body-shape alone is never sufficient on a public repo. Unverified
+ * comments are ignored, not fatal.
+ *
+ * A verified `vinaya/waiver:review` label (the exact actor-verification pattern,
+ * `isWaiverLabelActorVerified` reused directly and parameterized by label —
+ * see `waiver-label.ts`) lets a principal explicitly skip the requirement for
+ * one PR. Label presence alone is never sufficient — only an actor-verified
+ * label waives the gate, mirroring exactly.
+ *
+ * Reviewed-commit binding (#73, a duplicate of #71 closes this one). A clean
+ * verdict is no longer sufficient on its own — it must also cover the PR's
+ * CURRENT head. Design record (the four questions this fix had to answer,
+ * argued in full in the closing PR's body):
+ *
+ * 1. Commit sha, not tree hash. `headSha` is `gh pr view --json headRefOid`
+ *    verbatim — one API call, no second fetch of a commit object's tree.
+ *    Matches the Issue's own proposed fix shape and the hand-typed
+ *    convention reviewers were already using ("Judged head: <sha>", never a
+ *    tree hash). Cost accepted: a rebase or an empty amend that leaves the
+ *    tree byte-identical still invalidates every verdict — no free pass for
+ *    "the code didn't really change." That is the explicit trade for a
+ *    single mental model ("a verdict covers an exact commit") over a cheaper
+ *    but subtler one (two different code states could share a tree).
+ * 2. Every push that changes `headRefOid` invalidates unconditionally — a
+ *    rebase with an identical tree, a merge commit resolving a conflict
+ *    elsewhere, and a genuine content-changing amend all produce a new sha
+ *    and therefore a new required verdict. Only a push that does NOT change
+ *    `headRefOid` at all (a body-only PR-description edit; a force-push that
+ *    reproduces the exact same commit object) leaves an existing binding
+ *    intact, because there is nothing for it to have gone stale against.
+ * 3. `headSha` is REQUIRED on `ReviewGateInput`, not optional. An optional
+ *    field that silently skips the binding check when absent is fail-open —
+ *    exactly the defect class this task exists to close. Every caller
+ *    (`bin/verify-review-gate.ts`, `apps/cli/src/checks/bin/check-review-gate.ts`)
+ *    must supply it; the type system enforces that, not a runtime default.
+ * 4. Fail-closed for the transition. The moment this merges, every verdict
+ *    already posted on an open PR is unbound (it carries no `Judged head:`
+ *    line) and the gate stops honouring it — expensive, and correct: an
+ *    unbound verdict is exactly the property this task closes. The sanctioned
+ *    escape for a PR already far along in review is the existing
+ *    `vinaya/waiver:review` actor-verified label, applied by a principal, the
+ *    same mechanism that already exists for any other one-off skip.
+ *
+ * Pure — no `fs`, no `fetch`, no `process.env`. The CLI shim
+ * (`bin/verify-review-gate.ts`) resolves the PR's comments/labels/label-actor/
+ * head sha via `gh` and calls `checkReviewGate`.
+ */
+
+import { isPrincipal, isWaiverLabelActorVerified, PRINCIPAL_ALLOWLIST, WAIVER_LABEL_REVIEW } from './waiver-label'
+import { extractCodeReviewVerdict, extractSecurityReviewVerdict } from './verdict-extraction'
+
+export type ReviewGateVerdict = 'pass' | 'fail'
+
+export type ReviewGateResult = {
+  verdict: ReviewGateVerdict
+  reason: string
+  waived: boolean
+}
+
+export type ReviewGateComment = {
+  body: string
+  /** The comment author's GitHub login, or `null` when the caller could not resolve one. */
+  author: string | null
+}
+
+export type MechanicalCheckStatus = {
+  /** The check-run's display name, as GitHub reports it (`gh pr checks`' own `name` field). */
+  name: string
+  /** GitHub's own coalesced status vocabulary for this check-run — forwarded verbatim from `gh pr checks --json name,bucket`'s `bucket` field (e.g. "pass", "fail", "pending", "skipping", "cancel"). Not re-mapped to a smaller enum here — that would be a second copy of a vocabulary `gh` already owns. */
+  bucket: string
+}
+
+export type ReviewGateInput = {
+  /** Every comment on the PR, with its author. */
+  comments: ReviewGateComment[]
+  /** Every label currently applied to the PR. */
+  labels: string[]
+  /** Actor of the most recent `vinaya/waiver:review` labeling timeline event, or `null` when none exists. */
+  waiverLabelActor: string | null
+  /**
+   * The PR's current head commit sha (`gh pr view --json headRefOid`),
+   * resolved from GitHub — never from local git, an env var, or the PR's own
+   * checkout, all three of which a `pull_request`-triggered workflow's
+   * PR-editable YAML could steer (#73). REQUIRED, not optional: an omitted
+   * head would have to mean either skip-the-binding-check (fail-open, the
+   * exact defect this field exists to close) or unconditional-fail, and a
+   * required field makes that choice a compile error instead of a runtime
+   * default. Every verdict must cover this value to count as clean.
+   */
+  headSha: string
+  /**
+   * Every check-run reported for the PR's current head, EXCLUDING this
+   * repo's own review-gate check-run (the caller filters that out before
+   * calling in — see check-review-gate.ts's own comment for why the
+   * exclusion must not live here). An empty array means no mechanical
+   * check-run has reported yet, which does NOT count as clean — there is
+   * no proof to point to, not an implicit pass.
+   */
+  mechanicalChecks: MechanicalCheckStatus[]
+  /**
+   * Overrides `PRINCIPAL_ALLOWLIST` for this evaluation when provided — an
+   * adopter repo's own `vinaya.config.json` `principals` field, resolved by
+   * the CLI bin before calling in (never read from here; this stays pure).
+   * Defaults to `PRINCIPAL_ALLOWLIST` when omitted, so every existing caller
+   * (this repo's own `bin/verify-review-gate.ts` included) is unaffected.
+   * `PRINCIPAL_ALLOWLIST` hardcoding this repo's own principal made the gate
+   * structurally unpassable on any adopter repo — found live on a real
+   * client repo's first dispatched task, the reviewer/security verdicts it
+   * already had counted for nobody.
+   */
+  principalAllowlist?: string[]
+  /**
+   * The PATCH IDENTITY of a commit — `git diff <base>...<sha> | git patch-id
+   * --stable`, truncated — or `null` when git cannot answer for that sha
+   * (an unreachable commit after a force-push, a shallow clone, no git at
+   * all). Supplied by the caller because this module is pure; omitted
+   * entirely, the gate behaves exactly as before.
+   *
+   * Why a second binding at all: a verdict was judged, the branch merged
+   * `origin/main` to clear a stale base, and the verdict died — for a merge
+   * commit that changed not one line of the PR's own patch. Re-reviewing
+   * an identical patch is a round spent proving nothing. Patch identity is
+   * what a reviewer actually judged; the head sha is only its address.
+   *
+   * Two known limits, stated rather than papered over.
+   *
+   * A base that moved under an identical patch can carry a semantic conflict
+   * the earlier review could not have seen, and this binding will still
+   * hold. That is the same limit GitHub's own stale-review rule has, and CI
+   * at the new head — which this gate already requires green — is the guard
+   * for it.
+   *
+   * `git patch-id --stable` ignores whitespace, so a push that changes only
+   * whitespace produces the same patch identity and KEEPS the verdict. That
+   * is deliberate for reformatting, but it is not free: whitespace is
+   * semantic in some languages and some string literals, so a push that is
+   * whitespace-only to git can still change behaviour. Any change to
+   * non-whitespace content produces a different identity and correctly drops
+   * the verdict; only the whitespace-only case survives unreviewed.
+   */
+  patchIdOf?: (sha: string) => string | null
+}
+
+/**
+ * Branch names are contributor-controlled metadata, so none can exempt an
+ * authority check. The former `plan/*` exemption assumed those branches
+ * contained topology docs only; a contributor could put code on a branch
+ * with that prefix and make the adapter exit before it fetched the PR. Keep
+ * this exported predicate for API compatibility, but fail closed for every
+ * branch. A future plan-only exemption would need server-derived changed-file
+ * validation, not a name prefix.
+ */
+export function isReviewGateExemptBranch(_branch: string): boolean {
+  return false
+}
+
+/**
+ * True when `extraction.headSha` covers `headSha` — an exact match, or
+ * `headSha` starting with `extraction.headSha` (the abbreviated-sha case:
+ * a verdict may bind against a 7-char prefix, and `headSha` itself is always
+ * the full 40-char form GitHub's API returns). `false` when the extraction
+ * carries no `headSha` at all (no `Judged head:` line was found) — an
+ * unbound verdict never counts as covering anything.
+ */
+function isBoundToHead(extraction: { headSha: string | null }, headSha: string): boolean {
+  if (!extraction.headSha) return false
+  return headSha.toLowerCase().startsWith(extraction.headSha.toLowerCase())
+}
+
+/**
+ * True when the judged head and the current head carry the SAME patch — the
+ * verdict was cast on this exact set of changes, whatever sha now addresses
+ * it. Composed BESIDE `isBoundToHead`, never in place of it: sha binding
+ * still counts on its own, and this only widens what else counts.
+ *
+ * Fails closed on every uncertainty. `null` on either side is "git could not
+ * answer", not "they match" — a force-push that makes the judged head
+ * unreachable resolves to `null` and the verdict correctly stops counting.
+ */
+function isBoundByPatchIdentity(
+  extraction: { headSha: string | null },
+  headSha: string,
+  patchIdOf?: (sha: string) => string | null
+): boolean {
+  if (patchIdOf === undefined || !extraction.headSha) return false
+  const judged = patchIdOf(extraction.headSha)
+  const current = patchIdOf(headSha)
+  if (judged === null || current === null) return false
+  return judged === current
+}
+
+/** A verdict covers the current head when its sha binds it, or its patch identity does. */
+function isBoundToPatch(
+  extraction: { headSha: string | null },
+  headSha: string,
+  patchIdOf?: (sha: string) => string | null
+): boolean {
+  return isBoundToHead(extraction, headSha) || isBoundByPatchIdentity(extraction, headSha, patchIdOf)
+}
+
+/**
+ * `pass` when either (a) `vinaya/waiver:review` is present and actor-verified against
+ * `PRINCIPAL_ALLOWLIST`, or (b) both verdicts are clean AND bound — code-reviewer
+ * `APPROVE` (not `REQUEST_CHANGES`, not missing, not unclear) covering the PR's
+ * current `headSha` — by that sha, or by an equal patch identity when
+ * `patchIdOf` is supplied — and security-review `PASS` (not `FAIL`, not
+ * missing, not unclear) covering it too — AND every reported mechanical check-run for that
+ * same head is green, a `skipping`/`neutral` entry (a job whose own `if:`
+ * was false for this event) filtered out first as absent rather than
+ * counted either way (`mechanicalChecks`, after that filter, non-empty and
+ * every remaining entry's `bucket` is `"pass"`). `fail` otherwise, naming
+ * exactly which verdict(s) are not clean, not bound to the current head,
+ * which mechanical check(s) are not green, or that none have reported at
+ * all.
+ */
+export function checkReviewGate(input: ReviewGateInput): ReviewGateResult {
+  const principalAllowlist = input.principalAllowlist ?? PRINCIPAL_ALLOWLIST
+  const waived = isWaiverLabelActorVerified({
+    label: WAIVER_LABEL_REVIEW,
+    labels: input.labels,
+    labelActor: input.waiverLabelActor,
+    principalAllowlist
+  })
+  if (waived) {
+    return {
+      verdict: 'pass',
+      reason: `\`${WAIVER_LABEL_REVIEW}\` label is actor-verified — review requirement waived for this PR.`,
+      waived: true
+    }
+  }
+
+  // A `skipping` (GitHub `conclusion: "skipped"` or `"neutral"`) check-run is
+  // ABSENT, never a failure (Issue #402 O4): a job whose own `if:` is false
+  // for this event still reports a check-run — `vinaya-review.yml`'s
+  // `retrigger-on-ci-green` job reports `skipped` on every ordinary
+  // `pull_request_target` run — and counting that as "not green" blocked
+  // every PR (first seen on PR #401: "vinaya review gate (retrigger on CI
+  // green) (skipping)"). Filtered out before both the emptiness check and
+  // the clean-check, so a head reporting only skipped/neutral runs reads as
+  // "nothing has reported yet", not as a false pass.
+  const reportedMechanicalChecks = input.mechanicalChecks.filter(
+    (c) => c.bucket !== 'skipping' && c.bucket !== 'neutral'
+  )
+  const mechanicalChecksClean =
+    reportedMechanicalChecks.length > 0 && reportedMechanicalChecks.every((c) => c.bucket === 'pass')
+
+  // Verdict-AUTHOR verification (security finding on PR #806): on a public
+  // repo any GitHub account can post a `VERDICT: APPROVE`-shaped comment, and
+  // most-recent-clear-hit-wins extraction would let a forged later APPROVE
+  // override a real earlier REQUEST CHANGES. Only comments whose author is on
+  // the same `PRINCIPAL_ALLOWLIST` the waiver's actor check already trusts
+  // participate in verdict extraction; everything else — unknown authors and
+  // unresolvable (`null`) ones alike — is IGNORED, never fatal, so a drive-by
+  // comment cannot brick evaluation, only fail to count. Dispatched reviewer
+  // agents post under the principal's own `gh` identity, so the legitimate
+  // flow is unchanged.
+  const verified = input.comments.filter((c) => isPrincipal(c.author, principalAllowlist))
+  // Count only VERDICT-shaped ignored comments — deployment bots and ordinary
+  // chat are also non-allowlisted, and counting them would imply forgery
+  // where there is only noise (review finding, PR #806).
+  const ignoredCount = input.comments.filter(
+    (c) => !isPrincipal(c.author, principalAllowlist) && c.body.includes('VERDICT')
+  ).length
+  const verifiedBodies = verified.map((c) => c.body)
+
+  const codeReview = extractCodeReviewVerdict(verifiedBodies)
+  const security = extractSecurityReviewVerdict(verifiedBodies)
+  const codeReviewClean = codeReview.value === 'APPROVE'
+  const securityClean = security.value === 'PASS'
+  const codeReviewBound = isBoundToPatch(codeReview, input.headSha, input.patchIdOf)
+  const securityBound = isBoundToPatch(security, input.headSha, input.patchIdOf)
+
+  if (codeReviewClean && codeReviewBound && securityClean && securityBound && 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.`,
+      waived: false
+    }
+  }
+
+  const problems: string[] = []
+  if (!codeReviewClean) {
+    problems.push(`code-reviewer verdict is not a clean APPROVE (found: ${codeReview.value})`)
+  } else if (!codeReviewBound) {
+    problems.push(
+      `the newest code-review verdict covers ${codeReview.headSha ?? 'no recorded commit'}, head is ${input.headSha}`
+    )
+  }
+  if (!securityClean) {
+    problems.push(`security-review verdict is not a clean PASS (found: ${security.value})`)
+  } else if (!securityBound) {
+    problems.push(
+      `the newest security-review verdict covers ${security.headSha ?? 'no recorded commit'}, head is ${input.headSha}`
+    )
+  }
+  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(', ')}`
+    )
+  }
+  const ignoredNote =
+    ignoredCount > 0
+      ? ` ${ignoredCount} verdict-shaped comment(s) from authors outside the principal allowlist were ignored.`
+      : ''
+
+  return {
+    verdict: 'fail',
+    reason: `${problems.join('; ')}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).${ignoredNote}`,
+    waived: false
+  }
+}
+
+/**
+ * Exported so a caller can cheaply pre-check the branch BEFORE paying for
+ * whatever it takes to resolve `expectedAuthor` — resolving that value is a
+ * network round-trip (`resolveReleaseActor(loadTrustAnchorConfig())`) that
+ * must not run on every ordinary PR just because it is one of three
+ * arguments to `isChangesetsReleasePr`. Found live (code review, PR #169):
+ * evaluating it inline as a function argument runs it unconditionally,
+ * regardless of branch, since JS evaluates arguments eagerly.
+ */
+export const CHANGESET_RELEASE_BRANCH = 'changeset-release/main'
+
+/**
+ * The stock Changesets flow's default identity — a release PR opened by
+ * `changesets/action` using the ambient `GITHUB_TOKEN` shows this as its
+ * author. Only a SANE DEFAULT for adopters who haven't configured
+ * `releaseActor` — never assume it matches any specific repo's real setup.
+ * A repo that opens release PRs with a custom PAT (this repo's own
+ * `RELEASE_TOKEN`, `.github/workflows/release.yml`) has a DIFFERENT real PR
+ * author (the token's owner) and must set `releaseActor` in its
+ * `vinaya.config.json`.
+ */
+export const DEFAULT_RELEASE_ACTOR = 'github-actions[bot]'
+
+/**
+ * True only for the Changesets release PR. `branch` and `author` must both
+ * match — `branch` alone is not a trust boundary, an attacker can push a
+ * branch literally called `changeset-release/main`. `expectedAuthor` is
+ * caller-resolved, never hardcoded here — this ships in the published
+ * `@attalabs/vinaya` package, and hardcoding any one identity would be
+ * correct for at most one adopter's release-token setup. Callers resolve it
+ * via `resolveReleaseActor(loadTrustAnchorConfig())`, falling back to
+ * `DEFAULT_RELEASE_ACTOR`.
+ *
+ * This predicate is pure and trust-agnostic about ITS OWN inputs — the
+ * caller is entirely responsible for where `branch`/`author` come from.
+ * `check-body-bare-digits.ts` is the one caller, and only reachable in
+ * production from `vinaya-body-checks.yml`'s `pull_request_target` job:
+ * `branch`/`author` there come from a live `gh pr view <PR_NUMBER>` fetch,
+ * with `PR_NUMBER` itself sourced from `github.event.pull_request.number` —
+ * an expression evaluated from the workflow file on the DEFAULT BRANCH, a
+ * pull request cannot edit that file to substitute a different literal
+ * (the same `pull_request_target` boundary `vinaya-review.yml` already
+ * uses). Found live (round 5, PR #165): the identical exemption on a plain
+ * `pull_request` trigger let an attacker redirect `PR_NUMBER`/`BRANCH` to
+ * any already-approved PR by the configured release actor — verified no
+ * env-var or git-state signal inside that trigger type is a safe anchor,
+ * which is why this predicate never runs there again.
+ */
+export function isChangesetsReleasePr(branch: string, author: string | null, expectedAuthor: string): boolean {
+  return branch === CHANGESET_RELEASE_BRANCH && author === expectedAuthor
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/review-status.ts

@@ -0,0 +1,200 @@
+/**
+ * The review loop's own state, derived (review-convergence-v1 task 8, #381).
+ * Pure — no `fs`, no `fetch`, no `process.env`; the CLI shim
+ * (`apps/cli/src/commands/review-status.ts`) fetches the PR's comments, head
+ * and base through `gh` and hands them here.
+ *
+ * Why this exists: two PRs of this tranche took six and four review rounds,
+ * and every extra round traced to a sentence somebody wrote instead of a
+ * command somebody ran. "Is this loop still converging?" was one of those
+ * sentences. It is a function now: the four ways a loop stops converging are
+ * each a named `PAUSE` reason with the round that produced it, read off the
+ * PR's own comments.
+ *
+ * Every fact here is read through a parser that already exists. Verdict
+ * comments and their `Judged head:` binding come from `verdict-extraction.ts`
+ * — the same extractors `review-gate.ts` blocks merges with — so this command
+ * can never disagree with the gate about which comment cast a verdict or what
+ * head it judged. There is no second `Judged head:` regex in this file.
+ */
+
+import { extractCodeReviewVerdict, extractSecurityReviewVerdict } from './verdict-extraction'
+import { isPrincipal } from './waiver-label'
+
+/**
+ * The Developer's per-round comment marker. `roles/developer.md`'s post-open
+ * sequence renders it into the one comment headed `Head: <sha>`; every gate
+ * that needs to know a Developer round happened reads THIS marker at a fixed
+ * position rather than scanning the comment's free text for a phrase.
+ */
+const DEVELOPER_ROUND_MARKER = /<!--\s*aeg:developer:round-(\d+)\s*-->/i
+
+/**
+ * A rendered finding line as `review-post.ts`'s `renderFindingsSection`
+ * writes it — `<n>. [SEVERITY] <location> — F<id> <class> <state>: <text>` —
+ * read for its id and its re-review state together. The id half deliberately
+ * mirrors that renderer's own output rather than inventing a second finding
+ * grammar; the state half is what round-over-round convergence is measured
+ * from, and no exported parser carries it.
+ */
+const FINDING_LINE =
+  /^\d+\.\s+\[[A-Z]+\]\s+\S+\s+—\s+F(\d+)(?:\s+\S+)?(?:\s+(open|fix-claimed|reproduced|resolved))?:/gm
+
+export type ReviewStatus =
+  | { state: 'CONTINUE' }
+  | { state: 'PAUSE'; reason: 'reappearance' | 'zero-deaths' | 'stale' | 'max-rounds'; id?: string; round: number }
+
+export type ReviewStatusInput = {
+  comments: { body: string; author: string | null }[]
+  headSha: string
+  principalAllowlist: string[]
+  maxRounds: number
+}
+
+/**
+ * The round number a Developer round comment declares, or `null` when the
+ * body carries no marker at all. Fixed-position read: the marker is an HTML
+ * comment this repo's own doctrine renders, never a phrase inferred from the
+ * comment's prose.
+ */
+export function parseDeveloperRoundMarker(body: string): number | null {
+  const m = body.match(DEVELOPER_ROUND_MARKER)
+  if (!m) return null
+  const n = Number(m[1])
+  return Number.isFinite(n) ? n : null
+}
+
+type VerdictComment = { judgedHead: string | null; ids: Map<string, string | null> }
+
+function findingStates(body: string): Map<string, string | null> {
+  const out = new Map<string, string | null>()
+  for (const m of body.matchAll(FINDING_LINE)) {
+    const id = `F${m[1]}`
+    const state = m[2] ?? null
+    // A round that lists the same id twice keeps the first state it declared;
+    // a later id-less repeat must never erase a real `resolved`/`reproduced`.
+    if (!out.has(id) || out.get(id) === null) out.set(id, state)
+  }
+  return out
+}
+
+/**
+ * A comment counts as a verdict comment when either extractor parses it
+ * clean — the same "did this cast a verdict" test the merge gate applies,
+ * one body at a time so this function also learns WHICH body won.
+ */
+function asVerdictComment(body: string): VerdictComment | null {
+  const code = extractCodeReviewVerdict([body])
+  const security = extractSecurityReviewVerdict([body])
+  if (code.danglingNote !== null && security.danglingNote !== null) return null
+  return { judgedHead: code.headSha ?? security.headSha, ids: findingStates(body) }
+}
+
+type Round = { judgedHead: string | null; ids: Map<string, string | null> }
+
+/**
+ * One round per `Judged head:` value, in the order that head was first
+ * judged. A code-review verdict and a security verdict cast on the same head
+ * are one round, not two — which is why the grouping key is the judged head
+ * and not the comment count.
+ */
+function groupRounds(verdicts: VerdictComment[]): Round[] {
+  const rounds: Round[] = []
+  for (const v of verdicts) {
+    const existing = rounds.find((r) => r.judgedHead === v.judgedHead)
+    const target = existing ?? { judgedHead: v.judgedHead, ids: new Map<string, string | null>() }
+    if (!existing) rounds.push(target)
+    for (const [id, state] of v.ids) {
+      if (!target.ids.has(id) || target.ids.get(id) === null) target.ids.set(id, state)
+    }
+  }
+  return rounds
+}
+
+/**
+ * `CONTINUE` means the loop is still converging; a `PAUSE` names the one
+ * reason it is not and the round that produced it. The four reasons are
+ * evaluated in the order they are declared on `ReviewStatus`, most specific
+ * first: a reappearance names an individual finding, zero-deaths names a
+ * round, staleness names the loop's own inactivity, and max-rounds is the
+ * count alone. The first that holds is reported — a paused loop needs one
+ * actionable reason, not a list.
+ */
+export function deriveReviewStatus(input: ReviewStatusInput): ReviewStatus {
+  const verdicts: VerdictComment[] = []
+  let lastVerdictIndex = -1
+  input.comments.forEach((c, i) => {
+    if (!isPrincipal(c.author, input.principalAllowlist)) return
+    const v = asVerdictComment(c.body)
+    if (v === null) return
+    verdicts.push(v)
+    lastVerdictIndex = i
+  })
+  const rounds = groupRounds(verdicts)
+  if (rounds.length === 0) return { state: 'CONTINUE' }
+
+  // reappearance — an id this loop already called `resolved` comes back
+  // `reproduced` in the very next round. The loop is re-litigating, not
+  // converging.
+  for (let i = 1; i < rounds.length; i++) {
+    const prior = rounds[i - 1] as Round
+    const current = rounds[i] as Round
+    for (const [id, state] of current.ids) {
+      if (state === 'reproduced' && prior.ids.get(id) === 'resolved') {
+        return { state: 'PAUSE', reason: 'reappearance', id, round: i + 1 }
+      }
+    }
+  }
+
+  // zero-deaths — a round that kills nothing it inherited and still raises
+  // something new. Round one is excluded structurally: it inherits no ids, so
+  // "resolved none of them" is vacuously true there and would pause every
+  // loop at its first verdict.
+  for (let i = 1; i < rounds.length; i++) {
+    const current = rounds[i] as Round
+    const priorIds = new Set<string>()
+    for (let j = 0; j < i; j++) for (const id of (rounds[j] as Round).ids.keys()) priorIds.add(id)
+    if (priorIds.size === 0) continue
+    const killedOne = [...current.ids].some(([id, state]) => priorIds.has(id) && state === 'resolved')
+    const raisedNew = [...current.ids.keys()].some((id) => !priorIds.has(id))
+    if (!killedOne && raisedNew) return { state: 'PAUSE', reason: 'zero-deaths', round: i + 1 }
+  }
+
+  // stale — the newest verdict judged a head that is no longer the PR's, and
+  // no Developer round comment has landed since it. Nothing is moving: the
+  // reviewer is judging a superseded head and the Developer has not answered.
+  const newest = rounds[rounds.length - 1] as Round
+  const judged = newest.judgedHead
+  const boundToHead = judged !== null && (input.headSha.startsWith(judged) || judged.startsWith(input.headSha))
+  // Allowlist-filtered, exactly as the verdict scan above is: a round marker
+  // is an HTML comment any commenter can paste, and an unfiltered read would
+  // let a stranger's comment clear a `stale` pause the Developer never
+  // answered.
+  const developerAnswered = input.comments
+    .slice(lastVerdictIndex + 1)
+    .some((c) => isPrincipal(c.author, input.principalAllowlist) && parseDeveloperRoundMarker(c.body) !== null)
+  if (!boundToHead && !developerAnswered) {
+    return { state: 'PAUSE', reason: 'stale', round: rounds.length }
+  }
+
+  // max-rounds — the count alone. The loop may still be converging; it has
+  // simply run long enough that the Principal decides whether it continues.
+  if (rounds.length >= input.maxRounds) return { state: 'PAUSE', reason: 'max-rounds', round: rounds.length }
+
+  return { state: 'CONTINUE' }
+}
+
+/**
+ * The one-line rendering the CLI prints: `CONTINUE`, or `PAUSE: <reason>[ <id>]`
+ * — except `stale`, whose condition (the newest verdict's judged head is no
+ * longer the PR's, and no Developer round comment has answered it since) is
+ * exactly "a commit landed after the newest verdict, unacknowledged". Verdicts
+ * are the last forge event before merge (`roles/developer.md`), so that
+ * condition is rendered as the actionable fact it names rather than the bare
+ * reason word: `push after verdict — re-review required`.
+ */
+export function renderReviewStatus(status: ReviewStatus): string {
+  if (status.state === 'CONTINUE') return 'CONTINUE'
+  if (status.reason === 'stale') return 'push after verdict — re-review required'
+  return status.id !== undefined ? `PAUSE: ${status.reason} ${status.id}` : `PAUSE: ${status.reason}`
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/single-plan-pr.ts

@@ -0,0 +1,73 @@
+/**
+ * Single-plan-PR guard predicate (task 19 / #336). Extracted from
+ * `bin/open-pr.ts` (aeg-governance-hardening task 24, #364, Part 1) so the
+ * exact same implementation can be consumed by both the ring-0 local wrapper
+ * (`open-pr.ts`, prevention) and a ring-1 CI check (detection, for PRs opened
+ * via the web UI that bypass the wrapper entirely) — one implementation per
+ * fact (§11 constraint), never a second copy of this predicate.
+ *
+ * Pure — no `fs`, no `gh`/`git` I/O. Callers gather the facts (this branch's
+ * touched files, every other open PR's touched files) and pass them in.
+ */
+
+/**
+ * Parses a tranche slug from a touched file path, when that path is an
+ * active (non-`completed/`) tranche topology file. Returns `null` for
+ * everything else — including `README.md` and `*.tokens.md`, neither of
+ * which is a topology file the single-plan-PR guard (below) cares about.
+ */
+export function trancheSlugFromTopologyPath(path: string): string | null {
+  const m = path.match(/^aeg-root\/tranches\/([^/]+)\.md$/)
+  if (!m) return null
+  const slug = m[1] as string
+  if (slug === 'README' || slug.endsWith('.tokens')) return null
+  return slug
+}
+
+export type OpenPrFiles = { number: number; files: string[] }
+
+/**
+ * Single-plan-PR guard (task 19 / #336): refuses a plan-branch diff
+ * that touches a tranche's topology file when another OPEN PR's diff
+ * already touches that SAME tranche's topology file. Ends the plan-PR
+ * race that produced two concurrent plan PRs for `aeg-governance-hardening`
+ * itself (#352/#354) — each cut from `origin/main` unaware of the other's
+ * newly-cut Issue.
+ *
+ * `branchFiles` is this branch's diff vs `origin/main` (or vs the PR's
+ * base); `otherOpenPrs` is every other currently-open PR's touched files
+ * (the caller excludes this PR's own number when editing). An ordinary
+ * Dormant where plans are forge objects: with a tranche held as a
+ * Milestone plus labeled Issues, no plan diff touches a topology file and
+ * this predicate has nothing to compare. It stays because it is still the
+ * right guard for a repo that keeps plans as files — a dormant check that
+ * says so is honest; one that reads as live protection is not.
+ *
+ * task-branch PR touches no topology file at all, so `branchFiles` yields
+ * no slugs and this passes trivially without even needing `otherOpenPrs`.
+ */
+export function checkSinglePlanPr(
+  branchFiles: string[],
+  otherOpenPrs: OpenPrFiles[]
+): { ok: boolean; message?: string } {
+  const touchedSlugs = new Set(branchFiles.map(trancheSlugFromTopologyPath).filter((s): s is string => s !== null))
+  if (touchedSlugs.size === 0) return { ok: true }
+
+  for (const pr of otherOpenPrs) {
+    const otherSlugs = new Set(pr.files.map(trancheSlugFromTopologyPath).filter((s): s is string => s !== null))
+    for (const slug of touchedSlugs) {
+      if (otherSlugs.has(slug)) {
+        return {
+          ok: false,
+          message: `single-plan-pr: another open PR (#${pr.number}) already touches tranche "${slug}"'s topology file. Only one open plan PR per tranche is allowed at a time — wait for #${pr.number} to merge or close, or coordinate with its author.`
+        }
+      }
+    }
+  }
+  return { ok: true }
+}
+
+/** True when any of `files` touches an active tranche's topology file — i.e. this diff is a plan-PR diff. */
+export function touchesAnyTopology(files: string[]): boolean {
+  return files.some((f) => trancheSlugFromTopologyPath(f) !== null)
+}