@attalabs/vinaya 0.22.0 → 0.23.0

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

@@ -0,0 +1,163 @@
+/**
+ * Retired vocabulary — mechanisms genuinely gone from AEG's own methodology
+ * (the decision log, the lock, the `team-leader` role, the `D-###` decision
+ * id, …) with no legitimate positive occurrence anywhere but the exempt
+ * lists below. This is `retired-vocabulary.test.ts`'s `RETIRED` array and
+ * the non-citation members of its `RETIRED_IN_PRODUCT` array (both target
+ * the same retired-mechanism concern; the split between the two vitest
+ * arrays there is organic history, not a semantic boundary) — the file this
+ * module was extracted from names the incident: five review rounds each
+ * declared the decision-log claim swept, and each time it resurfaced a few
+ * lines from where the previous pass fixed it. A rule enforced by attention,
+ * not a gate.
+ *
+ * Deliberately NOT `RETIRED_IN_PRODUCT`'s forge-number / tranche-slug /
+ * legacy-slug patterns: those ban a LIVE, unexplained citation, not a
+ * retired concept, and are already this package's own
+ * `checkUnresolvableReferences` (`reader-resolvable-prose.ts`) — shipping
+ * both under two check names would double-report the identical match. This
+ * module is deliberately the narrower half of that file's original scan.
+ *
+ * Content copied verbatim from `retired-vocabulary.test.ts`'s `RETIRED`
+ * (minus its citation members), `EXEMPT`, and the non-citation entries of
+ * `PATTERN_EXEMPT`, never re-derived — this module's whole purpose is
+ * giving that list a CheckSpec adapter, not re-litigating it. Every pattern
+ * here is POSIX-ERE-safe (no `\d`/`\w`/`\s`, no lookaheads) by the same
+ * discipline `reader-resolvable-prose.ts` documents, so `grep -E` (the
+ * vitest suite) and native `RegExp` (this evaluator) agree on every match.
+ *
+ * Zero I/O: every input (file paths + contents) is read by the adapter and
+ * passed in, same charter as `reader-resolvable-prose.ts`.
+ */
+
+export type VocabSourceFile = { path: string; content: string }
+
+export type VocabFinding = {
+  file: string
+  line: number
+  pattern: string
+  message: string
+}
+
+/** The retired mechanisms this scan bans as claims of current-ness — see the module header for what is deliberately NOT here. */
+export const RETIRED_PATTERNS: readonly string[] = [
+  // the deleted decision-id format
+  String.raw`\bD-[0-9]{3}\b`,
+  'D-(###|NNN|nnn|xxx)',
+  // the retired record as a live, writable, required artifact, every
+  // inflection but never "decision logic"
+  'decision (entry|logged)',
+  'decision-log entry',
+  'decision log entry',
+  'decision log(s|ged|ging)?([^a-z]|$)',
+  'decision-log',
+  'decision entr',
+  'decisions? (are |is )?logged',
+  'log entries',
+  String.raw`decisions\.md`,
+  'decisions-legacy',
+  'CONTRADICTION',
+  'assumes Tier 3',
+  // the lock
+  'Lock: ?YES',
+  'Lock: ?NO',
+  'lock approvals?',
+  'approves locks',
+  'Conforms to lock',
+  'Challenges lock',
+  // checks deleted with the machinery
+  'checkDecisionNumbersFresh',
+  // the role that no longer exists
+  String.raw`roles/team-leader\.md`,
+  // the wreckage a citation strip leaves when it deletes the contents of a
+  // parenthetical and not the punctuation around it — the shape is banned,
+  // not one instance of it. `()` is deliberately absent: it is an ordinary
+  // function call, and banning it would make any TypeScript source unusable.
+  String.raw`\(,`,
+  String.raw`,\)`,
+  String.raw`\(\.\)`
+]
+
+/** Paths where a retired-vocabulary mention is legitimate: frozen archives and historical records. Substring match, same as the vitest suite's own `EXEMPT`. */
+export const RETIRED_EXEMPT_SUBSTRINGS: readonly string[] = [
+  'docs/decisions-legacy.md',
+  'apps/herald-ai/docs/',
+  'apps/vada-ai/docs/',
+  'aeg-root/tranches/completed/',
+  'packages/aeg-core/src/docs/published-prose',
+  'packages/aeg-core/src/retired-vocabulary.test.ts',
+  'packages/aeg-core/src/retired-vocabulary.ts',
+  '/fixtures/',
+  '/node_modules/',
+  '/.next/',
+  '/.turbo/'
+]
+
+/**
+ * Per-pattern exemptions on top of `RETIRED_EXEMPT_SUBSTRINGS`, for the
+ * handful of patterns with a real, load-bearing false-positive shape (a
+ * live doc that legitimately discusses the retired concept by name, or a
+ * same-shaped live feature). Copied verbatim from `retired-vocabulary.test.ts`'s
+ * `PATTERN_EXEMPT` — including entries for `apps/herald-ai`/`apps/vada-ai`
+ * paths this repo does not carry, since a nonexistent path costs nothing to
+ * keep and this module's whole point is not re-deriving the list.
+ */
+export const PATTERN_EXEMPT: Readonly<Record<string, readonly string[]>> = {
+  [String.raw`\bD-[0-9]{3}\b`]: ['./CLAUDE.md'],
+  [String.raw`decisions\.md`]: [
+    'docs-index.md',
+    'apps/vada-ai/specs/legacy/README.md',
+    'apps/vada-ai/specs/vada-product-spec.md',
+    'apps/vada-ai/web/CLAUDE.md',
+    'apps/vada-ai/CLAUDE.md'
+  ],
+  'decisions-legacy': [
+    'packages/aeg-core/src/file-classify.ts',
+    'packages/aeg-core/src/file-classify.test.ts',
+    'packages/aeg-core/src/pr-tier.test.ts',
+    'docs-index.md',
+    '.claude/skills/database/SKILL.md',
+    '.claude/skills/vada-architecture/SKILL.md',
+    'apps/vada-ai/specs/vada-byok-principles.md',
+    'apps/vada-ai/web/CLAUDE.md',
+    'apps/vada-ai/CLAUDE.md'
+  ],
+  CONTRADICTION: ['apps/vada-ai/specs/vada-reviewers-spec.md']
+}
+
+function lineNumbers(content: string, pattern: RegExp): number[] {
+  const out: number[] = []
+  const lines = content.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    if (pattern.test(lines[i] ?? '')) out.push(i + 1)
+  }
+  return out
+}
+
+/**
+ * Sweeps `files` for `RETIRED_PATTERNS`, skipping any file whose path
+ * contains a `RETIRED_EXEMPT_SUBSTRINGS` entry, or that pattern's own
+ * `PATTERN_EXEMPT` entry. Matching is per-line, case-sensitive — the same
+ * semantics `grep -E` (with no `-i`) gives the vitest suite this was
+ * extracted from.
+ */
+export function scanRetiredVocabulary(files: readonly VocabSourceFile[]): VocabFinding[] {
+  const findings: VocabFinding[] = []
+  for (const file of files) {
+    if (RETIRED_EXEMPT_SUBSTRINGS.some((e) => file.path.includes(e))) continue
+    for (const pattern of RETIRED_PATTERNS) {
+      const patternExempt = PATTERN_EXEMPT[pattern] ?? []
+      if (patternExempt.some((e) => file.path.includes(e))) continue
+      const re = new RegExp(pattern)
+      for (const line of lineNumbers(file.content, re)) {
+        findings.push({
+          file: file.path,
+          line,
+          pattern,
+          message: `claims a retired AEG mechanism is still live (matches /${pattern}/)`
+        })
+      }
+    }
+  }
+  return findings
+}

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

@@ -0,0 +1,269 @@
+/**
+ * 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 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
+  /**
+   * 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[]
+}
+
+/**
+ * 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())
+}
+
+/**
+ * `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.
+ */
+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
+    }
+  }
+
+  // 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 = isBoundToHead(codeReview, input.headSha)
+  const securityBound = isBoundToHead(security, input.headSha)
+
+  if (codeReviewClean && codeReviewBound && securityClean && securityBound) {
+    return {
+      verdict: 'pass',
+      reason: `code-reviewer verdict is a clean APPROVE and security-review verdict is a clean PASS, both covering head ${input.headSha}.`,
+      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}`
+    )
+  }
+  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/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)
+}