@moretea-labs/forge 1.5.0-rc.1

package/assets/hooks/stop-orchestrator.sh

@@ -0,0 +1,171 @@
+#!/bin/bash
+# Stop Orchestrator Hook - Stop
+# Refreshes handoff state and, for pending planning discussions, forces one
+# self-review pass before the agent stops.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/workflow-state.sh"
+
+plan_completeness_state_file() {
+  workflow_repo_relative_path \
+    "$(workflow_policy_get '.planning.completeness_state_file' '.ai/harness/planning/plan-completeness.json')" \
+    '.ai/harness/planning/plan-completeness.json' \
+    '.ai/harness/'
+}
+
+plan_completeness_signature() {
+  local kind prompt_slug draft_path source_ref created_at
+
+  kind="$(workflow_pending_orchestration_field kind 2>/dev/null || true)"
+  prompt_slug="$(workflow_pending_orchestration_field prompt_slug 2>/dev/null || true)"
+  draft_path="$(workflow_pending_orchestration_field draft_plan_path 2>/dev/null || true)"
+  source_ref="$(workflow_pending_orchestration_field source_ref 2>/dev/null || true)"
+  created_at="$(workflow_pending_orchestration_field created_at 2>/dev/null || true)"
+
+  printf '%s|%s|%s|%s|%s' \
+    "${kind:-unknown}" \
+    "${prompt_slug:-planning}" \
+    "${draft_path:-none}" \
+    "${source_ref:-none}" \
+    "${created_at:-unknown}"
+}
+
+plan_completeness_last_signature() {
+  local state_file value
+  state_file="$(plan_completeness_state_file)"
+  [[ -f "$state_file" ]] || return 1
+
+  if command -v jq >/dev/null 2>&1; then
+    value="$(jq -r '.last_signature // empty' "$state_file" 2>/dev/null || true)"
+  else
+    value="$(
+      awk '
+        /"last_signature"/ {
+          line = $0
+          sub(/^[^:]*:[[:space:]]*"/, "", line)
+          sub(/"[[:space:]]*,?[[:space:]]*$/, "", line)
+          print line
+          exit
+        }
+      ' "$state_file"
+    )"
+  fi
+
+  [[ -n "$value" ]] || return 1
+  printf '%s' "$value"
+}
+
+plan_completeness_record_signature() {
+  local signature="$1"
+  local state_file
+  state_file="$(plan_completeness_state_file)"
+  mkdir -p "$(dirname "$state_file")"
+
+  if command -v jq >/dev/null 2>&1; then
+    jq -nc \
+      --arg signature "$signature" \
+      --arg updated_at "$(date '+%Y-%m-%dT%H:%M:%S%z')" \
+      '{version:1,last_signature:$signature,updated_at:$updated_at}' > "$state_file"
+    return 0
+  fi
+
+  cat > "$state_file" <<EOF_STATE
+{"version":1,"last_signature":"$(workflow_json_escape "$signature")","updated_at":"$(workflow_json_escape "$(date '+%Y-%m-%dT%H:%M:%S%z')")"}
+EOF_STATE
+}
+
+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
+
+  length="$(printf '%s' "$message" | wc -c | tr -d ' ')"
+  [[ "${length:-0}" -ge 240 ]] || return 1
+
+  printf '%s\n' "$message" | grep -qEi \
+    '(Approved design summary|Building|Not building|Approach|Key decisions|Unknowns|Task Breakdown|Evidence Contract|P1|P2|P3|plan|design|方案|计划|设计)'
+}
+
+emit_stop_block_json() {
+  local reason="$1"
+
+  if command -v jq >/dev/null 2>&1; then
+    jq -nc --arg reason "$reason" '{decision:"block",reason:$reason}'
+    return 0
+  fi
+
+  printf '{"decision":"block","reason":"%s"}\n' "$(workflow_json_escape "$reason")"
+}
+
+refresh_handoff() {
+  workflow_write_handoff "session-stop"
+  echo "[FinalizeHandoff] Refreshed $(workflow_handoff_file)." >&2
+}
+
+should_run_plan_completeness_gate() {
+  local stop_active="$1"
+  local last_message="$2"
+  local active_plan
+
+  [[ "$stop_active" != "true" ]] || return 1
+  workflow_pending_orchestration_is_fresh || return 1
+
+  # If a repo plan is already active, the normal plan status gates own the next
+  # transition. This gate only covers host planning output that still needs
+  # capture.
+  active_plan="$(get_active_plan || true)"
+  [[ -z "$active_plan" || ! -f "$active_plan" ]] || return 1
+
+  assistant_message_looks_like_plan "$last_message"
+}
+
+refresh_handoff
+
+stop_hook_active="$(hook_json_get '.stop_hook_active' 'false')"
+last_assistant_message="$(hook_json_get '.last_assistant_message' '')"
+
+if should_run_plan_completeness_gate "$stop_hook_active" "$last_assistant_message"; then
+  signature="$(plan_completeness_signature)"
+  if [[ "$(plan_completeness_last_signature 2>/dev/null || true)" != "$signature" ]]; then
+    plan_completeness_record_signature "$signature"
+    summary="$(workflow_pending_orchestration_summary)"
+    guidance="$(plan_completeness_capture_guidance)"
+    emit_stop_block_json "[PlanCompletenessGate] A first planning answer was produced while pending orchestration is still open: ${summary}
+
+${guidance}"
+  fi
+fi

