mandrel 1.57.0

package/.agents/scripts/lib/config/gates/lighthouse.schema.js

@@ -0,0 +1,23 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code) */
+
+import { GATE_BASE, NULLABLE_NONEMPTY_SAFE_STRING } from './shared.js';
+
+const LIGHTHOUSE_ROUTE = {
+  type: 'object',
+  required: ['path'],
+  properties: {
+    path: { type: 'string', minLength: 1 },
+    formFactor: { type: 'string', enum: ['mobile', 'desktop'] },
+  },
+  additionalProperties: false,
+};
+
+export const LIGHTHOUSE_GATE = {
+  type: 'object',
+  properties: {
+    ...GATE_BASE,
+    baseUrl: NULLABLE_NONEMPTY_SAFE_STRING,
+    routes: { type: 'array', items: LIGHTHOUSE_ROUTE },
+  },
+  additionalProperties: false,
+};

package/.agents/scripts/lib/config/gates/lint.schema.js

@@ -0,0 +1,9 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code) */
+
+import { GATE_BASE } from './shared.js';
+
+export const LINT_GATE = {
+  type: 'object',
+  properties: { ...GATE_BASE },
+  additionalProperties: false,
+};

package/.agents/scripts/lib/config/gates/maintainability.schema.js

@@ -0,0 +1,20 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code) */
+
+import { GATE_BASE, LIST_OR_EXTENDER_OF_STRINGS } from './shared.js';
+
+export const MAINTAINABILITY_GATE = {
+  type: 'object',
+  properties: {
+    ...GATE_BASE,
+    targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
+    // Story #2165 — bounded timeout for `npm run maintainability:update`
+    // spawned by the baseline-attribution refresh path. Mirrors
+    // `coverage.timeoutMs` (Story #2142).
+    refreshTimeoutMs: { type: 'integer', minimum: 1 },
+    // Story #3217 — glob patterns matched against canonicalised repo-relative
+    // paths to exclude files from MI discovery before scoring. Orthogonal to
+    // `components` (grouping). Absent/empty preserves existing behaviour.
+    ignoreGlobs: { type: 'array', items: { type: 'string', minLength: 1 } },
+  },
+  additionalProperties: false,
+};

package/.agents/scripts/lib/config/gates/mutation.schema.js

@@ -0,0 +1,12 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code) */
+
+import { GATE_BASE, NULLABLE_NONEMPTY_SAFE_STRING } from './shared.js';
+
+export const MUTATION_GATE = {
+  type: 'object',
+  properties: {
+    ...GATE_BASE,
+    strykerConfigPath: NULLABLE_NONEMPTY_SAFE_STRING,
+  },
+  additionalProperties: false,
+};

package/.agents/scripts/lib/config/gates/shared.js

