@mjasnikovs/pi-task 0.31.0 → 0.33.0

package/README.md

@@ -111,7 +111,9 @@ It works like the clarify step you already know — **one question at a time, ea
 
 When the model runs out of questions it says so and offers the same three moves rather than proceeding behind your back. Answering something new re-opens it: a decision you volunteer can make a fresh question worth asking.
 
-Everything lands in `.pi-tasks/TASK_PLAN_NNNN.md` — the task prompt, the `## decisions` transcript, and a separate `## notes` section for what you asked. Only the decisions are handed to `/task`, as an authoritative block ahead of your original prompt; the notes stay behind, because an answer you read is not a decision you made. From there it is an ordinary `/task` run — same pipeline, same gates.
+**Planning is read-only.** Nothing in your project is created, edited, or deleted while you plan — the planning model runs with a one-tool allowlist (`read`), which also excludes write tools contributed by any extension you have whitelisted for helper sessions. That is verified as well as prevented: the working tree is compared before and after every step, and if anything outside `.pi-tasks/` ever changes, the run says so loudly and records it in the plan file rather than carrying on quietly. Read-only ends the moment you choose **Proceed to execution** — from there it is a normal `/task` run and it writes code.
+
+The one thing written during planning is the plan file itself, `.pi-tasks/TASK_PLAN_NNNN.md` — the task prompt, the `## decisions` transcript, and a separate `## notes` section for what you asked (a session you abandon before deciding anything deletes its own file, so an aborted plan leaves nothing at all). Only the decisions are handed to `/task`, as an authoritative block ahead of your original prompt; the notes stay behind, because an answer you read is not a decision you made. From there it is an ordinary `/task` run — same pipeline, same gates.
 
 It works from the browser too (see [Remote](#remote--drive-a-task-from-your-phone)): the prompt card grows an **Ask the model** and a **Proceed to execution** button alongside the usual Accept / Manual answer.
 

package/dist/task/plan-orchestrator.d.ts

@@ -48,5 +48,20 @@ export interface PlanCommandDeps {
     /** Hand the composed prompt to /task. Returns the produced task id, if any. */
     handoff(ctx: ExtensionCommandContext, cwd: string, prompt: string): Promise<string | undefined>;
 }
+/**
+ * Remove the plan file (and its debug log) when the session ended with nothing
+ * in it — the user opened /task-plan and backed out at the first question.
+ *
+ * The file is allocated up front so a crash mid-session still leaves the record,
+ * which means an abandoned session would otherwise leave a stub whose whole
+ * content is "(none yet)". That is exactly the artifact this command is not
+ * supposed to produce.
+ *
+ * It refuses to delete anything that carries a read-only violation: that section
+ * is the report of a file we could not account for, and it must outlive the
+ * session that found it. Best-effort — a failure here leaves the stub, which is
+ * harmless.
+ */
+export declare function discardEmptyPlanFile(cwd: string, planId: string): Promise<void>;
 export declare function handleTaskPlan(args: string, ctx: ExtensionCommandContext, commandDeps?: PlanCommandDeps): Promise<void>;
 export declare function registerTaskPlan(pi: ExtensionAPI): void;

package/dist/task/plan-orchestrator.js

@@ -24,7 +24,10 @@ import { runPhaseChild, prependHint, USER_CANCELLED } from './child-runner.js';
 import { PLAN_QUESTION_PROMPT, PLAN_ANSWER_PROMPT } from './plan-prompts.js';
 import { runPlanSession, ASK_TITLE } from './plan-session.js';
 import { allocatePlanId, buildPlanBody, buildHandoffPrompt, formatPlanDecisions } from './plan-io.js';
-import { writeTaskFile, setTaskSection, updateTaskFrontMatter, tasksDir } from './task-io.js';
+import { writeTaskFile, readTaskFile, setTaskSection, readSection, updateTaskFrontMatter, taskFilePath, tasksDir } from './task-io.js';
+import { extractSection } from './task-parsers.js';
+import { collectTreeChanges } from './gate-deps.js';
+import { PLAN_TOOLS, newTreeChanges, isEmptyChange, formatReadOnlyViolation } from './plan-readonly.js';
 import { deriveTitle } from './parsers.js';
 import { renderInlineMarkdown } from './inline-markdown.js';
 import { expandFeatureMentions } from './auto-orchestrator.js';
@@ -70,7 +73,14 @@ export function buildPlanDeps(ctx, cwd, planId, task, signal) {
         },
         ...(logDebug && { logDebug })
     };
-    /** Run a planning child under the shared /task-auto-style loader. */
+    /**
+     * Run a planning child under the shared /task-auto-style loader, with the
+     * read-only contract enforced around it: the child gets exactly
+     * {@link PLAN_TOOLS}, and the working tree is compared before and after so a
+     * hole in that prevention is reported instead of shipped silently. The
+     * comparison excludes `.pi-tasks/` (collectTreeChanges does), which is where
+     * the plan file itself is written.
+     */
     const child = async (name, prompt) => {
         lastLine = undefined;
         contextUsage = undefined;
@@ -85,11 +95,21 @@ export function buildPlanDeps(ctx, cwd, planId, task, signal) {
             lastLine,
             contextUsage
         }));
