@moretea-labs/forge 1.5.0-rc.1

package/docs/architecture/requests/archive/2026/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md

@@ -0,0 +1,60 @@
+# Architecture Drift Request: 20260529-094446-ai-hooks-ai-hooks-session-start-context-sh
+
+> **Status**: Superseded
+> **Detected**: 2026-05-29T09:44:46+0800
+> **Severity**: high
+> **Change Type**: workflow-surface
+> **File**: `.ai/hooks/session-start-context.sh`
+> **Functional Block**: `.ai/hooks`
+> **Capability ID**: `runtime-harness-hook-adapters`
+> **Matched Prefix**: `.ai/hooks`
+> **Architecture Domain**: `runtime-harness`
+> **Architecture Capability**: `hook-adapters`
+> **Architecture Module**: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+> **Workstream Directory**: `tasks/workstreams/runtime-harness/hook-adapters`
+> **Contract Files**: `AGENTS.md`, `CLAUDE.md`
+> **Contract Sync Required**: true
+> **Spawn Recommended**: true
+
+## Required Follow-up
+
+- Read root `AGENTS.md` / `CLAUDE.md`.
+- If functional block is not `root`, read its local `AGENTS.md` / `CLAUDE.md`.
+- Decide whether this change affects module boundaries, entrypoints, dependency rules, runtime paths, or verification commands.
+- For substantial changes, write a snapshot under `docs/architecture/snapshots/`.
+- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.
+- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.
+- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.
+- If this starts or advances durable execution, run `scripts/workstream-sync.sh ensure --block ".ai/hooks" --request "docs/architecture/requests/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md"`.
+- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.
+
+## Event Fields
+
+```json
+{
+  "ts": "2026-05-29T09:44:46+0800",
+  "file_path": ".ai/hooks/session-start-context.sh",
+  "severity": "high",
+  "functional_block": ".ai/hooks",
+  "capability_id": "runtime-harness-hook-adapters",
+  "matched_prefix": ".ai/hooks",
+  "architecture_domain": "runtime-harness",
+  "architecture_capability": "hook-adapters",
+  "architecture_module": "docs/architecture/modules/runtime-harness/hook-adapters.md",
+  "workstream_dir": "tasks/workstreams/runtime-harness/hook-adapters",
+  "contract_agents": "AGENTS.md",
+  "contract_claude": "CLAUDE.md",
+  "change_type": "workflow-surface",
+  "request_file": "docs/architecture/requests/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md",
+  "spawn_recommended": true,
+  "contract_sync_required": true
+}
+```
+
+## Archive Resolution
+
+- Status: Superseded
+- Archived: 2026-06-12T03:29:07+0800
+- Artifacts:
+- `docs/architecture/requests/runtime-harness-hook-adapters.md`
+- Note: Merged into architecture queue card by triage --before 2026-06-01.

package/docs/architecture/requests/archive/2026/20260613-002040-runtime-harness-hook-adapters.md