@@ -0,0 +1,117 @@
+/* node:coverage ignore file -- AJV schema declaration (data-as-code); flat literal helpers shared by per-gate sub-schemas */
+
+import { SHELL_INJECTION_PATTERN_STRING } from '../../config-schema-shared.js';
+
+/**
+ * Shared sub-schema fragments for `delivery.quality.gates.<tier>`.
+ *
+ * Every gate shares the same four-field base:
+ *
+ *   - `enabled`      — when `false`, the checker exits 0 with a skip line.
+ *   - `baselinePath` — repo-root-relative path to the gate's baseline file.
+ *   - `tolerance`    — `{ kind: 'absolute' | 'percent', value: number }`.
+ *   - `floors`       — workspace-keyed `{ "*": { ... } }` absolute floor object.
+ *
+ * Gate-specific extras (targetDirs for crap/MI, routes for lighthouse,
+ * bundles for bundle-size, coveragePath for coverage) layer on top via the
+ * per-gate schemas in sibling files. Split out of
+ * `config-settings-schema.js` (Story #1737) and then split again
+ * (Story #2987) to keep each module under the maintainability ceiling —
+ * schema literals score low on MI because they're long and flat.
+ */
+
+export const SAFE_STRING = {
+  type: 'string',
+  not: { pattern: SHELL_INJECTION_PATTERN_STRING },
+};
+
+export const NULLABLE_NONEMPTY_SAFE_STRING = {
+  type: ['string', 'null'],
+  minLength: 1,
+  not: { type: 'string', pattern: SHELL_INJECTION_PATTERN_STRING },
+};
+
+export const LIST_OR_EXTENDER_OF_STRINGS = {
+  oneOf: [
+    { type: 'array', items: { type: 'string' } },
+    {
+      type: 'object',
+      properties: {
+        append: { type: 'array', items: { type: 'string' } },
+        prepend: { type: 'array', items: { type: 'string' } },
+      },
+      additionalProperties: false,
+    },
+  ],
+};
+
+/** Object-shaped tolerance: `{ kind: 'absolute' | 'percent', value: number }`. */
+export const TOLERANCE_SCHEMA = {
+  type: 'object',
+  required: ['kind', 'value'],
+  properties: {
+    kind: { type: 'string', enum: ['absolute', 'percent'] },
+    value: { type: 'number', minimum: 0 },
+  },
+  additionalProperties: false,
+};
+
+/**
+ * Workspace-keyed floors object — `"*"` catch-all optional.
+ *
+ * Each value is a per-component floor object whose keys are the metric
+ * names the gate consumes. The metric name keyset is intentionally open
+ * (`additionalProperties: { type: 'number' }`) so per-kind rollup keys
+ * (e.g. `p95`, `perMethod`, `min`, `p50`, `score`, `errorCount`,
+ * `warningCount`) flow through without each per-gate sub-schema having
+ * to enumerate them. Story #1892 / Task #1894 affirmed this contract:
+ * the open-keyset shape is what unblocks the per-rollup floors that
+ * land in S6.
+ *
+ * Story #2032 / Task #2041: `*` is no longer required. When omitted, the
+ * framework-default floor (lines:90 branches:85 functions:90 for
+ * coverage, MI ≥ 70, CRAP ≤ 20) is injected by the resolver
+ * (`lib/config/quality.js`, Story #2125). Operators may pin a
+ * project-wide `*` floor explicitly when they want a value other than
+ * the framework default, or declare named non-`*` workspaces for
+ * monorepo consumers.
+ *
+ * The legacy `paths` escape-valve (Story #2029) and its per-row
+ * enforcement machinery were removed in Story #2125 after Story #2119
+ * verified the per-row path was decorative — the unified gate
+ * (`check-baselines.js`, Epic #1943) only enforces project-wide
+ * rollup floors.
+ */
+export const FLOORS_SCHEMA = {
+  type: 'object',
+  additionalProperties: {
+    type: 'object',
+    additionalProperties: { type: 'number' },
+  },
+};
+
+/**
+ * Per-gate `components` map — name → glob list. Defaulted to
+ * `{ '*': ['**'] }` at the resolver layer (see
+ * `.agents/scripts/lib/baselines/components.js`); the schema only
+ * constrains the shape when an operator declares it explicitly.
+ *
+ * Story #1892 / Task #1894: introduced as the shared seam between the
+ * reader and writer so per-component rollups + floors can land
+ * independently of any one gate.
+ */
+export const COMPONENTS_SCHEMA = {
+  type: 'object',
+  additionalProperties: {
+    type: 'array',
+    items: { type: 'string', minLength: 1 },
+  },
+};
+
+export const GATE_BASE = {
+  enabled: { type: 'boolean' },
+  baselinePath: { ...SAFE_STRING, minLength: 1 },
+  tolerance: TOLERANCE_SCHEMA,
+  floors: FLOORS_SCHEMA,
+  components: COMPONENTS_SCHEMA,
+};

package/.agents/scripts/lib/config/github.js

