@defrex/autobuild 0.8.0

package/packages/core/src/kernel/stall.ts

@@ -0,0 +1,155 @@
+/**
+ * Persistence-chain mechanics for stall detection (SPEC §15.4, D4).
+ *
+ * The split follows the constitution: deciding whether a new finding is *the
+ * same disagreement* as an earlier one is fuzzy → judgment → the reviewer
+ * (fresh each round) marks `persists`. Everything in this module is the
+ * deterministic half: following the marked links and applying the threshold.
+ *
+ * Chain model:
+ * - A chain is identified by its root — a finding whose `persists` resolves to
+ *   no earlier-round finding. `persists` links are honored only when the
+ *   target exists in a strictly earlier round; unknown ids and same/later
+ *   round targets are not links (ids are deposit-stamped, so a reviewer can
+ *   only ever reference rounds it was shown — §8.3).
+ * - Branching persists (two findings continuing one ancestor) extend the same
+ *   chain; a finding with multiple `persists` entries joins every chain its
+ *   ancestors belong to.
+ * - A chain's `rounds` is the longest run of *consecutive* rounds it occupies
+ *   (SPEC §15.4: a chain "survives" N rounds). A round in which no reviewer
+ *   continued the chain breaks the streak: that round's fresh skeptic saw all
+ *   prior findings (§8.3) and judged the disagreement resolved, so a later
+ *   re-raise starts surviving anew — though the chain's `ids` keep the full
+ *   history.
+ */
+import type { Finding } from '../ontology'
+
+export interface FindingChain {
+  /** Member finding ids in round order, chain root first. */
+  ids: string[]
+  /** Count of distinct consecutive rounds the chain spans (longest streak). */
+  rounds: number
+}
+
+interface ChainMembers {
+  ids: string[]
+  /** Parallel to `ids`: the 1-based round each member was found in. */
+  memberRounds: number[]
+}
+
+/**
+ * Follow `persists` links across rounds (`roundFindings[0]` is round 1) and
+ * group findings into chains, one per root. Single fresh findings are chains
+ * of `rounds: 1` — staying below any sane threshold is what "fresh" means.
+ */
+export function persistenceChains(roundFindings: Finding[][]): FindingChain[] {
+  return buildChains(roundFindings).map((chain) => ({
+    ids: chain.ids,
+    rounds: longestConsecutiveRun(chain.memberRounds),
+  }))
+}
+
+/**
+ * Chains whose streak has reached `stallRounds` (SPEC §15.4) — minus chains a
+ * human already resolved via `escalation.answered {dismiss-finding}`
+ * (§15.6-B).
+ *
+ * Dismissal semantics: a chain is human-resolved when every finding in its
+ * most recent round (its tip — the live continuations of the disagreement) is
+ * dismissed. Earlier members are history and need no dismissal. If a later
+ * round persists into a dismissed chain with a finding that is not itself
+ * dismissed, the tip moves and the chain resurrects — with its full streak
+ * intact, so a reviewer overriding a human dismissal re-escalates at the very
+ * next revise rather than burning `stallRounds` more rounds.
+ */
+export function stalledChains(
+  roundFindings: Finding[][],
+  stallRounds: number,
+  dismissedIds?: ReadonlySet<string>,
+): FindingChain[] {
+  const stalled: FindingChain[] = []
+  for (const chain of buildChains(roundFindings)) {
+    const rounds = longestConsecutiveRun(chain.memberRounds)
+    if (rounds < stallRounds) continue
+    if (dismissedIds !== undefined && tipDismissed(chain, dismissedIds)) continue
+    stalled.push({ ids: chain.ids, rounds })
+  }
+  return stalled
+}
+
+function buildChains(roundFindings: Finding[][]): ChainMembers[] {
+  const byId = new Map<string, { finding: Finding; round: number }>()
+  const traversal: string[] = []
+  roundFindings.forEach((findings, index) => {
+    for (const finding of findings) {
+      if (byId.has(finding.id)) continue
+      byId.set(finding.id, { finding, round: index + 1 })
+      traversal.push(finding.id)
+    }
+  })
+
+  // Links point strictly to earlier rounds, so recursion terminates; memoized
+  // so shared ancestors are resolved once.
+  const rootsMemo = new Map<string, ReadonlySet<string>>()
+  function rootsOf(id: string): ReadonlySet<string> {
+    const memoized = rootsMemo.get(id)
+    if (memoized !== undefined) return memoized
+    const node = byId.get(id)
+    if (node === undefined) return new Set()
+    const parents = node.finding.persists.filter((parentId) => {
+      const parent = byId.get(parentId)
+      return parent !== undefined && parent.round < node.round
+    })
+    const roots = new Set<string>()
+    if (parents.length === 0) {
+      roots.add(id)
+    } else {
+      for (const parentId of parents) {
+        for (const root of rootsOf(parentId)) roots.add(root)
+      }
+    }
+    rootsMemo.set(id, roots)
+    return roots
+  }
+
+  // Traversal is round-major, and a root is always its chain's earliest
+  // member, so each chain lists its root first and members in round order.
+  const chains = new Map<string, ChainMembers>()
+  for (const id of traversal) {
+    const node = byId.get(id)
+    if (node === undefined) continue
+    for (const root of rootsOf(id)) {
+      let chain = chains.get(root)
+      if (chain === undefined) {
+        chain = { ids: [], memberRounds: [] }
+        chains.set(root, chain)
+      }
+      chain.ids.push(id)
+      chain.memberRounds.push(node.round)
+    }
+  }
+  return [...chains.values()]
+}
+
+function longestConsecutiveRun(rounds: readonly number[]): number {
+  const occupied = new Set(rounds)
+  let longest = 0
+  for (const round of occupied) {
+    if (occupied.has(round - 1)) continue
+    let length = 1
+    while (occupied.has(round + length)) length += 1
+    if (length > longest) longest = length
+  }
+  return longest
+}
+
+function tipDismissed(chain: ChainMembers, dismissedIds: ReadonlySet<string>): boolean {
+  const tipRound = Math.max(...chain.memberRounds)
+  for (let i = 0; i < chain.ids.length; i += 1) {
+    const id = chain.ids[i]
+    if (chain.memberRounds[i] === tipRound && id !== undefined && !dismissedIds.has(id)) {
+      return false
+    }
+  }
+  return true
+}

