@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/harnesses/kiro/agents/doflow.json

@@ -0,0 +1,58 @@
+{
+  "name": "doflow",
+  "description": "DoFlow main session: spec-driven delivery with lifecycle hooks and specialist dispatch",
+  "prompt": "You are the DoFlow main session. Follow the DoFlow steering files under .kiro/steering (principles, rules, the spec-driven chain) and the skills under .kiro/skills. Dispatch specialist work by role to core-implementer, quality-guardian, spec-analyst, system-architect or research-writer, and keep decisions, verification and records in this session.\n",
+  "tools": [
+    "*"
+  ],
+  "hooks": [
+    {
+      "name": "doflow-pre-implementation-gate",
+      "trigger": "preToolUse",
+      "matcher": "write",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/pre-implement-gate.sh\" ] && printf '%s/.kiro/hooks/pre-implement-gate.sh' \"$root\" || printf '%s/.kiro/hooks/pre-implement-gate.sh' \"$HOME\")\""
+      },
+      "timeout": 10
+    },
+    {
+      "name": "doflow-pre-bash-guard",
+      "trigger": "preToolUse",
+      "matcher": "shell",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/pre-bash-guard.sh\" ] && printf '%s/.kiro/hooks/pre-bash-guard.sh' \"$root\" || printf '%s/.kiro/hooks/pre-bash-guard.sh' \"$HOME\")\""
+      },
+      "timeout": 10
+    },
+    {
+      "name": "doflow-mcp-tool-guard",
+      "trigger": "preToolUse",
+      "matcher": "*",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/mcp-tool-guard.sh\" ] && printf '%s/.kiro/hooks/mcp-tool-guard.sh' \"$root\" || printf '%s/.kiro/hooks/mcp-tool-guard.sh' \"$HOME\")\""
+      },
+      "timeout": 10
+    },
+    {
+      "name": "doflow-session-context",
+      "trigger": "agentSpawn",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/session-start.sh\" ] && printf '%s/.kiro/hooks/session-start.sh' \"$root\" || printf '%s/.kiro/hooks/session-start.sh' \"$HOME\")\""
+      },
+      "timeout": 10
+    },
+    {
+      "name": "doflow-stop-check",
+      "trigger": "stop",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/stop-check.sh\" ] && printf '%s/.kiro/hooks/stop-check.sh' \"$root\" || printf '%s/.kiro/hooks/stop-check.sh' \"$HOME\")\""
+      },
+      "timeout": 30
+    }
+  ]
+}

package/core/harnesses/kiro/hooks/doflow.json

@@ -0,0 +1,53 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "doflow-session-context",
+      "trigger": "SessionStart",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/session-start.sh\" ] && printf '%s/.kiro/hooks/session-start.sh' \"$root\" || printf '%s/.kiro/hooks/session-start.sh' \"$HOME\")\""
+      },
+      "enabled": true
+    },
+    {
+      "name": "doflow-pre-implementation-gate",
+      "trigger": "PreToolUse",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/pre-implement-gate.sh\" ] && printf '%s/.kiro/hooks/pre-implement-gate.sh' \"$root\" || printf '%s/.kiro/hooks/pre-implement-gate.sh' \"$HOME\")\""
+      },
+      "enabled": true
+    },
+    {
+      "name": "doflow-pre-bash-guard",
+      "trigger": "PreToolUse",
+      "matcher": "shell",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/pre-bash-guard.sh\" ] && printf '%s/.kiro/hooks/pre-bash-guard.sh' \"$root\" || printf '%s/.kiro/hooks/pre-bash-guard.sh' \"$HOME\")\""
+      },
+      "enabled": true
+    },
+    {
+      "name": "doflow-mcp-tool-guard",
+      "trigger": "PreToolUse",
+      "matcher": "@mcp",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/mcp-tool-guard.sh\" ] && printf '%s/.kiro/hooks/mcp-tool-guard.sh' \"$root\" || printf '%s/.kiro/hooks/mcp-tool-guard.sh' \"$HOME\")\""
+      },
+      "enabled": true
+    },
+    {
+      "name": "doflow-stop-check",
+      "trigger": "Stop",
+      "action": {
+        "type": "command",
+        "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.kiro/hooks/stop-check.sh\" ] && printf '%s/.kiro/hooks/stop-check.sh' \"$root\" || printf '%s/.kiro/hooks/stop-check.sh' \"$HOME\")\""
+      },
+      "timeout": 30,
+      "enabled": true
+    }
+  ]
+}

