@mjasnikovs/pi-task 0.13.17 → 0.13.19

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

@@ -34,14 +34,20 @@ 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 into every decomposed task title.
- * Decompose emits titles only, and a title is ALL a per-task pipeline ever sees
- * — so without this the design doc the feature pointed at is invisible
- * downstream and each task drifts to a generic reading of its one-line title
- * (this is how an "Implement @design.md" run built a generic `posts` table the
- * spec never mentioned). Appending the @refs makes the per-task refine/research
- * read the real spec and treat it as authoritative over the title. No readable
- * refs → titles unchanged, so a doc-less /task-auto behaves exactly as before.
+ * 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.
+ *
+ * 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.
  */
 export declare function attachSpecRefs(titles: string[], refs: string[]): string[];
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */

package/dist/task/auto-orchestrator.js

@@ -11,15 +11,20 @@ import { runSingleTask } from './orchestrator.js';
 import { parseClarifyList, deriveTitle } from './parsers.js';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
 import { AUTO_CLARIFY_PROMPT, AUTO_DECOMPOSE_PROMPT } from './auto-prompts.js';
+import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './question-dedup.js';
 import { allocateAutoId, buildAutoBody, parseDecomposeList, parseTaskList, checkOffTask, stampTaskInProgress, findResumableAuto } from './auto-io.js';
 import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath } from './task-io.js';
 import { gitCommitAll } from './auto-commit.js';
-import { runPhaseChild, USER_CANCELLED } from './child-runner.js';
+import { runPhaseChild, prependHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI, registerBridgeCommand } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { getConfig } from '../config/config.js';
 import { startAutoLoader } from './widget.js';
 import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