package/packages/core/src/kernel/verify-applicability.ts

@@ -0,0 +1,52 @@
+import { verifyPathGlobError } from '../config/schema'
+
+/**
+ * Pure verify-applicability rule. `always` is explicit rather than represented
+ * by an empty selector list, so mandatory-gate precedence cannot depend on
+ * truthiness or ordering.
+ */
+export type VerifyApplicabilityRule =
+  | { kind: 'always' }
+  | { kind: 'paths'; step: string; paths: readonly string[] }
+
+export type VerifyApplicabilityResult = { applies: true } | { applies: false; reason: string }
+
+/** Stable, queryable reason used by the kernel-authored skipped outcome. */
+export function pathExclusionReason(step: string, paths: readonly string[]): string {
+  return `excluded by [verify.${step}].paths: no changed path matched ${JSON.stringify(paths)}`
+}
+
+/**
+ * Evaluate one rule against Git's repository-relative, `/`-separated changed
+ * paths. Matching is case-sensitive and OR-shaped: one selector matching one
+ * changed path is enough. No I/O and no event writes occur here.
+ */
+export function evaluateVerifyApplicability(
+  rule: VerifyApplicabilityRule,
+  changedPaths: readonly string[],
+): VerifyApplicabilityResult {
+  if (rule.kind === 'always') return { applies: true }
+
+  // Parsed Config is the normal caller and has already validated these. Keep
+  // this exported pure seam fail-closed for direct callers too: Bun.Glob is
+  // never asked to interpret syntax outside the documented subset.
+  for (const path of rule.paths) {
+    const error = verifyPathGlobError(path)
+    if (error !== undefined) {
+      throw new Error(
+        `invalid [verify.${rule.step}].paths selector ${JSON.stringify(path)}: ${error}`,
+      )
+    }
+  }
+
+  const globs = rule.paths.map((path) => new Bun.Glob(path))
+  for (const changedPath of changedPaths) {
+    for (const glob of globs) {
+      if (glob.match(changedPath)) return { applies: true }
+    }
+  }
+  return {
+    applies: false,
+    reason: pathExclusionReason(rule.step, rule.paths),
+  }
+}

