@lannguyensi/harness 0.38.0 → 0.40.0

package/dist/cli/init/templates.d.ts

@@ -1,4 +1,4 @@
 export declare const MINIMAL_TEMPLATE = "# ~/.harness/harness.yaml (legacy: ~/.claude/harness.yaml)\n#\n# Bootstrapped by `harness init --template minimal`.\n#\n# This is the empty-but-valid manifest. Run `harness validate` to confirm it\n# parses, then add entries under the five top-level keys:\n#\n#   grounding:  evidence-ledger + claim-gate config (see docs/ARCHITECTURE.md \u00A72)\n#   tools:      mcp / cli / skills / builtin inventory   (\u00A73)\n#   memory:     directories, retention, scopes           (\u00A74)\n#   hooks:      event-bound shell commands               (\u00A75)\n#   policies:   named rules that bind hooks to triggers  (\u00A76)\n#\n# Phase 2 verbs to add entries safely: `harness add mcp <name> ...`,\n# `harness add cli`, `harness add hook`, `harness add skill`.\n# Per-machine overrides live at ~/.harness/machines/<discriminator>.harness.overrides.yaml\n# (ARCHITECTURE.md \u00A78) for paths that vary per host.\n#\n# Docs: https://github.com/LanNguyenSi/harness\n\nversion: 1\n";
