dev-loops 0.4.0 → 0.6.0

package/scripts/refine/refine-plan-file.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+
+import { buildParseError, formatCliError, parseJsonText } from "../_core-helpers.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
+import { validatePlanFile } from "./validate-plan-file.mjs";
+import { extractSection, isDirectCliRun } from "./_refine-helpers.mjs";
+import {
+  refinePlanFileInPlace,
+  PLAN_FILE_REFINE_STOP,
+} from "@dev-loops/core/loop/plan-file-refine-contract";
+import { PLAN_FILE_REFINEMENT_SECTIONS } from "@dev-loops/core/loop/plan-file-intake-contract";
+import { classifyDocsGrillFinding } from "../loop/docs-grill-contract.mjs";
+
+const USAGE = `Usage:
+  refine-plan-file.mjs --plan-file <path> --payload <path> [--json]
+Refine a local plan file in place: write the refiner-produced Acceptance
+criteria, Definition of done, coverage matrix, and recorded docs-grill
+findings into the plan file, advance the intake state to
+plan_refined_ready_for_promotion, and stop at a local human-review
+checkpoint. Read-only against the tracker: no GitHub calls, no issue/PR/
+comment, no promotion.
+
+Required:
+  --plan-file <path>  Path to the phase-doc-format plan file to refine in place
+  --payload <path>    Path to a JSON file with the refiner output
+                      ({ acceptanceCriteria, definitionOfDone, coverageMatrix,
+                        grillFindings? })
+Optional:
+  --json              Machine-readable JSON output
+  --help              Show this help
+Exit codes:
+  0  Refinement succeeded; plan written in place; stop for local human review
+  1  Argument error, or fail-closed refine/grill/ambiguous state (no write)`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseRefinePlanFileCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "plan-file": { type: "string" },
+      payload: { type: "string" },
+      json: { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = { help: false, planFile: undefined, payload: undefined, json: false };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") continue;
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "plan-file") {
+      options.planFile = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token.name === "payload") {
+      options.payload = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token.name === "json") {
+      options.json = true;
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (typeof options.planFile !== "string" || options.planFile.trim().length === 0) {
+    throw parseError("refine-plan-file requires --plan-file <path>");
+  }
+  if (typeof options.payload !== "string" || options.payload.trim().length === 0) {
+    throw parseError("refine-plan-file requires --payload <path>");
+  }
+  return options;
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseRefinePlanFileCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+
+  const planPath = path.resolve(options.planFile);
+  const markdownText = await readFile(planPath, "utf8");
+  const payload = parseJsonText(await readFile(path.resolve(options.payload), "utf8"));
+
+  // Read the section-presence facts with the P1 surfaces, then hand them to the
+  // pure refine contract. The contract owns the state-machine gate and the
+  // in-place rewrite; this script owns I/O only.
+  // The docs-grill runs as a step of refinement. Classify each finding here (this
+  // script owns the scripts/ boundary) with #948's classifier and pass the
+  // dispositions to the pure core contract; an invalid finding yields a null
+  // disposition, which the contract fails closed on (docs_grill_failed).
+  const rawFindings = Array.isArray(payload?.grillFindings) ? payload.grillFindings : [];
+  const grillDispositions = rawFindings.map((finding) => {
+    const classified = classifyDocsGrillFinding(finding);
+    return {
+      kind: finding?.kind,
+      summary: typeof finding?.summary === "string" ? finding.summary : "",
+      disposition: classified.ok ? classified.disposition : null,
+    };
+  });
+
+  const [acHeading, dodHeading] = PLAN_FILE_REFINEMENT_SECTIONS;
+  const result = refinePlanFileInPlace({
+    markdownText,
+    baseSectionsValid: validatePlanFile(markdownText).ok,
+    hasAcceptanceCriteria: extractSection(markdownText, acHeading) ? true : false,
+    hasDefinitionOfDone: extractSection(markdownText, dodHeading) ? true : false,
+    payload: { ...payload, grillDispositions },
+  });
+
+  if (!result.ok) {
+    // Fail closed: surface the reason, do not write, do not advance, do not promote.
+    if (options.json) {
+      stdout.write(`${JSON.stringify({ ok: false, reason: result.reason, planFileIntakeState: result.planFileIntakeState ?? null })}\n`);
+    } else {
+      stdout.write(`refine-plan-file: FAIL (${result.reason})\n`);
+    }
+    process.exitCode = 1;
+    return result;
+  }
+
+  // Write the refined plan back in place — the single canonical artifact.
+  await writeFile(planPath, result.refinedMarkdown, "utf8");
+
+  const summary = {
+    ok: true,
+    planFile: planPath,
+    planFileIntakeState: result.planFileIntakeState,
+    stop: result.stop,
+    grillDispositions: result.grillDispositions,
+  };
+  if (options.json) {
+    stdout.write(`${JSON.stringify(summary)}\n`);
+  } else {
+    stdout.write(
+      [
+        "refine-plan-file: PASS",
+        `  plan: ${planPath}`,
+        `  state: ${result.planFileIntakeState}`,
+        `  stop: ${result.stop.kind} (${PLAN_FILE_REFINE_STOP.LOCAL_HUMAN_REVIEW === result.stop.kind ? "stop for local human review; no tracker artifact created" : result.stop.kind})`,
+        `  grill findings recorded: ${result.grillDispositions.length}`,
+      ].join("\n") + "\n",
+    );
+  }
+  return summary;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/refine/scaffold-spike-file.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// Scaffold a STARTABLE spike findings artifact from an inline question (#988 P2).
+//
+// `/start-spike <question>` needs a findings artifact that passes
+// `validateSpikeExplorationSections` (non-empty Question/Approach/Findings) so
+// `resolve-dev-loop-startup --spike <path>` accepts it. This is the only new
+// piece behind /start-spike: a pure section builder + a thin file writer. The
+// Recommendation is left for the spike to fill in (the exit marker), matching
+// the spike-mode contract — so this scaffolds an in-progress spike, not a
+// ready-for-exit one. No new spike behavior; the intake/gate/exit machinery is
+// the shipped #964/#965/#966 surface.
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+
+import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { SPIKE_FILE_EXPLORATION_SECTIONS } from "./validate-spike-file.mjs";
+
+// Placeholder bodies the operator fills in during the spike. Non-empty so the
+// exploration scaffold validates; explicitly marked TBD so they are obviously
+// stubs, not findings. (`Recommendation` is intentionally omitted — it is the
+// exit marker, written when the spike concludes.)
+const PLACEHOLDER = "TBD — filled in during the spike.";
+
+const USAGE = `Usage:
+  scaffold-spike-file.mjs --question <text> --out <path>
+
+Scaffold a startable spike findings artifact from an inline question. Writes a
+file carrying the exploration scaffold (## Question filled from --question,
+## Approach/## Findings stubbed) so \`resolve-dev-loop-startup --spike <path>\`
+accepts it. The ## Recommendation is left for the spike to fill in.
+
+Options:
+  --question <text>   Required. The question the spike investigates.
+  --out <path>        Required. Where to write the findings artifact.
+  --help, -h          Show this help.
+
+Output (stdout):
+  JSON: { ok: true, path: "<abs>", question: "<text>" }
+
+${JQ_OUTPUT_USAGE}
+`.trim();
+
+// Pure builder: question text -> a findings-artifact markdown body carrying the
+// exploration scaffold. Question gets the operator's text; Approach/Findings get
+// non-empty placeholder bodies so the exploration scaffold validates.
+export function buildSpikeScaffold(question) {
+  const trimmed = String(question ?? "").trim();
+  if (trimmed.length === 0) {
+    throw Object.assign(new Error("--question must be non-empty"), { code: "INVALID_ARGS" });
+  }
+  const bodies = { Question: trimmed, Approach: PLACEHOLDER, Findings: PLACEHOLDER };
+  const sections = SPIKE_FILE_EXPLORATION_SECTIONS.map(
+    (heading) => `## ${heading}\n\n${bodies[heading]}\n`,
+  );
+  return `# Spike\n\n${sections.join("\n")}`;
+}
+
+function parseCliArgs(argv) {
+  const parseError = (message) => Object.assign(new Error(message), { usage: USAGE, code: "INVALID_ARGS" });
+  const requireValue = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw parseError(message);
+    }
+    return v;
+  };
+  // The question is free text embedded in the artifact body, never forwarded as
+  // a CLI option — so unlike --out/--jq it may legitimately begin with `-`
+  // (e.g. "- should we ...?"). Only require a non-empty value, matching the
+  // core free-text parser; leave the leading-`-` guard to the path/filter flags.
+  const requireQuestion = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0) {
+      throw parseError(message);
+    }
+    return v;
+  };
+
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      question: { type: "string" },
+      out: { type: "string" },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unexpected argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        args.help = true;
+        break;
+      case "json":
+        // Output is JSON by default; accepted as a no-op for callers that pass it.
+        break;
+      case "question":
+        args.question = requireQuestion(token, "--question requires a value");
+        break;
+      case "out":
+        args.out = requireValue(token, "--out requires a value (path)");
+        break;
+      case "jq":
+        args.jq = requireValue(token, "--jq requires a filter");
+        break;
+      case "silent":
+        args.silent = true;
+        break;
+      default:
+        throw parseError(`Unknown flag: ${token.rawName}`);
+    }
+  }
+  return args;
+}
+
+export async function main(args, { writeFileImpl = writeFile, mkdirImpl = mkdir } = {}) {
+  if (!args.question) {
+    throw Object.assign(new Error("--question is required"), { usage: USAGE, code: "INVALID_ARGS" });
+  }
+  if (!args.out) {
+    throw Object.assign(new Error("--out is required"), { usage: USAGE, code: "INVALID_ARGS" });
+  }
+  const body = buildSpikeScaffold(args.question);
+  const outPath = path.resolve(args.out);
+  await mkdirImpl(path.dirname(outPath), { recursive: true });
+  // Fail closed on an existing file: the slash-command picks a fresh path and
+  // must never clobber a spike already in progress. `wx` makes write+exclusive
+  // atomic, so a concurrent create still loses (no overwrite).
+  try {
+    await writeFileImpl(outPath, body, { encoding: "utf8", flag: "wx" });
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      throw Object.assign(new Error(`--out already exists, refusing to overwrite: ${outPath}`), {
+        usage: USAGE,
+        code: "INVALID_ARGS",
+      });
+    }
+    throw err;
+  }
+  return { ok: true, path: outPath, question: String(args.question).trim() };
+}
+
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  let args;
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  try {
+    const result = await main(args);
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = err.code === "INVALID_ARGS" ? 1 : 2;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 2;
+  });
+}

