@mjasnikovs/pi-task 0.17.11 → 0.17.12

package/dist/task/gate-deps.js

@@ -15,7 +15,7 @@
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
-import { tasksDir, readTaskFile } from './task-io.js';
+import { tasksDir, readTaskFile, appendGateRecord } from './task-io.js';
 import { gitCommitAll, gitDropLastCommit } from './auto-commit.js';
 import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
@@ -96,6 +96,9 @@ export function buildGateDeps(params) {
     };
     return {
         runTask,
+        // Durable per-task gate trail: every verdict/decision lands in the task
+        // file's `## gates` section so gate behavior is auditable from artifacts.
+        record: (cwd2, taskId, line) => appendGateRecord(cwd2, taskId, line),
         commit: (cwd2, message) => getConfig().autoCommit ?
             gitCommitAll(cwd2, message, signal)
             : Promise.resolve({ committed: false, reason: 'auto-commit disabled' }),

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

@@ -77,6 +77,16 @@ export interface GateDeps {
      * skips the revert and warns.
      */
     revert?: (cwd: string) => Promise<void>;
+    /**
+     * Append one line to the task's durable gate trail (`## gates` in the task
+     * file). Every gate outcome — each verify verdict, the user's FAIL resolution,
+     * the commit result, enforce mode + verdict, the differential guard's decision —
+     * is recorded so the sequence is auditable from artifacts alone (the mx5 audit
+     * could not tell WHY 10 of 18 tasks show no enforce run: verdicts lived only in
+     * terminal notifies). Best-effort: absent in tests → skipped; failures are
+     * swallowed by the implementation, never by this sequence.
+     */
+    record?: (cwd: string, taskId: string, line: string) => Promise<void>;
 }
 /** Inputs the sequence needs that vary per caller. */
 export interface GateParams {

package/dist/task/task-gates.js

@@ -34,6 +34,21 @@ export async function askVerifyResolution(ctx, title, failReason, rec) {
  */
 export async function runGatesForTask(ctxIn, deps, p) {
     let active = ctxIn;
+    // Durable per-task gate trail — every outcome below is also appended to the
+    // task file so the sequence is auditable from artifacts alone. Best-effort.
+    const rec = async (line) => {
+        try {
+            await deps.record?.(p.cwd, p.taskId, line);
+        }
+        catch {
+            // recording must never break the gate sequence
+        }
+    };
+    const verdictLine = (v) => v.ok ?
+        v.reason ?
+            `verify: PASS (${v.reason})`
+            : 'verify: PASS'
+        : `verify: FAIL — ${v.reason ?? 'did not verify'}`;
     // GATE: actually RUN the task's verification against the just-finished work
     // BEFORE it is checked off or committed. Whether this produced a GENUINE clean
     // pass (a real signal ran and the work met it) also decides how the enforce pass
@@ -44,24 +59,29 @@ export async function runGatesForTask(ctxIn, deps, p) {
     if (deps.verify) {
         active.ui.notify(`${p.tag}: verifying "${p.title}"…`, 'info');
         let verified = await deps.verify(active, p.cwd, p.title, p.taskId);
+        await rec(verdictLine(verified));
         // A FAIL no longer dead-stops: offer the boxed AUTOFIX / ACCEPT / dismiss
         // picker. The USER always decides; AUTOFIX loops straight back to the gate
         // as many times as they keep choosing it (no attempt cap).
         while (!verified.ok) {
             const failReason = verified.reason ?? 'did not verify';
-            const rec = deps.recommend ?
+            const recOutcome = deps.recommend ?
                 await deps.recommend(active, p.cwd, p.title, p.taskId, failReason)
                 : { recommend: 'autofix', rationale: failReason };
-            const choice = await askVerifyResolution(active, p.title, failReason, rec);
+            await rec(`resolution: recommended ${recOutcome.recommend.toUpperCase()}`);
+            const choice = await askVerifyResolution(active, p.title, failReason, recOutcome);
             if (choice.action === 'cancel') {
+                await rec('resolution: user dismissed the verify-FAIL picker — paused');
                 return { kind: 'paused', ctx: active, reason: failReason };
             }
             if (choice.action === 'accept') {
+                await rec('resolution: user ACCEPTED the work despite verify FAIL');
                 active.ui.notify(`${p.tag}: accepted "${p.title}" despite verify FAIL (${failReason.slice(0, 120)}) — proceeding.`, 'warning');
                 break;
             }
             // AUTOFIX: re-run the implementation turn with the failure (and any typed
             // guidance) prepended as a RE-ATTEMPT banner, then re-verify.
+            await rec('resolution: user chose AUTOFIX — re-running the implementation turn');
             active.ui.notify(`${p.tag}: autofixing "${p.title}"…`, 'info');
             const fixInstruction = choice.guidance ? `${failReason}\n\nUser guidance: ${choice.guidance}` : failReason;
             const fixRes = await deps.runTask(active, p.cwd, p.title, {
@@ -78,6 +98,7 @@ export async function runGatesForTask(ctxIn, deps, p) {
                 return { kind: 'failed', ctx: active, reason: fixRes.reason };
             // Resume reuses the same inner task id, so p.taskId is stable.
             verified = await deps.verify(active, p.cwd, p.title, p.taskId);
+            await rec(verdictLine(verified));
         }
         // Loop exited because the work verified OR the user accepted the artifact. A
         // genuine clean pass is ok===true with NO reason; a no-op pass or an
@@ -91,9 +112,11 @@ export async function runGatesForTask(ctxIn, deps, p) {
     // so a passing task is durably recorded no matter what enforcement later finds.
     const commit = await deps.commit(p.cwd, `task: ${p.title} (${p.taskId})`);
     if (commit.committed) {
+        await rec('commit: task snapshot committed');
         active.ui.notify(`${p.tag}: committed "${p.title}".`, 'info');
     }
     else {
+        await rec(`commit: skipped (${commit.reason ?? 'unknown'})`);
         active.ui.notify(`${p.tag}: not committed (${commit.reason ?? 'unknown'}) — continuing.`, 'warning');
     }
     // With the task committed, hold its work to AGENTS.md / CLAUDE.md — but as a step
@@ -106,6 +129,7 @@ export async function runGatesForTask(ctxIn, deps, p) {
             `${p.tag}: enforcing AGENTS.md/CLAUDE.md on "${p.title}"…`
             : `${p.tag}: reviewing "${p.title}" against AGENTS.md/CLAUDE.md (no verify signal — report only)…`, 'info');
         const verdict = await deps.enforce(active, p.cwd, p.title, mode);
+        await rec(`enforce(${mode}): ${verdict.ok ? `clean${verdict.reason ? ` (${verdict.reason})` : ''}` : (verdict.reason ?? 'not clean')}`);
         if (!verdict.ok) {
             active.ui.notify(`${p.tag}: guideline ${mode === 'edit' ? 'enforcement' : 'review'} on "${p.title}" — ${verdict.reason ?? 'not clean'} — continuing.`, 'warning');
         }
@@ -122,14 +146,24 @@ export async function runGatesForTask(ctxIn, deps, p) {
                 if (!after.ok) {
                     if (deps.revert)
                         await deps.revert(p.cwd);
+                    await rec(`enforce: fixes committed but re-verify FAILED (${(after.reason ?? 'now fails').slice(0, 200)}) — ${deps.revert ? 'REVERTED' : 'left in place (no revert available)'}`);
                     active.ui.notify(`${p.tag}: guideline fixes regressed verification on "${p.title}" (${(after.reason ?? 'now fails').slice(0, 120)}) — ${deps.revert ? 'reverted them, kept the verified work' : 'left in place (no revert available)'}.`, 'warning');
                 }
                 else {
+                    await rec('enforce: fixes committed — re-verify PASS, kept');
                     active.ui.notify(`${p.tag}: committed guideline fixes for "${p.title}".`, 'info');
                 }
             }
+            else {
+                await rec('enforce(edit): no fixes to commit');
+            }
         }
         // 'flag' mode makes no edits — nothing to commit or revert.
     }
+    else if (deps.enforce) {
+        // deps.enforce wired but nothing was committed this round — record the skip
+        // so a missing enforce run is explainable from the trail (mx5 audit gap).
+        await rec('enforce: skipped (nothing committed this round)');
+    }
     return { kind: 'done', ctx: active };
 }

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

@@ -21,5 +21,14 @@ export declare function writeTaskFile(cwd: string, fm: TaskFrontMatter, body: st
 export declare function updateTaskFrontMatter(cwd: string, id: string, patch: Partial<TaskFrontMatter>): Promise<void>;
 export declare function readSection(cwd: string, id: string, heading: string): Promise<string | null>;
 export declare function setTaskSection(cwd: string, id: string, heading: string, content: string): Promise<void>;
+/**
+ * Append one timestamped line to the task's `## gates` section — the durable
+ * per-task trail of gate outcomes (verify verdicts, enforce mode/verdict, commit
+ * results). Motivated by the mx5 audit: verdict text lived only in memory and
+ * terminal notifies, so "did enforce run for this task, and in which mode?" was
+ * unanswerable from artifacts. Best-effort by design: a failure to record must
+ * never break the gate sequence, so all errors are swallowed.
+ */
+export declare function appendGateRecord(cwd: string, id: string, line: string): Promise<void>;
 /** Remove a section (heading + body) if present; a no-op when it's absent. */
 export declare function removeTaskSection(cwd: string, id: string, heading: string): Promise<void>;

package/dist/task/task-io.js

@@ -112,6 +112,25 @@ export async function setTaskSection(cwd, id, heading, content) {
     }
     await writeTaskFile(cwd, { ...frontMatter, updated_at: new Date().toISOString() }, next);
 }
+/**
+ * Append one timestamped line to the task's `## gates` section — the durable
+ * per-task trail of gate outcomes (verify verdicts, enforce mode/verdict, commit
+ * results). Motivated by the mx5 audit: verdict text lived only in memory and
+ * terminal notifies, so "did enforce run for this task, and in which mode?" was
+ * unanswerable from artifacts. Best-effort by design: a failure to record must
+ * never break the gate sequence, so all errors are swallowed.
+ */
+export async function appendGateRecord(cwd, id, line) {
+    try {
+        const stamp = new Date().toISOString();
+        const entry = `- ${stamp} ${line.replace(/\s*\n\s*/g, ' ').trim()}`;
+        const existing = await readSection(cwd, id, 'gates');
+        await setTaskSection(cwd, id, 'gates', existing ? `${existing}\n${entry}` : entry);
+    }
+    catch {
+        // Recording is observability, not control flow — never propagate.
+    }
+}
 /** Remove a section (heading + body) if present; a no-op when it's absent. */
 export async function removeTaskSection(cwd, id, heading) {
     const { frontMatter, body } = await readTaskFile(cwd, id);

package/dist/task/verify-work.js

@@ -39,6 +39,20 @@
  * genuinely-broken shipped build FAILs 3/3, and a genuine external-service gap — which
  * the OLD prompt wrongly blamed on the code 3/3 — now correctly PASSes 3/3.
  *
+ * The sibling failure class is GREP-THEATER (mx5 run 2, TASK_0002): the composed VERIFY
+ * block was grep-only, so the child "verified" a schema.sql containing INVALID SQL by
+ * grepping for its own broken text — while a live PostgreSQL sat reachable in the same
+ * container, never touched. The prompt now (a) says a grep-only VERIFY block does not cap
+ * the obligation to execute/apply an executable artifact, and (b) requires PROBING a
+ * declared external service before invoking the absent-service exception — reachable ⇒
+ * the real verification must run against it. A/B on the faithful fixture (invalid
+ * `generate always as` schema, grep-only VERIFY, unadvertised trust-auth PostgreSQL on
+ * the default port, DATABASE_URL unset — exactly the mx5 shape): old prompt false-PASSed
+ * 4/5; new prompt FAILed 5/5, each naming the real syntax error. Guards: explicit-URL
+ * variant old 5/5 / new 5/5 correct-FAIL (no regression), valid schema 3/3 PASS (no
+ * paranoia), unreachable-DB 2/3 PASS via the env-gap exception + 1 conservative FAIL
+ * that still named the genuine SQL defect (safe direction — only false-PASS trashes work).
+ *
  * It runs as a GATE right after the implementation turn, BEFORE the task is
  * checked off or committed. A FAIL stops the /task-auto run exactly like an
  * implementation failure: the task is left unchecked and uncommitted so
@@ -138,18 +152,31 @@ export function buildVerifyPrompt(spec) {
         '3. Presence of a token / directive / string in a SOURCE file is NOT verification.',
         '   Judge the produced artifact and the real runtime behavior. A raw build directive',
         '   that SURVIVES into the built output means the build never ran — that is a FAIL.',
+        "   The spec's VERIFY block does not cap this obligation: if that block only greps or",
+        '   reads source files but the deliverable can be EXECUTED or APPLIED on this machine',
+        '   (a script, a schema, a server, a config a tool can load), you must ALSO execute or',
+        '   apply it and judge the real result. Grep-only checks passing while the artifact was',
+        '   never executed is NOT a PASS — a static match cannot prove an artifact works, only',
+        '   running it can.',
         '',
         '4. Treat the ACCEPTANCE criteria as the bar. If a command fails, or its real output',
         '   contradicts an ACCEPTANCE criterion, the work has NOT verified.',
         '',
         '5. The ONLY thing you may assume is already provided is a genuinely EXTERNAL running',
         '   service or network resource (a database server, an API host) that the project',
-        '   documents as a prerequisite. If a command fails purely because such an external',
-        '   service is ABSENT from this machine — and NOT because the project misconfigures',
-        '   how it connects — note that as an environment gap and judge the rest; do not fail',
-        '   the code for it. But a command that fails because of how the PROJECT ITSELF is',
-        '   wired (config it owns but does not load, a wrong default, a command that cannot',
-        '   run unaided) is a defect, not an environment gap.',
+        '   documents as a prerequisite. Before you rely on that assumption, PROBE for the',
+        '   service with a cheap real check using the connection details the project/spec',
+        '   already declares (attempt the connection: pg_isready, a client one-liner, curl',
+        '   with a short timeout). If the probe shows the service IS reachable, the exception',
+        '   does NOT apply — you must run the real verification against it (apply the schema,',
+        '   run the suite, hit the endpoint) and judge the real result; falling back to static',
+        '   checks with the service available is NOT verification. Only if a command fails',
+        '   purely because such an external service is genuinely ABSENT from this machine —',
+        '   and NOT because the project misconfigures how it connects — note that as an',
+        '   environment gap and judge the rest; do not fail the code for it. But a command',
+        '   that fails because of how the PROJECT ITSELF is wired (config it owns but does',
+        '   not load, a wrong default, a command that cannot run unaided) is a defect, not an',
+        '   environment gap.',
         '',
         '6. If the spec legitimately has no runnable verification (a pure docs / config change',
         '   with nothing to build or run), validating it cleanly is a PASS.',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.17.11",
+    "version": "0.17.12",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",