@attalabs/vinaya 0.22.0 → 0.24.0

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

@@ -0,0 +1,174 @@
+/**
+ * Typed model for AEG artifacts. See `aeg-root/tranche-model.md` for the
+ * canonical specification (§3 status table, §4 thin-file template).
+ *
+ * This module is pure: no I/O. The parser produces these shapes from file
+ * contents; `deriveTranche` consumes them plus a `ForgeFacts` snapshot.
+ */
+
+import type { ForgeFacts, Tranche, Lifecycle, Task } from '@attalabs/aeg-types'
+
+// ---------- Registry (projects.md) ----------
+
+export type Project = {
+  /** Registry-unique name. Authority for `Project:` validation. */
+  name: string
+  /** Declared home folder (e.g. `apps/<product>`). Never derived. */
+  path: string
+  /** Specs folder for the project. */
+  specsPath: string
+  /**
+   * Per-project state folder, or `null` when the cell holds prose like
+   * "state tracked globally for now" — i.e. state isn't tracked under this
+   * project's path.
+   */
+  statePath: string | null
+}
+
+export type Registry = Project[]
+
+// ---------- Tranche file (tranches/<name>.md) ----------
+
+/**
+ * `Lifecycle`/`Task`/`Tranche` live in `@attalabs/aeg-types` (task
+ * aeg-forge-state-v1 3a) — re-exported here since every existing call site
+ * across the repo imports them from `@attalabs/aeg-core`. Moved out so
+ * `@attalabs/aeg-forge-state` can depend on these shapes without creating a
+ * package cycle with `aeg-core` (which in turn depends on
+ * `aeg-forge-state`'s derivation function).
+ */
+export type { Lifecycle, Task, Tranche }
+
+// ---------- Forge facts ----------
+
+/**
+ * `ForgeFacts` lives in `@attalabs/aeg-types` (aeg-core-purity fix, #521) —
+ * re-exported here for the same reason as `Lifecycle`/`Task`/`Tranche`:
+ * every existing call site imports it from `@attalabs/aeg-core`, and it moved
+ * out so the I/O-performing fetchers that produce it (now in
+ * `@attalabs/aeg-forge-state`) don't need to depend on `aeg-core`.
+ */
+export type { ForgeFacts }
+
+// ---------- Derivation output ----------
+
+/**
+ * The statuses derivation can conclude. The *rules* that produce them are not
+ * written here or in `derive-tranche.ts` — they live as an ordered,
+ * pure-data list in `state-machine-model.ts` (the `actions.ts`
+ * discipline), which `deriveStatus` executes and the docs render from the
+ * same list.
+ *
+ * `backlog` remains a member because it is a project-level concept consumers
+ * still render; derivation never emits it inside a tranche.
+ *
+ * `dropped` and `incoherent` are the two **honest terminal** statuses.
+ * A closed Issue with no merged PR must never resolve to `todo` (which implies
+ * not-started). `dropped` = closed `NOT_PLANNED` (legitimately abandoned);
+ * `incoherent` = closed `COMPLETED` but with no merged-PR link (genuinely done
+ * yet unprovable, or a broken close). Both are surfaced, never hidden.
+ */
+export type DerivedStatus =
+  | 'backlog'
+  | 'todo'
+  | 'in-flight'
+  | 'in-review'
+  | 'changes-requested'
+  | 'merged'
+  | 'blocked'
+  | 'dropped'
+  | 'incoherent'
+
+export type DispatchBlockers = {
+  /** Depends-on edges whose target is not yet `merged`. */
+  dependsOnNotMerged: string[]
+  /**
+   * Conflicts-with edges whose target is currently occupying its collision
+   * domain — derived status `in-flight`, `in-review`, or `changes-requested`
+   * (§8 conflict gate).
+   */
+  conflictsWithOpenOrInFlight: string[]
+}
+
+export type DerivedTask = {
+  task: Task
+  status: DerivedStatus
+  /**
+   * `true` when the §8 gates allow dispatching this task: all `dependsOn`
+   * targets are `merged`, and no `conflictsWith` target is open/in-flight.
+   * Dispatchability is independent of this task's own current status — a
+   * task already `in-review` is still "dispatchable" by this definition (the
+   * gates would have allowed it to start).
+   */
+  dispatchable: boolean
+  blockers: DispatchBlockers
+}
+
+export type UnknownEdge = {
+  from: string
+  to: string
+  kind: 'depends-on' | 'conflicts-with'
+}
+
+export type DerivedTranche = {
+  tranche: Tranche
+  tasks: DerivedTask[]
+  /**
+   * Edges that reference task ids not present in this tranche's topology
+   * table. Surface for diagnostics; does not throw, since real files
+   * occasionally name dropped/prose-only ids (e.g. a `3a` that survives only
+   * in a tranche file's narrative).
+   */
+  unknownEdges: UnknownEdge[]
+}
+
+// ---------- Token ledger (tranches/<name>.tokens.md) ----------
+
+/**
+ * One row of the append-only per-tranche token/cost ledger. See
+ * `aeg-root/tranche-model.md` §12 for the canonical format. Each role
+ * appends one row at the end of its turn; re-entry appends another row.
+ * The tranche total is `sum(rows)`, derived at read time — never stored.
+ *
+ * The two capture sources surface here as `null` cells: a row written by a
+ * claude.ai role (Planner / Brief Author / Reviewer / Security) before the
+ * Principal has filled in its usage figure has `tokensIn`/`tokensOut`/`cost`
+ * as `null`; a terminal-role row (Developer / Archivist with `/cost`) has
+ * exact numbers.
+ */
+export type LedgerRow = {
+  /** Free-text phase identifier. Convention: `<task-id>: <phase>` per task
+   * (e.g. `9: develop`), or a bare phase for tranche-wide work (e.g.
+   * `planning`). The parser does not enforce the convention — the Phase
+   * cell is opaque so the table can be re-pivoted later. */
+  phase: string
+  role: string
+  /** Free-text — the role's agent + model (e.g. `claude-opus-4-7 (CC)`,
+   * `claude-opus-4-7 (chat)`). The PRICING table dependency is on the
+   * model name, not on the parser. */
+  agentModel: string
+  /** `null` when the cell was `—` / `-` / empty (unknown — claude.ai
+   * row not yet filled). */
+  tokensIn: number | null
+  tokensOut: number | null
+  /** Cost in USD as a number. `null` for unknown. Cost depends on the
+   * adapter's PRICING table — when the model is missing from it, this is
+   * `0` from the source row, not `null` (a known limitation, not a parser
+   * bug). */
+  cost: number | null
+  /** Raw date cell — typically `YYYY-MM-DD`. Captured as a string so the
+   * model docs can evolve the format without breaking the parser. */
+  date: string
+}
+
+/**
+ * `sumLedger(rows)` output — pure aggregate over the rows in source order.
+ * Null cells contribute zero; the row count is preserved so a UI can show
+ * "N entries totalling …".
+ */
+export type LedgerTotals = {
+  tokensIn: number
+  tokensOut: number
+  cost: number
+  rows: number
+}

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