-export declare const FULL_TEMPLATE = "# ~/.harness/harness.yaml (legacy: ~/.claude/harness.yaml)\n#\n# Bootstrapped by `harness init --template full`. The reference manifest:\n# every example policy from docs/examples/full-manifest.yaml wired through\n# the generic `harness policy intercept` engine, so no external shell\n# scripts under ~/.claude/hooks/ are required.\n#\n# Canonical source for the policy + policy_packs sections is\n# docs/examples/full-manifest.yaml. A parity vitest\n# (tests/cli/init-full-template-parity.test.ts) fails the build if the\n# two diverge on policy names or load-bearing fields.\n#\n# What you still need on PATH (the wizard offers to `npm i -g` these on\n# init): agent-tasks-mcp-bridge, grounding-mcp, memory-router-*,\n# understanding-gate-claude-*.\n\nversion: 1\n\ngrounding:\n  session:\n    auto_start: true\n    id_format: \"gs-{repo}-{rand:8}\"\n  evidence_ledger:\n    path: ~/.evidence-ledger/ledger.db\n    retention_days: 90\n  policies_source: ~/.claude/harness.d/policies/claim-gate.yaml\n\ntools:\n  mcp:\n    # codebase-oracle (the Pandora RAG MCP server) is intentionally NOT\n    # in the Full default. It is published as\n    # `@lannguyensi/codebase-oracle` and works fine standalone, but it\n    # is an opinionated workflow add-on (multi-repo semantic search)\n    # rather than infrastructure harness itself assumes. Operators who\n    # want it wire it explicitly:\n    #   npm i -g @lannguyensi/codebase-oracle\n    #   harness add mcp codebase-oracle --command codebase-oracle,mcp\n    # Set ORACLE_SCAN_ROOT (absolute path; tilde is not expanded by the\n    # MCP env block) and OPENAI_API_KEY (or switch providers via\n    # ORACLE_LLM_PROVIDER) before the first call.\n    - name: agent-tasks\n      # Zero-setup entry: `@agent-tasks/mcp-bridge` exposes the\n      # `agent-tasks-mcp-bridge` binary on PATH. The bridge owns token\n      # storage and defaults to the hosted backend; override with\n      # `AGENT_TASKS_BASE_URL` / `AGENT_TASKS_TOKEN` for self-hosted.\n      # `min_version` floor: 0.6.0 added the `--version` short-circuit\n      # the doctor probe needs (PR agent-tasks/240, release-cut PR 241).\n      # Bump the floor whenever a fix you depend on lands; loose floors\n      # are fine, the point is the drift signal not pinning a specific cut.\n      command: [agent-tasks-mcp-bridge]\n      min_version: \"0.6.0\"\n      health:\n        verb: projects_list\n        timeout_ms: 5000\n      enabled: true\n    - name: grounding-mcp\n      # Published bin from `@lannguyensi/grounding-mcp`. No env is set:\n      # the bundled default resolves to `~/.evidence-ledger/ledger.db`\n      # via os.homedir() at startup. Passing a literal tilde in env\n      # bypasses shell expansion and creates rogue cwd-relative DB files\n      # (see agent-tasks/42d224a6 incident). `min_version` floor: 0.2.0\n      # added the `--version` short-circuit the doctor probe needs (PR\n      # agent-grounding/76, release-cut PR 77).\n      command: [grounding-mcp]\n      min_version: \"0.2.0\"\n      health:\n        verb: ledger_status\n        timeout_ms: 5000\n      enabled: true\n\n  cli:\n    - name: gh\n      binary: gh\n      required: true\n\n  skills:\n    enabled:\n      - simplify\n      - init\n      - review\n      - security-review\n    source_dirs:\n      - ~/.claude/skills\n\n  builtin:\n    known: [Read, Edit, Write, Bash, Agent, Skill, TaskCreate, Glob, Grep]\n\nmemory:\n  directories:\n    - path: ~/.claude/projects/{project}/memory\n      scope: project\n  router:\n    # Published bin from `@lannguyensi/memory-router`.\n    # `min_version` floor: 0.3.0 added the `--version` short-circuit\n    # the doctor probe needs (PR agent-memory/40, release-cut PR 41).\n    command: [memory-router-user-prompt-submit]\n    min_version: \"0.3.0\"\n    enabled: true\n  retention:\n    staleness_days: 180\n    broken_refs: warn\n  scopes:\n    default: project\n    allowed: [project, user]\n\n# All PreToolUse hooks share the generic `harness policy intercept` CLI\n# entrypoint. The engine reads the tool event on stdin, evaluates whichever\n# policy below has a matching trigger (`match` + optional `bash_match`),\n# and emits Claude Code's deny envelope when the required ledger tag is\n# absent. No external shell scripts are required.\n#\n# The `git-preflight` SessionStart hook is the producer side of the\n# `preflight-before-*` policies: `harness session-start preflight` runs\n# agent-preflight against the session cwd and, on a ready:true result,\n# records `preflight:${REPO}` to the evidence ledger. It needs the\n# `preflight` binary on PATH (`npm i -g @lannguyensi/agent-preflight`); when\n# that is absent the hook logs to stderr and exits 0, so the session is\n# never broken \u2014 the preflight gates just stay closed until a tag is\n# produced some other way.\nhooks:\n  - name: git-preflight\n    event: SessionStart\n    command: harness session-start preflight\n    blocking: false\n    # 70s budget gives the wrapped preflight (default 60s) headroom plus\n    # ledger-write time. Was 30s through v0.17.4, but a healthy preflight\n    # on a medium-size repo takes ~28s and the old 25s wrapper ceiling\n    # blew through it. Bumped together with DEFAULT_PREFLIGHT_TIMEOUT_MS\n    # (agent-tasks/7265599e).\n    budget_ms: 70000\n    # Floor at agent-preflight 0.2.0, the release that makes secret\n    # detection git-aware and diff-scoped: a gitignored+untracked .env,\n    # a .md doc, a non-git dir, or a secret in a tracked file the branch\n    # never touched is a non-blocking warn, not a hard fail. Pre-0.2.0\n    # installs hard-fail preflight on the normal correct state (a\n    # gitignored .env holding real credentials), so this SessionStart\n    # producer never writes a preflight: tag and the preflight-before-*\n    # policies stay closed forever on any repo with a local .env. (0.1.1\n    # had already fixed the wrapper-script \"tool not installed\" false\n    # positive.) version_command points at the source-of-truth preflight\n    # binary, not at the `harness session-start preflight` wrapper.\n    min_version: \"0.2.0\"\n    version_command: [\"preflight\", \"--version\"]\n\n  - name: require-review-evidence\n    event: PreToolUse\n    match: \"mcp__agent-tasks__pull_requests_merge\"\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  # Tool-agnostic parallel of require-review-evidence for operators on the\n  # gh-cli workflow (`gh pr merge`) instead of agent-tasks MCP. Same generic\n  # `harness policy intercept` entrypoint; the matching review-before-merge-bash\n  # policy below picks up the trigger. A PolicyTrigger can only AND-match one\n  # surface (MCP tool-name OR Bash command), so two parallel definitions are\n  # the minimum-scope way to cover both PR surfaces without bumping the schema.\n  - name: require-review-evidence-bash\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*gh pr merge\\b'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  - name: require-dogfood-evidence\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*(npm publish\\b|git( -C \\S+)* tag v)'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  - name: require-preflight-evidence\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*git( -C \\S+)* (status|log|diff|branch)\\b'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 1000\n\n  - name: require-review-subagent-evidence\n    event: PreToolUse\n    match: \"mcp__agent-tasks__pull_requests_create\"\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  # Bash-surface parallel of require-review-subagent-evidence for operators\n  # who open PRs with `gh pr create` instead of agent-tasks MCP. The matching\n  # review-subagent-before-pr-create-bash policy below tags by branch\n  # (`review-subagent:${BRANCH}`) because no task UUID is in `gh pr create`\n  # arguments; the working branch is the closest stable handle for \"the\n  # PR-in-progress\" at this point in the cycle.\n  - name: require-review-subagent-evidence-bash\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*gh pr create\\b'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  - name: require-preflight-push-evidence\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*git( -C \\S+)* push\\b'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 1000\n\n  # risk-gate (Phase 7 #6): the Risk Gate enforcement hook. The\n  # gate-prod-destructive policies below reference it. Same generic\n  # `harness policy intercept` entrypoint as every other policy hook;\n  # the interceptor builds the Action Envelope, classifies risk against\n  # `risk.classifiers[]`, resolves the environment against\n  # `environments.resolvers[]`, and evaluates the policies' `when:`.\n  - name: risk-gate\n    event: PreToolUse\n    match: \"Bash\"\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\npolicies:\n  - name: review-before-merge\n    description: Block PR merges unless a ledger entry tagged review:<pr-number> exists for this session.\n    trigger:\n      event: PreToolUse\n      match: \"mcp__agent-tasks__pull_requests_merge\"\n      extract:\n        PR_NUMBER: \"toolArgs.prNumber\"\n    requires:\n      ledger_tag: \"review:${PR_NUMBER}\"\n    hook: require-review-evidence\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review:${PR_NUMBER} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review\"}'\n        description: Spawn a review subagent against the PR diff, capture its verdict, then persist a ledger entry tagged with the PR number. The content should be self-contained enough for an auditor to read without re-opening the chat.\n    ux:\n      cannot: \"You cannot merge PR #${PR_NUMBER} yet.\"\n      required:\n        - \"a recorded review of PR #${PR_NUMBER}\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"review:${PR_NUMBER} \u2014 <verdict + key findings + nits>\" }'\n\n  # Bash-surface parallel of review-before-merge for operators on the gh-cli\n  # workflow. Two scope notes:\n  #   1. Tag shape: `review:${BRANCH}` instead of `review:${PR_NUMBER}`. The\n  #      `gh pr merge` invocation can target the PR by number, by URL, or by\n  #      the current branch (default), and PR_NUMBER is not extractable from\n  #      `tool_input.command` with today's JSONPath-only extract DSL. BRANCH\n  #      is the stable identifier the producer can record at review time.\n  #   2. This sits ALONGSIDE review-before-merge \u2014 not as a replacement. An\n  #      operator using both surfaces (e.g. agent-tasks MCP for most repos\n  #      + gh-cli for a quick hotfix) will have both gates active, each with\n  #      its own tag shape, which is semantically honest.\n  - name: review-before-merge-bash\n    description: Block `gh pr merge` unless a ledger entry tagged review:<branch> exists for this session.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*gh pr merge\\b'\n    requires:\n      ledger_tag: \"review:${BRANCH}\"\n    hook: require-review-evidence-bash\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review:${BRANCH} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review\"}'\n        description: Spawn a review subagent against the branch diff, capture its verdict, then persist a ledger entry tagged with the branch name. Mirror of the review-before-merge producer for the gh-cli surface.\n    ux:\n      cannot: \"You cannot merge the PR for branch ${BRANCH} via `gh pr merge` yet.\"\n      required:\n        - \"a recorded review of the PR for branch ${BRANCH}\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"review:${BRANCH} \u2014 <verdict + key findings + nits>\" }'\n\n  - name: dogfood-before-release\n    description: Block npm publish / git tag v* without a recent dogfood ledger entry.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*(npm publish\\b|git( -C \\S+)* tag v)'\n    requires:\n      ledger_tag: \"dogfood:${SESSION_ID}\"\n      within: 24h\n    hook: require-dogfood-evidence\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"dogfood:${SESSION_ID} \u2014 <end-to-end smoke summary against the live system>\", source:\"manual smoke test\"}'\n        description: Before tagging or publishing, run the release path end-to-end against the live system (not just unit tests) and persist the result as a session-tagged ledger entry. Document what you exercised (install, CLI happy path, MCP handshake, etc.) so a future auditor can tell whether the smoke covered the change.\n    ux:\n      cannot: \"You cannot publish a release yet.\"\n      required:\n        - \"an end-to-end dogfood run in this session\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"dogfood:${SESSION_ID} \u2014 <end-to-end smoke summary>\" }'\n\n  - name: two-reviewers-required\n    description: At least two distinct reviewer ledger entries must exist for the PR.\n    trigger:\n      event: PreToolUse\n      match: \"mcp__agent-tasks__pull_requests_merge\"\n      extract:\n        PR_NUMBER: \"toolArgs.prNumber\"\n    requires:\n      ledger_tag: \"review:${PR_NUMBER}\"\n      count:\n        min: 2\n    hook: require-review-evidence\n    enforcement: warn\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review:${PR_NUMBER} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review (reviewer 2)\"}'\n        description: Same shape as review-before-merge but TWO DISTINCT reviewer entries must exist before the gate is satisfied (count.min 2). Distinguish reviewers by source so the count is honest. Warn-level enforcement, so the agent CAN merge with one reviewer but should consider spawning a second for load-bearing changes.\n\n  - name: preflight-before-investigation\n    description: Block investigative git reads (status/log/diff/branch) when agent-preflight has not run recently with ready:true for the current repo.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*git( -C \\S+)* (status|log|diff|branch)\\b'\n    requires:\n      ledger_tag: \"preflight:${REPO}\"\n      within: 1h\n    hook: require-preflight-evidence\n    enforcement: block\n    producers:\n      - kind: bash\n        command: harness session-start preflight\n        description: Runs agent-preflight against the current cwd; on ready:true, records preflight:${REPO} to the ledger. Standard producer.\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"preflight:${REPO}\", source:\"manual\"}'\n        description: Direct ledger write. Use when the Bash hook is locked down (e.g. understanding-gate active) or when the standard producer is unavailable.\n    ux:\n      cannot: \"You cannot investigate this repository yet.\"\n      required:\n        - \"verified repository preflight\"\n        - \"an approved Understanding Report, if the Understanding Gate is still active (it blocks `harness preflight` itself)\"\n      run:\n        - \"harness preflight\"\n\n  - name: review-subagent-before-pr-create\n    description: Block agent-tasks PR creation unless a review-subagent ledger entry tagged for this task already exists. Forces the rigorous review BEFORE the PR opens, not after.\n    trigger:\n      event: PreToolUse\n      match: \"mcp__agent-tasks__pull_requests_create\"\n      extract:\n        TASK_ID: \"toolArgs.taskId\"\n    requires:\n      ledger_tag: \"review-subagent:${TASK_ID}\"\n    hook: require-review-subagent-evidence\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review-subagent:${TASK_ID} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review\"}'\n        description: After running a review subagent against the staged diff, persist its verdict + load-bearing findings as a ledger entry tagged with the task UUID. The content should be self-contained enough to audit later without re-reading the chat.\n    ux:\n      cannot: \"You cannot open a pull request for task ${TASK_ID} yet.\"\n      required:\n        - \"a completed review-subagent pass on this task\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"review-subagent:${TASK_ID} \u2014 <verdict + key findings + nits>\" }'\n\n  # Bash-surface parallel of review-subagent-before-pr-create. Tag shape is\n  # `review-subagent:${BRANCH}` because TASK_ID is an agent-tasks-only\n  # concept; for the gh-cli workflow the working branch is the closest stable\n  # handle for \"the PR-in-progress\" at this point. Same rationale as\n  # review-before-merge-bash: sits alongside the MCP variant, not as a\n  # replacement.\n  - name: review-subagent-before-pr-create-bash\n    description: Block `gh pr create` unless a review-subagent ledger entry tagged review-subagent:<branch> exists for this session. Forces the rigorous review BEFORE the PR opens.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*gh pr create\\b'\n    requires:\n      ledger_tag: \"review-subagent:${BRANCH}\"\n    hook: require-review-subagent-evidence-bash\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review-subagent:${BRANCH} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review\"}'\n        description: After running a review subagent against the staged diff for the working branch, persist its verdict + load-bearing findings as a ledger entry tagged with the branch name. Mirror of the review-subagent-before-pr-create producer for the gh-cli surface.\n    ux:\n      cannot: \"You cannot open a pull request for branch ${BRANCH} via `gh pr create` yet.\"\n      required:\n        - \"a completed review-subagent pass on branch ${BRANCH}\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"review-subagent:${BRANCH} \u2014 <verdict + key findings + nits>\" }'\n\n  - name: preflight-before-push\n    description: Block git push unless a fresh preflight ledger entry exists for the current branch. Catches the stale-checkout class of incident at the last reversible step.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*git( -C \\S+)* push\\b'\n    requires:\n      ledger_tag: \"preflight:${BRANCH}\"\n      within: 10m\n      # at_head:true lets a preflight at the current HEAD satisfy the\n      # gate at any age (the standard producer writes head:<sha> into\n      # the tag content). The 10m window remains the freshness ceiling\n      # for the head-mismatch case (operator switched branch, preflight\n      # predates HEAD shift, runtime couldn't resolve a sha).\n      at_head: true\n    hook: require-preflight-push-evidence\n    enforcement: block\n    producers:\n      - kind: bash\n        command: harness session-start preflight\n        description: Runs agent-preflight against the current cwd; on ready:true, records preflight:${BRANCH} ready:true confidence:<n> head:<sha> to the ledger. Standard producer.\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"preflight:${BRANCH} head:<full-sha> \u2014 <summary of what is on the branch + smoke results>\", source:\"manual\"}'\n        description: Direct ledger write. Include head:<full-sha> if you want the entry to count under at_head; the branch is the WIP review surface and the content should summarise what is staged + the smoke evidence so a reviewer can audit later without re-reading the chat.\n    ux:\n      cannot: \"You cannot push branch ${BRANCH} yet.\"\n      required:\n        - \"a preflight for ${BRANCH} at the current HEAD (any age) OR any preflight within the last 10 minutes. Re-run `harness preflight` if you committed since the last preflight AND it has been more than 10 minutes.\"\n        - \"if solution-acceptance is enabled, a ready HEAD-pinned verdict at the SAME commit too (run `solution_evaluate`). `git push` trips both gates, so commit first if the tree is dirty, then satisfy both at one HEAD.\"\n        - \"an approved Understanding Report, if the Understanding Gate is still active (it blocks `harness preflight` itself)\"\n      run:\n        - \"harness preflight\"\n\n  # Phase 7 Risk Gate \u2014 the canonical built-in worked example. These two\n  # policies, with the dangerous-shell classifier and production-signals\n  # resolver below, are the Risk Gate's default stance: a destructive\n  # shell action whose target environment resolves to production is\n  # gated before the runtime fires it. Both fire ONLY when the\n  # environment resolves to production (a main / release branch, a\n  # prod-looking DATABASE_URL, or a prod kube context); on an ordinary\n  # feature branch the environment is unknown and neither fires. Ordered\n  # deny-first so a critical action (which also matches the high\n  # threshold) gets the hard-deny envelope. See docs/risk-gate.md.\n  - name: gate-prod-destructive\n    description: Deny critical-severity destructive shell actions against a production target.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n    when:\n      risk.severity_at_least: critical\n      environment.name: production\n    requires:\n      ledger_tag: \"risk-override:${SESSION_ID}\"\n    hook: risk-gate\n    enforcement: block\n    ux:\n      cannot: \"You cannot run this critical destructive action against production.\"\n      required:\n        - \"a deliberate operator override: a critical production mutation has no benign reading\"\n      run:\n        - \"Choose a non-destructive alternative, or run the command yourself outside the agent.\"\n        - \"Operator override (deliberate): run `harness approve risk --force <reason>` from your own shell (`! ` prefix in Claude Code, with --i-am-the-operator to acknowledge a non-TTY invocation).\"\n        - \"Session-wide kill switch: run `harness pause --for <duration>` instead (every gate silences until the sentinel expires or `harness resume` runs).\"\n  - name: gate-prod-destructive-approval\n    description: Require operator approval for high-severity destructive shell actions against a production target.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n    when:\n      risk.severity_at_least: high\n      environment.name: production\n    requires:\n      ledger_tag: \"risk-approved:${SESSION_ID}\"\n    hook: risk-gate\n    enforcement: require_approval\n    ux:\n      cannot: \"You cannot run this destructive production action yet.\"\n      required:\n        - \"operator approval of this Risk Gate decision\"\n      run:\n        - \"harness approve risk\"\n\n# Full inherits the Solo/Team understanding-gate stack: the Stop hook\n# persists each Understanding Report and the PreToolUse pre-tool-use\n# blocker refuses Edit/Write/Bash until the report is approved. Drop\n# this block if you want the reference policies above without the\n# baseline gate.\npolicy_packs:\n  - name: understanding-before-execution\n    source: builtin\n    enabled: true\n    description: Force agents to expose their task interpretation and wait for explicit human approval before any write-capable tool fires.\n    config:\n      mode: grill_me\n      # Producers (agent-tasks/25bced52): rendered into the gate's deny\n      # envelope by the same engine as policy producers. Constraint at\n      # this layer: at-least-one `ask`. Post-v0.14.0 the gate signal\n      # is a filesystem marker and the mcp ledger_add path no longer\n      # satisfies the gate; the canonical unblock surface is the\n      # operator-approval prompt.\n      producers:\n        - kind: ask\n          command: harness approve understanding\n          description: \"Bare command, no pipes or chaining. The hook recognises it via isEscapeCommand and emits permissionDecision:ask; the operator's go on that prompt IS the gate approval. Golden path.\"\n        - kind: bash\n          command: harness approve understanding\n          description: Same command from any un-hooked terminal (operator only, not reachable from inside the gated session). Writes the canonical marker at harness.generated/.approvals/${SESSION_ID}.\n      # ux (agent-tasks/e48e3b45): replaces the legacy engine-vocabulary\n      # deny envelope with the plain-language { cannot, required, run }\n      # shape. Engine details (the BLOCK reason naming session id /\n      # marker / report state) still land in stderr for operator audit;\n      # the agent only sees this.\n      ux:\n        cannot: \"You cannot use write-capable tools yet.\"\n        required:\n          - \"an approved Understanding Report for this session\"\n        run:\n          - \"Write an Understanding Report covering: Current Understanding, Intended Outcome, Derived Todos, Acceptance Criteria, Assumptions, Open Questions, Out Of Scope, Risks, Verification Plan, Prior Art (state what you searched for an existing solution and what you found, with an explicit adopt-or-build judgment)\"\n          - \"Run `harness approve understanding` (bare, no pipes, chaining, or redirection) and approve the prompt\"\n      # approval_lifecycle (agent-tasks/d8ee60ca + harness/f54e0ecb,\n      # v0.18.0+): expire the approval marker on task-completion\n      # boundaries so a multi-task session re-prompts for an\n      # Understanding Report between tasks. Without this the legacy\n      # \"one approval per session\" contract lets a stale interpretation\n      # drive the next task's edits.\n      #\n      # Full ships both boundary kinds: the agent-tasks MCP verbs for\n      # operators on that workflow, plus a Bash regex list for hybrid\n      # operators who also use gh-cli for PR mechanics. `max_age` is\n      # the safety net. Operators who prefer the legacy per-session\n      # behaviour opt out with `approval_lifecycle: { mode: session }`.\n      # Operators on other task systems override the matchers.\n      approval_lifecycle:\n        expire_on_tool_match:\n          - mcp__agent-tasks__task_finish\n          - mcp__agent-tasks__task_abandon\n          - mcp__agent-tasks__pull_requests_merge\n          - mcp__agent-tasks__tasks_transition\n        expire_on_bash_match:\n          - '^gh pr (merge|close)\\b'\n          - '^git push origin (master|main)\\b'\n        max_age: 4h\n\n  # branch-protection (agent-tasks/2fdc5bbe, default-enabled since v0.17.2):\n  # blocks Write/Edit (claude-code) or apply_patch (codex) on protected\n  # branches (default: master, main, develop). Complements\n  # preflight-before-push, which fires at the LAST reversible step;\n  # branch-protection fires at the FIRST source mutation, catching the\n  # \"forgot to branch off master\" pattern earlier in the cycle.\n  #\n  # Two satisfying signals: a fresh `branch:non-protected:<branch>` tag\n  # from the SessionStart producer (`harness session-start branch-check`),\n  # or the operator-only override marker written by\n  # `harness approve branch-protection --session <id>` for deliberate\n  # protected-branch edits (version bumps, CI workflow patches, hotfixes).\n  # A branch-protection-ack ledger tag is no longer a sufficient override\n  # on its own (it is agent-writable); the marker file is the trusted signal.\n  #\n  # Fails closed (any load / parse / ledger error refuses). Disable by\n  # setting `enabled: false` or removing this entry if your workflow\n  # routinely edits master directly. Override the protected list via\n  # `config.protected_branches`. Full reference:\n  # docs/policy-packs/branch-protection.md.\n  - name: branch-protection\n    source: builtin\n    enabled: true\n    description: Block Write/Edit on protected branches (master, main, develop) at the first source mutation.\n    config:\n      # ux (agent-tasks/9806d4f8): replaces the legacy\n      # \"branch-protection: refusing ...\" envelope with the\n      # plain-language { cannot, required, run } shape. Engine details\n      # (the BLOCK reason naming session id / freshness window) stay\n      # on stderr for operator audit.\n      ux:\n        cannot: \"You cannot edit files on protected branch ${BRANCH} yet.\"\n        required:\n          - \"a checkout of a non-protected branch (current `${BRANCH}` is protected)\"\n        run:\n          - \"git checkout -b feat/<your-task>\"\n          - \"harness session-start branch-check\"\n\n  # solution-acceptance (harness cc43c7a4): Verifier-gated Done. Gates the\n  # task-finishing tools (agent-tasks completion verbs + git push / gh pr\n  # merge) on a ready, HEAD-pinned verdict that the grounding-mcp producer\n  # (solution_evaluate) derives from a real preflight run, plus an\n  # anti-forgery write-guard on the verdict marker. DISABLED by default: it\n  # is a hard completion-gate and needs grounding-mcp (>= 0.3.2) under\n  # tools.mcp plus the preflight binary on PATH. Flip enabled: true once the\n  # producer is wired and you want completion earned, not claimed. The pack\n  # emits its own instructions.md on apply; harness validate warns if you\n  # enable it without the producer.\n  - name: solution-acceptance\n    source: builtin\n    enabled: false\n    description: Gate task completion on a ready, HEAD-pinned solution-acceptance verdict earned from a real preflight run.\n\n# Phase 7 Risk Gate vocabulary. The dangerous-shell classifier and\n# production-signals resolver feed the gate-prod-destructive policies\n# above: `harness policy intercept` builds the Action Envelope,\n# classifies the action against `risk.classifiers[]`, resolves the\n# target environment against `environments.resolvers[]`, and evaluates\n# each policy's `when:` clauses against the result. Full design and the\n# decision model: docs/risk-gate.md.\nrisk:\n  classifiers:\n    - name: dangerous-shell\n      tool: Bash\n      patterns:\n        - pattern: 'rm\\s+-rf\\s+(/|/var|/data|/mnt|~)'\n          categories: [destructive, data_loss]\n          severity: critical\n        - pattern: 'DROP\\s+TABLE|TRUNCATE\\s+TABLE|DELETE\\s+FROM'\n          categories: [destructive, data_loss]\n          severity: high\n        - pattern: 'kubectl\\s+delete\\s+(namespace|deployment|statefulset|pvc)'\n          categories: [destructive, infrastructure_change]\n          severity: high\n        - pattern: 'terraform\\s+destroy'\n          categories: [destructive, infrastructure_change]\n          severity: critical\n\nenvironments:\n  resolvers:\n    - name: production-signals\n      environment: production\n      signals:\n        branch_patterns: [main, \"release/*\"]\n        env_var_patterns:\n          - var: DATABASE_URL\n            patterns: [prod, production]\n        kube_context_patterns: [\".*prod.*\"]\n        kube_namespace_patterns: [prod, production]\n";
+export declare const FULL_TEMPLATE = "# ~/.harness/harness.yaml (legacy: ~/.claude/harness.yaml)\n#\n# Bootstrapped by `harness init --template full`. The reference manifest:\n# every example policy from docs/examples/full-manifest.yaml wired through\n# the generic `harness policy intercept` engine, so no external shell\n# scripts under ~/.claude/hooks/ are required.\n#\n# Canonical source for the policy + policy_packs sections is\n# docs/examples/full-manifest.yaml. A parity vitest\n# (tests/cli/init-full-template-parity.test.ts) fails the build if the\n# two diverge on policy names or load-bearing fields.\n#\n# What you still need on PATH (the wizard offers to `npm i -g` these on\n# init): agent-tasks-mcp-bridge, grounding-mcp, memory-router-*,\n# understanding-gate-claude-*.\n\nversion: 1\n\ngrounding:\n  session:\n    auto_start: true\n    id_format: \"gs-{repo}-{rand:8}\"\n  evidence_ledger:\n    path: ~/.evidence-ledger/ledger.db\n    retention_days: 90\n  policies_source: ~/.claude/harness.d/policies/claim-gate.yaml\n\ntools:\n  mcp:\n    # codebase-oracle (the Pandora RAG MCP server) is intentionally NOT\n    # in the Full default. It is published as\n    # `@lannguyensi/codebase-oracle` and works fine standalone, but it\n    # is an opinionated workflow add-on (multi-repo semantic search)\n    # rather than infrastructure harness itself assumes. Operators who\n    # want it wire it explicitly:\n    #   npm i -g @lannguyensi/codebase-oracle\n    #   harness add mcp codebase-oracle --command codebase-oracle,mcp\n    # Set ORACLE_SCAN_ROOT (absolute path; tilde is not expanded by the\n    # MCP env block) and OPENAI_API_KEY (or switch providers via\n    # ORACLE_LLM_PROVIDER) before the first call.\n    - name: agent-tasks\n      # Zero-setup entry: `@agent-tasks/mcp-bridge` exposes the\n      # `agent-tasks-mcp-bridge` binary on PATH. The bridge owns token\n      # storage and defaults to the hosted backend; override with\n      # `AGENT_TASKS_BASE_URL` / `AGENT_TASKS_TOKEN` for self-hosted.\n      # `min_version` floor: 0.6.0 added the `--version` short-circuit\n      # the doctor probe needs (PR agent-tasks/240, release-cut PR 241).\n      # Bump the floor whenever a fix you depend on lands; loose floors\n      # are fine, the point is the drift signal not pinning a specific cut.\n      command: [agent-tasks-mcp-bridge]\n      min_version: \"0.6.0\"\n      health:\n        verb: projects_list\n        timeout_ms: 5000\n      enabled: true\n    - name: grounding-mcp\n      # Published bin from `@lannguyensi/grounding-mcp`. No env is set:\n      # the bundled default resolves to `~/.evidence-ledger/ledger.db`\n      # via os.homedir() at startup. Passing a literal tilde in env\n      # bypasses shell expansion and creates rogue cwd-relative DB files\n      # (see agent-tasks/42d224a6 incident). `min_version` floor: 0.2.0\n      # added the `--version` short-circuit the doctor probe needs (PR\n      # agent-grounding/76, release-cut PR 77).\n      command: [grounding-mcp]\n      min_version: \"0.2.0\"\n      health:\n        verb: ledger_status\n        timeout_ms: 5000\n      enabled: true\n\n  cli:\n    - name: gh\n      binary: gh\n      required: true\n\n  skills:\n    enabled:\n      - simplify\n      - init\n      - review\n      - security-review\n    source_dirs:\n      - ~/.claude/skills\n\n  builtin:\n    known: [Read, Edit, Write, Bash, Agent, Skill, TaskCreate, Glob, Grep]\n\nmemory:\n  directories:\n    - path: ~/.claude/projects/{project}/memory\n      scope: project\n  router:\n    # Published bin from `@lannguyensi/memory-router`.\n    # `min_version` floor: 0.3.0 added the `--version` short-circuit\n    # the doctor probe needs (PR agent-memory/40, release-cut PR 41).\n    command: [memory-router-user-prompt-submit]\n    min_version: \"0.3.0\"\n    enabled: true\n  retention:\n    staleness_days: 180\n    broken_refs: warn\n  scopes:\n    default: project\n    allowed: [project, user]\n\n# All PreToolUse hooks share the generic `harness policy intercept` CLI\n# entrypoint. The engine reads the tool event on stdin, evaluates whichever\n# policy below has a matching trigger (`match` + optional `bash_match`),\n# and emits Claude Code's deny envelope when the required ledger tag is\n# absent. No external shell scripts are required.\n#\n# The `git-preflight` SessionStart hook is the producer side of the\n# `preflight-before-*` policies: `harness session-start preflight` runs\n# agent-preflight against the session cwd and, on a ready:true result,\n# records `preflight:${REPO}` to the evidence ledger. It needs the\n# `preflight` binary on PATH (`npm i -g @lannguyensi/agent-preflight`); when\n# that is absent the hook logs to stderr and exits 0, so the session is\n# never broken \u2014 the preflight gates just stay closed until a tag is\n# produced some other way.\nhooks:\n  - name: git-preflight\n    event: SessionStart\n    command: harness session-start preflight\n    blocking: false\n    # 70s budget gives the wrapped preflight (default 60s) headroom plus\n    # ledger-write time. Was 30s through v0.17.4, but a healthy preflight\n    # on a medium-size repo takes ~28s and the old 25s wrapper ceiling\n    # blew through it. Bumped together with DEFAULT_PREFLIGHT_TIMEOUT_MS\n    # (agent-tasks/7265599e).\n    budget_ms: 70000\n    # Floor at agent-preflight 0.2.0, the release that makes secret\n    # detection git-aware and diff-scoped: a gitignored+untracked .env,\n    # a .md doc, a non-git dir, or a secret in a tracked file the branch\n    # never touched is a non-blocking warn, not a hard fail. Pre-0.2.0\n    # installs hard-fail preflight on the normal correct state (a\n    # gitignored .env holding real credentials), so this SessionStart\n    # producer never writes a preflight: tag and the preflight-before-*\n    # policies stay closed forever on any repo with a local .env. (0.1.1\n    # had already fixed the wrapper-script \"tool not installed\" false\n    # positive.) version_command points at the source-of-truth preflight\n    # binary, not at the `harness session-start preflight` wrapper.\n    min_version: \"0.2.0\"\n    version_command: [\"preflight\", \"--version\"]\n\n  - name: require-review-evidence\n    event: PreToolUse\n    match: \"mcp__agent-tasks__pull_requests_merge\"\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  # Tool-agnostic parallel of require-review-evidence for operators on the\n  # gh-cli workflow (`gh pr merge`) instead of agent-tasks MCP. Same generic\n  # `harness policy intercept` entrypoint; the matching review-before-merge-bash\n  # policy below picks up the trigger. A PolicyTrigger can only AND-match one\n  # surface (MCP tool-name OR Bash command), so two parallel definitions are\n  # the minimum-scope way to cover both PR surfaces without bumping the schema.\n  - name: require-review-evidence-bash\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*gh pr merge\\b'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  - name: require-dogfood-evidence\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*(npm publish\\b|git( -C \\S+)* tag v)'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  - name: require-preflight-evidence\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*git( -C \\S+)* (status|log|diff|branch)\\b'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 1000\n\n  - name: require-review-subagent-evidence\n    event: PreToolUse\n    match: \"mcp__agent-tasks__pull_requests_create\"\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  # Bash-surface parallel of require-review-subagent-evidence for operators\n  # who open PRs with `gh pr create` instead of agent-tasks MCP. The matching\n  # review-subagent-before-pr-create-bash policy below tags by branch\n  # (`review-subagent:${BRANCH}`) because no task UUID is in `gh pr create`\n  # arguments; the working branch is the closest stable handle for \"the\n  # PR-in-progress\" at this point in the cycle.\n  - name: require-review-subagent-evidence-bash\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*gh pr create\\b'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  - name: require-preflight-push-evidence\n    event: PreToolUse\n    match: \"Bash\"\n    bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*git( -C \\S+)* push\\b'\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 1000\n\n  # risk-gate (Phase 7 #6): the Risk Gate enforcement hook. The\n  # gate-prod-destructive policies below reference it. Same generic\n  # `harness policy intercept` entrypoint as every other policy hook;\n  # the interceptor builds the Action Envelope, classifies risk against\n  # `risk.classifiers[]`, resolves the environment against\n  # `environments.resolvers[]`, and evaluates the policies' `when:`.\n  - name: risk-gate\n    event: PreToolUse\n    match: \"Bash\"\n    command: harness policy intercept\n    blocking: hard\n    budget_ms: 2000\n\n  # Optional: runtime-reality drift gate (NOT enabled by default).\n  # Blocks destructive runtime commands (compose down/restart, systemctl,\n  # kill/pkill, ./deploy-*) when the live process state has drifted from what\n  # your expectations file says should be running. Left COMMENTED on purpose:\n  # the hook is host-coupled and, without RUNTIME_REALITY_KEYWORD + an\n  # expectations file + RUNTIME_REALITY_PROBE_CMD, degrades silently to allow,\n  # a no-op that looks like protection. To arm it, uncomment the entry and\n  # fill in the three env values. The expectations-file format and how to\n  # install the probe are documented in docs/runtime-reality-hook.md.\n  #\n  # - name: runtime-reality\n  #   event: PreToolUse\n  #   command: >-\n  #     RUNTIME_REALITY_KEYWORD=<your-stack>\n  #     RUNTIME_REALITY_EXPECTATIONS_DIR=$HOME/.runtime-reality/expectations\n  #     RUNTIME_REALITY_PROBE_CMD=\"node $HOME/.runtime-reality/probes/runtime-reality-docker-probe.mjs\"\n  #     harness pack hook runtime-reality\n  #   blocking: hard\n  #   description: Block destructive runtime commands on critical process drift\n\npolicies:\n  - name: review-before-merge\n    description: Block PR merges unless a ledger entry tagged review:<pr-number> exists for this session.\n    trigger:\n      event: PreToolUse\n      match: \"mcp__agent-tasks__pull_requests_merge\"\n      extract:\n        PR_NUMBER: \"toolArgs.prNumber\"\n    requires:\n      ledger_tag: \"review:${PR_NUMBER}\"\n    hook: require-review-evidence\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review:${PR_NUMBER} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review\"}'\n        description: Spawn a review subagent against the PR diff, capture its verdict, then persist a ledger entry tagged with the PR number. The content should be self-contained enough for an auditor to read without re-opening the chat.\n    ux:\n      cannot: \"You cannot merge PR #${PR_NUMBER} yet.\"\n      required:\n        - \"a recorded review of PR #${PR_NUMBER}\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"review:${PR_NUMBER} \u2014 <verdict + key findings + nits>\" }'\n\n  # Bash-surface parallel of review-before-merge for operators on the gh-cli\n  # workflow. Two scope notes:\n  #   1. Tag shape: `review:${BRANCH}` instead of `review:${PR_NUMBER}`. The\n  #      `gh pr merge` invocation can target the PR by number, by URL, or by\n  #      the current branch (default), and PR_NUMBER is not extractable from\n  #      `tool_input.command` with today's JSONPath-only extract DSL. BRANCH\n  #      is the stable identifier the producer can record at review time.\n  #   2. This sits ALONGSIDE review-before-merge \u2014 not as a replacement. An\n  #      operator using both surfaces (e.g. agent-tasks MCP for most repos\n  #      + gh-cli for a quick hotfix) will have both gates active, each with\n  #      its own tag shape, which is semantically honest.\n  - name: review-before-merge-bash\n    description: Block `gh pr merge` unless a ledger entry tagged review:<branch> exists for this session.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*gh pr merge\\b'\n    requires:\n      ledger_tag: \"review:${BRANCH}\"\n    hook: require-review-evidence-bash\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review:${BRANCH} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review\"}'\n        description: Spawn a review subagent against the branch diff, capture its verdict, then persist a ledger entry tagged with the branch name. Mirror of the review-before-merge producer for the gh-cli surface.\n    ux:\n      cannot: \"You cannot merge the PR for branch ${BRANCH} via `gh pr merge` yet.\"\n      required:\n        - \"a recorded review of the PR for branch ${BRANCH}\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"review:${BRANCH} \u2014 <verdict + key findings + nits>\" }'\n\n  - name: dogfood-before-release\n    description: Block npm publish / git tag v* without a recent dogfood ledger entry.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*(npm publish\\b|git( -C \\S+)* tag v)'\n    requires:\n      ledger_tag: \"dogfood:${SESSION_ID}\"\n      within: 24h\n    hook: require-dogfood-evidence\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"dogfood:${SESSION_ID} \u2014 <end-to-end smoke summary against the live system>\", source:\"manual smoke test\"}'\n        description: Before tagging or publishing, run the release path end-to-end against the live system (not just unit tests) and persist the result as a session-tagged ledger entry. Document what you exercised (install, CLI happy path, MCP handshake, etc.) so a future auditor can tell whether the smoke covered the change.\n    ux:\n      cannot: \"You cannot publish a release yet.\"\n      required:\n        - \"an end-to-end dogfood run in this session\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"dogfood:${SESSION_ID} \u2014 <end-to-end smoke summary>\" }'\n\n  - name: two-reviewers-required\n    description: At least two distinct reviewer ledger entries must exist for the PR.\n    trigger:\n      event: PreToolUse\n      match: \"mcp__agent-tasks__pull_requests_merge\"\n      extract:\n        PR_NUMBER: \"toolArgs.prNumber\"\n    requires:\n      ledger_tag: \"review:${PR_NUMBER}\"\n      count:\n        min: 2\n    hook: require-review-evidence\n    enforcement: warn\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review:${PR_NUMBER} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review (reviewer 2)\"}'\n        description: Same shape as review-before-merge but TWO DISTINCT reviewer entries must exist before the gate is satisfied (count.min 2). Distinguish reviewers by source so the count is honest. Warn-level enforcement, so the agent CAN merge with one reviewer but should consider spawning a second for load-bearing changes.\n\n  - name: preflight-before-investigation\n    description: Block investigative git reads (status/log/diff/branch) when agent-preflight has not run recently with ready:true for the current repo.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*git( -C \\S+)* (status|log|diff|branch)\\b'\n    requires:\n      ledger_tag: \"preflight:${REPO}\"\n      within: 1h\n    hook: require-preflight-evidence\n    enforcement: block\n    producers:\n      - kind: bash\n        command: harness session-start preflight\n        description: Runs agent-preflight against the current cwd; on ready:true, records preflight:${REPO} to the ledger. Standard producer.\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"preflight:${REPO}\", source:\"manual\"}'\n        description: Direct ledger write. Use when the Bash hook is locked down (e.g. understanding-gate active) or when the standard producer is unavailable.\n    ux:\n      cannot: \"You cannot investigate this repository yet.\"\n      required:\n        - \"verified repository preflight\"\n        - \"an approved Understanding Report, if the Understanding Gate is still active (it blocks `harness preflight` itself)\"\n      run:\n        - \"harness preflight\"\n\n  - name: review-subagent-before-pr-create\n    description: Block agent-tasks PR creation unless a review-subagent ledger entry tagged for this task already exists. Forces the rigorous review BEFORE the PR opens, not after.\n    trigger:\n      event: PreToolUse\n      match: \"mcp__agent-tasks__pull_requests_create\"\n      extract:\n        TASK_ID: \"toolArgs.taskId\"\n    requires:\n      ledger_tag: \"review-subagent:${TASK_ID}\"\n    hook: require-review-subagent-evidence\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review-subagent:${TASK_ID} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review\"}'\n        description: After running a review subagent against the staged diff, persist its verdict + load-bearing findings as a ledger entry tagged with the task UUID. The content should be self-contained enough to audit later without re-reading the chat.\n    ux:\n      cannot: \"You cannot open a pull request for task ${TASK_ID} yet.\"\n      required:\n        - \"a completed review-subagent pass on this task\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"review-subagent:${TASK_ID} \u2014 <verdict + key findings + nits>\" }'\n\n  # Bash-surface parallel of review-subagent-before-pr-create. Tag shape is\n  # `review-subagent:${BRANCH}` because TASK_ID is an agent-tasks-only\n  # concept; for the gh-cli workflow the working branch is the closest stable\n  # handle for \"the PR-in-progress\" at this point. Same rationale as\n  # review-before-merge-bash: sits alongside the MCP variant, not as a\n  # replacement.\n  - name: review-subagent-before-pr-create-bash\n    description: Block `gh pr create` unless a review-subagent ledger entry tagged review-subagent:<branch> exists for this session. Forces the rigorous review BEFORE the PR opens.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*gh pr create\\b'\n    requires:\n      ledger_tag: \"review-subagent:${BRANCH}\"\n    hook: require-review-subagent-evidence-bash\n    enforcement: block\n    producers:\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"review-subagent:${BRANCH} \u2014 <verdict + key findings + nits>\", source:\"Agent(general-purpose) review\"}'\n        description: After running a review subagent against the staged diff for the working branch, persist its verdict + load-bearing findings as a ledger entry tagged with the branch name. Mirror of the review-subagent-before-pr-create producer for the gh-cli surface.\n    ux:\n      cannot: \"You cannot open a pull request for branch ${BRANCH} via `gh pr create` yet.\"\n      required:\n        - \"a completed review-subagent pass on branch ${BRANCH}\"\n      run:\n        - 'mcp__agent-grounding__ledger_add { sessionId: \"${SESSION_ID}\", type: \"fact\", content: \"review-subagent:${BRANCH} \u2014 <verdict + key findings + nits>\" }'\n\n  - name: preflight-before-push\n    description: Block git push unless a fresh preflight ledger entry exists for the current branch. Catches the stale-checkout class of incident at the last reversible step.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n      bash_match: '(^|\\n|;|\\||&&|\\()\\s*(\\w+=\\S+\\s+)*git( -C \\S+)* push\\b'\n    requires:\n      ledger_tag: \"preflight:${BRANCH}\"\n      within: 10m\n      # at_head:true lets a preflight at the current HEAD satisfy the\n      # gate at any age (the standard producer writes head:<sha> into\n      # the tag content). The 10m window remains the freshness ceiling\n      # for the head-mismatch case (operator switched branch, preflight\n      # predates HEAD shift, runtime couldn't resolve a sha).\n      at_head: true\n    hook: require-preflight-push-evidence\n    enforcement: block\n    producers:\n      - kind: bash\n        command: harness session-start preflight\n        description: Runs agent-preflight against the current cwd; on ready:true, records preflight:${BRANCH} ready:true confidence:<n> head:<sha> to the ledger. Standard producer.\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"preflight:${BRANCH} head:<full-sha> \u2014 <summary of what is on the branch + smoke results>\", source:\"manual\"}'\n        description: Direct ledger write. Include head:<full-sha> if you want the entry to count under at_head; the branch is the WIP review surface and the content should summarise what is staged + the smoke evidence so a reviewer can audit later without re-reading the chat.\n    ux:\n      cannot: \"You cannot push branch ${BRANCH} yet.\"\n      required:\n        - \"a preflight for ${BRANCH} at the current HEAD (any age) OR any preflight within the last 10 minutes. Re-run `harness preflight` if you committed since the last preflight AND it has been more than 10 minutes.\"\n        - \"if solution-acceptance is enabled, a ready HEAD-pinned verdict at the SAME commit too (run `solution_evaluate`). `git push` trips both gates, so commit first if the tree is dirty, then satisfy both at one HEAD.\"\n        - \"an approved Understanding Report, if the Understanding Gate is still active (it blocks `harness preflight` itself)\"\n      run:\n        - \"harness preflight\"\n\n  # Phase 7 Risk Gate \u2014 the canonical built-in worked example. These two\n  # policies, with the dangerous-shell classifier and production-signals\n  # resolver below, are the Risk Gate's default stance: a destructive\n  # shell action whose target environment resolves to production is\n  # gated before the runtime fires it. Both fire ONLY when the\n  # environment resolves to production (a main / release branch, a\n  # prod-looking DATABASE_URL, or a prod kube context); on an ordinary\n  # feature branch the environment is unknown and neither fires. Ordered\n  # deny-first so a critical action (which also matches the high\n  # threshold) gets the hard-deny envelope. See docs/risk-gate.md.\n  - name: gate-prod-destructive\n    description: Deny critical-severity destructive shell actions against a production target.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n    when:\n      risk.severity_at_least: critical\n      environment.name: production\n    requires:\n      ledger_tag: \"risk-override:${SESSION_ID}\"\n    hook: risk-gate\n    enforcement: block\n    # Operator-in-the-loop gate: the override tag is written by the\n    # operator verb (ask semantics), not by the agent. See\n    # writing-custom-policies.md, tripwire 4 (the trust model).\n    producers:\n      - kind: ask\n        command: harness approve risk --force <reason>\n        description: Deliberate operator override for a critical production mutation; run from the operator shell.\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"risk-override:${SESSION_ID} \u2014 operator-authorized <reason>\", source:\"operator\"}'\n        description: Recovery path if the approve verb is unavailable; only meaningful when the OPERATOR authorizes the content.\n    ux:\n      cannot: \"You cannot run this critical destructive action against production.\"\n      required:\n        - \"a deliberate operator override: a critical production mutation has no benign reading\"\n      run:\n        - \"Choose a non-destructive alternative, or run the command yourself outside the agent.\"\n        - \"Operator override (deliberate): run `harness approve risk --force <reason>` from your own shell (`! ` prefix in Claude Code, with --i-am-the-operator to acknowledge a non-TTY invocation).\"\n        - \"Session-wide kill switch: run `harness pause --for <duration>` instead (every gate silences until the sentinel expires or `harness resume` runs).\"\n  - name: gate-prod-destructive-approval\n    description: Require operator approval for high-severity destructive shell actions against a production target.\n    trigger:\n      event: PreToolUse\n      match: \"Bash\"\n    when:\n      risk.severity_at_least: high\n      environment.name: production\n    requires:\n      ledger_tag: \"risk-approved:${SESSION_ID}\"\n    hook: risk-gate\n    enforcement: require_approval\n    producers:\n      - kind: ask\n        command: harness approve risk\n        description: Operator approves this Risk Gate decision from their own shell.\n      - kind: mcp\n        verb: mcp__agent-grounding__ledger_add\n        example: '{sessionId:\"${SESSION_ID}\", type:\"fact\", content:\"risk-approved:${SESSION_ID} \u2014 operator-authorized\", source:\"operator\"}'\n        description: Recovery path if the approve verb is unavailable; only meaningful when the OPERATOR authorizes the content.\n    ux:\n      cannot: \"You cannot run this destructive production action yet.\"\n      required:\n        - \"operator approval of this Risk Gate decision\"\n      run:\n        - \"harness approve risk\"\n\n# Full inherits the Solo/Team understanding-gate stack: the Stop hook\n# persists each Understanding Report and the PreToolUse pre-tool-use\n# blocker refuses Edit/Write/Bash until the report is approved. Drop\n# this block if you want the reference policies above without the\n# baseline gate.\npolicy_packs:\n  - name: understanding-before-execution\n    source: builtin\n    enabled: true\n    description: Force agents to expose their task interpretation and wait for explicit human approval before any write-capable tool fires.\n    config:\n      mode: grill_me\n      # Producers (agent-tasks/25bced52): rendered into the gate's deny\n      # envelope by the same engine as policy producers. Constraint at\n      # this layer: at-least-one `ask`. Post-v0.14.0 the gate signal\n      # is a filesystem marker and the mcp ledger_add path no longer\n      # satisfies the gate; the canonical unblock surface is the\n      # operator-approval prompt.\n      producers:\n        - kind: ask\n          command: harness approve understanding\n          description: \"Bare command, no pipes or chaining. The hook recognises it via isEscapeCommand and emits permissionDecision:ask; the operator's go on that prompt IS the gate approval. Golden path.\"\n        - kind: bash\n          command: harness approve understanding\n          description: Same command from any un-hooked terminal (operator only, not reachable from inside the gated session). Writes the canonical marker at harness.generated/.approvals/${SESSION_ID}.\n      # ux (agent-tasks/e48e3b45): replaces the legacy engine-vocabulary\n      # deny envelope with the plain-language { cannot, required, run }\n      # shape. Engine details (the BLOCK reason naming session id /\n      # marker / report state) still land in stderr for operator audit;\n      # the agent only sees this.\n      ux:\n        cannot: \"You cannot use write-capable tools yet.\"\n        required:\n          - \"an approved Understanding Report for this session\"\n        run:\n          - \"Write an Understanding Report covering: Current Understanding, Intended Outcome, Derived Todos, Acceptance Criteria, Assumptions, Open Questions, Out Of Scope, Risks, Verification Plan, Prior Art (state what you searched for an existing solution and what you found, with an explicit adopt-or-build judgment)\"\n          - \"Run `harness approve understanding` with the report attached as a quoted heredoc (harness approve understanding <<'UNDERSTANDING_REPORT' ...report... UNDERSTANDING_REPORT) so it is persisted for audit, then approve the prompt; the heredoc is the only extra shell shape the gate allows (no pipes, chaining, or other redirection)\"\n      # approval_lifecycle (agent-tasks/d8ee60ca + harness/f54e0ecb,\n      # v0.18.0+): expire the approval marker on task-completion\n      # boundaries so a multi-task session re-prompts for an\n      # Understanding Report between tasks. Without this the legacy\n      # \"one approval per session\" contract lets a stale interpretation\n      # drive the next task's edits.\n      #\n      # Full ships both boundary kinds: the agent-tasks MCP verbs for\n      # operators on that workflow, plus a Bash regex list for hybrid\n      # operators who also use gh-cli for PR mechanics. `max_age` is\n      # the safety net. Operators who prefer the legacy per-session\n      # behaviour opt out with `approval_lifecycle: { mode: session }`.\n      # Operators on other task systems override the matchers.\n      approval_lifecycle:\n        expire_on_tool_match:\n          - mcp__agent-tasks__task_finish\n          - mcp__agent-tasks__task_abandon\n          - mcp__agent-tasks__pull_requests_merge\n          - mcp__agent-tasks__tasks_transition\n        expire_on_bash_match:\n          - '^gh pr (merge|close)\\b'\n          - '^git push origin (master|main)\\b'\n        max_age: 4h\n\n  # branch-protection (agent-tasks/2fdc5bbe, default-enabled since v0.17.2):\n  # blocks Write/Edit (claude-code) or apply_patch (codex) on protected\n  # branches (default: master, main, develop). Complements\n  # preflight-before-push, which fires at the LAST reversible step;\n  # branch-protection fires at the FIRST source mutation, catching the\n  # \"forgot to branch off master\" pattern earlier in the cycle.\n  #\n  # Two satisfying signals: a fresh `branch:non-protected:<branch>` tag\n  # from the SessionStart producer (`harness session-start branch-check`),\n  # or the operator-only override marker written by\n  # `harness approve branch-protection --session <id>` for deliberate\n  # protected-branch edits (version bumps, CI workflow patches, hotfixes).\n  # A branch-protection-ack ledger tag is no longer a sufficient override\n  # on its own (it is agent-writable); the marker file is the trusted signal.\n  #\n  # Fails closed (any load / parse / ledger error refuses). Disable by\n  # setting `enabled: false` or removing this entry if your workflow\n  # routinely edits master directly. Override the protected list via\n  # `config.protected_branches`. Full reference:\n  # docs/policy-packs/branch-protection.md.\n  - name: branch-protection\n    source: builtin\n    enabled: true\n    description: Block Write/Edit on protected branches (master, main, develop) at the first source mutation.\n    config:\n      # ux (agent-tasks/9806d4f8): replaces the legacy\n      # \"branch-protection: refusing ...\" envelope with the\n      # plain-language { cannot, required, run } shape. Engine details\n      # (the BLOCK reason naming session id / freshness window) stay\n      # on stderr for operator audit.\n      ux:\n        cannot: \"You cannot edit files on protected branch ${BRANCH} yet.\"\n        required:\n          - \"a checkout of a non-protected branch (current `${BRANCH}` is protected)\"\n        run:\n          - \"git checkout -b feat/<your-task>\"\n          - \"harness session-start branch-check\"\n\n  # solution-acceptance (harness cc43c7a4): Verifier-gated Done. Gates the\n  # task-finishing tools (agent-tasks completion verbs + git push / gh pr\n  # merge) on a ready, HEAD-pinned verdict that the grounding-mcp producer\n  # (solution_evaluate) derives from a real preflight run, plus an\n  # anti-forgery write-guard on the verdict marker. DISABLED by default: it\n  # is a hard completion-gate and needs grounding-mcp (>= 0.3.2) under\n  # tools.mcp plus the preflight binary on PATH. Flip enabled: true once the\n  # producer is wired and you want completion earned, not claimed. The pack\n  # emits its own instructions.md on apply; harness validate warns if you\n  # enable it without the producer.\n  - name: solution-acceptance\n    source: builtin\n    enabled: false\n    description: Gate task completion on a ready, HEAD-pinned solution-acceptance verdict earned from a real preflight run.\n\n# Phase 7 Risk Gate vocabulary. The dangerous-shell classifier and\n# production-signals resolver feed the gate-prod-destructive policies\n# above: `harness policy intercept` builds the Action Envelope,\n# classifies the action against `risk.classifiers[]`, resolves the\n# target environment against `environments.resolvers[]`, and evaluates\n# each policy's `when:` clauses against the result. Full design and the\n# decision model: docs/risk-gate.md.\nrisk:\n  classifiers:\n    - name: dangerous-shell\n      tool: Bash\n      patterns:\n        - pattern: 'rm\\s+-rf\\s+(/|/var|/data|/mnt|~)'\n          categories: [destructive, data_loss]\n          severity: critical\n        - pattern: 'DROP\\s+TABLE|TRUNCATE\\s+TABLE|DELETE\\s+FROM'\n          categories: [destructive, data_loss]\n          severity: high\n        - pattern: 'kubectl\\s+delete\\s+(namespace|deployment|statefulset|pvc)'\n          categories: [destructive, infrastructure_change]\n          severity: high\n        - pattern: 'terraform\\s+destroy'\n          categories: [destructive, infrastructure_change]\n          severity: critical\n\nenvironments:\n  resolvers:\n    - name: production-signals\n      environment: production\n      signals:\n        branch_patterns: [main, \"release/*\"]\n        env_var_patterns:\n          - var: DATABASE_URL\n            patterns: [prod, production]\n        kube_context_patterns: [\".*prod.*\"]\n        kube_namespace_patterns: [prod, production]\n";
 export type TemplateName = "minimal" | "full" | "solo" | "team";
 export declare function getTemplate(name: TemplateName): string;

