@dev-loops/core 0.3.0 → 0.5.0

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {
     "./bash-exit-one": "./src/bash-exit-one.mjs",
@@ -34,6 +37,9 @@
     "./loop/issue-refinement-artifact": "./src/loop/issue-refinement-artifact.mjs",
     "./loop/phase-files": "./src/loop/phase-files.mjs",
     "./loop/policy-constants": "./src/loop/policy-constants.mjs",
+    "./loop/plan-file-intake-contract": "./src/loop/plan-file-intake-contract.mjs",
+    "./loop/plan-file-promote-contract": "./src/loop/plan-file-promote-contract.mjs",
+    "./loop/plan-file-refine-contract": "./src/loop/plan-file-refine-contract.mjs",
     "./loop/pr-gate-coordination": "./src/loop/pr-gate-coordination.mjs",
     "./loop/pr-title-markers": "./src/loop/pr-title-markers.mjs",
     "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
@@ -45,6 +51,8 @@
     "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",
     "./loop/run-context": "./src/loop/run-context.mjs",
     "./loop/run-inspection": "./src/loop/run-inspection.mjs",
+    "./loop/spike-exit-contract": "./src/loop/spike-exit-contract.mjs",
+    "./loop/spike-intake-contract": "./src/loop/spike-intake-contract.mjs",
     "./loop/steering": "./src/loop/steering.mjs",
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
     "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",

package/src/config/config.mjs

@@ -53,6 +53,12 @@ const GatesConfig = z.strictObject({
   // `requireCi` is only behaviorally configurable for the draft gate.
   // preApproval always requires CI even if config repeats `requireCi`.
   preApproval: GateConfig.optional(),
+  // Relaxed spike gate profile (#965). A spike's deliverable is a findings doc,
+  // not production code, so it should not carry the full draft → pre-approval →
+  // Copilot production set. Resolved through the same config-merge layering and
+  // the same resolveGateConfig path as draft/preApproval — no new strategy→knob
+  // resolver. Absent for non-spike work, so production gates are unaffected.
+  spike: GateConfig.optional(),
   // Fail-closed enforcement that a gate verdict was produced by the
   // fan-out/fan-in review sub-loop (executionMode === "fanout_fanin" plus a
   // durable findings-log ledger), not an inline single-agent run. Default
@@ -75,12 +81,41 @@ const AutonomyConfig = z.strictObject({
   stopAt: z.array(
     z.enum(["refinement", "draft-pr", "pre-approval", "merge"])
   ),
+  // When true, merge is a fixed, non-overridable human action: the agent never
+  // runs `gh pr merge`, `resolveAutonomyStopAt` always includes "merge", and
+  // any per-run merge authorization (envelope flag / explicit instruction) is
+  // ignored — it fails closed. See resolveHumanMergeOnly / resolveEffectiveMergeAuthorized.
+  humanMergeOnly: z.boolean().optional(),
+});
+
+/**
+ * Human-handoff config (#920, Request B of #910): at the pre-approval /
+ * merge-handoff boundary, OFFER to assign the PR to a named human
+ * 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.
+ */
+const HumanHandoffConfig = z.strictObject({
+  enabled: z.boolean().default(false),
+  candidatesFrom: z
+    .array(z.enum(["codeowners", "recent-committers"]))
+    .optional(),
+  assignees: z.array(z.string().trim().min(1)).optional(),
+});
+
+const ApprovalConfig = z.strictObject({
+  humanHandoff: HumanHandoffConfig.optional(),
 });
 
 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(),
 });
@@ -104,6 +139,28 @@ const QueueConfig = z.strictObject({
   archiveOlderThanDays: z.number().int().positive().optional(),
 });
 
+/**
+ * Worktree lifecycle config (#909): which gitignored files/dirs to provision
+ * into a fresh worktree from the main checkout. Entries are repo-relative
+ * literal paths OR glob patterns. `copyOnInit` → `fs.cp` (isolated per
+ * worktree); `linkOnInit` → absolute symlink into the main checkout (read-only
+ * data). Both optional; empty/absent is a valid no-op.
+ */
+const WorktreeConfig = z.strictObject({
+  copyOnInit: z.array(z.string().trim().min(1)).optional(),
+  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);
 
@@ -123,6 +180,7 @@ const FileGateConfig = GateConfig.partial();
 const FileGatesConfig = z.strictObject({
   draft: FileGateConfig.optional(),
   preApproval: FileGateConfig.optional(),
+  spike: FileGateConfig.optional(),
   requireFanoutEvidence: z.boolean().optional(),
   maxFanoutReviewers: z.number().int().min(1).max(64).optional(),
   postFindingsComments: z.boolean().optional(),
@@ -147,11 +205,14 @@ export const DevLoopConfigSchema = z.strictObject({
   refinement: RefinementConfig.optional(),
   gates: GatesConfig.optional(),
   autonomy: AutonomyConfig.optional(),
+  approval: ApprovalConfig.optional(),
   workflow: WorkflowConfig.optional(),
   localImplementation: LocalImplementationConfig.optional(),
   queue: QueueConfig.optional(),
   personas: PersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
+  worktree: WorktreeConfig.optional(),
+  localPlanning: LocalPlanningConfig.optional(),
 });
 
 // ============================================================================
@@ -165,11 +226,19 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
   models: Object.freeze({}),
   refinement: Object.freeze({ fanOut: 3, mode: "parallel", maxCopilotRounds: 5, stopOnLowSignal: false, lowSignalRoundThreshold: 3, lowSignalMaxComments: 2 }),
   gates: Object.freeze({}),
-  autonomy: Object.freeze({ stopAt: Object.freeze(["merge"]) }),
+  autonomy: Object.freeze({ stopAt: Object.freeze(["merge"]), humanMergeOnly: false }),
+  approval: Object.freeze({
+    humanHandoff: Object.freeze({
+      enabled: false,
+      candidatesFrom: Object.freeze([]),
+      assignees: Object.freeze([]),
+    }),
+  }),
   workflow: Object.freeze({
     asyncStartMode: "required",
     requireRetrospective: false,
     requireRetrospectiveGate: false,
+    requireRetrospectiveInternalTooling: false,
     requireDraftFirst: false,
     devModeDefault: false,
   }),
@@ -193,6 +262,8 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     "^\\.github/",
     "^test/",
   ]),
+  worktree: Object.freeze({ copyOnInit: Object.freeze([]), linkOnInit: Object.freeze([]) }),
+  localPlanning: Object.freeze({ plansDir: "docs/phases/" }),
 });
 
 // ============================================================================
