agentplane 0.3.14 → 0.3.16

package/dist/commands/guard/impl/commit-diagnostics.js

@@ -0,0 +1,150 @@
+import { stripAnsi } from "../../../cli/shared/ansi.js";
+import { withDiagnosticContext } from "../../shared/diagnostics.js";
+import { CliError } from "../../../shared/errors.js";
+const COMMIT_FAILURE_SIGNAL_PATTERNS = [
+    /Code style issues found/i,
+    /Run Prettier with --write/i,
+    /\bESLint\b/i,
+    /\b[0-9]+\s+problems?\b/i,
+    /\berror\b/i,
+    /\bfailed\b/i,
+    /✖/,
+];
+const FORMATTER_SIGNAL_PATTERNS = [
+    /Code style issues found/i,
+    /Run Prettier with --write/i,
+];
+const ESLINT_SIGNAL_PATTERNS = [/\bESLint\b/i, /\b[0-9]+\s+problems?\b/i];
+function readText(value) {
+    if (typeof value === "string")
+        return value;
+    if (Buffer.isBuffer(value))
+        return value.toString("utf8");
+    return "";
+}
+function summarizeOutput(raw) {
+    const lines = raw
+        .replaceAll("\r\n", "\n")
+        .split("\n")
+        .map((line) => stripAnsi(line).trimEnd())
+        .filter((line) => line.trim().length > 0)
+        .map((line) => (line.length > 180 ? `${line.slice(0, 180)} [truncated]` : line));
+    if (lines.length <= 12)
+        return lines;
+    const selected = new Set();
+    for (let index = 0; index < Math.min(6, lines.length); index += 1)
+        selected.add(index);
+    for (let index = Math.max(lines.length - 6, 0); index < lines.length; index += 1) {
+        selected.add(index);
+    }
+    for (const [index, line] of lines.entries()) {
+        if (!selected.has(index) &&
+            COMMIT_FAILURE_SIGNAL_PATTERNS.some((pattern) => pattern.test(line))) {
+            selected.add(index);
+        }
+    }
+    const summary = [];
+    let previous = -1;
+    for (const index of [...selected].toSorted((a, b) => a - b)) {
+        if (previous >= 0 && index - previous > 1) {
+            summary.push(`[${index - previous - 1} lines omitted]`);
+        }
+        summary.push(lines[index] ?? "");
+        previous = index;
+    }
+    return summary;
+}
+function detectCommitFailureSignal(output) {
+    if (FORMATTER_SIGNAL_PATTERNS.some((pattern) => pattern.test(output)))
+        return "formatter";
+    if (ESLINT_SIGNAL_PATTERNS.some((pattern) => pattern.test(output)))
+        return "eslint";
+    return null;
+}
+function commitFailureDiagnostic(phase, output) {
+    const signal = detectCommitFailureSignal(output);
+    if (signal === "formatter") {
+        return {
+            state: phase === "close_commit"
+                ? "git rejected the generated close commit"
+                : "git rejected the requested task-scoped commit",
+            likelyCause: phase === "close_commit"
+                ? "a formatting check in the pre-commit path rejected the deterministic close commit after the task README was staged"
+                : "a formatting check in the pre-commit path rejected the staged task-scoped commit",
+            nextAction: {
+                command: "bun run format",
+                reason: "apply formatter fixes before retrying the commit flow",
+                reasonCode: "git_pre_commit_format",
+            },
+        };
+    }
+    if (signal === "eslint") {
+        return {
+            state: phase === "close_commit"
+                ? "git rejected the generated close commit"
+                : "git rejected the requested task-scoped commit",
+            likelyCause: phase === "close_commit"
+                ? "a lint check in the pre-commit path rejected the deterministic close commit after the task README was staged"
+                : "a lint check in the pre-commit path rejected the staged task-scoped commit",
+            nextAction: {
+                command: "bun run lint:core",
+                reason: "rerun lint and fix the reported error before retrying the commit flow",
+                reasonCode: "git_pre_commit_lint",
+            },
+        };
+    }
+    if (phase === "close_commit") {
+        return {
+            state: "git rejected the generated close commit",
+            likelyCause: "a hook or commit policy blocked the deterministic task close commit after the task README was staged",
+            nextAction: {
+                command: "git status --short --untracked-files=no",
+                reason: "inspect the staged close-commit payload before fixing the hook or policy failure",
+                reasonCode: "git_close_commit_blocked",
+            },
+        };
+    }
+    return {
+        state: "git rejected the requested task-scoped commit",
+        likelyCause: "a hook or commit policy blocked the staged changes after guard validation passed",
+        nextAction: {
+            command: "git status --short --untracked-files=no",
+            reason: "inspect the staged task-scoped payload before fixing the hook or policy failure",
+            reasonCode: "git_task_commit_blocked",
+        },
+    };
+}
+export function asCommitFailure(err, phase) {
+    if (!(err instanceof Error))
+        return null;
+    const e = err;
+    const shortMessage = typeof e.shortMessage === "string" ? e.shortMessage : "";
+    const message = typeof e.message === "string" ? e.message : "";
+    const extractedCommand = typeof e.cmd === "string"
+        ? e.cmd
+        : typeof e.escapedCommand === "string"
+            ? e.escapedCommand
+            : (/^Command failed(?: with exit code \d+)?: ([^\n]+)$/m.exec(shortMessage)?.[1] ??
+                /^Command failed(?: with exit code \d+)?: ([^\n]+)$/m.exec(message)?.[1] ??
+                "");
+    const cmd = extractedCommand.trim();
+    if (!cmd.startsWith("git commit"))
+        return null;
+    const output = [readText(e.stderr), readText(e.stdout)]
+        .filter((part) => part.length > 0)
+        .join("\n");
+    const summary = summarizeOutput(output);
+    const code = typeof e.code === "number" ? e.code : null;
+    const lines = ["git commit failed (hook or commit policy).", `command: ${cmd}`];
+    if (typeof code === "number")
+        lines.push(`exit_code: ${code}`);
+    if (summary.length > 0)
+        lines.push("output_summary:");
+    lines.push(...summary.map((line) => `  ${line}`));
+    return new CliError({
+        exitCode: 5,
+        code: "E_GIT",
+        message: lines.join("\n"),
+        context: withDiagnosticContext({ command: "commit" }, commitFailureDiagnostic(phase, output)),
+    });
+}

