@attalabs/vinaya 0.22.0 → 0.23.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/state-machine-model.ts

@@ -0,0 +1,269 @@
+/**
+ * state-machine-model.ts — the canonical, code-owned model of AEG's execution
+ * state machine: what it reads, what it can conclude, and the ordered rules
+ * that get from one to the other. Pure data, zero I/O — the same discipline as
+ * `actions.ts` and `waiver-label.ts` (one pure-data list, read by both
+ * the logic and the rendered docs, so the two can never drift). Its only
+ * non-type import is `label()` from the sibling pure-data label vocabulary
+ * (`@attalabs/aeg-forge-state`'s `labels.ts`), so the label names this model quotes
+ * cannot drift from the ones the mechanism actually matches.
+ *
+ * Three parts, in the order a reader needs them:
+ *
+ *   1. `FORGE_FACT_INPUTS` — every `ForgeFacts` field and the GitHub object it
+ *      is read from. The inputs are the whole source of truth: status is
+ * *derived* from forge objects, never written down. Descriptive
+ *      only — the mapping itself is performed by `map-forge-facts.ts`.
+ *   2. `DERIVED_STATUSES` — the statuses derivation can conclude.
+ *   3. `DERIVATION_RULES` — the ordered rule list, first match wins.
+ *
+ * **Order is load-bearing, not incidental.** `blocked` must win over every
+ * other conclusion; the reopened-after-merge rules must precede the plain
+ * `merged` rule or a reopened Issue would permanently read `merged` off a
+ * stale fact. `deriveStatus` (`derive-tranche.ts`) executes this list
+ * verbatim, so reordering entries here changes real status everywhere — every
+ * gate, the Studio, and the CLI read their status through it.
+ *
+ * **Deliberately not imported here: the label vocabulary.** Derivation works
+ * on `ForgeFacts` — booleans and enums — never on label *strings*; the one
+ * label that matters arrives pre-read as the `blockedLabel` fact. Importing
+ * `@attalabs/aeg-forge-state` for its `LABELS` would also drag that package's
+ * `node:child_process` into any browser bundle rendering this model, the same
+ * hazard `diagram-model.ts` documents for `ACTIONS`. Label names live in
+ * `@attalabs/aeg-forge-state`'s `labels.ts`; this module names them only in prose.
+ */
+
+import { label } from '@attalabs/aeg-forge-state'
+import type { ForgeFacts } from '@attalabs/aeg-types'
+import type { DerivedStatus } from './types'
+
+// ---------- 1. Inputs ----------
+
+export type ForgeFactInput = {
+  /** The `ForgeFacts` field, as the deriver sees it. */
+  fact: keyof ForgeFacts
+  /** The GitHub object and field it is read from, before mapping. */
+  readsFrom: string
+  /** What the fact means to derivation. */
+  meaning: string
+}
+
+/**
+ * One entry per `ForgeFacts` field. `closedAt` / `mergedAt` are carried for
+ * the coherence oracle rather than for status, and are marked as such — they
+ * are inputs to the model's world, but no derivation rule reads them.
+ */
+export const FORGE_FACT_INPUTS: ForgeFactInput[] = [
+  {
+    fact: 'issueState',
+    readsFrom: 'Issue.state (OPEN | CLOSED)',
+    meaning: 'Whether the task Issue is still open — the anchor for the honest terminal statuses.'
+  },
+  {
+    fact: 'assigned',
+    readsFrom: 'Issue.assignees (count > 0)',
+    meaning: 'An assignee exists. No longer affects derivation: assigned and unassigned are both todo.'
+  },
+  {
+    fact: 'branchExists',
+    readsFrom: 'Ref refs/heads/task/<tranche>/<id>',
+    meaning: 'A task branch has been published — the todo → in-flight transition, written by git push, not by hand.'
+  },
+  {
+    fact: 'prState',
+    readsFrom: 'PullRequest.state (OPEN | CLOSED | MERGED)',
+    meaning: 'Whether work is proposed or landed. CLOSED-without-merge collapses to none — AEG models open/merged/none.'
+  },
+  {
+    fact: 'reviewDecision',
+    readsFrom: 'PullRequest.reviewDecision',
+    meaning: "Only 'changes_requested' flips status; approved-but-unmerged stays in-review."
+  },
+  {
+    fact: 'blockedLabel',
+    readsFrom: `Issue.labels contains '${label('blocked')}'`,
+    meaning: 'Execution halted pending an external unblock. Wins over every other rule.'
+  },
+  {
+    fact: 'stateReason',
+    readsFrom: 'Issue.stateReason (COMPLETED | NOT_PLANNED | REOPENED | null)',
+    meaning: 'Separates a legitimate drop from an incoherent close on a closed, never-merged Issue.'
+  },
+  {
+    fact: 'closedAt',
+    readsFrom: 'Issue.closedAt',
+    meaning: 'Timestamp for the coherence oracle grandfather cutoff. No derivation rule reads it.'
+  },
+  {
+    fact: 'mergedAt',
+    readsFrom: 'PullRequest.mergedAt',
+    meaning: 'Timestamp for the coherence oracle grandfather cutoff. No derivation rule reads it.'
+  },
+  {
+    fact: 'closedByActor',
+    readsFrom: 'ClosedEvent.actor.login (most recent timeline CLOSED_EVENT)',
+    meaning:
+      'GitHub login that hand-closed the Issue. No task-status derivation rule reads it — it is consumed by dispatch-gate.ts/coherence-checks.ts A1 to recognize a hand-closed dependency as resolved (task vinaya-engine-v1 21, #99), not by this status model.'
+  }
+]
+
+// ---------- 2. Statuses ----------
+
+/**
+ * Every value `DerivedStatus` admits. `backlog` is a project-level concept and
+ * is never emitted by derivation inside a tranche — tranche tasks
+ * are committed work, so their floor is `todo`. It stays in the set because
+ * the type still admits it and consumers still render it.
+ */
+export const DERIVED_STATUSES: DerivedStatus[] = [
+  'backlog',
+  'todo',
+  'in-flight',
+  'in-review',
+  'changes-requested',
+  'merged',
+  'blocked',
+  'dropped',
+  'incoherent'
+]
+
+/** The statuses derivation can actually conclude — every value except `backlog`. */
+export const DERIVABLE_STATUSES: DerivedStatus[] = DERIVED_STATUSES.filter((s) => s !== 'backlog')
+
+// ---------- 3. Rules ----------
+
+export type DerivationRule = {
+  /** Stable identifier — safe to cite from docs and tests. */
+  id: string
+  /**
+   * Which step of the canonical chain this rule implements. Two steps branch
+   * on a second fact and are expressed as an adjacent pair of rules sharing a
+   * step number, so that every rule stays a flat predicate → status pair
+   * rather than a status-returning function.
+   */
+  chainStep: number
+  /** The condition in prose, for rendered docs. */
+  when: string
+  /** The condition in code. First rule to match decides the status. */
+  matches: (facts: ForgeFacts | undefined) => boolean
+  /** The status this rule concludes. */
+  status: DerivedStatus
+  /** Why the rule sits at this position — the part reordering would destroy. */
+  why: string
+}
+
+/**
+ * The ordered chain. First match wins; the final rule matches unconditionally,
+ * so the list is total and evaluation always concludes.
+ *
+ * Every predicate is written to be safe against `undefined` facts even though
+ * only the first rule can observe that case — the guard is structural, so
+ * adding a rule above the others can never turn into a null dereference.
+ */
+export const DERIVATION_RULES: DerivationRule[] = [
+  {
+    id: 'no-facts',
+    chainStep: 1,
+    when: 'No forge facts for this task',
+    matches: (facts) => !facts,
+    status: 'todo',
+    why: 'A task absent from the forge snapshot is committed work not yet started — never backlog, inside a tranche.'
+  },
+  {
+    id: 'blocked-label',
+    chainStep: 2,
+    when: 'The blocked label is present',
+    matches: (facts) => facts?.blockedLabel === true,
+    status: 'blocked',
+    why: 'Blocked wins over every other conclusion — a halted task must not read as progressing, whatever its branch or PR says.'
+  },
+  {
+    id: 'reopened-after-merge-with-branch',
+    chainStep: 3,
+    when: 'Issue is open, a PR already merged, and a task branch exists',
+    matches: (facts) => facts?.issueState === 'open' && facts.prState === 'merged' && facts.branchExists,
+    status: 'in-flight',
+    why: 'Must precede the plain merged rule: the Issue reopened and new work is already published, so the historical merge is stale.'
+  },
+  {
+    id: 'reopened-after-merge-no-branch',
+    chainStep: 3,
+    when: 'Issue is open and a PR already merged, but no task branch exists',
+    matches: (facts) => facts?.issueState === 'open' && facts.prState === 'merged',
+    status: 'todo',
+    why: 'Same reopen case, work not restarted. Without it a reopened Issue would read merged forever — GitHub never retracts merge history.'
+  },
+  {
+    id: 'pr-merged',
+    chainStep: 4,
+    when: 'A PR for this task is merged',
+    matches: (facts) => facts?.prState === 'merged',
+    status: 'merged',
+    why: 'The terminal success state. Reached only once the reopen exceptions above have declined the facts.'
+  },
+  {
+    id: 'pr-open-changes-requested',
+    chainStep: 5,
+    when: 'A PR is open and review requested changes',
+    matches: (facts) => facts?.prState === 'open' && facts.reviewDecision === 'changes_requested',
+    status: 'changes-requested',
+    why: 'Must precede the plain open-PR rule, which would otherwise swallow it as in-review and hide that the ball is back with the Developer.'
+  },
+  {
+    id: 'pr-open',
+    chainStep: 5,
+    when: 'A PR is open',
+    matches: (facts) => facts?.prState === 'open',
+    status: 'in-review',
+    why: 'Opening the PR is itself the in-flight → in-review transition; no status is ever written to record it.'
+  },
+  {
+    id: 'branch-exists',
+    chainStep: 6,
+    when: 'A task branch exists, with no PR',
+    matches: (facts) => facts?.branchExists === true,
+    status: 'in-flight',
+    why: 'Publishing the branch is the todo → in-flight transition. Below the PR rules, since a PR is the stronger signal.'
+  },
+  {
+    id: 'issue-open',
+    chainStep: 7,
+    when: 'The Issue is open, with no branch and no PR',
+    matches: (facts) => facts?.issueState === 'open',
+    status: 'todo',
+    why: 'Not started. Assigned or not, both are todo inside a tranche.'
+  },
+  {
+    id: 'closed-not-planned',
+    chainStep: 8,
+    when: 'Issue closed NOT_PLANNED, with no merged PR',
+    matches: (facts) => facts?.stateReason === 'not_planned',
+    status: 'dropped',
+    why: 'A legitimately abandoned task. Reached only when the Issue is closed and nothing merged.'
+  },
+  {
+    id: 'closed-without-merge',
+    chainStep: 8,
+    when: 'Issue closed for any other reason, with no merged PR',
+    matches: () => true,
+    status: 'incoherent',
+    why: 'The honest terminal fallback: closed but unprovable must never read as todo. Total by design, so derivation always concludes.'
+  }
+]
+
+/**
+ * Execute the model: the first rule whose predicate matches decides the
+ * status. `deriveStatus` in `derive-tranche.ts` delegates here, so the
+ * rendered rules and the real derivation are the same list — the whole point
+ * of the discipline.
+ *
+ * The trailing return is unreachable by construction (the final rule matches
+ * unconditionally) and exists only to satisfy the type checker;
+ * `state-machine-model.test.ts` asserts that totality directly.
+ */
+export function deriveStatusFromModel(facts: ForgeFacts | undefined): DerivedStatus {
+  for (const rule of DERIVATION_RULES) {
+    if (rule.matches(facts)) return rule.status
+  }
+  return 'incoherent'
+}

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