package/core/harnesses/kiro/hooks/lib.sh

@@ -0,0 +1,324 @@
+#!/usr/bin/env bash
+# lib.sh — shared constants and helpers for session lifecycle hooks
+#
+# Usage: source "$(dirname "$0")/lib.sh"
+#
+# All hooks must:
+#   1. source this file at the top
+#   2. call require_jq immediately after
+#   3. capture stdin once: INPUT=$(cat)
+#   4. use: json_field "$INPUT" ".field_name"
+#
+# Deployment:
+#   This file is installed by the doflow CLI and overwritten on update — do
+#   not edit an installed copy directly.
+
+set -euo pipefail
+
+# ── State directories ────────────────────────────────────────────────────────
+
+# XDG-compliant, agent-agnostic store shared by Claude Code, Codex, Gemini, etc.
+DOFLOW_HOME="${XDG_CONFIG_HOME:-$HOME/.config}/doflow"
+STATE_DIR="$DOFLOW_HOME/session-env"
+SESSION_DIR="$STATE_DIR/sessions"
+PROJECTS_DIR="$STATE_DIR/projects"
+# shellcheck disable=SC2034  # used by session-start.sh and session-end.sh which source this file
+SESSIONS_LOG="$DOFLOW_HOME/sessions.log"
+
+# Identifies which agent is running. Override via env var for non-Claude agents.
+export DOFLOW_AGENT="${DOFLOW_AGENT:-unknown}"
+
+# ── canonicalize_path ────────────────────────────────────────────────────────
+
+# Print an absolute, symlink-resolved form of $1 when it exists; otherwise
+# print $1 unchanged. Replaces `realpath -e "$1" 2>/dev/null || echo "$1"`,
+# which silently falls back to an uncanonicalized path on stock macOS (BSD
+# realpath has no -e flag). Uses only primitives present on every target
+# (cd, pwd -P, dirname, basename) — no GNU-only flag, no assumed Homebrew
+# coreutils.
+#
+# Hardening notes:
+#   - `CDPATH=` resets CDPATH for the internal `cd` so a user's exported
+#     CDPATH can't redirect it to an unrelated directory of the same name
+#     (and can't make `cd` echo a stray "found via CDPATH" line to stdout).
+#   - `--` guards `dirname`/`basename`/`cd` against a path that begins with
+#     `-` being parsed as an option.
+#   - if the internal `cd` fails for any reason, `||` falls through to the
+#     uncanonicalized-path branch instead of aborting under this file's
+#     `set -e` (matching the old `realpath ... || echo "$1"` degrade path).
+#   - a root-level parent directory ("/") is special-cased so the result
+#     never gets a leading `//`, which POSIX leaves undefined and which
+#     Cygwin/MSYS2 (a DoFlow target platform) interprets as a UNC path.
+canonicalize_path() {
+  local path="$1" dir base
+  if [[ -e "$path" ]] \
+    && dir=$(CDPATH= cd -P -- "$(dirname -- "$path")" 2>/dev/null && pwd -P); then
+    base=$(basename -- "$path")
+    if [[ "$dir" == "/" ]]; then
+      printf '/%s\n' "$base"
+    else
+      printf '%s/%s\n' "$dir" "$base"
+    fi
+  else
+    printf '%s\n' "$path"
+  fi
+}
+
+# ── with_file_lock ───────────────────────────────────────────────────────────
+
+# Internal: break in on $1 (a lock directory) if it looks abandoned — its
+# recorded owner PID is no longer alive, or it's older than 5x the caller's
+# timeout (floored at 30s so short test timeouts don't make legitimately-held
+# locks look stale). Best-effort: mkdir-based locking has no kernel-enforced
+# ownership the way flock did, so a PID can in principle be reused by an
+# unrelated process — the age check is the backstop for that race. The
+# guarded section this protects (session-log trimming) tolerates a rare
+# double-run; this is a soft safety net against a lock leaking forever after
+# its owner is SIGKILLed, not a hard mutual-exclusion guarantee.
+_with_file_lock_break_if_stale() {
+  local lockfile="$1"
+  local timeout_seconds="$2"
+
+  local owner_pid=""
+  [ -f "$lockfile/pid" ] && owner_pid=$(cat "$lockfile/pid" 2>/dev/null || true)
+  local owner_dead=0
+  if [ -n "$owner_pid" ] && ! kill -0 "$owner_pid" 2>/dev/null; then
+    owner_dead=1
+  fi
+
+  local too_old=0
+  local mtime
+  mtime=$(stat -f %m "$lockfile" 2>/dev/null || stat -c %Y "$lockfile" 2>/dev/null || echo "")
+  if [ -n "$mtime" ]; then
+    local max_age=$((timeout_seconds * 5))
+    [ "$max_age" -lt 30 ] && max_age=30
+    if [ $(($(date +%s) - mtime)) -gt "$max_age" ]; then
+      too_old=1
+    fi
+  fi
+
+  if [ "$owner_dead" -eq 1 ] || [ "$too_old" -eq 1 ]; then
+    rm -rf "$lockfile" 2>/dev/null || true
+  fi
+}
+
+# Acquire a lock via atomic `mkdir` (atomic on every filesystem DoFlow runs
+# on, including NTFS via MSYS2) — replaces `flock -x -w 5 200`, which is
+# util-linux-only and confirmed absent entirely on macOS.
+#
+# Usage: call to acquire, run the guarded section in the same shell/subshell,
+# then call again with "release" to release. The lock is also released
+# automatically on exit (normal or error) via an EXIT trap, so a crashed or
+# early-exiting guarded section never leaves the lock held.
+#
+#   if with_file_lock "$LOCK_FILE" 5; then
+#     ...guarded section...
+#     with_file_lock "$LOCK_FILE" release
+#   fi
+#
+# Returns 1 (without acquiring the lock) if timeout_seconds elapses first.
+# A lock whose owner process is gone, or that has sat far longer than the
+# caller's own timeout, is treated as abandoned and broken into rather than
+# waited out (see _with_file_lock_break_if_stale) — a `flock`-held lock was
+# always released by the kernel on process death; a bare `mkdir` lock is not,
+# so this replaces that guarantee instead of silently dropping it.
+#
+# Any EXIT trap the caller already had installed (e.g. its own temp-file
+# cleanup) is preserved: it still runs at real process exit (after this
+# lock's own cleanup), and is still armed as the active EXIT trap after an
+# explicit "release" call — acquiring/releasing this lock never discards it.
+with_file_lock() {
+  local lockfile="$1"
+  local arg="$2"
+
+  if [ "$arg" = "release" ]; then
+    rm -f "$lockfile/pid" 2>/dev/null || true
+    rmdir "$lockfile" 2>/dev/null || true
+    if [ -n "${_DOFLOW_LOCK_PREV_TRAP:-}" ]; then
+      eval "$_DOFLOW_LOCK_PREV_TRAP"
+    else
+      trap - EXIT
+    fi
+    unset _DOFLOW_LOCK_PREV_TRAP
+    return 0
+  fi
+
+  local timeout_seconds="$arg"
+  local waited=0
+  while ! mkdir "$lockfile" 2>/dev/null; do
+    _with_file_lock_break_if_stale "$lockfile" "$timeout_seconds"
+    if [ "$waited" -ge "$timeout_seconds" ]; then
+      return 1
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+  echo "$$" >"$lockfile/pid" 2>/dev/null || true
+
+  # Capture the caller's existing EXIT trap (if any) so releasing this lock
+  # can restore it verbatim, and so real process exit runs both this lock's
+  # cleanup and the caller's original cleanup rather than only the latest
+  # one registered.
+  _DOFLOW_LOCK_PREV_TRAP=$(trap -p EXIT)
+  local prev_cmd=""
+  if [ -n "$_DOFLOW_LOCK_PREV_TRAP" ]; then
+    local prev_body="${_DOFLOW_LOCK_PREV_TRAP#trap -- }"
+    prev_body="${prev_body% EXIT}"
+    eval "prev_cmd=$prev_body"
+  fi
+  # shellcheck disable=SC2064  # intentional immediate expansion of $lockfile/$prev_cmd
+  trap "rm -f '$lockfile/pid' 2>/dev/null; rmdir '$lockfile' 2>/dev/null; $prev_cmd" EXIT
+  return 0
+}
+
+# ── run_with_timeout ─────────────────────────────────────────────────────────
+
+# Run <command...> and terminate it if it exceeds <seconds>. Replaces bare
+# GNU `timeout` calls, which are not installed by default on stock macOS
+# without Homebrew coreutils. When neither a verified-GNU `timeout` nor
+# `gtimeout` (the Homebrew coreutils name) is on PATH, runs the command
+# directly with no enforced budget — a soft safety net, not a correctness
+# requirement.
+#
+# `timeout` is not trusted just because something by that name is on PATH:
+# on Git Bash/MSYS2, PATH can resolve it to Windows' native
+# `System32\timeout.exe`, whose syntax (`timeout /T n`) is incompatible —
+# invoking it the GNU way would fail the command outright instead of just
+# running it unbounded. `timeout --version` is a cheap, side-effect-free way
+# to confirm it's the GNU coreutils build before trusting it (Windows'
+# timeout.exe doesn't understand --version and errors).
+#
+# Usage: run_with_timeout <seconds> -- <command...>
+run_with_timeout() {
+  local seconds="$1"
+  shift
+  if [ "${1:-}" = "--" ]; then
+    shift
+  fi
+
+  if command -v timeout &>/dev/null && timeout --version &>/dev/null; then
+    timeout "$seconds" "$@"
+  elif command -v gtimeout &>/dev/null; then
+    gtimeout "$seconds" "$@"
+  else
+    "$@"
+  fi
+}
+
+# ── cwd_hash ─────────────────────────────────────────────────────────────────
+
+# Derive a stable 16-char hash of an absolute directory path.
+# Used to namespace per-project state (compact summaries, warnings).
+#
+# For a path that is (or resolves to) an existing directory — the case this
+# function exists for — fully resolves it, including a symlink at the path's
+# own leaf component, via `(cd "$1" && pwd -P)`, so equivalent directories
+# always hash identically. Callers that ever pass a non-directory or
+# nonexistent path fall back to the general-purpose canonicalize_path, which
+# — being usable by any file or missing path, not just directories — only
+# resolves symlinks in the parent chain, not the leaf itself.
+#
+# Hash fallback chain: sha256sum -> shasum -a 256 -> cksum (last resort).
+# The cksum branch is normalized via printf '%016x' to the same 16-char
+# hex contract every other branch provides — raw cksum output is a decimal
+# CRC, not hex, and not guaranteed to be 16 characters. Collision risk from
+# the cksum fallback is acceptable here — this is only a cache-key
+# namespace, not security-relevant.
+cwd_hash() {
+  local canonical
+  if [ -d "$1" ]; then
+    canonical=$(cd "$1" && pwd -P)
+  else
+    canonical=$(canonicalize_path "$1")
+  fi
+  if command -v sha256sum &>/dev/null; then
+    echo "$canonical" | sha256sum | cut -c1-16
+  elif command -v shasum &>/dev/null; then
+    echo "$canonical" | shasum -a 256 | cut -c1-16
+  else
+    printf '%016x\n' "$(echo "$canonical" | cksum | cut -d' ' -f1)"
+  fi
+}
+
+# ── Directory helpers ─────────────────────────────────────────────────────────
+
+# Create and return the session-scoped state directory for a given session_id.
+# Safe to call multiple times (mkdir -p is idempotent).
+ensure_session_dir() {
+  local session_id="$1"
+  mkdir -p "$SESSION_DIR/$session_id"
+  echo "$SESSION_DIR/$session_id"
+}
+
+# Create and return the project-scoped state directory for a given cwd.
+# Shared across all sessions in the same directory.
+ensure_project_dir() {
+  local cwd="$1"
+  local hash
+  hash=$(cwd_hash "$cwd")
+  mkdir -p "$PROJECTS_DIR/$hash"
+  echo "$PROJECTS_DIR/$hash"
+}
+
+# ── JSON helpers ──────────────────────────────────────────────────────────────
+
+# Extract a field from a JSON string.
+# Usage: json_field "$INPUT" ".field_name"
+# Returns empty string if field is null or jq fails.
+json_field() {
+  local json="$1"
+  local query="$2"
+  echo "$json" | jq -r "$query // empty" 2>/dev/null || echo ""
+}
+
+# ── Dependency guard ──────────────────────────────────────────────────────────
+
+# Verify jq is available at runtime. If absent, emit a diagnostic to stderr
+# and exit 0 (never block the harness — degraded operation is preferable to failure).
+require_jq() {
+  if ! command -v jq &>/dev/null; then
+    echo "[hooks] jq not found — install jq to enable session lifecycle hooks (apt install jq / brew install jq)" >&2
+    exit 0
+  fi
+}
+
+# ── kiro_bridge_payload ───────────────────────────────────────────────────────
+
+# Read a Kiro hook payload on stdin and print the canonical payload the shared policies read.
+# The shared policies understand Claude-style names; Kiro differs in four places, mapped here so
+# the policies stay untouched:
+#   - session_id: absent from some Kiro events; taken from $KIRO_SESSION_ID when empty
+#   - tool_name:  write|fs_write|fs_append|str_replace|delete_file|write_file -> Write
+#                 (tool_input.path also copied to tool_input.file_path),
+#                 shell|execute_bash|execute_cmd|execute_pwsh -> Bash,
+#                 @server/tool -> mcp__server__tool. Kiro CLI V3 already sanitizes MCP tool IDs to
+#                 mcp_<server>_<tool>; those pass through unchanged, because the shared
+#                 mcp-tool-guard matches the single-underscore mcp_ prefix case-insensitively.
+#   - assistant_response -> last_assistant_message (stop event)
+# Any other name passes through unchanged, so an unmapped tool fails open as it does without the
+# bridge. When jq is missing or rejects the payload, the original payload is printed unchanged.
+kiro_bridge_payload() {
+  local payload rewritten
+  payload=$(cat)
+  if command -v jq &>/dev/null \
+    && rewritten=$(printf '%s' "$payload" | jq -c --arg sid "${KIRO_SESSION_ID:-}" '
+      (if ((.session_id // "") == "") and ($sid != "") then .session_id = $sid else . end)
+      | (.tool_name // "") as $t
+      | (if ($t == "write" or $t == "fs_write" or $t == "fs_append" or $t == "str_replace" or $t == "delete_file" or $t == "write_file") then
+           .tool_name = "Write"
+           | (if ((.tool_input | type) == "object") and (.tool_input.path != null) and (.tool_input.file_path == null)
+              then .tool_input.file_path = .tool_input.path else . end)
+         elif ($t == "shell" or $t == "execute_bash" or $t == "execute_cmd" or $t == "execute_pwsh") then
+           .tool_name = "Bash"
+         elif ($t | startswith("@")) then
+           .tool_name = ("mcp__" + ($t[1:] | gsub("/"; "__")))
+         else . end)
+      | (if (.assistant_response != null) and (.last_assistant_message == null)
+         then .last_assistant_message = .assistant_response else . end)
+    ' 2>/dev/null) \
+    && [ -n "$rewritten" ]; then
+    printf '%s\n' "$rewritten"
+  else
+    printf '%s\n' "$payload"
+  fi
+}

package/core/harnesses/kiro/hooks/mcp-tool-guard.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Kiro adapter: reuse the canonical mcp-tool-guard policy with Kiro attribution.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-kiro}"
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+# Translate Kiro's payload (tool names, KIRO_SESSION_ID, assistant_response) to the canonical one.
+payload=$(kiro_bridge_payload)
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/mcp-tool-guard.sh" <<<"$payload"

package/core/harnesses/kiro/hooks/pre-bash-guard.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Kiro adapter: reuse the canonical pre-bash-guard policy with Kiro attribution.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-kiro}"
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+# Translate Kiro's payload (tool names, KIRO_SESSION_ID, assistant_response) to the canonical one.
+payload=$(kiro_bridge_payload)
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/pre-bash-guard.sh" <<<"$payload"

package/core/harnesses/kiro/hooks/pre-implement-gate.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Kiro adapter: reuse the canonical pre-implementation-gate policy with Kiro attribution.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-kiro}"
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+# Translate Kiro's payload (tool names, KIRO_SESSION_ID, assistant_response) to the canonical one.
+payload=$(kiro_bridge_payload)
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/pre-implementation-gate.sh" <<<"$payload"

package/core/harnesses/kiro/hooks/session-start.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Kiro adapter: reuse the canonical session-context policy with Kiro attribution.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-kiro}"
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+# Translate Kiro's payload (tool names, KIRO_SESSION_ID, assistant_response) to the canonical one.
+payload=$(kiro_bridge_payload)
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/session-context.sh" <<<"$payload"

package/core/harnesses/kiro/hooks/stop-check.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Kiro adapter: run the canonical stop-check policy and translate its verdict to the Kiro engine.
+#
+# The policy exits 2 to deny the stop. Kiro engines read a Stop hook differently:
+#   - Kiro CLI V3 / IDE (payload carries session_id): exit 0 finishes the turn; exit 0 with stdout
+#     JSON {"decision":"block","reason":"..."} starts another turn with that reason; exit 1 also
+#     starts another turn; other codes finish without forwarding output. Exit 2 does NOT block.
+#     So a policy deny becomes the JSON block on stdout with exit 0.
+#   - Kiro CLI 2.x (payload has no session_id): exit 0 succeeded, any other code shows stderr to the
+#     user as a warning. A policy deny is passed through as stderr with exit 2.
+# Every other policy outcome exits 0, never 1: V3 treats exit 1 as "continue another turn".
+# The policy blocks a given message once, so the continuation turn is not blocked again.
+# Docs: https://kiro.dev/docs/hooks/types/ , https://kiro.dev/docs/cli/v3/hooks-migration/
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-kiro}"
+here="$(dirname "$0")"
+# shellcheck source=lib.sh
+source "$here/lib.sh"
+set +e # lib.sh enables errexit; the policy exit code is handled explicitly below
+
+raw=$(cat)
+# Translate Kiro's payload (tool names, KIRO_SESSION_ID, assistant_response) to the canonical one.
+payload=$(kiro_bridge_payload <<<"$raw")
+
+# V3 and the IDE send session_id in the payload; 2.x does not (the bridge injects it from the env).
+raw_sid=""
+if command -v jq >/dev/null 2>&1; then
+  raw_sid=$(printf '%s' "$raw" | jq -r '.session_id // empty' 2>/dev/null) || raw_sid=""
+fi
+
+# Capture the policy's stderr (stdout discarded) and its exit code without a temp file.
+errtext=$(bash "$here/../../.doflow/shared/hooks/policies/stop-check.sh" <<<"$payload" 2>&1 >/dev/null)
+rc=$?
+
+if [ "$rc" -eq 2 ]; then
+  if [ -n "$raw_sid" ] && command -v jq >/dev/null 2>&1; then
+    jq -n --arg reason "$errtext" '{decision: "block", reason: $reason}'
+    exit 0
+  fi
+  printf '%s\n' "$errtext" >&2
+  exit 2
+fi
+exit 0

