devflow-kit 3.11.0 → 3.12.0

package/src/assets/scripts/ci-wait.cjs

@@ -9,24 +9,36 @@
 // only (D-CI-WORKFLOWS): at most one answered probe per run, and its answer is kept for
 // the run; a failed probe is a failed poll, and the next poll probes again. It waits for
 // CI to start until CI_WAIT_MAX_SECONDS, classifies the head it was told about, and
-// prints exactly one line.
+// prints one CI line. With --waits and --fixes it prints one more line, the next
+// action of the CI gate (D-CI-NEXT).
 // Installed beside hud.sh and redact-secrets.cjs under ~/.devflow/scripts/.
 //
 // Usage:
-//   node ci-wait.cjs --pr <n> --head <sha>
+//   node ci-wait.cjs --pr <n> --head <sha> [--waits <w> --fixes <f>]
 //     <n>    the pull request number: digits, no leading zero, at most 9
 //     <sha>  the pushed head: 40 lowercase hex
+//     <w>    the waits run so far, this one included: 1 to 3
+//     <f>    the Fix agents run so far: 0 to 2
+//   Give --waits and --fixes together or not at all.
 //
 // Run it from the worktree, so gh finds the repository from the working directory.
 //
-// stdout (D-CI-LINE) is exactly one line, ending in a newline:
+// stdout (D-CI-LINE) is one line, ending in a newline:
 //   CI <STATUS> pr=<n> head=<first 7 hex> failing=<names|-> pending=<names|-> waited=<seconds>
 // with ` reason=<code>` appended to INDETERMINATE only. STATUS is one of STATUSES,
-// the check-ci-status Output enum. An argv that fails its gate prints the short form
+// the check-ci-status Output enum. With --waits and --fixes (D-CI-NEXT) a second line
+// follows the CI line, ending in a newline:
+//   NEXT=<wait|fix|proceed> SAY=<message>
+// where the message is one fixed phrase of this file, or `none`. The line is the gate
+// table of /implement and /resolve as a pure function of the status, the reason, the
+// seconds waited and the two counts, so a prompt only acts on the answer. An argv that
+// fails its gate prints the short form
 // `CI INDETERMINATE pr=- head=- waited=0 reason=usage` and makes no gh call. The
-// boundary re-checks the line against LINE_RE and the 400-character bound before it
-// writes it. Exit 0 whenever a line was printed; a reader treats a missing or
-// unparseable line, an unlisted status or a non-zero exit as INDETERMINATE.
+// boundary re-checks the CI line against LINE_RE and the 400-character bound, and the
+// NEXT line against the fixed set NEXT_LINES, before it writes them. A failed check
+// prints the one failure line and no NEXT line, as it does without the two flags.
+// Exit 0 whenever a line was printed; a reader treats a missing or unparseable line, an
+// unlisted status or a non-zero exit as INDETERMINATE.
 //
 // Design constraints (binding). The text of each verdict rule is written once, at the
 // marker named below; this list points to it. The workflow-probe rule has two readers,
@@ -49,8 +61,11 @@
 //     way. A silent foreground node call of about 570 s under a Bash timeout of
 //     600000 ms completed in a main-thread `claude -p` probe on 2026-10-09.
 //   - D-CI-NO-EXIT: nothing here calls process.exit(). An explicit exit can
-//     truncate stdout when it is a pipe, and the one line is the whole result. The
+//     truncate stdout when it is a pipe, and the printed lines are the whole result. The
 //     boundary sets process.exitCode and lets the event loop drain.
+//   - D-CI-NEXT: see nextAction. The gate table is plumbing, not judgment: it maps a
+//     classified status and two counts to one action and one fixed phrase. The phrases
+//     carry no gh output, so no check name reaches the NEXT line.
 //   - D-CI-WAIT-BOUNDS: every loop has a fixed bound (MAX_POLLS, the deadline, the
 //     name lists), and every wait is capped at CI_WAIT_MAX_SECONDS.
 //
@@ -160,6 +175,9 @@ const NAME_TOKEN_RE = /^(?:-|\+[0-9]+)$/;
 
 const PR_RE = /^[1-9][0-9]{0,8}$/;
 const HEAD_RE = /^[0-9a-f]{40}$/;