package/assets/hooks/subagent-return-channel-guard.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+# Subagent Return Channel Guard — PreToolUse on Task|Agent|SendUserMessage.
+# Spawned subagents return only their final text to the caller. If they send a
+# report through SendUserMessage, the user may see it but the parent Agent tool
+# result receives only a tiny transition/final text. This guard appends that
+# return-channel contract to spawned agent prompts and blocks subagent
+# SendUserMessage calls that would bypass the caller.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+
+hook_read_stdin_once
+input="$HOOK_STDIN_JSON"
+[[ -n "$input" ]] || exit 0
+
+CONTRACT_MARKER="[forge:return-channel]"
+CONTRACT_TEXT=$'\n\n[forge:return-channel] Your final text message is the only channel returned to your caller. Put the complete findings/report in final text. Do not call SendUserMessage for report delivery; content sent through SendUserMessage is delivered outside the Agent tool result.'
+
+if command -v bun >/dev/null 2>&1; then
+  JSON_INPUT="$input" \
+  RETURN_CONTRACT_MARKER="$CONTRACT_MARKER" \
+  RETURN_CONTRACT_TEXT="$CONTRACT_TEXT" \
+  bun -e '
+    try {
+      const input = JSON.parse(process.env.JSON_INPUT ?? "");
+      const toolName = String(input.tool_name ?? "");
+      const marker = process.env.RETURN_CONTRACT_MARKER ?? "";
+      const contract = process.env.RETURN_CONTRACT_TEXT ?? "";
+
+      if (toolName === "Task" || toolName === "Agent") {
+        const toolInput = input.tool_input;
+        if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) process.exit(0);
+        if (typeof toolInput.prompt !== "string" || toolInput.prompt.includes(marker)) process.exit(0);
+
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            permissionDecisionReason: "subagent-return-channel-guard: delivery contract appended to spawn prompt",
+            updatedInput: {
+              ...toolInput,
+              prompt: toolInput.prompt + contract,
+            },
+          },
+        }) + "\n");
+        process.exit(0);
+      }
+
+      if (toolName === "SendUserMessage") {
+        const agentId = String(input.agent_id ?? "");
+        const transcriptPath = String(input.transcript_path ?? "");
+        if (!agentId && !transcriptPath.includes("/subagents/agent-")) process.exit(0);
+
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: "subagent-return-channel-guard: SendUserMessage from a spawned subagent does not reach the caller Agent tool result. Put the full report in final text and end the subagent turn.",
+          },
+        }) + "\n");
+      }
+    } catch {
+      process.exit(0);
+    }
+  ' 2>/dev/null || true
+  exit 0
+fi
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+case "$tool_name" in
+  Task|Agent)
+    printf '%s' "$input" | jq -e '.tool_input | type == "object"' >/dev/null 2>&1 || exit 0
+    printf '%s' "$input" | jq -e '.tool_input.prompt | type == "string"' >/dev/null 2>&1 || exit 0
+    if printf '%s' "$input" | jq -e --arg marker "$CONTRACT_MARKER" '.tool_input.prompt | contains($marker)' >/dev/null 2>&1; then
+      exit 0
+    fi
+
+    printf '%s' "$input" | jq -c --arg contract "$CONTRACT_TEXT" '
+      .tool_input as $toolInput
+      | {
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            permissionDecisionReason: "subagent-return-channel-guard: delivery contract appended to spawn prompt",
+            updatedInput: ($toolInput + {prompt: ($toolInput.prompt + $contract)})
+          }
+        }'
+    ;;
+  SendUserMessage)
+    agent_id="$(printf '%s' "$input" | jq -r '.agent_id // empty' 2>/dev/null || true)"
+    transcript_path="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null || true)"
+    [[ -n "$agent_id" || "$transcript_path" == *"/subagents/agent-"* ]] || exit 0
+
+    jq -nc '{
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: "subagent-return-channel-guard: SendUserMessage from a spawned subagent does not reach the caller Agent tool result. Put the full report in final text and end the subagent turn."
+      }
+    }'
+    ;;
+esac

