@khoavu882/doflow 2.0.0 → 2.0.2

package/README.md

@@ -28,7 +28,7 @@ flowchart LR
 |---|---|
 | Repeatable delivery work | 13 skills, including `/do-brainstorm`, `/do-plan`, `/do-test`, and `/do-code-review` |
 | Specialist review | 7 agents — `spec-analyst`, `system-architect`, `delivery-lead`, `core-implementer`, `quality-guardian`, `reviewer`, `research-writer` |
-| Safer automation | Claude hooks block destructive commands and unfinished implementation stubs |
+| Safer automation | Hooks advise when an edit starts before the spec exists and when work looks unfinished; the runtime enforces order and readiness at the stage handoff |
 | Shared standards | Rules for safety, workflow, quality, and clarification across supported tools |
 | Session continuity | Claude and Codex hooks capture lightweight Git context and compact-session summaries and deliver them on a session's first prompt |
 
@@ -125,10 +125,9 @@ Kiro's hooks are not in Kiro v3's
 untrusted-workspace exclusion list; an untrusted workspace asks before every shell command, and
 whether that covers hook commands is undocumented. Copilot CLI documents hooks, settings, and a
 plugin marketplace upstream; DoFlow still installs none of those there. OpenCode and Pi
-standard-adopt `AGENTS.md` for seamless zero-drift rule projection. See `docs/capability-map.md`
-and the [installation matrix](docs/setup.md#what-gets-installed) for the exact mapping.
+standard-adopt `AGENTS.md` for seamless zero-drift rule projection. See the
+[installation matrix](docs/setup.md#what-gets-installed) for the exact mapping.
 
 ## Contributing
 
-The repository layout and deployment model are documented in the [Architecture guide](docs/architecture.md).
-Run `npm test` and the shell suites described there before submitting changes.
+Run `npm test` and the shell suites under `test/` before submitting changes.

package/bin/doflow.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // doflow — DoFlow config installer CLI. Argument parsing, the installer command table and every
-// command handler live in src/cli/ (see docs/architecture.md); this file is only the forwarder
+// command handler live in src/cli/; this file is only the forwarder
 // so the `doflow` binary path and the doflow-run dispatcher seam
 // (core/shared/scripts/doflow/bin/doflow-run, which execs `node <repoRoot>/bin/doflow.js`)
 // keep resolving to this exact location.

package/core/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "doflow",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Reusable engineering workflows, quality gates, and specialist guidance for Claude Code.",
   "author": {
     "name": "DoFlow"

package/core/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "doflow",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Reusable engineering workflows, quality gates, and specialist guidance for Codex.",
   "author": {
     "name": "DoFlow",

package/core/.plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "doflow",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Reusable engineering workflows, quality gates, and specialist guidance for GitHub Copilot CLI.",
   "author": {
     "name": "DoFlow",

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

@@ -3,7 +3,10 @@
 set -uo pipefail
 export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
 if ! . "$(dirname "$0")/../../.doflow/shared/hooks/bridge/bridge.sh" 2>/dev/null; then
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t claude"}}'
+  # D1: a missing bridge allows. Only DOFLOW_FAULT_PROFILE=strict-1, a person's opt-in, denies.
+  if [ "${DOFLOW_FAULT_PROFILE:-}" = strict-1 ]; then
+    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t claude"}}'
+  fi
   exit 0
 fi
 doflow_bridge claude PreToolUse mcp-tool-guard

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

@@ -3,7 +3,10 @@
 set -uo pipefail
 export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
 if ! . "$(dirname "$0")/../../.doflow/shared/hooks/bridge/bridge.sh" 2>/dev/null; then
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t claude"}}'
+  # D1: a missing bridge allows. Only DOFLOW_FAULT_PROFILE=strict-1, a person's opt-in, denies.
+  if [ "${DOFLOW_FAULT_PROFILE:-}" = strict-1 ]; then
+    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t claude"}}'
+  fi
   exit 0
 fi
 doflow_bridge claude PreToolUse pre-implementation-gate

package/core/harnesses/claude/hooks/session-end.sh

@@ -5,7 +5,7 @@ case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; th
 # Runs when Claude Code closes a session. Responsibilities:
 #   1. Append END marker to sessions.log
 #   2. Write uncommitted-warning.txt if the working tree is dirty
-#   3. Delete the session-scoped state directory (cleanup)
+#   3. Delete the session-scoped state directory (cleanup) and the main session's model observation
 #   4. Trim sessions.log to last 500 lines (lock-guarded for parallel safety)
 #
 # Multi-session safe: with_file_lock (lib.sh) prevents concurrent sessions from
@@ -81,6 +81,26 @@ if [[ -n "$SESSION_ID" ]]; then
   rm -rf "$SESSION_PATH" 2>/dev/null || true
 fi
 
+# ── 3b. Remove this main session's model observation (120 IC-005) ─────────────
+
+# observe-model.sh keys the file by the first 16 hex of sha256(session id), under primary/<cwd_hash>/<harness>/.
+# Only the ending main session's own file goes: other sessions, worker observations and a missing file are left
+# alone, and a failure here changes nothing (SessionEnd is fire-and-forget).
+forget_model_observation() {
+  local key="" cwd="${CWD:-}" file=""
+  [[ -n "$SESSION_ID" ]] || return 0
+  [[ "$(doflow_session_role || echo main)" == "main" ]] || return 0
+  if command -v sha256sum >/dev/null 2>&1; then key=$(printf '%s' "$SESSION_ID" | sha256sum | cut -c1-16)
+  elif command -v shasum >/dev/null 2>&1; then key=$(printf '%s' "$SESSION_ID" | shasum -a 256 | cut -c1-16)
+  else return 0; fi
+  [[ $key =~ ^[0-9a-f]{16}$ ]] || return 0
+  case "$cwd" in /*) ;; *) cwd=$PWD ;; esac
+  file="$STATE_DIR/primary/$(cwd_hash "$cwd")/claude/$key.json"
+  if [[ -f "$file" && ! -L "$file" ]]; then rm -f "$file"; fi
+  return 0
+}
+forget_model_observation 2>/dev/null || true
+
 start_storage_upkeep
 
 # ── 4. Trim sessions.log (lock-guarded) ───────────────────────────────────────

package/core/harnesses/claude/settings/settings.json

@@ -21,6 +21,14 @@
       "Bash(git push --force*:*)",
       "Bash(git reset --hard*:*)",
       "Bash(git clean -fd*:*)"
+    ],
+    "ask": [
+      "Bash(git push:*)",
+      "Bash(git tag:*)",
+      "Bash(git * push:*)",
+      "Bash(git * tag:*)",
+      "Bash(git * push)",
+      "Bash(git * tag)"
     ]
   },
   "alwaysThinkingEnabled": true,
@@ -87,15 +95,6 @@
       }
     ],
     "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "~/.claude/hooks/pre-bash-guard.sh"
-          }
-        ]
-      },
       {
         "matcher": "mcp__.*",
         "hooks": [

package/core/harnesses/codex/hooks/hooks.json

@@ -43,16 +43,6 @@
       }
     ],
     "PreToolUse": [
-      {
-        "matcher": "^Bash$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/pre-bash-guard.sh\" ] && printf '%s/.codex/hooks/pre-bash-guard.sh' \"$root\" || printf '%s/hooks/pre-bash-guard.sh' \"${CODEX_HOME:-$HOME/.codex}\")\"",
-            "statusMessage": "Checking command safety"
-          }
-        ]
-      },
       {
         "matcher": "^mcp__.*",
         "hooks": [

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

@@ -3,7 +3,10 @@
 set -uo pipefail
 export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
 if ! . "$(dirname "$0")/../../.doflow/shared/hooks/bridge/bridge.sh" 2>/dev/null; then
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t codex"}}'
+  # D1: a missing bridge allows. Only DOFLOW_FAULT_PROFILE=strict-1, a person's opt-in, denies.
+  if [ "${DOFLOW_FAULT_PROFILE:-}" = strict-1 ]; then
+    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t codex"}}'
+  fi
   exit 0
 fi
 doflow_bridge codex PreToolUse mcp-tool-guard

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

@@ -3,7 +3,10 @@
 set -uo pipefail
 export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
 if ! . "$(dirname "$0")/../../.doflow/shared/hooks/bridge/bridge.sh" 2>/dev/null; then
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t codex"}}'
+  # D1: a missing bridge allows. Only DOFLOW_FAULT_PROFILE=strict-1, a person's opt-in, denies.
+  if [ "${DOFLOW_FAULT_PROFILE:-}" = strict-1 ]; then
+    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t codex"}}'
+  fi
   exit 0
 fi
 doflow_bridge codex PreToolUse pre-implementation-gate

package/core/harnesses/codex/hooks/session-end.impl.sh

@@ -5,7 +5,7 @@ case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; th
 # Runs when Claude Code closes a session. Responsibilities:
 #   1. Append END marker to sessions.log
 #   2. Write uncommitted-warning.txt if the working tree is dirty
-#   3. Delete the session-scoped state directory (cleanup)
+#   3. Delete the session-scoped state directory (cleanup) and the main session's model observation
 #   4. Trim sessions.log to last 500 lines (lock-guarded for parallel safety,
 #      via lib.sh's portable with_file_lock — no flock dependency)
 #
@@ -82,6 +82,26 @@ if [[ -n "$SESSION_ID" ]]; then
   rm -rf "$SESSION_PATH" 2>/dev/null || true
 fi
 
+# ── 3b. Remove this main session's model observation (120 IC-005) ─────────────
+
+# observe-model.sh keys the file by the first 16 hex of sha256(session id), under primary/<cwd_hash>/<harness>/.
+# Only the ending main session's own file goes: other sessions, worker observations and a missing file are left
+# alone, and a failure here changes nothing (SessionEnd is fire-and-forget).
+forget_model_observation() {
+  local key="" cwd="${CWD:-}" file=""
+  [[ -n "$SESSION_ID" ]] || return 0
+  [[ "$(doflow_session_role || echo main)" == "main" ]] || return 0
+  if command -v sha256sum >/dev/null 2>&1; then key=$(printf '%s' "$SESSION_ID" | sha256sum | cut -c1-16)
+  elif command -v shasum >/dev/null 2>&1; then key=$(printf '%s' "$SESSION_ID" | shasum -a 256 | cut -c1-16)
+  else return 0; fi
+  [[ $key =~ ^[0-9a-f]{16}$ ]] || return 0
+  case "$cwd" in /*) ;; *) cwd=$PWD ;; esac
+  file="$STATE_DIR/primary/$(cwd_hash "$cwd")/codex/$key.json"
+  if [[ -f "$file" && ! -L "$file" ]]; then rm -f "$file"; fi
+  return 0
+}
+forget_model_observation 2>/dev/null || true
+
 start_storage_upkeep
 
 # ── 4. Trim sessions.log (lock-guarded) ───────────────────────────────────────

package/core/harnesses/copilot/hooks/doflow-lib.sh

@@ -69,8 +69,8 @@ copilot_bridge_payload() {
 }
 
 # copilot_front_door <script-dir> <event> <policy> <fail>: run one shared policy through the bridge.
-# <fail> is `deny` for a pre-tool policy (a missing bridge denies the tool call, as Copilot's
-# preToolUse hooks are fail-closed on a non-zero exit anyway) or `open` for every other event.
+# <fail> is `deny` for a pre-tool policy (a missing bridge denies the tool call only under strict-1)
+# or `open` for every other event.
 copilot_front_door() {
   local dir="$1" event="$2" policy="$3" fail="${4:-open}" raw payload bridge status=0
   raw=$(cat)
@@ -83,7 +83,8 @@ copilot_front_door() {
   # User hooks under a custom $COPILOT_HOME sit beside no .doflow; the bridge is then in $HOME/.doflow.
   [ -f "$bridge" ] || bridge="${HOME:-}/.doflow/shared/hooks/bridge/bridge.sh"
   if [ ! -f "$bridge" ] || ! . "$bridge" 2>/dev/null; then
-    if [ "$fail" = deny ]; then
+    # D1: a missing bridge allows. Only DOFLOW_FAULT_PROFILE=strict-1, a person's opt-in, denies a pre-tool call.
+    if [ "$fail" = deny ] && [ "${DOFLOW_FAULT_PROFILE:-}" = strict-1 ]; then
       printf '%s\n' '{"permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t copilot"}'
     fi
     return 0

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

@@ -16,12 +16,6 @@
         "cwd": ".",
         "timeoutSec": 20
       },
-      {
-        "type": "command",
-        "bash": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.github/hooks/doflow-pre-bash-guard.sh\" ] && printf '%s/.github/hooks/doflow-pre-bash-guard.sh' \"$root\" || printf '%s/hooks/doflow-pre-bash-guard.sh' \"${COPILOT_HOME:-$HOME/.copilot}\")\"",
-        "cwd": ".",
-        "timeoutSec": 20
-      },
       {
         "type": "command",
         "bash": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.github/hooks/doflow-mcp-tool-guard.sh\" ] && printf '%s/.github/hooks/doflow-mcp-tool-guard.sh' \"$root\" || printf '%s/hooks/doflow-mcp-tool-guard.sh' \"${COPILOT_HOME:-$HOME/.copilot}\")\"",

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

@@ -16,16 +16,6 @@
       },
       "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",

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

@@ -19,16 +19,6 @@
       },
       "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",

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

@@ -11,11 +11,15 @@ payload=$(kiro_bridge_payload <<<"$raw")
 event="PreToolUse"
 if command -v jq >/dev/null 2>&1; then event=$(printf '%s' "$raw" | jq -r '.hook_event_name // "PreToolUse"' 2>/dev/null) || event="PreToolUse"; fi
 bridge="$here/../../.doflow/shared/hooks/bridge/bridge.sh"
-if [ ! -f "$bridge" ]; then
+# D1: a missing bridge allows with a warning on stderr. Only strict-1, a person's opt-in, blocks.
+bridge_missing=0
+[ -f "$bridge" ] || bridge_missing=1
+if [ "$bridge_missing" -eq 0 ]; then . "$bridge" 2>/dev/null || bridge_missing=1; fi
+if [ "$bridge_missing" -eq 1 ]; then
   printf '%s\n' '[doflow] shared hooks lack the bridge; run: doflow update -t kiro' >&2
-  exit 2
+  if [ "${DOFLOW_FAULT_PROFILE:-}" = strict-1 ]; then exit 2; fi
+  exit 0
 fi
-. "$bridge" 2>/dev/null || { printf '%s\n' '[doflow] shared hooks lack the bridge; run: doflow update -t kiro' >&2; exit 2; }
 if doflow_bridge kiro "$event" mcp-tool-guard <<<"$payload"; then
   status=0
 else

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

@@ -11,11 +11,15 @@ payload=$(kiro_bridge_payload <<<"$raw")
 event="PreToolUse"
 if command -v jq >/dev/null 2>&1; then event=$(printf '%s' "$raw" | jq -r '.hook_event_name // "PreToolUse"' 2>/dev/null) || event="PreToolUse"; fi
 bridge="$here/../../.doflow/shared/hooks/bridge/bridge.sh"
-if [ ! -f "$bridge" ]; then
+# D1: a missing bridge allows with a warning on stderr. Only strict-1, a person's opt-in, blocks.
+bridge_missing=0
+[ -f "$bridge" ] || bridge_missing=1
+if [ "$bridge_missing" -eq 0 ]; then . "$bridge" 2>/dev/null || bridge_missing=1; fi
+if [ "$bridge_missing" -eq 1 ]; then
   printf '%s\n' '[doflow] shared hooks lack the bridge; run: doflow update -t kiro' >&2
-  exit 2
+  if [ "${DOFLOW_FAULT_PROFILE:-}" = strict-1 ]; then exit 2; fi
+  exit 0
 fi
-. "$bridge" 2>/dev/null || { printf '%s\n' '[doflow] shared hooks lack the bridge; run: doflow update -t kiro' >&2; exit 2; }
 if doflow_bridge kiro "$event" pre-implementation-gate <<<"$payload"; then
   status=0
 else

package/core/harnesses/pi/extensions/doflow-guard.js

@@ -6,7 +6,6 @@ import { fileURLToPath } from 'node:url';
 const BRIDGE = new URL('../../shared/hooks/bridge/bridge.sh', import.meta.url);
 const ROUTES = [
   { tools: ['edit', 'write'], policy: 'pre-implementation-gate' },
-  { tools: ['bash'], policy: 'pre-bash-guard' },
 ];
 const LIMIT = 1024 * 1024;
 const TIMEOUT_MS = 5000;
@@ -136,7 +135,9 @@ export default function (pi) {
       if (profile !== 'compat-1' && profile !== 'strict-1') captureFailure(policy, 'fault-profile-unknown');
       if (!existsSync(BRIDGE)) {
         captureFailure(policy, 'bridge-missing');
-        return { block: true, reason: '[doflow] shared hooks lack the bridge; run: doflow update -t pi' };
+        // D1: a missing bridge allows (the failure is recorded for doctor); only strict-1, a person's opt-in, blocks.
+        if (profile === 'strict-1') return { block: true, reason: '[doflow] shared hooks lack the bridge; run: doflow update -t pi' };
+        return undefined;
       }
       let model;
       try {

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

@@ -36,7 +36,7 @@ them through), but sending nothing for a non-edit tool is equally correct and ch
 ## Version and mixed-install rules
 
 - A missing envelope or version, empty or non-object input, or a missing `contract.sh` is out of
-  step. The gate, bash guard and MCP guard deny with `DoFlow hooks out of step; run: doflow update
+  step. The gate and MCP guard deny with `DoFlow hooks out of step; run: doflow update
   -t <harness>`; Stop and context policies exit silently, except the prompt hook emits its `{}`
   no-op. Other envelope versions are unsupported and policies evaluate nothing.
 - If a door cannot load `bridge/bridge.sh`, it renders its fixed native out-of-step response. The

package/core/harnesses/shared/hooks/adapters/antigravity.js

@@ -20,7 +20,7 @@
  *
  * SessionStart and PostToolUse have no dedicated Antigravity-native shim in
  * src/adapters/antigravity/index.js's live projection. No Phase A canonical policy owns PostToolUse today (only
- * session-context, pre-implementation-gate, mcp-tool-guard, stop-check, pre-bash-guard exist),
+ * session-context, pre-implementation-gate, mcp-tool-guard, stop-check exist),
  * so its native shape is an ack passthrough either way.
  */
 

package/core/harnesses/shared/hooks/bridge/bridge.sh

@@ -42,31 +42,19 @@ doflow_bridge_effect() {
     profile=compat-1; doflow_bridge_failure "$policy" fault-profile-unknown
   fi
   DF_BRIDGE_PROFILE="$profile"
-  case "$policy" in pre-implementation-gate|pre-bash-guard|mcp-tool-guard|stop-check) block=1;; esac
+  case "$policy" in pre-implementation-gate|mcp-tool-guard|stop-check) block=1;; esac
   DF_BRIDGE_EFFECT=proceed
   if [ "$outcome" = deny ]; then DF_BRIDGE_EFFECT=block
   elif [ "$profile" = strict-1 ] && [ "$block" -eq 1 ] && [ "$policy" != stop-check ] && { [ "$outcome" = error ] || [ "$outcome" = unsupported ] || [ "$DF_BRIDGE_CODE" = bridge-spawn ] || [ "$DF_BRIDGE_CODE" = envelope-encode ]; }; then DF_BRIDGE_EFFECT=block
-  elif [ "$outcome" = error ] && [ "$DF_BRIDGE_CODE" != bridge-spawn ] && [ -n "$DF_BRIDGE_POINT" ] && [ "$profile" = compat-1 ]; then
-    case "$harness:$event" in
-      claude:PreToolUse|codex:PreToolUse|copilot:PreToolUse|pi:tool_call) DF_BRIDGE_EFFECT=block ;;
-      antigravity:PreToolUse|antigravity:Stop) case "$DF_BRIDGE_CODE" in signal-*) DF_BRIDGE_EFFECT=proceed;; *) DF_BRIDGE_EFFECT=block;; esac ;;
-      kiro:PreToolUse) [ "$DF_BRIDGE_CODE" = exit-2-unmarked ] && DF_BRIDGE_EFFECT=block ;;
-      claude:Stop) [ "$DF_BRIDGE_CODE" = exit-2-unmarked ] && DF_BRIDGE_EFFECT=block ;;
-      codex:Stop|codex:stop|copilot:Stop|kiro:Stop|kiro:stop) [ "$DF_BRIDGE_CODE" = exit-2-unmarked ] && DF_BRIDGE_EFFECT=block || DF_BRIDGE_EFFECT=proceed ;;
-    esac
-  fi
-  # Copilot CLI: a guarded preToolUse policy that errors or cannot decide (jq or the policy script
-  # missing, an edit with no decodable target) denies whatever the fault profile; only a policy that
-  # answered allow or advisory lets the call through. Copilot-only: every other harness keeps the
-  # profile rules above byte for byte.
-  if [ "$block" -eq 1 ] && [ "$DF_BRIDGE_EFFECT" = proceed ] && [ "$harness:$event" = copilot:PreToolUse ] && [ "$policy" != stop-check ]; then
-    case "$outcome" in error|unsupported) DF_BRIDGE_EFFECT=block ;; esac
   fi
