@mjasnikovs/pi-task 0.13.29 → 0.13.30

package/README.md

@@ -49,7 +49,7 @@ pi install npm:@mjasnikovs/pi-task
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
 | `/task-auto-resume` | Resume the active `/task-auto` run at the next unfinished task. |
 | `/task-auto-cancel` | Stop the `/task-auto` loop after the current task (still resumable). |
-| `/task-config` | Toggle pi-task settings in an editor dialog: remote server, compress reasoning, auto-commit, and orientation. |
+| `/task-config` | Toggle pi-task settings in an editor dialog: remote server, compress reasoning, auto-commit, orientation, and enforce guidelines. |
 | `/remote` | Show the QR code & URLs for the web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
 
 ## The pipeline
@@ -140,7 +140,7 @@ Resolves an installed npm package, indexes its `.d.ts` files and README into a l
 
 ## Settings — `/task-config`
 
-Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings persist to `~/.config/pi-task/config.json` and all default to **on**:
+Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings persist to `~/.config/pi-task/config.json`. All default to **on** except **enforce guidelines**:
 
 | Setting | What it does |
 | --- | --- |
@@ -148,6 +148,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **compress reasoning** | After each message, compresses the model's `<think>` blocks down to the decisions/constraints/facts that matter later — keeping long local-model runs from drowning their own context in self-talk. |
 | **auto-commit** | Snapshots the working tree into one git commit per `/task-auto` sub-task (see above). |
 | **orientation** | Pre-reads the project's core files (manifest, config, domain types, schema, entrypoints, API surface) once and hands the contents to the read-heavy research workers, so they skip re-discovering the same files cold. Bounded by a hard byte budget; applied only where it helps (FILES/APIS workers). |
+| **enforce guidelines** _(off by default)_ | Before each `/task-auto` commit, re-checks the sub-task's work against the project's `AGENTS.md` / `CLAUDE.md` (in the working directory). Local models drift and skip those rules, so a fresh pass of the same local model — with edit tools — reads the diff, fixes any violations in place, and returns a verdict. A violation it can't clear (or a pass that can't run) **blocks the commit and stops the run** so non-compliant work is never snapshotted; fix and `/task-auto-resume`. Adds one extra local-model pass per task, so it's opt-in. |
 
 ## Configuration
 

package/dist/config/config.d.ts

@@ -3,6 +3,7 @@ export interface PiTaskConfig {
     compressReasoning: boolean;
     autoCommit: boolean;
     orientation: boolean;
+    enforceGuidelines: boolean;
 }
 export declare function getConfig(): PiTaskConfig;
 export declare function saveConfig(config: PiTaskConfig): Promise<void>;

package/dist/config/config.js

@@ -6,7 +6,8 @@ const DEFAULTS = {
     remote: true,
     compressReasoning: true,
     autoCommit: true,
-    orientation: true
+    orientation: true,
+    enforceGuidelines: false
 };
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'pi-task', 'config.json');
 const _g = globalThis;

package/dist/config/register.js