+// Hard ceiling on clarify questions per feature. The loop is open-ended (it stops
+// when the model emits NONE), but a model that never says NONE would otherwise
+// barrage the user — the real mx5 run asked 10, several of them redundant.
+const MAX_CLARIFY_QUESTIONS = 8;
 // Matches pi's @-file completion token (a path after @, until whitespace).
 const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
 /**
@@ -75,22 +80,41 @@ export async function readableMentions(cwd, feature) {
     }
     return out;
 }
+/** A trailing "[decisions: …]" clause decompose may attach to a task line. */
+const DECISIONS_RE = /\s*\[decisions:\s*(.+?)\]\s*$/i;
 /**
- * Thread the feature's spec references into every decomposed task title.
- * Decompose emits titles only, and a title is ALL a per-task pipeline ever sees
- * — so without this the design doc the feature pointed at is invisible
- * downstream and each task drifts to a generic reading of its one-line title
- * (this is how an "Implement @design.md" run built a generic `posts` table the
- * spec never mentioned). Appending the @refs makes the per-task refine/research
- * read the real spec and treat it as authoritative over the title. No readable
- * refs → titles unchanged, so a doc-less /task-auto behaves exactly as before.
+ * 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.
+ *
+ * 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.
  */
 export function attachSpecRefs(titles, refs) {
-    if (refs.length === 0)
-        return titles;
     const list = refs.map(r => '@' + r).join(' ');
-    const suffix = ` | spec: ${list} — authoritative; read it and follow it over this title wherever they differ`;
-    return titles.map(t => (t.includes('| spec:') ? t : t + suffix));
+    return titles.map(t => {
+        if (t.includes('| spec:') || t.includes('| decisions'))
+            return t; // already threaded
+        const dm = DECISIONS_RE.exec(t);
+        const base = dm ? t.slice(0, dm.index).trimEnd() : t;
+        const decisions = dm ? dm[1].trim() : '';
+        let out = base;
+        if (decisions) {
+            out += ` | decisions (explicit user choices — these OVERRIDE the spec doc wherever they conflict; follow them exactly): ${decisions}`;
+        }
+        if (refs.length > 0) {
+            out += ` | spec: ${list} — otherwise authoritative; read it and follow it over this title wherever they differ`;
+        }
+        return out;
+    });
 }
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export async function planAuto(ctx, cwd, feature, deps) {
@@ -109,17 +133,39 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // the real content, not a one-line "Implement @file" that reads as trivial.
     const featureForModel = await expandFeatureMentions(cwd, feature);
     const answers = [];
-    // Open-ended: keep asking until the model emits NONE or the user dismisses.
-    for (;;) {
-        const qRaw = await deps.runChild('auto-clarify', 'read', AUTO_CLARIFY_PROMPT(featureForModel, answers.join('\n')));
+    // Plain text of every question already shown, for the duplicate backstop.
+    const askedQuestions = [];
+    // Deterministic guard against a model that ignores "never re-ask": consecutive
+    // near-duplicate questions are reprompted with an explicit hint, and once it
+    // strikes out (can't produce anything novel) we stop instead of barraging the
+    // user with the same decision worded N ways. Also caps the absolute count.
+    let dupStrikes = 0;
+    let dupHint = null;
+    // Open-ended: keep asking until the model emits NONE or the user dismisses —
+    // but never past MAX_CLARIFY_QUESTIONS distinct questions.
+    while (askedQuestions.length < MAX_CLARIFY_QUESTIONS) {
+        const qRaw = await deps.runChild('auto-clarify', 'read', prependHint(dupHint, AUTO_CLARIFY_PROMPT(featureForModel, answers.join('\n'))));
         const parsed = parseClarifyList(qRaw);
         if (parsed.length === 0)
             break; // NONE / nothing left to ask
+        // Backstop: if the model re-asked a topic already settled, don't surface it.
+        // Reprompt it to move on or finish; give up after MAX_DUP_STRIKES so a model
+        // stuck on one fork can't loop forever.
+        if (isDuplicateQuestion(askedQuestions, stripInlineMarkdown(parsed[0].question))) {
+            dupStrikes++;
+            if (dupStrikes >= MAX_DUP_STRIKES)
+                break;
+            dupHint = DUP_REPROMPT_HINT;
+            continue;
+        }
+        dupStrikes = 0;
+        dupHint = null;
         const { question, suggested, alt } = parsed[0];
         // Render markdown (bold/code) for the displayed prompt; keep plain text
         // for the editable default and the persisted file.
         const shownQ = renderInlineMarkdown(question, theme);
         const plainQ = stripInlineMarkdown(question);
+        askedQuestions.push(plainQ);
         const plainSuggested = suggested === undefined ? undefined : stripInlineMarkdown(suggested);
         const plainAlt = alt === undefined ? undefined : stripInlineMarkdown(alt);
         // Identical to /task's grill dialog: a binary fork becomes a select()

package/dist/task/auto-prompts.js

@@ -82,4 +82,10 @@ RULES:
 - Order tasks so earlier ones unblock later ones (foundations first).
 - Each task should be independently implementable as a single /task run.
 - Prefer a handful of substantial tasks over many trivial ones.
+- When a CLARIFICATION decision governs a task, append it to that task's line as
+  "[decisions: <directive>]" — include ONLY the decisions that bear on that task,
+  and attach a cross-cutting decision to EACH task it governs. Most tasks carry
+  none. These are explicit user choices that may contradict the referenced spec
+  doc; phrase them as imperative directives (e.g. "use Bun's built-in bundler, do
+  not add vite"). Do NOT invent decisions — only restate ones from CLARIFICATIONS.
 - Output the checkbox list and NOTHING else (no preamble, no numbering).`;

package/dist/task/phases.js

@@ -14,6 +14,7 @@ import { gatherExternalContext } from './external-context.js';
 import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS, appendNoThink } from './prompts.js';
 import { setTaskSection, updateTaskFrontMatter } from './task-io.js';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
+import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './question-dedup.js';
 import { parseGrillQuestions, parseAutoAnswer, autoAnswerHasTag, parseVerifyToolingOutput, deriveTitle } from './parsers.js';
 import { parseVerifyBlock, validateSpecShape, stripSpecPreamble, isCritiqueClean } from './spec-validation.js';
 import { runPhaseChild, runPhaseWithLoopGuard, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
@@ -314,15 +315,37 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
     const ui = new SessionUI(ctx);
     const out = []; // human-facing Q&A transcript (with auto-worker debug lines)
     const qa = []; // compact Q&A fed back into the next question
+    const askedQuestions = []; // plain text of each question, for the dup backstop
+    // Deterministic backstop against a model that ignores "never re-ask": a
+    // near-duplicate question is reprompted (not auto-answered or shown), and after
+    // MAX_DUP_STRIKES consecutive dups the loop stops. Each question otherwise runs
+    // the research-backed auto-answer, which fans out doc/fetch/search workers — so
+    // a re-ask isn't just an extra prompt, it's an expensive recompute. Capped at
+    // MAX_GRILL_QUESTIONS so a model that never emits NONE can't run unbounded.
+    let dupStrikes = 0;
+    let dupHint = null;
     // Open-ended: keep asking until the model emits NONE or the user dismisses.
-    for (let n = 0;; n++) {
+    for (let n = 0; n < MAX_GRILL_QUESTIONS; n++) {
         const tGenStart = Date.now();
-        const raw = await runPhaseWithLoopGuard(deps, 'grill-gen', 'read', hint => prependHint(hint, GRILL_GEN_PROMPT(refined, research, qa.join('\n'))));
+        const genHint = dupHint;
+        const raw = await runPhaseWithLoopGuard(deps, 'grill-gen', 'read', hint => prependHint(hint, prependHint(genHint, GRILL_GEN_PROMPT(refined, research, qa.join('\n')))));
         deps.recordSubStep?.('gen', Date.now() - tGenStart);
         const questions = parseGrillQuestions(raw);
         if (questions.length === 0)
             break; // NONE / nothing left to ask
         const q = questions[0];
+        // Suppress a re-asked decision before paying for its auto-answer.
+        if (isDuplicateQuestion(askedQuestions, stripInlineMarkdown(q))) {
+            dupStrikes++;
+            if (dupStrikes >= MAX_DUP_STRIKES)
+                break;
+            dupHint = DUP_REPROMPT_HINT;
+            n--;
+            continue;
+        }
+        dupStrikes = 0;
+        dupHint = null;
+        askedQuestions.push(stripInlineMarkdown(q));
         widgetState.lastLine = `auto-answering Q${n + 1}…`;
         const tAutoStart = Date.now();
         const auto = await phaseAutoAnswer(deps, refined, research, q);

package/dist/task/prompts.d.ts

@@ -4,7 +4,7 @@
  * Each template is a pure function: inputs → prompt string.  No I/O, no side
  * effects, trivially testable.
  */
-export declare const MAX_GRILL_QUESTIONS = 10;
+export declare const MAX_GRILL_QUESTIONS = 20;
 /**
  * Qwen3 "soft switch": placing `/no_think` in the prompt disables the model's
  * <think> reasoning trace for that turn and persists across the tool-call loop

package/dist/task/prompts.js

@@ -4,7 +4,10 @@
  * Each template is a pure function: inputs → prompt string.  No I/O, no side
  * effects, trivially testable.
  */
-export const MAX_GRILL_QUESTIONS = 10;
+// Caps both the per-response question count (parseGrillQuestions/parseClarifyList)
+// and the grill loop's total iterations, so a model that never emits NONE can't
+// run unbounded.
+export const MAX_GRILL_QUESTIONS = 20;
 /**
  * Qwen3 "soft switch": placing `/no_think` in the prompt disables the model's
  * <think> reasoning trace for that turn and persists across the tool-call loop

package/dist/task/question-dedup.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Detects when a freshly-generated clarifying question is a near-duplicate of one
+ * already asked. The clarify/grill loops re-call the generator after every answer
+ * and rely on a prompt instruction ("Never re-ask something already answered") to
+ * stop repeats. A weaker local model ignores that and re-asks the same fork worded
+ * differently (observed: a "Bun bundler vs Vite" question asked four ways across a
+ * single run). This is a deterministic backstop so a model that won't self-police
+ * can't barrage the user with the same decision.
+ *
+ * Pure logic, no I/O — trivially unit-testable, and validated against the actual
+ * repeated questions from a real /task-auto run (see question-dedup.test.ts).
+ */
+/**
+ * Lowercase, drop markdown emphasis/backticks, split on non-alphanumeric, then
+ * drop stopwords and 1-char tokens. `pg_trgm` → `pg`,`trgm`; `bun:sql` → `bun`,`sql`.
+ */
+export declare function tokenizeQuestion(q: string): Set<string>;
+/** Jaccard similarity of two token sets: |A∩B| / |A∪B|. 0 when either is empty. */
+export declare function jaccard(a: Set<string>, b: Set<string>): number;
+export declare const DEFAULT_DUP_THRESHOLD = 0.12;
+/**
+ * True when `next` is a near-duplicate of any question in `prior` (Jaccard of
+ * salient tokens ≥ threshold). Compares against the actual question text already
+ * asked, so a re-worded re-ask of an already-answered fork is caught.
+ */
+export declare function isDuplicateQuestion(prior: readonly string[], next: string, threshold?: number): boolean;
+export declare const MAX_DUP_STRIKES = 2;
+export declare const DUP_REPROMPT_HINT: string;

package/dist/task/question-dedup.js

@@ -0,0 +1,172 @@
+/**
+ * Detects when a freshly-generated clarifying question is a near-duplicate of one
+ * already asked. The clarify/grill loops re-call the generator after every answer
+ * and rely on a prompt instruction ("Never re-ask something already answered") to
+ * stop repeats. A weaker local model ignores that and re-asks the same fork worded
+ * differently (observed: a "Bun bundler vs Vite" question asked four ways across a
+ * single run). This is a deterministic backstop so a model that won't self-police
+ * can't barrage the user with the same decision.
+ *
+ * Pure logic, no I/O — trivially unit-testable, and validated against the actual
+ * repeated questions from a real /task-auto run (see question-dedup.test.ts).
+ */
+// Function words plus the boilerplate the prompt makes every question share
+// ("should we use", "or should", "this determines whether the task", …). Stripping
+// these keeps the comparison on the salient nouns that actually identify a topic
+// (vite, bundler, sharp, multer) instead of the scaffolding common to all of them.
+const STOPWORDS = new Set([
+    'the',
+    'a',
+    'an',
+    'and',
+    'or',
+    'of',
+    'to',
+    'in',
+    'on',
+    'for',
+    'with',
+    'as',
+    'by',
+    'at',
+    'be',
+    'is',
+    'are',
+    'should',
+    'we',
+    'use',
+    'used',
+    'using',
+    'it',
+    'its',
+    'this',
+    'that',
+    'these',
+    'those',
+    'into',
+    'from',
+    'than',
+    'then',
+    'so',
+    'if',
+    'whether',
+    'which',
+    'what',
+    'how',
+    'do',
+    'does',
+    'add',
+    'added',
+    'also',
+    'only',
+    'just',
+    'like',
+    'such',
+    'them',
+    'they',
+    'their',
+    'there',
+    'here',
+    'will',
+    'would',
+    'can',
+    'could',
+    'instead',
+    'rather',
+    'either',
+    'both',
+    'each',
+    'all',
+    'any',
+    'some',
+    'more',
+    'most',
+    'over',
+    'up',
+    'out',
+    'no',
+    'not',
+    'without',
+    'before',
+    'after',
+    'while',
+    'during',
+    'team',
+    'want',
+    'wants',
+    'approach',
+    'simpler',
+    'simple',
+    'specified',
+    'mentioned',
+    'set',
+    'sets',
+    'task',
+    'tasks',
+    'whole',
+    'entire',
+    'single',
+    'separate',
+    'new',
+    'extra',
+    'changes',
+    'change',
+    'determines',
+    'critical',
+    'because',
+    'mode',
+    'forks',
+    'fork',
+    'header',
+    'stack',
+    'lighter',
+    'built'
+]);
+/**
+ * Lowercase, drop markdown emphasis/backticks, split on non-alphanumeric, then
+ * drop stopwords and 1-char tokens. `pg_trgm` → `pg`,`trgm`; `bun:sql` → `bun`,`sql`.
+ */
+export function tokenizeQuestion(q) {
+    const cleaned = q.toLowerCase().replace(/\*\*/g, ' ').replace(/`/g, ' ');
+    const tokens = cleaned.split(/[^a-z0-9]+/).filter(t => t.length > 1 && !STOPWORDS.has(t));
+    return new Set(tokens);
+}
+/** Jaccard similarity of two token sets: |A∩B| / |A∪B|. 0 when either is empty. */
+export function jaccard(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+// Validated against the real mx5 run (question-dedup.test.ts): the re-asked
+// SPA-build/serve forks scored 0.152 / 0.275 / 0.421 against an earlier question,
+// while every genuinely-distinct subsystem question topped out at 0.077. 0.12 sits
+// in that gap — above the distinct ceiling, below the lowest true duplicate — so
+// it catches the repeats without suppressing a real question.
+export const DEFAULT_DUP_THRESHOLD = 0.12;
+/**
+ * True when `next` is a near-duplicate of any question in `prior` (Jaccard of
+ * salient tokens ≥ threshold). Compares against the actual question text already
+ * asked, so a re-worded re-ask of an already-answered fork is caught.
+ */
+export function isDuplicateQuestion(prior, next, threshold = DEFAULT_DUP_THRESHOLD) {
+    const nextTokens = tokenizeQuestion(next);
+    if (nextTokens.size === 0)
+        return false;
+    return prior.some(p => jaccard(tokenizeQuestion(p), nextTokens) >= threshold);
+}
+// After this many consecutive near-duplicate questions, the question loop stops:
+// a model that can't produce a novel question after being told to move on has
+// nothing genuinely new left to ask. Shared by /task-auto's clarify loop and
+// /task's grill loop.
+export const MAX_DUP_STRIKES = 2;
+// Reprompt injected when a duplicate is caught — tells the model the topic is
+// settled and to either move to a different open fork or finish.
+export const DUP_REPROMPT_HINT = 'You just re-asked a decision that is ALREADY answered above. Do not ask about '
+    + 'it again, even reworded. Ask about a DIFFERENT subsystem or fork that remains '
+    + 'genuinely open, or output the termination token if nothing decision-changing '
+    + 'is left.';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.13.17",
+    "version": "0.13.19",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",