@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/auto-io.js

@@ -7,6 +7,8 @@
  * `## coverage`. The checkbox list under `## tasks` is the resume cursor, and the
  * loop finds its next step with `entries.find(e => !e.done)` rather than a
  * remembered position.
+ *
+ * A checkbox line reads `- [ ] P01 TASK_0006 a2  title` — see {@link ENTRY_RE}.
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
@@ -14,6 +16,7 @@ import { tasksDir, ensureTasksDir, readTaskFile, setTaskSection } from './task-i
 import { extractSection, parseFrontMatter } from './task-parsers.js';
 import { readTextFile } from '../shared/fs-text.js';
 import { RESUMABLE_STATES } from './task-types.js';
+import { RUN_END_POLICY } from './run-end.js';
 const AUTO_FILE_RE = /^(TASK_AUTO_\d{4,})\.md$/;
 export async function allocateAutoId(cwd) {
     await ensureTasksDir(cwd);
@@ -52,14 +55,21 @@ export function parseDecomposeList(raw) {
     }
     return out;
 }
+/** The MISSING bound the coverage prompt states; a longer list is truncated
+ *  rather than rejected. */
+const MAX_MISSING_AREAS = 8;
+/** What an `unparseable` verdict contributes to the plan's missing-area list, so
+ *  the judge's own INCOMPLETE cannot be shipped as COMPLETE. */
+export const UNNAMED_COVERAGE_GAP = 'the coverage judge ruled INCOMPLETE without naming the uncovered area';
 /**
  * Parse the coverage-triage child's verdict. Returns null when no COVERAGE tag is
- * present (the model wrote prose), and the caller reads a null verdict as an
- * empty missing-list, so a malformed judgment can never block planning.
+ * present at all (the model wrote prose), and the caller reads a null verdict as
+ * an empty missing-list, so a malformed judgment can never block planning.
  *
- * `COVERAGE: INCOMPLETE` with no MISSING lines also returns null, deliberately:
- * it names nothing to reprompt with, so treating it as a verdict would loop
- * blind. Confirmed by running both shapes.
+ * `COVERAGE: INCOMPLETE` with no MISSING lines is NOT null, and that distinction
+ * is the whole point: prose is no verdict, while this is a verdict of INCOMPLETE
+ * that happens to name nothing. Collapsing the two shipped a plan the judge had
+ * just ruled incomplete, logged as COMPLETE.
  */
 export function parseCoverageVerdict(raw) {
     const tag = /^\s*COVERAGE:\s*(COMPLETE|INCOMPLETE)\s*$/im.exec(raw);
@@ -72,39 +82,95 @@ export function parseCoverageVerdict(raw) {
         const m = /^\s*MISSING:\s*(.+?)\s*$/i.exec(line);
         if (m && m[1].length > 0)
             missing.push(m[1]);
-        if (missing.length >= 8)
+        if (missing.length >= MAX_MISSING_AREAS)
             break;
     }
-    // INCOMPLETE with no MISSING lines carries no actionable signal to reprompt
-    // with — treat it like an unparseable verdict rather than looping blind.
-    return missing.length === 0 ? null : { kind: 'incomplete', missing };
+    return missing.length === 0 ? { kind: 'unparseable' } : { kind: 'incomplete', missing };
 }
 const CHECKBOX_RE = /^- \[([ xX])\]\s+(.+?)\s*$/;
