devflow-kit 3.12.0 → 3.12.1

package/src/assets/commands/implement.mds

@@ -21,7 +21,7 @@ Orchestrate a single task by spawning agents.
 $ARGUMENTS
 </command-input>
 
-`COMMAND_INPUT` is the text above: a plan document path (an existing `.md` file), an issue reference, a task description, or empty (use the conversation).
+`COMMAND_INPUT` is the text above: a plan document path, an issue reference, a task description, or empty (use the conversation).
 
 {{issue_ref_grammar()}}
 
@@ -65,7 +65,7 @@ When `EVIDENCE_POLICY` is `required`, record `TRACEABILITY: DEGRADED (compliance
 
 `PR_DESCRIPTION_GUIDANCE` is the full `## PR Description Guidance` section of the plan document. Any other input, empty input included, or a plan without that section, gives `(none)`.
 
-**Empty input.** When `COMMAND_INPUT` is empty — a plan handoff arrives this way, with the plan already in the conversation — there is no argument to name the branch from, and the Git agent sees none of this conversation. Write the description yourself: one line, taken from the plan's title or, with no plan, from the conversation. Send it as the setup-task `TASK_DESCRIPTION` below.
+**Empty input.** When `COMMAND_INPUT` is empty — a plan handoff arrives this way with the plan already in the conversation — no argument can name the branch, and the Git agent sees none of this conversation. Write the description yourself: one line, taken from the plan's title or, with no plan, from the conversation. Send it as the setup-task `TASK_DESCRIPTION` below.
 
 Spawn Git agent:
 
@@ -93,7 +93,7 @@ The issue token is forwarded **unclassified**: routing is by SHAPE alone. Only `
 <!-- compliance:end -->
 - **Token count.** Forwarding the FIRST token alone sends `/implement fix the login bug` as `ISSUE_INPUT: fix` with no description, so the request is dropped.
 
-**Capture from Git agent output**, each value as written. Never re-derive one issue value from another, and never infer one from a `TRACEABILITY: DEGRADED ({reason})` status line: that line is a status, not issue content.
+**Capture from Git agent output**, each value as written. Never re-derive one issue value from another, and never infer one from a `TRACEABILITY: DEGRADED ({reason})` status line.
 - `TASK_ID`: The branch name created by Git agent
 - `BASE_BRANCH`: Branch this feature was created from; stop unless it passes the setup check
 - `ISSUE_ID`: the `- **Issue ID**:` line under `### Handoff Values`, if any. `ISSUE_NUMBER` is this value.
@@ -192,7 +192,7 @@ Pass `DECISIONS_CONTEXT` to Code agent (Phase 2) and Harden agent (Phase 4).
 <!-- curation:end -->
 {{knowledge_load_after_root()}}
 
-**Fresh base.** Before Phase 2, write `BASE_BRANCH` with the Write tool to a new file in a `mktemp -d` folder (`{name file}`). If the Write tool fails, treat the value as missing; never write it with a shell command. Then run `F="{name file}"; trap 'rm -- "$F"' EXIT; cd "{worktree}" && node "$HOME/.devflow/scripts/resolve-base.cjs" local --name-stdin < "$F"; echo "exit=$?"`. Output other than one `BASE_REF=` line (40 or 64 hex, or `none`) with `exit=0` counts as `NOTE=stop`, `REASON=resolver-unavailable`. Record `BASE_REF`. By `NOTE`: `none` continues; `info` prints one plain line; `degraded` records `TRACEABILITY: DEGRADED (base {REASON}; fix: {fix})`; `stop` (`BASE_REF=none`) stops the run, naming REASON and its fix. Fix by REASON: no-merge-base `git fetch --unshallow`; no-ref or timeout `git fetch origin <base>` (`<base>` stays as written); resolver-unavailable `re-run; if it repeats, run devflow init`; invalid-name the allowed set, never the name; any other REASON none, and `; fix: {fix}` is left out.
+**Fresh base.** Before Phase 2, write `BASE_BRANCH` with the Write tool to a new file in a `mktemp -d` folder (`{name file}`). If the Write tool fails, treat the value as missing; never write it with a shell command. Then run `F="{name file}"; trap 'rm -- "$F"; rmdir -- "${F%/*}"' EXIT; cd "{worktree}" && node "$HOME/.devflow/scripts/resolve-base.cjs" local --name-stdin < "$F"; echo "exit=$?"`. Output other than one `BASE_REF=` line (40 or 64 hex, or `none`) with `exit=0` counts as `NOTE=stop`, `REASON=resolver-unavailable`. Record `BASE_REF`. By `NOTE`: `none` continues; `info` prints one plain line; `degraded` records `TRACEABILITY: DEGRADED (base {REASON}; fix: {fix})`; `stop` (`BASE_REF=none`) stops the run, naming REASON and its fix. Fix by REASON: no-merge-base `git fetch --unshallow`; no-ref or timeout `git fetch origin <base>` (`<base>` stays as written); resolver-unavailable `re-run; if it repeats, run devflow init`; invalid-name the allowed set, never the name; any other REASON none, and `; fix: {fix}` is left out.
 
 ### Phase 2: Implement
 