+  # D1 (advise-only hooks): under compat-1 a faulting policy never blocks, on any harness. Only a policy
+  # that answered deny (mcp-tool-guard blocked-pattern) blocks, and strict-1, a person's opt-in, blocks
+  # on a fault of a blocking policy (above).
 }
 
 doflow_bridge_drops_tool_streams() {
   case "$1" in
-    pre-implementation-gate|pre-bash-guard|mcp-tool-guard) ;;
+    pre-implementation-gate|mcp-tool-guard) ;;
     *) return 1 ;;
   esac
   case "$2:$3" in
@@ -77,7 +65,7 @@ doflow_bridge_drops_tool_streams() {
 
 doflow_bridge_drops_tool_stderr() {
   case "$1:$2:$3" in
-    pre-implementation-gate:kiro:PreToolUse|pre-bash-guard:kiro:PreToolUse|mcp-tool-guard:kiro:PreToolUse) return 1 ;;
+    pre-implementation-gate:kiro:PreToolUse|mcp-tool-guard:kiro:PreToolUse) return 1 ;;
   esac
   doflow_bridge_drops_tool_streams "$1" "$2" "$3"
 }
@@ -93,7 +81,7 @@ doflow_bridge_hook_line() {
   [ "${DOFLOW_TELEMETRY:-}" != off ] || return 0
   case "$DF_TUPLE" in ''|'{"dft":1}') return 0 ;; esac
   case "$1:$3:$2" in
