@attalabs/vinaya 0.23.0 → 0.24.0

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

@@ -73,6 +73,13 @@ export type ReviewGateComment = {
   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[]
@@ -91,6 +98,15 @@ export type ReviewGateInput = {
    * 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
@@ -103,6 +119,36 @@ export type ReviewGateInput = {
    * 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
 }
 
 /**
@@ -131,13 +177,51 @@ function isBoundToHead(extraction: { headSha: string | null }, headSha: string):
   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`, and security-review `PASS` (not `FAIL`, not missing, not
- * unclear) covering it too. `fail` otherwise, naming exactly which verdict(s)
- * are not clean, not bound to the current head, or both.
+ * 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
@@ -155,6 +239,21 @@ export function checkReviewGate(input: ReviewGateInput): ReviewGateResult {
     }
   }
 
+  // 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
@@ -178,13 +277,13 @@ export function checkReviewGate(input: ReviewGateInput): ReviewGateResult {
   const security = extractSecurityReviewVerdict(verifiedBodies)
   const codeReviewClean = codeReview.value === 'APPROVE'
   const securityClean = security.value === 'PASS'
-  const codeReviewBound = isBoundToHead(codeReview, input.headSha)
-  const securityBound = isBoundToHead(security, input.headSha)
+  const codeReviewBound = isBoundToPatch(codeReview, input.headSha, input.patchIdOf)
+  const securityBound = isBoundToPatch(security, input.headSha, input.patchIdOf)
 
-  if (codeReviewClean && codeReviewBound && securityClean && securityBound) {
+  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}.`,
+      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
     }
   }
@@ -204,6 +303,16 @@ export function checkReviewGate(input: ReviewGateInput): ReviewGateResult {
       `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.`

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/test-plan-gate.ts

@@ -1,6 +1,10 @@
 /**
  * Test Plan checkbox-state gate evaluator (aeg-governance-hardening
- * task 25, #365). Pure — no `fs`, no `gh`/`git`. The CLI shim
+ * task 25, #365; narrowed to `[principal]` boxes only by task 12, #387 —
+ * the `[agent]` half stopped being a checkbox at all: it is a fenced command
+ * list `vinaya pr report` executes and writes into the `AEG:EVIDENCE` block,
+ * which IS the evidence, so there is nothing left for this gate to grade on
+ * that half). Pure — no `fs`, no `gh`/`git`. The CLI shim
  * (`bin/verify-test-plan.ts`) reads `PR_BODY`/`BRANCH` from env and prints
  * this function's messages.
  *
@@ -12,14 +16,20 @@
  *     Test Plan is malformed, not exempt — the exact #377 live-fire gap).
  *   - No section found, non-task branch (or no BRANCH) → `pass` (advisory).
  *   - `Test Plan: unit-tests-only` sentinel → `pass`.
- *   - Any unticked `- [ ]` checkbox → `fail`, naming every unticked line.
- *   - All boxes ticked (or no checkbox items at all) → `pass`.
+ *   - Any unticked `- [ ]` `[principal]` checkbox → `fail`, naming every
+ *     unticked line. A `[agent]`-tagged checkbox (a pre-#387 body, still
+ *     grandfathered by `brief-shape`'s own rollout) is never graded here —
+ *     see the module doc comment above.
+ *   - All `[principal]` boxes ticked (or none exist at all) → `pass`.
  */
 
 import { locateTestPlanSection } from './test-plan-section'
 
 export type TestPlanGateVerdict = 'pass' | 'fail'
-export type TestPlanGateResult = { verdict: TestPlanGateVerdict; messages: string[] }
+export type TestPlanGateResult = {
+  verdict: TestPlanGateVerdict
+  messages: string[]
+}
 
 const TASK_BRANCH_PATTERN = /^task\/[^/]+\/[^/]+$/
 
@@ -66,16 +76,20 @@ export function evaluateTestPlanGate(body: string, branch: string): TestPlanGate
     }
   }
 
+  // `[agent]` checkboxes are never graded here — see the module doc comment.
+  // A pre-#387 body may still carry them (grandfathered by `brief-shape`'s
+  // own rollout); this gate simply does not look at that tag at all any
+  // more, ticked or not.
   const checkboxLines = section
     .split('\n')
     .map((line) => line.trimStart())
