@staix/agent-hub 0.20.0 → 0.22.0

package/src/hub/sdlc-merge.ts

@@ -1,6 +1,8 @@
 import { findingsForHead, findingHead, findingTally } from "./review-findings.ts";
 import { readMergeQueue, type DeliveryTask, type MergeQueue } from "./sdlc-queue.ts";
-import { readSdlcPr, stageDefinition, type AutoMergeMode, type PrEvidence, type SdlcConfig, type SdlcGh, type MergeRecord } from "./sdlc.ts";
+import { evalGapBlockers, evalGateView, evalReportedGap, evalRequiredChecks, readEvalFor, type EvalResult } from "./eval-gate.ts";
+import { mergeCostFrom } from "./cost-governance.ts";
+import { readPrCostHistory, readSdlcPr, stageDefinition, type AutoMergeMode, type PrEvidence, type SdlcConfig, type SdlcGh, type MergeRecord } from "./sdlc.ts";
 
 /**
  * #786 T1/T2: the one guarded merge. Given a task and the head its reviewer approved, it re-reads the PR (`readSdlcPr`) and the merge queue
@@ -26,7 +28,7 @@ export interface MergeInput {
   run: SdlcGh;
   readableMetadata?: (path: string) => boolean;
   /** Final synchronous authority and queue-input fence, after fresh gates and immediately before the gh call. */