-    claude:pre-bash-guard:PreToolUse|codex:pre-bash-guard:PreToolUse|kiro:pre-bash-guard:PreToolUse|antigravity:pre-bash-guard:PreToolUse|pi:pre-bash-guard:tool_call|claude:user-prompt-submit:UserPromptSubmit|codex:user-prompt-submit:UserPromptSubmit) ;;
+    claude:user-prompt-submit:UserPromptSubmit|codex:user-prompt-submit:UserPromptSubmit) ;;
     *) return 0 ;;
   esac
   if [ -n "${DOFLOW_CONFIG_DIR:-}" ]; then
@@ -145,7 +133,7 @@ doflow_bridge_hook_line() {
 }
 
 doflow_bridge() {
-  local harness="${1:-}" event="${2:-}" policy="${3:-}" response_event="" emit="native" payload="" encoded="" policy_path="" captured="" err="" code=0 policy_code=0 record="" emit_record="" reason="" decision_reason="" stdout="" status=0 decision="" line="" spawn_failed=0 encode_failed=0 _df_t0=""
+  local harness="${1:-}" event="${2:-}" policy="${3:-}" response_event="" emit="native" payload="" encoded="" policy_path="" captured="" err="" code=0 policy_code=0 record="" emit_record="" reason="" decision_reason="" stdout="" status=0 decision="" advice="" out_of_step=0 line="" spawn_failed=0 encode_failed=0 _df_t0=""
   DF_TUPLE=""
   if [ "${BASH_VERSINFO[0]:-0}" -ge 5 ] 2>/dev/null; then _df_t0=${EPOCHREALTIME:-}; fi
   . "$_DOFLOW_BRIDGE_DIR/respond.sh"
@@ -181,12 +169,24 @@ doflow_bridge() {
     doflow_bridge_failure "$policy" dependency-missing:jq
   fi
   case "$policy" in
-    pre-implementation-gate|pre-bash-guard|mcp-tool-guard|stop-check|session-context|user-prompt-submit|subagent-audit) ;;
+    pre-implementation-gate|mcp-tool-guard|stop-check|session-context|user-prompt-submit|subagent-audit) ;;
     *) spawn_failed=1 ;;
   esac
   policy_path="$_DOFLOW_BRIDGE_DIR/../policies/$policy.sh"
