repo-harness 0.1.4 → 0.1.5

package/README.md

@@ -121,11 +121,12 @@ npx -y repo-harness init
 ```
 
 The npm package release line is `0.1.x`; generated workflow compatibility is
-tracked separately as the `5.x` model line. The `0.1.4` package publishes the
+tracked separately as the `5.x` model line. The `0.1.5` package publishes the
 renamed `repo-harness` CLI, user-level Claude/Codex hook adapter bootstrap,
 AI-native scaffold overlays, the typed prompt-guard decision engine, plan-stem
-task artifact naming, Waza runtime skill sync, `diagram-design` sync, and the
-release gate used by maintainers before npm publish. When working from a source
+task artifact naming, `REPO_HARNESS_*` runtime aliases, repo-harness generated
+markers, Waza runtime skill sync, `diagram-design` sync, and the release gate
+used by maintainers before npm publish. When working from a source
 checkout instead of npm, run:
 
 ```bash
@@ -250,7 +251,7 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.1.4`
+- npm package: `repo-harness@0.1.5`
 - Generated workflow compatibility: `5.2.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -322,7 +323,7 @@ the public surface action-style while sharing the same router, contract, scripts
 and tests:
 
 - Planning and review: `repo-harness-plan`, `repo-harness-review`, `repo-harness-autoplan`
-- Repo workflow actions: `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
+- Repo workflow actions: `repo-harness-ship`, `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
 - Project creation: `repo-harness-scaffold`
 
 `repo-harness-init` is for an existing repo; `repo-harness-scaffold` creates a new

package/README.zh-CN.md

@@ -264,7 +264,7 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 公共 command skill facades 在 `assets/skill-commands/`：
 
 - Planning / review：`repo-harness-plan`、`repo-harness-review`、`repo-harness-autoplan`
-- Repo workflow actions：`repo-harness-init`、`repo-harness-migrate`、`repo-harness-upgrade`、`repo-harness-capability`、`repo-harness-architecture`、`repo-harness-handoff`、`repo-harness-deploy`、`repo-harness-repair`、`repo-harness-check`
+- Repo workflow actions：`repo-harness-ship`、`repo-harness-init`、`repo-harness-migrate`、`repo-harness-upgrade`、`repo-harness-capability`、`repo-harness-architecture`、`repo-harness-handoff`、`repo-harness-deploy`、`repo-harness-repair`、`repo-harness-check`
 - Project creation：`repo-harness-scaffold`
 
 `repo-harness-init` 用于已有仓库；`repo-harness-scaffold` 用于创建新项目或模块。

package/SKILL.md

@@ -103,7 +103,8 @@ the same engine. Use action-style names for discoverability:
 
 - `repo-harness-plan`: interactive planning; no repo mutation by default
 - `repo-harness-review`: plan review across product, engineering, design, and DevEx
-- `repo-harness-autoplan`: automatic plan -> review -> decision summary pipeline
+- `repo-harness-autoplan`: automatic plan -> self-review twice -> implementation -> check -> ship pipeline
+- `repo-harness-ship`: validate finished worktrees, push branches, and create PRs by default
 - `repo-harness-init`: install or refresh the harness in an existing repo
 - `repo-harness-scaffold`: create a new project or module scaffold, then attach the harness
 - `repo-harness-migrate`: migrate legacy workflow docs and stale harness artifacts

package/assets/hooks/codex.hooks.template.json

@@ -50,7 +50,7 @@
     "Stop": [
       {
         "hooks": [
-          { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_HOST=codex HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" finalize-handoff.sh" }
+          { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_HOST=codex HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" stop-orchestrator.sh" }
         ]
       }
     ]

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

@@ -289,7 +289,7 @@ workflow_plan_slug_from_path() {
   printf '%s' "$slug"
 }
 
