@attalabs/vinaya 0.4.3 → 0.4.5

package/aeg-root/enforcement.md

@@ -44,7 +44,7 @@ The same check implementations run at ring 0 and ring 1 — one codebase, two en
 | Starting the Dig (before authoring a brief) / starting Step 0 (before executing one) / **every push on a task branch before its PR exists** | Ever started work only to find out halfway it was blocked on something else? | hook | Refuses to start work until every precondition for the task is checked live and found clear. | **`verify-dispatch` CLI** (`packages/aeg-core/bin/verify-dispatch.ts` — mandated by `roles/developer.md` and `skills/brief-authoring/SKILL.md`; **now also hook-automated** — task 25) | Every dispatch precondition is re-checked live against the forge (the task's row/Issue are derived directly from a Milestone + `vinaya/tranche:<slug>`-labeled Issues as of the forge-native migration — no `origin/main` file read involved; leftover-branch detection still fetches `origin/main` for its own commit-count comparison): the task's row and Issue exist; the Issue passes the rationale gate; every `depends-on` PR is merged and no `conflicts-with` PR is open/in-flight; every named project's prior tranche is archived. (2026-07-13: the immediately-prior task's three-predicate archival bar — the row-adjacency predicate — was removed once the provenance-posting signal it existed to protect became automated.) A `NOT READY` result is a stop condition. Every `gh` call this script makes carries an explicit `-R <owner>/<repo>` (task 23) — from a linked `git worktree add` checkout, an untargeted `gh issue list`/`gh issue view`/`gh pr list` silently scopes to the wrong repo (or returns nothing), which previously produced false prior-tranche-archival blockers. **`.husky/pre-push`** now runs this gate itself on a `task/*/*` branch's first push (before a PR exists), refusing on genuine `NOT READY` and failing OPEN — loudly — when a `gh auth status` reachability probe fails or `verify-dispatch`'s own repo/token resolution fails (task 18's fail-open precedent). The gate reads only the `dispatch-readiness:` predicate, not verify-dispatch's combined exit code, which also folds in `leftover-detection` (a pre-Step-0 "safe to branch fresh" advisory that would otherwise false-block every push after the first on a task legitimately mid-flight — discovered live while building this gate). Once a PR exists, later pushes skip the gate: dispatch was already validated once. | `packages/aeg-core/bin/verify-dispatch.ts` |
 | Opening a task PR whose surface includes real code | Ever had a PR's description quietly stop matching what the code does? | event | Refuses a code-carrying pull request whose description no longer matches what it changes. | **Brief Validation — `checkPremiseCoverage`** | The PR body carries a `Premise:` block with at least one assertion (`contains`/`absent`/`sha256`) whose path falls inside the task's surface map — re-assertable at any point via `verify-dispatch --premise` or `verify-task`. | `packages/aeg-core/src/brief-validation.ts` |
 | Opening a task PR (final self-check before creation) | Ever opened a PR and only then discovered the tests were failing? | event | Runs the whole exit check before a pull request is created, so failures surface first. | **`verify-task` CLI** (`packages/aeg-core/bin/verify-task.ts` — mandated by `roles/developer.md`; **now also hook-automated** — task 25) | Typecheck, lint, tests, build, `verify-docs --pr`, and the premise coverage/recheck pair all pass, as one summary, against the PR's actual diff, before `open-pr.ts` is invoked. **`open-pr.ts` now runs this composite itself** for task branches (via `gatePlanForBranch`), invoked wholesale rather than partially re-implemented — non-task branches are unaffected (byte-identical gate set). `verify-docs --pr` runs twice on a task-branch PR-open as an accepted, measured overlap (~4s with a warm turbo cache). | `packages/aeg-core/bin/verify-task.ts` |
-| Spawning a check (`vinaya check`, ring-0 pre-push AND ring-1 CI) | Ever had a check quietly read a secret it had no business seeing, because nothing scoped what it could reach? | hook | Governs which environment variables a spawned check's child process can see, instead of every check inheriting the full parent environment unconditionally. | **Env allowlist** (`CheckSpec['env']`, `apps/vinaya/cli/src/checks/contract.ts`; construction: `buildCheckEnv`, `apps/vinaya/cli/src/checks/runner.ts`) | **⚠️ BREAKING, live (task 3):** a spawned check's child process sees only a fixed baseline (`PATH`, `LANG`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `TMPDIR`) plus whatever its own `env` declaration (`true` / `{ optional: true }` / `{ anyOf: [...] }` / a literal string) explicitly forwards — **no longer the full parent environment.** An undeclared variable a check's own code reads is now genuinely invisible to it, not merely warned about; a `true` or unsatisfied `anyOf` declaration missing from the caller's environment synthesizes a `CheckError` and the check never spawns at all. All 15 core checks in `registry.ts` carry an audited declaration, and every core check that spawns `gh` or reaches the forge through the token-resolution chain additionally forwards `GITHUB_TOKEN`/`GH_TOKEN` as `{ optional: true }` — on a CI runner those env vars are `gh`'s only authentication path, so a check that shells out without forwarding them runs unauthenticated there (hard-failing or silently degrading, depending on the bin's failure mode) while passing locally on `gh`'s keyring; the pairing is coupling-tested (`apps/vinaya/cli/tests/checks/registry-env.test.ts` detects `gh` invocations in any call shape — array-form, string-form, and template-literal — and demands both declarations); that detection is source-text pattern matching, so it does not yet catch a check that reaches the forge indirectly through `createForgeSource` (`@atta/vinaya-sources`) with no literal `gh` call of its own — found live: `closes-n` reaches the forge this way and had shipped without either token declared, passing locally under a developer's own `gh` keyring and failing unauthenticated on every CI runner, a known gap in the coupling test's own coverage rather than in the rule it's checking. This repo's own core checks are therefore unaffected — an adopter's **custom** check that reads `process.env` directly with no `env` declared will lose that access at this minor; declare `env` on it (`vinaya.config.json`'s `checks.<name>.env`) before upgrading. `vinaya check`'s prior warn-phase print (task 2) is retired now that the behavior it warned about is live; `vinaya doctor` still carries the same missing-declaration diagnostic permanently, at `info` severity, so a custom check's gap remains visible after upgrade even though `vinaya check` no longer prints it inline. | `apps/vinaya/cli/src/checks/runner.ts` |
+| Spawning a check (`vinaya check`, ring-0 pre-push AND ring-1 CI) | Ever had a check quietly read a secret it had no business seeing, because nothing scoped what it could reach? | hook | Governs which environment variables a spawned check's child process can see, instead of every check inheriting the full parent environment unconditionally. | **Env allowlist** (`CheckSpec['env']`, `apps/vinaya/cli/src/checks/contract.ts`; construction: `buildCheckEnv`, `apps/vinaya/cli/src/checks/runner.ts`) | **⚠️ BREAKING, live (task 3):** a spawned check's child process sees only a fixed baseline (`PATH`, `LANG`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `TMPDIR`) plus whatever its own `env` declaration (`true` / `{ optional: true }` / `{ anyOf: [...] }` / a literal string) explicitly forwards — **no longer the full parent environment.** An undeclared variable a check's own code reads is now genuinely invisible to it, not merely warned about; a `true` or unsatisfied `anyOf` declaration missing from the caller's environment synthesizes a `CheckError` and the check never spawns at all. All 15 core checks in `registry.ts` carry an audited declaration, and every core check that spawns `gh` or reaches the forge through the token-resolution chain additionally forwards `GITHUB_TOKEN`/`GH_TOKEN` as `{ optional: true }` — on a CI runner those env vars are `gh`'s only authentication path, so a check that shells out without forwarding them runs unauthenticated there (hard-failing or silently degrading, depending on the bin's failure mode) while passing locally on `gh`'s keyring; the pairing is coupling-tested (`apps/vinaya/cli/tests/checks/registry-env.test.ts` detects `gh` invocations in any call shape — array-form, string-form, and template-literal — and demands both declarations); that detection is source-text pattern matching, so it does not yet catch a check that reaches the forge indirectly through `createForgeSource` (`@atta/vinaya-sources`) with no literal `gh` call of its own — found live: `closes-n` reaches the forge this way and had shipped without either token declared, passing locally under a developer's own `gh` keyring and failing unauthenticated on every CI runner, a known gap in the coupling test's own coverage rather than in the rule it's checking. This repo's own core checks are therefore unaffected — an adopter's **custom** check that reads `process.env` directly with no `env` declared will lose that access at this minor; declare `env` on it (`vinaya.config.json`'s `checks.<name>.env`) before upgrading. `vinaya check`'s prior warn-phase print (task 2) is retired now that the behavior it warned about is live; `vinaya doctor` still carries the same missing-declaration diagnostic permanently, at `info` severity, so a custom check's gap remains visible after upgrade even though `vinaya check` no longer prints it inline. A second field, `requiresOpenPr?: boolean` (same no-privileged-field discipline as `env` — a custom check can declare it exactly like a core one), marks a check that can only evaluate meaningfully once a pull request exists; the generated `pre-commit`/`pre-push` hooks pass a new `--local` flag that skips every check declaring it, while CI (`vinaya-checks.yml`, `pull_request`-triggered) omits the flag and always runs them for real. Found live: `closes-n`/`test-plan` ran unconditionally in both hooks with no `requiresOpenPr` field to opt out on, so the first commit on a fresh task branch could never satisfy either — no PR exists yet at commit or push time, only after. Found live again, same missing-declaration class: `brief-shape` read `BRANCH` from `process.env` in its own bin without declaring it in `registry.ts`'s allowlist, so the runner stripped the variable before the child ever spawned — the non-task-branch bypass its logic depended on (skipping the `Closes #N` requirement for a standalone brief with no Issue to close) silently never fired; `registry.ts` now declares `BRANCH: { optional: true }` on that entry alongside `PR_BODY`, mirroring `test-plan`'s existing declaration for the same pair. `vinaya.config.json`'s `principals` field (the review-gate/waiver trust anchor, `apps/vinaya/cli/src/lib/config.ts`'s `resolvePrincipalAllowlist`) is resolved via `loadTrustAnchorConfig()` — a `gh api` read of the repository's DEFAULT BRANCH, never local git, the PR's working tree, or any env var. Three successive attempts got this wrong before landing (all caught pre-merge): reading the PR's working tree; reading `git show ${BASE_SHA}:…` where `BASE_SHA` was an env var; and reading `git show origin/main:…`, where `origin/main` is a LOCAL remote-tracking ref the PR's own workflow can `git update-ref`. The rule they establish: **inside a `pull_request`-triggered workflow nothing on the job's own disk or environment is a trust boundary against the PR author**, because the workflow definition itself comes from the PR. `check-doc-coverage.ts`/`check-doc-coverage-push.ts` keep their own, separate, legitimately-overridable `BASE_SHA` for diff-scoping only, never reused for a trust decision. The API read raises the bar but is not itself the boundary — a PR can still delete the gate's step from its own workflow copy; only **branch protection with the check marked required** makes review enforcement unbypassable, which is why `init` prints that command and `doctor` reports its absence. | `apps/vinaya/cli/src/checks/runner.ts` |
 | `vinaya check` / `vinaya check --plan` (a CLI mechanism, not a git hook — this row is `.husky`-free) | Ever had a config entry silently double-run alongside the core check it was meant to replace, with no way to see that from the outside? | event | Resolves core-registered and config-registered checks into one deterministic table before anything runs, instead of letting a config entry run alongside the core check it collides with, unannounced. | **Checks-side resolver** (`resolveChecks`/`isValidNamespacedKey`, `apps/vinaya/cli/src/checks/resolver.ts`) | An exact-key match against a core check ID is an **override** — a complete replacement of the spec, never a merge. A key containing exactly one `/`, both segments matching `[a-z0-9][a-z0-9-]*` and the `vinaya` prefix rejected as an exact segment match, is **additive**. Anything else — a bare key with no `/` matching no core ID — is a loud `FAIL_CLOSED` refusal: never silently dropped, never defaulted, never last-wins. `--plan` never resolves or prints an env *value*, only how each one resolves. **This release feeds `vinaya check --plan` / `--plan --json` only** — `vinaya check`'s real execution (`check.ts`'s flat `[...coreCheckRegistry(), ...customSpecs]` concat) is unaffected until a later task wires it in. | `apps/vinaya/cli/src/checks/resolver.ts` |
 
 **Documentation coverage, specifically** (a historical pain point): the code→document ownership rule is enforced at *two* prevention chokepoints — at every push (over the branch's cumulative change set) and again at pull-request creation and editing. A change to owned code cannot be published, let alone turned into a pull request, without its owning document.

package/aeg-root/state-machine.md

@@ -444,7 +444,7 @@ For each changed code file in the PR, glob-match against every binding. Per **ma
 | **Strong-pass** | The in-repo pointer is in the PR diff. |
 | **URL-ack** | The pointer is a URL **and** the PR body carries `Doc-ack: <pointer> — <note>` whose `<pointer>` exactly matches the binding's URL. |
 | **Neutral-edit** | The pointer is in-repo, absent from the diff, **and** the PR body carries `Doc-neutral: <pointer> — <note>` whose `<pointer>` exactly matches the binding's doc, **and** the diff of every matched code file is comment/whitespace-only (see below). Both the declaration and the evidence are required — either alone fails. |
-| **Waiver** | The pull request carries the `vinaya/waiver:docs` label, AND the actor of that label's most recent labeling timeline event is a configured principal. PR-wide, not per-binding — one verified label satisfies every fired binding in the PR. Label presence alone is never sufficient; there is no PR-body waiver field. |
+| **Waiver** | The pull request carries the `vinaya/waiver:docs` label, AND the actor of that label's most recent labeling timeline event is a configured principal (`isPrincipal`, `packages/aeg-core/src/waiver-label.ts` — matched **case-insensitively**, since GitHub logins are; an exact-match test fails closed but invisibly, stranding a real principal's action for a reason nothing states). PR-wide, not per-binding — one verified label satisfies every fired binding in the PR. Label presence alone is never sufficient; there is no PR-body waiver field. |
 
 If none of the above hold, C5 fails the PR. A binding whose in-repo pointer **does not exist on disk** is a distinct *dangling* failure (fix the binding or add the doc) — never silently ignored, because a dangling pointer is the failure mode the seam was built to prevent.
 

package/dist/checks/bin/check-branch-topology.js

@@ -1451,12 +1451,16 @@ function isCodeFile(p) {
 var WAIVER_LABEL = label("waiver-docs");
 var WAIVER_LABEL_REVIEW = label("waiver-review");
 var PRINCIPAL_ALLOWLIST = ["daniboomerang"];
+function isPrincipal(login, principalAllowlist) {
+  if (login === null)
+    return false;
+  const normalized = login.toLowerCase();
+  return principalAllowlist.some((p) => p.toLowerCase() === normalized);
+}
 function isWaiverLabelActorVerified(opts) {
   if (!opts.labels.includes(opts.label))
     return false;
-  if (opts.labelActor === null)
-    return false;
-  return opts.principalAllowlist.includes(opts.labelActor);
+  return isPrincipal(opts.labelActor, opts.principalAllowlist);
 }
 
 // ../../../packages/aeg-core/src/doc-owners.ts
@@ -1644,6 +1648,27 @@ function overrideActive(opts) {
 // ../../../packages/aeg-core/src/premise-check.ts
 var ASSERTION_KINDS = new Set(["contains", "absent", "sha256"]);
 
+// ../../../packages/aeg-core/src/test-plan-section.ts
+var HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im;
+var INLINE_FORM_RE = /^[ \t]*\*{0,2}Test Plan:?\*{0,2}/im;
+var NEXT_SECTION_RE = /\n(?:#{1,3}[ \t]|\*\*[A-Z][^*\n]*:\*\*)/;
+function locateTestPlanSection(body) {
+  const region = anchoredRegion(body, "TEST-PLAN");
+  if (region !== null)
+    return { found: true, section: region };
+  const headingMatch = HEADING_FORM_RE.exec(body);
+  const match = headingMatch ?? INLINE_FORM_RE.exec(body);
+  if (!match || match.index === undefined)
+    return { found: false };
+  const sectionBody = body.slice(match.index);
+  const firstLineEnd = sectionBody.indexOf(`
+`);
+  const searchFrom = firstLineEnd === -1 ? sectionBody.length : firstLineEnd + 1;
+  const nextMatch = sectionBody.slice(searchFrom).match(NEXT_SECTION_RE);
+  const sectionEnd = nextMatch ? searchFrom + (nextMatch.index ?? 0) : sectionBody.length;
+  return { found: true, section: sectionBody.slice(0, sectionEnd) };
+}
+
 // ../../../packages/aeg-core/src/brief-validation.ts
 function headerRegion(prBody) {
   const m = prBody.match(/^##\s/m);
@@ -1682,10 +1707,15 @@ function checkTierField(prBody, readTier) {
   };
 }
 var TEST_PLAN_UNIT_TESTS_ONLY_RE = /(?:\*\*)?Test Plan(?:\*\*)?\s*:\s*(?:\*\*)?\s*unit-tests-only/i;
+function testPlanRegion(prBody) {
+  const located = locateTestPlanSection(prBody);
+  return located.found ? located.section : prBody;
+}
 function checkTestPlan(prBody) {
-  if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(prBody))
+  const region = testPlanRegion(prBody);
+  if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
-  if (/\*\*\[(?:agent|principal)\]\*\*/.test(prBody))
+  if (/\*\*\[(?:agent|principal)\]\*\*/.test(region))
     return { status: "pass", errors: [] };
   return {
     status: "fail",
@@ -1695,9 +1725,10 @@ function checkTestPlan(prBody) {
   };
 }
 function checkTestPlanExclusivity(prBody) {
-  if (!TEST_PLAN_UNIT_TESTS_ONLY_RE.test(prBody))
+  const region = testPlanRegion(prBody);
+  if (!TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
-  if (/^-\s*\[[ xX]\]\s*\*{2}\[(?:agent|principal)\]\*{2}/im.test(prBody)) {
+  if (/^-\s*\[[ xX]\]\s*\*{2}\[(?:agent|principal)\]\*{2}/im.test(region)) {
     return {
       status: "fail",
       errors: [
@@ -1708,8 +1739,9 @@ function checkTestPlanExclusivity(prBody) {
   return { status: "pass", errors: [] };
 }
 function checkPrincipalPlaceholder(prBody) {
+  const region = testPlanRegion(prBody);
   const lineRe = /^-\s*\[[ xX]\]\s*\*{2}\[principal\]\*{2}(.*)$/gim;
-  for (const m of prBody.matchAll(lineRe)) {
+  for (const m of region.matchAll(lineRe)) {
     const content = m[1] ?? "";
     if (/^\s*None\b/i.test(content)) {
       return {
@@ -1788,6 +1820,15 @@ function checkClosesN(prBody) {
     errors: ["brief-validation Closes #N: no `Closes #<N>` (or Fixes/Resolves) reference found in the PR body."]
   };
 }
+var BRIEF_SHAPE_MARKERS = [checkSurfaceMap, checkDocUpdateList, checkStopConditions, checkAutonomyClause];
+var TASK_BRANCH_PATTERN = /^task\/[^/]+\/[^/]+$/;
+function isTaskBranch(branch) {
+  return TASK_BRANCH_PATTERN.test(branch);
+}
+function isBriefShaped(prBody) {
+  const stripped = stripCode(prBody);
+  return BRIEF_SHAPE_MARKERS.filter((check) => check(stripped).status === "pass").length >= 2;
+}
 function checkBriefSections(prBody, readTier, options = {}) {
   const { requireClosesN = true } = options;
   const results = [
@@ -2157,11 +2198,12 @@ function isReviewGateExemptBranch(branch) {
   return branch.startsWith("plan/");
 }
 function checkReviewGate(input) {
+  const principalAllowlist = input.principalAllowlist ?? PRINCIPAL_ALLOWLIST;
   const waived = isWaiverLabelActorVerified({
     label: WAIVER_LABEL_REVIEW,
     labels: input.labels,
     labelActor: input.waiverLabelActor,
-    principalAllowlist: PRINCIPAL_ALLOWLIST
+    principalAllowlist
   });
   if (waived) {
     return {
@@ -2170,8 +2212,8 @@ function checkReviewGate(input) {
       waived: true
     };
   }
-  const verified = input.comments.filter((c) => c.author !== null && PRINCIPAL_ALLOWLIST.includes(c.author));
-  const ignoredCount = input.comments.filter((c) => (c.author === null || !PRINCIPAL_ALLOWLIST.includes(c.author)) && c.body.includes("VERDICT")).length;
+  const verified = input.comments.filter((c) => isPrincipal(c.author, principalAllowlist));
+  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);
@@ -2724,28 +2766,8 @@ function decideIssueAssignment(input) {
     reason: `First push of \`${branch}\` — assigning Issue #${issue} to @${login} (the authenticated pusher).`
   };
 }
-// ../../../packages/aeg-core/src/test-plan-section.ts
-var HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im;
-var INLINE_FORM_RE = /^[ \t]*\*{0,2}Test Plan:?\*{0,2}/im;
-var NEXT_SECTION_RE = /\n(?:#{1,3}[ \t]|\*\*[A-Z][^*\n]*:\*\*)/;
-function locateTestPlanSection(body) {
-  const region = anchoredRegion(body, "TEST-PLAN");
-  if (region !== null)
-    return { found: true, section: region };
-  const headingMatch = HEADING_FORM_RE.exec(body);
-  const match = headingMatch ?? INLINE_FORM_RE.exec(body);
-  if (!match || match.index === undefined)
-    return { found: false };
-  const sectionBody = body.slice(match.index);
-  const firstLineEnd = sectionBody.indexOf(`
-`);
-  const searchFrom = firstLineEnd === -1 ? sectionBody.length : firstLineEnd + 1;
-  const nextMatch = sectionBody.slice(searchFrom).match(NEXT_SECTION_RE);
-  const sectionEnd = nextMatch ? searchFrom + (nextMatch.index ?? 0) : sectionBody.length;
-  return { found: true, section: sectionBody.slice(0, sectionEnd) };
-}
 // ../../../packages/aeg-core/src/test-plan-gate.ts
-var TASK_BRANCH_PATTERN = /^task\/[^/]+\/[^/]+$/;
+var TASK_BRANCH_PATTERN2 = /^task\/[^/]+\/[^/]+$/;
 function evaluateTestPlanGate(body, branch) {
   if (!body) {
     return {
@@ -2758,7 +2780,7 @@ function evaluateTestPlanGate(body, branch) {
   }
   const located = locateTestPlanSection(body);
   if (!located.found) {
-    if (TASK_BRANCH_PATTERN.test(branch)) {
+    if (TASK_BRANCH_PATTERN2.test(branch)) {
       return {
         verdict: "fail",
         messages: [

package/dist/checks/bin/check-brief-shape.js

@@ -1448,12 +1448,16 @@ function isCodeFile(p) {
 var WAIVER_LABEL = label("waiver-docs");
 var WAIVER_LABEL_REVIEW = label("waiver-review");
 var PRINCIPAL_ALLOWLIST = ["daniboomerang"];
+function isPrincipal(login, principalAllowlist) {
+  if (login === null)
+    return false;
+  const normalized = login.toLowerCase();
+  return principalAllowlist.some((p) => p.toLowerCase() === normalized);
+}
 function isWaiverLabelActorVerified(opts) {
   if (!opts.labels.includes(opts.label))
     return false;
-  if (opts.labelActor === null)
-    return false;
-  return opts.principalAllowlist.includes(opts.labelActor);
+  return isPrincipal(opts.labelActor, opts.principalAllowlist);
 }
 
 // ../../../packages/aeg-core/src/doc-owners.ts
@@ -1641,6 +1645,27 @@ function overrideActive(opts) {
 // ../../../packages/aeg-core/src/premise-check.ts
 var ASSERTION_KINDS = new Set(["contains", "absent", "sha256"]);
 
+// ../../../packages/aeg-core/src/test-plan-section.ts
+var HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im;
+var INLINE_FORM_RE = /^[ \t]*\*{0,2}Test Plan:?\*{0,2}/im;
+var NEXT_SECTION_RE = /\n(?:#{1,3}[ \t]|\*\*[A-Z][^*\n]*:\*\*)/;
+function locateTestPlanSection(body) {
+  const region = anchoredRegion(body, "TEST-PLAN");
+  if (region !== null)
+    return { found: true, section: region };
+  const headingMatch = HEADING_FORM_RE.exec(body);
+  const match = headingMatch ?? INLINE_FORM_RE.exec(body);
+  if (!match || match.index === undefined)
+    return { found: false };
+  const sectionBody = body.slice(match.index);
+  const firstLineEnd = sectionBody.indexOf(`
+`);
+  const searchFrom = firstLineEnd === -1 ? sectionBody.length : firstLineEnd + 1;
+  const nextMatch = sectionBody.slice(searchFrom).match(NEXT_SECTION_RE);
+  const sectionEnd = nextMatch ? searchFrom + (nextMatch.index ?? 0) : sectionBody.length;
+  return { found: true, section: sectionBody.slice(0, sectionEnd) };
+}
+
 // ../../../packages/aeg-core/src/brief-validation.ts
 function headerRegion(prBody) {
   const m = prBody.match(/^##\s/m);
@@ -1679,10 +1704,15 @@ function checkTierField(prBody, readTier) {
   };
 }
 var TEST_PLAN_UNIT_TESTS_ONLY_RE = /(?:\*\*)?Test Plan(?:\*\*)?\s*:\s*(?:\*\*)?\s*unit-tests-only/i;
+function testPlanRegion(prBody) {
+  const located = locateTestPlanSection(prBody);
+  return located.found ? located.section : prBody;
+}
 function checkTestPlan(prBody) {
-  if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(prBody))
+  const region = testPlanRegion(prBody);
+  if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
-  if (/\*\*\[(?:agent|principal)\]\*\*/.test(prBody))
+  if (/\*\*\[(?:agent|principal)\]\*\*/.test(region))
     return { status: "pass", errors: [] };
   return {
     status: "fail",
@@ -1692,9 +1722,10 @@ function checkTestPlan(prBody) {
   };
 }
 function checkTestPlanExclusivity(prBody) {
-  if (!TEST_PLAN_UNIT_TESTS_ONLY_RE.test(prBody))
+  const region = testPlanRegion(prBody);
+  if (!TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
-  if (/^-\s*\[[ xX]\]\s*\*{2}\[(?:agent|principal)\]\*{2}/im.test(prBody)) {
+  if (/^-\s*\[[ xX]\]\s*\*{2}\[(?:agent|principal)\]\*{2}/im.test(region)) {
     return {
       status: "fail",
       errors: [
@@ -1705,8 +1736,9 @@ function checkTestPlanExclusivity(prBody) {
   return { status: "pass", errors: [] };
 }
 function checkPrincipalPlaceholder(prBody) {
+  const region = testPlanRegion(prBody);
   const lineRe = /^-\s*\[[ xX]\]\s*\*{2}\[principal\]\*{2}(.*)$/gim;
-  for (const m of prBody.matchAll(lineRe)) {
+  for (const m of region.matchAll(lineRe)) {
     const content = m[1] ?? "";
     if (/^\s*None\b/i.test(content)) {
       return {
@@ -1785,6 +1817,15 @@ function checkClosesN(prBody) {
     errors: ["brief-validation Closes #N: no `Closes #<N>` (or Fixes/Resolves) reference found in the PR body."]
   };
 }
+var BRIEF_SHAPE_MARKERS = [checkSurfaceMap, checkDocUpdateList, checkStopConditions, checkAutonomyClause];
+var TASK_BRANCH_PATTERN = /^task\/[^/]+\/[^/]+$/;
+function isTaskBranch(branch) {
+  return TASK_BRANCH_PATTERN.test(branch);
+}
+function isBriefShaped(prBody) {
+  const stripped = stripCode(prBody);
+  return BRIEF_SHAPE_MARKERS.filter((check) => check(stripped).status === "pass").length >= 2;
+}
 function checkBriefSections(prBody, readTier, options = {}) {
   const { requireClosesN = true } = options;
   const results = [
@@ -2154,11 +2195,12 @@ function isReviewGateExemptBranch(branch) {
   return branch.startsWith("plan/");
 }
 function checkReviewGate(input) {
+  const principalAllowlist = input.principalAllowlist ?? PRINCIPAL_ALLOWLIST;
   const waived = isWaiverLabelActorVerified({
     label: WAIVER_LABEL_REVIEW,
     labels: input.labels,
     labelActor: input.waiverLabelActor,
-    principalAllowlist: PRINCIPAL_ALLOWLIST
+    principalAllowlist
   });
   if (waived) {
     return {
@@ -2167,8 +2209,8 @@ function checkReviewGate(input) {
       waived: true
     };
   }
-  const verified = input.comments.filter((c) => c.author !== null && PRINCIPAL_ALLOWLIST.includes(c.author));
-  const ignoredCount = input.comments.filter((c) => (c.author === null || !PRINCIPAL_ALLOWLIST.includes(c.author)) && c.body.includes("VERDICT")).length;
+  const verified = input.comments.filter((c) => isPrincipal(c.author, principalAllowlist));
+  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);
@@ -2721,28 +2763,8 @@ function decideIssueAssignment(input) {
     reason: `First push of \`${branch}\` — assigning Issue #${issue} to @${login} (the authenticated pusher).`
   };
 }
-// ../../../packages/aeg-core/src/test-plan-section.ts
-var HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im;
-var INLINE_FORM_RE = /^[ \t]*\*{0,2}Test Plan:?\*{0,2}/im;
-var NEXT_SECTION_RE = /\n(?:#{1,3}[ \t]|\*\*[A-Z][^*\n]*:\*\*)/;
-function locateTestPlanSection(body) {
-  const region = anchoredRegion(body, "TEST-PLAN");
-  if (region !== null)
-    return { found: true, section: region };
-  const headingMatch = HEADING_FORM_RE.exec(body);
-  const match = headingMatch ?? INLINE_FORM_RE.exec(body);
-  if (!match || match.index === undefined)
-    return { found: false };
-  const sectionBody = body.slice(match.index);
-  const firstLineEnd = sectionBody.indexOf(`
-`);
-  const searchFrom = firstLineEnd === -1 ? sectionBody.length : firstLineEnd + 1;
-  const nextMatch = sectionBody.slice(searchFrom).match(NEXT_SECTION_RE);
-  const sectionEnd = nextMatch ? searchFrom + (nextMatch.index ?? 0) : sectionBody.length;
-  return { found: true, section: sectionBody.slice(0, sectionEnd) };
-}
 // ../../../packages/aeg-core/src/test-plan-gate.ts
-var TASK_BRANCH_PATTERN = /^task\/[^/]+\/[^/]+$/;
+var TASK_BRANCH_PATTERN2 = /^task\/[^/]+\/[^/]+$/;
 function evaluateTestPlanGate(body, branch) {
   if (!body) {
     return {
@@ -2755,7 +2777,7 @@ function evaluateTestPlanGate(body, branch) {
   }
   const located = locateTestPlanSection(body);
   if (!located.found) {
-    if (TASK_BRANCH_PATTERN.test(branch)) {
+    if (TASK_BRANCH_PATTERN2.test(branch)) {
       return {
         verdict: "fail",
         messages: [
@@ -2819,7 +2841,12 @@ function main() {
   if (!prBody) {
     process.exit(0);
   }
-  const { errors } = checkBriefSections(prBody, readTierFromPrBody);
+  const branch = process.env.BRANCH ?? "";
+  const taskBranch = isTaskBranch(branch);
+  if (branch && !taskBranch && !isBriefShaped(prBody)) {
+    process.exit(0);
+  }
+  const { errors } = checkBriefSections(prBody, readTierFromPrBody, { requireClosesN: taskBranch });
   if (errors.length > 0) {
     for (const message of errors) {
       emitCheckError({

package/dist/checks/bin/check-closes-n.js

@@ -1451,12 +1451,16 @@ function isCodeFile(p) {
 var WAIVER_LABEL = label("waiver-docs");
 var WAIVER_LABEL_REVIEW = label("waiver-review");
 var PRINCIPAL_ALLOWLIST = ["daniboomerang"];
+function isPrincipal(login, principalAllowlist) {
+  if (login === null)
+    return false;
+  const normalized = login.toLowerCase();
+  return principalAllowlist.some((p) => p.toLowerCase() === normalized);
+}
 function isWaiverLabelActorVerified(opts) {
   if (!opts.labels.includes(opts.label))
     return false;
-  if (opts.labelActor === null)
-    return false;
-  return opts.principalAllowlist.includes(opts.labelActor);
+  return isPrincipal(opts.labelActor, opts.principalAllowlist);
 }
 
 // ../../../packages/aeg-core/src/doc-owners.ts
@@ -1644,6 +1648,27 @@ function overrideActive(opts) {
 // ../../../packages/aeg-core/src/premise-check.ts
 var ASSERTION_KINDS = new Set(["contains", "absent", "sha256"]);
 
+// ../../../packages/aeg-core/src/test-plan-section.ts
+var HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im;
+var INLINE_FORM_RE = /^[ \t]*\*{0,2}Test Plan:?\*{0,2}/im;
+var NEXT_SECTION_RE = /\n(?:#{1,3}[ \t]|\*\*[A-Z][^*\n]*:\*\*)/;
+function locateTestPlanSection(body) {
+  const region = anchoredRegion(body, "TEST-PLAN");
+  if (region !== null)
+    return { found: true, section: region };
+  const headingMatch = HEADING_FORM_RE.exec(body);
+  const match = headingMatch ?? INLINE_FORM_RE.exec(body);
+  if (!match || match.index === undefined)
+    return { found: false };
+  const sectionBody = body.slice(match.index);
+  const firstLineEnd = sectionBody.indexOf(`
+`);
+  const searchFrom = firstLineEnd === -1 ? sectionBody.length : firstLineEnd + 1;
+  const nextMatch = sectionBody.slice(searchFrom).match(NEXT_SECTION_RE);
+  const sectionEnd = nextMatch ? searchFrom + (nextMatch.index ?? 0) : sectionBody.length;
+  return { found: true, section: sectionBody.slice(0, sectionEnd) };
+}
+
 // ../../../packages/aeg-core/src/brief-validation.ts
 function headerRegion(prBody) {
   const m = prBody.match(/^##\s/m);
@@ -1682,10 +1707,15 @@ function checkTierField(prBody, readTier) {
   };
 }
 var TEST_PLAN_UNIT_TESTS_ONLY_RE = /(?:\*\*)?Test Plan(?:\*\*)?\s*:\s*(?:\*\*)?\s*unit-tests-only/i;
+function testPlanRegion(prBody) {
+  const located = locateTestPlanSection(prBody);
+  return located.found ? located.section : prBody;
+}
 function checkTestPlan(prBody) {
-  if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(prBody))
+  const region = testPlanRegion(prBody);
+  if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
-  if (/\*\*\[(?:agent|principal)\]\*\*/.test(prBody))
+  if (/\*\*\[(?:agent|principal)\]\*\*/.test(region))
     return { status: "pass", errors: [] };
   return {
     status: "fail",
@@ -1695,9 +1725,10 @@ function checkTestPlan(prBody) {
   };
 }
 function checkTestPlanExclusivity(prBody) {
-  if (!TEST_PLAN_UNIT_TESTS_ONLY_RE.test(prBody))
+  const region = testPlanRegion(prBody);
+  if (!TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
-  if (/^-\s*\[[ xX]\]\s*\*{2}\[(?:agent|principal)\]\*{2}/im.test(prBody)) {
+  if (/^-\s*\[[ xX]\]\s*\*{2}\[(?:agent|principal)\]\*{2}/im.test(region)) {
     return {
       status: "fail",
       errors: [
@@ -1708,8 +1739,9 @@ function checkTestPlanExclusivity(prBody) {
   return { status: "pass", errors: [] };
 }
 function checkPrincipalPlaceholder(prBody) {
+  const region = testPlanRegion(prBody);
   const lineRe = /^-\s*\[[ xX]\]\s*\*{2}\[principal\]\*{2}(.*)$/gim;
-  for (const m of prBody.matchAll(lineRe)) {
+  for (const m of region.matchAll(lineRe)) {
     const content = m[1] ?? "";
     if (/^\s*None\b/i.test(content)) {
       return {
@@ -1788,6 +1820,15 @@ function checkClosesN(prBody) {
     errors: ["brief-validation Closes #N: no `Closes #<N>` (or Fixes/Resolves) reference found in the PR body."]
   };
 }
+var BRIEF_SHAPE_MARKERS = [checkSurfaceMap, checkDocUpdateList, checkStopConditions, checkAutonomyClause];
+var TASK_BRANCH_PATTERN = /^task\/[^/]+\/[^/]+$/;
+function isTaskBranch(branch) {
+  return TASK_BRANCH_PATTERN.test(branch);
+}
+function isBriefShaped(prBody) {
+  const stripped = stripCode(prBody);
+  return BRIEF_SHAPE_MARKERS.filter((check) => check(stripped).status === "pass").length >= 2;
+}
 function checkBriefSections(prBody, readTier, options = {}) {
   const { requireClosesN = true } = options;
   const results = [
@@ -2157,11 +2198,12 @@ function isReviewGateExemptBranch(branch) {
   return branch.startsWith("plan/");
 }
 function checkReviewGate(input) {
+  const principalAllowlist = input.principalAllowlist ?? PRINCIPAL_ALLOWLIST;
   const waived = isWaiverLabelActorVerified({
     label: WAIVER_LABEL_REVIEW,
     labels: input.labels,
     labelActor: input.waiverLabelActor,
-    principalAllowlist: PRINCIPAL_ALLOWLIST
+    principalAllowlist
   });
   if (waived) {
     return {
@@ -2170,8 +2212,8 @@ function checkReviewGate(input) {
       waived: true
     };
   }
-  const verified = input.comments.filter((c) => c.author !== null && PRINCIPAL_ALLOWLIST.includes(c.author));
-  const ignoredCount = input.comments.filter((c) => (c.author === null || !PRINCIPAL_ALLOWLIST.includes(c.author)) && c.body.includes("VERDICT")).length;
+  const verified = input.comments.filter((c) => isPrincipal(c.author, principalAllowlist));
+  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);
@@ -2724,28 +2766,8 @@ function decideIssueAssignment(input) {
     reason: `First push of \`${branch}\` — assigning Issue #${issue} to @${login} (the authenticated pusher).`
   };
 }
-// ../../../packages/aeg-core/src/test-plan-section.ts
-var HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im;
-var INLINE_FORM_RE = /^[ \t]*\*{0,2}Test Plan:?\*{0,2}/im;
-var NEXT_SECTION_RE = /\n(?:#{1,3}[ \t]|\*\*[A-Z][^*\n]*:\*\*)/;
-function locateTestPlanSection(body) {
-  const region = anchoredRegion(body, "TEST-PLAN");
-  if (region !== null)
-    return { found: true, section: region };
-  const headingMatch = HEADING_FORM_RE.exec(body);
-  const match = headingMatch ?? INLINE_FORM_RE.exec(body);
-  if (!match || match.index === undefined)
-    return { found: false };
-  const sectionBody = body.slice(match.index);
-  const firstLineEnd = sectionBody.indexOf(`
-`);
-  const searchFrom = firstLineEnd === -1 ? sectionBody.length : firstLineEnd + 1;
-  const nextMatch = sectionBody.slice(searchFrom).match(NEXT_SECTION_RE);
-  const sectionEnd = nextMatch ? searchFrom + (nextMatch.index ?? 0) : sectionBody.length;
-  return { found: true, section: sectionBody.slice(0, sectionEnd) };
-}
 // ../../../packages/aeg-core/src/test-plan-gate.ts
-var TASK_BRANCH_PATTERN = /^task\/[^/]+\/[^/]+$/;
+var TASK_BRANCH_PATTERN2 = /^task\/[^/]+\/[^/]+$/;
 function evaluateTestPlanGate(body, branch) {
   if (!body) {
     return {
@@ -2758,7 +2780,7 @@ function evaluateTestPlanGate(body, branch) {
   }
   const located = locateTestPlanSection(body);
   if (!located.found) {
-    if (TASK_BRANCH_PATTERN.test(branch)) {
+    if (TASK_BRANCH_PATTERN2.test(branch)) {
       return {
         verdict: "fail",
         messages: [