-  beforeMerge?: () => string | undefined;
+  beforeMerge?: (queue: MergeQueue | undefined) => string | undefined;
   /** Post-run host fence and durable progress record. False or a throw withholds cleanup. No remote text is supplied. */
   recordMerge?: (record: MergeRecord) => boolean;
   /**
@@ -55,7 +57,7 @@ const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
  * threads, draft). Its other blockers (identity, local gate, GitHub approval) are the lifecycle's, not this merge's, and are not repeated here.
  */
 const QUEUE_BLOCKERS = [/^touching PRs require a person order$/, /^dependency /, /^artifact dependency cycle/, /^open PR /, /^PR file coverage is incomplete/,
-  /^required check .*: not successful on current head$/, /^review requests pending or unknown$/, /^review threads unresolved or unknown$/, /^PR is draft or draft status unknown$/];
+  /^required check .*: not successful on current head$/, /^review requests pending or unknown$/, /^review threads unresolved or unknown$/, /^PR is draft or draft status is unknown$/];
 
 /** The mode that applies to one repository: its own table first, then the top-level key, default off. */
 export function mergeModeFor(config: SdlcConfig, repo: string | undefined): AutoMergeMode {
@@ -78,10 +80,10 @@ export function assertMergeArgv(argv: readonly string[], head: string): void {
   if (!shape) throw new Error("refusing a merge argv outside the guarded shape");
 }
 
-function checkGates(evidence: PrEvidence, required: readonly string[]): string[] {
+function checkGates(evidence: PrEvidence, required: readonly string[], extra: readonly string[] = []): string[] {
   if (!required.length) return ["required checks unknown: name them in sdlc.toml"];
   const gates: string[] = [];
-  for (const name of required) {
+  for (const name of [...new Set([...required, ...extra])]) {
     const matches = evidence.checks.filter(check => check.name === name);
     const state = !matches.length ? "missing" : matches.some(c => c.state === "failed") ? "failing" : matches.some(c => c.state === "pending") ? "pending" : matches.some(c => c.state !== "passed") ? "unknown" : undefined;
     if (state) gates.push(`required check ${name}: ${state}`);
@@ -112,18 +114,18 @@ function dropEchoes(gates: string[]): string[] {
     if (check) return !named(new RegExp(`^required check ${check[1]!.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}: `));
     if (gate === "queue: review requests pending or unknown") return !named(/review requests? (unknown|pending)|^\d+ review requests? pending$/);
     if (gate === "queue: review threads unresolved or unknown") return !named(/review threads unknown|unresolved review thread/);
-    if (gate === "queue: PR is draft or draft status unknown") return !named(/^draft /);
+    if (gate === "queue: PR is draft or draft status is unknown") return !named(/^draft /);
     return true;
   });
 }
 
 /** The gates one reading of the PR can fail. Run on every reading this decision takes, so a gate that changes between reads is never judged on the older one. */
-function evidenceGates(evidence: PrEvidence, approved: string | undefined, required: readonly string[]): string[] {
+function evidenceGates(evidence: PrEvidence, approved: string | undefined, required: readonly string[], extra: readonly string[] = []): string[] {
   const gates: string[] = [];
   if (approved && evidence.head !== approved) gates.push(`head changed: reviewed ${approved.slice(0, 8)}, PR is at ${evidence.head.slice(0, 8)}`);
   if (evidence.state !== "OPEN") gates.push(`PR is ${evidence.state.toLowerCase()}`);
   if (evidence.draft !== false) gates.push("draft (or draft status unknown)");
-  gates.push(...checkGates(evidence, required));
+  gates.push(...checkGates(evidence, required, extra));
   if (evidence.review === "changes_requested") gates.push("change request pending");
   if (evidence.pendingReviews === null) gates.push("review requests unknown");
   else if (evidence.pendingReviews > 0) gates.push(`${evidence.pendingReviews} review request${evidence.pendingReviews === 1 ? "" : "s"} pending`);
@@ -151,11 +153,22 @@ export function localGates(input: { subject: DeliveryTask; state: string; taskSt
   return gates;
 }
 
+/**
+ * #481 S5: in enforce, a configuration PR whose eval check passed but reported no pass rate or suite version, or whose file coverage is unknown, does not merge.
+ * Advise and off add nothing here. Synchronous on purpose: the result is read before the final PR read, so judging the last reading awaits nothing remote.
+ * A result read for another head is ignored by the view, and a passed check with no result read at all counts as unreported (the PR moved into scope after the read).
+ */
+function evalGaps(config: SdlcConfig, evidence: PrEvidence, result: EvalResult | undefined): string[] {
+  if (config.mode !== "enforce") return [];
+  const view = evalGateView(config, evidence, result);
+  return [...new Set([...evalGapBlockers(view), ...(view?.state === "passed" && !result && view.check ? [evalReportedGap(view.check)] : [])])];
+}
+
 /**
  * Every failing gate, never the first only: a person reading a refusal fixes them in one pass. Unknown evidence is a failing gate, never a pass.
  * `approvedHead` is the head the reviewer's verdict recorded (`receipt.reviewedHead`); a head that moved since is `head changed`.
  */
-export async function decideMerge(input: MergeInput): Promise<MergeDecision> {
+export async function decideMerge(input: MergeInput, seen?: { queue?: MergeQueue }): Promise<MergeDecision> {
   const { subject, config, run } = input, receipt = subject.receipt, repo = receipt?.repo, pr = receipt?.pr, approved = receipt?.reviewedHead;
   const gates: string[] = [];
   if (subject.private) return { refused: ["private task: a person merges"] };
@@ -164,16 +177,19 @@ export async function decideMerge(input: MergeInput): Promise<MergeDecision> {
   const evidence = await readSdlcPr(receipt, run);
   if (!evidence) return { refused: [...gates, "PR evidence unavailable"] };
   const required = requiredChecksFor(config, repo);
-  gates.push(...evidenceGates(evidence, approved, required));
+  // The eval metadata is read before the final PR read, never after it: nothing remote is awaited between the last reading and its judgment.
+  const evalResult = config.mode === "enforce" ? await readEvalFor(config, evidence, repo, run) : undefined;
+  gates.push(...evidenceGates(evidence, approved, required, evalRequiredChecks(config, evidence)), ...evalGaps(config, evidence, evalResult));
   gates.push(...localGates({ subject, state: input.state, taskState: input.taskState, config, head: evidence.head }));
   let queue: MergeQueue | undefined;
   try { queue = await readMergeQueue(repo, config, input.tasks, run, input.readableMetadata); } catch { queue = undefined; }
+  if (seen) seen.queue = queue;   // `guardedMerge` hands it to the final fence: that fence compares the board links this queue read and no others (#491)
   gates.push(...queueGates(queue, pr));
   // The queue read newer evidence than the first read. Read the PR once more, last, and judge every gate on it too: a check, review request, thread, draft or
   // head that moved between the reads refuses here. `--match-head-commit` pins the head only, never these gates.
   const last = await readSdlcPr(receipt, run);
   if (!last) gates.push("PR evidence unavailable on the final read");
-  else { gates.push(...evidenceGates(last, approved, required)); gates.push(...localGates({ subject, state: input.state, taskState: input.taskState, config, head: last.head })); }
+  else { gates.push(...evidenceGates(last, approved, required, evalRequiredChecks(config, last)), ...evalGaps(config, last, evalResult)); gates.push(...localGates({ subject, state: input.state, taskState: input.taskState, config, head: last.head })); }
   const row = queue?.rows.find(r => r.pr === pr);
   if (row?.head !== undefined && approved && row.head !== approved && !gates.some(g => g.startsWith("head changed"))) gates.push(`head changed: the queue read ${row.head.slice(0, 8)}`);
   if (gates.length) return { refused: dropEchoes([...new Set(gates)]) };
@@ -204,7 +220,8 @@ export function dispatchGates(input: Pick<MergeInput, "subject" | "taskState"> &
  */
 export async function guardedMerge(input: MergeInput & { mode: AutoMergeMode }): Promise<MergeOutcome> {
   if (input.mode === "off") return { mode: "off", decision: { refused: ["auto_merge is off for this repository"] }, ran: false };
-  const decision = await decideMerge(input);
+  const seen: { queue?: MergeQueue } = {};
+  const decision = await decideMerge(input, seen);
   if (!("action" in decision) || input.mode !== "on") return { mode: input.mode, decision, ran: false };
   // ---- synchronous dispatch segment: no await from here to the call to `run` ----
   assertMergeArgv(decision.argv, decision.head);
@@ -213,7 +230,7 @@ export async function guardedMerge(input: MergeInput & { mode: AutoMergeMode }):
     if (refused.length) return { mode: input.mode, decision: { refused }, ran: false };
   }
   let started: Promise<{ code: number; stdout: string }>;
-  const moved = input.beforeMerge?.();
+  const moved = input.beforeMerge?.(seen.queue);
   if (moved) return { mode: input.mode, decision: { refused: [moved] }, ran: false };
   try { started = Promise.resolve(input.run(decision.argv, 10_000)); } catch { started = Promise.resolve({ code: 1, stdout: "" }); }
   // ---- end of the synchronous segment ----
@@ -236,7 +253,14 @@ export async function guardedMerge(input: MergeInput & { mode: AutoMergeMode }):
   }
   const result: NonNullable<MergeOutcome["result"]> = after?.state === "MERGED" ? {exit,state:"merged",...(after.mergeCommit?{mergeCommit:after.mergeCommit}:{})} : after ? {exit,state:"not_merged"} : {exit,state:"unknown"};
   if (input.recordMerge) {
-    let record: MergeRecord={repo:decision.repo,pr:decision.pr,head:decision.head,at:Date.now(),...result,cleanup:"not_started",ownerNotice:"not_started"};
+    // #481 S7: the merged PR's review and CI figures, read once now that the merge is observed. After the merge there is nothing left to race, so this await is fine;
+    // its own bound keeps a slow GitHub from holding the record, and a failed read records no cost (unknown), never a zero.
+    const costDeadline = performance.now() + 8000;
+    const cost = result.state === "merged" ? await readPrCostHistory(decision.repo, decision.pr, (args, timeout, cwd, cap) => {
+      const left = costDeadline - performance.now();
+      return left > 0 ? input.run(args, Math.min(timeout ?? 10_000, left), cwd, cap) : Promise.resolve({ code: 1, stdout: "" });
+    }).then(mergeCostFrom, () => undefined) : undefined;
+    let record: MergeRecord={repo:decision.repo,pr:decision.pr,head:decision.head,at:Date.now(),...result,...(cost?{cost}:{}),cleanup:"not_started",ownerNotice:"not_started"};
     const save = () => {try {return input.recordMerge!({...record});}catch{return false;}};
     if (!save()) {record={...record,cleanup:"skipped",reason:"authority_changed"};save();}
     else if (result.state!=="merged" || !result.mergeCommit) {record={...record,cleanup:"skipped",reason:result.state==="merged"?"missing_commit":"not_merged"};save();}

package/src/hub/sdlc-metrics.ts

@@ -2,8 +2,11 @@
 // A metric that cannot be derived is `unknown` and counted as such, never 0.
 // `first_pass_check` reads the hub's own completion check (`check passed` / `check failed` at hub_task_done), not PR CI: it is unknown where completion checks are off.
 
-export const BAND_METRICS = ["acceptance_to_plan_ms", "acceptance_to_first_review_ms", "first_pass_approval", "rework_rounds", "first_pass_check", "stale_head_re_reviews"] as const;
+export const BAND_METRICS = ["acceptance_to_plan_ms", "acceptance_to_first_review_ms", "first_pass_approval", "rework_rounds", "first_pass_check", "stale_head_re_reviews", "hotfix_rate", "security_open_alerts"] as const;
 export type BandMetric = typeof BAND_METRICS[number];
+/** Metrics whose series is not made of tasks: one value per shipped release (`hotfix_rate`, 1 for a hotfix) or per recorded security scan (`security_open_alerts`). The caller supplies them; the point's `task` is then a release or scan id. */
+export const EXTERNAL_METRICS: readonly BandMetric[] = ["hotfix_rate", "security_open_alerts"];
+export type SeriesPoint = { value: number; task: number };
 export const BAND_TIERS = ["ok", "log", "diagnose", "propose"] as const;
 export type BandTier = typeof BAND_TIERS[number];
 
@@ -30,6 +33,10 @@ export interface TaskSample {
   first_pass_check: 0 | 1 | null;
   same_head_ci_reruns: number | null;
   stale_head_re_reviews: number | null;
+  /** #481 S7 merge-time readback: review handoffs (dones) up to the merge, CI runs of the merged PR and GitHub reviews on it. Null where the merge was not read. */
+  review_rounds_at_merge: number | null;
+  ci_runs_at_merge: number | null;
+  github_reviews_at_merge: number | null;
 }
 
 export interface Summary { n: number; unknown: number; mean: number | null; median: number | null; p90: number | null; max: number | null }
@@ -50,20 +57,23 @@ export interface BandResult {
   lastTask: number | null;
   /** The task whose value started the run of non-ok values this one belongs to, else null: one breach episode has one card. */
   episode: number | null;
+  /** What `lastTask` and `episode` number: a task unless the metric is an external series (a release or a security scan). */
+  subject?: "task" | "release" | "scan";
 }
+export const SUBJECT: Partial<Record<BandMetric, "release" | "scan">> = { hotfix_rate: "release", security_open_alerts: "scan" };
 
 /** Which way is worse. A rate that falls and a time that grows are both breaches. */
 export const BAD_DIRECTION: Record<BandMetric, "up" | "down"> = {
-  acceptance_to_plan_ms: "up", acceptance_to_first_review_ms: "up", first_pass_approval: "down", rework_rounds: "up", first_pass_check: "down", stale_head_re_reviews: "up",
+  acceptance_to_plan_ms: "up", acceptance_to_first_review_ms: "up", first_pass_approval: "down", rework_rounds: "up", first_pass_check: "down", stale_head_re_reviews: "up", hotfix_rate: "up", security_open_alerts: "up",
 };
 const HOUR = 3_600_000;
 /** Per-metric floor on the absolute deviation, so a flat baseline does not make every wobble a breach. */
 export const DEFAULT_MIN_DELTA: Record<BandMetric, number> = {
-  acceptance_to_plan_ms: HOUR, acceptance_to_first_review_ms: HOUR, first_pass_approval: 0.5, rework_rounds: 1, first_pass_check: 0.5, stale_head_re_reviews: 1,
+  acceptance_to_plan_ms: HOUR, acceptance_to_first_review_ms: HOUR, first_pass_approval: 0.5, rework_rounds: 1, first_pass_check: 0.5, stale_head_re_reviews: 1, hotfix_rate: 0.5, security_open_alerts: 1,
 };
 /** Per-metric floor on the baseline deviation: a flat baseline (every value the same) must not turn one step into thousands of deviations. */
 export const SD_FLOOR: Record<BandMetric, number> = {
-  acceptance_to_plan_ms: HOUR / 2, acceptance_to_first_review_ms: HOUR / 2, first_pass_approval: 0.5, rework_rounds: 0.5, first_pass_check: 0.5, stale_head_re_reviews: 0.5,
+  acceptance_to_plan_ms: HOUR / 2, acceptance_to_first_review_ms: HOUR / 2, first_pass_approval: 0.5, rework_rounds: 0.5, first_pass_check: 0.5, stale_head_re_reviews: 0.5, hotfix_rate: 0.5, security_open_alerts: 0.5,
 };
 export const DEFAULT_BAND: Omit<BandConfig, "minDelta"> = { window: 20, minSamples: 8, logSigma: 2, diagnoseSigma: 3, proposeSigma: 4, driftRun: 6 };
 
@@ -91,7 +101,7 @@ function staleHeadRounds(history: MetricTask["history"]): number | null {
 }
 
 /** One task's values from its own history. A private task never reaches here. */
-export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciReruns?: number | null } = {}): TaskSample {
+export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciReruns?: number | null; ciRuns?: number | null; reviews?: number | null } = {}): TaskSample {
   const history = [...task.history].filter(entry => Number.isFinite(entry.at) && entry.at >= 0).sort((a, b) => a.at - b.at);
   const view: MetricTask = { id: task.id, history };
   const accepted = first(view, ["accepted"]);
@@ -116,6 +126,10 @@ export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciRerun
     rework_rounds: dones.length && approvedAt !== null ? history.filter(entry => entry.event === "changes_requested" && entry.evidenceOnly !== true).length : null,
     first_pass_check: ci ? (ci.event === "check passed" ? 1 : 0) : null,
     same_head_ci_reruns: extra.ciReruns === undefined ? null : extra.ciReruns,
+    // Counted only for a merged PR whose figures were read: a done before the merge is one review round.
+    review_rounds_at_merge: extra.mergedAt !== undefined && Number.isFinite(extra.mergedAt) ? dones.filter(entry => entry.at <= extra.mergedAt!).length : null,
+    ci_runs_at_merge: extra.ciRuns === undefined ? null : extra.ciRuns,
+    github_reviews_at_merge: extra.reviews === undefined ? null : extra.reviews,
     stale_head_re_reviews: approvedAt !== null ? staleHeadRounds(history) : null,
   };
 }
@@ -131,7 +145,8 @@ export function summarize(values: readonly (number | null)[]): Summary {
 const round = (value: number) => Math.round(value * 1000) / 1000;
 
 /** The values of one metric in the order they happened, unknown ones left out. */
-export function series(samples: readonly TaskSample[], metric: BandMetric): { value: number; task: number }[] {
+export type TaskMetric = Exclude<BandMetric, "hotfix_rate" | "security_open_alerts">;
+export function series(samples: readonly TaskSample[], metric: TaskMetric): SeriesPoint[] {
   const final = metric === "rework_rounds" || metric === "stale_head_re_reviews";
   const when = (sample: TaskSample) => final ? sample.approved_at ?? sample.at : sample.at;
   return [...samples].sort((a, b) => when(a) - when(b) || a.id - b.id).flatMap(sample => sample[metric] === null ? [] : [{ value: sample[metric] as number, task: sample.id }]);
@@ -172,7 +187,8 @@ export const EPISODE_LOOKBACK = 200;
  * key for as long as it lasts, and it is derived from history alone, so it survives a restart.
  */
 export function controlEpisode(points: readonly { value: number; task: number }[], metric: BandMetric, config: BandConfig): BandResult {
-  const now = controlBands(points, metric, config);
+  const subject = SUBJECT[metric];
+  const now = { ...controlBands(points, metric, config), ...(subject ? { subject } : {}) };
   if (now.tier === "ok") return now;
   let start = points.length - 1;
   for (let end = points.length - 2; end >= 0 && points.length - 1 - end <= EPISODE_LOOKBACK; end--) {
@@ -193,7 +209,10 @@ export interface MetricsReport {
     first_pass_check: { n: number; unknown: number; rate: number | null };
     same_head_ci_reruns: Summary;
     stale_head_re_reviews: Summary;
+    review_rounds_at_merge: Summary; ci_runs_at_merge: Summary; github_reviews_at_merge: Summary;
   };
+  /** Merged PRs whose review and CI figures were read at merge, and how many of the counted tasks have none (unknown, never 0). */
+  merged: { read: number; unknown: number };
   stalls: StallCounts;
   bands: BandResult[] | "off";
 }
@@ -207,12 +226,12 @@ const rate = (values: readonly (number | null)[]) => {
  * The whole report from board tasks. `since` keeps samples that count at or after it; `mergedAt` and `ciReruns` come from bounded
  * PR readbacks keyed by task id and are optional. Private tasks are counted as withheld and read for nothing else.
  */
-export function sdlcMetrics(tasks: readonly MetricTask[], opts: { since?: number; bands?: BandsConfig; stalls?: StallCounts; mergedAt?: Readonly<Record<number, number>>; ciReruns?: Readonly<Record<number, number | null>> } = {}): MetricsReport {
+export function sdlcMetrics(tasks: readonly MetricTask[], opts: { since?: number; bands?: BandsConfig; stalls?: StallCounts; mergedAt?: Readonly<Record<number, number>>; ciReruns?: Readonly<Record<number, number | null>>; ciRuns?: Readonly<Record<number, number | null>>; reviews?: Readonly<Record<number, number | null>>; external?: Partial<Record<BandMetric, readonly SeriesPoint[]>> } = {}): MetricsReport {
   const visible = tasks.filter(task => !task.private);
-  const all = visible.map(task => taskSample(task, { mergedAt: opts.mergedAt?.[task.id], ciReruns: opts.ciReruns?.[task.id] }));
+  const all = visible.map(task => taskSample(task, { mergedAt: opts.mergedAt?.[task.id], ciReruns: opts.ciReruns?.[task.id], ciRuns: opts.ciRuns?.[task.id], reviews: opts.reviews?.[task.id] }));
   const samples = opts.since === undefined ? all : all.filter(sample => sample.at >= opts.since!);
   const bands: BandResult[] | "off" = opts.bands && Object.keys(opts.bands).length
-    ? BAND_METRICS.flatMap(metric => opts.bands![metric] ? [controlEpisode(series(samples, metric), metric, opts.bands![metric]!)] : [])
+    ? BAND_METRICS.flatMap(metric => opts.bands![metric] ? [controlEpisode(EXTERNAL_METRICS.includes(metric) ? [...(opts.external?.[metric] ?? [])] : series(samples, metric as TaskMetric), metric, opts.bands![metric]!)] : [])
     : "off";
   return {
     since: opts.since ?? null, tasks: samples.length, withheldPrivate: tasks.length - visible.length,
@@ -222,7 +241,10 @@ export function sdlcMetrics(tasks: readonly MetricTask[], opts: { since?: number
       first_pass_approval: rate(samples.map(s => s.first_pass_approval)), rework_rounds: summarize(samples.map(s => s.rework_rounds)),
       first_pass_check: rate(samples.map(s => s.first_pass_check)), same_head_ci_reruns: summarize(samples.map(s => s.same_head_ci_reruns)),
       stale_head_re_reviews: summarize(samples.map(s => s.stale_head_re_reviews)),
+      review_rounds_at_merge: summarize(samples.map(s => s.review_rounds_at_merge)), ci_runs_at_merge: summarize(samples.map(s => s.ci_runs_at_merge)),
+      github_reviews_at_merge: summarize(samples.map(s => s.github_reviews_at_merge)),
     },
+    merged: { read: samples.filter(s => s.ci_runs_at_merge !== null || s.github_reviews_at_merge !== null).length, unknown: samples.filter(s => s.ci_runs_at_merge === null && s.github_reviews_at_merge === null).length },
     stalls: opts.stalls ?? { open: 0, byKind: {}, doneWithoutWrites: 0 }, bands,
   };
 }

package/src/hub/sdlc-queue.ts

@@ -1,10 +1,11 @@
 import { publicTestIntegrity, parseIssueLabels, readTestIntegrity, testIntegrityBlockers, type TestIntegrity } from "./test-integrity.ts";
 import { planConformance, planConformanceBlockers } from "./plan-conformance.ts";
+import { evalGapBlockers, evalGateView, readEvalFor, type EvalGate } from "./eval-gate.ts";
 import { findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CriteriaView } from "./workflow.ts";
 import { parsePrEvidence, readSdlcPr, sdlcGh, sdlcStatus, type PrEvidence, type SdlcConfig, type SdlcGh, type SdlcReceipt } from "./sdlc.ts";
 export interface DeliveryTask { plan?: { paths?: string[]; revision: number; fingerprint: string; accepted: { repo: string; pr: number; head: string; revision: number; fingerprint: string; paths: string[] }[] }; findings?: readonly ReviewFindingSet[]; id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView; }
-export interface MergeQueueRow { testIntegrity?: (TestIntegrity & { task?: number })[]; planConformance?: { task?: number; state: string; outside: number; untouched: number; accepted: boolean }[]; findings?: ReviewFindingTally; pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
+export interface MergeQueueRow { evalGate?: EvalGate; testIntegrity?: (TestIntegrity & { task?: number })[]; planConformance?: { task?: number; state: string; outside: number; untouched: number; accepted: boolean }[]; findings?: ReviewFindingTally; pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
 export interface MergeConflict { left: number; right: number; files: number; order: "dependency" | "person_required"; }
 export interface MergeQueue { repo: string; rows: MergeQueueRow[]; order: number[]; unordered?: number[]; conflicts: MergeConflict[]; complete: boolean; truncated: boolean; }
 const validRepo = (value: string) => /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
@@ -93,6 +94,11 @@ export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: De
       const integrity = rawIntegrity ? publicTestIntegrity(rawIntegrity, readableMetadata) : undefined;
       if (integrity) (row.testIntegrity ??= []).push({ task: holder!.id, ...integrity });
       row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+      // #481 S5: the eval check itself is a required check inside sdlcStatus; its recorded pass rate and suite are read once per PR here.
+      if (!row.evalGate) {
+        const gate = evalGateView(config, read, await readEvalFor(config, read, repo, bounded));
+        if (gate) { row.evalGate = gate; if (config.mode === "enforce") row.blockers.push(...evalGapBlockers(gate)); }
+      }
       if (config.mode === "enforce") row.blockers.push(...planConformanceBlockers(conformance), ...testIntegrityBlockers(integrity));
     }
   }

package/src/hub/sdlc-release.ts

@@ -21,7 +21,7 @@ const sdlcGh: SdlcGh = async (...args) => {
   catch { return { code: 1, stdout: "" }; }
 };
 export interface DocEvidence { schemaVersion: 1; head?: string; version?: string; documents: { path?: string; state: "fresh" | "stale" | "nonancestor" | "unknown"; verifiedAgainst?: string; commits?: number; dirty?: boolean }[]; errors: number; fresh: boolean; }
-export interface ReleaseReadiness { repo: string; head?: string; version?: string; tag?: string; tagCommit?: string; commits: string[]; mergedPrs: { pr: number; commit: string }[]; documents?: DocEvidence; liveIssues: { id: number; state: "open" | "closed" | "unknown" }[]; blockers: string[]; sourceReady: boolean; native: "unverified"; ready: false; }
+export interface ReleaseReadiness { /** #481 AC12: interval, approval-to-release lead time and hotfix rate over shipped releases, filled by Tasks.releaseReadiness. */ releaseMetrics?: ReturnType<typeof releaseMetrics>; repo: string; head?: string; version?: string; tag?: string; tagCommit?: string; commits: string[]; mergedPrs: { pr: number; commit: string }[]; documents?: DocEvidence; liveIssues: { id: number; state: "open" | "closed" | "unknown" }[]; blockers: string[]; sourceReady: boolean; native: "unverified"; ready: false; }
 export type ReleaseGit = (args: string[]) => { code: number; stdout: string };
 export interface ReleaseReaders { gh?: SdlcGh; git?: ReleaseGit; docs?: (root: string, timeoutMs: number) => Promise<DocEvidence | undefined>; }
 const SHA = /^[0-9a-f]{40}$/;

package/src/hub/sdlc.ts

@@ -3,6 +3,8 @@ import { planConformanceBlockers, type PlanConformance } from "./plan-conformanc
 import { DEFAULT_MAX_NITS, findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CostPlan } from "./cost-governance.ts";
 import { bandsConfig, type BandsConfig } from "./sdlc-metrics.ts";
+import { configPathList, evalGapBlockers, evalGateView, evalRequiredChecks, type EvalGate, type EvalResult } from "./eval-gate.ts";
+import { SECURITY_SOURCES, type SecuritySource } from "./security-baseline.ts";
 import { criteriaReceipt, type CriteriaReceipt, type CriteriaView, type LegacyPhaseReceipt } from "./workflow.ts";
 import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
 import { join } from "node:path";
@@ -36,9 +38,11 @@ export type SdlcMode = "off" | "advise" | "enforce";
 /** #786: `off` never merges, `dry-run` reports the decision and runs nothing, `on` runs the guarded `gh pr merge`. */
 export type AutoMergeMode = "off" | "dry-run" | "on";
 export const AUTO_MERGE_MODES: readonly AutoMergeMode[] = ["off", "dry-run", "on"];
+/** #481 S7: which GitHub alert sources the scan reads, how often, and for which repository (absent: the project repository). */
+export interface SecurityScanConfig { everyH: number; sources: SecuritySource[]; repo?: string }
 /** #786: one repository's own gate: its required checks (before the top-level list) and its own merge mode. */
 export interface RepoMergePolicy { requiredChecks?: string[]; autoMerge?: AutoMergeMode }
-export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; /** #481 S7: optional control bands per metric; absent means none. */ bands?: BandsConfig; mode: SdlcMode; requiredChecks: string[]; /** #786: absent reads as "off"; written only when the file names it. */ autoMerge?: AutoMergeMode; /** #786: per-repository tables, keyed by lowercase owner/name. */ repos?: Record<string, RepoMergePolicy>; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
+export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; /** #481 S7: optional control bands per metric; absent means none. */ bands?: BandsConfig; /** #481 S7: the scheduled security-scan baseline; absent means none is scheduled. */ securityScan?: SecurityScanConfig; /** #481 S5: the one check a configuration PR needs; no default, the person names it. */ evalCheck?: string; /** #481 S5: patterns that mark a PR as a configuration change; absent reads as the defaults in eval-gate.ts, an empty list turns the gate off. */ configPaths?: string[]; mode: SdlcMode; requiredChecks: string[]; /** #786: absent reads as "off"; written only when the file names it. */ autoMerge?: AutoMergeMode; /** #786: per-repository tables, keyed by lowercase owner/name. */ repos?: Record<string, RepoMergePolicy>; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
 export interface PlanReviewReceipt {
   planner: string;
   planAuthor?: string | null;
@@ -56,6 +60,8 @@ export interface MergeRecord {
   cleanup: "not_started" | "claimed" | "deleted" | "already_gone" | "skipped" | "unknown";
   reason?: "not_merged" | "missing_commit" | "metadata_unknown" | "identity_changed" | "protected_branch" | "default_branch" | "head_changed" | "authority_changed" | "delete_unconfirmed";
   ownerNotice: "not_started" | "claimed" | "sent" | "unknown";
+  /** #481 S7: the merged PR's review and CI figures, read once at merge by the host. Absent when the PR could not be read; fields inside are null when unknown. */
+  cost?: import("./cost-governance.ts").MergeCost;
 }
 export interface SdlcReceipt {
   merge?: MergeRecord;
@@ -152,6 +158,22 @@ const checkList = (value: unknown, what: string): string[] => {
   if (!Array.isArray(value) || value.length > 32 || value.some(c => typeof c !== "string" || !c.trim() || c.length > 120 || /[\r\n\x00-\x1f]/.test(c)) || new Set(value).size !== value.length) throw new Error(`${what}: expected at most 32 unique nonempty names`);
   return [...value] as string[];
 };
+const evalCheckName = (value: unknown): string => {
+  if (typeof value !== "string" || !value.trim() || value.length > 120 || /[\r\n\x00-\x1f]/.test(value)) throw new Error("sdlc.eval_check: expected one nonempty check name");
+  return value;
+};
+const securityScanConfig = (value: unknown): SecurityScanConfig => {
+  const fail = (path: string, why: string): never => { throw new Error(`sdlc.security_scan${path}: ${why}`); };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail("", "expected a table");
+  const raw = value as Record<string, unknown>;
+  for (const key of Object.keys(raw)) if (!["every_h", "sources", "repo"].includes(key)) fail(`.${key}`, "unknown field");
+  const everyH = raw.every_h === undefined ? 24 : raw.every_h;
+  if (typeof everyH !== "number" || !Number.isSafeInteger(everyH) || everyH < 1 || everyH > 720) fail(".every_h", "expected an integer number of hours from 1 to 720");
+  const sources = raw.sources;
+  if (!Array.isArray(sources) || !sources.length || sources.length > SECURITY_SOURCES.length || new Set(sources).size !== sources.length || sources.some(s => !SECURITY_SOURCES.includes(s as SecuritySource))) fail(".sources", `expected a nonempty list of unique names from ${SECURITY_SOURCES.join(", ")}; the scan has no default source`);
+  if (raw.repo !== undefined && !repo(raw.repo)) fail(".repo", "expected owner/repository");
+  return { everyH: everyH as number, sources: [...sources as SecuritySource[]], ...(raw.repo === undefined ? {} : { repo: raw.repo as string }) };
+};
 const autoMergeMode = (value: unknown, what: string): AutoMergeMode => {
   if (!AUTO_MERGE_MODES.includes(value as AutoMergeMode)) throw new Error(`${what}: expected off, dry-run or on`);
   return value as AutoMergeMode;
@@ -178,11 +200,15 @@ export function sdlcConfig(value: unknown, version?: string): SdlcConfig {
   if (value === undefined) return { mode: "off", requiredChecks: [], stages: [...SDLC_STAGES] };
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc: expected a table");
   const raw = value as Record<string, unknown>;
-  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions", "max_nits", "bands", "auto_merge", "repos"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
+  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions", "max_nits", "bands", "auto_merge", "repos", "eval_check", "config_paths", "security_scan"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
   const maxNits = raw.max_nits === undefined ? DEFAULT_MAX_NITS : raw.max_nits;
   if (typeof maxNits !== "number" || !Number.isSafeInteger(maxNits) || maxNits < 0 || maxNits > 64) throw new Error("sdlc.max_nits: expected an integer from 0 to 64");
   const bands = bandsConfig(raw.bands), bandConfig = Object.keys(bands).length ? { bands } : {};
-  const findingConfig = { ...(raw.max_nits === undefined ? {} : { maxNits }), ...bandConfig };
+  const evalConfig = {
+    ...(raw.eval_check === undefined ? {} : { evalCheck: evalCheckName(raw.eval_check) }),
+    ...(raw.config_paths === undefined ? {} : { configPaths: configPathList(raw.config_paths, "sdlc.config_paths") }),
+  };
+  const findingConfig = { ...(raw.max_nits === undefined ? {} : { maxNits }), ...bandConfig, ...evalConfig, ...(raw.security_scan === undefined ? {} : { securityScan: securityScanConfig(raw.security_scan) }) };
   const mode = raw.mode ?? "off";
   if (mode !== "off" && mode !== "advise" && mode !== "enforce") throw new Error("sdlc.mode: expected off, advise or enforce");
   // ponytail: the #481 S8 window is a fixed version; delete `workflow`, the phase aliases and their tests once it passes.
@@ -336,12 +362,13 @@ export const SPEC_STATE_TEXT: Record<Exclude<SpecState, "current">, string> = {
   changed: "spec changed after acceptance: the person re-accepts with ahub sdlc accept <task> --issue <n>",
   unknown: "spec edit time unknown: the issue could not be read",
 };
-export interface SdlcStatus { testIntegrity?: TestIntegrity; planConformance?: PlanConformance & { accepted?: boolean; earlierPushes?: "unknown"; revisionsAfterFirstObservedPush?: number }; findings?: ReviewFindingTally; spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
+export interface SdlcStatus { evalGate?: EvalGate; testIntegrity?: TestIntegrity; planConformance?: PlanConformance & { accepted?: boolean; earlierPushes?: "unknown"; revisionsAfterFirstObservedPush?: number }; findings?: ReviewFindingTally; spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
 /** The acceptance-criteria checklist (#481 S8, Compliance pass) counts once recorded, and on every task under the retired gsd-lite setting. Off keeps #257's output. */
 export const criteriaRequired = (config: SdlcConfig, receipt: SdlcReceipt | undefined): boolean => config.workflow === "gsd-lite" || (config.mode !== "off" && !!checklistOf(receipt));
-export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit, sets: readonly ReviewFindingSet[] = [], commit?: string, plan?: SdlcStatus["planConformance"], integrity?: TestIntegrity): SdlcStatus {
+export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit, sets: readonly ReviewFindingSet[] = [], commit?: string, plan?: SdlcStatus["planConformance"], integrity?: TestIntegrity, evalResult?: EvalResult): SdlcStatus {
   const stage = receipt?.stage ?? config.stages[0] ?? "spec", blockers: string[] = [];
   const definition = stageDefinition(config, stage);
+  const evalGate = evidence ? evalGateView(config, evidence, evalResult) : undefined;
   const items = findingsForHead(sets, findingHead(receipt, evidence, commit));
   const findings = items.length ? findingTally(items) : undefined;
   if (config.mode === "enforce" && findings?.openImportant) blockers.push("open important review findings: " + findings.openImportant);
@@ -355,10 +382,13 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
     if (receipt?.reviewedHead !== evidence.head) blockers.push("current head has not been reviewed");
     if (receipt?.localHead !== evidence.head || receipt.localResult !== "passed") blockers.push("local gate on current head missing or failed");
     if (!config.requiredChecks.length) blockers.push("required check set unknown");
-    for (const name of config.requiredChecks) {
+    // #481 S5: a configuration PR also needs the configured eval check; a code-only PR is unaffected.
+    for (const name of [...new Set([...config.requiredChecks, ...evalRequiredChecks(config, evidence)])]) {
       const matches = evidence.checks.filter(c => c.name === name);
       if (!matches.length || matches.some(c => c.state !== "passed")) blockers.push(`required check ${name}: not successful on current head`);
     }
+    // Gaps in the eval evidence block only in enforce; advise shows them in `evalGate` and the advice notice (never a silent pass, never an advise block).
+    if (config.mode === "enforce") blockers.push(...evalGapBlockers(evalGate));
     if (evidence.review !== "approved") blockers.push("GitHub review approval missing or changes requested");
     if (evidence.pendingReviews !== 0) blockers.push("review requests pending or unknown");
     if (evidence.unresolved !== 0) blockers.push("review threads unresolved or unknown");
@@ -371,7 +401,7 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
   const shown = criteria && (criteriaRequired(config, receipt) || definition && [...definition.entry_gates, ...definition.exit_gates].includes("criteria"));
   // Shown, not counted as a readiness blocker: the spec gate is build entry (#481 S1).
   const spec = config.mode !== "off" && receipt?.issue ? { spec: { issue: receipt.issue, state: specState(receipt, specEdit) } } : {};
-  return { ...spec, ...(config.mode !== "off" && integrity ? { testIntegrity: integrity } : {}), ...(config.mode !== "off" && plan ? { planConformance: plan } : {}), ...(findings ? { findings } : {}), ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
+  return { ...spec, ...(evalGate ? { evalGate } : {}), ...(config.mode !== "off" && integrity ? { testIntegrity: integrity } : {}), ...(config.mode !== "off" && plan ? { planConformance: plan } : {}), ...(findings ? { findings } : {}), ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
     actor: !definition ? "person" : shown && criteria.blockers.length ? "reviewer/person" : config.definitions ? definition.actor : baseActor(definition.base),
     // #694: the identity blocker keeps its exact text for gate matching; the next step says how to supply it.
     next: blockers[0] === "issue identity missing" ? "issue identity missing: name one issue (title #N, refs or hub_sdlc_record)" : blockers[0] ?? "person may inspect merge readiness; no automatic merge" };

package/src/hub/security-baseline.ts

@@ -0,0 +1,38 @@
+import type { SdlcGh } from "./sdlc.ts";
+
+/**
+ * #481 S7: the scheduled security-scan baseline. The hub runs no scanner and invents no control: it reads the open-alert counts GitHub already holds for the
+ * repository (Dependabot, secret scanning, code scanning), records one scan row each interval, and the existing control-band path judges the series. A source that
+ * is not enabled, not permitted or unreadable counts as unknown, never as zero alerts, so a repository with no source configured records nothing.
+ */
+export const SECURITY_SOURCES = ["dependabot", "secret_scanning", "code_scanning"] as const;
+export type SecuritySource = typeof SECURITY_SOURCES[number];
+export interface SecurityScan { repo: string; sources: SecuritySource[]; counts: Partial<Record<SecuritySource, number | null>>; total: number | null }
+const PATH: Record<SecuritySource, string> = { dependabot: "dependabot/alerts", secret_scanning: "secret-scanning/alerts", code_scanning: "code-scanning/alerts" };
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const MAX_ALERTS = 1000;
+
+/** Open alerts of one source, exactly (paged to the cap), or null when the source cannot be read completely. Counts only: no alert text, name or location is kept. */
+async function openAlerts(repo: string, source: SecuritySource, run: SdlcGh, deadline: number): Promise<number | null> {
+  let total = 0;
+  for (let page = 1; page <= MAX_ALERTS / 100; page++) {
+    const left = deadline - performance.now();
+    if (left <= 0) return null;
+    const reply = await run(["api", `repos/${repo}/${PATH[source]}?state=open&per_page=100&page=${page}`, "--jq", "length"], Math.min(10_000, left), undefined, 256).catch(() => undefined);
+    if (!reply || reply.code !== 0) return null;
+    const n = Number(reply.stdout.trim());
+    if (!Number.isSafeInteger(n) || n < 0 || n > 100) return null;
+    total += n;
+    if (n < 100) return total;
+  }
+  return null; // more than the cap: unknown, not a clipped number
+}
+
+/** Fixed argv, bounded time and output. The total is known only when every named source was read. */
+export async function readSecurityScan(repo: string, sources: readonly SecuritySource[], run: SdlcGh): Promise<SecurityScan | undefined> {
+  if (!REPO.test(repo) || repo.startsWith("-") || !sources.length || sources.some(source => !SECURITY_SOURCES.includes(source))) return undefined;
+  const deadline = performance.now() + 20_000, counts: SecurityScan["counts"] = {};
+  for (const source of sources) counts[source] = await openAlerts(repo, source, run, deadline);
+  const known = sources.every(source => counts[source] !== null && counts[source] !== undefined);
+  return { repo, sources: [...sources], counts, total: known ? sources.reduce((sum, source) => sum + counts[source]!, 0) : null };
+}

package/src/hub/settings.ts

@@ -1,3 +1,5 @@
+import { OPERATIONAL_NUMBERS } from "./operational-settings.ts";
+import { QUEUE_BACKPRESSURE_LIMITS } from "./queue-backpressure.ts";
 import { operationalRosterSetting, operationalSetting } from "./operational-authority.ts";
 import { ACTION_CLASSES } from "./action-class.ts";
 import { definitionOf, type KindMap, type ProjectAdapterCatalog, ADAPTERS, PLANNER_PEERS, SUPPORTED_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
@@ -26,7 +28,9 @@ export interface SettingDef {
   key: string;
   group: "Permissions" | "Start" | "Routing" | "Switches" | "Roster" | "Roles";
   label: string;
-  type: "enum" | "boolean" | "peers" | "roles" | "integer" | "number";
+  type: "enum" | "boolean" | "peers" | "roles" | "integer" | "number" | "lines";
+  /** Written only by the named hub command, never by `settings set`, a dashboard session or a conductor (#514b). */
+  managed?: "learn";
   min?: number; max?: number;
   /** The closed values of an enum; a route setting takes the project's own route ids instead. */
   values?: readonly string[];
@@ -57,7 +61,10 @@ export const SETTINGS: readonly SettingDef[] = [
   ...["interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"].map((key): SettingDef => ({ key: `task_sweep.${key}`, group: "Switches", label: `Task sweep: ${key}`, type: "number", min: 1, max: 2_147_483_647 / (key === "interval_s" ? 1000 : 60_000), store: "config", applies: "live", risk: "raises", path: ["task_sweep", key] })),
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "live", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
   { key: "tasks.escalate_after", group: "Routing", label: "Escalate after N consecutive changes_requested", type: "integer", min: 1, max: 10, store: "config", applies: "live", risk: "raises", path: ["tasks", "escalate_after"] },
+  ...OPERATIONAL_NUMBERS.map(({ defaultValue, unit, inventory, ...def }): SettingDef => def),
   { key: "tasks.auto_pull", group: "Switches", label: "Auto-pull the top reserved ready card when a planner slot frees", type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["tasks", "auto_pull"] },
+  { key: "tasks.queue_backpressure.max_queued", group: "Routing", label: "Automatic offers: max queued envelopes (0 disables)", type: "integer", min: 0, max: QUEUE_BACKPRESSURE_LIMITS.max_queued, store: "config", applies: "live", risk: "raises", path: ["tasks", "queue_backpressure", "max_queued"] },
+  { key: "tasks.queue_backpressure.max_oldest_s", group: "Routing", label: "Automatic offers: max oldest queued age in seconds (0 disables)", type: "integer", min: 0, max: QUEUE_BACKPRESSURE_LIMITS.max_oldest_s, store: "config", applies: "live", risk: "raises", path: ["tasks", "queue_backpressure", "max_oldest_s"] },
   { key: "planner", group: "Roles", label: "Planners (task-local selection)", type: "peers", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "next use", risk: "safe", path: ["catalog_roles", peer] })),
   { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
@@ -80,7 +87,16 @@ export const SETTINGS: readonly SettingDef[] = [
  * Never editable from settings, whatever the session: these choose what the hub executes or where secrets and task
  * text go. A key equal to an entry, or below it, is refused by name.
  */
-export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal", "instances", "adapters", "adapter_modules"] as const;
+export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal", "schedules", "folder_triggers", "corpus", "rooms", "instances", "adapters", "adapter_modules", "local.doc_read", "local.web_fetch"] as const;
+
+/**
+ * The one key `ahub learn accept` writes (#514b): the active profile's review checklist, which replaces as a unit. It is NOT a row of `SETTINGS` and `settingDef` does NOT resolve it, so
+ * `settings set|get|list`, the dashboard, a settings session and a conductor all see an unknown setting and nothing about them changed. Only the daemon's learn operation passes this
+ * definition to `settingsSet` itself (a function argument no request field can reach), so the write still goes through the same writer, loader check, reload and undo as every other setting.
+ */
+export const LEARN_CHECKLIST: SettingDef = Object.freeze({ key: "profile_overrides.review_checklist", group: "Routing", label: "Profile review checklist (written by ahub learn accept)", type: "lines", managed: "learn",
+  store: "config", applies: "restart", restartReason: "Session tool schemas and profile contracts are bound at startup", risk: "raises", path: Object.freeze(["profile_overrides", "review_checklist"]) });
+const LEARN_LINES_MAX = 16, LEARN_LINE_MAX = 500;
 
 /** Derive project-bound rows from the same builtin templates used by lookup, without registering aliases globally. */
 export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): readonly SettingDef[] {
@@ -138,6 +154,11 @@ export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAda
   return extra.length ? Object.freeze([...settings, ...extra]) : settings;
 }
 
+/** What undo may put back: a registry key, or the one managed key `ahub learn accept` writes. Never used to set anything. The CLI passes its project scope; the daemon has its own wrapper over its project-scoped lookup. */
+export function undoableDef(key: unknown, instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): SettingDef | string {
+  return key === LEARN_CHECKLIST.key ? LEARN_CHECKLIST : settingDef(key, instances, adapterCatalog);
+}
+
 /** The definition of a key, or why there is none. */
 export function settingDef(key: unknown, instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): SettingDef | string {
   if (typeof key !== "string" || key.length > 80) return "unknown setting";
@@ -158,6 +179,10 @@ export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonl
     if (typeof raw !== "number" || !(def.type === "integer" ? Number.isSafeInteger(raw) : Number.isFinite(raw)) || raw < (def.min ?? 0) || raw > (def.max ?? Number.MAX_SAFE_INTEGER)) throw new Error(`${def.key} takes ${def.type === "integer" ? "an integer" : "a number"} from ${def.min ?? 0} to ${def.max ?? Number.MAX_SAFE_INTEGER}`);
     return raw;
   }
+  if (def.type === "lines") {
+    if (!Array.isArray(raw) || !raw.length || raw.length > LEARN_LINES_MAX || raw.some(line => typeof line !== "string" || !line.trim() || line.length > LEARN_LINE_MAX || /[\x00-\x1f\x7f]/.test(line))) throw new Error(`${def.key} takes one to ${LEARN_LINES_MAX} lines of plain text, each at most ${LEARN_LINE_MAX} characters`);
+    return raw.map(line => line.trim());
+  }
   if (def.type === "boolean") {
     if (typeof raw !== "boolean") throw new Error(`${def.key} takes true or false`);
     return raw;

package/src/hub/shipped-packs.ts

@@ -0,0 +1,8 @@
+import example from "../../templates/packs/example.pack.json" with { type: "text" };
+
+/**
+ * The packs the hub ships (#513a), by file name without `.pack.json`. Imported as text so the bundle carries them, as `shipped-roles.ts` carries the role catalog.
+ * Only the format example is here: the writing, analysis and ops packs are #513b, which adds a file to `templates/packs/` and a line here.
+ */
+// TypeScript types a `.json` import as its parsed shape even with `type: "text"`; Bun hands over the file text, which `parsePack` parses and bounds itself.
+export const SHIPPED_PACKS: Readonly<Record<string, string>> = { example: example as unknown as string };