@mjasnikovs/pi-task 0.38.8 → 0.38.9

package/dist/task/auto-orchestrator.d.ts

@@ -1,6 +1,9 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { type GateDeps } from './task-gates.js';
 import { type FinalGateStageDeps } from './run-final-gate.js';
+import { type RequirementEntry } from './requirements.js';
+import { type ScoredPlan } from './coverage-loop.js';
+import { type DanglingRef } from './artifact-closure.js';
 /**
  * Injectable seams so the planner and loop are testable without spawning pi.
  * `runChild` is the planning-only seam used by planAuto; everything else is one of
@@ -75,6 +78,84 @@ export declare function attachSpecRefs(titles: string[], refs: string[]): string
  * authoritative spec ref still rides on THIS step's own title via attachSpecRefs.
  */
 export declare function buildScopeFence(titles: string[], currentIndex: number): string;
+/**
+ * What ORIENT establishes about the feature before anyone is asked anything: the
+ * spec text the planning children will actually read, and the requirement ledger
+ * derived from it. Every later stage reads these; none of them writes one.
+ */
+export interface OrientedFeature {
+    /** The inlined spec, with phantom runtime specifiers struck out. */
+    featureForModel: string;
+    /** Manifest/config already on disk, fed to every triage call. '' when absent. */
+    existingFilesBlock: string;
+    /** Grounded requirement units extracted from the spec. */
+    reqEntries: RequirementEntry[];
+    /** How many of those a single task could own (cross-cutting ones excluded). */
+    ownableRequirements: number;
+    /** The task-count floor those ownable requirements imply. 0 ⇒ no channel. */
+    coarseFloor: number;
+}
+/**
+ * ORIENT — read the feature, strike what must never reach a planning child, and
+ * derive the requirement ledger. Depends on nothing but the feature and the tree,
+ * which is why it runs before clarify: the plan-shape fork below needs a real
+ * count to judge with. Every fallible part is best-effort; a fault degrades the
+ * channel it belongs to and never fails planning.
+ */
+export declare function orientFeature(cwd: string, feature: string, deps: AutoDeps): Promise<OrientedFeature>;
+/**
+ * ELICIT — clarify, sequential & adaptive: ask one question at a time, feeding every
+ * answer back into the next call so later questions react to earlier ones (e.g. a
+ * framework choice reshapes what gets asked). Each question is shown exactly like
+ * /task's grill dialog: a binary fork offers two options (A/B), otherwise the model's
+ * recommendation is shown as the input placeholder and in the title. Nothing is
+ * pre-filled into the editor — submitting an empty field is what accepts the
+ * recommendation; typing overrides it. Each generated question first runs the
+ * answer-side TRIAGE (triageClarifyQuestion): a question the inlined spec already
+ * settles is auto-resolved and never shown — only genuine open forks reach the user.
+ * The model emits NONE when nothing remains.
+ *
+ * The ONLY stage that talks to the user, and so the only one that can be dismissed:
+ * `null` means the user cancelled and the cancellation has already been announced.
+ * Every other outcome is a transcript, possibly empty.
+ */
+export declare function elicitClarifications(ctx: ExtensionCommandContext, cwd: string, deps: AutoDeps, oriented: OrientedFeature): Promise<string | null>;
+/**
+ * What DECOMPOSE settles: the task list, plus the two things the coverage loop
+ * needs to ask for a better one. `decomposePrompt` and `parsePlan` are returned
+ * rather than rebuilt because COVER re-prompts with the identical prompt and must
+ * reconcile the reply identically — rebuilding either is how the two paths drift.
+ */
+export interface DecomposedPlan {
+    /** The reconciled, de-batched task titles. May be empty. */
+    planTitles: string[];
+    /** The exact prompt that produced them, for COVER's re-prompt. */
+    decomposePrompt: string;
+    /** Parse + fidelity-reconcile + de-batch, applied to EVERY decompose output. */
+    parsePlan: (raw: string) => string[];
+}
+/**
+ * DECOMPOSE — turn the settled feature into a task list, then defend that list's
+ * SHAPE: a plan under the granularity floor is sent back once to be split, and a
+ * suspect (empty or tiny) plan is regenerated on its own separate budget. Neither
+ * guard can block planning — a plan that survives both falls through to the judge.
+ */
+export declare function decomposePlan(cwd: string, deps: AutoDeps, oriented: OrientedFeature, clarifications: string): Promise<DecomposedPlan>;
+/** What COVER settles: the plan that ships, and the accounting behind it. */
+export interface CoveredPlan {
+    /** The best-covered plan seen across the rounds — adoption is monotone. */
+    best: ScoredPlan;
+    /** That plan's titles, which is what everything downstream persists. */
+    planTitles: string[];
+}
+/**
+ * COVER — judge the plan against the feature and re-prompt for a better one, up to
+ * a bounded number of rounds. Adoption is MONOTONE: a retry that drops a
+ * requirement the current plan owns is rejected, so coverage can only hold or grow,
+ * and the plan at exhaustion is the best one seen rather than the last one drawn.
+ * Best-effort throughout — a fault degrades a signal, it never blocks planning.
+ */
+export declare function coverPlan(ctx: ExtensionCommandContext, cwd: string, deps: AutoDeps, oriented: OrientedFeature, clarifications: string, decomposed: DecomposedPlan, specDangling: DanglingRef[]): Promise<CoveredPlan>;
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export declare function planAuto(ctx: ExtensionCommandContext, cwd: string, feature: string, deps: AutoDeps): Promise<string | null>;
 export declare function requestAutoCancel(): void;

