@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/auto-orchestrator.js

@@ -16,11 +16,17 @@ import { parseAutoAnswer, autoAnswerHasTag, deriveTitle } from './parsers.js';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
 import { AUTO_CLARIFY_PROMPT, AUTO_DECOMPOSE_PROMPT, DECOMPOSE_COVERAGE_PROMPT } from './auto-prompts.js';
 import { GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT } from './prompts.js';
-import { allocateAutoId, buildAutoBody, parseDecomposeList, parseCoverageVerdict, parseTaskList, checkOffTask, stampTaskInProgress, insertTaskAfter, findResumableAutoDetailed } from './auto-io.js';
+import { allocateAutoId, buildAutoBody, parseDecomposeList, parseCoverageVerdict, UNNAMED_COVERAGE_GAP, parseTaskList, planKeyAt, checkOffTask, stampTaskInProgress, beginTaskAttempt, recordTaskEnd, insertTaskAfter, findResumableAutoDetailed } from './auto-io.js';
 import { decideResume, UNATTENDED_STATES } from './resume-gap.js';
+import { ENTRY_ATTEMPT_BUDGET } from './gate-resolution.js';
+import { recordDebt } from './accept-debt.js';
 import { drainRepairQueue, mergeRepairCandidates, planHasRepairFor, parseRepairTitleFile, buildRepairTitle, buildRepairScopeFence, extractFailingCommand } from './root-cause-repair.js';
-import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasksDir } from './task-io.js';
-import { readTextFile } from '../shared/fs-text.js';
+import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath } from './task-io.js';
+// Re-exported as well as used: the @-mention helpers moved to their own module so
+// the research phase can select a cited spec doc without importing this one, and
+// the planning call sites still name them here.
+import { expandFeatureMentions, readableMentions } from './mentions.js';
+export { expandFeatureMentions, readableMentions };
 import { findPhantomImports, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
 import { isFatalChildCause, prependHint, USER_CANCELLED } from './child-runner.js';
 import { requestCancel, resetCancel, isCancelRequested, cancelCheckpoint } from './cancel-points.js';
@@ -36,16 +42,18 @@ import { gitUnmergedPaths, gitStashRef } from './auto-commit.js';
 import { runFinalIntegrationGate, deriveOpenDebts } from './final-gate.js';
 import { spawnCommand } from './command-run.js';
 import { getConfig } from '../config/config.js';
-import { debugLogLevel, shouldLogDebug } from './debug-log.js';
+import { debugLogLevel, sanitizeDebugLine, shouldLogDebug } from './debug-log.js';
+import { pruneRunLogs, runLogPath } from './state-dir.js';
 import { isYoloMode, yoloPickAnswer } from './yolo.js';
 import { QaTranscript, CLARIFY_QA_POLICY } from './qa-transcript.js';
 import { makeQuestionSource } from './question-source.js';
 import { CoverageLedger } from './plan-rounds.js';
 import { CLARIFY_QUALITY_RULES, PLAN_FORMAT_HINT } from './plan-session.js';
 import { configureResearchRun, resumeResearchRun } from '../workers/research-cache.js';
+import { currentRunContext } from './run-context.js';
 import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, appendContracts } from './contracts.js';
-import { reconcileTitleSources } from './decompose-fidelity.js';
-import { granularityFloor, granularitySplitHint, isPlanShapeQuestion, isTooCoarse, planShapeIsHostsToAnswer, PLAN_SHAPE_ANSWER } from './decompose-granularity.js';
+import { reconcileTitleSources, renderFragments } from './decompose-fidelity.js';
+import { granularityFloor, granularitySplitHint, isPlanShapeQuestion, isTooCoarse, planShapeIsHostsToAnswer, PLAN_SHAPE_ANSWER, PLAN_SHAPE_TOPIC } from './decompose-granularity.js';
 import { mandatesTestsInSameChange, rewriteBatchTestPlan } from './batch-test-task.js';
 import { REQUIREMENT_EXTRACT_PROMPT, COVERAGE_MAP_PROMPT, parseRequirementLines, keepGroundedRequirements, capRequirements, writeOwnedRequirements, enumerateObligationPassages, uncoveredPassages, extractionRetryHint, parseCoverageMap, accountCoverage, isCrossCuttingRequirement, appendCarriedRequirements, buildRequirementsLedger } from './requirements.js';
 import { groundedCoverage } from './coverage-loop.js';