-  if [ "$spawn_failed" -eq 1 ] || [ ! -f "$policy_path" ]; then
+  if [ "$spawn_failed" -eq 1 ] || [ ! -f "$policy_path" ] || [ ! -f "$_DOFLOW_BRIDGE_DIR/../policies/contract.sh" ]; then
     code=127; err=""; spawn_failed=1
+    # Without contract.sh no policy can run. The gate and the tool guard still say so: the one
+    # out-of-step line goes out as advice below, and the fault is recorded as bridge-spawn.
+    case "$policy" in
+      pre-implementation-gate|mcp-tool-guard)
+        if [ -f "$policy_path" ] && [ ! -f "$_DOFLOW_BRIDGE_DIR/../policies/contract.sh" ]; then
+          out_of_step="${DOFLOW_AGENT:-$harness}"
+          if [[ "$out_of_step" =~ ^[a-z]+$ ]]; then err="[$policy] DoFlow hooks out of step; run: doflow update -t $out_of_step"$'\n'
+          else err="[$policy] DoFlow hooks out of step; run: doflow update"$'\n'; fi
+          out_of_step=1
+        fi
+        ;;
+    esac
   else
     if [ "$emit" = decision ] || doflow_bridge_drops_tool_streams "$policy" "$harness" "$response_event" || { [ "$harness" = kiro ] && [ "$response_event" = Stop ]; }; then exec 5>/dev/null; else exec 5>&1; fi
     captured="$( {