package/scripts/refine/validate-plan-file.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+import { formatCliError } from "../_core-helpers.mjs";
+import {
+  DEFAULT_USAGE_SUFFIX,
+  checkBaseSections,
+  parseCheckerCliArgs,
+  writeCheckerOutput,
+  isDirectCliRun,
+} from "./_refine-helpers.mjs";
+
+const USAGE = `Usage:
+  validate-plan-file.mjs --input <path> [--json]
+Validate the base authoring sections of a phase-doc-format plan file: Status, Objective, In scope, Explicit non-goals.${"\n"}${DEFAULT_USAGE_SUFFIX}`;
+
+/**
+ * Base authoring sections a phase doc carries before refinement adds AC/DoD.
+ * Heading → distinct missing_* error code. Single source of truth: the section
+ * list is derived from these keys so the validator and the exported list cannot
+ * drift.
+ */
+const SECTION_CODES = {
+  Status: "missing_status",
+  Objective: "missing_objective",
+  "In scope": "missing_in_scope",
+  "Explicit non-goals": "missing_explicit_non_goals",
+};
+
+/** Base authoring section headings, in order (derived from SECTION_CODES). */
+export const PLAN_FILE_BASE_SECTIONS = Object.keys(SECTION_CODES);
+
+/**
+ * Pure validator. Reports whether a plan file (phase-doc format) carries every
+ * base authoring section with a non-empty body. An absent or empty-body section
+ * is reported under that section's distinct missing_* code. No side effects.
+ *
+ * @param {string} markdownText
+ * @returns {{ checker: "validate-plan-file", ok: boolean, errors: { code: string, message: string }[] }}
+ */
+export function validatePlanFile(markdownText) {
+  // checkBaseSections reports each absent/empty section under its distinct
+  // missing_* code; an empty-body section is malformed here too.
+  return checkBaseSections(markdownText, "validate-plan-file", SECTION_CODES);
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCheckerCliArgs(argv, USAGE, "validate-plan-file");
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+  const markdownText = await readFile(options.input, "utf8");
+  const result = validatePlanFile(markdownText);
+  writeCheckerOutput(result, { stdout, json: options.json });
+  return result;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/refine/validate-spike-file.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+import { formatCliError } from "../_core-helpers.mjs";
+import {
+  DEFAULT_USAGE_SUFFIX,
+  checkBaseSections,
+  parseCheckerCliArgs,
+  writeCheckerOutput,
+  isDirectCliRun,
+} from "./_refine-helpers.mjs";
+
+const USAGE = `Usage:
+  validate-spike-file.mjs --input <path> [--json]
+Validate the base authoring sections of a spike artifact: Question, Approach, Findings, Recommendation.${"\n"}${DEFAULT_USAGE_SUFFIX}`;
+
+/**
+ * Base authoring sections a spike artifact carries.
+ * Heading → distinct missing_* error code.
+ */
+const SECTION_CODES = {
+  Question: "missing_question",
+  Approach: "missing_approach",
+  Findings: "missing_findings",
+  Recommendation: "missing_recommendation",
+};
+
+export const SPIKE_FILE_BASE_SECTIONS = Object.keys(SECTION_CODES);
+
+/**
+ * Recommendation is the exit-marker section: present + non-empty means the
+ * spike has reached a recommendation and is ready for a discard/graduate exit
+ * decision. The exploration scaffold (Question/Approach/Findings) is what an
+ * in-progress spike must carry for `--spike` entry. (Mirrors the plan-file
+ * base-vs-refinement-section split.)
+ */
+export const SPIKE_FILE_EXIT_MARKER_SECTION = "Recommendation";
+export const SPIKE_FILE_EXPLORATION_SECTIONS = SPIKE_FILE_BASE_SECTIONS.filter(
+  (h) => h !== SPIKE_FILE_EXIT_MARKER_SECTION,
+);
+
+const EXPLORATION_SECTION_CODES = Object.fromEntries(
+  SPIKE_FILE_EXPLORATION_SECTIONS.map((h) => [h, SECTION_CODES[h]]),
+);
+
+/**
+ * Pure validator. Reports whether a spike artifact carries every base authoring
+ * section with a non-empty body. An absent or empty-body section is reported
+ * under that section's distinct missing_* code. No side effects.
+ *
+ * @param {string} markdownText
+ * @returns {{ checker: "validate-spike-file", ok: boolean, errors: { code: string, message: string }[] }}
+ */
+export function validateSpikeFile(markdownText) {
+  return checkBaseSections(markdownText, "validate-spike-file", SECTION_CODES);
+}
+
+/**
+ * Entry-gate validator for `--spike`: a spike is startable as soon as it carries
+ * the exploration scaffold (Question/Approach/Findings) with non-empty bodies;
+ * the Recommendation is filled in DURING the spike, not required to begin one.
+ *
+ * @param {string} markdownText
+ * @returns {{ checker: "validate-spike-file", ok: boolean, errors: { code: string, message: string }[] }}
+ */
+export function validateSpikeExplorationSections(markdownText) {
+  return checkBaseSections(markdownText, "validate-spike-file", EXPLORATION_SECTION_CODES);
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCheckerCliArgs(argv, USAGE, "validate-spike-file");
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+  const markdownText = await readFile(options.input, "utf8");
+  const result = validateSpikeFile(markdownText);
+  writeCheckerOutput(result, { stdout, json: options.json });
+  return result;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/release/extract-changelog-section.mjs

@@ -0,0 +1,111 @@
+import { readFile } from "node:fs/promises";
+
+import { isDirectCliRun } from "../_core-helpers.mjs";
+
+const USAGE = `Usage: extract-changelog-section.mjs --version <v> [--changelog <path>]
+
+Prints the CHANGELOG.md section for <version> (the block from "## <version>"
+up to the next "## " heading). Exits 1 if no such section exists or the section
+is empty, so a release is never created for an undocumented version. Exits 2 on
+usage/argument errors (missing --version, missing flag value, unreadable file).`;
+
+/**
+ * Extract the changelog block for a single version.
+ *
+ * Matches a heading line of the form "## <version>" optionally followed by
+ * " - <date>" (or any trailing text), and returns everything up to but not
+ * including the next "## " heading. Returns null when no matching section
+ * exists (fail closed — caller must not synthesize notes).
+ *
+ * @param {string} changelog - Full CHANGELOG.md contents.
+ * @param {string} version - Version without a leading "v" (e.g. "0.5.0").
+ * @returns {string|null} Trimmed section body (without the heading), or null.
+ */
+export function extractChangelogSection(changelog, version) {
+  const lines = changelog.split("\n");
+  // A heading is "## " followed by the exact version token, then either end of
+  // line or a non-version-character (space / "-"). This avoids "0.5.0" matching
+  // "0.5.0-rc1" or "0.5.01".
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const headingRe = new RegExp(`^##\\s+v?${escaped}(?=\\s|$)`);
+
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (headingRe.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+
+  if (start === -1) {
+    return null;
+  }
+
+  const body = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s/.test(lines[i])) {
+      break;
+    }
+    body.push(lines[i]);
+  }
+
+  return body.join("\n").trim();
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  let version;
+  let changelogPath = "CHANGELOG.md";
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--version" || argv[i] === "--changelog") {
+      const flag = argv[i];
+      const value = argv[i + 1];
+      if (value === undefined) {
+        process.stderr.write(`error: ${flag} requires a value\n\n${USAGE}\n`);
+        return 2;
+      }
+      if (flag === "--version") {
+        version = value;
+      } else {
+        changelogPath = value;
+      }
+      i += 1;
+    }
+  }
+
+  if (!version) {
+    process.stderr.write(`error: --version is required\n\n${USAGE}\n`);
+    return 2;
+  }
+
+  const normalized = version.replace(/^v/, "");
+
+  let changelog;
+  try {
+    changelog = await readFile(changelogPath, "utf8");
+  } catch (error) {
+    process.stderr.write(`error: cannot read ${changelogPath}: ${error.message}\n`);
+    return 2;
+  }
+
+  const section = extractChangelogSection(changelog, normalized);
+  if (section === null || section === "") {
+    process.stderr.write(
+      `error: no section found for version ${normalized} in ${changelogPath}. ` +
+        `Refusing to create a release for an undocumented version.\n`,
+    );
+    return 1;
+  }
+
+  process.stdout.write(`${section}\n`);
+  return 0;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  const exitCode = await main();
+  process.exitCode = exitCode;
+}