package/dist/task/auto-orchestrator.js

@@ -409,21 +409,14 @@ async function schedulePendingRepairs(cwd, id, afterIndex, ctx, deps) {
         // the plan is best-effort here; the underlying debt is already recorded
     }
 }
-/** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
-export async function planAuto(ctx, cwd, feature, deps) {
-    // clarify — sequential & adaptive: ask one question at a time, feeding every
-    // answer back into the next call so later questions react to earlier ones
-    // (e.g. a framework choice reshapes what gets asked). Each question is shown
-    // exactly like /task's grill dialog: a binary fork offers two options (A/B),
-    // otherwise the model's recommendation is shown as the input placeholder and
-    // in the title. Nothing is pre-filled into the editor — submitting an empty
-    // field is what accepts the recommendation (see the typed.length === 0 branch
-    // below); typing overrides it. Each generated question first runs the
-    // answer-side TRIAGE (triageClarifyQuestion): a question the inlined spec
-    // already settles is auto-resolved and never shown — only genuine open forks
-    // reach the user. The model emits NONE when nothing remains.
-    const theme = ctx.ui.theme;
-    const ui = new SessionUI(ctx);
+/**
+ * ORIENT — read the feature, strike what must never reach a planning child, and
+ * derive the requirement ledger. Depends on nothing but the feature and the tree,
+ * which is why it runs before clarify: the plan-shape fork below needs a real
+ * count to judge with. Every fallible part is best-effort; a fault degrades the
+ * channel it belongs to and never fails planning.
+ */
+export async function orientFeature(cwd, feature, deps) {
     // Inline any @file spec the user referenced so clarify/decompose reason over
     // the real content, not a one-line "Implement @file" that reads as trivial.
     const rawFeatureForModel = await expandFeatureMentions(cwd, feature);
@@ -456,12 +449,8 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // into the decompose prompt as a ledger (structure-mirroring can't discharge
     // them) and drive the per-requirement coverage accounting below.
     //
-    // Runs BEFORE clarify (it depends only on the inlined feature, never on the
-    // answers) so the plan-shape gate below has a real count to judge with: the
-    // host must not seize the granularity fork on a spec that has no breakdown to
-    // speak of. Best-effort:
-    // a fault leaves reqEntries empty and the whole channel degrades to the old
-    // behavior (one-liners / doc-less features naturally yield few or none).
+    // Best-effort: a fault leaves reqEntries empty and the whole channel degrades to
+    // the old behavior (one-liners / doc-less features naturally yield few or none).
     let reqEntries = [];
     try {
         // Recall floor: the obligation-marked passages ride into the prompt as a
@@ -499,6 +488,28 @@ export async function planAuto(ctx, cwd, feature, deps) {
         logPlanDebug(cwd, `granularity floor: ${ownableRequirements} ownable requirement(s) ⇒ at least `
             + `${coarseFloor} task(s)`);
     }
+    return { featureForModel, existingFilesBlock, reqEntries, ownableRequirements, coarseFloor };
+}
+/**
+ * ELICIT — clarify, sequential & adaptive: ask one question at a time, feeding every
+ * answer back into the next call so later questions react to earlier ones (e.g. a
+ * framework choice reshapes what gets asked). Each question is shown exactly like
+ * /task's grill dialog: a binary fork offers two options (A/B), otherwise the model's
+ * recommendation is shown as the input placeholder and in the title. Nothing is
+ * pre-filled into the editor — submitting an empty field is what accepts the
+ * recommendation; typing overrides it. Each generated question first runs the
+ * answer-side TRIAGE (triageClarifyQuestion): a question the inlined spec already
+ * settles is auto-resolved and never shown — only genuine open forks reach the user.
+ * The model emits NONE when nothing remains.
+ *
+ * The ONLY stage that talks to the user, and so the only one that can be dismissed:
+ * `null` means the user cancelled and the cancellation has already been announced.
+ * Every other outcome is a transcript, possibly empty.
+ */
+export async function elicitClarifications(ctx, cwd, deps, oriented) {
+    const { featureForModel, existingFilesBlock, ownableRequirements } = oriented;
+    const theme = ctx.ui.theme;
+    const ui = new SessionUI(ctx);
     const answers = [];
     // Plain text of every question already shown, for the duplicate backstop.
     const askedQuestions = [];
@@ -615,26 +626,16 @@ export async function planAuto(ctx, cwd, feature, deps) {
     if (answers.length === 0) {
         ctx.ui.notify('No clarifying questions needed — planning tasks…', 'info');
     }
-    const clarifications = answers.join('\n');
-    // Artifact-production closure, plan side (mx5 run 13, PROMPT 2): runtime
-    // files the spec REFERENCES (server snippets, prose "serve the built
-    // index.html") that neither its file tree, its parsed build outputs, nor the
-    // existing scaffold produce. Sentence-grounded coverage credited the SERVING
-    // side and reported "0 unowned" while nothing ever CREATED the file — so
-    // these ride the coverage loop's `missing` list as unowned areas until some
-    // task title claims the artifact (grounded in titles, which the coverage-map
-    // model cannot fake — the run-12 lesson). Deterministic and best-effort.
-    let specDangling = [];
-    try {
-        specDangling = findSpecDanglingArtifacts(featureForModel, rel => existsSync(path.join(cwd, rel)));
-        if (specDangling.length > 0) {
-            logPlanDebug(cwd, `artifact closure: ${specDangling.length} dangling runtime artifact(s) in the `
-                + `spec: ${specDangling.map(d => d.path).join(', ')}`);
-        }
-    }
-    catch {
-        // best-effort channel
-    }
+    return answers.join('\n');
+}
+/**
+ * DECOMPOSE — turn the settled feature into a task list, then defend that list's
+ * SHAPE: a plan under the granularity floor is sent back once to be split, and a
+ * suspect (empty or tiny) plan is regenerated on its own separate budget. Neither
+ * guard can block planning — a plan that survives both falls through to the judge.
+ */
+export async function decomposePlan(cwd, deps, oriented, clarifications) {
+    const { featureForModel, reqEntries, ownableRequirements, coarseFloor } = oriented;
     // Tests-in-the-same-change cadence (mx5 run 14, PROMPT item 6): when the
     // decisions mandate it, a whole-project batch test task contradicts them —
     // run 14 shipped one anyway (TASK_0037, 4.7h, yolo-accepted FAIL) because
@@ -729,6 +730,19 @@ export async function planAuto(ctx, cwd, feature, deps) {
         if (retryTitles.length > planTitles.length)
             planTitles = retryTitles;
     }
+    return { planTitles, decomposePrompt, parsePlan };
+}
+/**
+ * COVER — judge the plan against the feature and re-prompt for a better one, up to
+ * a bounded number of rounds. Adoption is MONOTONE: a retry that drops a
+ * requirement the current plan owns is rejected, so coverage can only hold or grow,
+ * and the plan at exhaustion is the best one seen rather than the last one drawn.
+ * Best-effort throughout — a fault degrades a signal, it never blocks planning.
+ */
+export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomposed, specDangling) {
+    const { featureForModel, reqEntries } = oriented;
+    const { decomposePrompt, parsePlan } = decomposed;
+    let planTitles = decomposed.planTitles;
     // Coverage gate: a stochastic degenerate completion (live mx5: ONE task +
     // natural EOS for an 18KB design doc) is nonempty, so the length guard below
     // never fires and the whole run "completes" after one task. Judge the list
@@ -905,6 +919,44 @@ export async function planAuto(ctx, cwd, feature, deps) {
             + 'task. To give it one, stop now and add it to the plan in .pi-tasks/; otherwise '
             + 'it proceeds.', 'warning');
     }
+    return { best, planTitles };
+}
+/** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
+export async function planAuto(ctx, cwd, feature, deps) {
+    // ORIENT. Reads the feature and the tree, asks nobody anything.
+    const oriented = await orientFeature(cwd, feature, deps);
+    // The floor and the ownable count are DECOMPOSE's to enforce; what the tail of
+    // this function still reads is the spec text and the requirement ledger.
+    const { featureForModel, reqEntries } = oriented;
+    // ELICIT. The only stage that talks to the user.
+    const clarifications = await elicitClarifications(ctx, cwd, deps, oriented);
+    if (clarifications === null)
+        return null; // dismissed; already announced
+    // Artifact-production closure, plan side (mx5 run 13, PROMPT 2): runtime
+    // files the spec REFERENCES (server snippets, prose "serve the built
+    // index.html") that neither its file tree, its parsed build outputs, nor the
+    // existing scaffold produce. Sentence-grounded coverage credited the SERVING
+    // side and reported "0 unowned" while nothing ever CREATED the file — so
+    // these ride the coverage loop's `missing` list as unowned areas until some
+    // task title claims the artifact (grounded in titles, which the coverage-map
+    // model cannot fake — the run-12 lesson). Deterministic and best-effort.
+    let specDangling = [];
+    try {
+        specDangling = findSpecDanglingArtifacts(featureForModel, rel => existsSync(path.join(cwd, rel)));
+        if (specDangling.length > 0) {
+            logPlanDebug(cwd, `artifact closure: ${specDangling.length} dangling runtime artifact(s) in the `
+                + `spec: ${specDangling.map(d => d.path).join(', ')}`);
+        }
+    }
+    catch {
+        // best-effort channel
+    }
+    // DECOMPOSE. Produces the task list and the means to ask for a better one.
+    const decomposedPlan = await decomposePlan(cwd, deps, oriented, clarifications);
+    // COVER. Judges the plan and re-prompts for a better one, monotonically.
+    const covered = await coverPlan(ctx, cwd, deps, oriented, clarifications, decomposedPlan, specDangling);
+    const best = covered.best;
+    const planTitles = covered.planTitles;
     // Carry what no single task owns (goal A(b)/(c)): cross-cutting requirements
     // become `.pi-tasks/requirements.md`, injected VERBATIM into every task's
     // refine/compose (run 11: §10's test-first cadence had no carrier — the "spec
@@ -942,6 +994,20 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ctx.ui.notify(`/task-auto: carrying ${parts.join(', ')} requirement(s) into every task`
             + ' — see .pi-tasks/requirements.md.', 'info');
     }
+    // Thread the feature's spec doc(s) into every title so each per-task
+    // pipeline — which only ever sees its title — reads the real spec instead of
+    // a lossy one-line paraphrase of it.
+    const refs = await readableMentions(cwd, feature);
+    const titles = attachSpecRefs(planTitles, refs);
+    if (titles.length === 0) {
+        announceDone(ctx, '/task-auto: no tasks produced from the feature.', 'warning');
+        return null;
+    }
+    // The two grounded extractions below run AFTER the empty-plan guard on purpose.
+    // They each spawn a child and each APPEND to a run-level artifact; on the
+    // empty-plan path the plan is discarded one line later, so running them first
+    // burned two model calls and left contracts.md / launch-contract.md carrying
+    // facts for a run that never produced a task.
     // Cross-slice contract registry (mx5 run 8, F3): now that the plan is settled,
     // extract the interface facts MORE THAN ONE slice must agree on — endpoint paths,
     // exported signatures, file layouts, env var names the DESIGN pins — into a
@@ -983,15 +1049,6 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ground: emitted => keepGroundedScripts(emitted, featureForModel),
         append: appendDeclaredScripts
     });
-    // Thread the feature's spec doc(s) into every title so each per-task
-    // pipeline — which only ever sees its title — reads the real spec instead of
-    // a lossy one-line paraphrase of it.
-    const refs = await readableMentions(cwd, feature);
-    const titles = attachSpecRefs(planTitles, refs);
-    if (titles.length === 0) {
-        announceDone(ctx, '/task-auto: no tasks produced from the feature.', 'warning');
-        return null;
-    }
     // Persist the TASK-MAPPED requirements keyed by the (spec-ref-attached) title
     // each task will carry (mx5 run 16: only cross-cutting entries travelled;
     // the 33 mapped ones shaped the title list and vanished — TASK_0008 narrowed

package/dist/task/run-final-gate.d.ts

@@ -30,7 +30,8 @@ import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { CommitResult } from './auto-commit.js';
 import type { FinalGateOutcome } from './final-gate.js';
 import type { FinalGateFixFn } from './gate-deps.js';
-import { type AcceptDebt } from './accept-debt.js';
+import { type AcceptDebt, type DebtOrigin } from './accept-debt.js';
+import { type OwnedRequirement } from './requirements.js';
 /**
  * The seams this stage drives. A strict subset of what /task-auto builds, and
  * deliberately narrow: every optional dep absent degrades to a documented earlier
@@ -86,6 +87,20 @@ export interface FinalGateStageDeps {
      *  file) — the same auditability contract the per-task records carry. Best-effort:
      *  absent in tests → skipped; a failure never breaks the gate. */
     record?: (cwd: string, taskId: string, line: string) => Promise<void>;