@@ -0,0 +1,122 @@
+/**
+ * `github.*` accessor (Epic #1720 Story #1739 — top-level reshape).
+ *
+ * GitHub identity, branch protection, merge methods, and notifications all
+ * live under the top-level `github` block post-reshape.
+ *
+ * `branchProtection.requiredChecks` is the single source of truth that
+ * drives both:
+ *
+ *   - `/agents-bootstrap-github` — registers GitHub required-status checks.
+ *   - `/git-merge-pr` → `git-pr-quality-gate.js` — runs each check locally
+ *     before merge.
+ */
+
+/**
+ * Default required-check suite. The framework runs lint + format:check +
+ * test by default; consumers override via
+ * `github.branchProtection.requiredChecks` in `.agentrc.json`.
+ */
+export const DEFAULT_REQUIRED_CHECKS = Object.freeze([
+  Object.freeze({
+    name: 'lint',
+    cmd: Object.freeze(['npm', 'run', 'lint']),
+  }),
+  Object.freeze({
+    name: 'format:check',
+    cmd: Object.freeze(['npm', 'run', 'format:check']),
+  }),
+  Object.freeze({
+    name: 'test',
+    cmd: Object.freeze(['npm', 'test']),
+  }),
+]);
+
+export const BRANCH_PROTECTION_DEFAULTS = Object.freeze({
+  enforce: true,
+  requiredChecks: DEFAULT_REQUIRED_CHECKS,
+});
+
+export const MERGE_METHODS_DEFAULTS = Object.freeze({
+  allow_squash_merge: true,
+  allow_rebase_merge: false,
+  allow_merge_commit: false,
+  allow_auto_merge: true,
+  delete_branch_on_merge: true,
+});
+
+export const NOTIFICATIONS_DEFAULTS = Object.freeze({
+  mentionOperator: false,
+  commentEvents: Object.freeze([
+    'state-transition',
+    'story-merged',
+    'operator-message',
+  ]),
+  webhookEvents: Object.freeze([
+    'epic-started',
+    'epic-progress',
+    'epic-blocked',
+    'epic-unblocked',
+    'epic-complete',
+  ]),
+});
+
+/**
+ * Read the merged `github.*` block. Accepts the full resolved config or
+ * the bare github bag. Operator-supplied keys shallow-overlay framework
+ * defaults; the required-checks list is replaced wholesale when present
+ * (no extender semantics).
+ *
+ * @param {object | null | undefined} config
+ * @returns {{
+ *   owner: string|null,
+ *   repo: string|null,
+ *   projectNumber: number|null,
+ *   projectOwner: string|null,
+ *   operatorHandle: string|null,
+ *   branchProtection: { enforce: boolean, requiredChecks: Array<{name:string,cmd:readonly string[]}> },
+ *   mergeMethods: typeof MERGE_METHODS_DEFAULTS,
+ *   notifications: typeof NOTIFICATIONS_DEFAULTS,
+ * }}
+ */
+export function getGitHub(config) {
+  const gh = config?.github ?? config ?? {};
+  const userBranchProtection =
+    gh.branchProtection && typeof gh.branchProtection === 'object'
+      ? gh.branchProtection
+      : {};
+  const userMergeMethods =
+    gh.mergeMethods && typeof gh.mergeMethods === 'object'
+      ? gh.mergeMethods
+      : {};
+  const userNotifications = gh.notifications ?? {};
+  return {
+    owner: gh.owner ?? null,
+    repo: gh.repo ?? null,
+    projectNumber: gh.projectNumber ?? null,
+    projectOwner: gh.projectOwner ?? null,
+    operatorHandle: gh.operatorHandle ?? null,
+    branchProtection: {
+      enforce:
+        typeof userBranchProtection.enforce === 'boolean'
+          ? userBranchProtection.enforce
+          : BRANCH_PROTECTION_DEFAULTS.enforce,
+      requiredChecks: Array.isArray(userBranchProtection.requiredChecks)
+        ? userBranchProtection.requiredChecks
+        : [...DEFAULT_REQUIRED_CHECKS],
+    },
+    mergeMethods: { ...MERGE_METHODS_DEFAULTS, ...userMergeMethods },
+    notifications: {
+      mentionOperator:
+        typeof userNotifications.mentionOperator === 'boolean'
+          ? userNotifications.mentionOperator
+          : NOTIFICATIONS_DEFAULTS.mentionOperator,
+      commentEvents: Array.isArray(userNotifications.commentEvents)
+        ? userNotifications.commentEvents
+        : [...NOTIFICATIONS_DEFAULTS.commentEvents],
+      webhookEvents: Array.isArray(userNotifications.webhookEvents)
+        ? userNotifications.webhookEvents
+        : [...NOTIFICATIONS_DEFAULTS.webhookEvents],
+    },
+  };
+}

