@mjasnikovs/pi-task 0.40.50 → 0.42.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;
@@ -75,6 +89,12 @@ export interface AcceptDebt {
      * string is the VERIFY-block line itself (`inv-command-provenance`).
      */
     verifyCommand?: string;
+    /**
+     * The task whose verified work CLOSED this debt (a health repair whose check
+     * went green — see closeHealthDebts). A closed debt stays in the ledger as the
+     * record of what fixed it, and no re-check reads it again.
+     */
+    resolvedBy?: string;
 }
 export declare function acceptDebtFile(cwd: string): string;
 /** The raw stored ledger ('' when none recorded yet). Parse with parseAcceptDebts. */
@@ -132,6 +152,16 @@ export declare function crossTaskDeletionReason(deletion: {
 export declare function extractDeletedDebtPath(reason: string): string | null;
 /** Overwrite the ledger with exactly these records (used to prune resolved debts). */
 export declare function writeAcceptDebts(cwd: string, debts: AcceptDebt[]): Promise<void>;
+/** The debts nothing has closed yet — the only ones a re-check may read. */
+export declare function readOpenAcceptDebts(cwd: string): Promise<AcceptDebt[]>;
+/**
+ * Close every open static-class debt that names `command`, stamping the task
+ * whose verified work made that check pass again. Returns the debts closed.
+ * A reason that quotes the command is the whole match: the health-check reason
+ * (`repo health: \`bun run lint\` exited 1`) and its inherited form both do,
+ * and nothing else in the ledger quotes a health command. Best-effort.
+ */
+export declare function closeHealthDebts(cwd: string, command: string, resolvedBy: string): Promise<AcceptDebt[]>;
 /**
  * STATIC-CLASS debt: one whose accepted FAIL was the deterministic whole-repo static
  * health check (`repo health: …`, the prefix runWorkVerification's repoHealth branch

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)',
@@ -109,6 +113,7 @@ export function parseAcceptDebts(raw) {
         // 4th field: the verbatim VERIFY command the reason names.
         // Absent in every legacy record, and absent in most new ones.
         const verifyCommand = parts[3]?.trim();
+        const resolvedBy = parts[4]?.trim();
         out.push({
             taskId: parts[0].trim(),
             reason: parts[1].trim(),
@@ -116,7 +121,8 @@ export function parseAcceptDebts(raw) {
             // implicit class, so an absent origin and a spelled-out 'accepted' must
             // parse to the same record.
             ...(isKnownOrigin(origin) && origin !== 'accepted' ? { origin } : {}),
-            ...(verifyCommand !== undefined && verifyCommand.length > 0 ? { verifyCommand } : {})
+            ...(verifyCommand !== undefined && verifyCommand.length > 0 ? { verifyCommand } : {}),
+            ...(resolvedBy !== undefined && resolvedBy.length > 0 ? { resolvedBy } : {})
         });
     }
     return out;
@@ -137,6 +143,16 @@ function serialize(d) {
     // only for the non-accepted classes, so old readers/files round-trip unchanged.
     // The 4th verify-command field forces the origin field to be written (positional
     // format) — 'accepted' spelled out there parses back to the same absent origin.
+    // The 5th field likewise forces an (empty) 4th.
+    if (d.resolvedBy !== undefined && d.resolvedBy.length > 0) {
+        return [
+            d.taskId,
+            d.reason,
+            d.origin ?? 'accepted',
+            d.verifyCommand ?? '',
+            d.resolvedBy
+        ].join(FIELD_SEP);
+    }
     if (d.verifyCommand !== undefined && d.verifyCommand.length > 0) {
         return [d.taskId, d.reason, d.origin ?? 'accepted', d.verifyCommand].join(FIELD_SEP);
     }
@@ -230,6 +246,33 @@ export function extractDeletedDebtPath(reason) {
 export async function writeAcceptDebts(cwd, debts) {
     await ledger.write(cwd, debts);
 }
+/** The debts nothing has closed yet — the only ones a re-check may read. */
+export async function readOpenAcceptDebts(cwd) {
+    return (await readAcceptDebts(cwd)).filter(d => d.resolvedBy === undefined);
+}
+/**
+ * Close every open static-class debt that names `command`, stamping the task
+ * whose verified work made that check pass again. Returns the debts closed.
+ * A reason that quotes the command is the whole match: the health-check reason
+ * (`repo health: \`bun run lint\` exited 1`) and its inherited form both do,
+ * and nothing else in the ledger quotes a health command. Best-effort.
+ */
+export async function closeHealthDebts(cwd, command, resolvedBy) {
+    try {
+        const all = await readAcceptDebts(cwd);
+        const quoted = `\`${command}\``;
+        const closing = all.filter(d => d.resolvedBy === undefined
+            && isStaticClassDebt(d.reason)
+            && d.reason.includes(quoted));
+        if (closing.length === 0)
+            return [];
+        await ledger.write(cwd, all.map(d => (closing.includes(d) ? { ...d, resolvedBy } : d)));
+        return closing;
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * STATIC-CLASS debt: one whose accepted FAIL was the deterministic whole-repo static
  * health check (`repo health: …`, the prefix runWorkVerification's repoHealth branch
@@ -508,7 +551,10 @@ export function describeDebt(d) {
 export async function deriveOpenDebts(cwd, staticOk, 
 /** The spawner for the VERIFY-COMMAND re-runs. Defaults to the real one. */
 run = spawnCommand, signal) {
-    const { open: openRaw, resolved, trail } = await recheckAcceptDebts(await readAcceptDebts(cwd), {
+    const all = await readAcceptDebts(cwd);
+    // Closed debts are kept as the record of what fixed them, and never re-checked.
+    const closed = all.filter(d => d.resolvedBy !== undefined);
+    const { open: openRaw, resolved, trail } = await recheckAcceptDebts(all.filter(d => d.resolvedBy === undefined), {
         staticOk,
         // Cross-task-deletion debts auto-close iff the deleted file is back in the
         // tree — a deterministic existence check, corroborating the per-file
@@ -520,7 +566,7 @@ run = spawnCommand, signal) {
         rerunVerify: cmd => rerunDebtVerifyCommand(cwd, cmd, run, signal)
     });
     if (resolved.length > 0)
-        await writeAcceptDebts(cwd, openRaw);
+        await writeAcceptDebts(cwd, [...closed, ...openRaw]);
     // Conflicting-claim annotation: an existence-as-failure debt whose
     // named file is another task's committed deliverable is a plan defect — surface
     // the contradiction with the debt so nobody (human or child) treats the claim as