@dev-loops/core 0.5.0 → 0.7.1

package/src/config/config.mjs

@@ -46,6 +46,13 @@ const GateConfig = z.strictObject({
     .min(1)
     .default(["must-fix"]),
   dynamicAngles: z.boolean().default(false),
+  // Additive counterpart to the subtractive dynamicAngles path (#1048): when
+  // true, the context-builder may also ADD catalog angles — from
+  // resolveAnglePool() (gates.anglePool, or else the union of the persona
+  // registry and this config's own configured angles) — that change-category
+  // heuristics recommend but that are not already in this gate's configured
+  // pool. Default false preserves today's subtractive-only behavior exactly.
+  additiveAngles: z.boolean().default(false),
 });
 
 const GatesConfig = z.strictObject({
@@ -65,6 +72,16 @@ const GatesConfig = z.strictObject({
   // true (opt-out): a clean gate verdict requires fan-out/fan-in evidence
   // unless explicitly disabled. See docs/gate-review-sub-loop-contract.md.
   requireFanoutEvidence: z.boolean().default(true),
+  // Fail-closed enforcement that a fanout_fanin gate verdict carries recorded,
+  // internally-consistent fan-out *provenance* (distinct reviewer count +
+  // per-angle dispatch). This RAISES THE BAR against a single agent self-producing
+  // every artifact but does NOT prove independence — provenance is self-reported,
+  // so it remains forgeable; un-forgeable recording is the Pi-harness bridge (see
+  // the honest caveat in docs/gate-review-sub-loop-contract.md). Layered ON TOP of
+  // requireFanoutEvidence — only takes effect when fan-out evidence enforcement
+  // is active. Default false (opt-in): closing this loophole is additive and
+  // does not change behavior for existing ledgers that carry no provenance.
+  requireFanoutProvenance: z.boolean().default(false),
   // Cap on how many scoped `review` reviewers the gate fan-out spawns in
   // parallel. When the resolved angle set exceeds this cap, the overflow runs
   // in sequential batches and the degradation is recorded in the gate evidence.
@@ -75,6 +92,12 @@ const GatesConfig = z.strictObject({
   // suppresses the PR comment when explicitly false. See
   // docs/gate-review-sub-loop-contract.md.
   postFindingsComments: z.boolean().default(true),
+  // Explicit global lens catalog override for additive angle selection
+  // (gates.<gate>.additiveAngles, #1048). When absent, resolveAnglePool()
+  // falls back to the union of the built-in persona registry's angle names
+  // and every angle configured across this config's own draft/preApproval/
+  // spike gates (angles + mandatoryAngles).
+  anglePool: z.array(z.string().trim().min(1)).optional(),
 });
 
 const AutonomyConfig = z.strictObject({
@@ -90,7 +113,7 @@ const AutonomyConfig = z.strictObject({
 
 /**
  * Human-handoff config (#920, Request B of #910): at the pre-approval /
- * merge-handoff boundary, OFFER to assign the PR to a named human
+ * merge-handoff boundary, OFFER to assign the PR to a contributor
  * reviewer/assignee. Opt-in (default off). Pairs with autonomy.humanMergeOnly.
  * `candidatesFrom` selects which sources the resolver queries; `assignees` is a
  * static highest-priority candidate list. Absent/empty = disabled no-op.
@@ -110,12 +133,6 @@ const ApprovalConfig = z.strictObject({
 const WorkflowConfig = z.strictObject({
   asyncStartMode: z.enum(["required", "allowed"]).default("required"),
   requireRetrospective: z.boolean(),
-  requireRetrospectiveGate: z.boolean().default(false),
-  // Developer-mode retro step (#982): enforce internal-tooling-only execution
-  // (no agent-level raw gh/python/node -e) in the retrospective gate. This is the
-  // dev-loops maintainers' own dogfooding discipline — opt-in, default OFF so
-  // consumers of the extension are never blocked by it.
-  requireRetrospectiveInternalTooling: z.boolean().default(false),
   requireDraftFirst: z.boolean(),
   devModeDefault: z.boolean(),
 });
@@ -151,16 +168,6 @@ const WorktreeConfig = z.strictObject({
   linkOnInit: z.array(z.string().trim().min(1)).optional(),
 });
 
-/**
- * Local-planning config (#949): where persisted markdown plan files (phase-doc
- * format) live when work originates from a plan file rather than a tracker
- * issue. `plansDir` is a repo-relative directory; defaults to the existing
- * phase-docs directory. See skills/docs/plan-file-contract.md.
- */
-const LocalPlanningConfig = z.strictObject({
-  plansDir: z.string().trim().min(1).optional(),
-});
-
 /** Internal path whitelist for internal-only PR detection — flat array of regex strings */
 const InternalPatternsConfig = z.array(z.string().trim().min(1)).min(1);
 
@@ -182,8 +189,10 @@ const FileGatesConfig = z.strictObject({
   preApproval: FileGateConfig.optional(),
   spike: FileGateConfig.optional(),
   requireFanoutEvidence: z.boolean().optional(),
+  requireFanoutProvenance: z.boolean().optional(),
   maxFanoutReviewers: z.number().int().min(1).max(64).optional(),
   postFindingsComments: z.boolean().optional(),
+  anglePool: z.array(z.string().trim().min(1)).optional(),
 });
 
 // Partial persona entries for file-level config (allows omitting fields)
@@ -212,7 +221,9 @@ export const DevLoopConfigSchema = z.strictObject({
   personas: PersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.optional(),
-  localPlanning: LocalPlanningConfig.optional(),
+  // Deprecated (removed in #1088): tolerated so consumer .devloops files that
+  // still carry a localPlanning block keep parsing. Accepted, never read.
+  localPlanning: z.unknown().optional(),
 });
 
 // ============================================================================
@@ -221,7 +232,7 @@ export const DevLoopConfigSchema = z.strictObject({
 
 export const BUILT_IN_DEFAULTS = Object.freeze({
   version: 1,
-  strategy: Object.freeze({ default: "github-first" }),
+  strategy: Object.freeze({ default: "local-first" }),
   inputSource: Object.freeze({ default: "tracker" }),
   models: Object.freeze({}),
   refinement: Object.freeze({ fanOut: 3, mode: "parallel", maxCopilotRounds: 5, stopOnLowSignal: false, lowSignalRoundThreshold: 3, lowSignalMaxComments: 2 }),
@@ -237,8 +248,6 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
   workflow: Object.freeze({
     asyncStartMode: "required",
     requireRetrospective: false,
-    requireRetrospectiveGate: false,
-    requireRetrospectiveInternalTooling: false,
     requireDraftFirst: false,
     devModeDefault: false,
   }),
@@ -263,7 +272,6 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     "^test/",
   ]),
   worktree: Object.freeze({ copyOnInit: Object.freeze([]), linkOnInit: Object.freeze([]) }),
-  localPlanning: Object.freeze({ plansDir: "docs/phases/" }),
 });
 
 // ============================================================================
@@ -285,7 +293,9 @@ export const FileConfigSchema = z.strictObject({
   personas: FilePersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.partial().optional(),
-  localPlanning: LocalPlanningConfig.partial().optional(),
+  // Deprecated (removed in #1088): tolerated so consumer .devloops files that
+  // still carry a localPlanning block keep parsing. Accepted, never read.
+  localPlanning: z.unknown().optional(),
 });
 
 // ============================================================================
@@ -943,7 +953,7 @@ export function resolveRefinement(config) {
  *
  * @param {DevLoopConfig} config
  * @param {"draft"|"preApproval"|"spike"} gate
- * @returns {{ angles: string[]|null, excludeAngles: string[], mandatoryAngles: string[], required: boolean, requireCi: boolean, blockCleanOnFindingSeverities: string[], dynamicAngles: boolean }}
+ * @returns {{ angles: string[]|null, excludeAngles: string[], mandatoryAngles: string[], required: boolean, requireCi: boolean, blockCleanOnFindingSeverities: string[], dynamicAngles: boolean, additiveAngles: boolean }}
  */
 export function resolveGateConfig(config, gate) {
   const gateConfig = config?.gates?.[gate];
@@ -960,6 +970,7 @@ export function resolveGateConfig(config, gate) {
     required: gateConfig?.required ?? true,
     requireCi: gateConfig?.requireCi ?? true,
     dynamicAngles: gateConfig?.dynamicAngles ?? false,
+    additiveAngles: gateConfig?.additiveAngles ?? false,
     blockCleanOnFindingSeverities: gateConfig?.blockCleanOnFindingSeverities && Array.isArray(gateConfig.blockCleanOnFindingSeverities)
       ? [...gateConfig.blockCleanOnFindingSeverities]
       : ["must-fix"],
@@ -984,28 +995,30 @@ export function resolveRequireFanoutEvidence(config) {
   return config?.gates?.requireFanoutEvidence !== false;
 }
 
-/** Default parallel fan-out reviewer cap (mirrors GatesConfig.maxFanoutReviewers). */
-export const DEFAULT_MAX_FANOUT_REVIEWERS = 8;
+/**
+ * Minimum distinct reviewer count for a fanout_fanin ledger to satisfy
+ * requireFanoutProvenance. A floor of 2 is the smallest count that is not a
+ * single agent; it raises the bar but does not prove independence (provenance
+ * is self-reported — see the honest caveat in
+ * docs/gate-review-sub-loop-contract.md).
+ */
+export const FANOUT_PROVENANCE_MIN_REVIEWERS = 2;
 
 /**
- * Resolve the parallel fan-out reviewer cap for the gate sub-loop.
+ * Resolve whether fan-out *provenance* is required for a fanout_fanin gate
+ * verdict (distinct reviewer count + per-angle dispatch recorded in the ledger).
  *
- * Returns the configured `gates.maxFanoutReviewers` when it is an integer in
- * the schema-bounded range 1..64; otherwise the built-in default (8). Clamping
- * here (not just the Zod schema) keeps programmatically-constructed config
- * objects that bypass schema validation within the same bound. The fan-out
- * spawns at most this many scoped `review` reviewers in parallel; overflow runs
- * sequentially.
+ * Default-OFF (opt-in): unlike resolveRequireFanoutEvidence, this uses a strict
+ * `=== true` test so behavior is byte-identical to today unless a repo
+ * explicitly opts in via `gates.requireFanoutProvenance: true`. Layered on top
+ * of fan-out evidence enforcement (see buildFanoutEnforcement). See
+ * docs/gate-review-sub-loop-contract.md.
  *
  * @param {DevLoopConfig} config
- * @returns {number}
+ * @returns {boolean}
  */
-export function resolveMaxFanoutReviewers(config) {
-  const raw = config?.gates?.maxFanoutReviewers;
-  if (typeof raw === "number" && Number.isInteger(raw) && raw >= 1 && raw <= 64) {
-    return raw;
-  }
-  return DEFAULT_MAX_FANOUT_REVIEWERS;
+export function resolveRequireFanoutProvenance(config) {
+  return config?.gates?.requireFanoutProvenance === true;
 }
 
 /**
@@ -1048,6 +1061,60 @@ export function resolveLightMode(config) {
   };
 }
 
+/** Label that forces full fan-out regardless of change size. */
+export const GATE_FULL_LABEL = "gate:full";
+
+/**
+ * Decide whether a gate should run as a single-agent inline check or the full
+ * fan-out, from light-mode config + authoritative PR facts.
+ *
+ * Precedence (first match wins):
+ *   1. `gate:full` label present            → full_fanout (label override)
+ *   2. light mode disabled / no threshold    → full_fanout (light mode off)
+ *   3. scope over threshold (files OR lines) → full_fanout (over threshold)
+ *   4. inline check produced a finding whose severity is in the gate's
+ *      blockCleanOnFindingSeverities set     → full_fanout (escalated)
+ *   5. otherwise                             → inline
+ *
+ * Two call phases share this one function:
+ *   - pre-check: omit `inlineFindingSeverities` (undefined) → decides whether to
+ *     run the inline pass at all.
+ *   - escalation: pass the inline pass's finding severities → auto-escalates when
+ *     the inline check surfaced anything worth fixing.
+ *
+ * Absent or partial `facts.scope` fails safe to full_fanout (missing
+ * filesChanged/linesChanged are treated as `Infinity` → over threshold).
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"} gate
+ * @param {object} facts
+ * @param {{ filesChanged?: number, linesChanged?: number }} [facts.scope] PR scope; absent/partial fields fail safe to full_fanout
+ * @param {boolean} [facts.hasFullLabel]           `gate:full` label present on the PR
+ * @param {string[]} [facts.inlineFindingSeverities] severities from the inline pass (escalation phase)
+ * @returns {{ mode: "inline"|"full_fanout", reason: string, threshold: {maxFiles:number,maxLines:number}|null }}
+ */
+export function resolveGateDispatchMode(config, gate, { scope, hasFullLabel = false, inlineFindingSeverities } = {}) {
+  if (hasFullLabel) {
+    return { mode: "full_fanout", reason: "gate_full_label", threshold: null };
+  }
+  const threshold = resolveLightMode(config);
+  if (!threshold) {
+    return { mode: "full_fanout", reason: "light_mode_disabled", threshold: null };
+  }
+  const filesChanged = Number(scope?.filesChanged ?? Infinity);
+  const linesChanged = Number(scope?.linesChanged ?? Infinity);
+  if (filesChanged > threshold.maxFiles || linesChanged > threshold.maxLines) {
+    return { mode: "full_fanout", reason: "over_threshold", threshold };
+  }
+  if (Array.isArray(inlineFindingSeverities) && inlineFindingSeverities.length > 0) {
+    const blocking = new Set(resolveGateConfig(config, gate).blockCleanOnFindingSeverities);
+    if (inlineFindingSeverities.some((s) => blocking.has(s))) {
+      return { mode: "full_fanout", reason: "escalated", threshold };
+    }
+  }
+  return { mode: "inline", reason: "under_threshold", threshold };
+}
+
 /**
  * Resolve review angles for a specific gate from the merged dev-loop config.
  *
@@ -1068,6 +1135,32 @@ export function resolveGateAngles(config, gate) {
   return merged.filter(a => !excluded.has(a));
 }
 
+/**
+ * Resolve the global lens catalog available for additive angle selection.
+ *
+ * Returns the explicit `gates.anglePool` override when configured (non-empty
+ * array of trimmed strings). Otherwise falls back to the union of all known
+ * review angles: the built-in persona registry's angle names, plus every
+ * angle actually configured across this config's own draft/preApproval/spike
+ * gates (angles + mandatoryAngles). The persona registry alone omits angles
+ * that ship in extension-defaults.yaml gate pools but have no dedicated
+ * persona (e.g. ci-guard, link-check) — see #1048.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {string[]}
+ */
+export function resolveAnglePool(config) {
+  const explicit = config?.gates?.anglePool;
+  if (Array.isArray(explicit) && explicit.length > 0) {
+    return [...new Set(explicit.map(a => (typeof a === "string" ? a.trim() : "")).filter(a => a.length > 0))];
+  }
+  const configured = ["draft", "preApproval", "spike"].flatMap((gate) => {
+    const gateConfig = resolveGateConfig(config, gate);
+    return [...(gateConfig.angles ?? []), ...gateConfig.mandatoryAngles];
+  });
+  return [...new Set([...Object.keys(BUILTIN_PERSONAS), ...configured])];
+}
+
 /**
  * Resolve gate angles dynamically when `dynamicAngles` is enabled in config.
  *
@@ -1077,17 +1170,23 @@ export function resolveGateAngles(config, gate) {
  * When `dynamicAngles` is disabled (default), returns the full configured
  * angle list (same as `resolveGateAngles`).
  *
+ * When `additiveAngles` is also enabled (default off, see #1048), catalog
+ * angles from `resolveAnglePool()` (`gates.anglePool`, or else the union of
+ * the persona registry and this config's own configured angles) recommended
+ * by change-category heuristics but absent from the gate's configured pool
+ * may also be added; `excludeAngles` remains a hard ceiling on additions.
+ *
  * @param {import("./types.js").DevLoopConfig} config
  * @param {"draft"|"preApproval"} gate
  * @param {object} [options]
  * @param {{ nameStatusOutput: string, diffOutput?: string }} [options.diff]
- * @returns {{ recommendedAngles: string[] | null, skippedAngles: string[], reasons: Record<string,string>, fallbackToAll: boolean, dynamicAnglesActive: boolean }}
+ * @returns {{ recommendedAngles: string[] | null, skippedAngles: string[], reasons: Record<string,string>, fallbackToAll: boolean, dynamicAnglesActive: boolean, addedAngles: string[], addedReasons: Record<string,string> }}
  */
 export async function resolveGateAnglesDynamic(config, gate, { diff } = {}) {
   const gateConfig = resolveGateConfig(config, gate);
   const staticAngles = resolveGateAngles(config, gate);
   if (staticAngles === null) {
-    return { recommendedAngles: null, skippedAngles: [], reasons: {}, fallbackToAll: false, dynamicAnglesActive: false };
+    return { recommendedAngles: null, skippedAngles: [], reasons: {}, fallbackToAll: false, dynamicAnglesActive: false, addedAngles: [], addedReasons: {} };
   }
 
   if (!gateConfig.dynamicAngles || !diff) {
@@ -1097,6 +1196,8 @@ export async function resolveGateAnglesDynamic(config, gate, { diff } = {}) {
       reasons: {},
       fallbackToAll: false,
       dynamicAnglesActive: false,
+      addedAngles: [],
+      addedReasons: {},
     };
   }
 
@@ -1114,17 +1215,35 @@ export async function resolveGateAnglesDynamic(config, gate, { diff } = {}) {
 
   const categories = [...new Set(analysis.t1?.changeCategories ?? [])];
 
+  // excludeAngles is a hard ceiling: computed once and reused both to cap the
+  // additive anglePool and to filter mandatoryAngles below.
+  const excluded = new Set(gateConfig.excludeAngles);
+  const anglePool = gateConfig.additiveAngles
+    ? resolveAnglePool(config).filter(a => !excluded.has(a))
+    : undefined;
+
   const { resolveDynamicAngles: resolve } = await import("../analysis/change-classifier.mjs");
   const dynamicResult = resolve({
     configuredAngles: candidatePool,
     changeCategories: categories,
     ambiguous: analysis.ambiguous,
+    anglePool,
   });
 
-  // Merge: mandatory always included (filtered by excludeAngles) + dynamically-selected candidates
-  const excluded = new Set(gateConfig.excludeAngles);
+  // Merge: mandatory always included (filtered by excludeAngles) + dynamically-selected
+  // candidates + additively-selected catalog angles (#1048)
   const filteredMandatory = gateConfig.mandatoryAngles.filter(a => !excluded.has(a));
-  const recommendedAngles = [...new Set([...filteredMandatory, ...dynamicResult.recommendedAngles])];
+
+  // An angle that is both mandatory AND additively recommended must stay
+  // attributed to the mandatory floor, not be reported as "added" — the
+  // resolver has no concept of "mandatory", so the caller (this function,
+  // which already owns the mandatory Set) filters its output.
+  const addedAngles = (dynamicResult.addedAngles ?? []).filter(a => !mandatory.has(a));
+  const addedReasons = Object.fromEntries(
+    Object.entries(dynamicResult.addedReasons ?? {}).filter(([a]) => !mandatory.has(a))
+  );
+
+  const recommendedAngles = [...new Set([...filteredMandatory, ...dynamicResult.recommendedAngles, ...addedAngles])];
 
   return {
     recommendedAngles,
@@ -1132,6 +1251,8 @@ export async function resolveGateAnglesDynamic(config, gate, { diff } = {}) {
     reasons: dynamicResult.reasons,
     fallbackToAll: dynamicResult.fallbackToAll,
     dynamicAnglesActive: true,
+    addedAngles,
+    addedReasons,
   };
 }
 
@@ -1142,7 +1263,7 @@ export async function resolveGateAnglesDynamic(config, gate, { diff } = {}) {
  * for the requested key.
  *
  * @param {DevLoopConfig} config
- * @param {"asyncStartMode"|"requireRetrospective"|"requireRetrospectiveGate"|"requireRetrospectiveInternalTooling"|"requireDraftFirst"|"devModeDefault"} key
+ * @param {"asyncStartMode"|"requireRetrospective"|"requireDraftFirst"|"devModeDefault"} key
  * @returns {string|boolean}
  */
 export function resolveWorkflowConfig(config, key) {
@@ -1154,14 +1275,6 @@ export function resolveWorkflowConfig(config, key) {
     return config?.workflow?.requireRetrospective ?? DEFAULT_WORKFLOW_CONFIG.requireRetrospective;
   }
 
-  if (key === "requireRetrospectiveGate") {
-    return config?.workflow?.requireRetrospectiveGate ?? DEFAULT_WORKFLOW_CONFIG.requireRetrospectiveGate;
-  }
-
-  if (key === "requireRetrospectiveInternalTooling") {
-    return config?.workflow?.requireRetrospectiveInternalTooling ?? DEFAULT_WORKFLOW_CONFIG.requireRetrospectiveInternalTooling;
-  }
-
   if (key === "requireDraftFirst") {
     return config?.workflow?.requireDraftFirst ?? DEFAULT_WORKFLOW_CONFIG.requireDraftFirst;
   }
@@ -1173,20 +1286,6 @@ export function resolveWorkflowConfig(config, key) {
   throw new Error(`Unknown workflow config key: ${key}`);
 }
 
-const DEFAULT_INTERNAL_PATH_PATTERNS = BUILT_IN_DEFAULTS.internalPathPatterns;
-
-/**
- * Resolve the internal path patterns from the merged dev-loop config.
- *
- * Returns an array of regex pattern strings used by detect-internal-only-pr.mjs
- * to classify files as internal tooling (vs consumer-facing). When the config
- * omits this section, returns the built-in shipped defaults.
- *
- * Consumers can override these in .devloops at repo root.
- *
- * @param {DevLoopConfig} config
- * @returns {string[]}
- */
 /**
  * Resolve the worktree lifecycle config from the merged dev-loop config.
  *
@@ -1207,24 +1306,6 @@ export function resolveWorktreeConfig(config) {
   return { copyOnInit: list(wt?.copyOnInit), linkOnInit: list(wt?.linkOnInit) };
 }
 
-/**
- * Resolve the local-planning plans directory from the merged dev-loop config.
- *
- * Returns the configured `localPlanning.plansDir` (trimmed) when present and
- * non-empty, otherwise the built-in default (`docs/phases/`) — the existing
- * phase-docs directory. See skills/docs/plan-file-contract.md.
- *
- * @param {DevLoopConfig} config
- * @returns {string}
- */
-export function resolvePlansDir(config) {
-  const raw = config?.localPlanning?.plansDir;
-  if (typeof raw === "string" && raw.trim().length > 0) {
-    return raw.trim();
-  }
-  return BUILT_IN_DEFAULTS.localPlanning.plansDir;
-}
-
 /**
  * Resolve the human-handoff config from the merged dev-loop config (#920).
  *
@@ -1259,14 +1340,3 @@ export function resolveHumanHandoffConfig(config) {
     assignees: enabled ? assignees : [],
   };
 }
-
-export function resolveInternalPathPatterns(config) {
-  if (
-    config?.internalPathPatterns &&
-    Array.isArray(config.internalPathPatterns) &&
-    config.internalPathPatterns.length > 0
-  ) {
-    return [...config.internalPathPatterns];
-  }
-  return [...DEFAULT_INTERNAL_PATH_PATTERNS];
-}

package/src/config/extension-defaults.yaml

@@ -100,12 +100,6 @@ workflow:
   # default (DEFAULT_WORKFLOW_CONFIG) and the contract. The dev-loops repo opts in via its own
   # repo-root .devloops, which takes precedence over these extension defaults.
   requireRetrospective: false
-  requireRetrospectiveGate: false
-  # Internal-tooling-only retro check (#982) is a DEVELOPER-MODE step — the dev-loops
-  # maintainers' own dogfooding discipline. It must never block a consumer's state
-  # changes (consumers may legitimately use raw gh/python/node -e), so it ships OFF.
-  # The dev-loops repo opts in via its own repo-root .devloops (takes precedence here).
-  requireRetrospectiveInternalTooling: false
   requireDraftFirst: true
   # Dev mode is the dev-loop self-improvement mode — it edits the loop's own skill/agent prompts
   # after a phase, which is only meaningful in the dev-loops repo. Shipped defaults must not force
@@ -113,11 +107,6 @@ workflow:
   # via its own repo-root .devloops (which takes precedence over these extension defaults).
   devModeDefault: false
 
-# Local-planning: where persisted markdown plan files (phase-doc format) live
-# when work originates from a plan file rather than a tracker issue (#949).
-localPlanning:
-  plansDir: docs/phases/
-
 # Light-mode threshold for small local changes.
 localImplementation:
   lightMode:

package/src/harness/extension-adapter.mjs

@@ -30,6 +30,7 @@
  * @property {string} cwd - Working directory for the current invocation.
  * @property {boolean} hasUI - Whether an interactive UI surface is attached.
  * @property {HarnessUi} ui - UI operations for this invocation.
+ * @property {((message: string, options?: Record<string, unknown>) => unknown) | undefined} sendUserMessage - Optional: send a user-turn message into the harness (Pi extension only; absent in other harnesses).
  *
  * @typedef {'session_start'|'tool_result'|'user_bash'|'agent_end'} HarnessLifecycleEvent
  *

package/src/harness/index.mjs

@@ -2,4 +2,3 @@ export { createHarnessAdapter, isHarnessAdapter } from "./adapter.mjs";
 export { createPiAdapter } from "./pi-adapter.mjs";
 export { createNoopAdapter } from "./noop-adapter.mjs";
 export { createExtensionHarnessAdapter } from "./extension-adapter.mjs";
-export { createClaudeExtensionAdapter } from "./claude-extension-adapter.mjs";

package/src/loop/async-start-contract.mjs

@@ -13,6 +13,7 @@
  * Async context marker (required when workflow.asyncStartMode is `required`)
  * — see `@dev-loops/core/loop/run-context`:
  * - DEVLOOPS_RUN_ID env var (neutral, harness-agnostic)
+ * - PI_SUBAGENT_RUN_ID env var (the alias the Pi runtime injects)
  *
  * Allowed modes:
  * - workflow.asyncStartMode: required | allowed
@@ -159,14 +160,20 @@ export function validateAsyncStartContext({
     };
   }
 
-  // No marker found — fail closed
+  // No marker found — fail closed.
+  // Derive the marker hint from ASYNC_CONTEXT_MARKERS (primary first, aliases after)
+  // so the message never drifts from the recognized-marker list.
+  const [primaryMarker, ...aliasMarkers] = ASYNC_CONTEXT_MARKERS;
+  const markerHint = aliasMarkers.length
+    ? `Set ${primaryMarker} (or the ${aliasMarkers.join("/")} alias) to proceed. `
+    : `Set ${primaryMarker} to proceed. `;
   return {
     status: ASYNC_START_STATUS.REJECTED,
     reason:
       "No async context detected. " +
       "The dev-loop must run within a visible async subagent session, " +
       "not as a detached local process. " +
-      `Set ${ASYNC_CONTEXT_MARKERS[0]} to proceed. ` +
+      markerHint +
       "Repository-maintained workflow policy controls any exceptions.",
     detectedMarker: null,
   };