@lannguyensi/harness 0.31.0 → 0.33.0

package/dist/policy-packs/builtin/solution-acceptance-runtime.js

@@ -0,0 +1,321 @@
+// Builtin Policy Pack runtime: `solution-acceptance` (consumer half).
+//
+// The PRODUCER lives in grounding-mcp (`solution_evaluate` / `solution_gate`,
+// @lannguyensi/grounding-mcp >= 0.3.2): it runs a real `preflight run --json`
+// and records a HEAD-pinned verdict marker outside the agent-writable
+// evidence ledger. harness is the CONSUMER: it reimplements the marker read +
+// gate decision here so it carries NO grounding-mcp runtime dependency (the
+// same precedent as understanding-before-execution reimplementing its
+// approval-marker read). Schema parity with the producer is pinned by a
+// golden-fixture test against a real 0.3.2 marker; if grounding-mcp changes
+// the Verdict shape, that test fails loudly.
+//
+// Two enforcement surfaces are built on top of these helpers (see the pack
+// definition + the two hook verbs):
+//
+//   1. completion-gate — denies the task-finishing tools (agent-tasks MCP
+//      task_finish / task_submit_pr / task_merge / pull_requests_merge, plus
+//      a belt-and-suspenders bash match for `git push` / `gh pr merge`)
+//      unless a ready verdict exists at the CURRENT git HEAD.
+//
+//   2. write-guard — the actual anti-forgery closure. Relocating the verdict
+//      dir is NOT sufficient: understanding-gate allows all Bash post-approval
+//      (it does no write-target inspection in the allow path), so an approved
+//      agent could otherwise hand-write a `ready:true` marker. The write-guard
+//      blocks the agent's enumerated write paths into the verdict dir.
+//
+// Anti-forgery honesty (operator decision, 2026-05-30): v1 closes the
+// ENUMERATED-WRITE-PATH residual (the Bash/Edit/Write spellings below), NOT
+// arbitrary same-uid forgery. A `0500` chmod on the dir would be incoherent
+// here because the producer (grounding-mcp) and the agent share a uid, so it
+// would block the producer too. Content-authenticity against an unguarded
+// write primitive is closed by marker signing, a cross-repo follow-up that
+// already touches the producer. This module must NOT claim the residual is
+// fully closed.
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const PACK_NAME = "solution-acceptance";
+/**
+ * agent-tasks MCP verbs that mark a completion boundary. The gate fires on
+ * these (matched by exact tool name `mcp__agent-tasks__<verb>`). These MCP
+ * choke points are reliable: unlike the bash matcher they cannot be evaded
+ * by shell indirection.
+ */
+export const DEFAULT_PROTECTED_COMPLETION_TOOLS = [
+    "task_finish",
+    "task_submit_pr",
+    "task_merge",
+    "pull_requests_merge",
+];
+/**
+ * Belt-and-suspenders bash matcher for `git push` / `gh pr merge`. Regex on
+ * the typed command, so an env-var indirection
+ * (`B=main && git push origin $B`) evades it — the MCP verbs above are the
+ * load-bearing choke points; hardening this is follow-up `7207d8f9`.
+ * Tolerates a leading `cd … &&`, inline `VAR=val` assignments, and `git -C
+ * <path> push`.
+ */
+export const DEFAULT_PUSH_BASH_RE = /(?:^|\n|;|\||&&|\()\s*(?:\w+=\S+\s+)*(?:git(?:\s+-C\s+\S+)?\s+push|gh\s+pr\s+merge)\b/;
+/**
+ * Resolve the completion verbs the gate fires on: the pack's
+ * `config.protected_completion_tools` override, else the default set.
+ * Always non-empty. Lives here (not in the pack module) so the
+ * completion-gate hook can share it without importing the pack's zod
+ * surface (mirrors `resolveProtectedBranches` in branch-protection-runtime).
+ */
+export function resolveProtectedCompletionTools(pack) {
+    const raw = pack.config["protected_completion_tools"];
+    if (Array.isArray(raw) &&
+        raw.length > 0 &&
+        raw.every((t) => typeof t === "string" && t.length > 0)) {
+        return raw;
+    }
+    return [...DEFAULT_PROTECTED_COMPLETION_TOOLS];
+}
+/** Env knob that overrides the verdict directory (mirrors the producer). */
+export const VERDICT_DIR_ENV = "SOLUTION_VERDICT_DIR";
+/**
+ * Env knob that supplies the verdict id for SOLO / non-agent-tasks sessions.
+ * The completion-gate consults it ONLY when no agent-tasks `active-claim` is
+ * recorded (resolution order: active-claim first, then this env, then
+ * fail-closed), so a claimed session's id stays authoritative and cannot be
+ * redirected by an env var. A sessionId fallback is intentionally still NOT a
+ * source (the wrong-scope bug class understanding-gate closed).
+ */
+export const VERDICT_ID_ENV = "SOLUTION_VERDICT_ID";
+/**
+ * Stable tail of the default verdict dir. The write-guard's reference
+ * detection matches on this so ANY spelling of the home prefix is caught
+ * (`~/.local/state/...`, `$HOME/...`, `$XDG_STATE_HOME/...`, the literal
+ * absolute path).
+ */
+export const VERDICT_DIR_TAIL = path.join("agent-grounding", "solution-verdicts");
+/**
+ * Resolve the verdict directory. Resolution order MUST match grounding-mcp's
+ * `verdictDir()` so the consumer reads exactly where the producer writes
+ * (operator decision B: both sides use the producer default; no apply-time
+ * env threading, no divergence risk):
+ *   1. SOLUTION_VERDICT_DIR
+ *   2. $XDG_STATE_HOME/agent-grounding/solution-verdicts
+ *   3. ~/.local/state/agent-grounding/solution-verdicts
+ */
+export function verdictDir(env = process.env, homedir = os.homedir) {
+    const override = env[VERDICT_DIR_ENV];
+    if (override && override.trim().length > 0)
+        return override;
+    const xdg = env["XDG_STATE_HOME"];
+    const base = xdg && xdg.trim().length > 0 ? xdg : path.join(homedir(), ".local", "state");
+    return path.join(base, "agent-grounding", "solution-verdicts");
+}
+/**
+ * Reduce a verdict id to a single safe path segment. Mirrors the producer's
+ * `sanitizeVerdictId`: non-portable chars collapse to `_`, `path.basename`
+ * strips any residual separator (path-traversal guard), empty / dot-only ids
+ * are rejected.
+ */
+export function sanitizeVerdictId(id) {
+    const cleaned = id.replace(/[^A-Za-z0-9._-]/g, "_");
+    const base = path.basename(cleaned);
+    if (base === "" || base === "." || base === "..") {
+        throw new Error(`invalid verdict id: ${JSON.stringify(id)}`);
+    }
+    return base;
+}
+export function verdictPathFor(dir, id) {
+    return path.join(dir, `${sanitizeVerdictId(id)}.json`);
+}
+/**
+ * Resolve the explicit verdict id from `SOLUTION_VERDICT_ID`, or null when it
+ * is unset, blank, or not a safe single path segment. Validated through
+ * `sanitizeVerdictId` so a traversal-y or empty value fails closed here
+ * (returns null -> the gate denies) rather than reaching the marker read. This
+ * is the solo / non-agent-tasks fallback the completion-gate uses only when no
+ * active-claim is present.
+ */
+export function resolveExplicitVerdictId(env = process.env) {
+    const raw = env[VERDICT_ID_ENV];
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    try {
+        sanitizeVerdictId(trimmed);
+    }
+    catch {
+        return null;
+    }
+    return trimmed;
+}
+/**
+ * Read + validate the verdict marker for `id`, or null when it is absent,
+ * unparseable, a symlink, or not a regular file. The lstat + symlink reject
+ * mirrors `checkApprovalMarker`: defense-in-depth against a symlink planted
+ * at the marker path pointing at agent-controlled content.
+ */
+export function readVerdict(dir, id) {
+    let p;
+    try {
+        p = verdictPathFor(dir, id);
+    }
+    catch {
+        return null; // invalid id
+    }
+    let stat;
+    try {
+        stat = fs.lstatSync(p);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        return null;
+    let raw;
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.id !== "string" ||
+            typeof parsed.head !== "string" ||
+            typeof parsed.ready !== "boolean") {
+            return null;
+        }
+        return {
+            id: parsed.id,
+            head: parsed.head,
+            ready: parsed.ready,
+            confidence: typeof parsed.confidence === "number" ? parsed.confidence : 0,
+            blockers: Array.isArray(parsed.blockers) ? parsed.blockers : [],
+            timestamp: typeof parsed.timestamp === "string" ? parsed.timestamp : "",
+            source: typeof parsed.source === "string" ? parsed.source : "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Evaluate the gate for `id` at `currentHead`. Mirrors grounding-mcp
+ * `evaluateGate` EXACTLY: allow iff `verdict.ready === true` AND
+ * `verdict.head === currentHead`. `confidence` is INFORMATIONAL ONLY and
+ * never gates — a `ready:true confidence:0` verdict at HEAD passes — so the
+ * harness consumer stays byte-parity with the producer's `solution_gate`
+ * (an operator running `solution_gate` and the harness gate must agree).
+ */
+export function evaluateGate(verdict, currentHead, id) {
+    if (!verdict) {
+        return {
+            allowed: false,
+            reason: `no solution-acceptance verdict recorded for "${id}" (run mcp__agent-grounding__solution_evaluate first)`,
+            verdict: null,
+        };
+    }
+    if (!verdict.ready) {
+        const why = verdict.blockers.length > 0 ? `: ${verdict.blockers.join("; ")}` : "";
+        return {
+            allowed: false,
+            reason: `solution-acceptance verdict for "${id}" is not ready${why} (fix, then re-run solution_evaluate)`,
+            verdict,
+        };
+    }
+    if (!currentHead) {
+        return {
+            allowed: false,
+            reason: `cannot resolve the current git HEAD to confirm the verdict for "${id}" is at HEAD`,
+            verdict,
+        };
+    }
+    if (verdict.head !== currentHead) {
+        return {
+            allowed: false,
+            reason: `stale solution-acceptance verdict for "${id}": recorded at ${verdict.head.slice(0, 7)}, current HEAD ${currentHead.slice(0, 7)} (re-run solution_evaluate after the rework)`,
+            verdict,
+        };
+    }
+    return {
+        allowed: true,
+        reason: `solution-acceptance verdict for "${id}" is ready at HEAD ${currentHead.slice(0, 7)} (confidence ${Math.round(verdict.confidence * 100)}%)`,
+        verdict,
+    };
+}
+// ── Write-guard target detection ──
+/**
+ * Is `target` inside `dir` after resolution? Used for the path-tool arm
+ * (Write/Edit/MultiEdit/NotebookEdit `file_path`) and for a Bash shell whose
+ * cwd is the protected dir. A relative `target` resolves against `cwd`
+ * (falling back to process.cwd()).
+ */
+export function isInsideDir(target, dir, cwd) {
+    if (typeof target !== "string" || target.length === 0)
+        return false;
+    const absDir = path.resolve(dir);
+    const absTarget = path.isAbsolute(target)
+        ? path.resolve(target)
+        : path.resolve(cwd ?? process.cwd(), target);
+    const rel = path.relative(absDir, absTarget);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * Does a Bash command TEXTUALLY reference the verdict dir? Catches the
+ * enumerated spellings without shell-evaluating (same contract as
+ * read-only-bash):
+ *   - the literal absolute dir,
+ *   - the `$SOLUTION_VERDICT_DIR` env token,
+ *   - the stable tail `agent-grounding/solution-verdicts` (covers `~/...`,
+ *     `$HOME/...`, `$XDG_STATE_HOME/...`, and absolute spellings), and
+ *   - the dir's LEAF segment (`solution-verdicts` for the default).
+ *
+ * The leaf segment closes the `cd <parent> && write <relative-into-dir>`
+ * descent (where the parent path and the child redirect never form the
+ * contiguous tail): ANY relative write into the dir from a cwd that is not
+ * the dir itself must name the leaf somewhere in the command, and a
+ * `cd <…/leaf>` to first make cwd==dir would itself contain the leaf. The
+ * write-guard's cwd-inside check covers the only remaining case (cwd already
+ * inside the dir). The leaf needle is length-guarded so a short custom
+ * basename does not over-block; the default leaf is distinctive, and a
+ * non-default dir already warns at validate time.
+ *
+ * `chmod`/`chattr` that target the dir are caught the same way, so the
+ * FS-perm-loosening attack is covered.
+ *
+ * Honest residual: a path constructed at runtime inside an interpreter with
+ * no textual reference (e.g. base64-decoded inside `python3 -c`) is NOT
+ * caught. That is what marker signing (follow-up) closes.
+ */
+export function bashReferencesVerdictDir(command, dir) {
+    if (typeof command !== "string" || command.length === 0)
+        return false;
+    const leaf = path.basename(dir);
+    // Direct literal references + the distinctive leaf segment.
+    if (command.includes(dir) ||
+        command.includes(VERDICT_DIR_ENV) ||
+        command.includes(VERDICT_DIR_TAIL) ||
+        (leaf.length >= 6 && command.includes(leaf))) {
+        return true;
+    }
+    // Glob-obscured references. bash expands `*?[` against EXISTING paths at
+    // runtime, so a glob like `solution-ver*/<id>.json` reaches the dir
+    // without the literal leaf ever appearing in the command text, and a
+    // matching glob can OVERWRITE an existing marker (flipping ready:false ->
+    // true). We cannot safely expand globs (that is the shell-eval surface
+    // read-only-bash refuses), so when a glob metachar is present we match the
+    // leaf's distinctive sub-words: a single glob can split the hyphenated
+    // leaf but not erase every >=6-char word of it (`solution-ver*` keeps
+    // "solution"; `solu*verdicts` keeps "verdicts"). The leaf words, not the
+    // parent segment, are used on purpose: the parent here is `agent-grounding`,
+    // which is also a repo name and would over-block legitimate work. A command
+    // that globs EVERY path segment is the residual the marker-signing
+    // follow-up closes.
+    if (/[*?[]/.test(command)) {
+        const leafWords = leaf.split(/[^A-Za-z0-9]+/).filter((w) => w.length >= 6);
+        if (leafWords.some((w) => command.includes(w)))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=solution-acceptance-runtime.js.map

package/dist/policy-packs/builtin/solution-acceptance-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solution-acceptance-runtime.js","sourceRoot":"","sources":["../../../src/policy-packs/builtin/solution-acceptance-runtime.ts"],"names":[],"mappings":"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"}

package/dist/policy-packs/builtin/solution-acceptance.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { PolicyPack } from "../../schema/index.js";
+import { type Runtime } from "../runtime.js";
+import type { PackContribution } from "../types.js";
+import { PACK_NAME } from "./solution-acceptance-runtime.js";
+export { PACK_NAME };
+/**
+ * Zod schema for this pack's `config:` block. Strict by design so typo'd
+ * keys fail loud at lint time (mirrors sibling packs).
+ */
+export declare const configSchema: z.ZodObject<{
+    protected_completion_tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ux: z.ZodOptional<z.ZodObject<{
+        cannot: z.ZodString;
+        required: z.ZodArray<z.ZodString, "many">;
+        run: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        cannot: string;
+        required: string[];
+        run: string[];
+    }, {
+        cannot: string;
+        required: string[];
+        run: string[];
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    ux?: {
+        cannot: string;
+        required: string[];
+        run: string[];
+    } | undefined;
+    protected_completion_tools?: string[] | undefined;
+}, {
+    ux?: {
+        cannot: string;
+        required: string[];
+        run: string[];
+    } | undefined;
+    protected_completion_tools?: string[] | undefined;
+}>;
+export declare function resolve(pack: PolicyPack, runtime?: Runtime): {
+    contribution: PackContribution;
+    warnings: string[];
+};

package/dist/policy-packs/builtin/solution-acceptance.js

@@ -0,0 +1,185 @@
+// Builtin Policy Pack: `solution-acceptance`.
+//
+// Consumer half of the solution-acceptance gate (the "Verifier-gated Done"
+// anti-lazyness mechanism). Makes a task's completion EARNED from a real
+// preflight run, not self-attested. The producer is grounding-mcp's
+// `solution_evaluate` (>= 0.3.2); harness reads the HEAD-pinned verdict
+// marker it writes and gates the task-finishing tools on it.
+//
+// Two PreToolUse hooks, both `blocking: hard`:
+//
+//   1. completion-gate (`harness pack hook solution-acceptance`): denies the
+//      agent-tasks completion verbs (task_finish / task_submit_pr /
+//      task_merge / pull_requests_merge) — and, belt-and-suspenders, a
+//      `git push` / `gh pr merge` bash command — unless a READY verdict
+//      exists at the CURRENT git HEAD. The verdict id is the active-claim
+//      task id; with no active claim the gate fails CLOSED.
+//
+//   2. write-guard (`harness pack hook solution-acceptance-writeguard`): the
+//      actual anti-forgery closure. Relocating the verdict dir is NOT enough
+//      — understanding-gate allows all Bash post-approval — so this hook
+//      blocks the agent's enumerated write paths (Bash redirects/`tee`/`mv`/
+//      `cp`/`ln`/interpreter writes that reference the dir, `chmod`/`chattr`
+//      on the dir, and Write/Edit/MultiEdit/NotebookEdit whose `file_path`
+//      lands inside the dir). The ONLY remaining writer is the producer
+//      (the operator-launched grounding-mcp MCP server, which runs real
+//      preflight and does not flow through the agent's gated tool surface).
+//
+// Anti-forgery scope (operator decision, 2026-05-30): v1 closes the
+// ENUMERATED-WRITE-PATH residual, NOT arbitrary same-uid forgery. Content
+// signing (a cross-repo follow-up that also touches the producer) is what
+// closes an unguarded write primitive. See solution-acceptance-runtime.ts.
+//
+// Pack is OFF by default; enable per-installation via
+// `harness pack add solution-acceptance`. The `full` init template wires it
+// as a disabled-by-policy exemplar... (see templates.ts). It REQUIRES
+// grounding-mcp under `tools.mcp` (the producer) and the `preflight` binary
+// on PATH; `harness validate` / `harness doctor` warn when the producer is
+// absent (a missing producer means the gate can never see a verdict and
+// would deadlock).
+import { z } from "zod";
+import { PolicyUxSchema } from "../../schema/policies.js";
+import { DEFAULT_RUNTIME } from "../runtime.js";
+import { PACK_NAME, resolveProtectedCompletionTools, } from "./solution-acceptance-runtime.js";
+export { PACK_NAME };
+/**
+ * Zod schema for this pack's `config:` block. Strict by design so typo'd
+ * keys fail loud at lint time (mirrors sibling packs).
+ */
+export const configSchema = z
+    .object({
+    // Override the agent-tasks completion verbs the gate fires on. The
+    // names are bare verbs (e.g. "task_finish"); the matcher prefixes
+    // `mcp__agent-tasks__`. Defaults to DEFAULT_PROTECTED_COMPLETION_TOOLS.
+    protected_completion_tools: z.array(z.string().min(1)).min(1).optional(),
+    // `ux` renders the agent-facing remediation block when a gate trips.
+    ux: PolicyUxSchema.optional(),
+})
+    .strict();
+const HOOK_NAME_PREFIX = `policy-pack:${PACK_NAME}`;
+const COMPLETION_BLOCKER_COMMAND = "harness pack hook solution-acceptance";
+const WRITEGUARD_BLOCKER_COMMAND = "harness pack hook solution-acceptance-writeguard";
+const WRITEGUARD_MATCH_CLAUDE = "Edit|Write|MultiEdit|NotebookEdit|Bash";
+const WRITEGUARD_MATCH_CODEX = "apply_patch|Bash";
+/**
+ * PreToolUse `match` for the completion-gate. `Bash` is always included for
+ * the `git push` / `gh pr merge` belt-and-suspenders arm; on the Claude
+ * runtime the agent-tasks MCP verbs are appended (the reliable choke
+ * points). Codex has no agent-tasks MCP surface here, so it gets the Bash
+ * arm only (documented limitation).
+ */
+function completionMatch(runtime, tools) {
+    if (runtime === "codex")
+        return "Bash";
+    const mcp = tools.map((t) => `mcp__agent-tasks__${t}`).join("|");
+    return `Bash|${mcp}`;
+}
+function buildHooks(runtime, tools) {
+    const writeGuardMatch = runtime === "codex" ? WRITEGUARD_MATCH_CODEX : WRITEGUARD_MATCH_CLAUDE;
+    return [
+        {
+            name: `${HOOK_NAME_PREFIX}:completion-gate`,
+            event: "PreToolUse",
+            match: completionMatch(runtime, tools),
+            command: COMPLETION_BLOCKER_COMMAND,
+            blocking: "hard",
+            budget_ms: 5000,
+            description: "Blocker: deny the task-finishing tools (agent-tasks completion verbs + `git push` / `gh pr merge`) unless a ready solution-acceptance verdict exists at the current git HEAD. Fail-closed.",
+        },
+        {
+            name: `${HOOK_NAME_PREFIX}:write-guard`,
+            event: "PreToolUse",
+            match: writeGuardMatch,
+            command: WRITEGUARD_BLOCKER_COMMAND,
+            blocking: "hard",
+            budget_ms: 5000,
+            description: "Anti-forgery write-guard: deny any agent write into the solution-verdict dir (redirects/tee/mv/cp/ln/interpreter writes that reference it, chmod/chattr on it, and path-tool file_path inside it). The producer (grounding-mcp MCP server) is the only legitimate writer.",
+        },
+    ];
+}
+function buildInstructions(pack, tools, runtime) {
+    const description = pack.description?.trim() ?? "";
+    return `# Policy Pack: ${PACK_NAME}
+
+> Operator audit copy. This pack makes task completion EARNED from a real
+> preflight run (the producer, grounding-mcp \`solution_evaluate\`) rather
+> than self-attested, and closes the enumerated-write-path forgery residual
+> on the verdict marker.
+
+## Runtime
+
+${runtime}
+
+## Producer (required)
+
+This pack is a pure CONSUMER. It needs the producer wired:
+
+- \`grounding-mcp\` (>= 0.3.2) declared under \`tools.mcp\`, exposing
+  \`solution_evaluate\` / \`solution_gate\`.
+- The \`preflight\` binary (\`@lannguyensi/agent-preflight\`) on PATH (or
+  \`SOLUTION_PREFLIGHT_BIN\`), which \`solution_evaluate\` shells out to.
+
+If the producer is absent the gate can never see a verdict and would
+deadlock; \`harness validate\` / \`harness doctor\` warn about this.
+
+## Effect
+
+Two \`PreToolUse\` hooks (both blocking: hard) are wired into the
+harness-managed settings:
+
+1. \`completion-gate\` (\`${COMPLETION_BLOCKER_COMMAND}\`): denies the
+   completion verbs unless a READY verdict exists at the CURRENT git HEAD.
+   Gated tools: ${tools.map((t) => `\`${t}\``).join(", ")} (matched as
+   \`mcp__agent-tasks__<verb>\`), plus a \`git push\` / \`gh pr merge\` bash
+   match. The verdict id is the active-claim task id; with no active claim
+   the gate fails CLOSED.
+
+2. \`write-guard\` (\`${WRITEGUARD_BLOCKER_COMMAND}\`): denies any agent write
+   into the verdict dir. The only legitimate writer is the producer.
+
+## Earning a verdict
+
+\`\`\`
+mcp__agent-grounding__solution_evaluate({ id: "<active-task-id>" })
+\`\`\`
+
+This runs \`preflight run --json\` and records a HEAD-pinned verdict. A
+not-ready run (failing checks, dirty tree) records a not-ready verdict; any
+commit after a green run shifts HEAD and invalidates it, so re-run after
+every change.
+
+## Anti-forgery scope (v1)
+
+v1 closes the ENUMERATED-WRITE-PATH residual: the write-guard blocks the
+agent's Bash/Edit/Write spellings that target the verdict dir. It does NOT
+close arbitrary same-uid forgery (an unguarded write primitive). Marker
+signing — a follow-up that also changes the producer — is what closes
+content-authenticity. A \`0500\` chmod on the dir is deliberately NOT used:
+producer and agent share a uid, so it would block the producer too.
+
+## Out of scope (v1)
+
+- Goodhart test-count-delta guard (producer side).
+- LLM-judge layer / relative best-of-N ranking.
+- Explicit verdict-id source for untasked sessions (follow-up; today an
+  untasked session fails closed).
+
+## Pack metadata
+${description ? `\n> ${description.replace(/\n/g, "\n> ")}\n` : ""}
+- Source: \`builtin\`
+- Pack: \`${PACK_NAME}\`
+- Runtime: \`${runtime}\`
+`;
+}
+export function resolve(pack, runtime = DEFAULT_RUNTIME) {
+    const tools = resolveProtectedCompletionTools(pack);
+    const hooks = buildHooks(runtime, tools);
+    const files = [
+        {
+            relativePath: `policy-packs/${PACK_NAME}/instructions.md`,
+            content: buildInstructions(pack, tools, runtime),
+        },
+    ];
+    return { contribution: { hooks, files }, warnings: [] };
+}
+//# sourceMappingURL=solution-acceptance.js.map

package/dist/policy-packs/builtin/solution-acceptance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solution-acceptance.js","sourceRoot":"","sources":["../../../src/policy-packs/builtin/solution-acceptance.ts"],"names":[],"mappings":"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"}

package/dist/policy-packs/builtin/understanding-before-execution.d.ts

@@ -6,6 +6,17 @@ export declare const PACK_NAME = "understanding-before-execution";
 export declare const VERSION_COMMAND: readonly [string, string];
 export type Mode = "fast_confirm" | "grill_me" | "strict";
 export declare const DEFAULT_MODE: Mode;
+/**
+ * The agent-facing `required:` phrase for the understanding-gate deny
+ * envelope, derived from the configured mode. Only `strict` forces
+ * `requiresHumanApproval` (see {@link modeFriction}); in `fast_confirm`
+ * and `grill_me` the agent self-attests and a structural validator
+ * checks the report, so naming it "human-approved" there would overstate
+ * what the gate actually enforces. Generation surfaces (the Custom
+ * composer, the init templates) call this so the wording can never drift
+ * from the mode it is paired with.
+ */
+export declare function understandingApprovalRequirement(mode: Mode): string;
 export declare function isMode(value: unknown): value is Mode;
 /**
  * Zod schema for this pack's `config:` block. Surfaced via

package/dist/policy-packs/builtin/understanding-before-execution.js

@@ -29,6 +29,21 @@ export const VERSION_COMMAND = [
 ];
 const MODES = ["fast_confirm", "grill_me", "strict"];
 export const DEFAULT_MODE = "grill_me";
+/**
+ * The agent-facing `required:` phrase for the understanding-gate deny
+ * envelope, derived from the configured mode. Only `strict` forces
+ * `requiresHumanApproval` (see {@link modeFriction}); in `fast_confirm`
+ * and `grill_me` the agent self-attests and a structural validator
+ * checks the report, so naming it "human-approved" there would overstate
+ * what the gate actually enforces. Generation surfaces (the Custom
+ * composer, the init templates) call this so the wording can never drift
+ * from the mode it is paired with.
+ */
+export function understandingApprovalRequirement(mode) {
+    return mode === "strict"
+        ? "a human-approved Understanding Report for this session"
+        : "an approved Understanding Report for this session";
+}
 const HOOK_NAME_PREFIX = `policy-pack:${PACK_NAME}`;
 // Per-runtime hook surface. Claude Code keys on tool name (Edit|Write|Bash);
 // Codex's write surface is `apply_patch` plus shell tool aliases used by