repo-harness 0.1.2 → 0.1.3

package/README.md

@@ -45,6 +45,16 @@ The design has three layers:
    the current repo's `.ai/hooks/*` scripts only when
    `.ai/harness/workflow-contract.json` exists.
 
+For `UserPromptSubmit`, the public adapter contract stays
+`repo-harness-hook UserPromptSubmit --route default`. The CLI route registry
+dispatches that route to `.ai/hooks/prompt-guard.sh`. The shell hook remains the
+repo-local adapter for host JSON parsing, workflow file reads, capture side
+effects, quality gate rendering, and host-safe stdout/stderr. The prompt intent
+and workflow-state decision is handled by the TypeScript decision engine behind
+`repo-harness-hook prompt-guard-decide`, which returns one action enum from an
+explicit decision table. That split keeps host configuration stable while moving
+the brittle classifier/state-machine layer out of shell conditionals.
+
 The core invariant is that durable truth lives in the repo, not in a chat
 thread. Hooks are accelerators and guardrails; the authority remains the
 file-backed plan, contract, review, checks, and handoff artifacts.
@@ -111,9 +121,10 @@ 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.2` package publishes the
+tracked separately as the `5.x` model line. The `0.1.3` package publishes the
 renamed `repo-harness` CLI, user-level Claude/Codex hook adapter bootstrap,
-Waza runtime skill sync, `diagram-design` sync, and the release gate used by
+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:
 
@@ -194,6 +205,23 @@ before applying anything.
 - Codex must mark `~/.codex/hooks.json` as trusted in Codex Settings before those hooks run.
 - Debug in this order: user-level adapter config -> `repo-harness-hook` (or fallback `repo-harness hook`) -> route registry -> `.ai/hooks/*`.
 
+Prompt guard has one extra internal step:
+
+```mermaid
+flowchart LR
+  Host["Claude/Codex UserPromptSubmit"] --> Adapter["user-level adapter"]
+  Adapter --> CLI["repo-harness-hook UserPromptSubmit --route default"]
+  CLI --> Route["route registry"]
+  Route --> Shell[".ai/hooks/prompt-guard.sh"]
+  Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
+  Decision --> Action["single action enum"]
+  Action --> Shell
+  Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
+```
+
+The shell layer still owns filesystem authority and side effects. TypeScript owns
+only the classifier plus `intent x plan state` decision table.
+
 ## Hook Failure Playbook
 
 When a hook blocks work, start with the structured output in the terminal. The core
@@ -222,7 +250,7 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.1.2`
+- npm package: `repo-harness@0.1.3`
 - Generated workflow compatibility: `5.2.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -270,6 +298,23 @@ Most common guards:
   - durable capability progress -> `tasks/workstreams/`
   - release history -> `docs/CHANGELOG.md`
 
+## Acknowledgements and Tooling Dependencies
+
+`repo-harness` is built around a small set of external skills and repos that
+proved useful while this project was being designed, debugged, and released.
+They are acknowledged here because they shaped the workflow contract, but they
+are not all bundled product dependencies.
+
+| Tool or repo | Used for | Dependency shape |
+| --- | --- | --- |
+| gstack skills, including `document-release`, `office-hours`, `plan-eng-review`, and `plan-design-review` | Product discovery, plan review, design review, and post-ship documentation hygiene | External operator workflow; advisory by default |
+| Waza skills, including `think`, `hunt`, `check`, `health`, `design`, `learn`, `read`, and `write` | Daily planning, bug hunts, verification, health checks, and Codex-first skill sync | Installed through the skills CLI into host skill roots |
+| `diagram-design` | Human-readable architecture and system-flow diagrams when Mermaid is not enough | Runtime-referenced skill, not vendored into generated repos |
+| `gbrain` | Knowledge sync, handoff retrieval, and long-form repo memory | Optional external CLI and index |
+| CodeGraph (`@colbymchenry/codegraph`) | Symbol-aware navigation, impact tracing, and readiness checks for this self-host repo | Dev dependency in this repo; generated repos stay global-MCP-first unless policy opts in |
+| Bun | Source checkout execution, tests, template assembly, and release checks | Required local runtime for maintainers |
+| `commander` | `repo-harness` CLI command parsing | Runtime npm dependency |
+
 ## Action Command Skills
 
 Source-owned command skill facades live in `assets/skill-commands/`. They keep
@@ -284,6 +329,15 @@ and tests:
 project or module scaffold. `hooks-init`, `docs-init`, and `create-project-dirs`
 are internal steps, not public commands.
 
+`repo-harness-scaffold` keeps the A-K plan catalog as the project-type authority
+and adds AI-native app structure through an optional `ai_native_profile` overlay.
+The default profile is `none`, so existing scaffold output remains unchanged.
+When selected, profiles such as `runtime-console`, `product-copilot`, and
+`sidecar-kernel` document the AG-UI event boundary, assistant-ui or CopilotKit
+UI runtime, Bun/Hono gateway, shared contracts, observability, and MCP/HTTP
+sidecar rules without installing model providers or making Python, Go, Rust, or
+A2UI mandatory defaults.
+
 Use `repo-harness-capability` when the harness already exists and only selected
 capability boundaries should be added. It updates `.ai/context/capabilities.json`,
 syncs the requested local `AGENTS.md` / `CLAUDE.md` contract files, and validates

package/README.zh-CN.md

@@ -40,6 +40,15 @@ repo-local hooks，然后验证这些 workflow surfaces 仍然一致。
    repo 是否存在 `.ai/harness/workflow-contract.json`；没有 opt in 就静默退出，有 opt in
    才进入当前仓库的 `.ai/hooks/*`。
 
+对 `UserPromptSubmit` 来说，公开 adapter contract 仍然是
+`repo-harness-hook UserPromptSubmit --route default`。CLI route registry 会把这个
+route dispatch 到 `.ai/hooks/prompt-guard.sh`。Shell hook 继续负责 host JSON 解析、
+workflow 文件读取、plan capture 副作用、quality gate 渲染，以及 host-safe
+stdout/stderr。Prompt intent 和 workflow state 的决策交给
+`repo-harness-hook prompt-guard-decide` 背后的 TypeScript decision engine；它从显式
+decision table 里返回一个 action enum。这样 host 配置不变，但最容易出错的
+classifier/state-machine 层不再散落在 shell 条件分支里。
+
 核心不变量：持久事实在仓库里，不在聊天窗口里。Hooks 只是加速器和 guardrail；
 真正的 authority 是 plan、contract、review、checks 和 handoff 这些文件。
 
@@ -103,9 +112,10 @@ npx -y repo-harness init
 ```
 
 npm package release line 是 `0.1.x`；生成的 workflow compatibility model line
-单独以 `5.x` 追踪。`repo-harness@0.1.2` 发布的是改名后的 CLI、Claude/Codex
-user-level hook adapter bootstrap、Waza runtime skill sync、`diagram-design` sync，
-以及 maintainer 发布 npm 前使用的 release gate。
+单独以 `5.x` 追踪。`repo-harness@0.1.3` 发布的是改名后的 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。
 
 如果从源码 checkout 工作：
 
@@ -180,6 +190,23 @@ bun test
 - Codex 必须在 Settings 里信任 `~/.codex/hooks.json`，hooks 才会执行。
 - 调试顺序：user-level adapter config -> `repo-harness-hook` 或 fallback `repo-harness hook` -> route registry -> `.ai/hooks/*`。
 
+Prompt guard 多一个内部步骤：
+
+```mermaid
+flowchart LR
+  Host["Claude/Codex UserPromptSubmit"] --> Adapter["user-level adapter"]
+  Adapter --> CLI["repo-harness-hook UserPromptSubmit --route default"]
+  CLI --> Route["route registry"]
+  Route --> Shell[".ai/hooks/prompt-guard.sh"]
+  Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
+  Decision --> Action["single action enum"]
+  Action --> Shell
+  Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
+```
+
+Shell 层仍然拥有文件系统 authority 和副作用。TypeScript 只拥有 classifier 加
+`intent x plan state` decision table。
+
 ## Hook Failure Playbook
 
 hook block 工作时，先看 terminal 里的结构化输出。核心字段是
@@ -208,7 +235,7 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.1.2`
+- npm package：`repo-harness@0.1.3`
 - Generated workflow compatibility：`5.2.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)

package/SKILL.md

@@ -138,6 +138,28 @@ Custom Presets (G-K):
 - Plan J: AI coding agent / TUI
 - Plan K: Fully custom configuration
 
+## AI-native scaffold overlay
+
+`repo-harness-scaffold` keeps A-K as the project-type catalog and uses
+`ai_native_profile` as a separate overlay axis. The default profile is `none`,
+so existing generated output stays on the selected A-K plan. Use an overlay only
+when the generated app needs agent runtime, UI protocol, tool, sidecar, state,
+or observability boundaries.
+
+Supported profile IDs live in `assets/initializer-question-pack.v4.json`.
+Generated structure overlays currently exist for:
+
+- `runtime-console`: Vite 8 + assistant-ui, AG-UI event transport, Bun/Hono
+  agent gateway, run store, contracts, approvals, artifacts, and telemetry
+- `product-copilot`: in-product copilot panel, AG-UI app-domain events, product
+  context loaders, business action tools, authorization and approval policies
+- `sidecar-kernel`: Bun/Hono app gateway with Python, Go, or Rust kernels behind
+  MCP tools or narrow HTTP jobs
+
+Do not turn the AI-native overlay into another lettered plan. Do not make A2UI,
+Python, Go, Rust, Redis, ClickHouse, Temporal, object storage, vector DBs, model
+providers, or tracing vendors mandatory defaults.
+
 ## Migration Rules
 
 For legacy repos, migrate old document surfaces before refreshing templates.

package/assets/hooks/post-bash.sh

@@ -10,12 +10,44 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 . "$SCRIPT_DIR/lib/workflow-state.sh"
 
+post_bash_set_tool_output_from_stdin() {
+  local parsed tmp
+
+  hook_read_stdin_once
+  [[ -n "${HOOK_STDIN_JSON:-}" ]] || return 1
+
+  if command -v jq >/dev/null 2>&1; then
+    if printf '%s' "$HOOK_STDIN_JSON" | jq -e 'has("tool_output") and .tool_output != null' >/dev/null 2>&1; then
+      IFS= read -r -d '' parsed < <(printf '%s' "$HOOK_STDIN_JSON" | jq -j '.tool_output' 2>/dev/null; printf '\0')
+      TOOL_OUTPUT="$parsed"
+      return 0
+    fi
+  fi
+
+  command -v bun >/dev/null 2>&1 || return 1
+  tmp="$(mktemp "${TMPDIR:-/tmp}/post-bash-tool-output.XXXXXX")" || return 1
+  if JSON_INPUT="$HOOK_STDIN_JSON" bun -e '
+    const raw = process.env.JSON_INPUT ?? "";
+    const value = JSON.parse(raw).tool_output;
+    if (value == null) process.exit(1);
+    if (typeof value === "object") process.stdout.write(JSON.stringify(value));
+    else process.stdout.write(String(value));
+  ' > "$tmp" 2>/dev/null; then
+    IFS= read -r -d '' parsed < <(cat "$tmp"; printf '\0')
+    TOOL_OUTPUT="$parsed"
+    rm -f "$tmp"
+    return 0
+  fi
+  rm -f "$tmp"
+  return 1
+}
+
 TOOL_OUTPUT="${1:-${TOOL_OUTPUT:-}}"
 EXIT_CODE="${2:-${EXIT_CODE:-}}"
 COMMAND_TEXT="$(hook_json_get '.tool_input.command' '')"
 
 if [[ -z "$TOOL_OUTPUT" ]]; then
-  TOOL_OUTPUT="$(hook_json_get '.tool_output' '')"
+  post_bash_set_tool_output_from_stdin || TOOL_OUTPUT="$(hook_json_get '.tool_output' '')"
 fi
 if [[ -z "$EXIT_CODE" ]]; then
   EXIT_CODE="$(hook_json_get '.exit_code' '')"
@@ -30,6 +62,35 @@ post_bash_output_line_count() {
   printf '%s' "$output" | awk 'END { print NR }'
 }
 
+post_bash_output_byte_count() {
+  local output="$1"
+  printf '%s' "$output" | wc -c | tr -d '[:space:]'
+}
+
+post_bash_sha256() {
+  local output="$1"
+  if command -v shasum >/dev/null 2>&1; then
+    printf '%s' "$output" | shasum -a 256 | awk '{ print $1 }'
+    return
+  fi
+  if command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "$output" | sha256sum | awk '{ print $1 }'
+    return
+  fi
+  printf ''
+}
+
+post_bash_failure_signal() {
+  local output="$1"
+  [[ -n "$output" ]] || return 1
+  printf '%s\n' "$output" | grep -qEi "(^|[[:space:]])(FAIL|FAILED|failed)([[:space:]:,]|$)|Traceback|panic:|fatal:|error.*test"
+}
+
+post_bash_exit_failed() {
+  local exit_code="$1"
+  [[ -n "$exit_code" && "$exit_code" != "0" ]]
+}
+
 post_bash_broad_command() {
   local command_text="$1"
   local trimmed
@@ -63,9 +124,45 @@ if post_bash_broad_command "$COMMAND_TEXT"; then
   recommended_next_tool="codegraph_context"
 fi
 output_line_count="$(post_bash_output_line_count "$TOOL_OUTPUT")"
+raw_output_bytes="$(post_bash_output_byte_count "$TOOL_OUTPUT")"
+failure_signal=false
+if post_bash_failure_signal "$TOOL_OUTPUT"; then
+  failure_signal=true
+fi
+rtk_available=false
+if command -v rtk >/dev/null 2>&1; then
+  rtk_available=true
+fi
+
+LONG_OUTPUT_LINES=200
+LONG_OUTPUT_BYTES=32768
+verbosity_class="inline"
+suggested_runner="inline"
+raw_output_path=""
+raw_output_sha256=""
+
+if post_bash_exit_failed "$EXIT_CODE"; then
+  verbosity_class="failure"
+  suggested_runner="raw"
+elif (( output_line_count >= LONG_OUTPUT_LINES || raw_output_bytes >= LONG_OUTPUT_BYTES )); then
+  verbosity_class="long"
+  if [[ "$broad_command" == "true" && "$rtk_available" == "true" ]]; then
+    suggested_runner="rtk"
+  else
+    suggested_runner="raw"
+  fi
+fi
+
+if [[ "$verbosity_class" != "inline" ]]; then
+  output_dir="$(workflow_runs_dir)/bash-output"
+  mkdir -p "$output_dir"
+  raw_output_sha256="$(post_bash_sha256 "$TOOL_OUTPUT")"
+  raw_output_path="${output_dir}/post-bash-$(date '+%Y%m%dT%H%M%S')-$$-${raw_output_sha256:0:12}.log"
+  printf '%s' "$TOOL_OUTPUT" > "$raw_output_path"
+fi
 
 if [[ "$EXIT_CODE" != "0" ]]; then
-  if echo "$TOOL_OUTPUT" | grep -qEi "(FAIL|failed|error.*test)"; then
+  if [[ "$failure_signal" == "true" ]]; then
     echo "[PostBash] Tests failed. Reminder: failure = rewrite module, not patching."
   fi
 fi
@@ -78,6 +175,16 @@ if [[ -f "$checks_file" ]] && grep -Eq '"source"[[:space:]]*:[[:space:]]*"verify
 fi
 
 mkdir -p "$(dirname "$target_checks_file")"
+if [[ -n "$raw_output_path" ]]; then
+  raw_output_path_json="\"$(hook_json_escape "$raw_output_path")\""
+else
+  raw_output_path_json="null"
+fi
+if [[ -n "$raw_output_sha256" ]]; then
+  raw_output_sha256_json="\"$(hook_json_escape "$raw_output_sha256")\""
+else
+  raw_output_sha256_json="null"
+fi
 cat > "$target_checks_file" <<EOF_CHECKS
 {
   "source": "post-bash",
@@ -86,6 +193,13 @@ cat > "$target_checks_file" <<EOF_CHECKS
   "status": "$([[ "${EXIT_CODE:-0}" = "0" ]] && echo pass || echo fail)",
   "broad_command": ${broad_command},
   "output_line_count": ${output_line_count:-0},
+  "verbosity_class": "$(hook_json_escape "$verbosity_class")",
+  "suggested_runner": "$(hook_json_escape "$suggested_runner")",
+  "raw_output_path": ${raw_output_path_json},
+  "raw_output_bytes": ${raw_output_bytes:-0},
+  "raw_output_sha256": ${raw_output_sha256_json},
+  "failure_signal": ${failure_signal},
+  "rtk_available": ${rtk_available},
   "recommended_next_tool": "$(hook_json_escape "$recommended_next_tool")",
   "generated_at": "$(date '+%Y-%m-%dT%H:%M:%S%z')"
 }