-    .filter((line) => /^[-*]\s+\[[ xX]\]/.test(line))
+    .filter((line) => /^[-*]\s+\[[ xX]\]\s*\*{0,2}\[principal\]\*{0,2}/i.test(line))
 
   if (checkboxLines.length === 0) {
     return {
       verdict: 'pass',
       messages: [
-        'Test Plan section found but has no checkbox items.',
+        'Test Plan section found but has no `[principal]` checkbox items.',
         "PASS (advisory) — the section may be empty or expressed in prose; verification is the Principal's call."
       ]
     }
@@ -84,21 +98,20 @@ export function evaluateTestPlanGate(body: string, branch: string): TestPlanGate
   const unchecked = checkboxLines.filter((line) => /^[-*]\s+\[\s\]/.test(line))
   const checked = checkboxLines.filter((line) => /^[-*]\s+\[[xX]\]/.test(line))
 
-  const messages = [`Test Plan items: ${checked.length} ticked, ${unchecked.length} unticked.`]
+  const messages = [`Test Plan [principal] items: ${checked.length} ticked, ${unchecked.length} unticked.`]
 
   if (unchecked.length > 0) {
-    messages.push('', 'FAIL — the following Test Plan items are unticked:')
+    messages.push('', 'FAIL — the following [principal] Test Plan items are unticked:')
     for (const line of unchecked) messages.push(`  ${line}`)
     messages.push(
       '',
-      'Per aeg-root/roles/developer.md (Verification), a PR is not mergeable while any Test Plan box is unticked.',
-      '- [agent] items: the Developer-agent posts the actual command output as evidence and ticks the box.',
-      '- [principal] items: the Principal runs the item in a real signed-in browser and ticks the box.',
+      'Per aeg-root/roles/developer.md (Verification), a PR is not mergeable while any [principal] Test Plan box is unticked.',
+      'The Principal runs the item in a real signed-in browser and ticks the box.',
       'Note: editing the PR body does not retrigger most workflows. If your PR body changes do not surface here, push an empty commit to re-run.'
     )
     return { verdict: 'fail', messages }
   }
 
-  messages.push('All Test Plan items ticked — runtime verification complete.', 'PASS.')
+  messages.push('All [principal] Test Plan items ticked — runtime verification complete.', 'PASS.')
   return { verdict: 'pass', messages }
 }

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/verdict-extraction.ts