package/dist/cli/init/templates.js

@@ -243,6 +243,26 @@ hooks:
     blocking: hard
     budget_ms: 2000
 
+  # Optional: runtime-reality drift gate (NOT enabled by default).
+  # Blocks destructive runtime commands (compose down/restart, systemctl,
+  # kill/pkill, ./deploy-*) when the live process state has drifted from what
+  # your expectations file says should be running. Left COMMENTED on purpose:
+  # the hook is host-coupled and, without RUNTIME_REALITY_KEYWORD + an
+  # expectations file + RUNTIME_REALITY_PROBE_CMD, degrades silently to allow,
+  # a no-op that looks like protection. To arm it, uncomment the entry and
+  # fill in the three env values. The expectations-file format and how to
+  # install the probe are documented in docs/runtime-reality-hook.md.
+  #
+  # - name: runtime-reality
+  #   event: PreToolUse
+  #   command: >-
+  #     RUNTIME_REALITY_KEYWORD=<your-stack>
+  #     RUNTIME_REALITY_EXPECTATIONS_DIR=$HOME/.runtime-reality/expectations
+  #     RUNTIME_REALITY_PROBE_CMD="node $HOME/.runtime-reality/probes/runtime-reality-docker-probe.mjs"
+  #     harness pack hook runtime-reality
+  #   blocking: hard
+  #   description: Block destructive runtime commands on critical process drift
+
 policies:
   - name: review-before-merge
     description: Block PR merges unless a ledger entry tagged review:<pr-number> exists for this session.
