repo-harness 0.4.2 → 0.4.3

package/README.es.md

@@ -345,8 +345,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.4.2`
-- Generated workflow stamp: `repo-harness@0.4.2+template@0.4.2`
+- npm package: `repo-harness@0.4.3`
+- Generated workflow stamp: `repo-harness@0.4.3+template@0.4.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -350,8 +350,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.4.2`
-- Generated workflow stamp : `repo-harness@0.4.2+template@0.4.2`
+- npm package : `repo-harness@0.4.3`
+- Generated workflow stamp : `repo-harness@0.4.3+template@0.4.3`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -312,8 +312,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.4.2`
-- Generated workflow stamp：`repo-harness@0.4.2+template@0.4.2`
+- npm package：`repo-harness@0.4.3`
+- Generated workflow stamp：`repo-harness@0.4.3+template@0.4.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -34,20 +34,29 @@ This repository now dogfoods its own tasks-first contract. It is both:
   read a 1KB capability contract or query the index instead of spending thousands of
   tokens rediscovering structure.
 
-## What's New in 0.4.2
-
-- **PRD-to-Sprint planning hierarchy.** `repo-harness-prd` now owns
-  upper-layer product requirements under `plans/prds/`, while
-  `repo-harness-sprint` derives ordered execution backlogs under
-  `plans/sprints/*.sprint.md`.
-- **Generated helper runtime isolation.** Downstream installs place real helper
-  implementations under `.ai/harness/scripts/` and keep root `scripts/*` as
-  compatibility wrappers; this self-host repo remains the source runtime.
-- **Subagent return-channel guard.** Managed hook routes include a guard that
-  keeps delegated runs reporting back through the parent session instead of
-  bypassing the file-backed contract.
-- **Release path alignment.** PRD/Sprint eval fixtures, workflow checks, and
-  command guidance now point at the same installed helper runtime.
+In an adopted repo, the surface area is intentionally small:
+
+| Surface | Purpose |
+| --- | --- |
+| `docs/spec.md` and `docs/reference-configs/` | Shared standards and stable product intent that every agent session can read. |
+| `plans/`, `plans/prds/`, and `plans/sprints/` | Decision-complete work packages before implementation starts. |
+| `tasks/contracts/`, `tasks/reviews/`, and `.ai/harness/checks/` | Scope, verification, and review evidence for proving the work is done. |
+| `.ai/harness/handoff/` and `tasks/current.md` | Session journal and resumable status, derived from workflow artifacts instead of chat memory. |
+
+## What's New in 0.4.3
+
+- **Runtime docs lookup.** `repo-harness docs list|path|show` resolves bundled
+  runtime/reference docs from the installed package instead of requiring copied
+  repo prose.
+- **Init-hook bootstrap audit.** `repo-harness init-hook --json` reports concrete
+  Agent actions for missing working rules, adapter drift, stale CLI installs,
+  and tooling readiness.
+- **First-principles edit guard.** Managed hook routes now include
+  anti-overengineering guidance for implementation edits while keeping the guard
+  advisory.
+- **Slimmer generated reference docs.** Generated and migrated repos write
+  deterministic `docs/reference-configs/*.md` pointer stubs while `.ai/harness/*`
+  and `.ai/context/*` remain local runtime artifacts.
 
 ## What repo-harness Does
 
@@ -200,9 +209,11 @@ concrete sprint instead of reinterpreting the original chat.
 ## First 5 Minutes
 
 This is the fastest path for an AI tooling owner evaluating whether the workflow is
-safe to adopt in a real repo.
+safe to adopt in a real repo. It separates the machine-level runtime bootstrap
+from the repo-local contract install, so a dry run can show exactly what will
+change before anything is applied.
 
-### Initial bootstrap
+### 1. Bootstrap the host runtime once
 
 ```bash
 npx -y repo-harness init
@@ -214,27 +225,36 @@ user-level hook adapters, configures Waza runtime skills, persists a brain root
 under `~/.repo-harness/config.json`, and configures CodeGraph MCP. It does not
 apply repo-local workflow files to the current directory.
 
-### Install or refresh a repo-local harness
+For an Agent-owned, read-only bootstrap audit, run `npx -y repo-harness
+init-hook --json` or add `--check-updates` for version advisories. `init-hook`
+is not a runtime hook: it does not write user-level files, install updates, or
+register adapters. It emits `agent_actions` with the reason, risk, target files,
+optional command, and verification surface for the Agent to execute deliberately.
+
+### 2. Preview the repo-local contract
 
 ```bash
 npx -y repo-harness update --dry-run
+```
+
+Run the dry run from the target repository root. It reports the specs, task
+state, helper runtime, hook adapter target, and verification files that would be
+created or refreshed. It should not create an application stack; existing repos
+use `repo-harness update`, while new projects or modules use
+`repo-harness-scaffold`.
+
+### 3. Apply, then prove the workflow
+
+```bash
 npx -y repo-harness update
+bash scripts/check-task-workflow.sh --strict
+bun test
 ```
 
-`update` is the existing-repo install and refresh path. Run it from a target
-repository to install or refresh workflow files, hook assets, host adapters,
-skill aliases, and repo-local verification surfaces from the current npm package.
-
-The npm package and generated workflow stamp now share the `0.4.x` release line.
-The `0.4.2` package keeps first-run
-global bootstrap (`repo-harness init`) separate from repo-local refresh
-(`repo-harness update`) while adding the PRD-to-Sprint planning hierarchy,
-isolated generated-project helper runtime, subagent return-channel guard, and
-release-path alignment on top of the `0.4.0` loop-engine surfaces.
-These sit on top of the renamed `repo-harness` CLI, user-level hook
-adapter bootstrap, AI-native scaffold overlays, the typed prompt-guard decision
-engine, plan-stem task artifact naming, `REPO_HARNESS_*` runtime aliases, Waza
-runtime skill sync, and the maintainer release gate.
+After apply, the repo should have a reviewable file-backed contract rather than
+tool-specific chat setup. Agents should be able to find the stable intent in
+`docs/spec.md`, execution state in `plans/` and `tasks/`, and resume state in
+`.ai/harness/handoff/`.
 
 Only maintainers editing the package need a source checkout:
 
@@ -293,13 +313,6 @@ The command should end with `=== Migration Report ===` and summarize:
 - `Helper runtime:` to show `.ai/harness/scripts/*` implementations and `scripts/*` compatibility wrappers after apply
 - `--- External Tooling ---` to show default gstack/Waza/gbrain routing plus advisory install/update hints
 
-### Next two commands
-
-```bash
-bash scripts/check-task-workflow.sh --strict
-bun test
-```
-
 If the dry-run output looks wrong, stop there and inspect
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md)
 before applying anything.
@@ -381,8 +394,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.4.2`
-- Generated workflow stamp: `repo-harness@0.4.2+template@0.4.2`
+- npm package: `repo-harness@0.4.3`
+- Generated workflow stamp: `repo-harness@0.4.3+template@0.4.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -527,6 +540,22 @@ bun scripts/inspect-project-state.ts --repo . --format text
 bash scripts/migrate-project-template.sh --repo . --dry-run
 ```
 
+### Runtime reference docs
+
+Generic repo-harness runtime/reference docs live in the installed package under
+`assets/reference-configs/` and are resolved through the CLI:
+
+```bash
+repo-harness docs list
+repo-harness docs path harness-overview
+repo-harness docs show harness-overview
+```
+
+Generated and migrated repos still keep `docs/reference-configs/*.md`, but
+those files are deterministic pointer stubs. Repo-local workflow state,
+policy, checks, runs, handoff packets, context maps, and helper snapshots stay
+under `.ai/`.
+
 ### Explicit template assembly
 
 ```bash
@@ -556,8 +585,9 @@ bun run benchmark:skills --eval repair-agents-task-sync
 - Plan mapping: `assets/plan-map.json`
 - Question-pack: `assets/initializer-question-pack.v4.json`
 - Shared hooks: `assets/hooks/`
+- Runtime reference docs: `assets/reference-configs/` via `repo-harness docs`
 - Workflow contract: `assets/workflow-contract.v1.json`
-- Hook operations reference: `docs/reference-configs/hook-operations.md`
+- Source repo reference docs: `docs/reference-configs/*.md`
 - Template assembler: `scripts/assemble-template.ts`
 - Question inference helper: `scripts/initializer-question-pack.ts`
 - State inspector: `scripts/inspect-project-state.ts`

package/README.zh-CN.md

@@ -23,19 +23,27 @@ repo-local workflow 的自托管样例。
   做渐进式上下文加载：一份小而稳定的 root context（约 12KB），加上只在改到对应文件时才加载的
   capability 块。agent 读一份 1KB 的 capability 合约或查索引，而不是花上千 token 重新摸清结构。
 
-## 0.4.2 新特性
-
-- **PRD-to-Sprint planning hierarchy。** `repo-harness-prd` 负责
-  `plans/prds/` 下的上层产品需求，`repo-harness-sprint` 负责把 PRD 或明确
-  slice 推成 `plans/sprints/*.sprint.md` 下的有序执行 backlog。
-- **Generated helper runtime isolation。** 下游安装把真实 helper 实现放到
-  `.ai/harness/scripts/`，root `scripts/*` 只保留 compatibility wrappers；
-  自托管源码仓库继续以 root `scripts/` 作为 source runtime。
-- **Subagent return-channel guard。** Managed hook routes 增加 return-channel
-  guard，要求 delegated runs 回到 parent session 汇报，避免绕过 file-backed
-  contract。
-- **Release path alignment。** PRD/Sprint eval fixtures、workflow checks 和
-  command guidance 现在都指向同一个 installed helper runtime。
+接入后的仓库只需要理解几个 surface：
+
+| Surface | 作用 |
+| --- | --- |
+| `docs/spec.md` 和 `docs/reference-configs/` | 共享标准和稳定产品意图，每个 agent 会话都能读取。 |
+| `plans/`、`plans/prds/`、`plans/sprints/` | 实现前先沉淀 decision-complete work package。 |
+| `tasks/contracts/`、`tasks/reviews/`、`.ai/harness/checks/` | 证明完成所需的 scope、verification 和 review evidence。 |
+| `.ai/harness/handoff/` 和 `tasks/current.md` | session journal 与可恢复状态，从 workflow artifacts 派生，而不是依赖聊天记忆。 |
+
+## 0.4.3 新特性
+
+- **Runtime docs lookup。** `repo-harness docs list|path|show` 从已安装 package
+  解析 bundled runtime/reference docs，不再要求把完整 repo prose 复制到下游。
+- **Init-hook bootstrap audit。** `repo-harness init-hook --json` 会把缺失的
+  working rules、adapter drift、stale CLI install 和 tooling readiness 汇成
+  具体 Agent actions。
+- **First-principles edit guard。** Managed hook routes 增加实现编辑时的
+  anti-overengineering guidance，同时保持 advisory，不把风格判断变成硬拦截。
+- **更轻的 generated reference docs。** 生成和迁移的仓库写入确定性的
+  `docs/reference-configs/*.md` pointer stubs，`.ai/harness/*` 和 `.ai/context/*`
+  继续作为 repo-local runtime artifacts。
 
 ## 产品做什么
 
@@ -166,9 +174,11 @@ source of truth，Codex Goal mode 只围绕具体 sprint 恢复和推进，而
 
 ## 前 5 分钟
 
-这是评估一个真实仓库是否适合接入该 workflow 的最快路径。
+这是评估一个真实仓库是否适合接入该 workflow 的最快路径。它把机器级 runtime
+bootstrap 和 repo-local contract install 分开，所以 dry-run 能先展示会改什么，
+再决定是否应用。
 
-### 初次引导
+### 1. 先做一次 host runtime bootstrap
 
 ```bash
 npx -y repo-harness init
@@ -179,27 +189,34 @@ skill aliases，安装 user-level hook adapters，配置 Waza runtime skills，
 root 持久化到 `~/.repo-harness/config.json`，并配置 CodeGraph MCP。它不会把当前目录
 默认迁移成 repo-local workflow。
 
-### 安装或刷新 repo-local harness
+如果要让 Agent 做只读 bootstrap audit，运行 `npx -y repo-harness init-hook
+--json`；需要版本提示时加 `--check-updates`。`init-hook` 不是 runtime hook：
+它不会写 user-level files、安装更新或注册 adapters，只输出带 reason、risk、
+targets、可选 command 和 verification 的 `agent_actions`，由 Agent 再显式执行。
+
+### 2. 预览 repo-local contract
 
 ```bash
 npx -y repo-harness update --dry-run
-npx -y repo-harness update
 ```
 
-`update` 是已有目标仓库的安装和刷新入口。从目标仓库根目录运行它，用当前 npm 包
-安装或刷新 workflow files、hook assets、host adapters、skill aliases 和
-repo-local verification surfaces。
+在目标仓库根目录运行 dry-run。它会报告将要创建或刷新的 spec、task state、
+helper runtime、hook adapter target 和 verification files。它不会创建应用技术栈；
+已有仓库走 `repo-harness update`，新项目或新模块走 `repo-harness-scaffold`。
 
-npm package 和 generated workflow stamp 现在共用 `0.4.x` release line。
-`repo-harness@0.4.2` 继续把首次全局引导（`repo-harness init`）
-和 repo-local 刷新（`repo-harness update`）拆开，并在 `0.4.0` loop-engine
-surfaces 之上加入 PRD-to-Sprint planning hierarchy、isolated generated-project
-helper runtime、subagent return-channel guard 和 release-path alignment。
-这些能力叠加在改名后的 CLI、user-level hook adapter bootstrap、AI-native scaffold overlays、
-typed prompt-guard decision engine、plan-stem task artifact 命名、`REPO_HARNESS_*`
-runtime aliases、Waza runtime skill sync，以及 maintainer 发布 npm 前使用的 release gate 之上。
+### 3. 应用后验证 workflow
+
+```bash
+npx -y repo-harness update
+bash scripts/check-task-workflow.sh --strict
+bun test
+```
 
-只有维护者需要在编辑 package 源码时使用 source checkout：
+应用后，目标仓库应该得到一套可审查的 file-backed contract，而不是 tool-specific
+聊天配置。agent 应该能在 `docs/spec.md` 找到稳定意图，在 `plans/` 和 `tasks/`
+找到执行状态，在 `.ai/harness/handoff/` 找到可恢复状态。
+
+只有维护者编辑 package 源码时才需要 source checkout：
 
 ```bash
 git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
@@ -253,13 +270,6 @@ npx -y repo-harness update
 - `Helper scripts:`：应用后会得到的操作工具链
 - `--- External Tooling ---`：gstack/Waza/gbrain 路由以及 advisory 安装/更新提示
 
-### 接着跑的两个命令
-
-```bash
-bash scripts/check-task-workflow.sh --strict
-bun test
-```
-
 如果 dry-run 输出不对，先停在这里，阅读
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md)。
 
@@ -333,8 +343,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.4.2`
-- Generated workflow stamp：`repo-harness@0.4.2+template@0.4.2`
+- npm package：`repo-harness@0.4.3`
+- Generated workflow stamp：`repo-harness@0.4.3+template@0.4.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/assets/hooks/anti-simplification.sh

@@ -1,30 +1,12 @@
 #!/bin/bash
-# Anti-Simplification Guard — PostToolUse on Edit|Write
-# Warns when changes suggest compatibility debt or unnecessary branch complexity.
+# Compatibility wrapper for the renamed First-Principles Guard.
 
 set -eo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=/dev/null
-. "$SCRIPT_DIR/hook-input.sh"
 
-FILE_PATH="$(hook_get_file_path "${1:-}")"
-[[ -z "$FILE_PATH" ]] && exit 0
-
-if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  exit 0
+if [[ -f "$SCRIPT_DIR/first-principles-guard.sh" ]]; then
+  exec bash "$SCRIPT_DIR/first-principles-guard.sh" "$@"
 fi
 
-DIFF_CONTENT="$(git diff -- "$FILE_PATH" 2>/dev/null || true)"
-[[ -z "$DIFF_CONTENT" ]] && exit 0
-
-if echo "$DIFF_CONTENT" | grep -E '^\+.*(legacy|compat|backward|polyfill|shim)' >/dev/null; then
-  echo "[AntiSimplification] Compatibility-like additions detected in $FILE_PATH"
-  echo "  Prefer clean upgrades and rewrite-over-patch instead of legacy branches."
-fi
-
-branch_additions="$(echo "$DIFF_CONTENT" | grep -E '^\+.*\b(if|else if|switch)\b' | wc -l | tr -d ' ')"
-if [[ "$branch_additions" -ge 4 ]]; then
-  echo "[AntiSimplification] Branch-heavy additions detected in $FILE_PATH ($branch_additions new branch lines)"
-  echo "  Re-check data structures before adding more control-flow branches."
-fi
+exit 0

package/assets/hooks/first-principles-guard.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# First-Principles Guard — PostToolUse on Edit|Write
+# Warns when diffs add likely overengineering. Advisory only.
+
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+
+FILE_PATH="$(hook_get_file_path "${1:-}")"
+[[ -z "$FILE_PATH" ]] && exit 0
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+DIFF_CONTENT="$(git diff -- "$FILE_PATH" 2>/dev/null || true)"
+[[ -z "$DIFF_CONTENT" ]] && exit 0
+
+ADDED_LINES="$(printf '%s\n' "$DIFF_CONTENT" | grep -E '^\+[^+]' | sed 's/^+//' || true)"
+[[ -z "$ADDED_LINES" ]] && exit 0
+
+warned=0
+
+count_matches() {
+  local pattern="$1"
+  { printf '%s\n' "$ADDED_LINES" | grep -Ei "$pattern" || true; } | wc -l | tr -d ' '
+}
+
+emit_warning() {
+  local category="$1"
+  local detail="$2"
+  warned=1
+  echo "[FirstPrinciples] ${category} in $FILE_PATH"
+  echo "  Re-check: must this exist, does platform/stdlib/current dependency already cover it, can the diff collapse?"
+  [[ -n "$detail" ]] && echo "  Trigger: $detail"
+}
+
+compat_count="$(count_matches '(^|[^[:alnum:]_])(legacy|compat|backward|polyfill|shim)([^[:alnum:]_]|$)')"
+if [[ "$compat_count" -gt 0 ]]; then
+  emit_warning "Compatibility debt additions detected" "${compat_count} compatibility-like line(s)"
+fi
+
+branch_count="$(count_matches '(^|[^[:alnum:]_])(if|else[[:space:]]+if|switch|case)([^[:alnum:]_]|$)')"
+if [[ "$branch_count" -ge 4 ]]; then
+  emit_warning "Branch-heavy additions detected" "${branch_count} new branch/control-flow line(s)"
+fi
+
+abstraction_count="$(count_matches '(^|[^[:alnum:]_])(interface|abstract[[:space:]]+class|factory|adapter|provider|strategy|manager|orchestrator|dispatcher|registry)([^[:alnum:]_]|$)')"
+if [[ "$abstraction_count" -gt 0 ]]; then
+  emit_warning "Abstraction-heavy additions detected" "${abstraction_count} abstraction-like line(s)"
+fi
+
+dependency_count="$(count_matches '(^|[[:space:]])(import[[:space:]].*from[[:space:]]*["'\''][^./]|import[[:space:]]*["'\''][^./]|require\(["'\''][^./]|"(dependencies|devDependencies|peerDependencies|optionalDependencies)"[[:space:]]*:|"[@A-Za-z0-9._/-]+"[[:space:]]*:[[:space:]]*"[~^0-9])')"
+if [[ "$dependency_count" -gt 0 ]]; then
+  emit_warning "Dependency-surface additions detected" "${dependency_count} dependency/import line(s)"
+fi
+
+config_count="$(count_matches '(^|[^[:alnum:]_])(process\.env|import\.meta\.env|feature[-_ ]?flag|FEATURE_|Config|config|Settings|settings)([^[:alnum:]_]|$)')"
+if [[ "$config_count" -gt 1 ]]; then
+  emit_warning "Config-surface additions detected" "${config_count} config/env/flag line(s)"
+fi
+
+state_machine_count="$(count_matches '(^|[^[:alnum:]_])(state[[:space:]_-]?machine|lifecycle|workflow|route|routing|registry|orchestrator)([^[:alnum:]_]|$)')"
+if [[ "$state_machine_count" -gt 1 ]]; then
+  emit_warning "Local orchestration additions detected" "${state_machine_count} orchestration-like line(s)"
+fi
+
+if [[ "$warned" -eq 1 ]]; then
+  echo "  Boundary: keep trust-boundary validation, data-loss prevention, security, accessibility, and explicit user-requested behavior."
+fi

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

@@ -148,9 +148,11 @@ if [[ "$BASENAME" =~ ^wrangler.*\.toml$ ]]; then
   echo "  Check: docs/guides/cf-deployment.md bindings/routes may need updating"
 fi
 
-# Aggregated advisory (route-registry keeps one PostToolUse edit entry; the
+# Aggregated advisories (route-registry keeps one PostToolUse edit entry; the
 # dispatcher-level aggregation lives here).
-if [[ -x "$SCRIPT_DIR/anti-simplification.sh" ]]; then
+if [[ -f "$SCRIPT_DIR/first-principles-guard.sh" ]]; then
+  bash "$SCRIPT_DIR/first-principles-guard.sh" "$FILE_PATH" </dev/null || true
+elif [[ -f "$SCRIPT_DIR/anti-simplification.sh" ]]; then
   bash "$SCRIPT_DIR/anti-simplification.sh" "$FILE_PATH" </dev/null || true
 fi
 

package/assets/hooks/stop-orchestrator.sh

@@ -79,6 +79,36 @@ plan_completeness_record_signature() {
 EOF_STATE
 }
 
+plan_completeness_shell_quote() {
+  printf '%q' "$1"
+}
+
+plan_completeness_capture_guidance() {
+  local kind prompt_slug source_ref title source_arg
+
+  kind="$(workflow_pending_orchestration_field kind 2>/dev/null || true)"
+  prompt_slug="$(workflow_pending_orchestration_field prompt_slug 2>/dev/null || true)"
+  source_ref="$(workflow_pending_orchestration_field source_ref 2>/dev/null || true)"
+
+  kind="${kind:-host-plan}"
+  prompt_slug="${prompt_slug:-planning}"
+  title="${source_ref:-$prompt_slug}"
+  source_arg=""
+  if [[ -n "$source_ref" ]]; then
+    source_arg=" --source-ref $(plan_completeness_shell_quote "$source_ref")"
+  fi
+
+  cat <<EOF_GUIDANCE
+If the planning answer is decision-complete, capture the final plan body before stopping:
+  printf '%s\n' '<decision-complete plan body>' | bash scripts/capture-plan.sh --slug $(plan_completeness_shell_quote "$prompt_slug") --title $(plan_completeness_shell_quote "$title") --status Draft --source $(plan_completeness_shell_quote "$kind") --orchestration-kind $(plan_completeness_shell_quote "$kind") --route planning${source_arg}
+
+If the user already approved implementation, use:
+  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug $(plan_completeness_shell_quote "$prompt_slug") --title $(plan_completeness_shell_quote "$title") --status Approved --source $(plan_completeness_shell_quote "$kind") --orchestration-kind $(plan_completeness_shell_quote "$kind") --route planning --execute${source_arg}
+
+If the plan is not decision-complete, revise once for: goal/success criteria, scope/non-scope, constraints, P1/P2/P3, fragile assumption, rejected alternative, public API/config/file-interface changes, external dependency/API key requirements, tests, rollback/failure handling, phase independence, and no placeholders. Do not implement until capture succeeds.
+EOF_GUIDANCE
+}
+
 assistant_message_looks_like_plan() {
   local message="$1"
   local length
@@ -133,8 +163,9 @@ if should_run_plan_completeness_gate "$stop_hook_active" "$last_assistant_messag
   if [[ "$(plan_completeness_last_signature 2>/dev/null || true)" != "$signature" ]]; then
     plan_completeness_record_signature "$signature"
     summary="$(workflow_pending_orchestration_summary)"
+    guidance="$(plan_completeness_capture_guidance)"
     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, scope/non-scope, constraints, P1 component map, P2 traced path, P3 decision rationale, fragile assumption, rejected alternative, public API/config/file-interface changes, external dependency/API key requirements, tests, rollback/failure handling, phase independence, and no placeholders. If the plan is already complete, say so explicitly and keep the revision concise. Then stop and wait for user approval."
+${guidance}"
   fi
 fi

package/assets/reference-configs/global-working-rules.md

@@ -5,7 +5,7 @@ Use this content for user-level `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` w
 ```md
 # Global Working Rules
 
-- Use the user's language for reports; keep technical terms in English.
+- Use Chinese by default for this user; keep technical terms in English. If the user writes in another language, mirror that language.
 - Act as an engineering collaborator: finish the concrete task, verify it, then report conclusion, actual change, reason, verification, and residual risk.
 - Prefer direct execution over repeated confirmation. Stop to ask only when continuing would likely produce output contrary to the user's intent.
 
@@ -41,6 +41,23 @@ For architecture reviews, bug hunts, risky refactors, deployment issues, auth/pa
 
 Reports must be concise and grounded in files, commands, runtime behavior, observed code, or verified system state.
 
+## Completion Summary Rule
+
+For non-trivial completed tasks, include a short `下一刀` section at the end of the final delivery report unless there is genuinely no meaningful follow-up.
+For non-trivial completed tasks, include a short `下一刀` section only when verified state shows a concrete next bottleneck, unresolved risk, failing check, deployment gap, review gap, or active-plan item that materially affects the user's stated goal.
+
+Do not manufacture follow-up work just to keep slicing. If the task is reasonably complete and the remaining work would be speculative, low-value polish, or over-engineering, omit `下一刀` and stop at the completion report.
+
+The recommendation is not a question. It must be one concrete, bounded next slice derived from verified state: active plan, todo, handoff, failing checks, review gaps, deployment state, unresolved risk, or observed system behavior.
+When included, the recommendation is not a question. It must be one concrete, bounded next slice derived from verified state: active plan, todo, handoff, failing checks, review gaps, deployment state, unresolved risk, or observed system behavior.
+
+Format:
+
+**下一刀**
+建议切 `<具体方向>`。理由是 `<最影响推进的未闭环点>`。入口是 `<路径/命令/验证面>`。
+
+The recommendation must also explain why this is the next bottleneck, why the slice is sufficient rather than an open-ended continuation, and the entrypoint file, command, route, artifact, or verification surface.
+
 ## Research Delegation
 
 When a task requires broad research, repo archaeology, multi-source synthesis, or background surveys, delegate or isolate the research pass when the runtime supports it. Keep the main thread focused on planning, integration, and decisions.

package/assets/reference-configs/handoff-protocol.md

@@ -24,13 +24,14 @@ Handoffs make long-running work resumable without trusting chat history.
 ## Restore Flow
 
 1. Start a fresh Codex session instead of relying on auto-compact or `codex resume` when the old session is near the limit.
-2. Read `.ai/harness/handoff/resume.md`.
-3. Read `.ai/harness/handoff/current.md`.
-4. Read `tasks/current.md` as an orientation snapshot only; in a non-target worktree, compare it with `git show <target>:tasks/current.md`.
-5. Read the active plan and sprint contract.
-6. Read the latest review file if one exists.
-7. Read `.ai/harness/checks/latest.json`.
-8. Resume from the exact next step.
+2. If the current user message lists files under `# Files mentioned by the user`, references `pasted-text.txt`, or includes an explicit attachment/file path, read those current-input files before repo recovery artifacts.
+3. Read `.ai/harness/handoff/resume.md`.
+4. Read `.ai/harness/handoff/current.md`.
+5. Read `tasks/current.md` as an orientation snapshot only; in a non-target worktree, compare it with `git show <target>:tasks/current.md`.
+6. Read the active plan and sprint contract.
+7. Read the latest review file if one exists.
+8. Read `.ai/harness/checks/latest.json`.
+9. Resume from the exact next step.
 
 ## Source Of Truth
 

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

@@ -2,6 +2,25 @@
 
 This repo uses a shared long-running harness. The durable workflow lives in repo-local artifacts, not in chat memory.
 
+## Adoption Model
+
+Use this file as the first onboarding map after `repo-harness update` installs
+or refreshes a repo. The harness gives agents three durable surfaces:
+
+- **Shared standards**: `docs/spec.md`, `docs/reference-configs/`, root
+  `AGENTS.md`, and root `CLAUDE.md` explain stable product intent, coding
+  rules, and local workflow boundaries.
+- **Task contracts**: `plans/`, `tasks/contracts/`, `tasks/reviews/`, and
+  `.ai/harness/checks/` turn a request into scoped implementation work with
+  evidence-backed completion.
+- **Session journal**: `.ai/harness/handoff/`, `tasks/current.md`, and
+  `.ai/harness/events.jsonl` let a new agent session resume from repo state
+  without treating chat history as authority.
+
+The install is not an app scaffold or an agent gateway. It adds a reviewable
+workflow contract around an existing repo, then leaves product code ownership
+with the project.
+
 ## Roles
 
 - **Planner** updates `docs/spec.md`, researches constraints, and writes or approves `plans/plan-*.md`.

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

@@ -36,7 +36,17 @@ repo-harness security scan --json
 
 `PostToolUse.always` runs one merged observer, `post-tool-observer.sh` (JSONL trace + lightweight advisories); the trace file `.claude/.trace.jsonl` is the single tool-trace record.
 
-`PostToolUse.edit` runs a downstream sync chain after local edit reminders: architecture drift record, context contract sync, capability-context queueing, repo-to-brain mirror sync, and active contract verification. These stages remain advisory. A failed downstream stage must emit one `[SyncChain] WARN: ...` line and let the edit hook exit 0 so local editing is not blocked by maintenance drift.
+`PostToolUse.edit` runs local edit reminders, the FirstPrinciples
+anti-overengineering advisory, then the downstream sync chain: architecture
+drift record, context contract sync, capability-context queueing, repo-to-brain
+mirror sync, and active contract verification. These stages remain advisory. A
+failed downstream stage must emit one `[SyncChain] WARN: ...` line and let the
+edit hook exit 0 so local editing is not blocked by maintenance drift. The
+FirstPrinciples advisory reviews only the current file diff and asks whether new
+dependencies, compatibility branches, abstractions, config surfaces, or
+branch-heavy logic truly need to exist; it must not override trust-boundary
+validation, data-loss prevention, security, accessibility, or explicit
+user-requested behavior.
 
 `.ai/harness/scripts/sync-brain-docs.sh --changed <path>` is hot-path optimized: the PostEdit hook starts it only when the changed repo path appears in the brain manifest. The script still owns authoritative JSON parsing and containment checks. Source files that resolve outside the repo, or brain targets that resolve outside the configured brain root through symlinks, are rejected.
 

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.4.2",
-  "templateVersion": "0.4.2",
+  "version": "0.4.3",
+  "templateVersion": "0.4.3",
   "skillName": "repo-harness",
   "contractId": "tasks-first-harness-v1",
   "retiredAliases": [
@@ -119,6 +119,10 @@
     {
       "version": "0.4.2",
       "description": "Adds the PRD-to-Sprint planning hierarchy, isolates generated-project helper runtime under .ai/harness/scripts, and installs the subagent return-channel guard"
+    },
+    {
+      "version": "0.4.3",
+      "description": "Adds bundled runtime docs lookup, init-hook bootstrap audit guidance, first-principles edit guard coverage, and slimmer generated reference-doc assets"
     }
   ],
   "generatedProjectStamp": {