package/assets/hooks/worktree-guard.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Worktree Guard — PreToolUse on Edit|Write
+# Default behavior: warn in primary tree.
+# Enforced behavior: block when .claude/.require-worktree exists.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+
+REQUIRE_MARKER=".claude/.require-worktree"
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "[WorktreeGuard] Not a git repository. Skip worktree policy check."
+  exit 0
+fi
+
+GIT_DIR="$(git rev-parse --git-dir 2>/dev/null || true)"
+if [[ "$GIT_DIR" == *".git/worktrees/"* ]]; then
+  exit 0
+fi
+
+if [[ -f "$REQUIRE_MARKER" ]]; then
+  echo "[WorktreeGuard] Mutation blocked: primary working tree detected ($GIT_DIR)."
+  echo "  Enforcement marker found: $REQUIRE_MARKER"
+  echo "  Use a linked worktree for write operations."
+  echo "  Example: git worktree add ../<repo>-wt-<branch> -b <branch>"
+  hook_structured_error \
+    "WorktreeGuard" \
+    "Primary working tree detected at $GIT_DIR while $REQUIRE_MARKER is present." \
+    "Create and switch to a linked worktree before retrying the write operation." \
+    "state_violation"
+  exit 2
+fi
+
+echo "[WorktreeGuard] Warning: primary working tree detected ($GIT_DIR)."
+echo "  To enforce linked worktrees, create $REQUIRE_MARKER"
+exit 0