@@ -0,0 +1,68 @@
+# Architecture Queue Card: runtime-harness-hook-adapters
+
+> **Status**: Resolved
+> **Detected**: 2026-06-13T00:01:34+0800
+> **Updated**: 2026-06-13T00:04:13+0800
+> **Severity**: high
+> **Change Type**: workflow-surface
+> **File**: `.ai/hooks/post-tool-observer.sh`
+> **Functional Block**: `.ai/hooks`
+> **Capability ID**: `runtime-harness-hook-adapters`
+> **Matched Prefix**: `.ai/hooks`
+> **Architecture Domain**: `runtime-harness`
+> **Architecture Capability**: `hook-adapters`
+> **Architecture Module**: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+> **Workstream Directory**: `tasks/workstreams/runtime-harness/hook-adapters`
+> **Contract Files**: `assets/hooks/AGENTS.md`, `assets/hooks/CLAUDE.md`
+> **Contract Sync Required**: true
+> **Spawn Recommended**: true
+> **Open Edits**: 1
+
+## Required Follow-up
+
+- Read root `AGENTS.md` / `CLAUDE.md`.
+- If functional block is not `root`, read its local `AGENTS.md` / `CLAUDE.md`.
+- Decide whether this change affects module boundaries, entrypoints, dependency rules, runtime paths, or verification commands.
+- For substantial changes, write a snapshot under `docs/architecture/snapshots/`.
+- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.
+- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.
+- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.
+- If this starts or advances durable execution, run `scripts/workstream-sync.sh ensure --block ".ai/hooks" --request "docs/architecture/requests/runtime-harness-hook-adapters.md"`.
+- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.
+
+## Touched Files
+
+| Last Event | Severity | Change Type | File |
+| --- | --- | --- | --- |
+| 2026-06-13T00:04:13+0800 | high | workflow-surface | `.ai/hooks/post-tool-observer.sh` |
+
+## Event Fields
+
+```json
+{
+  "ts": "2026-06-13T00:04:13+0800",
+  "file_path": ".ai/hooks/post-tool-observer.sh",
+  "severity": "high",
+  "functional_block": ".ai/hooks",
+  "capability_id": "runtime-harness-hook-adapters",
+  "matched_prefix": ".ai/hooks",
+  "architecture_domain": "runtime-harness",
+  "architecture_capability": "hook-adapters",
+  "architecture_module": "docs/architecture/modules/runtime-harness/hook-adapters.md",
+  "workstream_dir": "tasks/workstreams/runtime-harness/hook-adapters",
+  "contract_agents": "assets/hooks/AGENTS.md",
+  "contract_claude": "assets/hooks/CLAUDE.md",
+  "change_type": "workflow-surface",
+  "request_file": "docs/architecture/requests/runtime-harness-hook-adapters.md",
+  "spawn_recommended": true,
+  "contract_sync_required": true
+}
+```
+
+## Archive Resolution
+
+- Status: Resolved
+- Archived: 2026-06-13T00:20:40+0800
+- Artifacts:
+- `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Note: Resolved by documenting that PRD/Sprint helper runtime isolation keeps hook routes under .ai/hooks, moves generated workflow helpers to .ai/harness/scripts, and introduces no post-tool-observer route boundary change.

package/docs/architecture/requests/archive/2026/root.md

@@ -0,0 +1,68 @@
+# Architecture Queue Card: root
+
+> **Status**: No architecture change
+> **Detected**: 2026-05-29T00:03:22+0800
+> **Updated**: 2026-06-12T03:34:14+0800
+> **Severity**: medium
+> **Change Type**: boundary-or-config
+> **File**: `apps/web/src/routes/account.tsx`
+> **Functional Block**: `root`
+> **Capability ID**: `root`
+> **Matched Prefix**: `root`
+> **Architecture Domain**: `root`
+> **Architecture Capability**: `_root`
+> **Architecture Module**: `docs/architecture/index.md`
+> **Workstream Directory**: `tasks/workstreams/root/_root`
+> **Contract Files**: `none`, `none`
+> **Contract Sync Required**: false
+> **Spawn Recommended**: false
+> **Open Edits**: 2
+
+## Required Follow-up
+
+- Read root `AGENTS.md` / `CLAUDE.md`.
+- If functional block is not `root`, read its local `AGENTS.md` / `CLAUDE.md`.
+- Decide whether this change affects module boundaries, entrypoints, dependency rules, runtime paths, or verification commands.
+- For substantial changes, write a snapshot under `docs/architecture/snapshots/`.
+- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.
+- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.
+- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.
+- If this starts or advances durable execution, run `scripts/workstream-sync.sh ensure --block "root" --request "docs/architecture/requests/root.md"`.
+- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.
+
+## Touched Files
+
+| Last Event | Severity | Change Type | File |
+| --- | --- | --- | --- |
+| 2026-06-12T03:34:14+0800 | medium | boundary-or-config | `apps/web/src/routes/account.tsx` |
+| 2026-05-29T00:03:22+0800 | medium | boundary-or-config | `package.json` |
+
+## Event Fields
+
+```json
+{
+  "ts": "2026-06-12T03:34:14+0800",
+  "file_path": "apps/web/src/routes/account.tsx",
+  "severity": "medium",
+  "functional_block": "root",
+  "capability_id": "root",
+  "matched_prefix": "root",
+  "architecture_domain": "root",
+  "architecture_capability": "_root",
+  "architecture_module": "docs/architecture/index.md",
+  "workstream_dir": "tasks/workstreams/root/_root",
+  "contract_agents": "",
+  "contract_claude": "",
+  "change_type": "boundary-or-config",
+  "request_file": "docs/architecture/requests/root.md",
+  "spawn_recommended": false,
+  "contract_sync_required": false
+}
+```
+
+## Archive Resolution
+
+- Status: No architecture change
+- Archived: 2026-06-12T03:36:05+0800
+- Artifacts: (none)
+- Note: Root-level pending card did not require an architecture boundary change for this queue migration.

package/docs/architecture/requests/archive/2026/runtime-harness-hook-adapters.md

@@ -0,0 +1,76 @@
+# Architecture Queue Card: runtime-harness-hook-adapters
+
+> **Status**: Resolved
+> **Detected**: 2026-05-28T15:47:40+0800
+> **Updated**: 2026-05-29T09:44:46+0800
+> **Severity**: high
+> **Change Type**: workflow-surface
+> **File**: `.ai/hooks/session-start-context.sh`
+> **Functional Block**: `.ai/hooks`
+> **Capability ID**: `runtime-harness-hook-adapters`
+> **Matched Prefix**: `.ai/hooks`
+> **Architecture Domain**: `runtime-harness`
+> **Architecture Capability**: `hook-adapters`
+> **Architecture Module**: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+> **Workstream Directory**: `tasks/workstreams/runtime-harness/hook-adapters`
+> **Contract Files**: `AGENTS.md`, `CLAUDE.md`
+> **Contract Sync Required**: true
+> **Spawn Recommended**: true
+> **Open Edits**: 9
+
+## Required Follow-up
+
+- Read root `AGENTS.md` / `CLAUDE.md`.
+- If functional block is not `root`, read its local `AGENTS.md` / `CLAUDE.md`.
+- Decide whether this change affects module boundaries, entrypoints, dependency rules, runtime paths, or verification commands.
+- For substantial changes, write a snapshot under `docs/architecture/snapshots/`.
+- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.
+- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.
+- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.
+- If this starts or advances durable execution, run `scripts/workstream-sync.sh ensure --block ".ai/hooks" --request "docs/architecture/requests/runtime-harness-hook-adapters.md"`.
+- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.
+
+## Touched Files
+
+| Last Event | Severity | Change Type | File |
+| --- | --- | --- | --- |
+| 2026-05-29T09:44:46+0800 | high | workflow-surface | `.ai/hooks/session-start-context.sh` |
+| 2026-05-29T09:44:30+0800 | high | workflow-surface | `assets/hooks/session-start-context.sh` |
+| 2026-05-29T09:43:39+0800 | high | workflow-surface | `assets/hooks/prompt-guard.sh` |
+| 2026-05-29T09:43:31+0800 | high | workflow-surface | `.ai/hooks/prompt-guard.sh` |
+| 2026-05-29T00:42:38+0800 | high | workflow-surface | `.ai/hooks/lib/workflow-state.sh` |
+| 2026-05-28T22:47:36+0800 | high | workflow-surface | `.ai/hooks/hook-input.sh` |
+| 2026-05-28T22:27:05+0800 | high | workflow-surface | `.ai/hooks/worktree-guard.sh` |
+| 2026-05-28T22:26:48+0800 | high | workflow-surface | `.ai/hooks/pre-edit-guard.sh` |
+| 2026-05-28T15:48:16+0800 | high | workflow-surface | `assets/hooks/hook-input.sh` |
+
+## Event Fields
+
+```json
+{
+  "ts": "2026-05-29T09:44:46+0800",
+  "file_path": ".ai/hooks/session-start-context.sh",
+  "severity": "high",
+  "functional_block": ".ai/hooks",
+  "capability_id": "runtime-harness-hook-adapters",
+  "matched_prefix": ".ai/hooks",
+  "architecture_domain": "runtime-harness",
+  "architecture_capability": "hook-adapters",
+  "architecture_module": "docs/architecture/modules/runtime-harness/hook-adapters.md",
+  "workstream_dir": "tasks/workstreams/runtime-harness/hook-adapters",
+  "contract_agents": "AGENTS.md",
+  "contract_claude": "CLAUDE.md",
+  "change_type": "workflow-surface",
+  "request_file": "docs/architecture/requests/runtime-harness-hook-adapters.md",
+  "spawn_recommended": true,
+  "contract_sync_required": true
+}
+```
+
+## Archive Resolution
+
+- Status: Resolved
+- Archived: 2026-06-12T03:36:04+0800
+- Artifacts:
+- `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Note: Post-edit hook architecture recording now routes through architecture-queue.sh with advisory semantics.

