@attalabs/vinaya 0.22.0 → 0.24.0

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

@@ -0,0 +1,183 @@
+import { readMarkdownTable } from './parse-registry'
+import type { Tranche, Lifecycle, Task } from './types'
+
+/**
+ * Parse `aeg-root/tranches/<name>.md` into a typed `Tranche`.
+ *
+ * Captures:
+ *   - the tranche's name (from `# Tranche: <name> — <timeframe>`; the
+ *     superseded `# Iteration:` spelling is still read, see `parseName`)
+ *   - the lifecycle marker (`Lifecycle: active|complete`, defaulting to
+ *     `'active'` when absent — pre-§11 files have no marker)
+ *   - the first goal paragraph
+ *   - the `## Tasks (topology)` table rows
+ *   - per-task rationale blocks (raw markdown, captured verbatim)
+ *   - an optional `## Backlog` section as bullets
+ *
+ * Real tranche files include narrative references to dropped task ids in
+ * prose (e.g. a "Task 3a — removed" note). The parser ignores those — only
+ * rows present in the topology table become tasks.
+ */
+export function parseTranche(md: string): Tranche {
+  return {
+    name: parseName(md),
+    lifecycle: parseLifecycle(md),
+    goal: parseGoal(md),
+    tasks: parseTasks(md),
+    backlog: parseBacklog(md)
+  }
+}
+
+function parseName(md: string): string {
+  // The H1 is `# Tranche: <slug> — <timeframe>`. The slug may contain
+  // hyphens (e.g. `some-tranche-name`, `another-v1`), so capture the first
+  // non-whitespace run — the space before the em-dash is the delimiter.
+  //
+  // `Iteration:` is accepted as the superseded spelling, permanently. This is
+  // a READER of files this repo does not necessarily own: content pulled out
+  // of git history predates the rename and cannot be rewritten, and an
+  // adopter's own topology files are theirs, not ours to migrate. Refusing
+  // the old marker would not fail loudly — `parseName` returns `''`, which
+  // reads downstream as a nameless tranche. The writer side is unaffected:
+  // every file this repo emits or archives carries `# Tranche:`.
+  const m = md.match(/^#\s+(?:Tranche|Iteration):\s+(\S+)/m)
+  return m?.[1] ? m[1].trim() : ''
+}
+
+function parseLifecycle(md: string): Lifecycle {
+  // `Lifecycle: active` or `Lifecycle: complete`. The label may be wrapped in
+  // bold (`**Lifecycle:** active`); the closing `**` sits after the colon.
+  const m = md.match(/^\s*(?:\*\*)?Lifecycle\s*:(?:\*\*)?\s*(active|complete)\b/im)
+  return m?.[1] ? (m[1].toLowerCase() as Lifecycle) : 'active'
+}
+
+function parseGoal(md: string): string {
+  // Match `Goal (…): <text>` to the end of the paragraph.
+  // The live files use various subtitles ("execution, not roadmap-why",
+  // "execution, not product-why"); strip everything up to the colon and
+  // capture the first paragraph that follows.
+  const lines = md.split(/\r?\n/)
+  const buf: string[] = []
+  let inGoal = false
+  for (const raw of lines) {
+    const line = stripBoldWrappers(raw)
+    if (!inGoal) {
+      const m = line.match(/^Goal\b[^:]*:\s*(.*)$/i)
+      if (m) {
+        inGoal = true
+        const rest = (m[1] ?? '').trim()
+        if (rest) buf.push(rest)
+      }
+    } else {
+      if (line.trim() === '') break
+      // Stop at the next markdown heading or HR.
+      if (/^#{1,6}\s/.test(line) || /^---+\s*$/.test(line)) break
+      buf.push(line.trim())
+    }
+  }
+  return buf.join(' ').trim()
+}
+
+function stripBoldWrappers(line: string): string {
+  // Remove bold markers around `Goal …:` or `Lifecycle:` style lines so the
+  // greedy regexes above work on either `**Goal:**` or plain `Goal:`.
+  return line.replace(/\*\*/g, '')
+}
+
+function parseTasks(md: string): Task[] {
+  const rows = readMarkdownTable(md, /^##\s+Tasks\b/i)
+  const rationales = extractRationales(md)
+  const tasks: Task[] = []
+  for (const row of rows) {
+    // Expected 6 columns: # | Task | Issue | Project(s) | Depends-on | Conflicts-with.
+    if (row.length < 6) continue
+    const id = (row[0] ?? '').trim()
+    if (!id) continue
+    tasks.push({
+      id,
+      title: (row[1] ?? '').trim(),
+      issue: parseIssueCell(row[2] ?? ''),
+      projects: parseCsvCell(row[3] ?? ''),
+      dependsOn: parseEdgeCell(row[4] ?? ''),
+      conflictsWith: parseEdgeCell(row[5] ?? ''),
+      rationaleMarkdown: rationales.get(id) ?? ''
+    })
+  }
+  return tasks
+}
+
+function parseIssueCell(cell: string): number | null {
+  const trimmed = stripBackticks(cell).trim()
+  if (!trimmed) return null
+  if (isEmDashOrDash(trimmed)) return null
+  const m = trimmed.match(/#?(\d+)/)
+  return m ? Number(m[1]) : null
+}
+
+function parseCsvCell(cell: string): string[] {
+  const cleaned = stripBackticks(cell).trim()
+  if (!cleaned || isEmDashOrDash(cleaned)) return []
+  return cleaned
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+function parseEdgeCell(cell: string): string[] {
+  return parseCsvCell(cell)
+}
+
+function isEmDashOrDash(s: string): boolean {
+  const t = s.trim()
+  return t === '—' || t === '-' || t === '–'
+}
+
+function stripBackticks(s: string): string {
+  return s.replace(/`/g, '')
+}
+
+/**
+ * Capture each `### Task <id> — …` block as raw markdown — from the heading
+ * through the line before the next `### ` / `## ` / `# ` / end-of-file.
+ * The id may be `1`, `7a`, `7b`, etc. Per-task rationale lives inline in the
+ * tranche file (see §4 template); the planner's rationale also lives in the
+ * Issue body, but the inline copy is what `parseTranche` exposes.
+ */
+function extractRationales(md: string): Map<string, string> {
+  const out = new Map<string, string>()
+  const lines = md.split(/\r?\n/)
+  let i = 0
+  while (i < lines.length) {
+    const m = (lines[i] ?? '').match(/^###\s+Task\s+(\S+)\s+—/)
+    if (!m?.[1]) {
+      i++
+      continue
+    }
+    const id = m[1]
+    const start = i
+    i++
+    while (i < lines.length && !/^#{1,3}\s/.test(lines[i] ?? '')) i++
+    out.set(id, lines.slice(start, i).join('\n').trimEnd())
+  }
+  return out
+}
+
+function parseBacklog(md: string): string[] {
+  const lines = md.split(/\r?\n/)
+  let i = 0
+  for (; i < lines.length; i++) {
+    if (/^##\s+Backlog\b/i.test(lines[i] ?? '')) {
+      i++
+      break
+    }
+  }
+  if (i >= lines.length) return []
+  const bullets: string[] = []
+  for (; i < lines.length; i++) {
+    const line = lines[i] ?? ''
+    if (/^#{1,3}\s/.test(line)) break
+    const m = line.match(/^\s*[-*+]\s+(.*)$/)
+    if (m?.[1]) bullets.push(m[1].trim())
+  }
+  return bullets
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/pr-report-density.ts

@@ -0,0 +1,116 @@
+/**
+ * PR-report density (aeg-governance-hardening, dogfooding finding 2026-09-02).
+ * Pure — no `fs`, no `fetch`, no `process.env`.
+ *
+ * `aeg-root/roles/developer.md` § "PR body — canonical form" and
+ * `aeg-root/templates/pr-report-template.md` both require `## Summary` and
+ * `## Scope` to be exactly one paragraph — narrative root-cause detail
+ * belongs in a section of its own below the canonical four, a commit
+ * message, or the changeset, never padded into the report itself and never
+ * hand-typed into the AEG:EVIDENCE block. Nothing enforced that rule
+ * mechanically:
+ * confirmed live, three real PRs (`atta-labs/vinaya#343`, `#346`, `#354`)
+ * shipped multi-paragraph Summary/Scope sections and nothing caught it,
+ * neither at `vinaya pr create`/`pr edit` time nor in CI. Longer, denser
+ * prose is also strictly more surface for every other body-text gate
+ * (`body-bare-digits`, `reader-resolvable-prose`'s glossary rule) — the same
+ * class of gap `#341` hit in code, just in prose instead.
+ *
+ * Deterministic and structural only, matching `brief-validation.ts`'s own
+ * "presence-only" philosophy: this counts blank-line-delimited text blocks,
+ * never judges whether the prose itself is good.
+ *
+ * The rule is literal — one paragraph, full stop — so a `### subsection`, a
+ * bullet list, or a markdown table under Summary/Scope all fail too, same as
+ * a second prose paragraph would (confirmed by probe, PR review on #358).
+ * That is intentional, not an oversight: `developer.md`'s own escape hatch
+ * for exactly this case is "Add anything you want beneath the four
+ * sections" — structured detail belongs in a section of its own below
+ * Summary/Scope/Test-plan/Evidence, not folded into one of the four. A
+ * multi-line blockquote is the one shape this rule does NOT split on (its
+ * `\n>\n` continuation lines are never blank) — but only when the
+ * blockquote IS the section, start to finish: prose before or after it is
+ * still a separate blank-line-delimited block, so "intro sentence, then a
+ * blockquote aside, then a closing sentence" is three blocks and still
+ * fails (confirmed by probe, PR review on #358 — this is not the
+ * "structured aside alongside prose" shape it can look like at a glance).
+ * The exemption only covers a section whose entire content, quoted in
+ * full, is the one thing being said.
+ */
+
+import { anchoredRegionBounds, stripCode } from './anchored-region'
+
+export type DensityResult = { status: 'pass' | 'fail'; errors: string[] }
+
+/**
+ * The named `## <heading>` section's raw body text — from just after the
+ * heading line to the next `##`-or-shallower heading, or end of body.
+ * `null` when the heading itself is absent (a different check's job to
+ * require it — this one is silent on presence, per the module's scope).
+ */
+function headingSectionBody(prBody: string, heading: string): string | null {
+  const headingRe = new RegExp(`^##\\s+${heading}\\s*$`, 'im')
+  const m = headingRe.exec(prBody)
+  if (!m) return null
+  const start = m.index + m[0].length
+  const rest = prBody.slice(start)
+  const nextHeading = /^#{1,2}\s/m.exec(rest)
+  return nextHeading ? rest.slice(0, nextHeading.index) : rest
+}
+
+/**
+ * `headingSectionBody`'s text with every well-formed `AEG:*` anchor block removed
+ * outright (not just unwrapped) — an anchored field (Scope's trailing
+ * `AEG:TIER` block, in the canonical template) is a field, not a second
+ * prose paragraph, and must not count as one. Reuses `anchoredRegionBounds`
+ * (the same span `vinaya pr report --write` targets) rather than a second,
+ * drifting regex for "what an anchor block looks like."
+ */
+function stripAnchorBlocks(sectionText: string): string {
+  let result = sectionText
+  for (const field of ['CLOSES', 'PROJECT', 'TIER', 'PREMISE', 'TEST-PLAN', 'EVIDENCE'] as const) {
+    for (;;) {
+      const bounds = anchoredRegionBounds(result, field)
+      if (!bounds) break
+      result = result.slice(0, bounds.outerStart) + result.slice(bounds.outerEnd)
+    }
+  }
+  return result
+}
+
+/** Non-empty, blank-line-delimited text blocks, code-blind (a fenced example inside the section is not a second paragraph). */
+function paragraphCount(sectionText: string): number {
+  const stripped = stripCode(stripAnchorBlocks(sectionText)).trim()
+  if (stripped.length === 0) return 0
+  return stripped
+    .split(/\n[ \t]*\n/)
+    .map((block) => block.trim())
+    .filter((block) => block.length > 0).length
+}
+
+function checkSectionDensity(prBody: string, heading: string): DensityResult {
+  const body = headingSectionBody(prBody, heading)
+  if (body === null) return { status: 'pass', errors: [] }
+  const count = paragraphCount(body)
+  if (count <= 1) return { status: 'pass', errors: [] }
+  return {
+    status: 'fail',
+    errors: [
+      `pr-report-density ${heading}: "## ${heading}" holds ${count} paragraphs — the canonical PR-report form (aeg-root/roles/developer.md § PR body) requires exactly one. Collapse it to one paragraph; move the rest into a section of your own below the canonical four ("Add anything you want beneath the four sections", developer.md), a commit message, or the changeset — never into the AEG:EVIDENCE block, which is emitted only, never hand-typed.`
+    ]
+  }
+}
+
+export function checkSummaryDensity(prBody: string): DensityResult {
+  return checkSectionDensity(prBody, 'Summary')
+}
+
+export function checkScopeDensity(prBody: string): DensityResult {
+  return checkSectionDensity(prBody, 'Scope')
+}
+
+/** Aggregates both section checks — one error line per over-dense section. */
+export function checkPrReportDensity(prBody: string): { errors: string[] } {
+  const results = [checkSummaryDensity(prBody), checkScopeDensity(prBody)]
+  return { errors: results.flatMap((r) => r.errors) }
+}

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

@@ -0,0 +1,81 @@
+/**
+ * PR tier derivation and the docs-gate override check. Pure — takes the diff,
+ * PR body, and env-derived strings as explicit parameters. The original
+ * `scripts/verify-docs.ts` read `process.env.PR_BODY` / `OVERRIDE_DOCS` /
+ * `PR_LABELS` directly inside these functions; that hidden I/O is removed
+ * here — the caller (the CLI shim) reads env once and passes the values in.
+ */
+
+import { hasLabel, label } from '@attalabs/aeg-forge-state'
+import { anchoredRegion } from './anchored-region'
+import { isDocFile, isSpecFile } from './file-classify'
+
+/**
+ * Derive a tier from the changed-file list when no `Tier:` field is in the PR body.
+ *
+ * Rules (in priority order):
+ *   1. Spec or doc file in diff   → Tier 1
+ *   2. Otherwise (code/config…)   → Tier 0
+ *
+ * A frozen archive carries no tier signal: nothing reads it, so touching one
+ * says nothing about a change's impact.
+ */
+export function deriveTierFromDiff(changed: string[]): 0 | 1 {
+  if (changed.some((p) => isSpecFile(p) || isDocFile(p))) return 1
+  return 0
+}
+
+/**
+ * Read the `Tier:` field from the PR body.
+ *
+ * Tolerates the three markdown shapes the field appears in:
+ *   - plain:        `Tier: 3`
+ *   - bold colon:   `**Tier:** 3`   (the `**` wraps `Tier:` including the colon)
+ *   - bold label:   `**Tier**: 3`   (the `**` wraps only `Tier`)
+ *
+ * The field may appear inline in a metadata line (e.g.
+ * `Tranche: x · Task: 1 · **Tier:** 3 · Project: y`), so it is NOT anchored
+ * to line-start. Returns null when no Tier field is present at all — the caller
+ * decides what a missing tier means (PR mode treats it as an explicit error,
+ * NOT a silent default).
+ *
+ * When the body carries an `AEG:TIER` anchor pair (`anchored-region.ts`,
+ * task 30), the same regex runs exclusively inside that pair — a `Tier:`
+ * mention anywhere else (a pasted reference brief, a quoted example) is
+ * ignored. Bodies without the pair parse exactly as before.
+ */
+/**
+ * The exact `Tier:` field grammar, exported so a consumer that needs the
+ * MATCH itself (not just the parsed number) — `body-bare-digits`, which
+ * needs to know precisely which substring is the field's real value so it
+ * can exempt exactly that and nothing appended after it — reuses this one
+ * definition rather than a second regex that could silently drift from it.
+ * An optional bold-open, the word Tier, an optional bold-close, a colon, an
+ * optional bold-close (covers `**Tier:**`), optional space, then the digit.
+ */
+export const TIER_FIELD = /(\*\*)?\s*Tier\s*(\*\*)?\s*:\s*(\*\*)?\s*([013])\b/i
+
+export function readTierFromPrBody(prBody: string): 0 | 1 | 3 | null {
+  const searchIn = anchoredRegion(prBody, 'TIER') ?? prBody
+  const m = searchIn.match(TIER_FIELD)
+  if (!m) return null
+  const t = Number(m[4])
+  return t === 0 || t === 1 || t === 3 ? (t as 0 | 1 | 3) : null
+}
+
+/**
+ * The body token that activates the override — the label name in brackets, so
+ * the two spellings cannot drift. Built from the code-owned vocabulary rather
+ * than written as a literal (#614): `override:docs` was the one §14 system
+ * label the namespace migration missed, precisely because it lived here as a
+ * bare string that no label-family grep looked for.
+ */
+const OVERRIDE_BODY_TOKEN = `[${label('override-docs')}]`
+
+export function overrideActive(opts: { overrideDocsEnv?: string; prLabels?: string; prBody?: string }): boolean {
+  if (opts.overrideDocsEnv === '1') return true
+  const labels = (opts.prLabels || '').split(',').map((s) => s.trim())
+  if (hasLabel('override-docs', labels)) return true
+  if ((opts.prBody || '').includes(OVERRIDE_BODY_TOKEN)) return true
+  return false
+}

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

@@ -0,0 +1,160 @@
+/**
+ * Premise-pinning grammar (aeg-governance-hardening task 11, #324). Pure —
+ * no `fs`; file content is injected via `fileReader` so the checker stays
+ * testable and CWD-independent.
+ *
+ * A brief/PR body's `Premise:` block pins concrete, checkable facts about the
+ * code surface at authoring time — e.g. "this function still exists", "this
+ * constant is still absent". `verify-dispatch --premise <body-file>`
+ * re-asserts every pin immediately before Step 0: a premise that no longer
+ * holds means the surface moved since the brief was written, and the
+ * Developer should stop and re-dig rather than execute against a stale
+ * mental model (the exact failure of aeg-governance-hardening's live-fire
+ * #3 — two briefs described a target architecture a later, uncited migration
+ * had already superseded).
+ *
+ * Deliberately minimal — exactly three assertion kinds. This is a pin
+ * format, not a DSL; resist adding more.
+ */
+
+import { createHash } from 'node:crypto'
+import { anchoredRegion } from './anchored-region'
+
+export type PremiseAssertion =
+  | { kind: 'contains'; path: string; value: string }
+  | { kind: 'absent'; path: string; value: string }
+  | { kind: 'sha256'; path: string; value: string }
+
+const ASSERTION_KINDS = new Set(['contains', 'absent', 'sha256'])
+
+/**
+ * True for the header line in either serialization the rest of the brief
+ * grammar uses (`brief-validation.ts`, `issue-validation.ts`): `**Premise:**`
+ * bold-inline or `### Premise` heading. Strips `*`/`#` markup first rather
+ * than trying to enumerate every marker placement — `**Premise:**` closes
+ * its bold markers *after* the colon, `**Premise**:` closes them *before*.
+ */
+function isPremiseHeader(line: string): boolean {
+  const stripped = line.replace(/[*#]/g, '').trim()
+  return /^premise\s*:?$/i.test(stripped)
+}
+
+/** Matches one bullet line: `- <path> <kind>: <value>`. */
+const PREMISE_LINE = /^[-*]\s*(\S+)\s+(contains|absent|sha256)\s*:\s*(.+)$/i
+
+/**
+ * Parse every `- <path> <kind>: <value>` bullet under the `Premise:` header.
+ * Malformed bullets (wrong kind, missing colon) are silently skipped — this
+ * mirrors `parsePremiseBlock`'s sibling parsers' presence-only philosophy;
+ * the caller decides whether zero assertions is itself a failure
+ * (`checkPremiseCoverage`). Stops the block at the first blank line or the
+ * first non-bullet line after the header.
+ *
+ * When the body carries an `AEG:PREMISE` anchor pair (`anchored-region.ts`,
+ * task 30), the block is parsed exclusively inside that pair — the pair must
+ * contain the `**Premise:**` header line and its bullets; a premise-shaped
+ * block anywhere else in the body is ignored. Bodies without the pair parse
+ * exactly as before.
+ */
+export function parsePremiseBlock(prBody: string): PremiseAssertion[] {
+  const searchIn = anchoredRegion(prBody, 'PREMISE') ?? prBody
+  const lines = searchIn.split(/\r?\n/)
+  const assertions: PremiseAssertion[] = []
+  let inBlock = false
+
+  for (const raw of lines) {
+    const line = raw.trim()
+    if (!inBlock) {
+      if (isPremiseHeader(line)) inBlock = true
+      continue
+    }
+    if (line === '') break
+    const m = line.match(PREMISE_LINE)
+    if (!m) break
+    const [, path, kindRaw, value] = m
+    const kind = (kindRaw as string).toLowerCase()
+    if (!ASSERTION_KINDS.has(kind)) continue
+    assertions.push({ kind, path: path as string, value: (value as string).trim() } as PremiseAssertion)
+  }
+
+  return assertions
+}
+
+/**
+ * The `Premise:` block's own raw text (header line through its last bullet),
+ * mirroring `parsePremiseBlock`'s exact same header/bullet/stop rules so the
+ * two can never disagree about where the block ends. Returns `null` when no
+ * header is found. Used by `brief-validation.ts`'s `checkNoUnpinnedCodeClaims`
+ * to exclude the block's own bullets (a pin's path is a legitimate file
+ * reference, not an unpinned prose claim) — reuses this parser's block
+ * boundaries rather than a second one.
+ */
+export function premiseBlockText(prBody: string): string | null {
+  const searchIn = anchoredRegion(prBody, 'PREMISE') ?? prBody
+  const lines = searchIn.split(/\r?\n/)
+  let startIdx = -1
+  let endIdxExclusive = lines.length
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = (lines[i] as string).trim()
+    if (startIdx === -1) {
+      if (isPremiseHeader(line)) startIdx = i
+      continue
+    }
+    if (line === '') {
+      endIdxExclusive = i
+      break
+    }
+    if (!PREMISE_LINE.test(line)) {
+      endIdxExclusive = i
+      break
+    }
+  }
+
+  if (startIdx === -1) return null
+  return lines.slice(startIdx, endIdxExclusive).join('\n')
+}
+
+export type PremiseCheckResult = { pass: boolean; failures: string[] }
+
+/**
+ * Re-assert every parsed premise against the current file content, injected
+ * via `fileReader` (returns `null` when the path does not exist). One
+ * failure line per broken pin, naming the exact path/kind/value so the
+ * Developer can see precisely what moved.
+ */
+export function checkPremises(
+  assertions: PremiseAssertion[],
+  fileReader: (path: string) => string | null
+): PremiseCheckResult {
+  const failures: string[] = []
+
+  for (const a of assertions) {
+    const content = fileReader(a.path)
+    if (content === null) {
+      failures.push(
+        `premise-check: ${a.path} does not exist on disk (premise asserted \`${a.kind}: ${a.value}\`) — the surface moved since this brief was authored; re-dig before proceeding.`
+      )
+      continue
+    }
+
+    if (a.kind === 'contains' && !content.includes(a.value)) {
+      failures.push(
+        `premise-check: ${a.path} no longer contains "${a.value}" — the premise this brief pinned has moved; re-dig before proceeding.`
+      )
+    } else if (a.kind === 'absent' && content.includes(a.value)) {
+      failures.push(
+        `premise-check: ${a.path} now contains "${a.value}", but the brief pinned it absent — the premise has moved; re-dig before proceeding.`
+      )
+    } else if (a.kind === 'sha256') {
+      const actual = createHash('sha256').update(content).digest('hex')
+      if (actual !== a.value.toLowerCase()) {
+        failures.push(
+          `premise-check: ${a.path} sha256 mismatch (brief pinned ${a.value}, file is now ${actual}) — the file changed since this brief was authored; re-dig before proceeding.`
+        )
+      }
+    }
+  }
+
+  return { pass: failures.length === 0, failures }
+}