@staix/agent-hub 0.12.34 → 0.12.36

package/src/hub/sdlc.ts

@@ -1,20 +1,50 @@
-import { phaseReceipt, type PhaseReceipt, type PhaseView } from "./workflow.ts";
+import type { CostPlan } from "./cost-governance.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";
 import { spawn } from "node:child_process";
 import { childEnv, stopOwnedProcess } from "./child-process.ts";
 import { hostExecutable } from "./host-executable.ts";
 
+/** The off-mode default (#257). Off output, receipts and schemas keep this shape. */
 export const SDLC_STAGES = ["spec", "plan", "implement", "review", "verify", "merge", "release"] as const;
-export type SdlcBaseStage = typeof SDLC_STAGES[number];
+/** The enabled default (#481 S0): the AI-Native SDLC Playbook stage model. */
+export const PLAYBOOK_STAGES = ["intent", "spec", "plan", "build", "test", "review", "merge", "release", "maintain"] as const;
+export type SdlcBaseStage = typeof SDLC_STAGES[number] | typeof PLAYBOOK_STAGES[number];
+const BASES: readonly string[] = [...new Set<string>([...SDLC_STAGES, ...PLAYBOOK_STAGES])];
+/** Legacy ids read as their playbook stage; a receipt written with one stores the canonical id. */
+const ALIASES: Record<string, string> = { implement: "build", verify: "test" };
+export const canonicalStage = (stage: string): string => ALIASES[stage] ?? stage;
+const PLAYBOOK_LABEL: Record<string, string> = { intent: "Plan", spec: "Design", plan: "Build", build: "Build", test: "Test", review: "Deploy", merge: "Deploy", release: "Deploy", maintain: "Maintain" };
+export const playbookStage = (base: string): string | undefined => PLAYBOOK_LABEL[canonicalStage(base)];
+/** #481 S8: `workflow` and the `phase` gate/receipt name load with a warning before this hub version and refuse from it. */
+export const RETIRED_WORKFLOW_FROM = "0.13.0";
+const olderThan = (version: string, limit: string): boolean => {
+  const a = version.split(/[.-]/).slice(0, 3).map(Number), b = limit.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) < (b[i] ?? 0);
+  return false;
+};
 export type SdlcStage = string;
-export type StageGate = "issue" | "pr" | "local" | "review" | "checks" | "phase";
+export type StageGate = "issue" | "pr" | "local" | "review" | "checks" | "criteria";
 export interface StageDefinition { base: SdlcBaseStage; actor: string; entry_gates: StageGate[]; exit_gates: StageGate[]; after: string[]; }
 export type SdlcMode = "off" | "advise" | "enforce";
