@mjasnikovs/pi-task 0.38.15 → 0.38.17

package/dist/task/phases.d.ts

@@ -3,12 +3,7 @@
  * critique) plus the config table that drives the orchestrator loop.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
-import { docsFocused } from '../workers/docs-core.js';
-import { fetchFocused } from '../workers/fetch-core.js';
-import { type RunWorkerInput, type RunWorkerResult } from '../workers/pi-worker-core.js';
-import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
-import type { SearchProvider } from '../workers/search-types.js';
-import { type ExternalContextDeps } from './external-context.js';
+import { type SearchProvider } from '../workers/search-types.js';
 import { MAX_GRILL_QUESTIONS } from './prompts.js';
 import { type PhaseName } from './task-types.js';
 import { type WidgetState } from './widget.js';
@@ -38,7 +33,34 @@ export interface PhaseConfig {
     name: PhaseName;
     section: string;
     field: OutputField;
+    /**
+     * The pure, idempotent transform this phase performs on `PhaseContext` fields
+     * OTHER than its own `field` — the phase's CARRY. Mutates `pc` and returns the
+     * trail lines the decision produced; it performs no I/O of its own.
+     *
+     * A carry runs on BOTH arms of the orchestrator loop: before `run` on the live
+     * path, and in place of `run` on the resume path. That is the whole point. A
+     * row's `section` is what resume restores from disk, and it restores exactly
+     * ONE field — so a phase that settles a second field and does not declare it
+     * here silently loses that work on every resume past it. Compose is the case
+     * that matters: it drops constraints research REFUTED from `refined`, critique
+     * re-reads `refined` as GROUND TRUTH under a prompt that says CONSTRAINTS "MUST
+     * be preserved", and `## refined prompt` on disk is deliberately left as refine
+     * wrote it. A resume at critique used to hand the refuted constraint straight
+     * back — the mx5 run-19 defect, restored by the very machinery that closed it.
+     *
+     * The trail is returned rather than written so the replay cannot duplicate a
+     * gate line the live run already recorded.
+     */
+    carry?: (deps: PhaseDeps, pc: PhaseContext) => Promise<string[]>;
     run: (deps: PhaseDeps, pc: PhaseContext) => Promise<string>;
+    /**
+     * What this phase must do once its output is PERSISTED — after the section
+     * write, so a fault here cannot lose the output. A row field rather than a
+     * `phase.name !== 'refine'` test inside one function, so the compiler can tell
+     * you which rows have a post-commit effect.
+     */
+    postCommit?: (deps: PhaseDeps, pc: PhaseContext, out: string) => Promise<void>;
 }
 /** Extract the TOOLING section commands from a research output string. */
 export declare function extractToolingCommands(research: string): string[] | null;
@@ -101,29 +123,9 @@ export declare function resolveOwnedFreezeForThisTask(deps: PhaseDeps, spec: str
 export declare function claimOwnedFreezeForThisTask(deps: PhaseDeps, refined: string): Promise<void>;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: string) => Promise<string>;
 export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): Promise<string>;
-export interface PhaseResearchDeps extends ExternalContextDeps {
-    getFileInventory?: (cwd: string, signal?: AbortSignal) => Promise<string>;
-    /**
-     * Run ONE research worker. Absent (production) → the real `runWorker`.
-     *
-     * The seam exists for the same reason `getFileInventory` does: every decision
-     * `runSpec` makes — the three Research retry gates, the fatal/runaway/empty
-     * classification, the marker choice, `postProcess` — is a pure function of the
-     * returned `RunWorkerResult`, but reaching any of them used to require driving
-     * a fake process that emits JSON events. Substituting the result lets a gate be
-     * tested by the fields it actually reads.
-     *
-     * `label` is the worker's name — the same one `recordWorker` trails. It is
-     * passed because a substitute must answer differently per worker, and the only
-     * alternative is matching a marker sentence inside the prompt, which makes
-     * prompt copy load-bearing test infrastructure. Same reason
-     * `PhaseDeps.runChild` takes a name.
-     */
-    runWorker?: (label: string, input: RunWorkerInput) => Promise<RunWorkerResult>;
-}
 /**
  * Is live web search configured for this process? The keyless providers (exa,
- * ddg) always are; only brave needs its API key — mirrors search-core's lookup.
+ * ddg) always are; only brave needs its API key.
  */
 export declare function searchConfigured(getEnv?: (k: string) => string | undefined, provider?: SearchProvider): boolean;
 /** Extra prompt block for the APIS worker when search is available — trigger-framed
@@ -177,13 +179,8 @@ export declare function degradedSectionBody(name: string, reason: string, partia
  */
 export declare function emptySectionBody(name: string): string;
 export declare function isBareNoneAnswer(text: string): boolean;
-export declare function phaseResearch(deps: PhaseDeps, refined: string, researchDeps?: PhaseResearchDeps): Promise<string>;
-export interface PhaseAutoAnswerDeps {
-    docsFocused?: typeof docsFocused;
-    fetchFocused?: typeof fetchFocused;
-    searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
-}
-export declare function phaseAutoAnswer(deps: PhaseDeps, refined: string, research: string, question: string, autoDeps?: PhaseAutoAnswerDeps): Promise<AutoAnswer>;
+export declare function phaseResearch(deps: PhaseDeps, refined: string): Promise<string>;
+export declare function phaseAutoAnswer(deps: PhaseDeps, refined: string, research: string, question: string): Promise<AutoAnswer>;
 export declare function phaseGrill(deps: PhaseDeps, ctx: ExtensionCommandContext, widgetState: WidgetState, refined: string, research: string): Promise<string>;
 /**
  * A refutation is a DELETION. Where the run's own research explicitly says a
@@ -206,6 +203,17 @@ export declare function phaseGrill(deps: PhaseDeps, ctx: ExtensionCommandContext
  * STEP 0 `scripts/refuted-constraint-baserate.ts`; A/B-1 `…-ab.ts` (PASS).
  */
 export declare function dropRefutedConstraints(deps: PhaseDeps, refined: string, research: string): Promise<string>;