package/docs/architecture/requests/archive/2026/verification-evals-checks.md

@@ -0,0 +1,68 @@
+# Architecture Queue Card: verification-evals-checks
+
+> **Status**: Resolved
+> **Detected**: 2026-05-28T16:18:53+0800
+> **Updated**: 2026-05-28T16:18:53+0800
+> **Severity**: high
+> **Change Type**: workflow-surface
+> **File**: `scripts/check-task-workflow.sh`
+> **Functional Block**: `scripts/check-task-workflow.sh`
+> **Capability ID**: `verification-evals-checks`
+> **Matched Prefix**: `scripts/check-task-workflow.sh`
+> **Architecture Domain**: `verification`
+> **Architecture Capability**: `evals-checks`
+> **Architecture Module**: `docs/architecture/modules/verification/evals-checks.md`
+> **Workstream Directory**: `tasks/workstreams/verification/evals-checks`
+> **Contract Files**: `AGENTS.md`, `CLAUDE.md`
+> **Contract Sync Required**: true
+> **Spawn Recommended**: true
+> **Open Edits**: 1
+
+## Required Follow-up
+
+- Read root `AGENTS.md` / `CLAUDE.md`.
+- If functional block is not `root`, read its local `AGENTS.md` / `CLAUDE.md`.
+- Decide whether this change affects module boundaries, entrypoints, dependency rules, runtime paths, or verification commands.
+- For substantial changes, write a snapshot under `docs/architecture/snapshots/`.
+- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.
+- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.
+- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.
+- If this starts or advances durable execution, run `scripts/workstream-sync.sh ensure --block "scripts/check-task-workflow.sh" --request "docs/architecture/requests/verification-evals-checks.md"`.
+- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.
+
+## Touched Files
+
+| Last Event | Severity | Change Type | File |
+| --- | --- | --- | --- |
+| 2026-05-28T16:18:53+0800 | high | workflow-surface | `scripts/check-task-workflow.sh` |
+
+## Event Fields
+
+```json
+{
+  "ts": "2026-05-28T16:18:53+0800",
+  "file_path": "scripts/check-task-workflow.sh",
+  "severity": "high",
+  "functional_block": "scripts/check-task-workflow.sh",
+  "capability_id": "verification-evals-checks",
+  "matched_prefix": "scripts/check-task-workflow.sh",
+  "architecture_domain": "verification",
+  "architecture_capability": "evals-checks",
+  "architecture_module": "docs/architecture/modules/verification/evals-checks.md",
+  "workstream_dir": "tasks/workstreams/verification/evals-checks",
+  "contract_agents": "AGENTS.md",
+  "contract_claude": "CLAUDE.md",
+  "change_type": "workflow-surface",
+  "request_file": "docs/architecture/requests/verification-evals-checks.md",
+  "spawn_recommended": true,
+  "contract_sync_required": true
+}
+```
+
+## Archive Resolution
+
+- Status: Resolved
+- Archived: 2026-06-12T03:36:04+0800
+- Artifacts:
+- `docs/architecture/modules/verification/evals-checks.md`
+- Note: Required-file checks and focused tests now track architecture-queue.sh.