@@ -25,6 +25,23 @@
  * code-reviewer.md`/`security-reviewer.md` require verbatim) — tightening
  * to it closes the gap without inventing a new convention.
  *
+ * The VALUE is windowed to the comment's first THREE lines only
+ * (review-convergence-v1 task 2, round 4, `#392`) — never a line anywhere
+ * else in the body. Every shape this package's own callers render puts the
+ * `VERDICT:`/`ESCALATE:` line first and `Judged head:` third; a
+ * caller-supplied field (findings, conformance prose, a summary) never
+ * renders before line 5. Restricting the read window closes a
+ * caller-controlled-text injection route without narrowing what any real
+ * render needs matched.
+ *
+ * The CANDIDATE SET stays whole-body (review-convergence-v1 task 2, round 5,
+ * `#392`) — round 4 windowed where a verdict's value is read, not which
+ * comments count as a candidate at all. A comment whose only VERDICT-shaped
+ * line sits outside its first three lines is still the most recent
+ * candidate if it is the most recent comment; it reads as DANGLING rather
+ * than being skipped, so it correctly shadows an earlier clean verdict
+ * instead of silently letting the earlier one win.
+ *
  * The anchor tolerates a leading markdown EMPHASIS run — one to three `*` or
  * `_`, immediately abutting the token — so `**VERDICT: APPROVE**` and
  * `_VERDICT: APPROVE_` match (PR #636: the reviewer subagent emitted the
@@ -87,8 +104,27 @@
 
 const HEAD_SHA_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Judged head:\s*([0-9a-f]{7,40})(?![A-Za-z0-9])/im
 
+/**
+ * Round-4 ruling on `#392`: both markers are read from a comment's first
+ * THREE lines only, never anywhere else in the body. Every shape this
+ * package itself renders (`review-post.ts`'s `renderCodeReviewComment`/
+ * `renderSecurityComment`/`renderEscalationComment`) puts `VERDICT:`/
+ * `ESCALATE:` on line 1 and `Judged head:` on line 3 — every caller-supplied
+ * field (findings, conformance prose, scope, a summary) renders strictly
+ * after that, starting at line 5 at the earliest. Restricting the window to
+ * lines 1–3 costs no real render anything: it is a strictly narrower read
+ * than "anywhere in the body," and it closes the class of defect that
+ * motivated this ruling — a caller-supplied field that smuggled a raw
+ * newline followed by a `VERDICT:`- or `Judged head:`-shaped line could
+ * previously inject a structural line from outside the command's own
+ * three-line skeleton; that line can now never be read as one.
+ */
+function firstThreeLines(comment: string): string {
+  return comment.split('\n').slice(0, 3).join('\n')
+}
+
 function extractHeadSha(comment: string): string | null {
-  const m = comment.match(HEAD_SHA_PATTERN)
+  const m = firstThreeLines(comment).match(HEAD_SHA_PATTERN)
   return m ? (m[1] as string).toLowerCase() : null
 }
 
@@ -102,22 +138,45 @@ function extractHeadSha(comment: string): string | null {
  */
 export type VerdictExtraction = { value: string; headSha: string | null; danglingNote: string | null }
 
+/**
+ * Round 5 (`#392`): the candidate set — which comments even ATTEMPTED a
+ * verdict — is a whole-body test, the pre-round-4 pattern. Only the VALUE is
+ * read from the first three lines (round 4, kept). Round 4's own change
+ * built `clearHits` from the windowed text directly, which made a comment
+ * whose marker sits below line 3 vanish from consideration entirely rather
+ * than counting as present-but-unclear — "most recent clear hit wins" then
+ * silently fell through to an OLDER comment, so a later blocking verdict
+ * that happened to render past line 3 let an earlier clean pass win. Here,
+ * the most recent CANDIDATE is picked first; only then is its value read
+ * from its own first three lines. A candidate whose window carries no value
+ * is DANGLING — never skipped in favour of an earlier one — so a later
+ * unclear comment still shadows an earlier clean verdict, the fail-closed
+ * direction every other branch of this function already takes.
+ */
 function extractVerdict(comments: string[], valuePattern: RegExp, missingLabel: string): VerdictExtraction {
-  const clearHits = comments.filter((c) => valuePattern.test(c))
-  if (clearHits.length > 0) {
-    const latest = clearHits[clearHits.length - 1] as string
-    const m = latest.match(valuePattern) as RegExpMatchArray
+  const candidates = comments.filter((c) => valuePattern.test(c))
+  if (candidates.length === 0) {
+    return {
+      value: `no ${missingLabel} pass was run before merge — DANGLING, see below`,
+      headSha: null,
+      danglingNote: `no ${missingLabel} verdict comment found on this PR`
+    }
+  }
+
+  const latest = candidates[candidates.length - 1] as string
+  const m = firstThreeLines(latest).match(valuePattern)
+  if (!m) {
     return {
-      value: (m[1] as string).toUpperCase().replace(/[_-]/g, ' '),
-      headSha: extractHeadSha(latest),
-      danglingNote: null
+      value: `the most recent ${missingLabel} comment's VERDICT line is not within its first three lines — DANGLING, see below`,
+      headSha: null,
+      danglingNote: `the most recent ${missingLabel} verdict comment carries a VERDICT-shaped line outside the first-three-line read window`
     }
   }
 
   return {
-    value: `no ${missingLabel} pass was run before merge — DANGLING, see below`,
-    headSha: null,
-    danglingNote: `no ${missingLabel} verdict comment found on this PR`
+    value: (m[1] as string).toUpperCase().replace(/[_-]/g, ' '),
+    headSha: extractHeadSha(latest),
+    danglingNote: null
   }
 }
 

package/studio-standalone/apps/vinaya-studio/web/.next/BUILD_ID

@@ -1 +1 @@
-5xy_GA7G5KRuE3HDumIiw
+QY2GhiI47-765D9DHGy1I

package/studio-standalone/apps/vinaya-studio/web/.next/build-manifest.json

@@ -7,9 +7,9 @@
     "static/chunks/0cz1d0mv5g_q7.js"
   ],
   "lowPriorityFiles": [
-    "static/5xy_GA7G5KRuE3HDumIiw/_buildManifest.js",
-    "static/5xy_GA7G5KRuE3HDumIiw/_ssgManifest.js",
-    "static/5xy_GA7G5KRuE3HDumIiw/_clientMiddlewareManifest.js"
+    "static/QY2GhiI47-765D9DHGy1I/_buildManifest.js",
+    "static/QY2GhiI47-765D9DHGy1I/_ssgManifest.js",
+    "static/QY2GhiI47-765D9DHGy1I/_clientMiddlewareManifest.js"
   ],
   "rootMainFiles": [
     "static/chunks/1hklle-my0ly_.js",

package/studio-standalone/apps/vinaya-studio/web/.next/prerender-manifest.json

@@ -29,8 +29,8 @@
   "dynamicRoutes": {},
   "notFoundRoutes": [],
   "preview": {
-    "previewModeId": "a3b0a9b026a44ef8737f46f409d836a2",
-    "previewModeSigningKey": "a8c09c70586d91fcf55df81d161a79e0e79d590d89a16b9133739bc9e0cfd060",
-    "previewModeEncryptionKey": "3e382dfd9bc6989a28fe017f6149dae6e5c3997c3f038ffb5b560030f95dace8"
+    "previewModeId": "6c1eff09a35d132d0b34583f9da20f05",
+    "previewModeSigningKey": "7dc30b59adbc55dad328594e58967a6f497c97ccf2c930ccc1625d0228f961c2",
+    "previewModeEncryptionKey": "7eade789aac49d9d0df75df427d7d9f0d3183a0ca892d36db2139826cc4e6529"
   }
 }