@mjasnikovs/pi-task 0.40.50 → 0.42.0

package/dist/task/health-repair.js

@@ -0,0 +1,124 @@
+import { parseRepairTitleFile } from './root-cause-repair.js';
+/** A path-like token: at least one directory separator, ending in a file name. */
+const PATH_TOKEN_RE = /(?:[\w.@-]+[\\/])+[\w.@-]+\.\w+/g;
+function normalisePath(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '').trim();
+}
+/**
+ * Resolve a token the output printed to the ONE tracked file it names. Linters
+ * print absolute paths, compilers print repo-relative ones, and a stack trace
+ * prints `node_modules/...` — the tracked list is what tells a deliverable from
+ * noise. An ambiguous suffix (two tracked `src/x.ts`) resolves to nothing rather
+ * than to a guess.
+ */
+function resolveTracked(token, cwd, tracked) {
+    let t = normalisePath(token);
+    const root = normalisePath(cwd);
+    if (root.length > 0 && t.startsWith(`${root}/`))
+        t = t.slice(root.length + 1);
+    if (tracked.includes(t))
+        return t;
+    const bySuffix = tracked.filter(r => t.endsWith(`/${r}`));
+    return bySuffix.length === 1 ? bySuffix[0] : null;
+}
+/**
+ * What a red health result is about. Null when the result records no failing
+ * command (a legacy baseline, or a signal with no per-command detail) — there is
+ * nothing a repair could be pinned to.
+ */
+export function healthRedSubject(health, cwd, tracked) {
+    const failing = (health.commands ?? []).find(c => c.outcome === 'fail');
+    if (!failing)
+        return null;
+    const files = [];
+    if (tracked) {
+        for (const m of (health.output ?? '').matchAll(PATH_TOKEN_RE)) {
+            const rel = resolveTracked(m[0], cwd, tracked);
+            if (rel !== null && !files.includes(rel))
+                files.push(rel);
+        }
+    }
+    return { command: failing.cmd, exitCode: failing.exitCode, files };
+}
+// ─── Plan entry ──────────────────────────────────────────────────────────────
+/**
+ * The plan title, in one of two fixed shapes the parser below recovers:
+ *   `repair src/a.ts, src/b.ts: \`bun run lint\` exits 1 (introduced by TASK_0033)`
+ *   `repair \`bun run lint\`: exits 1 (no task in this run owns it)`
+ * The subject sits right after the prefix so it is both the dedup key and what
+ * the scope fence pins.
+ */
+export function buildHealthRepairTitle(red) {
+    const exits = `exits ${red.exitCode ?? '?'}`;
+    const owner = red.owners.length > 0 ?
+        `introduced by ${red.owners.join(', ')}`
+        : 'no task in this run owns it';
+    return red.files.length > 0 ?
+        `repair ${red.files.join(', ')}: \`${red.command}\` ${exits} (${owner})`
+        : `repair \`${red.command}\`: ${exits} (${owner})`;
+}
+const PATH = String.raw `(?:[\w.@-]+\/)*[\w.@-]+\.\w+`;
+const HEALTH_REPAIR_TITLE_RE = new RegExp(`^repair\\s+(?:\`([^\`]+)\`\\s*:\\s*exits|(${PATH}(?:,\\s*${PATH})*)\\s*:\\s*\`([^\`]+)\`\\s+exits)\\s`);
+/** The command and files a health-repair title names, or null for any other title. */
+export function parseHealthRepairTitle(title) {
+    const m = HEALTH_REPAIR_TITLE_RE.exec(title.trim());
+    if (!m)
+        return null;
+    if (m[1] !== undefined)
+        return { command: m[1].trim(), files: [] };
+    return { command: m[3].trim(), files: m[2].split(',').map(f => f.trim()) };
+}
+/**
+ * Does the plan already carry a repair for this red? Same command, or any of the
+ * same files — including a file-scoped root-cause repair (root-cause-repair.ts),
+ * which pins the same file. Checked-off entries count: a repair that ran and
+ * failed lands in the debt ledger, never in the plan a second time.
+ */
+export function planCoversHealthRed(titles, red) {
+    const files = new Set(red.files.map(f => normalisePath(f).toLowerCase()));
+    return titles.some(t => {
+        const rootCause = parseRepairTitleFile(t);
+        if (rootCause !== null && files.has(normalisePath(rootCause).toLowerCase()))
+            return true;
+        const h = parseHealthRepairTitle(t);
+        if (h === null)
+            return false;
+        if (h.command === red.command)
+            return true;
+        return h.files.some(f => files.has(normalisePath(f).toLowerCase()));
+    });
+}
+/**
+ * The extra scope fence a health-repair entry carries into refine. Without it
+ * "repair src/a.ts" refines into "overhaul the client", and a fix child left free
+ * to choose greens a linter fastest by suppressing it — which is how the red in
+ * the run this closes was painted over the first time.
+ */
+export function buildHealthRepairFence(subject) {
+    const scope = subject.files.length > 0 ?
+        [
+            `  - ${subject.files.map(f => `\`${f}\``).join(', ')} ${subject.files.length > 1 ? 'are' : 'is'} the ONLY`,
+            '    file(s) you may modify. Do not refactor, restructure, or "improve" anything else,',
+            '    and do not create new files.'
+        ]
+        : [
+            '  - Modify only the files the command reports. Do not refactor, restructure, or',
+            '    "improve" anything else, and do not create new files.'
+        ];
+    return [
+        `REPAIR TASK — this step exists ONLY to make \`${subject.command}\` pass again. It`,
+        'was created because that check was red before this step, and every later step',
+        'would otherwise build on the red; it is not a feature step and must not grow into one.',
+        '',
+        'HARD CONSTRAINTS for this step (they override any broader reading of the title):',
+        ...scope,
+        '  - Fix the reported findings and nothing more. Do NOT redesign the build, the',
+        '    lint configuration, the schema, or any shared infrastructure — a wider change',
+        "    here would silently overwrite sibling tasks' shipped work.",
+        '  - Do NOT suppress, disable, ignore or weaken the check to make it pass: no',
+        '    disable comments, no ignore entries, no relaxed rules, no deleted or skipped',
+        '    tests. A finding is fixed in the code it reports.',
+        `  - The VERIFY block MUST be exactly: \`${subject.command}\` — the check that was`,
+        '    red. It passing is the whole acceptance criterion.'
+    ].join('\n');
+}

