repo-harness 0.8.2 → 0.8.3

package/AGENTS.md

@@ -6,7 +6,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
 - `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
-- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; task contracts stay the execution slices)
+- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `repo-harness run sprint-backlog`; task contracts stay the execution slices
 - `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
 - `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
 - `tasks/lessons.md` for correction-derived rules
@@ -35,8 +35,8 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
 - Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
 - Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
-- Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
-- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `scripts/capture-plan.sh --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- Treat contract-level task execution as worktree-first: `repo-harness run plan-to-todo --plan <approved-plan>` starts `repo-harness run contract-worktree start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `repo-harness run contract-worktree finish`.
+- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `repo-harness run plan-to-todo --plan <active-plan>`.
 - Promote work into a top-level `plans/plan-*.md` only when `Artifact Level: work-package` is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan `## Task Breakdown`; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
 - If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
 - Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
@@ -55,7 +55,7 @@ bun test
 bash scripts/check-deploy-sql-order.sh
 bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
-bash scripts/check-task-workflow.sh --strict
+repo-harness run check-task-workflow --strict
 bun scripts/inspect-project-state.ts --repo . --format text
 bash scripts/migrate-project-template.sh --repo . --dry-run
 ```

package/CLAUDE.md

@@ -6,7 +6,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
 - `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
-- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; task contracts stay the execution slices)
+- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `repo-harness run sprint-backlog`; task contracts stay the execution slices
 - `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
 - `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
 - `tasks/lessons.md` for correction-derived rules
@@ -35,8 +35,8 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
 - Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
 - Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
-- Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
-- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `scripts/capture-plan.sh --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- Treat contract-level task execution as worktree-first: `repo-harness run plan-to-todo --plan <approved-plan>` starts `repo-harness run contract-worktree start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `repo-harness run contract-worktree finish`.
+- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `repo-harness run plan-to-todo --plan <active-plan>`.
 - Promote work into a top-level `plans/plan-*.md` only when `Artifact Level: work-package` is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan `## Task Breakdown`; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
 - If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
 - Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
@@ -55,7 +55,7 @@ bun test
 bash scripts/check-deploy-sql-order.sh
 bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
-bash scripts/check-task-workflow.sh --strict
+repo-harness run check-task-workflow --strict
 bun scripts/inspect-project-state.ts --repo . --format text
 bash scripts/migrate-project-template.sh --repo . --dry-run
 ```

package/README.es.md

@@ -85,7 +85,7 @@ artifacts.
 ## Novedades
 
 Las notas de versión viven en [`docs/CHANGELOG.md`](docs/CHANGELOG.md). La línea
-actual es `0.8.2`.
+actual es `0.8.3`.
 
 ## Cómo funciona
 
@@ -419,8 +419,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.8.2`
-- Generated workflow stamp: `repo-harness@0.8.2+template@0.8.2`
+- npm package: `repo-harness@0.8.3`
+- Generated workflow stamp: `repo-harness@0.8.3+template@0.8.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -85,7 +85,7 @@ l'emportent.
 ## Nouveautés
 
 Les notes de version vivent dans [`docs/CHANGELOG.md`](docs/CHANGELOG.md). La
-ligne actuelle est `0.8.2`.
+ligne actuelle est `0.8.3`.
 
 ## Comment ça marche
 
@@ -424,8 +424,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.8.2`
-- Generated workflow stamp : `repo-harness@0.8.2+template@0.8.2`
+- npm package : `repo-harness@0.8.3`
+- Generated workflow stamp : `repo-harness@0.8.3+template@0.8.3`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -75,7 +75,7 @@ review、checks、handoff と食い違う場合は、source artifacts を優先
 ## What's New
 
 リリースノートは [`docs/CHANGELOG.md`](docs/CHANGELOG.md) にあります。現在の
-ラインは `0.8.2` です。
+ラインは `0.8.3` です。
 
 ## 仕組み
 
@@ -398,8 +398,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.8.2`
-- Generated workflow stamp：`repo-harness@0.8.2+template@0.8.2`
+- npm package：`repo-harness@0.8.3`
+- Generated workflow stamp：`repo-harness@0.8.3+template@0.8.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -79,7 +79,7 @@ active plan, contract, review, checks, or handoff, the source artifacts win.
 ## What's New
 
 Release notes live in [`docs/CHANGELOG.md`](docs/CHANGELOG.md). The current line
-is `0.8.2`.
+is `0.8.3`.
 
 ## How It Works
 