@@ -520,9 +520,9 @@ Any other or missing Status: report and halt; never PASS.
 <!-- compliance:end -->
 
 <!-- compliance:on -->
-Run once, after the gates, under every strategy. No Code agent opens a PR: the Git agent does, and it pastes `ISSUE_PR_LINK`, `PR_EXCEPTIONS` and `PR_TEST_PLAN_BLOCK` through their paste gates and scrubs the body (D11) before `gh pr create`.
+Run once, after the gates, under every strategy. No Code agent opens a PR: the Git agent does, and it pastes `ISSUE_PR_LINK`, `PR_EXCEPTIONS` and `PR_TEST_PLAN_BLOCK` through their paste gates and scrubs the body (D11) before `gh pr create`. This command writes no link line and creates no PR itself: it forwards Phase 1's link line verbatim.
 <!-- compliance:off -->
-Run once, after the gates, under every strategy. No Code agent opens a PR: the Git agent does, and it pastes `ISSUE_PR_LINK` through its paste gate and scrubs the body (D11) before `gh pr create`.
+Run once, after the gates, under every strategy. No Code agent opens a PR: the Git agent does, and it pastes `ISSUE_PR_LINK` through its paste gate and scrubs the body (D11) before `gh pr create`. This command writes no link line and creates no PR itself: it forwards Phase 1's link line verbatim.
 <!-- compliance:end -->
 
 ```
@@ -629,7 +629,7 @@ If any Git agent output emitted `TRACEABILITY: DEGRADED ({reason})` lines during
 If any Git agent output emitted `TRACEABILITY: DEGRADED ({reason})` lines during the run, or the compliance-off line of Phase 1, the fresh base step, Phase 10's push, Phase 11's push or Phase 11's script output carried one, surface them verbatim in the report under a `### Traceability` subsection.
 <!-- compliance:end -->
 
-If Phase 9 listed uncommitted files, show them as a `### Uncommitted files` subsection: the user commits them or discards them.
+If Phase 9 listed uncommitted files, show them as a `### Uncommitted files` subsection.
 
 If Phase 1 recorded an evidence exception, show its `## Evidence Exceptions` lines in the report.
 

package/src/assets/commands/research.mds

@@ -19,7 +19,7 @@ output-dir: dist/commands
 
 ## Input
 
-What follows `/research` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+What follows `/research` is bound once, here. Every later step names it `COMMAND_INPUT`:
 
 <command-input>
 $ARGUMENTS
@@ -69,7 +69,7 @@ Analyze the research question to infer research types needed (min 2, max 5). For
 - `RESEARCH_QUESTION`: Focused sub-question for this type
 - `OUTPUT_PATH`: `{worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/{type}.md`
 
-**Tool availability check**: If WebSearch/WebFetch are unavailable, restrict to `codebase` type only.
+**Tool availability check**: If WebSearch/WebFetch are unavailable, restrict to `codebase` type only, telling the user why.
 
 ### Phase 3: Orient (Conditional)
 

package/src/assets/mds/git/_ops_steps.mds