package/.agents/scripts/lib/config/lifecycle.js

@@ -0,0 +1,40 @@
+/**
+ * `delivery.lifecycle` accessor + framework defaults.
+ *
+ * `TimeoutWatchdog` returns null (no budget) for any timeout key absent from
+ * the operator config, meaning phases can hang indefinitely on projects that
+ * omit the block. These defaults ensure every Epic run has a watchdog out of
+ * the box; projects override individual keys by supplying their own values,
+ * which are merged over the defaults.
+ */
+
+export const LIFECYCLE_DEFAULTS = Object.freeze({
+  timeouts: Object.freeze({
+    'acceptance.reconcile': 600,
+    'epic.finalize': 600,
+    'epic.watch': 1800,
+  }),
+  heartbeatWarnSeconds: 60,
+});
+
+/**
+ * Read the merged `delivery.lifecycle` block, applying framework defaults
+ * for any field the operator omitted. Accepts the full resolved config or
+ * a bare `{ delivery: { lifecycle: ... } }` / `{ lifecycle: ... }` shape.
+ *
+ * User-supplied timeout keys win over defaults; unknown keys are preserved
+ * so projects can define custom phase budgets.
+ *
+ * @param {object | null | undefined} config
+ * @returns {{ timeouts: Record<string, number>, heartbeatWarnSeconds: number }}
+ */
+export function getLifecycle(config) {
+  const lc = config?.delivery?.lifecycle ?? config?.lifecycle ?? config ?? {};
+  return {
+    timeouts: { ...LIFECYCLE_DEFAULTS.timeouts, ...(lc.timeouts ?? {}) },
+    heartbeatWarnSeconds:
+      Number.isInteger(lc.heartbeatWarnSeconds) && lc.heartbeatWarnSeconds >= 1
+        ? lc.heartbeatWarnSeconds
+        : LIFECYCLE_DEFAULTS.heartbeatWarnSeconds,
+  };
+}

package/.agents/scripts/lib/config/limits.js