@@ -599,8 +599,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.8.2`
-- Generated workflow stamp: `repo-harness@0.8.2+template@0.8.2`
+- npm package: `repo-harness@0.8.3`
+- Generated workflow stamp: `repo-harness@0.8.3+template@0.8.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -69,7 +69,7 @@ review、checks 或 handoff 冲突，以 source artifacts 为准。
 
 ## What's New
 
-Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是 `0.8.2`。
+Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是 `0.8.3`。
 
 ## 工作原理
 
@@ -445,8 +445,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.8.2`
-- Generated workflow stamp：`repo-harness@0.8.2+template@0.8.2`
+- npm package：`repo-harness@0.8.3`
+- Generated workflow stamp：`repo-harness@0.8.3+template@0.8.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/assets/hooks/AGENTS.md

@@ -37,7 +37,7 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 ## Refresh Hints
 
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
-- `bash scripts/check-task-workflow.sh --strict`
+- `repo-harness run check-task-workflow --strict`
 <!-- END CAPABILITY CONTEXT -->
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->

package/assets/hooks/CLAUDE.md

@@ -37,7 +37,7 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 ## Refresh Hints
 
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
-- `bash scripts/check-task-workflow.sh --strict`
+- `repo-harness run check-task-workflow --strict`
 <!-- END CAPABILITY CONTEXT -->
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->

package/assets/hooks/lib/workflow-state.sh