package/skills/dev-loop/SKILL.md

@@ -35,7 +35,14 @@ For async-required routes (config `workflow.asyncStartMode`, default `required`)
 > Under the Claude Code harness the dev-loop runs as a single agent: run these steps directly — no read-only boundary and no separate async-subagent dispatch. See [Main Agent Contract](../docs/main-agent-contract.md).
 
 <!-- pi-only -->
-**CLI invocation (`<dev-loops-package-root>`):** dev-loop CLI commands below are invoked as `node <dev-loops-package-root>/cli/index.mjs <verb...>` using the package-local CLI rather than `npx`, so they resolve unambiguously from the installed package without a global install. Resolve `<dev-loops-package-root>` from this skill's own installed path: this skill is installed at `<package-root>/.pi/skills/dev-loop/SKILL.md`, so the package root is `../../..` from this skill's directory. (The `dev-loop` agent resolves it analogously from its own installed path.)
+**CLI invocation (`<dev-loops-package-root>`):** dev-loop CLI commands below are invoked as `node <dev-loops-package-root>/cli/index.mjs <verb...>` using the package-local CLI rather than `npx`, so they resolve unambiguously from the installed package without a global install. Resolve `<dev-loops-package-root>` via the first of these **bounded** candidates whose `cli/index.mjs` exists — never assume a single fixed layout (under a Pi user-level install the package lives at `~/.pi/agent/npm/node_modules/dev-loops/`, so the old `../../..` package-relative guess from `skills/dev-loop/SKILL.md` overshoots the package root):
+
+1. **Node module resolution** (best-effort first try): `node -e "try{const p=require('node:path');console.log(p.resolve(p.dirname(require.resolve('dev-loops/cli/index.mjs')),'..'))}catch{process.exit(1)}"` — resolves the package root when `dev-loops` is reachable from Node's module search path (notably under `~/.pi/agent/npm`); this is cwd-dependent and commonly misses from a target-repo cwd, so the probe is wrapped in try/catch (no stack trace, exits non-zero on miss) — treat a non-zero exit as "probe missed, try the next candidate", not a hard failure.
+2. **Pi user-agent npm root** (reliable for user-level installs): `~/.pi/agent/npm/node_modules/dev-loops`.
+3. **Package-relative (legacy):** `../../..` from this skill's own directory (the original package-local install layout).
+4. **Global npm root:** `$(npm root -g)/dev-loops`.
+
+NEVER fall back to `find /` or any unbounded filesystem walk to locate the CLI — it stalls and trips the needs-attention timeout. If every bounded candidate fails, stop and ask the orchestrator/operator for the dev-loops package root rather than searching. (The `dev-loop` agent resolves it analogously.)
 <!-- /pi-only -->
 
 Resolve authoritative state via the startup resolver (`node <dev-loops-package-root>/cli/index.mjs loop startup --issue <n>` for issues, `node <dev-loops-package-root>/cli/index.mjs loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `node <dev-loops-package-root>/cli/index.mjs loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
@@ -118,6 +125,21 @@ Info/handoff requests can be served directly via `node <dev-loops-package-root>/
 - `node <dev-loops-package-root>/cli/index.mjs loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
 - `node <dev-loops-package-root>/cli/index.mjs loop info --issue <n> --json` — machine-readable JSON output
 
+## Reading tool output (token-economical convention)
+
+When you need a fact from a dev-loops JSON-emitting script, climb this ladder and stop at the first rung that answers the question — never read more output than you need:
+
+1. **Prefer the dev-loops subcommand / concise mode.** Use `loop info` or a script's `--concise`/`--summary` mode (e.g. `run-watch-cycle.mjs --concise`, `probe-copilot-review.mjs --concise`) for a human-readable digest. The concise modes surface loop state, Copilot round count, unresolved/actionable thread counts, round-cap-clean eligibility, CI status, next action, and the current round's new Copilot comment bodies.
+2. **`--silent` / `-s` for a yes/no check.** Reads ZERO output: `… --jq '<predicate>' --silent; echo $?` exits `0` for true / `1` for false. Without `--jq`, `--silent` maps the script's success (`ok:true`) to exit `0`, failure to `1`. Example: `probe-copilot-review.mjs --repo o/r --pr N --jq '.status=="idle"' -s`.
+3. **`--jq <filter>` to extract a single field.** The `--jq`-wired scripts (`probe-copilot-review.mjs`, `capture-review-threads.mjs`, `upsert-checkpoint-verdict.mjs`, the `scripts/projects/*` queue scripts) accept a gh-style `--jq` filter (jq subset: field access, `.[]`/`.[N]`, `|`, `select(...)`, `==`/`!=`/`<`/`<=`/`>`/`>=`, `length`, `keys`). It prints only the filtered value. An invalid filter fails closed (stderr + exit `2`), distinct from a clean predicate-false (silent exit `1`).
+4. **Use a dev-loops wrapper for `gh` reads — never an agent-level raw `gh`.** With `workflow.requireRetrospectiveInternalTooling: true`, a raw `gh` call is a recorded retro violation (fail-closed). If no script covers the read you need, treat it as a tooling gap: file/build a thin wrapper (reuse `scripts/lib/jq-output.mjs`, like the three below), don't shell out. The reads that already have wrappers:
+   - CI run-log tail (a failing PR's job log) → `scripts/github/fetch-ci-logs.mjs --repo <o/r> --pr <n> [--failed-only] [--tail <n>]`, **never raw `gh run view --log`/`--log-failed`**. (`probe-ci-status.mjs` names the failed checks; this returns the LOG.)
+   - Issue list/filter → `scripts/github/list-issues.mjs --repo <o/r> [--state <open|closed|all>] [--label <l>] [--limit <n>]`, **never raw `gh issue list`**. (The queue tool lists the project board; this is for arbitrary issue queries.)
+   - Issue comment → `scripts/github/comment-issue.mjs --repo <o/r> --issue <n> (--body <text> | --body-file <path>)`, **never raw `gh issue comment`**. Returns `{ ok, commentUrl }`.
+
+   All three accept the same `--jq`/`--silent` output flags as the other JSON-emitting scripts.
+5. **NEVER `| python3` or `node -e`** to parse tool JSON. If a field you need is missing from a script's output, add it to the script (or its concise mode), not an inline parser.
+
 ## Guard rules
 
 **Handoff envelope precedence:** The dev-loop builds the envelope immediately after authoritative-state resolution and treats it as the first handoff artifact. Read it first, load only `requiredReads`, execute `nextAction`. See [Resolve authoritative state](#resolve-authoritative-state). Derivation contract: [Workflow Handoff Contract](../docs/workflow-handoff-contract.md).
@@ -128,7 +150,7 @@ Info/handoff requests can be served directly via `node <dev-loops-package-root>/
 
 **Bounded async task contract:** Break work into discrete tasks with clear inputs, explicit outputs, bounded scope. No shell polling — use `run-watch-cycle.mjs` or `gh run watch`.
 
-**Round-cap budget check (enforced):** After every watch cycle, fix pass, or reply-resolve, check whether completed Copilot review rounds have reached the maximum (default: 5). Stop re-requesting Copilot review when the limit is reached — never re-request after the cap.
+**Round-cap budget check (enforced):** After every watch cycle, fix pass, or reply-resolve, check whether completed Copilot review rounds have reached the maximum (default: 5). Stop re-requesting Copilot review when the limit is reached — never re-request after the cap. Read these gate-cadence facts via the token-economical convention above (`run-watch-cycle.mjs --concise`, or `--jq`/`--silent` for a single field/predicate) — never `| python3` or `node -e`.
 
 ## Shorthand issue-based auto trigger contract