@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/task/phases.d.ts

@@ -46,8 +46,8 @@ export interface PhaseConfig {
      * 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.
+     * wrote it. A resume at critique hands the refuted constraint straight
+     * back — the 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.
@@ -84,41 +84,41 @@ export declare function refineExistingFilesBlock(deps: PhaseDeps): Promise<strin
 export declare function phaseContractsBlock(deps: PhaseDeps): Promise<string>;
 /**
  * The carried-context blocks a GENERATIVE phase (refine, compose) receives: the
- * cross-slice contracts plus the carried cross-cutting requirements (mx5 run 11,
- * goals A/C — `.pi-tasks/requirements.md`, written at plan time). The verbatim
- * requirement quotes travel INTO every task's spec generation, so a mandated
- * methodology ("a test lands in the same change as each new route") reaches the
- * task's GOAL/CONSTRAINTS and its VERIFY — a pointer back to the spec doc
- * recovered the dropped §10 in only 1 of ~6 applicable run-11 tasks; content
- * travels, pointers don't. Both blocks are '' outside their runs, so a bare
- * /task is byte-identical to before.
+ * cross-slice contracts plus the carried cross-cutting requirements
+ * (`.pi-tasks/requirements.md`, written at plan time). The verbatim requirement
+ * quotes travel INTO every task's spec generation, so a mandated methodology
+ * ("a test lands in the same change as each new route") reaches the task's
+ * GOAL/CONSTRAINTS and its VERIFY. Content travels; a pointer back to the spec
+ * doc does not. Both blocks are '' outside a /task-auto run, so a bare /task
+ * sees no change.
  */
 export declare function phaseCarriedBlocks(deps: PhaseDeps): Promise<string>;
 /**
- * DETACH (nexttask 2) — an owned requirement this task cannot satisfy, because a
+ * DETACH — an owned requirement this task cannot satisfy, because a
  * category freeze in the very spec that carries it covers the only file that
  * could, stops being this task's obligation and is released to whichever later
  * task writes that file.
  *
  * Runs at the LAST spec-producing step, where the pair first exists: the stamped
  * bullet is written one statement earlier by `appendOwnedConstraints`, and a
- * critique-time probe measured 0/40 because the stamp did not exist yet. It
- * never edits prose and never asks a model — the run-18 rewrite lever resolved
- * 11 of 20 pairs by DELETING the authoritative clause. The quote stays in the
- * ledger throughout; only its owner changes.
+ * critique-time probe would find nothing because the stamp does not exist yet.
+ * It never edits prose and never asks a model — a model asked to remove a
+ * contradiction can satisfy the request by DELETING the authoritative clause,
+ * which is not satisfaction of the requirement. The quote stays in the ledger
+ * throughout; only its owner changes.
  */
 export declare function resolveOwnedFreezeForThisTask(deps: PhaseDeps, spec: string): Promise<string>;
 /**
- * CLAIM (nexttask 2) — the other half. A requirement detached by an earlier task
+ * CLAIM — the other half. A requirement detached by an earlier task
  * becomes THIS task's own when its refined prompt says it writes the frozen
  * file. Run before compose builds its carried blocks, so the claimed obligation
  * rides the same belt every owned requirement does and the braces stamp it onto
  * this spec.
  *
- * The claimant is the only party that knows: at detach time the later tasks are
- * bare plan titles, and none of mx5 run 19's 26 titles contains the path. Over
- * the same run's 26 REFINED prompts, `writeIntent` picks out exactly the two
- * tasks that write the server file.
+ * The claimant is the only party that knows. At detach time the later tasks are
+ * bare plan titles, and a plan title names a slice of behaviour rather than a
+ * file. By its own compose a task has a REFINED prompt, which does say which
+ * files it will write — and that is what `writeIntent` reads.
  */
 export declare function claimOwnedFreezeForThisTask(deps: PhaseDeps, refined: string): Promise<void>;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: string) => Promise<string>;
@@ -127,10 +127,10 @@ export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): P
  * The worker channels the APIS research worker is given.
  *
  * `pi-worker-search` + `pi-worker-fetch` ride along only when the configured
- * engine is usable (a keyless engine always is; brave needs its key). A tool
- * without a key just errors, and a weak model burns calls on it — while search
- * being ABSENT was structural in the other direction: three consecutive audited
- * runs made 0 search calls because the child literally did not have the tool.
+ * engine is usable. `searchConfigured` decides: exa and ddg are keyless and
+ * always usable, brave is usable only with its key. A keyless tool that errors
+ * on every call is something a weak model burns calls on; a tool the child was
+ * never handed is a channel it cannot use at all, however the prompt is worded.
  *
  * Both halves of "given a channel" — the tools string and the `-e` path — come
  * from the same rows, so they cannot disagree.
