@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/requirements.js

@@ -10,8 +10,9 @@
  *
  * Mechanism (spec-shape-agnostic, contracts.ts pattern):
  *   1. EXTRACT requirement units as VERBATIM quotes from whatever structure the
- *      spec has (headings, tables, bullets, prose) — each host-GROUNDED by the
- *      normalised-substring guard, so a fabricated requirement can never enter.
+ *      spec has (headings, bullets, prose) — each host-GROUNDED by the
+ *      normalised-substring guard against a CANDIDATE block (`RequirementPolicy`),
+ *      so neither a fabricated requirement nor a DDL column can enter.
  *   2. MAP each grounded requirement against the task list (a per-requirement
  *      verdict: TASK n / CROSS-CUTTING / NONE). Completeness is then computed
  *      HOST-SIDE from the map — a blanket "COMPLETE" is structurally impossible
@@ -29,6 +30,7 @@
  */
 import { normalise } from './contracts.js';
 import { makeLedger } from './ledger.js';
+import { blocksOf, demark, groundIn, parseSpecDoc, preambleOf, sectionPlains } from './spec-doc.js';
 const REQUIREMENTS_FILE = 'requirements.md';
 /** Cap kept entries so the injected block stays bounded on a large design. */
 const MAX_REQUIREMENTS = 40;
@@ -36,6 +38,16 @@ const MAX_REQUIREMENTS = 40;
 const MAX_REQUIREMENT_LENGTH = 300;
 /** Too short to state an obligation (and to ground unambiguously). */
 const MIN_QUOTE_LENGTH = 6;
+/** The checklist rides into the extraction prompt, so it stays readable. */
+const MAX_OBLIGATION_PASSAGES = 20;
+export const REQUIREMENT_POLICY = {
+    candidateKinds: new Set(['para', 'list-item', 'quote']),
+    excludePreamble: true
+};
+function candidates(doc, policy) {
+    const excluded = policy.excludePreamble ? new Set(preambleOf(doc)) : new Set();
+    return b => policy.candidateKinds.has(b.kind) && !excluded.has(b);
+}
 function carriedLineKey(line) {
     const q = /"([^"]+)"/.exec(line);
     return normalise(q ? q[1] : line);
@@ -69,22 +81,27 @@ export function parseRequirementLines(text) {
     }
     return entries;
 }
