@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/phases.js

@@ -4,7 +4,6 @@
  */
 import { fileURLToPath } from 'node:url';
 import { docsFocused } from '../workers/docs-core.js';
-import { detectEcosystems } from '../workers/docs-ecosystems.js';
 import { fetchFocused } from '../workers/fetch-core.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
@@ -14,14 +13,14 @@ import { snapshotLeverEnv, workerProgressCeilingMs, projectDocsBudget, projectDo
 import { isIntegrationUnknown } from './unknown-routing.js';
 import { extractUserDirectives, preserveDirectivesBlock, enforceDirectives } from './user-directives.js';
 import { demoteUnsourcedAttributions } from './context-attribution.js';
-import { getFileInventory } from './file-inventory.js';
-import { buildOrientation, orientationTier } from './orientation.js';
+import { ORIENTATION_TIERS, orientationTier } from './orientation.js';
 import { getConfig } from '../config/config.js';
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
 import { buildExternalContext, gatherExternalContext } from './external-context.js';
+import { currentRunContext } from './run-context.js';
+import { readableMentions } from './mentions.js';
 import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS } from './prompts.js';
-import { appendGateRecord, readSection, removeTaskSection, setTaskSection, updateTaskFrontMatter } from './task-io.js';
+import { appendGateRecord, readSection, readTaskFile, removeTaskSection, setTaskSection, updateTaskFrontMatter } from './task-io.js';
+import { extractSection } from './task-parsers.js';
 import { applyDeprecations } from './deprecated-constraint.js';
 import { applyRefutations } from './refuted-constraint.js';
 import { spawnSync } from 'node:child_process';
@@ -37,16 +36,24 @@ import { settleQuestion } from './question-dialog.js';
 import { findSynthesizedApis, synthesizedApiReaskHint } from './api-synthesis.js';
 import { GREP_THEATER_RETRY_HINT } from './verify-quality.js';
 import { readContracts, buildContractsBlock, buildContractsVerifyBlock } from './contracts.js';
-import { readRequirements, buildRequirementsBlock, buildOwnedRequirementsBlock, readOwnedRequirements, writeOwnedRequirements, ownedForTitle, appendOwnedConstraints } from './requirements.js';
+import { readRequirements, buildRequirementsBlock, buildOwnedRequirementsBlock, readOwnedRequirements, writeOwnedRequirements, ownedForTask, appendOwnedConstraints } from './requirements.js';
 import { detachUnsatisfiableRequirements, claimPendingRequirements, unclaimedPendingRequirements, formatReassignActions } from './owned-freeze-reassign.js';
 import { trackedSourceOracle } from './owned-freeze-conflict.js';
 import { groupArgsForChild, runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED, ChildFailureError, isFatalChildCause } from './child-runner.js';
-import { runResearchWorker, researchWorkerCacheHeading } from './research-worker.js';
+import { runResearchStage, runResearchWorker, researchWorkerCacheHeading } from './research-worker.js';
 import { SessionUI, notifyRun } from '../remote/bridge.js';
 import { isYoloMode, yoloPickAutoAnswer } from './yolo.js';
 import { QaTranscript, GRILL_QA_POLICY } from './qa-transcript.js';
 // ─── Re-export constants from their home modules ────────────────────────────
 export { MAX_GRILL_QUESTIONS };