@@ -126,23 +134,6 @@ function suspectPlanHint(count) {
         + 'list for the ENTIRE feature, covering every part of the spec end to end. '
         + 'Output every task, one "- [ ] " line each, nothing else.]');
 }
-// Matches pi's @-file completion token (a path after @, until whitespace).
-const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
-// Trailing punctuation a user naturally types AFTER an @-mention when it sits in
-// prose — "Implement @design.md, reuse…" or "see @spec.md." — which the greedy
-// [^\s]+ above would otherwise swallow into the path. Left unstripped, the
-// resulting "design.md," resolves to no file, expansion is silently skipped, and
-// the planner reasons over a one-line "Implement @design.md" with NO spec inline
-// → it fabricates generic questions and tasks the spec never called for.
-//
-// Measured against a real file: the greedy token from "Implement @design.md,
-// reuse the parser" is `design.md,`, which does not exist; stripped, `design.md`
-// does. None of these chars are legitimate trailing characters of a doc path.
-const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
-/** The cleaned path token of an @-mention: greedy match minus trailing prose punctuation. */
-function mentionPath(token) {
-    return token.replace(MENTION_TRAILING_PUNCT, '');
-}
 /**
  * Every plan-debug write not yet on disk, chained.
  *
@@ -161,9 +152,9 @@ export function flushPlanDebug() {
  * Fire-and-forget debug line for the PLAN phase (clarify/decompose). It is the
  * only trail that phase has: planning runs before any task file exists, so there
  * is no per-task `TASK_NNNN-debug.log` to write into yet. This goes to
- * `.pi-tasks/plan-debug.log`, whose `*-debug.log` suffix matches the pattern
- * debug-log.ts documents, so one grep still finds every log. Never throws — the
- * mkdir and the append are both best-effort.
+ * `plan-debug.log` in the run's state dir, beside every other log of the run, so
+ * one grep still finds them all. Never throws — the mkdir and the append are both
+ * best-effort.
  *
  * Every call site records a plan DECISION (how many titles a round produced,
  * whether a retry was adopted, which clarify answer was auto-resolved), so all of
@@ -173,11 +164,11 @@ export function flushPlanDebug() {
 function logPlanDebug(cwd, msg) {
     if (!shouldLogDebug('event', debugLogLevel()))
         return;
-    const line = `${new Date().toISOString()} ${msg}\n`;
-    const dir = tasksDir(cwd);
+    const line = `${new Date().toISOString()} ${sanitizeDebugLine(msg)}\n`;
+    const file = runLogPath(cwd, 'plan-debug.log');
     planDebugChain = planDebugChain
-        .then(() => fsp.mkdir(dir, { recursive: true }))
-        .then(() => fsp.appendFile(path.join(dir, 'plan-debug.log'), line))
+        .then(() => fsp.mkdir(path.dirname(file), { recursive: true }))
+        .then(() => fsp.appendFile(file, line))
         .catch(() => { });
 }
 /**
@@ -240,61 +231,6 @@ async function triageClarifyQuestion(deps, cwd, featureForModel, existingFilesBl
         return null;
     }
 }
-/**
- * Expand any @file references in the feature text by appending each referenced
- * file's contents, so the planning children (clarify, decompose) always see the
- * real spec inline instead of relying on the model to open the file itself.
- * Without this, clarify on a one-line "Implement @spec.md" tends to bail with
- * NONE because, to the model, the request looks small and unambiguous.
- * Unreadable mentions (typos, non-file @tokens) are left untouched; the feature
- * is returned verbatim when nothing readable is referenced.
- */
-export async function expandFeatureMentions(cwd, feature) {
-    const seen = new Set();
-    const blocks = [];
-    for (const m of feature.matchAll(MENTION_RE)) {
-        const rel = mentionPath(m[1]);
-        if (rel === '' || seen.has(rel))
-            continue;
-        seen.add(rel);
-        try {
-            // Normalize CRLF/CR so an @-mentioned design doc saved on Windows
-            // inlines with LF endings the downstream phase parsers expect.
-            const body = await readTextFile(path.resolve(cwd, rel));
-            if (body.trim().length > 0) {
-                blocks.push(`--- contents of ${rel} ---\n${body.trim()}`);
-            }
-        }
-        catch {
-            // not a readable file — leave the @token in place, skip expansion
-        }
-    }
-    return blocks.length === 0 ? feature : `${feature.trim()}\n\n${blocks.join('\n\n')}`;
-}
-/**
- * The @file references in the feature that point at a readable file on disk —
- * the bare path tokens, deduped, in first-seen order. Unreadable mentions
- * (typos, non-file @tokens) are dropped so we never advertise a missing file as
- * an authoritative spec.
- */
-export async function readableMentions(cwd, feature) {
-    const out = [];
-    const seen = new Set();
-    for (const m of feature.matchAll(MENTION_RE)) {
-        const rel = mentionPath(m[1]);
-        if (rel === '' || seen.has(rel))
-            continue;
-        seen.add(rel);
-        try {
-            await fsp.access(path.resolve(cwd, rel));
-            out.push(rel);
-        }
-        catch {
-            // not a readable file — don't thread it into task titles
-        }
-    }
-    return out;
-}
 /** A trailing "[decisions: …]" clause decompose may attach to a task line. */
 const DECISIONS_RE = /\s*\[decisions:\s*(.+?)\]\s*$/i;
 /**
@@ -342,29 +278,37 @@ export function attachSpecRefs(titles, refs) {
  *
  * The plan listing strips the threaded "| decisions … | spec …" tail from each
  * title and keeps the human-readable head, so the model reads clean step names,
- * and it marks the current one "(THIS STEP)" — both confirmed by building a fence
+ * and it marks the current one `[this]` — both confirmed by building a fence
  * over threaded titles. The authoritative spec ref still rides on THIS step's own
  * title via attachSpecRefs.
+ *
+ * Every sibling used to read as unbuilt, which is a lie about the first half of
+ * any plan past step one: a step told its predecessors are "done in later runs"
+ * re-scaffolds what is already in the tree. The entries carry their own done
+ * state, so the listing states it.
  */