@@ -0,0 +1,14 @@
+import type { Tranche } from './types'
+
+/**
+ * The seam the pure evaluators (`deriveTranche`, `sumLedger`, ...) consume
+ * state through, instead of a raw `Tranche` tied to one storage shape.
+ * Implementations (forge-backed, file-backed) perform I/O and therefore live
+ * outside `aeg-core` (`apps/vinaya/sources`) — this package only defines the
+ * contract. Async on both adapters, even though the file adapter's own read
+ * is sync-capable, so callers get one uniform type regardless of which
+ * adapter is selected.
+ */
+export type StateSource = {
+  getTranche(slug: string): Promise<Tranche>
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Spec status-block check (C1/F1). Pure — takes file
+ * content as a string, returns findings. No filesystem, no git.
+ */
+
+export function hasStatusBlock(content: string): boolean {
+  return /(^|\n)\s*(\*\*)?Status:?(\*\*)?\s*:?\s*(draft|target|ratified|retired)/i.test(content)
+}

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

@@ -0,0 +1,26 @@
+import type { LedgerRow, LedgerTotals } from './types'
+
+/**
+ * Pure aggregate over ledger rows. The tranche total is derived from the
+ * rows — never stored — so re-entry (a role appending a second row for the
+ * same phase) naturally adds to the total without any "replace existing"
+ * semantics. This is the same philosophy as derived task status and the
+ * append-only ledger: don't store the aggregate, sum the immutable
+ * entries.
+ *
+ * Null cells contribute zero — a claude.ai row the Principal has not yet
+ * filled in does not inflate the total with imaginary tokens. The row
+ * count includes those rows so a UI can still surface "5 entries, 2
+ * pending fill".
+ */
+export function sumLedger(rows: LedgerRow[]): LedgerTotals {
+  let tokensIn = 0
+  let tokensOut = 0
+  let cost = 0
+  for (const r of rows) {
+    if (r.tokensIn != null) tokensIn += r.tokensIn
+    if (r.tokensOut != null) tokensOut += r.tokensOut
+    if (r.cost != null) cost += r.cost
+  }
+  return { tokensIn, tokensOut, cost, rows: rows.length }
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Two files in one package declaring the same symbol name.
+ *
+ * Not a style rule — a verification hazard. `parse-registry.ts` and
+ * `registry-parse.ts` are transpositions of each other, `parse-tranche.ts` is a
+ * third neighbour, and all three declare an unexported `stripBackticks`. So
+ * "the registry's backtick stripper" names nothing a reader can resolve, and
+ * checking a claim about it by grepping returns a confident answer about
+ * whichever copy the search landed on. That happened twice while writing
+ * atta-labs/vinaya#181: once in a verification pass that reached the right
+ * conclusion for the wrong reason, once in a filed Issue that sent a reader to
+ * the wrong file. `parse-registry.ts` was also binary to git at the time (see
+ * `no-binary-sources.test.ts`), so `git grep` could not have shown its copy.
+ *
+ * The lint does not forbid the collision. Plenty are harmless — a `makeTask`
+ * helper in two test files collides with nothing anyone reasons about. It
+ * reports them so a name that cannot be resolved by eye is known to be one.
+ *
+ * Deliberately syntactic. Resolving *references* needs the compiler API and is
+ * a different, larger job; this only reads declarations, so it is fast, has no
+ * dependencies, and cannot silently degrade the way a text search does.
+ */
+export type SymbolDeclaration = { name: string; file: string; exported: boolean }
+export type SymbolCollision = { name: string; files: string[]; anyExported: boolean }
+
+/**
+ * A top-level declaration — no leading whitespace, so nested and block-scoped
+ * declarations are out of scope by construction.
+ *
+ * `const enum` is matched before bare `const`, or `export const enum E` would
+ * capture the keyword `enum` as the symbol name.
+ *
+ * KNOWN BLIND SPOTS, stated rather than papered over — a detector that implies
+ * coverage it does not have is the failure class it was built to catch:
+ *   - a multi-declarator statement (`const a = 1, b = 2`) reports only the
+ *     first name;
+ *   - column-0 text inside a template literal or a block comment is read as
+ *     code, so either can produce a false hit;
+ *   - `export { x } from './y'` re-exports are not declarations and are not
+ *     reported — correct for this purpose, but it means this does not measure
+ *     a module's export surface.
+ * Closing these needs a real parse, which is the compiler API and a far larger
+ * job than this file.
+ */
+const DECLARATION =
+  /^(export\s+)?(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:function\s*\*?|class|interface|type|const\s+enum|enum|const|let|var)\s+([A-Za-z_$][\w$]*)/gm
+
+export function declarationsIn(file: string, source: string): SymbolDeclaration[] {
+  const out: SymbolDeclaration[] = []
+  DECLARATION.lastIndex = 0
+  let m: RegExpExecArray | null = DECLARATION.exec(source)
+  while (m !== null) {
+    out.push({ name: m[2] as string, file, exported: m[1] !== undefined })
+    m = DECLARATION.exec(source)
+  }
+  return out
+}
+
+/**
+ * Names declared in more than one file. `files` is sorted so the report is
+ * stable across filesystem ordering — a lint that reorders between runs
+ * produces diff noise and gets ignored, which is how a lint stops working.
+ */
+export function findCollisions(decls: SymbolDeclaration[]): SymbolCollision[] {
+  const byName = new Map<string, SymbolDeclaration[]>()
+  for (const d of decls) {
+    const list = byName.get(d.name) ?? []
+    list.push(d)
+    byName.set(d.name, list)
+  }
+  const out: SymbolCollision[] = []
+  for (const [name, list] of byName) {
+    const files = [...new Set(list.map((d) => d.file))].sort()
+    if (files.length < 2) continue
+    out.push({ name, files, anyExported: list.some((d) => d.exported) })
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name))
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Test Plan checkbox-state gate evaluator (aeg-governance-hardening
+ * task 25, #365). 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.
+ *
+ * See `locateTestPlanSection` for section-boundary detection (both the
+ * inline `**Test Plan:**` marker and the `## N. Test Plan` heading form).
+ * This module owns the checkbox tick-state decision built on top of it:
+ *
+ * - No section found, task branch → `fail` (a task PR without a
+ *     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`.
+ */
+
+import { locateTestPlanSection } from './test-plan-section'
+
+export type TestPlanGateVerdict = 'pass' | 'fail'
+export type TestPlanGateResult = { verdict: TestPlanGateVerdict; messages: string[] }
+
+const TASK_BRANCH_PATTERN = /^task\/[^/]+\/[^/]+$/
+
+export function evaluateTestPlanGate(body: string, branch: string): TestPlanGateResult {
+  if (!body) {
+    return {
+      verdict: 'pass',
+      messages: [
+        'PR_BODY env var is empty; nothing to check.',
+        'PASS (no body — likely a local invocation; CI sets PR_BODY automatically).'
+      ]
+    }
+  }
+
+  const located = locateTestPlanSection(body)
+
+  if (!located.found) {
+    if (TASK_BRANCH_PATTERN.test(branch)) {
+      return {
+        verdict: 'fail',
+        messages: [
+          `FAIL — no Test Plan section found in the PR body for task branch \`${branch}\`.`,
+          'Searched for a `## Test Plan` / `## N. Test Plan` heading and an inline `**Test Plan:**`/`Test Plan:` marker — neither was found.',
+          'Per, a task PR without a Test Plan is malformed, not exempt — add one (or `Test Plan: unit-tests-only` for a pure-logic brief with no runtime surface).'
+        ]
+      }
+    }
+    return {
+      verdict: 'pass',
+      messages: [
+        'No Test Plan section in PR body.',
+        'PASS (advisory) — see aeg-root/roles/developer.md (Verification) and aeg-root/skills/brief-authoring/SKILL.md §9.',
+        'Non-task branch (or BRANCH unset) — a brief that touches a runtime surface and has no Test Plan is malformed on a task branch; Brief Validation catches that case pre-dispatch.'
+      ]
+    }
+  }
+
+  const section = located.section
+
+  if (/unit-tests-only/i.test(section)) {
+    return {
+      verdict: 'pass',
+      messages: ['Test Plan: unit-tests-only — pure-logic brief, CI unit-tests are the proof.', 'PASS.']
+    }
+  }
+
+  const checkboxLines = section
+    .split('\n')
+    .map((line) => line.trimStart())
+    .filter((line) => /^[-*]\s+\[[ xX]\]/.test(line))
+
+  if (checkboxLines.length === 0) {
+    return {
+      verdict: 'pass',
+      messages: [
+        'Test Plan section found but has no checkbox items.',
+        "PASS (advisory) — the section may be empty or expressed in prose; verification is the Principal's call."
+      ]
+    }
+  }
+
+  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.`]
+
+  if (unchecked.length > 0) {
+    messages.push('', 'FAIL — the following 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.',
+      '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.')
+  return { verdict: 'pass', messages }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/test-plan-section.ts

@@ -0,0 +1,65 @@
+/**
+ * Test Plan section locator (aeg-governance-hardening task 25, #365). Pure —
+ * no `fs`, no `gh`/`git`. Extracted from `bin/verify-test-plan.ts`'s original
+ * inline-only regex to fix the live-fire gap PR #377 exposed: its body used
+ * the `## 9. Test Plan` heading form, which the old inline-only regex never
+ * matched, so `verify-test-plan` reported "no section" and advisory-PASSED a
+ * PR that actually had an unticked `**[principal]**` box.
+ *
+ * Recognizes BOTH forms `roles/developer.md`'s canonical PR-body template and
+ * real brief numbering produce:
+ *   - Heading form:  `## Test Plan`, `## 9. Test Plan`, `### 9a. Test Plan`
+ *   - Inline form:   `**Test Plan:**`, `Test Plan:` (optionally followed on
+ *                     the same line by the `unit-tests-only` sentinel)
+ *
+ * NOT unified with `brief-validation.ts`'s `checkTestPlan`/
+ * `checkTestPlanExclusivity` (the closest analogs to the brief's named
+ * `checkPlanShape`, which does not exist under that name in this codebase):
+ * those are whole-body presence checks (a Test Plan section is not
+ * even located — they match `**[agent]**`/`**[principal]**` tags or the
+ * `unit-tests-only` sentinel anywhere in the PR body), used pre-dispatch to
+ * validate brief shape. This module locates section BOUNDARIES to check
+ * checkbox tick-state at PR-open/push time — a different property. Unifying
+ * would force `checkTestPlan` to become section-scoped, changing its
+ * already-shipped pass/fail behavior — see this task's PR body for the
+ * decision record.
+ */
+
+import { anchoredRegion } from './anchored-region'
+
+export type TestPlanSection = { found: true; section: string } | { found: false }
+
+const HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im
+const INLINE_FORM_RE = /^[ \t]*\*{0,2}Test Plan:?\*{0,2}/im
+const NEXT_SECTION_RE = /\n(?:#{1,3}[ \t]|\*\*[A-Z][^*\n]*:\*\*)/
+
+/**
+ * Locates the Test Plan section (heading form preferred, falling back to the
+ * inline marker form) and slices it out up to — but not including — the next
+ * heading or `**Field:**`-style section boundary. Returns `{ found: false }`
+ * when neither form is present anywhere in the body.
+ *
+ * When the body carries an `AEG:TEST-PLAN` anchor pair (`anchored-region.ts`,
+ * task 30), the pair IS the section: its whole content is returned verbatim,
+ * with no heading/inline marker required inside it — requiring a second,
+ * redundant in-region marker would reintroduce the unrecognized-heading
+ * failure class (#377) the anchors exist to close. Identical-looking Test
+ * Plan text elsewhere in the body (a pasted reference brief's own §9, the
+ * PR #392 shape) is ignored. Bodies without the pair parse exactly as before.
+ */
+export function locateTestPlanSection(body: string): TestPlanSection {
+  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('\n')
+  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) }
+}