@mjasnikovs/pi-task 0.16.5 → 0.17.1

package/dist/task/auto-prompts.js

@@ -9,19 +9,16 @@
  * when no clarification remains. priorQA carries the questions already answered so
  * each next question adapts to them.
  */
-export const AUTO_CLARIFY_PROMPT = (feature, priorQA, projectState = '') => `You are planning how to split a feature into separate implementation tasks, one clarifying question at a time.
+export const AUTO_CLARIFY_PROMPT = (feature, priorQA) => `You are planning how to split a feature into separate implementation tasks, one clarifying question at a time.
 
 FEATURE REQUEST:
 ${feature.trim()}
 
 ANSWERS SO FAR:
 ${priorQA.trim() || '(none yet)'}
-${projectState.trim() ? `\n${projectState.trim()}\n` : ''}
+
 You may use the read tool to inspect the repo and any referenced docs so your
-question and recommendation are grounded in what already exists. When a PROJECT
-STATE snapshot is given above, trust it: never assume an empty or greenfield
-project, never invent directory paths, and never recommend creating files it
-already lists — at most propose updating them.
+question and recommendation are grounded in what already exists.
 
 Output the SINGLE most important clarifying question that REMAINS — the one whose
 answer would most change HOW this feature is split into tasks (scope boundaries,

package/dist/task/file-inventory.d.ts

@@ -17,19 +17,3 @@ export declare function stripTasksDir(raw: string): string;
 /** Cap output to maxLines real (non-blank) paths; tag truncation when cut. */
 export declare function capInventory(raw: string, maxLines?: number): string;
 export declare function getFileInventory(cwd: string, signal?: AbortSignal, maxLines?: number): Promise<string>;
-/**
- * Derive a compact PROJECT STATE block (root-level files + top-level directories)
- * from a raw `git ls-files` listing. Pure/testable; `getProjectSnapshot` wires it
- * to the live repo. Returns '' when there is nothing tracked so the caller omits
- * the block entirely (and the model is then correctly free to treat the target as
- * an empty/greenfield project).
- */
-export declare function formatProjectSnapshot(raw: string): string;
-/**
- * Live PROJECT STATE snapshot for the planning phase. Clarify otherwise only
- * "may" read the repo; a weak model that skips the read then assumes a greenfield
- * project and recommends creating package.json/tsconfig from scratch — or invents
- * a path like /workspace — even when those configs already exist on disk. Handing
- * it the facts up front removes the guess. Empty (non-git / nothing tracked) ⇒ ''.
- */
-export declare function getProjectSnapshot(cwd: string, signal?: AbortSignal): Promise<string>;

package/dist/task/file-inventory.js

@@ -59,40 +59,3 @@ export async function getFileInventory(cwd, signal, maxLines = DEFAULT_MAX_LINES
         return '';
     return capInventory(stripTasksDir(raw), maxLines);
 }
-/**
- * Derive a compact PROJECT STATE block (root-level files + top-level directories)
- * from a raw `git ls-files` listing. Pure/testable; `getProjectSnapshot` wires it
- * to the live repo. Returns '' when there is nothing tracked so the caller omits
- * the block entirely (and the model is then correctly free to treat the target as
- * an empty/greenfield project).
- */
-export function formatProjectSnapshot(raw) {
-    const lines = stripTasksDir(raw)
-        .split('\n')
-        .map(l => l.trim())
-        .filter(l => l.length > 0);
-    const rootFiles = [...new Set(lines.filter(l => !l.includes('/')))].sort();
-    const dirs = [...new Set(lines.filter(l => l.includes('/')).map(l => l.split('/')[0]))].sort();
-    if (rootFiles.length === 0 && dirs.length === 0)
-        return '';
-    return ('EXISTING PROJECT STATE (a factual snapshot of the target directory — trust it over '
-        + 'assumptions: do NOT assume an empty or greenfield project, do NOT invent directory '
-        + 'paths, and do NOT propose creating files that already exist. Treat the config/manifest '
-        + "files listed here as the project's established setup unless the request explicitly says "
-        + 'to replace them):\n'
-        + `Root files: ${rootFiles.join(', ') || '(none)'}\n`
-        + `Top-level directories: ${dirs.join(', ') || '(none)'}`);
-}
-/**
- * Live PROJECT STATE snapshot for the planning phase. Clarify otherwise only
- * "may" read the repo; a weak model that skips the read then assumes a greenfield
- * project and recommends creating package.json/tsconfig from scratch — or invents
- * a path like /workspace — even when those configs already exist on disk. Handing
- * it the facts up front removes the guess. Empty (non-git / nothing tracked) ⇒ ''.
- */
-export async function getProjectSnapshot(cwd, signal) {
-    const raw = await runGitLsFiles(cwd, signal);
-    if (!raw)
-        return '';
-    return formatProjectSnapshot(raw);
-}

package/dist/task/gate-deps.d.ts

@@ -0,0 +1,16 @@
+import type { GateDeps } from './task-gates.js';
+/** A function that re-runs a task's implementation turn (AUTOFIX). Injected by the
+ *  command so this module stays free of the orchestrators (avoids an import cycle). */
+export type RunTaskFn = GateDeps['runTask'];
+/**
+ * Build the gate deps for one command run. `runTask` is the orchestrator's
+ * implementation re-runner, injected by the caller. The returned object also drives
+ * a shared status widget: `getLastLine`/`getContextUsage` expose the children's
+ * latest stream line and context usage so the caller can mirror them in its own
+ * loader if it wants (the gate closures already render their own loaders).
+ */
+export declare function buildGateDeps(params: {
+    signal: AbortSignal;
+    parentContextWindow: number;
+    runTask: RunTaskFn;
+}): GateDeps;

package/dist/task/gate-deps.js

@@ -0,0 +1,221 @@
+/**
+ * gate-deps — builds the concrete {@link GateDeps} (verify / enforce / recommend /
+ * commit / revert) that the post-implementation gate sequence drives.
+ *
+ * Lifted out of /task-auto's `defaultDeps` so both /task-auto and the single /task
+ * command construct the gate children identically. `runTask` (the AUTOFIX re-run) is
+ * INJECTED rather than imported, so this module never imports the orchestrators —
+ * keeping the dependency graph acyclic (the orchestrators import this).
+ *
+ * The gate children — verify, the post-FAIL recommend, and enforce — are read-only
+ * (or read,edit for enforce) passes of the same local model that must run to
+ * completion: unguarded (no wall-clock timeout, exact-match loop guard only,
+ * path-revisit disabled because re-running the same check IS the job), each with a
+ * status widget and a per-gate debug log under .pi-tasks/.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tasksDir, readTaskFile } from './task-io.js';
+import { gitCommitAll, gitDropLastCommit } from './auto-commit.js';
+import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
+import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
+import { researchResolution } from './verify-resolution.js';
+import { runWorker } from '../workers/pi-worker-core.js';
+import { formatLoopHint } from './child-runner.js';
+import { getConfig } from '../config/config.js';
+import { startAutoLoader } from './widget.js';
+import { resolveContextUsage } from './context-usage.js';
+/**
+ * Build the gate deps for one command run. `runTask` is the orchestrator's
+ * implementation re-runner, injected by the caller. The returned object also drives
+ * a shared status widget: `getLastLine`/`getContextUsage` expose the children's
+ * latest stream line and context usage so the caller can mirror them in its own
+ * loader if it wants (the gate closures already render their own loaders).
+ */
+export function buildGateDeps(params) {
+    const { signal, parentContextWindow, runTask } = params;
+    // Captured by each gate child's loader so the widget mirrors the child's latest
+    // output line and context usage, exactly like the single-task phase widget.
+    let lastLine;
+    let contextUsage;
+    // Shared runner for the per-task GATE children (verify + post-FAIL recommend).
+    // Both are read-only passes of the same local model that must run to completion:
+    // unguarded (no wall-clock timeout, exact-match loop guard only, path-revisit
+    // disabled because re-running the same check is the job), with a status widget
+    // and a per-gate debug log. Returns the closure runWorkVerification /
+    // researchResolution expect as `runChild`.
+    const makeGateChild = (gateCtx, cwd2, taskTitle, kind, logFile) => async (tools, prompt, sig) => {
+        lastLine = undefined;
+        contextUsage = undefined;
+        const startedAt = Date.now();
+        const logPath = path.join(tasksDir(cwd2), logFile);
+        const log = (msg) => {
+            void fsp.appendFile(logPath, `${new Date().toISOString()} ${msg}\n`).catch(() => { });
+        };
+        log(`=== ${kind} start: ${taskTitle} ===`);
+        const stopLoader = startAutoLoader(gateCtx, () => ({
+            title: taskTitle,
+            kind,
+            step: kind,
+            stepNum: 1,
+            stepTotal: 1,
+            startedAt,
+            lastLine,
+            contextUsage
+        }));
+        try {
+            const r = await runWorker({
+                prompt,
+                cwd: cwd2,
+                signal: sig,
+                tools,
+                timeoutMs: 0,
+                loop: { pathThreshold: Number.POSITIVE_INFINITY },
+                onLine: line => {
+                    lastLine = line;
+                    log(line);
+                },
+                onContextUsage: snapshot => {
+                    contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
+                }
+            });
+            if (r.loopHit) {
+                log(`=== ${kind} LOOP WARNING — ${formatLoopHint(r.loopHit)} ===`);
+                gateCtx.ui.notify(`${taskTitle}: ${kind} worker looped past the nudges — continuing (not blocked).`, 'warning');
+            }
+            const failure = classifyEnforceChildFailure(r);
+            log(failure ? `=== ${kind} end: FAIL — ${failure} ===` : `=== ${kind} end: ok ===`);
+            if (failure)
+                throw new Error(failure);
+            return r.text;
+        }
+        finally {
+            stopLoader();
+        }
+    };
+    return {
+        runTask,
+        commit: (cwd2, message) => getConfig().autoCommit ?
+            gitCommitAll(cwd2, message, signal)
+            : Promise.resolve({ committed: false, reason: 'auto-commit disabled' }),
+        revert: cwd2 => gitDropLastCommit(cwd2, signal),
+        enforce: (enforceCtx, cwd2, taskTitle, mode) => {
+            if (!getConfig().enforceGuidelines) {
+                return Promise.resolve({ ok: true, reason: 'disabled' });
+            }
+            return runGuidelineEnforcement({
+                cwd: cwd2,
+                signal,
+                mode,
+                // Run the worker child UNGUARDED: no loop detector, no wall-clock
+                // timeout. This pass reworks files in place until every violation is
+                // fixed and legitimately reads/edits the same file many times — the
+                // research-worker guards mislabel that as a runaway and kill good work
+                // (proven on mx5 TASK_0002). classifyEnforceChildFailure still blocks
+                // on a real failure (non-zero exit, leaked tool call) or a user cancel.
+                runChild: async (tools, prompt, sig) => {
+                    lastLine = undefined;
+                    contextUsage = undefined;
+                    const startedAt = Date.now();
+                    // Per-pass debug log; the enforce child is otherwise unobservable.
+                    const enforceLogPath = path.join(tasksDir(cwd2), 'enforce-debug.log');
+                    const logEnforce = (msg) => {
+                        void fsp
+                            .appendFile(enforceLogPath, `${new Date().toISOString()} ${msg}\n`)
+                            .catch(() => { });
+                    };
+                    logEnforce(`=== enforce start: ${taskTitle} ===`);
+                    const stopLoader = startAutoLoader(enforceCtx, () => ({
+                        title: taskTitle,
+                        kind: 'enforce',
+                        step: 'guidelines',
+                        stepNum: 1,
+                        stepTotal: 1,
+                        startedAt,
+                        lastLine,
+                        contextUsage
+                    }));
+                    try {
+                        const r = await runWorker({
+                            prompt,
+                            cwd: cwd2,
+                            signal: sig,
+                            tools,
+                            timeoutMs: 0, // no wall-clock timeout — run to completion
+                            // Exact-match loop guard only: pathThreshold Infinity
+                            // disables the path-revisit heuristic, so revisiting one
+                            // file (which IS this pass's job) never trips — only a
+                            // literally-identical call repeated past threshold does.
+                            loop: { pathThreshold: Number.POSITIVE_INFINITY },
+                            onLine: line => {
+                                lastLine = line;
+                                logEnforce(line);
+                            },
+                            onContextUsage: snapshot => {
+                                contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
+                            }
+                        });
+                        // A loop that survived the restart-with-hint nudges is a
+                        // warning, not a failure: log it and tell the user, but let the
+                        // verdict gate be the only thing that can block.
+                        if (r.loopHit) {
+                            logEnforce(`=== enforce LOOP WARNING — ${formatLoopHint(r.loopHit)} ===`);
+                            enforceCtx.ui.notify(`${taskTitle}: enforce worker looped past the nudges — continuing (not blocked).`, 'warning');
+                        }
+                        const failure = classifyEnforceChildFailure(r);
+                        logEnforce(failure ?
+                            `=== enforce end: FAIL — ${failure} ===`
+                            : '=== enforce end: verdict captured ===');
+                        if (failure)
+                            throw new Error(failure);
+                        return r.text;
+                    }
+                    finally {
+                        stopLoader();
+                    }
+                }
+            });
+        },
+        verify: async (verifyCtx, cwd2, taskTitle, taskId) => {
+            if (!getConfig().verifyWork) {
+                return { ok: true, reason: 'disabled' };
+            }
+            // The spec to verify against is the composed spec committed in the task
+            // file. A task that never reached compose has no spec section —
+            // runWorkVerification treats a null spec as a no-op pass.
+            let spec;
+            try {
+                const { body } = await readTaskFile(cwd2, taskId);
+                spec = extractSpecForVerification(body);
+            }
+            catch {
+                spec = null;
+            }
+            return runWorkVerification({
+                cwd: cwd2,
+                signal,
+                spec,
+                runChild: makeGateChild(verifyCtx, cwd2, taskTitle, 'verify', 'verify-debug.log')
+            });
+        },
+        recommend: async (recCtx, cwd2, taskTitle, taskId, failReason) => {
+            // Read the same composed spec the verify gate judged against, so the
+            // recommendation reasons over the real contract (degrade to the bare title).
+            let spec;
+            try {
+                const { body } = await readTaskFile(cwd2, taskId);
+                spec = extractSpecForVerification(body) ?? taskTitle;
+            }
+            catch {
+                spec = taskTitle;
+            }
+            return researchResolution({
+                cwd: cwd2,
+                signal,
+                spec,
+                failReason,
+                runChild: makeGateChild(recCtx, cwd2, taskTitle, 'recommend', 'verify-debug.log')
+            });
+        }
+    };
+}

package/dist/task/orchestrator.d.ts

@@ -17,6 +17,8 @@
  */
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { type WidgetState } from './widget.js';
+import { type RunTaskFn } from './gate-deps.js';
+import { type GateDeps } from './task-gates.js';
 import type { SpawnFn } from '../shared/child-process.js';
 /** Encapsulates the full lifecycle of a single pi-task run. */
 export declare class TaskRunner {
@@ -216,4 +218,23 @@ export declare function resumeAcrossCompactions(ctx: SteerCtx): Promise<number>;
  * front-matter state (TaskRunner.run never throws).
  */
 export declare function runSingleTask(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, opts?: RunSingleTaskOptions): Promise<RunSingleTaskResult>;
+/**
+ * The AUTOFIX re-runner injected into the gate deps: re-run a task's
+ * implementation turn, blocking until it finishes (steering across interrupts and
+ * resuming across compactions). Shared by /task and /task-auto so both gate the
+ * same way; lives here because it wraps runSingleTask (gate-deps must not import the
+ * orchestrators, to keep the dependency graph acyclic).
+ */
+export declare const gateRunTask: RunTaskFn;
+/**
+ * Run a single /task through implementation AND the shared verify + enforce gates,
+ * blocking until both finish. Used instead of the fire-and-forget handoff whenever
+ * `verify work` or `enforce guidelines` is enabled — so /task gates exactly like a
+ * /task-auto sub-task does. A terminal stop (the implementation died, or a gate
+ * paused/failed) leaves the task resumable and tells the user to /task-resume.
+ */
+export declare function runGatedTask(ctx: ExtensionCommandContext, cwd: string, raw: string, opts?: {
+    resumeId?: string;
+    deps?: GateDeps;
+}): Promise<void>;
 export declare function registerTask(pi: ExtensionAPI): void;

package/dist/task/orchestrator.js

@@ -24,8 +24,11 @@ import { normaliseTaskId, parseFrontMatter, extractSection } from './task-parser
 import { allocateTaskId, ensureTasksDir, readSection, readTaskFile, setTaskSection, taskFilePath, tasksDir, updateTaskFrontMatter, writeTaskFile } from './task-io.js';
 import { startWidget } from './widget.js';
 import { armImplWidget, disarmImplWidget, setupImplWidget } from './impl-widget.js';
-import { publishViewer, publishNotify, registerBridgeCommand, getBridge } from '../remote/bridge.js';
+import { publishViewer, publishNotify, publishLifecycleNotice, registerBridgeCommand, getBridge } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
+import { getConfig } from '../config/config.js';
+import { buildGateDeps } from './gate-deps.js';
+import { runGatesForTask } from './task-gates.js';
 import { parseVerifyBlock } from './spec-validation.js';
 import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phantom-imports.js';
 import { titleForDisplay } from './parsers.js';
@@ -555,6 +558,121 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
     }
     return { taskId, ok, sessionCancelled: false, ctx: freshCtx, interrupted, reason: implError };
 }
