@attalabs/vinaya 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attalabs/vinaya",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Vinaya — Agentic Engineering Harness. Deterministic checks every AI coding agent must satisfy before merge.",
   "type": "module",
   "license": "Apache-2.0",

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

@@ -0,0 +1,173 @@
+/**
+ * actions.ts — the canonical, aeg-core-owned enumeration of every AEG action
+ * that either crosses into GitHub or hands work across a role-seam contract.
+ * Pure data, zero I/O, zero imports beyond the type itself — same discipline
+ * as `waiver-label.ts`.
+ *
+ * Two consumers read this one list (Issue #505): G3's "no seventh way into
+ * GitHub" completeness story (`registry-checks.ts`) targets the
+ * `crosses: 'into-github'` subset against `enforcement.md`'s Ring-0 gate rows;
+ * task 506's DiagramModel places each action both inside a ring-0 gate (as a
+ * guarded crossing) and on the edge between role/contract nodes (as a seam
+ * hand-off). One list, so an `ACTIONS.length`-driven diagram edge count and
+ * G3's crossing list can never drift apart.
+ *
+ * The set is 11 distinct actions: the 6 crossings named in Issue #505 plus 5
+ * seam-only actions (4 original, plus `create-the-milestone`,
+ * vinaya-milestone-model-v1 task 2). Two of the six contract seams are already
+ * accomplished by a GitHub crossing (the Planner→Brief seam's carrier is the
+ * Issue body, created by `create-a-task-issue`; the Developer→Reviewer seam's
+ * carrier is the PR, created by `open-a-pull-request`), so they get no
+ * duplicate id — inventing one would give two ids for one real act and break
+ * any `ACTIONS.length`-driven edge count.
+ *
+ * `crosses` is factually per-action, not a mirror of Issue #505's prose:
+ * `commit-the-work` is `'none'` because `git commit` never leaves the local
+ * machine — it is `git push` (`publish-the-branch`) that reaches the
+ * GitHub-hosted remote. `enforcement.md`'s own Ring-0 table lists them as
+ * separate rows (`.husky/pre-commit` vs `.husky/pre-push`) for exactly this
+ * reason..
+ *
+ * The only valid `performedBy` values are the 9 `role_id`s under
+ * `aeg-root/roles/*.md` (task 2, #522) — asserted by the real-file test.
+ */
+
+export type ActionCrossing = 'into-github' | 'none'
+
+export type Action = {
+  id: string
+  label: string
+  crosses: ActionCrossing
+  performedBy: string[] // role_id[]
+  /** The rhetorical question — what a reader recognises. */
+  summary: string
+  /** What the action actually is, plainly. The counterpart to `summary`:
+   * the question earns attention, this answers it. Required, so a new action
+   * cannot be added without one — the same bar `roles/*.md` and
+   * `contracts/*.md` hold via their `description:` frontmatter. */
+  description: string
+}
+
+export const ACTIONS: Action[] = [
+  {
+    id: 'publish-the-branch',
+    label: 'publish the branch',
+    crosses: 'into-github',
+    performedBy: ['developer'],
+    summary: 'Ever had a branch pushed straight to main by mistake?',
+    description: 'Pushing local commits up to GitHub, where the rest of the mechanism can finally see them.'
+  },
+  {
+    id: 'create-a-task-issue',
+    label: 'create a task issue',
+    crosses: 'into-github',
+    performedBy: ['planner'],
+    summary: 'Ever opened a ticket that turned out to have zero plan behind it?',
+    description:
+      'Opening the Issue that a task exists as — its scope, its reasoning and its dependencies, written down before anyone starts.'
+  },
+  {
+    id: 'open-a-pull-request',
+    label: 'open a pull request',
+    crosses: 'into-github',
+    performedBy: ['developer'],
+    summary: 'Ever gotten a PR with no explanation of what it does or why?',
+    description:
+      'Proposing finished work for review, carrying the account of what changed and which intent it came from.'
+  },
+  {
+    id: 'revise-a-pull-request',
+    label: 'revise a pull request',
+    crosses: 'into-github',
+    performedBy: ['developer', 'planner'],
+    summary: 'Ever seen a PR quietly gutted after it already passed review?',
+    description:
+      'Editing a pull request after it exists — its code, its title or its description, whether or not review already happened.'
+  },
+  {
+    id: 'grant-a-waiver',
+    label: 'grant a waiver',
+    crosses: 'into-github',
+    performedBy: ['principal'],
+    summary: 'Ever had someone bypass a rule just by typing the right words?',
+    description:
+      'Deliberately excusing a rule for one case — an authority the mechanism grants to a person, never to an agent.'
+  },
+  {
+    id: 'commit-the-work',
+    label: 'commit the work',
+    crosses: 'none',
+    performedBy: ['developer'],
+    summary: "Ever had a commit land that plain doesn't build?",
+    description: 'Recording a change locally — the last moment it costs nothing to catch a mistake.'
+  },
+  {
+    id: 'author-the-brief',
+    label: 'author the brief',
+    crosses: 'none',
+    performedBy: ['brief-author'],
+    summary: 'Ever started a task with no clear idea of what "done" means?',
+    description:
+      'Turning one intent into instructions someone can execute: what to build, what is out of scope, and what done means.'
+  },
+  {
+    id: 'produce-the-verdict',
+    label: 'produce the verdict',
+    crosses: 'none',
+    performedBy: ['reviewer', 'security'],
+    summary: 'Ever gotten a review that was really just a rubber stamp?',
+    description: 'Judging finished work against the brief it came from, and saying plainly whether it passes.'
+  },
+  {
+    id: 'post-provenance-comment',
+    label: 'post the provenance comment',
+    crosses: 'none',
+    performedBy: ['archivist'],
+    summary: 'Ever needed to know exactly what shipped, and why, six months later?',
+    description: 'Writing the permanent record of a merged task — what shipped, from what intent, checked by whom.'
+  },
+  {
+    id: 'write-the-retrospective',
+    label: 'write the retrospective',
+    crosses: 'none',
+    performedBy: ['tranche-archivist'],
+    summary: 'Ever finished a big chunk of work with nobody writing down what was learned?',
+    description: 'Closing out a finished phase of work by recording what actually happened and what it taught.'
+  },
+  {
+    id: 'create-the-milestone',
+    label: 'create the milestone',
+    // Not into-github: `crosses` marks the specific Ring-0 local-git-hook
+    // crossing class G3 polices (raw `gh issue create`/`gh pr create`/`git
+    // push` bypass), not "touches the GitHub API" generally — the same
+    // reason `post-provenance-comment`/`produce-the-verdict` are 'none'
+    // despite writing PR comments via the API. `vinaya milestone create`
+    // is a manually-invoked CLI command with no Ring-0 hook intercepting a
+    // raw bypass, so it stays seam-only here (vinaya-milestone-model-v1
+    // task 2).
+    crosses: 'none',
+    performedBy: ['architect'],
+    summary: 'Ever had a Milestone whose title quietly became the only place a version lived?',
+    description:
+      "Declaring a product goal as a Milestone — free-text title, prose goal, an optional Release: field as the version's sole authority, and an optional list of which tranches serve it."
+  }
+]
+
+// A stable keyword per into-github action that must appear (case-insensitive)
+// in some real Ring-0 gate row's action text — the "feeds G3" tripwire from
+// Issue #505. If enforcement.md ever drops the gate row backing a crossing,
+// the corresponding assertion fails. grant-a-waiver's keyword is
+// `pull request`: granting a waiver is an act on a pull request (labeling it),
+// honored at the Ring-0 PR-creation/editing gate and refused-from-agents at
+// the raw-API gate — both reference pull requests. See PR body.
+//
+// Consumed by both `actions.test.ts` (the crossing tripwire) and
+// `diagram-model.ts` (the `guards` gate→action edges), so the one keyword map
+// can never drift between them (same no-drift principle as ACTIONS).
+export const CROSSING_KEYWORDS: Record<string, string> = {
+  'publish-the-branch': 'git push',
+  'create-a-task-issue': 'task issue',
+  'open-a-pull-request': 'pull request',
+  'revise-a-pull-request': 'pull request',
+  'grant-a-waiver': 'pull request'
+}

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

