pi-gauntlet 8.4.6 → 8.4.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v8.4.8 - 2026-11-11
+
+- Brainstorming opens with Today, The change, and What I checked in everyday words, followed by one question. Sources stay in the draft; the opening span is capped at 220 words except corrected or unchecked claims and intact quoted ticket rows.
+
+## v8.4.7 - 2026-11-11
+
+### Fixed
+- Plan tasks can declare `- Delete:` entries as literal write ownership without an existence requirement; unrecognized Files lines produce `files-block` findings, and rebuild restores Delete paths from the wave base. (#140)
+
 ## v8.4.6 - 2026-11-08
 
 - Require pi-cohort >=7.7.0 for model-only `subagent` registrations; remove the now-unreachable scripted-dispatch guard and nested-result exclusion. The codemode guide documents direct-only dispatch under both `on` and `only` and clarifies that skill examples illustrate direct tool calls, not scripts to execute. (#135)

package/README.md

@@ -142,7 +142,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) >= 1.5.0 - supports model-only tracker exposure and sequential tracker execution, so updates persist as transcript tool results rather than nested calls.
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.7.0 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.7.3 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
 
 Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both. At each pi-gauntlet release, set the pi-cohort peer minimum and README floor together to the newest released pi-cohort version; `/skill:release` checks the registry before proceeding.
 

package/extensions/lib/plan-check.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
 import test from "node:test";
 import { checkPlan, renderManifest, sha256, type FsPort, type PlanCheckFinding } from "./plan-check.ts";
 
@@ -177,6 +178,102 @@ test("valid fixture: checkPlan returns no findings (also covers the placeholder
   assert.deepEqual(findings, []);
 });
 
