@mjasnikovs/pi-task 0.38.28 → 0.38.30

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

@@ -1,32 +1,23 @@
 /**
  * Running ONE bounded fix child and deciding what its ending MEANS.
  *
- * Two graduated-resolution passes drive a fix child through the same four rungs —
- * cancel propagates, a thrown child is an error, a self-declared BLOCKED ends the
- * attempt, anything else is DONE — and `final-gate-fix.ts:12` says so out loud:
- * it "mirrors the per-task graduated-resolution shape (lint-fix.ts)". This is that
- * ladder, once.
+ * Two graduated-resolution passes — `lint-fix.ts` and `final-gate-fix.ts` — drive
+ * a fix child through the same four rungs: a cancel propagates as a throw, a
+ * child that threw for any other reason is an `error`, a self-declared BLOCKED is
+ * `blocked`, and anything else is `done`. `final-gate-fix.ts`'s own header says
+ * it "mirrors the per-task graduated-resolution shape (lint-fix.ts)". This is
+ * that ladder, written once.
  *
- * NOT the rejected sharing. CONTEXT.md's "the two resolution loops stay two" is
- * about `runGatesForTask` vs `runFinalGateStage` — the LOOPS, at two altitudes.
- * This is one altitude down: the single child invocation inside each, where the
- * two had actually drifted.
+ * Both prompts instruct the marker their pass parses: `LINT-FIX: DONE` /
+ * `LINT-FIX: BLOCKED <why>` and `FINAL-GATE-FIX: DONE` / `FINAL-GATE-FIX:
+ * BLOCKED <why>`.
  *
- *  - **The lint-fix marker was a DEAD protocol.** `buildLintFixPrompt` instructs
- *    the child to end with `LINT-FIX: DONE` or `LINT-FIX: BLOCKED <why>`, and the
- *    call site was `await deps.runChild(...)` with the return value DISCARDED —
- *    nothing in `src/` or `scripts/` parsed it. The twin parsed its own marker and
- *    used it to skip the expensive gate re-run. So a lint-fix child that reported
- *    BLOCKED still paid the full guard stack plus a whole repo-health run (15–69s
- *    measured), and the user was told `did not converge: <health.reason>` instead
- *    of the child's own stated reason. The suite fed `'LINT-FIX: DONE'` as fake
- *    output, so it stayed green whether the marker was parsed or deleted.
- *  - **The cancel rung re-typed its constant.** `lint-fix.ts` compared against a
- *    literal `'__user_cancelled__'`; it was the only production site in `src/` not
- *    importing `USER_CANCELLED`.
- *
- * What stays per-site: the arbiter (a gate re-run vs a repo-health re-run), the
- * result shape, and the guard sets. Only the child call is shared.
+ * What stays per-site: the arbiter, the result shape, and the guard sets. Only
+ * the child call is shared. The arbiters differ in kind — `final-gate-fix` calls
+ * `deps.gate`, `lint-fix` calls `deps.repoHealth` — and so does what BLOCKED
+ * buys: `final-gate-fix` skips its gate re-run on a blocked child, while
+ * `lint-fix` runs repo-health regardless and uses the marker only to word the
+ * failure.
  */
 /** How one fix child ended. A CANCEL is not a member: it throws, so the caller's
  *  own `USER_CANCELLED` path runs unchanged. */
