@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/README.md

@@ -233,7 +233,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
 | **profile** | default | How much the helper sessions think, in one word, for every step at once. Local models differ sharply here: some break without reasoning, some waste minutes with it, and some cannot do it at all. **default** uses the per-step table pi-task has measured, **on** and **off** force one answer everywhere and ignore that table, and **custom** is whatever the step rows say — changing any of them switches this to custom. A step on **inherit** passes no flag at all, so it uses whatever thinking level pi itself is set to, which is what every step did before this setting existed. |
 | **steps: …** | models `inherit`; levels per the shipped table | One row per group of steps, carrying BOTH dials: the model those children run on and the level they think at, shown as `level · model`. Enter walks a two-step picker — model first, then level — and **the level step offers only what that model declares, opening on the one that will actually run**. That is the whole point of the merge: pi silently CLAMPS a level a model cannot do (a level you set can be erased, and an `off` can be clamped back up to `medium`), so instead of discovering that later you watch the cursor land on the level you are really getting. Models are offered from `pi.modelRegistry.getAvailable()` and stored as the canonical `provider/id` that pi's own `--model` takes. **inherit** on the model half emits no flag, so an all-inherit table is byte-identical to a build without this feature; that is the shipped default, because which models exist is a property of your machine and nothing here can be measured for you. A stored model this machine cannot resolve is never erased (you may have set it on another machine): the flag is dropped, the step runs on pi's default, and a startup hint names the step. Two need care — a provider registered by a host **extension** needs that extension enabled under **ext: …** or those children exit 1; and **implementation** is not free, because it is *your* session moved for the turn and moved back, and a model switch re-bills the whole prompt as a cache miss, twice per task. |
-| **debug logs** | events | How much of a run is written to `.pi-tasks/*-debug.log`. **`events`** keeps decisions and guard actions — which phase ran, why a worker was retried, what the git-state guard restored, what a write-capable child changed on disk, why a gate returned FAIL — a few lines per task. **`full`** adds every line the child model emitted and every tool result; that's ~85% of the bytes (a real 247 KB `verify-debug.log` is 1315 lines, 521 of them tool dumps) and is what you want while actively debugging. **`off`** writes nothing. Nothing in pi-task ever reads these files back, so the setting cannot change how a run behaves — only whether you can explain it afterwards, and a log not written can't be recovered later. |
+| **debug logs** | events | How much of a run is written to its log directory, `${XDG_STATE_HOME:-~/.local/state}/pi-task/<repo-hash>/<run-id>/*-debug.log` — outside the repository, so the trail is never committed, never rewound by a gate, and never re-read when one is. **`events`** keeps decisions and guard actions — which phase ran, why a worker was retried, what the git-state guard restored, what a write-capable child changed on disk, why a gate returned FAIL — a few lines per task. **`full`** adds every line the child model emitted and every tool result; that's ~85% of the bytes (a real 247 KB `verify-debug.log` is 1315 lines, 521 of them tool dumps) and is what you want while actively debugging. **`off`** writes nothing. Control characters are stripped and long lines are capped, so the files stay greppable. Nothing in pi-task ever reads these files back, so the setting cannot change how a run behaves — only whether you can explain it afterwards, and a log not written can't be recovered later. A completed `/task-auto` run keeps the 20 most recent runs' logs for the repository and deletes the rest. |
 | **watch: …** | all on | One toggle per tool in the live session, deciding whether **command timeout** applies to it. The list is discovered from `pi.getAllTools()` when the menu opens — built-ins first, then each extension's tools with the owning entry-point path in the description — so nothing is typed by hand and an uninstalled tool just stops being listed. Turn one **off** only for a tool that already owns a longer bounded, cancellable contract of its own (the guard exists because pi's `bash` has an optional timeout with *no* default — that reasoning doesn't transfer to a tool that has one). Two things to know before you do: a genuine hang in an unwatched tool is caught by nothing, since **stuck reply retry** is paused for the whole time any tool runs; and an unwatched tool is still killed as collateral if a *watched* sibling in the same turn overruns, because pi runs sibling tool calls concurrently and the abort ends the whole turn. Stored as exemptions, so the default and every tool pi-task has never seen stay guarded. |
 | **ext: …** | all off | One toggle per installed host `pi` extension, loading it into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
 
