@dev-loops/core 1.0.0-rc.6 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -22,6 +22,7 @@
     "./debt/signal": "./src/debt/debt-signal.mjs",
     "./github/copilot-helpers": "./src/github/copilot-helpers.mjs",
     "./github/comment-id-guard": "./src/github/comment-id-guard.mjs",
+    "./github/gh": "./src/github/gh.mjs",
     "./github/issue-ops": "./src/github/issue-ops.mjs",
     "./github/ownership-helpers": "./src/github/ownership-helpers.mjs",
     "./github/repo-slug": "./src/github/repo-slug.mjs",
@@ -37,6 +38,7 @@
     "./loop/gate-fanin": "./src/loop/gate-fanin.mjs",
     "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
     "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",
+    "./loop/markdown-sections": "./src/loop/markdown-sections.mjs",
     "./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",
@@ -51,17 +53,20 @@
     "./loop/refinement-grill-state": "./src/loop/refinement-grill-state.mjs",
     "./loop/queue-board-ordering": "./src/loop/queue-board-ordering.mjs",
     "./loop/default-branch-guard": "./src/loop/default-branch-guard.mjs",
+    "./loop/commit-msg-guard": "./src/loop/commit-msg-guard.mjs",
     "./loop/queue-board-sync": "./src/loop/queue-board-sync.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
     "./loop/queue-membership": "./src/loop/queue-membership.mjs",
     "./loop/queue-parallel": "./src/loop/queue-parallel.mjs",
     "./loop/queue-state": "./src/loop/queue-state.mjs",
+    "./loop/size-budget-merge-gate": "./src/loop/size-budget-merge-gate.mjs",
     "./loop/cache-telemetry-evidence": "./src/loop/cache-telemetry-evidence.mjs",
     "./loop/primer-evidence": "./src/loop/primer-evidence.mjs",
     "./loop/review-dispatch-plan": "./src/loop/review-dispatch-plan.mjs",
     "./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/run-post-merge-actions": "./src/loop/run-post-merge-actions.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",
@@ -73,6 +78,7 @@
     "./loop/ui-review-diagnose": "./src/loop/ui-review-diagnose.mjs",
     "./loop/ui-review-report": "./src/loop/ui-review-report.mjs",
     "./loop/ui-review-teardown": "./src/loop/ui-review-teardown.mjs",
+    "./security/secret-scan": "./src/security/secret-scan.mjs",
     "./projects/list-queue-items": "./src/projects/list-queue-items.mjs",
     "./projects/move-queue-item": "./src/projects/move-queue-item.mjs",
     "./projects/resolve-project": "./src/projects/resolve-project.mjs",
@@ -80,6 +86,7 @@
     "./tracker": "./src/tracker/index.mjs",
     "./loop/worktree-guard": "./src/loop/worktree-guard.mjs",
     "./loop/main-checkout-ff": "./src/loop/main-checkout-ff.mjs",