@@ -0,0 +1,118 @@
+/**
+ * AEG anchored-region grammar (aeg-governance-hardening task 30, #393). Pure —
+ * no `fs`, no `gh`/`git`.
+ *
+ * One anchor syntax for every gate-read field: an HTML comment pair
+ * `<!-- AEG:<FIELD>:START -->` … `<!-- AEG:<FIELD>:END -->` delimiting the
+ * field's one canonical home inside a PR/Issue body. HTML comments render
+ * invisibly on the forge, survive inside `<details>` blocks, and can never be
+ * produced accidentally by freeform prose — which is exactly the failure class
+ * this closes (PR #392's pasted reference brief duplicated its own Test Plan
+ * inside the PR body; #363/#377 were the same shape as real bugs).
+ *
+ * Recognition semantics, shared by every consumer
+ * (`pr-tier.ts`, `test-plan-section.ts`, `premise-check.ts`,
+ * `brief-validation.ts`/`archive-task.ts`'s Project read, and the `Closes #N`
+ * reads in `coherence-checks.ts`/`archive-task.ts`):
+ *
+ *   - **Anchors are additive, never required.** A body with no anchor pair for
+ *     a field parses byte-identically to the pre-anchor behavior — every
+ *     already-merged PR/Issue keeps reading exactly as today.
+ *   - **When a pair is present, it is authoritative.** The consumer reads the
+ *     field exclusively from inside the pair and ignores identical-looking
+ *     text anywhere else in the body — there is deliberately no fallback to
+ *     body-wide search, since falling back would resurrect the decoy problem
+ *     the anchor exists to solve.
+ *   - **First pair wins** when a field is (incorrectly) anchored twice —
+ *     mirroring the first-match-wins philosophy of the existing prose parsers.
+ *   - **A `START` with no following `END` is treated as no anchor at all**
+ *     (prose fallback) — a malformed half-pair must not be able to hide a
+ *     field from the gates.
+ *   - **Markers inside fenced code blocks or inline code spans do not count**
+ *     — example/quoted anchor syntax in documentation or evidence output is
+ *     never mistaken for a real anchor (same code-stripping philosophy as
+ *     `archive-task.ts`'s `stripCode`, #311 regression).
+ *
+ * The field line/block goes on its own line(s) INSIDE the pair — e.g.
+ *
+ *     <!-- AEG:TIER:START -->
+ *     **Tier:** 1
+ *     <!-- AEG:TIER:END -->
+ *
+ * Deliberately minimal: seven field names, one shape. This is a delimiting
+ * convention, not a metadata DSL; resist adding structure to it.
+ *
+ * `EVIDENCE` (fix/pr-report-emitter) differs from the other six in one way:
+ * it is never hand-typed. `vinaya pr report --write` is the only writer, and
+ * `check-evidence-fresh` is the only reader — no prose-fallback recognition
+ * exists or is planned for this field, unlike the anchor-optional grammar
+ * described above for the other five.
+ */
+
+import { maskCode } from '@attalabs/aeg-forge-state/strip-code'
+
+/**
+ * The seven gate-read fields with an anchored home. `TOKENS` (task 5, #378)
+ * joined here rather than through a second, parallel field list —
+ * `pr-report.ts`'s own `AEG:TOKENS:START`/`:END` markers already use this
+ * exact grammar, so the registry is the fix, not a workaround beside it.
+ */
+export const ANCHOR_FIELDS = ['CLOSES', 'PROJECT', 'TIER', 'PREMISE', 'TEST-PLAN', 'EVIDENCE', 'TOKENS'] as const
+
+export type AnchorField = (typeof ANCHOR_FIELDS)[number]
+
+/**
+ * The code-recognition grammar — `stripCode`, `maskCode` and their fence /
+ * indented-block / inline-span scanners — moved down to
+ * `@attalabs/aeg-forge-state` (`strip-code.ts`) so `projectFieldFromBody` can
+ * read a body "minus its examples" through the SAME implementation rather than
+ * a second copy of it. `aeg-core` already depends on `aeg-forge-state`, so the
+ * grammar could only be shared by moving it down; importing upward would close
+ * a cycle. It is re-exported here because `anchored-region` remains this
+ * package's documented home for body-parsing primitives and every existing
+ * `import { stripCode } from './anchored-region'` call site is unchanged.
+ */
+export { stripCode } from '@attalabs/aeg-forge-state'
+export type { StripCodeOptions } from '@attalabs/aeg-forge-state'
+
+/**
+ * The START/END markers' positions in `body`, found the same code-blind way
+ * `anchoredRegion` finds its content — `null` under the identical conditions
+ * `anchoredRegion` returns `null`. `outerStart`/`outerEnd` span the markers
+ * themselves; `innerStart`/`innerEnd` span the content between them (what
+ * `anchoredRegion` returns as a string).
+ *
+ * Exists so a WRITER (`vinaya pr report --write`'s `replaceEvidenceBlock`)
+ * can target the same real, non-fenced pair a reader would — a naive
+ * `body.indexOf(START)` finds whichever copy comes first in raw text, fenced
+ * decoy included, and a body that quotes a worked example of its own anchor
+ * (exactly what this task's own PR body does, in its Test Plan evidence)
+ * would get ITS OWN replacement written into the quoted example instead of
+ * the real field. One masked search, shared by the reader and the writer,
+ * closes that by construction rather than by convention.
+ */
+export function anchoredRegionBounds(
+  body: string,
+  field: AnchorField
+): { outerStart: number; outerEnd: number; innerStart: number; innerEnd: number } | null {
+  const masked = maskCode(body)
+  const start = new RegExp(`<!--\\s*AEG:${field}:START\\s*-->`).exec(masked)
+  if (!start) return null
+  const innerStart = start.index + start[0].length
+  const end = new RegExp(`<!--\\s*AEG:${field}:END\\s*-->`).exec(masked.slice(innerStart))
+  if (!end) return null
+  const innerEnd = innerStart + end.index
+  return { outerStart: start.index, outerEnd: innerEnd + end[0].length, innerStart, innerEnd }
+}
+
+/**
+ * The text between the first `<!-- AEG:<field>:START -->` and the first
+ * `<!-- AEG:<field>:END -->` after it, or `null` when the body carries no
+ * (well-formed, non-code) pair for this field. `null` is the signal for
+ * consumers to run their unchanged prose/heading recognition.
+ */
+export function anchoredRegion(body: string, field: AnchorField): string | null {
+  const bounds = anchoredRegionBounds(body, field)
+  if (!bounds) return null
+  return body.slice(bounds.innerStart, bounds.innerEnd)
+}

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