@@ -0,0 +1,199 @@
+/**
+ * Shared code-reviewer / security-review verdict extraction (aeg-review-gate-v1
+ * task 1, #474). Originally private to `archive-task.ts`'s post-merge
+ * provenance assembly (advisory-only, DANGLING on a missing/unclear verdict).
+ * Extracted so the pre-merge `review-gate.ts` blocking check calls the
+ * IDENTICAL regex/parsing logic — a future drift between two copies of the
+ * same pattern would silently reopen the gap this task exists to close (one
+ * implementation per fact, §11 constraint). Pure — no `fs`, no `fetch`.
+ *
+ * Picks the MOST RECENT comment carrying a clear value, not the first comment
+ * merely matching the pattern (aeg-review-gate-v1 task 1 fix — the original
+ * single-comment `.find()` broke on real multi-comment PRs: a REQUEST_CHANGES
+ * verdict followed by fixes and a later clean APPROVE).
+ *
+ * Line-anchored `VERDICT:` marker only — NOT a bare word search anywhere in
+ * the comment (aeg-review-gate-v1 task 1 follow-up, security-review FAIL
+ * finding, confirmed by direct execution: the old bare `\b(PASS|FAIL)\b`
+ * pattern matched the post-merge Archivist's own auto-generated DANGLING
+ * placeholder text — "no security-review pass was run before merge —
+ * DANGLING, see below" — as a clean PASS, since it contains the standalone
+ * word "pass". Same risk in reverse for "APPROVE" inside ordinary prose,
+ * e.g. "I do NOT approve of that design"). `^\s*VERDICT:\s*<value>\b`,
+ * multiline, is the real subagent contract (`roles/reviewer.md`/
+ * `roles/security.md`'s own VERDICT block, which `.claude/agents/
+ * 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
+ * bolded form and the gate read the PR as carrying no code-review verdict at
+ * all). The spec still mandates the bare line; this only stops an agent's
+ * markdown drift from silently DANGLING a real verdict.
+ *
+ * Emphasis ONLY — the following are deliberately NOT tolerated, because each
+ * is a way for prose to *mention* a verdict rather than *cast* one, and this
+ * gate blocks merges (#639 review, findings 1/3/5):
+ *   `> VERDICT: APPROVE`   blockquote — GitHub's quote-reply syntax. A
+ *                          Developer quoting the reviewer's earlier text
+ *                          would otherwise become the PR's own verdict, and
+ *                          most-recent-hit-wins means the quote beats a live
+ *                          REQUEST CHANGES. Fail-open and silent.
+ *   `* VERDICT: APPROVE`   list item — the space is what distinguishes it
+ *                          from emphasis; a bullet is prose context. `-` and
+ *                          `1.` never matched, so `*` must not either.
+ *   `# VERDICT: APPROVE`   heading — same mention-not-cast reasoning.
+ *   `` `VERDICT: APPROVE` ``  code span — decided, not overlooked. A
+ *                          backticked marker is exactly how the role docs
+ *                          and this comment WRITE about the contract, so
+ *                          tolerating it would match prose describing the
+ *                          rule. If a real agent ever emits the backticked
+ *                          form, fix the agent: it fails loud (DANGLING),
+ *                          which is the safe direction.
+ *
+ * The value-side boundary is `(?![A-Za-z0-9])`, not `\b`: `_` is a word
+ * character, so `\b` after the captured value would reject the closing `_` of
+ * `_VERDICT: APPROVE_` while accepting the `*` of the bolded form — the class
+ * and the claim would disagree. It still rejects `APPROVED`/`PASSED`.
+ *
+ * What is NOT loosened is the requirement that a literal `VERDICT:` token be
+ * present — ordinary prose and the Archivist's own DANGLING placeholder still
+ * miss.
+ *
+ * No separate "marker present but value unclear" branch: a generic
+ * `VERDICT:`-prefix-only marker would itself cross-contaminate the two
+ * extractors (a security reviewer's own `VERDICT: PASS` line would loosely
+ * match the code-review marker too, misreporting "code-reviewer comment
+ * found but unclear" for a comment that was never a code review at all).
+ * Anything that doesn't match the exact value pattern reads as "missing",
+ * identical to no comment existing — which is also what the DANGLING
+ * placeholder case above requires.
+ *
+ * Reviewed-commit binding (#73, a duplicate of #71 closes this one). The
+ * winning comment (the one whose `VERDICT:` line matched) is also searched
+ * for a `Judged head: <sha>` line — the exact phrase reviewers on
+ * atta-labs/attalabs#664 were already hand-typing before this existed as a
+ * mechanism, formalized rather than invented. Same anchor discipline as
+ * `VERDICT:` itself: line-start, optional leading emphasis run, no
+ * blockquote/list-item/heading/code-span tolerance — a sha mentioned in
+ * ordinary prose ("see 8365ca57 for context") is a mention, not a binding,
+ * and must not parse as one. Accepts both the abbreviated (7-char) and full
+ * (40-char) hex forms; `review-gate.ts` does the prefix comparison against
+ * the PR's actual head. Searched only within the SAME comment body that
+ * produced the winning verdict — a sha mentioned in a different comment is
+ * not this verdict's binding.
+ */
+
+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 = firstThreeLines(comment).match(HEAD_SHA_PATTERN)
+  return m ? (m[1] as string).toLowerCase() : null
+}
+
+/**
+ * `headSha` is `null` in two distinct situations that both mean "cannot
+ * confirm this verdict covers the current head": no verdict comment matched
+ * at all (`danglingNote` is also set), or a verdict comment matched but
+ * carried no `Judged head:` line (`danglingNote` is `null` — the verdict
+ * itself is real, only the binding is missing). `review-gate.ts` treats both
+ * as unbound; only their `danglingNote`/`value` differ.
+ */
+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 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: `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: (m[1] as string).toUpperCase().replace(/[_-]/g, ' '),
+    headSha: extractHeadSha(latest),
+    danglingNote: null
+  }
+}
+
+/** `value` is `APPROVE`, `REQUEST CHANGES`, `LGTM`, or a DANGLING placeholder string. */
+export function extractCodeReviewVerdict(comments: string[]): VerdictExtraction {
+  return extractVerdict(
+    comments,
+    /^[ \t]*(?:\*{1,3}|_{1,3})?VERDICT:\s*(APPROVE|REQUEST[ _-]?CHANGES|LGTM)(?![A-Za-z0-9])/im,
+    'code-reviewer'
+  )
+}
+
+/** `value` is `PASS`, `FAIL`, or a DANGLING placeholder string. */
+export function extractSecurityReviewVerdict(comments: string[]): VerdictExtraction {
+  return extractVerdict(
+    comments,
+    /^[ \t]*(?:\*{1,3}|_{1,3})?VERDICT:\s*(PASS|FAIL)(?![A-Za-z0-9])/im,
+    'security-review'
+  )
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/vocabulary-citation.ts

@@ -0,0 +1,114 @@
+/**
+ * vocabulary-citation.ts — a generic, regex-parameterized citation checker.
+ *
+ * `retired-vocabulary.test.ts` hand-rolls this exact sweep shape (pattern +
+ * scope + exemptions + a non-vacuity self-test) for this repo's own internal
+ * use, but as a `vitest` file no adopter can install it — and it hardcodes
+ * every pattern, scope and exemption as a repo-specific literal. This module
+ * generalizes the sweep into a reusable primitive: every pattern, its scope,
+ * its exemptions, and the sample that proves it is not vacuous arrive as
+ * caller-supplied input. It contains no product name, host-tool path, or
+ * any other repo-specific literal — that knowledge belongs to whoever
+ * configures an instance (a Vinaya check bin is one such consumer).
+ *
+ * Pure — no `fs`, no child-process I/O. The caller injects `grepFn`/
+ * `matchFn`, mirroring `evaluateC5`'s `fileExists` injection in
+ * `doc-owners.ts`: this file decides what counts as a finding, the I/O shim
+ * decides how to look.
+ */
+
+export type VocabularyPattern = {
+  /** Short, stable id for reporting — never the raw regex, which can be long. */
+  id: string
+  /**
+   * POSIX ERE, `grep -E` compatible. Never `\d`/`\w`/`\s` — GNU grep reads
+   * those as literal characters, not shorthand classes, so a pattern relying
+   * on them can pass locally (a permissive grep) and go silently vacuous on
+   * CI (GNU grep). Use `[0-9]` etc. instead. `\b` is safe: both GNU and BSD
+   * `grep -E` support it as an extension.
+   */
+  pattern: string
+  /** Repo-root-relative paths/dirs this pattern is checked against. */
+  scope: string[]
+  /** Path substrings exempted for this pattern only, beyond `globalExempt`. */
+  exempt?: string[]
+  /**
+   * Substrings that, when present on the matched LINE, make the hit legitimate.
+   * Distinct from `exempt`, which filters by path: a name can be leakage in one
+   * sentence and the product's own identifier in the next, within the same file.
+   * An npm scope or a domain that merely CONTAINS a product name is the product
+   * naming itself, not an unexplained reference an adopter cannot resolve —
+   * exempting the whole file would blind the pattern to real leakage beside it.
+   *
+   * Granularity is the LINE, which is the accepted limit: a genuine leak that
+   * shares a line with a legitimate citation escapes. Prose puts them on
+   * separate lines in practice, and the alternative — exempting only the
+   * matched span — would need column offsets `grep -n` does not report.
+   */
+  exemptContent?: string[]
+  /** A string this pattern MUST match — proves the pattern is not vacuous. */
+  sample: string
+  /**
+   * When true, a hit on a line that is a markdown table row (starts with
+   * `|`, ignoring leading whitespace) is not a finding. A registry table's
+   * "implementation" column citing a harness path is verified by a gate
+   * (e.g. `verify-registry.ts`'s G1/G2), not a claim stated as normative
+   * prose — banning the shape would flag the very registry a widened
+   * pattern exists to protect.
+   */
+  exemptTableRow?: boolean
+}
+
+export type VocabularyHit = { file: string; line: number; content: string }
+
+export type VocabularyFinding = VocabularyHit & { patternId: string }
+
+export type VocabularyCheckResult = {
+  findings: VocabularyFinding[]
+  /**
+   * Patterns whose sample failed to self-match — a config bug, reported
+   * loud instead of silently passing. A pattern that matches nothing passes
+   * every scope silently, which is not hypothetical: this is the exact
+   * failure mode `retired-vocabulary.test.ts`'s own non-vacuity suite exists
+   * to catch (`\bD-(###|NNN)\b` shipped green over eleven live sites because
+   * `\b` cannot anchor after `#`).
+   */
+  vacuousPatterns: string[]
+}
+
+const TABLE_ROW = /^\s*\|/
+
+/**
+ * Evaluates every pattern against its own scope, filtering exempted paths
+ * and (optionally) table-row citations, and reports which patterns proved
+ * vacuous against their own sample instead of silently returning clean.
+ */
+export function evaluateVocabularyCitation(
+  patterns: VocabularyPattern[],
+  grepFn: (pattern: string, scope: string[]) => VocabularyHit[],
+  matchFn: (pattern: string, sample: string) => boolean,
+  globalExempt: string[] = []
+): VocabularyCheckResult {
+  const findings: VocabularyFinding[] = []
+  const vacuousPatterns: string[] = []
+
+  for (const p of patterns) {
+    if (!matchFn(p.pattern, p.sample)) {
+      vacuousPatterns.push(p.id)
+      continue
+    }
+
+    const exempt = [...globalExempt, ...(p.exempt ?? [])]
+    const exemptContent = p.exemptContent ?? []
+    const hits = grepFn(p.pattern, p.scope).filter((h) => {
+      if (exempt.some((e) => h.file.includes(e))) return false
+      if (exemptContent.some((e) => h.content.includes(e))) return false
+      if (p.exemptTableRow && TABLE_ROW.test(h.content)) return false
+      return true
+    })
+
+    for (const h of hits) findings.push({ ...h, patternId: p.id })
+  }
+
+  return { findings, vacuousPatterns }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/waiver-label.ts

@@ -0,0 +1,52 @@
+/**
+ * Waiver-label actor verification. A doc-coverage waiver is honored
+ * ONLY when the `vinaya/waiver:docs` PR label is present AND the actor of that
+ * label's most recent labeling timeline event is a configured principal.
+ * Label presence alone is never sufficient — that is exactly the
+ * agent-emittable-string hole closes (supersedes's
+ * `Doc-waiver:` grammar). Pure — no env reads here; I/O stays in the CLI
+ * shim, same discipline as `pr-tier.ts`.
+ *
+ * `isWaiverLabelActorVerified` is parameterized by `label` (aeg-review-gate-v1
+ * task 1, #474) so a second waiver label (`vinaya/waiver:review`) can reuse the exact
+ * same actor-verification predicate rather than a copy-pasted duplicate that
+ * could drift out of sync.
+ *
+ * The label strings themselves are read from the code-owned vocabulary in
+ * `@attalabs/aeg-forge-state`'s `labels.ts`, never written as literals here — a
+ * namespace change lands in one file (discipline).
+ */
+
+import { label as labelFor } from '@attalabs/aeg-forge-state'
+
+export const WAIVER_LABEL = labelFor('waiver-docs')
+export const WAIVER_LABEL_REVIEW = labelFor('waiver-review')
+export const PRINCIPAL_ALLOWLIST = ['daniboomerang']
+
+/**
+ * Membership test for a principal allowlist. **Case-insensitive, because
+ * GitHub logins are** — `Alice` and `alice` address the same account, and the
+ * forge may return either casing depending on the API surface. An exact-match
+ * test fails closed, but it fails closed *invisibly*: an adopter who wrote
+ * `"principals": ["Alice"]` would watch Alice's genuine verdicts land as
+ * DANGLING with no stated reason — precisely the baffling symptom the
+ * `principals` field exists to remove (review finding, PR #862).
+ *
+ * Shared by every allowlist consumer so the waiver check and the review gate
+ * can never disagree about whether a given login is a principal.
+ */
+export function isPrincipal(login: string | null, principalAllowlist: string[]): boolean {
+  if (login === null) return false
+  const normalized = login.toLowerCase()
+  return principalAllowlist.some((p) => p.toLowerCase() === normalized)
+}
+
+export function isWaiverLabelActorVerified(opts: {
+  label: string
+  labels: string[]
+  labelActor: string | null
+  principalAllowlist: string[]
+}): boolean {
+  if (!opts.labels.includes(opts.label)) return false
+  return isPrincipal(opts.labelActor, opts.principalAllowlist)
+}