+    "./loop/normalize": "./src/loop/normalize.mjs",
     "./loop/tracker-first-loop-state": "./src/loop/tracker-first-loop-state.mjs"
   },
   "bin": {

package/src/analysis/change-classifier.mjs

@@ -22,6 +22,10 @@ export const ChangeCategory = Object.freeze({
   // child_process/shell exec, untrusted network fetch, destructive filesystem
   // ops / local-file upload). Triggers an up-front adversarial threat-model angle.
   SECURITY_SENSITIVE_SEAM: "SECURITY_SENSITIVE_SEAM",
+  // #1442: a changed file is on the prose surface (docs/articles/**,
+  // docs/presentations/**, README*, narrative docs/*.md) — ADR 0041 prose half.
+  // Triggers the required fail-closed `deslop` gate angle.
+  PROSE_PRESENT: "PROSE_PRESENT",
 });
 
 // ---------------------------------------------------------------------------
@@ -69,6 +73,12 @@ export const CATEGORY_ANGLE_MAP = {
   [ChangeCategory.SECURITY_SENSITIVE_SEAM]: [
     "threat-model", "input-validation", "scope", "correctness",
   ],
+  // #1442 (ADR 0041 prose half): a prose-surface path is present → run the
+  // required `deslop` gate angle. skills/docs/** is deliberately NOT prose, so
+  // a normative-contract-only docs diff never triggers deslop.
+  [ChangeCategory.PROSE_PRESENT]: [
+    "deslop",
+  ],
 };
 
 /**

package/src/analysis/diff-analyzer.mjs

@@ -21,6 +21,44 @@
 // fails closed toward a full re-review, which is what a version bump needs.
 const DOTFILE_CONFIG_BASENAMES = new Set([".devloops"]);
 
+// #1442 (ADR 0041 prose half): the prose surface that triggers the required
+// `deslop` gate angle. skills/docs/** is deliberately excluded — those are
+// normative contracts (owned by the contract style guide + contradiction
+// lens), not prose, and deslop's contrast-cutting must not fight RFC-2119
+// modality.
+const PROSE_PATH_RE = /^docs\/(articles|presentations)\//;
+const NARRATIVE_DOC_RE = /^docs\/[^/]+\.(md|markdown)$/;
+// #1442 review finding: the skills/docs/** exemption must hold for the README
+// rule too. PROSE_PATH_RE / NARRATIVE_DOC_RE are anchored to `docs/` so
+// skills/docs files never match them; the README basename rule is the ONLY
+// path by which a skills/docs file could be classified prose (e.g. a future
+// `skills/docs/README-*.md`). Carve the normative-contract subtree out
+// explicitly so a README-named contract never arms deslop.
+const SKILLS_DOCS_EXEMPT_RE = /^(skills\/docs|\x2eclaude\/skills\/docs)\//;
+
+/**
+ * Whether a file path is on the prose surface (#1442): docs/articles/**,
+ * docs/presentations/**, README*, or a narrative direct-child docs/*.md.
+ * skills/docs/** (and .claude/skills/docs/**) is exempt (normative
+ * contracts, not prose) across ALL rules, including the README basename rule.
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isProsePath(filePath) {
+  // #1442 review finding (input-validation): exported trust-boundary guard.
+  // Fail closed (false) on a non-string/empty argument rather than crashing in
+  // normalizeSep(filePath).replaceAll(...).
+  if (typeof filePath !== "string" || filePath.length === 0) return false;
+  const fp = normalizeSep(filePath);
+  if (SKILLS_DOCS_EXEMPT_RE.test(fp)) return false;
+  if (PROSE_PATH_RE.test(fp)) return true;
+  if (NARRATIVE_DOC_RE.test(fp)) return true;
+  const base = fp.split("/").pop() ?? "";
+  if (base.startsWith("README")) return true;
+  return false;
+}
+
 /**
  * @typedef {object} T0Result
  * @property {string[]} files — flat file paths
@@ -56,6 +94,13 @@ export function analyzeT0(nameStatusOutput) {
   const extensions = new Set();
   const directories = new Set();
   let renameCount = 0;
+  // #1442 review finding: prose arming must be scoped to content-carrying
+  // rows. A pure deletion (`D` name-status row) has no prose content for the
+  // deslop reviewer to strip — arming deslop on it over-selects and re-runs
+  // the fan-out over a content-free delta. Added/modified/renamed-dest rows
+  // (A / M / M? / R-dest) carry content and still arm prose. Rename rows emit
+  // `R<score>\told\tnew` (rawPath = parts[2], the new content-bearing path).
+  let prosePresent = false;
 
   for (const line of lines) {
     const parts = line.split("\t");
@@ -73,6 +118,16 @@ export function analyzeT0(nameStatusOutput) {
     if (dir) directories.add(dir);
 
     if (status.startsWith("R")) renameCount++;
+    // #1442: a content-carrying prose file arms PROSE_PRESENT → deslop. Pure
+    // deletions (`D`) are excluded (no prose content to strip, avoids noise);
+    // a pure `R100` rename (git's 100% similarity score — no content changed)
+    // is likewise content-free and must not arm deslop. Renames with a score
+    // below 100 (`R<score>\told\tnew`, rawPath = the new content-bearing path)
+    // carry content and still arm prose.
+    if (prosePresent) continue;
+    if (status === "D" || status.startsWith("D")) continue;
+    if (status.startsWith("R") && status === "R100") continue;
+    if (isProsePath(path)) prosePresent = true;
   }
 
   const renameOnly = lines.length > 0 && renameCount === lines.length;
@@ -87,6 +142,7 @@ export function analyzeT0(nameStatusOutput) {
     directories: [...directories].sort(),
     renameOnly,
     allDocs,
+    prosePresent,
   };
 }
 
@@ -372,6 +428,7 @@ function t0FileCategories(t0) {
   const categories = [];
   if (t0.renameOnly) categories.push("RENAME_ONLY");
   if (t0.allDocs) categories.push("DOCS_ONLY");
+  if (t0.prosePresent) categories.push("PROSE_PRESENT");
   if (t0.files.every((f) => classifyFile(f) === "config")) categories.push("CONFIG_ONLY");
   if (t0.files.every((f) => classifyFile(f) === "test")) categories.push("TEST_ONLY");
   if (t0.files.every((f) => classifyFile(f) === "ci")) categories.push("CI_ONLY");
@@ -392,6 +449,7 @@ function t0PresentSurfaceCategories(t0) {
   const categories = [];
   const cats = new Set(t0.files.map(classifyFile));
   if (cats.has("docs")) categories.push("DOCS_ONLY");
+  if (t0.prosePresent) categories.push("PROSE_PRESENT");
   if (cats.has("config")) categories.push("CONFIG_ONLY");
   if (cats.has("test")) categories.push("TEST_ONLY");
   if (cats.has("ci")) categories.push("CI_ONLY");
@@ -445,8 +503,17 @@ export function analyzeDiff({ nameStatusOutput, diffOutput }) {
   // When t1 is null (unambiguous diff), infer categories from t0
   // so dynamic angle resolution can narrow for config-only / test-only etc.
   if (!t1) {
+    // #1442 Copilot finding: a genuinely MIXED diff whose T1 never ran (no
+    // diffOutput) must NOT get a T0-only PROSE_PRESENT category. Non-empty
+    // categories set ambiguous=false, so a mixed code+prose diff would
+    // under-select to just deslop + always-include and drop the code-review
+    // core. T0-only inference is only safe for unambiguous diffs (docs-only /
+    // single surface); a mixed diff without hunk content is unclassifiable, so
+    // return empty categories and let resolveDynamicAngles fall back to the
+    // full angle set (fail closed).
+    const changeCategories = t0Ambiguous ? [] : inferCategoriesFromT0(t0);
     t1 = {
-      changeCategories: inferCategoriesFromT0(t0),
+      changeCategories,
       hunkCount: 0,
       lineStats: { added: 0, deleted: 0 },
     };

package/src/claude/hook-decisions.mjs

@@ -383,6 +383,23 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
  */
 export const DEVLOOPS_COMMIT_AUTH_PENDING_VAR = "DEVLOOPS_COMMIT_AUTH_PENDING";
 
+/**
+ * Env var that exempts an orchestrator-owned-commit dispatch from the SubagentStop
+ * uncommitted-work guard (#1786).
+ *
+ * A "LOCAL EDITS ONLY: no commit" dispatch (e.g. the `developer`/`quality`/`docs` delegation
+ * pattern in `skills/local-implementation/SKILL.md` "Delegation contract") tells the subagent to
+ * make local edits and report changed files, leaving commit + push to the dispatching
+ * orchestrator once it consolidates results. Without an exemption, that subagent's own
+ * SubagentStop event still sees the dirty worktree it was told not to commit and deadlocks. The
+ * dispatcher sets `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` for that dispatch to declare it owns the
+ * commit — same opt-in `DEVLOOPS_*` signal shape as `DEVLOOPS_COMMIT_AUTH_PENDING`, but distinct:
+ * this one exempts a non-interactive delegated dispatch whose commit responsibility sits with its
+ * caller, not an interactive session awaiting operator authorization. Left unset, an ordinary
+ * dispatch's commit-before-exit obligation stays enforced (fail closed by default).
+ */
+export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT";
+
 /**
  * Decide whether a SubagentStop must be blocked because the subagent's worktree has
  * uncommitted changes (#1619).
@@ -391,7 +408,8 @@ export const DEVLOOPS_COMMIT_AUTH_PENDING_VAR = "DEVLOOPS_COMMIT_AUTH_PENDING";
  * uncommitted changes in a worktree are destroyed with no warning. `LOCAL-COMMIT-BEFORE-EXIT`
  * existed only as prose. This decider makes it mechanical: refuse the subagent stop when the
  * cwd is under `tmp/worktrees/` and `git status --porcelain` is non-empty, unless the session
- * is an interactive one awaiting commit authorization (exempt). A clean worktree, a cwd
+ * is an interactive one awaiting commit authorization, or the dispatch is an explicit
+ * orchestrator-owned-commit exemption (#1786) (either exempt). A clean worktree, a cwd
  * outside `tmp/worktrees/`, and a git-error/empty-porcelain case all allow the stop.
  *
  * Pure and side-effect free. The hook script gathers `cwd` and the `git status --porcelain`
@@ -406,13 +424,16 @@ export const DEVLOOPS_COMMIT_AUTH_PENDING_VAR = "DEVLOOPS_COMMIT_AUTH_PENDING";
  * @param {boolean} [params.pendingCommitAuthorization] - True when the interactive session is
  *   awaiting commit authorization (exempt) — derived by the hook script from the
  *   `DEVLOOPS_COMMIT_AUTH_PENDING=1` opt-in env signal.
+ * @param {boolean} [params.orchestratorOwnsCommit] - True when this dispatch is an explicit
+ *   orchestrator-owned-commit exemption (exempt) — derived by the hook script from the
+ *   `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` opt-in env signal.
  * @returns {HookDecision}
  */
-export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false }) {
+export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false, orchestratorOwnsCommit = false }) {
   if (typeof cwd !== "string" || !isUnderWorktreePath(cwd)) {
     return ALLOW;
   }
-  if (pendingCommitAuthorization) {
+  if (pendingCommitAuthorization || orchestratorOwnsCommit) {
     return ALLOW;
   }
   if (typeof porcelain !== "string" || porcelain.trim() === "") {
@@ -422,6 +443,17 @@ export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthoriza
     .split("\n")
     .map((l) => l.trim())
     .filter(Boolean);
+  // The reason is fed back to the stopping subagent as context, so the path
+  // enumeration is capped: an unbounded list on a very dirty worktree produces a
+  // multi-megabyte reason that consumers truncate or choke on, burying the one
+  // actionable line. The "Dirty paths (N):" header below always carries the full
+  // dirty count; the trailing "… and X more" line (when present) carries the
+  // remaining count past the cap, not the full total.
+  const MAX_LISTED_DIRTY_PATHS = 50;
+  const listed = dirty.slice(0, MAX_LISTED_DIRTY_PATHS).map((p) => "  " + p);
+  if (dirty.length > MAX_LISTED_DIRTY_PATHS) {
+    listed.push(`  … and ${dirty.length - MAX_LISTED_DIRTY_PATHS} more (run \`git status --porcelain\` for the full list)`);
+  }
   return {
     decision: "block",
     reason:
@@ -429,6 +461,6 @@ export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthoriza
       "to prevent silent data loss from post-merge worktree cleanup (cleanup-worktree.mjs runs " +
       "`git worktree remove --force`). Commit your work before stopping. " +
       `Dirty paths (${dirty.length}):\n` +
-      dirty.map((p) => "  " + p).join("\n"),
+      listed.join("\n"),
   };
 }

package/src/cli/primitives.mjs

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
 
 /**
@@ -113,7 +115,7 @@ export function parsePositiveInteger(value, flag, parseError = null) {
 
 export function parseNonNegativeInteger(value, flag, parseError = null) {
   if (!/^\d+$/.test(value)) {
-    throw toCliError(`${flag} must be a non-negative integer`, parseError);
+    throw toCliError(`${flag} must be a non-negative integer, got "${value}"`, parseError);
   }
   return Number(value);
 }
@@ -167,6 +169,33 @@ export function runChild(command, args, env = process.env, stdinText = undefined
   });
 }
 
+/**
+ * Resolve a `--body <text>` / `--body-file <path>` pair to the actual body
+ * string, the one file-reading step every `--body-file` CLI flag in this repo
+ * needs: read the file (or stdin, when `allowStdin` and `bodyFile === "-"`)
+ * and FAIL CLOSED (throw) on an empty/whitespace-only result, so a blank or
+ * unreadable `--body-file` can never silently clear a PR/comment body. When
+ * `bodyFile` is absent, `body` is returned unchanged (no emptiness check —
+ * callers that must reject an empty inline `--body` do that themselves,
+ * since not every caller enforces it).
+ *
+ * @param {object} input
+ * @param {string} [input.body] — inline body value, returned as-is when no bodyFile
+ * @param {string} [input.bodyFile] — path to read the body from ("-" = stdin, when allowStdin)
+ * @param {boolean} [input.allowStdin] — honor `bodyFile === "-"` as stdin (fd 0); default false
+ * @returns {Promise<string | undefined>}
+ */
+export async function resolveBodyOrFile({ body, bodyFile, allowStdin = false } = {}) {
+  if (bodyFile === undefined || bodyFile === null) return body;
+  // fs/promises readFile does not accept an integer fd, so stdin (fd 0) is
+  // read synchronously via readFileSync, which does accept one.
+  const content = allowStdin && bodyFile === "-" ? readFileSync(0, "utf8") : await readFile(bodyFile, "utf8");
+  if (content.trim().length === 0) {
+    throw new Error(`--body-file ${bodyFile} is empty`);
+  }
+  return content;
+}
+
 export function runCommand(command, args, { cwd = process.cwd(), env = process.env } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });