@mjasnikovs/pi-task 0.14.22 → 0.15.1

package/dist/config/register.js

@@ -18,15 +18,15 @@ const ITEMS = [
         label: 'orientation',
         description: 'Pre-supply the project core (manifest, types, schema…) to the read-heavy research workers'
     },
-    {
-        id: 'enforceGuidelines',
-        label: 'enforce guidelines',
-        description: 'Before each /task-auto commit, re-check the work against AGENTS.md/CLAUDE.md and fix drift'
-    },
     {
         id: 'verifyWork',
         label: 'verify work',
-        description: "After each /task-auto task, RUN its spec's VERIFY block in the workspace and report a PASS/FAIL verdict"
+        description: "After each /task-auto task, RUN its spec's VERIFY block in the workspace and report a PASS/FAIL verdict (also the signal that lets 'enforce guidelines' fix safely)"
+    },
+    {
+        id: 'enforceGuidelines',
+        label: 'enforce guidelines',
+        description: "Check each /task-auto commit against AGENTS.md/CLAUDE.md. Needs 'verify work' to FIX drift (fixes are reverted if they regress verification); without it, only reports violations"
     }
 ];
 function makeTheme(theme) {

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

@@ -18,3 +18,22 @@ export interface CommitResult {
  * `{committed: false, reason}` so the caller can warn and keep going.
  */
 export declare function gitCommitAll(cwd: string, message: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<CommitResult>;
+/**
+ * Drop the last commit, restoring the tree to its parent — the differential
+ * guard's "revert" when an `'edit'` enforcement pass regressed the verified task
+ * commit. The enforcement fixes are committed first (as `ENFORCE GUIDELINES`);
+ * when re-running verification against that commit reports a regression, this
+ * `git reset --hard HEAD~1` throws the enforce commit away and brings back the
+ * verified task commit underneath it.
+ *
+ * `reset --hard` is safe here precisely because it runs right after the enforce
+ * commit: the working tree is clean (everything was just committed), so there is
+ * no unrelated uncommitted work for it to destroy. HEAD~1 is the verified task
+ * commit. The enforcement child runs `read,edit` with no `write`, so the dropped
+ * commit contains only its in-place source edits — nothing else to preserve.
+ *
+ * Best-effort and never throws: a git failure is swallowed (the caller has
+ * already decided to keep the verified work; a failed reset only leaves the
+ * enforce commit in place, which is surfaced as a warning).
+ */
+export declare function gitDropLastCommit(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<void>;

package/dist/task/auto-commit.js

@@ -54,3 +54,24 @@ export async function gitCommitAll(cwd, message, signal, spawnFn) {
     }
     return { committed: true };
 }
+/**
+ * Drop the last commit, restoring the tree to its parent — the differential
+ * guard's "revert" when an `'edit'` enforcement pass regressed the verified task
+ * commit. The enforcement fixes are committed first (as `ENFORCE GUIDELINES`);
+ * when re-running verification against that commit reports a regression, this
+ * `git reset --hard HEAD~1` throws the enforce commit away and brings back the
+ * verified task commit underneath it.
+ *
+ * `reset --hard` is safe here precisely because it runs right after the enforce
+ * commit: the working tree is clean (everything was just committed), so there is
+ * no unrelated uncommitted work for it to destroy. HEAD~1 is the verified task
+ * commit. The enforcement child runs `read,edit` with no `write`, so the dropped
+ * commit contains only its in-place source edits — nothing else to preserve.
+ *
+ * Best-effort and never throws: a git failure is swallowed (the caller has
+ * already decided to keep the verified work; a failed reset only leaves the
+ * enforce commit in place, which is surfaced as a warning).
+ */
+export async function gitDropLastCommit(cwd, signal, spawnFn) {
+    await git(cwd, ['reset', '--hard', 'HEAD~1'], signal, spawnFn);
+}

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

@@ -33,7 +33,14 @@ export interface AutoDeps {
      * each task runs in a fresh session, so the captured ctx is stale by the time
      * enforcement runs and using it for the loader widget throws "stale ctx".
      */
-    enforce?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string) => Promise<EnforceOutcome>;
+    enforce?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, 
+    /**
+     * `'edit'` (read,edit — fix in place) only when there is a clean
+     * verification signal to guard the edits against; otherwise `'flag'`
+     * (read-only, report don't fix). The loop picks the mode from whether the
+     * verify gate produced a genuine clean pass.
+     */
+    mode: 'edit' | 'flag') => Promise<EnforceOutcome>;
     /**
      * Verify the just-finished task's work by RUNNING its composed spec's VERIFY
      * block in the real workspace (a fresh child of the same local model, with a
@@ -53,6 +60,15 @@ export interface AutoDeps {
      * taskId (to read the spec) and the gate's failure reason.
      */
     recommend?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, taskId: string, failReason: string) => Promise<ResolutionOutcome>;
+    /**
+     * Discard the working-tree edits an `'edit'` enforcement pass made, restoring
+     * the verified task commit. The differential guard calls this when re-running
+     * verification AFTER enforcement reports a regression: the guideline fixes are
+     * thrown away and the verified implementation is kept. Optional: absent in
+     * tests; the loop then skips the revert (and warns). Scoped to exclude the
+     * .pi-tasks bookkeeping so task front matter is not rolled back.
+     */
+    revert?: (cwd: string) => Promise<void>;
 }
 /**
  * Expand any @file references in the feature text by appending each referenced

package/dist/task/auto-orchestrator.js

@@ -14,7 +14,7 @@ import { AUTO_CLARIFY_PROMPT, AUTO_DECOMPOSE_PROMPT } from './auto-prompts.js';
 import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './question-dedup.js';
 import { allocateAutoId, buildAutoBody, parseDecomposeList, parseTaskList, checkOffTask, stampTaskInProgress, findResumableAuto } from './auto-io.js';
 import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasksDir } from './task-io.js';
-import { gitCommitAll } from './auto-commit.js';
+import { gitCommitAll, gitDropLastCommit } from './auto-commit.js';
 import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { researchResolution, resolutionOptions, classifyResolutionAnswer } from './verify-resolution.js';
@@ -446,13 +446,15 @@ function defaultDeps(ctx, cwd, signal, title) {
         commit: (cwd2, message) => getConfig().autoCommit ?
             gitCommitAll(cwd2, message, signal)
             : Promise.resolve({ committed: false, reason: 'auto-commit disabled' }),
-        enforce: (enforceCtx, cwd2, taskTitle) => {
+        revert: cwd2 => gitDropLastCommit(cwd2, signal),
+        enforce: (enforceCtx, cwd2, taskTitle, mode) => {
             if (!getConfig().enforceGuidelines) {
                 return Promise.resolve({ ok: true, reason: 'disabled' });
             }
             return runGuidelineEnforcement({
                 cwd: cwd2,
                 signal,
+                mode,
                 // Run the worker child UNGUARDED: no loop detector, no wall-clock
                 // timeout. This pass's job is to rework files in place until every
                 // violation is fixed, and it legitimately reads and edits the same
@@ -721,6 +723,14 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             // /task-auto-resume re-runs it (rather than blessing broken work). Off
             // by default (deps.verify returns a disabled no-op) and a no-op when the
             // task has no composed spec to verify against.
+            //
+            // Whether this gate produced a GENUINE clean pass (a real signal ran
+            // and the work met it) also decides how the enforce pass below is
+            // allowed to behave: only a genuine pass gives a signal to revert
+            // against, so only then may enforce edit in place (see the enforce
+            // block). A no-op pass (no spec), a disabled gate, or a user
+            // accept-override leaves this false → enforce runs flag-only.
+            let verifyCleanPass = false;
             if (deps.verify) {
                 active.ui.notify(`${id}: verifying "${next.title}"…`, 'info');
                 let verified = await deps.verify(active, cwd, next.title, res.taskId);
@@ -781,6 +791,10 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 }
                 // Loop exited because the work verified OR the user accepted the
                 // artifact — either way fall through to check-off/commit/enforce.
+                // A genuine clean pass is ok===true with NO reason; a no-op pass
+                // ('no spec to verify') or an accept-override (verified.ok still
+                // false at break) does NOT count as a guardable signal.
+                verifyCleanPass = verified.ok && !verified.reason;
             }
             // res.ok === true means runner.run() completed, so res.taskId is the
             // allocated TASK_NNNN id (never empty here). checkOffTask tolerates an
@@ -799,29 +813,63 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 active.ui.notify(`${id}: not committed (${commit.reason ?? 'unknown'}) — continuing.`, 'warning');
             }
             // With the task committed, hold its work to the project's AGENTS.md /
-            // CLAUDE.md rules. Local models drift and skip those guidelines, so the
-            // enforcement pass re-reads THE LAST COMMIT's diff with the same local
-            // model (edit tools enabled) and fixes violations in place; those fixes
-            // are then committed SEPARATELY under an "ENFORCE GUIDELINES" commit so
-            // they form an independent, auditable diff on top of the task commit.
-            // A non-clean verdict only warns — the task commit already landed, so
-            // the run continues. Skipped when nothing was committed this round
-            // (autoCommit off or an empty commit): there is no "last commit" of this
-            // task's work to verify. (Also a no-op when the feature is off, when
-            // there are no guideline files, or in tests with no enforce dep.)
+            // CLAUDE.md rules — but as a step INSIDE the validation gate, never the
+            // blind post-commit write pass it used to be. A bare read,edit enforce
+            // pass trashes working code: A/B-proven, it degraded a clean build in
+            // 4/5 runs while declaring CLEAN. So enforcement is now gated by the
+            // verify signal:
+            //
+            //   - 'edit' mode (read,edit — fix in place) runs ONLY when the verify
+            //     gate just produced a genuine clean pass. That pass is the
+            //     differential SIGNAL: enforce commits its fixes, then the SAME
+            //     signal is re-run against the enforced tree. A regression means the
+            //     pass made the artifact worse than it found it — its commit is
+            //     dropped and the verified implementation is kept (A/B: 5/5 clean).
+            //   - 'flag' mode (read-only — report don't fix) runs when there is no
+            //     such signal (verify off, no spec, or an accept-override): with
+            //     nothing to revert against, the pass may not rewrite logic, only
+            //     surface violations as a warning ("no signal ⇒ no license"; A/B:
+            //     5/5 clean, 5/5 caught the real violation).
+            //
+            // Skipped when nothing was committed this round (autoCommit off or an
+            // empty commit), when the feature is off, when there are no guideline
+            // files, or in tests with no enforce dep.
             if (deps.enforce && commit.committed) {
-                active.ui.notify(`${id}: enforcing AGENTS.md/CLAUDE.md on "${next.title}"…`, 'info');
-                const verdict = await deps.enforce(active, cwd, next.title);
+                const mode = verifyCleanPass ? 'edit' : 'flag';
+                active.ui.notify(mode === 'edit' ?
+                    `${id}: enforcing AGENTS.md/CLAUDE.md on "${next.title}"…`
+                    : `${id}: reviewing "${next.title}" against AGENTS.md/CLAUDE.md (no verify signal — report only)…`, 'info');
+                const verdict = await deps.enforce(active, cwd, next.title, mode);
                 if (!verdict.ok) {
-                    active.ui.notify(`${id}: guideline enforcement on "${next.title}" — ${verdict.reason ?? 'not clean'} — continuing.`, 'warning');
+                    active.ui.notify(`${id}: guideline ${mode === 'edit' ? 'enforcement' : 'review'} on "${next.title}" — ${verdict.reason ?? 'not clean'} — continuing.`, 'warning');
                 }
-                // Commit whatever the pass fixed as its own snapshot. A no-op when
-                // the pass made no edits (gitCommitAll reports nothing to commit),
-                // so a clean task adds no empty commit — only announce a real one.
-                const enforceCommit = await deps.commit(cwd, `ENFORCE GUIDELINES: ${next.title} (${res.taskId})`);
-                if (enforceCommit.committed) {
-                    active.ui.notify(`${id}: committed guideline fixes for "${next.title}".`, 'info');
+                if (mode === 'edit') {
+                    // Commit whatever the pass fixed as its own snapshot. A no-op
+                    // when it made no edits (nothing to commit) — and then there is
+                    // nothing to re-verify or revert, so a clean task skips the
+                    // second verify entirely.
+                    const enforceCommit = await deps.commit(cwd, `ENFORCE GUIDELINES: ${next.title} (${res.taskId})`);
+                    if (enforceCommit.committed) {
+                        // Differential guard: re-run the verify signal against the
+                        // enforced tree. verifyCleanPass implies deps.verify exists,
+                        // so this is a real check. A regression ⇒ drop the enforce
+                        // commit, keep the verified task commit underneath it.
+                        const after = deps.verify ?
+                            await deps.verify(active, cwd, next.title, res.taskId)
+                            : { ok: true };
+                        if (!after.ok) {
+                            // Regression: drop the enforce commit if we can, and
+                            // never report it as a kept fix.
+                            if (deps.revert)
+                                await deps.revert(cwd);
+                            active.ui.notify(`${id}: guideline fixes regressed verification on "${next.title}" (${(after.reason ?? 'now fails').slice(0, 120)}) — ${deps.revert ? 'reverted them, kept the verified work' : 'left in place (no revert available)'}.`, 'warning');
+                        }
+                        else {
+                            active.ui.notify(`${id}: committed guideline fixes for "${next.title}".`, 'info');
+                        }
+                    }
                 }
+                // 'flag' mode makes no edits — nothing to commit or revert.
             }
         }
     }

package/dist/task/enforce-guidelines.d.ts

@@ -21,6 +21,20 @@ export declare const GUIDELINE_FILENAMES: readonly ["AGENTS.md", "CLAUDE.md"];
  *    (the prompt scopes them) but is a soft instruction for READS.
  */
 declare const ENFORCE_TOOLS = "read,edit";
+/**
+ * Flag-only enforcement gets exactly ONE tool: `read`. It can inspect the changed
+ * files and report violations but CANNOT edit, create, or run anything.
+ *
+ * This is the "no signal ⇒ no license to rewrite logic" half of the gate. When a
+ * task ships no behavioral verification to guard a destructive edit (no runnable
+ * VERIFY, or the verify gate did not produce a genuine clean pass), letting the
+ * weak model rewrite working code is exactly what trashes the build — A/B-proven:
+ * with `read,edit` and no guard the model degraded a clean tree in 4/5 runs while
+ * declaring CLEAN. Demoted to `read`, it cannot trash anything (5/5 clean) and
+ * still names the real violation (5/5). So with no signal to revert against, the
+ * pass reports the violation as a warning instead of editing.
+ */
+declare const ENFORCE_FLAG_TOOLS = "read";
 export interface GuidelineDoc {
     /** Filenames found, in discovery order (e.g. ['AGENTS.md', 'CLAUDE.md']). */
     files: string[];
@@ -48,6 +62,13 @@ export declare function discoverGuidelines(cwd: string, readFile?: (p: string) =
  * is unit-tested without spawning pi.
  */
 export declare function buildEnforcePrompt(rulesText: string, diff: string): string;
+/**
+ * Build the FLAG-ONLY enforcement prompt: same rules + diff, but the child has a
+ * `read` tool only and is told to REPORT violations, not fix them. Kept pure so
+ * the wording is unit-tested without spawning pi. Used when there is no
+ * verification signal to guard a destructive edit (see ENFORCE_FLAG_TOOLS).
+ */
+export declare function buildEnforceFlagPrompt(rulesText: string, diff: string): string;
 /**
  * Parse the child's final verdict. Scans for the LAST `ENFORCE: CLEAN` /
  * `ENFORCE: VIOLATION` marker (the model may discuss before concluding).
@@ -115,6 +136,16 @@ export declare function captureCommitDiff(cwd: string, signal?: AbortSignal, spa
 export interface EnforcementDeps {
     cwd: string;
     signal?: AbortSignal;
+    /**
+     * Which capability the pass runs with.
+     *  - `'edit'` (default): `read,edit` — the model fixes violations in place. The
+     *    caller is responsible for guarding those edits with a differential
+     *    verification check (revert on regression), because a bare edit pass
+     *    trashes working code (A/B: 4/5).
+     *  - `'flag'`: `read` only — the model reports violations but cannot touch the
+     *    tree. Used when there is no verification signal to guard an edit against.
+     */
+    mode?: 'edit' | 'flag';
     /** Defaults to the real cwd-only file discovery. */
     discover?: (cwd: string) => Promise<GuidelineDoc | null>;
     /** Defaults to the real git diff capture. */
@@ -130,4 +161,4 @@ export interface EnforcementDeps {
  * blocking outcome (ok: false) so an unverifiable task is not committed.
  */
 export declare function runGuidelineEnforcement(deps: EnforcementDeps): Promise<EnforceOutcome>;
-export { ENFORCE_TOOLS };
+export { ENFORCE_TOOLS, ENFORCE_FLAG_TOOLS };

package/dist/task/enforce-guidelines.js

@@ -48,6 +48,20 @@ export const GUIDELINE_FILENAMES = ['AGENTS.md', 'CLAUDE.md'];
  *    (the prompt scopes them) but is a soft instruction for READS.
  */
 const ENFORCE_TOOLS = 'read,edit';
+/**
+ * Flag-only enforcement gets exactly ONE tool: `read`. It can inspect the changed
+ * files and report violations but CANNOT edit, create, or run anything.
+ *
+ * This is the "no signal ⇒ no license to rewrite logic" half of the gate. When a
+ * task ships no behavioral verification to guard a destructive edit (no runnable
+ * VERIFY, or the verify gate did not produce a genuine clean pass), letting the
+ * weak model rewrite working code is exactly what trashes the build — A/B-proven:
+ * with `read,edit` and no guard the model degraded a clean tree in 4/5 runs while
+ * declaring CLEAN. Demoted to `read`, it cannot trash anything (5/5 clean) and
+ * still names the real violation (5/5). So with no signal to revert against, the
+ * pass reports the violation as a warning instead of editing.
+ */
+const ENFORCE_FLAG_TOOLS = 'read';
 /**
  * Read the guideline files that live directly in `cwd` (AGENTS.md, CLAUDE.md).
  * Returns null when none exist or all are empty — the caller treats that as a
@@ -110,6 +124,37 @@ export function buildEnforcePrompt(rulesText, diff) {
         'Output the verdict line verbatim — it is parsed mechanically.'
     ].join('\n');
 }
+/**
+ * Build the FLAG-ONLY enforcement prompt: same rules + diff, but the child has a
+ * `read` tool only and is told to REPORT violations, not fix them. Kept pure so
+ * the wording is unit-tested without spawning pi. Used when there is no
+ * verification signal to guard a destructive edit (see ENFORCE_FLAG_TOOLS).
+ */
+export function buildEnforceFlagPrompt(rulesText, diff) {
+    return [
+        'You are a strict guideline-enforcement REVIEW pass running right after an AI',
+        'coding agent finished a task and committed it. The agent is known to skip',
+        'project rules, so do not trust that it followed them — verify against the',
+        'changes.',
+        '',
+        'You have a `read` tool — and NOTHING else. You CANNOT edit, create, or run',
+        'anything. Your job is to REVIEW and REPORT, not to fix.',
+        '',
+        'PROJECT GUIDELINES (from this repository):',
+        rulesText,
+        '',
+        'CHANGES IN THE LAST COMMIT (review these specifically against the rules):',
+        diff.trim().length > 0 ? diff : '(no textual diff captured — nothing to verify)',
+        '',
+        'Read each changed file and check it against EVERY rule above. Do NOT attempt',
+        'to fix anything — only report what you find.',
+        '',
+        'When you are done, output EXACTLY ONE of these as the final line:',
+        '  ENFORCE: CLEAN              (the changes comply with every rule)',
+        '  ENFORCE: VIOLATION <text>  (a rule is violated; say which — do not fix it)',
+        'Output the verdict line verbatim — it is parsed mechanically.'
+    ].join('\n');
+}
 /**
  * Parse the child's final verdict. Scans for the LAST `ENFORCE: CLEAN` /
  * `ENFORCE: VIOLATION` marker (the model may discuss before concluding).
@@ -228,9 +273,12 @@ export async function runGuidelineEnforcement(deps) {
     if (!doc)
         return { ok: true, reason: 'no guideline files' };
     const diff = await getDiff(deps.cwd, deps.signal);
+    const flagOnly = deps.mode === 'flag';
+    const tools = flagOnly ? ENFORCE_FLAG_TOOLS : ENFORCE_TOOLS;
+    const prompt = flagOnly ? buildEnforceFlagPrompt(doc.text, diff) : buildEnforcePrompt(doc.text, diff);
     let text;
     try {
-        text = await deps.runChild(ENFORCE_TOOLS, buildEnforcePrompt(doc.text, diff), deps.signal);
+        text = await deps.runChild(tools, prompt, deps.signal);
     }
     catch (err) {
         // A user cancellation is not an enforcement failure — re-throw it so the
@@ -246,4 +294,4 @@ export async function runGuidelineEnforcement(deps) {
         return { ok: true };
     return { ok: false, reason: `guideline violation: ${verdict.detail}` };
 }
-export { ENFORCE_TOOLS };
+export { ENFORCE_TOOLS, ENFORCE_FLAG_TOOLS };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.14.22",
+    "version": "0.15.1",
     "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",