@@ -207,11 +278,14 @@ export const FileConfigSchema = z.strictObject({
   refinement: RefinementConfig.partial().optional(),
   gates: FileGatesConfig.optional(),
   autonomy: AutonomyConfig.partial().optional(),
+  approval: ApprovalConfig.partial().optional(),
   workflow: WorkflowConfig.partial().optional(),
   localImplementation: LocalImplementationConfig.partial().optional(),
   queue: QueueConfig.partial().optional(),
   personas: FilePersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
+  worktree: WorktreeConfig.partial().optional(),
+  localPlanning: LocalPlanningConfig.partial().optional(),
 });
 
 // ============================================================================
@@ -727,10 +801,66 @@ export function resolveConductorModel(config) {
  * @returns {string[]}
  */
 export function resolveAutonomyStopAt(config) {
-  if (config?.autonomy?.stopAt && Array.isArray(config.autonomy.stopAt)) {
-    return [...config.autonomy.stopAt];
+  const base = (config?.autonomy?.stopAt && Array.isArray(config.autonomy.stopAt))
+    ? [...config.autonomy.stopAt]
+    : ["merge"];
+  // Fail closed: humanMergeOnly forces a human stop at merge regardless of
+  // what stopAt is configured (even an explicit []).
+  if (resolveHumanMergeOnly(config) && !base.includes("merge")) {
+    base.push("merge");
   }
-  return ["merge"];
+  return base;
+}
+
+/**
+ * Resolve the fixed human-merge-only invariant from the merged dev-loop config.
+ *
+ * When true, the agent must never perform the merge itself: `gh pr merge` is a
+ * human-only action and any per-run merge authorization is ignored. Defaults to
+ * false (the agent may merge once authorized).
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveHumanMergeOnly(config) {
+  return config?.autonomy?.humanMergeOnly === true;
+}
+
+/**
+ * Authoritative gate: resolve the effective merge authorization for the agent.
+ *
+ * This is the single chokepoint that decides whether the agent is cleared to
+ * run `gh pr merge`. When `humanMergeOnly` is set on the repo config, this
+ * ALWAYS returns false — the per-run `mergeAuthorized` flag (envelope flag or
+ * explicit "merge" instruction) cannot override the repo invariant. Fails
+ * closed: a non-boolean `mergeAuthorized` is treated as not authorized.
+ *
+ * @param {boolean} mergeAuthorized per-run authorization signal
+ * @param {DevLoopConfig} config merged dev-loop config
+ * @returns {boolean}
+ */
+export function resolveEffectiveMergeAuthorized(mergeAuthorized, config) {
+  if (resolveHumanMergeOnly(config)) return false;
+  return mergeAuthorized === true;
+}
+
+/**
+ * Authoritative gate for callers that load the config themselves and hold its
+ * `{ config, errors }` load result. FAILS CLOSED on any config load/validation
+ * error: `loadDevLoopConfig` never throws (it returns an `errors` array), so a
+ * caller must not assume "no exception" means "config is safe". If the config
+ * could not be loaded/validated, the `.devloops` file declaring `humanMergeOnly`
+ * may be the very one that failed — so merge authorization is denied rather than
+ * silently granted from a fallback config that lacks the invariant.
+ *
+ * @param {boolean} mergeAuthorized per-run authorization signal
+ * @param {{ config?: DevLoopConfig, errors?: Array<unknown> }} loadResult result of `loadDevLoopConfig`
+ * @returns {boolean}
+ */
+export function resolveEffectiveMergeAuthorizedFromLoad(mergeAuthorized, loadResult) {
+  const errors = loadResult?.errors ?? [];
+  if (errors.length > 0) return false;
+  return resolveEffectiveMergeAuthorized(mergeAuthorized, loadResult?.config);
 }
 
 const DEFAULT_REFINEMENT_CONFIG = BUILT_IN_DEFAULTS.refinement;
@@ -812,7 +942,7 @@ export function resolveRefinement(config) {
  * flags always resolve to stable defaults.
  *
  * @param {DevLoopConfig} config
- * @param {"draft"|"preApproval"} gate
+ * @param {"draft"|"preApproval"|"spike"} gate
  * @returns {{ angles: string[]|null, excludeAngles: string[], mandatoryAngles: string[], required: boolean, requireCi: boolean, blockCleanOnFindingSeverities: string[], dynamicAngles: boolean }}
  */
 export function resolveGateConfig(config, gate) {
@@ -1012,7 +1142,7 @@ export async function resolveGateAnglesDynamic(config, gate, { diff } = {}) {
  * for the requested key.
  *
  * @param {DevLoopConfig} config
- * @param {"asyncStartMode"|"requireRetrospective"|"requireRetrospectiveGate"|"requireDraftFirst"|"devModeDefault"} key
+ * @param {"asyncStartMode"|"requireRetrospective"|"requireRetrospectiveGate"|"requireRetrospectiveInternalTooling"|"requireDraftFirst"|"devModeDefault"} key
  * @returns {string|boolean}
  */
 export function resolveWorkflowConfig(config, key) {
@@ -1028,6 +1158,10 @@ export function resolveWorkflowConfig(config, key) {
     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;
   }
@@ -1053,6 +1187,79 @@ const DEFAULT_INTERNAL_PATH_PATTERNS = BUILT_IN_DEFAULTS.internalPathPatterns;
  * @param {DevLoopConfig} config
  * @returns {string[]}
  */
+/**
+ * Resolve the worktree lifecycle config from the merged dev-loop config.
+ *
+ * Returns `{ copyOnInit, linkOnInit }` with empty-array defaults when the
+ * config omits the `worktree` section or either list. Entries are trimmed,
+ * repo-relative literal paths or glob patterns expanded against the main
+ * checkout at provision time. See scripts/loop/provision-worktree.mjs.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {{ copyOnInit: string[], linkOnInit: string[] }}
+ */
+export function resolveWorktreeConfig(config) {
+  const wt = config?.worktree;
+  const list = (v) =>
+    Array.isArray(v)
+      ? v.map((s) => (typeof s === "string" ? s.trim() : "")).filter((s) => s.length > 0)
+      : [];
+  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).
+ *
+ * Returns a normalized `{ enabled, candidatesFrom, assignees }`. Defaults to
+ * disabled with empty arrays when the `approval.humanHandoff` section is absent.
+ * When disabled (default), this is a no-op: callers must not source candidates
+ * or assign anyone. Pairs with `autonomy.humanMergeOnly`: when human-merge is
+ * enforced, this names who should take the merge.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {{ enabled: boolean, candidatesFrom: ("codeowners"|"recent-committers")[], assignees: string[] }}
+ */
+export function resolveHumanHandoffConfig(config) {
+  const hh = config?.approval?.humanHandoff;
+  const enabled = hh?.enabled === true;
+  const list = (v) =>
+    Array.isArray(v)
+      ? v.map((s) => (typeof s === "string" ? s.trim() : "")).filter((s) => s.length > 0)
+      : [];
+  const candidatesFrom = list(hh?.candidatesFrom).filter(
+    (s) => s === "codeowners" || s === "recent-committers"
+  );
+  // Normalize assignees: strip a leading `@`, trim, and drop empties so an empty
+  // login (e.g. config value of `"@"` or `""`) can never leak downstream into
+  // `gh pr edit --add-assignee ""`.
+  const assignees = list(hh?.assignees)
+    .map((s) => s.replace(/^@/, "").trim())
+    .filter((s) => s.length > 0);
+  return {
+    enabled,
+    candidatesFrom: enabled ? candidatesFrom : [],
+    assignees: enabled ? assignees : [],
+  };
+}
+
 export function resolveInternalPathPatterns(config) {
   if (
     config?.internalPathPatterns &&

package/src/config/extension-defaults.yaml

@@ -49,6 +49,9 @@ gates:
     requireCi: true
     mandatoryAngles:
       - pr-description
+  # Gate findings comments live ON the PR (the local-first spec-of-record /
+  # human-review surface), so they are evidence, not tracker noise — keep them on.
+  postFindingsComments: true
   preApproval:
     angles:
       - dry
@@ -67,11 +70,27 @@ gates:
     required: true
     mandatoryAngles:
       - pr-checklist-matrix
+  # Relaxed spike gate profile (#965). A spike's deliverable is a findings doc,
+  # not production code, so it is intentionally lighter than the production
+  # draft -> pre-approval -> Copilot set: a small docs-first angle set, not a
+  # required gate, and no CI prerequisite. Resolved through the same
+  # config-merge layering and resolveGateConfig path as draft/preApproval; only
+  # applies to spike-mode work, so production gates are unaffected.
+  spike:
+    angles:
+      - scope
+      - docs
+    excludeAngles: []
+    required: false
+    requireCi: false
+    mandatoryAngles: []
 
 # Autonomy: only merge requires operator confirmation by default.
 autonomy:
   stopAt:
     - merge
+  # Local-first never auto-merges; a human always merges.
+  humanMergeOnly: true
 
 # Workflow enforcement defaults.
 workflow:
@@ -82,6 +101,11 @@ workflow:
   # 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
@@ -89,6 +113,11 @@ 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:
@@ -99,7 +128,9 @@ localImplementation:
 # Queue defaults (repo-specific projectNumber/boardTitle omitted by design).
 queue:
   maxParallel: 3
-  maxAutoFiledIssues: 10
+  # Local-first is PR-first (issues are skipped, #952), so auto-filing issues is
+  # near-zero; a low cap keeps tracker noise minimal, especially early.
+  maxAutoFiledIssues: 1
   reDispatchMaxRetries: 1
 
 # Persona registry used by gate review angle resolution.

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

@@ -10,10 +10,9 @@
  * async context marker. When the marker is absent, the check fails closed
  * and returns a machine-readable rejection rather than silently proceeding.
  *
- * Async context markers (required when workflow.asyncStartMode is `required`),
- * neutral-first — see `@dev-loops/core/loop/run-context`:
+ * 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 (Pi subagent framework; retained as a compatibility alias)
  *
  * Allowed modes:
  * - workflow.asyncStartMode: required | allowed
@@ -30,11 +29,10 @@ import { RUN_ID_MARKERS, isClaudeHarness } from "./run-context.mjs";
 // ---------------------------------------------------------------------------
 
 /**
- * Environment variable names that indicate an async context, neutral-first.
+ * Environment variable names that indicate an async context.
  * Sourced from the shared run-context contract so the markers stay in one place.
- * The historical name is kept for back-compat; it now includes DEVLOOPS_RUN_ID.
  */
-export const PI_ASYNC_CONTEXT_MARKERS = RUN_ID_MARKERS;
+export const ASYNC_CONTEXT_MARKERS = RUN_ID_MARKERS;
 
 /** Supported workflow async-start modes. */
 export const ASYNC_START_MODE = Object.freeze({
@@ -130,8 +128,8 @@ export function validateAsyncStartContext({
     };
   }
 
-  // Check for any async context marker (neutral DEVLOOPS_RUN_ID or the Pi alias)
-  for (const marker of PI_ASYNC_CONTEXT_MARKERS) {
+  // Check for any async context marker (DEVLOOPS_RUN_ID)
+  for (const marker of ASYNC_CONTEXT_MARKERS) {
     const value = env[marker];
     if (typeof value === "string" && value.trim().length > 0) {
       return {
@@ -150,24 +148,7 @@ export function validateAsyncStartContext({
     };
   }
 
-  const sessionOnlyMarker =
-    (typeof env.PI_SESSION_ID === "string" && env.PI_SESSION_ID.trim().length > 0)
-      ? "PI_SESSION_ID"
-      : ((typeof env.PI_ASYNC_CONTEXT === "string" && env.PI_ASYNC_CONTEXT.trim().length > 0)
-          ? "PI_ASYNC_CONTEXT"
-          : null);
-  if (sessionOnlyMarker !== null) {
-    return {
-      status: ASYNC_START_STATUS.REJECTED,
-      reason:
-        `Detected ${sessionOnlyMarker}, but GitHub-first async-start requires a visible ` +
-        "subagent run id for inspectable startup/resume evidence. " +
-        "Set DEVLOOPS_RUN_ID (or the PI_SUBAGENT_RUN_ID alias) to proceed. Any exception must come from repository-maintained workflow policy.",
-      detectedMarker: null,
-    };
-  }
-
-  if (env.PI_DEV_LOOP_DETACHED === "1") {
+  if (env.DEVLOOPS_DETACHED === "1") {
     return {
       status: ASYNC_START_STATUS.REJECTED,
       reason:
@@ -185,7 +166,7 @@ export function validateAsyncStartContext({
       "No async context detected. " +
       "The dev-loop must run within a visible async subagent session, " +
       "not as a detached local process. " +
-      `Set ${PI_ASYNC_CONTEXT_MARKERS[0]} (or the PI_SUBAGENT_RUN_ID alias) to proceed. ` +
+      `Set ${ASYNC_CONTEXT_MARKERS[0]} to proceed. ` +
       "Repository-maintained workflow policy controls any exceptions.",
     detectedMarker: null,
   };

package/src/loop/handoff-envelope.mjs

@@ -21,6 +21,7 @@ import {
 import { normalizeRepoSlug } from "../github/repo-slug.mjs";
 import { COPILOT_REVIEW_WAIT_TIMEOUT_MS } from "./policy-constants.mjs";
 import { resolveEffectiveAsyncStartMode } from "./async-start-contract.mjs";
+import { resolveHumanMergeOnly } from "../config/config.mjs";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -243,10 +244,18 @@ function deriveTarget(bundle, repo) {
 // ---------------------------------------------------------------------------
 
 function deriveStopRules(settings, strategy) {
-  if (settings?.autonomy?.stopAt && Array.isArray(settings.autonomy.stopAt)) {
-    return [...settings.autonomy.stopAt];
+  const base = (settings?.autonomy?.stopAt && Array.isArray(settings.autonomy.stopAt))
+    ? [...settings.autonomy.stopAt]
+    : [...(STRATEGY_DEFAULT_STOP_RULES[strategy] ?? [])];
+  // Fail closed: humanMergeOnly forces "merge" into the dispatched agent's
+  // stopRules regardless of configured stopAt, mirroring the authoritative
+  // resolveAutonomyStopAt(config) invariant. Without this, a custom
+  // stopAt that omits "merge" (e.g. [] or ["draft-pr"]) would tell the agent
+  // NOT to stop at merge — a direct humanMergeOnly bypass.
+  if (resolveHumanMergeOnly(settings) && !base.includes("merge")) {
+    base.push("merge");
   }
-  return [...(STRATEGY_DEFAULT_STOP_RULES[strategy] ?? [])];
+  return base;
 }
 
 // ---------------------------------------------------------------------------
@@ -316,28 +325,61 @@ function deriveCwd(bundle, options = {}) {
   const kind = normalizeTargetKind(artifact.kind);
 
   if (root) {
+    // issue/pr go through the single source of truth (resolveWorktreePath); other
+    // slug kinds (local_branch/local_phase) still use the namespace + slug.
+    if (kind === DEV_LOOP_TARGET_KIND.ISSUE && Number.isInteger(artifact.issue) && artifact.issue > 0) {
+      return resolveWorktreePath({ repoRoot: root, kind: "issue", number: artifact.issue });
+    }
+    if (kind === DEV_LOOP_TARGET_KIND.PR && Number.isInteger(artifact.pr) && artifact.pr > 0) {
+      return resolveWorktreePath({ repoRoot: root, kind: "pr", number: artifact.pr });
+    }
     const slug = buildWorktreeSlug(artifact, kind);
     if (slug) {
-      return `${root}/tmp/worktrees/${slug}`;
+      return `${root}/${WORKTREE_NAMESPACE}/${slug}`;
     }
   }
 
   return null;
 }
 
+/** Repo-relative root for loop-owned worktrees. The `dev-loops/` namespace */
+/** marks them so cleanup can only ever remove its own (issue #909). */
+export const WORKTREE_NAMESPACE = "tmp/worktrees/dev-loops";
+
+/**
+ * Resolve the canonical, namespaced worktree path for an issue/PR. Sole source
+ * of truth shared by create, provision, and cleanup. No branch suffix, so the
+ * path is recomputable from the issue/PR number alone.
+ *
+ * @param {{ repoRoot: string, kind: "issue"|"pr", number: number }} args
+ * @returns {string} Absolute path `<repoRoot>/tmp/worktrees/dev-loops/<kind>-<number>`
+ */
+export function resolveWorktreePath({ repoRoot, kind, number } = {}) {
+  const root = normalizeString(repoRoot);
+  if (!root) throw new Error("resolveWorktreePath: repoRoot is required and must be a non-empty string");
+  const k = typeof kind === "string" ? kind.trim().toLowerCase() : "";
+  if (k !== DEV_LOOP_TARGET_KIND.ISSUE && k !== DEV_LOOP_TARGET_KIND.PR) {
+    throw new Error(`resolveWorktreePath: kind must be "issue" or "pr", got "${kind}"`);
+  }
+  if (!Number.isInteger(number) || number < 1) {
+    throw new Error(`resolveWorktreePath: number must be a positive integer, got ${number}`);
+  }
+  return `${root}/${WORKTREE_NAMESPACE}/${k}-${number}`;
+}
+
 function flattenSlugSegment(s) {
   if (typeof s !== "string") return "";
   return s.replace(/[/\\]/g, "-").replace(/[^a-zA-Z0-9._-]/g, "");
 }
 
 function buildWorktreeSlug(artifact, kind) {
+  // Canonical naming is namespaced + no branch suffix (issue #909) so the path
+  // is recomputable from the issue/PR number alone (cleanup can find it).
   if (kind === DEV_LOOP_TARGET_KIND.ISSUE && Number.isInteger(artifact.issue) && artifact.issue > 0) {
-    const branch = normalizeString(artifact.branch);
-    return branch ? `issue-${artifact.issue}-${flattenSlugSegment(branch)}` : `issue-${artifact.issue}`;
+    return `issue-${artifact.issue}`;
   }
   if (kind === DEV_LOOP_TARGET_KIND.PR && Number.isInteger(artifact.pr) && artifact.pr > 0) {
-    const branch = normalizeString(artifact.branch);
-    return branch ? `pr-${artifact.pr}-${flattenSlugSegment(branch)}` : `pr-${artifact.pr}`;
+    return `pr-${artifact.pr}`;
   }
   if (kind === DEV_LOOP_TARGET_KIND.LOCAL_BRANCH) {
     const branch = normalizeString(artifact.branch);

package/src/loop/lifecycle-state.mjs

@@ -162,6 +162,7 @@ function normalizeLifecycleState(value) {
  *   hasUnresolvedThreads, // boolean: unresolved review threads exist
  *   preApprovalGatePassed, // boolean: current-head pre_approval_gate clean
  *   mergeAuthorized,    // boolean: explicit merge authorization granted
+ *   humanMergeOnly,     // boolean: repo invariant — agent may never merge (fails closed)
  *   isMerged,           // boolean: PR has been merged
  * }
  * ```
@@ -194,9 +195,18 @@ export function resolveLifecycleState(input = {}) {
     hasUnresolvedThreads = false,
     preApprovalGatePassed = false,
     mergeAuthorized = false,
+    humanMergeOnly = false,
     isMerged = false,
   } = input;
 
+  // Fail closed: when the repo enforces human-only merge, the agent is never
+  // cleared to advance to the merge action — the per-run mergeAuthorized signal
+  // is ignored. Also fail closed on a non-boolean `mergeAuthorized` (only an
+  // exact `true` clears merge), matching the authoritative
+  // `resolveEffectiveMergeAuthorized` gate. An already-merged PR (isMerged) is
+  // still terminal below.
+  const effectiveMergeAuthorized = humanMergeOnly !== true && mergeAuthorized === true;
+
   // 1. Explicit phase override — canonical or fail closed
   if (phase !== null && phase !== undefined) {
     const normalized = normalizeLifecycleState(phase);
@@ -212,7 +222,9 @@ export function resolveLifecycleState(input = {}) {
   }
 
   // 3. Merge authorized with pre-approval + linked PR → merge
-  if (mergeAuthorized && preApprovalGatePassed && hasLinkedPr) {
+  // (humanMergeOnly forces effectiveMergeAuthorized=false above, so the loop
+  // stays at the pre_approval_gate human-merge handoff instead.)
+  if (effectiveMergeAuthorized && preApprovalGatePassed && hasLinkedPr) {
     return buildResult(LIFECYCLE_STATE.MERGE);
   }