+// ─── Gated single-task flow ────────────────────────────────────────────────────
+/**
+ * The AUTOFIX re-runner injected into the gate deps: re-run a task's
+ * implementation turn, blocking until it finishes (steering across interrupts and
+ * resuming across compactions). Shared by /task and /task-auto so both gate the
+ * same way; lives here because it wraps runSingleTask (gate-deps must not import the
+ * orchestrators, to keep the dependency graph acyclic).
+ */
+export const gateRunTask = (c, cwd, t, opts) => runSingleTask(c, cwd, t, {
+    waitForImplementation: true,
+    resumeId: opts?.resumeId,
+    onStart: opts?.onStart,
+    planContext: opts?.planContext,
+    fixInstruction: opts?.fixInstruction
+});
+/**
+ * Demote a task file to a resumable state after a gate (or its implementation)
+ * stopped short. The file is marked `completed` at spec-handoff — before the work
+ * is even verified — so a gate FAIL would otherwise leave it un-resumable
+ * (`completed` is not in RESUMABLE_STATES). Best-effort; a missing/empty id is a
+ * no-op. Mirrors how /task-auto marks the parent run `failed` so resume re-runs it.
+ */
+async function markResumable(cwd, taskId) {
+    if (!taskId)
+        return;
+    try {
+        await updateTaskFrontMatter(cwd, taskId, { state: 'failed' });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Run a single /task through implementation AND the shared verify + enforce gates,
+ * blocking until both finish. Used instead of the fire-and-forget handoff whenever
+ * `verify work` or `enforce guidelines` is enabled — so /task gates exactly like a
+ * /task-auto sub-task does. A terminal stop (the implementation died, or a gate
+ * paused/failed) leaves the task resumable and tells the user to /task-resume.
+ */
+export async function runGatedTask(ctx, cwd, raw, opts = {}) {
+    const abort = new AbortController();
+    const deps = opts.deps
+        ?? buildGateDeps({
+            signal: abort.signal,
+            parentContextWindow: getParentContextWindow(ctx),
+            runTask: gateRunTask
+        });
+    let active = ctx;
+    // One push + remote bubble on the terminal outcome (parity with the
+    // notifyFinish push the fire-and-forget path emits via runSingleTask).
+    const announce = (msg, level) => {
+        active.ui.notify(msg, level);
+        publishLifecycleNotice(msg, level);
+        void pushNotify('Task finished', msg, 'pi-end').catch(() => { });
+    };
+    // First implementation run (blocking).
+    const res = await deps.runTask(active, cwd, raw, { resumeId: opts.resumeId });
+    active = res.ctx ?? active;
+    const tag = res.taskId || 'Task';
+    if (res.sessionCancelled) {
+        announce(`${tag} — could not start a fresh session for /task.`, 'warning');
+        return;
+    }
+    if (res.interrupted) {
+        await markResumable(cwd, res.taskId);
+        announce(`${tag} paused — resume with /task-resume.`, 'warning');
+        return;
+    }
+    if (!res.ok) {
+        await markResumable(cwd, res.taskId);
+        const why = res.reason ? ` — ${res.reason.slice(0, 160)}` : '';
+        announce(`${tag} stopped${why} — fix and run /task-resume.`, 'error');
+        return;
+    }
+    // The composed task's own front-matter title — used in commit messages and
+    // notifies (the gate sequence has no plan title to borrow). Degrade to the id.
+    let title = tag;
+    try {
+        const { frontMatter } = await readTaskFile(cwd, res.taskId);
+        title = frontMatter.title || tag;
+    }
+    catch {
+        /* keep the id as the title */
+    }
+    const gate = await runGatesForTask(active, deps, {
+        cwd,
+        taskId: res.taskId,
+        title,
+        tag
+        // No sibling plan → no scope fence; no parent list → no check-off.
+    });
+    active = gate.ctx;
+    switch (gate.kind) {
+        case 'paused':
+            await markResumable(cwd, res.taskId);
+            announce(`${tag} paused — verification failed and you dismissed the choice; resume with /task-resume.`, 'warning');
+            return;
+        case 'session-cancelled':
+            announce(`${tag} paused — could not start a session for autofix. Run /task-resume to retry.`, 'warning');
+            return;
+        case 'interrupted':
+            await markResumable(cwd, res.taskId);
+            announce(`${tag} paused — resume with /task-resume.`, 'warning');
+            return;
+        case 'failed': {
+            await markResumable(cwd, res.taskId);
+            const why = gate.reason ? ` — ${gate.reason.slice(0, 160)}` : '';
+            announce(`${tag} stopped${why} — fix and run /task-resume.`, 'error');
+            return;
+        }
+        case 'done':
+            announce(`${tag} complete — verified.`, 'info');
+            return;
+    }
+}
 // ─── Command handlers ────────────────────────────────────────────────────────
 async function handleTask(args, ctx) {
     await ctx.waitForIdle();
@@ -565,6 +683,15 @@ async function handleTask(args, ctx) {
         ctx.ui.notify('Type your prompt after /task (use @ for file completion).', 'info');
         return;
     }
+    // When a gate is enabled, /task awaits the implementation and runs the same
+    // verify + enforce gates a /task-auto sub-task does. With both gates off
+    // (the default), /task stays fire-and-forget: hand the spec to the main
+    // conversation and return immediately, exactly as before.
+    const cfg = getConfig();
+    if (cfg.verifyWork || cfg.enforceGuidelines) {
+        await runGatedTask(ctx, cwd, raw);
+        return;
+    }
     const { sessionCancelled } = await runSingleTask(ctx, cwd, raw, { notifyFinish: true });
     if (sessionCancelled) {
         ctx.ui.notify('Could not start a fresh session for /task.', 'warning');
@@ -648,6 +775,12 @@ async function handleTaskResume(args, ctx) {
         }
         id = candidates[0].id;
     }
+    // Match /task: resume through the gates when one is enabled, else fire-and-forget.
+    const cfg = getConfig();
+    if (cfg.verifyWork || cfg.enforceGuidelines) {
+        await runGatedTask(ctx, cwd, '', { resumeId: id });
+        return;
+    }
     const { sessionCancelled } = await runSingleTask(ctx, cwd, '', { resumeId: id, notifyFinish: true });
     if (sessionCancelled) {
         ctx.ui.notify('Could not start a fresh session for /task-resume.', 'warning');

package/dist/task/phases.d.ts

@@ -42,6 +42,14 @@ export interface PhaseConfig {
 export declare function extractToolingCommands(research: string): string[] | null;
 /** Replace the TOOLING section in a research string with a VERIFIED-TOOLING section. */
 export declare function replaceToolingWithVerified(research: string, verifiedCommands: string[]): string;
+/**
+ * Manifest + config content (orientation tiers 0–1) for refine, with the preserve
+ * directive. Reuses the SAME orientation machinery research feeds its workers — not
+ * a parallel reader — scoped to the "accumulative" files a from-scratch rewrite
+ * silently destroys. '' (non-git/empty/orientation-off) leaves refine unchanged, so
+ * a genuinely greenfield task is still free to create.
+ */
+export declare function refineExistingFilesBlock(deps: PhaseDeps): Promise<string>;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: string) => Promise<string>;
 export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): Promise<string>;
 export interface PhaseResearchDeps extends ExternalContextDeps {

package/dist/task/phases.js

@@ -11,7 +11,7 @@ import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
 import { isIntegrationUnknown } from './unknown-routing.js';
 import { getFileInventory } from './file-inventory.js';
-import { buildOrientation } from './orientation.js';
+import { buildOrientation, orientationTier } from './orientation.js';
 import { getConfig } from '../config/config.js';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -63,15 +63,67 @@ export function replaceToolingWithVerified(research, verifiedCommands) {
     return replaced;
 }
 // ─── Phase functions ─────────────────────────────────────────────────────────
-export const phaseRefine = (deps, raw, planContext) => runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext))), 
-// refine's deliverable is a 4-section text rewrite that never strictly
-// needs a successful read — on a test-writing task against a large
-// existing codebase the model over-explores (re-reads source hunting for
-// the impl) and burns the loop budget. Degrade to a no-tools final
-// attempt instead of hard-failing the whole run. See TASK_0016 (mx5):
-// refine looped 3×/resume forever; the deliverable was always producible
-// from the title + design doc alone.
-{ degradeOnExhaustion: true });
+// Authoritative directive that travels with the refine orientation block. Refine
+// runs BEFORE research, so on a "Scaffold project with package.json…" title it has
+// no signal the file already exists and authors greenfield strip-constraints
+// ("bun-plugin-tailwind the only dependency", "exactly N scripts") that compose
+// then obeys over the research facts — the implementer executes a wholesale
+// rewrite that drops every existing dependency and script (mx5 TASK_0001 emptied
+// package.json; the REAL pipeline reproduced it 3/3 even with research surfacing
+// the deps). Handing refine the manifest/config CONTENT up front, with this
+// reframe, fixes it at the origin (A/B: 1/5 → 5/5 preserve, 5/5 end-to-end).
+const REFINE_PRESERVE_DIRECTIVE = 'EXISTING FILES ON DISK — AUTHORITATIVE (overrides any "scaffold / create / set '
+    + 'up / initialize / from scratch / only / exactly / minimal" wording in the task '
+    + 'below): the files shown in the PROJECT ORIENTATION block ALREADY EXIST. When '
+    + 'the task says to scaffold, create, set up, initialize, or configure a file that '
+    + 'already exists, your GOAL and CONSTRAINTS MUST frame it as an in-place UPDATE '
+    + 'that PRESERVES every existing dependency, devDependency, script, field, and '
+    + "compiler option — adding or changing only the task's explicit delta. Do NOT "
+    + 'author any constraint that empties, reduces to a fixed/minimal set, renames, '
+    + 'recreates, or drops existing entries (no "X is the only dependency", no '
+    + '"exactly N scripts", no "produce exactly N files from scratch"). An existing '
+    + 'entry is NEVER scope drift and is never removed because it "belongs to a later step".';
+/**
+ * Manifest + config content (orientation tiers 0–1) for refine, with the preserve
+ * directive. Reuses the SAME orientation machinery research feeds its workers — not
+ * a parallel reader — scoped to the "accumulative" files a from-scratch rewrite
+ * silently destroys. '' (non-git/empty/orientation-off) leaves refine unchanged, so
+ * a genuinely greenfield task is still free to create.
+ */
+export async function refineExistingFilesBlock(deps) {
+    if (!getConfig().orientation)
+        return '';
+    const inventoryRaw = await getFileInventory(deps.cwd, deps.signal).catch(() => '');
+    if (inventoryRaw.length === 0)
+        return '';
+    const paths = inventoryRaw
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0 && (orientationTier(l) === 0 || orientationTier(l) === 1));
+    if (paths.length === 0)
+        return '';
+    const { block } = await buildOrientation(paths, async (p) => {
+        try {
+            return await readFile(resolve(deps.cwd, p), 'utf8');
+        }
+        catch {
+            return null;
+        }
+    });
+    return block.trim().length === 0 ? '' : `${REFINE_PRESERVE_DIRECTIVE}\n\n${block.trim()}`;
+}
+export const phaseRefine = async (deps, raw, planContext) => {
+    const existingFiles = await refineExistingFilesBlock(deps).catch(() => '');
+    return runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext, existingFiles))), 
+    // refine's deliverable is a 4-section text rewrite that never strictly
+    // needs a successful read — on a test-writing task against a large
+    // existing codebase the model over-explores (re-reads source hunting for
+    // the impl) and burns the loop budget. Degrade to a no-tools final
+    // attempt instead of hard-failing the whole run. See TASK_0016 (mx5):
+    // refine looped 3×/resume forever; the deliverable was always producible
+    // from the title + design doc alone.
+    { degradeOnExhaustion: true });
+};
 export async function phaseVerifyTooling(deps, research) {
     const commands = extractToolingCommands(research);
     if (!commands || commands.length === 0) {

package/dist/task/prompts.d.ts

@@ -47,7 +47,7 @@ export declare const COMPRESS_LABEL_PROMPT: (title: string, maxChars: number) =>
  * "Scaffold …" title re-expands the entire design into one task (validated: a real
  * /task-auto run implemented all 24 steps under step 1).
  */
-declare const REFINE_PROMPT: (raw: string, planContext?: string) => string;
+declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: string) => string;
 declare const RESEARCH_READ_ONLY_CONSTRAINT = "IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.";
 declare const RESEARCH_FILES_PROMPT: (refined: string) => string;
 declare const RESEARCH_APIS_PROMPT: (refined: string) => string;

package/dist/task/prompts.js

@@ -61,7 +61,7 @@ ${title}`;
  * "Scaffold …" title re-expands the entire design into one task (validated: a real
  * /task-auto run implemented all 24 steps under step 1).
  */
-const REFINE_PROMPT = (raw, planContext) => `${planContext ? planContext + '\n\n---\n\n' : ''}You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
+const REFINE_PROMPT = (raw, planContext, existingFiles) => `${planContext ? planContext + '\n\n---\n\n' : ''}You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
 
 Output structure (four sections, exact headings, in this order):
 
@@ -87,7 +87,7 @@ Rules:
 - Do not invent requirements not implied by the input.
 - If the task references a design/spec document (an @-path or a named spec file), READ it and treat it as authoritative. Carry its concrete schema verbatim into GOAL/CONSTRAINTS — table and column names, types, endpoint methods and paths, enum values. The task title is only a pointer into that spec: where the title and the spec disagree, follow the spec, and never introduce a table, column, endpoint, or dependency the spec does not define.
 - Do not output any preamble, commentary, or markdown headings beyond the four sections above.
-
+${existingFiles && existingFiles.trim() ? `\n${existingFiles.trim()}\n` : ''}
 Task: ${raw}`;
 // ─── Research fan-out prompts ─────────────────────────────────────────────────
 const RESEARCH_READ_ONLY_CONSTRAINT = `IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.`;