-workflow_plan_artifact_stem_from_path() {
+workflow_plan_original_artifact_stem_from_path() {
   local plan_file="$1"
   local base stem
 
@@ -303,6 +303,56 @@ workflow_plan_artifact_stem_from_path() {
   workflow_plan_slug_from_path "$plan_file"
 }
 
+workflow_is_transient_plan_slug() {
+  case "$1" in
+    think-plan-[0-9]*|codex-plan-[0-9]*|approved-plan-[0-9]*)
+      return 0
+      ;;
+  esac
+  return 1
+}
+
+workflow_plan_title_slug_from_file() {
+  local plan_file="$1"
+  local title slug
+
+  [[ -f "$plan_file" ]] || return 1
+  title="$(awk '
+    /^# Plan:[[:space:]]*/ {
+      sub(/^# Plan:[[:space:]]*/, "")
+      print
+      exit
+    }
+  ' "$plan_file" | xargs)"
+  [[ -n "$title" ]] || return 1
+
+  slug="$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  [[ -n "$slug" ]] || return 1
+  printf '%s' "$slug"
+}
+
+workflow_plan_artifact_stem_from_path() {
+  local plan_file="$1"
+  local stem stamp slug title_slug
+
+  stem="$(workflow_plan_original_artifact_stem_from_path "$plan_file" || true)"
+  if [[ "$stem" =~ ^[0-9]{8}-[0-9]{4}-.+ ]]; then
+    stamp="$(printf '%s' "$stem" | sed -E 's/^([0-9]{8}-[0-9]{4})-.+$/\1/')"
+    slug="$(printf '%s' "$stem" | sed -E 's/^[0-9]{8}-[0-9]{4}-//')"
+    if workflow_is_transient_plan_slug "$slug"; then
+      title_slug="$(workflow_plan_title_slug_from_file "$plan_file" || true)"
+      if [[ -n "$title_slug" && "$title_slug" != "$slug" ]]; then
+        printf '%s-%s' "$stamp" "$title_slug"
+        return 0
+      fi
+    fi
+    printf '%s' "$stem"
+    return 0
+  fi
+
+  workflow_plan_slug_from_path "$plan_file"
+}
+
 workflow_preferred_or_legacy_path() {
   local preferred="$1"
   local legacy="$2"

package/assets/hooks/run-hook.sh

@@ -23,6 +23,28 @@ fi
 export HOOK_REPO_ROOT="$REPO_ROOT"
 cd "$REPO_ROOT"
 
+if [[ "${HOOK_HOST:-}" == "codex" && "$HOOK_NAME" == "stop-orchestrator.sh" ]]; then
+  tmp_stdout="$(mktemp)"
+  tmp_stderr="$(mktemp)"
+  if bash "$HOOK_PATH" "$@" >"$tmp_stdout" 2>"$tmp_stderr"; then
+    if grep -q '"decision"[[:space:]]*:' "$tmp_stdout"; then
+      cat "$tmp_stdout"
+    fi
+    rm -f "$tmp_stdout" "$tmp_stderr"
+    exit 0
+  else
+    hook_status=$?
+    if [[ -s "$tmp_stderr" ]]; then
+      cat "$tmp_stderr" >&2
+    fi
+    if [[ -s "$tmp_stdout" ]]; then
+      grep -v '^{"guard":' "$tmp_stdout" >&2 || true
+    fi
+    rm -f "$tmp_stdout" "$tmp_stderr"
+    exit "$hook_status"
+  fi
+fi
+
 if [[ "${HOOK_HOST:-}" == "codex" && "$HOOK_NAME" != "session-start-context.sh" ]]; then
   tmp_stdout="$(mktemp)"
   tmp_stderr="$(mktemp)"

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

@@ -13,7 +13,10 @@ resume_file="$(workflow_resume_packet_file)"
 
 resume_available() {
   [[ -f "$resume_file" ]] || return 1
-  grep -Fq "<!-- generated-by: project-initializer codex-handoff-resume v1 -->" "$resume_file" || return 1
+  {
+    grep -Fq "<!-- generated-by: repo-harness codex-handoff-resume v1 -->" "$resume_file" ||
+      grep -Fq "<!-- generated-by: project-initializer codex-handoff-resume v1 -->" "$resume_file"
+  } || return 1
   grep -Fq "## Resume Prompt" "$resume_file"
 }
 
@@ -254,6 +257,14 @@ EOF_CONTEXT
   fi
 }
 
+input_priority_context() {
+  cat <<'EOF_CONTEXT'
+# Input Priority
+
+If the current user message mentions `# Files mentioned by the user`, `pasted-text.txt`, or an explicit attachment/file path, read those current-input files first. Treat handoff, resume, and `tasks/current.md` as recovery context only.
+EOF_CONTEXT
+}
+
 context=""
 if resume_current_for_handoff; then
   if context_budget_active \
@@ -293,6 +304,10 @@ if [[ -n "$current_status_context" ]]; then
   fi
 fi
 
+if [[ -n "$context" ]]; then
+  context="$(input_priority_context)"$'\n'"${context}"
+fi
+
 # Cross-review availability for Codex. The dispatcher swallows prompt-guard's
 # success stdout on Codex, so attach a short reminder only when SessionStart is
 # already injecting actionable context.

package/assets/hooks/settings.template.json

@@ -50,7 +50,7 @@
     "Stop": [
       {
         "hooks": [
-          { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" finalize-handoff.sh" }
+          { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" stop-orchestrator.sh" }
         ]
       }
     ]

package/assets/hooks/stop-orchestrator.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# Stop Orchestrator Hook - Stop
+# Refreshes handoff state and, for pending planning discussions, forces one
+# self-review pass before the agent stops.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/workflow-state.sh"
+
+plan_completeness_state_file() {
+  workflow_repo_relative_path \
+    "$(workflow_policy_get '.planning.completeness_state_file' '.ai/harness/planning/plan-completeness.json')" \
+    '.ai/harness/planning/plan-completeness.json' \
+    '.ai/harness/'
+}
+
+plan_completeness_signature() {
+  local kind prompt_slug draft_path source_ref created_at
+
+  kind="$(workflow_pending_orchestration_field kind 2>/dev/null || true)"
+  prompt_slug="$(workflow_pending_orchestration_field prompt_slug 2>/dev/null || true)"
+  draft_path="$(workflow_pending_orchestration_field draft_plan_path 2>/dev/null || true)"
+  source_ref="$(workflow_pending_orchestration_field source_ref 2>/dev/null || true)"
+  created_at="$(workflow_pending_orchestration_field created_at 2>/dev/null || true)"
+
+  printf '%s|%s|%s|%s|%s' \
+    "${kind:-unknown}" \
+    "${prompt_slug:-planning}" \
+    "${draft_path:-none}" \
+    "${source_ref:-none}" \
+    "${created_at:-unknown}"
+}
+
+plan_completeness_last_signature() {
+  local state_file value
+  state_file="$(plan_completeness_state_file)"
+  [[ -f "$state_file" ]] || return 1
+
+  if command -v jq >/dev/null 2>&1; then
+    value="$(jq -r '.last_signature // empty' "$state_file" 2>/dev/null || true)"
+  else
+    value="$(
+      awk '
+        /"last_signature"/ {
+          line = $0
+          sub(/^[^:]*:[[:space:]]*"/, "", line)
+          sub(/"[[:space:]]*,?[[:space:]]*$/, "", line)
+          print line
+          exit
+        }
+      ' "$state_file"
+    )"
+  fi
+
+  [[ -n "$value" ]] || return 1
+  printf '%s' "$value"
+}
+
+plan_completeness_record_signature() {
+  local signature="$1"
+  local state_file
+  state_file="$(plan_completeness_state_file)"
+  mkdir -p "$(dirname "$state_file")"
+
+  if command -v jq >/dev/null 2>&1; then
+    jq -nc \
+      --arg signature "$signature" \
+      --arg updated_at "$(date '+%Y-%m-%dT%H:%M:%S%z')" \
+      '{version:1,last_signature:$signature,updated_at:$updated_at}' > "$state_file"
+    return 0
+  fi
+
+  cat > "$state_file" <<EOF_STATE
+{"version":1,"last_signature":"$(workflow_json_escape "$signature")","updated_at":"$(workflow_json_escape "$(date '+%Y-%m-%dT%H:%M:%S%z')")"}
+EOF_STATE
+}
+
+assistant_message_looks_like_plan() {
+  local message="$1"
+  local length
+
+  length="$(printf '%s' "$message" | wc -c | tr -d ' ')"
+  [[ "${length:-0}" -ge 240 ]] || return 1
+
+  printf '%s\n' "$message" | grep -qEi \
+    '(Approved design summary|Building|Not building|Approach|Key decisions|Unknowns|Task Breakdown|Evidence Contract|P1|P2|P3|plan|design|方案|计划|设计)'
+}
+
+emit_stop_block_json() {
+  local reason="$1"
+
+  if command -v jq >/dev/null 2>&1; then
+    jq -nc --arg reason "$reason" '{decision:"block",reason:$reason}'
+    return 0
+  fi
+
+  printf '{"decision":"block","reason":"%s"}\n' "$(workflow_json_escape "$reason")"
+}
+
+refresh_handoff() {
+  workflow_write_handoff "session-stop"
+  echo "[FinalizeHandoff] Refreshed $(workflow_handoff_file)." >&2
+}
+
+should_run_plan_completeness_gate() {
+  local stop_active="$1"
+  local last_message="$2"
+  local active_plan
+
+  [[ "$stop_active" != "true" ]] || return 1
+  workflow_pending_orchestration_is_fresh || return 1
+
+  # If a repo plan is already active, the normal plan status gates own the next
+  # transition. This gate only covers host planning output that still needs
+  # capture.
+  active_plan="$(get_active_plan || true)"
+  [[ -z "$active_plan" || ! -f "$active_plan" ]] || return 1
+
+  assistant_message_looks_like_plan "$last_message"
+}
+
+refresh_handoff
+
+stop_hook_active="$(hook_json_get '.stop_hook_active' 'false')"
+last_assistant_message="$(hook_json_get '.last_assistant_message' '')"
+
+if should_run_plan_completeness_gate "$stop_hook_active" "$last_assistant_message"; then
+  signature="$(plan_completeness_signature)"
+  if [[ "$(plan_completeness_last_signature 2>/dev/null || true)" != "$signature" ]]; then
+    plan_completeness_record_signature "$signature"
+    summary="$(workflow_pending_orchestration_summary)"
+    emit_stop_block_json "[PlanCompletenessGate] A first planning answer was produced while pending orchestration is still open: ${summary}
+
+Before stopping, run one self-review pass on the plan. Do not implement. Check for missing goal/success criteria, constraints, P1 component map, P2 traced path, P3 decision rationale, fragile assumption, rejected alternative, tests, rollback/failure handling, and no placeholders. If the plan is already complete, say so explicitly and keep the revision concise. Then stop and wait for user approval."
+  fi
+fi

package/assets/initializer-question-pack.v4.json

@@ -50,7 +50,7 @@
       "title": "AI-Native Profile",
       "batch": 2,
       "questions": [
-        "Choose AI-native overlay: none (default), chat-agent, runtime-console, product-copilot, workflow-agent, generative-ui-agent, browser-agent, research-agent, coding-agent, enterprise-agent-platform, voice-agent, or sidecar-kernel",
+        "Choose AI-native overlay: none (default), chat-agent, collaborative-editor, runtime-console, product-copilot, workflow-agent, generative-ui-agent, browser-agent, research-agent, coding-agent, enterprise-agent-platform, voice-agent, or sidecar-kernel",
         "Confirm whether generated structure should add AG-UI, assistant-ui or CopilotKit, Bun/Hono gateway, MCP/tool, sidecar, and observability boundaries"
       ],
       "required": false
@@ -278,17 +278,35 @@
       "description": "Ordinary AI chat, RAG, or help assistant inside the selected app plan.",
       "frontend": "Vite 8 + assistant-ui or the selected plan UI",
       "runtimeProtocol": "AI SDK UI stream or AG-UI lite",
-      "backend": "Bun/Hono gateway or existing API boundary",
+      "backend": "Bun/Hono gateway or Mastra/Hono runtime behind the existing API boundary",
       "stateDefault": "TanStack Query + Zustand",
       "sidecarPolicy": "Python only when the model framework needs it",
       "uiSchema": "Hardcoded React components",
       "techStackRows": [
         "| AI UI | assistant-ui chat surface |",
         "| Agent stream | AI SDK UI stream or AG-UI lite |",
-        "| Agent gateway | Bun/Hono or existing API |",
+        "| Agent runtime | Bun/Hono by default; Mastra when TS agents need memory, tools, workflows, or evals |",
         "| Agent state | TanStack Query + Zustand |"
       ]
     },
+    "collaborative-editor": {
+      "label": "Collaborative editor",
+      "description": "AI-aware document, CMS, or knowledge workspace with local-first collaboration and explicit sync ownership.",
+      "frontend": "Vite 8 + React 19 + Plate + shadcn/ui",
+      "runtimeProtocol": "Loro CRDT document events; AI SDK or AG-UI only for user-visible agent runs",
+      "backend": "Bun/Hono sync and agent gateway, or existing API boundary",
+      "stateDefault": "Loro document state + TanStack Query server cache + Zustand UI state",
+      "sidecarPolicy": "None by default; Python or Go sidecars only for extraction, indexing, or heavy sync workers",
+      "uiSchema": "Plate node/plugin schema plus app-owned document contracts",
+      "projectStructureFile": "assets/project-structures/ai-native-collaborative-editor.txt",
+      "techStackRows": [
+        "| Editor UI | Plate + shadcn/ui in a Vite 8 React surface |",
+        "| Collaboration | Loro CRDT document state and sync contracts |",
+        "| Agent runtime | AI SDK or AG-UI only for user-visible assistant/document actions |",
+        "| Sync gateway | Bun/Hono or existing API boundary owns persistence and auth |",
+        "| State split | Loro for document replicas; TanStack Query for server cache; Zustand for UI chrome |"
+      ]
+    },
     "runtime-console": {
       "label": "Runtime console",
       "description": "Agent runtime console with trace, replay, prompt playground, approvals, artifacts, and tool-call visibility.",
@@ -332,12 +350,12 @@
       "runtimeProtocol": "AG-UI",
       "backend": "Bun/Hono gateway",
       "stateDefault": "Jotai + Zustand + TanStack Query",
-      "sidecarPolicy": "LangGraph, Temporal, Inngest, or BullMQ only when execution needs them",
+      "sidecarPolicy": "Mastra, LangGraph, Temporal, Inngest, or BullMQ only when execution needs workflow durability or orchestration",
       "uiSchema": "A2UI optional experiment",
       "techStackRows": [
         "| Workflow UI | React Flow/xyflow + Monaco |",
         "| Agent protocol | AG-UI workflow/run events |",
-        "| Executor | Bun/Hono gateway with optional workflow engine |",
+        "| Executor | Bun/Hono gateway with optional Mastra or durable workflow engine |",
         "| Agent state | Jotai + Zustand + TanStack Query |"
       ]
     },
@@ -444,14 +462,14 @@
       "runtimeProtocol": "AG-UI when user-visible agent runs exist; MCP/HTTP for sidecars",
       "backend": "Bun/Hono gateway owns app-facing API",
       "stateDefault": "TanStack Query + Zustand, plus domain stores as needed",
-      "sidecarPolicy": "Python for model/eval/data pipelines, Go for workers, Rust for low-latency parsing/indexing/sandboxing",
+      "sidecarPolicy": "Python ADK/FastAPI for model/eval/data pipelines, Go/Gin for high-concurrency workers or infra adapters, Rust for low-latency parsing/indexing/sandboxing",
       "uiSchema": "None by default",
       "projectStructureFile": "assets/project-structures/ai-native-sidecar-kernel.txt",
       "techStackRows": [
         "| App gateway | Bun/Hono owns app-facing API |",
         "| Sidecar protocol | MCP tools or narrow HTTP jobs |",
-        "| Python sidecar | Model frameworks, evals, data science |",
-        "| Go sidecar | High-concurrency workers and infra adapters |",
+        "| Python sidecar | Google ADK/FastAPI, model frameworks, evals, data science |",
+        "| Go sidecar | Gin workers, Supabase REST adapters, high-concurrency infra jobs |",
         "| Rust sidecar | Parsing, indexing, sandboxing, native kernels |"
       ]
     }

