@mjasnikovs/pi-task 0.35.0 → 0.36.0

package/dist/remote/bridge.d.ts

@@ -57,6 +57,12 @@ export interface AskSpec {
      * {@link AskQuestionBoxSpec.manualLabel}). Ignored without `options`.
      */
     manualLabel?: string;
+    /**
+     * Where the free-text card sits among `options` (see
+     * {@link AskQuestionBoxSpec.manualPosition}). Local picker only — remote
+     * browsers always render the text box above the action buttons.
+     */
+    manualPosition?: number;
     /**
      * Extra buttons the BROWSER card shows alongside the recommendation, each
      * answering with its own `value`. Unlike `options` — which are answers, and

package/dist/remote/bridge.js

@@ -101,6 +101,7 @@ export class SessionUI {
                     recommended: i === 0
                 })),
                 ...(spec.manualLabel !== undefined && { manualLabel: spec.manualLabel }),
+                ...(spec.manualPosition !== undefined && { manualPosition: spec.manualPosition }),
                 signal
             });
         }

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

@@ -43,13 +43,31 @@ export declare function buildPlanBody(task: string): string;
  * there is no hidden channel.
  */
 export declare function formatPlanDecisions(entries: readonly PlanEntry[]): string;
+/**
+ * The line that pins the DELIVERABLE, and it is not optional.
+ *
+ * The task prompt leads the handoff verbatim, and users reach /task-plan by
+ * phrasing the request as planning — live (aiz-client TASK_PLAN_0001,
+ * 2026-08-05): "Lets plan new tab and report @src/app/reports/". /task's refine
+ * read the verb as the deliverable and produced a task titled "Plan the addition
+ * of a new sub-tab…", whose ACCEPTANCE was "a planning document exists with
+ * placeholder sections" and whose VERIFY asserted that no `.ts`/`.tsx` file had
+ * changed. It passed. Nothing was built.
+ *
+ * Planning already happened — this prompt IS its output — so the handoff says so
+ * rather than letting the request's own wording re-open it. It rides on every
+ * handoff, decisions or none: the verb leaks regardless of how much got settled.
+ */
+export declare const HANDOFF_DELIVERABLE_RULE: string;
 /**
  * The prompt handed to /task when the user proceeds to execution.
  *
  * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
- * a normal task description first; the decisions follow as an authoritative block.
- * Anything the user did NOT settle is simply absent — /task's own grill phase asks
- * about what is left, which is why this block never invents a decision to fill a
- * gap.
+ * a normal task description first; the deliverable rule and then the decisions
+ * follow as an authoritative block. Anything the user did NOT settle is simply
+ * absent — /task's own grill phase asks about what is left, which is why this
+ * block never invents a decision to fill a gap. A question the user left
+ * unanswered is likewise absent: "(skipped)" is not a decision, and carrying it
+ * as one is how a non-answer becomes an instruction.
  */
 export declare function buildHandoffPrompt(task: string, entries: readonly PlanEntry[]): string;

package/dist/task/plan-io.js

