@moretea-labs/forge 1.7.1 → 1.8.0

package/adapters/mcp/types.ts

@@ -0,0 +1,41 @@
+export type McpProfileName = 'planner' | 'executor' | 'orchestrator' | 'controller';
+export type McpPathIntent = 'read' | 'write';
+export type McpAgentRunnerName = 'codex' | 'claude';
+/** Controller MCP tools/list exposure profile.
+ * - facade: explicit five-tool ChatGPT orchestration surface
+ * - core/advanced (default compatibility labels): bounded stable controller surface
+ * - full: compatibility mode — all legacy + runtime tools
+ */
+export type McpToolset = 'facade' | 'core' | 'advanced' | 'full';
+
+export interface McpPolicy {
+  profile: McpProfileName;
+  readGlobs: string[];
+  writeGlobs: string[];
+  denyGlobs: string[];
+  maxFileBytes: number;
+  execution: {
+    fixedWorkflowCheck: boolean;
+    codexRunner: boolean;
+    agentRunner: boolean;
+    allowedAgents: McpAgentRunnerName[];
+    runnerTimeoutMs: number;
+    runnerMaxTimeoutMs: number;
+  };
+}
+
+export interface McpPathDecision {
+  ok: boolean;
+  relativePath?: string;
+  absolutePath?: string;
+  reason?: string;
+}
+
+export interface McpAuditEntry {
+  timestamp: string;
+  tool: string;
+  status: 'ok' | 'blocked' | 'failed';
+  targetPath?: string;
+  inputHash?: string;
+  error?: string;
+}

package/assets/AGENTS.md

@@ -10,17 +10,15 @@ Keep this file focused on the local contract for this primary functional block.
 - Name: `contract-assets`
 - Primary prefix: `assets/workflow-contract.v1.json`
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Workstream: `tasks/workstreams/workflow-engine/contract-assets`
 
 ## Positioning
 
-Owns the workflow-engine-contract-assets capability boundary declared in .ai/context/capabilities.json.
+Owns packaged workflow/compatibility contract assets. Mutable execution lifecycle is Controller Home authority; assets must not reintroduce repo-local machine workflow state.
 
 ## Source Map
 
 - Primary prefix: `assets/workflow-contract.v1.json` (entrypoint)
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md` (design-source)
-- Workstream: `tasks/workstreams/workflow-engine/contract-assets` (durable-progress)
 
 ## Refresh Hints
 
@@ -52,17 +50,5 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 - Semantic diagram source: `docs/architecture/modules/workflow-engine/contract-assets.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- `tasks/workstreams/workflow-engine/contract-assets/cleanup-script-policy.md`
-  - status: completed
-  - current_slice: todo-01
-  - source_plan: (none)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/workflow-engine/contract-assets`.
-- `tasks/current.md` is a tracked derived status snapshot, not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/CLAUDE.md

@@ -10,17 +10,15 @@ Keep this file focused on the local contract for this primary functional block.
 - Name: `contract-assets`
 - Primary prefix: `assets/workflow-contract.v1.json`
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Workstream: `tasks/workstreams/workflow-engine/contract-assets`
 
 ## Positioning
 
-Owns the workflow-engine-contract-assets capability boundary declared in .ai/context/capabilities.json.
+Owns packaged workflow/compatibility contract assets. Mutable execution lifecycle is Controller Home authority; assets must not reintroduce repo-local machine workflow state.
 
 ## Source Map
 
 - Primary prefix: `assets/workflow-contract.v1.json` (entrypoint)
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md` (design-source)
-- Workstream: `tasks/workstreams/workflow-engine/contract-assets` (durable-progress)
 
 ## Refresh Hints
 
@@ -52,17 +50,5 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 - Semantic diagram source: `docs/architecture/modules/workflow-engine/contract-assets.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- `tasks/workstreams/workflow-engine/contract-assets/cleanup-script-policy.md`
-  - status: completed
-  - current_slice: todo-01
-  - source_plan: (none)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/workflow-engine/contract-assets`.
-- `tasks/current.md` is a tracked derived status snapshot, not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/AGENTS.md