@@ -476,6 +496,17 @@ policies:
       ledger_tag: "risk-override:\${SESSION_ID}"
     hook: risk-gate
     enforcement: block
+    # Operator-in-the-loop gate: the override tag is written by the
+    # operator verb (ask semantics), not by the agent. See
+    # writing-custom-policies.md, tripwire 4 (the trust model).
+    producers:
+      - kind: ask
+        command: harness approve risk --force <reason>
+        description: Deliberate operator override for a critical production mutation; run from the operator shell.
+      - kind: mcp
+        verb: mcp__agent-grounding__ledger_add
+        example: '{sessionId:"\${SESSION_ID}", type:"fact", content:"risk-override:\${SESSION_ID} — operator-authorized <reason>", source:"operator"}'
+        description: Recovery path if the approve verb is unavailable; only meaningful when the OPERATOR authorizes the content.
     ux:
       cannot: "You cannot run this critical destructive action against production."
       required:
@@ -496,6 +527,14 @@ policies:
       ledger_tag: "risk-approved:\${SESSION_ID}"
     hook: risk-gate
     enforcement: require_approval
+    producers:
+      - kind: ask
+        command: harness approve risk
+        description: Operator approves this Risk Gate decision from their own shell.
+      - kind: mcp
+        verb: mcp__agent-grounding__ledger_add
+        example: '{sessionId:"\${SESSION_ID}", type:"fact", content:"risk-approved:\${SESSION_ID} — operator-authorized", source:"operator"}'
+        description: Recovery path if the approve verb is unavailable; only meaningful when the OPERATOR authorizes the content.
     ux:
       cannot: "You cannot run this destructive production action yet."
       required:
@@ -539,7 +578,7 @@ policy_packs:
           - "an approved Understanding Report for this session"
         run:
           - "Write an Understanding Report covering: Current Understanding, Intended Outcome, Derived Todos, Acceptance Criteria, Assumptions, Open Questions, Out Of Scope, Risks, Verification Plan, Prior Art (state what you searched for an existing solution and what you found, with an explicit adopt-or-build judgment)"
-          - "Run \`harness approve understanding\` (bare, no pipes, chaining, or redirection) and approve the prompt"
+          - "Run \`harness approve understanding\` with the report attached as a quoted heredoc (harness approve understanding <<'UNDERSTANDING_REPORT' ...report... UNDERSTANDING_REPORT) so it is persisted for audit, then approve the prompt; the heredoc is the only extra shell shape the gate allows (no pipes, chaining, or other redirection)"
       # approval_lifecycle (agent-tasks/d8ee60ca + harness/f54e0ecb,
       # v0.18.0+): expire the approval marker on task-completion
       # boundaries so a multi-task session re-prompts for an

package/dist/cli/init/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/cli/init/templates.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;CAqB/B,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAynB5B,CAAC;AAEF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAI7D,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,SAAS;YACZ,OAAO,gBAAgB,CAAC;IAC5B,CAAC;AACH,CAAC"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/cli/init/templates.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;CAqB/B,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgqB5B,CAAC;AAEF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAI7D,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,SAAS;YACZ,OAAO,gBAAgB,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/cli/loader.js

