repo-harness 0.1.3 → 0.1.5

package/AGENTS.md

@@ -21,7 +21,7 @@ This repository self-hosts the `repo-harness` contract, formerly `repo-harness-s
 ## Operating Rules
 
 - Sync `tasks/` whenever substantive repo changes are made.
-- Use `tasks/notes/<slug>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
+- Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
 - Treat `.ai/hooks/` as the shared repo-local hook implementation; user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
 - Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.

package/CLAUDE.md

@@ -21,7 +21,7 @@ This repository self-hosts the `repo-harness` contract, formerly `repo-harness-s
 ## Operating Rules
 
 - Sync `tasks/` whenever substantive repo changes are made.
-- Use `tasks/notes/<slug>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
+- Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
 - Treat `.ai/hooks/` as the shared repo-local hook implementation; user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
 - Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.

package/README.md

@@ -77,9 +77,9 @@ flowchart TD
 
   Approve --> Project["Project plan into execution<br/>capture-plan.sh --execute<br/>or plan-to-todo.sh --plan"]
   Project --> Active["Active markers<br/>.ai/harness/active-plan<br/>.ai/harness/active-worktree"]
-  Project --> Contract["Sprint contract<br/>tasks/contracts/task-slug.contract.md"]
-  Project --> ReviewFile["Review file<br/>tasks/reviews/task-slug.review.md"]
-  Project --> Notes["Task notes<br/>tasks/notes/task-slug.notes.md"]
+  Project --> Contract["Sprint contract<br/>tasks/contracts/YYYYMMDD-HHMM-task-slug.contract.md"]
+  Project --> ReviewFile["Review file<br/>tasks/reviews/YYYYMMDD-HHMM-task-slug.review.md"]
+  Project --> Notes["Task notes<br/>tasks/notes/YYYYMMDD-HHMM-task-slug.notes.md"]
 
   Contract --> WorktreePolicy{"Contract worktree required?"}
   WorktreePolicy -->|yes| Checkout["Checkout isolated worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
@@ -121,12 +121,13 @@ 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.3` 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, 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:
+AI-native scaffold overlays, the typed prompt-guard decision engine, plan-stem
+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
 git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
@@ -250,7 +251,7 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.1.3`
+- 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

@@ -69,9 +69,9 @@ flowchart TD
 
   Approve --> Project["投射到执行面<br/>capture-plan.sh --execute<br/>或 plan-to-todo.sh --plan"]
   Project --> Active["Active markers<br/>.ai/harness/active-plan<br/>.ai/harness/active-worktree"]
-  Project --> Contract["Sprint contract<br/>tasks/contracts/task-slug.contract.md"]
-  Project --> ReviewFile["Review file<br/>tasks/reviews/task-slug.review.md"]
-  Project --> Notes["Task notes<br/>tasks/notes/task-slug.notes.md"]
+  Project --> Contract["Sprint contract<br/>tasks/contracts/YYYYMMDD-HHMM-task-slug.contract.md"]
+  Project --> ReviewFile["Review file<br/>tasks/reviews/YYYYMMDD-HHMM-task-slug.review.md"]
+  Project --> Notes["Task notes<br/>tasks/notes/YYYYMMDD-HHMM-task-slug.notes.md"]
 
   Contract --> WorktreePolicy{"是否需要 contract worktree?"}
   WorktreePolicy -->|是| Checkout["Checkout 隔离 worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
@@ -112,10 +112,10 @@ npx -y repo-harness init
 ```
 
 npm package release line 是 `0.1.x`；生成的 workflow compatibility model line
-单独以 `5.x` 追踪。`repo-harness@0.1.3` 发布的是改名后的 CLI、Claude/Codex
+单独以 `5.x` 追踪。`repo-harness@0.1.4` 发布的是改名后的 CLI、Claude/Codex
 user-level hook adapter bootstrap、AI-native scaffold overlays、typed prompt-guard
-decision engine、Waza runtime skill sync、`diagram-design` sync，以及 maintainer
-发布 npm 前使用的 release gate。
+decision engine、plan-stem task artifact 命名、Waza runtime skill sync、
+`diagram-design` sync，以及 maintainer 发布 npm 前使用的 release gate。
 
 如果从源码 checkout 工作：
 
@@ -235,7 +235,7 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.1.3`
+- npm package：`repo-harness@0.1.4`
 - Generated workflow compatibility：`5.2.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.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

@@ -275,7 +275,7 @@ get_todo_source_plan() {
   awk -F': ' '/^\> \*\*Source Plan\*\*:/ {print $2; exit}' tasks/todo.md | xargs
 }
 
-derive_contract_path() {
+workflow_plan_slug_from_path() {
   local plan_file="$1"
   local base slug
 
@@ -286,7 +286,93 @@ derive_contract_path() {
     return 1
   fi
 
-  printf 'tasks/contracts/%s.contract.md' "$slug"
+  printf '%s' "$slug"
+}
+
+workflow_plan_original_artifact_stem_from_path() {
+  local plan_file="$1"
+  local base stem
+
+  base="$(basename "$plan_file")"
+  stem="$(printf '%s' "$base" | sed -E 's/^plan-//; s/\.md$//')"
+  if [[ "$stem" =~ ^[0-9]{8}-[0-9]{4}-.+ ]]; then
+    printf '%s' "$stem"
+    return 0
+  fi
+
+  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"
+
+  if [[ -f "$preferred" ]] || [[ ! -f "$legacy" ]]; then
+    printf '%s' "$preferred"
+  else
+    printf '%s' "$legacy"
+  fi
+}
+
+derive_contract_path() {
+  local plan_file="$1"
+  local stem slug
+
+  stem="$(workflow_plan_artifact_stem_from_path "$plan_file" || true)"
+  slug="$(workflow_plan_slug_from_path "$plan_file" || true)"
+  [[ -n "$stem" && -n "$slug" ]] || return 1
+
+  workflow_preferred_or_legacy_path "tasks/contracts/${stem}.contract.md" "tasks/contracts/${slug}.contract.md"
 }
 
 workflow_plan_slug() {
@@ -296,7 +382,7 @@ workflow_plan_slug() {
     return 1
   fi
 
-  slug="$(basename "$active_plan" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
+  slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
   if [[ -n "$slug" ]]; then
     printf '%s' "$slug"
     return 0
@@ -930,7 +1016,7 @@ workflow_contract_slug() {
   local active_plan slug
   active_plan="$(get_active_plan || true)"
   [[ -n "$active_plan" ]] || return 1
-  slug="$(basename "$active_plan" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
+  slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
   [[ -n "$slug" ]] || return 1
   printf '%s' "$slug"
 }
@@ -945,18 +1031,25 @@ workflow_active_contract() {
 }
 
 workflow_active_review() {
-  local slug
-  slug="$(workflow_contract_slug || true)"
-  [[ -n "$slug" ]] || return 1
-  printf 'tasks/reviews/%s.review.md' "$slug"
+  local active_plan stem slug reviews_dir
+  active_plan="$(get_active_plan || true)"
+  [[ -n "$active_plan" ]] || return 1
+  stem="$(workflow_plan_artifact_stem_from_path "$active_plan" || true)"
+  slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
+  [[ -n "$stem" && -n "$slug" ]] || return 1
+  reviews_dir="$(workflow_repo_relative_path "$(workflow_policy_get '.tasks.reviews_dir' 'tasks/reviews')" 'tasks/reviews' 'tasks/')"
+  workflow_preferred_or_legacy_path "${reviews_dir}/${stem}.review.md" "${reviews_dir}/${slug}.review.md"
 }
 
 workflow_active_notes() {
-  local slug notes_dir
-  slug="$(workflow_contract_slug || true)"
-  [[ -n "$slug" ]] || return 1
+  local active_plan stem slug notes_dir
+  active_plan="$(get_active_plan || true)"
+  [[ -n "$active_plan" ]] || return 1
+  stem="$(workflow_plan_artifact_stem_from_path "$active_plan" || true)"
+  slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
+  [[ -n "$stem" && -n "$slug" ]] || return 1
   notes_dir="$(workflow_repo_relative_path "$(workflow_policy_get '.tasks.notes_dir' 'tasks/notes')" 'tasks/notes' 'tasks/')"
-  printf '%s/%s.notes.md' "$notes_dir" "$slug"
+  workflow_preferred_or_legacy_path "${notes_dir}/${stem}.notes.md" "${notes_dir}/${slug}.notes.md"
 }
 
 workflow_checks_file() {

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/partials/07-footer.partial.md

@@ -14,9 +14,9 @@ CLAUDE.md is a routing card. Keep context minimal and load only what the current
 |---------|----------------|
 | Deep codebase investigation | `tasks/research.md` |
 | Active implementation planning | `plans/plan-*.md` |
-| Sprint done definition | `tasks/contracts/<slug>.contract.md` |
-| Evaluator verdict | `tasks/reviews/<slug>.review.md` |
-| Implementation notes | `tasks/notes/<slug>.notes.md` |
+| Sprint done definition | `tasks/contracts/<plan-stem>.contract.md` |
+| Evaluator verdict | `tasks/reviews/<plan-stem>.review.md` |
+| Implementation notes | `tasks/notes/<plan-stem>.notes.md` |
 | Latest verification evidence | `.ai/harness/checks/latest.json` |
 | Historical implementation context | `plans/archive/` and `tasks/archive/` |
 | Agentic skill routing | `docs/reference-configs/agentic-development-flow.md` |

package/assets/partials/08-orchestration.partial.md

@@ -36,7 +36,7 @@
 - Define per-sprint contract files in `tasks/contracts/`.
 - Verify contract exit criteria before claiming completion.
 - Require Waza `/check` to produce the matching evaluator review before any done/completed response.
-- Use `scripts/verify-contract.sh --contract tasks/contracts/{slug}.contract.md --strict`.
+- Use `scripts/verify-contract.sh --contract tasks/contracts/{plan-stem}.contract.md --strict`.
 
 ### 7. Balanced Elegance
 - Redesign hacky non-trivial fixes before shipping.

package/assets/partials-agents/04-task-protocol.partial.md

@@ -29,16 +29,16 @@ RULES:
   - Keep multiple active plans in parallel worktrees when tasks diverge; fill workflow inventory before implementation: active plan, owning worktree, contract, review, notes, deferred ledger, checks, runs, scope owner, switching rule, and worktree path
   - Process annotation notes before implementing
   - Extract approved plan tasks into tasks/todo.md
-  - Define task contracts in tasks/contracts/{slug}.contract.md
-  - Fill tasks/reviews/{slug}.review.md from Waza /check after verification
-  - Record only non-obvious implementation decisions, deviations, tradeoffs, and open questions in tasks/notes/{slug}.notes.md
+  - Define task contracts in tasks/contracts/{plan-stem}.contract.md
+  - Fill tasks/reviews/{plan-stem}.review.md from Waza /check after verification
+  - Record only non-obvious implementation decisions, deviations, tradeoffs, and open questions in tasks/notes/{plan-stem}.notes.md
   - Verify contracts before claiming completion
   - Require review pass before claiming completion
   - Keep tasks/todo.md limited to deferred medium/long-term goals, with tradeoff and revisit trigger; do not duplicate plan Task Breakdown
   - Record correction-derived prevention rules in tasks/lessons.md
   - Distill repeated corrections into tasks/lessons.md instead of keeping them in tasks/todo.md
   - Capture deep findings and hidden contracts in tasks/research.md
-  - Keep sprint-level verification notes, behavior diffs, and residual risks in tasks/reviews/{slug}.review.md
+  - Keep sprint-level verification notes, behavior diffs, and residual risks in tasks/reviews/{plan-stem}.review.md
   - Do not use implementation notes as durable memory or task logs; archive them on close and promote only after evidence shows the rule should outlive the sprint
   - Promote implementation-ready follow-up work into a new plans/plan-{timestamp}-{slug}.md file; keep deferred goals in tasks/todo.md only when intentionally postponed
   - Treat `.ai/hooks/` as the shared automation entrypoint when repo scripts reference hook-backed workflow checks