@@ -0,0 +1,211 @@
+/**
+ * Limits/budgets/signals accessors (Epic #1720 Story #1739 — top-level reshape).
+ *
+ * Pre-reshape, every runtime ceiling lived under the legacy `agentSettings.limits.*` bag.
+ * Post-reshape, the surviving keys are split across `planning.*` and
+ * `delivery.*`:
+ *
+ *   - `planning.maxTickets` (decomposer ceiling)
+ *   - `planning.context.{maxBytes, summaryMode}` (planning-context budget)
+ *   - `delivery.maxTokenBudget` (task-prompt hydration cap)
+ *   - `delivery.execution.timeoutMs` (per-process execution timeout)
+ *   - `delivery.lease.ttlMs` (assignee-as-lease staleness window — Story #3480)
+ *   - `delivery.signals.{hotspot, rework, retry}` (performance-signal
+ *     detector thresholds — `churn` and `idle` dropped)
+ *
+ * Dropped entirely: `maxInstructionSteps`, `friction.*` (the LLM
+ * self-pacing thresholds rewritten as qualitative prose in
+ * `.agents/instructions.md`), `executionMaxBuffer` (now a framework-internal
+ * constant in the spawn caller modules), `signals.{churn, idle}`.
+ *
+ * The historic combined accessor `getLimits(config)` is preserved as a
+ * compatibility surface: it returns a wrapper carrying the surviving
+ * subset so existing call sites that destructured `getLimits` keep
+ * working. New call sites should prefer the specific accessors below.
+ */
+
+import { getPreflight } from './preflight.js';
+
+/**
+ * Framework defaults for the performance-signal detector thresholds. The two
+ * dropped detectors (`churn`, `idle`) are omitted entirely.
+ */
+export const SIGNALS_DEFAULTS = Object.freeze({
+  hotspot: Object.freeze({ p95Multiplier: 1.25 }),
+  rework: Object.freeze({ editsPerFile: 5 }),
+  retry: Object.freeze({ repeatCount: 3 }),
+});
+
+/**
+ * Default TTL for the assignee-as-lease primitive (Story #3480). A claim
+ * whose owner has not emitted a `story.heartbeat` within this window is
+ * considered stale and may be reclaimed by another operator. 15 minutes
+ * gives a healthy run comfortable headroom over the §2e idle watchdog's
+ * 10-minute re-tick while still releasing a genuinely dead claim promptly.
+ */
+export const LEASE_TTL_MS_DEFAULT = 900000;
+
+/**
+ * Framework defaults for the surviving limits surface. `executionTimeoutMs`
+ * bumps from 5 min to 10 min per the Story 1 decisions log.
+ *
+ * `maxTokenBudget` is a **single global value** (Story #3875 — raised once
+ * from 200000 to 300000 so capability-sized Stories are not clipped by
+ * hydration elision). There is intentionally no per-profile or
+ * per-complexity budget branch anywhere in the resolver.
+ */
+export const LIMITS_DEFAULTS = Object.freeze({
+  maxTickets: 60,
+  maxTokenBudget: 300000,
+  executionTimeoutMs: 600000,
+  leaseTtlMs: LEASE_TTL_MS_DEFAULT,
+  planningContext: Object.freeze({
+    maxBytes: 50000,
+    summaryMode: 'auto',
+  }),
+  signals: SIGNALS_DEFAULTS,
+});
+
+/**
+ * Per-detector merge of an operator-supplied `delivery.signals.*` block
+ * with framework defaults. Each detector is shallow-overlaid so an
+ * operator can override a single threshold without re-listing the others.
+ *
+ * @param {object|undefined} userSignals
+ * @returns {{ hotspot: {p95Multiplier: number}, rework: {editsPerFile: number}, retry: {repeatCount: number} }}
+ */
+function mergeSignals(userSignals) {
+  const user =
+    userSignals && typeof userSignals === 'object' ? userSignals : {};
+  const merged = {};
+  for (const detector of Object.keys(SIGNALS_DEFAULTS)) {
+    const userDetector =
+      user[detector] && typeof user[detector] === 'object'
+        ? user[detector]
+        : {};
+    merged[detector] = { ...SIGNALS_DEFAULTS[detector], ...userDetector };
+  }
+  return merged;
+}
+
+/**
+ * Resolve the surviving limits surface against a `.agentrc.json` shape
+ * (post-reshape). Accepts the resolved-config wrapper or a partial bag —
+ * pulls `maxTickets` and `planningContext` from `planning.*`, pulls
+ * `maxTokenBudget` and `executionTimeoutMs` from `delivery.*`, pulls
+ * signals from `delivery.signals.*`.
+ *
+ * @param {object|undefined} config
+ * @returns {{
+ *   maxTickets: number,
+ *   maxTokenBudget: number,
+ *   executionTimeoutMs: number,
+ *   leaseTtlMs: number,
+ *   planningContext: { maxBytes: number, summaryMode: string },
+ *   signals: ReturnType<typeof mergeSignals>,
+ * }}
+ */
+export function resolveLimits(config) {
+  const planning =
+    config?.planning && typeof config.planning === 'object'
+      ? config.planning
+      : {};
+  const delivery =
+    config?.delivery && typeof config.delivery === 'object'
+      ? config.delivery
+      : {};
+  const planningContextUser =
+    planning.context && typeof planning.context === 'object'
+      ? planning.context
+      : {};
+  const execution =
+    delivery.execution && typeof delivery.execution === 'object'
+      ? delivery.execution
+      : {};
+  const lease =
+    delivery.lease && typeof delivery.lease === 'object' ? delivery.lease : {};
+  return {
+    maxTickets: planning.maxTickets ?? LIMITS_DEFAULTS.maxTickets,
+    maxTokenBudget: delivery.maxTokenBudget ?? LIMITS_DEFAULTS.maxTokenBudget,
+    executionTimeoutMs:
+      execution.timeoutMs ?? LIMITS_DEFAULTS.executionTimeoutMs,
+    leaseTtlMs: lease.ttlMs ?? LIMITS_DEFAULTS.leaseTtlMs,
+    planningContext: {
+      ...LIMITS_DEFAULTS.planningContext,
+      ...planningContextUser,
+    },
+    signals: mergeSignals(delivery.signals),
+  };
+}
+
+/**
+ * Read the merged limits surface. Accepts the full resolved config bag.
+ * Returns the wrapper described in `resolveLimits`.
+ *
+ * @param {object | null | undefined} config
+ * @returns {ReturnType<typeof resolveLimits>}
+ */
+export function getLimits(config) {
+  return resolveLimits(config ?? undefined);
+}
+
+/**
+ * Read the merged `delivery.signals` block. Equivalent to
+ * `getLimits(config).signals` but exposed as a standalone accessor so
+ * detector wiring can import it without dragging the whole limits
+ * surface into their bundle.
+ *
+ * @param {object | null | undefined} config
+ * @returns {ReturnType<typeof resolveLimits>['signals']}
+ */
+export function getSignals(config) {
+  return getLimits(config).signals;
+}
+
+/**
+ * Resolve the configured `delivery.preflight.max*` ceilings as a plain
+ * object holding **only** the keys the operator actually configured
+ * (Story #3875 — plan-time/delivery-time reconciliation). Unconfigured
+ * ceilings (`null` floors, meaning "no cap") are omitted entirely so the
+ * decomposition context can thread a compact, non-null envelope to the
+ * planner. An Epic on a zero-config project yields `{}` — never `null`.
+ *
+ * @param {object | null | undefined} config
+ * @returns {Record<string, number>}
+ */
+export function resolvePreflightCeilings(config) {
+  const resolved = getPreflight(config);
+  const ceilings = {};
+  for (const [key, value] of Object.entries(resolved)) {
+    if (value !== null) ceilings[key] = value;
+  }
+  return ceilings;
+}
+
+/**
+ * Resolve the assignee-as-lease TTL in milliseconds (Story #3480). Standalone
+ * accessor so the `ticket-lease` module can import it without dragging the
+ * whole limits surface into its bundle. Precedence:
+ *
+ *   1. An explicit `override` (a positive finite number) — lets a caller or
+ *      test pin the TTL directly.
+ *   2. `delivery.lease.ttlMs` from the resolved config.
+ *   3. `LEASE_TTL_MS_DEFAULT`.
+ *
+ * A non-positive or non-finite override is ignored (falls through to config /
+ * default) so a stray `0` can never collapse every claim to instantly-stale.
+ *
+ * @param {object | null | undefined} config
+ * @param {number} [override]
+ * @returns {number}
+ */
+export function resolveLeaseTtlMs(config, override) {
+  if (
+    typeof override === 'number' &&
+    Number.isFinite(override) &&
+    override > 0
+  ) {
+    return override;
+  }
+  return getLimits(config).leaseTtlMs;
+}

