@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/auto-commit.js

@@ -1,10 +1,12 @@
 /**
  * Per-task git commit for /task-auto.
  *
- * After each decomposed task passes, runAutoLoop snapshots the working tree into
- * a single commit so the run produces one commit per task. This is best-effort:
- * outside a git repo, with nothing staged, or on any git error we report the
- * reason and let the loop continue (the task already succeeded).
+ * After each decomposed task passes, the loop snapshots the working tree into a
+ * single commit, so a run produces one commit per task. Best-effort throughout,
+ * and confirmed by calling it: outside a git repo it answers
+ * `{committed: false, reason: 'not a git repository'}`, on a clean tree
+ * `{committed: false, reason: 'nothing to commit'}`. Nothing throws — the task
+ * already succeeded, and a failed snapshot must not undo that.
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
@@ -14,15 +16,21 @@ import { isDeletionExemptArtifact } from './regenerable-artifacts.js';
  *  ledgers. Preserved verbatim across a revert (see gitDropLastCommit). */
 const TRAIL_DIR = '.pi-tasks';
 /**
- * Does this git stderr describe a missing author identity? Seen live (mx5 run 4):
- * the headless docker container has no HOME gitconfig, so EVERY per-task commit
- * failed "Author identity unknown" — which silently disabled enforce and every
- * commit-based differential guard for the whole run.
+ * Does this git stderr describe a missing author identity?
+ *
+ * The failure it catches is total rather than partial: with no usable gitconfig
+ * every per-task commit fails, which silently disables enforce and every
+ * commit-based differential guard for the rest of the run. Reproduced with real
+ * git — committing with `HOME` unset and both config files pointed at
+ * `/dev/null` prints "Author identity unknown" plus the `user.email` /
+ * `user.name` advice, and this predicate matches that text while rejecting an
+ * unrelated `fatal: not a git repository`.
  */
 export function isIdentityFailure(stderr) {
     return /identity unknown|unable to auto-detect email|user\.(name|email)/i.test(stderr);
 }