@@ -10,7 +10,7 @@ Keep this file focused on the local contract for this primary functional block.
 - Route deep implementation detail into nearby docs instead of inflating root agent context files.
 - Treat `.ai/context/context-map.json` as the index of discoverable context files.
 - Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
-- Prefer repo-local workflow artifacts over tool-specific chat memory.
+- Prefer authored repository context for durable source knowledge and Controller Home for mutable workflow state; tool-specific chat memory is never authority.
 
 <!-- BEGIN CAPABILITY CONTEXT -->
 ## Capability Context
@@ -20,7 +20,6 @@ Keep this file focused on the local contract for this primary functional block.
 - Name: `hook-adapters`
 - Primary prefix: `assets/hooks`
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Workstream: `tasks/workstreams/runtime-harness/hook-adapters`
 
 ## Positioning
 
@@ -30,12 +29,11 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 
 - Primary prefix: `assets/hooks` (entrypoint)
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md` (design-source)
-- Workstream: `tasks/workstreams/runtime-harness/hook-adapters` (durable-progress)
 
 ## Refresh Hints
 
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
-- `bash scripts/check-task-workflow.sh --strict`
+- `forge run check-task-workflow --strict`
 <!-- END CAPABILITY CONTEXT -->
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
@@ -62,14 +60,5 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- (none yet)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
-- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/CLAUDE.md

@@ -10,7 +10,7 @@ Keep this file focused on the local contract for this primary functional block.
 - Route deep implementation detail into nearby docs instead of inflating root agent context files.
 - Treat `.ai/context/context-map.json` as the index of discoverable context files.
 - Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
-- Prefer repo-local workflow artifacts over tool-specific chat memory.
+- Prefer authored repository context for durable source knowledge and Controller Home for mutable workflow state; tool-specific chat memory is never authority.
 
 <!-- BEGIN CAPABILITY CONTEXT -->
 ## Capability Context
@@ -20,7 +20,6 @@ Keep this file focused on the local contract for this primary functional block.
 - Name: `hook-adapters`
 - Primary prefix: `assets/hooks`
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Workstream: `tasks/workstreams/runtime-harness/hook-adapters`
 
 ## Positioning
 
@@ -30,12 +29,11 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 
 - Primary prefix: `assets/hooks` (entrypoint)
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md` (design-source)
-- Workstream: `tasks/workstreams/runtime-harness/hook-adapters` (durable-progress)
 
 ## Refresh Hints
 
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
-- `bash scripts/check-task-workflow.sh --strict`
+- `forge run check-task-workflow --strict`
 <!-- END CAPABILITY CONTEXT -->
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
@@ -62,14 +60,5 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- (none yet)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
-- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/hook-input.sh

@@ -14,9 +14,12 @@ if [[ -z "${HOOK_REPO_ROOT:-}" ]]; then
   export HOOK_REPO_ROOT
 fi
 
-if [[ -f "${HOOK_REPO_ROOT:-$(pwd)}/.ai/hooks/lib/workflow-state.sh" ]]; then
+HOOK_BUNDLE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+if [[ -f "$HOOK_BUNDLE_DIR/lib/workflow-state.sh" ]]; then
+  # Source workflow helpers from the same selected hook bundle. A central hook
+  # must never fall back to a stale repo-local lib and silently change authority.
   # shellcheck source=/dev/null