@@ -248,7 +248,9 @@ doflow_bridge() {
     status=0
     if [ "$DF_BRIDGE_OUTCOME" = error ]; then
       case "$policy:$harness:$response_event" in
-        session-context:*:*|user-prompt-submit:*:*|subagent-audit:*:*|*:kiro:PreToolUse|*:claude:Stop) status="$code" ;;
+        session-context:*:*|user-prompt-submit:*:*|subagent-audit:*:*) status="$code" ;;
+        # The blocking-set policies are advise-only (D1): a proceed effect must not let a raw exit 2 block.
+        *:kiro:PreToolUse|*:claude:Stop) case "$policy" in pre-implementation-gate|mcp-tool-guard|stop-check) status=0 ;; *) status="$code" ;; esac ;;
       esac
     fi
   fi
@@ -258,14 +260,22 @@ doflow_bridge() {
     local render_status=$?
     return "$render_status"
   fi
+  # D1: an advisory (or out-of-step) line from a blocking-set policy is shown where the harness shows it.
+  advice=""
+  if [ "$DF_BRIDGE_EFFECT" = proceed ] && { [ "$DF_BRIDGE_OUTCOME" = advisory ] || [ "$DF_BRIDGE_OUTCOME" = unsupported ] || [ "$out_of_step" = 1 ]; } && [ -n "$err" ]; then
+    case "$policy:$harness:$response_event" in
+      pre-implementation-gate:claude:PreToolUse|pre-implementation-gate:codex:PreToolUse|mcp-tool-guard:claude:PreToolUse|mcp-tool-guard:codex:PreToolUse|stop-check:claude:Stop|stop-check:codex:Stop|stop-check:codex:stop)
+        advice="${err%$'\n'}"; advice="${advice//$'\n'/ }" ;;
+    esac
+  fi
   case "$policy:$DF_BRIDGE_OUTCOME:$harness:$response_event:$DF_BRIDGE_CODE" in
     session-context:error:*:*:*|user-prompt-submit:error:*:*:*|subagent-audit:error:*:*:*|session-context:unsupported:*:*:*|user-prompt-submit:unsupported:*:*:*|subagent-audit:unsupported:*:*:*) ;;
     *:error:codex:Stop:exit-*|*:error:codex:Stop:signal-*|*:error:copilot:Stop:exit-*|*:error:copilot:Stop:signal-*|*:error:codex:stop:exit-*|*:error:codex:stop:signal-*|*:error:kiro:PreToolUse:exit-*|*:error:kiro:PreToolUse:signal-*|*:error:kiro:Stop:exit-*|*:error:kiro:Stop:signal-*|*:error:claude:Stop:exit-*|*:error:claude:Stop:signal-*) ;;
     *)