@@ -17,6 +17,11 @@ const ITEMS = [
         id: 'orientation',
         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'
     }
 ];
 function makeTheme(theme) {
@@ -53,7 +58,7 @@ async function handleTaskConfig(_args, ctx) {
 }
 export function registerConfig(pi) {
     registerBridgeCommand(pi, 'task-config', {
-        description: 'Configure pi-task settings (remote, compress reasoning, auto-commit, orientation).',
+        description: 'Configure pi-task settings (remote, compress reasoning, auto-commit, orientation, enforce guidelines).',
         handler: handleTaskConfig
     });
 }

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

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { RunSingleTaskResult } from './orchestrator.js';
 import { type CommitResult } from './auto-commit.js';
+import { type EnforceOutcome } from './enforce-guidelines.js';
 /**
  * Injectable seams so the planner and loop are testable without spawning pi.
  * `runChild` is used by planAuto; `runTask` is used by runAutoLoop.
@@ -15,6 +16,13 @@ export interface AutoDeps {
     }) => Promise<RunSingleTaskResult>;
     /** Snapshot the working tree into one commit after a task passes. */
     commit: (cwd: string, message: string) => Promise<CommitResult>;
+    /**
+     * Verify the just-finished task's work against the project's AGENTS.md /
+     * CLAUDE.md guidelines (and auto-fix violations) BEFORE it is committed.
+     * Optional: when absent (tests, or the feature disabled), the loop treats it
+     * as a pass. ok === false blocks the commit and fails the task.
+     */
+    enforce?: (cwd: string, taskTitle: string) => Promise<EnforceOutcome>;
 }
 /**
  * Expand any @file references in the feature text by appending each referenced

package/dist/task/auto-orchestrator.js

@@ -15,6 +15,8 @@ import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './quest
 import { allocateAutoId, buildAutoBody, parseDecomposeList, parseTaskList, checkOffTask, stampTaskInProgress, findResumableAuto } from './auto-io.js';
 import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath } from './task-io.js';
 import { gitCommitAll } from './auto-commit.js';
+import { runGuidelineEnforcement, ENFORCE_TIMEOUT_MS } from './enforce-guidelines.js';
+import { runWorker } from '../workers/pi-worker-core.js';
 import { runPhaseChild, prependHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI, registerBridgeCommand } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
@@ -303,7 +305,43 @@ function defaultDeps(ctx, cwd, signal, title) {
         }),
         commit: (cwd2, message) => getConfig().autoCommit ?
             gitCommitAll(cwd2, message, signal)
-            : Promise.resolve({ committed: false, reason: 'auto-commit disabled' })
+            : Promise.resolve({ committed: false, reason: 'auto-commit disabled' }),
+        enforce: (cwd2, _taskTitle) => {
+            if (!getConfig().enforceGuidelines) {
+                return Promise.resolve({ ok: true, reason: 'disabled' });
+            }
+            return runGuidelineEnforcement({
+                cwd: cwd2,
+                signal,
+                // Reuse the timeout- and loop-guarded worker child. It runs the
+                // same local model with edit tools so it can fix violations in
+                // place. Any non-clean exit (loop kill, timeout, leaked tool call,
+                // non-zero) throws so the pass becomes a blocking outcome rather
+                // than trusting a partial transcript.
+                runChild: async (tools, prompt, sig) => {
+                    const r = await runWorker({
+                        prompt,
+                        cwd: cwd2,
+                        signal: sig,
+                        tools,
+                        timeoutMs: ENFORCE_TIMEOUT_MS,
+                        onLine: line => phaseDeps.logDebug?.(`enforce: ${line}`)
+                    });
+                    if (r.aborted && !r.timedOut)
+                        throw new Error(USER_CANCELLED);
+                    if (r.timedOut)
+                        throw new Error('enforcement child timed out');
+                    if (r.loopHit)
+                        throw new Error('enforcement child looped');
+                    if (r.leakedToolCall)
+                        throw new Error('enforcement child leaked a tool call');
+                    if (r.exitCode !== 0) {
+                        throw new Error(`enforcement child exited ${r.exitCode}`);
+                    }
+                    return r.text;
+                }
+            });
+        }
     };
 }
 // ─── Loop ────────────────────────────────────────────────────────────────────
@@ -402,6 +440,24 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 announceDone(active, `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`, 'error');
                 return;
             }
+            // Before checking the task off or committing, hold the work to the
+            // project's AGENTS.md / CLAUDE.md rules. Local models drift and skip
+            // those guidelines, so the enforcement pass re-reads the diff with the
+            // same local model (edit tools enabled) and fixes violations in place.
+            // A non-clean verdict — or a pass that could not run — blocks the
+            // commit and fails the task: non-compliant work is never snapshotted,
+            // and the run pauses for /task-auto-resume. (No-op when the feature is
+            // off, when there are no guideline files, or in tests with no enforce
+            // dep.) Fixes it makes are folded into this task's snapshot below.
+            if (deps.enforce) {
+                active.ui.notify(`${id}: enforcing AGENTS.md/CLAUDE.md on "${next.title}"…`, 'info');
+                const verdict = await deps.enforce(cwd, next.title);
+                if (!verdict.ok) {
+                    await updateTaskFrontMatter(cwd, id, { state: 'failed' });
+                    announceDone(active, `${id} stopped at "${next.title}" — ${verdict.reason ?? 'guideline check failed'} — fix and run /task-auto-resume.`, 'error');
+                    return;
+                }
+            }
             // res.ok === true means runner.run() completed, so res.taskId is the
             // allocated TASK_NNNN id (never empty here). checkOffTask tolerates an
             // empty id by writing a plain checked line, but that path is unreachable.

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

@@ -0,0 +1,74 @@
+import { type SpawnFn } from '../shared/child-process.js';
+/** Filenames discovered in the working directory (cwd only — no tree walk). */
+export declare const GUIDELINE_FILENAMES: readonly ["AGENTS.md", "CLAUDE.md"];
+/** Tools the fix pass is allowed: read/search to inspect, edit/write to fix. */
+declare const ENFORCE_TOOLS = "read,grep,find,ls,edit,write";
+/** Wall-clock ceiling for the enforcement child. Local models are slow and the
+ *  fix pass reads several files and may rewrite a few; give it room but never
+ *  let a wedged child hang the whole run. */
+declare const ENFORCE_TIMEOUT_MS = 600000;
+export interface GuidelineDoc {
+    /** Filenames found, in discovery order (e.g. ['AGENTS.md', 'CLAUDE.md']). */
+    files: string[];
+    /** The concatenated rules text, each file under a `## <name>` header. */
+    text: string;
+}
+export interface EnforceOutcome {
+    /** true → compliant (after any fixes), enforcement disabled, or no
+     *  guideline files. false → a violation the pass could not clear, or the
+     *  pass could not run / produced no verdict. */
+    ok: boolean;
+    /** Short, human-readable reason. Always set when ok === false; on the pass
+     *  path set to the no-op cause ('disabled', 'no guideline files'). */
+    reason?: string;
+}
+/**
+ * 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
+ * pass. cwd-only by design: no walk up to the git root.
+ */
+export declare function discoverGuidelines(cwd: string, readFile?: (p: string) => Promise<string>): Promise<GuidelineDoc | null>;
+/**
+ * Build the enforcement child's prompt: the rules, the diff of the work just
+ * done, and the contract for the final verdict line. Kept pure so the wording
+ * is unit-tested without spawning pi.
+ */
+export declare function buildEnforcePrompt(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).
+ *
+ * No marker at all is treated as NOT clean: a pass that cannot state a verdict
+ * is a gray area, and the contract is that uncertain work does not get
+ * committed.
+ */
+export declare function parseEnforceVerdict(text: string): {
+    clean: boolean;
+    detail: string;
+};
+/**
+ * Capture the work to verify as text: the tracked diff against HEAD plus the
+ * names of any new (untracked) files. Non-destructive — it does not touch the
+ * index, so the later `git add -A` in gitCommitAll still stages everything
+ * (including fixes the enforcement child makes).
+ */
+export declare function captureDiff(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string>;
+export interface EnforcementDeps {
+    cwd: string;
+    signal?: AbortSignal;
+    /** Defaults to the real cwd-only file discovery. */
+    discover?: (cwd: string) => Promise<GuidelineDoc | null>;
+    /** Defaults to the real git diff capture. */
+    getDiff?: (cwd: string, signal?: AbortSignal) => Promise<string>;
+    /** Runs the enforcement child and returns its assistant text. Injected so
+     *  the orchestrator wires the real child runner and tests use a fake. */
+    runChild: (tools: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+}
+/**
+ * Run the full enforcement pass for one task. Discovery is cwd-only; an empty
+ * result is a pass. Otherwise capture the diff, run the fix child, and turn its
+ * verdict into an ok/blocked outcome. Never throws — a child failure becomes a
+ * blocking outcome (ok: false) so an unverifiable task is not committed.
+ */
+export declare function runGuidelineEnforcement(deps: EnforcementDeps): Promise<EnforceOutcome>;
+export { ENFORCE_TOOLS, ENFORCE_TIMEOUT_MS };

package/dist/task/enforce-guidelines.js

@@ -0,0 +1,146 @@
+/**
+ * Guideline enforcement for /task-auto.
+ *
+ * Local models drift: they skip the rules written in AGENTS.md / CLAUDE.md even
+ * when those files sit right next to the code. After a /task-auto sub-task's
+ * implementation turn settles — but BEFORE its per-task commit — this runs a
+ * fresh child pi (the same local model that did the work) that is handed the
+ * project's guideline files plus the task's diff, fixes any violations in place
+ * with its edit tools, and reports a CLEAN / VIOLATION verdict.
+ *
+ * A VIOLATION (or an enforcement pass that cannot confirm CLEAN) blocks the
+ * commit and fails the task, so non-compliant work is never snapshotted — the
+ * run pauses for /task-auto-resume. This is deliberately strict: the whole
+ * point is that "the model probably followed the rules" is not good enough.
+ *
+ * Gated by the `enforceGuidelines` config flag. With the flag off, or with no
+ * guideline files in the working directory, enforcement is a pass (ok: true).
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { runChildDefault } from '../shared/child-process.js';
+/** Filenames discovered in the working directory (cwd only — no tree walk). */
+export const GUIDELINE_FILENAMES = ['AGENTS.md', 'CLAUDE.md'];
+/** Tools the fix pass is allowed: read/search to inspect, edit/write to fix. */
+const ENFORCE_TOOLS = 'read,grep,find,ls,edit,write';
+/** Wall-clock ceiling for the enforcement child. Local models are slow and the
+ *  fix pass reads several files and may rewrite a few; give it room but never
+ *  let a wedged child hang the whole run. */
+const ENFORCE_TIMEOUT_MS = 600_000;
+/**
+ * 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
+ * pass. cwd-only by design: no walk up to the git root.
+ */
+export async function discoverGuidelines(cwd, readFile = p => fsp.readFile(p, 'utf8')) {
+    const files = [];
+    const sections = [];
+    for (const name of GUIDELINE_FILENAMES) {
+        let raw;
+        try {
+            raw = await readFile(path.join(cwd, name));
+        }
+        catch {
+            continue; // missing file — skip
+        }
+        if (raw.trim().length === 0)
+            continue; // present but empty — nothing to enforce
+        files.push(name);
+        sections.push(`## ${name}\n\n${raw.trim()}`);
+    }
+    if (files.length === 0)
+        return null;
+    return { files, text: sections.join('\n\n') };
+}
+/**
+ * Build the enforcement child's prompt: the rules, the diff of the work just
+ * done, and the contract for the final verdict line. Kept pure so the wording
+ * is unit-tested without spawning pi.
+ */
+export function buildEnforcePrompt(rulesText, diff) {
+    return [
+        'You are a strict guideline-enforcement pass running after an AI coding agent',
+        'finished a task but before its work is committed. The agent is known to skip',
+        'project rules, so do not trust that it followed them — verify against the diff.',
+        '',
+        'PROJECT GUIDELINES (from this repository):',
+        rulesText,
+        '',
+        'CHANGES JUST MADE (verify these specifically; read any file you need in full):',
+        diff.trim().length > 0 ? diff : '(no textual diff captured — inspect the working tree)',
+        '',
+        'Your job:',
+        '1. Check the changed files against EVERY rule above.',
+        '2. For each violation you find, FIX it directly using your edit/write tools.',
+        '   Make the minimal change that satisfies the rule; do not rewrite unrelated code.',
+        '3. Do not introduce new behavior or features — only bring the work into compliance.',
+        '',
+        'When you are done, output EXACTLY ONE of these as the final line:',
+        '  ENFORCE: CLEAN              (the changes comply with every rule, after your fixes)',
+        '  ENFORCE: VIOLATION <text>  (a rule is still violated and you could not fix it; say which)',
+        '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).
+ *
+ * No marker at all is treated as NOT clean: a pass that cannot state a verdict
+ * is a gray area, and the contract is that uncertain work does not get
+ * committed.
+ */
+export function parseEnforceVerdict(text) {
+    const re = /ENFORCE:\s*(CLEAN|VIOLATION)\b[ \t]*(.*)/gi;
+    let last = null;
+    for (let m = re.exec(text); m !== null; m = re.exec(text))
+        last = m;
+    if (!last)
+        return { clean: false, detail: 'no verdict emitted' };
+    const clean = last[1].toUpperCase() === 'CLEAN';
+    return { clean, detail: clean ? '' : last[2].trim() || 'unspecified violation' };
+}
+/**
+ * Capture the work to verify as text: the tracked diff against HEAD plus the
+ * names of any new (untracked) files. Non-destructive — it does not touch the
+ * index, so the later `git add -A` in gitCommitAll still stages everything
+ * (including fixes the enforcement child makes).
+ */
+export async function captureDiff(cwd, signal, spawnFn) {
+    const run = (args) => runChildDefault({ command: 'git', args }, cwd, signal, { mode: 'text' }, spawnFn);
+    const tracked = await run(['diff', 'HEAD']);
+    const untracked = await run(['ls-files', '--others', '--exclude-standard']);
+    const parts = [];
+    if (tracked.exitCode === 0 && tracked.stdout.trim().length > 0)
+        parts.push(tracked.stdout.trim());
+    const newFiles = untracked.exitCode === 0 ? untracked.stdout.trim() : '';
+    if (newFiles.length > 0)
+        parts.push(`New (untracked) files — read them in full:\n${newFiles}`);
+    return parts.join('\n\n');
+}
+/**
+ * Run the full enforcement pass for one task. Discovery is cwd-only; an empty
+ * result is a pass. Otherwise capture the diff, run the fix child, and turn its
+ * verdict into an ok/blocked outcome. Never throws — a child failure becomes a
+ * blocking outcome (ok: false) so an unverifiable task is not committed.
+ */
+export async function runGuidelineEnforcement(deps) {
+    const discover = deps.discover ?? (cwd => discoverGuidelines(cwd));
+    const getDiff = deps.getDiff ?? ((cwd, signal) => captureDiff(cwd, signal));
+    const doc = await discover(deps.cwd);
+    if (!doc)
+        return { ok: true, reason: 'no guideline files' };
+    const diff = await getDiff(deps.cwd, deps.signal);
+    let text;
+    try {
+        text = await deps.runChild(ENFORCE_TOOLS, buildEnforcePrompt(doc.text, diff), deps.signal);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `enforcement pass could not run: ${msg}` };
+    }
+    const verdict = parseEnforceVerdict(text);
+    if (verdict.clean)
+        return { ok: true };
+    return { ok: false, reason: `guideline violation: ${verdict.detail}` };
+}
+export { ENFORCE_TOOLS, ENFORCE_TIMEOUT_MS };

package/package.json

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