@@ -0,0 +1,206 @@
+/**
+ * Post-merge Archivist provenance assembly (aeg-governance-hardening
+ * task 5d, #309). Pure — no `fs`, no `fetch`, no `process.env`. The CLI shim
+ * (`bin/archive-task.ts`) resolves the merged PR via `gh`, gathers
+ * `MergedPrFacts`, and calls these functions.
+ *
+ * The cardinal constraint (`aeg-root/roles/archivist.md`): ASSEMBLE, never
+ * author. Every provenance field is copied from a fact the merge already
+ * froze — the PR body, PR metadata, or PR comments. A field whose source
+ * fact is absent becomes a DANGLING entry, never an inferred or defaulted
+ * value. Field/heading shapes below mirror the live provenance comments
+ * posted by hand on PRs #302/#305/#306.
+ */
+
+import { hasLabel } from '@attalabs/aeg-forge-state'
+import { type AnchorField, anchoredRegion, stripCode } from './anchored-region'
+import { headerRegion } from './brief-validation'
+import { readTierFromPrBody } from './pr-tier'
+import { extractCodeReviewVerdict, extractSecurityReviewVerdict } from './verdict-extraction'
+
+export type MergedPrFacts = {
+  number: number
+  headRefName: string
+  body: string
+  mergedAt: string
+  mergeSha: string
+  comments: string[]
+}
+
+const TASK_BRANCH_PATTERN = /^task\/([^/]+)\/([^/]+)$/
+
+/**
+ * null when headRefName is not task/<tranche>/<taskId>.
+ *
+ * This is ONE of two independent eligibility signals for provenance —
+ * the branch-name pattern — not the only one. A PR that closes a
+ * tranche-labeled Issue from a non-`task/*` branch (e.g. a small ad-hoc
+ * `fix/*` cleanup that finally attaches `Closes #N` to a task whose real
+ * work already shipped elsewhere) is EQUALLY eligible: the CLI shim
+ * (`bin/archive-task.ts`) additionally checks the closed Issue's own
+ * `vinaya/tranche:*` label via `gh issue view --json labels` and proceeds if
+ * either signal is present. `buildProvenanceBlock` already tolerates a
+ * `null` ref (falls back to a branch-name task label), so this function's
+ * only remaining job is the branch-name half of that OR — it is no longer
+ * the sole gate. (Confirmed gap: a task whose Issue carried a
+ * `vinaya/tranche:*` label was closed by a `fix/*`-branch PR;
+ * branch-name-only detection silently skipped provenance forever.)
+ */
+export function taskRefFromBranch(branch: string): { tranche: string; taskId: string } | null {
+  const m = branch.match(TASK_BRANCH_PATTERN)
+  if (!m) return null
+  return { tranche: m[1] as string, taskId: m[2] as string }
+}
+
+/**
+ * The eligibility decision itself, pulled out as a pure function so it's
+ * testable without mocking `gh` — the CLI shim (`bin/archive-task.ts`) does
+ * only the I/O (resolve `ref`, fetch the closed Issue's labels) and hands
+ * both facts here. True when EITHER signal holds: a real task-branch `ref`,
+ * or the closed Issue's own labels carry an `vinaya/tranche:*` tag.
+ */
+export function isEligibleForProvenance(
+  ref: { tranche: string; taskId: string } | null,
+  issueLabels: string[]
+): boolean {
+  if (ref !== null) return true
+  return hasLabel('tranche', issueLabels)
+}
+
+const PROVENANCE_HEADING = '### AEG provenance'
+
+/** true when any comment already carries the provenance heading (idempotency, scoped to this PR). */
+export function hasProvenance(comments: string[]): boolean {
+  return comments.some((c) => c.includes(PROVENANCE_HEADING))
+}
+
+/**
+ * Tolerant field reader: accepts `Field:` and `**Field:**`, line-anchored,
+ * searched ONLY in the header region (shared with `brief-validation.ts`'s
+ * gate — gate and archivist read the same region, so a body that passes the
+ * gate can't produce a DANGLING field here). Whole-body scanning is the
+ * regression from #311's first live run, where a prose sentence *about* the
+ * `Ticket:` field in a later section was extracted as the field's value.
+ *
+ * When `anchor` is given and the body carries that anchor pair
+ * (`anchored-region.ts`, task 30), the pair replaces the header region as the
+ * one place the field is read from — same recognition the gate side
+ * (`checkProjectField`) uses, preserving gate/archivist parity.
+ */
+function extractField(body: string, labelPattern: string, anchor?: AnchorField): string | null {
+  const anchored = anchor !== undefined ? anchoredRegion(body, anchor) : null
+  const region = anchored ?? headerRegion(body)
+  const re = new RegExp(`^(?:\\*\\*)?\\s*${labelPattern}\\s*(?:\\*\\*)?\\s*:\\s*(?:\\*\\*)?\\s*([^\\n·]+)`, 'im')
+  const m = region.match(re)
+  if (!m) return null
+  const value = (m[1] as string).trim()
+  return value.length > 0 ? value : null
+}
+
+function closesRefs(text: string): number[] {
+  return [...new Set([...text.matchAll(/Closes #(\d+)/gi)].map((m) => Number(m[1] as string)))]
+}
+
+/**
+ * Primary Issue = first `Closes #N` in the header block (canonical placement),
+ * falling back to the first anywhere in the body (flagged, not lost). Extras
+ * are scanned body-wide so a real second closing reference in prose is still
+ * flagged — but always fence-stripped, so example text like a Test Plan's
+ * `Closes #123` fixture never counts (#311 regression).
+ *
+ * When the body carries an `AEG:CLOSES` anchor pair (`anchored-region.ts`,
+ * task 30), the pair replaces the header block as the canonical placement:
+ * the primary Issue is the first `Closes #N` inside the pair (never flagged
+ * `outsideHeader` — anchored IS canonical), and extras are still scanned
+ * body-wide so stray closing references stay flagged. Bodies without the
+ * pair parse exactly as before.
+ */
+export function extractIssue(body: string): { issue: number | null; extraIssues: number[]; outsideHeader: boolean } {
+  // Strip ONCE over the whole body, then slice — never strip a slice. The
+  // strip's block rules read context a fragment no longer carries: an anchor
+  // indented inside a list item is list content in the full body (kept, and
+  // GitHub *does* auto-close it) but looks like a bare 4-space indented code
+  // block once sliced, so stripping the region blanked the reference and
+  // returned `issue: null` — the Issue then goes unclosed on merge, the exact
+  // stranding this PR exists to eliminate, reintroduced along the over-strip
+  // axis (PR #617 review MAJOR). Stripping first also subsumes the decoy
+  // protection rather than trading against it: `AEG:*` markers are HTML
+  // comments and survive the strip, while a decoy anchor inside code does not
+  // survive to be sliced in the first place.
+  const stripped = stripCode(body)
+  const bodyNums = closesRefs(stripped)
+  const anchored = anchoredRegion(stripped, 'CLOSES')
+  if (anchored !== null) {
+    const anchorNums = closesRefs(anchored)
+    if (anchorNums.length === 0) return { issue: null, extraIssues: bodyNums, outsideHeader: false }
+    const issue = anchorNums[0] as number
+    return { issue, extraIssues: bodyNums.filter((n) => n !== issue), outsideHeader: false }
+  }
+  const headerNums = closesRefs(headerRegion(stripped))
+  if (bodyNums.length === 0) return { issue: null, extraIssues: [], outsideHeader: false }
+  const issue = headerNums.length > 0 ? (headerNums[0] as number) : (bodyNums[0] as number)
+  return { issue, extraIssues: bodyNums.filter((n) => n !== issue), outsideHeader: headerNums.length === 0 }
+}
+
+/** Assemble the block purely from frozen facts; absent facts become DANGLING entries. */
+export function buildProvenanceBlock(facts: MergedPrFacts): {
+  block: string
+  issue: number | null
+  dangling: string[]
+} {
+  const ref = taskRefFromBranch(facts.headRefName)
+  const dangling: string[] = []
+
+  const { issue, extraIssues, outsideHeader } = extractIssue(facts.body)
+  if (issue === null) {
+    dangling.push('no `Closes #N` found in PR body — Issue field is DANGLING, no Issue will be closed')
+  }
+  if (outsideHeader) {
+    dangling.push(
+      `\`Closes #${issue}\` was found outside the PR body's header block — the canonical form places it before the first \`##\` heading`
+    )
+  }
+  if (extraIssues.length > 0) {
+    dangling.push(
+      `PR body references additional Issues (${extraIssues.map((n) => `#${n}`).join(', ')}) beyond the first — closing only #${issue}, the rest are flagged, not closed`
+    )
+  }
+
+  const tier = readTierFromPrBody(facts.body)
+  if (tier === null) dangling.push('no `Tier:` field found in PR body — Tier field is DANGLING')
+
+  const project = extractField(facts.body, 'Project(?:\\(s\\))?', 'PROJECT')
+  if (!project) dangling.push('no `Project:` field found in PR body — Project(s) field is DANGLING')
+
+  const forField = extractField(facts.body, 'For')
+  if (!forField) dangling.push('no `For:` field found in PR body — Model/agent field is DANGLING')
+
+  const codeReview = extractCodeReviewVerdict(facts.comments)
+  if (codeReview.danglingNote) dangling.push(codeReview.danglingNote)
+
+  const security = extractSecurityReviewVerdict(facts.comments)
+  if (security.danglingNote) dangling.push(security.danglingNote)
+
+  const ticket = extractField(facts.body, 'Ticket') ?? 'none'
+
+  const taskLabel = ref ? `task ${ref.taskId} (tranche ${ref.tranche})` : `task (branch ${facts.headRefName})`
+
+  const lines = [
+    `${PROVENANCE_HEADING} — ${taskLabel}`,
+    `- Issue:        ${issue !== null ? `#${issue}  (closed by merge)` : 'DANGLING — no Closes #N in PR body'}`,
+    `- Tier:         ${tier !== null ? tier : 'DANGLING — no Tier field in PR body'}`,
+    '- Brief:        in this PR body (the frozen intent)',
+    `- Project(s):   ${project ?? 'DANGLING — no Project field in PR body'}`,
+    `- Model/agent:  ${forField ?? 'DANGLING — no For field in PR body'}`,
+    `- Code review:  ${codeReview.value}`,
+    `- Security:     ${security.value}`,
+    `- Ticket:       ${ticket}`,
+    `- Merged:       ${facts.mergeSha} at ${facts.mergedAt}`
+  ]
+
+  if (dangling.length > 0) {
+    lines.push('', `DANGLING: ${dangling.join('; ')}`)
+  }
+
+  return { block: lines.join('\n'), issue, dangling }
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Finding-count baseline capture + comparison (aeg-governance-hardening task
+ * 11, #324). Pure — does not run `verify-docs.ts`/`verify-coherence.ts`
+ * itself and never calls `Date.now()` (a pure `src/` module cannot — see
+ * `packages/aeg-core/CLAUDE.md`-equivalent constraint, this repo's is the
+ * Workflow-script rule of the same shape). The CLI shim runs those tools,
+ * counts their findings, and passes the counts plus a caller-supplied
+ * timestamp in here.
+ *
+ * Exists to make the dispatch-readiness bar honestly "no new findings versus
+ * the captured baseline" rather than "zero findings" — live-fire #2
+ * (aeg-governance-hardening's own dispatch wave) asserted "verify-docs full
+ * mode must be green" as a pre-flight precondition without ever running it;
+ * full mode had 44 pre-existing, unrelated findings and was never green.
+ * Baseline data is capture-at-run only, never a committed file.
+ */
+
+export type BaselineEntry = {
+  tool: string
+  findingCount: number
+  /** ISO timestamp supplied by the caller — never generated inside this module. */
+  capturedAt: string
+}
+
+/** Stamps a set of tool→findingCount pairs into baseline records, using the caller-supplied `capturedAt`. */
+export function captureBaseline(
+  counts: Array<{ tool: string; findingCount: number }>,
+  capturedAt: string
+): BaselineEntry[] {
+  return counts.map((c) => ({ tool: c.tool, findingCount: c.findingCount, capturedAt }))
+}
+
+export type BaselineToolComparison = { tool: string; baseline: number; current: number; delta: number }
+
+export type BaselineComparison = {
+  /** True iff no tool's current finding count exceeds its baseline. */
+  withinBudget: boolean
+  /** Sum of every tool's delta (positive = net new findings across all tools). */
+  delta: number
+  perTool: BaselineToolComparison[]
+}
+
+/**
+ * Compare current finding counts against a captured baseline, per tool.
+ * A tool absent from the baseline (never captured before) has nothing to
+ * regress against — its delta reports as `0` and its current count becomes
+ * the effective baseline going forward, rather than failing budget purely
+ * because no prior baseline was ever recorded for it.
+ */
+export function compareToBaseline(
+  current: Array<{ tool: string; findingCount: number }>,
+  baseline: BaselineEntry[]
+): BaselineComparison {
+  const perTool: BaselineToolComparison[] = current.map((c) => {
+    const baselineEntry = baseline.find((b) => b.tool === c.tool)
+    const baselineCount = baselineEntry ? baselineEntry.findingCount : c.findingCount
+    return { tool: c.tool, baseline: baselineCount, current: c.findingCount, delta: c.findingCount - baselineCount }
+  })
+
+  return {
+    withinBudget: perTool.every((t) => t.delta <= 0),
+    delta: perTool.reduce((sum, t) => sum + t.delta, 0),
+    perTool
+  }
+}