+/**
+ * This run's context, or a throwaway one for a caller outside a run bracket (a
+ * direct phase call in a test). Every per-project fact a phase asks for goes
+ * through it, so a /task-auto run derives each one once instead of per task.
+ */
+function runContextFor(deps) {
+    return deps.runContext ?? currentRunContext(deps.cwd);
+}
 // ─── Tooling helpers ─────────────────────────────────────────────────────────
 /** Extract the TOOLING section commands from a research output string. */
 export function extractToolingCommands(research) {
@@ -116,23 +123,16 @@ const REFINE_PRESERVE_DIRECTIVE = 'EXISTING FILES ON DISK — AUTHORITATIVE (ove
 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')
+    const runContext = runContextFor(deps);
+    const paths = (await runContext.inventoryPaths())
         .map(l => l.trim())
-        .filter(l => l.length > 0 && (orientationTier(l) === 0 || orientationTier(l) === 1));
+        .filter(l => {
+        const tier = orientationTier(l);
+        return tier !== null && tier <= ORIENTATION_TIERS.config;
+    });
     if (paths.length === 0)
         return '';
-    const { block } = await buildOrientation(paths, async (p) => {
-        try {
-            return await readFile(resolve(deps.cwd, p), 'utf8');
-        }
-        catch {
-            return null;
-        }
-    });
+    const { block } = await runContext.orientationOf(paths);
     return block.trim().length === 0 ? '' : `${REFINE_PRESERVE_DIRECTIVE}\n\n${block.trim()}`;
 }
 /**
@@ -163,9 +163,8 @@ export async function phaseCarriedBlocks(deps) {
     return [contracts, requirements, owned].filter(b => b.length > 0).join('\n');
 }
 /**
- * The owned (task-mapped) requirements for THIS task: matched by
- * the plan title the coverage map keyed them to, which is the task's stored
- * `raw prompt` section verbatim. Empty outside /task-auto runs, for spliced
+ * The owned (task-mapped) requirements for THIS task, joined on the plan key the
+ * coverage map assigned them to. Empty outside /task-auto runs, for spliced
  * repair tasks, and when the plan recorded no mapping — all of which make this a
  * no-op. This is the BELT (a prompt block, into refine and compose);
  * `appendOwnedConstraints` on the final spec is the BRACES. The belt is a request
@@ -173,20 +172,27 @@ export async function phaseCarriedBlocks(deps) {
  */
 async function ownedForThisTask(deps) {
     try {
-        const title = (await readSection(deps.cwd, deps.taskId, 'raw prompt')) ?? '';
-        return ownedForTitle(await readOwnedRequirements(deps.cwd), title.trim());
+        return ownedForTask(await readOwnedRequirements(deps.cwd), await planJoin(deps));
     }
     catch {
         return [];
     }
 }
