dev-loops 0.2.1 → 0.2.2

package/.claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Agent-harness-agnostic dev-loop: agents, skills, and hooks for GitHub/Copilot-driven development loops.",
   "author": {
     "name": "Manuel Fittko",

package/.claude/skills/dev-loop/SKILL.md

@@ -25,7 +25,7 @@ Required installed runtime contract docs are shared bundled copies under `../doc
 
 The main agent must **always** dispatch the `dev-loop` async subagent for any dev-loop work.
 Do not run `dev-loops loop startup` or any startup resolver in the main agent.
-The resolver requires `PI_SUBAGENT_RUN_ID` for async-required routes (the default `required` mode); the startup resolver can also run without it for non-async routes. Regardless, only the `dev-loop` async subagent runs it — never the main agent.
+For async-required routes (config `workflow.asyncStartMode`, default `required`) the resolver needs an async run-id marker (`DEVLOOPS_RUN_ID`, or the `PI_SUBAGENT_RUN_ID` alias) that the Pi harness injects when it dispatches the async subagent; under the Claude Code harness the requirement is relaxed automatically (no marker needed). The startup resolver also runs without a marker for non-async routes. Regardless, only the `dev-loop` subagent runs it — never the main agent.
 
 ### Dev-loop subagent (post-dispatch)
 
@@ -85,7 +85,7 @@ Do not preload route packs before the resolver selects the strategy.
 
 ## Async dispatch
 
-**Async dispatch rule (enforced):** the resolver enforces fail-closed for GitHub-first strategies when `canonicalStateSummary.requiresAsyncDispatch` is `true` (default `required` mode). Inline invocation without `PI_SUBAGENT_RUN_ID` is rejected only for those routes. See [Startup procedure](#startup-procedure).
+**Async dispatch rule (enforced):** the resolver fails closed for GitHub-first strategies when `canonicalStateSummary.requiresAsyncDispatch` is `true` (default `required` mode) — inline invocation without an async run-id marker (`DEVLOOPS_RUN_ID`, or the `PI_SUBAGENT_RUN_ID` alias) is rejected for those routes. Under the Claude Code harness this requirement is relaxed automatically. See [Startup procedure](#startup-procedure).
 
 
 ## Fallback gate-comment poster

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.2.2
+
+### Fixed
+
+- **Claude Code: dev-loop no longer dead-ends on the async-start contract** (#830). Running
+  `/dev-loop` from the installed plugin failed immediately because `dev-loops loop startup`
+  enforces an async-start contract — it requires a run-id env marker (`DEVLOOPS_RUN_ID` /
+  `PI_SUBAGENT_RUN_ID`) that Pi injects when dispatching an async subagent but Claude Code's
+  Agent tool does not. That contract guards against detached, uninspectable background
+  processes, a risk that does not exist under Claude's Agent model (each subagent run is
+  visible and inspectable). The async requirement remains configurable via
+  `workflow.asyncStartMode` (`required` | `allowed`); under the Claude harness it is now
+  **relaxed to `allowed` at runtime** via `resolveEffectiveAsyncStartMode`, which consults the
+  new `isClaudeHarness` helper (`CLAUDECODE=1`) in `@dev-loops/core/loop/run-context`. An
+  explicit `DEVLOOPS_RUN_ID` still resolves as `valid`, and Pi behavior is unchanged (outside
+  Claude the configured mode is honored verbatim).
+- The async-start CLI contract test is now hermetic — it clears `CLAUDECODE` (and the run-id
+  markers) so the rejection path is exercised regardless of the harness the suite runs under.
+- The generated `dev-loop` skill prose no longer claims `PI_SUBAGENT_RUN_ID` is *required* — it
+  now describes the async run-id marker (`DEVLOOPS_RUN_ID` / `PI_SUBAGENT_RUN_ID` alias) and notes
+  the Claude-harness relaxation, so the plugin's docs match the runtime behavior. Subagent
+  spawning via the `dev-loop` agent is confirmed correctly wired: it grants the `Agent` tool
+  (the current subagent-spawning tool, renamed from `Task` in Claude Code v2.1.63) and the
+  strategy skills delegate to the worker agents (`developer`/`quality`/`refiner`/`fixer`/`review`/`docs`).
+
 ## 0.2.1
 
 ### Added

package/package.json

@@ -40,14 +40,9 @@
     "repo-wiki:lint": "node scripts/repo-wiki.mjs lint --repo .",
     "repo-wiki:search": "node scripts/repo-wiki.mjs search --repo .",
     "repo-wiki:init": "node scripts/repo-wiki.mjs init --repo .",
-    "repo-wiki:local": "node scripts/repo-wiki-local.mjs",
-    "repo-wiki:local-bootstrap": "node scripts/repo-wiki-local.mjs scan --repo . && node scripts/repo-wiki-local.mjs plan --repo . && node scripts/repo-wiki-local.mjs compile --repo .",
-    "repo-wiki:local-scan": "node scripts/repo-wiki-local.mjs scan --repo .",
-    "repo-wiki:local-plan": "node scripts/repo-wiki-local.mjs plan --repo .",
-    "repo-wiki:local-lint-docs": "node scripts/repo-wiki-local.mjs lint-docs --repo .",
-    "repo-wiki:local-compile": "node scripts/repo-wiki-local.mjs compile --repo .",
-    "repo-wiki:local-lint": "node scripts/repo-wiki-local.mjs lint --repo .",
-    "repo-wiki:prepare": "node scripts/repo-wiki-local.mjs prepare"
+    "repo-wiki:prepare": "node scripts/repo-wiki.mjs --source local prepare",
+    "repo-wiki:local": "node scripts/repo-wiki.mjs --source local",
+    "repo-wiki:local-prepare": "node scripts/repo-wiki.mjs --source local prepare"
   },
   "bin": {
     "dev-loops": "./cli/index.mjs"
@@ -58,7 +53,6 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
-    "c8": "^11.0.0",
     "tsx": "^4.22.0"
   },
   "pi": {
@@ -74,8 +68,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "zod": "^4.4.3",
-    "@dev-loops/core": "^0.2.1"
+    "@dev-loops/core": "^0.2.2"
   },
   "repository": {
     "type": "git",
@@ -85,7 +78,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "files": [
     "cli/",
     "lib/",

package/scripts/github/reply-resolve-review-thread.mjs

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import { defineSubcommand, isDirectCliRun } from "@dev-loops/core/cli/subcommand-runner";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
+import { parsePositiveInteger } from "@dev-loops/core/cli/primitives";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
   replyAndMaybeResolve,
@@ -9,34 +12,90 @@ import {
 
 export { hasCommitShaReference } from "./_review-thread-mutations.mjs";
 
-const { runAsScript } = defineSubcommand({
-  name: "reply-resolve-review-thread --repo <owner/name> --pr <n> --comment-id <n> --thread-id <id> --body-file <path>",
-  description: "Reply to a review thread comment and resolve the thread.",
-  options: [
-    { flag: "--repo", type: "string", required: true, description: "GitHub repository slug" },
-    { flag: "--pr", type: "pr", required: true, description: "Pull request number" },
-    { flag: "--comment-id", type: "positiveInt", required: true, description: "GraphQL databaseId of the comment to reply to" },
-    { flag: "--thread-id", type: "string", required: true, description: "GraphQL node ID of the review thread" },
-    { flag: "--body-file", type: "string", required: true, description: "Path to file containing the reply body text" },
-  ],
-  async run({ repo, pr, commentId, threadId, bodyFile }) {
-    parseRepoSlug(repo);
-
-    const rawBody = await readFile(bodyFile, "utf8");
-    if (rawBody.trim().length === 0) throw new Error("--body-file must contain non-empty text");
-    validateResolutionMessage(rawBody);
-
-    const result = await replyAndMaybeResolve(
-      { repo, pr, commentId, threadId, body: rawBody, resolve: true },
-      { env: process.env, ghCommand: "gh" },
-    );
-
-    process.stdout.write(JSON.stringify({
-      ok: true, repo, pr, commentId, threadId,
-      replyId: result.replyId, replyUrl: result.replyUrl, resolved: true,
-    }) + "\n");
+const USAGE = `Usage: dev-loops reply-resolve-review-thread --repo <owner/name> --pr <n> --comment-id <n> --thread-id <id> --body-file <path>
+
+Reply to a review thread comment and resolve the thread.
+
+Required:
+  --repo <owner/name>      GitHub repository slug
+  --pr <n>                 Pull request number
+  --comment-id <n>         GraphQL databaseId of the comment to reply to
+  --thread-id <id>         GraphQL node ID of the review thread
+  --body-file <path>       Path to file containing the reply body text`;
+
+function parseError(message) {
+  return Object.assign(new Error(message), { usage: USAGE });
+}
+
+function parseCliArgs(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        repo: { type: "string" },
+        pr: { type: "string" },
+        "comment-id": { type: "string" },
+        "thread-id": { type: "string" },
+        "body-file": { type: "string" },
+        help: { type: "boolean", short: "h" },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    throw parseError(err instanceof Error ? err.message : String(err));
+  }
+
+  if (values.help) {
+    return { help: true };
+  }
+
+  if (!values.repo) throw parseError("Missing required option: --repo");
+  if (!values.pr) throw parseError("Missing required option: --pr");
+  if (!values["comment-id"]) throw parseError("Missing required option: --comment-id");
+  if (!values["thread-id"]) throw parseError("Missing required option: --thread-id");
+  if (!values["body-file"]) throw parseError("Missing required option: --body-file");
+
+  const repoSlug = values.repo;
+  parseRepoSlug(repoSlug);
+  const pr = parsePositiveInteger(values.pr, "--pr", parseError);
+  const commentId = parsePositiveInteger(values["comment-id"], "--comment-id", parseError);
+
+  return { repo: repoSlug, pr, commentId, threadId: values["thread-id"], bodyFile: values["body-file"] };
+}
+
+async function run(argv) {
+  const parsed = parseCliArgs(argv);
+  if (parsed.help) {
+    process.stdout.write(`${USAGE}\n`);
     return 0;
-  },
-});
+  }
+
+  const { repo: repoSlug, pr, commentId, threadId, bodyFile } = parsed;
+  const rawBody = await readFile(bodyFile, "utf8");
+  if (rawBody.trim().length === 0) throw new Error("--body-file must contain non-empty text");
+  validateResolutionMessage(rawBody);
+
+  const result = await replyAndMaybeResolve(
+    { repo: repoSlug, pr, commentId, threadId, body: rawBody, resolve: true },
+    { env: process.env, ghCommand: "gh" },
+  );
+
+  process.stdout.write(JSON.stringify({
+    ok: true, repo: repoSlug, pr, commentId, threadId,
+    replyId: result.replyId, replyUrl: result.replyUrl, resolved: true,
+  }) + "\n");
+  return 0;
+}
 
-if (isDirectCliRun(import.meta.url)) { runAsScript(); }
+if (isDirectCliRun(import.meta.url)) {
+  run(process.argv.slice(2)).then(
+    (code) => { process.exitCode = typeof code === "number" ? code : 0; },
+    (error) => {
+      const usage = error instanceof Error && typeof error.usage === "string" ? error.usage : undefined;
+      process.stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error), ...(usage && { usage }) })}\n`);
+      process.exitCode = 1;
+    },
+  );
+}