@@ -52,9 +43,12 @@ export interface FixChildInput {
 }
 /**
  * Parse a fix child's final marker. Last match wins: the model reasons before
- * concluding, and bash output can echo the words. No marker → DONE, because the
- * pass's own arbiter re-runs either way; a missing marker only forfeits the
- * early-out on a self-declared BLOCKED.
+ * concluding, and both passes give the child `bash`, so its own command output is
+ * in the text being scraped.
+ *
+ * No marker → DONE. Neither pass treats the marker as the verdict — the arbiter
+ * decides — so a missing marker costs at most the blocked early-out in
+ * `final-gate-fix`, and nothing at all in `lint-fix`.
  */
 export declare function parseFixMarker(marker: string, text: string): {
     blocked: boolean;

package/dist/task/fix-child.js

@@ -1,39 +1,33 @@
 /**
  * Running ONE bounded fix child and deciding what its ending MEANS.
  *
- * Two graduated-resolution passes drive a fix child through the same four rungs —
- * cancel propagates, a thrown child is an error, a self-declared BLOCKED ends the
- * attempt, anything else is DONE — and `final-gate-fix.ts:12` says so out loud:
- * it "mirrors the per-task graduated-resolution shape (lint-fix.ts)". This is that
- * ladder, once.
+ * Two graduated-resolution passes — `lint-fix.ts` and `final-gate-fix.ts` — drive
+ * a fix child through the same four rungs: a cancel propagates as a throw, a
+ * child that threw for any other reason is an `error`, a self-declared BLOCKED is
+ * `blocked`, and anything else is `done`. `final-gate-fix.ts`'s own header says
+ * it "mirrors the per-task graduated-resolution shape (lint-fix.ts)". This is
+ * that ladder, written once.
  *
- * NOT the rejected sharing. CONTEXT.md's "the two resolution loops stay two" is
- * about `runGatesForTask` vs `runFinalGateStage` — the LOOPS, at two altitudes.
- * This is one altitude down: the single child invocation inside each, where the
- * two had actually drifted.
+ * Both prompts instruct the marker their pass parses: `LINT-FIX: DONE` /
+ * `LINT-FIX: BLOCKED <why>` and `FINAL-GATE-FIX: DONE` / `FINAL-GATE-FIX:
+ * BLOCKED <why>`.
  *
- *  - **The lint-fix marker was a DEAD protocol.** `buildLintFixPrompt` instructs
- *    the child to end with `LINT-FIX: DONE` or `LINT-FIX: BLOCKED <why>`, and the
- *    call site was `await deps.runChild(...)` with the return value DISCARDED —
- *    nothing in `src/` or `scripts/` parsed it. The twin parsed its own marker and
- *    used it to skip the expensive gate re-run. So a lint-fix child that reported
- *    BLOCKED still paid the full guard stack plus a whole repo-health run (15–69s
- *    measured), and the user was told `did not converge: <health.reason>` instead
- *    of the child's own stated reason. The suite fed `'LINT-FIX: DONE'` as fake
- *    output, so it stayed green whether the marker was parsed or deleted.
- *  - **The cancel rung re-typed its constant.** `lint-fix.ts` compared against a
- *    literal `'__user_cancelled__'`; it was the only production site in `src/` not
- *    importing `USER_CANCELLED`.
- *
- * What stays per-site: the arbiter (a gate re-run vs a repo-health re-run), the
- * result shape, and the guard sets. Only the child call is shared.
+ * What stays per-site: the arbiter, the result shape, and the guard sets. Only
+ * the child call is shared. The arbiters differ in kind — `final-gate-fix` calls
+ * `deps.gate`, `lint-fix` calls `deps.repoHealth` — and so does what BLOCKED
+ * buys: `final-gate-fix` skips its gate re-run on a blocked child, while
+ * `lint-fix` runs repo-health regardless and uses the marker only to word the
+ * failure.
  */
 import { USER_CANCELLED } from './child-runner.js';
 /**
  * Parse a fix child's final marker. Last match wins: the model reasons before
- * concluding, and bash output can echo the words. No marker → DONE, because the
- * pass's own arbiter re-runs either way; a missing marker only forfeits the
- * early-out on a self-declared BLOCKED.
+ * concluding, and both passes give the child `bash`, so its own command output is
+ * in the text being scraped.
+ *
+ * No marker → DONE. Neither pass treats the marker as the verdict — the arbiter
+ * decides — so a missing marker costs at most the blocked early-out in
+ * `final-gate-fix`, and nothing at all in `lint-fix`.
  */
 export function parseFixMarker(marker, text) {
     const re = new RegExp(`${marker}:\\s*(DONE|BLOCKED)\\b[ \\t]*(.*)`, 'gi');

package/dist/task/foreign-path.d.ts

@@ -18,8 +18,9 @@ export interface ForeignPathFinding {
  * `src/client/api.ts`). Returns the resolved repo-relative path, or null.
  *
  * This mirrors how the tools that CONSUME these paths (vite/tsconfig aliases,
- * bundler resolvers) look them up — without it the mx5 true positive
- * `/workspace/src/client/api` would be missed, since only `src/client/api.ts` exists.
+ * bundler resolvers) look them up. Without it an extensionless leak is missed:
+ * measured here, `src/task/foreign-path` resolves to `src/task/foreign-path.ts`,
+ * and `src/nope` resolves to null.
  */
 export declare function resolveRepoPath(rel: string, exists: (rel: string) => boolean): string | null;
 /**
@@ -30,9 +31,9 @@ export declare function resolveRepoPath(rel: string, exists: (rel: string) => bo
  * synthetic tree.
  *
  * The tail search strips the FEWEST leading segments that still resolve, so the
- * finding names the smallest foreign prefix (`/workspace`, not `/workspace/src`)
- * and the largest repo-relative target — the reading that matches how a mount
- * actually shadows a tree.
+ * finding names the smallest foreign prefix and the largest repo-relative target —
+ * the reading that matches how a mount shadows a tree. Measured:
+ * `/aaa/bbb/src/task/foreign-path.ts` reports prefix `/aaa/bbb`, not `/aaa`.
  */
 export declare function findForeignPaths(lines: AddedLine[], existsOnHost: (abs: string) => boolean, existsInRepo: (rel: string) => boolean): ForeignPathFinding[];
 /**

package/dist/task/frozen-conflict.d.ts

@@ -1,6 +1,6 @@
 /** One unsatisfiable freeze/requires-edit pair found in a composed spec. */
 export interface FrozenPathConflict {
-    /** The frozen path (normalized: no leading ./, no trailing /). */
+    /** The frozen path (normalized: no leading./, no trailing /). */
     path: string;
     /** The freeze line, verbatim (the `Do NOT modify` constraint). */
     constraint: string;
@@ -20,17 +20,16 @@ export interface FrozenPathConflict {
  * SPEC alone; research contributes only the statement side (live compose
  * sometimes drops the research's "must also be included" nuance from the spec
  * text while shipping the freeze and the file creation - the contradiction is
- * then visible only across the compose boundary). Deterministic, pure text -
- * the same extraction the live A/B grounds its measurements in, so the model
- * cannot self-report its way past it. Empty on a null spec or one that froze
- * nothing.
+ * then visible only across the compose boundary). Deterministic and pure text,
+ * so the model cannot self-report its way past it. Empty on a null spec or one
+ * that froze nothing.
  */
 export declare function findFrozenPathConflicts(spec: string | null | undefined, research?: string | null): FrozenPathConflict[];
 /**
- * The forced critique-rewrite defect text (skip-escape pattern: MANDATORY,
- * self-contained, names the exact resolution options). The two permitted
- * resolutions come straight from the incident analysis: scoped ownership or
- * dropping the creation — prose acknowledging the gap is called out as a
- * non-resolution because that is precisely what the live model shipped.
+ * The forced critique-rewrite defect text: MANDATORY, self-contained, and it
+ * names the exact resolution options. Only two are permitted — scoped ownership
+ * or dropping the creation — and prose acknowledging the gap is called out as a
+ * non-resolution, because that is the shape a model reaches for first and it
+ * leaves the contradiction intact.
  */
 export declare function frozenConflictProbeText(conflicts: FrozenPathConflict[]): string;

package/dist/task/frozen-conflict.js

@@ -1,54 +1,50 @@
 /**
  * frozen-conflict — deterministic detection of an UNSATISFIABLE spec pair at
- * compose time (mx5 run 12 root cause, PROMPT 1 layer A).
+ * compose time.
  *
- * The failure this closes: compose authored TASK_0020 with a blanket freeze
- * ("Do not modify `tsconfig.json`, `eslint.config.js`, or `.prettierrc.cjs`;
- * those are handled in steps 1–2") while the deliverable — new
- * `playwright-ct.config.ts` + `playwright/index.ts` — needs exactly that
- * registration edit, and the spec "resolved" the contradiction with prose
- * surrender ("Accept that `playwright-ct.config.ts` will not be covered by
- * `tsc --noEmit` since `tsconfig.json` is not modified in this step"). Typed
- * ESLint does not "accept" anything: the moment the created files land,
- * `bun run lint` hard-errors REPO-WIDE and permanently — and the "owning"
- * steps 1–2 completed long ago, so NO task may ever perform the edit (every
- * spec carries the same freeze). Every subsequent task then burned its
- * unattended AUTOFIX rounds on a repo-health FAIL none of them was allowed to
- * fix, and the eventual "escape" was a child DELETING the deliverables.
+ * The shape: a spec blanket-freezes a config file while its own deliverable
+ * needs exactly the registration edit that freeze forbids, and the
+ * contradiction is "resolved" in prose ("Accept that it will not be covered by
+ * `tsc --noEmit` since `tsconfig.json` is not modified in this step"). A typed
+ * linter accepts nothing. The moment the created files land the repo-wide
+ * static check fails PERMANENTLY, and because the step that owns the frozen
+ * file has already completed, no later task is allowed to fix it either — every
+ * one of them burns its autofix rounds on a defect none of them may touch.
  *
- * The contradiction is visible IN THE COMPOSED TEXT ITSELF, so it must die at
- * spec time. Like the skip-escape / synthesized-wiring / plan-contradiction
- * probes (prompt-only rules are A/B-proven ~0–1/5 on the weak model), the
- * detector is deterministic and its finding is FORCED into the critique
- * rewrite: the rewrite must either grant scoped ownership ("MAY edit `X` ONLY
- * to register the files this task creates") or drop the file creation.
+ * The contradiction is visible IN THE COMPOSED TEXT ITSELF, so it dies at spec
+ * time: the detector is deterministic and its finding is FORCED into the
+ * critique rewrite, which must either grant scoped ownership ("MAY edit `X`
+ * ONLY to register the files this task creates") or drop the file creation.
+ *
+ * High-precision by construction. Each rule below was run against the detector:
  *
- * High-precision by construction (FP-swept over the 26 real mx5 run-12 specs):
  *   - the freeze side must be BLANKET — a `Do NOT modify` line with no
- *     exception clause; a scoped freeze ("MAY edit … ONLY to register",
- *     "Only edit `X` …", "… except to add …") is already the resolution shape
- *     and must never re-fire;
- *   - the statement side is judged per SENTENCE, not per line (real GOALs are
- *     one giant line — line scoping false-fired on `must include` in a
- *     response-shape sentence three paths away from the frozen one);
- *   - a sentence that is itself prohibition-shaped ("Preserve … do not
- *     remove or modify …") is the freeze side restated, never a statement;
- *   - the sentence must NAME the frozen path (pathNamedIn) AND match one of
- *     the measured phrasing families: passive registration ("must also be
- *     included"), unless-added ("won't be type-checked unless added"),
- *     directional active ("requires adding … to" / "must add … to"), or the
- *     prose SURRENDER itself ("will not be covered … since `X` is not
- *     modified" — the exact line the live TASK_0020 spec shipped).
- * Mere co-mention never fires.
+ *     exception clause. A scoped freeze is already the resolution shape and
+ *     must never re-fire; "… except to add …", "You MAY edit `X` ONLY to
+ *     register …" and "Only edit `X` (…)" each yield zero against a statement
+ *     that otherwise fires;
+ *   - the statement side is judged per SENTENCE, not per line, because real
+ *     GOALs are one giant line. Measured: a line carrying the GOAL, a
+ *     response-shape "must include `id` and `name`", and a path mention yields
+ *     nothing, while the same line shape carrying a real registration sentence
+ *     yields one;
+ *   - a prohibition-shaped sentence ("Preserve … do not remove or modify …") is
+ *     the freeze side restated and yields nothing;
+ *   - the sentence must NAME the frozen path AND match one of the phrasing
+ *     families. All six fire: passive registration, unless-added,
+ *     not-checked-unless, "requires adding … to", "must add … to", and the
+ *     surrender pair.
+ *
+ * Mere co-mention never fires: "The build reads `tsconfig.json` at startup."
+ * yields nothing.
  */
 import { extractProhibitions, PROHIBITION_RE } from './prohibition-probe.js';
 import { pathNamedIn } from './frozen-path-guard.js';
 /**
  * A freeze that carves out its own exception is SCOPED, not blanket — it is
- * exactly the resolution shape the probe demands ("MAY edit `X` ONLY to
- * register…", "Only edit `X` (add the search route)…", "Do not modify `X`
- * except to add…"), so it never counts as the freeze side of a conflict, or
- * the recomposed spec would re-fire forever.
+ * exactly the resolution shape the probe demands, so it never counts as the
+ * freeze side of a conflict. Without this the recomposed spec would re-fire
+ * forever on its own fix.
  */
 const EXCEPTION_RE = /\b(?:except|unless|beyond|other\s+than|apart\s+from|only\s+(?:to|for|if|when|where|edit|modify|change|touch|update)|may\s+(?:edit|modify|change|update|add))\b/i;
 /** Passive registration: "must (also) be included/added/registered/…". */
@@ -58,13 +54,13 @@ const UNLESS_ADDED_RE = /\bunless\s+(?:it\s+is\s+|it'?s\s+|they\s+are\s+|first\s
 /** "won't be type-checked/compiled/linted/covered … unless …". */
 const NOT_CHECKED_UNLESS_RE = /\b(?:won'?t|will\s+not|cannot|can'?t|does\s+not|doesn'?t|is\s+not|isn'?t)\s+(?:be\s+)?[\w\s-]{0,40}?(?:type-?check|compil|lint|cover|resolv|recogni[sz]|includ|pick)\w*[^;]{0,80}?\bunless\b/i;
 /** Directional active: "requires adding … to …" / "must add … to/into/in …".
- *  The preposition requirement is what keeps a response-shape "must include
- *  `field`" sentence from counting as a registration edit. */
+ *  The preposition is what keeps a response-shape sentence from counting as a
+ *  registration edit — measured, "The response must include `tsconfig.json`."
+ *  yields nothing while "You must add the new entry to `tsconfig.json`." fires. */
 const REQUIRES_DIRECTIONAL_RE = /\brequires?\s+(?:add|includ|regist|updat|edit|modify|chang)\w*[^;]{0,80}?\b(?:to|into|in)\b/i;
 const MUST_ADD_DIRECTIONAL_RE = /\bmust\s+(?:also\s+)?(?:add|includ|regist|updat)\w*[^;]{0,80}?\b(?:to|into|in)\b/i;
 /** The prose-surrender pair: an artifact "will not be covered/type-checked/…"
- *  BECAUSE the (frozen) path "is not modified". Both halves must be present —
- *  this is the exact contradiction shape the live TASK_0020 spec shipped. */
+ *  BECAUSE the (frozen) path "is not modified". BOTH halves must be present. */
 const NOT_COVERED_RE = /\b(?:will\s+not|won'?t|cannot|can'?t|is\s+not|isn'?t)\s+(?:be\s+)?(?:covered|type-?checked|checked|compiled|linted|validated|included)\b/i;
 const BECAUSE_NOT_MODIFIED_RE = /\b(?:since|because|as)\b[^;]{0,80}?\b(?:is\s+|are\s+|was\s+|were\s+)?not\s+(?:be(?:ing)?\s+)?(?:modif|edit|chang|updat|touch)\w*/i;
 function isRequiresEditStatement(sentence) {
@@ -77,16 +73,18 @@ function isRequiresEditStatement(sentence) {
 }
 /**
  * Split a spec line into sentences: a `.` or `;` followed by whitespace and a
- * capital/backtick/bracket opener ends a sentence. The opener requirement
- * keeps `e.g. foo` and mid-path dots intact; backtick paths carry no `. ` so
- * they never split. Judging per sentence is what makes one-giant-line GOALs
- * scannable without cross-sentence false fires.
+ * capital, backtick or bracket opener ends a sentence. The opener requirement
+ * keeps `e.g. foo` and mid-path dots intact — measured, a sentence containing
+ * "e.g." still matches as one piece. Judging per sentence is what makes
+ * one-giant-line GOALs scannable without cross-sentence false fires.
  */
 function splitSentences(line) {
     return line.split(/[.;]\s+(?=[A-Z`([-])/);
 }
-/** Backtick-quoted path-shaped tokens in a sentence (the same shape rule the
- *  prohibition extractor applies), minus surrounding quotes. */
+/** Backtick-quoted path-shaped tokens in a sentence, minus surrounding quotes.
+ *  The same three-way test `looksLikePath` applies in prohibition-probe.ts:
+ *  path characters only, and either a separator, an extension, or a leading
+ *  dot. */
 function pathTokensIn(sentence) {
     const out = [];
     for (const m of sentence.matchAll(/`([^`]+)`/g)) {
@@ -103,11 +101,11 @@ function pathTokensIn(sentence) {
  *  frozen path, appending each new pair to `out`.
  *
  *  `anchorSpec` (research scans only): a research statement counts ONLY when,
- *  besides the frozen path, it names at least one other path that still
- *  appears in the SPEC. That anchor is what makes resolution (b) terminal:
- *  when the rewrite DROPS the file creation, the created file vanishes from
- *  the spec, the research statement about it loses its anchor, and the
- *  detector goes quiet instead of re-firing forever on stale research. */
+ *  besides the frozen path, it names at least one other path that still appears
+ *  in the SPEC. That anchor is what makes resolution (b) terminal — measured,
+ *  the same research sentence fires while the spec still creates the file and
+ *  goes quiet once the spec no longer mentions it, instead of re-firing forever
+ *  on stale research. */
 function scanForStatements(text, blanket, source, out, seen, anchorSpec) {
     for (const raw of text.split('\n')) {
         for (const fragment of splitSentences(raw)) {
@@ -146,10 +144,9 @@ function scanForStatements(text, blanket, source, out, seen, anchorSpec) {
  * SPEC alone; research contributes only the statement side (live compose
  * sometimes drops the research's "must also be included" nuance from the spec
  * text while shipping the freeze and the file creation - the contradiction is
- * then visible only across the compose boundary). Deterministic, pure text -
- * the same extraction the live A/B grounds its measurements in, so the model
- * cannot self-report its way past it. Empty on a null spec or one that froze
- * nothing.
+ * then visible only across the compose boundary). Deterministic and pure text,
+ * so the model cannot self-report its way past it. Empty on a null spec or one
+ * that froze nothing.
  */
 export function findFrozenPathConflicts(spec, research) {
     if (!spec)
@@ -171,11 +168,11 @@ export function findFrozenPathConflicts(spec, research) {
     return out;
 }
 /**
- * The forced critique-rewrite defect text (skip-escape pattern: MANDATORY,
- * self-contained, names the exact resolution options). The two permitted
- * resolutions come straight from the incident analysis: scoped ownership or
- * dropping the creation — prose acknowledging the gap is called out as a
- * non-resolution because that is precisely what the live model shipped.
+ * The forced critique-rewrite defect text: MANDATORY, self-contained, and it
+ * names the exact resolution options. Only two are permitted — scoped ownership
+ * or dropping the creation — and prose acknowledging the gap is called out as a
+ * non-resolution, because that is the shape a model reaches for first and it
+ * leaves the contradiction intact.
  */
 export function frozenConflictProbeText(conflicts) {
     const items = conflicts.map(c => `- the spec FREEZES \`${c.path}\` ("${c.constraint.slice(0, 160)}") yet `

package/dist/task/frozen-path-guard.d.ts

@@ -5,19 +5,24 @@ export type FrozenGit = (args: string[]) => Promise<{
 }>;
 /**
  * The concrete paths the spec forbids modifying, normalized and de-duplicated —
- * the SAME extraction the verify prohibition-probe and the accept-debt ledger
- * consume, so "frozen" means one thing across the gates. Empty when the spec is
- * null or names no path-like token on a modification-ban line: the guard is then a
- * no-op by construction.
+ * `extractProhibitions`, the same extraction the verify prohibition probe
+ * (gate-deps.ts) and the compose-time conflict detector (frozen-conflict.ts)
+ * consume, so "frozen" means one thing across the gates.
+ *
+ * Normalisation strips a leading `./` and a trailing `/`: measured, a spec
+ * banning `` `./src/a.ts` `` and `` `src/b/` `` yields `src/a.ts` and `src/b`.
+ * A null spec, or one with no modification-ban line naming a path, yields an
+ * empty list and the guard is a no-op by construction.
  */
 export declare function frozenPathsFromSpec(spec: string | null | undefined): string[];
 /**
- * Does this prose/tool-output text NAME the given path? Word-bounded on both
- * sides so `tsconfig.json` matches `` `tsconfig.json` ``, `(tsconfig.json:18)`
- * and a bare mention, but never `foo.tsconfig.json`, `config/tsconfig.json`
- * (a different file) or `tsconfig.json5`/`tsconfig.json.bak`. Shared by the
- * compose-time unsatisfiable-pair detector (frozen-conflict.ts) and lint-fix's
- * non-convergence trace, so "the text names a frozen path" means one thing.
+ * Does this prose or tool-output text NAME the given path? Word-bounded on both
+ * sides. Measured against `tsconfig.json`: `` `tsconfig.json` ``,
+ * `(tsconfig.json:18)` and a bare mention all match; `foo.tsconfig.json`,
+ * `config/tsconfig.json` (a different file), `tsconfig.json5` and
+ * `tsconfig.json.bak` all do not. Shared by the compose-time unsatisfiable-pair
+ * detector (frozen-conflict.ts) and lint-fix's non-convergence trace, so "the
+ * text names a frozen path" means one thing.
  */
 export declare function pathNamedIn(text: string, path: string): boolean;
 /**
@@ -26,6 +31,10 @@ export declare function pathNamedIn(text: string, path: string): boolean;
  * anything must be reverted at all. A rename line (`R  old -> new`) yields the NEW
  * path — the side that carries the child's write. Deterministic and pure so the
  * parsing is unit-tested without a real repo.
+ *
+ * Every shape below was taken from real `git status --porcelain` output, not
+ * assumed: ` M path`, ` D path`, `?? path`, `R  old -> new`, and a path
+ * containing a space, which git emits wrapped in double quotes.
  */
 export declare function parseChangedFrozenFiles(porcelain: string): string[];
 /**
@@ -36,10 +45,22 @@ export declare function parseChangedFrozenFiles(porcelain: string): string[];
  * Runs AFTER the task's own work is committed (HEAD), so "restore to HEAD" keeps
  * the verified task's version of the frozen file and discards ONLY the gate
  * child's edit on top of it — the task's own frozen-path edits, if any, are a
- * separate concern the verify prohibition-probe surfaces. `git checkout HEAD`
- * covers modified/deleted tracked files under each pathspec; `git clean` removes
- * any untracked file the pass created under a frozen directory. Both are scoped to
- * the frozen pathspec, so nothing else in the tree is touched.
+ * separate concern the verify prohibition probe surfaces. `git checkout -f HEAD`
+ * covers modified and deleted tracked files under each pathspec; `git clean -fdq`
+ * removes untracked files the pass created under a frozen directory. Both are
+ * scoped to the frozen pathspec.
+ *
+ * Run against a real repo with one frozen directory and one free one: a modified
+ * file came back to its HEAD content, a deleted file came back, and two untracked
+ * creations (one with a space in its name) were removed, while an edit to a file
+ * OUTSIDE the pathspec survived untouched.
+ *
+ * ONE CASE IS NOT FULLY UNDONE: a rename already STAGED in the index. `git mv`
+ * inside the frozen directory leaves `frozen/new.txt` present and staged after
+ * both commands, because checkout cannot restore a path HEAD does not contain and
+ * clean skips tracked files — while this function still reports it as reverted.
+ * An ordinary edit-tool rename is a delete plus an untracked create, and that IS
+ * fully undone; staging requires git, which the enforce child does not have.
  *
  * Best-effort: an empty frozen list, a non-git tree, or any git error yields an
  * empty result — the guard must never break the gate on a project it cannot reason

package/dist/task/frozen-path-guard.js

@@ -1,41 +1,41 @@
 /**
  * frozen-path-guard — deterministic write-deny on spec-frozen paths for the
- * write-capable gate children (the enforce EDIT pass especially).
+ * write-capable gate children, the enforce EDIT pass especially.
  *
- * The failure class (carried from mx5 run 6, deferred there as the last unshipped
- * piece of the frozen-contract work): a spec's CONSTRAINTS pin a path as
- * off-limits ("**Do NOT modify** `src/server/index.ts`"), and a later
- * write-enabled GATE pass — the enforce child runs `read,edit` — edits that path
- * anyway. Its edits are judged only locally (a guideline-compliance verdict), then
- * committed as an "ENFORCE GUIDELINES" snapshot on top of the verified task. The
- * frozen contract is silently mutated by the very pass meant to police the work.
+ * The failure class: a spec's CONSTRAINTS pin a path as off-limits ("**Do NOT
+ * modify** `src/server/index.ts`"), and a later write-enabled GATE pass edits it
+ * anyway. The enforce child runs with `ENFORCE_TOOLS = 'read,edit'`, its edits
+ * are judged only for guideline compliance, and they are then committed as an
+ * `ENFORCE GUIDELINES` snapshot on top of the verified task — so the frozen
+ * contract gets mutated by the very pass meant to police the work.
  *
- * Prompt framing is A/B-PROVEN insufficient for this class (the "FROZEN CONTRACT,
- * MUST NOT edit" instruction held 0/5 unguarded, ~1/5 with framing — the weak
- * local model ignores an explicit capitalized MUST-NOT most of the time). A
- * chmod-style physical deny holds 5/5 but makes the model THRASH on the bare
- * EACCES (1000+ futile re-attempts observed) — unacceptable on the enforce child,
- * which runs UNGUARDED (no wall-clock timeout). pi itself has no path-level edit
- * interception (only tool-NAME allow/deny), so the achievable, thrash-free,
- * stack-agnostic realization of a tool-layer deny is this: let the pass edit
- * freely, then deterministically UNDO any frozen-path change it made before those
- * edits can be committed. The violating write never lands in a commit, regardless
- * of what the model intended — no model in the loop, same discipline as
- * git-state-guard.
+ * A tool-layer deny is not available. pi 0.84.4 offers `--tools` and
+ * `--exclude-tools`, both allow/deny by tool NAME; no flag scopes an edit to a
+ * path. A chmod-style physical deny would leave the child thrashing on a bare
+ * EACCES, and the enforce child has NO WALL CLOCK to stop it — the `gate` row of
+ * WORKER_PROFILES sets `worker-timeout` to `{timeoutMs: 0}`, leaving only a
+ * per-command watchdog and a stream watchdog.
  *
- * Everything degrades to a no-op when the spec froze nothing (a single-`/task`
- * run, or a spec with no `Do NOT modify` line naming a path → no frozen paths →
- * nothing snapshotted, nothing reverted) and on any git error. Pure git shape,
- * zero stack assumptions — a frozen path exists for a CLI, a library, a script
- * collection exactly as for a web app.
+ * So the achievable deny is after the fact: let the pass edit freely, then
+ * deterministically UNDO any frozen-path change before those edits can be
+ * committed. No model is in the loop, the same discipline as git-state-guard.
+ *
+ * Everything degrades to a no-op when the spec froze nothing — a single-`/task`
+ * run, or a spec with no `Do NOT modify` line naming a path — and on any git
+ * error. Pure git shape, zero stack assumptions: a frozen path exists for a CLI,
+ * a library or a script collection exactly as for a web app.
  */
 import { extractProhibitions } from './prohibition-probe.js';
 /**
  * The concrete paths the spec forbids modifying, normalized and de-duplicated —
- * the SAME extraction the verify prohibition-probe and the accept-debt ledger
- * consume, so "frozen" means one thing across the gates. Empty when the spec is
- * null or names no path-like token on a modification-ban line: the guard is then a
- * no-op by construction.
+ * `extractProhibitions`, the same extraction the verify prohibition probe
+ * (gate-deps.ts) and the compose-time conflict detector (frozen-conflict.ts)
+ * consume, so "frozen" means one thing across the gates.
+ *
+ * Normalisation strips a leading `./` and a trailing `/`: measured, a spec
+ * banning `` `./src/a.ts` `` and `` `src/b/` `` yields `src/a.ts` and `src/b`.
+ * A null spec, or one with no modification-ban line naming a path, yields an
+ * empty list and the guard is a no-op by construction.
  */
 export function frozenPathsFromSpec(spec) {
     if (!spec)
@@ -50,12 +50,13 @@ export function frozenPathsFromSpec(spec) {
 }
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 /**
- * Does this prose/tool-output text NAME the given path? Word-bounded on both
- * sides so `tsconfig.json` matches `` `tsconfig.json` ``, `(tsconfig.json:18)`
- * and a bare mention, but never `foo.tsconfig.json`, `config/tsconfig.json`
- * (a different file) or `tsconfig.json5`/`tsconfig.json.bak`. Shared by the
- * compose-time unsatisfiable-pair detector (frozen-conflict.ts) and lint-fix's
- * non-convergence trace, so "the text names a frozen path" means one thing.
+ * Does this prose or tool-output text NAME the given path? Word-bounded on both
+ * sides. Measured against `tsconfig.json`: `` `tsconfig.json` ``,
+ * `(tsconfig.json:18)` and a bare mention all match; `foo.tsconfig.json`,
+ * `config/tsconfig.json` (a different file), `tsconfig.json5` and
+ * `tsconfig.json.bak` all do not. Shared by the compose-time unsatisfiable-pair
+ * detector (frozen-conflict.ts) and lint-fix's non-convergence trace, so "the
+ * text names a frozen path" means one thing.
  */
 export function pathNamedIn(text, path) {
     const p = path.replace(/^\.\//, '').replace(/\/+$/, '');
@@ -69,6 +70,10 @@ export function pathNamedIn(text, path) {
  * anything must be reverted at all. A rename line (`R  old -> new`) yields the NEW
  * path — the side that carries the child's write. Deterministic and pure so the
  * parsing is unit-tested without a real repo.
+ *
+ * Every shape below was taken from real `git status --porcelain` output, not
+ * assumed: ` M path`, ` D path`, `?? path`, `R  old -> new`, and a path
+ * containing a space, which git emits wrapped in double quotes.
  */
 export function parseChangedFrozenFiles(porcelain) {
     const out = [];
@@ -104,10 +109,22 @@ export function parseChangedFrozenFiles(porcelain) {
  * Runs AFTER the task's own work is committed (HEAD), so "restore to HEAD" keeps
  * the verified task's version of the frozen file and discards ONLY the gate
  * child's edit on top of it — the task's own frozen-path edits, if any, are a
- * separate concern the verify prohibition-probe surfaces. `git checkout HEAD`
- * covers modified/deleted tracked files under each pathspec; `git clean` removes
- * any untracked file the pass created under a frozen directory. Both are scoped to
- * the frozen pathspec, so nothing else in the tree is touched.
+ * separate concern the verify prohibition probe surfaces. `git checkout -f HEAD`
+ * covers modified and deleted tracked files under each pathspec; `git clean -fdq`
+ * removes untracked files the pass created under a frozen directory. Both are
+ * scoped to the frozen pathspec.
+ *
+ * Run against a real repo with one frozen directory and one free one: a modified
+ * file came back to its HEAD content, a deleted file came back, and two untracked
+ * creations (one with a space in its name) were removed, while an edit to a file
+ * OUTSIDE the pathspec survived untouched.
+ *
+ * ONE CASE IS NOT FULLY UNDONE: a rename already STAGED in the index. `git mv`
+ * inside the frozen directory leaves `frozen/new.txt` present and staged after
+ * both commands, because checkout cannot restore a path HEAD does not contain and
+ * clean skips tracked files — while this function still reports it as reverted.
+ * An ordinary edit-tool rename is a delete plus an untracked create, and that IS
+ * fully undone; staging requires git, which the enforce child does not have.
  *
  * Best-effort: an empty frozen list, a non-git tree, or any git error yields an
  * empty result — the guard must never break the gate on a project it cannot reason