-/** This task's plan title — the owned ledger's join key. */
-async function planTitle(deps) {
+/**
+ * How this task addresses the owned ledger: its plan key, and its plan title —
+ * the stored `raw prompt` section verbatim — for a ledger written before keys.
+ */
+async function planJoin(deps) {
     try {
-        return ((await readSection(deps.cwd, deps.taskId, 'raw prompt')) ?? '').trim();
+        const { frontMatter, body } = await readTaskFile(deps.cwd, deps.taskId);
+        const title = extractSection(body, 'raw prompt') ?? '';
+        return {
+            ...(frontMatter.plan_key !== undefined && { key: frontMatter.plan_key }),
+            title: title.trim()
+        };
     }
     catch {
-        return '';
+        return { title: '' };
     }
 }
 /** The `isSource` oracle production uses: git tracks the path in this tree. */
@@ -214,12 +220,12 @@ export async function resolveOwnedFreezeForThisTask(deps, spec) {
     const ledger = await readOwnedRequirements(deps.cwd).catch(() => []);
     if (ledger.length === 0)
         return spec;
-    const title = await planTitle(deps);
-    if (title.length === 0)
+    const join = await planJoin(deps);
+    if (join.title.length === 0)
         return spec;
     const res = detachUnsatisfiableRequirements({
         spec,
-        title,
+        ...join,
         ledger,
         isSource: repoSourceOracle(deps.cwd)
     });
@@ -247,10 +253,10 @@ export async function claimOwnedFreezeForThisTask(deps, refined) {
     const ledger = await readOwnedRequirements(deps.cwd).catch(() => []);
     if (unclaimedPendingRequirements(ledger).length === 0)
         return;
-    const title = await planTitle(deps);
-    if (title.length === 0)
+    const join = await planJoin(deps);
+    if (join.title.length === 0)
         return;
-    const res = claimPendingRequirements({ intent: refined, title, ledger });
+    const res = claimPendingRequirements({ intent: refined, ...join, ledger });
     if (res.actions.length === 0)
         return;
     deps.logDebug?.(formatReassignActions(res.actions));
@@ -298,29 +304,43 @@ export async function phaseVerifyTooling(deps, research) {
     if (!commands || commands.length === 0) {
         return replaceToolingWithVerified(research, []);
     }
-    const toolingList = commands.join('\n');
-    let verifyOutput;
-    try {
-        verifyOutput = await runPhaseChild(deps, 'verify-tooling', 'read,bash', VERIFY_TOOLING_PROMPT(toolingList));
-    }
-    catch (e) {
-        if (isFatalChildCause(e))
-            throw e;
-        // The fallback ships the tooling list UNVERIFIED, which is the right
-        // degrade for a child that merely failed. A hung command is different: it
-        // cost the ceiling on every strike and says the SPEC named something
-        // unbounded, so it is the one cause worth a trail line rather than silence.
-        if (e instanceof ChildFailureError && e.failure.kind === 'command-timeout') {
-            deps.logDebug?.(`verify-tooling: ${e.message} — shipping the list unverified`);
+    // UNVERIFIED is the degrade for a child that merely failed, and it is decided
+    // here rather than inside the run context so a failure is never cached as a
+    // verdict: the next task asks again.
+    let unverified = false;
+    let inconclusive = false;
+    const verified = await runContextFor(deps).verifiedToolingFor(commands, async (unknown) => {
+        let output;
+        try {
+            output = await runPhaseChild(deps, 'verify-tooling', 'read,bash', VERIFY_TOOLING_PROMPT(unknown.join('\n')));
+        }
+        catch (e) {
+            if (isFatalChildCause(e))
+                throw e;
+            // A hung command is the one cause worth a trail line: it cost the
+            // ceiling on every strike and says the SPEC named something unbounded.
+            if (e instanceof ChildFailureError && e.failure.kind === 'command-timeout') {
+                deps.logDebug?.(`verify-tooling: ${e.message} — shipping the list unverified`);
+            }
+            unverified = true;
+            return { verified: [], rejected: [] };
         }
+        const parsed = parseVerifyToolingOutput(output);
+        inconclusive = parsed.verified.length === 0 && parsed.rejected.length === 0;
+        return {
+            verified: parsed.verified.map(v => ({ cmd: v.cmd, class: v.class })),
+            rejected: parsed.rejected.map(r => r.cmd)
+        };
+    });
+    if (unverified)
         return replaceToolingWithVerified(research, commands);
-    }
-    const parsed = parseVerifyToolingOutput(verifyOutput);
-    const verifiedSection = parsed.verified.length > 0 ? parsed.verified.join('\n')
-        : parsed.rejected.length > 0 ? '(none verified)'
-            : '(verification inconclusive)';
-    await setTaskSection(deps.cwd, deps.taskId, 'verified tooling', verifiedSection);
-    return replaceToolingWithVerified(research, parsed.verified);
+    const cmds = verified.map(v => v.cmd);
+    // Written per task for provenance even though the verdicts are the run's: the
+    // task file has to say what THIS task was told its tooling was.
+    await setTaskSection(deps.cwd, deps.taskId, 'verified tooling', cmds.length > 0 ? verified.map(v => `${v.cmd}  ${v.class}`).join('\n')
+        : inconclusive ? '(verification inconclusive)'
+            : '(none verified)');
+    return replaceToolingWithVerified(research, cmds);
 }
 /**
  * The worker channels the APIS research worker is given.
@@ -389,22 +409,6 @@ export function scopedToolingGoal(refined) {
     const firstBullet = goal.search(/\n[ \t]*[-*]\s/);
     return firstBullet === -1 ? goal : goal.slice(0, firstBullet).trim();
 }
-/**
- * Dependency names declared by the project manifest, used by the CONTEXT post-check to
- * tell "this bullet is about an external library" from "this bullet is about our source".
- * A missing or malformed package.json yields none, which makes the post-check a no-op
- * rather than an error — a non-node project must still be able to run research.
- */
-async function manifestDependencyNames(cwd) {
-    try {
-        const raw = await readFile(resolve(cwd, 'package.json'), 'utf8');
-        const pkg = JSON.parse(raw);
-        return [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
-    }
-    catch {
-        return [];
-    }
-}
 /**
  * Prepended to worker:apis's prompt on the ONE retry the zero-retrieval gate triggers. It
  * names the exact failure (a section written with no retrieval) so the correction is concrete,
@@ -436,42 +440,43 @@ const CONTEXT_SILENT_RETRY_PREAMBLE = 'STOP. Your previous attempt at this task
     + 'nothing else. Keep the same rules as before: state an external library/API behaviour as fact '
     + 'ONLY when quoting an EXTERNAL CONTEXT block; otherwise write it as an "unverified:" open '
     + 'question. One claim per bullet. Better to emit three sharp sourced bullets than to say nothing.';
-export async function phaseResearch(deps, refined) {
-    const fileInventoryFn = deps.getFileInventory ?? getFileInventory;
+export async function phaseResearch(deps, refined, rawPrompt = '') {
+    const runContext = runContextFor(deps);
     const runWorkerFn = deps.runWorker ?? ((_label, input) => runWorker(input));
     const externalContext = await gatherExternalContext(refined, deps);
-    // Pre-compute the project file inventory once and hand it to every worker.
+    // The project file inventory, derived ONCE PER RUN and handed to every worker.
     // Workers can then jump straight to targeted read/grep on known paths
     // instead of each spawning its own discovery loop (find/ls). A '' result
     // (non-git repo, git missing, abort) silently falls back to the original
-    // behavior.
-    const inventoryRaw = await fileInventoryFn(deps.cwd, deps.signal).catch(() => '');
+    // behavior. The seam wins when a caller supplied one.
+    const inventoryRaw = deps.getFileInventory ?
+        await deps.getFileInventory(deps.cwd, deps.signal).catch(() => '')
+        : await runContext.inventory();
     const inventoryHeader = inventoryRaw.length > 0 ? `PROJECT FILE INVENTORY\n${inventoryRaw}\n\n` : '';
-    // Pre-read the project's orientation core (manifest, config, domain types,
-    // schema, entrypoints, API surface) ONCE and hand the full contents to the
-    // READ-HEAVY workers in their header. The workers run as separate child
-    // processes, so without this each one that explores re-reads the same hot
-    // files cold. Bounded by a hard byte budget so it can't overflow on a large
-    // repo; purely additive (nothing is blocked) so it can only remove a
-    // redundant read, never hide a file.
+    // The spec document(s) this task's own prompt points at. A cited doc is the
+    // one file orientation cannot select by convention and the one every worker
+    // needs — in the mx5 run it was read 50 times — so the mentions are threaded
+    // here and the `cited` rule (orientation.ts) puts it first in line for the
+    // byte budget.
+    const cited = await readableMentions(deps.cwd, rawPrompt);
+    // Pre-read the project's orientation core (the cited doc, manifest, config,
+    // project rules, domain types, schema, entrypoints, API surface) ONCE and hand
+    // the full contents to the EXPLORING workers in their header. The workers run
+    // as separate child processes, so without this each one that explores re-reads
+    // the same hot files cold. Bounded by a hard byte budget so it can't overflow
+    // on a large repo; purely additive (nothing is blocked) so it can only remove
+    // a redundant read, never hide a file.
     //
-    // Applied to FILES and APIS only — NOT CONTEXT/TOOLING, and the split is by
-    // whether the worker reads at all. FILES and APIS explore by reading, so
-    // pre-supplying the core replaces reads they would otherwise make. CONTEXT
-    // works from the inventory and grep, and TOOLING is scoped to the GOAL prose
-    // and single-read-guarded, so for those two the block is pure prefill with no
-    // read to displace. Orientation only goes where reads actually happen.
-    const orientationPaths = getConfig().orientation && inventoryRaw.length > 0 ?
-        inventoryRaw.split('\n').filter(l => l.trim().length > 0)
-        : [];
-    const orientation = await buildOrientation(orientationPaths, async (path) => {
-        try {
-            return await readFile(resolve(deps.cwd, path), 'utf8');
-        }
-        catch {
-            return null;
-        }
-    }).catch(() => ({ block: '', supplied: new Set() }));
+    // All but TOOLING, and the split is by whether the worker reads at all. FILES,
+    // APIS and CONTEXT all explore — CONTEXT with `read,grep` — so pre-supplying
+    // the core replaces reads they would otherwise make. TOOLING is scoped to the
+    // GOAL prose and single-read-guarded, so for it the block is pure prefill with
+    // no read to displace.
+    const orientation = getConfig().orientation && inventoryRaw.length > 0 ?
+        deps.getFileInventory ?
+            await runContext.orientationOf(inventoryRaw.split('\n').filter(l => l.trim().length > 0), cited)
+            : await runContext.orientation(cited)
+        : { block: '', supplied: new Set() };
     if (orientation.supplied.size > 0) {
         deps.logDebug?.(`orientation: pre-supplied ${orientation.supplied.size} core files`);
     }
@@ -479,7 +484,7 @@ export async function phaseResearch(deps, refined) {
     // Braces for the CONTEXT worker's LIVE-DATA RULE (the belt is the prompt itself).
     // Judged against the EXTERNAL CONTEXT this run actually gathered — the same string
     // the worker is handed below — and the manifest's dependency names.
-    const manifestPackages = await manifestDependencyNames(deps.cwd);
+    const manifestPackages = runContext.manifestDeps();
     // The spec-cited-URL lever from ./spec-urls.ts is built and unit-tested but is
     // NOT WIRED HERE: pointing the worker at a page it should have read did not
     // change what it produced, so the block would be prefill on every APIS prompt
@@ -522,14 +527,11 @@ export async function phaseResearch(deps, refined) {
         }
         return r;
     });
-    // Run the four workers ONE AT A TIME by default. Which order wins depends on
-    // the backend: concurrent streams share one local GPU and slow each other
-    // down, so the sum of four fast workers can beat the max of four slowed ones,
-    // while a backend that genuinely serves parallel streams has no such tradeoff.
-    // `parallelResearchWorkers` is the opt-in for those backends. The worker's
-    // reasoning level (config/reasoning.ts `research` group) changes decode length
-    // and so changes the answer too, which is why this is a config knob and not a
-    // constant.
+    // The four workers and the ONE dependency between them: APIS is written
+    // against the FILES map, and everything else is independent. `runResearchStage`
+    // reads that off `after`, so FILES runs, then APIS, with CONTEXT and TOOLING
+    // alongside both — and `researchConcurrency: 'serial'` still runs them in order
+    // for a single local GPU, where concurrent streams share one device.
     //
     // Result order (files, apis, context, tooling) is preserved for assembly.
     // Resolved once: `searchConfigured()` reads the environment, and the tools
@@ -545,14 +547,15 @@ export async function phaseResearch(deps, refined) {
         {
             section: 'APIS',
             label: 'worker:apis',
+            // The one declared edge: FILES' finished map rides along, so the worker
+            // doesn't re-derive where-things-live through project-docs queries the
+            // FILES worker just answered.
+            after: ['FILES'],
             // Read-heavy: gets the orientation core (see note above). Search/fetch
             // ride along only when a Brave key exists — see SEARCH_EXTENSION_PATH.
-            // FILES' finished map rides along when available (serial default), so
-            // the worker doesn't re-derive where-things-live through project-docs
-            // queries the FILES worker just answered.
             prompt: prior => orientation.block
                 + promptHeader
-                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined, detectEcosystems(deps.cwd))
+                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined, runContext.ecosystems())
                 + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')
                 // Empty unless PI_TASK_PROJECT_DOCS_BUDGET is set. The tool-side
                 // half lives in pi-worker-docs.ts; a budget enforced without being
@@ -585,7 +588,9 @@ export async function phaseResearch(deps, refined) {
         {
             section: 'CONTEXT',
             label: 'worker:context',
-            prompt: promptHeader + RESEARCH_CONTEXT_PROMPT(refined),
+            // Read-heavy too: it holds `read,grep` and reads to understand, so the
+            // core displaces reads here exactly as it does for FILES and APIS.
+            prompt: orientation.block + promptHeader + RESEARCH_CONTEXT_PROMPT(refined),
             // Context owns architectural understanding, not path discovery —
             // FILES handles that. Dropping `find`/`ls` keeps the worker from
             // spawning long enumeration loops whose output then inflates
@@ -632,15 +637,7 @@ export async function phaseResearch(deps, refined) {
             extensions: [SINGLE_READ_EXTENSION_PATH]
         }
     ];
-    // Persisting a worker's section is a read-modify-write of the shared task
-    // file, so writes are chained through one lock — a no-op in serial mode,
-    // load-bearing in parallel mode where two workers can settle together.
-    let persistChain = Promise.resolve();
-    const persistSection = (heading, text) => {
-        const next = persistChain.then(() => setTaskSection(deps.cwd, deps.taskId, heading, text));
-        persistChain = next.catch(() => { });
-        return next;
-    };
+    const persistSection = (heading, text) => setTaskSection(deps.cwd, deps.taskId, heading, text);
     /**
      * This phase's binding of the research-worker driver: everything about THIS
      * RUN, gathered once, so each of the four rows is plain data.
@@ -665,32 +662,7 @@ export async function phaseResearch(deps, refined) {
         persistSection,
         leverEnv
     }, prior);
-    const sections = [];
-    if (!getConfig().parallelResearchWorkers) {
-        // Default: ONE AT A TIME (see the note above the worker specs) — a fatal
-        // failure throws before later workers run, and each worker can see the
-        // finished sections before it (APIS builds on the FILES map).
-        for (const spec of workerSpecs) {
-            sections.push(await drive(spec, sections));
-        }
-    }
-    else {
-        // Opt-in for parallel-capable backends. allSettled (not all): every
-        // worker runs to its own outcome first, so one fatal failure cannot
-        // orphan the others' output — their sections persist for the resume
-        // before the failure is thrown. Assembly order stays the spec order
-        // regardless of completion order. No prior sections exist here, so prompt
-        // builders get none — APIS runs without the FILES map it gets when serial.
-        const settled = await Promise.allSettled(workerSpecs.map(spec => drive(spec, [])));
-        for (const s of settled) {
-            if (s.status === 'rejected')
-                throw s.reason;
-        }
-        for (const s of settled) {
-            if (s.status === 'fulfilled')
-                sections.push(s.value);
-        }
-    }
+    const sections = await runResearchStage(workerSpecs, drive, getConfig().researchConcurrency);
     // All workers succeeded — the assembled output below becomes the canonical
     // 'research' section (written by the orchestrator). The per-worker caches
     // exist only to survive a mid-phase failure, so drop them now to avoid
@@ -1162,7 +1134,7 @@ export async function refinePhase(d, p) {
  */
 export async function researchPhase(d, p) {
     const tResearch = Date.now();
-    const rawResearch = await phaseResearch(d, p.refined);
+    const rawResearch = await phaseResearch(d, p.refined, p.rawPrompt);
     d.recordSubStep?.('workers', Date.now() - tResearch);
     const tVerify = Date.now();
     const out = await phaseVerifyTooling(d, rawResearch);

package/dist/task/plan-orchestrator.js

@@ -21,12 +21,11 @@
  * receives beyond a bare /task is HANDOFF_DELIVERABLE_RULE, which rides on every
  * handoff, and the decisions block when anything was settled.
  */
-import * as path from 'node:path';
 import { 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, readTaskFile, setTaskSection, readSection, updateTaskFrontMatter, taskFilePath, tasksDir } from './task-io.js';
+import { writeTaskFile, readTaskFile, setTaskSection, readSection, updateTaskFrontMatter, taskFilePath } 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';
@@ -38,7 +37,8 @@ import { SessionUI, registerBridgeCommand, notifyBoth, notifyRun, isRemoteOrigin
 import { withRun, announceTerminal } from './run-bracket.js';
 import { getConfig } from '../config/config.js';
 import { isYoloMode } from './yolo.js';
-import { gateDebugWriter } from './debug-log.js';
+import { appendDebugLine, gateDebugWriter } from './debug-log.js';
+import { runLogPath } from './state-dir.js';
 import { getParentContextWindow } from './context-usage.js';
 import { ChildStatus, runPlanningChild, statusCallbacks } from './child-status.js';
 import * as fsp from 'node:fs/promises';
@@ -59,8 +59,7 @@ export function buildPlanDeps(ctx, cwd, planId, task, signal) {
     const childStatus = new ChildStatus({ parentContextWindow: getParentContextWindow(ctx) });
     const title = deriveTitle(task);
     const logDebug = gateDebugWriter((msg) => {
-        const line = `${new Date().toISOString()} ${msg}\n`;
-        void fsp.appendFile(path.join(tasksDir(cwd), `${planId}-debug.log`), line).catch(() => { });
+        appendDebugLine(runLogPath(cwd, `${planId}-debug.log`), msg);
     });
     const phaseDeps = {
         cwd,
@@ -225,7 +224,7 @@ export async function discardEmptyPlanFile(cwd, planId) {
         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 });
+        await fsp.rm(runLogPath(cwd, `${planId}-debug.log`), { force: true });
     }
     catch {
         /* best-effort: an unreadable file is left exactly where it is */

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

@@ -48,6 +48,7 @@ export declare class CoverageLedger {
     private _round;
     private _cap;
     private _bonusUsed;
+    private _terminal;
     constructor(_best: ScoredPlan, _opts: CoverageLedgerOptions);
     /** The best-covered plan seen so far — the one that reprompts, and the one that ships. */
     best(): ScoredPlan;

package/dist/task/plan-rounds.js

@@ -27,6 +27,7 @@ export class CoverageLedger {
     _round = 0;
     _cap;
     _bonusUsed = false;
+    _terminal = false;
     constructor(_best, _opts) {
         this._best = _best;
         this._opts = _opts;
@@ -42,7 +43,7 @@ export class CoverageLedger {
     }
     /** May another reprompt round run? */
     mayRetry() {
-        return this._round < this._cap;
+        return !this._terminal && this._round < this._cap;
     }
     /** Spend a round. Call once per reprompt, before the child runs. */
     startRound() {
@@ -65,6 +66,11 @@ export class CoverageLedger {
      */
     consider(cand) {
         const decision = decideAdoption(this._best.plan, cand.plan, this._opts.hasRequirements);
+        // A terminal verdict ends the loop HERE, before the bonus round can extend
+        // it: the bonus exists to buy one more draw, and the whole finding of a
+        // terminal verdict is that another draw answers the same question again.
+        if (decision.terminal === true)
+            this._terminal = true;
         if (!decision.adopt)
             return { adopted: false, decision, grantedBonusRound: false };
         const priorCovered = this._best.plan.covered.size;
@@ -73,6 +79,7 @@ export class CoverageLedger {
         // never come from different rounds.
         this._best = cand;
         const grant = !this._bonusUsed
+            && !this._terminal
             && this._round >= this._cap
             && this._opts.hasRequirements
             && cand.plan.covered.size > priorCovered

package/dist/task/prohibition-probe.d.ts

@@ -26,6 +26,7 @@
  * violated.
  */
 import type { ChangedFile } from './substitution-probe.js';
+import { type ConstraintProvenance, type QaResolver } from './spec-model.js';
 /** One "do not modify X" constraint extracted from the spec text. */
 export interface Prohibition {
     /** The forbidden path exactly as the spec spells it (file or directory). */
@@ -33,6 +34,10 @@ export interface Prohibition {
     /** The full spec line carrying the prohibition, so the verify child judges
      *  against the EXACT wording — including any exception clause it states. */
     constraint: string;
+    /** Where the constraint carrying this ban came from. An advisory one is
+     *  reported and does not decide the verdict alone — 0043 failed on a ban a
+     *  grill auto-answer invented. */
+    provenance: ConstraintProvenance;
 }
 /**
  * Does this line express a modification ban? Matches the active forms ("do not
@@ -47,7 +52,7 @@ export declare const PROHIBITION_RE: RegExp;
  * Prose-only prohibitions ("do not modify server-side code" with no path named)
  * extract nothing — the prompt-level rule still covers them.
  */
-export declare function extractProhibitions(spec: string): Prohibition[];
+export declare function extractProhibitions(spec: string, resolve?: QaResolver): Prohibition[];
 /**
  * Intersect the spec's prohibitions with the task's changed files (git shape —
  * the same collector the substitution probe uses). A prohibition matches a

package/dist/task/prohibition-probe.js

@@ -1,3 +1,5 @@
+import { parseSpec } from './spec-model.js';
+import { weightTag } from './constraint-policy.js';
 /**
  * Does this line express a modification ban? Matches the active forms ("do not
  * modify", "must not touch", "never edit", "don't change") and the passive form
@@ -23,22 +25,39 @@ function looksLikePath(token) {
  * Prose-only prohibitions ("do not modify server-side code" with no path named)
  * extract nothing — the prompt-level rule still covers them.
  */
-export function extractProhibitions(spec) {
+export function extractProhibitions(spec, resolve) {
     const out = [];
     const seen = new Set();
-    for (const line of spec.split('\n')) {
-        if (!PROHIBITION_RE.test(line))
+    for (const { text, provenance } of prohibitionCandidates(spec, resolve)) {
+        if (!PROHIBITION_RE.test(text))
             continue;
-        for (const m of line.matchAll(/`([^`]+)`/g)) {
+        for (const m of text.matchAll(/`([^`]+)`/g)) {
             const token = m[1].trim();
             if (!looksLikePath(token) || seen.has(token))
                 continue;
             seen.add(token);
-            out.push({ path: token, constraint: line.trim() });
+            out.push({ path: token, constraint: text.trim(), provenance });
         }
     }
     return out;
 }
+/**
+ * The lines a ban can live on: the spec's parsed CONSTRAINTS, each with its own
+ * provenance — or, for text that parses to no constraints at all, every line at
+ * `derived`.
+ *
+ * The fallback is not a courtesy to malformed specs. Half this probe's callers
+ * hand it a bare constraint list or a fragment rather than a four-section spec,
+ * and a probe that saw nothing in those would silently stop finding the
+ * violations it was built for.
+ */
+function prohibitionCandidates(spec, resolve) {
+    const parsed = parseSpec(spec, resolve);
+    if (parsed.constraints.length > 0) {
+        return parsed.constraints.flatMap(c => c.text.split('\n').map(text => ({ text, provenance: c.provenance })));
+    }
+    return spec.split('\n').map(text => ({ text, provenance: 'derived' }));
+}
 /** Normalise a path for comparison: strip leading ./ and trailing /. */
 const norm = (p) => p.replace(/^\.\//, '').replace(/\/+$/, '');
 /**
@@ -58,7 +77,8 @@ export function findProhibitionViolations(prohibitions, files) {
         });
         if (!hit)
             continue;
-        findings.push(`${f.path} — modified by this task, but the spec forbids it: "${hit.constraint}"`);
+        findings.push(`${f.path} ${weightTag(hit.provenance)} — modified by this task, but the spec `
+            + `forbids it: "${hit.constraint}"`);
     }
     return findings;
 }