package/dist/task/ledger.d.ts

@@ -22,6 +22,16 @@ export interface LedgerSpec<T> {
      * writer produces, so it is an option, not a unification.
      */
     onNoop?: 'rewrite' | 'skip';
+    /**
+     * What `append` does when an incoming record's key is already stored:
+     *   'keep-first' (default) — the stored record wins, so provenance traces to
+     *     whoever established it first;
+     *   'replace' — the incoming record wins and moves to the end of the file, so
+     *     the freshest statement of a fact is the one that survives the cap.
+     * env-notes is the second kind: a re-measured environment fact SUPERSEDES the
+     * earlier one, and keeping the first is how a stale fact becomes permanent.
+     */
+    conflict?: 'keep-first' | 'replace';
 }
 export interface Ledger<T> {
     /** Absolute path of the ledger file for this cwd. */

package/dist/task/ledger.js

@@ -4,11 +4,11 @@
  * requirements, requirements-owned).
  *
  * The ritual is seven steps: read the file (ANY error → ''), parse it into records,
- * key the records, drop an incoming item whose key is already present, cap to the
- * newest MAX (oldest dropped), mkdir the tasks dir, write the whole file back
- * (`lines.join('\n') + '\n'`, plain `writeFile`, NOT atomic). Every fault is
- * swallowed — a ledger is a sharpener or an auditing aid, never a blocker of the
- * phase or gate that calls it.
+ * key the records, settle an incoming item whose key is already present (see
+ * `conflict`), cap to the newest MAX (oldest dropped), mkdir the tasks dir, write
+ * the whole file back (`lines.join('\n') + '\n'`, plain `writeFile`, NOT atomic).
+ * Every fault is swallowed — a ledger is a sharpener or an auditing aid, never a
+ * blocker of the phase or gate that calls it.
  *
  * What varies per site is the DATA SHAPE (file name, cap, key, line format, parser)
  * and exactly one RULE — what an append does when it adds nothing new (see
@@ -21,8 +21,9 @@
  *   • `read` is `parse(readRaw)`; every adapter's parser skips blank lines and lines
  *     it cannot read, so a corrupt line is dropped, never thrown on.
  *   • `append` with an empty batch is a no-op — it does not even create `.pi-tasks/`.
- *     Within a batch the first item with a key wins; a key already stored wins over
- *     the batch.
+ *     Under the default `conflict` the first item with a key wins within a batch,
+ *     and a key already stored wins over the batch; under `'replace'` the last
+ *     statement of a key wins and moves to the end.
  *   • `write` overwrites with exactly these records; an empty list writes an empty
  *     file (this is how a drained queue and a fully-resolved debt ledger look).
  *   • Neither `append` nor `write` ever throws.
@@ -33,6 +34,7 @@ import { tasksDir } from './task-io.js';
 export function makeLedger(spec) {
     const { file, max, key, serialize, parse } = spec;
     const onNoop = spec.onNoop ?? 'rewrite';
+    const conflict = spec.conflict ?? 'keep-first';
     const filePath = (cwd) => path.join(tasksDir(cwd), file);
     async function readRaw(cwd) {
         try {
@@ -57,14 +59,23 @@ export function makeLedger(spec) {
             const existing = await read(cwd);
             const seen = new Set(existing.map(key));
             const merged = [...existing];
+            let added = 0;
             for (const item of items) {
                 const k = key(item);
-                if (seen.has(k))
-                    continue;
-                seen.add(k);
+                if (seen.has(k)) {
+                    if (conflict === 'keep-first')
+                        continue;
+                    const at = merged.findIndex(m => key(m) === k);
+                    if (at !== -1)
+                        merged.splice(at, 1);
+                }
+                else {
+                    seen.add(k);
+                    added++;
+                }
                 merged.push(item);
             }
-            if (merged.length === existing.length && onNoop === 'skip')
+            if (added === 0 && onNoop === 'skip')
                 return;
             const kept = max === undefined ? merged : merged.slice(-max);
             await persist(cwd, kept);

package/dist/task/lint-fix.d.ts

@@ -1,8 +1,19 @@
+import type { SpecContradiction } from './gate-resolution.js';
 export interface LintFixResult {
     /** true → findings fixed, repo health passes, work preserved. */
     ok: boolean;
+    /**
+     * WHAT this pass proved, as data. `frozen-path` used to travel as a
+     * `frozen-path:` prefix on `reason`, which the gate loop recovered by
+     * re-typing the literal — a reword of either side silently disarmed the
+     * cross-task-contradiction routing.
+     */
+    class: 'converged' | 'frozen-path' | 'not-applied';
     /** why the fix was not applied (guard trip, no convergence, child error). */
     reason?: string;
+    /** Set exactly on `frozen-path`: the criterion and the frozen path whose edit
+     *  is the only way to meet it, for the gate's decision table. */
+    contradiction?: SpecContradiction;
 }
 export interface LintFixDeps {
     cwd: string;

package/dist/task/lint-fix.js

@@ -261,6 +261,7 @@ export async function runBoundedLintFix(deps) {
         deps.log?.(`lint-fix REVERT-GUARD — discarded ${violations.length} work file(s)`);
         return {
             ok: false,
+            class: 'not-applied',
             reason: `revert-guard: fix pass discarded work (${violations.slice(0, 3).join(', ')}`
                 + `${violations.length > 3 ? ', …' : ''}) — fix ${snapshot ? 'rolled back' : 'REJECTED but no snapshot to restore'}`
         };
@@ -288,6 +289,7 @@ export async function runBoundedLintFix(deps) {
                 deps.log?.(`lint-fix CROSS-TASK-DELETION GUARD — ${named[0]}`);
                 return {
                     ok: false,
+                    class: 'not-applied',
                     reason: `cross-task-deletion: fix child DELETED sibling task deliverable(s) `
                         + `(${named.slice(0, 3).join('; ')}${crossDeletions.length > 3 ? '; …' : ''}) `
                         + `— restored from HEAD; deleting another task's committed work is not a fix`
@@ -311,6 +313,8 @@ export async function runBoundedLintFix(deps) {
                 deps.log?.(`lint-fix FROZEN-PATH GUARD — ${frozenViolations.slice(0, 3).join(', ')}`);
                 return {
                     ok: false,
+                    class: 'frozen-path',
+                    contradiction: { criterion: deps.failReason, frozenPath: frozenViolations[0] },
                     reason: `frozen-path: fix child modified spec-frozen path(s) `
                         + `(${frozenViolations.slice(0, 3).join(', ')}`
                         + `${frozenViolations.length > 3 ? ', …' : ''}) — `
@@ -322,7 +326,7 @@ export async function runBoundedLintFix(deps) {
     }
     if (end.kind === 'error') {
         deps.log?.(`lint-fix child failed — ${end.msg}`);
-        return { ok: false, reason: `fix child failed: ${end.msg}` };
+        return { ok: false, class: 'not-applied', reason: `fix child failed: ${end.msg}` };
     }
     if (end.kind === 'blocked')
         deps.log?.(`lint-fix BLOCKED — ${end.note}`);
@@ -344,28 +348,30 @@ export async function runBoundedLintFix(deps) {
     const health = await deps.repoHealth();
     if (!health.ok) {
         if (end.kind === 'blocked') {
-            return { ok: false, reason: `fix child blocked: ${end.note}` };
+            return { ok: false, class: 'not-applied', reason: `fix child blocked: ${end.note}` };
         }
         // FROZEN-PATH TRACE on non-convergence: when the child was honest — it did
         // NOT touch the frozen path, so the guard above never tripped — but the
         // check is still red and its own output NAMES a frozen path (the typed
         // ESLint message quoted in this file's header), the findings can only be
-        // fixed by an edit this task's spec forbids. Report it under the same
-        // `frozen-path:` prefix as the guard trip, so the gate loop can route
-        // straight to the human picker instead of burning unattended AUTOFIX
-        // rounds an impl re-run under the same freeze cannot converge out of.
+        // fixed by an edit this task's spec forbids. Report the same
+        // `frozen-path` class as the guard trip, so the gate's decision table
+        // exits on round one instead of burning unattended AUTOFIX rounds an impl
+        // re-run under the same freeze cannot converge out of.
         const implicated = frozen.filter(p => pathNamedIn(`${health.reason}\n${health.output ?? ''}`, p));
         if (implicated.length > 0) {
             deps.log?.(`lint-fix FROZEN-PATH TRACE — ${implicated.slice(0, 3).join(', ')}`);
             return {
                 ok: false,
+                class: 'frozen-path',
+                contradiction: { criterion: health.reason, frozenPath: implicated[0] },
                 reason: `frozen-path: static findings implicate spec-frozen path(s) `
                     + `(${implicated.slice(0, 3).join(', ')}`
                     + `${implicated.length > 3 ? ', …' : ''}) — did not converge `
                     + `(${health.reason}); a fix under this task's constraints cannot converge`
             };
         }
-        return { ok: false, reason: `did not converge: ${health.reason}` };
+        return { ok: false, class: 'not-applied', reason: `did not converge: ${health.reason}` };
     }
-    return { ok: true, reason: guardNote };
+    return { ok: true, class: 'converged', ...(guardNote === undefined ? {} : { reason: guardNote }) };
 }

package/dist/task/loop-detector.d.ts

@@ -30,7 +30,15 @@ export interface ToolCall {
 export interface LoopHit {
     call: ToolCall;
     count: number;
-    windowSize: number;
+    /**
+     * How many recent calls `count` was counted over.
+     *
+     * OPTIONAL because a stall hit counts a streak or a byte total, not a window
+     * — it used to carry 0 there, which every renderer printed as "in the last 0
+     * calls". Absent means "this hit has no window"; a renderer must say what the
+     * hit actually measured instead.
+     */
+    windowSize?: number;
     /**
      * Set when the kill came from the whole-run StallDetector rather than this
      * short-window detector, naming which of its two rules tripped
@@ -63,11 +71,25 @@ export declare class LoopDetector {
     /** Revisits of one path needed to trip; defaults to the exact threshold. */
     private readonly pathThreshold;
     private readonly buf;
+    /**
+     * Every path the attempt has targeted, with the span it covered — the WHOLE
+     * attempt, not the window `buf` holds. It is the only record of what a killed
+     * attempt actually read: the kill fires from the tool-call hook, before a byte
+     * of answer text streams, so text carry-forward is empty by construction and
+     * the re-spawn would otherwise start blind.
+     */
+    private readonly visits;
     constructor(window?: number, threshold?: number, 
     /** Revisits of one path needed to trip; defaults to the exact threshold. */
     pathThreshold?: number);
     /** Record a tool call. Returns LoopHit if either threshold is breached, else null. */
     record(call: ToolCall): LoopHit | null;
+    /**
+     * The attempt's READ-SET, in first-seen order: every path it opened, with the
+     * line span when the call named one. This is what a restart carries instead of
+     * answer text — see {@link visits}.
+     */
+    visited(): string[];
     /**
      * Count same-path calls in the window that are "revisits" — accesses that end
      * no further into the file than the furthest line already covered for that
@@ -84,5 +106,32 @@ export declare class LoopDetector {
      */
     private countRevisits;
 }
-/** The restart hint a re-spawned child gets after a loop kill: names the call. */
-export declare function formatLoopHint(hit: LoopHit): string;
+/**
+ * What killed the attempt, as prose a human reads in a degraded section or a
+ * `loop events` line.
+ *
+ * ONE renderer because each rule measures something different — calls in a
+ * window, a consecutive streak, bytes against a context window — and a shared
+ * "×N in the last M calls" template printed the streak's absent window as
+ * "in the last 0 calls".
+ */
+export declare function describeLoopHit(hit: LoopHit): string;
+/**
+ * The read-set clause a restart hint carries, or '' when the killed attempt
+ * opened nothing.
+ *
+ * It is the only thing a loop restart CAN carry: the kill fires from the
+ * tool-call hook, so there is no partial answer to hand forward (which is why
+ * `loop` is absent from CARRY_FORWARD_REASONS in pi-worker-core.ts). Without it
+ * "do not re-read what you have already read" names no files and the re-spawn
+ * re-reads the same ones.
+ *
+ * Bounded so a rotation over hundreds of files cannot outgrow the prompt it is
+ * prepended to; the count keeps the elision honest.
+ */
+export declare function formatReadSet(visited: readonly string[]): string;
+/**
+ * The restart hint a re-spawned child gets after a loop kill: names the call, and
+ * the read-set the killed attempt built up.
+ */
+export declare function formatLoopHint(hit: LoopHit, visited?: readonly string[]): string;

package/dist/task/loop-detector.js

@@ -96,6 +96,14 @@ export class LoopDetector {
     threshold;
     pathThreshold;
     buf = [];
+    /**
+     * Every path the attempt has targeted, with the span it covered — the WHOLE
+     * attempt, not the window `buf` holds. It is the only record of what a killed
+     * attempt actually read: the kill fires from the tool-call hook, before a byte
+     * of answer text streams, so text carry-forward is empty by construction and
+     * the re-spawn would otherwise start blind.
+     */
+    visits = new Map();
     constructor(window = LOOP_WINDOW, threshold = LOOP_THRESHOLD, 
     /** Revisits of one path needed to trip; defaults to the exact threshold. */
     pathThreshold = threshold) {
@@ -107,9 +115,17 @@ export class LoopDetector {
     record(call) {
         const key = loopKey(call);
         const offset = readOffset(call.args);
-        this.buf.push({ key, path: primaryPath(call.args), offset, end: readEnd(call.args, offset) });
+        const path = primaryPath(call.args);
+        const end = readEnd(call.args, offset);
+        this.buf.push({ key, path, offset, end });
         if (this.buf.length > this.window)
             this.buf.shift();
+        if (path !== null) {
+            const seen = this.visits.get(path);
+            this.visits.set(path, seen ?
+                { from: Math.min(seen.from, offset), to: Math.max(seen.to, end) }
+                : { from: offset, to: end });
+        }
         // 1. Exact-match loop: identical (name, args) repeated past threshold.
         let exact = 0;
         for (const e of this.buf)
@@ -120,7 +136,6 @@ export class LoopDetector {
         // 2. Path-aware loop: the same file re-targeted without forward progress.
         // Caught here precisely because varied offset/limit change the exact key on
         // every call, so pattern 1 above can never see it.
-        const path = this.buf[this.buf.length - 1].path;
         if (path !== null) {
             const revisits = this.countRevisits(path);
             if (revisits >= this.pathThreshold) {
@@ -129,6 +144,14 @@ export class LoopDetector {
         }
         return null;
     }
+    /**
+     * The attempt's READ-SET, in first-seen order: every path it opened, with the
+     * line span when the call named one. This is what a restart carries instead of
+     * answer text — see {@link visits}.
+     */
+    visited() {
+        return [...this.visits].map(([path, span]) => span.to === Infinity ? path : `${path} (lines ${span.from}-${span.to})`);
+    }
     /**
      * Count same-path calls in the window that are "revisits" — accesses that end
      * no further into the file than the furthest line already covered for that
@@ -157,11 +180,64 @@ export class LoopDetector {
         return revisits;
     }
 }
-/** The restart hint a re-spawned child gets after a loop kill: names the call. */
-export function formatLoopHint(hit) {
+/**
+ * What killed the attempt, as prose a human reads in a degraded section or a
+ * `loop events` line.
+ *
+ * ONE renderer because each rule measures something different — calls in a
+ * window, a consecutive streak, bytes against a context window — and a shared
+ * "×N in the last M calls" template printed the streak's absent window as
+ * "in the last 0 calls".
+ */
+export function describeLoopHit(hit) {
+    const call = `${hit.call.name}(${JSON.stringify(hit.call.args)})`;
+    if (hit.stall === 'context-churn') {
+        return (`pulled in about ${hit.count} tokens of tool output, more than its `
+            + `${hit.windowSize}-token context window holds (last call ${call})`);
+    }
+    if (hit.stall === 'no-new-ground') {
+        return (`stopped covering new ground — ${hit.count} consecutive tool calls returned `
+            + `nothing it had not already seen (last call ${call})`);
+    }
+    return `stuck in a loop — called ${call} ×${hit.count} in the last ${hit.windowSize} calls`;
+}
+/**
+ * The read-set clause a restart hint carries, or '' when the killed attempt
+ * opened nothing.
+ *
+ * It is the only thing a loop restart CAN carry: the kill fires from the
+ * tool-call hook, so there is no partial answer to hand forward (which is why
+ * `loop` is absent from CARRY_FORWARD_REASONS in pi-worker-core.ts). Without it
+ * "do not re-read what you have already read" names no files and the re-spawn
+ * re-reads the same ones.
+ *
+ * Bounded so a rotation over hundreds of files cannot outgrow the prompt it is
+ * prepended to; the count keeps the elision honest.
+ */
+export function formatReadSet(visited) {
+    if (visited.length === 0)
+        return '';
+    const shown = visited.slice(0, MAX_READ_SET_ENTRIES);
+    const rest = visited.length - shown.length;
+    return (` You have already read, do not re-open: ${shown.join(', ')}`
+        + (rest > 0 ? `, and ${rest} more` : '')
+        + '.');
+}
+/**
+ * How many paths a restart hint lists. The read-set is a reminder, not an
+ * inventory: past a screenful the tail stops being read and only costs prefill,
+ * and the elision line still tells the child there was more.
+ */
+const MAX_READ_SET_ENTRIES = 40;
+/**
+ * The restart hint a re-spawned child gets after a loop kill: names the call, and
+ * the read-set the killed attempt built up.
+ */
+export function formatLoopHint(hit, visited = []) {
     const argsStr = JSON.stringify(hit.call.args);
     return (`[SYSTEM NOTE: Your prior attempt called ${hit.call.name}(${argsStr}) `
         + `${hit.count} times in the last ${hit.windowSize} tool calls — you appeared to be `
         + `stuck in a loop. Avoid repeating that exact call; if you've already seen its result, `
-        + `work from memory or pick a different angle.]`);
+        + `work from memory or pick a different angle.`
+        + `${formatReadSet(visited)}]`);
 }

package/dist/task/mentions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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[]>;

package/dist/task/mentions.js

@@ -0,0 +1,86 @@
+/**
+ * `@file` references in a prompt, and the two things done with them: inlining the
+ * file's contents for the planning children, and naming the files themselves.
+ *
+ * Its own module because both the PLANNING side (auto-orchestrator, which threads
+ * the spec doc into every task title) and the PHASE side (research, which lets the
+ * orientation core select a cited doc) need the same answer, and the phase side
+ * cannot import the orchestrator that imports it.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { readTextFile } from '../shared/fs-text.js';
+const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
+// Trailing punctuation a user naturally types AFTER an @-mention when it sits in
+// prose — "Implement @design.md, reuse…" or "see @spec.md." — which the greedy
+// [^\s]+ above would otherwise swallow into the path. Left unstripped, the
+// resulting "design.md," resolves to no file, expansion is silently skipped, and
+// the planner reasons over a one-line "Implement @design.md" with NO spec inline
+// → it fabricates generic questions and tasks the spec never called for.
+//
+// Measured against a real file: the greedy token from "Implement @design.md,
+// reuse the parser" is `design.md,`, which does not exist; stripped, `design.md`
+// does. None of these chars are legitimate trailing characters of a doc path.
+const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
+/** The cleaned path token of an @-mention: greedy match minus trailing prose punctuation. */
+function mentionPath(token) {
+    return token.replace(MENTION_TRAILING_PUNCT, '');
+}
+/** Every distinct @-mention path in `text`, in first-seen order. */
+function mentionPaths(text) {
+    const out = [];
+    const seen = new Set();
+    for (const m of text.matchAll(MENTION_RE)) {
+        const rel = mentionPath(m[1]);
+        if (rel === '' || seen.has(rel))
+            continue;
+        seen.add(rel);
+        out.push(rel);
+    }
+    return out;
+}
+/**
+ * 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 async function expandFeatureMentions(cwd, feature) {
+    const blocks = [];
+    for (const rel of mentionPaths(feature)) {
+        try {
+            // Normalize CRLF/CR so an @-mentioned design doc saved on Windows
+            // inlines with LF endings the downstream phase parsers expect.
+            const body = await readTextFile(path.resolve(cwd, rel));
+            if (body.trim().length > 0) {
+                blocks.push(`--- contents of ${rel} ---\n${body.trim()}`);
+            }
+        }
+        catch {
+            // not a readable file — leave the @token in place, skip expansion
+        }
+    }
+    return blocks.length === 0 ? feature : `${feature.trim()}\n\n${blocks.join('\n\n')}`;
+}
+/**
+ * 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 async function readableMentions(cwd, feature) {
+    const out = [];
+    for (const rel of mentionPaths(feature)) {
+        try {
+            await fsp.access(path.resolve(cwd, rel));
+            out.push(rel);
+        }
+        catch {
+            // not a readable file — don't thread it into task titles
+        }
+    }
+    return out;
+}