@@ -641,7 +641,7 @@ workflow_next_action() {
     target="$(workflow_target_branch)"
     current_branch="$(workflow_current_branch)"
     if workflow_is_linked_worktree && [[ -n "$current_branch" && "$current_branch" != "$target" ]]; then
-      printf 'finish\tbash scripts/contract-worktree.sh finish\tReview/checks pass; finish and fast-forward merge this contract worktree.\n'
+      printf 'finish\trepo-harness run contract-worktree finish\tReview/checks pass; finish and fast-forward merge this contract worktree.\n'
       return 0
     fi
   fi
@@ -649,7 +649,7 @@ workflow_next_action() {
   if candidate="$(workflow_cleanup_candidate)"; then
     IFS=$'\t' read -r slug branch worktree <<< "$candidate"
     target="$(workflow_target_branch)"
-    command="bash scripts/contract-worktree.sh cleanup --slug ${slug} --target ${target}"
+    command="repo-harness run contract-worktree cleanup --slug ${slug} --target ${target}"
     printf 'cleanup\t%s\tClean up merged contract worktree %s.\n' "$command" "${branch:-$slug}"
     return 0
   fi

package/assets/hooks/post-edit-guard.sh

@@ -11,10 +11,27 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 . "$SCRIPT_DIR/lib/workflow-state.sh"
 
+repo_harness_runner_available() {
+  if [[ -n "${REPO_HARNESS_CLI:-}" && -f "$REPO_HARNESS_CLI" ]] && command -v bun >/dev/null 2>&1; then
+    return 0
+  fi
+  command -v repo-harness >/dev/null 2>&1
+}
+
+run_repo_harness_helper() {
+  local helper="$1"
+  shift
+  if [[ -n "${REPO_HARNESS_CLI:-}" && -f "$REPO_HARNESS_CLI" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$REPO_HARNESS_CLI" run "$helper" "$@"
+    return $?
+  fi
+  repo-harness run "$helper" "$@"
+}
+
 run_continuous_contract_verification() {
   local active_plan contract_file checks_file
 
-  [[ -f "scripts/verify-contract.sh" ]] || return 0
+  repo_harness_runner_available || return 0
 
   active_plan="$(get_active_plan || true)"
   [[ -n "$active_plan" && -f "$active_plan" ]] || return 0
@@ -25,16 +42,16 @@ run_continuous_contract_verification() {
   mkdir -p "$(dirname "$checks_file")"
 
   if contract_references_path "$contract_file" "$FILE_PATH"; then
-    bash "scripts/verify-contract.sh" --contract "$contract_file" --quiet --report-file "$checks_file" || true
+    run_repo_harness_helper verify-contract --contract "$contract_file" --quiet --report-file "$checks_file" || true
   fi
 }
 
 run_architecture_queue_sync() {
   local queue_output status
 
-  [[ -x "scripts/architecture-queue.sh" ]] || return 0
+  repo_harness_runner_available || return 0
 
-  if queue_output="$(bash "scripts/architecture-queue.sh" record --file "$FILE_PATH" 2>&1)"; then
+  if queue_output="$(run_repo_harness_helper architecture-queue record --file "$FILE_PATH" 2>&1)"; then
     :
   else
     status=$?
@@ -45,8 +62,8 @@ run_architecture_queue_sync() {
   [[ -n "$queue_output" ]] && printf '%s\n' "$queue_output"
 
   if printf '%s\n' "$queue_output" | grep -q '^\[ArchitectureDrift\] Request:'; then
-    if [[ -x "scripts/context-contract-sync.sh" ]]; then
-      if bash "scripts/context-contract-sync.sh" sync-latest; then
+    if repo_harness_runner_available; then
+      if run_repo_harness_helper context-contract-sync sync-latest; then
         :
       else
         status=$?
@@ -79,7 +96,7 @@ run_architecture_queue_sync() {
 }
 
 run_brain_doc_sync() {
-  [[ -x "scripts/sync-brain-docs.sh" ]] || return 0
+  repo_harness_runner_available || return 0
   [[ -f ".ai/harness/brain-manifest.json" ]] || return 0
 
   # Fast-path: most edits are not repo-to-brain sources. Avoid starting the JS
@@ -88,7 +105,7 @@ run_brain_doc_sync() {
     return 0
   fi
 
-  if bash "scripts/sync-brain-docs.sh" --changed "$FILE_PATH"; then
+  if run_repo_harness_helper sync-brain-docs --changed "$FILE_PATH"; then
     :
   else
     local status=$?

package/assets/hooks/pre-edit-guard.sh

@@ -100,12 +100,12 @@ run_edit_plan_gate() {
   if [[ ! -f "docs/spec.md" ]]; then
     echo "[SpecGuard] Implementation edit without docs/spec.md: $FILE_PATH"
     if [[ "$mode" == "advice" ]]; then
-      echo "[SpecGuard] Advisory: run bash scripts/new-spec.sh and capture stable product intent."
+      echo "[SpecGuard] Advisory: run repo-harness run new-spec and capture stable product intent."
     else
       hook_structured_error \
         "SpecGuard" \
         "Implementation edit to $FILE_PATH without docs/spec.md." \
-        "Run bash scripts/new-spec.sh and capture stable product intent before implementing." \
+        "Run repo-harness run new-spec and capture stable product intent before implementing." \
         "missing_artifact"
       exit 2
     fi
@@ -115,12 +115,12 @@ run_edit_plan_gate() {
   if [[ -z "$gate_plan" || ! -f "$gate_plan" ]]; then
     echo "[PlanStatusGuard] No active plan covers implementation edit: $FILE_PATH"
     if [[ "$mode" == "advice" ]]; then
-      echo "[PlanStatusGuard] Advisory: capture the approved plan with bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute"
+      echo "[PlanStatusGuard] Advisory: capture the approved plan with repo-harness run capture-plan --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute"
     else
       hook_structured_error \
         "PlanStatusGuard" \
         "Implementation edit to $FILE_PATH without an active plan." \
-        "Capture the approved planning output with bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute, or set policy .guards.edit_plan_gate to advice/off for this repo." \
+        "Capture the approved planning output with repo-harness run capture-plan --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute, or set policy .guards.edit_plan_gate to advice/off for this repo." \
         "missing_artifact"
       exit 2
     fi

package/assets/hooks/prompt-guard.sh

@@ -27,6 +27,23 @@ if [[ -f "$SCRIPT_DIR/lib/minimal-change.sh" ]]; then
   . "$SCRIPT_DIR/lib/minimal-change.sh"
 fi
 
+repo_harness_runner_available() {
+  if [[ -n "${REPO_HARNESS_CLI:-}" && -f "$REPO_HARNESS_CLI" ]] && command -v bun >/dev/null 2>&1; then
+    return 0
+  fi
+  command -v repo-harness >/dev/null 2>&1
+}
+
+run_repo_harness_helper() {
+  local helper="$1"
+  shift
+  if [[ -n "${REPO_HARNESS_CLI:-}" && -f "$REPO_HARNESS_CLI" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$REPO_HARNESS_CLI" run "$helper" "$@"
+    return $?
+  fi
+  repo-harness run "$helper" "$@"
+}
+
 # --- Filesystem/worktree helpers (shell-owned authority) ---
 
 prompt_matches_worktree_record() {
@@ -518,7 +535,7 @@ emit_pending_orchestration_discussion() {
   echo "[PlanDiscussionGate] Pending plan/orchestration discussion is still open; continuing discussion, not implementation."
   echo "[PlanDiscussionGate] $(workflow_pending_orchestration_summary)"
   echo "[PlanDiscussionGate] When the decision is complete, capture the final plan body before editing implementation files:"
-  echo "  printf '%s\n' '<decision-complete plan body>' | bash scripts/capture-plan.sh --slug <slug> --title <title> --status Draft --source ${kind:-host-plan} --orchestration-kind ${kind:-host-plan} --route planning${source_arg}"
+  echo "  printf '%s\n' '<decision-complete plan body>' | repo-harness run capture-plan --slug <slug> --title <title> --status Draft --source ${kind:-host-plan} --orchestration-kind ${kind:-host-plan} --route planning${source_arg}"
 }
 
 emit_pending_orchestration_capture_gate() {
@@ -531,7 +548,7 @@ emit_pending_orchestration_capture_gate() {
   echo "[PlanCaptureGate] Implementation requested while a pending plan/orchestration discussion has not been captured."
   echo "[PlanCaptureGate] $(workflow_pending_orchestration_summary)"
   echo "[PlanCaptureGate] Capture the final plan body first; if implementation is already approved, use --status Approved --execute with a work-package promotion reason:"
-  echo "  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source ${kind:-host-plan} --orchestration-kind ${kind:-host-plan} --route planning --execute${source_arg}"
+  echo "  printf '%s\n' '<approved plan body>' | repo-harness run capture-plan --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source ${kind:-host-plan} --orchestration-kind ${kind:-host-plan} --route planning --execute${source_arg}"
   return 0
 }
 
@@ -546,8 +563,8 @@ maybe_start_plan_workflow() {
     return 0
   fi
 
-  if [[ ! -x "scripts/ensure-task-workflow.sh" ]]; then
-    echo "[PlanStartGate] Think/plan intent detected, but scripts/ensure-task-workflow.sh is missing. Continue with planning and capture manually."
+  if ! repo_harness_runner_available; then
+    echo "[PlanStartGate] Think/plan intent detected, but repo-harness run is unavailable. Continue with planning and capture manually."
     return 0
   fi
 
@@ -558,7 +575,7 @@ maybe_start_plan_workflow() {
   kind="${PG_PENDING_KIND:-repo-harness-plan}"
   source_ref="$title"
   echo "[PlanStartGate] Think/plan intent detected. Starting independent file-backed Draft plan workflow."
-  if ! start_output="$(bash "scripts/ensure-task-workflow.sh" --new-plan --slug "$slug" --title "$title" 2>&1)"; then
+  if ! start_output="$(run_repo_harness_helper ensure-task-workflow --new-plan --slug "$slug" --title "$title" 2>&1)"; then
     printf '%s\n' "$start_output"
     return 0
   fi
@@ -633,12 +650,12 @@ maybe_capture_embedded_approved_plan() {
     return 0
   fi
 
-  if [[ ! -x "scripts/capture-plan.sh" ]]; then
-    echo "[PlanCaptureGate] Embedded approved plan detected, but scripts/capture-plan.sh is missing."
+  if ! repo_harness_runner_available; then
+    echo "[PlanCaptureGate] Embedded approved plan detected, but repo-harness run is unavailable."
     hook_structured_error \
       "PlanCaptureGate" \
-      "Embedded approved plan detected but scripts/capture-plan.sh is missing." \
-      "Install workflow helpers before executing an embedded approved plan." \
+      "Embedded approved plan detected but repo-harness run is unavailable." \
+      "Install the repo-harness global runtime before executing an embedded approved plan." \
       "missing_artifact"
     exit 2
   fi
@@ -650,7 +667,7 @@ maybe_capture_embedded_approved_plan() {
     hook_structured_error \
       "PlanCaptureGate" \
       "PLEASE IMPLEMENT THIS PLAN was provided without a plan body." \
-      "Paste the approved plan body after the marker so scripts/capture-plan.sh can store and project it." \
+      "Paste the approved plan body after the marker so repo-harness run capture-plan can store and project it." \
       "missing_artifact"
     exit 2
   fi
@@ -662,12 +679,12 @@ maybe_capture_embedded_approved_plan() {
   fi
 
   echo "[PlanCaptureGate] Embedded approved plan detected. Capturing and projecting before implementation."
-  if ! capture_output="$(printf '%s\n' "$body" | bash "scripts/capture-plan.sh" --slug "$slug" --title "$title" --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source user-approved-plan --route planning --execute 2>&1)"; then
+  if ! capture_output="$(printf '%s\n' "$body" | run_repo_harness_helper capture-plan --slug "$slug" --title "$title" --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source user-approved-plan --route planning --execute 2>&1)"; then
     printf '%s\n' "$capture_output"
     hook_structured_error \
       "PlanCaptureGate" \
       "Embedded approved plan capture failed." \
-      "Fix the capture-plan.sh or plan-to-todo.sh error before editing implementation files." \
+      "Fix the repo-harness run capture-plan or plan-to-todo error before editing implementation files." \
       "state_violation"
     exit 2
   fi
@@ -884,7 +901,7 @@ render_prompt_guard_action() {
       ;;
     spec_block)
       echo "[SpecGuard] Advisory: docs/spec.md is missing. Create stable product truth before implementation."
-      echo "[SpecGuard] Run bash scripts/new-spec.sh and capture stable product intent; implementation edits without a spec are blocked at the edit layer."
+      echo "[SpecGuard] Run repo-harness run new-spec and capture stable product intent; implementation edits without a spec are blocked at the edit layer."
       exit 0
       ;;
     stale_active_plan_advice)
@@ -906,19 +923,19 @@ render_prompt_guard_action() {
       echo "[PlanCaptureGate] Approval detected before an active plan artifact exists."
       echo "[PlanCaptureGate] Let the agent run the approved-plan capture path now:"
       echo "  git status --short --branch -uall"
-      echo "  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source waza-think --route planning --execute"
+      echo "  printf '%s\n' '<approved plan body>' | repo-harness run capture-plan --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source waza-think --route planning --execute"
       exit 0
       ;;
     plan_status_no_active_block)
       echo "[PlanStatusGuard] Advisory: No active plan found in plans/. Implementation edits will be blocked at the edit layer until a plan is captured."
-      echo "[PlanStatusGuard] Capture the approved planning output with: bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute"
-      echo "[PlanStatusGuard] If there is no captured planning output yet, run: bash scripts/ensure-task-workflow.sh --slug <slug> --title <title>"
+      echo "[PlanStatusGuard] Capture the approved planning output with: repo-harness run capture-plan --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute"
+      echo "[PlanStatusGuard] If there is no captured planning output yet, run: repo-harness run ensure-task-workflow --slug <slug> --title <title>"
       exit 0
       ;;
     plan_capture_draft_advice)
       echo "[PlanCaptureGate] Approval detected for $plan_status plan: $active_plan"
       echo "[PlanCaptureGate] Recapture the exact approved plan body with --artifact-level work-package --promotion-reason <reason> --status Approved --execute, or mark this plan Approved and run:"
-      echo "  bash scripts/plan-to-todo.sh --plan $active_plan"
+      echo "  repo-harness run plan-to-todo --plan $active_plan"
       exit 0
       ;;
     plan_status_not_approved_block)
@@ -934,12 +951,12 @@ render_prompt_guard_action() {
     plan_execution_scaffold_advice)
       echo "[PlanExecutionGate] Approval detected for approved plan: $active_plan"
       echo "[PlanExecutionGate] Create the sprint contract/review/notes before implementation:"
-      echo "  bash scripts/plan-to-todo.sh --plan $active_plan"
+      echo "  repo-harness run plan-to-todo --plan $active_plan"
       exit 0
       ;;
     contract_missing_block)
       echo "[ContractGuard] Advisory: missing active sprint contract for $active_plan."
-      echo "[ContractGuard] Run bash scripts/plan-to-todo.sh --plan $active_plan to create the contract/review/notes scaffold before implementation."
+      echo "[ContractGuard] Run repo-harness run plan-to-todo --plan $active_plan to create the contract/review/notes scaffold before implementation."
       exit 0
       ;;
     done_missing_active_plan)
@@ -1109,11 +1126,11 @@ fi
 if [ "$done_intent" -eq 1 ]; then
   render_prompt_guard_action "$PG_ACTION"
 
-  if [ -f "scripts/verify-contract.sh" ]; then
+  if repo_harness_runner_available; then
     # --read-only: hook-driven verification must not rewrite the contract Status
     # header, otherwise a transient failure (e.g. flaky `bun test`) dirties the
     # worktree and chains into worktree-guard on the next prompt.
-    if ! bash "scripts/verify-contract.sh" --contract "$contract_file" --strict --read-only; then
+    if ! run_repo_harness_helper verify-contract --contract "$contract_file" --strict --read-only; then
       echo "[ContractGuard] Contract verification failed: $contract_file"
       hook_structured_error \
         "ContractGuard" \
@@ -1123,7 +1140,7 @@ if [ "$done_intent" -eq 1 ]; then
       exit 2
     fi
   else
-    echo "[ContractGuard] verify-contract.sh not found at scripts/verify-contract.sh (degraded mode: skipping strict verification)."
+    echo "[ContractGuard] repo-harness run verify-contract is unavailable (degraded mode: skipping strict verification)."
   fi
 
   review_file="$(workflow_active_review || true)"
@@ -1196,7 +1213,7 @@ if [ "$done_intent" -eq 1 ]; then
     hook_structured_error \
       "EvidenceGuard" \
       "$checks_error" \
-      "Run bash scripts/verify-sprint.sh so .ai/harness/checks/latest.json records a passing current sprint verification." \
+      "Run repo-harness run verify-sprint so .ai/harness/checks/latest.json records a passing current sprint verification." \
       "quality_gate"
     exit 2
   fi
@@ -1228,24 +1245,24 @@ if [ "$done_intent" -eq 1 ]; then
     exit 0
   fi
 
-  if [ ! -x scripts/archive-workflow.sh ]; then
-    echo "[AutoArchive] scripts/archive-workflow.sh is missing or not executable. Skipping auto-archive."
+  if ! repo_harness_runner_available; then
+    echo "[AutoArchive] repo-harness run archive-workflow is unavailable. Skipping auto-archive."
     hook_structured_error \
       "AutoArchive" \
-      "scripts/archive-workflow.sh is missing or not executable." \
-      "Install the workflow helper before relying on auto-archive." \
+      "repo-harness run archive-workflow is unavailable." \
+      "Install the repo-harness global runtime before relying on auto-archive." \
       "missing_artifact"
     exit 1
   fi
 
   outcome="${PG_DONE_OUTCOME:-Completed}"
   echo "[AutoArchive] All quality gates passed. Archiving $active_plan as outcome=$outcome"
-  if ! archive_output="$(bash scripts/archive-workflow.sh --plan "$active_plan" --outcome "$outcome" 2>&1)"; then
+  if ! archive_output="$(run_repo_harness_helper archive-workflow --plan "$active_plan" --outcome "$outcome" 2>&1)"; then
     printf '%s\n' "$archive_output"
     hook_structured_error \
       "AutoArchive" \
       "Automatic archive failed for $active_plan." \
-      "Run bash scripts/archive-workflow.sh --plan $active_plan --outcome $outcome and resolve the error." \
+      "Run repo-harness run archive-workflow --plan $active_plan --outcome $outcome and resolve the error." \
       "contract_failure"
     exit 1
   fi

package/assets/hooks/session-start-context.sh

@@ -15,22 +15,10 @@ workflow_rotate_events_file ".ai/harness/architecture/events.jsonl" 2>/dev/null
 
 resume_file="$(workflow_resume_packet_file)"
 
-helper_script_path() {
+helper_command() {
   local helper_name="$1"
-  local helper_dir
-
-  helper_dir="$(workflow_policy_get '.harness.helper_runtime_dir' '.ai/harness/scripts')"
-  if [[ -f "$helper_dir/$helper_name" ]]; then
-    printf '%s/%s' "$helper_dir" "$helper_name"
-    return 0
-  fi
-
-  if [[ -f "scripts/$helper_name" ]]; then
-    printf '%s/%s' "scripts" "$helper_name"
-    return 0
-  fi
-
-  printf '%s/%s' "$helper_dir" "$helper_name"
+  helper_name="${helper_name%.sh}"
+  printf 'repo-harness run %s' "$helper_name"
 }
 
 resume_available() {
@@ -304,10 +292,10 @@ architecture_queue_pending() {
   local pending_count="0"
   local oldest_epoch="" oldest_days="unknown"
   local now_epoch request detected detected_date detected_epoch
-  local queue_script
+  local queue_cmd
 
   [[ -d "$requests_dir" ]] || return 1
-  queue_script="$(helper_script_path "architecture-queue.sh")"
+  queue_cmd="$(helper_command "architecture-queue.sh")"
 
   now_epoch="$(date '+%s' 2>/dev/null || true)"
   while IFS= read -r request; do
@@ -336,13 +324,13 @@ architecture_queue_pending() {
 ${pending_count} capabilities have pending architecture drift (oldest ${oldest_days}). Run:
 
 \`\`\`bash
-bash ${queue_script} status
+${queue_cmd} status
 \`\`\`
 EOF_CONTEXT
 }
 
 pending_plan_capture_context() {
-  local active_plan summary draft_path prompt_slug kind source_ref capture_source source_arg capture_script
+  local active_plan summary draft_path prompt_slug kind source_ref capture_source source_arg capture_cmd
 
   workflow_pending_orchestration_is_fresh || return 1
   active_plan="$(get_active_plan || true)"
@@ -358,7 +346,7 @@ pending_plan_capture_context() {
   if [[ -n "$source_ref" ]]; then
     source_arg=" --source-ref <source-ref>"
   fi
-  capture_script="$(helper_script_path "capture-plan.sh")"
+  capture_cmd="$(helper_command "capture-plan.sh")"
 
   cat <<EOF_CONTEXT
 # Pending Plan Capture
@@ -372,13 +360,13 @@ A host/thread planning discussion is pending capture and no active repo plan is
 Capture the decision-complete plan body:
 
 \`\`\`bash
-printf '%s\n' '<decision-complete plan body>' | bash ${capture_script} --slug ${prompt_slug:-<slug>} --title <title> --status Draft --source ${capture_source} --orchestration-kind ${capture_source} --route planning${source_arg}
+printf '%s\n' '<decision-complete plan body>' | ${capture_cmd} --slug ${prompt_slug:-<slug>} --title <title> --status Draft --source ${capture_source} --orchestration-kind ${capture_source} --route planning${source_arg}
 \`\`\`
 
 If the user has already approved implementation:
 
 \`\`\`bash
-printf '%s\n' '<approved plan body>' | bash ${capture_script} --slug ${prompt_slug:-<slug>} --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source ${capture_source} --orchestration-kind ${capture_source} --route planning --execute${source_arg}
+printf '%s\n' '<approved plan body>' | ${capture_cmd} --slug ${prompt_slug:-<slug>} --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source ${capture_source} --orchestration-kind ${capture_source} --route planning --execute${source_arg}
 \`\`\`
 EOF_CONTEXT
 }
@@ -445,7 +433,7 @@ EOF_CONTEXT
 active_sprint_context() {
   local marker=".ai/harness/sprint/active-sprint"
   local sprint_file status progress next_task
-  local sprint_script capture_script
+  local sprint_cmd capture_cmd
 
   if [[ -f ".ai/harness/policy.json" ]] && command -v jq >/dev/null 2>&1; then
     marker="$(jq -r '.sprints.active_marker_file // empty' .ai/harness/policy.json 2>/dev/null || true)"
@@ -481,8 +469,8 @@ active_sprint_context() {
     }
     END { if (!found) print "(none)" }
   ' "$sprint_file")"
-  sprint_script="$(helper_script_path "sprint-backlog.sh")"
-  capture_script="$(helper_script_path "capture-plan.sh")"
+  sprint_cmd="$(helper_command "sprint-backlog.sh")"
+  capture_cmd="$(helper_command "capture-plan.sh")"
 
   cat <<EOF_CONTEXT
 # Active Sprint
@@ -490,7 +478,7 @@ active_sprint_context() {
 - Sprint: \`${sprint_file}\` status=${status:-unknown} backlog=${progress}
 - Next sprint task: ${next_task}
 - Rule: a Sprint is a long-task container. Use \`\$think\` to expand the next sprint task into a detailed \`plans/plan-*.md\`, then run the existing plan -> contract -> worktree flow. \`tasks/todos.md\` stays the deferred-goal ledger.
-- Entrypoint: inspect with \`${sprint_script} next\`; after \`\$think\` produces an approved plan, capture it with \`${capture_script} --source waza-think --source-ref sprint:${sprint_file}#${next_task}\`.
+- Entrypoint: inspect with \`${sprint_cmd} next\`; after \`\$think\` produces an approved plan, capture it with \`${capture_cmd} --source waza-think --source-ref sprint:${sprint_file}#${next_task}\`.
 EOF_CONTEXT
 }