package/assets/initializer-question-pack.v1.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "initializer-question-pack.v1",
+  "goal": "Infer strong defaults first, then batch confirm and override.",
+  "decisionPoints": [
+    {
+      "id": "project_identity",
+      "title": "Project Identity",
+      "batch": 1,
+      "questions": [
+        "Project name",
+        "Developer name",
+        "One-line product brief"
+      ],
+      "required": true
+    },
+    {
+      "id": "plan_selection",
+      "title": "Plan Selection",
+      "batch": 1,
+      "questions": [
+        "Choose core plan A-F or Custom Presets",
+        "If Custom Presets: choose G/H/I/J/K"
+      ],
+      "required": true
+    },
+    {
+      "id": "delivery_constraints",
+      "title": "Delivery Constraints",
+      "batch": 2,
+      "questions": [
+        "Team size",
+        "MVP scope and acceptance criteria"
+      ],
+      "required": true
+    },
+    {
+      "id": "runtime_defaults",
+      "title": "Runtime Defaults",
+      "batch": 2,
+      "questions": [
+        "Confirm inferred package manager",
+        "Permission mode: Permissionless / Plan-only / Standard (default: Plan-only)",
+        "Confirm commit policy"
+      ],
+      "required": true
+    },
+    {
+      "id": "plan_overrides",
+      "title": "Plan Overrides",
+      "batch": 3,
+      "questions": [
+        "UI library",
+        "State management",
+        "Backend provider"
+      ],
+      "required": false
+    },
+    {
+      "id": "quality_rules",
+      "title": "Quality Rules",
+      "batch": 3,
+      "questions": [
+        "Project-specific prohibitions",
+        "Any must-enforce compliance constraints"
+      ],
+      "required": false
+    },
+    {
+      "id": "plugin_profile",
+      "title": "Plugin Profile",
+      "batch": 4,
+      "questions": [
+        "Install recommended global plugins",
+        "Enable LSP set by stack"
+      ],
+      "required": false
+    },
+    {
+      "id": "hook_profile",
+      "title": "Hook Profile",
+      "batch": 4,
+      "questions": [
+        "Choose hooks preset A-F",
+        "Any local hook customization"
+      ],
+      "required": false
+    }
+  ],
+  "planTiers": {
+    "core": [
+      "A",
+      "B",
+      "C",
+      "D",
+      "E",
+      "F"
+    ],
+    "presets": [
+      "G",
+      "H",
+      "I",
+      "J",
+      "K"
+    ]
+  },
+  "inferredDefaults": {
+    "packageManagerPriority": [
+      "bun",
+      "pnpm",
+      "npm"
+    ],
+    "runtimeProfile": "Plan-only"
+  },
+  "runtimeProfiles": {
+    "permissionless": {
+      "label": "Plan + Permissionless",
+      "claudePolicy": "--dangerously-skip-permissions",
+      "codexPolicy": "sandbox_mode=danger-full-access, approval_policy=never"
+    },
+    "plan-only": {
+      "label": "Plan-only (recommended)",
+      "claudePolicy": "(default permissions)",
+      "codexPolicy": "sandbox_mode=platform-default, approval_policy=on-failure"
+    },
+    "standard": {
+      "label": "Standard (ask before each action)",
+      "claudePolicy": "(default permissions)",
+      "codexPolicy": "sandbox_mode=platform-default, approval_policy=always"
+    }
+  }
+}

