@mjasnikovs/pi-task 0.31.0 → 0.32.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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.31.0",
+    "version": "0.32.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",