package/core/harnesses/shared/hooks/ENVELOPE_MIGRATION.md

@@ -0,0 +1,39 @@
+# The normalized hook envelope, and each front door's share of the migration
+
+`policies/pre-implementation-gate.sh` prefers one normalized event over every native payload
+shape (review R7):
+
+```json
+{"doflow_event": {"operation": "edit", "paths": ["src/a.js"], "projectRoot": "/repo", "taskId": "001-auth"}}
+```
+
+A front door that sends this envelope needs none of the policy's legacy union parsing — the four
+tool-name spellings, five file-path field names, and Codex `apply_patch` diff extraction exist
+only for front doors still forwarding raw native payloads. Each adapter that adopts the envelope
+retires its share of that union; when the last one does, the union decoder is deleted.
+
+## Which native event each front door decodes
+
+Per-harness pre-edit event names, from the hook-event inventory compiled 2026-08-28 against each
+tool's official docs (cross-checked against tool source where docs were incomplete):
+
+| Harness | Native pre-edit event | Notes for the decoder |
+|---|---|---|
+| Claude Code | `PreToolUse` | `tool_name` Edit/Write/MultiEdit; `tool_input.file_path` |
+| Codex | `PreToolUse` | `apply_patch` carries paths inside a unified diff under `tool_input.command` — the ONE decoder that must parse patch text |
+| Gemini CLI | `BeforeTool` | also offers `BeforeToolSelection` (pre-selection restriction), which the gate does not use |
+| GitHub Copilot | `preToolUse` | camelCase event names; `permissionRequest` is CLI-only, not fired in the cloud agent |
+| OpenCode | `tool.execute.before` | a pluggable hook method, not a sub-event of the generic `event` hook |
+| Pi | `tool_execution_start` | Pi's 36-event surface also exposes `tool_call`; the execution-start event is the gate's anchor |
+| Antigravity | `PreToolUse` | 5-event surface, `hooks.json` + stdin/stdout JSON contract |
+
+`operation` is `"edit"` for anything that writes source; a decoder maps its native create/replace/
+patch tool vocabulary down to that one word. Non-edit operations may be sent (the policy allows
+them through), but sending nothing for a non-edit tool is equally correct and cheaper.
+
+## Rules that hold on both paths
+
+- The envelope, when present, **outranks** any native fields beside it.
+- Root resolution: `DOFLOW_PROJECT_DIR` beats the envelope's `projectRoot` beats git discovery.
+- The policy remains a pure file-existence gate (FR-012): the envelope changes how it hears about
+  an edit, never what it decides, and it must never consult readiness or evidence state.