package/assets/plan-map.json

@@ -66,7 +66,7 @@
       "cloudflareNative": true,
       "aiNativeOverlayDefaults": {
         "defaultProfile": "none",
-        "recommendedProfiles": ["runtime-console", "product-copilot", "chat-agent"]
+        "recommendedProfiles": ["runtime-console", "product-copilot", "chat-agent", "collaborative-editor"]
       },
       "defaultHarnessProfiles": {
         "orchestration": "shared-long-running-harness",

package/assets/project-structures/ai-native-collaborative-editor.txt

@@ -0,0 +1,25 @@
+# AI-native Collaborative Editor Overlay
+
+{{PROJECT_NAME}}/
+├── apps/
+│   └── web/
+│       ├── src/routes/documents.$id.tsx     # editor route and document run surface
+│       ├── src/components/editor/           # Plate editor, toolbars, nodes, marks
+│       ├── src/components/assistant/        # document assistant or inline actions
+│       ├── src/collab/loro-doc.ts           # Loro document factory and peer identity
+│       ├── src/collab/sync-client.ts        # sync transport adapter
+│       └── src/stores/editor-ui-store.ts    # bounded Zustand UI chrome only
+├── services/
+│   └── document-gateway/
+│       ├── src/routes/documents.ts          # Bun/Hono document CRUD and auth boundary
+│       ├── src/routes/sync.ts               # CRDT sync endpoint
+│       ├── src/routes/agent-actions.ts      # AI SDK or AG-UI document actions
+│       └── src/storage/                     # snapshots, updates, and audit records
+├── packages/
+│   └── contracts/
+│       ├── src/documents.ts                 # document metadata and ACL schemas
+│       ├── src/crdt.ts                      # Loro update/snapshot contracts
+│       ├── src/editor-nodes.ts              # Plate node/plugin contracts
+│       └── src/agent-actions.ts             # assistant action input/output schemas
+└── workers/
+    └── indexing/                            # optional extraction, search, or sync compaction

package/assets/reference-configs/agentic-development-flow.md

@@ -24,7 +24,8 @@ migrating, repairing, or verifying this repo-local harness:
 |-----------|---------|----------|
 | Decision-complete harness plan | `repo-harness-plan` | Plans only; no repo mutation by default |
 | Review an existing harness plan | `repo-harness-review` | Product, engineering, design, and DevEx review dimensions |
-| Automatic planning pipeline | `repo-harness-autoplan` | Plan -> review -> decision summary with final gates only |
+| Automatic workflow pipeline | `repo-harness-autoplan` | Plan -> two self-review passes -> implementation -> `/check` -> `repo-harness-ship` |
+| Ship finished work | `repo-harness-ship` | Validates finished worktrees, pushes branches, and creates PRs by default |
 | Add harness to an existing repo | `repo-harness-init` | Uses inspector and migration engine; does not create an app stack |
 | Create a new app or module scaffold | `repo-harness-scaffold` | Uses plan catalog A-K, then attaches the harness |
 | Convert legacy workflow surfaces | `repo-harness-migrate` | Archives or preserves user-authored legacy docs |
@@ -61,7 +62,7 @@ work, or shared contracts, report the P1/P2/P3 evidence explicitly.
 5. Approved plans must include `## Evidence Contract` with state/progress path, verification evidence, evaluator rubric, stop condition, and rollback surface before execution. `capture-plan.sh` supplies this contract for captured planning output.
 6. Convert approved plans to execution scaffolding with `scripts/plan-to-todo.sh --plan <plan>`; if approval is already explicit, use `scripts/capture-plan.sh --status Approved --execute ...`. The plan's own `## Task Breakdown` remains the execution checklist; `tasks/todo.md` remains a deferred-goal ledger. Contract-level plans are projected into a linked `codex/<slug>` worktree when the policy enables it.
 7. Use `scripts/refresh-current-status.sh` for an explicit `tasks/current.md` preview or `--write` snapshot. In non-target worktrees, `git show <target>:tasks/current.md` reads the mainline snapshot, but it never replaces source artifacts.
-8. After substantive changes, run project checks and record evidence in `tasks/`. For contract worktrees, run Waza `/check`, start host-aware external acceptance in parallel, fill the review artifact from both verdicts, then run `scripts/contract-worktree.sh finish`.
+8. After substantive changes, run project checks and record evidence in `tasks/`. For contract worktrees, run Waza `/check`, start host-aware external acceptance in parallel, fill the review artifact from both verdicts, then use `repo-harness-ship` for default PR closeout. It calls `scripts/contract-worktree.sh finish --no-merge`, pushes the `codex/<slug>` branch, and opens a draft PR. Use `repo-harness-ship --local-merge` only when an explicit maintainer workflow wants the older fast-forward merge and cleanup path.
 
 ## Passive Plan Capture
 

package/assets/reference-configs/external-tooling.md

@@ -45,7 +45,7 @@ installations.
 
 Use `bash scripts/check-agent-tooling.sh` for a read-only tooling report.
 Init and migration reports run the detector without update checks by default;
-set `AGENTIC_DEV_CHECK_TOOLING_UPDATES=1` when that advisory pass should
+set `REPO_HARNESS_CHECK_TOOLING_UPDATES=1` when that advisory pass should
 also compare upstream versions.
 
 Supported flags:

package/assets/reference-configs/harness-overview.md

@@ -35,7 +35,7 @@ This repo uses a shared long-running harness. The durable workflow lives in repo
 - Before implementation, the plan and contract should both expose a concrete workflow inventory so the agent does not rediscover or guess active artifacts.
 - Implementation should prefer `docs/spec.md`, an approved plan, and an active sprint contract.
 - Claiming completion should include contract verification evidence, a run snapshot, implementation notes, and a passing Waza `/check` review artifact.
-- Stopping a session should refresh `.ai/harness/handoff/current.md` for easier resume.
+- Stopping a session should refresh `.ai/harness/handoff/current.md` for easier resume; while pending planning orchestration is open, Stop may block once to force a plan completeness self-review before execution.
 - Refresh `tasks/current.md` with `scripts/refresh-current-status.sh --write --reason <reason>` only at explicit lifecycle boundaries or as a deliberate maintainer action; ordinary hooks should not dirty tracked files.
 - In non-target worktrees, read the target branch snapshot with `git show <target>:tasks/current.md` and verify stale or surprising state against the source artifacts before acting.
 - Use `docs/reference-configs/agentic-development-flow.md` for skill routing and `docs/reference-configs/external-tooling.md` for install/update commands.
@@ -66,7 +66,7 @@ This repo uses a shared long-running harness. The durable workflow lives in repo
 - Declare capabilities in `.ai/context/capabilities.json`; each capability owns prefixes, paired contract files, an architecture module, a workstream directory, and local verification hints.
 - Add selected capabilities with `repo-harness-capability` or `bun scripts/capability-config.ts add --prefix <path>` when the harness already exists and a full init/migrate/upgrade pass would be too broad.
 - Resolve edited paths through `scripts/capability-resolver.ts match --path <path>`; longest prefix wins and equal-length ambiguity fails.
-- Treat `.ai/context/agent-context-blocks.txt`, `PROJECT_INITIALIZER_CONTEXT_BLOCKS`, and existing nested `CLAUDE.md`/`AGENTS.md` files as migration inputs or compatibility fallbacks only.
+- Treat `.ai/context/agent-context-blocks.txt`, `REPO_HARNESS_CONTEXT_BLOCKS`, legacy `PROJECT_INITIALIZER_CONTEXT_BLOCKS`, and existing nested `CLAUDE.md`/`AGENTS.md` files as migration inputs or compatibility fallbacks only.
 - Selected capabilities receive paired `CLAUDE.md` and `AGENTS.md` files so Claude Code and Codex share the same local contract.
 - Use `repo-harness capability-context status|request|sync` to keep paired local context files aligned with the registry. The command writes only the controlled `CAPABILITY CONTEXT` block and preserves hand-authored content plus the separate architecture contract block.
 - `.ai/context/capability-source-map.json` is the optional human-edited source-map manifest for capability positioning and source pointers. Missing entries fall back to registry/architecture/workstream metadata; `--auto-fill-positioning` writes deterministic draft entries explicitly, not from hooks.

package/assets/reference-configs/hook-operations.md

@@ -16,12 +16,26 @@ Start with the shortest truth path:
 3. The route registry selects the ordered `.ai/hooks/*` scripts for that event and route.
 4. `.ai/hooks/*` is the shared implementation layer and the default place to edit.
 
+`UserPromptSubmit.default` keeps that same public route, but prompt-guard has a
+split implementation:
+
+1. `repo-harness-hook UserPromptSubmit --route default` dispatches to `.ai/hooks/prompt-guard.sh`.
+2. `prompt-guard.sh` parses host prompt JSON, reads workflow files, performs capture side effects, runs quality gates, and renders host-safe stdout/stderr.
+3. For intent plus workflow-state routing, `prompt-guard.sh` calls `repo-harness-hook prompt-guard-decide`.
+4. The TypeScript decision engine classifies prompt facts, reads state facts from environment variables, and returns one action enum from the explicit decision table.
+5. `prompt-guard.sh` renders that action as allow, advice, block, capture guidance, execution guidance, or done-gate output.
+
 If you are asking "which hook file should I edit?", default to `.ai/hooks/`.
 After installing or refreshing `~/.codex/hooks.json`, open Codex Settings and
 mark the user-level hook config as trusted; otherwise Codex will not execute it.
 Repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters are
 legacy project-level config and should be retired during migration.
 
+`Stop.default` routes through `stop-orchestrator.sh`. On Codex, dispatcher
+stdout stays quiet for ordinary successful hooks, but valid Stop decision JSON
+is forwarded so Codex can honor a one-shot planning completeness block; success
+stderr such as handoff refresh noise remains suppressed.
+
 ## Hook Failure Playbook
 
 When a hook blocks work:

package/assets/skill-commands/manifest.json

@@ -20,10 +20,17 @@
     },
     {
       "name": "repo-harness-autoplan",
-      "class": "automated-planning",
-      "mutatesRepoByDefault": false,
-      "engine": "plan then review then decision summary",
-      "summary": "Runs the full planning and review pipeline automatically, surfacing only final decision gates."
+      "class": "automated-workflow",
+      "mutatesRepoByDefault": true,
+      "engine": "plan, two self-review passes, execution, check, then repo-harness-ship",
+      "summary": "Runs the full repo-harness workflow automatically and delegates final PR closeout to repo-harness-ship."
+    },
+    {
+      "name": "repo-harness-ship",
+      "class": "ship-closeout",
+      "mutatesRepoByDefault": true,
+      "engine": "ship-worktrees default PR mode",
+      "summary": "Validates finished worktrees, commits through finish --no-merge, pushes branches, and creates GitHub PRs by default."
     },
     {
       "name": "repo-harness-init",

package/assets/skill-commands/repo-harness-autoplan/SKILL.md

@@ -1,19 +1,23 @@
 ---
 name: repo-harness-autoplan
-description: Fully automated planning pipeline for repo-harness workflow work. Reads repo state and existing docs, drafts a plan, reviews it, and surfaces only final decision gates.
-when_to_use: "repo-harness-autoplan, auto plan repo-harness work, automatic review harness plan, run all repo-harness reviews, make the workflow planning decisions"
+description: Full repo-harness workflow orchestrator. Reads repo state, drafts a plan, self-reviews twice, executes the approved plan, runs review/check gates, and delegates final PR closeout to repo-harness-ship.
+when_to_use: "repo-harness-autoplan, auto plan repo-harness work, automatic review harness plan, run all repo-harness reviews, make the workflow planning decisions, full repo-harness workflow"
 ---
 
 # repo-harness-autoplan
 
-Use this command when the user wants the planning and review pipeline handled automatically.
+Use this command when the user wants the whole repo-harness workflow handled automatically.
 
 ## Protocol
 
 1. Confirm the working repo and inspect state with `bun scripts/inspect-project-state.ts --repo <repo> --format text` when available.
 2. Draft the action plan with `repo-harness-plan` rules.
-3. Review the draft with `repo-harness-review` rules.
-4. Return the final plan, unresolved taste decisions, and the next action command.
+3. Run self-review 1, the completeness pass: goal, scope, P1/P2/P3, interfaces, tests, rollback, no placeholders.
+4. Revise the plan once from the completeness findings.
+5. Run self-review 2, the adversarial and shipability pass: failing gates, unsafe automation, permission boundaries, 10x breakpoints, and PR closeout readiness.
+6. Execute the approved plan without re-litigating decisions unless live repo drift makes it unsafe.
+7. Run Waza `/check` semantics and record the sprint review, external acceptance, and `verify-sprint` evidence.
+8. Call `repo-harness-ship` for the final default PR closeout.
 
 ## Reusable Workflow Packaging Rubric
 
@@ -34,8 +38,11 @@ or existing command extension:
 
 ## Boundaries
 
-- Does not edit files or run mutating scripts by default.
-- Never aborts into a long interactive review unless the repo state makes automatic planning unsafe.
+- Mutates repo files by default only after the user explicitly invokes `repo-harness-autoplan`.
+- Runs exactly two plan self-review passes; do not recurse into open-ended self critique.
+- Stops for the user only when the remaining ambiguity would change product intent, safety boundaries, or ship mode.
+- Never aborts into a long interactive review unless the repo state makes automatic workflow execution unsafe.
 - Surfaces only decisions that materially change scope, risk, or command selection.
 - Does not create skills, subagents, automations, or command assets until the
   user approves the plan.
+- Delegates default branch push and PR creation to `repo-harness-ship`; `repo-harness-autoplan` does not merge PRs or publish releases.