-export interface SdlcConfig { workflow?: "gsd-lite"; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; }
+/** `workflow: "gsd-lite"` marks the retired setting during its window (#481 S8): every task then needs a criteria checklist. */
+export interface SdlcConfig { workflow?: "gsd-lite"; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
+export interface PlanReviewReceipt {
+  planner: string;
+  planningRevision: number;
+  recordedAt: number;
+  scope?: CostPlan;
+  issue?: PlanIssueMetadata;
+}
 export interface SdlcReceipt {
   stage: SdlcStage;
-  phase?: PhaseReceipt;
+  planReview?: PlanReviewReceipt;
+  criteria?: CriteriaReceipt;
+  /** Stored before #481 S8 and read as `criteria`; never written again. */
+  phase?: LegacyPhaseReceipt;
+  /** The person's spec acceptance (#481 S1): set only by Tasks.acceptSpec, never by hub_sdlc_record. */
+  acceptance?: SpecAcceptance;
   repo?: string;
   issue?: number;
   pr?: number;
@@ -43,33 +73,42 @@ const repo = (value: unknown): value is string => typeof value === "string" && /
 const id = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 
 const STAGE_ID = /^[a-z][a-z0-9_-]{0,47}$/;
-const STAGE_GATES: StageGate[] = ["issue", "pr", "local", "review", "checks", "phase"];
-const baseActor = (base: SdlcBaseStage) => base === "review" || base === "verify" ? "reviewer" : base === "merge" || base === "release" ? "person" : "owner/planner";
+// #451 froze this literal as non-peer gate names ("local" is the local-check gate). "phase" is read as criteria (#481 S8).
+const STAGE_GATES = ["issue", "pr", "local", "review", "checks", "phase"];
+const GATES = STAGE_GATES.map(gate => gate === "phase" ? "criteria" : gate) as StageGate[];
+const baseActor = (base: string) => base === "review" || canonicalStage(base) === "test" ? "reviewer" : base === "merge" || base === "release" ? "person" : "owner/planner";
+/** A receipt's checklist under either stored name. */
+export const checklistOf = (receipt: SdlcReceipt | undefined): CriteriaReceipt | undefined => receipt?.criteria ?? receipt?.phase;
 export function stageDefinition(config: SdlcConfig, stage: string): StageDefinition | undefined {
-  if (!config.stages.includes(stage)) return undefined;
+  if (!config.stages.includes(stage)) return stage !== canonicalStage(stage) ? stageDefinition(config, canonicalStage(stage)) : undefined;
   if (config.definitions && Object.hasOwn(config.definitions, stage)) return config.definitions[stage];
-  if (!(SDLC_STAGES as readonly string[]).includes(stage)) return undefined;
+  if (!BASES.includes(stage)) return undefined;
   const base = stage as SdlcBaseStage;
   return { base, actor: baseActor(base), entry_gates: [], exit_gates: [], after: [] };
 }
 export function lifecycleStage(config: SdlcConfig, base: SdlcBaseStage): string {
   return config.stages.find(stage => stageDefinition(config, stage)?.base === base) ?? base;
 }
-function definitions(raw: unknown, stages: unknown): { stages: string[]; definitions: Record<string, StageDefinition> } {
+function definitions(raw: unknown, stages: unknown, phaseAlias: { allowed: boolean; used: boolean }): { stages: string[]; definitions: Record<string, StageDefinition> } {
   if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).length > 32) throw new Error("sdlc.definitions: expected at most 32 stage definitions");
   if (!Array.isArray(stages) || !stages.length || stages.length > 32 || stages.some(s => typeof s !== "string" || !STAGE_ID.test(s)) || new Set(stages).size !== stages.length) throw new Error("sdlc.stages: expected 1..32 distinct bounded stage ids");
   const result: Record<string, StageDefinition> = Object.create(null);
   for (const [id, value] of Object.entries(raw)) {
     if (!STAGE_ID.test(id) || !stages.includes(id) || !value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc.definitions: invalid or unlisted stage");
     const def = value as Record<string, unknown>;
-    if (Object.keys(def).some(k => !["base", "actor", "entry_gates", "exit_gates", "after"].includes(k)) || !(SDLC_STAGES as readonly unknown[]).includes(def.base)) throw new Error("sdlc.definitions: unknown field or base");
+    if (Object.keys(def).some(k => !["base", "actor", "entry_gates", "exit_gates", "after"].includes(k)) || !BASES.includes(def.base as string)) throw new Error("sdlc.definitions: unknown field or base");
     const base = def.base as SdlcBaseStage;
     if ((SDLC_STAGES as readonly string[]).includes(id) && id !== base) throw new Error("sdlc.definitions: built-in stage base cannot change");
+    if (!(SDLC_STAGES as readonly string[]).includes(id) && (PLAYBOOK_STAGES as readonly string[]).includes(id) && canonicalStage(id) !== canonicalStage(base)) throw new Error("sdlc.definitions: built-in playbook stage base cannot change");
     const actor = def.actor ?? baseActor(base);
     if (typeof actor !== "string" || actor !== baseActor(base) && !["owner", "reviewer", "person", "planner"].includes(actor)) throw new Error("sdlc.definitions.actor: unknown actor");
     const gates = (key: string): StageGate[] => {
-      const list = def[key] ?? [];
-      if (!Array.isArray(list) || list.length > 6 || list.some(g => !STAGE_GATES.includes(g)) || new Set(list).size !== list.length) throw new Error(`sdlc.definitions.${key}: unknown or duplicate gate`);
+      const given = def[key] ?? [];
+      const retired = Array.isArray(given) && given.includes("phase");
+      if (retired && !phaseAlias.allowed) throw new Error(`sdlc.definitions.${key}: the phase gate was retired in ${RETIRED_WORKFLOW_FROM} (#481); name it criteria`);
+      if (retired) phaseAlias.used = true;
+      const list = Array.isArray(given) ? given.map(g => g === "phase" ? "criteria" : g) : given;
+      if (!Array.isArray(list) || list.length > 6 || list.some(g => !GATES.includes(g)) || new Set(list).size !== list.length) throw new Error(`sdlc.definitions.${key}: unknown or duplicate gate`);
       return [...list] as StageGate[];
     };
     const after = def.after ?? [];
@@ -81,28 +120,38 @@ function definitions(raw: unknown, stages: unknown): { stages: string[]; definit
   return { stages: [...stages], definitions: result };
 }
 
-export function sdlcConfig(value: unknown): SdlcConfig {
+/** `version` is the running hub's, which closes the #481 S8 window; the daemon and Tasks pass it. Without one the window is open. */
+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"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
   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.
+  const window = version === undefined || olderThan(version, RETIRED_WORKFLOW_FROM);
+  if (raw.workflow !== undefined && !window) throw new Error(`sdlc.workflow: retired in ${RETIRED_WORKFLOW_FROM} (#481); remove it and record a criteria checklist instead`);
   const workflow = raw.workflow ?? "none";
   if (workflow !== "none" && workflow !== "gsd-lite") throw new Error("sdlc.workflow: expected none or gsd-lite");
+  const notes = workflow === "gsd-lite" ? [`sdlc.workflow = "gsd-lite" is deprecated and stops loading in ${RETIRED_WORKFLOW_FROM} (#481): remove it; every task then needs a criteria checklist recorded with hub_sdlc_record`] : [];
+  const phaseAlias = { allowed: window, used: false };
   const checks = raw.required_checks ?? [];
   if (!Array.isArray(checks) || checks.length > 32 || checks.some(c => typeof c !== "string" || !c.trim() || c.length > 120 || /[\r\n\x00-\x1f]/.test(c)) || new Set(checks).size !== checks.length) throw new Error("sdlc.required_checks: expected at most 32 unique nonempty names");
   if (raw.definitions !== undefined) {
-    const custom = definitions(raw.definitions, raw.stages);
-    if (workflow !== "gsd-lite" && Object.values(custom.definitions).some(d => [...d.entry_gates, ...d.exit_gates].includes("phase"))) throw new Error("sdlc.definitions: phase gates require workflow = gsd-lite");
-    return { mode, requiredChecks: [...checks] as string[], ...custom, ...(workflow === "gsd-lite" ? { workflow } : {}) };
+    const custom = definitions(raw.definitions, raw.stages, phaseAlias);
+    if (phaseAlias.used) notes.push(`the sdlc phase gate is deprecated and stops loading in ${RETIRED_WORKFLOW_FROM} (#481): name it criteria`);
+    return { mode, requiredChecks: [...checks] as string[], ...custom, ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
   }
-  const stages = raw.stages ?? [...SDLC_STAGES];
-  if (!Array.isArray(stages) || stages.length !== SDLC_STAGES.length || stages.some((stage, i) => stage !== SDLC_STAGES[i])) throw new Error("sdlc.stages: use spec, plan, implement, review, verify, merge, release in that order; custom stages are not supported yet");
-  return { mode, requiredChecks: [...checks] as string[], stages: [...stages] as SdlcStage[], ...(workflow === "gsd-lite" ? { workflow } : {}) };
+  // Off keeps the #257 seven stages byte for byte; an enabled lifecycle defaults to the playbook (#481 S0).
+  const given = raw.stages ?? (mode === "off" ? [...SDLC_STAGES] : [...PLAYBOOK_STAGES]);
+  const exactly = (list: readonly string[]) => Array.isArray(given) && given.length === list.length && given.every((stage, i) => stage === list[i]);
+  // An enabled #257 list keeps its order under canonical ids, so implement/verify stay read-only aliases there too.
+  const stages = mode !== "off" && exactly(SDLC_STAGES) ? SDLC_STAGES.map(canonicalStage) : given;
+  if (!exactly(SDLC_STAGES) && !exactly(PLAYBOOK_STAGES)) throw new Error(`sdlc.stages: use ${PLAYBOOK_STAGES.join(", ")} in that order (or the #257 list ${SDLC_STAGES.join(", ")}); other lists need definitions`);
+  return { mode, requiredChecks: [...checks] as string[], stages: [...stages as string[]], ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
 }
 
-export function loadSdlc(cwd: string): SdlcConfig {
+export function loadSdlc(cwd: string, version?: string): SdlcConfig {
   try {
     const fd = openSync(join(cwd, ".agenthub", "sdlc.toml"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
     try {
@@ -112,23 +161,29 @@ export function loadSdlc(cwd: string): SdlcConfig {
       while ((n = readSync(fd, bytes, length, bytes.length - length, null)) > 0) { length += n; if (length > cap) throw new Error("sdlc.toml exceeds 64 KiB"); }
       const after = fstatSync(fd);
       if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || length !== after.size) throw new Error("sdlc.toml changed during read");
-      return sdlcConfig(Bun.TOML.parse(bytes.subarray(0, length).toString("utf8")));
+      return sdlcConfig(Bun.TOML.parse(bytes.subarray(0, length).toString("utf8")), version);
     } finally { closeSync(fd); }
   }
   catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return sdlcConfig(undefined); throw error; }
 }
 
 /** Identities and claimed local receipts only. External facts are read, never accepted as input. */
-export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined = undefined, config: SdlcConfig = sdlcConfig(undefined)): SdlcReceipt {
+export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined = undefined, config: SdlcConfig = sdlcConfig(undefined), version?: string): SdlcReceipt {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc receipt: expected an object");
   const raw = value as Record<string, unknown>;
-  for (const key of Object.keys(raw)) if (!["stage", "repo", "issue", "pr", "reviewedHead", "localHead", "localResult", "phase"].includes(key)) throw new Error(`sdlc receipt.${key}: unsupported or externally observed field`);
+  for (const key of Object.keys(raw)) if (!["stage", "repo", "issue", "pr", "reviewedHead", "localHead", "localResult", "criteria", "phase"].includes(key)) throw new Error(`sdlc receipt.${key}: unsupported or externally observed field`);
+  if (raw.criteria !== undefined && raw.phase !== undefined) throw new Error("sdlc receipt: give criteria only; phase is its retired name");
+  if (raw.phase !== undefined && version !== undefined && !olderThan(version, RETIRED_WORKFLOW_FROM)) throw new Error(`sdlc receipt.phase: retired in ${RETIRED_WORKFLOW_FROM} (#481); use criteria`);
   previous ??= { stage: config.stages[0] ?? "spec" };
   const next = { ...previous };
-  if (raw.phase !== undefined) next.phase = phaseReceipt(raw.phase);
+  const checklist = raw.criteria ?? raw.phase;
+  // Off keeps the #257 receipt bytes for a phase write (task import stays retired); everything else stores criteria.
+  if (raw.phase !== undefined && config.mode === "off" && !config.workflow) { const legacy = criteriaReceipt(raw.phase); next.phase = { id: legacy.id, ...(legacy.head ? { head: legacy.head } : {}), tasks: [], criteria: legacy.criteria }; delete next.criteria; }
+  else if (checklist !== undefined) { next.criteria = criteriaReceipt(checklist); delete next.phase; }
   if (raw.stage !== undefined) {
     if (typeof raw.stage !== "string" || !stageDefinition(config, raw.stage)) throw new Error("sdlc receipt.stage: unknown stage");
-    next.stage = raw.stage as SdlcStage;
+    // A legacy id is accepted from older clients but stored under the stage the config actually lists (#481 S0).
+    next.stage = (config.stages.includes(raw.stage) ? raw.stage : canonicalStage(raw.stage)) as SdlcStage;
   }
   if (raw.repo !== undefined) { if (!repo(raw.repo)) throw new Error("sdlc receipt.repo: expected owner/repository"); next.repo = raw.repo; }
   for (const key of ["issue", "pr"] as const) if (raw[key] !== undefined) { if (!id(raw[key])) throw new Error(`sdlc receipt.${key}: expected a positive integer`); next[key] = raw[key]; }
@@ -137,10 +192,12 @@ export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined =
     if (!["passed", "failed", "unknown"].includes(String(raw.localResult))) throw new Error("sdlc receipt.localResult: expected passed, failed or unknown");
     next.localResult = raw.localResult as SdlcReceipt["localResult"];
   }
+  // An acceptance names one spec issue; relinking the receipt to another drops it (#481 S1).
+  if (next.repo !== previous.repo || next.issue !== previous.issue) delete next.acceptance;
   // A new artifact cannot inherit another PR's review or local gate.
   if (next.repo !== previous.repo || next.pr !== previous.pr) {
     delete next.head; delete next.observed;
-    if (raw.phase === undefined) delete next.phase;
+    if (checklist === undefined) { delete next.criteria; delete next.phase; }
     if (raw.reviewedHead === undefined) delete next.reviewedHead;
     if (raw.localHead === undefined) delete next.localHead;
     if (raw.localResult === undefined) delete next.localResult;
@@ -155,7 +212,7 @@ export function parsePrEvidence(value: unknown): PrEvidence {
     const name = c.name ?? c.context;
     if (typeof name !== "string" || !name || name.length > 120) throw new Error("PR readback: invalid check identity");
     const native = c.conclusion ?? c.state;
-    const state = native === "SUCCESS" ? "passed" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED"].includes(String(native)) ? "failed" : ["PENDING", "QUEUED", "IN_PROGRESS"].includes(String(c.status ?? native)) ? "pending" : "unknown";
+    const state = ["PENDING", "QUEUED", "IN_PROGRESS"].includes(String(c.status ?? native)) ? "pending" : native === "SUCCESS" ? "passed" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED"].includes(String(native)) ? "failed" : "unknown";
     return { name, state } as PrEvidence["checks"][number];
   });
   const paths = p.files.map((f: Record<string, unknown>) => { if (typeof f.path !== "string" || !f.path || f.path.length > 1000) throw new Error("PR readback: invalid file identity"); return f.path; });
@@ -166,8 +223,26 @@ export function parsePrEvidence(value: unknown): PrEvidence {
     ...(sha(p.mergeCommit?.oid) ? { mergeCommit: p.mergeCommit.oid } : {}) };
 }
 
-export interface SdlcStatus { workflow?: "gsd-lite"; phase?: PhaseView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
-export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, phase?: PhaseView): SdlcStatus {
+/** Issue identity and edit times only; no body is fetched or stored. `lastEditedAt` moves on a body edit, not on comments. */
+export interface SpecEdit { lastEditedAt: string | null; updatedAt: string }
+export interface SpecAcceptance extends SpecEdit { repo: string; issue: number; acceptedAt: number }
+export type SpecState = "missing" | "current" | "changed" | "unknown";
+/** Whether the receipt's spec issue is accepted at its current body. `edit` undefined means the readback failed. */
+export function specState(receipt: SdlcReceipt | undefined, edit: SpecEdit | undefined): SpecState {
+  const accepted = receipt?.acceptance;
+  if (!accepted || accepted.repo !== receipt?.repo || accepted.issue !== receipt?.issue) return "missing";
+  if (!edit) return "unknown";
+  return edit.lastEditedAt === accepted.lastEditedAt ? "current" : "changed";
+}
+export const SPEC_STATE_TEXT: Record<Exclude<SpecState, "current">, string> = {
+  missing: "spec acceptance missing: the person runs ahub sdlc accept <task> --issue <n>",
+  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 { 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): SdlcStatus {
   const stage = receipt?.stage ?? config.stages[0] ?? "spec", blockers: string[] = [];
   const definition = stageDefinition(config, stage);
   if (!definition) blockers.push("lifecycle stage definition unknown");
@@ -187,20 +262,22 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
     if (evidence.pendingReviews !== 0) blockers.push("review requests pending or unknown");
     if (evidence.unresolved !== 0) blockers.push("review threads unresolved or unknown");
   }
-  if (config.workflow === "gsd-lite") {
-    blockers.unshift(...(phase?.blockers ?? ["phase board evidence unknown"]));
-    if (!evidence || receipt?.phase?.head !== evidence.head) blockers.push("phase checklist head missing or stale");
-  }
-  const custom = config.definitions && definition ? stageGates(definition, blockers, receipt, evidence, phase) : undefined;
+  const viewBlockers = criteria?.blockers ?? ["criteria board evidence unknown"];
+  const staleHead = !evidence || checklistOf(receipt)?.head !== evidence.head ? ["criteria checklist head missing or stale"] : [];
+  if (criteriaRequired(config, receipt)) { blockers.unshift(...viewBlockers); blockers.push(...staleHead); }
+  const custom = config.definitions && definition ? stageGates(definition, blockers, [...viewBlockers, ...staleHead]) : undefined;
   if (custom) for (const blocker of [...custom.entry, ...custom.exit]) if (!blockers.includes(blocker)) blockers.push(blocker);
-  return { ...(config.workflow ? { workflow: config.workflow, ...(phase ? { phase } : {}) } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
-    actor: !definition ? "person" : phase?.blockers.length ? "reviewer/person" : config.definitions && definition ? definition.actor : stage === "review" || stage === "verify" ? "reviewer" : stage === "merge" || stage === "release" ? "person" : "owner/planner",
+  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" && 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),
     next: blockers[0] ?? "person may inspect merge readiness; no automatic merge" };
 }
 
-function stageGates(def: StageDefinition, blockers: string[], receipt: SdlcReceipt | undefined, evidence: PrEvidence | undefined, phase: PhaseView | undefined): { entry: string[]; exit: string[] } {
+function stageGates(def: StageDefinition, blockers: string[], checklist: string[]): { entry: string[]; exit: string[] } {
   const select = (gates: StageGate[]) => [...new Set(gates.flatMap(gate => {
-    if (gate === "phase") return [...(phase?.blockers ?? ["phase board evidence unknown"]), ...(!evidence || receipt?.phase?.head !== evidence.head ? ["phase checklist head missing or stale"] : [])];
+    if (gate === "criteria") return checklist;
     const matching = (text: string) => gate === "issue" ? text === "issue identity missing" : gate === "pr" ? ["PR identity missing", "current PR evidence unknown", "PR is not open"].includes(text) : gate === "local" ? ["current PR evidence unknown", "local gate on current head missing or failed"].includes(text) : gate === "checks" ? text === "current PR evidence unknown" || text === "required check set unknown" || text.startsWith("required check ") : ["current PR evidence unknown", "current head has not been reviewed", "GitHub review approval missing or changes requested", "review requests pending or unknown", "review threads unresolved or unknown"].includes(text);
     return blockers.filter(matching);
   }))];
@@ -233,6 +310,20 @@ export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 2
   child.once("close", code => { clearTimeout(timer); resolve({ code: failed ? 1 : code ?? 1, stdout: failed ? "" : stdout }); });
 });
 
+/** Read-only, fixed argv: the issue's edit times, never its body. */
+export async function readSpecEdit(repoName: string, issue: number, run: SdlcGh = sdlcGh): Promise<SpecEdit | undefined> {
+  if (!repo(repoName) || !id(issue)) return undefined;
+  const [owner, name] = repoName.split("/");
+  try {
+    const out = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){number lastEditedAt updatedAt}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${issue}`]);
+    if (out.code !== 0) return undefined;
+    const found = JSON.parse(out.stdout)?.data?.repository?.issue;
+    const stamp = (v: unknown) => typeof v === "string" && v.length <= 40 && !Number.isNaN(Date.parse(v));
+    if (found?.number !== issue || !stamp(found.updatedAt) || (found.lastEditedAt !== null && !stamp(found.lastEditedAt))) return undefined;
+    return { lastEditedAt: found.lastEditedAt, updatedAt: found.updatedAt };
+  } catch { return undefined; }
+}
+
 export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Promise<PrEvidence | undefined> {
   if (!repo(receipt.repo) || !id(receipt.pr)) return undefined;
   try {
@@ -252,3 +343,159 @@ export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Pr
     return parsePrEvidence(p);
   } catch { return undefined; }
 }
+
+export interface PlanIssueMetadata {
+  repo: string;
+  issue: number;
+  state: "OPEN" | "CLOSED";
+  /** Body edit time; comment activity must never invalidate a plan review. */
+  editedAt: string;
+  /** Nullable GitHub body edit field, retained to compare independent S1 acceptance evidence. */
+  lastEditedAt?: string | null;
+}
+
+/** Metadata only: never request issue bodies or comments for a planning receipt. */
+export async function readPlanIssueMetadata(repository: string, number: number, run: SdlcGh = sdlcGh): Promise<PlanIssueMetadata | undefined> {
+  if (!repo(repository) || !id(number)) return undefined;
+  const [owner, name] = repository.split("/");
+  try {
+    const result = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){number state createdAt lastEditedAt}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${number}`], 10_000, undefined, 8 * 1024);
+    if (result.code !== 0 || Buffer.byteLength(result.stdout) > 8 * 1024) return undefined;
+    const response = JSON.parse(result.stdout);
+    if (response.errors !== undefined) return undefined;
+    const issue = response.data?.repository?.issue;
+    if (!issue || issue.number !== number || !["OPEN", "CLOSED"].includes(issue.state)) return undefined;
+    const editedAt = issue.lastEditedAt === null ? issue.createdAt : issue.lastEditedAt;
+    if (typeof editedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(editedAt) || !Number.isFinite(Date.parse(editedAt))) return undefined;
+    return { repo: repository, issue: number, state: issue.state, editedAt, lastEditedAt: issue.lastEditedAt };
+  } catch { return undefined; }
+}
+
+/** A complete resolved-thread snapshot already proves there is no pending unanswered bot thread. */
+export function reviewReadinessFromEvidence(evidence: PrEvidence | undefined, expected: string | undefined, required: readonly string[]): ReviewReadiness | undefined {
+  if (!evidence || evidence.unresolved !== 0) return undefined;
+  const checks = required.length ? [...required] : ["check (ubuntu-latest)", "check (macos-latest)", "seeded guards"];
+  if (!checks.every(name => evidence.checks.some(check => check.name === name)) || evidence.checks.some(check => check.state === "unknown")) return undefined;
+  const blockers: string[] = [];
+  if (!expected || !sha(expected)) blockers.push("review head missing");
+  else if (evidence.head !== expected) blockers.push("review head changed");
+  if (evidence.state !== "OPEN") blockers.push("review PR is not open");
+  if (!checks.every(name => { const matched = evidence.checks.filter(check => check.name === name); return matched.length === 1 && matched[0]?.state === "passed"; })) blockers.push("exact-head full CI is not green");
+  return { head: evidence.head, ready: blockers.length === 0, blockers };
+}
+
+export interface ReviewReadiness { head?: string; ready: boolean; blockers: string[]; reusedRun?: number }
+/** Metadata-only pre-review admission; no remote body or comment text is requested. */
+export async function readReviewReadiness(receipt: SdlcReceipt, expected: string | undefined, run: SdlcGh = sdlcGh, requiredChecks: readonly string[] = []): Promise<ReviewReadiness> {
+  const unknown = (): ReviewReadiness => ({ ready: false, blockers: ["review readiness unavailable"] });
+  if (!repo(receipt.repo) || !id(receipt.pr)) return unknown();
+  const [owner, name] = receipt.repo.split("/");
+  const query = "query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid state commits(last:1){nodes{commit{oid tree{oid} statusCheckRollup{contexts(first:100){nodes{... on CheckRun{name status conclusion} ... on StatusContext{context state}} pageInfo{hasNextPage}}}}}} reviewThreads(first:100){nodes{isResolved comments(first:100){nodes{author{__typename} createdAt} pageInfo{hasNextPage}}} pageInfo{hasNextPage}}}}}";
+  try {
+    const deadline = performance.now() + 20_000;
+    const bounded: SdlcGh = (args, timeout, cwd, cap) => performance.now() < deadline
+      ? run(args, Math.max(1, Math.min(timeout ?? 10_000, deadline - performance.now())), cwd, cap)
+      : Promise.resolve({ code: 1, stdout: "" });
+    const args = ["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${receipt.pr}`];
+    const response = await bounded(args, 10_000, undefined, 512 * 1024);
+    if (response.code !== 0 || Buffer.byteLength(response.stdout) > 512 * 1024) return unknown();
+    const parsed = JSON.parse(response.stdout), pr = parsed.data?.repository?.pullRequest;
+    if (parsed.errors || !pr || !sha(pr.headRefOid)) return unknown();
+    const blockers: string[] = [];
+    if (!expected || !sha(expected)) blockers.push("review head missing");
+    else if (pr.headRefOid !== expected) blockers.push("review head changed");
+    if (pr.state !== "OPEN") blockers.push("review PR is not open");
+    const commit = pr.commits?.nodes?.[0]?.commit;
+    if (!commit || commit.oid !== pr.headRefOid) blockers.push("review head changed");
+    const contexts = commit?.statusCheckRollup?.contexts;
+    const nodes: unknown[] | undefined = contexts?.nodes;
+    const full = requiredChecks.length ? [...requiredChecks] : ["check (ubuntu-latest)", "check (macos-latest)", "seeded guards"];
+    let reusedRun: number | undefined;
+    if (contexts?.pageInfo?.hasNextPage !== false || !Array.isArray(nodes) || nodes.length > 100
+      || !full.every(name => {
+        const matches = (nodes as { name?: string; context?: string; status?: string; conclusion?: string; state?: string }[]).filter(node => (node?.name ?? node?.context) === name);
+        return matches.length === 1 && (matches[0]?.name ? matches[0].status === "COMPLETED" && matches[0].conclusion === "SUCCESS" : matches[0]?.state === "SUCCESS");
+      })) blockers.push("exact-head full CI is not green");
+    if (blockers.includes("exact-head full CI is not green") && contexts?.pageInfo?.hasNextPage === false && Array.isArray(nodes)
+      && full.every(name => { const matches = (nodes as { name?: string; conclusion?: string }[]).filter(node => node?.name === name); return matches.length === 1 && matches[0]?.conclusion === "SKIPPED"; }) && sha(commit?.tree?.oid)) {
+      reusedRun = await identicalTreeGate(receipt.repo, commit.tree.oid, bounded, full);
+      if (reusedRun !== undefined) {
+        // Proof reads can await several API calls: recheck the complete head/check/thread snapshot before admission.
+        const after = await bounded(args, 10_000, undefined, 512 * 1024);
+        try { if (after.code !== 0 || JSON.stringify(JSON.parse(after.stdout)?.data?.repository?.pullRequest) !== JSON.stringify(pr)) reusedRun = undefined; }
+        catch { reusedRun = undefined; }
+        if (reusedRun !== undefined) blockers.splice(blockers.indexOf("exact-head full CI is not green"), 1);
+      }
+    }
+    const threads = pr.reviewThreads;
+    if (threads?.pageInfo?.hasNextPage !== false || !Array.isArray(threads.nodes) || threads.nodes.length > 100) blockers.push("bot review thread evidence unavailable");
+    else for (const thread of threads.nodes) {
+      if (thread?.isResolved === true) continue;
+      if (thread?.isResolved !== false) { blockers.push("bot review thread evidence unavailable"); continue; }
+      const comments = thread?.comments;
+      if (comments?.pageInfo?.hasNextPage !== false || !Array.isArray(comments.nodes) || comments.nodes.length > 100
+        || comments.nodes.some((comment: { author?: { __typename?: string }; createdAt?: string }) => !["Bot", "User"].includes(comment?.author?.__typename ?? "") || !Number.isFinite(Date.parse(comment.createdAt ?? "")))) {
+        blockers.push("bot review thread evidence unavailable"); continue;
+      }
+      let unanswered = false;
+      for (const comment of comments.nodes) {
+        if (comment.author.__typename === "Bot") unanswered = true;
+        else if (comment.author.__typename === "User") unanswered = false;
+      }
+      if (unanswered) blockers.push("bot review threads unanswered");
+    }
+    return { head: pr.headRefOid, ready: blockers.length === 0, blockers: [...new Set(blockers)], ...(reusedRun !== undefined ? { reusedRun } : {}) };
+  } catch { return unknown(); }
+}
+
+/** Same proof floor as scripts/ci-gates.mjs: the identical tree includes the workflow itself. No skipped proof. */
+async function identicalTreeGate(repository: string, tree: string, run: SdlcGh, required: readonly string[]): Promise<number | undefined> {
+  try {
+    const list = await run(["api", `repos/${repository}/actions/workflows/check.yml/runs?status=success&per_page=20`, "--jq", "{total_count,workflow_runs:[.workflow_runs[]|{id,event,conclusion,head_sha}]}"], 10_000, undefined, 64 * 1024);
+    if (list.code !== 0) return;
+    const runs = JSON.parse(list.stdout)?.workflow_runs;
+    if (!Array.isArray(runs) || runs.length > 20) return;
+    for (const candidate of runs) {
+      if (!id(candidate?.id) || candidate.conclusion !== "success" || !["pull_request", "push"].includes(candidate.event) || !sha(candidate.head_sha)) continue;
+      const commit = await run(["api", `repos/${repository}/git/commits/${candidate.head_sha}`, "--jq", "{tree:{sha:.tree.sha}}"], 10_000, undefined, 4096);
+      if (commit.code !== 0 || JSON.parse(commit.stdout)?.tree?.sha !== tree) continue;
+      const jobs = await run(["api", `repos/${repository}/actions/runs/${candidate.id}/jobs?per_page=100`, "--jq", '{total_count,jobs:[.jobs[]|{name,conclusion,reused:any(.steps[]?; .name=="Reuse verified identical-tree full gate" and .conclusion=="success")}]}'], 10_000, undefined, 32 * 1024);
+      if (jobs.code !== 0) continue;
+      const proof = JSON.parse(jobs.stdout);
+      if (!Array.isArray(proof.jobs) || proof.jobs.length > 100 || proof.total_count !== proof.jobs.length) continue;
+      if (required.every(name => {
+        const found = proof.jobs.filter((job: { name?: string }) => job?.name === name); return found.length === 1 && found[0]?.conclusion === "success" && found[0]?.reused !== true;
+      })) return candidate.id;
+    }
+  } catch { return; }
+}
+
+/** PR cost evidence excludes titles, bodies and comment text; unknown/truncated coverage never becomes zero. */
+export async function readPrCostHistory(repository: string, number: number, run: SdlcGh = sdlcGh): Promise<import("./cost-governance.ts").CostPr | undefined> {
+  if (!repo(repository) || !id(number)) return;
+  const [owner, name] = repository.split("/");
+  try {
+    const query = "query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){number state headRefOid mergedAt commits(first:100){nodes{commit{oid}} pageInfo{hasNextPage}} reviews(first:100){nodes{databaseId commit{oid}} pageInfo{hasNextPage}}}}}";
+    const reply = await run(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${number}`], 10_000, undefined, 128 * 1024);
+    if (reply.code !== 0) return;
+    const parsed = JSON.parse(reply.stdout), pr = parsed.data?.repository?.pullRequest;
+    if (parsed.errors || pr?.number !== number || !["OPEN", "CLOSED", "MERGED"].includes(pr.state)) return;
+    const result: import("./cost-governance.ts").CostPr = { repo: repository, pr: number, state: pr.state, complete: false,
+      ...(typeof pr.mergedAt === "string" && Number.isFinite(Date.parse(pr.mergedAt)) ? { mergedAt: Date.parse(pr.mergedAt) } : {}) };
+    if (pr.state !== "MERGED") return result; // Cost metrics count merged PRs, not an active work queue.
+    const reviews = pr.reviews, commits = pr.commits;
+    const reviewComplete = reviews?.pageInfo?.hasNextPage === false && Array.isArray(reviews.nodes) && reviews.nodes.length <= 100 && reviews.nodes.every((node: { databaseId?: number }) => id(node?.databaseId));
+    const commitComplete = commits?.pageInfo?.hasNextPage === false && Array.isArray(commits.nodes) && commits.nodes.length <= 100 && sha(pr.headRefOid) && commits.nodes.every((node: { commit?: { oid?: string } }) => sha(node?.commit?.oid));
+    if (reviewComplete) result.reviews = new Set(reviews.nodes.map((review: { databaseId?: unknown }) => review.databaseId).filter((id: unknown) => Number.isSafeInteger(id))).size;
+    const heads = new Set<string>([pr.headRefOid, ...(commits?.nodes ?? []).map((node: { commit?: { oid?: string } }) => node?.commit?.oid), ...(reviews?.nodes ?? []).map((node: { commit?: { oid?: string } }) => node?.commit?.oid)].filter(sha));
+    const checks = await run(["api", `repos/${repository}/actions/workflows/check.yml/runs?per_page=100`, "--jq", "{total_count,workflow_runs:[.workflow_runs[]|{id,run_attempt,head_sha,pull_requests:[.pull_requests[].number]}]}"], 10_000, undefined, 128 * 1024);
+    if (checks.code !== 0) return result;
+    const runs = JSON.parse(checks.stdout);
+    if (!Array.isArray(runs.workflow_runs) || runs.workflow_runs.length > 100 || !Number.isSafeInteger(runs.total_count) || runs.total_count < runs.workflow_runs.length) return result;
+    const linked = runs.workflow_runs.filter((row: { head_sha?: string; pull_requests?: number[] }) => heads.has(row.head_sha ?? "") || Array.isArray(row.pull_requests) && row.pull_requests.includes(number));
+    if (linked.some((row: { id?: number; run_attempt?: number }) => !id(row.id) || !id(row.run_attempt))) return result;
+    result.ciRuns = linked.map((row: { id: number; run_attempt: number }) => ({ id: row.id, attempt: row.run_attempt }));
+    result.complete = reviewComplete && commitComplete && runs.total_count === runs.workflow_runs.length;
+    return result;
+  } catch { return; }
+}

package/src/hub/settings.ts

@@ -1,5 +1,6 @@
-import { definitionOf, ADAPTERS, PLANNER_PEERS, SUPPORTED_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
+import { definitionOf, type KindMap, ADAPTERS, PLANNER_PEERS, SUPPORTED_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
 import { createHash } from "node:crypto";
+import { types } from "node:util";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
@@ -70,12 +71,37 @@ 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"] 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", "instances"] as const;
+
+/** Derive project-bound rows from the same builtin templates used by lookup, without registering aliases globally. */
+export function projectSettings(instances?: KindMap): readonly SettingDef[] {
+  if (!instances || typeof instances !== "object" || types.isProxy(instances) || Array.isArray(instances)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(instances)) || Object.getOwnPropertySymbols(instances).length) return SETTINGS;
+  const extra: SettingDef[] = [];
+  for (const peer of Object.keys(instances)) {
+    if (definitionOf(peer)) continue; // An explicit declaration never changes a builtin's setting definition.
+    const adapter = definitionOf(peer, instances);
+    if (!adapter) continue;
+    const copy = (base: SettingDef, key: string): SettingDef => Object.freeze({ ...base, key,
+      label: base.label.replace(`${adapter.kind}:`, `${peer}:`),
+      path: Object.freeze(base.path.map(part => part === adapter.kind ? peer : part)),
+      ...(base.values ? { values: Object.freeze([...base.values]) } : {}),
+    });
+    for (const prefix of ["roster", "permission", "permission_modes"]) {
+      const base = SETTINGS.find(def => def.key === `${prefix}.${adapter.kind}`);
+      if (base) extra.push(copy(base, `${prefix}.${peer}`));
+    }
+    // I2 declarations select the headless engine; settings cannot opt an extra into a native TUI.
+    extra.push(Object.freeze({ key: `peers.${peer}.start_mode`, group: "Start", label: `${peer}: start mode (headless only)`,
+      type: "enum", values: Object.freeze(["headless"]), store: "config", applies: "next use", risk: "raises", floor: "headless", path: Object.freeze(["peers", peer, "start_mode"]) } satisfies SettingDef));
+  }
+  return extra.length ? Object.freeze([...SETTINGS, ...extra]) : SETTINGS;
+}
 
 /** The definition of a key, or why there is none. */
-export function settingDef(key: unknown): SettingDef | string {
+export function settingDef(key: unknown, instances?: KindMap): SettingDef | string {
   if (typeof key !== "string" || key.length > 80) return "unknown setting";
-  const found = SETTINGS.find((s) => s.key === key);
+  const found = projectSettings(instances).find((s) => s.key === key);
   if (found) return found;
   if (NEVER_EDITABLE.some((never) => key === never || key.startsWith(`${never}.`))) return `${key} chooses what the hub runs or where secrets and task text go: it is never editable from settings; edit .agenthub/config.local.json in your editor`;
   return "unknown setting; run ahub settings list";
@@ -390,6 +416,8 @@ const same = (a: unknown, b: unknown): boolean => JSON.stringify(a ?? null) ===
  */
 export function settingRows(input: {
   cwd: string; routing: Routing;
+  /** Captured trusted declarations for this daemon/project, never taken from a settings request. */
+  instances?: KindMap;
   running: (path: readonly string[]) => unknown;
   next: ((path: readonly string[]) => unknown) | undefined;
   mode: (peer: string) => { value?: string; note?: string };
@@ -404,9 +432,9 @@ export function settingRows(input: {
   const projectRouting = existsSync(join(input.cwd, ".agenthub", "routing.toml"));
   const routes = [...Object.keys(input.routing.routes), ...Object.keys(input.routing.hub_routes ?? {})];
   const scalar = (value: unknown): SettingValue => typeof value === "string" || typeof value === "boolean" || typeof value === "number" ? value : Array.isArray(value) ? value.map(String) : null;
-  return SETTINGS.map((def): SettingRow => {
+  return projectSettings(input.instances).map((def): SettingRow => {
     const base = { key: def.key, group: def.group, label: def.label, type: def.type, ...(["integer", "number"].includes(def.type) ? { min: def.min, max: def.max } : {}), applies: def.applies, ...(def.restartReason ? { restartReason: def.restartReason } : {}), risk: def.risk, ...(def.floor === undefined ? {} : { floor: def.floor }),
-      ...(def.key === "scoped_grants.protect_instructions" ? { hint: "AGENTS.md, CLAUDE.md and QWEN.md remain grantable by default; enabling this asks before scoped writes and edits" } : def.group === "Permissions" ? { hint: permissionBoundary(def.path.at(-1)!) } : {}) };
+      ...(def.key === "scoped_grants.protect_instructions" ? { hint: "AGENTS.md, CLAUDE.md and QWEN.md remain grantable by default; enabling this asks before scoped writes and edits" } : def.group === "Permissions" ? { hint: permissionBoundary(def.path.at(-1)!, input.instances) } : {}) };
     if (def.store === "runtime") {
       const mode = input.mode(def.path[0]!);
       return { ...base, values: def.values!, file: "this hub run", value: mode.value ?? null, fileValue: mode.value ?? null, source: "this hub run", ...(mode.note ? { note: mode.note } : {}) };