package/scripts/loop/checkpoint-contract.mjs

@@ -1,11 +1,28 @@
 #!/usr/bin/env node
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { defineSubcommand, isDirectCliRun } from "@dev-loops/core/cli/subcommand-runner";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
 
 const CHECKPOINT_FILE = ".pi/dev-loop-retrospective-checkpoint.json";
 const ALLOWED_STATES = new Set(["required", "complete", "skipped", "none", "missing"]);
 
+const USAGE = `Usage: dev-loops checkpoint-contract --state <state> [--notes <text>] [--reason <text>]
+
+Write .pi/dev-loop-retrospective-checkpoint.json using the retrospective contract format.
+
+Required:
+  --state <state>          Checkpoint state (required, complete, skipped, none, missing)
+
+Optional:
+  --notes <text>           Required when --state is complete
+  --reason <text>          Required when --state is skipped`;
+
+function parseError(message) {
+  return Object.assign(new Error(message), { usage: USAGE });
+}
+
 export function buildRetrospectiveCheckpointPayload({ state, notes = null, reason = null }, now = new Date()) {
   const timestamp = now.toISOString();
   if (state === "complete") return { state, completedAt: timestamp, notes };
@@ -16,34 +33,66 @@ export function buildRetrospectiveCheckpointPayload({ state, notes = null, reaso
   throw new Error(`Unsupported state: ${state}`);
 }
 
-const { runAsScript } = defineSubcommand({
-  name: "checkpoint-contract --state <state>",
-  description: "Write .pi/dev-loop-retrospective-checkpoint.json using the retrospective contract format.",
-  options: [
-    { flag: "--state", type: "string", required: true, choices: [...ALLOWED_STATES],
-      description: "Checkpoint state (required, complete, skipped, none, missing)" },
-    { flag: "--notes", type: "string", description: "Required when --state is complete" },
-    { flag: "--reason", type: "string", description: "Required when --state is skipped" },
-  ],
-  async run({ state, notes, reason }, { args: _args, usage }) {
-    if (!ALLOWED_STATES.has(state)) {
-      throw Object.assign(new Error(`Invalid --state: "${state}". Allowed: ${[...ALLOWED_STATES].join(", ")}.`), { usage });
-    }
-    if (state === "complete" && !notes) {
-      throw Object.assign(new Error('state "complete" requires --notes'), { usage });
-    }
-    if (state === "skipped" && !reason) {
-      throw Object.assign(new Error('state "skipped" requires --reason'), { usage });
-    }
-
-    const cwd = process.cwd();
-    const payload = buildRetrospectiveCheckpointPayload({ state, notes, reason });
-    const checkpointPath = path.join(cwd, CHECKPOINT_FILE);
-    await mkdir(path.dirname(checkpointPath), { recursive: true });
-    await writeFile(checkpointPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-    process.stdout.write(JSON.stringify({ ok: true, path: CHECKPOINT_FILE, checkpoint: payload }) + "\n");
+function parseCliArgs(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        state: { type: "string" },
+        notes: { type: "string" },
+        reason: { type: "string" },
+        help: { type: "boolean", short: "h" },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    throw parseError(err instanceof Error ? err.message : String(err));
+  }
+
+  if (values.help) {
+    return { help: true };
+  }
+
+  if (!values.state) throw parseError("Missing required option: --state");
+  const state = values.state;
+  if (!ALLOWED_STATES.has(state)) {
+    throw parseError(`--state must be one of: ${[...ALLOWED_STATES].join(", ")}`);
+  }
+  if (state === "complete" && !values.notes) {
+    throw parseError('state "complete" requires --notes');
+  }
+  if (state === "skipped" && !values.reason) {
+    throw parseError('state "skipped" requires --reason');
+  }
+
+  return { state, notes: values.notes ?? null, reason: values.reason ?? null };
+}
+
+async function run(argv) {
+  const parsed = parseCliArgs(argv);
+  if (parsed.help) {
+    process.stdout.write(`${USAGE}\n`);
     return 0;
-  },
-});
+  }
 
-if (isDirectCliRun(import.meta.url)) { runAsScript(); }
+  const { state, notes, reason } = parsed;
+  const payload = buildRetrospectiveCheckpointPayload({ state, notes, reason });
+  const checkpointPath = path.join(process.cwd(), CHECKPOINT_FILE);
+  await mkdir(path.dirname(checkpointPath), { recursive: true });
+  await writeFile(checkpointPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  process.stdout.write(JSON.stringify({ ok: true, path: CHECKPOINT_FILE, checkpoint: payload }) + "\n");
+  return 0;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  run(process.argv.slice(2)).then(
+    (code) => { process.exitCode = typeof code === "number" ? code : 0; },
+    (error) => {
+      const usage = error instanceof Error && typeof error.usage === "string" ? error.usage : undefined;
+      process.stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error), ...(usage && { usage }) })}\n`);
+      process.exitCode = 1;
+    },
+  );
+}

package/scripts/loop/outer-loop.mjs

@@ -22,6 +22,7 @@ import {
   ASYNC_START_STATUS,
   buildAsyncStartRejection,
   validateAsyncStartContext,
+  resolveEffectiveAsyncStartMode,
 } from "@dev-loops/core/loop/async-start-contract";
 import { loadDevLoopConfig, resolveConductorModel, resolveAutonomyStopAt, resolveWorkflowConfig } from "@dev-loops/core/config";
 const USAGE = `Usage: outer-loop.mjs --repo <owner/name> --pr <number>
@@ -286,9 +287,11 @@ export async function runOuterLoop(options, { env = process.env, ghCommand = "gh
       devLoopConfig = loaded.config;
     }
   }
-  const asyncStartMode = devLoopConfig === null
+  const configuredAsyncStartMode = devLoopConfig === null
     ? "required"
     : resolveWorkflowConfig(devLoopConfig, "asyncStartMode");
+  // Relaxed to "allowed" under the Claude harness (Pi async-start contract does not apply).
+  const asyncStartMode = resolveEffectiveAsyncStartMode(configuredAsyncStartMode, env);
   const asyncStartValidation = validateAsyncStartContext({ env, isSnapshotMode, asyncStartMode });
   if (asyncStartValidation.status === ASYNC_START_STATUS.REJECTED) {
     return buildAsyncStartRejection(asyncStartValidation);

package/scripts/loop/resolve-dev-loop-startup.mjs

@@ -16,6 +16,7 @@ import {
 import {
   validateAsyncStartContext,
   buildAsyncStartRejection,
+  resolveEffectiveAsyncStartMode,
   ASYNC_START_STATUS,
 } from "@dev-loops/core/loop/async-start-contract";
 import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
@@ -411,7 +412,10 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
     ? (STRATEGY_ASYNC_DISPATCH[bundle.selectedStrategy] ?? false)
     : false;
   if (requiresAsyncDispatch) {
-    const validation = validateAsyncStartContext({ env: effectiveEnv, asyncStartMode });
+    // The configured async-start mode is relaxed to "allowed" under the Claude
+    // harness, where the Pi async-subagent start contract does not apply.
+    const effectiveAsyncStartMode = resolveEffectiveAsyncStartMode(asyncStartMode, effectiveEnv);
+    const validation = validateAsyncStartContext({ env: effectiveEnv, asyncStartMode: effectiveAsyncStartMode });
     if (validation.status === ASYNC_START_STATUS.REJECTED) {
       return buildAsyncStartRejection(validation);
     }

package/scripts/repo-wiki.mjs

@@ -1,42 +1,36 @@
 #!/usr/bin/env node
-// Primary repo-wiki wrapper. Proxies to the published @mfittko/repo-wiki npm package
-// at a pinned version, after validating that the consumer-repo config exists.
+// Primary repo-wiki wrapper. Proxies to either the published @mfittko/repo-wiki
+// npm package (default) or a pinned local source checkout when --source local or
+// REPO_WIKI_SOURCE=local is set.
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 
 import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
 
 // Pinned to the latest published release at the time this slice was opened.
-// Bump deliberately when the consumer repo wants to adopt a newer release.
 export const REPO_WIKI_NPM_PACKAGE = "@mfittko/repo-wiki";
 export const REPO_WIKI_NPM_VERSION = "0.2.6";
+export const REPO_WIKI_MIN_NODE_MAJOR = 20;
+
+export const REPO_WIKI_GIT_URL = "https://github.com/mfittko/repo-wiki.git";
+export const REPO_WIKI_REF = "d7e772e3d702a75896a6f4eec574a4e4e5bfa6dd";
+export const REPO_WIKI_LOCAL_MIN_NODE_MAJOR = 24;
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = path.resolve(__dirname, "..");
 
-export const REPO_WIKI_MIN_NODE_MAJOR = 20;
+export const REPO_WIKI_LOCAL_CONFIG_PATH = resolveRepoWikiConfigPath();
+export const REPO_WIKI_SCHEMA_PATH = path.join(PROJECT_ROOT, ".llmwiki", "schema.md");
 
 export function resolveRepoWikiConfigPath(projectRoot = PROJECT_ROOT) {
   return path.join(projectRoot, ".llmwiki", "config.json");
 }
 
-export const REPO_WIKI_CONFIG_PATH = resolveRepoWikiConfigPath();
-export const REPO_WIKI_SCHEMA_PATH = path.join(PROJECT_ROOT, ".llmwiki", "schema.md");
-
-export function parseCliArgs(argv) {
-  const args = Array.isArray(argv) ? [...argv] : [];
-  if (args.length === 0) {
-    return { passthroughArgs: ["--help"] };
-  }
-  if (args[0] === "--help" || args[0] === "-h") {
-    return { passthroughArgs: ["--help"] };
-  }
-  return { passthroughArgs: args };
-}
-
 export function assertSupportedNodeVersion(version = process.versions.node) {
   const major = Number.parseInt(String(version).split(".")[0] ?? "", 10);
   if (!Number.isInteger(major) || major < REPO_WIKI_MIN_NODE_MAJOR) {
@@ -46,15 +40,21 @@ export function assertSupportedNodeVersion(version = process.versions.node) {
   }
 }
 
+export function assertSupportedLocalNodeVersion(version = process.versions.node) {
+  const major = Number.parseInt(String(version).split(".")[0] ?? "", 10);
+  if (!Number.isInteger(major) || major < REPO_WIKI_LOCAL_MIN_NODE_MAJOR) {
+    throw new Error(
+      `repo-wiki local helper requires Node.js ${REPO_WIKI_LOCAL_MIN_NODE_MAJOR}+ because repo-wiki itself requires Node.js ${REPO_WIKI_LOCAL_MIN_NODE_MAJOR}+. Current runtime: ${version}`,
+    );
+  }
+}
+
 export function assertConsumerConfigPresent({
-  configPath = REPO_WIKI_CONFIG_PATH,
+  configPath = REPO_WIKI_LOCAL_CONFIG_PATH,
   projectRoot = PROJECT_ROOT,
 } = {}) {
-  // When callers override projectRoot without overriding configPath, derive the
-  // expected config path from the override so tests and other call sites stay
-  // consistent with the per-project layout.
   const resolvedConfigPath =
-    configPath === REPO_WIKI_CONFIG_PATH ? resolveRepoWikiConfigPath(projectRoot) : configPath;
+    configPath === REPO_WIKI_LOCAL_CONFIG_PATH ? resolveRepoWikiConfigPath(projectRoot) : configPath;
   if (!existsSync(resolvedConfigPath)) {
     throw new Error(
       `Missing required repo-wiki config at ${path.relative(projectRoot, resolvedConfigPath) || resolvedConfigPath}.\n` +
@@ -73,38 +73,185 @@ export function buildNpxInvocation({
   return ["npx", "--yes", `${packageName}@${version}`, ...passthroughArgs];
 }
 
-export function runNpxInvocation({
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd ?? PROJECT_ROOT,
+    env: { ...process.env, ...(options.env ?? {}) },
+    stdio: options.stdio ?? "inherit",
+    encoding: options.encoding ?? "utf8",
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0 && !options.allowNonZero) {
+    const printable = [command, ...args].join(" ");
+    throw new Error(`Command failed (${result.status ?? "unknown"}): ${printable}`);
+  }
+
+  return result;
+}
+
+function runNpxInvocation({
   command,
   args,
   cwd = PROJECT_ROOT,
   env = process.env,
 } = {}) {
-  const result = spawnSync(command, args, {
-    cwd,
-    env,
+  return run(command, args, { cwd, env, stdio: "inherit", allowNonZero: true });
+}
+
+const VALID_REPO_WIKI_SOURCES = new Set(["npm", "local"]);
+
+export function parseCliArgs(argv) {
+  const args = Array.isArray(argv) ? [...argv] : [];
+  const { values } = parseArgs({
+    args,
+    options: {
+      source: { type: "string" },
+    },
+    strict: false,
+  });
+
+  const sourceEnv = process.env.REPO_WIKI_SOURCE;
+  const source = values.source || sourceEnv || "npm";
+  if (!VALID_REPO_WIKI_SOURCES.has(source)) {
+    throw new Error(`Unknown repo-wiki source "${source}". Valid sources: npm, local`);
+  }
+
+  const passthroughArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--source") {
+      i++;
+      continue;
+    }
+    if (a.startsWith("--source=")) continue;
+    passthroughArgs.push(a);
+  }
+
+  if (passthroughArgs.length === 0 || passthroughArgs[0] === "help" || passthroughArgs[0] === "--help" || passthroughArgs[0] === "-h") {
+    return { source, prepareOnly: false, passthroughArgs: ["--help"] };
+  }
+
+  if (passthroughArgs[0] === "prepare") {
+    return { source, prepareOnly: true, passthroughArgs: [] };
+  }
+
+  return { source, prepareOnly: false, passthroughArgs };
+}
+
+export function resolveRepoWikiPaths(projectRoot = PROJECT_ROOT, ref = REPO_WIKI_REF) {
+  const baseDir = path.join(projectRoot, ".tmp", "repo-wiki", ref);
+  const sourceDir = path.join(baseDir, "source");
+  const cliPath = path.join(sourceDir, "dist", "bin", "repo-wiki.js");
+  const buildStampPath = path.join(baseDir, "build-stamp.json");
+  return { projectRoot, baseDir, sourceDir, cliPath, buildStampPath };
+}
+
+async function readBuildStamp(buildStampPath) {
+  try {
+    return JSON.parse(await readFile(buildStampPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeBuildStamp(buildStampPath) {
+  await writeFile(buildStampPath, JSON.stringify({ ref: REPO_WIKI_REF }, null, 2) + "\n", "utf8");
+}
+
+export async function ensureRepoWikiPrepared(projectRoot = PROJECT_ROOT) {
+  assertSupportedLocalNodeVersion();
+  const { baseDir, sourceDir, cliPath, buildStampPath } = resolveRepoWikiPaths(projectRoot);
+  await mkdir(baseDir, { recursive: true });
+
+  let currentHead = null;
+  try {
+    run("git", ["-C", sourceDir, "rev-parse", "--is-inside-work-tree"], { stdio: "ignore" });
+    currentHead = run("git", ["-C", sourceDir, "rev-parse", "HEAD"], { stdio: "pipe" }).stdout.trim();
+  } catch {
+    run("git", ["clone", REPO_WIKI_GIT_URL, sourceDir], { cwd: baseDir });
+  }
+
+  if (currentHead !== REPO_WIKI_REF) {
+    run("git", ["-C", sourceDir, "fetch", "origin", REPO_WIKI_REF, "--depth", "1"]);
+    run("git", ["-C", sourceDir, "checkout", "--force", REPO_WIKI_REF]);
+  }
+
+  const stamp = await readBuildStamp(buildStampPath);
+  if (stamp?.ref !== REPO_WIKI_REF) {
+    run("npm", ["install", "--silent"], { cwd: sourceDir });
+    run("npm", ["run", "build", "--silent"], { cwd: sourceDir });
+    await writeBuildStamp(buildStampPath);
+  } else {
+    try {
+      run(process.execPath, [cliPath, "--help"], { stdio: "ignore" });
+    } catch {
+      run("npm", ["install", "--silent"], { cwd: sourceDir });
+      run("npm", ["run", "build", "--silent"], { cwd: sourceDir });
+      await writeBuildStamp(buildStampPath);
+    }
+  }
+
+  return resolveRepoWikiPaths(projectRoot);
+}
+
+async function runRepoWikiNpm(passthroughArgs, projectRoot) {
+  assertSupportedNodeVersion();
+  assertConsumerConfigPresent({ projectRoot });
+  const invocation = buildNpxInvocation({ passthroughArgs });
+  const result = runNpxInvocation({ command: invocation[0], args: invocation.slice(1), cwd: projectRoot });
+
+  if (result.status !== 0) {
+    return { ok: false, status: result.status ?? 1, source: "npm", invocation };
+  }
+  return { ok: true, status: 0, source: "npm", invocation };
+}
+
+async function _runRepoWikiLocal(passthroughArgs, projectRoot) {
+  const { cliPath } = await ensureRepoWikiPrepared(projectRoot);
+  const result = spawnSync(process.execPath, [cliPath, ...passthroughArgs], {
+    cwd: projectRoot,
+    env: process.env,
     stdio: "inherit",
   });
   if (result.error) {
     throw result.error;
   }
-  return result;
+  if (result.status !== 0) {
+    return { ok: false, status: result.status ?? 1, source: "local", cliPath };
+  }
+  return { ok: true, status: 0, source: "local", cliPath };
 }
 
 // Composable entry point: returns a structured result instead of calling
 // process.exit so importers can reuse this wrapper without terminating the host
 // process. The direct-run block below owns the process-level exit-code mapping.
+// Convenience export for callers that explicitly want the pinned source path.
+export async function runRepoWikiLocal(argv, projectRoot = PROJECT_ROOT) {
+  const args = argv.some((a) => a === "--source" || a.startsWith("--source="))
+    ? argv
+    : ["--source", "local", ...argv];
+  return runRepoWiki(args, projectRoot);
+}
+
 export async function runRepoWiki(argv, projectRoot = PROJECT_ROOT) {
-  assertSupportedNodeVersion();
-  assertConsumerConfigPresent({ projectRoot });
-  const { passthroughArgs } = parseCliArgs(argv);
-  const invocation = buildNpxInvocation({ passthroughArgs });
+  const { source, prepareOnly, passthroughArgs } = parseCliArgs(argv);
 
-  const result = runNpxInvocation({ command: invocation[0], args: invocation.slice(1), cwd: projectRoot });
+  if (source === "local") {
+    if (prepareOnly) {
+      const { cliPath } = await ensureRepoWikiPrepared(projectRoot);
+      return { ok: true, status: 0, source: "local", prepared: true, cliPath };
+    }
+    return _runRepoWikiLocal(passthroughArgs, projectRoot);
+  }
 
-  if (result.status !== 0) {
-    return { ok: false, status: result.status ?? 1, invocation };
+  if (prepareOnly) {
+    // prepare is meaningless for the npm source; treat as help.
+    return runRepoWikiNpm(["--help"], projectRoot);
   }
-  return { ok: true, status: 0, invocation };
+  return runRepoWikiNpm(passthroughArgs, projectRoot);
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/skills/dev-loop/SKILL.md

@@ -26,7 +26,7 @@ Required installed runtime contract docs are shared bundled copies under `../doc
 
 The main agent must **always** dispatch the `dev-loop` async subagent for any dev-loop work.
 Do not run `dev-loops loop startup` or any startup resolver in the main agent.
-The resolver requires `PI_SUBAGENT_RUN_ID` for async-required routes (the default `required` mode); the startup resolver can also run without it for non-async routes. Regardless, only the `dev-loop` async subagent runs it — never the main agent.
+For async-required routes (config `workflow.asyncStartMode`, default `required`) the resolver needs an async run-id marker (`DEVLOOPS_RUN_ID`, or the `PI_SUBAGENT_RUN_ID` alias) that the Pi harness injects when it dispatches the async subagent; under the Claude Code harness the requirement is relaxed automatically (no marker needed). The startup resolver also runs without a marker for non-async routes. Regardless, only the `dev-loop` subagent runs it — never the main agent.
 
 ### Dev-loop subagent (post-dispatch)
 
@@ -86,7 +86,7 @@ Do not preload route packs before the resolver selects the strategy.
 
 ## Async dispatch
 
-**Async dispatch rule (enforced):** the resolver enforces fail-closed for GitHub-first strategies when `canonicalStateSummary.requiresAsyncDispatch` is `true` (default `required` mode). Inline invocation without `PI_SUBAGENT_RUN_ID` is rejected only for those routes. See [Startup procedure](#startup-procedure).
+**Async dispatch rule (enforced):** the resolver fails closed for GitHub-first strategies when `canonicalStateSummary.requiresAsyncDispatch` is `true` (default `required` mode) — inline invocation without an async run-id marker (`DEVLOOPS_RUN_ID`, or the `PI_SUBAGENT_RUN_ID` alias) is rejected for those routes. Under the Claude Code harness this requirement is relaxed automatically. See [Startup procedure](#startup-procedure).
 
 
 ## Fallback gate-comment poster

package/scripts/repo-wiki-local.mjs

@@ -1,156 +0,0 @@
-#!/usr/bin/env node
-// Pinned-source fallback repo-wiki wrapper. Clones mfittko/repo-wiki at a fixed
-// commit, installs/builds it locally, and proxies the requested command against
-// this repo.
-//
-// This helper is retained for environments that prefer a pinned source checkout
-// over the published npm install path (deterministic source pin, controlled
-// GitHub-only network access, offline reproduction after the initial clone).
-// It still requires git access to https://github.com/mfittko/repo-wiki.git for
-// the initial clone/fetch step.
-//
-// The primary repo-wiki entrypoint is `scripts/repo-wiki.mjs` (npm-installed).
-import { spawnSync } from "node:child_process";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-import { fileURLToPath } from "node:url";
-
-import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
-
-export const REPO_WIKI_GIT_URL = "https://github.com/mfittko/repo-wiki.git";
-export const REPO_WIKI_REF = "d7e772e3d702a75896a6f4eec574a4e4e5bfa6dd";
-export const REPO_WIKI_MIN_NODE_MAJOR = 24;
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PROJECT_ROOT = path.resolve(__dirname, "..");
-
-export function parseCliArgs(argv) {
-  const args = Array.isArray(argv) ? [...argv] : [];
-  if (args.length === 0) {
-    return { prepareOnly: false, passthroughArgs: ["--help"] };
-  }
-  if (args[0] === "prepare") {
-    return { prepareOnly: true, passthroughArgs: [] };
-  }
-  return { prepareOnly: false, passthroughArgs: args };
-}
-
-export function resolveRepoWikiPaths(projectRoot = PROJECT_ROOT, ref = REPO_WIKI_REF) {
-  const baseDir = path.join(projectRoot, ".tmp", "repo-wiki", ref);
-  const sourceDir = path.join(baseDir, "source");
-  const cliPath = path.join(sourceDir, "dist", "bin", "repo-wiki.js");
-  const buildStampPath = path.join(baseDir, "build-stamp.json");
-  return { projectRoot, baseDir, sourceDir, cliPath, buildStampPath };
-}
-
-export function assertSupportedNodeVersion(version = process.versions.node) {
-  const major = Number.parseInt(String(version).split(".")[0] ?? "", 10);
-  if (!Number.isInteger(major) || major < REPO_WIKI_MIN_NODE_MAJOR) {
-    throw new Error(
-      `repo-wiki local helper requires Node.js ${REPO_WIKI_MIN_NODE_MAJOR}+ because repo-wiki itself requires Node.js ${REPO_WIKI_MIN_NODE_MAJOR}+. Current runtime: ${version}`,
-    );
-  }
-}
-
-function run(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    cwd: options.cwd ?? PROJECT_ROOT,
-    env: { ...process.env, ...(options.env ?? {}) },
-    stdio: options.stdio ?? "inherit",
-    encoding: options.encoding ?? "utf8",
-  });
-
-  if (result.error) {
-    throw result.error;
-  }
-  if (result.status !== 0) {
-    const printable = [command, ...args].join(" ");
-    throw new Error(`Command failed (${result.status ?? "unknown"}): ${printable}`);
-  }
-
-  return result;
-}
-
-async function readBuildStamp(buildStampPath) {
-  try {
-    return JSON.parse(await readFile(buildStampPath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-async function writeBuildStamp(buildStampPath) {
-  await writeFile(buildStampPath, JSON.stringify({ ref: REPO_WIKI_REF }, null, 2) + "\n", "utf8");
-}
-
-export async function ensureRepoWikiPrepared(projectRoot = PROJECT_ROOT) {
-  assertSupportedNodeVersion();
-  const { baseDir, sourceDir, cliPath, buildStampPath } = resolveRepoWikiPaths(projectRoot);
-  await mkdir(baseDir, { recursive: true });
-
-  let currentHead = null;
-  try {
-    run("git", ["-C", sourceDir, "rev-parse", "--is-inside-work-tree"], { stdio: "ignore" });
-    currentHead = run("git", ["-C", sourceDir, "rev-parse", "HEAD"], { stdio: "pipe" }).stdout.trim();
-  } catch {
-    run("git", ["clone", REPO_WIKI_GIT_URL, sourceDir], { cwd: baseDir });
-  }
-
-  if (currentHead !== REPO_WIKI_REF) {
-    run("git", ["-C", sourceDir, "fetch", "origin", REPO_WIKI_REF, "--depth", "1"]);
-    run("git", ["-C", sourceDir, "checkout", "--force", REPO_WIKI_REF]);
-  }
-
-  const stamp = await readBuildStamp(buildStampPath);
-  if (stamp?.ref !== REPO_WIKI_REF) {
-    run("npm", ["install", "--silent"], { cwd: sourceDir });
-    run("npm", ["run", "build", "--silent"], { cwd: sourceDir });
-    await writeBuildStamp(buildStampPath);
-  } else {
-    try {
-      run(process.execPath, [cliPath, "--help"], { stdio: "ignore" });
-    } catch {
-      run("npm", ["install", "--silent"], { cwd: sourceDir });
-      run("npm", ["run", "build", "--silent"], { cwd: sourceDir });
-      await writeBuildStamp(buildStampPath);
-    }
-  }
-
-  return resolveRepoWikiPaths(projectRoot);
-}
-
-// Composable entry point: returns a structured result instead of calling
-// process.exit so importers can reuse this wrapper without terminating the host
-// process. The direct-run block below owns the process-level exit-code mapping.
-export async function runRepoWikiLocal(argv, projectRoot = PROJECT_ROOT) {
-  const { prepareOnly, passthroughArgs } = parseCliArgs(argv);
-  const { cliPath } = await ensureRepoWikiPrepared(projectRoot);
-  if (prepareOnly) {
-    return { ok: true, status: 0, prepared: true, cliPath };
-  }
-
-  const result = spawnSync(process.execPath, [cliPath, ...passthroughArgs], {
-    cwd: projectRoot,
-    env: process.env,
-    stdio: "inherit",
-  });
-  if (result.error) {
-    throw result.error;
-  }
-  if (result.status !== 0) {
-    return { ok: false, status: result.status ?? 1, cliPath };
-  }
-  return { ok: true, status: 0, prepared: true, cliPath };
-}
-
-if (isDirectCliRun(import.meta.url)) {
-  runRepoWikiLocal(process.argv.slice(2)).then((result) => {
-    if (!result.ok) {
-      process.exitCode = result.status;
-    }
-  }).catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-  });
-}