+/**
+ * COMPOSE's carry: the refutation drop, as a `PhaseConfig.carry`.
+ *
+ * Same transform as `dropRefutedConstraints` over the same pure core, minus the
+ * recording — the caller decides whether this application is the live one or a
+ * resume replay. `dropRefutedConstraints` stays exported and unchanged for the
+ * harnesses under `scripts/` that drive the drop directly.
+ */
+export declare function composeCarry(_deps: PhaseDeps, pc: PhaseContext): Promise<string[]>;
+/** Write a carry's trail to the debug log and the task file's `## gates` section. */
+export declare function recordPhaseTrail(deps: PhaseDeps, phaseName: string, trail: string[]): Promise<void>;
 export declare function phaseCompose(deps: PhaseDeps, refined: string, research: string, qa: string): Promise<string>;
 export declare function phaseCritique(deps: PhaseDeps, spec: string, refined: string, qa: string, planContext?: string, research?: string, 
 /**
@@ -220,5 +228,83 @@ export declare function phaseCritique(deps: PhaseDeps, spec: string, refined: st
  */
 extraDefects?: string | null): Promise<string>;
 export declare function critiqueWithFallback(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * REFINE — restate the raw prompt as a bounded 4-section spec, then subtractively
+ * strike any phantom runtime specifier (`bun:sql`) it carried up verbatim from the
+ * spec doc, BEFORE it flows to research/grill/compose. An appended correction alone
+ * loses: the affirmative survives into the composed GOAL and on to the implementer
+ * (proven: compose re-leaks it 4/4). Rewriting the source so compose has nothing to
+ * contradict is the fix. Silent + no-op when nothing is wrong or the runtime's types
+ * aren't installed.
+ */
+export declare function refinePhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * RESEARCH — the four workers, then the TOOLING verification pass, then a
+ * deterministic check of every runtime builtin specifier the refined task names
+ * (`bun:sql`, `node:…`) against the installed types. A doc can confidently name a
+ * module that does not exist; left unchecked it rides through every phase and the
+ * implementer fabricates a `declare module` shim to compile it. The corrections are
+ * APPENDED so compose folds them into CONSTRAINTS. No LLM cost, silent when clean.
+ */
+export declare function researchPhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/** GRILL — the adaptive question loop, and the only phase that talks to the user. */
+export declare function grillPhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * COMPOSE — compose the spec from the refined task, the research and the Q&A.
+ *
+ * The refutation drop that must happen first is compose's declared `carry`
+ * (`composeCarry`), not a line at the top of this function. It settles `p.refined`,
+ * which is not compose's own `field`, so the orchestrator has to replay it on the
+ * resume path too — and a `run` body cannot be replayed.
+ */
+export declare function composePhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * CRITIQUE — the last spec-producing step, and the two host-side corrections that
+ * must run after it in THIS ORDER.
+ *
+ * BRACES (mx5 run 16): append any owned design obligation the spec still omits as a
+ * CONSTRAINTS bullet. The belt block upstream is obeyed ~25% (measured); a host-side
+ * append is obeyed by construction. Idempotent — quotes the spec already carries
+ * (belt-obeying reps) are skipped.
+ *
+ * Then DETACH: an owned obligation whose only file this spec also FREEZES is
+ * unsatisfiable here, so it moves to the pending task that writes that file rather
+ * than shipping a requirement no one can meet. It MUST run after the append, because
+ * the append is what writes the stamp the detach reads — a critique-time probe
+ * measured 0/40 because the stamp did not exist yet.
+ */
+export declare function critiquePhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
+/**
+ * The pipeline, as a table with no bodies.
+ *
+ * Every row's `run` is a named exported function, so the COMPOSITION inside a
+ * step — which is where this codebase's recorded phase defects have lived, not in
+ * the parts — is drivable directly instead of only through a whole TaskRunner run.
+ * The parts stay exported and separately covered; what changed is that the ORDER
+ * they run in is now asserted by driving the row rather than retyped in a test.
+ */
 export declare const PHASES: PhaseConfig[];
+/**
+ * Run one phase row the way the orchestrator does: carry, then run.
+ *
+ * The row is the interface, so this is the surface a row-driving test crosses —
+ * calling `row.run` alone tests past it and would not have caught a carry that the
+ * resume path drops. The orchestrator adds only persistence, timings and the
+ * checkpoint around this.
+ */
+export declare function runPhaseRow(row: PhaseConfig, deps: PhaseDeps, pc: PhaseContext): Promise<string>;
+/**
+ * Re-apply one phase row's carry on the RESUME path, where `run` is skipped.
+ *
+ * The trail is discarded: the live run that produced this phase's output already
+ * recorded it on `## gates`, and a replay must not append a second copy.
+ */
+export declare function replayPhaseCarry(row: PhaseConfig, deps: PhaseDeps, pc: PhaseContext): Promise<void>;
+/** Dispatch a row's declared post-commit effect. Rows with none do nothing. */
 export declare function postCommitPhase(phase: PhaseConfig, deps: PhaseDeps, pc: PhaseContext, out: string): Promise<void>;
+/**
+ * REFINE's post-commit: derive the task title from the refined prompt, then a short
+ * display label. Runs after the section write, so a fault here cannot lose the
+ * output it reads.
+ */
+export declare function refinePostCommit(deps: PhaseDeps, pc: PhaseContext, out: string): Promise<void>;