@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/owned-freeze-reassign.js

@@ -1,69 +1,49 @@
 /**
  * owned-freeze-reassign — the DETERMINISTIC resolution for the owned/freeze
- * unsatisfiable pair (nexttask 2): an AUTHORITATIVE owned requirement whose only
- * implementing file the same spec FREEZES. No model, no prose edit. The
- * requirement text is never altered — only which task's ledger entry carries it,
- * so "resolution by deletion" is structurally impossible.
- *
- * WHY NOT A REWRITE. Measured on mx5 run 18 (scripts/live-owned-freeze-conflict
- * -ab.ts, 20 trials/arm): forcing the pair through the critique seam drives
- * pair-present 8/20 → 0/20, but 11 of the 20 resolutions DELETE the
- * AUTHORITATIVE clause instead of moving it, and the delivered VERIFY still
- * greps `package.json` in both arms (6/20). Removal of the pair is not
- * satisfaction of the requirement.
+ * unsatisfiable pair: an AUTHORITATIVE owned requirement whose only implementing
+ * file the same spec FREEZES. No model, no prose edit. The requirement text is
+ * never altered — only which task's ledger entry carries it, so "resolution by
+ * deletion" is structurally impossible. That is the whole point: a model asked to
+ * remove a contradiction can satisfy the request by deleting the requirement, and
+ * removal of the pair is not satisfaction of the requirement.
  *
  * ── THE MECHANISM: DETACH, then CLAIM ───────────────────────────────────────
  *
  * Two steps, each run where the information it needs actually exists:
  *
- *   DETACH  at the conflicting task's own critique (right after the braces
- *           stamp the bullet, which is the first moment the pair exists): the
- *           entry is marked `pending: [frozen paths]` in the ledger and its
- *           stamped bullet is dropped from this spec. It is now owned by
- *           nobody; `ownedForTitle` skips it; the quote is still there, byte for
- *           byte.
- *   CLAIM   at every LATER task's compose, before the belt block is built: if
- *           that task's REFINED PROMPT shows a write intent on one of the
- *           pending paths, the entry becomes that task's own — belt into its
- *           compose, braces onto its spec.
- *
- * ── WHY NOT "PICK THE TARGET AT DETACH TIME", WHICH IS WHAT nexttask2.md ASKS ─
- *
- * nexttask2.md's branch 1 is "if exactly one OTHER task in the plan names path
- * `P` — its title or its spec's file list contains `P` — move the requirement
- * there". Measured over all 60 recorded composed specs on disk
- * (scripts/owned-freeze-reassign-baserate.ts), on the one conflict the corpus
- * contains (mx5 run 19 TASK_0015, path `src/server/index.ts`):
+ *   DETACH  at the conflicting task's own critique (`critiquePhase`, right after
+ *           `appendOwnedConstraints` stamps the bullet, which is the first moment
+ *           the pair exists): the entry is marked `pending: [frozen paths]` in the
+ *           ledger and its stamped bullet is dropped from this spec. It is now
+ *           owned by nobody; `ownedForTitle` skips it; the quote is still there,
+ *           byte for byte.
+ *   CLAIM   at every LATER task's compose, before the belt block is built: if that
+ *           task's REFINED PROMPT shows a write intent on one of the pending
+ *           paths, the entry becomes that task's own — belt into its compose,
+ *           braces onto its spec. First claimant wins.
  *
- *     title-only    3 candidates   TASK_0014 TASK_0016 TASK_0017
- *     FILES-only    7 candidates   TASK_0016 … TASK_0025
- *     either        8 candidates   → "exactly one" NEVER holds
+ * ── WHY NOT "PICK THE TARGET AT DETACH TIME" ─────────────────────────────────
  *
- * and, decisively, that measurement is against RECORDED SPECS, which production
- * does not have: at the conflicting task's compose the later tasks are still
- * bare plan titles. None of run 19's 26 plan titles contains the string
- * `src/server/index.ts` — TASK_0017's reads "Client API layer — typed
- * hono/client hc<AppType> in api.ts, small fetch/mutation hooks, SPA fallback
- * route on server". A path-lexical target rule at detach time is therefore
- * BLIND IN PRODUCTION (0 candidates), the same way the run-18 critique probe was.
+ * The obvious rule is "if exactly one OTHER task in the plan names path `P`, move
+ * the requirement there". It needs COMPOSED SPECS, and at the conflicting task's
+ * compose the later tasks are still bare plan titles. A plan title describes a
+ * slice of behaviour, not a file list, so a path-lexical target rule at detach
+ * time finds nothing to point at.
  *
- * The claimant knows what the planner did not. By its own compose, TASK_0017 has
- * a refined prompt that says "add an SPA fallback route to the existing server
- * `src/server/index.ts`". Over run 19's 26 refined prompts, `writeIntent` on that
- * path fires on exactly two: TASK_0014 (which created the file, already run) and
- * TASK_0017. Nothing else in the plan claims it — six other specs mention the
- * path, all of them to fence themselves off it.
+ * The claimant knows what the planner did not. By its own compose the later task
+ * has a REFINED prompt, which does say which files it will write — and
+ * `writeIntent` reads exactly that, while its negation fence keeps every sibling
+ * that merely mentions the path in order to fence itself off it.
  *
- * ── WHY NOT nexttask2.md's BRANCH 2 (CARRY EVERYTHING CROSS-CUTTING) ────────
+ * ── WHY NOT CARRY IT AS CROSS-CUTTING ────────────────────────────────────────
  *
  * The cross-cutting channel is for prohibitions and product-wide rules
- * (`isCrossCuttingRequirement`; `accountCoverage` only routes those there). The
- * corpus conflict is a task-specific deliverable clause — carrying it would push
- * "the server serves static `dist/`" into the 11 tasks that had not yet run,
- * none of which owns the server file. That is spec inflation dressed as a fix.
- * An entry nobody claims stays `pending` and is surfaced at the end of the run
- * (`unclaimedPendingRequirements`), which is a debt the run can see rather than
- * an obligation that quietly evaporated.
+ * (`isCrossCuttingRequirement`; `accountCoverage` only routes those there). A
+ * task-specific deliverable clause carried that way lands in every task that has
+ * not run yet, none of which owns the file — spec inflation dressed as a fix. An
+ * entry nobody claims stays `pending` and `unclaimedPendingRequirements` surfaces
+ * it at the end of the run (run-final-gate.ts), so it becomes a debt the run can
+ * see rather than an obligation that quietly evaporated.
  */
 import { findOwnedFreezeConflicts } from './owned-freeze-conflict.js';
 import { ownedForTitle } from './requirements.js';