-      if ! doflow_bridge_drops_tool_stderr "$policy" "$harness" "$response_event" && [ -n "$err" ]; then printf '%s' "$err" >&2; fi
+      if [ -z "$advice" ] && ! doflow_bridge_drops_tool_stderr "$policy" "$harness" "$response_event" && [ -n "$err" ]; then printf '%s' "$err" >&2; fi
       ;;
   esac
-  doflow_render_response "$harness" "$event" "$DF_BRIDGE_OUTCOME" "$reason" "$status"
+  doflow_render_response "$harness" "$event" "$DF_BRIDGE_OUTCOME" "$reason" "$status" "$advice"
   local render_status=$?
   return "$render_status"
 }

package/core/harnesses/shared/hooks/bridge/envelope.jq

@@ -103,7 +103,7 @@ def dft_tuple($native; $d):
     if . == {dft:1} then . else
       (if $ARGS.named.mode == "observe" then . + {duration_ms:null, tool_duration_ms:($native.duration_ms |
         if type == "number" and . >= 0 and . <= 9007199254740991 and . == floor then . else null end)} else . + {tool_duration_ms:null} end) |
-      if ($policy == "pre-bash-guard" or $ARGS.named.mode == "observe") and $d.operation == "command"
+      if $ARGS.named.mode == "observe" and $d.operation == "command"
       then . + {test_class:classify($d.command)} else . + {test_class:null} end
     end) catch {dft:1}] | if length == 1 then .[0] else {dft:1} end;
 if ($ARGS.named.mode // "encode") == "minimal" then {doflow_event:{version:(1),harness:$harness,event:(event_name($event)),operation:event_operation($event)}} elif type != "object" then . else

package/core/harnesses/shared/hooks/bridge/respond.sh

@@ -61,6 +61,12 @@ doflow_render_response() {
       *) printf '%s\n' "$reason" >&2; return 2 ;;
     esac
   fi
+  if [ -n "${6:-}" ]; then
+    case "$harness:$event" in
+      claude:PreToolUse|codex:PreToolUse) emit_pretooluse_advice "$6" || return $?; return 0 ;;
+      claude:Stop|codex:Stop|codex:stop) emit_stop_advice "$6" || return $?; return 0 ;;
+    esac
+  fi
   case "$harness:$event" in
     codex:Stop|codex:stop) printf '%s\n' '{}' ;;
     antigravity:PreToolUse) printf '%s\n' '{"decision":"allow"}' ;;