package/dist/commands/guard/impl/commit.d.ts

@@ -0,0 +1,25 @@
+import { type CommandContext } from "../../shared/task-backend.js";
+export declare function cmdCommit(opts: {
+    ctx?: CommandContext;
+    cwd: string;
+    rootOverride?: string;
+    baseBranchOverride?: string | null;
+    taskId: string;
+    message: string;
+    close: boolean;
+    allow: string[];
+    autoAllow: boolean;
+    allowTasks: boolean;
+    allowBase: boolean;
+    allowPolicy: boolean;
+    allowConfig: boolean;
+    allowHooks: boolean;
+    allowCI: boolean;
+    requireClean: boolean;
+    quiet: boolean;
+    closeUnstageOthers: boolean;
+    closeCheckOnly: boolean;
+    closeStageTaskArtifacts?: boolean;
+    closeRefreshTaskArtifacts?: boolean;
+}): Promise<number>;
+//# sourceMappingURL=commit.d.ts.map

package/dist/commands/guard/impl/commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/commit.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAgKtC,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CA2HlB"}

package/dist/commands/guard/impl/commit.js

@@ -0,0 +1,366 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { buildTaskArtifactRefreshCommitSubject } from "@agentplaneorg/core";
+import { resolveTaskIndexPath } from "../../../backends/task-index.js";
+import { mapCoreError } from "../../../cli/error-map.js";
+import { infoMessage, successMessage } from "../../../cli/output.js";
+import { withDiagnosticContext } from "../../shared/diagnostics.js";
+import { CliError } from "../../../shared/errors.js";
+import { protectedPathKindForFile } from "../../../shared/protected-paths.js";
+import { refreshBranchPrArtifactsAfterTaskCommit } from "../../shared/post-commit-pr-artifacts.js";
+import { isTaskLocalAdvancePath } from "../../shared/task-local-freshness.js";
+import { loadCommandContext, loadTaskFromContext, } from "../../shared/task-backend.js";
+import { execFileAsync, gitEnv } from "../../shared/git.js";
+import { ensureReconciledBeforeMutation } from "../../shared/reconcile-check.js";
+import { stageAllowlist } from "./allow.js";
+import { resolveIgnoredDirectCloseDirtyPaths } from "./close-dirt.js";
+import { buildCloseCommitMessage, taskReadmePathForTask } from "./close-message.js";
+import { asCommitFailure } from "./commit-diagnostics.js";
+import { buildGitCommitEnv, resolveCanonicalGitIdentity } from "./env.js";
+import { guardCommitCheck } from "./policy.js";
+async function resetRebuildableTaskIndexCache(ctx) {
+    const gitRoot = path.resolve(ctx.resolvedProject.gitRoot);
+    const workflowDirAbs = path.resolve(gitRoot, ctx.config.paths.workflow_dir);
+    const cachePath = path.resolve(resolveTaskIndexPath(workflowDirAbs));
+    const relativeCachePath = path.relative(gitRoot, cachePath);
+    if (!relativeCachePath || relativeCachePath.startsWith(".."))
+        return;
+    try {
+        await execFileAsync("git", ["ls-files", "--error-unmatch", "--", relativeCachePath], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+        const gitPath = relativeCachePath.split(path.sep).join("/");
+        const cacheBlob = await execFileAsync("git", ["show", `HEAD:${gitPath}`], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+        await mkdir(path.dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, cacheBlob.stdout, "utf8");
+        await execFileAsync("git", ["restore", "--staged", "--", relativeCachePath], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+    }
+    catch {
+        await rm(cachePath, { force: true });
+    }
+    ctx.git.invalidateStatus();
+}
+async function stageCloseCommitPaths(opts) {
+    const stagePaths = new Set([opts.readmeRel]);
+    if (opts.allowPolicy) {
+        const changedPaths = await opts.ctx.git.statusChangedPaths();
+        for (const relPath of changedPaths) {
+            if (protectedPathKindForFile({
+                filePath: relPath,
+                tasksPath: opts.ctx.config.paths.tasks_path,
+                workflowDir: opts.ctx.config.paths.workflow_dir,
+                taskId: opts.taskId,
+            }) === "policy") {
+                stagePaths.add(relPath);
+            }
+        }
+    }
+    await opts.ctx.git.stage([...stagePaths].toSorted((a, b) => a.localeCompare(b)));
+}
+async function commitRefreshedTaskArtifacts(opts) {
+    const changedPaths = await opts.ctx.git.statusChangedPaths();
+    const taskArtifactPaths = changedPaths.filter((relPath) => isTaskLocalAdvancePath({
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+        tasksPath: opts.ctx.config.paths.tasks_path,
+        relPath,
+    }));
+    if (taskArtifactPaths.length === 0)
+        return null;
+    await stageAllowlist({
+        ctx: opts.ctx,
+        allow: [],
+        allowTasks: true,
+        allowPolicy: false,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+        tasksPath: opts.ctx.config.paths.tasks_path,
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+        allowTaskOnly: true,
+        emptyAllowMessage: "PR artifact refresh produced no task-local files to stage for the follow-up commit.",
+        noMatchMessage: "PR artifact refresh produced changes outside the active task artifact scope; inspect the working tree before retrying the commit flow.",
+    });
+    const message = buildTaskArtifactRefreshCommitSubject({
+        taskId: opts.taskId,
+        baseSubject: opts.sourceMessage,
+    });
+    await guardCommitCheck({
+        ctx: opts.ctx,
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride,
+        baseBranchOverride: null,
+        taskId: opts.taskId,
+        message,
+        allow: [],
+        allowBase: false,
+        allowTasks: true,
+        allowPolicy: false,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+        requireClean: true,
+        quiet: opts.quiet,
+    });
+    const env = buildGitCommitEnv({
+        taskId: opts.taskId,
+        allowTasks: true,
+        allowBase: false,
+        allowPolicy: false,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+        gitIdentity: await resolveCanonicalGitIdentity(),
+    });
+    await opts.ctx.git.commit({ message, env });
+    return await opts.ctx.git.headHashSubject();
+}
+function hasExplicitCommitScope(opts) {
+    return (opts.allow.some((prefix) => prefix.trim().length > 0) ||
+        opts.allowTasks ||
+        opts.allowPolicy ||
+        opts.allowConfig ||
+        opts.allowHooks ||
+        opts.allowCI);
+}
+function formatCommitRef(commit) {
+    if (!commit)
+        return "";
+    return `${commit.hash?.slice(0, 12) ?? ""} ${commit.subject ?? ""}`.trim();
+}
+export async function cmdCommit(opts) {
+    try {
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        if (opts.close) {
+            return await cmdCloseCommit({ ...opts, ctx });
+        }
+        if (opts.autoAllow) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "--auto-allow is disabled; pass explicit --allow <path-prefix>.",
+            });
+        }
+        await ensureReconciledBeforeMutation({ ctx, command: "commit" });
+        let autoStaged = [];
+        const staged = await ctx.git.statusStagedPaths();
+        if (staged.length === 0) {
+            if (!hasExplicitCommitScope(opts)) {
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: "No staged files and no commit allowlist. Pass --allow <path-prefix>, use --allow-tasks for active task artifacts, or stage files manually.",
+                });
+            }
+            autoStaged = await stageAllowlist({
+                ctx,
+                allow: opts.allow,
+                allowTasks: opts.allowTasks,
+                allowPolicy: opts.allowPolicy,
+                allowConfig: opts.allowConfig,
+                allowHooks: opts.allowHooks,
+                allowCI: opts.allowCI,
+                tasksPath: ctx.config.paths.tasks_path,
+                workflowDir: ctx.config.paths.workflow_dir,
+                taskId: opts.taskId,
+                allowTaskOnly: true,
+                emptyAllowMessage: "No staged files and no commit allowlist. Pass --allow <path-prefix>, use --allow-tasks for active task artifacts, or stage files manually.",
+                noMatchMessage: "No changed files matched the commit allowlist (adjust --allow, protected allow flags, or --allow-tasks; otherwise stage files manually).",
+            });
+            if (!opts.quiet) {
+                process.stdout.write(`${infoMessage(`commit auto-staged ${autoStaged.length} path(s) from allowlist`)}\n`);
+            }
+        }
+        await guardCommitCheck({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            baseBranchOverride: opts.baseBranchOverride ?? null,
+            taskId: opts.taskId,
+            message: opts.message,
+            allow: opts.allow,
+            allowBase: opts.allowBase,
+            allowTasks: opts.allowTasks,
+            allowPolicy: opts.allowPolicy,
+            allowConfig: opts.allowConfig,
+            allowHooks: opts.allowHooks,
+            allowCI: opts.allowCI,
+            requireClean: opts.requireClean,
+            quiet: opts.quiet,
+        });
+        const env = buildGitCommitEnv({
+            taskId: opts.taskId,
+            allowTasks: opts.allowTasks,
+            allowBase: opts.allowBase,
+            allowPolicy: opts.allowPolicy,
+            allowConfig: opts.allowConfig,
+            allowHooks: opts.allowHooks,
+            allowCI: opts.allowCI,
+            gitIdentity: await resolveCanonicalGitIdentity(),
+        });
+        await ctx.git.commit({ message: opts.message, env });
+        const primaryCommit = await ctx.git.headHashSubject();
+        await refreshBranchPrArtifactsAfterTaskCommit({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+            quiet: opts.quiet,
+        });
+        ctx.git.invalidateStatus();
+        const refreshCommit = await commitRefreshedTaskArtifacts({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+            sourceMessage: opts.message,
+            quiet: opts.quiet,
+        });
+        if (!opts.quiet) {
+            process.stdout.write(`${successMessage("committed", formatCommitRef(primaryCommit), [
+                autoStaged.length > 0 ? `staged=${autoStaged.join(", ")}` : null,
+                refreshCommit ? `refresh=${formatCommitRef(refreshCommit)}` : null,
+            ]
+                .filter(Boolean)
+                .join("; ") || undefined)}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        const commitFailure = asCommitFailure(err, opts.close ? "close_commit" : "task_commit");
+        if (commitFailure)
+            throw commitFailure;
+        throw mapCoreError(err, { command: "commit", root: opts.rootOverride ?? null });
+    }
+}
+async function cmdCloseCommit(opts) {
+    if (!opts.closeCheckOnly) {
+        await ensureReconciledBeforeMutation({ ctx: opts.ctx, command: "commit" });
+        await resetRebuildableTaskIndexCache(opts.ctx);
+    }
+    let staged = await opts.ctx.git.statusStagedPaths();
+    if (staged.length > 0 && opts.closeUnstageOthers) {
+        if (!opts.closeCheckOnly) {
+            await execFileAsync("git", ["restore", "--staged", "--", "."], {
+                cwd: opts.ctx.resolvedProject.gitRoot,
+                env: gitEnv(),
+            });
+        }
+        staged = opts.closeCheckOnly ? staged : await opts.ctx.git.statusStagedPaths();
+    }
+    if (staged.length > 0 && !opts.closeUnstageOthers) {
+        throw new CliError({
+            exitCode: 5,
+            code: "E_GIT",
+            message: "Staged files exist (close commit requires an empty index; rerun with --unstage-others to auto-unstage).",
+            context: withDiagnosticContext({ command: "commit" }, {
+                state: "close commit cannot run with a non-empty git index",
+                likelyCause: "deterministic close commits only stage the active task artifact scope, but other staged files are already in the index",
+                nextAction: {
+                    command: "git restore --staged -- .",
+                    reason: "clear the current index before rerunning the close commit flow",
+                    reasonCode: "git_close_commit_dirty_index",
+                },
+            }),
+        });
+    }
+    const task = await loadTaskFromContext({ ctx: opts.ctx, taskId: opts.taskId });
+    const msg = await buildCloseCommitMessage({ gitRoot: opts.ctx.resolvedProject.gitRoot, task });
+    const readmeAbs = taskReadmePathForTask({
+        gitRoot: opts.ctx.resolvedProject.gitRoot,
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+    });
+    const readmeRel = readmeAbs.startsWith(opts.ctx.resolvedProject.gitRoot)
+        ? readmeAbs.slice(opts.ctx.resolvedProject.gitRoot.length + 1)
+        : readmeAbs;
+    if (opts.closeCheckOnly) {
+        if (!opts.quiet) {
+            const stagedCount = staged.length;
+            const suffix = stagedCount > 0 && opts.closeUnstageOthers ? `; would unstage ${stagedCount} path(s)` : "";
+            process.stdout.write(`${successMessage("close preflight", opts.taskId, `subject=${msg.subject}${suffix}`)}\n`);
+        }
+        return 0;
+    }
+    if (opts.closeStageTaskArtifacts === true) {
+        if (opts.closeRefreshTaskArtifacts !== false) {
+            await refreshBranchPrArtifactsAfterTaskCommit({
+                ctx: opts.ctx,
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride,
+                taskId: opts.taskId,
+                quiet: opts.quiet,
+            });
+        }
+        opts.ctx.git.invalidateStatus();
+    }
+    await (opts.closeStageTaskArtifacts === true
+        ? stageAllowlist({
+            ctx: opts.ctx,
+            allow: [],
+            allowTasks: true,
+            allowPolicy: opts.allowPolicy,
+            tasksPath: opts.ctx.config.paths.tasks_path,
+            workflowDir: opts.ctx.config.paths.workflow_dir,
+            taskId: opts.taskId,
+            allowTaskOnly: true,
+            emptyAllowMessage: "No changed task artifacts to stage for the deterministic close commit.",
+            noMatchMessage: "No changed files matched the active task artifact scope for the deterministic close commit.",
+        })
+        : stageCloseCommitPaths({
+            ctx: opts.ctx,
+            readmeRel,
+            taskId: opts.taskId,
+            allowPolicy: opts.allowPolicy,
+        }));
+    const ignoredUnstagedTrackedPaths = await resolveIgnoredDirectCloseDirtyPaths({
+        ctx: opts.ctx,
+        taskId: opts.taskId,
+    });
+    await guardCommitCheck({
+        ctx: opts.ctx,
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride,
+        baseBranchOverride: opts.baseBranchOverride ?? null,
+        taskId: opts.taskId,
+        message: msg.subject,
+        allow: [],
+        allowBase: opts.allowBase,
+        allowTasks: true,
+        allowPolicy: opts.allowPolicy,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+        requireClean: true,
+        ignoredUnstagedTrackedPaths,
+        quiet: opts.quiet,
+    });
+    const env = buildGitCommitEnv({
+        taskId: opts.taskId,
+        allowTasks: true,
+        allowBase: opts.allowBase,
+        allowPolicy: opts.allowPolicy,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+        allowStaleDist: true,
+        gitIdentity: await resolveCanonicalGitIdentity(),
+    });
+    await opts.ctx.git.commit({ message: msg.subject, body: msg.body, env });
+    if (!opts.quiet) {
+        const { hash, subject } = await opts.ctx.git.headHashSubject();
+        process.stdout.write(`${successMessage("committed", `${hash?.slice(0, 12) ?? ""} ${subject ?? ""}`.trim())}\n`);
+    }
+    return 0;
+}

package/dist/commands/guard/impl/guard-commit.d.ts

@@ -0,0 +1,3 @@
+import { type GuardCommitOptions } from "./policy.js";
+export declare function cmdGuardCommit(opts: GuardCommitOptions): Promise<number>;
+//# sourceMappingURL=guard-commit.d.ts.map

package/dist/commands/guard/impl/guard-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/guard-commit.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAExE,wBAAsB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa9E"}

package/dist/commands/guard/impl/guard-commit.js

@@ -0,0 +1,21 @@
+import { mapCoreError } from "../../../cli/error-map.js";
+import { CliError } from "../../../shared/errors.js";
+import { loadCommandContext } from "../../shared/task-backend.js";
+import { ensureReconciledBeforeMutation } from "../../shared/reconcile-check.js";
+import { guardCommitCheck } from "./policy.js";
+export async function cmdGuardCommit(opts) {
+    try {
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        await ensureReconciledBeforeMutation({ ctx, command: "guard commit" });
+        await guardCommitCheck({ ...opts, ctx });
+        if (!opts.quiet)
+            process.stdout.write("OK\n");
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "guard commit", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/guard/impl/policy.d.ts

@@ -14,6 +14,7 @@ export type GuardCommitOptions = {
     allowHooks: boolean;
     allowCI: boolean;
     requireClean: boolean;
+    ignoredUnstagedTrackedPaths?: string[];
     quiet: boolean;
 };
 export declare function guardCommitCheck(opts: GuardCommitOptions): Promise<void>;

package/dist/commands/guard/impl/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/policy.ts"],"names":[],"mappings":"AAKA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEvF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+C9E"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/policy.ts"],"names":[],"mappings":"AAKA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEvF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,2BAA2B,CAAC,EAAE,MAAM,EAAE,CAAC;IACvC,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwD9E"}

package/dist/commands/guard/impl/policy.js

@@ -4,10 +4,17 @@ import { gitCurrentBranch } from "../../shared/git-ops.js";
 import { throwIfPolicyDenied } from "../../shared/policy-deny.js";
 import { loadCommandContext } from "../../shared/task-backend.js";
 export async function guardCommitCheck(opts) {
-    const ctx = opts.ctx ??
+    const loadedContext = opts.ctx ??
         (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+    const ctx = loadedContext;
     const staged = await ctx.git.statusStagedPaths();
-    const unstagedTrackedPaths = opts.requireClean ? await ctx.git.statusUnstagedTrackedPaths() : [];
+    const ignoredUnstagedTrackedPaths = new Set((opts.ignoredUnstagedTrackedPaths ?? []).map((value) => value.trim()).filter(Boolean));
+    const rawUnstagedTrackedPaths = opts.requireClean
+        ? await ctx.git.statusUnstagedTrackedPaths()
+        : [];
+    const unstagedTrackedPaths = opts.requireClean
+        ? rawUnstagedTrackedPaths.filter((relPath) => !ignoredUnstagedTrackedPaths.has(relPath))
+        : [];
     const inBranchPr = ctx.config.workflow_mode === "branch_pr";
     const explicitBaseBranch = opts.baseBranchOverride?.trim();
     const baseBranch = inBranchPr

package/dist/commands/guard/impl/suggest.d.ts

@@ -0,0 +1,6 @@
+export declare function cmdGuardSuggestAllow(opts: {
+    cwd: string;
+    rootOverride?: string;
+    format: "lines" | "args";
+}): Promise<number>;
+//# sourceMappingURL=suggest.d.ts.map

package/dist/commands/guard/impl/suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/suggest.ts"],"names":[],"mappings":"AAKA,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB"}

package/dist/commands/guard/impl/suggest.js

@@ -0,0 +1,33 @@
+import { mapCoreError } from "../../../cli/error-map.js";
+import { CliError } from "../../../shared/errors.js";
+import { loadCommandContext } from "../../shared/task-backend.js";
+import { suggestAllowPrefixes } from "./allow.js";
+export async function cmdGuardSuggestAllow(opts) {
+    try {
+        const ctx = await loadCommandContext({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const staged = await ctx.git.statusStagedPaths();
+        if (staged.length === 0) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "No staged files (git index empty)",
+            });
+        }
+        const prefixes = suggestAllowPrefixes(staged);
+        if (opts.format === "args") {
+            const args = prefixes.map((p) => `--allow ${p}`).join(" ");
+            process.stdout.write(`${args}\n`);
+        }
+        else {
+            for (const prefix of prefixes)
+                process.stdout.write(`${prefix}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        throw mapCoreError(err, { command: "guard suggest-allow", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/hooks/index.d.ts

@@ -1,4 +1,7 @@
 export declare const HOOK_NAMES: readonly ["commit-msg", "pre-commit", "pre-push", "post-merge"];
+export declare function resolvePrePushHookScriptPath(gitRoot: string, opts?: {
+    bundledScriptPath?: string;
+}): Promise<string | null>;
 export declare function cmdHooksInstall(opts: {
     cwd: string;
     rootOverride?: string;