package/.agents/scripts/lib/config/paths.js

@@ -0,0 +1,73 @@
+/**
+ * `project.paths` accessor (Epic #1720 Story #1739 — top-level reshape).
+ *
+ * The seven legacy `*Root` subdirectory keys and the legacy `auditOutputDir`
+ * were dropped — every `${dir}Root` is derived at runtime as
+ * `${agentRoot}/<dir>`, and `auditOutputDir` is derived as `${tempRoot}/audits`.
+ */
+
+/**
+ * Framework defaults for the derived path keys. `agentRoot`, `docsRoot`, and
+ * `tempRoot` are schema-required (no defaults — the resolver never silently
+ * fills them in); everything else is derived from the required roots and
+ * exposed here so call sites that previously read e.g.
+ * `paths.scriptsRoot` keep working byte-identically.
+ */
+export const PATHS_DEFAULTS = Object.freeze({
+  agentRoot: '.agents',
+  docsRoot: 'docs',
+  tempRoot: 'temp',
+});
+
+/**
+ * Resolve the merged `project.paths` block, deriving the legacy `*Root`
+ * subdirectory keys at runtime so existing call sites keep reading the
+ * same shape.
+ *
+ * @param {object|undefined} userPaths
+ * @returns {{
+ *   agentRoot: string,
+ *   docsRoot: string,
+ *   tempRoot: string,
+ *   auditOutputDir: string,
+ *   scriptsRoot: string,
+ *   workflowsRoot: string,
+ *   personasRoot: string,
+ *   schemasRoot: string,
+ *   skillsRoot: string,
+ *   templatesRoot: string,
+ *   rulesRoot: string,
+ * }}
+ */
+export function resolvePaths(userPaths) {
+  const paths = userPaths && typeof userPaths === 'object' ? userPaths : {};
+  const agentRoot = paths.agentRoot ?? PATHS_DEFAULTS.agentRoot;
+  const docsRoot = paths.docsRoot ?? PATHS_DEFAULTS.docsRoot;
+  const tempRoot = paths.tempRoot ?? PATHS_DEFAULTS.tempRoot;
+  return {
+    agentRoot,
+    docsRoot,
+    tempRoot,
+    // Derived: every `${dir}Root` lives directly under the framework's
+    // `agentRoot`; `auditOutputDir` lives under `tempRoot/audits`.
+    auditOutputDir: `${tempRoot}/audits`,
+    scriptsRoot: `${agentRoot}/scripts`,
+    workflowsRoot: `${agentRoot}/workflows`,
+    personasRoot: `${agentRoot}/personas`,
+    schemasRoot: `${agentRoot}/schemas`,
+    skillsRoot: `${agentRoot}/skills`,
+    templatesRoot: `${agentRoot}/templates`,
+    rulesRoot: `${agentRoot}/rules`,
+  };
+}
+
+/**
+ * Read the merged `project.paths` block. Accepts the full resolved config
+ * or a bare `{ project }` bag.
+ *
+ * @param {object | null | undefined} config
+ * @returns {ReturnType<typeof resolvePaths>}
+ */
+export function getPaths(config) {
+  return resolvePaths(config?.project?.paths);
+}