-/** Fallback identity for environments with no git config (headless containers). */
+/** Fallback identity for environments with no git config. Confirmed against real
+ *  git: the same commit that fails with no identity succeeds with these args. */
 export const FALLBACK_IDENTITY_ARGS = [
     '-c',
     'user.name=pi-task',
@@ -42,21 +50,22 @@ export async function git(cwd, args, signal, spawnFn) {
  * `test-results/`, `playwright-report/`, `coverage/`, `.nyc_output/`,
  * `.last-run.json`, `*.tsbuildinfo`.
  *
- * This is the other half of mx5 run 20. TASK_0027's snapshot ran a bare
- * `git add -A` over a tree the test run had just littered with three Playwright
- * FAILURE screenshots (`*-actual.png` — written only when a screenshot assertion
- * fails), committed them, and thereby made them tracked deliverables. Two whole
- * final-gate fix attempts were then rejected for deleting them. The deletion guard
- * fix (write-guard.ts) stops the rejection; this stops the tracking.
+ * The failure this closes: a bare `git add -A` sweeps up whatever the test run
+ * just littered the tree with — a failure screenshot, a coverage dir — and commits
+ * it, making regenerable output a TRACKED deliverable. A later task that cleans it
+ * up then reads as deleting someone's work.
  *
  * ONLY UNTRACKED PATHS ARE EXCLUDED, and that is load-bearing rather than tidy.
- * `git ls-files --others` lists untracked, non-ignored files and nothing else, so a
- * path git ALREADY tracks can never appear here — meaning a project that
- * deliberately commits, say, a `coverage/` badge keeps having its edits to it
- * committed. Excluding by directory pathspec instead (`:(exclude)coverage/`) would
- * silently stop committing those.
+ * Both halves measured with real git in a repo with a gitignored `coverage/` and
+ * an untracked `test-results/`:
+ *   • `ls-files --others --exclude-standard` returned the untracked file alone;
+ *     dropping the flag brought the gitignored one back too.
+ *   • a TRACKED file never appears, even while modified.
+ * So a project that deliberately commits, say, a `coverage/` badge keeps having
+ * its edits to it committed. Excluding by directory pathspec instead
+ * (`:(exclude)coverage/`) would silently stop committing those.
  *
- * Best-effort: any git failure yields an empty list, i.e. today's `git add -A`.
+ * Best-effort: any git failure yields an empty list, i.e. a plain `git add -A`.
  */
 export async function untrackedArtifacts(cwd, signal, spawnFn) {
     const r = await git(cwd, ['ls-files', '--others', '--exclude-standard', '-z'], signal, spawnFn);
@@ -69,7 +78,7 @@ export async function untrackedArtifacts(cwd, signal, spawnFn) {
         .sort();
 }
 /** `:(exclude)` pathspecs for `git add -A`; empty when nothing is excluded, so the
- *  common case is byte-identical to the previous bare `git add -A`. */
+ *  common case adds no arguments at all and stays a bare `git add -A`. */
 export function stagePathspec(excluded) {
     if (excluded.length === 0)
         return [];
@@ -80,10 +89,12 @@ export function stagePathspec(excluded) {
  * Empty outside a git repo or on any git error — this is a GUARD input, and a
  * guard that cannot conclude must not block.
  *
- * Why it exists (mx5 run 6): a stale `git stash pop` mid-task left two paths UU;
- * every later commit was doomed, three verify passes ran against a conflicted
- * tree, and — worse — a blind `git add -A` on that index would have silently
- * "resolved" the conflict with whatever happened to be on disk.
+ * Why it exists: with an unmerged index every later commit is doomed, verify runs
+ * against a conflicted tree, and — worst — a blind `git add -A` SILENTLY resolves
+ * the conflict with whatever is on disk. Reproduced on a real conflict: `git
+ * status` showed `UU c.txt`, then a bare `git add -A` turned it into `M  c.txt`
+ * and left `ls-files -u` empty. The conflict markers become staged content and
+ * nothing says so.
  */
 export async function gitUnmergedPaths(cwd, signal, spawnFn) {
     const r = await git(cwd, ['ls-files', '-u'], signal, spawnFn);
@@ -103,7 +114,7 @@ export async function gitUnmergedPaths(cwd, signal, spawnFn) {
 }
 /** Sha of `refs/stash`, or null when there is no stash (or not a git repo). Used
  *  to detect a stash created (or consumed) during a task and left behind — the
- *  exact landmine that detonated mx5 run 6 two days after it was pushed. */
+ *  exact landmine that detonates days after it is pushed. */
 export async function gitStashRef(cwd, signal, spawnFn) {
     const r = await git(cwd, ['rev-parse', '-q', '--verify', 'refs/stash'], signal, spawnFn);
     return r.exitCode === 0 ? r.stdout.trim() : null;
@@ -187,18 +198,20 @@ export async function gitCommitAll(cwd, message, signal, spawnFn) {
  * verified task commit underneath it.
  *
  * `reset --hard` targets the enforce pass's in-place SOURCE edits. But it must NOT
- * rewind the forensic gate trail: `.pi-tasks/` is frequently TRACKED (the per-task
- * snapshots stage it via `git add -A`), so a bare reset restores TASK_00NN.md to the
- * snapshot commit and ERASES every trail line written after it — the "commit: task
- * snapshot committed", "enforce(edit): …", and resolution lines (mx5 run 9:
- * TASK_0007/0008/0012 each lost their whole post-snapshot trail on this exact path,
- * so a passing-then-reverted task looked like it had never been committed). So the
- * trail is snapshotted before the reset and restored after — the revert undoes code,
- * the audit log survives.
+ * rewind the forensic gate trail. `.pi-tasks/` is frequently TRACKED here — unlike
+ * the accept-debt ledger's writers, the per-task snapshot stages it with a plain
+ * `git add -A` and no exclusion — so a bare reset rewinds the task file along with
+ * the source and ERASES every trail line written after the snapshot.
+ *
+ * Both halves were run on a real repo. A bare `reset --hard HEAD~1` restored the
+ * source AND dropped the trail line added after the snapshot; calling this
+ * function on the identical setup restored the source and kept that line. The
+ * revert undoes code, the audit log survives.
  *
- * Best-effort and never throws: a git failure is swallowed (the caller has
- * already decided to keep the verified work; a failed reset only leaves the
- * enforce commit in place, which is surfaced as a warning).
+ * Best-effort and never throws: a git failure is swallowed, since the caller has
+ * already decided to keep the verified work and a failed reset only leaves the
+ * enforce commit in place, which is surfaced as a warning. Called on a directory
+ * that is not a repo at all, it returns without throwing.
  */
 export async function gitDropLastCommit(cwd, signal, spawnFn) {
     const trail = await snapshotTrail(cwd);

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

@@ -10,12 +10,16 @@ export declare function allocateAutoId(cwd: string): Promise<string>;
 /**
  * Parse a decompose-phase model output into a clean list of titles.
  *
- * No cap: every title the model emits is kept. An arbitrary ceiling (was 30)
- * silently dropped the tail of a large plan AND re-clipped every coverage retry,
- * so a design that genuinely needed >N tasks could never escape the ceiling —
- * it burned its coverage rounds and shipped a knowingly-gapped plan. The real
- * bound on task count is the design's own grounded-requirement scope, enforced
- * downstream by the coverage loop; this parser must not pre-empt it.
+ * No cap: every title the model emits is kept — 100 lines in, 100 titles out.
+ * A ceiling here would be invisible and self-defeating, because it would clip the
+ * tail of a large plan AND re-clip every coverage retry, so a design that
+ * genuinely needs more tasks than the ceiling could never grow past it — it would
+ * burn its coverage rounds and ship a knowingly-gapped plan. The real bound is
+ * the design's own grounded-requirement scope, enforced downstream by the
+ * coverage loop; this parser must not pre-empt it.
+ *
+ * Accepts checkbox, bare-dash and numbered forms (`1.` and `2)`), indented or
+ * not, and skips prose lines and empty bullets.
  */
 export declare function parseDecomposeList(raw: string): string[];
 /** Parsed DECOMPOSE_COVERAGE_PROMPT verdict. */
@@ -24,16 +28,21 @@ export interface CoverageVerdict {
     missing: string[];
 }
 /**
- * Parse the coverage-triage child's verdict. Returns null when no COVERAGE tag
- * is present (the model wrote prose) — the caller treats that as "accept the
- * list as-is", so a malformed judgment can never block planning.
+ * 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.
+ *
+ * `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.
  */
 export declare function parseCoverageVerdict(raw: string): CoverageVerdict | null;
 /** Parse the "## tasks" checkbox list. */
 export declare function parseTaskList(body: string): TaskEntry[];
 /** Build the initial AUTO-file body. `coverage` is the requirement-level
- *  accounting summary (goal A(c) — a durable, user-visible record of what was
- *  carried cross-cutting and what stayed unowned); '' omits the section. */
+ *  accounting summary — a durable, user-visible record of what was carried
+ *  cross-cutting and what stayed unowned. An empty string omits the section
+ *  entirely rather than emitting a blank heading. */
 export declare function buildAutoBody(feature: string, clarifications: string, titles: string[], coverage?: string): string;
 /** Check off the Nth checkbox line, stamping the produced TASK_NNNN id. */
 export declare function checkOffTask(cwd: string, id: string, index: number, producedId: string, title: string): Promise<void>;
@@ -46,18 +55,24 @@ export declare function checkOffTask(cwd: string, id: string, index: number, pro
 export declare function stampTaskInProgress(cwd: string, id: string, index: number, producedId: string, title: string): Promise<void>;
 /**
  * Insert a NEW unchecked entry directly after the `afterIndex`th checkbox — the
- * mid-run plan mutation the root-cause repair channel needs (mx5 run 14 item 5:
- * a repair task must land BEFORE the next dependent task, not at the end of the
- * plan, or the defect keeps failing everything in between).
+ * mid-run plan mutation the root-cause repair channel needs: a repair task must
+ * land BEFORE the next dependent task, not at the end of the plan, or the defect
+ * keeps failing everything in between.
  *
- * MONOTONIC by construction (the run-12 replacement lesson): this only ever
- * SPLICES a line in. No existing entry is rewritten, reordered, or dropped, and
- * an already-present title is a no-op — so a plan can grow mid-run but never
- * shrink, and a retried insert cannot duplicate. Returns whether a line was added.
+ * MONOTONIC by construction: this only ever SPLICES a line in. No existing entry
+ * is rewritten, reordered or dropped, and an already-present title is a no-op —
+ * so a plan can grow mid-run but never shrink, and a retried insert cannot
+ * duplicate. Returns whether a line was added.
+ *
+ * Run against a real plan: inserting a new title after entry 0 returns true and
+ * lands it directly after that entry; the same title again returns false; a title
+ * that is already present AND CHECKED also returns false; an empty title returns
+ * false. Everything else keeps its order.
  *
  * Later entries shift down by one, which is safe because the /task-auto loop
  * re-reads and re-parses the plan at the top of every iteration and locates its
- * next step by "first unchecked" rather than by a cached index.
+ * next step with `entries.find(e => !e.done)` — first unchecked — rather than a
+ * cached index.
  */
 export declare function insertTaskAfter(cwd: string, id: string, afterIndex: number, title: string): Promise<boolean>;
 /**
@@ -65,12 +80,17 @@ export declare function insertTaskAfter(cwd: string, id: string, afterIndex: num
  * last-write time the resume banner reports (see resume-gap.ts). Null when there
  * is nothing resumable.
  *
- * `states` narrows which states count as resumable, and the UNATTENDED path passes
- * UNATTENDED_STATES so the search answers the question that path actually asks —
- * "is there an IN-FLIGHT run to pick up?". Selecting the newest human-resumable run
- * and only then refusing it on state let one failed run shadow an in-flight one
- * behind it: the boot hook refused every restart and the in-flight run stayed in
- * exactly the dead air this feature exists to end.
+ * `states` narrows which states count as resumable BEFORE the newest-wins sort,
+ * and that ordering is the whole point. The UNATTENDED path passes
+ * UNATTENDED_STATES so the search answers the question it actually asks — "is
+ * there an IN-FLIGHT run to pick up?"
+ *
+ * Filtering after the sort instead would let one failed run shadow an in-flight
+ * one behind it. Demonstrated on two files, the newer `failed` and the older
+ * `in_progress`: the default states pick the newer failed one, while
+ * UNATTENDED_STATES picks the older in-progress one. Had the newest been chosen
+ * first and only then refused on state, the restart would find nothing and the
+ * in-flight run would sit in exactly the dead air this exists to end.
  */
 export declare function findResumableAutoDetailed(cwd: string, states?: readonly TaskState[]): Promise<AutoResumeCandidate | null>;
 /** Id-only form of {@link findResumableAutoDetailed}. */

package/dist/task/auto-io.js

@@ -2,8 +2,11 @@
  * AUTO-file I/O & parsing for /task-auto.
  *
  * Thin layer over task-io/task-parsers: a TASK_AUTO_NNNN.md is a normal task
- * file (same front matter) whose body holds feature prompt, clarifications, and
- * a markdown checkbox list of task titles. The checkboxes are the resume cursor.
+ * file — the same front matter, parsed by the same `parseFrontMatter` — whose
+ * body holds `## feature prompt`, `## clarifications`, `## tasks` and optionally
+ * `## 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.
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
@@ -29,12 +32,16 @@ export async function allocateAutoId(cwd) {
 /**
  * Parse a decompose-phase model output into a clean list of titles.
  *
- * No cap: every title the model emits is kept. An arbitrary ceiling (was 30)
- * silently dropped the tail of a large plan AND re-clipped every coverage retry,
- * so a design that genuinely needed >N tasks could never escape the ceiling —
- * it burned its coverage rounds and shipped a knowingly-gapped plan. The real
- * bound on task count is the design's own grounded-requirement scope, enforced
- * downstream by the coverage loop; this parser must not pre-empt it.
+ * No cap: every title the model emits is kept — 100 lines in, 100 titles out.
+ * A ceiling here would be invisible and self-defeating, because it would clip the
+ * tail of a large plan AND re-clip every coverage retry, so a design that
+ * genuinely needs more tasks than the ceiling could never grow past it — it would
+ * burn its coverage rounds and ship a knowingly-gapped plan. The real bound is
+ * the design's own grounded-requirement scope, enforced downstream by the
+ * coverage loop; this parser must not pre-empt it.
+ *
+ * Accepts checkbox, bare-dash and numbered forms (`1.` and `2)`), indented or
+ * not, and skips prose lines and empty bullets.
  */
 export function parseDecomposeList(raw) {
     const out = [];
@@ -46,9 +53,13 @@ export function parseDecomposeList(raw) {
     return out;
 }
 /**
- * Parse the coverage-triage child's verdict. Returns null when no COVERAGE tag
- * is present (the model wrote prose) — the caller treats that as "accept the
- * list as-is", so a malformed judgment can never block planning.
+ * 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.
+ *
+ * `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.
  */
 export function parseCoverageVerdict(raw) {
     const tag = /^\s*COVERAGE:\s*(COMPLETE|INCOMPLETE)\s*$/im.exec(raw);
@@ -98,8 +109,9 @@ export function parseTaskList(body) {
     return entries;
 }
 /** Build the initial AUTO-file body. `coverage` is the requirement-level
- *  accounting summary (goal A(c) — a durable, user-visible record of what was
- *  carried cross-cutting and what stayed unowned); '' omits the section. */
+ *  accounting summary — a durable, user-visible record of what was carried
+ *  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');
     return (`\n## feature prompt\n\n${feature.trim() || '(none)'}\n\n`
@@ -151,18 +163,24 @@ function entryTitle(line) {
 }
 /**
  * Insert a NEW unchecked entry directly after the `afterIndex`th checkbox — the
- * mid-run plan mutation the root-cause repair channel needs (mx5 run 14 item 5:
- * a repair task must land BEFORE the next dependent task, not at the end of the
- * plan, or the defect keeps failing everything in between).
+ * mid-run plan mutation the root-cause repair channel needs: a repair task must
+ * land BEFORE the next dependent task, not at the end of the plan, or the defect
+ * keeps failing everything in between.
  *
- * MONOTONIC by construction (the run-12 replacement lesson): this only ever
- * SPLICES a line in. No existing entry is rewritten, reordered, or dropped, and
- * an already-present title is a no-op — so a plan can grow mid-run but never
- * shrink, and a retried insert cannot duplicate. Returns whether a line was added.
+ * MONOTONIC by construction: this only ever SPLICES a line in. No existing entry
+ * is rewritten, reordered or dropped, and an already-present title is a no-op —
+ * so a plan can grow mid-run but never shrink, and a retried insert cannot
+ * duplicate. Returns whether a line was added.
+ *
+ * Run against a real plan: inserting a new title after entry 0 returns true and
+ * lands it directly after that entry; the same title again returns false; a title
+ * that is already present AND CHECKED also returns false; an empty title returns
+ * false. Everything else keeps its order.
  *
  * Later entries shift down by one, which is safe because the /task-auto loop
  * re-reads and re-parses the plan at the top of every iteration and locates its
- * next step by "first unchecked" rather than by a cached index.
+ * next step with `entries.find(e => !e.done)` — first unchecked — rather than a
+ * cached index.
  */
 export async function insertTaskAfter(cwd, id, afterIndex, title) {
     const clean = title.trim();
@@ -186,8 +204,13 @@ export async function insertTaskAfter(cwd, id, afterIndex, title) {
         if (seen === afterIndex)
             break;
     }
-    // An out-of-range index appends after the LAST checkbox rather than throwing:
-    // a plan that grew underneath the caller must still receive the entry.
+    // 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
+    // plan that grew underneath the caller must still receive it. Confirmed with
+    // afterIndex 99 on a five-entry plan.
+    //
+    // The guard below is the different case: a `## tasks` section with NO checkbox
+    // lines at all, where there is no position to splice into.
     if (insertAt === -1)
         return false;
     lines.splice(insertAt, 0, `- [ ] ${clean}`);
@@ -199,12 +222,17 @@ export async function insertTaskAfter(cwd, id, afterIndex, title) {
  * last-write time the resume banner reports (see resume-gap.ts). Null when there
  * is nothing resumable.
  *
- * `states` narrows which states count as resumable, and the UNATTENDED path passes
- * UNATTENDED_STATES so the search answers the question that path actually asks —
- * "is there an IN-FLIGHT run to pick up?". Selecting the newest human-resumable run
- * and only then refusing it on state let one failed run shadow an in-flight one
- * behind it: the boot hook refused every restart and the in-flight run stayed in
- * exactly the dead air this feature exists to end.
+ * `states` narrows which states count as resumable BEFORE the newest-wins sort,
+ * and that ordering is the whole point. The UNATTENDED path passes
+ * UNATTENDED_STATES so the search answers the question it actually asks — "is
+ * there an IN-FLIGHT run to pick up?"
+ *
+ * Filtering after the sort instead would let one failed run shadow an in-flight
+ * one behind it. Demonstrated on two files, the newer `failed` and the older
+ * `in_progress`: the default states pick the newer failed one, while
+ * UNATTENDED_STATES picks the older in-progress one. Had the newest been chosen
+ * first and only then refused on state, the restart would find nothing and the
+ * in-flight run would sit in exactly the dead air this exists to end.
  */
 export async function findResumableAutoDetailed(cwd, states = RESUMABLE_STATES) {
     await ensureTasksDir(cwd);

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

@@ -16,15 +16,15 @@ export interface AutoDeps extends GateDeps, FinalGateStageDeps {
     runChild: (name: string, tools: string, prompt: string) => Promise<string>;
     /**
      * Paths with unmerged index entries (an in-progress merge conflict). The loop
-     * refuses to START a task on a conflicted tree — mx5 run 6 ran a full impl turn
-     * plus three verifies against one, with every commit doomed from the outset.
+     * refuses to START a task on a conflicted tree: a full implementation turn
+     * and its verifies run against one with every commit doomed from the outset.
      * Absent (tests) → treated as clean.
      */
     unmergedPaths?: (cwd: string) => Promise<string[]>;
     /**
      * Sha of refs/stash or null. Compared around each task so a stash pushed (or
      * consumed) during the task and left behind is called out — an orphan stash is
-     * exactly the landmine that detonated as an unresolvable conflict in run 6.
+     * exactly the landmine that detonates as an unresolvable conflict later.
      * Absent (tests) → the check is skipped.
      */
     stashRef?: (cwd: string) => Promise<string | null>;
@@ -50,34 +50,35 @@ export declare function expandFeatureMentions(cwd: string, feature: string): Pro
 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 design doc the feature pointed at and the user's clarification choices have
- * to ride along or they're invisible downstream — this is how an "Implement
- * @design.md" run built a generic `posts` table the spec never mentioned, and how
- * a "do not use vite" clarification got silently overridden by the doc's own
- * vite.config.ts.
+ * decomposed task title. A title is ALL a per-task pipeline ever sees, so both the
+ * design doc the feature pointed at and the user's clarification choices have to
+ * ride along or they are invisible downstream — a task that cannot see the doc
+ * invents its own schema, and one that cannot see "do not use vite" is overridden
+ * by whatever the doc's own config says.
  *
- * Precedence is the crux: a clarification is a CORRECTION to a (possibly stale)
- * spec doc, so the decisions clause is marked as overriding the doc, while the doc
- * stays authoritative for everything the decisions don't touch. Decompose scopes
- * each decision to the task(s) it governs, so most titles carry none. No readable
- * refs and no decisions → title unchanged, so a doc-less /task-auto behaves
- * exactly as before.
+ * Precedence is the crux: a clarification is a CORRECTION to a possibly stale spec
+ * doc, so the decisions clause is marked as overriding the doc while the doc stays
+ * authoritative for everything the decisions do not touch. The emitted order puts
+ * decisions first, then the spec ref. Decompose scopes each decision to the tasks
+ * it governs, so most titles carry none.
+ *
+ * Run: with no refs and no decisions the title comes back unchanged, and
+ * re-threading an already-threaded list is a no-op.
  */
 export declare function attachSpecRefs(titles: string[], refs: string[]): string[];
 /**
  * Build the refine scope fence for step `currentIndex` of an N-step /task-auto
  * plan. Every per-step pipeline only ever sees its own title, so without this the
  * refine phase — told "the task title is only a pointer into that spec; follow the
- * spec" — re-expands the whole referenced design into one task (a real run
- * implemented all 24 steps under step 1). The fence lists the sibling steps by
- * number and forbids touching anything they own, so refine bounds this step's
- * slice. Validated on the local model: with the fence, refine's CONSTRAINTS gained
- * an explicit per-step deferral list and tool calls dropped 27→11.
+ * spec" — re-expands the whole referenced design into a single task, implementing
+ * the entire plan under step one. The fence lists the sibling steps by number and
+ * forbids touching anything they own, so refine bounds this step's slice.
  *
  * The plan listing strips the threaded "| decisions … | spec …" tail from each
- * title (keeps the human-readable head) so the model reads clean step names. The
- * authoritative spec ref still rides on THIS step's own title via attachSpecRefs.
+ * 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
+ * over threaded titles. The authoritative spec ref still rides on THIS step's own
+ * title via attachSpecRefs.
  */
 export declare function buildScopeFence(titles: string[], currentIndex: number): string;
 /**
@@ -117,8 +118,9 @@ export declare function orientFeature(cwd: string, feature: string, deps: AutoDe
  * 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.
+ * The ONLY stage that ASKS the user anything, and so the only one that can be
+ * dismissed — the others only notify, which cannot be. `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>;