-/** THE ANTI-SYNTHESIS GUARD: keep only entries whose quote is a normalised
- *  substring of the source doc (same rule as keepGroundedContracts). Does NOT
- *  cap — capping is capRequirements' job, which protects obligation-marked
- *  passages from doc-order truncation. */
-export function keepGroundedRequirements(entries, sourceDoc) {
-    const haystack = normalise(sourceDoc);
+/** THE ANTI-SYNTHESIS GUARD: keep only entries whose quote grounds in a CANDIDATE
+ *  block of the source doc (same rule as keepGroundedContracts, narrowed by the
+ *  policy). A quote whose only match lies in an excluded block is dropped — the
+ *  model is free to propose it, the document decides. Does NOT cap — capping is
+ *  capRequirements' job, which protects obligation-marked passages from doc-order
+ *  truncation. */
+export function keepGroundedRequirements(entries, sourceDoc, policy = REQUIREMENT_POLICY) {
+    const doc = typeof sourceDoc === 'string' ? parseSpecDoc(sourceDoc) : sourceDoc;
+    const accept = candidates(doc, policy);
+    const preamble = new Set(preambleOf(doc));
     const seen = new Set();
     const kept = [];
     for (const e of entries) {
-        const key = normalise(e.quote);
+        const key = normalise(demark(e.quote));
         if (key.length === 0 || seen.has(key))
             continue;
-        if (!haystack.includes(key))
+        const block = groundIn(doc, e.quote, accept);
+        if (block === null)
             continue;
         seen.add(key);
-        kept.push(e);
+        kept.push({ ...e, line: block.line, preamble: preamble.has(block) });
     }
     return kept;
 }
@@ -110,9 +127,9 @@ export function capRequirements(entries, passages, sourceDoc,
 deprioritiseLowValue = true) {
     if (entries.length <= MAX_REQUIREMENTS)
         return entries;
-    const norms = passages.map(normalise);
+    const norms = passages.map(p => normalise(demark(p)));
     const covers = (e) => {
-        const q = normalise(e.quote);
+        const q = normalise(demark(e.quote));
         return norms.some(p => p.includes(q));
     };
     const marked = entries.filter(covers);
@@ -218,24 +235,6 @@ function budgetedByObligation(entries, budget, sourceDoc) {
         .map(x => x.e);
     return [...keep, ...restored];
 }
-/** The doc split into heading-delimited sections, each pre-normalised for
- *  containment tests. Text before the first heading is its own section. */
-function normalisedSections(doc) {
-    const out = [];
-    let current = [];
-    for (const line of doc.replace(/\r\n?/g, '\n').split('\n')) {
-        if (/^#{1,6}\s+\S/.test(line)) {
-            if (current.length > 0)
-                out.push(normalise(current.join('\n')));
-            current = [line];
-            continue;
-        }
-        current.push(line);
-    }
-    if (current.length > 0)
-        out.push(normalise(current.join('\n')));
-    return out.filter(s => s.length > 0);
-}
 /** Round-robin fill across doc sections: bucket each entry by the FIRST section
  *  whose normalised text contains its quote (the same containment rule that
  *  grounded it), take each bucket's entries in in-section order, one per bucket
@@ -246,10 +245,10 @@ function sectionFairFill(entries, budget, sourceDoc) {
         return [];
     if (!sourceDoc)
         return entries.slice(0, budget);
-    const sections = normalisedSections(sourceDoc);
+    const sections = sectionPlains(parseSpecDoc(sourceDoc));
     const buckets = new Map();
     entries.forEach((e, given) => {
-        const q = normalise(e.quote);
+        const q = normalise(demark(e.quote));
         let b = sections.findIndex(s => s.includes(q));
         let at;
         if (b < 0) {
@@ -292,19 +291,23 @@ function sectionFairFill(entries, budget, sourceDoc) {
  * uncoveredPassages() below turns "a marked passage produced no quote" into hard
  * evidence for one forced re-extraction.
  */
-export function enumerateObligationPassages(doc) {
+export function enumerateObligationPassages(doc, policy = REQUIREMENT_POLICY) {
+    const parsed = typeof doc === 'string' ? parseSpecDoc(doc) : doc;
+    const accept = candidates(parsed, policy);
     const out = [];
-    // Normalise CRLF/CR → LF: a Windows-authored spec would otherwise collapse
-    // into one giant paragraph (the split marker never matches `\r\n\r\n`) and
-    // the per-obligation recall floor would enumerate nothing.
-    for (const para of doc.replace(/\r\n?/g, '\n').split(/\n[ \t]*\n/)) {
-        const p = para.trim();
+    // The SAME policy grounding uses. A marked passage no quote can be grounded
+    // in would report itself uncovered forever and force a re-extraction every
+    // round that can never discharge it.
+    for (const b of blocksOf(parsed)) {
+        if (!accept(b))
+            continue;
+        const p = b.text.trim();
         if (p.length < MIN_QUOTE_LENGTH)
             continue;
         if (!/\b(required|must)\b/i.test(p))
             continue;
         out.push(p);
-        if (out.length >= 20)
+        if (out.length >= MAX_OBLIGATION_PASSAGES)
             break;
     }
     return out;
@@ -318,9 +321,9 @@ function passageHead(p) {
  *  extraction recall failed there (a kept quote "covers" a passage when the
  *  passage contains it, normalised). */
 export function uncoveredPassages(passages, kept) {
-    const keptNorm = kept.map(e => normalise(e.quote));
+    const keptNorm = kept.map(e => normalise(demark(e.quote)));
     return passages.filter(p => {
-        const pn = normalise(p);
+        const pn = normalise(demark(p));
         return !keptNorm.some(q => pn.includes(q));
     });
 }
@@ -342,7 +345,7 @@ export const REQUIREMENT_EXTRACT_PROMPT = (feature, passages = []) => [
     'functional behavior, constraints, quality bars, security/accessibility rules, and any',
     'MANDATED METHODOLOGY (testing cadence, verification practice, required scripts, files,',
     'directory structures, databases). Extract from WHATEVER structure the text has —',
-    'numbered sections, tables, bullet lists, or flowing prose with no headings at all.',
+    'numbered sections, bullet lists, or flowing prose with no headings at all.',
     "Pay particular attention to obligations that are NOT part of the text's main",
     'feature/milestone structure (a "required" testing or security section, an obligation',
     'buried mid-prose) — those are the ones downstream planning loses.',
@@ -366,20 +369,24 @@ export const REQUIREMENT_EXTRACT_PROMPT = (feature, passages = []) => [
     'paraphrase, merge, normalise, or complete it; ungrounded quotes are DISCARDED',
     'host-side. (2) Prefer the single sentence or line that states the obligation most',
     'directly. (3) One obligation per line. (4) Do NOT quote examples, rationale, or',
-    'reference links. (5) Never invent a requirement the text does not state.',
+    'reference links. (5) Never invent a requirement the text does not state. (6) Quote',
+    'the PROSE that states the obligation — a quote taken from a code/DDL block, from a',
+    "table row, or from the text's opening description is DISCARDED host-side; where an",
+    'obligation only appears there, quote the sentence that introduces it instead.',
     '',
     'Output the REQUIREMENT: lines and nothing else. If the text states no requirements,',
     'output nothing.'
 ].join('\n');
 /**
  * A requirement no single task can ever OWN: a PROHIBITION (it states what must
- * NOT exist or happen — there is no task that "delivers" an absence) or a GLOBAL
- * POLICY (a product-wide rule every slice obeys, not one slice's deliverable). The
- * per-task coverage map maps both to NONE forever, so left in the `unmapped` set
- * they hold the decompose loop's verdict at INCOMPLETE and make it regenerate the
- * whole plan every round — which can replace a good plan with a worse one. These
- * belong in the CROSS-CUTTING carry, injected verbatim into every task, never fed
- * back as a missing area.
+ * NOT exist or happen — there is no task that "delivers" an absence), a GLOBAL
+ * POLICY (a product-wide rule every slice obeys, not one slice's deliverable), or
+ * a DESCRIPTION (what the product IS, which no slice delivers either). The
+ * per-task coverage map maps all three to NONE forever, so left in the `unmapped`
+ * set they hold the decompose loop's verdict at INCOMPLETE and make it regenerate
+ * the whole plan every round — which can replace a good plan with a worse one.
+ * These belong in the CROSS-CUTTING carry, injected verbatim into every task,
+ * never fed back as a missing area.
  *
  * Deterministic and precision-biased: it only reclassifies clear prohibitions and
  * clearly product-global policies. It does NOT need to catch every un-ownable line
@@ -387,19 +394,52 @@ export const REQUIREMENT_EXTRACT_PROMPT = (feature, passages = []) => [
  * miss here can at most cost one wasted regeneration, never a dropped area. Spec-
  * shape/domain agnostic: pure phrasing, no feature nouns.
  */
-const PROHIBITION_RE = /\b(?:must not|must never|shall not|should not|may not|cannot|can'?t|won'?t|do(?:es)? not|don'?t|doesn'?t|no|not|never|none|without|avoids?|prohibit(?:ed|s|ing)?|forbid(?:den|s)?|disallow(?:ed|s|ing)?|excludes?|excluded|neither|nor)\b/i;
+// Bare `no`, `not` and `none` are NOT here. They read as prohibitions in a
+// grammar that has none: "the page renders even when the user is not logged in"
+// is an ownable behaviour statement, and the bare-negative rule swept it — and
+// everything like it — into a carry no task ever delivers. What remains is modal
+// negation and explicit exclusion verbs, which cannot fire that way.
+const PROHIBITION_RE = /\b(?:must not|must never|shall not|shall never|should not|may not|cannot|can'?t|won'?t|will not|do(?:es)? not|don'?t|doesn'?t|never|without|avoids?|prohibit(?:ed|s|ing)?|forbid(?:den|s)?|disallow(?:ed|s|ing)?|excludes?|excluded|neither|nor)\b/i;
+/** "must have NO runtime dependencies" — the absence shape bare `no` used to
+ *  carry. Anchored to an existence verb AND gated by a modal below, because
+ *  without the modal it is ordinary description: "the empty state shows when
+ *  there are no listings yet" obligates nothing. */
+const NEGATED_EXISTENCE_RE = /\b(?:is|are|be|been|being|has|have|had|contains?|ships?|leaves?|with)\s+no\b/i;
 // Kept narrow on purpose — bare "all"/"every"/"any" appear in plenty of ownable
 // feature statements ("lists all photos"), so the global branch keys only on
 // scope words that name the WHOLE product and is additionally gated by a modal.
 const GLOBAL_SCOPE_RE = /\b(?:everywhere|throughout|always|global(?:ly)?|across (?:the|all|every)|site-?wide|app(?:lication)?-?wide|universal(?:ly)?|consistent(?:ly)?|entire (?:app|application|site|codebase|product|system|ui|project))\b/i;
 const MODAL_RE = /\b(?:must|shall|should|require[sd]?|required|needs? to|has to|have to)\b/i;
-export function isCrossCuttingRequirement(quote) {
+/**
+ * `descriptive` is the class the coverage loop must not chase: a line that says
+ * what the product IS rather than what the work must do. It cost two whole
+ * rejected decompose rounds live — "Invite-only used-parts marketplace for a
+ * local Mazda MX-5 club." was extracted as a requirement, mapped NONE by every
+ * round because no task delivers a sentence, and held the verdict INCOMPLETE.
+ *
+ * Both marks are required, not either: preamble POSITION (above every heading,
+ * where a spec states its subject) and the absence of any modal. A preamble
+ * sentence that does carry a modal is a real obligation stated up front, and a
+ * modal-free sentence anywhere else is the ordinary shape of a feature statement
+ * — treating either alone as descriptive would empty the coverage gate.
+ */
+export function classifyRequirement(quote, fromPreamble = false) {
     const q = quote.trim();
     if (PROHIBITION_RE.test(q))
-        return true;
+        return 'prohibition';
+    if (NEGATED_EXISTENCE_RE.test(q) && MODAL_RE.test(q))
+        return 'prohibition';
     if (GLOBAL_SCOPE_RE.test(q) && MODAL_RE.test(q))
-        return true;
-    return false;
+        return 'global-policy';
+    if (fromPreamble && !MODAL_RE.test(q))
+        return 'descriptive';
+    return 'ownable';
+}
+/** A requirement no single task can ever OWN, judged on the quote alone — the
+ *  shape `groundedCoverage` and the granularity floor get. */
+export function isCrossCuttingRequirement(quote) {
+    const c = classifyRequirement(quote);
+    return c === 'prohibition' || c === 'global-policy';
 }
 /** Requirement INDICES a task owns (a `TASK n` verdict), the monotonic-replacement
  *  signal (coverage-loop.ts). Index-aligned with the requirements list. */
@@ -466,11 +506,13 @@ export function accountCoverage(requirements, mappings) {
             acc.mapped.push({ req: requirements[i], task: m.task });
         else if (m.kind === 'cross')
             acc.crossCutting.push(requirements[i]);
-        // NONE — but a prohibition/global-policy requirement can never be OWNED by
-        // a task (it states an absence or a product-wide rule); the model maps it
-        // NONE every round, which forces endless whole-plan regeneration.
-        // Carry it cross-cutting instead, so it stops driving the coverage loop.
-        else if (isCrossCuttingRequirement(requirements[i].quote))
+        // NONE — but a prohibition, a global policy and a product description can
+        // never be OWNED by a task (an absence, a product-wide rule, a statement of
+        // what the thing IS); the model maps them NONE every round, which forces
+        // endless whole-plan regeneration. Carry them cross-cutting instead, so
+        // they stop driving the coverage loop — carried, never dropped.
+        else if (classifyRequirement(requirements[i].quote, requirements[i].preamble ?? false)
+            !== 'ownable')
             acc.crossCutting.push(requirements[i]);
         else
             acc.unmapped.push(requirements[i]);
@@ -570,6 +612,7 @@ const ownedLedger = makeLedger({
     key: o => normalise(o.quote),
     serialize: o => `OWNED: "${o.quote}"${o.anchor ? ` [anchor: ${o.anchor}]` : ''}`
         + (o.pending && o.pending.length > 0 ? ` [pending: ${o.pending.join(', ')}]` : '')
+        + (o.key ? ` [key: ${o.key}]` : '')
         + ` [title: ${o.title.replace(/\n/g, ' ')}]`,
     parse: parseOwnedRequirements
 });
@@ -587,30 +630,49 @@ export async function readOwnedRequirements(cwd) {
 }
 export function parseOwnedRequirements(text) {
     const out = [];
-    for (const m of text.matchAll(/^OWNED:\s*"([^"\n]+)"(?:\s*\[anchor:\s*([^\]]*)\])?(?:\s*\[pending:\s*([^\]]*)\])?\s*\[title:\s*([^\n]+)\]\s*$/gim)) {
+    for (const m of text.matchAll(/^OWNED:\s*"([^"\n]+)"(?:\s*\[anchor:\s*([^\]]*)\])?(?:\s*\[pending:\s*([^\]]*)\])?(?:\s*\[key:\s*([^\]]*)\])?\s*\[title:\s*([^\n]+)\]\s*$/gim)) {
         const pending = (m[3] ?? '')
             .split(',')
             .map(p => p.trim())
             .filter(p => p.length > 0);
+        const key = (m[4] ?? '').trim();
         out.push({
             quote: m[1].trim(),
             anchor: (m[2] ?? '').trim(),
-            title: m[4].replace(/\]\s*$/, '').trim(),
+            title: m[5].replace(/\]\s*$/, '').trim(),
+            ...(key.length > 0 ? { key } : {}),
             ...(pending.length > 0 ? { pending } : {})
         });
     }
     return out;
 }
+/** A DETACHED entry (`pending`) is owned by nobody until a task claims it, so no
+ *  join returns it — its `title` is provenance, not ownership. */
+const isOwned = (o) => !(o.pending && o.pending.length > 0);
 /** The owned entries whose plan title matches THIS task's title (normalised
  *  equality — titles travel verbatim from the plan list into task creation;
- *  spliced repair tasks simply match nothing). A DETACHED entry (`pending`) is
- *  owned by nobody until a task claims it, so it is never returned here — its
- *  `title` is provenance, not ownership. */
+ *  spliced repair tasks simply match nothing). */
 export function ownedForTitle(owned, title) {
     const t = normalise(title);
     if (t.length === 0)
         return [];
-    return owned.filter(o => normalise(o.title) === t && !(o.pending && o.pending.length > 0));
+    return owned.filter(o => normalise(o.title) === t && isOwned(o));
+}
+/** The owned entries assigned to THIS task's plan entry. */
+export function ownedForKey(owned, key) {
+    return owned.filter(o => o.key === key && isOwned(o));
+}
+/**
+ * THIS task's owned entries. The key is the join; the title is the fallback for a
+ * ledger written before keys existed, and only then — once ANY entry carries a
+ * key the ledger is a keyed one, and a task the plan did not key (a spliced
+ * repair step) owns nothing, which is the same answer the title join gave it.
+ */
+export function ownedForTask(owned, join) {
+    if (join.key !== undefined && owned.some(o => o.key !== undefined)) {
+        return ownedForKey(owned, join.key);
+    }
+    return ownedForTitle(owned, join.title);
 }
 /** The injection block for a task's OWN mapped obligations. Mirrors
  *  buildRequirementsBlock (the directive pattern that measurably works) but is

package/dist/task/research-worker.d.ts

@@ -18,6 +18,7 @@
  * named measure; and `confirmedEmpty` suppresses the silent gate, because that
  * retry already asked "you wrote nothing" and got the same answer.
  */
+import type { ResearchConcurrency } from '../config/config.js';
 import type { RunWorkerInput, RunWorkerResult } from '../workers/pi-worker-core.js';
 import type { SpawnFn } from '../shared/child-process.js';
 import type { DebugLine } from './debug-log.js';
@@ -29,8 +30,17 @@ import type { DebugLine } from './debug-log.js';
 export interface ResearchWorkerSpec {
     section: string;
     label: string;
-    /** Static, or built from the sections completed so far (serial mode hands
-     *  APIS the finished FILES map; parallel mode hands it nothing). */
+    /**
+     * Sections that must be FINISHED before this worker starts — the edges of the
+     * stage's execution graph (see {@link runResearchStage}).
+     *
+     * A dependency is declared because the worker READS the other's output, not to
+     * order the machine: APIS builds on the FILES map, and everything else is free
+     * to run alongside. Absent means "no dependency", which is what lets three of
+     * the four workers overlap.
+     */
+    after?: string[];
+    /** Static, or built from the sections this worker declared it comes `after`. */
     prompt: string | ((prior: ReadonlyArray<{
         name: string;
         text: string;
@@ -178,3 +188,34 @@ export declare function runResearchWorker(spec: ResearchWorkerSpec, run: Researc
     name: string;
     text: string;
 }>;
+/** One finished research section, under the heading compose assembles it by. */
+export interface ResearchSection {
+    name: string;
+    text: string;
+}
+/** How one worker is actually run. The stage schedules; this does the work. */
+export type DriveWorker = (spec: ResearchWorkerSpec, prior: ReadonlyArray<ResearchSection>) => Promise<ResearchSection>;
+/**
+ * Run a stage of research workers, honouring the dependencies they declare.
+ *
+ * WHY A GRAPH. Running the four one at a time cost 24 % of a run's wall clock,
+ * and running them all at once lost the one handoff that matters: APIS is written
+ * against the FILES map, and under a flat `Promise.all` it got nothing. Only ONE
+ * edge exists — the other three questions are independent — so a scheduler that
+ * reads `after` runs FILES, then APIS, with CONTEXT and TOOLING alongside both,
+ * and the handoff survives the concurrency.
+ *
+ * `prior` is a worker's DECLARED dependencies, not "whatever happened to finish".
+ * The second would make a prompt a function of scheduling order, so the same task
+ * would produce different prompts on two machines.
+ *
+ * FAILURE. A worker whose dependency never produced a section does not start; its
+ * independent siblings still finish, so their sections reach the task file for the
+ * resume. The first failure in spec order is then thrown — every worker has
+ * settled by that point, which is what keeps a fatal APIS from orphaning the
+ * three that answered.
+ *
+ * `serial` is preserved for a single local GPU, where concurrent streams share one
+ * device and the sum of four fast workers beats the max of four slowed ones.
+ */
+export declare function runResearchStage(specs: ReadonlyArray<ResearchWorkerSpec>, drive: DriveWorker, mode?: ResearchConcurrency): Promise<ResearchSection[]>;

package/dist/task/research-worker.js

@@ -19,9 +19,10 @@
  * retry already asked "you wrote nothing" and got the same answer.
  */
 import { classifyWorkerFailure } from '../workers/worker-failure.js';
+import { describeLoopHit } from './loop-detector.js';
 import { classifyContextSilence, countBullets } from './context-silence.js';
 import { cancelCheckpoint } from './cancel-points.js';
-import { USER_CANCELLED } from './child-runner.js';
+import { appendLoopEvents, USER_CANCELLED } from './child-runner.js';
 /**
  * Task-file heading under which a research worker's validated output is cached.
  * A resumed research phase reads these to skip workers that already succeeded,
@@ -73,15 +74,11 @@ export function classifyResearchWorker(name, result) {
     const failure = classifyWorkerFailure(result);
     if (failure) {
         switch (failure.kind) {
-            case 'loop': {
-                const argsStr = JSON.stringify(failure.hit.call.args);
+            case 'loop':
                 return {
                     kind: 'runaway',
-                    reason: `stuck in a loop — called ${failure.hit.call.name}(${argsStr}) `
-                        + `×${failure.hit.count} in the last ${failure.hit.windowSize} calls `
-                        + `and still looped after restarts`
+                    reason: `${describeLoopHit(failure.hit)} and did not recover after restarts`
                 };
-            }
             case 'worker-timeout':
                 return { kind: 'runaway', reason: 'timed out after restarts' };
             case 'command-timeout':
@@ -231,7 +228,16 @@ export async function runResearchWorker(spec, run, prior = []) {
     }
     run.logDebug?.(`${spec.label}: start`);
     const basePrompt = typeof spec.prompt === 'function' ? spec.prompt(prior) : spec.prompt;
-    const runOnce = (extraPreamble) => run.record(spec.label, run.runWorker(spec.label, {
+    // A research worker's loop kill is the one the run pays most for — it is
+    // what discards a restart's minutes — and it was the only child whose kills
+    // never reached the task file's `## loop events`, so the trail said the phase
+    // ran clean. Awaited so the section is on disk before the next gate reads it.
+    const runOnce = async (extraPreamble) => {
+        const result = await runWorkerOnce(extraPreamble);
+        await appendLoopEvents(run.cwd, run.taskId, spec.label, result);
+        return result;
+    };
+    const runWorkerOnce = (extraPreamble) => run.record(spec.label, run.runWorker(spec.label, {
         prompt: extraPreamble ? `${extraPreamble}\n\n${basePrompt}` : basePrompt,
         cwd: run.cwd,
         contextWindow: run.contextWindow,
@@ -416,3 +422,92 @@ export async function runResearchWorker(spec, run, prior = []) {
     }
     return { name: spec.section, text: sectionText };
 }
+/**
+ * Run a stage of research workers, honouring the dependencies they declare.
+ *
+ * WHY A GRAPH. Running the four one at a time cost 24 % of a run's wall clock,
+ * and running them all at once lost the one handoff that matters: APIS is written
+ * against the FILES map, and under a flat `Promise.all` it got nothing. Only ONE
+ * edge exists — the other three questions are independent — so a scheduler that
+ * reads `after` runs FILES, then APIS, with CONTEXT and TOOLING alongside both,
+ * and the handoff survives the concurrency.
+ *
+ * `prior` is a worker's DECLARED dependencies, not "whatever happened to finish".
+ * The second would make a prompt a function of scheduling order, so the same task
+ * would produce different prompts on two machines.
+ *
+ * FAILURE. A worker whose dependency never produced a section does not start; its
+ * independent siblings still finish, so their sections reach the task file for the
+ * resume. The first failure in spec order is then thrown — every worker has
+ * settled by that point, which is what keeps a fatal APIS from orphaning the
+ * three that answered.
+ *
+ * `serial` is preserved for a single local GPU, where concurrent streams share one
+ * device and the sum of four fast workers beats the max of four slowed ones.
+ */
+export async function runResearchStage(specs, drive, mode = 'graph') {
+    if (mode === 'serial') {
+        const done = [];
+        for (const spec of specs)
+            done.push(await drive(spec, done));
+        return done;
+    }
+    const bySection = new Map(specs.map(s => [s.section, s]));
+    assertSchedulable(specs, bySection);
+    const done = new Map();
+    const failed = new Map();
+    const started = new Map();
+    const run = (spec) => {
+        const inFlight = started.get(spec.section);
+        if (inFlight)
+            return inFlight;
+        const after = spec.after ?? [];
+        const p = (async () => {
+            await Promise.all(after.map(dep => run(bySection.get(dep))));
+            if (after.some(dep => !done.has(dep)))
+                return;
+            try {
+                done.set(spec.section, await drive(spec, after.map(dep => done.get(dep))));
+            }
+            catch (e) {
+                failed.set(spec.section, e);
+            }
+        })();
+        started.set(spec.section, p);
+        return p;
+    };
+    await Promise.all(specs.map(run));
+    for (const spec of specs) {
+        if (failed.has(spec.section))
+            throw failed.get(spec.section);
+    }
+    return specs.flatMap(s => {
+        const section = done.get(s.section);
+        return section ? [section] : [];
+    });
+}
+/**
+ * Reject a graph the scheduler cannot run before any child is spawned: an `after`
+ * naming a section that is not in this stage, or a cycle. Either would otherwise
+ * surface as a research phase that never returns.
+ */
+function assertSchedulable(specs, bySection) {
+    const settled = new Set();
+    const walk = (spec, chain) => {
+        if (settled.has(spec.section))
+            return;
+        if (chain.includes(spec.section)) {
+            throw new Error(`research stage: dependency cycle ${[...chain, spec.section].join(' → ')}`);
+        }
+        for (const dep of spec.after ?? []) {
+            const next = bySection.get(dep);
+            if (!next) {
+                throw new Error(`research stage: ${spec.section} declares after: ${dep}, which is not a worker`);
+            }
+            walk(next, [...chain, spec.section]);
+        }
+        settled.add(spec.section);
+    };
+    for (const spec of specs)
+        walk(spec, []);
+}

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

@@ -4,14 +4,16 @@
  * Every long-running command — `/task`, `/task-auto`, `/task-auto-resume`,
  * `/task-plan`, and `TaskRunner.run` inside all of them — spends most of its
  * life with the host session idle: the spec phases, the planning children and
- * every gate are child `pi` processes, not host turns. Two things must be true
- * for exactly that window, and both are refcounted because the runs nest
- * (`/task-auto` brackets its loop, each task inside brackets its own run):
+ * every gate are child `pi` processes, not host turns. Three things must be true
+ * for exactly that window, and all of them account for nesting because the runs
+ * nest (`/task-auto` brackets its loop, each task inside brackets its own run):
  *
  *   1. mid-run input is HELD, not queued or turned into a competing turn
  *      (`mid-run-input.ts`: `beginRun`/`endRun`);
  *   2. the raw-stdin interception that makes the terminal behave like the
- *      browser is ARMED (`cancel-input.ts`: `armCancelListener`/`disarm…`).
+ *      browser is ARMED (`cancel-input.ts`: `armCancelListener`/`disarm…`);
+ *   3. the run's per-project facts are DERIVED ONCE and shared by every task in
+ *      it (`run-context.ts`: `openRunContext`/`closeRunContext`).
  *
  * The teardown order is not observable — both halves are synchronous, the
  * listener only consults `isRunActive()` on a keystroke, and no keystroke can
@@ -27,6 +29,9 @@
  * driving the other's lifecycle, or a third counter with both modules demoted to
  * flags — a wider change than the drift it prevents. What prevents drift now is
  * that this bracket is the ONLY production caller of either pair.
+ *
+ * The run context counts nothing: it is opened by the outermost bracket only, and
+ * an inner one is handed the same object.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 export interface RunBracketOptions {

package/dist/task/run-bracket.js

@@ -4,6 +4,7 @@ import { reportDroppedInput } from './dropped-input.js';
 import { publishLifecycleNotice } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { resetCancel } from './cancel-points.js';
+import { closeRunContext, openRunContext } from './run-context.js';
 /**
  * Run `fn` as the owner of the session: hold mid-run input and arm the terminal
  * interception for exactly its duration, then release both — on return AND on
@@ -22,6 +23,12 @@ export async function withRun(ctx, opts, fn) {
         resetCancel();
     beginRun();
     armCancelListener(ctx, opts.onCancel);
+    // The run's per-project facts live as long as the OUTERMOST bracket: one
+    // inventory, one orientation core, one set of verified tooling commands for
+    // every task inside it. An inner bracket joins that run rather than opening
+    // its own — and must not close it either, which is why this follows
+    // `outermost` instead of refcounting a third time.
+    const runContext = outermost ? openRunContext(ctx.cwd) : null;
     try {
         return await fn();
     }
@@ -29,6 +36,8 @@ export async function withRun(ctx, opts, fn) {
         disarmCancelListener();
         if (outermost)
             resetCancel();
+        if (runContext)
+            closeRunContext(runContext);
         reportDroppedInput(endRun(), ctx);
     }
 }