@@ -54,7 +54,15 @@ function readYamlFile(filePath, label) {
     }
     catch (err) {
         if (err.code === "ENOENT") {
-            throw new HarnessExitError(`${label} not found: ${filePath}`, EX_NOINPUT);
+            // First-run DX (task 24ec07a6): a fresh machine's first command is
+            // often a read verb (doctor/describe/validate), which previously
+            // dead-ended here with no pointer to init. Only the BASE manifest
+            // gets the hint; a missing override layer mid-read is a race, not
+            // a first-run, and "run init" would be wrong advice for it.
+            const hint = label === "manifest"
+                ? ". No harness.yaml on this machine yet: run `harness init --interactive` (or `harness init --template solo`) to create one"
+                : "";
+            throw new HarnessExitError(`${label} not found: ${filePath}${hint}`, EX_NOINPUT);
         }
         throw new HarnessExitError(`${label} could not be read: ${err.message}`, EX_NOINPUT);
     }

package/dist/cli/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/cli/loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/cli/loader.ts"],"names":[],"mappings":"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"}

package/dist/cli/pack/approve-escape.d.ts

@@ -0,0 +1,19 @@
+export interface ApproveReportHeredoc {
+    /** The executable command part (first line, heredoc intro stripped). */
+    command: string;
+    /** The heredoc delimiter word. */
+    delimiter: string;
+    /** The heredoc body — the Understanding Report markdown. */
+    body: string;
+}
+/**
+ * Parse the report-heredoc shape. Returns null unless the WHOLE command
+ * is exactly one clean `harness approve ...` line plus one single-quoted
+ * heredoc and nothing else.
+ */
+export declare function parseApproveReportHeredoc(command: string): ApproveReportHeredoc | null;
+/**
+ * The operator-approval command `harness approve ...`. See module
+ * header for the accepted shapes and the rationale for strictness.
+ */
+export declare function isEscapeCommand(command: string): boolean;

