pi-gauntlet 7.41.3 → 7.42.0

package/extensions/lib/plan-check.ts

@@ -43,6 +43,7 @@ interface TestsBullet {
 }
 
 interface Task {
+  orchestrator?: string;
   leg?: string;
   number: number;
   line: number;
@@ -96,7 +97,7 @@ interface Header {
   separatorLine: number | undefined;
 }
 
-interface ParsedPlan {
+export interface ParsedPlan {
   lines: string[];
   header: Header;
   waves: Wave[];
@@ -303,6 +304,7 @@ function parsePlan(planText: string): ParsedPlan {
       bodyStartLine: i + 1,
       bodyEndLine: bodyEndIdx + 1,
       waveNumber,
+      orchestrator: lines.slice(i + 1, bodyEndIdx + 1).map(line => /^Orchestrator: (.+)$/.exec(line)).find(match => match)?.[1],
       filesBlockMissing: filesLine === undefined,
       files,
       specAnchorLine,
@@ -1278,11 +1280,12 @@ function checkLedger(planText: string, specText: string): PlanCheckFinding[] {
   return findings;
 }
 
-export function checkPlan(planText: string, specText: string, fs: FsPort): PlanCheckFinding[] {
+export function checkPlan(planText: string, specText: string, fs: FsPort): { findings: PlanCheckFinding[]; parsed?: ParsedPlan; ledger: boolean } {
+  const ledger = planText.split("\n", 1)[0] === "# Ledger - loop engine";
   try {
     const ownership = legOwnership(specText);
-    if (ownership.findings.length) return ownership.findings;
-    if (planText.split("\n", 1)[0] === "# Ledger - loop engine") return checkLedger(planText, specText);
+    if (ownership.findings.length) return { findings: ownership.findings, ledger };
+    if (ledger) return { findings: checkLedger(planText, specText), ledger };
     const parsed = parsePlan(planText);
     const findings: PlanCheckFinding[] = [];
     if (ownership.legs.length) {
@@ -1293,7 +1296,7 @@ export function checkPlan(planText: string, specText: string, fs: FsPort): PlanC
         if (!ownership.legs.some(l => l.repo === task.leg)) findings.push({ check: "leg-unknown", line: task.line + 1, text: first, reason: `unknown task leg ${task.leg}` });
         if (parsed.lines.slice(task.line + (explicit ? 1 : 0), task.bodyEndLine).some(l => /^Leg:/.test(l))) findings.push({ check: "leg-unknown", line: task.line, text: task.text, reason: "Leg: must be the first line after the task heading" });
       }
-      if (findings.length) return findings;
+      if (findings.length) return { findings, parsed, ledger };
       for (const wave of parsed.waves) if (new Set(parsed.tasks.filter(t => t.waveNumber === wave.number).map(t => t.leg)).size > 1) findings.push({ check: "wave-leg", line: wave.line, text: wave.text, reason: "wave mixes task legs" });
     }
 
@@ -1343,16 +1346,33 @@ export function checkPlan(planText: string, specText: string, fs: FsPort): PlanC
     findings.push(...checkHeaderEntrypoint(parsed));
     findings.push(...checkHappyPathLine(parsed));
     findings.push(...checkWaiverLiteral(parsed));
-    return findings;
+    return { findings, parsed, ledger };
   } catch (err) {
     const message = String(err instanceof Error ? err.message : err);
-    return [
+    return { ledger, findings: [
       {
         check: "internal",
         line: 0,
         text: "",
         reason: message.split("\n")[0],
       },
-    ];
+    ] };
   }
 }
+
+export function renderManifest(parsed: ParsedPlan, planAbs: string, specAbs: string): string {
+  const kinds = { create: "Create", modify: "Modify", test: "Test" };
+  return [
+    `manifest: ${planAbs} | spec: ${specAbs} | tasks: ${parsed.tasks.length} | waves: ${parsed.waves.length}`,
+    ...parsed.tasks.map(task => JSON.stringify({
+      task: task.number,
+      wave: task.waveNumber,
+      ...(/\bin-place\b/.test(parsed.waves.find(wave => wave.number === task.waveNumber)?.label ?? "") ? { mode: "in-place" } : {}),
+      heading: task.text.replace(/^### Task \d+: /, ""),
+      files: task.files.map(file => ({ kind: kinds[file.kind], path: file.path })),
+      tests: task.tests.map(bullet => bullet.value),
+      ...(task.leg !== undefined ? { leg: task.leg } : {}),
+      ...(task.orchestrator !== undefined ? { orchestrator: task.orchestrator } : {}),
+    })),
+  ].join("\n");
+}

package/extensions/phase-tracker.test.ts

@@ -990,7 +990,12 @@ test("plan_check pass: text, details, and stamp arming when a flow is entered",
     content: { text: string }[];
     details: { status: string; planPath: string; planSha256: string; specPath: string; specSha256: string };
   };
-  assert.match(res.content[0].text, /^PASS/);
+  assert.match(res.content[0].text, /^PASS[^\n]*\n\nmanifest: /);
+  const manifestLines = res.content[0].text.split("\n").slice(2);
+  assert.equal(manifestLines[0], `manifest: ${planPath} | spec: ${specPath} | tasks: 2 | waves: 1`);
+  assert.deepEqual(manifestLines.slice(1).map(line => JSON.parse(line).task), [1, 2]);
+  const repeated = await tool.execute("repeat", { planPath }, undefined, undefined, h.ctx);
+  assert.deepEqual(repeated, res);
   assert.equal(res.details.status, "pass");
   assert.equal(res.details.planPath, planPath);
   assert.equal(res.details.specPath, specPath);
@@ -1043,7 +1048,7 @@ test("plan_check pass outside a flow: no stamp, plain-linter text", async () =>
   await h.emit("session_start");
   const tool = h.tools.find((t) => t.name === "plan_check")!;
   const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[] };
-  assert.match(res.content[0].text, /^PASS \(no flow to stamp\)/);
+  assert.match(res.content[0].text, /^PASS \(no flow to stamp\)\n\nmanifest: /);
 });
 
 test("plan_check fail: mutated plan body, no error key, clears stamp", async () => {
@@ -1059,6 +1064,7 @@ test("plan_check fail: mutated plan body, no error key, clears stamp", async ()
     details: { status: string; error?: string };
   };
   assert.match(res.content[0].text, /^FAIL/);
+  assert.ok(!res.content[0].text.includes("\nmanifest:"));
   assert.equal(res.details.status, "fail");
   assert.equal("error" in res.details, false);
 
@@ -1448,6 +1454,7 @@ test("ledger handler stamps after brainstorm and skipped plan, then admits imple
   await call("skip", "plan", "loop engine");
   const checked = await h.tools.find(t => t.name === "plan_check")!.execute("check", { planPath }, undefined, undefined, h.ctx) as any;
   assert.equal(checked.details.status, "pass");
+  assert.equal(checked.content[0].text, "PASS \u2014 plan verified and stamped for implement-start");
   assert.equal(checked.details.planSha256, sha256Hex(readFileSync(planPath)));
   const started = await call("start", "implement");
   assert.equal(started.details.error, undefined);
@@ -2649,3 +2656,54 @@ for (const pattern of [".worktrees/<name>", "../companion-<name>"]) test(`plan_c
   const missing = await tool.execute("legs-missing-root", { planPath }, undefined, undefined, h.ctx) as { details: { findings: { check: string }[] } };
   assert.ok(missing.details.findings.some(f => f.check === "input"));
 });
+
+for (const length of [32767, 32768, 32769]) {
+  test(`plan_check complete manifest JS length ${length} bounds stamping`, async () => {
+    const dir = gitPrimary().primary;
+    const { planPath, specPath } = writePlanFixture(dir);
+    const passLine = "PASS \u2014 plan verified and stamped for implement-start";
+    const prefix = `${passLine}\n\nmanifest: ${planPath} | spec: ${specPath} | tasks: 1 | waves: 1\n`;
+    const task = { task: 1, wave: 1, heading: "Docs", files: [{ kind: "Modify", path: "file-a.ts" }], tests: [], orchestrator: "é" };
+    task.orchestrator += "a".repeat(length - prefix.length - JSON.stringify(task).length);
+    const expected = prefix + JSON.stringify(task);
+    assert.equal(expected.length, length);
+    assert.ok(Buffer.byteLength(expected, "utf8") > length);
+    writeFileSync(planPath, `# Plan
+**Spec:** \`doc/specs/spec.md\`
+**Verification:** all-checks
+---
+## Wave 1 - Docs
+### Task 1: Docs
+Orchestrator: ${task.orchestrator}
+**Files:**
+- Modify: file-a.ts
+**Tests:**
+- none: docs
+## Spec coverage
+| anchor | requirement | owner |
+|---|---|---|
+| - | mechanical: docs | Task 1 |
+`);
+    const h = harness({ cwd: dir, branch: readyForImplementBranch });
+    await h.emit("session_start");
+    const tool = h.tools.find(t => t.name === "plan_check")!;
+    const result = await tool.execute("size", { planPath }, undefined, undefined, h.ctx) as {
+      content: { text: string }[]; details: { status: string; findings?: { check: string; line: number; reason: string }[] };
+    };
+    if (length < 32768) {
+      assert.equal(result.details.status, "pass");
+      assert.equal(result.content[0].text, expected);
+    } else {
+      assert.equal(result.details.status, "fail");
+      assert.equal(result.details.findings?.length, 1);
+      assert.equal(result.details.findings?.[0].check, "manifest-size");
+      assert.equal(result.details.findings?.[0].line, 0);
+      assert.equal(result.details.findings?.[0].reason, `manifest content is ${length} characters (limit 32,768); the plan is too large for the orchestrator's manifest - stop and ask the user to reduce it`);
+      assert.ok(!result.content[0].text.includes("\nmanifest:"));
+    }
+    const phase = h.tools.find(t => t.name === "phase_tracker")!;
+    const start = await phase.execute("start", { action: "start", phase: "implement" }, undefined, undefined, h.ctx) as { details: { error?: string; phases: { implement: { status: string } } } };
+    if (length < 32768) assert.equal(start.details.phases.implement.status, "in_progress");
+    else assert.match(start.details.error ?? "", /plan_check/);
+  });
+}

package/extensions/phase-tracker.ts

@@ -29,7 +29,7 @@ import {
 } from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
 import { checkoutOf, gitSync } from "./lib/checkout.ts";
-import { checkPlan, legOwnership, sha256, type FsPort, type PlanCheckFinding } from "./lib/plan-check.ts";
+import { checkPlan, renderManifest, legOwnership, sha256, type FsPort, type PlanCheckFinding } from "./lib/plan-check.ts";
 import {
   checkSubstep,
   dispatchLabel,
@@ -1054,8 +1054,14 @@ export default function (pi: ExtensionAPI) {
           exists: (p, leg) => existsSync(resolve(leg ? roots.get(leg)! : root, p)),
           glob: (pattern, leg) => globSync(pattern, { cwd: leg ? roots.get(leg)! : root }),
         };
-        const findings = checkPlan(planText, specText, port);
-        if (findings.length > 0) return fail(findings, planAbs);
+        const result = checkPlan(planText, specText, port);
+        if (result.findings.length > 0) return fail(result.findings, planAbs);
+        const passLine = gauntletEntered ? "PASS \u2014 plan verified and stamped for implement-start" : "PASS (no flow to stamp)";
+        const resultText = result.ledger ? passLine : `${passLine}\n\n${renderManifest(result.parsed!, planAbs, specAbs)}`;
+        if (resultText.length >= 32768) return fail([{
+          check: "manifest-size", line: 0, text: "",
+          reason: `manifest content is ${resultText.length} characters (limit 32,768); the plan is too large for the orchestrator's manifest - stop and ask the user to reduce it`,
+        }], planAbs);
 
         const planSha256 = sha256(planBytes);
         const specSha256 = sha256(specBytes);
@@ -1069,11 +1075,11 @@ export default function (pi: ExtensionAPI) {
         if (gauntletEntered) {
           planCheckStamp = { planPath: planAbs, planSha256, specPath: specAbs, specSha256 };
           return {
-            content: [{ type: "text" as const, text: "PASS \u2014 plan verified and stamped for implement-start" }],
+            content: [{ type: "text" as const, text: resultText }],
             details,
           };
         }
-        return { content: [{ type: "text" as const, text: "PASS (no flow to stamp)" }], details };
+        return { content: [{ type: "text" as const, text: resultText }], details };
       } catch (err) {
         return fail([{ check: "internal", line: 0, text: "", reason: String(err) }], planAbs);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "7.41.3",
+  "version": "7.42.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/reference/amendment-surface.md

@@ -1,6 +1,6 @@
 # Amendment surface
 
-`read` this file (the `read` tool at its absolute path, never a shell command) from `skills/brainstorming/SKILL.md` section Amending an approved spec, from any phase, for amend-class changes; at approval, load only [Standing grants](#standing-grants), not the batch procedure. Keep redraws outside this procedure. Classify a text correction to an approved drafted acceptance-criteria row backed by implementer evidence (a quoted test, assertion, or code line in a `BLOCKED`/`NEEDS_CONTEXT` return) as an amend item. Keep ticket rows, row add/remove, reviewer-only or taste objections, problem statement changes, and component boundary changes as redraws at batch preparation, before any standing grant: re-draft from the new design and ratify at the full gate. Keep a disposition-only change to such a row in this grammar so it keeps the cut question. Apply an item the human has answered by letter or custom text as recorded. Only the main loop holding `edit`/`write` authors amendments and human-facing amendment text. Use the human last: a fresh reviewer clears evidence-backed factual corrections; present the rest to the human once per batch plainly.
+`read` this file (the `read` tool at its absolute path, never a shell command) from `skills/brainstorming/SKILL.md` section Amending an approved spec, from any phase, for amend-class changes; at approval, load only [Standing grants](#standing-grants), not the batch procedure. Keep redraws outside this procedure. Classify a text correction to an approved drafted acceptance-criteria row backed by implementer evidence (a quoted test, assertion, or code line in a `BLOCKED`/`NEEDS_CONTEXT` return) as an amend item. Keep ticket rows, row add/remove, reviewer-only or taste objections, problem statement changes, and component boundary changes as redraws at batch preparation, before any standing grant: re-draft from the new design and ratify at the full gate. Keep a disposition-only change to such a row in this grammar so it keeps the cut question. Apply an item the human has answered by letter or custom text as recorded. Keep human-facing amendment text with the main loop holding `edit`/`write`; delegate implement-phase spec authorship only through the implement-only route below. Keep all other callers' authorship with the main loop. Use the human last: a fresh reviewer clears evidence-backed factual corrections; present the rest to the human once per batch plainly.
 
 ## Standing grants
 
@@ -40,6 +40,8 @@ When the spec file is mid-batch (uncommitted amend edits), the consent edit ride
 
 ## 1. Prepare - never apply yet
 
+**Implement callers only, with a task plan:** delegate preparation to `plan-writer` in a one-step chain with the ordinary five absolute paths, this surface's absolute path, and an implement-only `Amend-prepare:` block carrying evidence already in context (checker FAIL lines, structured `concerns`/`question`, or baseline rows). Consume `{ items: [{ evidence, recommended: "accept" | "alt-<n>", location: "<spec section>", edit: string }], redraws: [{ location: "<spec section>", reason: string (max 300 characters) }] }`; keep supporting context in the saved report. Require both `items` and `redraws` arrays, including when empty; redraw proposals appear only in `redraws`, never in `items`. Fail malformed preparation output. The child reads spec and plan, writes nothing, and bounds each proposed edit to one paragraph. Enforce the redraw gate: a nonempty `redraws` array holds the whole batch before grant evaluation or applying any sibling item. Hold amend siblings for re-batching after the redraw resolves; the primary never opens the preparation report to discover redraws. Run the standing-grant predicate and Value decoding unchanged; without amend permission, take sections 2-4 and stop for the human's answer. Forward only resolved, authorized items to the apply route in section 5. Planning callers keep the ordinary preparation below. For ledger-engine (`loop-implementation`) callers, prepare through the ordinary path below without a `plan-writer` dispatch.
+
 Collect every amendment pending at this decision point (same spec-review round, same blocked wave, same conformance inventory) into one batch. Never wait for more; a later finding is a new batch. For each item hold, unapplied:
 
 | Field | Content |
@@ -143,6 +145,8 @@ Reply grammar: one line per item, `<n>. <letter or free text>`; bare `1` applies
 
 Before the aftermath, `read` this section again; never run it from memory.
 
+**Implement callers only, with a task plan:** replace parent spec edits and the ordinary plan aftermath with a one-step chain to `plan-writer` carrying an implement-only `Amend-apply:` block, the granted items verbatim, the five absolute paths, and the parent's explicit `In-flight:` list. Authorize only those named spec sections. Require ordinary `Amend:` preservation of unaffected titles and wave positions, Baseline ownership, dirty-baseline safety, and the child's self-check. Consume `{ amendedSections: string[], tasksAdded: number[], tasksAnchorChanged: number[], tasksRemoved: number[], passed: boolean, failLines?: string[] }`; use pre-apply task numbers, never tracker positions. Require the child to capture the original task numbers, titles, spec anchors, and wave positions in the existing saved apply report before the first apply and retain that original inventory on every return, including failures; add no sidecar. On `passed: false`, repeat once with `failLines` as the rule and `previousApplyReport` set to the first apply report path. Require the fresh retry worker to read that original inventory, apply granted edits idempotently without duplicating already-applied edits, and compute deltas against that original inventory rather than the already-mutated plan. Missing original inventory fails the retry; send a second failure to the human with verbatim findings, including substantive baseline failures. Keep the attribution, protected-path, and dirty-baseline exits below; no delegated restoration permission is granted. On pass, print `amended the spec: <title> - <location>` for each applied item, run the parent's `plan_check` for stamping, and use its fresh manifest with the returned task numbers without reading the plan or spec. Add `tasksAdded`, reopen completed `tasksAnchorChanged` as `in_progress`, and handle `tasksRemoved` through the removal rules below. Require parent PASS before tracker changes. Skip the ordinary parent edit, `Amend:` dispatch, and amended-plan read; preserve companion aftermath, audit, and the single batch commit below. Planning callers keep the ordinary apply and aftermath below; ledger and no-plan routes stay unchanged.
+
 Apply accepted items only: reviewer clears, `accept`, `alt-n`, and state-changing `custom`. Print one line per applied item: `amended the spec: <title> - <what>`.
 
 Preserve scope indices on disposition-only amendments, including cuts; validate