package/packages/core/src/markdown.ts

@@ -0,0 +1,67 @@
+/**
+ * Approximate Markdown reference extraction, shared by the checks that ask
+ * "does this link point at something that exists?".
+ *
+ * These are regexes, not a CommonMark parser. Reference-style targets
+ * (`![alt][ref]`) and targets containing parentheses are invisible to them.
+ * Both callers are link-existence checks, where an unseen reference fails
+ * toward a loud complaint rather than a silent pass, so the approximation is
+ * safe — but a false report is a signal to widen the parser, never to delete
+ * the thing it failed to see.
+ */
+
+/**
+ * Blanks out fenced code blocks, preserving line count. A target inside a fence
+ * is sample text, not a rendered reference. Backtick and tilde fences are
+ * tracked separately so a `~~~` line inside a ``` block does not close it.
+ */
+export function withoutFencedCode(markdown: string): string {
+  const lines = markdown.split('\n')
+  let fence: '`' | '~' | undefined
+  return lines
+    .map((line) => {
+      const opening = line.match(/^\s*(`{3,}|~{3,})/)
+      if (opening) {
+        const marker = opening[1]![0] as '`' | '~'
+        if (fence === undefined) fence = marker
+        else if (fence === marker) fence = undefined
+        return ''
+      }
+      return fence === undefined ? line : ''
+    })
+    .join('\n')
+}
+
+/**
+ * Inline link and image targets, in source order. Angle brackets are unwrapped
+ * and a title suffix is dropped, so `[a](<b.md> "T")` yields `b.md`.
+ */
+export function markdownTargets(markdown: string): string[] {
+  const targets: string[] = []
+  for (const match of markdown.matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) {
+    const inline = match[1]!.trim()
+    // An angle-bracketed destination runs to its closing `>`, and whatever
+    // follows is the title. The two must be read together: unwrapping first
+    // fails whenever a title is present (the text no longer ends in `>`), and
+    // splitting the title off first would truncate a bracketed destination that
+    // legitimately contains whitespace and a quote. A `<` with no closing `>`
+    // is malformed, and falls through to the unbracketed reading.
+    const closing = inline.startsWith('<') ? inline.indexOf('>') : -1
+    targets.push(closing === -1 ? inline.split(/\s+["']/u, 1)[0]! : inline.slice(1, closing))
+  }
+  return targets
+}
+
+/**
+ * `src` attributes of raw `<img>` tags, in source order. Kept separate from
+ * `markdownTargets` so callers that only care about Markdown syntax keep their
+ * existing behaviour: Markdown permits raw HTML, and this repository's README
+ * already mixes it in, so a centred hero image would otherwise be invisible.
+ */
+export function htmlImageTargets(markdown: string): string[] {
+  const targets: string[] = []
+  for (const match of markdown.matchAll(/<img\b[^>]*?\ssrc\s*=\s*("([^"]*)"|'([^']*)')/giu)) {
+    targets.push((match[2] ?? match[3])!.trim())
+  }
+  return targets
+}

package/packages/core/src/ontology.ts

@@ -0,0 +1,288 @@
+/**
+ * The ontology (SPEC §4): one name, used everywhere; every noun lives in
+ * exactly one layer. Schemas are the source of truth — the `ab` CLI and the
+ * store validate deposits against them (D6), and the TypeScript types are
+ * inferred.
+ *
+ * Reserved-word discipline: **build** names the whole pipeline execution and
+ * nothing else; the coding phase is **implement**.
+ */
+import { z } from 'zod'
+
+// ── Phases (SPEC §5) ─────────────────────────────────────────────────────────
+
+export const CORE_PHASES = [
+  'plan',
+  'plan-review',
+  'implement',
+  'code-review',
+  'finalize',
+  'reconcile',
+] as const
+export type CorePhase = (typeof CORE_PHASES)[number]
+
+/** Verify steps are config-defined — an open set (SPEC §15.2.1). */
+export type VerifyPhase = `verify:${string}`
+export type Phase = CorePhase | VerifyPhase
+
+export function isCorePhase(value: string): value is CorePhase {
+  return (CORE_PHASES as readonly string[]).includes(value)
+}
+
+export function isVerifyPhase(value: string): value is VerifyPhase {
+  return value.startsWith('verify:') && value.length > 'verify:'.length
+}
+
+export function isPhase(value: string): value is Phase {
+  return isCorePhase(value) || isVerifyPhase(value)
+}
+
+/** `verify:e2e` → `e2e` */
+export function verifyStep(phase: VerifyPhase): string {
+  return phase.slice('verify:'.length)
+}
+
+export function verifyPhase(step: string): VerifyPhase {
+  return `verify:${step}`
+}
+
+export const phaseSchema = z.custom<Phase>((value) => typeof value === 'string' && isPhase(value), {
+  message: 'not a phase: expected a core phase or "verify:<step>"',
+})
+
+// ── Findings (SPEC §15.4) ────────────────────────────────────────────────────
+
+export const severitySchema = z.enum(['blocking', 'important', 'minor'])
+export type Severity = z.infer<typeof severitySchema>
+
+export const findingSchema = z.strictObject({
+  /** Kernel-assigned at deposit, stable for the build (e.g. `f_3a91`). */
+  id: z.string().min(1),
+  severity: severitySchema,
+  file: z.string().optional(),
+  lines: z.array(z.number().int()).optional(),
+  summary: z.string().min(1),
+  detail: z.string().optional(),
+  /** Reviewer-marked: ids of earlier findings this one continues (stall input). */
+  persists: z.array(z.string()).default([]),
+})
+export type Finding = z.infer<typeof findingSchema>
+
+/** What an agent submits — ids are stamped at deposit, never self-assigned. */
+export const findingDraftSchema = findingSchema.omit({ id: true })
+export type FindingDraft = z.infer<typeof findingDraftSchema>
+
+// ── Verdicts (SPEC §4, §10) ──────────────────────────────────────────────────
+
+/** Review-phase vocabulary (`plan-review`, `code-review`). */
+export const reviewVerdictKindSchema = z.enum(['approve', 'revise', 'escalate'])
+export type ReviewVerdictKind = z.infer<typeof reviewVerdictKindSchema>
+
+/** Durable outcome of any `verify.completed` fact. */
+export const verifyOutcomeSchema = z.enum(['pass', 'fail', 'skipped'])
+export type VerifyOutcome = z.infer<typeof verifyOutcomeSchema>
+
+/** Agent-verify CLI vocabulary (`verify:*` steps of kind "agent"). */
+export const verifyVerdictKindSchema = z.enum(['pass', 'fail', 'skip'])
+export type VerifyVerdictKind = z.infer<typeof verifyVerdictKindSchema>
+
+/** Structured outcome of a review, as consumed by `converge` (SPEC §10). */
+export type Verdict =
+  | { verdict: 'approve' }
+  | { verdict: 'revise'; findings: Finding[] }
+  | { verdict: 'escalate'; reason: string }
+
+// ── Observations (SPEC §4, §12) ──────────────────────────────────────────────
+
+export const observationKindSchema = z.enum(['followup', 'refactor', 'latent-bug'])
+export type ObservationKind = z.infer<typeof observationKindSchema>
+
+// ── Escalations (SPEC §11, §15.3) ────────────────────────────────────────────
+
+export const escalationSourceSchema = z.enum(['agent', 'stall', 'policy'])
+export type EscalationSource = z.infer<typeof escalationSourceSchema>
+
+/** Closed identity for every policy-authored escalation condition. `round`
+ * scopes an occurrence; it does not identify which policy guard raised it. */
+export const policyEscalationCauseSchema = z.enum([
+  'review-round-limit',
+  'verify-failure-limit',
+  'reconcile-no-progress',
+  'setup-failure-limit',
+  'infrastructure-failure-limit',
+  'phase-attempt-limit',
+  'non-retryable-phase-failure',
+])
+export type PolicyEscalationCause = z.infer<typeof policyEscalationCauseSchema>
+
+/** Setup may block a build through the escalation protocol without becoming a
+ * pipeline phase. Keeping this target separate preserves the fixed phase
+ * grammar while allowing the ordinary answer/retry machinery to re-arm setup. */
+export type EscalationTarget = Phase | 'setup'
+export const escalationTargetSchema = z.custom<EscalationTarget>(
+  (value) => value === 'setup' || (typeof value === 'string' && isPhase(value)),
+  { message: 'not an escalation target: expected "setup", a core phase, or "verify:<step>"' },
+)
+
+export const escalationResolutionSchema = z.enum([
+  'guidance',
+  'dismiss-finding',
+  'revise-spec',
+  'abort',
+  /** Bare re-attempt with no phase guidance: human UI, or policy-only startup. */
+  'retry',
+])
+export type EscalationResolution = z.infer<typeof escalationResolutionSchema>
+
+// ── Tickets ──────────────────────────────────────────────────────────────────
+
+export const ticketRefSchema = z.strictObject({
+  source: z.string().min(1),
+  id: z.string().min(1),
+  url: z.string().optional(),
+  title: z.string().optional(),
+})
+export type TicketRef = z.infer<typeof ticketRefSchema>
+
+// ── Artifacts ────────────────────────────────────────────────────────────────
+
+/**
+ * Revisions are 0-based per kind: the first deposit of a kind is rev 0
+ * (normative in SPEC §6.3 — the spec is "kind `spec`, revision 0"), and every
+ * later deposit of the same kind is max+1.
+ */
+export const artifactRefSchema = z.strictObject({
+  kind: z.string().min(1),
+  rev: z.number().int().nonnegative(),
+})
+export type ArtifactRef = z.infer<typeof artifactRefSchema>
+
+/** Closed set of core kinds; verify reports are per-step (open set). */
+export const CORE_ARTIFACT_KINDS = [
+  'spec',
+  'plan',
+  'plan-review',
+  'implement-notes',
+  'code-review',
+  'pr-description',
+  'reconcile-notes',
+  'transcript',
+] as const
+export type CoreArtifactKind = (typeof CORE_ARTIFACT_KINDS)[number]
+
+/** `e2e` → `verify-report:e2e` */
+export function verifyReportKind(step: string): string {
+  return `verify-report:${step}`
+}
+
+// ── Pull-request attachments ─────────────────────────────────────────────────
+
+/** Deliberately narrower than GitHub's full repository-name policy: one
+ * non-blank, whitespace-free `owner/repo` pair is enough for deterministic
+ * routing without pretending to validate a remote identifier locally. */
+export const githubRepositorySchema = z
+  .string()
+  .regex(
+    /^[^/\s]+\/[^/\s]+$/,
+    'expected exactly one non-blank GitHub repository pair in "owner/repo" form',
+  )
+export type GitHubRepository = z.infer<typeof githubRepositorySchema>
+
+/** Optional, frozen destination for review-window image copies. */
+export const prImageHostSchema = z.strictObject({
+  provider: z.literal('github-release'),
+  repository: githubRepositorySchema,
+  releaseId: z.number().int().positive(),
+})
+export type PrImageHostTarget = z.infer<typeof prImageHostSchema>
+
+/** A basename safe to render and pass back to `ab artifact download`. */
+export const prAttachmentFilenameSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .refine((value) => value.trim().length > 0, 'attachment filename must be non-blank')
+  .refine((value) => value !== '.' && value !== '..', 'attachment filename must name a file')
+  .refine(
+    (value) => !/[\\/\u0000-\u001f\u007f]/.test(value),
+    'attachment filename must be a basename without path separators or control characters',
+  )
+
+/** Normalized MIME media type: lowercase type/subtype with no parameters. */
+export const mediaTypeSchema = z
+  .string()
+  .regex(
+    /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/,
+    'expected a normalized lowercase media type without parameters',
+  )
+
+/** One exact BuildStore artifact explicitly designated for PR projection. */
+export const prAttachmentSchema = z.strictObject({
+  artifact: artifactRefSchema,
+  filename: prAttachmentFilenameSchema,
+  mediaType: mediaTypeSchema,
+})
+export type PrAttachment = z.infer<typeof prAttachmentSchema>
+
+/** Durable deletion handle returned after one image attachment is hosted. */
+export const hostedPrAttachmentAssetSchema = z.strictObject({
+  provider: z.literal('github-release'),
+  repository: githubRepositorySchema,
+  releaseId: z.number().int().positive(),
+  assetId: z.number().int().positive(),
+  url: z
+    .string()
+    .url()
+    .refine((url) => url.startsWith('https://'), 'hosted PR attachment URL must use HTTPS'),
+})
+export type HostedPrAttachmentAsset = z.infer<typeof hostedPrAttachmentAssetSchema>
+
+// ── Builds ───────────────────────────────────────────────────────────────────
+
+export const buildOutcomeSchema = z.enum(['merged', 'closed-unmerged', 'abandoned', 'discarded'])
+export type BuildOutcome = z.infer<typeof buildOutcomeSchema>
+
+/** Derived status — a reduction of events, never stored (SPEC §15.5). */
+export const BUILD_STATUSES = ['queued', 'running', 'paused', 'blocked', 'done', 'aborted'] as const
+export type BuildStatus = (typeof BUILD_STATUSES)[number]
+
+export const commitRangeSchema = z.strictObject({
+  base: z.string().min(1),
+  head: z.string().min(1),
+})
+export type CommitRange = z.infer<typeof commitRangeSchema>
+
+/** How a workspace's branch tip was selected at provision time. */
+export const workspaceBaseSchema = z.discriminatedUnion('source', [
+  z.strictObject({
+    source: z.literal('remote'),
+    sha: z.string().min(1),
+  }),
+  z.strictObject({
+    source: z.literal('local'),
+    sha: z.string().min(1),
+    remoteError: z.string().min(1),
+  }),
+  z.strictObject({
+    source: z.literal('existing'),
+    sha: z.string().min(1),
+  }),
+])
+export type WorkspaceBase = z.infer<typeof workspaceBaseSchema>
+
+// ── Feedback (phase-occurrence input — SPEC §10, §15.3 started events) ─────
+
+export const feedbackSchema = z.union([
+  /** Findings from a revise verdict, by id (payloads carry refs, not blobs). */
+  z.strictObject({ findings: z.array(z.string()) }),
+  /** A verify failure report routed back into the code loop (SPEC §5). */
+  z.strictObject({
+    verify: z.strictObject({ step: z.string(), report: artifactRefSchema }),
+  }),
+  /** A human escalation answer fed to a producer or agent verifier as
+   * authoritative feedback (§15.6-B). */
+  z.strictObject({
+    guidance: z.strictObject({ escalation: z.string(), answer: z.string() }),
+  }),
+])
+export type Feedback = z.infer<typeof feedbackSchema>