package/dist/cli/pack/approve-escape.js

@@ -0,0 +1,120 @@
+// Escape-command matcher for the understanding-gate PreToolUse hook.
+//
+// The operator-approval command `harness approve ...` must not be
+// hard-denied by the gate (denying the unblock surface makes the gate
+// un-recoverable from inside the session), so the hook defers it to the
+// interactive permission prompt instead. This module decides what
+// qualifies. Deliberately strict: anything that could smuggle other work
+// past the gate (chaining, substitution, redirection) is rejected.
+//
+// Two accepted shapes:
+//   1. Single line: `harness approve ...` with no shell metacharacters.
+//   2. Report heredoc (task 61fd36db): the same command with the
+//      Understanding Report attached as a quoted heredoc on stdin:
+//
+//        harness approve understanding <<'UNDERSTANDING_REPORT'
+//        ## Understanding Report
+//        ...
+//        UNDERSTANDING_REPORT
+//
+//      This is the report-capture channel: the Stop-hook producer fires
+//      only at END of turn (after approve already ran), and current
+//      Claude Code builds do not reliably persist mid-turn assistant
+//      text to the transcript JSONL, so the command itself is the only
+//      channel that reliably carries the report to `harness approve
+//      understanding`. As a bonus the operator reads the full report
+//      inside the permission prompt before approving.
+//
+// Heredoc safety: the delimiter must be single-quoted (no parameter or
+// command substitution inside the body), the command part before `<<`
+// must match a strict character WHITELIST (so no quoting/escaping trick
+// can change how the shell tokenizes the line — see
+// heredocCommandPartIsClean), the terminator is the FIRST line exactly
+// equal to the delimiter (mirroring shell semantics for a plain `<<'X'`
+// intro, which the whitelist guarantees is the only intro that can
+// reach it), and nothing but whitespace may follow it. Any deviation —
+// unquoted delimiter, second redirect, escaped/quote-obscured intro,
+// trailing commands, unterminated body — fails closed to the ordinary
+// gate block.
+/** Metacharacters rejected in the executable (non-heredoc-body) part. */
+const COMMAND_META_RE = /[;&|<>]/;
+function commandPartIsClean(part) {
+    if (COMMAND_META_RE.test(part))
+        return false;
+    if (part.includes("`") || part.includes("$("))
+        return false;
+    return /^harness\s+approve\b/.test(part);
+}
+// The heredoc command part is held to a WHITELIST, not the blacklist
+// above (review 2026-07-10, HIGH): a backslash-escaped redirect
+// (`harness approve understanding \<<'UR'`) slipped the blacklist —
+// the `<` characters were consumed by the heredoc-intro regex and `\`
+// is not a rejected metachar — but bash reads `\<` as a literal `<`
+// plus a file redirect, so no heredoc exists and the "body" lines
+// execute as ordinary commands. A legitimate approve command part only
+// ever contains the binary name, subcommand, flags, ids, and paths;
+// everything else (backslashes, quotes, `$`, parens, globs) fails
+// closed. The single-line shape keeps the blacklist for back-compat:
+// it admits no `<` at all, so this divergence class cannot arise there.
+const HEREDOC_COMMAND_PART_ALLOWED_RE = /^[A-Za-z0-9_\s,./=:@~-]*$/;
+function heredocCommandPartIsClean(part) {
+    if (!HEREDOC_COMMAND_PART_ALLOWED_RE.test(part))
+        return false;
+    return commandPartIsClean(part);
+}
+/**
+ * Parse the report-heredoc shape. Returns null unless the WHOLE command
+ * is exactly one clean `harness approve ...` line plus one single-quoted
+ * heredoc and nothing else.
+ */
+export function parseApproveReportHeredoc(command) {
+    const trimmed = command.trim();
+    const nl = trimmed.indexOf("\n");
+    if (nl === -1)
+        return null;
+    const head = trimmed.slice(0, nl);
+    // CR anywhere in the head means the line structure is not what the
+    // shell will see; fail closed. (Body CRs are inert data.)
+    if (head.includes("\r"))
+        return null;
+    // Lazy `.*?` + end-anchor: a second redirect after the heredoc intro
+    // forces the intro into the command part, where the metachar check
+    // rejects it.
+    const m = /^(.*?)<<\s*'([A-Z_][A-Z0-9_]*)'\s*$/.exec(head);
+    if (!m)
+        return null;
+    const commandPart = m[1].trimEnd();
+    const delimiter = m[2];
+    if (!heredocCommandPartIsClean(commandPart))
+        return null;
+    const rest = trimmed.slice(nl + 1).split("\n");
+    // First line EXACTLY equal to the delimiter terminates the body — the
+    // same rule the shell applies — so a delimiter line smuggled early in
+    // the body shifts the terminator up and the trailing content check
+    // below rejects the command as a whole.
+    const termIdx = rest.findIndex((line) => line === delimiter);
+    if (termIdx === -1)
+        return null;
+    const after = rest.slice(termIdx + 1);
+    if (!after.every((line) => line.trim() === ""))
+        return null;
+    return {
+        command: commandPart,
+        delimiter,
+        body: rest.slice(0, termIdx).join("\n"),
+    };
+}
+/**
+ * The operator-approval command `harness approve ...`. See module
+ * header for the accepted shapes and the rationale for strictness.
+ */
+export function isEscapeCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed.includes("\n")) {
+        if (trimmed.includes("\r"))
+            return false;
+        return commandPartIsClean(trimmed);
+    }
+    return parseApproveReportHeredoc(trimmed) !== null;
+}
+//# sourceMappingURL=approve-escape.js.map