package/docs/architecture/requests/archive/2026/workflow-engine-contract-assets.md

@@ -0,0 +1,69 @@
+# Architecture Queue Card: workflow-engine-contract-assets
+
+> **Status**: Resolved
+> **Detected**: 2026-05-28T16:18:51+0800
+> **Updated**: 2026-05-28T16:19:11+0800
+> **Severity**: high
+> **Change Type**: workflow-surface
+> **File**: `assets/workflow-contract.v1.json`
+> **Functional Block**: `assets/workflow-contract.v1.json`
+> **Capability ID**: `workflow-engine-contract-assets`
+> **Matched Prefix**: `assets/workflow-contract.v1.json`
+> **Architecture Domain**: `workflow-engine`
+> **Architecture Capability**: `contract-assets`
+> **Architecture Module**: `docs/architecture/modules/workflow-engine/contract-assets.md`
+> **Workstream Directory**: `tasks/workstreams/workflow-engine/contract-assets`
+> **Contract Files**: `AGENTS.md`, `CLAUDE.md`
+> **Contract Sync Required**: true
+> **Spawn Recommended**: true
+> **Open Edits**: 2
+
+## Required Follow-up
+
+- Read root `AGENTS.md` / `CLAUDE.md`.
+- If functional block is not `root`, read its local `AGENTS.md` / `CLAUDE.md`.
+- Decide whether this change affects module boundaries, entrypoints, dependency rules, runtime paths, or verification commands.
+- For substantial changes, write a snapshot under `docs/architecture/snapshots/`.
+- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.
+- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.
+- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.
+- If this starts or advances durable execution, run `scripts/workstream-sync.sh ensure --block "assets/workflow-contract.v1.json" --request "docs/architecture/requests/workflow-engine-contract-assets.md"`.
+- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.
+
+## Touched Files
+
+| Last Event | Severity | Change Type | File |
+| --- | --- | --- | --- |
+| 2026-05-28T16:19:11+0800 | high | workflow-surface | `assets/workflow-contract.v1.json` |
+| 2026-05-28T16:18:51+0800 | high | workflow-surface | `.ai/harness/workflow-contract.json` |
+
+## Event Fields
+
+```json
+{
+  "ts": "2026-05-28T16:19:11+0800",
+  "file_path": "assets/workflow-contract.v1.json",
+  "severity": "high",
+  "functional_block": "assets/workflow-contract.v1.json",
+  "capability_id": "workflow-engine-contract-assets",
+  "matched_prefix": "assets/workflow-contract.v1.json",
+  "architecture_domain": "workflow-engine",
+  "architecture_capability": "contract-assets",
+  "architecture_module": "docs/architecture/modules/workflow-engine/contract-assets.md",
+  "workstream_dir": "tasks/workstreams/workflow-engine/contract-assets",
+  "contract_agents": "AGENTS.md",
+  "contract_claude": "CLAUDE.md",
+  "change_type": "workflow-surface",
+  "request_file": "docs/architecture/requests/workflow-engine-contract-assets.md",
+  "spawn_recommended": true,
+  "contract_sync_required": true
+}
+```
+
+## Archive Resolution
+
+- Status: Resolved
+- Archived: 2026-06-12T03:36:05+0800
+- Artifacts:
+- `docs/architecture/modules/workflow-engine/contract-assets.md`
+- Note: Workflow contract and helper inventory now use architecture-queue.sh.