package/core/harnesses/shared/hooks/policies/capture-failure.sh

@@ -6,7 +6,7 @@
 # example its pattern file is missing). It exists only to be sourced, in a subshell with all output
 # discarded, from inside a branch where the policy already fails open:
 #
-#   ( . "<policy-dir>/capture-failure.sh"; doflow_capture_failure pre-bash-guard patterns-missing ) >/dev/null 2>&1 || true
+#   ( . "<policy-dir>/capture-failure.sh"; doflow_capture_failure mcp-tool-guard contract-missing ) >/dev/null 2>&1 || true
 #
 # The subshell keeps anything this file does away from the policy, which runs with `set -uo pipefail`,
 # does not source lib.sh and would change exit codes under `set -e`. So this file:

package/core/harnesses/shared/hooks/policies/compact-text.sh

@@ -21,6 +21,14 @@ doflow_compact_text() {
       "$preserve" "${CWD:-unknown}")
   fi
 
+  # Malformed UTF-8 (a commit subject or path can carry any byte) becomes U+FFFD here, before the cap, so the
+  # Claude (raw stdout) and Codex (jq --arg) outputs decode to the same text and the cap counts the bytes sent.
+  # jq is a hard requirement of both hooks; without it the text is left as it was (FU-535bfv).
+  if command -v jq >/dev/null 2>&1; then
+    local clean
+    if clean=$(printf '%s' "$text" | jq -Rsj '.' 2>/dev/null); then text="$clean"; fi
+  fi
+
   # The cap is 490 BYTES in every locale: LC_ALL=C makes the substring and length below count bytes,
   # where a UTF-8 locale would count characters. A cut can then end inside a multi-byte character, so
   # a trailing partial UTF-8 sequence is dropped (FU-tsq77m).