package/dist/cli/pack/approve-escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approve-escape.js","sourceRoot":"","sources":["../../../src/cli/pack/approve-escape.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,kEAAkE;AAClE,sEAAsE;AACtE,wEAAwE;AACxE,kEAAkE;AAClE,yEAAyE;AACzE,mEAAmE;AACnE,EAAE;AACF,uBAAuB;AACvB,wEAAwE;AACxE,iEAAiE;AACjE,mEAAmE;AACnE,EAAE;AACF,gEAAgE;AAChE,iCAAiC;AACjC,aAAa;AACb,8BAA8B;AAC9B,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,qEAAqE;AACrE,uEAAuE;AACvE,oEAAoE;AACpE,qEAAqE;AACrE,sDAAsD;AACtD,EAAE;AACF,uEAAuE;AACvE,sEAAsE;AACtE,wEAAwE;AACxE,oDAAoD;AACpD,uEAAuE;AACvE,wEAAwE;AACxE,mEAAmE;AACnE,uEAAuE;AACvE,qEAAqE;AACrE,sEAAsE;AACtE,cAAc;AAEd,yEAAyE;AACzE,MAAM,eAAe,GAAG,SAAS,CAAC;AAElC,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5D,OAAO,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED,qEAAqE;AACrE,gEAAgE;AAChE,oEAAoE;AACpE,sEAAsE;AACtE,oEAAoE;AACpE,kEAAkE;AAClE,uEAAuE;AACvE,oEAAoE;AACpE,kEAAkE;AAClE,qEAAqE;AACrE,wEAAwE;AACxE,MAAM,+BAA+B,GAAG,2BAA2B,CAAC;AAEpE,SAAS,yBAAyB,CAAC,IAAY;IAC7C,IAAI,CAAC,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe;IAEf,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAClC,mEAAmE;IACnE,0DAA0D;IAC1D,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,qEAAqE;IACrE,mEAAmE;IACnE,cAAc;IACd,MAAM,CAAC,GAAG,qCAAqC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,SAAS,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACxB,IAAI,CAAC,yBAAyB,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,sEAAsE;IACtE,sEAAsE;IACtE,mEAAmE;IACnE,wCAAwC;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAC7D,IAAI,OAAO,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5D,OAAO;QACL,OAAO,EAAE,WAAW;QACpB,SAAS;QACT,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACzC,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,yBAAyB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;AACrD,CAAC"}

package/dist/cli/pack/hook-bootstrap.d.ts

@@ -1,5 +1,5 @@
 import { type LoaderOptions } from "../loader.js";
-import type { Manifest } from "../../schema/index.js";
+import { type Manifest, type PolicyUx } from "../../schema/index.js";
 /**
  * Standard promise-based stdin reader for pack hook events. Resolves to the
  * full UTF-8 string read from the stream. Rejects on stream error.
@@ -45,3 +45,16 @@ export interface ManifestLoadResult {
  *   }
  */
 export declare function loadManifestOrInjected(loaderOpts: LoaderOptions, injected: Manifest | undefined): ManifestLoadResult;
+/**
+ * Parse the optional `ux:` block from a pack config (task 19e293c6). This
+ * body existed as four byte-identical copies (hook-pre-tool-use,
+ * hook-codex-pre-tool-use, hook-branch-protection, hook-solution-acceptance)
+ * whose only difference was the stderr prefix — the exact drift the
+ * CHANGELOG had flagged at copy #3 and that landed a 4th time anyway.
+ * `hookLabel` carries that prefix so the per-hook stderr warnings stay
+ * byte-identical to the pre-extraction output (pinned by a test).
+ *
+ * Best-effort: a malformed `ux:` is ignored with a one-line warning; the
+ * hook then falls back to its legacy message shape.
+ */
+export declare function parseConfigUx(raw: unknown, stderr: NodeJS.WritableStream, hookLabel: string): PolicyUx | undefined;

package/dist/cli/pack/hook-bootstrap.js

@@ -1,7 +1,7 @@
 // Shared bootstrap helpers for Claude Code pack hooks.
 //
-// Extracts the three init-phase boilerplate pieces that all (or most) pack
-// hooks reimplemented independently:
+// Extracts the boilerplate pieces that all (or most) pack hooks
+// reimplemented independently:
 //
 //   1. stdin envelope read (the common event-stream pattern).
 //   2. pause-sentinel check with announcement (wrapping checkPauseFromLoader
@@ -9,6 +9,8 @@
 //   3. manifest load with injection support (the common if-injected / else
 //      loadManifest pattern; callers wrap the call in their own try/catch
 //      because error semantics differ per hook).
+//   4. pack `config.ux` parsing (label-parameterized; formerly four
+//      byte-identical copies, task 19e293c6).
 //
 // Not used by:
 //   - hook-runtime-reality.ts: its stdin reader uses async iteration + an
@@ -21,6 +23,7 @@
 // to each hook. This module covers structural boilerplate only, not semantics.
 import { checkPauseFromLoader } from "../pause-check.js";
 import { loadManifest } from "../loader.js";
+import { PolicyUxSchema } from "../../schema/index.js";
 // ---------------------------------------------------------------------------
 // 1. Standard stdin reader
 // ---------------------------------------------------------------------------
@@ -83,4 +86,31 @@ export function loadManifestOrInjected(loaderOpts, injected) {
     const loaded = loadManifest(loaderOpts);
     return { manifest: loaded.manifest, manifestPath: loaded.resolved.base };
 }
+// ---------------------------------------------------------------------------
+// 4. Pack `config.ux` parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse the optional `ux:` block from a pack config (task 19e293c6). This
+ * body existed as four byte-identical copies (hook-pre-tool-use,
+ * hook-codex-pre-tool-use, hook-branch-protection, hook-solution-acceptance)
+ * whose only difference was the stderr prefix — the exact drift the
+ * CHANGELOG had flagged at copy #3 and that landed a 4th time anyway.
+ * `hookLabel` carries that prefix so the per-hook stderr warnings stay
+ * byte-identical to the pre-extraction output (pinned by a test).
+ *
+ * Best-effort: a malformed `ux:` is ignored with a one-line warning; the
+ * hook then falls back to its legacy message shape.
+ */
+export function parseConfigUx(raw, stderr, hookLabel) {
+    if (raw === undefined)
+        return undefined;
+    const result = PolicyUxSchema.safeParse(raw);
+    if (!result.success) {
+        stderr.write(`${hookLabel}: config.ux ignored (${result.error.issues
+            .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+            .join("; ")})\n`);
+        return undefined;
+    }
+    return result.data;
+}
 //# sourceMappingURL=hook-bootstrap.js.map

package/dist/cli/pack/hook-bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-bootstrap.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-bootstrap.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,2EAA2E;AAC3E,qCAAqC;AACrC,EAAE;AACF,8DAA8D;AAC9D,6EAA6E;AAC7E,6DAA6D;AAC7D,2EAA2E;AAC3E,0EAA0E;AAC1E,iDAAiD;AACjD,EAAE;AACF,eAAe;AACf,0EAA0E;AAC1E,+DAA+D;AAC/D,iEAAiE;AACjE,gDAAgD;AAChD,6EAA6E;AAC7E,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAE/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAsB,MAAM,cAAc,CAAC;AAGhE,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAA6B;IAC3D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,IAAI,IAAI,KAAK,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,MAA6B,EAC7B,UAA0B,EAC1B,YAAqB,EACrB,GAAU;IAEV,OAAO,oBAAoB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;AACpF,CAAC;AAeD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAyB,EACzB,QAA8B;IAE9B,4EAA4E;IAC5E,8EAA8E;IAC9E,sDAAsD;IACtD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"hook-bootstrap.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/cli/pack/hook-branch-protection.js

@@ -39,8 +39,7 @@ import { resolveGeneratedDir } from "../../io/generated-dir.js";
 import { resolveGitContext } from "../../runtime/git-context.js";
 import { POLICY_DECISION_TYPE } from "../../runtime/ledger-record.js";
 import { renderAgentFacing } from "../../runtime/agent-facing.js";
-import { PolicyUxSchema } from "../../schema/index.js";
-import { checkHookPause, loadManifestOrInjected, readStdin, } from "./hook-bootstrap.js";
+import { checkHookPause, loadManifestOrInjected, parseConfigUx, readStdin, } from "./hook-bootstrap.js";
 /**
  * Pull the destination file path out of a PreToolUse event's `tool_input`
  * payload for the tools that mutate a single file. Returns null for tools
@@ -175,21 +174,6 @@ async function probeLedger(manifest, sessionId, opts) {
     }
     return evaluateEntries(result.entries, opts.now ?? new Date());
 }
-// Parse pack config.ux. Mirrors parseConfigUx in hook-pre-tool-use.ts
-// and hook-codex-pre-tool-use.ts; a follow-up cleanup will extract the
-// three copies into a shared helper once we have a fourth call site.
-function parseConfigUx(raw, stderr) {
-    if (raw === undefined)
-        return undefined;
-    const result = PolicyUxSchema.safeParse(raw);
-    if (!result.success) {
-        stderr.write(`harness pack hook branch-protection: config.ux ignored (${result.error.issues
-            .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
-            .join("; ")})\n`);
-        return undefined;
-    }
-    return result.data;
-}
 function blockJson(toolName, branch, detail, protectedList, ux, sessionId) {
     // When the pack config declares `ux:`, the agent-facing surface
     // becomes the plain-language `{ cannot, required, run }` shape and
@@ -303,7 +287,7 @@ export async function runPackHookBranchProtectionCli(opts = {}) {
         return { exitCode: 0, blocked: false, diagnostic };
     }
     const { branches: protectedList } = resolveProtectedBranches(pack);
-    const configUx = parseConfigUx(pack.config["ux"], stderr);
+    const configUx = parseConfigUx(pack.config["ux"], stderr, "harness pack hook branch-protection");
     // Resolve the branch context to gate against. For tools that target a
     // single file (Write, Edit, MultiEdit, NotebookEdit), the relevant
     // branch is whatever repo OWNS the target path — not cwd. Without this