-const PRODUCED_ID_RE = /^(TASK_\d{4,})\s{2,}(.+)$/;
+/**
+ * The checkbox line grammar: `- [ ] P01 TASK_0006 a2  title`, where the attempts
+ * field may carry how the last attempt ended — `a2:failed`.
+ *
+ * Every field is optional and each is followed by ONE space; the title is set off
+ * by an EXTRA space. That two-space delimiter is what keeps the grammar
+ * unambiguous against prose: a title of its own may begin `TASK_0006 is broken`
+ * or `(auto) …` and is read whole, because a single space never separates a field
+ * from a title. Both legacy forms — `TASK_0006  title` and a bare `title` — are
+ * the same grammar with fields missing, so no migration pass is needed on read.
+ *
+ * The end suffix spells out the endings RUN_END_POLICY registers rather than
+ * accepting any word, so `a2:whatever ` stays prose and a renamed ending is a
+ * parse miss, never a silently mis-read field.
+ */
+const ENTRY_RE = new RegExp('^(?:(?:(P\\d{2,}) )?(?:(TASK_\\d{4,}) )?'
+    + `(?:a(\\d+)(?::(${Object.keys(RUN_END_POLICY).join('|')}))? )? )?(.+)$`);
+function parseEntryLine(line, index) {
+    const m = CHECKBOX_RE.exec(line.trim());
+    if (!m)
+        return null;
+    const f = ENTRY_RE.exec(m[2].trim());
+    if (!f)
+        return null;
+    const [, key, producedId, attempts, lastEnd, title] = f;
+    // Attempts are only ever written alongside an id (they are minted when the
+    // inner task starts), so a bare `a7  …` is a title, not a field.
+    const keyed = key !== undefined || producedId !== undefined;
+    return {
+        index,
+        done: m[1].toLowerCase() === 'x',
+        // A line carries a stamped TASK_NNNN id both when done (the completed
+        // inner task) and when merely started — an unchecked, stamped line is an
+        // in-progress entry whose inner task can be resumed.
+        ...(key !== undefined && { key }),
+        ...(producedId !== undefined && { producedId }),
+        ...(keyed && attempts !== undefined && { attempts: parseInt(attempts, 10) }),
+        ...(keyed && lastEnd !== undefined && { lastEnd: lastEnd }),
+        title: keyed || attempts === undefined ? title.trim() : m[2].trim()
+    };
+}
+/**
+ * Render one entry back into the line grammar.
+ *
+ * An entry with NEITHER a key nor an id has no field to anchor an attempts count
+ * against, and `a2  title` alone re-parses as a title (see {@link ENTRY_RE}) — so
+ * the count is dropped rather than written into a line that would read it back as
+ * prose. Only pre-key legacy plans are in that state, and they predate the counter.
+ */
+function renderEntryLine(e) {
+    const anchored = e.key !== undefined || e.producedId !== undefined;
+    const attempts = e.attempts === undefined || !anchored ?
+        undefined
+        : `a${e.attempts}${e.lastEnd === undefined ? '' : `:${e.lastEnd}`}`;
+    const fields = [e.key, e.producedId, attempts]
+        .filter((f) => f !== undefined && f.length > 0)
+        .join(' ');
+    return `- [${e.done ? 'x' : ' '}] ${fields.length > 0 ? `${fields}  ` : ''}${e.title}`;
+}
+/** The plan key for the `index`th entry of a freshly planned list. */
+export function planKeyAt(index) {
+    return `P${String(index + 1).padStart(2, '0')}`;
+}
+/**
+ * The lowest key number no entry in `entries` holds. Keys are allocated 1:1 with
+ * plan entries, so an unkeyed legacy list has implicitly spent its first N
+ * numbers — counting it in keeps a spliced repair step from minting a key an
+ * eventual migration would hand to an existing entry.
+ */
+export function nextPlanKey(entries) {
+    const highest = entries.reduce((max, e) => Math.max(max, e.key ? parseInt(e.key.slice(1), 10) : 0), entries.length);
+    return planKeyAt(highest);
+}
 /** Parse the "## tasks" checkbox list. */
 export function parseTaskList(body) {
     const section = extractSection(body, 'tasks');
     if (section === null)
         return [];
     const entries = [];
-    let index = 0;
     for (const line of section.split('\n')) {
-        const m = CHECKBOX_RE.exec(line.trim());
-        if (!m)
-            continue;
-        const done = m[1].toLowerCase() === 'x';
-        const rest = m[2].trim();
-        // A line carries a stamped TASK_NNNN id both when done (the completed
-        // inner task) and when merely started — an unchecked, stamped line is an
-        // in-progress entry whose inner task can be resumed.
-        const idm = PRODUCED_ID_RE.exec(rest);
-        if (idm) {
-            entries.push({ index, title: idm[2].trim(), done, producedId: idm[1] });
-        }
-        else {
-            entries.push({ index, title: rest, done });
-        }
-        index++;
+        const entry = parseEntryLine(line, entries.length);
+        if (entry)
+            entries.push(entry);
     }
     return entries;
 }