-  . "${HOOK_REPO_ROOT:-$(pwd)}/.ai/hooks/lib/workflow-state.sh"
+  . "$HOOK_BUNDLE_DIR/lib/workflow-state.sh"
 fi
 
 hook_read_stdin_once() {
@@ -546,6 +549,10 @@ hook_failure_log_file() {
     workflow_failure_log_file
     return 0
   fi
+  if [[ -n "${FORGE_HOOK_STATE_ROOT:-}" && "${FORGE_HOOK_STATE_ROOT}" == /* ]]; then
+    printf '%s/failures/latest.jsonl' "${FORGE_HOOK_STATE_ROOT%/}"
+    return 0
+  fi
   printf '.ai/harness/failures/latest.jsonl'
 }
 

package/assets/hooks/lib/workflow-state.sh

@@ -70,44 +70,62 @@ workflow_repo_relative_path() {
   esac
 }
 
+workflow_machine_state_path() {
+  local value="$1"
+  local default_value="$2"
+  local relative_path
+
+  value="$(workflow_repo_relative_path "$value" "$default_value" '.ai/harness/')"
+  if [[ -n "${FORGE_HOOK_STATE_ROOT:-}" && "${FORGE_HOOK_STATE_ROOT}" == /* ]]; then
+    relative_path="${value#.ai/harness/}"
+    printf '%s/%s' "${FORGE_HOOK_STATE_ROOT%/}" "$relative_path"
+    return 0
+  fi
+  printf '%s' "$value"
+}
+
 workflow_context_map_file() {
   workflow_repo_relative_path "$(workflow_policy_get '.context.map_file' '.ai/context/context-map.json')" '.ai/context/context-map.json' '.ai/context/'
 }
 
 workflow_failure_log_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.failure_log_file' '.ai/harness/failures/latest.jsonl')" '.ai/harness/failures/latest.jsonl' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.harness.failure_log_file' '.ai/harness/failures/latest.jsonl')" '.ai/harness/failures/latest.jsonl'
 }
 
 workflow_events_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.events_file' '.ai/harness/events.jsonl')" '.ai/harness/events.jsonl' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.harness.events_file' '.ai/harness/events.jsonl')" '.ai/harness/events.jsonl'
 }
 
 workflow_trace_file() {
+  if [[ -n "${FORGE_HOOK_STATE_ROOT:-}" && "${FORGE_HOOK_STATE_ROOT}" == /* ]]; then
+    printf '%s/trace.jsonl' "${FORGE_HOOK_STATE_ROOT%/}"
+    return 0
+  fi
   printf '%s' ".claude/.trace.jsonl"
 }
 
 workflow_runs_dir() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.runs_dir' '.ai/harness/runs')" '.ai/harness/runs' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.harness.runs_dir' '.ai/harness/runs')" '.ai/harness/runs'
 }
 
 workflow_resume_packet_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.session.resume_file' '.ai/harness/session/resume.md')" '.ai/harness/session/resume.md' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.session.resume_file' '.ai/harness/session/resume.md')" '.ai/harness/session/resume.md'
 }
 
 workflow_pending_orchestration_file() {
+  # Legacy read/migration surface only. Modern controller-home repositories do
+  # not create a second file-backed Plan/pending authority from hooks.
   workflow_repo_relative_path "$(workflow_policy_get '.planning.pending_orchestration_file' '.ai/harness/planning/pending.json')" '.ai/harness/planning/pending.json' '.ai/harness/'
 }
 
 workflow_ensure_harness_surface() {
+  # Hooks initialize only rebuildable machine diagnostics. Authored task/context
+  # directories and semantic Plan state remain repository/Controller concerns.
   mkdir -p \
-    "tasks/notes" \
-    "$(dirname "$(workflow_context_map_file)")" \
-    "$(dirname "$(workflow_policy_file)")" \
     "$(dirname "$(workflow_checks_file)")" \
     "$(dirname "$(workflow_session_continuation_file)")" \
     "$(dirname "$(workflow_resume_packet_file)")" \
     "$(dirname "$(workflow_failure_log_file)")" \
-    "$(dirname "$(workflow_pending_orchestration_file)")" \
     "$(workflow_runs_dir)"
 
   [[ -f "$(workflow_checks_file)" ]] || printf "{}\n" > "$(workflow_checks_file)"
@@ -1094,11 +1112,11 @@ workflow_active_notes() {
 }
 
 workflow_checks_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.checks_file' '.ai/harness/checks/latest.json')" '.ai/harness/checks/latest.json' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.harness.checks_file' '.ai/harness/checks/latest.json')" '.ai/harness/checks/latest.json'
 }
 
 workflow_session_continuation_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.session.continuation_file' '.ai/harness/session/continuation.md')" '.ai/harness/session/continuation.md' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.session.continuation_file' '.ai/harness/session/continuation.md')" '.ai/harness/session/continuation.md'
 }
 
 # mkdir-based mutual exclusion (macOS ships no flock). Spins ~2s, breaks locks

package/assets/hooks/prompt-guard.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 # Prompt Guard Hook — UserPromptSubmit
-# Shell layer: filesystem authority (plan/contract/worktree state), capture
-# side effects, and host-safe rendering. All prompt-text intent classification
+# Shell layer: compatibility reads for legacy plan/contract/worktree state plus
+# host-safe rendering. Modern controller-home repositories never create or use
+# repo-local Plan/Work files as authority. All prompt-text intent classification
 # lives in the TypeScript engine behind `prompt-guard-decide`, which receives
 # {"prompt": ...} on stdin plus PROMPT_GUARD_*_STATE env vars and returns a
 # single-line verdict JSON (action + intent facts + derived strings).
@@ -392,6 +393,15 @@ pg_fact() {
   [[ "${!var:-0}" == "1" ]]
 }
 
+modern_controller_home_runtime() {
+  [[ -f "forge.config.json" ]] || return 1
+  if command -v jq >/dev/null 2>&1; then
+    [[ "$(jq -r '.runtimeState // empty' forge.config.json 2>/dev/null || true)" == "controller-home" ]]
+    return
+  fi
+  grep -Eq '"runtimeState"[[:space:]]*:[[:space:]]*"controller-home"' forge.config.json 2>/dev/null
+}
+
 # --- Side effects and hints (driven by engine facts) ---
 
 emit_pending_orchestration_discussion() {
@@ -603,38 +613,26 @@ run_codegraph_init_command() {
   return "$status"
 }
 
-ensure_codegraph_index_for_route() {
-  local output status
-
-  [[ -f ".codegraph/codegraph.db" ]] && return 0
-
-  output="$(run_codegraph_init_command 2>&1)"
-  status=$?
-
-  if [[ "$status" -eq 0 && -f ".codegraph/codegraph.db" ]]; then
-    echo "[CodegraphRoute] Initialized missing CodeGraph index before routing hint."
-  elif [[ "$status" -ne 127 ]]; then
-    echo "[CodegraphRoute] CodeGraph index init skipped or failed; run codegraph init -i . if structural tools are unavailable."
+emit_codegraph_route_hint() {
+  if pg_fact CODEGRAPH_ROUTE || pg_fact NONTRIVIAL_CODE_TASK; then
+    echo "[CodegraphRoute] Structural code-navigation intent detected. Prefer Forge rh_context/semantic navigation or an already-configured structural provider; do not initialize repo-local .codegraph state from a prompt hook."
   fi
 }
 
-emit_codegraph_route_hint() {
-  local session_key session_file=".claude/.session-id"
-
-  mkdir -p .claude
-  session_key="$(session_state_resolve_key "$session_file" "${1:-}")"
+modern_controller_home_workflow() {
+  [[ -f "forge.config.json" ]]
+}
 
-  if session_state_codegraph_used "$session_key" || session_state_codegraph_nudged "$session_key"; then
-    return 0
+emit_modern_controller_home_guidance() {
+  if pg_fact THINK_PLAN_START || pg_fact PLAN_START; then
+    echo "[ForgeRoute] Planning intent detected. Keep repo files for authored product/architecture content only; use Forge Plan/Work authority when durable execution state is needed."
+    echo "[ArchitectureCompleteness] For high-risk or architecture-changing work, Context Closure + Engineering Design receipts are correctness gates; prompt guidance is advisory only."
   fi
-
-  if pg_fact CODEGRAPH_ROUTE; then
-    ensure_codegraph_index_for_route || true
-    echo "[CodegraphRoute] Structural code-navigation intent detected. Prefer CodeGraph context/search/callers/impact before grep/read when available."
-    session_state_mark_codegraph_nudged "$session_key" || true
-  elif pg_fact NONTRIVIAL_CODE_TASK; then
-    echo "[CodegraphRoute] Structural code-navigation intent detected. Prefer CodeGraph context/search/callers/impact before grep/read when available."
-    session_state_mark_codegraph_nudged "$session_key" || true
+  if pg_fact IMPLEMENT; then
+    echo "[ArchitectureCompleteness] Implementation intent detected. Preserve the approved authority/lifecycle/authorization/resource/replay/retention contract; Forge admission and implementation review own enforcement."
+  fi
+  if pg_fact DONE; then
+    echo "[Review] Completion intent detected. Use current Forge verification/review evidence; do not materialize repo-local task/check/session closeout state."
   fi
 }
 
@@ -834,6 +832,18 @@ PROMPT_INTENT_TEXT="$(prompt_intent_text)"
 prompt_guard_refresh_state
 prompt_guard_engine_call
 
+# Kernel V2 cutover: forge.config.json selects the Controller Home workflow.
+# Prompt hooks are advisory only in this mode and MUST NOT materialize repo-local
+# Plan/Work/check/session/cache state. Legacy .ai/harness projects continue below
+# only so they can be migrated without breaking their existing workflow.
+if modern_controller_home_workflow; then
+  emit_agentic_packaging_hint
+  emit_forge_route_hint
+  emit_codegraph_route_hint
+  emit_modern_controller_home_guidance
+  exit 0
+fi
+
 if [[ "$PG_ENGINE_STATE" != "ok" ]]; then
   if [[ "$PG_ENGINE_STATE" == "legacy" ]]; then
     echo "[PromptGuard] Advisory: the installed forge CLI predates the prompt-verdict protocol; prompt intent gates are degraded to advisory for this prompt."
@@ -858,6 +868,22 @@ pg_fact DONE && done_intent=1
 plan_start_intent=0
 pg_fact PLAN_START && plan_start_intent=1
 
+if modern_controller_home_runtime; then
+  if [ "$plan_start_intent" -eq 1 ]; then
+    echo "[PlanStartGate] Planning intent detected. Durable decomposition belongs to Forge Controller Plan/Work; no repo-local Draft plan or pending marker will be created."
+  fi
+  if [ "$implement_intent" -eq 1 ] && [ "$PG_ACTION" = "spec_block" ]; then
+    echo "[SpecGuard] Advisory: docs/spec.md is missing. Create or update authored product truth before implementation when the change needs a durable specification."
+  fi
+  if [ "$done_intent" -eq 1 ]; then
+    echo "[PlanStatusGuard] Controller Home owns completion authority; legacy active-plan/task-contract files are ignored for modern repositories."
+  fi
+  if [ "$implement_intent" -eq 0 ]; then
+    emit_workflow_file_guards
+  fi
+  exit 0
+fi
+
 plan_research_ready=1
 if [ "$plan_start_intent" -eq 1 ]; then
   if ! has_research_for_new_plan; then
@@ -944,9 +970,9 @@ if [ "$done_intent" -eq 1 ]; then
   IFS=$'\t' read -r total_tasks done_tasks next_task <<< "$task_state"
   remaining_tasks=$(( ${total_tasks:-0} - ${done_tasks:-0} ))
   if [ "${remaining_tasks:-0}" -gt 0 ]; then
-    echo "[ArchiveGuard] Done intent detected but active plan still has $remaining_tasks unchecked item(s). Refusing to auto-archive."
+    echo "[WorkflowCloseoutGuard] Done intent detected but active plan still has $remaining_tasks unchecked item(s). Refusing workflow closeout."
     hook_structured_error \
-      "ArchiveGuard" \
+      "WorkflowCloseoutGuard" \
       "Done intent with $remaining_tasks unchecked active-plan task(s)." \
       "Finish the remaining Task Breakdown item: ${next_task:-see $active_plan}." \
       "state_violation"
@@ -968,22 +994,22 @@ if [ "$done_intent" -eq 1 ]; then
   fi
 
   if [ ! -x scripts/archive-workflow.sh ]; then
-    echo "[AutoArchive] scripts/archive-workflow.sh is missing or not executable. Skipping auto-archive."
+    echo "[WorkflowCloseout] scripts/archive-workflow.sh compatibility helper is missing or not executable. Skipping closeout."
     hook_structured_error \
-      "AutoArchive" \
+      "WorkflowCloseout" \
       "scripts/archive-workflow.sh is missing or not executable." \
-      "Install the workflow helper before relying on auto-archive." \
+      "Install the workflow closeout helper before relying on automatic terminal cleanup." \
       "missing_artifact"
     exit 1
   fi
 
   outcome="${PG_DONE_OUTCOME:-Completed}"
-  echo "[AutoArchive] All quality gates passed. Archiving $active_plan as outcome=$outcome"
+  echo "[WorkflowCloseout] All quality gates passed. Closing $active_plan as outcome=$outcome"
   if ! archive_output="$(bash scripts/archive-workflow.sh --plan "$active_plan" --outcome "$outcome" 2>&1)"; then
     printf '%s\n' "$archive_output"
     hook_structured_error \
-      "AutoArchive" \
-      "Automatic archive failed for $active_plan." \
+      "WorkflowCloseout" \
+      "Automatic workflow closeout failed for $active_plan." \
       "Run bash scripts/archive-workflow.sh --plan $active_plan --outcome $outcome and resolve the error." \
       "contract_failure"
     exit 1

package/assets/hooks/security-sentinel.sh

@@ -6,7 +6,8 @@ set -euo pipefail
 # SessionStart context reminder if forge security scan finds anything.
 
 REPO_ROOT="${HOOK_REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
-SECURITY_DIR="$REPO_ROOT/.ai/harness/security"
+HOOK_STATE_ROOT="${FORGE_HOOK_STATE_ROOT:-$REPO_ROOT/.ai/harness}"
+SECURITY_DIR="${HOOK_STATE_ROOT%/}/security"
 STATE_FILE="$SECURITY_DIR/state.sha256"
 LATEST_FILE="$SECURITY_DIR/latest.json"
 

package/assets/hooks/session-start-context.sh

@@ -9,9 +9,10 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 . "$SCRIPT_DIR/lib/workflow-state.sh"
 
-# Cold-path housekeeping: both event logs grow unbounded otherwise.
+# Cold-path housekeeping: machine event logs grow unbounded otherwise. Both
+# paths resolve below Controller Home hook-state for modern forge-hook runs.
 workflow_rotate_events_file "$(workflow_events_file)" 2>/dev/null || true
-workflow_rotate_events_file ".ai/harness/architecture/events.jsonl" 2>/dev/null || true
+workflow_rotate_events_file "$(workflow_machine_state_path '.ai/harness/architecture/events.jsonl' '.ai/harness/architecture/events.jsonl')" 2>/dev/null || true
 
 resume_file="$(workflow_resume_packet_file)"
 
@@ -209,11 +210,11 @@ render_tooling_update_context_once() {
 tooling_update_advisory_context() {
   local target state_dir report_file marker_file lock_dir tmp_report
 
-  [[ -f ".ai/harness/workflow-contract.json" ]] || return 1
+  [[ -f "forge.config.json" || -f ".ai/harness/workflow-contract.json" ]] || return 1
   [[ "${FORGE_TOOLING_ADVISORY:-1}" != "0" ]] || return 1
 
   target="$(tooling_update_target)"
-  state_dir=".ai/harness/security"
+  state_dir="$(workflow_machine_state_path '.ai/harness/security' '.ai/harness/security')"
   report_file="$state_dir/tooling-update-advisory-${target}.json"
   marker_file="$state_dir/tooling-update-advisory-${target}.rendered"
   lock_dir="$state_dir/tooling-update-advisory-${target}.lock"
@@ -269,7 +270,8 @@ continuation_section_has_signal() {
 }
 
 capability_context_pending() {
-  local queue_file=".ai/harness/capability-context/requests.jsonl"
+  local queue_file
+  queue_file="$(workflow_machine_state_path '.ai/harness/capability-context/requests.jsonl' '.ai/harness/capability-context/requests.jsonl')"
   local pending_lines=""
   local pending_count="0"
 

package/assets/hooks/stop-orchestrator.sh

@@ -12,10 +12,9 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$SCRIPT_DIR/lib/workflow-state.sh"
 
 plan_completeness_state_file() {
-  workflow_repo_relative_path \
+  workflow_machine_state_path \
     "$(workflow_policy_get '.planning.completeness_state_file' '.ai/harness/planning/plan-completeness.json')" \
-    '.ai/harness/planning/plan-completeness.json' \
-    '.ai/harness/'
+    '.ai/harness/planning/plan-completeness.json'
 }
 
 plan_completeness_signature() {
@@ -155,6 +154,17 @@ should_run_plan_completeness_gate() {
 
 refresh_handoff
 
+# Modern V2 delegates semantic Plan/Work completion to Controller Home. Keep the
+# rebuildable session continuation above, but never revive repo-local pending
+# orchestration or PlanCompleteness as a second completion authority.
+if [[ -f "forge.config.json" ]]; then
+  if command -v jq >/dev/null 2>&1; then
+    [[ "$(jq -r '.runtimeState // empty' forge.config.json 2>/dev/null || true)" != "controller-home" ]] || exit 0
+  elif grep -Eq '"runtimeState"[[:space:]]*:[[:space:]]*"controller-home"' forge.config.json 2>/dev/null; then
+    exit 0
+  fi
+fi
+
 stop_hook_active="$(hook_json_get '.stop_hook_active' 'false')"
 last_assistant_message="$(hook_json_get '.last_assistant_message' '')"
 

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "version": "initializer-question-pack.v4",
-  "goal": "Infer strong harness defaults first, then confirm only the decisions that materially change the generated repo-local workflow.",
+  "goal": "Infer strong harness defaults first, then confirm only decisions that materially change authored repository structure or Controller-owned workflow behavior.",
   "decisionPoints": [
     {
       "id": "project_identity",
@@ -185,7 +185,7 @@
     "evaluationProfile": "browser-qa",
     "handoffProfile": "artifact-aware",
     "recoveryProfile": "hybrid",
-    "stateProfile": "file-backed",
+    "stateProfile": "controller-home",
     "contextProfile": "stable-root-progressive-subdir",
     "documentationProfile": "minimal-agentic",
     "aiNativeProfile": "none",
@@ -211,7 +211,7 @@
   "orchestrationProfiles": {
     "shared-long-running-harness": {
       "label": "Shared long-running harness",
-      "description": "Default planner -> generator -> evaluator loop with repo-local artifacts and strict execution gates."
+      "description": "Default Controller-guided planning -> implementation -> verification loop with durable Runtime authority in Controller Home and authored repository evidence only."
     },
     "lightweight-collaboration": {
       "label": "Lightweight collaboration",
@@ -253,13 +253,17 @@
     }
   },
   "stateProfiles": {
-    "file-backed": {
-      "label": "File-backed",
-      "description": "Persist execution, verification, and handoff state to repo-local artifacts."
+    "controller-home": {
+      "label": "Controller Home",
+      "description": "Persist mutable execution, verification, authorization, handoff, and lifecycle state under the Forge Controller Home; keep the repository limited to authored/declarative content."
     },
     "context-light": {
       "label": "Context-light",
-      "description": "Use the same workflow surface with fewer persisted state assumptions for lightweight repos."
+      "description": "Use Controller Home only when durable continuity is required; keep bounded direct work ephemeral."
+    },
+    "file-backed": {
+      "label": "Legacy file-backed (migration only)",
+      "description": "Compatibility input for older adopted repositories. Do not select for new projects or create new repo-local Runtime state."
     }
   },
   "contextProfiles": {