package/assets/initializer-question-pack.v1.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "initializer-question-pack.v1.schema.json",
+  "type": "object",
+  "required": ["version", "goal", "decisionPoints", "planTiers", "inferredDefaults"],
+  "properties": {
+    "version": {
+      "const": "initializer-question-pack.v1"
+    },
+    "goal": { "type": "string" },
+    "decisionPoints": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "batch", "questions", "required"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "batch": { "type": "integer", "minimum": 1 },
+          "questions": { "type": "array", "items": { "type": "string" } },
+          "required": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "planTiers": {
+      "type": "object",
+      "required": ["core", "presets"],
+      "properties": {
+        "core": { "type": "array", "items": { "type": "string" } },
+        "presets": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "inferredDefaults": {
+      "type": "object",
+      "required": ["packageManagerPriority", "runtimeProfile", "codexPolicy", "claudePolicy"],
+      "properties": {
+        "packageManagerPriority": { "type": "array", "items": { "type": "string" } },
+        "runtimeProfile": { "type": "string" },
+        "codexPolicy": { "type": "string" },
+        "claudePolicy": { "type": "string" }
+      }
+    }
+  }
+}

package/assets/initializer-question-pack.v2.json

@@ -0,0 +1,174 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "initializer-question-pack.v2",
+  "goal": "Infer strong harness defaults first, then confirm only the decisions that materially change the generated repo-local workflow.",
+  "decisionPoints": [
+    {
+      "id": "project_identity",
+      "title": "Project Identity",
+      "batch": 1,
+      "questions": [
+        "Project name",
+        "Developer name",
+        "One-line product brief"
+      ],
+      "required": true
+    },
+    {
+      "id": "plan_selection",
+      "title": "Plan Selection",
+      "batch": 1,
+      "questions": [
+        "Choose core plan A-F or Custom Presets",
+        "If Custom Presets: choose G/H/I/J/K"
+      ],
+      "required": true
+    },
+    {
+      "id": "delivery_constraints",
+      "title": "Delivery Constraints",
+      "batch": 2,
+      "questions": [
+        "Team size",
+        "MVP scope and acceptance criteria"
+      ],
+      "required": true
+    },
+    {
+      "id": "runtime_defaults",
+      "title": "Runtime Defaults",
+      "batch": 2,
+      "questions": [
+        "Confirm inferred package manager",
+        "Permission mode: Permissionless / Plan-only / Standard (default: Plan-only)",
+        "Confirm commit policy"
+      ],
+      "required": true
+    },
+    {
+      "id": "orchestration_profile",
+      "title": "Orchestration Profile",
+      "batch": 3,
+      "questions": [
+        "Confirm planner -> generator -> evaluator harness flow",
+        "Override artifact strictness only if the team needs a lighter loop"
+      ],
+      "required": true
+    },
+    {
+      "id": "evaluation_profile",
+      "title": "Evaluation Profile",
+      "batch": 3,
+      "questions": [
+        "Choose browser QA vs command QA default",
+        "Any extra scoring dimensions or hard thresholds"
+      ],
+      "required": false
+    },
+    {
+      "id": "handoff_profile",
+      "title": "Handoff Profile",
+      "batch": 4,
+      "questions": [
+        "When should the repo force a handoff artifact",
+        "Any custom handoff sections or restore expectations"
+      ],
+      "required": false
+    },
+    {
+      "id": "quality_rules",
+      "title": "Quality Rules",
+      "batch": 4,
+      "questions": [
+        "Project-specific prohibitions",
+        "Any must-enforce compliance constraints"
+      ],
+      "required": false
+    },
+    {
+      "id": "plugin_profile",
+      "title": "Plugin Profile",
+      "batch": 5,
+      "questions": [
+        "Install recommended global plugins",
+        "Enable LSP set by stack"
+      ],
+      "required": false
+    }
+  ],
+  "planTiers": {
+    "core": [
+      "A",
+      "B",
+      "C",
+      "D",
+      "E",
+      "F"
+    ],
+    "presets": [
+      "G",
+      "H",
+      "I",
+      "J",
+      "K"
+    ]
+  },
+  "inferredDefaults": {
+    "packageManagerPriority": [
+      "bun",
+      "pnpm",
+      "npm"
+    ],
+    "runtimeProfile": "plan-only",
+    "orchestrationProfile": "shared-long-running-harness",
+    "evaluationProfile": "browser-qa",
+    "handoffProfile": "artifact-aware"
+  },
+  "runtimeProfiles": {
+    "permissionless": {
+      "label": "Plan + Permissionless",
+      "claudePolicy": "--dangerously-skip-permissions",
+      "codexPolicy": "sandbox_mode=danger-full-access, approval_policy=never"
+    },
+    "plan-only": {
+      "label": "Plan-only (recommended)",
+      "claudePolicy": "(default permissions)",
+      "codexPolicy": "sandbox_mode=platform-default, approval_policy=on-failure"
+    },
+    "standard": {
+      "label": "Standard (ask before each action)",
+      "claudePolicy": "(default permissions)",
+      "codexPolicy": "sandbox_mode=platform-default, approval_policy=always"
+    }
+  },
+  "orchestrationProfiles": {
+    "shared-long-running-harness": {
+      "label": "Shared long-running harness",
+      "description": "Default planner -> generator -> evaluator loop with repo-local artifacts and strict execution gates."
+    },
+    "lightweight-collaboration": {
+      "label": "Lightweight collaboration",
+      "description": "Keeps the artifact model but uses softer review and handoff gates."
+    }
+  },
+  "evaluationProfiles": {
+    "browser-qa": {
+      "label": "Browser QA + evaluator rubric",
+      "description": "Use browser-first QA evidence and UI-aware scoring when the plan includes a user-facing surface."
+    },
+    "command-qa": {
+      "label": "Command QA + evaluator rubric",
+      "description": "Use command/test/build evidence and reliability scoring when the plan is backend or TUI focused."
+    }
+  },
+  "handoffProfiles": {
+    "artifact-aware": {
+      "label": "Artifact-aware handoff",
+      "description": "Force a structured handoff artifact on context rollover, failed verification, and session stop."
+    },
+    "manual-handoff": {
+      "label": "Manual handoff",
+      "description": "Generate handoff artifacts on demand while keeping the same file format."
+    }
+  }
+}