+        const before = await collectTreeChanges(cwd, signal).catch(() => null);
         try {
-            return await runPhaseChild(phaseDeps, name, 'read', prompt);
+            return await runPhaseChild(phaseDeps, name, PLAN_TOOLS, prompt);
         }
         finally {
             stopLoader();
+            // Outside a git repo `before` is null and there is nothing to compare
+            // against — the same degrade every other tree-reading guard here takes.
+            if (before) {
+                const after = await collectTreeChanges(cwd, signal).catch(() => null);
+                const touched = after ? newTreeChanges(before, after) : null;
+                if (touched && !isEmptyChange(touched)) {
+                    await reportReadOnlyViolation(ctx, cwd, planId, name, touched, logDebug);
+                }
+            }
         }
     };
     return {
@@ -120,6 +140,32 @@ export function buildPlanDeps(ctx, cwd, planId, task, signal) {
         ...(logDebug && { logDebug })
     };
 }
+/**
+ * A planning step touched the project: say so on every surface and write it into
+ * the plan file, which is the one record that outlives the session.
+ *
+ * Deliberately NOT a rollback. If this ever fires, something wrote a file we
+ * cannot account for; deleting it unseen would turn a reporting bug into data
+ * loss. The user gets the path and decides.
+ */
+async function reportReadOnlyViolation(ctx, cwd, planId, step, touched, logDebug) {
+    const line = formatReadOnlyViolation(step, touched);
+    logDebug?.(line);
+    try {
+        ctx.ui.notify(line, 'error');
+    }
+    catch {
+        /* stale ctx — the record below is what matters */
+    }
+    publishLifecycleNotice(line, 'error');
+    try {
+        const existing = (await readSection(cwd, planId, 'read-only violations')) ?? '';
+        await setTaskSection(cwd, planId, 'read-only violations', existing ? `${existing}\n- ${line}` : `- ${line}`);
+    }
+    catch {
+        /* best-effort */
+    }
+}
 /**
  * Write the transcript into the plan file. The decisions and the model's answers
  * to the user's questions live in separate sections: only the decisions are
@@ -161,6 +207,37 @@ const DEFAULT_COMMAND_DEPS = {
     run: runPlanSession,
     handoff: defaultHandoff
 };
+/**
+ * Remove the plan file (and its debug log) when the session ended with nothing
+ * in it — the user opened /task-plan and backed out at the first question.
+ *
+ * The file is allocated up front so a crash mid-session still leaves the record,
+ * which means an abandoned session would otherwise leave a stub whose whole
+ * content is "(none yet)". That is exactly the artifact this command is not
+ * supposed to produce.
+ *
+ * It refuses to delete anything that carries a read-only violation: that section
+ * is the report of a file we could not account for, and it must outlive the
+ * session that found it. Best-effort — a failure here leaves the stub, which is
+ * harmless.
+ */
+export async function discardEmptyPlanFile(cwd, planId) {
+    try {
+        const { body } = await readTaskFile(cwd, planId);
+        if (extractSection(body, 'read-only violations') !== null)
+            return;
+        const decisions = extractSection(body, 'decisions');
+        if (decisions !== null && decisions.trim() !== '(none yet)')
+            return;
+        if (extractSection(body, 'notes') !== null)
+            return;
+        await fsp.rm(taskFilePath(cwd, planId), { force: true });
+        await fsp.rm(path.join(tasksDir(cwd), `${planId}-debug.log`), { force: true });
+    }
+    catch {
+        /* best-effort: an unreadable file is left exactly where it is */
+    }
+}
 export async function handleTaskPlan(args, ctx, commandDeps = DEFAULT_COMMAND_DEPS) {
     await ctx.waitForIdle();
     const cwd = ctx.cwd;
@@ -204,9 +281,11 @@ export async function handleTaskPlan(args, ctx, commandDeps = DEFAULT_COMMAND_DE
         return;
     }
     if (outcome.kind === 'cancelled') {
-        // Nothing is handed to /task, but whatever WAS decided stays on disk —
-        // a cancelled plan is a record, not a rollback.
+        // Whatever WAS decided stays on disk — a cancelled plan is a record, not
+        // a rollback. A session that decided NOTHING leaves nothing at all.
         await updateTaskFrontMatter(cwd, planId, { state: 'cancelled' }).catch(() => { });
+        if (outcome.entries.length === 0)
+            await discardEmptyPlanFile(cwd, planId);
         const line = outcome.entries.length === 0 ?
             `${planId} cancelled — nothing planned.`
             : `${planId} cancelled — ${outcome.entries.length} entr${outcome.entries.length === 1 ? 'y' : 'ies'} kept in .pi-tasks/${planId}.md`;

package/dist/task/plan-readonly.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The read-only contract for /task-plan.
+ *
+ * Planning happens BEFORE the work is agreed, so a plan session must leave the
+ * project exactly as it found it: no file created, edited, or deleted. Nothing is
+ * built yet, so any artifact a plan produced would be an artifact nobody approved
+ * — and it would sit in the tree looking like part of the change the user is
+ * still deciding whether to make.
+ *
+ * Two layers, because one of them is somebody else's flag:
+ *
+ *   PREVENTION — the planning children run with {@link PLAN_TOOLS}, an allowlist
+ *   of exactly one tool. pi applies `--tools` to built-in, extension AND custom
+ *   tools, so a write tool contributed by a whitelisted extension is excluded too
+ *   (proven live — scripts/live-task-plan-readonly.ts). This is what actually
+ *   makes the session read-only.
+ *
+ *   VERIFICATION — after every child, the working tree is compared against the
+ *   snapshot taken before it. `.pi-tasks/` is excluded (that is where the plan
+ *   file itself lives — see collectTreeChanges), so what remains is precisely
+ *   "did planning touch the project". If it ever fires, prevention has a hole:
+ *   it is reported loudly and recorded in the plan file rather than silently
+ *   tolerated. It never deletes anything — an unexplained file is a thing to show
+ *   the user, not a thing to quietly destroy.
+ */
+import type { TreeChangeSummary } from './write-guard.js';
+/**
+ * The tool allowlist every /task-plan child runs under. One tool: `read`.
+ *
+ * Deliberately a named constant with a test pinning it (plan-readonly.test.ts):
+ * widening this string is the single edit that would end the read-only guarantee,
+ * and it should never happen by accident. The same value grill and clarify use
+ * for their generation children — planning has never needed more.
+ */
+export declare const PLAN_TOOLS = "read";
+/**
+ * What appeared in `after` that was not already in `before`.
+ *
+ * A set difference, not an emptiness check: /task-plan runs against whatever the
+ * user already has in progress, and a tree that was dirty when planning started
+ * is normal — only what planning ADDED is a violation.
+ */
+export declare function newTreeChanges(before: TreeChangeSummary, after: TreeChangeSummary): TreeChangeSummary;
+/** True when the summary names nothing at all. */
+export declare function isEmptyChange(c: TreeChangeSummary): boolean;
+/** One line naming what a planning step touched, for the notify and the record. */
+export declare function formatReadOnlyViolation(step: string, c: TreeChangeSummary): string;

package/dist/task/plan-readonly.js

@@ -0,0 +1,67 @@
+/**
+ * The read-only contract for /task-plan.
+ *
+ * Planning happens BEFORE the work is agreed, so a plan session must leave the
+ * project exactly as it found it: no file created, edited, or deleted. Nothing is
+ * built yet, so any artifact a plan produced would be an artifact nobody approved
+ * — and it would sit in the tree looking like part of the change the user is
+ * still deciding whether to make.
+ *
+ * Two layers, because one of them is somebody else's flag:
+ *
+ *   PREVENTION — the planning children run with {@link PLAN_TOOLS}, an allowlist
+ *   of exactly one tool. pi applies `--tools` to built-in, extension AND custom
+ *   tools, so a write tool contributed by a whitelisted extension is excluded too
+ *   (proven live — scripts/live-task-plan-readonly.ts). This is what actually
+ *   makes the session read-only.
+ *
+ *   VERIFICATION — after every child, the working tree is compared against the
+ *   snapshot taken before it. `.pi-tasks/` is excluded (that is where the plan
+ *   file itself lives — see collectTreeChanges), so what remains is precisely
+ *   "did planning touch the project". If it ever fires, prevention has a hole:
+ *   it is reported loudly and recorded in the plan file rather than silently
+ *   tolerated. It never deletes anything — an unexplained file is a thing to show
+ *   the user, not a thing to quietly destroy.
+ */
+/**
+ * The tool allowlist every /task-plan child runs under. One tool: `read`.
+ *
+ * Deliberately a named constant with a test pinning it (plan-readonly.test.ts):
+ * widening this string is the single edit that would end the read-only guarantee,
+ * and it should never happen by accident. The same value grill and clarify use
+ * for their generation children — planning has never needed more.
+ */
+export const PLAN_TOOLS = 'read';
+/**
+ * What appeared in `after` that was not already in `before`.
+ *
+ * A set difference, not an emptiness check: /task-plan runs against whatever the
+ * user already has in progress, and a tree that was dirty when planning started
+ * is normal — only what planning ADDED is a violation.
+ */
+export function newTreeChanges(before, after) {
+    const diff = (a, b) => {
+        const seen = new Set(b);
+        return a.filter(p => !seen.has(p));
+    };
+    return {
+        modified: diff(after.modified, before.modified),
+        added: diff(after.added, before.added),
+        deleted: diff(after.deleted, before.deleted)
+    };
+}
+/** True when the summary names nothing at all. */
+export function isEmptyChange(c) {
+    return c.modified.length + c.added.length + c.deleted.length === 0;
+}
+/** One line naming what a planning step touched, for the notify and the record. */
+export function formatReadOnlyViolation(step, c) {
+    const parts = [];
+    if (c.added.length > 0)
+        parts.push(`created ${c.added.join(', ')}`);
+    if (c.modified.length > 0)
+        parts.push(`modified ${c.modified.join(', ')}`);
+    if (c.deleted.length > 0)
+        parts.push(`deleted ${c.deleted.join(', ')}`);
+    return `/task-plan is read-only, but the ${step} step ${parts.join('; ')}`;
+}

package/dist/task/task-gates.d.ts

@@ -285,6 +285,29 @@ export type GateResult = {
  * regardless of this count (blessing an artifact as-is is a human's call).
  */
 export declare const MAX_AUTO_AUTOFIX = 3;
+/** Which of the four disjoint branches sent a FAIL to the terminal YOLO ACCEPT. */
+export interface YoloAcceptContext {
+    /** Rule 5c: the spec-required check could not run (tooling absent). */
+    isUnobserved: boolean;
+    /** Cross-task contradiction: the repo-health fix needs a spec-frozen path. */
+    isFrozenBlocked: boolean;
+    /** What the resolution research recommended, when it was consulted at all. */
+    recommend: ResolutionOutcome['recommend'];
+    /** Unattended AUTOFIX attempts already spent on this task. */
+    autoFixCount: number;
+}
+/**
+ * The reason an auto-ACCEPT is being written — NAMED, not assumed.
+ *
+ * The line this replaces asserted "autofix budget spent" on every branch. It was
+ * measured false in 2709 of 2709 recorded accepts (scripts/yolo-accept-baserate.ts):
+ * the budget has never once reached MAX_AUTO_AUTOFIX anywhere in the corpus — 30%
+ * of accepts are UNOBSERVED (the research is never even consulted) and 70% are an
+ * ACCEPT recommendation with the budget fully untouched. A durable trail that
+ * misstates why a defect shipped is worse than no trail: mx5 run 19's TASK_0009
+ * reads as an exhausted fixer when nothing was ever attempted.
+ */
+export declare function yoloAcceptReason(c: YoloAcceptContext): string;
 /**
  * Show the boxed two-choice picker after a verify FAIL and return what the user
  * decided. The model-recommended card is placed first so the renderer tints it

package/dist/task/task-gates.js

@@ -13,6 +13,29 @@ import { attributeEnforceFailure } from './enforce-attribution.js';
  * regardless of this count (blessing an artifact as-is is a human's call).
  */
 export const MAX_AUTO_AUTOFIX = 3;
+/**
+ * The reason an auto-ACCEPT is being written — NAMED, not assumed.
+ *
+ * The line this replaces asserted "autofix budget spent" on every branch. It was
+ * measured false in 2709 of 2709 recorded accepts (scripts/yolo-accept-baserate.ts):
+ * the budget has never once reached MAX_AUTO_AUTOFIX anywhere in the corpus — 30%
+ * of accepts are UNOBSERVED (the research is never even consulted) and 70% are an
+ * ACCEPT recommendation with the budget fully untouched. A durable trail that
+ * misstates why a defect shipped is worse than no trail: mx5 run 19's TASK_0009
+ * reads as an exhausted fixer when nothing was ever attempted.
+ */
+export function yoloAcceptReason(c) {
+    if (c.isUnobserved)
+        return 'verify UNOBSERVED — tooling absent, an unattended re-run cannot provision it';
+    if (c.isFrozenBlocked)
+        return 'repo-health blocked by a spec-frozen path — an impl re-run under the same freeze cannot converge';
+    if (c.recommend === 'autofix') {
+        return `autofix budget spent (${c.autoFixCount}/${MAX_AUTO_AUTOFIX})`;
+    }
+    return c.autoFixCount === 0 ?
+        `judge recommended ACCEPT (autofix budget 0/${MAX_AUTO_AUTOFIX} unused)`
+        : `judge recommended ACCEPT (autofix budget ${c.autoFixCount}/${MAX_AUTO_AUTOFIX} already spent)`;
+}
 /**
  * Bound a captured health-check output before it is embedded in a gate-trail line.
  * appendGateRecord flattens newlines to spaces, so the trail stays one line per
@@ -134,6 +157,8 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // defect is recorded as a durable debt for the final gate.
         let frozenContradiction = null;
         let frozenDebtRecorded = false;
+        // YOLO only: has the one-attempt rescue below already been spent on this task?
+        let yoloRescueUsed = false;
         while (!verified.ok) {
             const failReason = verified.reason ?? 'did not verify';
             // GRADUATED resolution: a repo-health FAIL (pure static findings) gets ONE
@@ -213,23 +238,54 @@ export async function runGatesForTask(ctxIn, deps, p) {
             const autoFixNow = !isUnobserved
                 && !isFrozenBlocked
                 && recOutcome.recommend === 'autofix'
-                && autoFixCount < MAX_AUTO_AUTOFIX;
-            // YOLO: the picker is unreachable with nobody watching, and by the time
-            // we are here the unattended AUTOFIX budget is ALREADY spent (autoFixNow
-            // is false) — so the only option left that terminates is ACCEPT, recorded
-            // as its own 'yolo-accepted' debt. Deliberately NOT a re-entry into
-            // autofix: MAX_AUTO_AUTOFIX exists to break a non-converging loop, and an
+                && autoFixCount < MAX_AUTO_AUTOFIX
+                // A rescue attempt that still FAILed is terminal under YOLO: the
+                // recommendation that got us here was ACCEPT, so a later flip to
+                // AUTOFIX must not bootstrap the full budget from it.
+                && !yoloRescueUsed;
+            // YOLO, THE RESCUE BRANCH: the recommendation is ACCEPT, nobody can be
+            // asked, and the unattended budget is UNTOUCHED. Accepting here ships a
+            // defect having attempted nothing — mx5 run 19 did exactly that twice,
+            // and the final-gate autofix later fixed one of the two in a single pass
+            // (`0 pass 130 fail` → `121 pass 0 fail`). So spend ONE attempt first.
+            // Bounded by construction: one, not MAX_AUTO_AUTOFIX, so an ACCEPT
+            // recommendation can never restart a full loop; if it still FAILs the
+            // next turn falls through to the same auto-ACCEPT and the same debt.
+            const yoloRescueNow = isYoloMode()
+                && !yoloRescueUsed
+                && !isUnobserved
+                && !isFrozenBlocked
+                && recOutcome.recommend === 'accept'
+                && autoFixCount === 0;
+            // YOLO: the picker is unreachable with nobody watching, and every
+            // unattended attempt this task may make has been made — so the only
+            // option left that terminates is ACCEPT, recorded as its own
+            // 'yolo-accepted' debt. Deliberately NOT a re-entry into autofix:
+            // MAX_AUTO_AUTOFIX exists to break a non-converging loop, and an
             // auto-pick here would restart the budget from the site that proves it ran out.
-            const yoloChoice = autoFixNow ? null : yoloVerifyResolution(isYoloMode());
+            const yoloChoice = autoFixNow || yoloRescueNow ? null : yoloVerifyResolution(isYoloMode());
             let choice;
             if (yoloChoice !== null) {
                 choice = yoloChoice;
-                await rec(`resolution: auto-ACCEPTED despite verify FAIL — autofix budget spent, nobody to ask ${YOLO_STAMP}`);
+                // NAME the branch. This line is the durable record of why a defect
+                // shipped; asserting a spent budget on all four branches made run
+                // 19's zero-attempt accepts read as an exhausted fixer.
+                await rec(`resolution: auto-ACCEPTED despite verify FAIL — ${yoloAcceptReason({
+                    isUnobserved,
+                    isFrozenBlocked,
+                    recommend: recOutcome.recommend,
+                    autoFixCount
+                })}, nobody to ask ${YOLO_STAMP}`);
             }
-            else if (autoFixNow) {
+            else if (autoFixNow || yoloRescueNow) {
                 autoFixCount += 1;
-                await rec(`resolution: auto-AUTOFIX (recommended, unattended ${autoFixCount}/${MAX_AUTO_AUTOFIX})`);
-                active.ui.notify(`${p.tag}: verify FAIL on "${p.title}" — auto-fixing (recommended, ${autoFixCount}/${MAX_AUTO_AUTOFIX})…`, 'info');
+                if (yoloRescueNow)
+                    yoloRescueUsed = true;
+                await rec(yoloRescueNow ?
+                    `resolution: auto-AUTOFIX (${YOLO_STAMP} rescue — judge recommended ACCEPT with the unattended `
+                        + `budget unspent; one attempt, ${autoFixCount}/${MAX_AUTO_AUTOFIX})`
+                    : `resolution: auto-AUTOFIX (recommended, unattended ${autoFixCount}/${MAX_AUTO_AUTOFIX})`);
+                active.ui.notify(`${p.tag}: verify FAIL on "${p.title}" — auto-fixing (${yoloRescueNow ? `${YOLO_STAMP} one attempt before accepting` : 'recommended'}, ${autoFixCount}/${MAX_AUTO_AUTOFIX})…`, 'info');
                 choice = { action: 'autofix' };
             }
             else {
@@ -292,7 +348,13 @@ export async function runGatesForTask(ctxIn, deps, p) {
             // hand that diagnosis to the re-run so it fixes the located cause
             // instead of re-deriving it from the bare FAIL line. Skipped when there
             // is no researched rationale beyond the failure text itself.
-            await rec('resolution: user chose AUTOFIX — re-running the implementation turn');
+            // Only the picker branch may claim a person chose this: the two
+            // unattended branches already recorded themselves one line above, and a
+            // trail that says "user chose" when nobody was asked is the same lie the
+            // accept line used to tell.
+            if (!autoFixNow && !yoloRescueNow) {
+                await rec('resolution: user chose AUTOFIX — re-running the implementation turn');
+            }
             active.ui.notify(`${p.tag}: autofixing "${p.title}"…`, 'info');
             const diagnosis = (recOutcome.recommend === 'autofix'
                 && recOutcome.rationale.length > 0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.31.0",
+    "version": "0.33.0",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",