+    /**
+     * Write one ACCEPT debt to the ledger. The run-level twin of `GateDeps.recordDebt`,
+     * and injectable for the same reason: without it a test that only wants to observe
+     * WHICH debts a scenario carries has to write, and then read back, the real ledger
+     * on disk. Absent → the real `accept-debt.ts` writer, so production wiring and the
+     * prior behaviour are unchanged.
+     */
+    recordDebt?: (cwd: string, taskId: string, reason: string, origin: DebtOrigin) => Promise<void>;
+    /**
+     * Read the owned-requirement ledger, to report obligations a task DETACHED and no
+     * later task claimed. Absent → the real `requirements.ts` reader (prior behaviour);
+     * injectable so that check is testable without seeding a real ledger file.
+     */
+    ownedRequirements?: (cwd: string) => Promise<OwnedRequirement[]>;
 }
 /** Inputs that vary per caller. */
 export interface FinalGateStageParams {

package/dist/task/run-final-gate.js

@@ -73,7 +73,7 @@ export async function runFinalGateStage(active, deps, p) {
      * What they no longer each restate is WHERE the debt goes: the run's own id, under
      * origin 'final-gate', which is what the next run's gate re-checks.
      */
-    const carryDebt = (reason) => recordDebt(cwd, id, reason, 'final-gate');
+    const carryDebt = (reason) => (deps.recordDebt ?? recordDebt)(cwd, id, reason, 'final-gate');
     // Set when the gate finished having observed NOTHING dynamic. Declared out here so
     // the run-completion announcement can say so.
     let unobservedNote = null;
@@ -147,7 +147,7 @@ export async function runFinalGateStage(active, deps, p) {
     // satisfy it, nexttask 2) and no later task claimed. Detach never deletes the
     // quote, so the run ends holding it — say so, or the resolution would be a quieter
     // version of the deletion it exists to prevent.
-    const unclaimed = unclaimedPendingRequirements(await readOwnedRequirements(cwd).catch(() => []));
+    const unclaimed = unclaimedPendingRequirements(await (deps.ownedRequirements ?? readOwnedRequirements)(cwd).catch(() => []));
     for (const o of unclaimed) {
         await recGate(`owned requirement UNCLAIMED — "${o.quote.slice(0, 200)}"`
             + ` [frozen in "${o.title.slice(0, 60)}"; no task claimed`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.38.8",
+    "version": "0.38.9",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",