-export function buildScopeFence(titles, currentIndex) {
-    const n = titles.length;
-    const listing = titles
-        .map((t, i) => {
-        const head = t.split(' | ')[0].trim();
-        const tag = i === currentIndex ? ' (THIS STEP)' : '';
-        return `[${i + 1}]${tag} ${head}`;
+export function buildScopeFence(entries, currentIndex) {
+    const n = entries.length;
+    const listing = entries
+        .map((e, i) => {
+        const head = e.title.split(' | ')[0].trim();
+        const marker = i === currentIndex ? 'this'
+            : e.done ? 'done'
+                : 'later';
+        return `[${i + 1}] [${marker}] ${head}`;
     })
         .join('\n');
     return (`PLAN CONTEXT — this task is STEP ${currentIndex + 1} of ${n} in an already-decomposed plan. `
-        + `Each step below is implemented by its OWN separate run; the others are NOT your job and `
-        + `are done in later runs. Implement ONLY the slice named in "Task" below.\n\n`
+        + `Each step below is implemented by its OWN separate run: a [done] step is ALREADY BUILT and `
+        + `in the tree (build on it — never rebuild, duplicate or re-scaffold it), a [later] step is `
+        + `not built yet and is NOT your job. Implement ONLY the slice named in "Task" below.\n\n`
         + `The design/spec document the task references describes the WHOLE system across all ${n} `
         + `steps. Read it to get exact names, types, and signatures for YOUR step and to understand `
         + `how your step fits — but DO NOT design, scaffold, schema, route, page, query, component, or `
         + `test anything that belongs to another step listed below. Your GOAL / CONSTRAINTS / `
         + `KNOWN-UNKNOWNS must cover only THIS step's slice. Do not pull in tables, endpoints, pages, `
         + `components, or flows owned by a later step.\n\n`
-        + `The full plan (these run separately — do NOT implement them here):\n${listing}`);
+        + `The full plan (these run separately — do NOT implement the [later] ones here):\n${listing}`);
 }
 /**
  * The scope fence for step `currentIndex`, plus the REPAIR fence when that step is
@@ -377,12 +321,13 @@ export function buildScopeFence(titles, currentIndex) {
  * `bun run test` yields it while a plain-prose defect yields undefined and only the
  * file pin applies.
  */
-function buildStepFence(titles, currentIndex) {
-    const base = buildScopeFence(titles, currentIndex);
-    const repairFile = parseRepairTitleFile(titles[currentIndex] ?? '');
+export function buildStepFence(entries, currentIndex) {
+    const base = buildScopeFence(entries, currentIndex);
+    const title = entries[currentIndex]?.title ?? '';
+    const repairFile = parseRepairTitleFile(title);
     if (!repairFile)
         return base;
-    return `${base}\n\n${buildRepairScopeFence(repairFile, extractFailingCommand(titles[currentIndex] ?? ''))}`;
+    return `${base}\n\n${buildRepairScopeFence(repairFile, extractFailingCommand(title))}`;
 }
 /**
  * Drain the gate's root-cause repair queue into the running plan: one scoped
@@ -566,6 +511,7 @@ export async function elicitClarifications(ctx, cwd, deps, oriented) {
         generate: hint => deps.runChild('auto-clarify', 'read', prependHint(hint, AUTO_CLARIFY_PROMPT(featureForModel, transcript.forGenerator()))),
         formatHint: PLAN_FORMAT_HINT,
         rules: CLARIFY_QUALITY_RULES,
+        topics: [{ id: PLAN_SHAPE_TOPIC, match: isPlanShapeQuestion }],
         cap: MAX_CLARIFY_QUESTIONS,
         log: msg => logPlanDebug(cwd, `clarify: ${msg}`)
     });
@@ -589,6 +535,10 @@ export async function elicitClarifications(ctx, cwd, deps, oriented) {
         if (planShapeIsHostsToAnswer(ownableRequirements) && isPlanShapeQuestion(plainQ)) {
             logPlanDebug(cwd, `plan-shape question answered host-side (not the triage): ${plainQ.replace(/\s+/g, ' ').slice(0, 120)}`);
             transcript.add('host-set', plainQ, PLAN_SHAPE_ANSWER);
+            // The transcript entry alone never stopped the re-draw: the generator
+            // is stateless and reworded the same fork (often into the plural),
+            // which then reached the user or the triage as if it were open.
+            source.settle(PLAN_SHAPE_TOPIC);
             continue;
         }
         // Answer-side triage (grill parity): if the inlined spec already settles
@@ -658,7 +608,7 @@ export async function decomposePlan(cwd, deps, oriented, clarifications) {
             logPlanDebug(cwd, `decompose fidelity: ${plan.sourced}/${plan.titles.length} titles cited a grounded source; `
                 + `${plan.restored.length} restoration(s)`
                 + plan.restored
-                    .map(r => ` [task ${r.index + 1}: ${r.fragments.join(', ')}]`)
+                    .map(r => ` [task ${r.index + 1}: ${renderFragments(r.fragments)}]`)
                     .join(''));
         }
         // Batch-test ban (item 6): drop or scope a whole-project "write all the
@@ -777,7 +727,12 @@ export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomp
             rethrowIfCancelled(err);
             verdict = null;
         }
-        const verdictMissing = verdict?.kind === 'incomplete' ? verdict.missing : [];
+        // An `unparseable` verdict IS a verdict of INCOMPLETE — it just names no
+        // area. Reading it as "nothing missing" shipped a plan the judge had ruled
+        // incomplete; the host names the gap instead so the round still happens.
+        const verdictMissing = verdict?.kind === 'incomplete' ? verdict.missing
+            : verdict?.kind === 'unparseable' ? [UNNAMED_COVERAGE_GAP]
+                : [];
         let acc = null;
         // The monotonic guard's owned-set is grounded DETERMINISTICALLY in
         // requirement↔title token overlap — NOT the coverage-map model's TASK
@@ -880,6 +835,10 @@ export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomp
                         .slice(0, 200)}]`
                     : ''));
         }
+        if (outcome.decision.terminal === true) {
+            logPlanDebug(cwd, 'decompose-coverage: TERMINAL — another round asks the same question');
+            break;
+        }
     }
     const best = rounds.best();
     const round = rounds.round();
@@ -1026,16 +985,23 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ground: emitted => keepGroundedScripts(emitted, featureForModel),
         append: appendDeclaredScripts
     });
-    // Persist the TASK-MAPPED requirements keyed by the (spec-ref-attached) title
-    // each task will carry. With only cross-cutting entries travelling, the
-    // mapped ones shape the title list and then vanish, and a task can narrow a
-    // requirement out of its own spec with nothing to stop it.
+    // Persist the TASK-MAPPED requirements under the plan key of the entry each
+    // was mapped to — the same key `buildAutoBody` is about to write onto the
+    // checkbox line, so the two sides of the join are minted from one index. With
+    // only cross-cutting entries travelling, the mapped ones shape the title list
+    // and then vanish, and a task can narrow a requirement out of its own spec
+    // with nothing to stop it.
     // Inert until the owned-requirements injection is wired into the phase
     // prompts; recorded regardless so the plan's mapping is auditable per run.
     if (best.accounting && best.accounting.mapped.length > 0) {
         await writeOwnedRequirements(cwd, best.accounting.mapped
             .filter(m => m.task >= 1 && m.task <= titles.length)
-            .map(m => ({ quote: m.req.quote, anchor: m.req.anchor, title: titles[m.task - 1] })));
+            .map(m => ({
+            quote: m.req.quote,
+            anchor: m.req.anchor,
+            key: planKeyAt(m.task - 1),
+            title: titles[m.task - 1]
+        })));
     }
     // persist
     const id = await allocateAutoId(cwd);
@@ -1276,9 +1242,28 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     return;
                 }
                 await updateTaskFrontMatter(cwd, id, { state: 'completed' });
+                // Retention runs HERE and nowhere else: a completed run is the one
+                // moment the state dir is quiet and this process still knows which
+                // repo it was serving. A failed or cancelled run keeps its logs —
+                // those are the ones somebody is about to read.
+                await pruneRunLogs(cwd);
                 announceDone(active, stage.message, stage.level);
                 return;
             }
+            // ABANDON an entry that has spent its attempt budget. A task that
+            // crashes before it can be checked off is re-entered by every resume,
+            // for as long as anyone keeps resuming — the plan never advances and
+            // the entry never converges. Give up on THIS entry, write down what was
+            // left unfinished, and let the rest of the plan run.
+            if ((next.attempts ?? 0) >= ENTRY_ATTEMPT_BUDGET) {
+                await recordDebt(cwd, next.producedId ?? id, `"${next.title}" was abandoned after ${next.attempts} attempts`
+                    + `${next.lastEnd ? ` (last ended: ${next.lastEnd})` : ''}`
+                    + ' — no verified artifact; the plan moved on without it', 'abandoned');
+                await checkOffTask(cwd, id, next.index, next.producedId ?? '', next.title);
+                notifyBoth(active, `${id}: abandoned "${next.title}" after ${next.attempts} attempts — `
+                    + 'recorded as debt; continuing with the rest of the plan.', 'warning');
+                continue;
+            }
             // REFUSE to start on a conflicted tree: an unmerged index dooms every
             // commit ahead and a `git add -A` would silently mis-resolve it.
             const unmerged = deps.unmergedPaths ? await deps.unmergedPaths(cwd) : [];
@@ -1323,6 +1308,18 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             if (checkpoint.committed) {
                 notifyRun(active, `${id}: checkpointed uncommitted work before "${next.title}".`, 'info');
             }
+            // REPO-HEALTH BASELINE, taken here because the checkpoint above just made
+            // the tree clean: what the project's own statics say now is what this task
+            // INHERITED, and the verify gate attributes a red check against it instead
+            // of failing the task for a sibling's defect (health-baseline.ts). The
+            // inner task file does not exist yet, so the capture is handed to the
+            // runner, which writes the section once its id is allocated.
+            const capture = deps.captureHealthBaseline;
+            const healthBaseline = capture ?
+                {
+                    healthBaseline: (taskCtx) => capture(taskCtx, cwd, next.title)
+                }
+                : {};
             // Stash ref before the task: compared after the gates so a stash pushed
             // during the task (impl model or any child) and left behind is called
             // out instead of silently waiting to detonate in a later task.
@@ -1336,14 +1333,21 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     announceDone(active, `${id} cancelled before "${next.title}" — resume with /task-auto-resume.`, 'warning');
                     return;
                 }
+                // Counted BEFORE the run, not after it: a run that takes pi down
+                // with it would never reach an after-the-fact increment, and an
+                // attempt nobody counted is exactly the one the budget exists to
+                // bound.
+                await beginTaskAttempt(cwd, id, next.index);
                 const res = await deps.runTask(active, cwd, next.title, {
                     resumeId,
+                    ...healthBaseline,
                     // Fence this step against re-expanding the whole referenced spec:
                     // name the sibling steps so refine bounds this step's slice. Only
                     // matters when refine runs fresh (a resumed task past refine ignores
                     // it), but always supplied so a resume that restarts at refine is
                     // fenced too.
-                    planContext: buildStepFence(entries.map(e => e.title), next.index),
+                    planContext: buildStepFence(entries, next.index),
+                    ...(next.key !== undefined && { planKey: next.key }),
                     onStart: resumeId ? undefined : (innerId => stampTaskInProgress(cwd, id, next.index, innerId, next.title))
                 });
                 active = res.ctx ?? active;
@@ -1356,6 +1360,10 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 // only the wording is this command's.
                 if (!runSucceeded(res.end)) {
                     const policy = RUN_END_POLICY[res.end.kind];
+                    // The ending goes on the ENTRY, where the next resume reads it:
+                    // the inner task file's own state cannot distinguish the entry
+                    // that keeps faulting from the one a user stopped once.
+                    await recordTaskEnd(cwd, id, next.index, res.end.kind);
                     // Demote the INNER task file: it reads `completed` from
                     // spec-handoff, and leaving it that way is how a failed run's task
                     // file claims success after the run failed.
@@ -1396,7 +1404,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     title: next.title,
                     tag: id,
                     // Fence an AUTOFIX re-run against re-expanding the whole spec.
-                    planContext: buildStepFence(entries.map(e => e.title), next.index),
+                    planContext: buildStepFence(entries, next.index),
                     // res.ok === true means runner.run() completed, so res.taskId is the
                     // allocated TASK_NNNN id (never empty here). The parent task-list
                     // check-off runs after verify passes/accepts and before the commit,
@@ -1481,10 +1489,12 @@ async function handleTaskAuto(args, ctx) {
     // and the ordinary command path cannot reach us.
     try {
         await withRun(ctx, { onCancel: terminalCancel }, async () => {
-            // Stamp a fresh per-run research-cache id BEFORE planning so enrichment and
+            // Stamp the per-run research-cache id BEFORE planning so enrichment and
             // every task's research phase share one run's cache; disabled ⇒ clears any token a
-            // prior run left, so nothing is cached.
-            configureResearchRun(getConfig().researchCache);
+            // prior run left, so nothing is cached. It is the RUN's own id (the bracket
+            // opened the run context one statement ago), so the cache file and the
+            // env-notes ledger name this run the same way.
+            configureResearchRun(getConfig().researchCache, currentRunContext(cwd).runId);
             const abort = new AbortController();
             const deps = defaultDeps(ctx, cwd, abort.signal, deriveTitle(raw));
             let id;
@@ -1557,6 +1567,10 @@ async function handleTaskAutoResume(args, ctx) {
             // working cache, and a whole-file freshness gate can never hold on a
             // greenfield run that installs packages as it goes — so invalidation is
             // per entry. See resumeResearchRun.
+            //
+            // The RUN context keeps its own fresh id, deliberately: an external doc
+            // digest does not go stale over a pause, and an environment fact measured
+            // against the tree before it does.
             const research = await resumeResearchRun(cwd, getConfig().researchCache);
             if (research.reused) {
                 logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies), `

package/dist/task/child-runner.d.ts

@@ -16,6 +16,7 @@ import type { docsRaw, docsFocused } from '../workers/docs-core.js';
 import type { fetchRaw, fetchFocused } from '../workers/fetch-core.js';
 import type { npmVersionLookup } from '../workers/npm-version.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
+import type { RunContext } from './run-context.js';
 export declare const USER_CANCELLED = "__user_cancelled__";
 /**
  * Why a phase child did not answer.
@@ -65,6 +66,13 @@ export interface PhaseDeps {
     cwd: string;
     taskId: string;
     signal: AbortSignal;
+    /**
+     * What is true of the RUN rather than of this task: the inventory, the
+     * orientation core, the manifest deps, the ecosystems, the verified tooling.
+     * Absent → the phase builds a throwaway context for itself, which is the old
+     * per-task behaviour (see run-context.ts).
+     */
+    runContext?: RunContext;
     onChildOutput?: (line: string) => void;
     onContextUsage?: (snapshot: ContextSnapshot) => void;
     /**
@@ -215,6 +223,16 @@ export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: stri
  */
 export declare function formatDegradeHint(hit: LoopHit): string;
 export declare function prependHint(hint: string | null, prompt: string): string;
+/**
+ * Append one line per loop kill to the task file's `loop events` section.
+ *
+ * Best-effort by contract: it runs for every phase child AND every research
+ * worker, and not every caller
+ * owns a task file on disk (a scripted harness, a bare unit deps bag). A trail
+ * that cannot be written must cost the phase nothing — the loop kill itself is
+ * already reported through the debug log and the thrown error.
+ */
+export declare function appendLoopEvents(cwd: string, taskId: string, phase: string, r: RunWorkerResult): Promise<void>;
 /**
  * Run a child up to twice; the second attempt gets `emphasized=true` to escalate
  * the prompt. On success, return the validator's value; on two failures, throw

package/dist/task/child-runner.js

@@ -11,9 +11,9 @@
 import { runWorker } from '../workers/pi-worker-core.js';
 import { classifyWorkerFailure } from '../workers/worker-failure.js';
 import { isFatalKill } from '../workers/worker-kill.js';
-import { MAX_LOOP_RESTARTS } from './loop-detector.js';
+import { describeLoopHit, MAX_LOOP_RESTARTS } from './loop-detector.js';
 import { MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
-import { readSection, setTaskSection } from './task-io.js';
+import { mergeTaskSection } from './task-io.js';
 import { streamStallCause } from '../shared/stream-watchdog.js';
 import { getConfig } from '../config/config.js';
 import { groupChildArgs, groupWindow } from '../config/group-args.js';
@@ -238,15 +238,15 @@ export function prependHint(hint, prompt) {
 /**
  * Append one line per loop kill to the task file's `loop events` section.
  *
- * Best-effort by contract: it runs for EVERY phase child, and not every caller
+ * Best-effort by contract: it runs for every phase child AND every research
+ * worker, and not every caller
  * owns a task file on disk (a scripted harness, a bare unit deps bag). A trail
  * that cannot be written must cost the phase nothing — the loop kill itself is
  * already reported through the debug log and the thrown error.
  */
-async function appendLoopEvents(cwd, taskId, phase, r) {
+export async function appendLoopEvents(cwd, taskId, phase, r) {
     const line = (hit, strike, outcome) => `- ${new Date().toISOString()}  ${phase}  strike ${strike}/${MAX_LOOP_RESTARTS + 1}  `
-        + `${hit.call.name}(${JSON.stringify(hit.call.args)}) ×${hit.count} in last `
-        + `${hit.windowSize} calls  → ${outcome}`;
+        + `${describeLoopHit(hit)}  → ${outcome}`;
     const lines = r.restarts.flatMap(x => x.loopHit ?
         [
             line(x.loopHit, x.attempt, x.rescue ? 'degraded — no-tools final attempt' : 'restarted with hint')
@@ -257,8 +257,7 @@ async function appendLoopEvents(cwd, taskId, phase, r) {
     if (lines.length === 0)
         return;
     try {
-        const existing = (await readSection(cwd, taskId, 'loop events')) ?? '';
-        await setTaskSection(cwd, taskId, 'loop events', [existing, ...lines].filter(Boolean).join('\n'));
+        await mergeTaskSection(cwd, taskId, 'loop events', existing => [existing ?? '', ...lines].filter(Boolean).join('\n'));
     }
     catch {
         /* best-effort: a trail is never worth failing a phase for */

package/dist/task/command-run.d.ts

@@ -172,6 +172,10 @@ export type VerifyRerunOutcome = {
     outcome: 'gap';
     detail: string;
 };
+/** The command word of a shell line, past any leading `VAR=value` assignments.
+ *  Exported for gate-evidence, which spawns the same shape of line and must
+ *  resolve the same runner against the same stripped PATH. */
+export declare function leadingBin(line: string): string | null;
 /**
  * Re-run one VERIFY-block command line under the gate's existing
  * env-gap contract, so a debt whose reason NAMES that command can be closed by the

package/dist/task/command-run.js

@@ -308,8 +308,10 @@ export function classifyCommandRun(run, gapPatterns = [], opts = {}) {
         tail: outputTail(run.stdout, run.stderr)
     };
 }
-/** The command word of a shell line, past any leading `VAR=value` assignments. */
-function leadingBin(line) {
+/** The command word of a shell line, past any leading `VAR=value` assignments.
+ *  Exported for gate-evidence, which spawns the same shape of line and must
+ *  resolve the same runner against the same stripped PATH. */
+export function leadingBin(line) {
     for (const tok of line.trim().split(/\s+/)) {
         if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tok))
             continue;

package/dist/task/constraint-policy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * constraint-policy — how much a constraint's PROVENANCE is worth, as one table
+ * both gate children render from.
+ *
+ * The verify child was told a spec constraint is unwaivable, full stop. The
+ * resolution judge was told to judge by function and treat over-literal wording
+ * as a false alarm. Neither was wrong on its own; together they made the gate's
+ * answer depend on which child happened to speak. 0043 is what that costs: a
+ * constraint a grill AUTO-ANSWER invented ("do NOT touch `test/ct/template/
+ * index.html`") was held as unwaivable as one the user typed, and the task failed
+ * on it.
+ *
+ * A constraint a human stated, or one the refined task carried in, BINDS. A
+ * constraint some automation produced — an auto-answer, a YOLO pick, an untagged
+ * line the composer wrote itself — is ADVISORY: it sharpens the work, and it
+ * fails a gate only when an ACCEPTANCE bullet also fails. Acceptance is the bar;
+ * an advisory constraint is a hint about how to clear it.
+ *
+ * One table, one renderer, two call sites (verify rule 4b, the judge's rules).
+ */
+import type { Constraint, ConstraintProvenance } from './spec-model.js';
+export type ConstraintWeight = 'binding' | 'advisory';
+/**
+ * What each provenance is worth. A new `ConstraintProvenance` member is a compile
+ * error until it declares its weight — which is the point, since the cheapest way
+ * back to 0043 is a new automated kind quietly defaulting to `binding`.
+ *
+ * `accepted` binds because a human read the recommendation and took it; `typed`
+ * and `host-set` for the same reason at either end (a person's own words, and a
+ * decision the host makes deterministically rather than leaving to a model).
+ * Everything else was produced by automation reasoning about the task, and
+ * automation may not mint an unwaivable rule.
+ */
+export declare const CONSTRAINT_WEIGHTS: Record<ConstraintProvenance, ConstraintWeight>;
+export declare function constraintWeight(provenance: ConstraintProvenance): ConstraintWeight;
+/** The weight marker a child sees on a constraint line, and probes match on. */
+export declare function weightTag(provenance: ConstraintProvenance): string;
+/** Does this collection of findings name at least one BINDING constraint? */
+export declare function anyBinding(findings: readonly string[]): boolean;
+/**
+ * The spec's CONSTRAINTS, annotated with each line's weight, for a child that
+ * must judge them. Returns null when the spec states none — the caller then emits
+ * no block rather than an empty heading.
+ */
+export declare function annotateConstraints(constraints: readonly Constraint[]): string | null;
+/**
+ * The policy, as prompt lines. ONE renderer: the verify pass and the resolution
+ * judge cite the same paragraph, so the two children cannot hold opposite
+ * policies again. `heading` differs because the two prompts number their rules
+ * differently — that is the only thing a call site may vary.
+ */
+export declare function renderConstraintPolicy(heading: string): string[];