package/docs/architecture/reviews/2026-07-11-access-surface-review.md

@@ -0,0 +1,99 @@
+# Access and Public Surface Architecture Review — 2026-07-11
+
+## Verdict
+
+The Work permission snapshot is directionally correct: Goal Workloop stores `constraints.accessMode` when the WorkContract starts, and later operations continue to use that captured mode. The current product surface is nevertheless blocked by the following architecture gaps.
+
+## Confirmed findings
+
+### P0 — Thin Gateway is not thin at discovery time
+
+`DEFAULT_CONTROLLER_TOOL_NAMES` points to `STABLE_CONTROLLER_TOOL_NAMES`. That set includes repository editing, command execution, Git, Issue/Task, Campaign, plugin, browser, iOS, recovery, and maintenance tools. `core` and `advanced` also resolve to the same set.
+
+Impact:
+
+- ChatGPT and other MCP clients still choose among a large ambiguous tool surface.
+- Schema and prompt cost grows with every internal capability.
+- Product facade and compatibility APIs are indistinguishable at discovery time.
+- There is no real small facade profile for constrained clients.
+
+Required follow-up:
+
+1. Define a real facade/bootstrap public profile.
+2. Keep the broad compatibility surface opt-in.
+3. Make the `thin` readiness claim depend on the served profile, not only schema consistency.
+
+### P0 — “Start execution” does not establish execution
+
+`rh_work.start` and the Local Controller `/work/start` path route through `routeWorkStart`. Direct Control returns an edit recommendation without applying it. Goal Workloop creates a WorkContract, but repository execution requires a separate delegate or advanced tool. The GUI button is labelled “开始执行”, which promises more than the facade guarantees.
+
+Impact:
+
+- A user can receive a running WorkContract with no executor attached.
+- `continue` may only recommend context, verification, or finalization.
+- The facade-only path cannot complete an ordinary repository change by itself.
+
+Required follow-up:
+
+1. Add an explicit execution transition to `rh_work` that dispatches the selected editor or worker.
+2. Persist dispatch and mutation evidence on the WorkContract.
+3. Either make GUI Start atomically create and dispatch, or rename it to “创建任务” and show `created_not_dispatched`.
+
+### P1 — Request approval could be bypassed by omitted caller hints
+
+The policy gate returns `approval_required` for Request-mode workspace writes. The work router previously created a handoff only when the caller also supplied `requiresApproval`, `requiresUserApproval`, destructive, remote, or secret flags. A normal multi-file Request-mode workloop could therefore create a running WorkContract despite the policy decision.
+
+Resolved in this change:
+
+- Every `approval_required` policy decision blocks WorkContract creation.
+- The approval handoff preserves the access-mode snapshot for replay.
+- A targeted regression test covers callers that omit the approval hint.
+
+### P1 — Access preview returned contradictory toolset data
+
+The preview target hard-coded `effectiveToolset: full`, while the effective controller compatibility label is `advanced`, and the same payload reported `toolsetChanged: false`.
+
+Resolved in this change:
+
+- Preview reports the current effective toolset because Request versus Full Access changes approval policy, not schema/toolset.
+
+### P1 — Verification evidence is not mutation evidence
+
+`hasExecutionEvidence` treats any check record as execution evidence. A WorkContract may therefore pass a check and finalize without recorded edit, worker dispatch, worktree, or changed-file evidence. That may be valid for read-only review work but is insufficient for mutation objectives.
+
+Required follow-up:
+
+1. Classify each WorkContract as read-only or mutating.
+2. Require mutation evidence for mutation objectives.
+3. Do not infer source execution from a check record alone.
+
+### P1 — Access configuration has two sources of truth
+
+The facade persists both MCP service-level access mode and per-repository policy. Repository execution reads the repository policy, while diagnostics also expose service-level state. These can diverge across repository-only changes or mixed repository policies.
+
+Required follow-up:
+
+1. Make per-repository policy the effective execution source of truth.
+2. Treat service-level mode only as an onboarding/default value and name it accordingly.
+3. Display mixed repository state explicitly.
+
+## Usage-surface assessment
+
+| Scenario | Current behavior | Assessment |
+| --- | --- | --- |
+| Read/search repository | Works | Not blocked |
+| Small bounded edit in Request | Policy permits it, but facade only recommends an edit | Execution blocked |
+| Multi-file local work in Request | Requests approval | Fixed in this change |
+| Normal local development in Full Access | Policy permits it; facade still needs a separate executor path | Partially blocked |
+| Existing Work after mode switch | Keeps captured access mode | Correct |
+| Remote/destructive/secret effects | Remain gated or denied | Correct |
+| Client requiring a small MCP schema | No real small default profile | Blocked |
+| GUI user clicking “开始执行” | May only create orchestration state | Misleading/blocking |
+
+## Recommended implementation order
+
+1. Make `rh_work.start` atomically dispatch, or return explicit `created_not_dispatched` state.
+2. Introduce a real facade/bootstrap profile and move the broad schema behind opt-in compatibility mode.
+3. Separate mutation evidence from verification evidence.
+4. Consolidate global default and per-repository effective access semantics.
+5. Add one end-to-end acceptance path: objective → dispatch → mutation evidence → checks → finalize → commit/merge/cleanup.

