@dev-loops/core 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {
@@ -8,7 +8,6 @@
     "./cli/helpers": "./src/cli/helpers.mjs",
     "./cli/primitives": "./src/cli/primitives.mjs",
     "./cli/retry-wrapper": "./src/cli/retry-wrapper.mjs",
-    "./cli/subcommand-runner": "./src/cli/subcommand-runner.mjs",
     "./claude/asset-generation": "./src/claude/asset-generation.mjs",
     "./claude/headless-entry": "./src/claude/headless-entry.mjs",
     "./claude/hook-decisions": "./src/claude/hook-decisions.mjs",

package/src/config/config.mjs

@@ -28,7 +28,7 @@ const ModelsConfig = z.strictObject({
 const RefinementConfig = z.strictObject({
   fanOut: z.number().int().min(1).max(10),
   mode: z.enum(["parallel", "sequential"]),
-  maxCopilotRounds: z.number().int().positive().default(5),
+  maxCopilotRounds: z.number().int().nonnegative().default(5),
   stopOnLowSignal: z.boolean().default(false),
   lowSignalRoundThreshold: z.number().int().nonnegative().default(3),
   lowSignalMaxComments: z.number().int().nonnegative().default(2),

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

@@ -23,7 +23,7 @@
  * This module is intentionally pure and side-effect free.
  */
 
-import { RUN_ID_MARKERS } from "./run-context.mjs";
+import { RUN_ID_MARKERS, isClaudeHarness } from "./run-context.mjs";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -54,6 +54,39 @@ export const ASYNC_START_STATUS = Object.freeze({
   REJECTED: "rejected",
 });
 
+/**
+ * Resolve the effective async-start mode for the current harness.
+ *
+ * The async-start contract is configurable via `workflow.asyncStartMode`
+ * (`required` | `allowed`) — see defaults.yaml. It exists to stop the Pi
+ * harness from running the loop as a detached, uninspectable background
+ * process. Claude Code's Agent tool has no detached-process variant (each
+ * subagent run is visible and inspectable), so under the Claude harness a
+ * *recognized* mode is relaxed to `allowed` at runtime. An unrecognized
+ * (e.g. typo'd) `configuredMode` is returned verbatim — not relaxed — so
+ * `validateAsyncStartContext` still rejects it and the config error surfaces
+ * even under Claude. Pi behavior is unchanged: outside Claude the configured
+ * mode is always returned verbatim.
+ *
+ * @param {string} configuredMode - Mode from workflow config; normally
+ *   `"required"` | `"allowed"`, but any value is accepted and an unrecognized
+ *   one is passed through unchanged for downstream validation.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string} The effective mode (`"allowed"` when a recognized mode is
+ *   relaxed under Claude; otherwise `configuredMode` verbatim).
+ */
+export function resolveEffectiveAsyncStartMode(configuredMode, env = process.env) {
+  // Only relax a recognized mode. An unrecognized configuredMode must pass through
+  // verbatim so validateAsyncStartContext still rejects it (surfacing the config
+  // error) rather than having the Claude relaxation silently mask a typo'd value.
+  const isRecognizedMode =
+    configuredMode === ASYNC_START_MODE.REQUIRED || configuredMode === ASYNC_START_MODE.ALLOWED;
+  if (isRecognizedMode && isClaudeHarness(env)) {
+    return ASYNC_START_MODE.ALLOWED;
+  }
+  return configuredMode;
+}
+
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------

package/src/loop/pr-gate-coordination.mjs

@@ -447,6 +447,12 @@ export function shouldGuardCopilotReviewRequest({
   if (!gateBoundariesRequiringCopilotFormalRequest.has(gateBoundary)) {
     return false;
   }
+  // Copilot review disabled for the repo (maxCopilotRounds: 0): never force a
+  // formal request — the loop runs draft_gate → pre_approval with the local
+  // harness only. See evaluatePrGateCoordination (internal_only routing).
+  if (maxCopilotRounds === 0) {
+    return false;
+  }
   if (copilotReviewRequestStatus !== "none") {
     return false;
   }
@@ -477,9 +483,14 @@ export function evaluatePrGateCoordination(input = {}) {
   const prClosed = input.prClosed === true;
   const prMerged = input.prMerged === true;
   const sameHeadCleanConverged = input.sameHeadCleanConverged === true;
-  const reviewMode = typeof input.reviewMode === "string"
-    ? input.reviewMode.trim().toLowerCase()
-    : null;
+  // maxCopilotRounds: 0 disables the external Copilot review gate entirely
+  // (for repos without Copilot / local-harness-only review). It reuses the
+  // existing internal_only routing — skip the Copilot cycle, go straight to
+  // pre_approval — so no separate skip path is needed.
+  const copilotReviewDisabled = input.maxCopilotRounds === 0;
+  const reviewMode = copilotReviewDisabled
+    ? "internal_only"
+    : (typeof input.reviewMode === "string" ? input.reviewMode.trim().toLowerCase() : null);
   const mergeStateStatus = normalizeMergeStateStatus(input.mergeStateStatus);
   const conflictFiles = normalizeConflictFiles(input.conflictFiles);
   const ciStatus = normalizeCiStatus(input.ciStatus);
@@ -813,7 +824,9 @@ export function evaluatePrGateCoordination(input = {}) {
           allowedNextActions,
           forbiddenActions,
           nextAction: PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
-          reason: "This is an explicitly internal-only PR with clean draft_gate evidence and current-head clean pre_approval_gate, so it is ready for final human approval.",
+          reason: copilotReviewDisabled
+            ? "Copilot review is disabled for this repo (maxCopilotRounds: 0); with clean draft_gate evidence and current-head clean pre_approval_gate, the PR is ready for final human approval."
+            : "This is an explicitly internal-only PR with clean draft_gate evidence and current-head clean pre_approval_gate, so it is ready for final human approval.",
           mergeStateStatus,
           conflictFiles,
             refinementArtifact,
@@ -835,7 +848,9 @@ export function evaluatePrGateCoordination(input = {}) {
         allowedNextActions,
         forbiddenActions,
         nextAction: PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
-        reason: "This is an explicitly internal-only PR, so `pre_approval_gate` is the next legal boundary instead of an external Copilot review cycle.",
+        reason: copilotReviewDisabled
+          ? "Copilot review is disabled for this repo (maxCopilotRounds: 0), so `pre_approval_gate` is the next legal boundary instead of an external Copilot review cycle."
+          : "This is an explicitly internal-only PR, so `pre_approval_gate` is the next legal boundary instead of an external Copilot review cycle.",
         mergeStateStatus,
         conflictFiles,
           refinementArtifact,

package/src/loop/run-context.mjs

@@ -34,6 +34,27 @@ export const PI_RUN_ID_ALIAS_VAR = "PI_SUBAGENT_RUN_ID";
 /** State-file name (under `.pi/`, consistent with existing dev-loop checkpoint files). */
 export const RUN_CONTEXT_FILENAME = "dev-loop-run-context.json";
 
+/**
+ * Env var Claude Code sets in every tool/subagent shell it spawns.
+ * Used as the harness signal — see `isClaudeHarness`.
+ */
+export const CLAUDE_HARNESS_MARKER = "CLAUDECODE";
+
+/**
+ * True when running under the Claude Code harness.
+ *
+ * Claude Code sets `CLAUDECODE=1` in the environment of every Bash tool and
+ * subagent it spawns. This is the harness-detection seam used to relax
+ * Pi-specific runtime contracts (e.g. the async-start contract) that do not
+ * apply to Claude's execution model.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {boolean}
+ */
+export function isClaudeHarness(env = process.env) {
+  return env?.[CLAUDE_HARNESS_MARKER] === "1";
+}
+
 /**
  * Resolve the active run id from the environment, neutral marker first.
  *

package/src/cli/subcommand-runner.mjs

@@ -1,246 +0,0 @@
-/**
- * Shared subcommand runner for standardizing CLI script boilerplate.
- * Extracted per issue #548 Phase 3.
- *
- * Replaces per-script: USAGE string, parseError, arg-parsing loop,
- * removed-flags handling, and direct-invocation boilerplate.
- */
-
-import { buildParseError, isDirectCliRun } from "./helpers.mjs";
-import { requireOptionValue, parsePrNumber, parseIssueNumber,
-         parsePositiveInteger, parseNonNegativeInteger } from "./primitives.mjs";
-
-/**
- * Option descriptor for defineSubcommand.
- *
- * @typedef {Object} CliOption
- * @property {string} flag       - e.g. "--repo"
- * @property {string} [key]      - override output key name; defaults to dashed→camelCase (e.g. "--head-sha" → "headSha")
- * @property {string} [valueName] - human-readable value name for usage (ignored for boolean flags)
- * @property {string} [description] - help text
- * @property {"string"|"number"|"boolean"|"pr"|"issue"|"positiveInt"|"nonNegativeInt"} [type] - default "string"
- * @property {boolean} [required] - default false
- * @property {*} [default]        - default value
- * @property {string[]} [choices] - allowed values
- * @property {string[]} [removedAliases] - flags that should be rejected with a message
- */
-
-/** Convert a dashed flag name (e.g. "--head-sha") to camelCase (e.g. "headSha"). */
-function dashedToCamel(flag) {
-  const stem = flag.replace(/^--/, "");
-  return stem.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-}
-
-/** Return the parsed output key for an option. Respects opt.key override. */
-function optionKey(opt) {
-  if (opt.key) return opt.key;
-  return dashedToCamel(opt.flag);
-}
-
-/** Render a single option's usage fragment for the generated help text. */
-function optionUsageFragment(opt) {
-  if (opt.type === "boolean") return opt.flag;
-  const vn = opt.valueName || opt.flag.replace(/^--/, "").replace(/-/g, "_").toUpperCase();
-  return `${opt.flag} <${vn}>`;
-}
-
-/**
- * Define a subcommand with auto-generated usage, arg parsing, and help.
- *
- * @param {Object} def
- * @param {string} def.name        - subcommand name for usage
- * @param {string} def.description - one-line description
- * @param {string} [def.longDescription] - extended help text
- * @param {CliOption[]} def.options - option descriptors
- * @param {Function} def.run       - async (parsed, { args, stdout, stderr }) => exitCode
- * @param {Object} [def.extraUsage] - extra usage lines
- * @param {Object} [def.outputSchema] - stdout JSON schema description
- * @returns {{ parseArgs, runAsScript, usage, parseError }}
- */
-export function defineSubcommand(def) {
-  const {
-    name,
-    description,
-    longDescription = "",
-    options = [],
-    run,
-    extraUsage = {},
-    outputSchema = null,
-  } = def;
-
-  // Auto-build usage string
-  const requiredOpts = options.filter((o) => o.required);
-  const optionalOpts = options.filter((o) => !o.required);
-
-  const usageLines = [`Usage: dev-loops ${name}`];
-  for (const opt of requiredOpts) {
-    usageLines.push(`  ${optionUsageFragment(opt)}`);
-  }
-  if (optionalOpts.length > 0) {
-    const optStrs = optionalOpts.map((o) => optionUsageFragment(o));
-    usageLines.push(`  [${optStrs.join("] [")}]`);
-  }
-
-  if (description) usageLines.push("", description);
-  if (longDescription) usageLines.push("", longDescription);
-
-  if (requiredOpts.length > 0) {
-    usageLines.push("", "Required:");
-    for (const opt of requiredOpts) {
-      usageLines.push(`  ${optionUsageFragment(opt)}${opt.description ? `    ${opt.description}` : ""}`);
-    }
-  }
-
-  if (optionalOpts.length > 0) {
-    usageLines.push("", "Optional:");
-    for (const opt of optionalOpts) {
-      usageLines.push(`  ${optionUsageFragment(opt)}${opt.description ? `    ${opt.description}` : ""}`);
-    }
-  }
-
-  if (extraUsage.before) usageLines.splice(1, 0, ...extraUsage.before);
-  if (extraUsage.after) usageLines.push(...extraUsage.after);
-
-  if (outputSchema) {
-    usageLines.push("", "Output (stdout, JSON):", JSON.stringify(outputSchema, null, 2));
-  }
-
-  const usage = usageLines.join("\n");
-  const parseError = buildParseError(usage);
-
-  // Build removed-flags set
-  const removedFlags = new Set();
-  for (const opt of options) {
-    if (opt.removedAliases) {
-      for (const alias of opt.removedAliases) removedFlags.add(alias);
-    }
-  }
-
-  function parseValue(raw, opt) {
-    if (raw === undefined) return opt.default;
-    switch (opt.type) {
-      case "number": case "positiveInt": case "nonNegativeInt": {
-        if (opt.type === "positiveInt") return parsePositiveInteger(raw, opt.flag, parseError);
-        if (opt.type === "nonNegativeInt") return parseNonNegativeInteger(raw, opt.flag, parseError);
-        const n = Number(raw);
-        if (isNaN(n)) throw parseError(`${opt.flag} must be a number`);
-        return n;
-      }
-      case "pr": return parsePrNumber(raw, parseError);
-      case "issue": return parseIssueNumber(raw, parseError);
-      case "string":
-      default: {
-        const v = raw.trim();
-        if (opt.choices && !opt.choices.includes(v)) {
-          throw parseError(`${opt.flag} must be one of: ${opt.choices.join(", ")}`);
-        }
-        return v;
-      }
-    }
-  }
-
-  function parseArgs(argv) {
-    const args = [...argv];
-    const parsed = {};
-    // Initialize defaults for all options
-    for (const opt of options) {
-      if (opt.default !== undefined) {
-        parsed[optionKey(opt)] = opt.default;
-      }
-    }
-
-    while (args.length > 0) {
-      const token = args.shift();
-
-      if (token === "--help" || token === "-h") {
-        return { help: true };
-      }
-
-      if (removedFlags.has(token)) {
-        throw parseError(
-          `${token} has been removed. Omit the flag.`,
-        );
-      }
-
-      const opt = options.find((o) => o.flag === token);
-      if (opt) {
-        if (opt.type === "boolean") {
-          // Boolean flags are presence-only: --flag sets true, no value required.
-          parsed[optionKey(opt)] = true;
-        } else {
-          const raw = requireOptionValue(args, opt.flag, parseError);
-          parsed[optionKey(opt)] = parseValue(raw, opt);
-        }
-        continue;
-      }
-
-      throw parseError(`Unknown argument: ${token}`);
-    }
-
-    // Validate option definitions
-    for (const opt of options) {
-      if (opt.required && opt.default !== undefined) {
-        throw new Error(`Option ${opt.flag}: 'required' and 'default' conflict`);
-      }
-    }
-
-    // Check required
-    for (const opt of requiredOpts) {
-      const key = optionKey(opt);
-      if (parsed[key] === undefined) {
-        throw parseError(`Missing required option: ${opt.flag}`);
-      }
-    }
-
-    return { parsed };
-  }
-
-  async function runAsScript(scriptArgv = process.argv.slice(2)) {
-    try {
-      const result = parseArgs(scriptArgv);
-      if (result.help) {
-        process.stdout.write(`${usage}\n`);
-        process.exitCode = 0;
-        return;
-      }
-      const code = await run(result.parsed, { args: scriptArgv, usage });
-      process.exitCode = typeof code === "number" ? code : 0;
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error);
-      if (error instanceof Error && typeof error.usage === "string") {
-        process.stderr.write(JSON.stringify({ ok: false, error: msg, usage: error.usage }) + "\n");
-      } else {
-        process.stderr.write(JSON.stringify({ ok: false, error: msg }) + "\n");
-      }
-      process.exitCode = 1;
-    }
-  }
-
-  return { parseArgs, runAsScript, usage, parseError };
-}
-
-/**
- * Run a CLI function as the main entrypoint when the module is invoked directly.
- * Handles process.exitCode and error formatting.
- *
- * Usage: replace `if (isDirectCliRun(import.meta.url)) { ... }` with:
- *   if (isDirectCliRun(import.meta.url)) { runAsMain(runCli); }
- *
- * @param {Function} fn - async function returning exit code or void
- * @param {Object} [opts]
- * @param {Function} [opts.formatError] - error formatter (default: JSON.stringify)
- */
-export function runAsMain(fn, { formatError } = {}) {
-  Promise.resolve(fn()).then(
-    (code) => { process.exitCode = typeof code === "number" ? code : 0; },
-    (error) => {
-      const msg = formatError
-        ? formatError(error)
-        : JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) });
-      process.stderr.write(`${msg}\n`);
-      process.exitCode = 1;
-    },
-  );
-}
-
-export { isDirectCliRun };