@@ -151,9 +151,9 @@ export declare const RESEARCH_SEARCH_HINT: string;
  * In-process guards loaded into the TOOLING worker only: block a re-read of any
  * file already read, and block any byte-identical grep/find/ls repeat, feeding
  * the model "you already have this, answer now" instead of letting it re-run.
- * TOOLING reads each file once and never needs an identical search twice in any
- * healthy recorded run, so neither rule has a legitimate false positive here.
- * See single-read-guard.ts.
+ * TOOLING's job is to name verification commands, so it has no reason to read a
+ * file twice or repeat a search byte for byte — which is what makes both rules
+ * safe to arm HERE and nowhere else. See single-read-guard.ts.
  */
 export declare const SINGLE_READ_EXTENSION_PATH: string;
 /**
@@ -161,15 +161,13 @@ export declare const SINGLE_READ_EXTENSION_PATH: string;
  * cares about — never the per-file edit list. Big refined prompts embed a long
  * bulleted "fix these files" checklist *inside* the GOAL block; handing that to
  * a weak local model drags it into reading/grepping source it doesn't need and
- * it loops (TASK_0017: read(sql-adapter.ts) ×5 → loop-kill → fails the phase).
+ * it loops.
  * So scope TOOLING's view to the GOAL prose, truncated at the first bullet.
  *
  * Fallbacks, in order: no bare `GOAL` header (free-form refined) → the whole
  * refined unchanged; a GOAL block with no bullets → the full GOAL block. The
  * GOAL boundary is the next bare ALL-CAPS header (CONSTRAINTS, KNOWN-UNKNOWNS,
- * …) or end of text. Verified against every recorded refined prompt: the
- * bullet-heavy failure case drops 3319→329 chars with zero source-file
- * mentions; the rest are unchanged or only lightly trimmed.
+ * …) or end of text.
  */
 export declare function scopedToolingGoal(refined: string): string;
 export declare function phaseResearch(deps: PhaseDeps, refined: string): Promise<string>;
@@ -192,8 +190,6 @@ export declare function phaseGrill(deps: PhaseDeps, ctx: ExtensionCommandContext
  * the same place. The task file's `## refined prompt` is deliberately left as
  * refine wrote it; the drop is recorded on the `## gates` trail with both source
  * lines quoted, so the decision stays auditable after the fact.
- *
- * 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>;
 /**
@@ -213,11 +209,9 @@ export declare function phaseCritique(deps: PhaseDeps, spec: string, refined: st
  * An additional deterministic defect block, forced into the rewrite exactly
  * like the probes below and overriding a CLEAN triage the same way.
  *
- * This is the A/B seam for a probe that is not wired yet: the discipline
- * here is "wire only on PASS" (memory/prompt4-spec-urls-failed.md), so a
- * candidate probe has to be measurable through the SHIPPED critique path
- * rather than through a hand-copied replica of it, or the two arms differ by
- * more than the probe. Undefined in production.
+ * The seam exists so a candidate probe can be exercised through the SHIPPED
+ * critique path rather than through a hand-copied replica of it — otherwise a
+ * comparison differs by more than the probe. Undefined in production.
  */
 extraDefects?: string | null): Promise<string>;
 export declare function critiqueWithFallback(d: PhaseDeps, p: PhaseContext): Promise<string>;
@@ -225,8 +219,8 @@ export declare function critiqueWithFallback(d: PhaseDeps, p: PhaseContext): Pro
  * 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
+ * loses: the affirmative survives into the composed GOAL and on to the
+ * implementer, because compose re-leaks it. 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.
  */
@@ -255,26 +249,25 @@ export declare function composePhase(d: PhaseDeps, p: PhaseContext): Promise<str
  * 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
+ * BRACES: append any owned design obligation the spec still omits as a
+ * CONSTRAINTS bullet. The belt block upstream is obeyed only sometimes; 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.
+ * the append is what writes the stamp the detach reads, so a critique-time probe
+ * would find nothing.
  */
 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.
+ * step is drivable directly instead of only through a whole TaskRunner run. That
+ * matters because a step's parts can each be correct while the order they run in
+ * is wrong — see `runPhaseRow`, which is the surface that pins the order.
  */
 export declare const PHASES: PhaseConfig[];
 /**