@lannguyensi/harness 0.23.2 → 0.24.1

package/dist/cli/init/profiles.js

@@ -16,8 +16,8 @@
 // Both manifests are validate-clean against the v1 schema. They use the
 // same path layouts as the existing FULL template (`~/git/pandora/...`,
 // `~/.claude/...`); operators on a different layout should override via
-// `~/.claude/machines/<host>.harness.overrides.yaml` (ARCHITECTURE §8).
-export const SOLO_TEMPLATE = `# ~/.claude/harness.yaml
+// `~/.harness/machines/<host>.harness.overrides.yaml` (ARCHITECTURE §8).
+export const SOLO_TEMPLATE = `# ~/.harness/harness.yaml (legacy: ~/.claude/harness.yaml)
 #
 # Bootstrapped by \`harness init --template solo\`.
 #
@@ -28,7 +28,7 @@ export const SOLO_TEMPLATE = `# ~/.claude/harness.yaml
 # review-gating).
 #
 # Adapt the paths under \`command:\` to your install layout, or move
-# host-specific paths to ~/.claude/machines/<host>.harness.overrides.yaml.
+# host-specific paths to ~/.harness/machines/<host>.harness.overrides.yaml.
 
 version: 1
 
@@ -94,7 +94,7 @@ policy_packs:
           - '^git push origin (master|main)\\b'
         max_age: 1h
 `;
-export const TEAM_TEMPLATE = `# ~/.claude/harness.yaml
+export const TEAM_TEMPLATE = `# ~/.harness/harness.yaml (legacy: ~/.claude/harness.yaml)
 #
 # Bootstrapped by \`harness init --template team\`.
 #
@@ -105,7 +105,7 @@ export const TEAM_TEMPLATE = `# ~/.claude/harness.yaml
 # before it can land.
 #
 # Adapt the paths under \`command:\` to your install layout, or move
-# host-specific paths to ~/.claude/machines/<host>.harness.overrides.yaml.
+# host-specific paths to ~/.harness/machines/<host>.harness.overrides.yaml.
 
 version: 1
 

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

@@ -1 +1 @@
-{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../../src/cli/init/profiles.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,uEAAuE;AACvE,yCAAyC;AACzC,EAAE;AACF,sEAAsE;AACtE,kEAAkE;AAClE,kEAAkE;AAClE,kEAAkE;AAClE,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,kEAAkE;AAClE,gDAAgD;AAChD,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,wEAAwE;AACxE,wEAAwE;AAExE,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4E5B,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwI5B,CAAC"}
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../../src/cli/init/profiles.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,uEAAuE;AACvE,yCAAyC;AACzC,EAAE;AACF,sEAAsE;AACtE,kEAAkE;AAClE,kEAAkE;AAClE,kEAAkE;AAClE,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,kEAAkE;AAClE,gDAAgD;AAChD,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,wEAAwE;AACxE,yEAAyE;AAEzE,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4E5B,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwI5B,CAAC"}

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

@@ -1,4 +1,4 @@
-export declare const MINIMAL_TEMPLATE = "# ~/.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 ~/.claude/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 = "# ~/.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.1.1, the release that distinguishes\n    # \"tool not installed\" (e.g. an npm script invoking eslint that is\n    # not in devDependencies) from real lint/test/typecheck failures.\n    # Stale 0.1.0 installs silently emit false-positive blockers that\n    # keep the preflight-before-* policies closed forever. version_command\n    # points at the source-of-truth preflight binary, not at the\n    # `harness session-start preflight` wrapper.\n    min_version: \"0.1.1\"\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\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      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      run:\n        - \"harness preflight\"\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\"\n          - \"Run `harness approve understanding` 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 a `branch-protection-ack:<reason>` override the operator writes\n  # via mcp__agent-grounding__ledger_add for deliberate protected-branch\n  # edits (version bumps, CI workflow patches, hotfixes).\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";
+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.1.1, the release that distinguishes\n    # \"tool not installed\" (e.g. an npm script invoking eslint that is\n    # not in devDependencies) from real lint/test/typecheck failures.\n    # Stale 0.1.0 installs silently emit false-positive blockers that\n    # keep the preflight-before-* policies closed forever. version_command\n    # points at the source-of-truth preflight binary, not at the\n    # `harness session-start preflight` wrapper.\n    min_version: \"0.1.1\"\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\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      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      run:\n        - \"harness preflight\"\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\"\n          - \"Run `harness approve understanding` 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 a `branch-protection-ack:<reason>` override the operator writes\n  # via mcp__agent-grounding__ledger_add for deliberate protected-branch\n  # edits (version bumps, CI workflow patches, hotfixes).\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";
 export type TemplateName = "minimal" | "full" | "solo" | "team";
 export declare function getTemplate(name: TemplateName): string;

package/dist/cli/init/templates.js

@@ -1,4 +1,4 @@
-export const MINIMAL_TEMPLATE = `# ~/.claude/harness.yaml
+export const MINIMAL_TEMPLATE = `# ~/.harness/harness.yaml (legacy: ~/.claude/harness.yaml)
 #
 # Bootstrapped by \`harness init --template minimal\`.
 #
@@ -13,14 +13,14 @@ export const MINIMAL_TEMPLATE = `# ~/.claude/harness.yaml
 #
 # Phase 2 verbs to add entries safely: \`harness add mcp <name> ...\`,
 # \`harness add cli\`, \`harness add hook\`, \`harness add skill\`.