@@ -246,6 +246,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | `CARGO_HOME` | `pi-worker-docs` | Where crate source checkouts are read from (defaults to `~/.cargo`). |
 | `CABAL_DIR` | `pi-worker-docs` | Where cabal's downloaded package tarballs are read from (also checks `~/.cabal/packages` and `${XDG_CACHE_HOME:-~/.cache}/cabal/packages`). |
 | `XDG_DATA_HOME` | remote push | Where the VAPID keypair is stored (defaults to `~/.local/share`). |
+| `XDG_STATE_HOME` | task trail | Where a run's `*-debug.log` files are kept, under `pi-task/<repo-hash>/<run-id>/` (defaults to `~/.local/state`). A relative value is ignored, per the XDG spec. |
 | `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
 | `PI_REMOTE_PUSH_DEBUG` | remote push | When set (e.g. `1`), logs push delivery and push-service HTTP status. Off by default. |
 | `PI_REMOTE_PUSH_LOG` | remote push | Path for the debug log (defaults to `/tmp/pi-task-push.log`). |
@@ -255,15 +256,17 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 
 Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. A run also keeps small
 line-oriented ledgers beside them — contracts, launch contract, environment
-notes, accepted debt, repair queue, requirements — plus `*-debug.log` when
-**debug logs** is on. Add `.pi-tasks/` to your `.gitignore` if you don't want
+notes, accepted debt, repair queue, requirements. The `*-debug.log` trail is not
+among them: it lives outside the tree, under
+`${XDG_STATE_HOME:-~/.local/state}/pi-task/<repo-hash>/<run-id>/`.
+Add `.pi-tasks/` to your `.gitignore` if you don't want
 them checked in.
 
 ## Development
 
 ```sh
 bun install
-bun run test       # 4631 tests pass across 247 files (1 skip)
+bun run test       # 4770 tests pass across 252 files (3 skips)
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/config/config.d.ts

@@ -7,13 +7,27 @@ export interface PiTaskConfig {
     enforceGuidelines: boolean;
     verifyWork: boolean;
     /**
-     * Run the four research workers concurrently instead of one at a time
-     * (task/phases.ts). DEFAULT OFF. Serial is also what lets a worker read the
-     * sections finished before it — APIS builds on the FILES map, and gets
-     * nothing under the parallel branch. Measure your own backend before
-     * turning this on.
+     * What shape the research phase runs its four workers in (task/phases.ts).
+     *
+     * `graph` (DEFAULT) runs each worker as soon as the sections it declares it
+     * comes `after` are finished: FILES first, then APIS, with CONTEXT and TOOLING
+     * alongside. The FILES→APIS handoff survives, which the old all-at-once
+     * parallel mode lost.
+     *
+     * `serial` runs them one at a time, for a single local GPU where concurrent
+     * streams share one device and slow each other down.
+     */
+    researchConcurrency: ResearchConcurrency;
+    /**
+     * Extra paths the project tour must never pre-read, as `.gitignore`-style
+     * patterns (`docs/generated/**`, `fixtures/`).
+     *
+     * The shipped exclusions — vendored dependencies, build output, the agent's
+     * own directories — are `VENDORED_DIRS` in task/orientation.ts, and the
+     * repo's `.gitignore` is read on top of them. This is the hand-edited third
+     * source, for a tracked directory that is bulk to this project alone.
      */
-    parallelResearchWorkers: boolean;
+    orientationExclude: string[];
     /**
      * Cache docs/search/fetch worker RESULTS for the duration of one /task-auto
      * run, so sibling tasks re-asking the same (package/url, query) reuse the
@@ -44,6 +58,15 @@ export interface PiTaskConfig {
      * /task-config, which enumerates the currently installed extensions.
      */
     extensionWhitelist: string[];
+    /**
+     * Extra suppression spellings the verify gate's widening probe counts, as
+     * regular-expression SOURCES (see task/suppression-probe.ts). The shipped
+     * registry covers the common checkers across ecosystems; this is for a
+     * project's own — a house `// SAFETY-OVERRIDE` marker, a generated-code
+     * pragma. An entry that does not compile is dropped, never fatal.
+     * DEFAULT empty: the shipped rows are the policy until a project says more.
+     */
+    suppressionPatterns: string[];
     /**
      * Wall-clock ceiling (ms) on a SINGLE tool execution before the command
      * watchdog steps in. pi's bash tool declares its `timeout` parameter as
@@ -117,14 +140,13 @@ export interface PiTaskConfig {
      */
     yoloMode: boolean;
     /**
-     * How much the run writes to its `.pi-tasks/*-debug.log` forensic trail
-     * (task/debug-log.ts). Nothing in `src/` reads these files back —
-     * `task-io.ts` only matches `TASK_NNNN.md`, and auto-commit's trail snapshot
-     * reads every `.pi-tasks/` file as bytes and writes them back unparsed — so
-     * this knob is behaviour-neutral by construction. It trades disk and repo
-     * noise against the ability to explain a run after it has finished. The
-     * TESTS do read the trail back, which is why the test preload pins the
-     * config path away from the developer's own file.
+     * How much the run writes to its `*-debug.log` forensic trail
+     * (task/debug-log.ts), kept in the run's state dir (task/state-dir.ts).
+     * Nothing in `src/` reads these files back, so this knob is
+     * behaviour-neutral by construction. It trades disk against the ability to
+     * explain a run after it has finished. The TESTS do read the trail back,
+     * which is why the test preload pins the config path — and the state home —
+     * away from the developer's own.
      *
      * `full` is every line the child model emitted plus every tool result;
      * `events` keeps only decisions and guard actions; `off` writes nothing.
@@ -171,8 +193,26 @@ export interface PiTaskConfig {
      */
     groupModels: Record<ChildGroup, string>;
 }