@@ -113,24 +179,31 @@ export function parseTaskList(body) {
  *  cross-cutting and what stayed unowned. An empty string omits the section
  *  entirely rather than emitting a blank heading. */
 export function buildAutoBody(feature, clarifications, titles, coverage = '') {
-    const tasks = titles.map(t => `- [ ] ${t}`).join('\n');
+    const tasks = titles
+        .map((t, i) => renderEntryLine({ key: planKeyAt(i), title: t, done: false }))
+        .join('\n');
     return (`\n## feature prompt\n\n${feature.trim() || '(none)'}\n\n`
         + `## clarifications\n\n${clarifications.trim() || '(none)'}\n\n`
         + `## tasks\n\n${tasks}\n`
         + (coverage.trim().length > 0 ? `\n## coverage\n\n${coverage.trim()}\n` : ''));
 }
-/** Rewrite the Nth checkbox line of the "## tasks" section in place. */
+/**
+ * Rewrite the Nth checkbox line of the "## tasks" section in place. `render`
+ * receives the line as parsed, so a rewrite that only changes one field carries
+ * the others — a check-off must not drop the key the ownership join reads.
+ */
 async function rewriteTaskLine(cwd, id, index, render, label) {
     const { body } = await readTaskFile(cwd, id);
     const section = extractSection(body, 'tasks') ?? '';
     const lines = section.split('\n');
     let seen = -1;
     for (let i = 0; i < lines.length; i++) {
-        if (!CHECKBOX_RE.test(lines[i].trim()))
+        const entry = parseEntryLine(lines[i], seen + 1);
+        if (!entry)
             continue;
         seen++;
         if (seen === index) {
-            lines[i] = render();
+            lines[i] = render(entry);
             break;
         }
     }
@@ -141,25 +214,45 @@ async function rewriteTaskLine(cwd, id, index, render, label) {
 }
 /** Check off the Nth checkbox line, stamping the produced TASK_NNNN id. */
 export async function checkOffTask(cwd, id, index, producedId, title) {
-    await rewriteTaskLine(cwd, id, index, () => (producedId ? `- [x] ${producedId}  ${title}` : `- [x] ${title}`), 'checkOffTask');
+    await rewriteTaskLine(cwd, id, index, e => renderEntryLine({ ...e, done: true, title, producedId: producedId || undefined }), 'checkOffTask');
 }
 /**
  * Stamp the inner TASK_NNNN id onto the Nth (still-unchecked) entry the moment
  * the inner task is allocated. This links the AUTO entry to its in-progress
  * inner task so /task-auto-resume can continue it from its saved phase instead
  * of starting a brand-new task — matching how /task-resume behaves.
+ *
+ * The first stamp is also where the attempt counter is minted: an entry under way
+ * has had one attempt.
  */
 export async function stampTaskInProgress(cwd, id, index, producedId, title) {
-    await rewriteTaskLine(cwd, id, index, () => `- [ ] ${producedId}  ${title}`, 'stampTaskInProgress');
+    await rewriteTaskLine(cwd, id, index, e => renderEntryLine({ ...e, done: false, title, producedId }), 'stampTaskInProgress');
 }
-/** The bare title of a checkbox line (id stamp stripped), or null if not one. */
+/**
+ * Count one more attempt on the `index`th entry and return the new total.
+ *
+ * Called for a fresh start AND for a resume, because both spend a run on the
+ * entry: a task that crashes in refine is re-entered from scratch every time, and
+ * a counter that only saw fresh starts would read 1 forever while the loop re-ran
+ * it without end. The previous ending is cleared here — it describes the attempt
+ * that is now over.
+ */
+export async function beginTaskAttempt(cwd, id, index) {
+    let attempts = 1;
+    await rewriteTaskLine(cwd, id, index, e => {
+        attempts = (e.attempts ?? 0) + 1;
+        const { lastEnd: _ended, ...rest } = e;
+        return renderEntryLine({ ...rest, attempts });
+    }, 'beginTaskAttempt');
+    return attempts;
+}
+/** Record how the `index`th entry's attempt ended. */
+export async function recordTaskEnd(cwd, id, index, lastEnd) {
+    await rewriteTaskLine(cwd, id, index, e => renderEntryLine({ ...e, attempts: e.attempts ?? 1, lastEnd }), 'recordTaskEnd');
+}
+/** The bare title of a checkbox line (fields stripped), or null if not one. */
 function entryTitle(line) {
-    const m = CHECKBOX_RE.exec(line.trim());
-    if (!m)
-        return null;
-    const rest = m[2].trim();
-    const idm = PRODUCED_ID_RE.exec(rest);
-    return idm ? idm[2].trim() : rest;
+    return parseEntryLine(line, 0)?.title ?? null;
 }
 /**
  * Insert a NEW unchecked entry directly after the `afterIndex`th checkbox — the
@@ -194,15 +287,15 @@ export async function insertTaskAfter(cwd, id, afterIndex, title) {
     // sits relative to afterIndex — never add a second one.
     if (lines.some(l => entryTitle(l) === clean))
         return false;
-    let seen = -1;
+    const entries = [];
     let insertAt = -1;
     for (let i = 0; i < lines.length; i++) {
-        if (!CHECKBOX_RE.test(lines[i].trim()))
+        const entry = parseEntryLine(lines[i], entries.length);
+        if (!entry)
             continue;
-        seen++;
-        insertAt = i + 1;
-        if (seen === afterIndex)
-            break;
+        entries.push(entry);
+        if (entries.length - 1 <= afterIndex)
+            insertAt = i + 1;
     }
     // An out-of-range afterIndex is not an error: the loop above leaves `insertAt`
     // just past the LAST checkbox, so the entry is appended rather than lost — a
@@ -213,7 +306,7 @@ export async function insertTaskAfter(cwd, id, afterIndex, title) {
     // lines at all, where there is no position to splice into.
     if (insertAt === -1)
         return false;
-    lines.splice(insertAt, 0, `- [ ] ${clean}`);
+    lines.splice(insertAt, 0, renderEntryLine({ key: nextPlanKey(entries), title: clean, done: false }));
     await setTaskSection(cwd, id, 'tasks', lines.join('\n'));
     return true;
 }

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

@@ -1,4 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { type TaskEntry } from './auto-io.js';
+import { expandFeatureMentions, readableMentions } from './mentions.js';
+export { expandFeatureMentions, readableMentions };
 import { type GateDeps } from './task-gates.js';
 import { type FinalGateStageDeps } from './run-final-gate.js';
 import { type RequirementEntry } from './requirements.js';
@@ -31,23 +34,6 @@ export interface AutoDeps extends GateDeps, FinalGateStageDeps {
 }
 /** Wait for every plan-debug line written so far to reach disk. Tests only. */
 export declare function flushPlanDebug(): Promise<unknown>;
-/**
- * Expand any @file references in the feature text by appending each referenced
- * file's contents, so the planning children (clarify, decompose) always see the
- * real spec inline instead of relying on the model to open the file itself.
- * Without this, clarify on a one-line "Implement @spec.md" tends to bail with
- * NONE because, to the model, the request looks small and unambiguous.
- * Unreadable mentions (typos, non-file @tokens) are left untouched; the feature
- * is returned verbatim when nothing readable is referenced.
- */
-export declare function expandFeatureMentions(cwd: string, feature: string): Promise<string>;
-/**
- * The @file references in the feature that point at a readable file on disk —
- * the bare path tokens, deduped, in first-seen order. Unreadable mentions
- * (typos, non-file @tokens) are dropped so we never advertise a missing file as
- * an authoritative spec.
- */
-export declare function readableMentions(cwd: string, feature: string): Promise<string[]>;
 /**
  * Thread the feature's spec references AND any per-task decisions into every
  * decomposed task title. A title is ALL a per-task pipeline ever sees, so both the
@@ -76,11 +62,28 @@ export declare function attachSpecRefs(titles: string[], refs: string[]): string
  *
  * The plan listing strips the threaded "| decisions … | spec …" tail from each
  * title and keeps the human-readable head, so the model reads clean step names,
- * and it marks the current one "(THIS STEP)" — both confirmed by building a fence
+ * and it marks the current one `[this]` — both confirmed by building a fence
  * over threaded titles. The authoritative spec ref still rides on THIS step's own
  * title via attachSpecRefs.
+ *
+ * Every sibling used to read as unbuilt, which is a lie about the first half of
+ * any plan past step one: a step told its predecessors are "done in later runs"
+ * re-scaffolds what is already in the tree. The entries carry their own done
+ * state, so the listing states it.
+ */
+export declare function buildScopeFence(entries: readonly TaskEntry[], currentIndex: number): string;
+/**
+ * The scope fence for step `currentIndex`, plus the REPAIR fence when that step is
+ * a queued root-cause repair. A repair title ("repair test/teardown.ts: …") reads
+ * to refine like any other feature step, and refine's job is to expand a title into
+ * a full spec — which is exactly how "repair the teardown" becomes "overhaul the
+ * test infrastructure". The extra fence pins the one editable file, and pins VERIFY
+ * to the failing command WHEN the title carries one: `extractFailingCommand` reads
+ * a backticked runner command out of the defect text, so a defect quoting
+ * `bun run test` yields it while a plain-prose defect yields undefined and only the
+ * file pin applies.
  */
-export declare function buildScopeFence(titles: string[], currentIndex: number): string;
+export declare function buildStepFence(entries: readonly TaskEntry[], 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