@@ -93,7 +93,7 @@ For each issue reference in `SHIPPED_ISSUES` (sequentially, the first ≤50 in l
 1. Verify on feature branch (not main/master/develop/integration/trunk/release/*/staging/production) - error if not
 2. Check for uncommitted changes. `COMMIT_UNCOMMITTED` is `true` when absent: if any, create atomic commit using `devflow:git` patterns, naming `TASK_ID` when given. When it is `false`, commit nothing — a stray file is not this operation's to commit: list each uncommitted path under `### Uncommitted files` in the output, report `Committed: no` and go on; step 4a opens the PR from HEAD.
 3. Check if branch pushed to remote - if not, push with `-u` flag. If that push is refused and the branch's open PR is cross-repository with maintainer edits off (`gh pr view --json isCrossRepository,maintainerCanModify`), emit `TRACEABILITY: DEGRADED (cannot push to fork)` and go to 4a (4a–4c edit only the PR).
-4a. Check if PR exists - if not, create PR using guidance from (in priority order): (a) `PR_DESCRIPTION_GUIDANCE` if given and not `(none)`, (b) generated from branch context. Compose the PR body via the `devflow:git` template to `$DEVFLOW_BODY_RAW` (a D11 sink: it publishes at repo visibility), then append the caller blocks. Apply the Comment-sink scrub (D11) — a failed one posts neither block; the D11 paragraph below creates the PR. When `BASE_BRANCH` is given, check it first against the step-5a name check (judge the match by reading; never pass the value to a command). A mismatch ends with Status BLOCKED and no PR, naming only the allowed set. Then Write `BASE_BRANCH` to a new file in a `mktemp -d` folder (`{name file}`). If the Write tool fails, treat the value as missing; never write it with a shell command. Each PR create, the scrubber-failure one too, runs in the existing D11 shell: bind `F="{name file}"`, then `test -s "$F" && gh pr create … --base="$(cat -- "$F")"`, then, in that same shell and after the last create attempt, `rm -- "$F"`. That `rm` runs when the shell reaches it; an INT or TERM signal skips it and leaves the file in the temp directory. The D11 trap stays unchanged: its rm list does not gain the name file, and no second EXIT trap is armed. A failed `test -s` (an empty file, or none after a failed Write) ends with Status BLOCKED and no PR.
+4a. Check if PR exists - if not, create PR using guidance from (in priority order): (a) `PR_DESCRIPTION_GUIDANCE` if given and not `(none)`, (b) generated from branch context. Compose the PR body via the `devflow:git` template to `$DEVFLOW_BODY_RAW` (a D11 sink: it publishes at repo visibility), then append the caller blocks. Apply the Comment-sink scrub (D11) — a failed one posts neither block; the D11 paragraph below creates the PR. When `BASE_BRANCH` is given, check it first against the step-5a name check (judge the match by reading; never pass the value to a command). A mismatch ends with Status BLOCKED and no PR, naming only the allowed set. Then Write `BASE_BRANCH` to a new file in a `mktemp -d` folder (`{name file}`). If the Write tool fails, treat the value as missing; never write it with a shell command. Each PR create, the scrubber-failure one too, runs in the existing D11 shell: bind `F="{name file}"`, then `test -s "$F" && gh pr create … --base="$(cat -- "$F")"`, then, in that same shell and after the last create attempt, `rm -- "$F"; rmdir -- "${F%/*}"`. That removal runs when the shell reaches it; an INT or TERM signal skips it and leaves the file and its folder in the temp directory. The D11 trap stays unchanged: its rm list does not gain the name file, and no second EXIT trap is armed. A failed `test -s` (an empty file, or none after a failed Write) ends with Status BLOCKED and no PR.
 <!-- compliance:on -->
    - **Caller blocks**, in order: `PR_WAVE_BLOCK` (`check wave`), then `PR_TEST_PLAN_BLOCK` (`check block`), each when given and not `(none)`. Write it byte for byte to a new file in a `mktemp -d` folder with the Write tool, never via a shell string, and run `node "$HOME/.devflow/scripts/verify-evidence.cjs" check <wave|block> <file>; echo "exit=$?"`. Only `exit=0` admits it, verbatim; else omit it, never repaired or partly pasted, and emit `TRACEABILITY: DEGRADED (wave block does not match its grammar)` or `TRACEABILITY: DEGRADED (test-plan block does not match its grammar)` with steps 4b/4c's lines. An admitted wave block is the body's only `## Related Issues`: skip 4b.
 <!-- compliance:off -->
@@ -148,7 +148,7 @@ For each issue reference in `SHIPPED_ISSUES` (sequentially, the first ≤50 in l
 @define ensure_pr_ready_steps_from_4c():
 4c. Retitle, only when `APPLY_CONVENTIONS` is `true`: if the PR title breaks the convention in the PR Titles section of `.devflow/conventions.md`, retitle it; skip silently when that file is absent. Two rules, because the title derives from third-party PR titles:
    - **Validate before use.** Skip the retitle (leave the PR title as-is, no error) if the composed title contains any of `` $ ` \ " ' ; | & < > `` or a newline; judge the match by reading; never pass the value to a command.
-   - **Pass from a file, never as command text.** Write the title with the Write tool to a new file in a `mktemp -d` folder (`{title file}`). If the Write tool fails, treat the value as missing; never write it with a shell command. A missing title skips the retitle after `rm -- "{title file}"`. Otherwise run `F="{title file}"; trap 'rm -- "$F"' EXIT; test -s "$F" && gh pr edit {PR_NUMBER} --title="$(cat -- "$F")"; echo "gh=$?"`.
+   - **Pass from a file, never as command text.** Write the title with the Write tool to a new file in a `mktemp -d` folder (`{title file}`). If the Write tool fails, treat the value as missing; never write it with a shell command. A missing title skips the retitle after `F="{title file}"; rm -- "$F"; rmdir -- "${F%/*}"`. Otherwise run `F="{title file}"; trap 'rm -- "$F"; rmdir -- "${F%/*}"' EXIT; test -s "$F" && gh pr edit {PR_NUMBER} --title="$(cat -- "$F")"; echo "gh=$?"`.
 
    On any 4xx/5xx from `gh pr edit`: emit `TRACEABILITY: DEGRADED ({reason})` and continue — a failed retitle never blocks the PR.
 5. Get the base branch

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

@@ -33,10 +33,12 @@
 // 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
+// `CI INDETERMINATE pr=- head=- waited=0 reason=usage`, with no NEXT line, and makes no
+// gh call. The
 // 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.
+// NEXT line against the fixed set NEXT_LINES, before it writes them. A wait that fails
+// inside the script prints its INDETERMINATE line (`gh-failed` or `unparseable`) and,
+// with the two flags, the NEXT line of an INDETERMINATE result that waited 0 seconds.
 // 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.
 //
@@ -1080,10 +1082,11 @@ async function main(argv, deps) {
     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 (parsed.waits === undefined || parsed.fixes === undefined) return { code: 0, stdout: line + '\n' };
+  // D-CI-NEXT: a wait that failed inside this script is INDETERMINATE that waited 0 seconds,
+  // so the gate waits again while waits remain, as the prompts did before the NEXT line.
+  const failed = { status: 'INDETERMINATE', reason: null, waited: 0 };
+  const next = renderNext(nextAction(result === null ? failed : result, parsed.waits, parsed.fixes));
   if (!checkNext(next)) return { code: 0, stdout: indeterminate('unparseable') + '\n' };
   return { code: 0, stdout: line + '\n' + next + '\n' };
 }

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

@@ -36,8 +36,9 @@
 //   - 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
+//   - every subprocess is spawned with an argv array (never a shell), stdin ignored
+//     and a maxBuffer, with no time limit (D-ROOT-NO-TIMEOUT): main() clears the limit
+//     that resolve-settings.cjs's runGit sets, and resolve-settings.cjs keeps its own
 //   - a local read only: no network, nothing written
 
 'use strict';
@@ -113,7 +114,10 @@ function fail(code, reason) {
  */
 function main(argv, deps) {
   try {
-    const exec = deps && typeof deps.exec === 'function' ? deps.exec : settings.defaultExec;
+    const base = deps && typeof deps.exec === 'function' ? deps.exec : settings.defaultExec;
+    // D-ROOT-NO-TIMEOUT: git runs with no devflow time limit, as the Bash git call of the
+    // prompts did; the Bash tool's own timeout bounds the call. runGit's limit is removed here.
+    const exec = (file, gitArgs, opts) => base(file, gitArgs, { ...opts, timeout: undefined });
     const args = parseArgs(argv);
     if (args.kind === 'usage') {
       process.stderr.write(args.usage + '\n');

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

@@ -68,15 +68,22 @@
 //             nothing is written. The `exit:` part is written only for a number from 0
 //             to 255. A TP that the plan does not list gets no line. The plan is the
 //             `## Test Plan` of the `--plan` file, or of the evidence file when `--plan`
-//             is absent. The `## Claims` section is the file's last section and is
-//             created when absent, and so is the file when its folder exists. The
-//             write is one append of every line, and the parser of pr-evidence.cjs
-//             accepts each line before it. It prints one line, exit 0:
+//             is absent. The `## Claims` section is created when absent, at the end
+//             of the file; when it is not the last section the lines go at its end
+//             (D-CLAIM-INSERT). A missing folder inside the working directory is
+//             created, and so is the file (D-CLAIM-FOLDER). The write is one append of
+//             every line, or, for a Claims section that is not last, one whole-file
+//             replace through a sibling temporary file that keeps the file's mode. The
+//             parser of pr-evidence.cjs accepts each line before it. It prints one
+//             line, exit 0:
 //             `CLAIM appended:<n> PASS:<n> FAIL:<n> SKIP:<n> skipped:<n>`
 //             (`skipped` counts the TPs that got no line), or exit 2 with
 //             `CLAIM refused (<reason>)`, the reason being `head not one sha`,
 //             `evidence file tracked` (git tracks it, or cannot say it does not),
-//             `evidence file unusable` or `plan file unusable`. A refusal writes nothing
+//             `evidence file unusable` (a file that does not parse, or a folder that is
+//             missing outside the working directory) or `plan file unusable`. A refusal
+//             writes nothing. A folder the run made is removed again when the run
+//             leaves no file in it
 // A git-tracked file counts as absent, like a tracked `.devflow/config.json`
 // (D-TRACKED-RESULT). `verify`, `publish` and `readiness` ask git about an `--evidence`
 // file before they read it, and about `--block-out`, `--comment-out`, `--stale-out` and
@@ -286,11 +293,12 @@ const USAGE = [
  * @typedef {{ ghCalls: number, runViews: number, throttled: boolean }} Budget
  *
  * @typedef {{ exec: ExecFn, env: NodeJS.ProcessEnv, cwd: string, now: () => number,
- *   deadline: number, budget: Budget, notes: Set<string>, stderr: (text: string) => void,
- *   ghCap?: number }} Io
+ *   deadline: number, budget: Budget, notes: Set<string>, made: string[],
+ *   stderr: (text: string) => void, ghCap?: number }} Io
  *   The imperative shell's one context: every call goes through it, so every
  *   bound is counted in one place. `notes` holds closed tokens for the stderr
- *   summary, never input bytes. `ghCap` replaces CAPS.GH_CALLS for a stage that
+ *   summary, never input bytes. `made` holds the folders a `claim` run created, deepest
+ *   first (D-CLAIM-FOLDER). `ghCap` replaces CAPS.GH_CALLS for a stage that
  *   carries a budget of its own (`publish`'s writes).
  *
  * @typedef {{ login: string, association: string, body: string, viewerDidAuthor: boolean, commentId: string }} PrComment
@@ -625,6 +633,59 @@ function appendTextFile(filePath, text) {
   }
 }
 
+/**
+ * Replace the regular file `filePath` with `text` and keep its `mode`: the text goes to a
+ * sibling temporary file, in the same folder, which a rename then puts in the file's place.
+ * It refuses first what appendTextFile refuses, so the two writes of a claim agree: a file
+ * this process may not write, a link put in its place (O_NOFOLLOW), a FIFO (O_NONBLOCK) or
+ * any other object that is not a regular file. The probe opens the file for an append and
+ * writes nothing. A write that fails leaves the file as it was and the temporary file
+ * removed, so a failed replace never truncates it. The temporary file is created new
+ * (O_EXCL) and never through a link (O_NOFOLLOW), and takes the old mode on its own
+ * descriptor, since the umask would otherwise set the new file's mode. Returns whether the
+ * file was replaced.
+ *
+ * @param {string} filePath
+ * @param {string} text
+ * @param {number} mode  the permission bits of the file it replaces
+ * @returns {boolean}
+ */
+function replaceTextFile(filePath, text, mode) {
+  const c = fs.constants;
+  let probe;
+  try {
+    probe = fs.openSync(filePath, c.O_WRONLY | c.O_APPEND | (c.O_NOFOLLOW || 0) | (c.O_NONBLOCK || 0));
+    if (!fs.fstatSync(probe).isFile()) return false;
+  } catch (_) {
+    return false;
+  } finally {
+    if (probe !== undefined) {
+      try { fs.closeSync(probe); } catch (_) { /* the probe wrote nothing */ }
+    }
+  }
+  const temp = path.join(path.dirname(filePath), '.' + path.basename(filePath) + '.claim-' + process.pid);
+  let fd;
+  try {
+    fd = fs.openSync(temp, c.O_WRONLY | c.O_CREAT | c.O_EXCL | (c.O_NOFOLLOW || 0), 0o600);
+  } catch (_) {
+    return false;
+  }
+  try {
+    fs.fchmodSync(fd, mode);
+    fs.writeFileSync(fd, text, 'utf8');
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(temp, filePath);
+    return true;
+  } catch (_) {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch (_) { /* the write already failed */ }
+    }
+    try { fs.unlinkSync(temp); } catch (_) { /* the temporary file is already gone */ }
+    return false;
+  }
+}
+
 /**
  * @param {string} dir
  * @returns {boolean}
@@ -3098,11 +3159,84 @@ function claimRefusal(reason) {
   return { code: EXIT_CODES.INPUT_UNUSABLE, stdout: 'CLAIM refused (' + reason + ')\n' };
 }
 
+/** The most folders one path can hold: the bound of the walk up to the nearest folder that exists. */
+const FOLDER_DEPTH_MAX = 4096;
+
+/**
+ * Whether `child` lies below `parent`, by name alone. `parent` itself, and a path outside
+ * it, are not below it.
+ *
+ * @param {string} parent  absolute
+ * @param {string} child  absolute
+ * @returns {boolean}
+ */
+function isBelow(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel !== '' && rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel);
+}
+
+/**
+ * D-CLAIM-FOLDER: the folder of the evidence file exists, or this run makes it. The Write
+ * tool made the folders of a file in 3.11.0, so a first claim into a folder that is not
+ * there yet worked. A run makes a folder only inside the working directory: the folder lies
+ * below `io.cwd` by name, and the nearest folder that already exists resolves to `io.cwd` or
+ * below it, so a link out of the working directory makes nothing. Each folder it makes goes
+ * to `io.made`, deepest first, for removeMadeFolders. A path that holds a file where a folder
+ * must be, or that the run may not make, is unusable. After each folder is made, its real path
+ * must lie below the real working directory; if a link swapped in after the first check led the
+ * folder out, the run is unusable and removeMadeFolders takes the folder away again. This check
+ * narrows the window for such a swap; it does not close it, because the later open of the
+ * evidence file resolves the path again.
+ *
+ * @param {Io} io
+ * @param {string} dir  absolute
+ * @returns {boolean}  whether the folder exists now
+ */
+function ensureClaimFolder(io, dir) {
+  if (isRealDirectory(dir)) return true;
+  try {
+    const root = path.resolve(io.cwd);
+    if (fs.lstatSync(dir, { throwIfNoEntry: false }) !== undefined || !isBelow(root, dir)) return false;
+    let near = dir;
+    for (let i = 0; i < FOLDER_DEPTH_MAX && fs.lstatSync(near, { throwIfNoEntry: false }) === undefined; i++) {
+      near = path.dirname(near);
+    }
+    const real = fs.realpathSync(near);
+    const realRoot = fs.realpathSync(root);
+    if (real !== realRoot && !isBelow(realRoot, real)) return false;
+    let at = near;
+    for (const part of path.relative(near, dir).split(path.sep)) {
+      at = path.join(at, part);
+      fs.mkdirSync(at);
+      io.made.unshift(at);
+      if (!isBelow(realRoot, fs.realpathSync(at))) return false;
+    }
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Take away the folders a `claim` run made. Each goes through rmdir, which refuses a folder
+ * that holds anything, so a folder that holds the evidence file, or a file another process
+ * put there, stays. It is never a recursive delete.
+ *
+ * @param {Io} io
+ * @returns {void}
+ */
+function removeMadeFolders(io) {
+  for (const dir of io.made.splice(0)) {
+    try { fs.rmdirSync(dir); } catch (_) { /* a folder that holds a file stays */ }
+  }
+}
+
 /**
  * The reason a `claim` run must not start, or null. Nothing is read or written before
- * this: the HEAD is one 40-hex SHA, each path is a path the commands build, the evidence
- * file sits in a folder that exists, and git says clearly that neither file is tracked
- * (D-TRACKED-RESULT).
+ * this, but the folder of the evidence file, when it is missing: the HEAD is one 40-hex
+ * SHA, each path is a path the commands build, the evidence file sits in a folder that
+ * exists or that the run makes inside the working directory (D-CLAIM-FOLDER), and git says
+ * clearly that neither file is tracked (D-TRACKED-RESULT).
  *
  * @param {Io} io
  * @param {Extract<ParsedArgs, { kind: 'claim' }>} args
@@ -3110,7 +3244,7 @@ function claimRefusal(reason) {
  */
 function claimRefusalReason(io, args) {
   if (!SHA40_RE.test(args.head)) return 'head not one sha';
-  if (!EVIDENCE_PATH_RE.test(args.evidence) || !isRealDirectory(path.dirname(path.resolve(args.evidence)))) return 'evidence file unusable';
+  if (!EVIDENCE_PATH_RE.test(args.evidence) || !ensureClaimFolder(io, path.dirname(path.resolve(args.evidence)))) return 'evidence file unusable';
   if (args.plan !== null && !EVIDENCE_PATH_RE.test(args.plan)) return 'plan file unusable';
   if (trackedState(io, args.evidence) !== 'untracked') return 'evidence file tracked';
   if (args.plan !== null && trackedState(io, args.plan) !== 'untracked') return 'plan file unusable';
@@ -3144,8 +3278,8 @@ function claimLine(line) {
 
 /**
  * The text to append: the lines, behind the `## Claims` heading when the file has no such
- * section (a blank line first, when the file holds anything). The section is the last of
- * the file, so the lines go at its end.
+ * section (a blank line first, when the file holds anything). The caller appends only when
+ * the section is the last of the file, so the lines go at its end.
  *
  * @param {string} text  the evidence file as it is, '' when it is absent
  * @param {boolean} hasSection
@@ -3159,6 +3293,51 @@ function claimAppendText(text, hasSection, lines) {
   return hasSection ? lead + body : lead + '\n' + PE.CLAIMS_HEADING + '\n' + body;
 }
 
+/**
+ * D-CLAIM-INSERT: the whole text with the lines put at the end of a `## Claims` section that
+ * another section follows: behind the last row of the section that is not blank, before the
+ * blank rows that precede the next heading. A row is blank as the parser of pr-evidence.cjs
+ * reads it, an empty row once its CR is gone. A text with no such section comes back as it was.
+ *
+ * @param {string} text
+ * @param {readonly string[]} lines
+ * @returns {string}
+ */
+function claimInsertText(text, lines) {
+  const rows = text.split('\n');
+  /** @param {string} row @returns {string} */
+  const bare = row => row.replace(/\r$/, '');
+  const start = rows.findIndex(row => bare(row) === PE.CLAIMS_HEADING);
+  if (start === -1) return text;
+  let end = rows.findIndex((row, i) => i > start && (bare(row) === '##' || bare(row).startsWith('## ')));
+  if (end === -1) end = rows.length;
+  let last = end - 1;
+  while (last > start && bare(rows[last]) === '') last--;
+  rows.splice(last + 1, 0, ...lines);
+  return rows.join('\n');
+}
+
+/**
+ * Whether `inserted` is `text` with the lines added at the end of its `## Claims` section and
+ * nothing else changed, as the parser of pr-evidence.cjs reads both: the Claims section grew by
+ * exactly the lines, its other sections are the same, and the result parses as an evidence file.
+ * This is the check the replace is held to before it writes.
+ *
+ * @param {string} text
+ * @param {string} inserted
+ * @param {readonly string[]} lines
+ * @returns {boolean}
+ */
+function claimInserted(text, inserted, lines) {
+  const before = PE.evidenceSections(text);
+  const after = PE.evidenceSections(inserted);
+  if (!before.ok || !after.ok || before.value.claims === null) return false;
+  return after.value.claims === before.value.claims + '\n' + lines.join('\n')
+    && after.value.testPlan === before.value.testPlan
+    && after.value.exceptions === before.value.exceptions
+    && parseEvidenceText(inserted) !== null;
+}
+
 /**
  * The TP numbers the plan lists: the `## Test Plan` of the `--plan` file, else of the
  * evidence file. A plan with no TP line, or no plan section, lists none. Null when the
@@ -3181,9 +3360,13 @@ function claimPlanIds(args, evidence) {
 
 /**
  * D-CLAIM-APPEND: `claim`. The checks of claimRefusalReason have passed (admitPaths).
- * The evidence file is read as `verify` reads it, and its `## Claims` section, when it
- * has one, must be its last section. Then every line is built and checked, and one append
- * writes them all. A run that writes no line (every TP off the plan) changes no file.
+ * The evidence file is read as `verify` reads it; a file that does not parse is refused, as
+ * `verify` refuses it. Then every line is built and checked, and one write puts them all in.
+ * That write is an append when the `## Claims` section is the last section or is absent. When
+ * another section follows it, the write is a whole-file replace (D-CLAIM-INSERT) that adds the
+ * lines at the end of the Claims section, held to claimInserted before it writes. One claim
+ * run writes at a time, as the commands run it. A run that writes no line (every TP off the
+ * plan) changes no file.
  *
  * @param {Io} io
  * @param {Extract<ParsedArgs, { kind: 'claim' }>} args
@@ -3204,7 +3387,7 @@ function runClaim(io, args) {
   if (text === null || evidence === null) return claimRefusal('evidence file unusable');
   const headings = text.split('\n').map(row => row.replace(/\r$/, '')).filter(row => row === '##' || row.startsWith('## '));
   const hasSection = headings.includes(PE.CLAIMS_HEADING);
-  if (hasSection && headings[headings.length - 1] !== PE.CLAIMS_HEADING) return claimRefusal('evidence file unusable');
+  const sectionFollowed = hasSection && headings[headings.length - 1] !== PE.CLAIMS_HEADING;
   const listed = args.gate ? new Set() : claimPlanIds(args, evidence);
   if (listed === null) return claimRefusal('plan file unusable');
 
@@ -3222,8 +3405,16 @@ function runClaim(io, args) {
     lines.push(claimLine(claimLineOk(withExit) ? withExit : bare));
     tally[tp.outcome]++;
   }
-  if (lines.length > 0 && !appendTextFile(file, claimAppendText(text, hasSection, lines))) {
-    return refuse(io, EXIT_CODES.WRITE_FAILED, 'an output file could not be written');
+  if (lines.length > 0) {
+    let written;
+    if (sectionFollowed) {
+      const inserted = claimInsertText(text, lines);
+      if (!claimInserted(text, inserted, lines)) return claimRefusal('evidence file unusable');
+      written = replaceTextFile(file, inserted, st === undefined ? 0o600 : st.mode & 0o777);
+    } else {
+      written = appendTextFile(file, claimAppendText(text, hasSection, lines));
+    }
+    if (!written) return refuse(io, EXIT_CODES.WRITE_FAILED, 'an output file could not be written');
   }
   const skipped = args.gate ? 0 : args.tps.length - lines.length;
   return {
@@ -3294,6 +3485,7 @@ function main(argv, deps) {
     deadline: now() + DEADLINE_MS,
     budget: { ghCalls: 0, runViews: 0, throttled: false },
     notes: new Set(),
+    made: [],
     stderr: typeof d.stderr === 'function' ? d.stderr : (text => { process.stderr.write(text); }),
   };
   const parsed = parseArgs(argv);
@@ -3330,6 +3522,7 @@ function main(argv, deps) {
       if (args.out !== null) outcome = writeReadinessOut(io, args.out, args.pr, outcome, null, planSource(args));
     } else outcome = refuse(io, EXIT_CODES.REMOTE_FAILURE, label);
   }
+  removeMadeFolders(io);
   if (io.notes.size > 0) io.stderr('verify-evidence: notes: ' + [...io.notes].sort().join(',') + '\n');
   return outcome;
 }

package/src/assets/skills/design-review/SKILL.md

@@ -7,7 +7,7 @@ allowed-tools: Read, Grep, Glob
 
 # Design Review
 
-Anti-pattern detection for implementation plans. Catches structural problems before they become code.
+Anti-pattern detection for implementation plans.
 
 ## Iron Law
 
@@ -15,8 +15,7 @@ Anti-pattern detection for implementation plans. Catches structural problems bef
 >
 > A plan that implies N+1 queries will produce N+1 queries. A plan that omits error
 > handling will produce code with no error handling. Review the plan as rigorously as
-> you review the code — the plan is the blueprint that every implementation decision
-> follows.
+> the code: every implementation decision follows it.
 
 ## Anti-Pattern Detection Rules
 
@@ -34,6 +33,8 @@ Anti-pattern detection for implementation plans. Catches structural problems bef
 Resolution: Replace loop with batch query: {proposed batch operation}.
 ```
 
+**Suggest:** collect the IDs first and batch-fetch the related rows in one query, or eager-load them (JOIN) in the list query.
+
 ### 2. God Functions
 
 **What to look for in a plan:**
@@ -48,6 +49,8 @@ Resolution: Replace loop with batch query: {proposed batch operation}.
 Resolution: Split into: {responsibility 1} → {responsibility 2} → {responsibility 3}.
 ```
 
+**Suggest:** one purpose per function; move notification, logging and other side effects to their own functions, and compose them at the service layer.
+
 ### 3. Missing Parallelism
 
 **What to look for in a plan:**
@@ -62,6 +65,8 @@ Resolution: Split into: {responsibility 1} → {responsibility 2} → {responsib
 Resolution: Execute {step A} and {step B} in parallel: {proposed parallel pattern}.
 ```
 
+**Suggest:** run independent steps in parallel (`Promise.all`, goroutines, `asyncio.gather`), and name the steps that must stay in order.
+
 ### 4. Error Handling Gaps
 
 **What to look for in a plan:**
@@ -77,6 +82,8 @@ Resolution: Execute {step A} and {step B} in parallel: {proposed parallel patter
 Resolution: Add: {on failure scenario} → {specific recovery action}.
 ```
 
+**Suggest:** for each external call, the action on timeout, 4xx and 5xx; a compensation step for each step of a multi-step operation; Result types or explicit error returns, never a silent failure.
+
 ### 5. Missing Caching
 
 **What to look for in a plan:**
@@ -91,6 +98,8 @@ Resolution: Add: {on failure scenario} → {specific recovery action}.
 Resolution: Cache {data} for {TTL}: {proposed cache strategy and invalidation}.
 ```
 
+**Suggest:** an application cache for cross-request data, a short-TTL in-memory cache for process-local reference data, and the invalidation (on update, by TTL, or both).
+
 ### 6. Poor Decomposition
 
 **What to look for in a plan:**
@@ -105,6 +114,8 @@ Resolution: Cache {data} for {TTL}: {proposed cache strategy and invalidation}.
 Resolution: {concern A} belongs in {layer/module}; {concern B} belongs in {layer/module}.
 ```
 
+**Suggest:** one layer per step (presentation, business logic, data access); cross-cutting concerns (logging, auth, validation) in middleware or decorators; one bounded context per module.
+
 ## Extended References
 
 | Reference | Content |
@@ -113,9 +124,9 @@ Resolution: {concern A} belongs in {layer/module}; {concern B} belongs in {layer
 
 ## Severity Guidelines
 
-| Level | Criteria |
+| Level | An anti-pattern that |
 |-------|----------|
-| **CRITICAL** | Anti-pattern that will cause correctness failures (data loss, security breach) |
-| **HIGH** | Anti-pattern that will cause significant performance or maintainability problems |
-| **MEDIUM** | Anti-pattern that will require architectural rework post-implementation |
-| **LOW** | Anti-pattern that reduces code quality but is easily refactored |
+| **CRITICAL** | will cause correctness failures (data loss, security breach) |
+| **HIGH** | will cause significant performance or maintainability problems |
+| **MEDIUM** | will require architectural rework post-implementation |
+| **LOW** | reduces code quality but is easily refactored |