+test("unknown Files kind fails and later Modify is still checked", () => {
+  const missing = "extensions/lib/fixture-missing.ts";
+  const malformed = [
+    "- Modfy: old.ts",
+    "- Rename: old.ts",
+    "- Mod-ify: old.ts",
+    ...["Create", "Modify", "Test", "Delete"].flatMap(kind => [`- ${kind}: `, `- ${kind}:   `]),
+  ];
+  for (const entry of malformed) {
+    const plan = VALID_PLAN.replace(
+      "- Modify: extensions/lib/fixture-shared.ts",
+      `${entry}\n\n- Modify: ${missing}`,
+    );
+    const result = checkPlan(plan, SPEC_TEXT, {
+      exists: path => path !== missing,
+      glob: () => [],
+    });
+    assert.deepEqual(findingsFor(result.findings, "files-block"), [{
+      check: "files-block",
+      line: plan.split("\n").indexOf(entry) + 1,
+      text: entry,
+      reason: `Task 1: Files line "${entry}" is not a Create, Modify, Test or Delete entry with a path`,
+    }], entry);
+    assert.deepEqual(findingsFor(result.findings, "paths-exist"), [{
+      check: "paths-exist",
+      line: lineOf(plan, `- Modify: ${missing}`),
+      text: `- Modify: ${missing}`,
+      reason: `Modify: path "${missing}" does not exist`,
+    }], entry);
+    assert.deepEqual(result.parsed.tasks[0].files.map(file => file.path), [
+      "extensions/lib/fixture-task1.ts", missing, "extensions/lib/fixture-task1.test.ts",
+    ], entry);
+    assert.deepEqual(findingsFor(result.findings, "tests-block"), [], entry);
+    assert.equal(result.findings.length, 2, entry);
+  }
+});
+
+test("Delete glob fails", () => {
+  for (const path of ["src/*.ts", "src/file?.ts", "src/{old,new}.ts", "app/[id]/page.tsx"]) {
+    for (const suffix of ["", ":1-2"]) {
+      const entry = `- Delete: \`${path}${suffix}\``;
+      const plan = VALID_PLAN.replace(
+        "- Test: extensions/lib/fixture-task1.test.ts",
+        `${entry}\n- Test: extensions/lib/fixture-task1.test.ts`,
+      );
+      assert.deepEqual(checkPlan(plan, SPEC_TEXT, alwaysTruePort()).findings, [{
+        check: "files-block",
+        line: lineOf(plan, entry),
+        text: entry,
+        reason: `Task 1: Delete: path "${path}" is a glob; Delete takes a literal path`,
+      }]);
+    }
+  }
+});
+
+test("removal-only plan declares one Delete owner and passes checkPlan", () => {
+  const spec = `# Retire unused adapter
+
+## Design
+Remove \`src/legacy.ts\`; no other repository file changes.
+Keep the supported public entrypoint working.
+
+## Acceptance criteria
+- [ ] The unused adapter is absent.
+- [ ] The supported public entrypoint still works.
+`;
+  const candidate = JSON.parse(readFileSync(new URL("../../eval/writing-plans/results/removal-lists-delete/candidate.json", import.meta.url), "utf8"));
+  const outputs = Object.entries(candidate.outputs) as [string, { status: string; text: string }][];
+  assert.equal(outputs.length, 2);
+  for (const [model, output] of outputs) {
+    assert.equal(output.status, "ok", model);
+    const start = output.text.indexOf("```markdown\n");
+    const plan = start === -1 ? output.text : output.text.slice(start + "```markdown\n".length, output.text.lastIndexOf("```"));
+    const result = checkPlan(plan, spec, alwaysTruePort());
+    assert.deepEqual(result.findings, [], model);
+    assert.deepEqual(result.parsed.tasks.flatMap(task => task.files).map(({ kind, path }) => ({ kind, path })), [
+      { kind: "delete", path: "src/legacy.ts" },
+      { kind: "test", path: "tests/retirement.test.mjs" },
+    ], model);
+    assert.deepEqual(Object.values<{ after: string }>(candidate.judge[model].facts).map(fact => fact.after), Array(4).fill("holds"), model);
+  }
+});
+
+test("Delete entry passes before and after removal", () => {
+  const path = "extensions/lib/fixture-removed.ts";
+  const plan = VALID_PLAN.replace("- Test: extensions/lib/fixture-task1.test.ts", `- Delete: ${path}\n- Test: extensions/lib/fixture-task1.test.ts`);
+  for (const exists of [true, false]) {
+    const result = checkPlan(plan, SPEC_TEXT, {
+      exists: p => p !== path || exists,
+      glob: () => [],
+    });
+    assert.deepEqual(result.findings, [], `Delete path exists: ${exists}`);
+    assert.ok(result.parsed?.tasks[0].files.some(f => f.kind === "delete" && f.path === path));
+  }
+});
+
 test("no gauntlet grammar at all: emits both an absent-wave-headers and an absent-task-headers finding", () => {
   const plan = "# Just a plan\n\nSome prose with no wave or task headers at all.\n";
   const findings = checkPlan(plan, SPEC_TEXT, alwaysTruePort()).findings;
@@ -560,6 +657,37 @@ test("wave-file-disjointness: Test/Test allowed; Test vs Modify conflict; Modify
   assert.ok(WD(modifyModify).some((f) => f.reason.includes("fixture-shared.ts")));
 });
 
+test("wave-file-disjointness: Delete conflicts with every kind at every Files position before and after removal", () => {
+  const path = "extensions/lib/fixture-removed.ts";
+  const entries = [
+    "- Create: extensions/lib/fixture-task1.ts",
+    "- Modify: extensions/lib/fixture-shared.ts",
+    "- Test: extensions/lib/fixture-task1.test.ts",
+  ];
+  for (const kind of ["Create", "Modify", "Test", "Delete"]) {
+    for (let position = 0; position <= entries.length; position++) {
+      for (const exists of [true, false]) {
+        for (const suffix of ["", ":10-20"]) {
+          const files = [...entries];
+          files.splice(position, 0, `- Delete: ${path}${suffix}`);
+          const plan = VALID_PLAN.replace(entries.join("\n"), files.join("\n"))
+            .replace("- Create: extensions/lib/fixture-task2.ts", `- ${kind}: ${path}`);
+          const findings = checkPlan(plan, SPEC_TEXT, {
+            exists: p => p !== path || exists,
+            glob: () => [],
+          }).findings;
+          assert.deepEqual(findingsFor(findings, "wave-file-disjointness"), [{
+            check: "wave-file-disjointness",
+            line: lineOf(plan, "## Wave 1"),
+            text: plan.split("\n")[lineOf(plan, "## Wave 1") - 1],
+            reason: `Task 1 and Task 2 in Wave 1 both declare "${path}" / "${path}"`,
+          }], JSON.stringify({ kind, position, exists, suffix }));
+        }
+      }
+    }
+  }
+});
+
 test("Verification quote-integrity: task-owned literal check unchanged", () => {
   const mutated = VALID_PLAN.replace(
     "- via: `helperFn()`\n\nThis task implements helperFn() for parsing.",
@@ -659,21 +787,23 @@ test("check 3 fail-closed: unparseable **Spec:** anchor line", () => {
   assert.equal(ar[0].line, lineOf(mutated, "**Spec:** doc/specs/fixture-spec.md § Design without quotes"));
 });
 
-test("check 4 paths-exist: Modify: literal path does not exist", () => {
+for (const [name, prefix] of [
+  ["check 4 paths-exist: Modify: literal path does not exist", ""],
+  ["Modify after Delete is still existence-checked", "- Delete: extensions/lib/fixture-removed.ts\n"],
+]) test(name, () => {
+  const entry = "- Modify: extensions/lib/fixture-shared.ts";
+  const plan = VALID_PLAN.replace(entry, prefix + entry);
   const port: FsPort = {
     exists: (p) => p !== "extensions/lib/fixture-shared.ts",
     glob: () => [],
   };
-  const findings = checkPlan(VALID_PLAN, SPEC_TEXT, port).findings;
-  const pe = findingsFor(findings, "paths-exist");
-  assert.ok(
-    pe.some((f) => f.reason.includes("fixture-shared.ts") && f.reason.includes("does not exist")),
-    `expected a paths-exist finding, got: ${JSON.stringify(pe)}`,
-  );
-  assert.ok(
-    pe.some((f) => f.line === lineOf(VALID_PLAN, "- Modify: extensions/lib/fixture-shared.ts")),
-    `expected the paths-exist finding's line to point at the offending Modify: entry, got: ${JSON.stringify(pe)}`,
-  );
+  const findings = checkPlan(plan, SPEC_TEXT, port).findings;
+  assert.deepEqual(findingsFor(findings, "paths-exist"), [{
+    check: "paths-exist",
+    line: lineOf(plan, entry),
+    text: entry,
+    reason: 'Modify: path "extensions/lib/fixture-shared.ts" does not exist',
+  }]);
 });
 
 test("check 4 paths-exist: backtick-wrapped Modify: path is stripped before the existence check", () => {
@@ -929,6 +1059,38 @@ function tb(plan: string, spec = SPEC_TEXT, fs: FsPort = alwaysTruePort()): Plan
   return findingsFor(checkPlan(plan, spec, fs).findings, "tests-block");
 }
 
+test("unknown kinds outside Files are not Files findings", () => {
+  const nonePlan = VALID_PLAN.replace(T2_FILES_TEST, "")
+    .replace(T2_TESTS + "- baseline: abc1234 pass\n", "**Tests:**\n- none: docs\n");
+  for (const plan of [
+    nonePlan,
+    VALID_PLAN.replace("**Files:**", "- Rename: before.ts\n\n**Files:**"),
+    VALID_PLAN.replace("This task handles naming details.", "- Rename: after.ts"),
+    ...["- [ ] **Step 1: Work**", "- `echo work`"].map(boundary =>
+      VALID_PLAN.replace(T2_FILES_TEST, `${T2_FILES_TEST}${boundary}\n- Modfy: outside.ts\n`)),
+  ]) {
+    const result = checkPlan(plan, SPEC_TEXT, alwaysTruePort());
+    assert.deepEqual(findingsFor(result.findings, "files-block"), []);
+    assert.ok(result.parsed.tasks.every(task => task.filesUnknown.length === 0));
+    if (plan === nonePlan) assert.deepEqual(result.findings, []);
+  }
+});
+
+test("unheaded line in the Files run is a files-block finding", () => {
+  const entry = "- none: docs";
+  const plan = VALID_PLAN.replace(T2_FILES_TEST, "")
+    .replace(T2_TESTS + "- baseline: abc1234 pass\n", `${entry}\n`);
+  const findings = checkPlan(plan, SPEC_TEXT, alwaysTruePort()).findings;
+  assert.deepEqual(findingsFor(findings, "files-block"), [{
+    check: "files-block",
+    line: lineOf(plan, entry),
+    text: entry,
+    reason: `Task 2: Files line "${entry}" is not a Create, Modify, Test or Delete entry with a path`,
+  }]);
+  assert.ok(tb(plan).some((f) => f.reason.includes("block missing") && f.reason.includes("Task 2")));
+  assert.equal(findings.length, 2);
+});
+
 test("tests-block: block missing when a task has no **Tests:**", () => {
   const mutated = VALID_PLAN.replace(T2_TESTS, "");
   assert.ok(tb(mutated).some((f) => f.reason.includes("block missing") && f.reason.includes("Task 2")));
@@ -1409,6 +1571,22 @@ test("coordinated ledger rejects duplicate mapping sections", () => {
 });
 
 
+test("manifest carries Delete and later entries", () => {
+  const entry = "- Delete: extensions/lib/fixture-removed.ts:1-2";
+  const plan = VALID_PLAN.replace("**Files:**", `**Files:**\n${entry}`);
+  const result = checkPlan(plan, SPEC_TEXT, alwaysTruePort());
+  assert.deepEqual(result.findings, []);
+  assert.ok(result.parsed);
+  const tasks = renderManifest(result.parsed, "/plan", "/spec").split("\n").slice(1).map(line => JSON.parse(line));
+  assert.equal(tasks[0].task, 1);
+  assert.deepEqual(tasks[0].files, [
+    { kind: "Delete", path: "extensions/lib/fixture-removed.ts:1-2" },
+    { kind: "Create", path: "extensions/lib/fixture-task1.ts" },
+    { kind: "Modify", path: "extensions/lib/fixture-shared.ts" },
+    { kind: "Test", path: "extensions/lib/fixture-task1.test.ts" },
+  ]);
+});
+
 test("manifest preserves ordered task data and optional coordination fields", () => {
   const plan = VALID_PLAN.replaceAll("Task 1", "Task 4").replaceAll("Task 2", "Task 9")
     .replace("Implement helper", 'Implement | "helper"')

package/extensions/lib/plan-check.ts

@@ -30,7 +30,7 @@ interface Anchor {
 }
 
 interface FileEntry {
-  kind: "create" | "modify" | "test";
+  kind: "create" | "modify" | "test" | "delete";
   line: number;
   text: string;
   path: string;
@@ -53,6 +53,7 @@ interface Task {
   waveNumber: number;
   filesBlockMissing: boolean;
   files: FileEntry[];
+  filesUnknown: { line: number; text: string }[];
   specAnchorLine: number | undefined;
   anchors: Anchor[];
   anchorParseError: boolean;
@@ -216,7 +217,9 @@ function parsePlan(planText: string): ParsedPlan {
     }
 
     let filesLine: number | undefined;
+    let lastFilesLine = -1;
     const files: FileEntry[] = [];
+    const filesUnknown: Task["filesUnknown"] = [];
     let specAnchorLine: number | undefined;
     let anchors: Anchor[] = [];
     let anchorParseError = false;
@@ -225,6 +228,7 @@ function parsePlan(planText: string): ParsedPlan {
       const line = lines[k];
       if (filesLine === undefined && /^(?:\*\*Files:\*\*|Files:)/.test(line)) {
         filesLine = k + 1;
+        lastFilesLine = k;
         let p = k + 1;
         while (p <= bodyEndIdx) {
           const l = lines[p];
@@ -232,14 +236,19 @@ function parsePlan(planText: string): ParsedPlan {
             p++;
             continue;
           }
-          const fm = /^- (Create|Modify|Test): (.+)$/.exec(l);
-          if (!fm) break;
-          files.push({
-            kind: fm[1].toLowerCase() as FileEntry["kind"],
-            line: p + 1,
-            text: l,
-            path: fm[2].trim().replace(/^`|`$/g, ""),
-          });
+          if (!/^- [^\s:]+: /.test(l)) break;
+          lastFilesLine = p;
+          const fm = /^- (Create|Modify|Test|Delete): (.*\S.*)$/.exec(l);
+          if (fm) {
+            files.push({
+              kind: fm[1].toLowerCase() as FileEntry["kind"],
+              line: p + 1,
+              text: l,
+              path: fm[2].trim().replace(/^`|`$/g, ""),
+            });
+          } else {
+            filesUnknown.push({ line: p + 1, text: l });
+          }
           p++;
         }
       }
@@ -260,15 +269,7 @@ function parsePlan(planText: string): ParsedPlan {
 
     let headingIdx = -1;
     if (filesLine !== undefined) {
-      let lastEntry = filesLine - 1;
-      let p = filesLine;
-      while (p <= bodyEndIdx) {
-        const l = lines[p];
-        if (l.trim() === "") { p++; continue; }
-        if (/^- \w+: /.test(l)) { lastEntry = p; p++; continue; }
-        break;
-      }
-      let q = lastEntry + 1;
+      let q = lastFilesLine + 1;
       while (q <= bodyEndIdx && lines[q].trim() === "") q++;
       if (q <= bodyEndIdx && !mask[q] && lines[q] === "**Tests:**") {
         headingIdx = q;
@@ -307,6 +308,7 @@ function parsePlan(planText: string): ParsedPlan {
       orchestrator: lines.slice(i + 1, bodyEndIdx + 1).map(line => /^Orchestrator: (.+)$/.exec(line)).find(match => match)?.[1],
       filesBlockMissing: filesLine === undefined,
       files,
+      filesUnknown,
       specAnchorLine,
       anchors,
       anchorParseError,
@@ -872,6 +874,32 @@ function checkAnchorResolution(parsed: ParsedPlan, specLines: string[]): PlanChe
   return findings;
 }
 
+function checkFilesBlock(parsed: ParsedPlan): PlanCheckFinding[] {
+  const out: PlanCheckFinding[] = [];
+  for (const task of parsed.tasks) {
+    for (const entry of task.filesUnknown) {
+      out.push({
+        check: "files-block",
+        line: entry.line,
+        text: entry.text,
+        reason: `Task ${task.number}: Files line "${entry.text}" is not a Create, Modify, Test or Delete entry with a path`,
+      });
+    }
+    for (const entry of task.files) {
+      const path = stripLineSuffix(entry.path);
+      if (entry.kind === "delete" && isGlob(path)) {
+        out.push({
+          check: "files-block",
+          line: entry.line,
+          text: entry.text,
+          reason: `Task ${task.number}: Delete: path "${path}" is a glob; Delete takes a literal path`,
+        });
+      }
+    }
+  }
+  return out;
+}
+
 function checkPathsExist(parsed: ParsedPlan, fs: FsPort): PlanCheckFinding[] {
   const findings: PlanCheckFinding[] = [];
   for (const task of parsed.tasks) {
@@ -1335,6 +1363,7 @@ export function checkPlan(planText: string, specText: string, fs: FsPort): { fin
     findings.push(...checkQuoteIntegrity(parsed, specLines));
     findings.push(...checkAnchorResolution(parsed, specLines));
     findings.push(...checkPathsExist(parsed, fs));
+    findings.push(...checkFilesBlock(parsed));
     findings.push(...checkTestsBlock(parsed, fs));
     const { policies, local } = baselinePolicy(parsed);
     if (policies.length && !local) findings.push({ check: "baseline-line", line: 0, text: policies.join("\n"), reason: "expected one header Baseline policy: implement-local" });
@@ -1374,7 +1403,7 @@ export function checkPlan(planText: string, specText: string, fs: FsPort): { fin
 }
 
 export function renderManifest(parsed: ParsedPlan, planAbs: string, specAbs: string): string {
-  const kinds = { create: "Create", modify: "Modify", test: "Test" };
+  const kinds = { create: "Create", modify: "Modify", test: "Test", delete: "Delete" };
   return [
     `manifest: ${planAbs} | spec: ${specAbs} | tasks: ${parsed.tasks.length} | waves: ${parsed.waves.length}`,
     ...parsed.tasks.map(task => JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "8.4.6",
+  "version": "8.4.8",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -62,7 +62,7 @@
     "test": "node scripts/ci.mjs"
   },
   "peerDependencies": {
-    "pi-cohort": ">=7.7.0"
+    "pi-cohort": ">=7.7.3"
   },
   "dependencies": {
     "yaml": "^2.9.0"

package/skills/brainstorming/SKILL.md

@@ -95,7 +95,7 @@ Clarify freely. For a PR subject, run the framing check against the PR's diff as
 
 `Read` the gathered draft unconditionally before question one. Treat it as a helper, not a fence: verify load-bearing claims from primary code, and confirm whether the codebase or ecosystem already solves the problem.
 
-Ask one question per message, about purpose, constraints, success, and affected actors. Offer 2-4 labeled options (`A)`, `B)`, ...) for every questionary question, each a different outcome. Put the lead-in before the first option, each labeled option on its own physical line, and `Recommendation: <letter> - <why>` on its own final line; when more outcomes are plausible, the last option is `other - name it` or the question splits in two. Use this one-option-per-line layout even when chat-style rules in `AGENTS.md` require one paragraph or no Options/Recommendation layout. A decision that would be a yes/no or "may I" question is not asked: make it, state it as an assumption in the message that carries the next question or the premise note, and record it in the draft. Before asking, check code, docs, and tracker: look up current-state facts (dispatch a subagent when costly); adopt a ticket-recorded decision and cite the ticket, asking it only when a cited code or API contradiction, or conflicting recorded outcomes, prevents adopting it. Other approvals retain their wording.
+Ask one question per message, about purpose, constraints, success, and affected actors. Offer 2-4 labeled options (`A)`, `B)`, ...) for every questionary question, each a different outcome. Put the lead-in before the first option, each labeled option on its own physical line, and `Recommendation: <letter> - <why>` on its own final line; when more outcomes are plausible, the last option is `other - name it` or the question splits in two. Use this one-option-per-line layout even when chat-style rules in `AGENTS.md` require one paragraph or no Options/Recommendation layout. A decision that would be a yes/no or "may I" question is not asked: make it, state it as an assumption in the message that carries the next question or the premise note, and record it in the draft. Before asking, check code, docs, and tracker: look up current-state facts (dispatch a subagent when costly); adopt a ticket-recorded decision and attribute it to the ticket, asking it only when a cited code or API contradiction, or conflicting recorded outcomes, prevents adopting it. Other approvals retain their wording.
 
 Bad: `May I treat those two acceptance criteria as location-only deviations? Recommendation: yes`
 Good:
@@ -108,37 +108,18 @@ C) the existing skill step.
 Recommendation: A - the extension already holds the poll loop, so no new entrypoint.
 ```
 
-Append only citable findings - schemas, hard constraints, contradictions, and scope-changing answers - to `## Appended during questionary` using `edit`.
+Before sending the opening message, append every checked claim, held ones included, with its source, the lookup, and the result, together with schemas, hard constraints, contradictions, and scope-changing answers, using `edit`: to `## Appended during questionary` when the draft is the gather draft; directly to `## Problem` when it is the approved or carried spec (redraw or the unmarked spec-only PR route), where gather is skipped and that section does not exist.
 
-Before approaches, state in chat the supported, disproved, corrected, and unverified premises with sources and attempted lookups, in full sentences - no status-keyword lists, no template; if the design depends on no claims, one sentence says so. Treat an implicit dependency found missing as a corrected premise and one not checkable as unverified; state each in the premise note with the lookup the repo or spec names and its result, and carry it into `## Problem`. An unverified claim is not a stop: put it in Open Questions or a stated assumption. If a load-bearing claim is contradicted, the premise note is your next message - even as question one - and states the corrected fact with its source; the design continues on it and the user overrides in reply. Record the corrected fact, and any override, in the draft for `## Problem` or the relevant design decision.
+Before approaches, state in chat the supported, disproved, corrected, and unverified premises in the opening message's `## What I checked` section: supported renders as `Held:`, disproved and corrected as `Corrected:`, and unverified as `Not checked:`; that section is the premise note, and after the opening message a premise note is a `Corrected:` line. Treat an implicit dependency found missing as a corrected premise and one not checkable as unverified; state each in the premise note in everyday words that name what was looked at and what was found; record the lookup the repo or spec names and its result in the draft, and carry it into `## Problem`. An unverified claim is not a stop: put it in Open Questions or a stated assumption. If a load-bearing claim is contradicted, the premise note is your next message - even as question one - and states the corrected fact; the design continues on it and the user overrides in reply. Record the corrected fact, and any override, in the draft for `## Problem` or the relevant design decision; spec-writing carries every recorded claim, held ones included, into `## Problem`.
 
-Before question one, verify the draft's `Framing:` line against primary code and add your own recon. This check adds to the premise verification above and never replaces it: trace every consumer, caller, and data path the ask's constraints name, including retained loaders and every repro and verification step's implicit dependencies, before writing the holds-statement or the question; check those dependencies with the lookup the repo or spec names, and name the traces and dependencies in the holds-statement, not only the files read. A framing concern exists when you can state a cited case that the ask is misdiagnosed, wrong-sized, already solved, a band-aid where the root cause is reachable, or cuts across a sound pattern - including a repo convention that is itself the debt - and can name the alternative it implies; an objection without an alternative is a lead to investigate, not a concern. With a concern, question one is the framing question in the questionary format:
+Before question one, verify the draft's `Framing:` line against primary code and add your own recon. This check adds to the premise verification above and never replaces it: trace every consumer, caller, and data path the ask's constraints name, including retained loaders and every repro and verification step's implicit dependencies, before writing the holds-statement or the question; check those dependencies with the lookup the repo or spec names, and record the traces and dependencies in the draft through the evidence write above. A framing concern exists when you can state a cited case that the ask is misdiagnosed, wrong-sized, already solved, a band-aid where the root cause is reachable, or cuts across a sound pattern - including a repo convention that is itself the debt - and can name the alternative it implies; an objection without an alternative is a lead to investigate, not a concern. With a concern, question one is the framing question; without a concern, the message carries the holds-statement and the first ordinary question.
 
-```text
-gauntlet: question
-A) as framed
-B) pivot: <named alternative> - <cited reason>
-C) smaller or none: <what ships, or what happens if nothing ships>
-Recommendation: <letter> - <why>
-```
-
-For a band-aid concern, put the root-cause alternative in B. Without a concern, follow the marker with one sentence naming what was checked - `The framing holds: checked <x>, <y>` - and continue to the first ordinary question; a scout objection that yielded no alternative is named among the things checked.
+Read [Opening message](reference/opening-message.md) now and write question one's message against it; unreadable -> stop with a blocking error, never write it from memory.
 
 After any premise correction in the same message, ask the framing question or give the holds-statement. Ask the framing question at most once per brainstorm, including after pushback; the user's reply is final, and later doubts on the same point go to Open Questions or a `Pattern:` line. Recommend; never pivot without the reply. A ticket-recorded decision on the exact point follows the ticket rule above; an adopted decision records `Framing: kept (ticket <id>)`. A pivot never rewrites AC rows: rows it no longer satisfies take `deviates:` dispositions, and a pivot that changes the topic re-mints the slug.
 
 Record the outcome in the draft under `## Appended during questionary` as `Framing: kept` or `Framing: pivoted to <x> - <why>`; spec-writing carries that line into `## Problem`. On redraw entry (checklist step 4) the count restarts: run this evaluation once against the new draft. On redraw the draft is the approved spec: its `## Problem` `Framing:` line is context, not scout evidence, and the new outcome is recorded directly in `## Problem`. When the scout failed there is no `Framing:` line; supply the implicit-dependency check and the holds-statement or question from your own recon.
 
-Bad: `The ask adds another settings path - should we? Recommendation: no`
-Good:
-```text
-gauntlet: question
-The ask adds a second settings path beside the resolver that already owns every setting (settings/resolver.ts:11).
-A) as framed
-B) pivot: a key under the existing resolver - one read path, no new boundary
-C) smaller or none: document the default and ship no setting.
-Recommendation: B - the owning schema already exists.
-```
-
 ### 4. Explore approaches
 
 In a separate message after the premise note, restate each implicit dependency recorded as missing or not checkable, with its lookup and result, before presenting any approaches.

package/skills/brainstorming/reference/opening-message.md

@@ -0,0 +1,96 @@
+# Opening message
+
+Use this wording for question one's message at checklist step 4, including fresh, redraw, restored, and unmarked spec-only PR entry. Apply [Menu layout](menu-layout.md) for the first-line rule. The relatedness question before provisioning belongs to `pr-subject.md`.
+
+## Shape
+
+```text
+gauntlet: question
+
+## Today
+<how the affected part works now>
+
+## The change
+<what the request does to it, as something the user observes>
+
+## What I checked
+- Held: <one short sentence naming the held claims by role>
+- Corrected: <the claim as stated>; <the fact>, so <the consequence for the design>.
+- Not checked: <the claim> - <why it could not be checked>, so <what the design assumes or waits on>.
+
+The framing holds: checked <things, named by what they do>.
+<lead-in question>
+A) <outcome>
+B) <outcome>
+Recommendation: <letter> - <why>
+```
+
+Keep the three titles in that order, with a blank line between sections. Give each body one short paragraph or one list. Use `##`: pi renders it as a bold title, while `###` keeps its hashes.
+
+| Section | Write |
+|---|---|
+| `## Today` | Summarize how the affected part behaves now in one to three present-tense sentences total, combining related behaviors within a sentence. For a PR subject describe the PR's current state; on a redraw, the approved spec. |
+| `## The change` | Write one to three sentences total about the changes the user observes once it ships; fit related outcomes and any stated assumption into those sentences. Put the held claims' consequence for the design here, not on the `Held:` line. For a ticket request, say what the ticket asks, without listing acceptance rows. Put an assumption made in place of a yes/no question last. |
+| `## What I checked` | Group the held claims by role in one short `Held:` sentence; keep per-claim evidence in the draft. Give each corrected premise one `Corrected:` line stating the fact and its consequence for the design. Give each unverified premise, and a ticket gather could not fetch, one `Not checked:` line with the reason and what the design assumes or waits on. Use SKILL.md's premise paragraph to classify them. Omit labels with no entry. With no claims, write only `The design rests on no claims.` |
+
+For a request that is only an unread ticket reference, make `## Today` and `## The change` one sentence each saying their content is not known until the ticket's content is supplied. Infer neither current behavior nor the requested change from the reference or repo recon. Keep the `Not checked:` line, the framing line, and the usual question slot; name the failed ticket fetch among the things checked in `The framing holds: checked ...`.
+
+## Words and length
+
+Name each part by what it does. Use a literal name when the user used it in the request or when it is the finding itself: a missing file, a failing input, a quoted ticket row. Name a lookup by what was looked at, such as `the supplied templates/ directory listing`. Keep file-and-line references, commit ids, tracker ids, and trace counts in the draft. Use a tracker id only inside a command option such as `/skill:shape-ticket <ref>`, even when the user typed it; elsewhere, including an unfetched-ticket line, say `the ticket`, and render a lettered option with an unsupplied destination as a request to name that destination.
+
+Keep at most 220 words from the `## Today` line through the line before the first lettered option, both included. Exclude the marker and options. Count whitespace-delimited tokens containing a letter or digit: titles and labels count; `##` and `-` do not. Over the cap, cut `## Today` and `## The change` to one sentence each; keep `Held:` to its one short sentence. Only `Corrected:` lines, `Not checked:` lines, and an intact quoted ticket row in the question may then carry the message past 220: none of them is dropped, and the row stays intact.
+
+## Framing and question
+
+Write `The framing holds: checked <x>, <y>` with the checked things named by role, including a scout objection that yielded no alternative. For a concern, replace that line with the concern in one sentence, then offer `A) as framed`, `B) pivot: <named alternative> - <reason in everyday words>`, and `C) smaller or none: <what ships, or what happens if nothing ships>`, ending with `Recommendation: <letter> - <why>`. Put the root-cause alternative in B for a band-aid concern.
+
+Use the question slot for one question: the framing question with a concern, otherwise the first ordinary question. Apply [Ticket acceptance - Cut question](ticket-acceptance.md#cut-question) and its trigger table for which question comes first, when a cut question takes the slot, and how its row is quoted.
+
+Render the sections from the recon at hand; give anything it could not check a `Not checked:` line. Leave scout-failure flow to SKILL.md's `Framing:` record paragraph.
+
+Open the next message after a later correction with one `Corrected:` line under the same register, with no section titles: the first line, or directly after the marker when the message has one.
+
+## Worked examples
+
+Holds:
+
+```text
+gauntlet: question
+
+## Today
+The export uses the saved column order for every download.
+
+## The change
+Users can choose a different order for one download. The saved order remains the default, so existing downloads stay the same.
+
+## What I checked
+- Held: The export reads the saved order, and the download form can pass a different order.
+
+The framing holds: checked the saved order and the download form.
+Where should users choose the order?
+A) in the download form
+B) in a separate preview
+Recommendation: A - users can choose without leaving the download.
+```
+
+Concern:
+
+```text
+gauntlet: question
+
+## Today
+Every caller reads settings through the same resolver.
+
+## The change
+The request adds another settings file to supply a timeout override.
+
+## What I checked
+- Corrected: The draft says the resolver cannot accept overrides; it already accepts a timeout override, so the caller can pass it without another settings file.
+
+Another settings file duplicates the existing read path. Which outcome should we pursue?
+A) as framed
+B) pivot: pass the override through the existing resolver - it already supports it
+C) smaller or none: document the default and ship no setting
+Recommendation: B - the existing resolver can handle the override.
+```

package/skills/subagent-driven-development/SKILL.md

@@ -117,7 +117,7 @@ Run every plan task through this loop in a wave of N >= 1 tasks. Run waves in se
 - **Lifecycle per task:** `pending → in_progress (wave fan-out) → complete (wave commit)`; keep `in_progress` through exhausted integration or repair attempts pending the human's decision (see [When a Subagent Fails](#when-a-subagent-fails)); use `failed` only for a human-decided terminal failure; `skipped` when the plan drops it as not applicable (terminal, counted done). A rejected `update` names the earlier pending tasks and the legal fixes - record those tasks' true state, never `clear` or re-`init` to move on.
 - **Widget caveat (known, deliberately unfixed).** The persistent `plan_tracker` widget's icon strip (`○ → ✓`) and `(c/total)` count reflect every task, but its trailing *name* shows only the **first** `in_progress` task. Use the icon strip and the `status` action for the full in-flight view; a richer multi-task widget is a separate extension change, out of scope (YAGNI).
 
-1. **Independence check.** Assert pairwise-disjoint manifest `files`: Test/Test is allowed, Test/Create, Test/Modify and Modify/Modify overlap. Split overlaps into singleton waves. Trust the plan for runtime-resource disjointness; capture `WAVE_BASE_SHA` with `git -C <worktree> rev-parse HEAD`, print `wave <w> base <sha>` and hold it.
+1. **Independence check.** Assert pairwise-disjoint manifest `files`: only Test/Test may share a path. Split overlaps into singleton waves. Trust the plan for runtime-resource disjointness; capture `WAVE_BASE_SHA` with `git -C <worktree> rev-parse HEAD`, print `wave <w> base <sha>` and hold it.
 2. **Dispatch.** One one-step chain whose single `parallel` step contains only implementers, one item per task: `subagent({ async: false, context: "fresh", cwd: <worktree>, chain: [{ parallel: [{ agent: "implementer", as: "impl_<n>", outputSchema: IMPLEMENTER_STATUS_SCHEMA, output: "<REPORT_DIR>/wave<w>-task<n>.md", outputMode: "file-only", task: ... }], worktree: true, concurrency: 4, stopOn: { path: "/status", in: ["BLOCKED", "NEEDS_CONTEXT", "DONE_WITH_CONCERNS"] } }] })`. Use step `stopOn` to expose `## Outputs` structured JSON in the tool-result text; top-level `tasks` has no item schema and is not used. For manifest `"mode":"in-place"`: `cwd` the branch checkout, no `worktree:`, the wave union as `SCOPED_TEST_COMMANDS`. Payload is `planPath`, task anchor, spec path, `Leg:` with additive `Rules:` per [Leg routing](#leg-routing), `SCOPED_TEST_COMMANDS` (the task's own `tests` for isolated waves), status protocol. Dispatch no reviewer step after the implementers.
 3. **Read and integrate.** Read each child's structured output and report under the bound above; print `wave <w> task <n> <status> report <path> patch <path>`. Isolated waves: before integrating `DONE` / `DONE_WITH_CONCERNS`, require an `Artifacts:` patch path and a successful `test -s <patch>`. A missing or zero-byte initial patch takes the transition-table repair row; apply nothing and retain siblings. A nonempty patch -> `git -C <worktree> apply --index <patch>` in plan index order, print `wave <w> integrated task <n>`; a nonempty initial patch that fails to apply prints `wave <w> task <n> apply failed`, leaves every already-integrated sibling staged, and stops with a stop note listing which tasks are integrated and which failed - no automatic rebuild (the human may ask for one, which runs the rebuild recipe below). In-place waves: nothing to apply; the checkout already carries the work. `BLOCKED` / `NEEDS_CONTEXT` -> the takeable-decision ladder below.
 4. **Test gate.** Run each manifest test for the wave union separately, logs to `gate-<i>.log`; print `wave <w> gate <i> exit <code>`. A red gate enters step 6 as a gate repair for every task whose `files` the failing test belongs to (the manifest's `tests` owner), before any review; the review in step 5 runs only on a green gate.
@@ -172,7 +172,7 @@ Execution escalation to `implModel` is available whenever `failed[n]` reaches 2,
 
 ### Rebuild
 
-A repair delta that fails `git apply --index` prints `rebuild: task <n> - delta apply failed` and counts one failed attempt. Then, in the integrated tree: partition the task's manifest paths - every `Create` path (including a new test file declared as both `Create` and `Test`) is removed (`git -C <worktree> rm -q -f --ignore-unmatch -- <paths>`), and the remaining `Modify` / `Test` paths, deduplicated and excluding every `Create` path, are restored from the wave base (`git -C <worktree> restore --source="$WAVE_BASE_SHA" --staged --worktree -- <paths>`); sibling paths are untouched (step 1 guarantees disjointness). Run the repair-base recipe on that tree, so the snapshot holds the base plus every accepted sibling and nothing of task n; dispatch one `implementer` from `<RP_TREE>` with `worktree: true` and the task's original payload (this dispatch is the next attempt on `failed[n]`'s counter - the escalated round when the counter has reached 2); apply its `Artifacts:` patch to the integrated tree with `git apply --index` (a failure here is a hard stop, not a second rebuild). The rebuilt task rejoins its original wave: re-run the gate for the wave union, one `wave-reviewer` re-review with the marker and the prior report path, and step 7 commits the whole wave once and completes all of its indices together. The human may ask for a rebuild at any stop, which runs this same recipe; nothing else triggers one. `BLOCKED` / `NEEDS_CONTEXT` on a repair never rebuilds or re-snapshots: the ladder answers, then the identical payload is re-dispatched into the existing repair tree with the answer appended.
+A repair delta that fails `git apply --index` prints `rebuild: task <n> - delta apply failed` and counts one failed attempt. Then, in the integrated tree: partition the task's manifest paths, trailing `:N[-M]` stripped. Remove every `Create` path: `git -C <worktree> rm -q -f --ignore-unmatch -- <paths>`. Restore the `Modify` / `Test` paths plus the `Delete` paths `git -C <worktree> ls-tree -r --name-only "$WAVE_BASE_SHA" -- <Delete paths>` prints, deduplicated and excluding every `Create` path: `git -C <worktree> restore --source="$WAVE_BASE_SHA" --staged --worktree -- <paths>`. Skip a command with no paths. Sibling paths are untouched (step 1 guarantees disjointness). Run the repair-base recipe on that tree, so the snapshot holds the base plus every accepted sibling and nothing of task n; dispatch one `implementer` from `<RP_TREE>` with `worktree: true` and the task's original payload (this dispatch is the next attempt on `failed[n]`'s counter - the escalated round when the counter has reached 2); apply its `Artifacts:` patch to the integrated tree with `git apply --index` (a failure here is a hard stop, not a second rebuild). The rebuilt task rejoins its original wave: re-run the gate for the wave union, one `wave-reviewer` re-review with the marker and the prior report path, and step 7 commits the whole wave once and completes all of its indices together. The human may ask for a rebuild at any stop, which runs this same recipe; nothing else triggers one. `BLOCKED` / `NEEDS_CONTEXT` on a repair never rebuilds or re-snapshots: the ladder answers, then the identical payload is re-dispatched into the existing repair tree with the answer appended.
 
 ### Escalation and funding
 

package/skills/writing-plans/SKILL.md

@@ -213,6 +213,7 @@ For both rebase forms, consume every `pending` member in listed order, run `git
 **Files:**
 - Create: `exact/path/to/file.py`
 - Modify: `exact/path/to/existing.py:123-145`
+- Delete: `exact/path/to/removed.py`
 - Test: `tests/exact/path/to/test.py`
 
 **Tests:**
@@ -264,6 +265,8 @@ Every code task carries this step (red -> green -> fmt/lint -> commit). Doc-only
 
 Use bare `git` in task commit steps: the orchestrator commits each wave after code review accepts; a task's own commit step runs inside its nested worktree and is captured as its patch.
 
+Declare `Delete:` as write ownership with a literal path and no existence requirement; follow [the Files contract](reference/plan-contract.md#files-wave-file-disjointness-paths-exist-files-block).
+
 **Anchor rules.** See [reference/plan-contract.md § Spec anchors](reference/plan-contract.md). A task with no anchorable requirement omits the `**Spec:**` line and carries a mechanical-task row in `## Spec coverage` — silence is never valid.
 
 ## Spec Coverage Table

package/skills/writing-plans/reference/plan-contract.md

@@ -13,15 +13,15 @@ A wave is a maximal set of tasks that have no ordering dependency on each other,
 
 Read the home spec's `## Legs` using [the leg contract](../../brainstorming/reference/legs.md). Write `Leg: <repo>` immediately after each task heading, before `**Files:**`; absence means home. Keep the plan and its `**Spec:**` header at home, citing the home spec. Repair a `leg-unknown` task in the plan, never by adding spec membership.
 
-Write one `Baseline <repo>: <sha>` header per member. Match each task's baseline bullets to its own leg's SHA; require equality within a leg, not across legs. Resolve `Modify:`/`Create:`/`Test:` paths and globs against the admitted leg checkout, using its recorded `home:` with shared `NAME` against its declared primary. Key file overlap and cross-task created anchors on `(leg, path)`.
+Write one `Baseline <repo>: <sha>` header per member. Match each task's baseline bullets to its own leg's SHA; require equality within a leg, not across legs. Resolve `Modify:`/`Create:`/`Test:`/`Delete:` paths and globs against the admitted leg checkout, using its recorded `home:` with shared `NAME` against its declared primary. Key file overlap and cross-task created anchors on `(leg, path)`.
 
 Split mixed waves into consecutive leg-homogeneous waves, preserving dependencies. Re-walk each task's `Files:` under its leg using the leg contract's Gather rules procedure. Append task `Rules:` for files missing from the spec list; resolve `Rules: root only - paths unresolved`. Read the combined lists before execution and review.
 
-## Files (`wave-file-disjointness`, `paths-exist`)
+## Files (`wave-file-disjointness`, `paths-exist`, `files-block`)
 
 **File-ownership contract.** The per-task `**Files:**` block *is* the ownership declaration — no new syntax. Rule: **within a wave, the union of every task's declared paths must be pairwise disjoint.** Globs are allowed for `Modify` when exact paths are unknown, but must not overlap another same-wave task's paths. A task that must touch another's file belongs in a later wave.
 
-`Test:` entries are run anchors, not ownership: `Test`/`Test` on the same path across same-wave tasks is allowed; `Test` vs another task's `Create`/`Modify` is a conflict; writer/writer stays a conflict. `Modify:` paths must exist.
+Treat `Create`, `Modify`, and `Delete` as writers and `Test:` entries as run anchors, not ownership. Allow `Test`/`Test` on the same path across same-wave tasks; reject every other same-path pair. Require `Modify:` paths to exist. Declare `Delete:` as write ownership with a literal path and no existence requirement. List a file the task removes as `Delete:` in exactly one task, never also as `Modify:`. Treat any other `- <token>:` line in the Files list as a `files-block` finding.
 
 ## Spec anchors (`anchor-resolution`)