-/** How verbose the `.pi-tasks/*-debug.log` trail is. See {@link PiTaskConfig.debugLogs}. */
+/** How verbose the `*-debug.log` trail is. See {@link PiTaskConfig.debugLogs}. */
 export type DebugLogLevel = 'off' | 'events' | 'full';
+/** How the research workers are scheduled. See {@link PiTaskConfig.researchConcurrency}. */
+export type ResearchConcurrency = 'graph' | 'serial';
+/** The concurrency choices offered by /task-config, in cycle order. */
+export declare const RESEARCH_CONCURRENCY_OPTIONS: ReadonlyArray<{
+    label: string;
+    value: ResearchConcurrency;
+}>;
+/** Pin a hand-edited or stale value to one of the offered choices. */
+export declare function sanitizeResearchConcurrency(value: unknown): ResearchConcurrency;
+/**
+ * The boolean this setting shipped as, and how a stored one is read.
+ *
+ * `true` meant "all four at once", which is the graph without its one edge, so it
+ * maps to `graph`; `false` meant one at a time. Kept as a documented alias rather
+ * than dropped, because dropping it silently re-enables concurrency on the local
+ * GPU of every user who turned it off.
+ */
+export declare const DEPRECATED_PARALLEL_KEY = "parallelResearchWorkers";
 /**
  * The debug-log choices offered by /task-config, in cycle order (quietest →
  * loudest, so the cycle reads as a volume dial). Unlike the timeout options the
@@ -200,6 +240,8 @@ export declare const COMMAND_TIMEOUT_OPTIONS: ReadonlyArray<{
  * one of the offered choices so the watchdog never arms on a nonsense value.
  */
 export declare function sanitizeRequestTimeoutMs(value: unknown): number;
+/** Keep only non-empty string patterns from a hand-edited exclusion list. */
+export declare function sanitizeIgnorePatterns(value: unknown): string[];
 /** Keep only exact, unique Pi tool names from an advanced config override. */
 export declare function sanitizeCommandTimeoutExemptTools(value: unknown): string[];
 /**
@@ -222,10 +264,11 @@ export declare function sanitizeStreamInactivityMs(value: unknown): number;
  */
 export declare const DEFAULT_CONFIG: PiTaskConfig;
 /**
- * A hand-edited config can hold anything; keep only string entries so a stray
- * object/number can't reach the child argv as `-e [object Object]`.
+ * A hand-edited config can hold anything; keep only non-blank string entries so a
+ * stray object/number can't reach the child argv as `-e [object Object]`, or
+ * `new RegExp`.
  */