package/core/harnesses/shared/hooks/policies/deny-json.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
-# deny-json.sh — shared PreToolUse deny-JSON emitters for front-door dispatchers.
+# deny-json.sh — shared PreToolUse deny-JSON and advice-JSON emitters for front-door dispatchers.
 #
 # Deliberately carries no `set` directive (unlike lib.sh, which sets -euo
 # pipefail on source): a front door needs `set -e` OFF while it captures a
@@ -53,3 +53,25 @@ emit_pretooluse_deny_nested() {
     printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' "$(_doflow_json_reason "$reason")"
   fi
 }
+
+# Advice emitters (D1, advise-only hooks). An advisory outcome never changes a decision; these put its
+# one line where a harness shows it. Claude/Codex PreToolUse: additionalContext reaches the model, and
+# carries no permissionDecision, so the user's own permission prompt still applies. Claude/Codex Stop:
+# systemMessage is shown to the user and, unlike additionalContext, does not continue the turn.
+emit_pretooluse_advice() {
+  local line="$1"
+  if command -v jq >/dev/null 2>&1; then
+    jq -n --arg line "$line" '{hookSpecificOutput: {hookEventName: "PreToolUse", additionalContext: $line}}'
+  else
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$(_doflow_json_reason "$line")"
+  fi
+}
+
+emit_stop_advice() {
+  local line="$1"
+  if command -v jq >/dev/null 2>&1; then
+    jq -n --arg line "$line" '{systemMessage: $line}'
+  else
+    printf '{"systemMessage":%s}\n' "$(_doflow_json_reason "$line")"
+  fi
+}

package/core/harnesses/shared/hooks/policies/mcp-policy.conf

@@ -1,6 +1,6 @@
 # mcp-policy.conf — MCP tool deny patterns for mcp-tool-guard.sh
 #
-# Format (TAB-separated), identical convention to blocked-patterns.conf:
+# Format (TAB-separated):
 #   regex<TAB>reason shown to the harness
 #
 # Rules: