@mjasnikovs/pi-task 0.18.19 → 0.18.21

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![pi-task pipeline: a /task request runs through refine, research, grill, compose and critique, then the final spec is delivered to your main pi session in the same chat. Every phase boundary is persisted to .pi-tasks/TASK_NNNN.md, so the task is crash-safe and resumable.](https://raw.githubusercontent.com/mjasnikovs/pi-task/main/assets/pipeline.svg)
+![Local models drift. pi-task doesn't trust one prompt. Your ask runs through five fixed phases — refine, research, grill, compose, critique — and what comes out is a spec.](https://raw.githubusercontent.com/mjasnikovs/pi-task/main/assets/hero.svg)
 
 # pi-task
 
@@ -38,6 +38,22 @@ pi install npm:@mjasnikovs/pi-task
 
 > Requires [`pi`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (the Earendil coding agent) ≥ 0.80.
 
+## Quickstart
+
+One change — `/task` runs it through the full pipeline and hands the finished spec back in the same chat:
+
+```
+/task add rate limiting to the /api/upload endpoint
+```
+
+A whole plan — `/task-auto` splits it into an ordered task list and runs each one through `/task`:
+
+```
+/task-auto Implement @MY_DETAILED_AND_LARGE_PLAN.md
+```
+
+`@`-mentioning a file inlines its **contents**, so point it at the design doc you already wrote — no copy-paste.
+
 ## Slash commands
 
 | Command | What it does |
@@ -54,6 +70,12 @@ pi install npm:@mjasnikovs/pi-task
 
 ## The pipeline
 
+<div align="center">
+
+![pi-task pipeline: a /task request runs through refine, research, grill, compose and critique, then the final spec is delivered to your main pi session in the same chat. Every phase boundary is persisted to .pi-tasks/TASK_NNNN.md, so the task is crash-safe and resumable.](https://raw.githubusercontent.com/mjasnikovs/pi-task/main/assets/pipeline.svg)
+
+</div>
+
 | Phase | Output section | What happens |
 | --- | --- | --- |
 | **refine** | `refined prompt` | Sharpens your raw ask into an unambiguous, self-contained statement. |

package/assets/hero.svg

@@ -0,0 +1,92 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 600" width="960" height="600" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif" role="img" aria-label="pi-task. Local models drift. pi-task doesn't trust one prompt. Your ask runs through five fixed phases — refine, research, grill, compose, critique — and what comes out is a spec.">
+  <defs>
+    <clipPath id="frame"><rect x="6" y="6" width="948" height="588" rx="18"/></clipPath>
+    <style>
+      .code { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+      .ic   { fill:none; stroke-width:2.25; stroke-linecap:round; stroke-linejoin:round; }
+      .icf  { stroke:none; }
+      .ph   { font-size:18px; fill:#c9d1d9; }
+      .arw  { fill:none; stroke:#6e7681; stroke-width:2.07; stroke-linecap:round; stroke-linejoin:round; }
+    </style>
+  </defs>
+
+  <rect x="6" y="6" width="948" height="588" rx="18" fill="#0d1117" stroke="#30363d" stroke-width="1.5"/>
+
+  <!-- ── watermark ── -->
+  <defs>
+    <linearGradient id="mtFade" gradientUnits="userSpaceOnUse" x1="6" y1="0" x2="688" y2="0">
+      <stop offset="0" stop-color="#fff" stop-opacity="1"/>
+      <stop offset="0.55" stop-color="#fff" stop-opacity="0.9"/>
+      <stop offset="1" stop-color="#fff" stop-opacity="0"/>
+    </linearGradient>
+    <mask id="mtMask"><rect x="0" y="0" width="960" height="600" fill="url(#mtFade)"/></mask>
+  </defs>
+  <g clip-path="url(#frame)" mask="url(#mtMask)" fill="none" stroke="#a371f7" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M6.0 594.0L75.6 530.2L139.4 550.5L203.2 486.7L275.7 518.6L342.4 449.0L412.0 501.2L484.5 460.6L559.9 521.5L629.5 486.7L687.5 594.0" stroke-width="1.5" opacity="0.12"/>
+    <path d="M264.1 330.1L6.0 594.0M264.1 330.1L130.7 594.0M264.1 330.1L255.4 594.0M264.1 330.1L380.1 594.0M264.1 330.1L504.8 594.0M264.1 330.1L629.5 594.0" stroke-width="1" opacity="0.08"/>
+    <path d="M56.8 538.9L56.8 594.0M95.9 556.3L95.9 594.0M148.1 475.1L148.1 594.0M191.6 495.4L191.6 594.0M226.4 405.5L226.4 594.0M264.1 330.1L264.1 594.0M290.2 382.3L290.2 594.0M316.3 364.9L316.3 594.0M351.1 443.2L351.1 594.0M385.9 422.9L385.9 594.0M423.6 489.6L423.6 594.0M458.4 469.3L458.4 594.0M499.0 530.2L499.0 594.0M539.6 515.7L539.6 594.0M586.0 567.9L586.0 594.0" stroke-width="1" opacity="0.07"/>
+    <path d="M6.0 594.0L56.8 538.9L95.9 556.3L148.1 475.1L191.6 495.4L226.4 405.5L264.1 330.1L290.2 382.3L316.3 364.9L351.1 443.2L385.9 422.9L423.6 489.6L458.4 469.3L499.0 530.2L539.6 515.7L586.0 567.9L629.5 594.0" stroke-width="2" opacity="0.30"/>
+    <circle cx="6.0" cy="594.0" r="2.6" fill="#a371f7" stroke="none" opacity="0.34"/>
+    <circle cx="148.1" cy="475.1" r="2.6" fill="#a371f7" stroke="none" opacity="0.34"/>
+    <circle cx="264.1" cy="330.1" r="2.6" fill="#a371f7" stroke="none" opacity="0.34"/>
+    <circle cx="351.1" cy="443.2" r="2.6" fill="#a371f7" stroke="none" opacity="0.34"/>
+    <circle cx="458.4" cy="469.3" r="2.6" fill="#a371f7" stroke="none" opacity="0.34"/>
+    <circle cx="586.0" cy="567.9" r="2.6" fill="#a371f7" stroke="none" opacity="0.34"/>
+  </g>
+
+  <!-- ── logo lockup · π in a broken circle, drawn as paths (no font dependency) ── -->
+  <g transform="translate(371,59) scale(1.2500)" fill="none" stroke="#a371f7" stroke-width="2.40" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M30.18 4.98A20 20 0 1 0 41.66 14.61"/>
+    <path d="M13.5 17H34.5M19.5 17V32M28.5 17V32"/>
+  </g>
+  <text x="449" y="99" font-size="44" font-weight="700" fill="#e6edf3">pi-task</text>
+
+  <!-- ── headline ── -->
+  <text x="480" y="224" text-anchor="middle" font-size="82" font-weight="700" fill="#6e7681">Local models drift.</text>
+  <text x="480" y="319" text-anchor="middle" font-size="82" font-weight="700" fill="#e6edf3">pi-task doesn&#39;t trust</text>
+  <text x="480" y="414" text-anchor="middle" font-size="82" font-weight="700" fill="#e6edf3">one prompt.</text>
+
+  <!-- ── phase strip ── -->
+  <rect x="65" y="473" width="831" height="61" rx="30.5" fill="#161b22" fill-opacity="0.92" stroke="#30363d" stroke-width="1.5"/>
+  <g transform="translate(108,492.5) scale(0.9167)" stroke="#58a6ff">
+    <circle class="ic" cx="12" cy="12" r="10"/>
+    <path class="ic" d="M22 12h-4M6 12H2M12 6V2M12 22v-4"/>
+    <circle class="icf" cx="12" cy="12" r="2.4" fill="#58a6ff"/>
+  </g>
+  <text x="139" y="509.8" class="ph">refine</text>
+  <path class="arw" d="M195 503.5h17.2M206.6 496.8l6.7 6.7-6.7 6.7"/>
+  <g transform="translate(229,492.5) scale(0.9167)" stroke="#39c5cf">
+    <path class="ic" d="M9.56 9.83 15.44 6.67M10.1 12h4.79M9.56 14.17 15.44 17.33"/>
+    <circle class="icf" cx="5.5" cy="12" r="2.4" fill="#39c5cf"/>
+    <circle class="icf" cx="19.5" cy="4.5" r="2.1" fill="#39c5cf"/>
+    <circle class="icf" cx="19.5" cy="12" r="2.1" fill="#39c5cf"/>
+    <circle class="icf" cx="19.5" cy="19.5" r="2.1" fill="#39c5cf"/>
+  </g>
+  <text x="260" y="509.8" class="ph">research</text>
+  <path class="arw" d="M341 503.5h17.2M352.6 496.8l6.7 6.7-6.7 6.7"/>
+  <g transform="translate(375,492.5) scale(0.9167)" stroke="#d29922">
+    <path class="ic" d="M7.6 8.4a4.5 4.5 0 1 1 5.9 4.3c-.9.35-1.5 1.2-1.5 2.2v.6"/>
+    <circle class="icf" cx="12" cy="19.8" r="1.5" fill="#d29922"/>
+  </g>
+  <text x="406" y="509.8" class="ph">grill</text>
+  <path class="arw" d="M446 503.5h17.2M457.6 496.8l6.7 6.7-6.7 6.7"/>
+  <g transform="translate(480,492.5) scale(0.9167)" stroke="#3fb950">
+    <path class="ic" d="M12 2.5 22 7.5 12 12.5 2 7.5 12 2.5z"/>
+    <path class="ic" d="M2 16.5 12 21.5 22 16.5"/>
+  </g>
+  <text x="511" y="509.8" class="ph">compose</text>
+  <path class="arw" d="M597 503.5h17.2M608.5 496.8l6.7 6.7-6.7 6.7"/>
+  <g transform="translate(631,492.5) scale(0.9167)" stroke="#a371f7">
+    <path class="ic" d="M20.5 15a9 9 0 1 1-2.1-9.4L23 10"/>
+    <path class="ic" d="M23 4v6h-6"/>
+  </g>
+  <text x="662" y="509.8" class="ph">critique</text>
+  <path class="arw" d="M732 503.5h17.2M743.5 496.8l6.7 6.7-6.7 6.7"/>
+  <g transform="translate(766,492.5) scale(0.9167)" stroke="#3fb950">
+    <path class="ic" d="M14 2.5H6.5a2 2 0 0 0-2 2v15a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V8z"/>
+    <path class="ic" d="M14 2.5V8h5.5"/>
+    <path class="ic" d="M8.5 13.5h7M8.5 17.5h7"/>
+  </g>
+  <text x="797" y="509.8" class="ph" font-weight="600" fill="#3fb950">a spec</text>
+
+</svg>

package/dist/task/auto-orchestrator.js

@@ -42,7 +42,19 @@ import { LAUNCH_EXTRACT_PROMPT, enumerateScriptCandidates, parseScriptLines, kee
 const MAX_CLARIFY_QUESTIONS = 8;
 // Bounded coverage-triage rounds after decompose: judge → reprompt-with-missing
 // → judge again, at most. Two rounds so one flaky retry doesn't end the gate,
-// while a judge that keeps flagging can't loop the plan phase forever.
+// while a judge that keeps flagging can't loop the plan phase forever. Each round
+// spawns three model children (decompose + coverage-map + coverage-verdict), so
+// the ceiling is also a latency/spawn budget, not just a correctness bound.
+//
+// Why 2 is safe to sit this low: when this number was picked (2026-07-03) adoption
+// was LAST-WINS, so more rounds meant more chances to overwrite a good plan with a
+// worse regeneration — the cap was protective. Adoption is now MONOTONE
+// (coverage-loop.ts, 2026-07-15): a retry that drops owned coverage is rejected,
+// never adopted, so extra rounds can only hold or grow coverage. The one gap that
+// remained is that an adoption landing ON the last round can expose a NEW area with
+// no round left to chase it — handled surgically by a single bonus round granted
+// only in that exact case (see the loop), rather than by raising this ceiling for
+// every run.
 const MAX_COVERAGE_ROUNDS = 2;
 /** Reprompt prefix when the coverage triage found feature areas no task covers. */
 function coverageRepromptHint(missing) {
@@ -106,6 +118,17 @@ function logPlanDebug(cwd, msg) {
         .then(() => fsp.appendFile(path.join(dir, 'plan-debug.log'), line))
         .catch(() => { });
 }
+/** Normalise a missing-area string for cross-round identity — lowercased alnum
+ *  words, punctuation and quote-wrapping collapsed. Used only to tell whether an
+ *  adopted plan introduced a NEW gap versus re-surfacing the same one (#2 bonus
+ *  round); intentionally coarse, so trivial rewording of the same area does not
+ *  read as new and buy an extra round. */
+function normMissingArea(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+}
 /**
  * Clarify's answer-side TRIAGE — the second stage /task-auto's clarify gate was
  * missing that /task's grill already had. /task-auto's clarify was single-stage:
@@ -569,7 +592,8 @@ export async function planAuto(ctx, cwd, feature, deps) {
         return {
             plan: { titles, covered, missing },
             accounting: acc,
-            suspect: isSuspectPlan(titles, featureForModel)
+            suspect: isSuspectPlan(titles, featureForModel),
+            judgeMissing: verdictMissing
         };
     };
     const hasRequirements = reqEntries.length > 0;
@@ -579,6 +603,17 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // The carried accounting (cross-cutting + unowned) for the plan that ships.
     let accounting = best.accounting;
     let round = 0;
+    // #2: the round cap can be lifted ONCE. An adoption is a fresh whole-plan roll,
+    // so the plan that gets adopted can expose an uncovered area the pre-adoption
+    // plan never had — and if that adoption lands on the last allowed round, the
+    // loop breaks before the new gap ever gets a reprompt (mx5 2026-07-16: the
+    // 55-title plan was adopted on the final round AND was the first to reveal §10's
+    // test-infra gap; the cap fired the same instant, so it was never chased). Grant
+    // exactly one bonus round when — and only when — an adoption introduces a NEW
+    // missing area at the cap. Bounded to one so a judge that flags forever still
+    // cannot loop the plan phase; a persistent (non-new) gap never re-triggers it.
+    let roundCap = MAX_COVERAGE_ROUNDS;
+    let bonusRoundUsed = false;
     for (;;) {
         if (best.plan.titles.length === 0)
             break;
@@ -596,7 +631,7 @@ export async function planAuto(ctx, cwd, feature, deps) {
             }
             break;
         }
-        if (round >= MAX_COVERAGE_ROUNDS)
+        if (round >= roundCap)
             break;
         round++;
         logPlanDebug(cwd, `decompose-coverage round ${round}: INCOMPLETE — missing: `
@@ -606,9 +641,29 @@ export async function planAuto(ctx, cwd, feature, deps) {
         const cand = await scorePlan(retryTitles);
         const decision = decideAdoption(best.plan, cand.plan, hasRequirements);
         if (decision.adopt) {
+            // Snapshot the pre-adoption plan to decide whether this adoption earns a
+            // bonus round. Two guards keep the bonus off generic judge churn: it must
+            // be a real coverage GAIN (grounded covered-set strictly grew — a flaky
+            // judge that just relabels the same-shaped plan's gap does not qualify),
+            // and it must expose a NEW area (a gap already present is one we have or
+            // will reprompt against anyway). Requirements-path only: without grounded
+            // requirements "missing" is pure holistic-judge free-text that can change
+            // every round, so there is no trustworthy "grew"/"new" signal to gate on.
+            const priorCovered = best.plan.covered.size;
+            const priorMissing = new Set(best.plan.missing.map(normMissingArea));
             best = cand;
             accounting = cand.accounting ?? accounting;
             logPlanDebug(cwd, `decompose retry ADOPTED — ${decision.reason}`);
+            if (!bonusRoundUsed
+                && round >= roundCap
+                && hasRequirements
+                && cand.plan.covered.size > priorCovered
+                && cand.plan.missing.some(m => !priorMissing.has(normMissingArea(m)))) {
+                bonusRoundUsed = true;
+                roundCap++;
+                logPlanDebug(cwd, 'decompose-coverage: bonus round granted — adoption grew coverage and '
+                    + 'exposed a new uncovered area at the cap');
+            }
         }
         else {
             // Rejected: keep the better current plan. The loop re-checks it at the
@@ -631,7 +686,10 @@ export async function planAuto(ctx, cwd, feature, deps) {
     if (unresolvedMissing !== null) {
         logPlanDebug(cwd, `decompose-coverage exhausted ${round} round(s) still INCOMPLETE — missing: `
             + unresolvedMissing.join('; ').slice(0, 300));
-        ctx.ui.notify(`/task-auto: plan may be missing coverage — ${unresolvedMissing.join('; ').slice(0, 200)} — review the plan before running.`, 'warning');
+        ctx.ui.notify(`/task-auto: no task fully owns — ${unresolvedMissing.join('; ').slice(0, 200)}. `
+            + 'Carried into every task via .pi-tasks/requirements.md, but not as a dedicated '
+            + 'task. To give it one, stop now and add it to the plan in .pi-tasks/; otherwise '
+            + 'it proceeds.', 'warning');
     }
     // Carry what no single task owns (goal A(b)/(c)): cross-cutting requirements
     // become `.pi-tasks/requirements.md`, injected VERBATIM into every task's
@@ -639,15 +697,25 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // is authoritative" pointer recovered it in 1 of ~6 tasks; content travels,
     // pointers don't). Requirements still unmapped after the rounds are carried
     // too — marked — and recorded user-visibly in the plan file, never dropped.
-    if (accounting !== null) {
-        await appendCarriedRequirements(cwd, accounting.crossCutting, accounting.unmapped);
-        if (accounting.crossCutting.length > 0 || accounting.unmapped.length > 0) {
-            ctx.ui.notify(`/task-auto: carrying ${accounting.crossCutting.length} cross-cutting`
-                + (accounting.unmapped.length > 0 ?
-                    ` and ${accounting.unmapped.length} unowned`
-                    : '')
-                + ' requirement(s) into every task — see .pi-tasks/requirements.md.', 'info');
-        }
+    //
+    // #1: the holistic-judge missing areas are carried as a THIRD channel. They are
+    // areas requirement-extraction never captured as a tracked entry (so the
+    // grounded accounting is structurally blind to them), seen only by the judge —
+    // exactly the class that, having no carrier, was warned-about then dropped (mx5
+    // 2026-07-16, §10 test-infra). Carried independent of `accounting` so a mapping
+    // fault (accounting === null) can't strand them either.
+    const carriedCrossCutting = accounting?.crossCutting ?? [];
+    const carriedUnmapped = accounting?.unmapped ?? [];
+    const carriedJudge = best.judgeMissing;
+    if (carriedCrossCutting.length > 0 || carriedUnmapped.length > 0 || carriedJudge.length > 0) {
+        await appendCarriedRequirements(cwd, carriedCrossCutting, carriedUnmapped, carriedJudge);
+        const parts = [
+            carriedCrossCutting.length > 0 ? `${carriedCrossCutting.length} cross-cutting` : '',
+            carriedUnmapped.length > 0 ? `${carriedUnmapped.length} unowned` : '',
+            carriedJudge.length > 0 ? `${carriedJudge.length} judge-flagged` : ''
+        ].filter(p => p.length > 0);
+        ctx.ui.notify(`/task-auto: carrying ${parts.join(', ')} requirement(s) into every task`
+            + ' — see .pi-tasks/requirements.md.', 'info');
     }
     // Cross-slice contract registry (mx5 run 8, F3): now that the plan is settled,
     // extract the interface facts MORE THAN ONE slice must agree on — endpoint paths,

package/dist/task/coverage-loop.js

@@ -32,17 +32,106 @@
 // domain-agnostic (no mx5/web vocabulary).
 const COVERAGE_STOPWORDS = new Set([
     // function words
-    'the', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'on', 'for', 'with', 'by', 'at', 'as', 'is',
-    'are', 'be', 'it', 'its', 'that', 'this', 'from', 'into', 'out', 'up', 'per', 'via', 'not', 'no',
-    'but', 'if', 'then', 'than', 'so', 'such', 'each', 'any', 'all', 'every', 'when', 'where', 'must',
-    'should', 'shall', 'may', 'can', 'will', 'end', 'new',
+    'the',
+    'a',
+    'an',
+    'and',
+    'or',
+    'of',
+    'to',
+    'in',
+    'on',
+    'for',
+    'with',
+    'by',
+    'at',
+    'as',
+    'is',
+    'are',
+    'be',
+    'it',
+    'its',
+    'that',
+    'this',
+    'from',
+    'into',
+    'out',
+    'up',
+    'per',
+    'via',
+    'not',
+    'no',
+    'but',
+    'if',
+    'then',
+    'than',
+    'so',
+    'such',
+    'each',
+    'any',
+    'all',
+    'every',
+    'when',
+    'where',
+    'must',
+    'should',
+    'shall',
+    'may',
+    'can',
+    'will',
+    'end',
+    'new',
     // generic task verbs
-    'add', 'implement', 'create', 'build', 'scaffold', 'setup', 'set', 'support', 'handle', 'apply',
-    'use', 'used', 'using', 'make', 'makes', 'made', 'enable', 'provide', 'ensure', 'allow', 'run',
-    'runs', 'get', 'gets', 'define', 'configure', 'init', 'update', 'manage',
+    'add',
+    'implement',
+    'create',
+    'build',
+    'scaffold',
+    'setup',
+    'set',
+    'support',
+    'handle',
+    'apply',
+    'use',
+    'used',
+    'using',
+    'make',
+    'makes',
+    'made',
+    'enable',
+    'provide',
+    'ensure',
+    'allow',
+    'run',
+    'runs',
+    'get',
+    'gets',
+    'define',
+    'configure',
+    'init',
+    'update',
+    'manage',
     // generic project nouns
-    'cli', 'tool', 'app', 'application', 'project', 'feature', 'task', 'tasks', 'user', 'users',
-    'mode', 'flag', 'flags', 'option', 'options', 'system', 'code', 'thing', 'things', 'work'
+    'cli',
+    'tool',
+    'app',
+    'application',
+    'project',
+    'feature',
+    'task',
+    'tasks',
+    'user',
+    'users',
+    'mode',
+    'flag',
+    'flags',
+    'option',
+    'options',
+    'system',
+    'code',
+    'thing',
+    'things',
+    'work'
 ]);
 /** Distinctive content tokens of a phrase: lowercased alphanumeric words ≥3 chars,
  *  minus the ubiquitous stopwords. `--json` → `json`, `dead-letter` → `dead`,`letter`.

package/dist/task/gate-deps.js

@@ -492,17 +492,33 @@ export function buildGateDeps(params) {
                 contracts: () => readContracts(cwd2)
             });
         },
-        lintFix: (fixCtx, cwd2, taskTitle, failReason) => runBoundedLintFix({
-            cwd: cwd2,
-            signal,
-            failReason,
-            runChild: makeGateChild(fixCtx, cwd2, taskTitle, 'lint-fix', 'verify-debug.log'),
-            repoHealth: () => Promise.resolve(runRepoHealthCheck(cwd2)),
-            git: async (args) => {
-                const r = await git(cwd2, args, signal);
-                return { exitCode: r.exitCode, stdout: r.stdout };
+        lintFix: async (fixCtx, cwd2, taskTitle, taskId, failReason) => {
+            // Same frozen extraction the enforce guard and the verify rule-4b
+            // probe consume (mx5 run 12: the lint-fix child edited spec-frozen
+            // tsconfig.json because ESLint's own error text instructed it, then
+            // verify failed the TASK for that edit — the child must know the
+            // spec's do-not-touch list AND be mechanically denied it).
+            let frozenPaths = [];
+            try {
+                const { body } = await readTaskFile(cwd2, taskId);
+                frozenPaths = frozenPathsFromSpec(extractSpecForVerification(body));
             }
-        }),
+            catch {
+                // spec unreadable → no frozen paths; the guard degrades to a no-op
+            }
+            return runBoundedLintFix({
+                cwd: cwd2,
+                signal,
+                failReason,
+                runChild: makeGateChild(fixCtx, cwd2, taskTitle, 'lint-fix', 'verify-debug.log'),
+                repoHealth: () => Promise.resolve(runRepoHealthCheck(cwd2)),
+                git: async (args) => {
+                    const r = await git(cwd2, args, signal);
+                    return { exitCode: r.exitCode, stdout: r.stdout };
+                },
+                frozenPaths
+            });
+        },
         // Deterministic static check + tree helpers for the enforce pre-commit gate.
         repoHealth: cwd2 => Promise.resolve(runRepoHealthCheck(cwd2)),
         dirty: async (cwd2) => {

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

@@ -1,33 +1,3 @@
-/**
- * lint-fix — the bounded, graduated resolution for a repo-health verify FAIL.
- *
- * The failure this closes (mx5 run 3, TASK_0017): AUTOFIX's only hammer is a FULL
- * implementation re-run. For a repo-health FAIL of 10 trivial lint findings the live
- * run burned two 36–56-minute impl turns, each REGENERATING a fresh 900-line rewrite
- * that failed lint differently — the loop cannot converge because the tool is bigger
- * than the defect. Validated live on the real TASK_0017 tree: a bounded fix child
- * (read,edit,bash) reached lint-clean in 64s and 106s, 2/2.
- *
- * The same validation caught the design's failure mode: BOTH runs cheated, running
- * `git checkout -- src/test/request.ts` — REVERTING the task's uncommitted work to
- * make the findings vanish. So this pass ships with a deterministic REVERT-GUARD,
- * outcome-based (command filtering can't catch every path to the same effect):
- *
- *   - Before the child runs: snapshot the full working state (`git add -A` +
- *     `git write-tree`, then unstage) and record which files differ from HEAD.
- *   - After: any pre-existing work file now byte-identical to HEAD means the child
- *     discarded work instead of fixing it → restore the snapshot, report not-applied.
- *   - Converge check: the injected repoHealth must pass; otherwise not-applied.
- *
- * A file whose ENTIRE pre-fix diff was the lint finding (fixing it legitimately
- * restores HEAD) trips the guard conservatively — the fix is discarded and the
- * ordinary AUTOFIX picker takes over. Safe direction: the guard may only cost time,
- * never work.
- *
- * Not-applied is never terminal: the caller falls through to the existing
- * recommend → AUTOFIX/ACCEPT/dismiss picker, so this pass can only make the loop
- * faster, never change what it can decide.
- */
 export interface LintFixResult {
     /** true → findings fixed, repo health passes, work preserved. */
     ok: boolean;
@@ -51,6 +21,13 @@ export interface LintFixDeps {
         exitCode: number;
         stdout: string;
     }>;
+    /**
+     * Paths the task's spec forbids modifying (frozenPathsFromSpec over the same
+     * composed spec verify judges). Injected into the child's prompt AND enforced
+     * deterministically post-child: a frozen path the child changed is reverted
+     * and the fix reported not-applied. Absent/empty → no-op, prior behavior.
+     */
+    frozenPaths?: string[];
 }
 /** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
 export declare const LINT_FIX_TOOLS = "read,edit,bash";
@@ -60,14 +37,15 @@ export declare const LINT_FIX_TOOLS = "read,edit,bash";
  * an explicit ban on discarding work (both validation runs reached green via
  * `git checkout` of the work file until the guard existed).
  */
-export declare function buildLintFixPrompt(failReason: string): string;
+export declare function buildLintFixPrompt(failReason: string, frozenPaths?: string[]): string;
 /**
  * Pure guard core: which pre-existing work files did the fix pass revert to HEAD?
  * `preDirty` = files differing from HEAD before the fix; `stillDirty` = after.
  */
 export declare function revertGuardViolations(preDirty: string[], stillDirty: Set<string>): string[];
 /**
- * Run the bounded fix: snapshot → child → revert-guard → converge check. Never
- * throws for an outcome; only a child-level user cancel propagates from runChild.
+ * Run the bounded fix: snapshot → child → revert-guard → frozen-path guard →
+ * converge check. Never throws for an outcome; only a child-level user cancel
+ * propagates from runChild.
  */
 export declare function runBoundedLintFix(deps: LintFixDeps): Promise<LintFixResult>;

package/dist/task/lint-fix.js

@@ -27,7 +27,24 @@
  * Not-applied is never terminal: the caller falls through to the existing
  * recommend → AUTOFIX/ACCEPT/dismiss picker, so this pass can only make the loop
  * faster, never change what it can decide.
+ *
+ * FROZEN-PATH GUARD (mx5 run 12, TASK_0021/0022): the checker's own error text
+ * can INSTRUCT an edit to a spec-frozen file (typed ESLint: "playwright/index.ts
+ * was not found by the project … Consider either including it in the
+ * tsconfig.json") and this child complies — while the task's spec froze
+ * `tsconfig.json` and verify's rule-4b prohibition probe then fails the TASK for
+ * the gate child's edit. Two gates, contradictory rules, same file; the loop
+ * never converges (live: TASK_0021 burned all three unattended AUTOFIX rounds).
+ * Prompt framing alone is A/B-proven ~0–1/5 on the weak model (see
+ * frozen-path-guard.ts), so the deny is mechanical: the spec's frozen paths are
+ * threaded in via `frozenPaths`, injected into the prompt as a do-not-touch list
+ * (belt), and any frozen path the child still changed is deterministically
+ * reverted post-child and the fix reported not-applied (suspenders). Only paths
+ * that were CLEAN before the child ran are reverted — a frozen path already
+ * dirty with (possibly task) work is left alone, in the guard's safe direction:
+ * cost time, never work.
  */
+import { parseChangedFrozenFiles, revertFrozenPaths } from './frozen-path-guard.js';
 /** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
 export const LINT_FIX_TOOLS = 'read,edit,bash';
 /**
@@ -36,7 +53,20 @@ export const LINT_FIX_TOOLS = 'read,edit,bash';
  * an explicit ban on discarding work (both validation runs reached green via
  * `git checkout` of the work file until the guard existed).
  */
-export function buildLintFixPrompt(failReason) {
+export function buildLintFixPrompt(failReason, frozenPaths = []) {
+    const frozenBlock = frozenPaths.length === 0 ?
+        []
+        : [
+            '3b. HARD CONSTRAINT — SPEC-FROZEN PATHS. The task spec forbids modifying:',
+            ...frozenPaths.map(p => `   - ${p}`),
+            '   You must NOT edit, create, or delete anything at or under these paths,',
+            "   EVEN IF the checker's own error message suggests exactly that fix",
+            '   (e.g. "consider including it in the tsconfig.json"). Any change you make',
+            '   to a frozen path is detected and reverted, and the whole fix is rejected.',
+            '   If the check cannot pass without touching a frozen path, STOP and report',
+            '   LINT-FIX: BLOCKED with the reason.',
+            ''
+        ];
     return [
         'You are a bounded static-analysis fix pass. A verification gate just failed',
         `with: ${failReason}`,
@@ -59,6 +89,7 @@ export function buildLintFixPrompt(failReason) {
         '   Reverting the work would make the findings vanish — that is destroying the',
         '   task, not fixing it, and it is detected and rejected.',
         '',
+        ...frozenBlock,
         '4. Re-run the check after editing and confirm it exits 0.',
         '',
         'End with exactly one line:',
@@ -91,8 +122,21 @@ async function dirtyFiles(deps) {
         .filter(l => l.length > 0);
 }
 /**
- * Run the bounded fix: snapshot → child → revert-guard → converge check. Never
- * throws for an outcome; only a child-level user cancel propagates from runChild.
+ * Which spec-frozen paths currently show a change in `git status`? Null when git
+ * itself failed — inconclusive, not evidence (same discipline as dirtyFiles).
+ */
+async function frozenDirtySet(deps, frozen) {
+    if (frozen.length === 0)
+        return new Set();
+    const r = await deps.git(['status', '--porcelain', '--', ...frozen]);
+    if (r.exitCode !== 0)
+        return null;
+    return new Set(parseChangedFrozenFiles(r.stdout));
+}
+/**
+ * Run the bounded fix: snapshot → child → revert-guard → frozen-path guard →
+ * converge check. Never throws for an outcome; only a child-level user cancel
+ * propagates from runChild.
  */
 export async function runBoundedLintFix(deps) {
     // Snapshot the full working state as a tree object (includes untracked files),
@@ -122,8 +166,14 @@ export async function runBoundedLintFix(deps) {
             snapshot = wt.stdout.trim();
         await deps.git(['reset']);
     }
+    // FROZEN-PATH baseline: frozen paths already dirty BEFORE the child ran carry
+    // (possibly the task's own) work — the guard must never revert those, only
+    // changes the CHILD introduces on top of a clean frozen path. A git failure
+    // here disables the guard for this run (inconclusive ≠ license to revert).
+    const frozen = deps.frozenPaths ?? [];
+    const preFrozenDirty = await frozenDirtySet(deps, frozen);
     try {
-        await deps.runChild(LINT_FIX_TOOLS, buildLintFixPrompt(deps.failReason), deps.signal);
+        await deps.runChild(LINT_FIX_TOOLS, buildLintFixPrompt(deps.failReason, frozen), deps.signal);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -174,6 +224,31 @@ export async function runBoundedLintFix(deps) {
                 + `${violations.length > 3 ? ', …' : ''}) — fix ${snapshot ? 'rolled back' : 'REJECTED but no snapshot to restore'}`
         };
     }
+    // FROZEN-PATH GUARD: a frozen path that was clean pre-child and is changed
+    // now is the child's edit — the exact write verify's rule-4b prohibition
+    // probe is guaranteed to fail the TASK for (mx5 run 12: ESLint's own error
+    // text instructed the tsconfig.json edit and the child complied, 5/5 in the
+    // live A/B). Revert JUST those paths (they were clean, so HEAD == pre-state:
+    // no work can be lost) and report not-applied so the caller falls through to
+    // the ordinary recommend → AUTOFIX/ACCEPT picker. Inconclusive git (either
+    // side) → guard steps aside; the verify probe still catches what survives.
+    if (preFrozenDirty !== null) {
+        const postFrozenDirty = await frozenDirtySet(deps, frozen);
+        if (postFrozenDirty !== null) {
+            const frozenViolations = [...postFrozenDirty].filter(f => !preFrozenDirty.has(f));
+            if (frozenViolations.length > 0) {
+                const reverted = await revertFrozenPaths(frozenViolations, deps.git);
+                return {
+                    ok: false,
+                    reason: `frozen-path: fix child modified spec-frozen path(s) `
+                        + `(${frozenViolations.slice(0, 3).join(', ')}`
+                        + `${frozenViolations.length > 3 ? ', …' : ''}) — `
+                        + `${reverted.length > 0 ? 'reverted' : 'REJECTED (revert found nothing to undo)'}; `
+                        + `the static findings need a fix that respects the spec's constraints`
+                };
+            }
+        }
+    }
     const health = await deps.repoHealth();
     if (!health.ok) {
         return { ok: false, reason: `did not converge: ${health.reason}` };

package/dist/task/requirements.d.ts

@@ -76,11 +76,20 @@ export declare function accountCoverage(requirements: RequirementEntry[], mappin
 /** The stored carried-requirements text ('' when none recorded). */
 export declare function readRequirements(cwd: string): Promise<string>;
 /**
- * Append carried requirements (cross-cutting, plus any left unmapped after the
- * retry rounds — better carried into every task than silently lost), deduped
- * against what is stored. Host-side only; children never write it. Best-effort.
+ * Append carried requirements, deduped against what is stored. Three channels,
+ * each better carried into every task than silently lost — host-side only,
+ * children never write it, best-effort:
+ *   • `crossCutting` — obligations no single task owns (policy/global rules).
+ *   • `unresolved`   — grounded requirements still unmapped after the retry rounds.
+ *   • `judgeFlagged` — free-text areas the holistic coverage judge flagged as
+ *     uncovered that requirement-extraction never captured as a tracked entry, so
+ *     the grounded channels above are structurally blind to them (mx5 2026-07-16:
+ *     §10's test-infra setup was seen ONLY by the judge and, having no carrier,
+ *     was warned-about then dropped). These are plain strings, not quotes of the
+ *     source; marked distinctly so a task can tell an inferred area from a verbatim
+ *     obligation.
  */
-export declare function appendCarriedRequirements(cwd: string, crossCutting: RequirementEntry[], unresolved?: RequirementEntry[]): Promise<void>;
+export declare function appendCarriedRequirements(cwd: string, crossCutting: RequirementEntry[], unresolved?: RequirementEntry[], judgeFlagged?: string[]): Promise<void>;
 /**
  * The read-only block refine/compose receive when carried requirements exist.
  * Verbatim content travels with every task (the directive pattern that works),

package/dist/task/requirements.js

@@ -308,12 +308,21 @@ function formatEntry(e, marker) {
     return `"${e.quote}"${anchor}${marker ? ` [${marker}]` : ''}`;
 }
 /**
- * Append carried requirements (cross-cutting, plus any left unmapped after the
- * retry rounds — better carried into every task than silently lost), deduped
- * against what is stored. Host-side only; children never write it. Best-effort.
+ * Append carried requirements, deduped against what is stored. Three channels,
+ * each better carried into every task than silently lost — host-side only,
+ * children never write it, best-effort:
+ *   • `crossCutting` — obligations no single task owns (policy/global rules).
+ *   • `unresolved`   — grounded requirements still unmapped after the retry rounds.
+ *   • `judgeFlagged` — free-text areas the holistic coverage judge flagged as
+ *     uncovered that requirement-extraction never captured as a tracked entry, so
+ *     the grounded channels above are structurally blind to them (mx5 2026-07-16:
+ *     §10's test-infra setup was seen ONLY by the judge and, having no carrier,
+ *     was warned-about then dropped). These are plain strings, not quotes of the
+ *     source; marked distinctly so a task can tell an inferred area from a verbatim
+ *     obligation.
  */
-export async function appendCarriedRequirements(cwd, crossCutting, unresolved = []) {
-    if (crossCutting.length === 0 && unresolved.length === 0)
+export async function appendCarriedRequirements(cwd, crossCutting, unresolved = [], judgeFlagged = []) {
+    if (crossCutting.length === 0 && unresolved.length === 0 && judgeFlagged.length === 0)
         return;
     try {
         const existing = (await readRequirements(cwd)).split('\n').filter(l => l.trim().length > 0);
@@ -324,7 +333,11 @@ export async function appendCarriedRequirements(cwd, crossCutting, unresolved =
         const merged = [...existing];
         for (const [entries, marker] of [
             [crossCutting, undefined],
-            [unresolved, 'no task owns this — surfaced at plan time']
+            [unresolved, 'no task owns this — surfaced at plan time'],
+            [
+                judgeFlagged.map(q => ({ quote: q, anchor: '' })),
+                'judge-flagged uncovered area, no task owns this — surfaced at plan time'
+            ]
         ]) {
             for (const e of entries) {
                 const key = normalise(e.quote);

package/dist/task/task-gates.d.ts

@@ -87,7 +87,7 @@ export interface GateDeps {
      * at most once per gate sequence; not-applied falls through to the picker.
      * Absent → the loop goes straight to recommend/picker as before.
      */
-    lintFix?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, failReason: string) => Promise<{
+    lintFix?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, taskId: string, failReason: string) => Promise<{
         ok: boolean;
         reason?: string;
     }>;

package/dist/task/task-gates.js

@@ -98,7 +98,7 @@ export async function runGatesForTask(ctxIn, deps, p) {
             if (!lintFixAttempted && deps.lintFix && failReason.startsWith('repo health:')) {
                 lintFixAttempted = true;
                 active.ui.notify(`${p.tag}: static findings on "${p.title}" — attempting bounded lint fix…`, 'info');
-                const fix = await deps.lintFix(active, p.cwd, p.title, failReason);
+                const fix = await deps.lintFix(active, p.cwd, p.title, p.taskId, failReason);
                 await rec(`lint-fix: ${fix.ok ?
                     `applied${fix.reason ? ` (${fix.reason})` : ''} — re-verifying`
                     : `not applied (${fix.reason ?? 'failed'})`}`);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.19",
+    "version": "0.18.21",
     "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",
@@ -85,6 +85,6 @@
         "extensions": [
             "dist/index.js"
         ],
-        "image": "https://raw.githubusercontent.com/mjasnikovs/pi-task/main/assets/pipeline.png"
+        "image": "https://raw.githubusercontent.com/mjasnikovs/pi-task/main/assets/hero.png"
     }
 }