package/.agents/scripts/lib/config/preflight.js

@@ -0,0 +1,58 @@
+/**
+ * `delivery.preflight` accessor + framework defaults — Story #2899
+ * (Epic #2880, F13).
+ *
+ * Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`.
+ * The defaults are intentionally generous so that a brand-new Epic on a
+ * zero-config project does not trip a breach. Operators tighten thresholds
+ * per project in `.agentrc.json`. A `null` floor means "no cap" — used by
+ * the preflight runner to skip the corresponding breach check.
+ */
+
+export const PREFLIGHT_DEFAULTS = Object.freeze({
+  maxStories: null,
+  maxWaves: null,
+  maxInstallCostSeconds: null,
+  maxGithubApiRequests: null,
+  maxClaudeQuotaTokens: null,
+});
+
+/**
+ * Read the merged `delivery.preflight` block, applying framework defaults
+ * for any field the operator omitted. Accepts the full resolved config,
+ * the bare delivery bag, or the bare preflight bag.
+ *
+ * @param {object | null | undefined} config
+ * @returns {{
+ *   maxStories: number | null,
+ *   maxWaves: number | null,
+ *   maxInstallCostSeconds: number | null,
+ *   maxGithubApiRequests: number | null,
+ *   maxClaudeQuotaTokens: number | null,
+ * }}
+ */
+export function getPreflight(config) {
+  const pf = config?.delivery?.preflight ?? config?.preflight ?? config ?? {};
+  return {
+    maxStories: normaliseFloor(pf.maxStories, PREFLIGHT_DEFAULTS.maxStories),
+    maxWaves: normaliseFloor(pf.maxWaves, PREFLIGHT_DEFAULTS.maxWaves),
+    maxInstallCostSeconds: normaliseFloor(
+      pf.maxInstallCostSeconds,
+      PREFLIGHT_DEFAULTS.maxInstallCostSeconds,
+    ),
+    maxGithubApiRequests: normaliseFloor(
+      pf.maxGithubApiRequests,
+      PREFLIGHT_DEFAULTS.maxGithubApiRequests,
+    ),
+    maxClaudeQuotaTokens: normaliseFloor(
+      pf.maxClaudeQuotaTokens,
+      PREFLIGHT_DEFAULTS.maxClaudeQuotaTokens,
+    ),
+  };
+}
+
+function normaliseFloor(value, fallback) {
+  if (value === null) return null;
+  if (Number.isInteger(value) && value >= 1) return value;
+  return fallback;
+}