-# Per-machine overrides live at ~/.claude/machines/<discriminator>.harness.overrides.yaml
+# Per-machine overrides live at ~/.harness/machines/<discriminator>.harness.overrides.yaml
 # (ARCHITECTURE.md §8) for paths that vary per host.
 #
 # Docs: https://github.com/LanNguyenSi/harness
 
 version: 1
 `;
-export const FULL_TEMPLATE = `# ~/.claude/harness.yaml
+export const FULL_TEMPLATE = `# ~/.harness/harness.yaml (legacy: ~/.claude/harness.yaml)
 #
 # Bootstrapped by \`harness init --template full\`. The reference manifest:
 # every example policy from docs/examples/full-manifest.yaml wired through

package/dist/cli/loader.js

@@ -1,14 +1,17 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { applyLayers } from "../overrides/merge.js";
 import { machineOverrideCandidates, resolveMachineDiscriminators, } from "../overrides/machines.js";
 import { ManifestParseError, parseManifest } from "../schema/index.js";
+import { resolveHomeDir } from "../runtime/home-dir.js";
 import { EX_NOINPUT, HarnessExitError } from "./exit-codes.js";
 const DEFAULT_BASENAME = "harness.yaml";
 function defaultHome(opts) {
-    return opts.homeDir ?? path.join(os.homedir(), ".claude");
+    // resolveHomeDir handles flag > $HARNESS_HOME > ~/.harness/ (new) >
+    // ~/.claude/ (legacy fallback with deprecation warning) >
+    // ~/.harness/ (create-on-first-use). See runtime/home-dir.ts.
+    return resolveHomeDir({ ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}) }).path;
 }
 export function resolvePaths(opts = {}) {
     if (opts.homeDir === undefined &&
@@ -17,12 +20,13 @@ export function resolvePaths(opts = {}) {
         // Defense against the recurring test-isolation class (v0.21.1 preflight
         // stage leak, v0.22.0 approveUnderstanding marker leak, latent post-pause
         // pause-sentinel read leak): without an explicit `homeDir` or
-        // `configPath`, this resolver would silently fall back to
-        // `~/.claude/harness.yaml` and the caller would read/write the
-        // operator's runtime dir. The harness CLI binary sets the env var
-        // before `run()`; tests don't, so this throw surfaces leak sites at
-        // assertion time instead of as silent operator-state mutation.
-        throw new Error("resolvePaths refused to fall back to ~/.claude/ — set { homeDir } or { configPath } on LoaderOptions, " +
+        // `configPath`, this resolver would silently fall back to the
+        // operator's real `~/.harness/` (or legacy `~/.claude/`) and the
+        // caller would read/write that real state dir. The harness CLI
+        // binary sets the env var before `run()`; tests don't, so this
+        // throw surfaces leak sites at assertion time instead of as silent
+        // operator-state mutation.
+        throw new Error("resolvePaths refused to fall back to the real harness home dir, set { homeDir } or { configPath } on LoaderOptions, " +
             "or (for the real harness binary) set HARNESS_ALLOW_REAL_GENERATED_DIR=1");
     }
     const home = defaultHome(opts);

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/main.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-// Opt the binary into reading the operator's real `~/.claude/harness.yaml`
-// fallback when no --config / --home is supplied. The loader (`resolvePaths`)
+// Opt the binary into reading the operator's real harness home dir
+// (`~/.harness/harness.yaml` preferred, `~/.claude/harness.yaml` as
+// legacy fallback) when no --config / --home is supplied. The loader
+// (`resolvePaths`)
 // refuses that fallback unless this flag is set, so tests that forget to
 // inject `homeDir` / `generatedDir` fail loudly instead of silently
 // reading/writing the operator's runtime dir. Recurring class, two prior

package/dist/cli/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AACA,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,oEAAoE;AACpE,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,mCAAmC;AACnC,EAAE;AACF,sEAAsE;AACtE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,6DAA6D;AAC7D,sEAAsE;AACtE,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,GAAG,GAAG,CAAC;AAEtD,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEjC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;IAClB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AACA,mEAAmE;AACnE,oEAAoE;AACpE,qEAAqE;AACrE,mBAAmB;AACnB,yEAAyE;AACzE,oEAAoE;AACpE,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,mCAAmC;AACnC,EAAE;AACF,sEAAsE;AACtE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,6DAA6D;AAC7D,sEAAsE;AACtE,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,GAAG,GAAG,CAAC;AAEtD,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEjC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;IAClB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC,CAAC,CAAC"}

package/dist/cli/migrate-home/index.d.ts

@@ -0,0 +1,39 @@
+export declare const MIGRATION_MARKER_BASENAME = "MOVED_TO_~_DOT_HARNESS.txt";
+export interface MigrateHomeOptions {
+    /** If true, perform the move; otherwise dry-run. */
+    apply?: boolean;
+    /** Test injection for `os.homedir()`. */
+    userHome?: string;
+    /** Test injection for stdout. */
+    stdout?: NodeJS.WritableStream;
+    /** Test injection for stderr. */
+    stderr?: NodeJS.WritableStream;
+}
+export interface MigrateHomeResult {
+    legacyPath: string;
+    newPath: string;
+    /** Per-item plan: what was found, what would be moved, what was moved. */
+    items: MigrateHomeItemResult[];
+    /**
+     * Outcome of the run:
+     *   - `no-op`: nothing to migrate (legacy dir empty, or already moved).
+     *   - `would-apply`: dry-run; the listed items would move.
+     *   - `applied`: items moved this run.
+     *   - `partial`: some items moved before an error stopped the run.
+     *   - `target-conflict`: a corresponding item already exists at the
+     *     new path; the run refuses to overwrite. Operator must resolve.
+     */
+    outcome: "no-op" | "would-apply" | "applied" | "partial" | "target-conflict";
+    /** Path of the breadcrumb marker, present on `applied`. */
+    markerPath?: string;
+}
+export interface MigrateHomeItemResult {
+    basename: string;
+    legacyExists: boolean;
+    newExists: boolean;
+    /** What the run did (or would do) with this item. */
+    action: "skip" | "would-move" | "moved" | "target-exists";
+    /** Error message if `target-exists` or a move failed. */
+    detail?: string;
+}
+export declare function migrateHome(opts?: MigrateHomeOptions): MigrateHomeResult;

package/dist/cli/migrate-home/index.js

@@ -0,0 +1,194 @@
+// Phase 7 / v0.24.0 — `harness migrate-home` command.
+//
+// Moves harness operator-state from the legacy `~/.claude/` root to the
+// runtime-neutral `~/.harness/` introduced in task e65decef. Default
+// behaviour is dry-run (plan + report, no writes); `--apply` performs
+// the move. Re-running on already-migrated state is a no-op.
+//
+// What gets moved:
+//   - `~/.claude/harness.yaml`              → `~/.harness/harness.yaml`
+//   - `~/.claude/harness.generated/`        → `~/.harness/harness.generated/`
+//   - `~/.claude/.understanding-gate/`      → `~/.harness/.understanding-gate/`
+//   - `~/.claude/harness.lock`              → `~/.harness/harness.lock`
+//
+// What is NOT touched (operator-owned, runtime config, not harness state):
+//   - `~/.claude/settings.json`             (Claude Code's runtime config)
+//   - any other operator-authored content under `~/.claude/`
+//
+// Atomicity contract:
+//   - Each item is moved with `fs.renameSync` first. If that fails with
+//     `EXDEV` (cross-filesystem rename), the command falls back to a
+//     copy-then-delete sequence so the source side is removed only
+//     after the destination side is fully written.
+//   - The four items are moved in sequence. A failure midway leaves a
+//     partial state in `~/.harness/` and the remaining items in
+//     `~/.claude/`. The deprecation warning will fire on the next
+//     command (legacy detection sees the remaining state) and the
+//     operator can re-run `harness migrate-home --apply` to finish.
+//   - Subsequent passes are idempotent: items already missing on the
+//     source side are skipped.
+//
+// On successful `--apply`, a small marker `MOVED_TO_~_DOT_HARNESS.txt`
+// is written into `~/.claude/` so an operator who later runs an old
+// command from muscle memory has a paper trail pointing at the new
+// location. The marker is plain text and does not block any other
+// `~/.claude/` consumer (e.g. Claude Code itself).
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { HARNESS_HOME_DIRNAME, LEGACY_HARNESS_HOME_DIRNAME, } from "../../runtime/home-dir.js";
+import { EX_FAIL, HarnessExitError } from "../exit-codes.js";
+export const MIGRATION_MARKER_BASENAME = "MOVED_TO_~_DOT_HARNESS.txt";
+const ITEMS = [
+    { basename: "harness.yaml", isDir: false },
+    { basename: "harness.generated", isDir: true },
+    { basename: ".understanding-gate", isDir: true },
+    { basename: "harness.lock", isDir: false },
+];
+export function migrateHome(opts = {}) {
+    const userHome = opts.userHome ?? os.homedir();
+    const legacyPath = path.join(userHome, LEGACY_HARNESS_HOME_DIRNAME);
+    const newPath = path.join(userHome, HARNESS_HOME_DIRNAME);
+    const stdout = opts.stdout ?? process.stdout;
+    const stderr = opts.stderr ?? process.stderr;
+    const apply = opts.apply === true;
+    // Plan phase: classify each item by (legacy exists, new exists).
+    const items = ITEMS.map((it) => {
+        const legacyItem = path.join(legacyPath, it.basename);
+        const newItem = path.join(newPath, it.basename);
+        const legacyExists = pathExists(legacyItem);
+        const newExists = pathExists(newItem);
+        if (!legacyExists) {
+            return { basename: it.basename, legacyExists, newExists, action: "skip" };
+        }
+        if (newExists) {
+            return {
+                basename: it.basename,
+                legacyExists,
+                newExists,
+                action: "target-exists",
+                detail: `${newItem} already present; refuse to overwrite. Inspect, then remove one side and re-run.`,
+            };
+        }
+        return {
+            basename: it.basename,
+            legacyExists,
+            newExists,
+            action: "would-move",
+        };
+    });
+    const movable = items.filter((i) => i.action === "would-move");
+    const conflicts = items.filter((i) => i.action === "target-exists");
+    if (conflicts.length > 0) {
+        for (const c of conflicts) {
+            stderr.write(`harness migrate-home: ${c.basename}: ${c.detail}\n`);
+        }
+        return { legacyPath, newPath, items, outcome: "target-conflict" };
+    }
+    if (movable.length === 0) {
+        stdout.write(`harness migrate-home: nothing to migrate (no harness state under ${legacyPath}).\n`);
+        return { legacyPath, newPath, items, outcome: "no-op" };
+    }
+    if (!apply) {
+        stdout.write(`harness migrate-home: would move ${movable.length} item(s) from ${legacyPath} to ${newPath}:\n`);
+        for (const m of movable) {
+            stdout.write(`  ${path.join(legacyPath, m.basename)}\n`);
+        }
+        stdout.write("Re-run with --apply to perform the move. After moving, run `harness apply` to regenerate any embedded paths (e.g. UNDERSTANDING_GATE_REPORT_DIR in settings.json).\n");
+        return { legacyPath, newPath, items, outcome: "would-apply" };
+    }
+    // Apply phase: move each item. Create the destination root first.
+    try {
+        fs.mkdirSync(newPath, { recursive: true });
+    }
+    catch (err) {
+        throw new HarnessExitError(`failed to create ${newPath}: ${err.message}`, EX_FAIL);
+    }
+    let anyError = null;
+    for (const m of movable) {
+        const src = path.join(legacyPath, m.basename);
+        const dst = path.join(newPath, m.basename);
+        try {
+            moveSync(src, dst);
+            m.action = "moved";
+            stdout.write(`moved ${src} to ${dst}\n`);
+        }
+        catch (err) {
+            const msg = err.message;
+            m.detail = msg;
+            anyError = msg;
+            stderr.write(`harness migrate-home: failed to move ${m.basename}: ${msg}\n`);
+            break;
+        }
+    }
+    const moved = items.filter((i) => i.action === "moved");
+    if (moved.length > 0) {
+        // Breadcrumb: drop a small text file so an operator who later
+        // recalls the old path knows where to look.
+        const markerPath = path.join(legacyPath, MIGRATION_MARKER_BASENAME);
+        try {
+            const body = [
+                `harness state was migrated to ${newPath} on ${new Date().toISOString()}.`,
+                "",
+                "If you are looking for harness.yaml, harness.generated/, or .understanding-gate/,",
+                `they now live under ${newPath}.`,
+                "",
+                "Files moved this run:",
+                ...moved.map((m) => `  - ${m.basename}`),
+                "",
+                "Note: this marker is harness-owned. Your Claude Code settings.json and any",
+                "other ~/.claude/ contents were not touched.",
+                "",
+            ].join("\n");
+            fs.writeFileSync(markerPath, body);
+        }
+        catch {
+            /* best-effort breadcrumb; failure to write the marker does not unwind the move */
+        }
+        if (anyError !== null) {
+            return {
+                legacyPath,
+                newPath,
+                items,
+                outcome: "partial",
+                markerPath,
+            };
+        }
+        stdout.write("Run `harness apply` to regenerate any embedded paths (e.g. UNDERSTANDING_GATE_REPORT_DIR in settings.json) and re-emit hook command strings against the new home dir.\n");
+        return {
+            legacyPath,
+            newPath,
+            items,
+            outcome: "applied",
+            markerPath,
+        };
+    }
+    // No items actually moved despite plan saying we should — fell into
+    // an error on the first item. Surface as partial.
+    return { legacyPath, newPath, items, outcome: "partial" };
+}
+function pathExists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function moveSync(src, dst) {
+    try {
+        fs.renameSync(src, dst);
+        return;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code !== "EXDEV")
+            throw err;
+    }
+    // Cross-filesystem fallback: recursive copy then delete. fs.cpSync
+    // is in Node 16.7+; harness requires Node 18+ per package.json.
+    fs.cpSync(src, dst, { recursive: true });
+    fs.rmSync(src, { recursive: true, force: true });
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/migrate-home/index.js.map

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

package/dist/cli/pack/add.js

@@ -4,10 +4,10 @@
 // flock; surface dup-name + bad-mode errors at the point the user runs
 // the command, not at the next `harness apply`.
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { atomicWriteFile } from "../../io/atomic-write.js";
+import { resolveHomeDir } from "../../runtime/home-dir.js";
 import { withFileLock } from "../../io/lock.js";
 import { unifiedDiff } from "../../io/patch.js";
 import { formatValidationErrors, validateBeforeWrite, } from "../../io/validate-before-write.js";
@@ -20,7 +20,7 @@ const LOCK_BASENAME = ".harness.lock";
 function resolveTargetPath(opts) {
     if (opts.configPath)
         return path.resolve(opts.configPath);
-    return path.join(opts.homeDir ?? path.join(os.homedir(), ".claude"), DEFAULT_BASENAME);
+    return path.join(resolveHomeDir({ ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}) }).path, DEFAULT_BASENAME);
 }
 export async function packAdd(entry, opts = {}) {
     const target = resolveTargetPath(opts);

package/dist/cli/pack/add.js.map

@@ -1 +1 @@
-{"version":3,"file":"add.js","sourceRoot":"","sources":["../../../src/cli/pack/add.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"add.js","sourceRoot":"","sources":["../../../src/cli/pack/add.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,gDAAgD;AAEhD,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EACL,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAqB,MAAM,aAAa,CAAC;AAe9D,MAAM,gBAAgB,GAAG,cAAc,CAAC;AACxC,MAAM,aAAa,GAAG,eAAe,CAAC;AAEtC,SAAS,iBAAiB,CAAC,IAAoB;IAC7C,IAAI,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,IAAI,CACd,cAAc,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,EACzF,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAmB,EACnB,OAAuB,EAAE;IAEzB,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,gBAAgB,CACxB,iCAAiC,MAAM,8BAA8B,EACrE,UAAU,CACX,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,0EAA0E;IAC1E,yEAAyE;IACzE,4CAA4C;IAC5C,MAAM,YAAY,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC;IAChE,IAAI,YAAY,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,IAAI,gBAAgB,CACxB,uBAAuB,IAAI,CAAC,SAAS,CACnC,KAAK,CAAC,MAAM,CACb,6EAA6E,EAC9E,OAAO,CACR,CAAC;IACJ,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,gBAAgB,CACxB,qBAAqB,IAAI,CAAC,SAAS,CACjC,KAAK,CAAC,IAAI,CACX,2EAA2E,EAC5E,OAAO,CACR,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,WAAW,CAAC;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC/B,OAAO,EAAE,QAAQ;QACjB,OAAO,EAAE,QAAQ;QACjB,SAAS,EAAE,SAAS;QACpB,SAAS,EAAE,UAAU;KACtB,CAAC,CAAC;IAEH,qEAAqE;IACrE,6CAA6C;IAC7C,MAAM,YAAY,GAAG,mBAAmB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;QACrB,MAAM,IAAI,gBAAgB,CACxB,+CAA+C,sBAAsB,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,EAC5F,OAAO,CACR,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAClE,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC;IAChE,MAAM,YAAY,CAAC,QAAQ,EAAE,GAAG,EAAE;QAChC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,mBAAmB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QACrD,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,MAAM,IAAI,gBAAgB,CACxB,sEAAsE,sBAAsB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAC9G,OAAO,CACR,CAAC;QACJ,CAAC;QACD,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC"}

package/dist/cli/pack/hook-codex-pre-tool-use.js

@@ -21,7 +21,7 @@
 // net for solo users; the harness blocker is strictly more powerful.
 import { queryLedgerByTag } from "../../policies/index.js";
 import { checkApprovalMarker, checkPersistedReport, defaultReportsDir, matchLedgerEntries, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
-import { resolveGeneratedDir } from "../../runtime/pending-approval.js";
+import { resolveGeneratedDir, writePendingApproval, } from "../../runtime/pending-approval.js";
 import { renderAgentFacing } from "../../runtime/agent-facing.js";
 import { PolicyUxSchema } from "../../schema/index.js";
 import { loadManifest } from "../loader.js";
@@ -187,6 +187,21 @@ export async function runPackHookCodexPreToolUseCli(opts = {}) {
     }
     // Audit-only ledger probe.
     const ledger = await checkLedger(manifest, sessionId, opts);
+    // Stage the session id so `harness approve understanding`, run from
+    // the operator's shell where neither $CODEX_SESSION_ID nor
+    // $CLAUDE_SESSION_ID is set, can resolve it without scraping logs or
+    // grepping transcript dirs. Mirrors the Claude blocker's symmetric
+    // staging (hook-pre-tool-use.ts) so arg-less approval after a Codex
+    // PreToolUse block has the same shape. Best-effort: a staging-write
+    // failure must not escalate a gate block into a hook error.
+    if (generatedDir !== undefined) {
+        try {
+            writePendingApproval(generatedDir, sessionId);
+        }
+        catch {
+            /* best-effort; the block below proceeds regardless */
+        }
+    }
     // Neither operator source approved. Codex blocks via non-zero exit
     // + stderr reason; there is no JSON-decision wire to write to stdout.
     const reason = generatedDir !== undefined