@mjasnikovs/pi-task 0.18.15 → 0.18.17

package/dist/task/decompose-fidelity.js

@@ -0,0 +1,132 @@
+/**
+ * decompose-fidelity — verbatim fidelity of plan derivations (mx5 run 11, goal B).
+ *
+ * The failure this closes: the design's §12 milestone lines 2 and 4 end in
+ * "guards + tests" / "contact + tests"; the decomposed titles carried everything
+ * BUT the "+ tests" suffix. A title is ALL a per-task pipeline ever sees, so a
+ * silently dropped constraint fragment vanishes from the whole run — the dropped
+ * tests were exactly the instrument that would have caught the shipped 404 bug.
+ * Decompose paraphrases freely and NOTHING compared a title to the spec line it
+ * derives from.
+ *
+ * Mechanism (contracts.ts pattern, applied to decompose itself): the decompose
+ * prompt asks each task line to cite its origin as a trailing
+ * `[source: "<verbatim spec line>"]`. The host then:
+ *   1. GROUNDS the quote — a citation that is not a (whitespace/case-normalised)
+ *      substring of the source doc is fabricated and is stripped, never trusted;
+ *   2. deterministically detects DROPPED ADDITIVE FRAGMENTS: the `+`-joined
+ *      trailing constraints of the cited line ("… + tests") whose words are
+ *      absent from the title;
+ *   3. RE-ATTACHES the missing fragments to the title verbatim.
+ *
+ * Scope is deliberately the additive-suffix class (`+`-joined fragments): those
+ * are constraints by construction, so re-attachment can never inject noise that
+ * the cited line doesn't demand — worst case is redundancy with what the title
+ * already says, never fabrication. Whole-line paraphrase drift is NOT judged here
+ * (a title is a paraphrase by design); requirement-level coverage owns that.
+ * No similarity thresholds anywhere: grounding is exact normalised substring,
+ * presence is exact word membership (with a singular/plural `s` allowance).
+ */
+import { normalise } from './contracts.js';
+/** Trailing `[source: "…"]` clause a decompose line may carry (prompt asks for it last). */
+const SOURCE_RE = /\s*\[source:\s*"(.+)"\s*\]\s*$/i;
+/** Split a decompose title into its base and its GROUNDED source citation.
+ *  An absent clause yields no source; a fabricated (ungrounded) one is stripped
+ *  and dropped — exactly like keepGroundedContracts rejects a paraphrased quote. */
+export function extractTitleSource(title, sourceDoc) {
+    const m = SOURCE_RE.exec(title);
+    if (!m)
+        return { base: title.trim() };
+    const base = title.slice(0, m.index).trim();
+    const quote = m[1].trim();
+    if (quote.length === 0 || !normalise(sourceDoc).includes(normalise(quote))) {
+        return { base };
+    }
+    return { base, source: quote };
+}
+/** Word tokens for presence checks: alphanumeric runs, lowercased. */
+function words(s) {
+    return s.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+/** Is every word of `fragment` present in `titleWords`? A bare trailing `s`
+ *  difference (test/tests) does not count as absence — a rule, not a threshold. */
+function fragmentPresent(fragment, titleWords) {
+    return words(fragment).every(w => {
+        if (titleWords.has(w))
+            return true;
+        if (w.endsWith('s') && titleWords.has(w.slice(0, -1)))
+            return true;
+        return titleWords.has(w + 's');
+    });
+}
+/**
+ * The `+`-joined trailing constraint fragments of `sourceLine` whose words are
+ * absent from `title`. "2. **Auth** — sessions, login/logout/me, guards + tests."
+ * yields the fragment "tests"; a title that never mentions tests gets it back.
+ * Fragments before the first `+` are the task's body — a title paraphrases those
+ * freely and they are never judged here. A `+`-part is further split on commas
+ * ("+ Tailwind v4 tokens, nav, router" is three constraints), so a title missing
+ * one of them gets ONLY that one restored, not the whole phrase (measured live:
+ * whole-phrase restoration re-attached text the title already carried).
+ */
+export function findDroppedPlusFragments(sourceLine, title) {
+    const parts = sourceLine.split('+');
+    if (parts.length < 2)
+        return [];
+    const titleWords = new Set(words(title));
+    const missing = [];
+    for (const raw of parts.slice(1)) {
+        for (const sub of raw.split(',')) {
+            // A fragment runs to the next `+`/comma; strip trailing sentence
+            // punctuation and markdown emphasis so "tests.**" compares as "tests".
+            const fragment = sub
+                .replace(/[*_`]/g, '')
+                .replace(/[.,;:!?)\]]+\s*$/, '')
+                .trim();
+            if (fragment.length === 0)
+                continue;
+            if (words(fragment).length === 0)
+                continue;
+            if (!fragmentPresent(fragment, titleWords))
+                missing.push(fragment);
+        }
+    }
+    return missing;
+}
+/**
+ * Reconcile decompose output against the source doc: ground each citation, strip
+ * the clause (its job ends here), and re-attach any dropped `+`-fragments to the
+ * title verbatim so downstream refine/compose — which see ONLY the title — get
+ * the constraint back. Titles without a citation pass through unchanged, so a
+ * model that never cites degrades to exactly the old behavior.
+ */
+export function reconcileTitleSources(titles, sourceDoc) {
+    const out = [];
+    const restored = [];
+    let sourced = 0;
+    for (let i = 0; i < titles.length; i++) {
+        const { base, source } = extractTitleSource(titles[i], sourceDoc);
+        if (source === undefined) {
+            out.push(base);
+            continue;
+        }
+        sourced++;
+        const missing = findDroppedPlusFragments(source, base);
+        if (missing.length === 0) {
+            out.push(base);
+            continue;
+        }
+        restored.push({ index: i, fragments: missing, source });
+        out.push(`${base} — MUST also cover (restored from its spec line): ${missing.join(', ')}`);
+    }
+    return { titles: out, restored, sourced };
+}
+/** The decompose-prompt rule that makes titles citable (the belt half; the host
+ *  grounding + restoration above is the lever). Kept here so prompt and parser
+ *  can't drift apart. */
+export const DECOMPOSE_SOURCE_RULE = '- When a task derives from a specific line of the feature/spec (a milestone, a'
+    + ' bullet, a requirement sentence), END that task\'s line with [source: "<that'
+    + ' line copied VERBATIM>"]. Copy exactly — a paraphrased or invented quote is'
+    + ' discarded host-side. Put the [source: …] clause after any [decisions: …]'
+    + ' clause. When the cited line carries additive constraints ("+ tests",'
+    + ' "+ docs"), those are PART of the task — keep them in the title itself.';

package/dist/task/final-gate-fix.d.ts

@@ -1,3 +1,4 @@
+import { type TreeChangeSummary } from './write-guard.js';
 /** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
  *  failing command (and the project's own tooling), not to mutate git state. */
 export declare const FINAL_FIX_TOOLS = "read,edit,bash";
@@ -79,13 +80,31 @@ export interface FinalFixDeps {
     /** Labels of every currently-discoverable gate command (static + integration),
      *  for the shrink guard. Pure discovery — nothing is executed. */
     discoverLabels: (cwd: string) => string[];
-    /** Discard the fix child's working-tree edits (shrink-guard trip only). Absent
+    /** Discard the fix child's working-tree edits (guard trips only). Absent
      *  → the violation is still rejected, edits are left for inspection. */
     discard?: (cwd: string) => Promise<void>;
+    /** The fix child's tree changes (`git status --porcelain` shape) — diff capture
+     *  for the log and the deletion guard's input. The tree was clean before the
+     *  child ran (every task committed), so status IS the child's work. */
+    treeChanges?: () => Promise<TreeChangeSummary>;
+    /** The union of every task spec's frozen (Do-NOT-modify) paths — the whole-run
+     *  write-deny set, since this child works across all slices at once. */
+    frozenPaths?: () => Promise<string[]>;
+    /** Restore the given frozen paths to HEAD; returns the files actually reverted
+     *  (same mechanical deny the enforce pass carries — see frozen-path-guard.ts). */
+    revertFrozen?: (paths: string[]) => Promise<string[]>;
+    /** Deterministic probe scan over the child's ADDED lines (probe-gaming, F6):
+     *  a fix written to game a check rather than meet it rejects the attempt —
+     *  run 11's autofix replaced the typed client with a hand-written contract
+     *  copy to green the lint. Findings are verbatim offending lines. */
+    probeScan?: () => Promise<string[]>;
+    /** Write a timestamped line to the gate debug log (guard events). */
+    log?: (msg: string) => void;
 }
 /**
- * Run one bounded final-gate fix attempt: snapshot discovery → child → shrink
- * guard → gate re-run. Never throws for an outcome; only a user cancel inside
+ * Run one bounded final-gate fix attempt: snapshot discovery → child → write-guard
+ * stack (diff capture → frozen-path revert → deletion guard → shrink guard → probe
+ * scan) → gate re-run. Never throws for an outcome; only a user cancel inside
  * runChild propagates (the caller's USER_CANCELLED path handles it).
  */
 export declare function runFinalGateAutofix(deps: FinalFixDeps): Promise<FinalFixResult>;

package/dist/task/final-gate-fix.js

@@ -25,8 +25,26 @@
  * the child runs; any previously-discovered command that is no longer
  * discoverable afterwards rejects the attempt and discards its edits. A fix may
  * change what a command DOES, never make it disappear.
+ *
+ * WRITE-GUARD STACK (mx5 run 11): this child was added after the run-8 guard
+ * generation and inherited none of them — it ran `rm` on a sibling task's
+ * verified deliverable to satisfy a recorded debt claim and hand-copied a pinned
+ * contract to green the lint, with free bash and no trace. Every attempt now
+ * runs, deterministically and in order: frozen-path revert (when a freeze set is
+ * wired — see below) → deletion guard (a tracked file deleted without relocation
+ * rejects the attempt) → shrink guard (above) → probe-gaming scan over the added
+ * lines (a fix that SAYS it games a check rejects the attempt). Diff capture for
+ * every write-capable gate child lives at the gate-deps seam, keyed on the
+ * child's TOOLS, so the next write-capable kind cannot run invisibly either.
+ *
+ * The frozen-path deny is implemented but NOT wired by gate-deps: per-task
+ * frozen fences are task-SCOPED (they fence a task off a sibling's territory),
+ * and the measured union over the run-11 specs would have reverted the one
+ * legitimate whole-repo fix that run needed (migrate.ts — frozen by its own
+ * producing task). It activates only when a run-GLOBAL freeze source exists.
  */
 import { USER_CANCELLED } from './child-runner.js';
+import { findForbiddenDeletions } from './write-guard.js';
 /** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
  *  failing command (and the project's own tooling), not to mutate git state. */
 export const FINAL_FIX_TOOLS = 'read,edit,bash';
@@ -100,6 +118,10 @@ export function buildFinalFixPrompt(failReason) {
         '     command pass. Relocating or scoping a file the runner was never meant',
         '     to pick up (per the project’s own config) is a legitimate fix;',
         '     deleting it or marking it skipped is not.',
+        '   - Do NOT delete tracked files at all. Every tracked file is a completed',
+        '     task’s committed deliverable; a deletion is detected and the whole fix',
+        '     is rejected. A legitimate relocation keeps the file (same file name)',
+        '     elsewhere in the tree.',
         '   - Do NOT remove or rename the project’s own commands (its test/build/',
         '     lint scripts or targets). Making the gate unable to find the command',
         '     is detected and the whole fix is rejected.',
@@ -135,8 +157,9 @@ export function parseFinalFixMarker(text) {
     return { blocked: false, note: last[2].trim() || undefined };
 }
 /**
- * Run one bounded final-gate fix attempt: snapshot discovery → child → shrink
- * guard → gate re-run. Never throws for an outcome; only a user cancel inside
+ * Run one bounded final-gate fix attempt: snapshot discovery → child → write-guard
+ * stack (diff capture → frozen-path revert → deletion guard → shrink guard → probe
+ * scan) → gate re-run. Never throws for an outcome; only a user cancel inside
  * runChild propagates (the caller's USER_CANCELLED path handles it).
  */
 export async function runFinalGateAutofix(deps) {
@@ -151,6 +174,38 @@ export async function runFinalGateAutofix(deps) {
             throw err;
         return { ok: false, reason: `fix child failed: ${msg}` };
     }
+    const rejected = (what) => ({
+        ok: false,
+        reason: `${what} — edits ${deps.discard ? 'discarded' : 'REJECTED but left in the tree (no discard available)'}`
+    });
+    // (Diff capture — what the pass changed, durably — happens at the gate-deps
+    // seam for every write-capable child; here only the guards act on it.)
+    // FROZEN-PATH WRITE-DENY: undo the child's edits to any path a task spec
+    // froze, before anything downstream can act on them — same mechanical deny
+    // the enforce pass carries (prompt framing is A/B-proven insufficient).
+    // Non-fatal: the rest of the fix survives, only the frozen edits are undone.
+    if (deps.frozenPaths && deps.revertFrozen) {
+        const frozen = await deps.frozenPaths();
+        if (frozen.length > 0) {
+            const reverted = await deps.revertFrozen(frozen);
+            if (reverted.length > 0) {
+                deps.log?.(`final-fix FROZEN-PATH GUARD — reverted spec-frozen file(s) the fix pass modified: ${reverted.join(', ')}`);
+            }
+        }
+    }
+    // DELETION GUARD (post-revert state): a tracked file the pass deleted without
+    // relocating it is a committed deliverable destroyed — reject the attempt.
+    if (deps.treeChanges) {
+        const gone = findForbiddenDeletions(await deps.treeChanges());
+        if (gone.length > 0) {
+            if (deps.discard)
+                await deps.discard(deps.cwd);
+            const r = rejected(`fix pass DELETED tracked file(s) (${gone.join(', ')}) — a completed task's `
+                + `committed deliverable is not the fix child's to remove`);
+            deps.log?.(`final-fix DELETION GUARD — ${r.reason}`);
+            return r;
+        }
+    }
     // SHRINK GUARD: every gate command discoverable before the fix must still be
     // discoverable after it. A vanished command means the child "fixed" the gate
     // by removing the check — reject and (when possible) discard the edits.
@@ -159,11 +214,21 @@ export async function runFinalGateAutofix(deps) {
     if (vanished.length > 0) {
         if (deps.discard)
             await deps.discard(deps.cwd);
-        return {
-            ok: false,
-            reason: `fix pass removed the gate's own command(s) (${vanished.join(', ')}) — `
-                + `edits ${deps.discard ? 'discarded' : 'REJECTED but left in the tree (no discard available)'}`
-        };
+        return rejected(`fix pass removed the gate's own command(s) (${vanished.join(', ')})`);
+    }
+    // PROBE SCAN (F6): added lines whose stated purpose is to make a check pass
+    // rather than meet the requirement reject the attempt — there is no verify
+    // child downstream of this pass to judge the finding, and the probe is
+    // FP-measured at 1 true hit in 50,735 added lines on the real corpus.
+    if (deps.probeScan) {
+        const findings = await deps.probeScan();
+        if (findings.length > 0) {
+            if (deps.discard)
+                await deps.discard(deps.cwd);
+            const r = rejected(`fix pass added CHECK-GAMING code (${findings.slice(0, 2).join('; ').slice(0, 300)})`);
+            deps.log?.(`final-fix PROBE-GAMING GUARD — ${r.reason}`);
+            return r;
+        }
     }
     const marker = parseFinalFixMarker(text);
     if (marker.blocked) {

package/dist/task/final-gate.d.ts

@@ -1,10 +1,24 @@
 import { type HealthCommand } from './repo-health-check.js';
 import { type AcceptDebt } from './accept-debt.js';
+import { type RenderOutcome } from './render-check.js';
 export interface FinalGateOutcome {
     /** true → statics and every runnable integration command passed (or nothing to run). */
     ok: boolean;
-    /** On a fail: the exact command, its exit code, and the tail of its output. */
+    /**
+     * On a fail: the exact command, its exit code, and the tail of its output — the
+     * MECHANICAL failure only. The accept-debt note is deliberately NOT folded in
+     * here (mx5 run 11): this string seeds the final-gate AUTOFIX child's prompt,
+     * and a debt included there is read as an instruction — the run-11 fix child
+     * `rm`'d a sibling task's verified deliverable to satisfy a recorded claim. The
+     * child cannot act on text it never receives; debts travel in `debtNote`.
+     */
     reason: string;
+    /**
+     * Human-facing suffix listing the still-open accepted-defect claims (see
+     * buildAcceptDebtNote) — for the picker question and the trail, NEVER for the
+     * autofix seed. Absent when nothing is open.
+     */
+    debtNote?: string;
     /**
      * ACCEPT-despite-verify-FAIL debts still open at run end (mx5 run 4 B3 / run 8
      * TASK_0012): tasks the user blessed as-is despite a verify-FAIL that a
@@ -33,6 +47,9 @@ export declare function discoverLockfileChecks(cwd: string): HealthCommand[];
 export declare function discoverBootCommand(cwd: string): HealthCommand | null;
 type BootOutcome = {
     outcome: 'skip' | 'pass';
+    /** Set when the render check could not OBSERVE the served page (no browser,
+     *  undeterminable port) — surfaced by the gate as an UNOBSERVED warning. */
+    renderNote?: string;
 } | {
     outcome: 'fail';
     detail: string;
@@ -60,6 +77,20 @@ export interface BootDeps {
      * real socket; the default probes ss/lsof + pgid.
      */
     groupHasListener?: (pgid: number) => boolean;
+    /**
+     * The (lowest) TCP port a listener owned by process group `pgid` is bound to,
+     * or null when it cannot be determined. Feeds the render check's URL; injected
+     * for tests, default probes ss/lsof + pgid.
+     */
+    groupListeningPort?: (pgid: number) => number | null;
+    /**
+     * Load the served page once in a headless browser and judge the RENDERED DOM
+     * (mx5 runs 8/11: curl cannot execute JS, so a blank-mount app passed every
+     * gate). Runs only for a served app, against the live listener, before the
+     * boot child is killed. Absent → the boot check behaves exactly as before;
+     * the gate wires runRenderCheck by default for served apps.
+     */
+    renderProbe?: (url: string) => RenderOutcome;
 }
 /**
  * Does the finished run stand up a listening HTTP server? Deterministic, from the
@@ -101,6 +132,22 @@ export declare function runBootCheck(cwd: string, [bin, args]: HealthCommand, gr
  * gaming the gate, not fixing the defect.
  */
 export declare function discoverGateCommandLabels(cwd: string): string[];
+/**
+ * A non-zero exit whose output shows the EXTERNAL INFRASTRUCTURE a launch script
+ * talks to is absent HERE — a database/daemon that is not running or not
+ * installed — rather than a fault in the script itself. Applied ONLY to
+ * launch-contract scripts (a migrate/seed against no DB is an environment gap on
+ * this box; the same wording in a `test` run is a real failure the suite must own).
+ */
+export declare const INFRA_GAP_OUTPUT_RE: RegExp;
+/**
+ * The task whose commit INTRODUCED `rel` (oldest `--diff-filter=A` commit whose
+ * subject carries the pi-task `(TASK_nnnn)` suffix — both the task snapshot and the
+ * ENFORCE commit shapes match). Null when the file predates the run, was never
+ * committed, git is unavailable, or the adding commit is not a task commit — every
+ * unknown degrades to "no conflict claim".
+ */
+export declare function taskThatIntroduced(cwd: string, rel: string): string | null;
 /**
  * Run the final gate: static analysis first, then the lockfile consistency
  * checks, then the discovered integration commands, then one boot exercise of