+/** D-CI-NEXT: the waits run so far, this one included (1 to MAX_WAITS), and the fixes (0 to MAX_FIXES). */
+const WAITS_RE = /^[1-3]$/;
+const FIXES_RE = /^[0-2]$/;
 const NO_PR_RE = /Could not resolve to a PullRequest/;
 const NO_CHECKS_RE = /no checks reported/i;
 
@@ -173,6 +191,35 @@ const LINE_RE = new RegExp(
 
 const USAGE_LINE = 'CI INDETERMINATE pr=- head=- waited=0 reason=usage';
 
+/**
+ * D-CI-NEXT: the budget of one CI gate (3 waits and 2 fixes in all), the actions it
+ * answers with and the phrases it says. A phrase is fixed text of this file; none holds
+ * gh output. `none` says nothing. After a full-deadline wait that ends in one of
+ * FINAL_AFTER_FULL_WAIT, another wait cannot change the answer, so the gate stops.
+ * WAITS_RE and FIXES_RE spell the same two bounds.
+ */
+const MAX_WAITS = 3;
+const MAX_FIXES = 2;
+const NEXTS = Object.freeze(['wait', 'fix', 'proceed']);
+const FINAL_AFTER_FULL_WAIT = Object.freeze(['head-mismatch', 'no-workflow-check']);
+const SAY_NONE = 'none';
+const SAY_NO_CI = 'No PR/CI configured, skipping CI validation.';
+const SAY_RUNNING = 'CI still running — verify manually before merging';
+const SAY_UNKNOWN = 'CI status unknown — verify manually before merging';
+const SAY_FIX = 'CI failed — a fix runs for the failing checks';
+const SAY_STILL_FAILS = 'CI still fails after ' + MAX_FIXES + ' fixes — verify manually before merging';
+
+/** The only NEXT lines this script prints: an action and a phrase that go together. */
+const NEXT_LINES = Object.freeze([
+  'NEXT=wait SAY=' + SAY_NONE,
+  'NEXT=fix SAY=' + SAY_FIX,
+  'NEXT=proceed SAY=' + SAY_NONE,
+  'NEXT=proceed SAY=' + SAY_NO_CI,
+  'NEXT=proceed SAY=' + SAY_RUNNING,
+  'NEXT=proceed SAY=' + SAY_UNKNOWN,
+  'NEXT=proceed SAY=' + SAY_STILL_FAILS,
+]);
+
 /**
  * D-CI-WORKFLOWS: the probe, a GET of the repository's workflow list. It is a fixed
  * argv with no field flag, no method flag and no input, and it names neither the PR nor
@@ -204,6 +251,8 @@ const VIEW_FIELDS = 'headRefOid,mergeable,state';
  * @typedef {{ status: string, pr: string, head: string, failing: string[], pending: string[],
  *   waited: number, reason: string | null }} CiResult
  *   `head` is the first 7 hex characters.
+ * @typedef {{ next: string, say: string }} NextAction
+ *   `next` is one of NEXTS; `say` is one fixed phrase or SAY_NONE (D-CI-NEXT).
  * @typedef {{ pr: string, head: string, exec: ExecFn, clock: Clock, env?: NodeJS.ProcessEnv }} WaitInput
  * @typedef {{ state: 'deadline', rowsRead: boolean } | { state: 'failed' } | { state: 'pending', pending: string[] }
  *   | { state: 'open' }
@@ -231,26 +280,34 @@ const DEADLINE_LAST = Object.freeze({ status: 'INDETERMINATE', reason: 'deadline
 // ---------------------------------------------------------------------------
 
 /**
- * D-CI-ARGV: exactly `--pr <digits> --head <40 lowercase hex>`, each once, in either
- * order, and nothing else. Anything that fails is refused before any gh call, so a
- * value never reaches gh's argv unless it is a plain number or a plain SHA.
+ * D-CI-ARGV: exactly `--pr <digits> --head <40 lowercase hex>`, each once, in any
+ * order, and nothing else. D-CI-NEXT adds an opt-in pair, `--waits <1 to 3>` and
+ * `--fixes <0 to 2>`: both or neither, each once, a single digit in its range. Anything
+ * that fails is refused before any gh call, so a value never reaches gh's argv unless it
+ * is a plain number or a plain SHA. The result holds `waits` and `fixes` only when the
+ * pair was given.
  *
  * @param {readonly string[]} args  the arguments after the script path
- * @returns {{ pr: string, head: string } | null}
+ * @returns {{ pr: string, head: string, waits?: number, fixes?: number } | null}
  */
 function parseArgs(args) {
-  if (!Array.isArray(args) || args.length !== 4) return null;
+  if (!Array.isArray(args) || (args.length !== 4 && args.length !== 8)) return null;
   let pr = null;
   let head = null;
-  for (let i = 0; i < 4; i += 2) {
+  let waits = null;
+  let fixes = null;
+  for (let i = 0; i < args.length; i += 2) {
     const flag = args[i];
     const value = args[i + 1];
     if (typeof value !== 'string') return null;
     if (flag === '--pr' && pr === null && PR_RE.test(value)) pr = value;
     else if (flag === '--head' && head === null && HEAD_RE.test(value)) head = value;
+    else if (flag === '--waits' && waits === null && WAITS_RE.test(value)) waits = Number(value);
+    else if (flag === '--fixes' && fixes === null && FIXES_RE.test(value)) fixes = Number(value);
     else return null;
   }
-  return pr !== null && head !== null ? { pr, head } : null;
+  if (pr === null || head === null) return null;
+  return waits === null || fixes === null ? { pr, head } : { pr, head, waits, fixes };
 }
 
 // ---------------------------------------------------------------------------
@@ -364,6 +421,63 @@ function checkLine(line) {
   return m !== null && (m[1] === 'INDETERMINATE') === (m[4] !== undefined);
 }
 
+/**
+ * D-CI-NEXT: what the CI gate does with one printed result. The table is the one the
+ * /implement and /resolve prompts used to carry:
+ *   PASSING                 proceed, saying nothing
+ *   NO_PR, NO_CI            proceed, saying that no CI is configured
+ *   PENDING                 wait while fewer than MAX_WAITS waits have run, else proceed
+ *   INDETERMINATE           wait while fewer than MAX_WAITS waits have run, unless the
+ *                           wait ran the whole deadline and the reason is one of
+ *                           FINAL_AFTER_FULL_WAIT; else proceed, saying the status is unknown
+ *   FAILING                 fix while fewer than MAX_FIXES fixes have run, else proceed
+ * A status outside STATUSES is unknown, which fails closed to the same proceed.
+ * `waited` and `reason` are the result's own values, never read back from text.
+ *
+ * @param {{ status: string, reason: string | null, waited: number }} result
+ * @param {number} waits  the waits run so far, this one included
+ * @param {number} fixes  the Fix agents run so far
+ * @returns {NextAction}
+ */
+function nextAction(result, waits, fixes) {
+  const proceed = say => ({ next: 'proceed', say });
+  switch (result.status) {
+    case 'PASSING':
+      return proceed(SAY_NONE);
+    case 'NO_PR':
+    case 'NO_CI':
+      return proceed(SAY_NO_CI);
+    case 'PENDING':
+      return waits < MAX_WAITS ? { next: 'wait', say: SAY_NONE } : proceed(SAY_RUNNING);
+    case 'INDETERMINATE': {
+      const final = result.waited === CI_WAIT_MAX_SECONDS && FINAL_AFTER_FULL_WAIT.includes(result.reason);
+      return waits < MAX_WAITS && !final ? { next: 'wait', say: SAY_NONE } : proceed(SAY_UNKNOWN);
+    }
+    case 'FAILING':
+      return fixes < MAX_FIXES ? { next: 'fix', say: SAY_FIX } : proceed(SAY_STILL_FAILS);
+    default:
+      return proceed(SAY_UNKNOWN);
+  }
+}
+
+/**
+ * @param {NextAction} action
+ * @returns {string}  `NEXT=<action> SAY=<message>`
+ */
+function renderNext(action) {
+  return 'NEXT=' + action.next + ' SAY=' + action.say;
+}
+
+/**
+ * Whether a line is one this script may print as the NEXT line: one of NEXT_LINES, whole.
+ *
+ * @param {string} line
+ * @returns {boolean}
+ */
+function checkNext(line) {
+  return typeof line === 'string' && NEXT_LINES.includes(line);
+}
+
 // ---------------------------------------------------------------------------
 // One bounded gh call
 // ---------------------------------------------------------------------------
@@ -947,9 +1061,10 @@ async function main(argv, deps) {
   /** @param {string} reason */
   const indeterminate = reason =>
     'CI INDETERMINATE pr=' + parsed.pr + ' head=' + parsed.head.slice(0, 7) + ' waited=0 reason=' + reason;
+  let result = null;
   let line;
   try {
-    const result = await waitForCi({
+    result = await waitForCi({
       pr: parsed.pr,
       head: parsed.head,
       exec: injected.exec || defaultExec,
@@ -958,10 +1073,19 @@ async function main(argv, deps) {
     });
     line = renderLine(result);
   } catch (_) {
+    result = null;
     line = indeterminate('gh-failed');
   }
-  if (!checkLine(line)) line = indeterminate('unparseable');
-  return { code: 0, stdout: line + '\n' };
+  if (!checkLine(line)) {
+    result = null;
+    line = indeterminate('unparseable');
+  }
+  if (result === null || parsed.waits === undefined || parsed.fixes === undefined) {
+    return { code: 0, stdout: line + '\n' };
+  }
+  const next = renderNext(nextAction(result, parsed.waits, parsed.fixes));
+  if (!checkNext(next)) return { code: 0, stdout: indeterminate('unparseable') + '\n' };
+  return { code: 0, stdout: line + '\n' + next + '\n' };
 }
 
 // ---------------------------------------------------------------------------
@@ -1011,6 +1135,11 @@ module.exports = Object.freeze({
   NAMES_LISTED,
   LINE_RE,
   USAGE_LINE,
+  MAX_WAITS,
+  MAX_FIXES,
+  NEXTS,
+  FINAL_AFTER_FULL_WAIT,
+  NEXT_LINES,
   WORKFLOWS_ARGS,
   parseArgs,
   sanitizeName,
@@ -1024,6 +1153,9 @@ module.exports = Object.freeze({
   askWorkflows,
   renderLine,
   checkLine,
+  nextAction,
+  renderNext,
+  checkNext,
   waitForCi,
   main,
 });

package/src/assets/scripts/hooks/assets/orchestrator-charter.md

@@ -3,12 +3,12 @@ You are the orchestrator of this session: you coordinate, agents produce.
 
 Never do work-product mainline: no file edits, no builds, no multi-file reads, no codebase orientation, no debug loops. Delegate all of it, with one bounded exception: the main thread may run a single git, gh or script command whose output stays under about 40 lines, never a diff, log or test run.
 
-Routing (Agent tool), by kind of work:
+Routing (Agent tool):
 - Search and listing: Explore. Codebase orientation: Skim.
 - Execution against a spec: Code (write code to a plan; open the prompt with `OPERATION: <mode>`: `issue-fix` for pre-classified review issues, else `implement`), Refactor (a given mechanical change: renames, moves, boilerplate; `OPERATION: edit`), Polish (clarity pass that keeps behaviour), Validate (build, typecheck, lint, test), Git (git/GitHub).
 - Checks: Harden (self-review that fixes, after Code), Evaluate (alignment with request and plan), Test (scenario QA on acceptance criteria; never fixes). Gate failures: Fix (`OPERATION:` `validation-fix`, `alignment-fix`, `qa-fix` or `ci-fix`), else Code (`OPERATION: implement`).
 - Bug fix: Code (`OPERATION: implement`). All debug work (root cause of a reported bug): devflow:debug, else Explore investigates and Code fixes; never the Debug agent.
-- Analysis, design, research: Design, Research, Review, Triage (validate review issues), Synthesize (many or large reports; open its prompt with `Mode: <mode>`).
+- Analysis, design, research: Design, Architect, Research, Review, Triage (validate review issues), Synthesize (many or large reports; open its prompt with `Mode: <mode>`).
 - A new knowledge base, only if the user asks: Knowledge (slug, name, directories).
 - Real-scale work matching a workflow: invoke the full skill instead: devflow:implement, devflow:plan, devflow:research, devflow:explore, devflow:code-review, devflow:resolve, devflow:bug-analysis (hunt bugs in a branch before merge).
 - Anything else: the closest roster agent, never general-purpose.
@@ -20,5 +20,5 @@ Operating rules:
 - Subagents see none of this conversation. Make every delegation self-contained: goal, constraints, relevant session decisions and facts, exact paths. A deliverable that draws on the conversation (issue, PR, report) needs its substance in the prompt, not a pointer.
 - Report cap: ask every direct delegation for a final report of at most about 1,500 tokens: findings, paths and verdicts, not file dumps.
 - Parallelize independent delegations in one message. Git operations stay sequential.
-- Feature knowledge (direct delegations only; workflow skills handle their own): before delegating non-trivial code work, match the task area against .devflow/features/index.md and pass each matching KB's one to three most relevant `## Rules` bullets (verbatim, IDs included; a KB without Rules: Anti-Patterns or Gotchas entries, cited by section), its path and its `##` heading index as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge to refresh that KB.
+- Feature knowledge (direct delegations only): before delegating non-trivial code work, match the task area against .devflow/features/index.md and pass each matching KB's one to three most relevant `## Rules` bullets (verbatim, IDs included; a KB without Rules: Anti-Patterns or Gotchas entries, cited by section), its path and its `##` heading index as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge to refresh that KB.
 - Plan handoff: if the user's first message begins with `Implement the following plan:`, say so in one sentence, then immediately invoke devflow:implement via the Skill tool with no arguments: the plan is already in this conversation. Do not pause to ask.

package/src/assets/scripts/hooks/preamble

@@ -11,7 +11,7 @@
 #      which the installed render drops when implement is absent) and in the dispatch below —
 #      update both together if Claude Code changes the handoff format.
 #   2. Slash skip: no reminder for slash commands (/...).
-#   3. Orchestrator reminder (2 lines): all other prompts, and a handoff prompt when implement
+#   3. Orchestrator reminder (1 line): all other prompts, and a handoff prompt when implement
 #      is not installed, get a generic delegation reminder.
 
 # Safe no-op fallback: must exist before hook-bootstrap is sourced.
@@ -85,8 +85,7 @@ elif [[ "$HEAD" == "/"* ]]; then
   dbg "EXIT: slash command — no reminder"
 else
   dbg "ORCHESTRATOR_REMINDER injected"
-  json_prompt_output "Orchestrator reminder: coordinate, don't produce — delegate edits, builds and multi-file reads to the fitting roster agent (Agent tool) or the matching devflow workflow skill.
-Keep only judgment work mainline: conversation, decisions, routing, combining a few agent reports."
+  json_prompt_output "Orchestrator reminder: coordinate, don't produce — delegate edits, builds and multi-file reads to a roster agent or a devflow workflow skill; keep only judgment work mainline (conversation, decisions, routing, combining agent reports)."
 fi
 
 dbg "=== HOOK COMPLETE ==="

package/src/assets/scripts/pr-evidence.cjs

@@ -1966,6 +1966,7 @@ module.exports = Object.freeze({
   MARKERS,
   TP_LINE_RE,
   CLAIM_LINE_RE,
+  CLAIMS_HEADING,
   EXCEPTION_LINE_RE,
   EVIDENCE_LINE_RE,
   SHA_RE,

package/src/assets/scripts/resolve-evidence-policy.cjs

@@ -15,7 +15,7 @@
 // `.devflow/policy.json` is detected by presence and never parsed
 // (D-POLICY-JSON-RETIRED).
 //
-// stdout is exactly one line plus "\n", or empty (D-POLICY-LINE):
+// stdout is exactly one line plus "\n" (D-POLICY-LINE):
 //   EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error>
 //   REF=<branch|none>[ WARN=<w>[,<w>…]] ISSUE_REQUIRED=<bool> APPLY_CONVENTIONS=<bool>
 //   REQUIRE_NON_AUTHOR_APPROVAL=<bool>
@@ -25,7 +25,7 @@
 //
 // Exit codes (a caller treats EVERY non-zero code as `required`):
 //   0  resolved — the line above
-//   1  usage error — stdout entirely empty, usage on stderr
+//   1  usage error — usage on stderr; prints FAIL_CLOSED_LINE
 //   2  input unusable — <dir> missing or not a directory; prints FAIL_CLOSED_LINE
 //   3  never emitted — this script writes no file, so the write-failure code of
 //      redact-secrets.cjs has no arm here and is absent from EXIT_CODES
@@ -139,8 +139,9 @@ const { SAFE_REF_RE } = projectConfig;
 const OUTPUT_LINE_RE = /^EVIDENCE_POLICY=(?<policy>required|standard) SOURCE=(?<source>file|worktree|default|invalid|error) REF=(?<ref>none|(?![A-Za-z0-9._/-]{0,254}\.\.)[A-Za-z0-9][A-Za-z0-9._/-]{0,254})(?: WARN=(?<warn>(?:remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy)(?:,(?:remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy)){0,3}))? ISSUE_REQUIRED=(?<issue>true|false) APPLY_CONVENTIONS=(?<conventions>true|false) REQUIRE_NON_AUTHOR_APPROVAL=(?<approval>true|false)$/;
 
 /**
- * The line every refusal prints (exits 2, 4 and 5). A constant, so the boundary
+ * The line every refusal prints (exits 1, 2, 4 and 5). A constant, so the boundary
  * can never fail to compose it, and `required` in every field a consumer reads.
+ * The literal fallback of the _evidence_policy.mds partial is these bytes.
  */
 const FAIL_CLOSED_LINE =
   'EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true';
@@ -196,7 +197,7 @@ const LS_REMOTE_SYMREF_RE = /^ref: refs\/heads\/([^\t\n]{1,255})\tHEAD$/;
  *   Injected by tests only, to reach the output gate.
  *
  * @typedef {{ code: number, line: string }} MainOutcome
- *   `line` is '' only for code 1, FAIL_CLOSED_LINE for codes 2, 4 and 5.
+ *   `line` is FAIL_CLOSED_LINE for codes 1, 2, 4 and 5.
  */
 
 /** @type {ParsedPolicy} */
@@ -1008,8 +1009,8 @@ function passesOutputGate(line, resolution) {
 
 /**
  * Settle whatever main() returned into what the boundary may print. The code
- * must be a known exit code and the line must fit it: '' for usage, a coherent
- * line for 0, FAIL_CLOSED_LINE for the refusals. Anything else is refused.
+ * must be a known exit code and the line must fit it: a coherent line for 0,
+ * FAIL_CLOSED_LINE for the refusals. Anything else is refused.
  *
  * @param {unknown} outcome
  * @returns {MainOutcome}
@@ -1019,11 +1020,10 @@ function settleOutcome(outcome) {
   if (o === null || typeof o !== 'object' || typeof o.line !== 'string') {
     return { code: EXIT_CODES.INTERNAL_ERROR, line: FAIL_CLOSED_LINE };
   }
-  if (o.code === EXIT_CODES.USAGE) return { code: EXIT_CODES.USAGE, line: '' };
   if (o.code === EXIT_CODES.RESOLVED) {
     return isCoherentLine(o.line) ? { code: o.code, line: o.line } : { code: EXIT_CODES.OUTPUT_GATE_REFUSED, line: FAIL_CLOSED_LINE };
   }
-  if (o.code === EXIT_CODES.INPUT_UNUSABLE || o.code === EXIT_CODES.OUTPUT_GATE_REFUSED) {
+  if (o.code === EXIT_CODES.USAGE || o.code === EXIT_CODES.INPUT_UNUSABLE || o.code === EXIT_CODES.OUTPUT_GATE_REFUSED) {
     return { code: o.code, line: FAIL_CLOSED_LINE };
   }
   return { code: EXIT_CODES.INTERNAL_ERROR, line: FAIL_CLOSED_LINE };
@@ -1069,7 +1069,7 @@ function main(argv, deps) {
   const args = parseArgs(argv);
   if (args.kind === 'usage') {
     process.stderr.write(args.usage + '\n');
-    return { code: EXIT_CODES.USAGE, line: '' };
+    return { code: EXIT_CODES.USAGE, line: FAIL_CLOSED_LINE };
   }
 
   if (!isUsableDirectory(args.dir)) {
@@ -1106,9 +1106,9 @@ function main(argv, deps) {
 //
 // This is the ONLY place that writes to stdout and sets process.exitCode.
 // It re-checks what main() returned (settleOutcome) before writing, so even a
-// main() that returned something malformed prints either nothing (usage) or a
-// line that passes the gate. Its catch is the fail-closed arm for anything
-// main() did not anticipate.
+// main() that returned something malformed prints a line that passes the gate
+// or FAIL_CLOSED_LINE. Its catch is the fail-closed arm for anything main() did
+// not anticipate.
 // ---------------------------------------------------------------------------
 
 if (require.main === module) {
@@ -1120,7 +1120,7 @@ if (require.main === module) {
     outcome = { code: EXIT_CODES.INTERNAL_ERROR, line: FAIL_CLOSED_LINE };
   }
   const settled = settleOutcome(outcome);
-  if (settled.line !== '') process.stdout.write(settled.line + '\n');
+  process.stdout.write(settled.line + '\n');
   process.exitCode = settled.code;
 }
 
@@ -1141,5 +1141,6 @@ module.exports = Object.freeze({
   complianceDefault,
   resolve,
   formatLine,
+  settleOutcome,
   main,
 });

package/src/assets/scripts/resolve-root.cjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// src/assets/scripts/resolve-root.cjs
+//
+// Prints the two roots a prompt works from, so a command runs ONE call for them:
+// the checkout (where docs artifacts and feature knowledge live) and the ledger
+// (where the curation index lives). Installed as a top-level sibling of
+// resolve-settings.cjs under ~/.devflow/scripts/, and it requires that file: the git
+// call, its default exec and the ledger rule are resolve-settings.cjs's own
+// (gitToplevel, defaultExec, ledgerRootOf). The ledger rule is the one the hooks apply
+// (hooks/resolve-project-root, and its TypeScript twin src/core/ledger-root.ts).
+// The script holds no other judgment.
+//
+// Usage: node resolve-root.cjs [<dir>]      (<dir> defaults to cwd)
+//
+// stdout on success is exactly two lines, each ended by "\n":
+//   WORKTREE=<absolute path>
+//   LEDGER=<absolute path>
+// WORKTREE is git's toplevel for <dir>. LEDGER is the main worktree when <dir> is in
+// a linked worktree and the main worktree holds a `.devflow/` folder that is not the
+// home directory; otherwise it is the toplevel. When git does not know the ledger
+// root, LEDGER is the toplevel. Outside a git repository both lines name the absolute
+// form of <dir>.
+//
+// Fail closed: on any failure stdout stays empty, stderr holds one reason line and the
+// exit code is not 0. The caller then uses its start directory for both roots.
+//
+// Exit codes:
+//   0  resolved — the two lines above
+//   1  usage error — usage on stderr
+//   2  input unusable — <dir> is missing or not a directory, or a path holds a control
+//      character (any C0 character, such as CR, LF or NUL)
+//   4  internal error — or git did not answer
+//   (the numbers match resolve-settings.cjs; 3 and 5 are never emitted)
+//
+// Design constraints (shared with resolve-settings.cjs):
+//   - main() returns {code, line} and never calls process.exit or throws; the single
+//     `require.main === module` boundary is the only stdout write and the only
+//     exitCode assignment
+//   - every subprocess is spawned with an argv array (never a shell), stdin ignored,
+//     a timeout and a maxBuffer — resolve-settings.cjs's runGit does this
+//   - a local read only: no network, nothing written
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const settings = require('./resolve-settings.cjs');
+
+const EXIT_CODES = Object.freeze({
+  RESOLVED: 0,
+  USAGE: 1,
+  INPUT_UNUSABLE: 2,
+  INTERNAL_ERROR: 4,
+});
+
+const USAGE = 'Usage: node resolve-root.cjs [<dir>]';
+
+/** Any C0 control character: a path that holds one cannot be a one-line answer. */
+const CONTROL_RE = /[\x00-\x1f]/;
+
+/** The grammar of a successful answer: two absolute paths, one per line, no control character. */
+const OUTPUT_RE = /^WORKTREE=\/[^\x00-\x1f]*\nLEDGER=\/[^\x00-\x1f]*$/;
+
+/**
+ * @param {readonly string[]} argv  process.argv
+ * @returns {{ kind: 'resolve', dir: string } | { kind: 'usage', usage: string }}
+ */
+function parseArgs(argv) {
+  const rest = Array.isArray(argv) ? argv.slice(2) : [];
+  /** @type {string[]} */
+  const positionals = [];
+  for (const arg of rest) {
+    if (typeof arg !== 'string' || arg.startsWith('-')) {
+      return {
+        kind: 'usage',
+        usage: 'resolve-root: unrecognised argument ' + JSON.stringify(String(arg)).slice(0, 80) + '\n' + USAGE,
+      };
+    }
+    positionals.push(arg);
+  }
+  if (positionals.length > 1) return { kind: 'usage', usage: USAGE };
+  return { kind: 'resolve', dir: positionals.length === 1 ? positionals[0] : process.cwd() };
+}
+
+/**
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isUsableDirectory(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Print one reason line and return the failure outcome.
+ *
+ * @param {number} code
+ * @param {string} reason
+ * @returns {{ code: number, line: string }}
+ */
+function fail(code, reason) {
+  process.stderr.write('resolve-root: ' + reason + ' — failing closed\n');
+  return { code, line: '' };
+}
+
+/**
+ * @param {readonly string[]} argv  process.argv
+ * @param {{ exec?: (file: string, args: string[], opts: object) => unknown }} [deps]  tests only
+ * @returns {{ code: number, line: string }}
+ */
+function main(argv, deps) {
+  try {
+    const exec = deps && typeof deps.exec === 'function' ? deps.exec : settings.defaultExec;
+    const args = parseArgs(argv);
+    if (args.kind === 'usage') {
+      process.stderr.write(args.usage + '\n');
+      return { code: EXIT_CODES.USAGE, line: '' };
+    }
+    const dir = path.resolve(args.dir);
+    if (CONTROL_RE.test(dir)) return fail(EXIT_CODES.INPUT_UNUSABLE, 'the directory path holds a control character');
+    if (!isUsableDirectory(dir)) {
+      return fail(EXIT_CODES.INPUT_UNUSABLE, 'not a usable directory: ' + JSON.stringify(dir).slice(0, 300));
+    }
+    const toplevel = settings.gitToplevel(exec, dir);
+    if (toplevel.kind === 'unknown') return fail(EXIT_CODES.INTERNAL_ERROR, 'git did not answer');
+    let worktree = dir;
+    let ledger = dir;
+    if (toplevel.kind === 'root') {
+      worktree = toplevel.root;
+      const found = settings.ledgerRootOf(toplevel.root, { exec });
+      ledger = found.kind === 'root' ? found.root : toplevel.root;
+    }
+    if (CONTROL_RE.test(worktree) || CONTROL_RE.test(ledger)) {
+      return fail(EXIT_CODES.INPUT_UNUSABLE, 'a root path holds a control character');
+    }
+    return { code: EXIT_CODES.RESOLVED, line: 'WORKTREE=' + worktree + '\nLEDGER=' + ledger };
+  } catch (_) {
+    return fail(EXIT_CODES.INTERNAL_ERROR, 'internal error');
+  }
+}
+
+/**
+ * Settle whatever main() returned into what the boundary may print: a success carries
+ * a line that passes the grammar, and every other outcome prints nothing.
+ *
+ * @param {unknown} outcome
+ * @returns {{ code: number, line: string }}
+ */
+function settleOutcome(outcome) {
+  const o = /** @type {any} */ (outcome);
+  if (o === null || typeof o !== 'object' || typeof o.line !== 'string' || typeof o.code !== 'number') {
+    return { code: EXIT_CODES.INTERNAL_ERROR, line: '' };
+  }
+  if (o.code === EXIT_CODES.RESOLVED) {
+    return OUTPUT_RE.test(o.line) ? { code: o.code, line: o.line } : { code: EXIT_CODES.INTERNAL_ERROR, line: '' };
+  }
+  return { code: o.code === EXIT_CODES.USAGE || o.code === EXIT_CODES.INPUT_UNUSABLE ? o.code : EXIT_CODES.INTERNAL_ERROR, line: '' };
+}
+
+// ---------------------------------------------------------------------------
+// Top-level boundary — the ONLY stdout write and the ONLY exitCode assignment
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  let outcome;
+  try {
+    outcome = main(process.argv);
+  } catch (_) {
+    process.stderr.write('resolve-root: internal error — failing closed\n');
+    outcome = { code: EXIT_CODES.INTERNAL_ERROR, line: '' };
+  }
+  const settled = settleOutcome(outcome);
+  if (settled.line !== '') process.stdout.write(settled.line + '\n');
+  process.exitCode = settled.code;
+}
+
+module.exports = Object.freeze({
+  EXIT_CODES,
+  OUTPUT_RE,
+  parseArgs,
+  settleOutcome,
+  main,
+});