@@ -73,20 +73,43 @@ export function buildPlanBody(task) {
 export function formatPlanDecisions(entries) {
     return entries.length === 0 ? '(none yet)' : formatPlanTranscript(entries);
 }
+/**
+ * The line that pins the DELIVERABLE, and it is not optional.
+ *
+ * The task prompt leads the handoff verbatim, and users reach /task-plan by
+ * phrasing the request as planning — live (aiz-client TASK_PLAN_0001,
+ * 2026-08-05): "Lets plan new tab and report @src/app/reports/". /task's refine
+ * read the verb as the deliverable and produced a task titled "Plan the addition
+ * of a new sub-tab…", whose ACCEPTANCE was "a planning document exists with
+ * placeholder sections" and whose VERIFY asserted that no `.ts`/`.tsx` file had
+ * changed. It passed. Nothing was built.
+ *
+ * Planning already happened — this prompt IS its output — so the handoff says so
+ * rather than letting the request's own wording re-open it. It rides on every
+ * handoff, decisions or none: the verb leaks regardless of how much got settled.
+ */
+export const HANDOFF_DELIVERABLE_RULE = 'PLANNING IS ALREADY DONE. This prompt is the OUTPUT of an interactive planning session '
+    + 'that has now ended; you are the implementation step. Build the thing. Do not produce a '
+    + 'plan, a design, a proposal, or a "planning-only" deliverable, do not write a document '
+    + 'whose acceptance is that no code changed, and do not defer the work pending user '
+    + 'confirmation — no user is available from here on.';
 /**
  * The prompt handed to /task when the user proceeds to execution.
  *
  * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
- * a normal task description first; the decisions follow as an authoritative block.
- * Anything the user did NOT settle is simply absent — /task's own grill phase asks
- * about what is left, which is why this block never invents a decision to fill a
- * gap.
+ * a normal task description first; the deliverable rule and then the decisions
+ * follow as an authoritative block. Anything the user did NOT settle is simply
+ * absent — /task's own grill phase asks about what is left, which is why this
+ * block never invents a decision to fill a gap. A question the user left
+ * unanswered is likewise absent: "(skipped)" is not a decision, and carrying it
+ * as one is how a non-answer becomes an instruction.
  */
 export function buildHandoffPrompt(task, entries) {
-    const decisions = entries.filter(e => e.kind !== 'note');
+    const decisions = entries.filter(e => e.kind !== 'note' && !(e.kind === 'decision' && /^\(skipped/i.test(e.answer.trim())));
+    const head = `${task.trim()}\n\n${HANDOFF_DELIVERABLE_RULE}`;
     if (decisions.length === 0)
-        return task.trim();
-    return (`${task.trim()}\n\n`
+        return head;
+    return (`${head}\n\n`
         + `PLANNING DECISIONS — these were settled with the user before this task was started. `
         + `They are authoritative: implement them as written, and do not re-open or contradict `
         + `them. They may not cover everything; decide anything they leave open as usual.\n\n`

package/dist/task/plan-prompts.js

@@ -67,6 +67,14 @@ repo, and any stated constraints; it is shown to the user as a recommendation th
 accept or override. When the question is a genuine binary "A or B?" fork, also give
 the single best alternative as an ALT line; otherwise emit only the one SUGGESTED.
 
+The SUGGESTED must DECIDE. Never recommend asking, clarifying, confirming, or
+checking with the user, and never recommend waiting, deferring, or leaving the
+question open — the user is answering this very question right now, so "find out
+from the user" is not an answer, it is the question you just asked. If you truly
+cannot tell which way to go, still commit to the option you would take if it were
+your call, and let the user override it. A default that could not be implemented
+as written is not a default.
+
 OUTPUT FORMAT (exact) — read as much as you like, but your written REPLY is 2 or
 3 lines and nothing else:
 - Do NOT report what you read. No preamble, no analysis, no findings, no numbered

package/dist/task/plan-session.d.ts

@@ -20,7 +20,10 @@
  *                                    doubles as "state a decision" when the model
  *                                    has nothing to ask
  *   ▶ proceed to execution        — stop planning, hand the decisions to /task
- *                                    (PLAN_PROCEED)
+ *                                    (PLAN_PROCEED). Always the LAST card in the
+ *                                    box — it ends the session, so it sits under
+ *                                    every move that continues it, including the
+ *                                    free-text card (see `manualPosition`).
  *
  * The loop is pure with respect to I/O: every side effect (child calls, dialogs,
  * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
@@ -85,6 +88,32 @@ export declare function pickQuestion<T extends {
  * Deliberately shallow — an "X or Y?" in the question's own clause.
  */
 export declare function looksLikeFork(question: string): boolean;
+/**
+ * Does the recommended default DEFER the decision instead of making one?
+ *
+ * The prompt asks for a "concrete, decisive default", and nothing enforced it.
+ * Live (aiz-client TASK_PLAN_0001, 2026-08-05): the model asked "what specific
+ * report should this new tab display?" and recommended
+ * "clarify with the user what the report is meant to show before proceeding".
+ * The user pressed enter, so it was recorded `(accepted recommendation)` and rode
+ * into /task's handoff as an AUTHORITATIVE decision — an order not to proceed,
+ * addressed to a run where no user exists. /task duly built a task whose
+ * ACCEPTANCE was "a planning document with placeholder sections" and whose VERIFY
+ * asserted that no source file had changed.
+ *
+ * A deferral is not an answer, and the one place it can never be one is here: the
+ * user IS present during planning, so "ask the user" is a null move — that IS the
+ * question. Detection is anchored to the START of the default, which keeps it off
+ * legitimate product behaviour ("prompt the user to confirm deletion" decides
+ * something; "ask the user which report" decides nothing).
+ */
+export declare function isDeferralSuggestion(suggested: string): boolean;
+/**
+ * Corrective re-prompt for a default that deferred the decision. Same one-shot
+ * budget and same quote-it-back shape as {@link planForkHint}, because the child
+ * is stateless and cannot otherwise know what it just recommended.
+ */
+export declare function planDecisiveHint(question: string, suggested: string): string;
 /**
  * Corrective re-prompt for a fork-shaped question that shipped only ONE option.
  *
@@ -109,6 +138,7 @@ export type PlanAskSpec = AskSpec & {
         value: string;
     }[];
     manualLabel: string;
+    manualPosition: number;
     actions: {
         label: string;
         value: string;
@@ -155,9 +185,10 @@ interface PendingQuestion {
 /**
  * Build the picker for a pending model question: the recommendation first (index
  * 0 is the green RECOMMENDED card), the alternative second when the question is a
- * binary fork, then the two control actions. The free-text card is appended by
+ * binary fork, then the two control actions. The free-text card is supplied by
  * askQuestionBox itself — that is the "answer in your own words" affordance, and
- * it is the same card grill and clarify already show.
+ * it is the same card grill and clarify already show — placed just above the
+ * trailing "proceed to execution" card so proceed stays last.
  */
 export declare function buildQuestionSpec(p: PendingQuestion): PlanAskSpec;
 /**
@@ -165,6 +196,8 @@ export declare function buildQuestionSpec(p: PendingQuestion): PlanAskSpec;
  * questions, or the cap/duplicate backstop stopped it. The same three moves are
  * still on offer; only "answer this question" is gone, because there is no
  * question, so the free-text card becomes "add a decision of your own".
+ * Proceed stays last here, as it is under a question: handing off to /task ends
+ * planning, so it never sits where a reflexive first-item press can hit it.
  */
 export declare function buildIdleSpec(): PlanAskSpec;
 /**

package/dist/task/plan-session.js

@@ -20,7 +20,10 @@
  *                                    doubles as "state a decision" when the model
  *                                    has nothing to ask
  *   ▶ proceed to execution        — stop planning, hand the decisions to /task
- *                                    (PLAN_PROCEED)
+ *                                    (PLAN_PROCEED). Always the LAST card in the
+ *                                    box — it ends the session, so it sits under
+ *                                    every move that continues it, including the
+ *                                    free-text card (see `manualPosition`).
  *
  * The loop is pure with respect to I/O: every side effect (child calls, dialogs,
  * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
@@ -98,6 +101,51 @@ export function pickQuestion(parsed) {
 export function looksLikeFork(question) {
     return /\bor\b/i.test(question.split('?')[0] ?? '');
 }
+/**
+ * Does the recommended default DEFER the decision instead of making one?
+ *
+ * The prompt asks for a "concrete, decisive default", and nothing enforced it.
+ * Live (aiz-client TASK_PLAN_0001, 2026-08-05): the model asked "what specific
+ * report should this new tab display?" and recommended
+ * "clarify with the user what the report is meant to show before proceeding".
+ * The user pressed enter, so it was recorded `(accepted recommendation)` and rode
+ * into /task's handoff as an AUTHORITATIVE decision — an order not to proceed,
+ * addressed to a run where no user exists. /task duly built a task whose
+ * ACCEPTANCE was "a planning document with placeholder sections" and whose VERIFY
+ * asserted that no source file had changed.
+ *
+ * A deferral is not an answer, and the one place it can never be one is here: the
+ * user IS present during planning, so "ask the user" is a null move — that IS the
+ * question. Detection is anchored to the START of the default, which keeps it off
+ * legitimate product behaviour ("prompt the user to confirm deletion" decides
+ * something; "ask the user which report" decides nothing).
+ */
+export function isDeferralSuggestion(suggested) {
+    const s = suggested.trim().replace(/^["'`*_\s]+/, '');
+    return (/^(ask|clarify|confirm|check|discuss|decide)\b[^.]{0,60}\b(with |from |the )?user\b/i.test(s)
+        || /^(wait|hold off|hold|defer|postpone|pause|park)\b/i.test(s)
+        || /^(tbd|to be (determined|decided|defined|specified))\b/i.test(s)
+        || /^(pending|awaiting|await)\b/i.test(s)
+        || /^leave (it|this|that)?\s*(to|for|open|undecided|unspecified)\b/i.test(s)
+        || /^the user (must|should|needs? to|has to|will)\b/i.test(s)
+        || /^(do not|don'?t|no)\b[^.]{0,40}\b(proceed|implement|build|start|write|decide)\b/i.test(s));
+}
+/**
+ * Corrective re-prompt for a default that deferred the decision. Same one-shot
+ * budget and same quote-it-back shape as {@link planForkHint}, because the child
+ * is stateless and cannot otherwise know what it just recommended.
+ */
+export function planDecisiveHint(question, suggested) {
+    return ('[SYSTEM NOTE: Your previous reply asked this question:\n'
+        + `"${question}"\n`
+        + `and recommended: "${suggested}"\n`
+        + 'That recommendation DEFERS the decision instead of making one — it tells the user to '
+        + 'ask, clarify, wait, or leave it open. The user is answering this question RIGHT NOW, so '
+        + '"find out from the user" is not an answer, it is the question you just asked. Ask the '
+        + 'SAME question again — do not change the subject — and this time make SUGGESTED a '
+        + 'concrete choice that could be implemented as written, naming real things from the repo. '
+        + 'If the question is a genuine A-or-B fork, add the ALT line too. Nothing else.]');
+}
 /**
  * Corrective re-prompt for a fork-shaped question that shipped only ONE option.
  *
@@ -124,9 +172,10 @@ export function planForkHint(question) {
 /**
  * Build the picker for a pending model question: the recommendation first (index
  * 0 is the green RECOMMENDED card), the alternative second when the question is a
- * binary fork, then the two control actions. The free-text card is appended by
+ * binary fork, then the two control actions. The free-text card is supplied by
  * askQuestionBox itself — that is the "answer in your own words" affordance, and
- * it is the same card grill and clarify already show.
+ * it is the same card grill and clarify already show — placed just above the
+ * trailing "proceed to execution" card so proceed stays last.
  */
 export function buildQuestionSpec(p) {
     const options = [];
@@ -153,7 +202,10 @@ export function buildQuestionSpec(p) {
         allowSkip: false,
         options: [...options, ...actions],
         actions,
-        manualLabel: PLAN_ANSWER_LABEL
+        manualLabel: PLAN_ANSWER_LABEL,
+        // The free-text card goes ABOVE "proceed to execution" — proceed ends the
+        // session, so it is the last card in the box, under every other move.
+        manualPosition: options.length + actions.length - 1
     };
 }
 /**
@@ -161,11 +213,13 @@ export function buildQuestionSpec(p) {
  * questions, or the cap/duplicate backstop stopped it. The same three moves are
  * still on offer; only "answer this question" is gone, because there is no
  * question, so the free-text card becomes "add a decision of your own".
+ * Proceed stays last here, as it is under a question: handing off to /task ends
+ * planning, so it never sits where a reflexive first-item press can hit it.
  */
 export function buildIdleSpec() {
     const actions = [
-        { label: PLAN_PROCEED_LABEL, value: PLAN_PROCEED },
-        { label: PLAN_ASK_LABEL, value: PLAN_ASK }
+        { label: PLAN_ASK_LABEL, value: PLAN_ASK },
+        { label: PLAN_PROCEED_LABEL, value: PLAN_PROCEED }
     ];
     return {
         localTitle: PLAN_NO_QUESTIONS,
@@ -177,7 +231,8 @@ export function buildIdleSpec() {
         allowSkip: false,
         options: actions,
         actions,
-        manualLabel: PLAN_STATE_LABEL
+        manualLabel: PLAN_STATE_LABEL,
+        manualPosition: actions.length - 1
     };
 }
 /**
@@ -278,11 +333,31 @@ export async function runPlanSession(deps) {
                 formatHint = PLAN_FORMAT_HINT;
                 continue;
             }
+            // A default that defers decides nothing, and an accepted deferral
+            // reaches /task dressed as an authoritative decision. One re-prompt to
+            // make it decisive; if it comes back deferring anyway the option is
+            // DROPPED rather than shown, so an empty submit records "(skipped)" —
+            // an unanswered question — instead of a decision the user never made.
+            const defers = suggested !== undefined && isDeferralSuggestion(suggested);
+            if (defers && formatHint === null) {
+                deps.logDebug?.('plan: SUGGESTED deferred the decision — one re-prompt');
+                formatHint = planDecisiveHint(plain, suggested);
+                continue;
+            }
+            // When only the recommendation defers, the ALT is still a real
+            // commitment: promote it so the question keeps a usable default.
+            const usableSuggested = defers ? alt : suggested;
+            const usableAlt = defers ? undefined : alt;
+            if (defers) {
+                deps.logDebug?.(usableSuggested === undefined ?
+                    'plan: SUGGESTED still deferred — question shown with no recommendation'
+                    : 'plan: SUGGESTED still deferred — promoted the ALT to the recommendation');
+            }
             // A question that offers a choice but ships one option leaves the
             // user typing out the alternative the model just named. Same one-shot
             // budget, quoting the question back so the (stateless) child re-asks
             // this one instead of a new one.
-            if (alt === undefined && formatHint === null && looksLikeFork(plain)) {
+            if (usableAlt === undefined && formatHint === null && !defers && looksLikeFork(plain)) {
                 deps.logDebug?.('plan: fork-shaped question with no ALT — one re-prompt');
                 formatHint = planForkHint(plain);
                 continue;
@@ -294,13 +369,13 @@ export async function runPlanSession(deps) {
             pending = {
                 plain,
                 shown: render(question),
-                ...(suggested !== undefined && {
-                    suggested: stripInlineMarkdown(suggested),
-                    shownSuggested: render(suggested)
+                ...(usableSuggested !== undefined && {
+                    suggested: stripInlineMarkdown(usableSuggested),
+                    shownSuggested: render(usableSuggested)
                 }),
-                ...(alt !== undefined && {
-                    alt: stripInlineMarkdown(alt),
-                    shownAlt: render(alt)
+                ...(usableAlt !== undefined && {
+                    alt: stripInlineMarkdown(usableAlt),
+                    shownAlt: render(usableAlt)
                 })
             };
         }

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

@@ -84,6 +84,14 @@ export interface AskQuestionBoxSpec {
      * what the card actually does.
      */
     manualLabel?: string;
+    /**
+     * Where the free-text card sits among the options. Defaults to the end, which
+     * is right when the picker is answering a question. /task-plan passes an
+     * earlier index so its "proceed to execution" card — the one that ENDS the
+     * session — is literally the last entry in the list, and never sits above a
+     * card the user is more likely to want.
+     */
+    manualPosition?: number;
 }
 /**
  * Show the boxed picker and resolve to the chosen option's `value`, the text the

package/dist/task/question-box.js

@@ -143,12 +143,14 @@ export class QuestionBoxComponent {
  */
 export async function askQuestionBox(ctx, spec) {
     const { question, options, inputTitle, signal } = spec;
+    const manualIndex = Math.max(0, Math.min(options.length, spec.manualPosition ?? options.length));
+    const asCard = (o) => ({ label: o.label, recommended: o.recommended });
     const cards = [
-        ...options.map(o => ({ label: o.label, recommended: o.recommended })),
-        { label: spec.manualLabel ?? MANUAL_CARD_LABEL }
+        ...options.slice(0, manualIndex).map(asCard),
+        { label: spec.manualLabel ?? MANUAL_CARD_LABEL },
+        ...options.slice(manualIndex).map(asCard)
     ];
     const colors = boxColors(ctx.ui.theme);
-    const manualIndex = options.length;
     const choice = await ctx.ui.custom((_tui, _theme, _kb, done) => {
         if (signal.aborted) {
             done(undefined);
@@ -167,5 +169,5 @@ export async function askQuestionBox(ctx, spec) {
     if (choice === manualIndex) {
         return ctx.ui.input(inputTitle, undefined, { signal });
     }
-    return options[choice]?.value;
+    return options[choice < manualIndex ? choice : choice - 1]?.value;
 }

package/package.json

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