@@ -72,11 +52,10 @@ import { PROHIBITION_RE } from './prohibition-probe.js';
  * Does this text CLAIM a write on `p` — a create/modify verb reaching a mention
  * of the path, not fenced by a negation?
  *
- * The negation half is not decoration. Every sibling task's refined prompt names
- * the files it must not touch ("Do not create or modify any other files outside
- * this slice (e.g., no changes to `src/server/index.ts`, …)" — mx5 run 19
- * TASK_0008). Without the fence check that spec claims the server file; with it,
- * run 19's 26 refined prompts yield exactly the two tasks that do write it.
+ * The negation half is not decoration. A refined prompt routinely names the files
+ * its task must NOT touch, in the same sentence as a write verb — "Do not create
+ * or modify any other files outside this slice (e.g. no changes to `X`)". Without
+ * the fence check, every such sibling claims `X`.
  */
 export function writeIntent(text, p) {
     const re = new RegExp(String.raw `\b(?:creat|add|implement|modif|updat|extend|wir|writ|mount|chang)\w*\b`
@@ -84,7 +63,7 @@ export function writeIntent(text, p) {
         + p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
     for (const m of text.matchAll(re)) {
         // The negation usually sits BEFORE the verb, so the window reaches back
-        // past it — matching only the verb→path span misses TASK_0008 entirely.
+        // past it — matching only the verb→path span misses a fenced spec entirely.
         const from = Math.max(0, (m.index ?? 0) - 90);
         const window = text.slice(from, (m.index ?? 0) + m[0].length);
         if (NEGATED_RE.test(window) || PROHIBITION_RE.test(window))
@@ -171,8 +150,9 @@ export function detachUnsatisfiableRequirements(args) {
  * pending paths its refined prompt writes. Run at the START of compose, so the
  * claimed obligation rides the same belt block every owned requirement does.
  *
- * First claimant wins (`inv-single-owner`): the entry stops being pending the
- * moment it is claimed, so a later task cannot take it as well.
+ * First claimant wins: `delete entry.pending` runs before the entry is retitled,
+ * so a later task finds nothing pending to take. The test named
+ * `inv-single-owner` pins that.
  */
 export function claimPendingRequirements(args) {
     const out = { ledger: args.ledger.map(o => ({ ...o })), actions: [] };

package/dist/task/parsers.d.ts

@@ -12,8 +12,10 @@
  *     bare recommendation): a genuine open fork carrying a best-effort suggestion.
  *   - 'api-synthesis' — the answer was ANSWERED, then DEMOTED because it names an
  *     API identifier absent from the research and the question, in a namespace the
- *     research covers (mx5 run 13: an invented `Bun.mkdirSync` reached requirements
- *     AND the VERIFY block). The suggestion rides along for a HUMAN to judge.
+ *     research covers. `Bun.mkdirSync` is the shape: bun-types declares no such
+ *     member, but an answer naming it reads as authoritative and can reach both
+ *     requirements and the VERIFY block. The suggestion rides along for a HUMAN
+ *     to judge.
  *   - 'integration' — an integration/build-wiring unknown no fetched doc grounded;
  *     a wrong guess is a structural landmine, so the model's answer is offered as
  *     a recommendation instead of being taken silently.

package/dist/task/parsers.js

@@ -224,10 +224,10 @@ export function deriveTitle(refined) {
 }
 // ─── Display label ───────────────────────────────────────────────────────────
 //
-// `title` is stored in full (a refine GOAL paragraph can be 1000+ chars — see
-// the "no truncation at storage" contract in deriveTitle). These helpers shrink
-// it for status surfaces (widget head, /task list) WITHOUT touching what's
-// stored: the pipeline always reads the full title. A model-compressed `label`
+// `title` is stored in full: `deriveTitle` returns the GOAL line whole, however
+// long it is, and nothing clamps it on the way to disk. These helpers shrink it
+// for status surfaces (widget head, /task list) WITHOUT touching what is stored —
+// the pipeline always reads the full title. A model-compressed `label`
 // is preferred when present (see title-label.ts); otherwise we fall back to a
 // deterministic, word-boundary truncation so a label-less task still reads
 // cleanly.

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[];
 /**