-export declare function sanitizeExtensionWhitelist(value: unknown): string[];
+export declare function sanitizeStringList(value: unknown): string[];
 /**
  * How each setting's STORED value becomes a safe in-memory value — one loader per
  * key, keyed on the config's own type.

package/dist/config/config.js

@@ -6,6 +6,27 @@ import { isSearchProvider } from '../workers/search-types.js';
 import { DEFAULT_REASONING_TABLE, sanitizeReasoningLevels, sanitizeReasoningMode } from './reasoning.js';
 import { DEFAULT_GROUP_MODELS, sanitizeGroupModels } from './group-models.js';
 import { DEFAULT_STREAM_INACTIVITY_MS } from '../shared/stream-watchdog.js';
+/** The concurrency choices offered by /task-config, in cycle order. */
+export const RESEARCH_CONCURRENCY_OPTIONS = [
+    { label: 'by dependency', value: 'graph' },
+    { label: 'one at a time', value: 'serial' }
+];
+/** Pin a hand-edited or stale value to one of the offered choices. */
+export function sanitizeResearchConcurrency(value) {
+    return RESEARCH_CONCURRENCY_OPTIONS.some(o => o.value === value) ?
+        value
+        : DEFAULT_RESEARCH_CONCURRENCY;
+}
+const DEFAULT_RESEARCH_CONCURRENCY = 'graph';
+/**
+ * The boolean this setting shipped as, and how a stored one is read.
+ *
+ * `true` meant "all four at once", which is the graph without its one edge, so it
+ * maps to `graph`; `false` meant one at a time. Kept as a documented alias rather
+ * than dropped, because dropping it silently re-enables concurrency on the local
+ * GPU of every user who turned it off.
+ */
+export const DEPRECATED_PARALLEL_KEY = 'parallelResearchWorkers';
 /**
  * The debug-log choices offered by /task-config, in cycle order (quietest →
  * loudest, so the cycle reads as a volume dial). Unlike the timeout options the
@@ -46,6 +67,15 @@ export function sanitizeRequestTimeoutMs(value) {
         value
         : DEFAULT_REQUEST_TIMEOUT_MS;
 }
+/** Keep only non-empty string patterns from a hand-edited exclusion list. */
+export function sanitizeIgnorePatterns(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((p) => typeof p === 'string')
+        .map(p => p.trim())
+        .filter(p => p.length > 0);
+}
 /** Keep only exact, unique Pi tool names from an advanced config override. */
 export function sanitizeCommandTimeoutExemptTools(value) {
     if (!Array.isArray(value))
@@ -94,10 +124,14 @@ export const DEFAULT_CONFIG = {
     orientation: true,
     enforceGuidelines: true,
     verifyWork: true,
-    parallelResearchWorkers: false,
+    // GRAPH: three of the four workers have no dependency on each other, and the
+    // one that does keeps its input. See ResearchConcurrency.
+    researchConcurrency: DEFAULT_RESEARCH_CONCURRENCY,
+    orientationExclude: [],
     researchCache: true,
     searchProvider: 'exa',
     extensionWhitelist: [],
+    suppressionPatterns: [],
     requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
     commandTimeoutExemptTools: [],
     streamInactivityMs: DEFAULT_STREAM_INACTIVITY_MS,
@@ -115,10 +149,11 @@ export const DEFAULT_CONFIG = {
     groupModels: { ...DEFAULT_GROUP_MODELS }
 };
 /**
- * A hand-edited config can hold anything; keep only string entries so a stray
- * object/number can't reach the child argv as `-e [object Object]`.
+ * A hand-edited config can hold anything; keep only non-blank string entries so a
+ * stray object/number can't reach the child argv as `-e [object Object]`, or
+ * `new RegExp`.
  */
-export function sanitizeExtensionWhitelist(value) {
+export function sanitizeStringList(value) {
     if (!Array.isArray(value))
         return [];
     return value.filter((p) => typeof p === 'string' && p.trim().length > 0);
@@ -146,13 +181,15 @@ export const CONFIG_LOADERS = {
     orientation: asBoolean('orientation'),
     enforceGuidelines: asBoolean('enforceGuidelines'),
     verifyWork: asBoolean('verifyWork'),
-    parallelResearchWorkers: asBoolean('parallelResearchWorkers'),
+    researchConcurrency: sanitizeResearchConcurrency,
+    orientationExclude: sanitizeIgnorePatterns,
     researchCache: asBoolean('researchCache'),
     yoloMode: asBoolean('yoloMode'),
     // A hand-edited or stale enum value must not leak an unknown provider into
     // the dispatch switch — fall back to the default.
     searchProvider: raw => (isSearchProvider(raw) ? raw : DEFAULT_CONFIG.searchProvider),
-    extensionWhitelist: sanitizeExtensionWhitelist,
+    extensionWhitelist: sanitizeStringList,
+    suppressionPatterns: sanitizeStringList,
     requestTimeoutMs: sanitizeRequestTimeoutMs,
     commandTimeoutExemptTools: sanitizeCommandTimeoutExemptTools,
     streamInactivityMs: sanitizeStreamInactivityMs,
@@ -184,6 +221,13 @@ export function loadConfig(raw) {
         ;
         out[key] = CONFIG_LOADERS[key](stored[key]);
     }
+    // The deprecated boolean answers only for a config saved before the setting
+    // became an enum — a file carrying both was written by this version, so the
+    // enum is the user's live choice and the boolean is the leftover.
+    if (stored.researchConcurrency === undefined
+        && typeof stored[DEPRECATED_PARALLEL_KEY] === 'boolean') {
+        out.researchConcurrency = stored[DEPRECATED_PARALLEL_KEY] ? 'graph' : 'serial';
+    }
     return out;
 }
 /**

package/dist/config/register.js

@@ -6,7 +6,7 @@ import { PairPicker } from './option-picker.js';
 import { registerBridgeCommand, isRemoteOrigin, publishNote } from '../remote/bridge.js';
 import { readPkgVersion } from '../shared/pkg-version.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
-import { COMMAND_TIMEOUT_OPTIONS, DEBUG_LOG_OPTIONS, getConfig, sanitizeDebugLogs, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
+import { COMMAND_TIMEOUT_OPTIONS, DEBUG_LOG_OPTIONS, getConfig, RESEARCH_CONCURRENCY_OPTIONS, sanitizeDebugLogs, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
 import { listGuardableTools } from './tool-list.js';
 import { CHILD_GROUPS, REASONING_MODES, sanitizeReasoningMode, STEP_GROUP_HELP, REASONING_SETTINGS, effectiveReasoning, resolveReasoning } from './reasoning.js';
@@ -174,9 +174,22 @@ export const ITEMS = [
     booleanItem('research', 'orientation', 'project tour', 'Show the research workers the shape of the project first — package manifest, '
         + 'types, schema — so they spend their steps on the question instead of on finding '
         + 'their way around'),
-    booleanItem('research', 'parallelResearchWorkers', 'parallel research', 'Run the 4 research workers at once instead of one after another. Only faster if '
-        + 'your model backend can answer several requests at the same time — on a single '
-        + 'local GPU it is measurably slower, so leave it off there'),
+    {
+        id: 'researchConcurrency',
+        section: 'research',
+        label: 'research workers',
+        description: 'How the 4 research workers are run. "by dependency" starts each one as soon as '
+            + 'the work it builds on is done, so three of them overlap; "one at a time" runs '
+            + 'them in order, which is faster on a single local GPU, where parallel requests '
+            + 'share one device',
+        values: RESEARCH_CONCURRENCY_OPTIONS.map(o => o.label),
+        format: cfg => RESEARCH_CONCURRENCY_OPTIONS.find(o => o.value === cfg.researchConcurrency).label,
+        apply: (cfg, chosen) => {
+            const opt = RESEARCH_CONCURRENCY_OPTIONS.find(o => o.label === chosen);
+            if (opt)
+                cfg.researchConcurrency = opt.value;
+        }
+    },
     booleanItem('research', 'researchCache', 'research cache', 'Remember docs and web pages for the length of one run, so later tasks reuse what '
         + 'the first one already fetched instead of downloading it again. Only external '
         + 'sources, only successful fetches, and it is dropped when the run ends'),
@@ -259,7 +272,7 @@ export const ITEMS = [
         id: 'debugLogs',
         section: 'logging',
         label: 'debug logs',
-        description: 'How much of a run gets written to .pi-tasks/*-debug.log. "events" keeps the '
+        description: 'How much of a run gets written to the run log dir. "events" keeps the '
             + 'decisions and the guard actions — what a checking step changed, why something '
             + 'failed — a few lines per task. "full" adds everything the model said and every '
             + 'command it ran, which is most of the size and only useful while you are digging '

package/dist/shared/content-tokens.d.ts

@@ -0,0 +1,16 @@
+/**
+ * content-tokens — the distinctive words of a phrase, and the one tokenizer that
+ * decides them.
+ *
+ * Two consumers ask the same question of a string and must get the same answer:
+ * the coverage guard, which grounds requirement/title ownership in shared
+ * distinctive nouns, and the research cache, whose key is the sorted token set of
+ * a query so two phrasings of one question share one digest. A second tokenizer
+ * would be a second answer.
+ */
+export declare const CONTENT_STOPWORDS: Set<string>;
+/** Distinctive content tokens of a phrase: lowercased alphanumeric words ≥3 chars,
+ *  minus the ubiquitous stopwords. `--json` → `json`, `dead-letter` → `dead`,`letter`.
+ *  A single trailing `s` is stripped (len ≥4) so `scan`/`scans`, `file`/`files`,
+ *  `serialize`/`serializes` match — plain plural/3rd-person, no full stemmer. */
+export declare function contentTokens(s: string): Set<string>;

package/dist/shared/content-tokens.js

@@ -0,0 +1,137 @@
+/**
+ * content-tokens — the distinctive words of a phrase, and the one tokenizer that
+ * decides them.
+ *
+ * Two consumers ask the same question of a string and must get the same answer:
+ * the coverage guard, which grounds requirement/title ownership in shared
+ * distinctive nouns, and the research cache, whose key is the sorted token set of
+ * a query so two phrasings of one question share one digest. A second tokenizer
+ * would be a second answer.
+ */
+// Ubiquitous words that carry no coverage signal: they appear across most task
+// titles and requirement quotes, so overlap on them would falsely connect a
+// requirement to any plan. Stopped so grounding keys on the DISTINCTIVE nouns
+// (json, dead-letter, serialize, symlink…) that actually name a deliverable.
+//
+// Confirmed: titles built only from these words own NOTHING, while titles naming
+// `JSON output` and `dead-letter queue` own the matching requirements.
+//
+// English function words + generic task verbs + generic project nouns — all
+// domain-agnostic.
+export const CONTENT_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',
+    // 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',
+    // generic project nouns
+    '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`.
+ *  A single trailing `s` is stripped (len ≥4) so `scan`/`scans`, `file`/`files`,
+ *  `serialize`/`serializes` match — plain plural/3rd-person, no full stemmer. */
+export function contentTokens(s) {
+    const out = new Set();
+    for (const raw of s.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 3 || CONTENT_STOPWORDS.has(raw))
+            continue;
+        const w = raw.length >= 4 && raw.endsWith('s') && !raw.endsWith('ss') ? raw.slice(0, -1) : raw;
+        out.add(w);
+    }
+    return out;
+}

package/dist/task/accept-debt.d.ts

@@ -47,8 +47,22 @@ import { type CommandRunner } from './command-run.js';
  *     defect is recorded here and a scoped repair task is queued into the plan
  *     (root-cause-repair.ts). Recording without queuing would let the same root
  *     cause be re-recorded by each task it fails, with nothing ever fixing it.
+ *   - 'spec-contradiction' — the gate's decision table proved the failing criterion
+ *     can only be met by editing a path the SAME spec freezes, on any fail class
+ *     (gate-resolution.ts). Supersedes 'frozen-blocked', which said the same thing
+ *     about repo-health alone; that origin stays registered because debts already
+ *     on disk carry it.
+ *   - 'dismissed' — a human was shown the verify-FAIL picker and walked away. The
+ *     defect is no less real for not being answered, and this is the class that
+ *     used to leave no ledger entry at all.
+ *   - 'inherited-health' — the repo entered the task ALREADY failing its own static
+ *     check, so the FAIL is not this task's regression (see the differential health
+ *     delta). Recorded rather than blamed: the task proceeds, the pre-existing
+ *     breakage is still surfaced at run end.
+ *   - 'abandoned' — the loop gave up on the task past its attempt budget without a
+ *     verified artifact. Nothing else records what was left unfinished.
  */
-export type DebtOrigin = 'accepted' | 'enforce-revert' | 'enforce-kept' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate' | 'root-cause';
+export type DebtOrigin = 'accepted' | 'enforce-revert' | 'enforce-kept' | 'frozen-blocked' | 'spec-contradiction' | 'dismissed' | 'inherited-health' | 'abandoned' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate' | 'root-cause';
 /** One recorded defect: the task, why its VERIFY failed, and how it was recorded. */
 export interface AcceptDebt {
     taskId: string;

package/dist/task/accept-debt.js

@@ -66,6 +66,10 @@ const DEBT_LABELS = {
     'enforce-revert': 'enforce re-verify FAILED then the edits were reverted (defect indicts the ORIGINAL work, still shipped)',
     'enforce-kept': 'enforce re-verify FAILED on a check the enforce diff cannot reach — the guideline edits were KEPT (reverting them could not fix it) and the defect indicts the ORIGINAL work, still shipped',
     'frozen-blocked': 'repo health blocked by a spec-frozen path (cross-task contradiction — no task may perform the fixing edit)',
+    'spec-contradiction': "the failing criterion can only be met by editing a path this task's own spec freezes (no re-run under the same freeze converges)",
+    dismissed: 'the verify-FAIL picker was DISMISSED — a human saw the defect and answered nothing',
+    'inherited-health': "the repo was ALREADY failing its own static check before this task ran (pre-existing, not this task's regression)",
+    abandoned: 'the task was abandoned past its attempt budget with no verified artifact',
     'cross-task-deletion': "a sibling task's committed deliverable was DELETED by this task's work and the deletion was accepted (still missing from the tree)",
     'yolo-accepted': 'auto-ACCEPTED by YOLO mode despite verify-FAIL (unattended — no human weighed this)',
     'final-gate': 'final-gate check DEMOTED to UNOBSERVED (identical failure across two tree-changing fix attempts — unfalsifiable in that environment, never proven passing)',

package/dist/task/artifact-closure.js

@@ -51,6 +51,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { shippedSources, stripCommentLines, SOURCE_HTML_RE, SOURCE_JS_RE } from './shipped-source.js';
+import { blocksOf, parseSpecDoc } from './spec-doc.js';
 export function emptyProducers() {
     return {
         files: new Set(),
@@ -940,10 +941,15 @@ const PROSE_CONSUME_RE = /\b(?:serves?|serving|served|fallback|reads?|loads?|ren
  *  `index.html`, `data/seed.json` and `assets/logo.svg` all extract.
  *  Code-construct refs are not subject to this list. */
 const PROSE_ASSET_EXT_RE = /\.(?:html?|css|m?js|cjs|json|svg|png|jpe?g|gif|webp|ico|woff2?|ttf|otf|wasm|webmanifest|xml|csv|sql|ya?ml|toml|pdf|mp[34]|db|sqlite)$/i;
+/** The block kinds that can carry consuming PROSE. A fence is code — its
+ *  `serve`/`read` calls are the code channel's to resolve, not prose's — and a
+ *  blockquote is quoting something the spec is not itself saying. */
+const PROSE_KINDS = new Set(['para', 'list-item', 'table-row']);
 /** Backticked, asset-extension, path-shaped tokens on consuming-verb lines. */
 export function extractSpecProseRefs(spec) {
     const out = [];
-    for (const line of spec.split('\n')) {
+    const prose = blocksOf(parseSpecDoc(spec)).filter(b => PROSE_KINDS.has(b.kind));
+    for (const line of prose.flatMap(b => b.text.split('\n'))) {
         if (!PROSE_CONSUME_RE.test(line))
             continue;
         const tick = /`([^`\n]+)`/g;

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

@@ -1,10 +1,27 @@
 import type { TaskState } from './task-types.js';
 import type { AutoResumeCandidate } from './resume-gap.js';
+import { type RunEndKind } from './run-end.js';
 export interface TaskEntry {
+    /** Position in the list — shifts when a repair step is spliced in. */
     index: number;
+    /**
+     * The entry's stable identity, allocated at plan time and never reused.
+     * `index` moves and `title` is prose a later pass may rewrite; this is what
+     * the owned-requirements ledger joins on. Absent on an AUTO file written
+     * before the key existed, where the title join is still the only one there is.
+     */
+    key?: string;
     title: string;
     done: boolean;
     producedId?: string;
+    /** How many implementation attempts this entry has had. */
+    attempts?: number;
+    /**
+     * How the last attempt ENDED, recorded only when it ended abnormally. A
+     * resume otherwise cannot tell an entry the user cancelled from one that
+     * faulted, because both leave the same unchecked, stamped line.
+     */
+    lastEnd?: RunEndKind;
 }
 export declare function allocateAutoId(cwd: string): Promise<string>;
 /**
@@ -23,20 +40,40 @@ export declare function allocateAutoId(cwd: string): Promise<string>;
  */
 export declare function parseDecomposeList(raw: string): string[];
 /** Parsed DECOMPOSE_COVERAGE_PROMPT verdict. */
-export interface CoverageVerdict {
-    kind: 'complete' | 'incomplete';
+export type CoverageVerdict = {
+    kind: 'complete';
+    missing: string[];
+} | {
+    kind: 'incomplete';
     missing: string[];
 }
+/** The judge DID rule INCOMPLETE but named nothing to reprompt with. */
+ | {
+    kind: 'unparseable';
+};
+/** What an `unparseable` verdict contributes to the plan's missing-area list, so
+ *  the judge's own INCOMPLETE cannot be shipped as COMPLETE. */
+export declare const UNNAMED_COVERAGE_GAP = "the coverage judge ruled INCOMPLETE without naming the uncovered area";
 /**
  * Parse the coverage-triage child's verdict. Returns null when no COVERAGE tag is
- * present (the model wrote prose), and the caller reads a null verdict as an
- * empty missing-list, so a malformed judgment can never block planning.
+ * present at all (the model wrote prose), and the caller reads a null verdict as
+ * an empty missing-list, so a malformed judgment can never block planning.
  *
- * `COVERAGE: INCOMPLETE` with no MISSING lines also returns null, deliberately:
- * it names nothing to reprompt with, so treating it as a verdict would loop
- * blind. Confirmed by running both shapes.
+ * `COVERAGE: INCOMPLETE` with no MISSING lines is NOT null, and that distinction
+ * is the whole point: prose is no verdict, while this is a verdict of INCOMPLETE
+ * that happens to name nothing. Collapsing the two shipped a plan the judge had
+ * just ruled incomplete, logged as COMPLETE.
  */
 export declare function parseCoverageVerdict(raw: string): CoverageVerdict | null;
+/** The plan key for the `index`th entry of a freshly planned list. */
+export declare function planKeyAt(index: number): string;
+/**
+ * The lowest key number no entry in `entries` holds. Keys are allocated 1:1 with
+ * plan entries, so an unkeyed legacy list has implicitly spent its first N
+ * numbers — counting it in keeps a spliced repair step from minting a key an
+ * eventual migration would hand to an existing entry.
+ */
+export declare function nextPlanKey(entries: readonly TaskEntry[]): string;
 /** Parse the "## tasks" checkbox list. */
 export declare function parseTaskList(body: string): TaskEntry[];
 /** Build the initial AUTO-file body. `coverage` is the requirement-level
@@ -51,8 +88,23 @@ export declare function checkOffTask(cwd: string, id: string, index: number, pro
  * the inner task is allocated. This links the AUTO entry to its in-progress
  * inner task so /task-auto-resume can continue it from its saved phase instead
  * of starting a brand-new task — matching how /task-resume behaves.
+ *
+ * The first stamp is also where the attempt counter is minted: an entry under way
+ * has had one attempt.
  */
 export declare function stampTaskInProgress(cwd: string, id: string, index: number, producedId: string, title: string): Promise<void>;
+/**
+ * Count one more attempt on the `index`th entry and return the new total.
+ *
+ * Called for a fresh start AND for a resume, because both spend a run on the
+ * entry: a task that crashes in refine is re-entered from scratch every time, and
+ * a counter that only saw fresh starts would read 1 forever while the loop re-ran
+ * it without end. The previous ending is cleared here — it describes the attempt
+ * that is now over.
+ */
+export declare function beginTaskAttempt(cwd: string, id: string, index: number): Promise<number>;
+/** Record how the `index`th entry's attempt ended. */
+export declare function recordTaskEnd(cwd: string, id: string, index: number, lastEnd: RunEndKind): Promise<void>;
 /**
  * Insert a NEW unchecked entry directly after the `afterIndex`th checkbox — the
  * mid-run plan mutation the root-cause repair channel needs: a repair task must