package/docs/architecture/snapshots/.gitkeep

@@ -0,0 +1 @@
+

package/docs/forge-autonomous-goal-loop.md

@@ -0,0 +1,7 @@
+# Forge Goal Loop
+
+Forge supports bounded goal progression through durable Goal, Work, Process, evidence, policy, and handoff records. The kernel does not recursively invent unlimited work, select arbitrary models, or bypass authorization. Semantic planning and provider selection belong to the external controller; deterministic repository and provider operations remain Forge-owned.
+
+Every continuation must have a finite objective, resource scope, budget, stop condition, and reviewable evidence. Remote or destructive effects stay separately authorized.
+
+See [Dispatch and Agent Strategy](architecture/current/dispatch-and-agent-strategy.md), [Schedule Engine](architecture/current/automation-and-schedule-engine.md), and [Governance](architecture/current/governance.md).

package/docs/forge-chatgpt-browser-engine.md

@@ -0,0 +1,11 @@
+# Forge ChatGPT Browser Engine
+
+Forge exposes browser automation through the bundled `browser` capability, the stable plugin action surface, and bounded Process Runtime execution. Browser actions remain policy-scoped, domain-allowlisted, timeout-bounded, and evidence-producing. Human login, MFA, CAPTCHA, consent, or device approval uses the Human Interaction Plane rather than hidden automation.
+
+Authoritative references:
+
+- [Browser plugin operations](operations/controller-browser-plugin.md)
+- [Human Interaction Plane](architecture/current/human-interaction-plane.md)
+- [Plugin baseline](architecture/current/personal-assistant-plugin-baseline.md)
+
+The browser engine is not a second controller, Runtime, plugin marketplace, or lifecycle owner.