@moretea-labs/forge 1.7.2 → 1.8.1

package/docs/architecture/history/ios-semantic-automation-provider-v2.md

@@ -1,170 +0,0 @@
-# iOS Semantic Automation Provider v2
-
-Status: **Historical Design Evidence — Not Runtime Authority**
-
-Archived after the still-current physical-device ownership, capability-negotiation, failure-disposition, and evidence invariants were folded into [`../CURRENT.md`](../CURRENT.md) from current source. The original implementation-stage terminology and legacy product identity below are retained only as historical rationale.
-
-Historical snapshot status: implementation in progress
-Historical issue: `ISS-20260720-66E25D` / `T5`
-
-## Why this redesign exists
-
-The 2026-08-01 physical-device test produced evidence that the current integration is not merely missing a selector. The failure surface crosses executable identity, CLI contract drift, XCTest lifecycle, snapshot policy, semantic targeting, session disposition and fallback routing.
-
-Observed facts:
-
-- The same Mac had Homebrew `agent-device 0.19.3` and Volta `0.20.2`; different processes resolved different executables.
-- `snapshot -i` is supported, while `snapshot --interactive` is not supported by the installed 0.19.3/0.20.2 CLI contracts.
-- A shallow JD snapshot returned only 18 nodes and missed search. A depth-20 raw snapshot returned 204 nodes, found the SearchField and completed in about 533 ms on the warm Runner.
-- Rebooting the physical iPhone restored an XCTest/DTX channel that had failed across two Xcode versions and two agent-device versions.
-- CoreDevice open and screenshot remained available while XCTest UI automation was unavailable.
-- A semantic fill error was redacted into an opaque generic error and the wrapper destroyed the otherwise healthy session.
-
-## Defect ownership
-
-### Repo Harness adapter defects
-
-1. Exact version pinning instead of capability negotiation.
-2. No executable identity or CLI-contract fingerprint in status/evidence.
-3. Raw argv construction spread across workflow code.
-4. Unsupported `--interactive` emitted by recovery code while the generic snapshot path used `-i`.
-5. JD target discovery used a shallow default snapshot despite an App-specific tree shape.
-6. Element extraction parsed formatted strings instead of structured snapshot nodes.
-7. Every command error invoked `failSession`, conflating semantic misses with transport death.
-8. Fill diagnostics removed provider code and all actionable redacted context.
-9. App workflow, provider transport, signing, lifecycle, selector logic and MCP descriptors live in one 1,700+ line module.
-10. CoreDevice facts and optional WDA UI automation form a second partially overlapping physical-device stack.
-
-### Upstream agent-device candidates
-
-These require upstream-source tests before a fork is justified:
-
-- XCTest/DTX startup recovery and health probing.
-- Xcode/devicectl version-specific relaunch or process termination behavior.
-- Stable machine-readable fill/press error codes from the iOS Runner.
-- Batch support for keyboard Return and richer capability discovery.
-
-Repo Harness must not fork upstream to fix defects that belong in its own adapter.
-
-## Target architecture
-
-```text
-MCP iOS actions (stable public IDs)
-        |
-        v
-IOS Plugin Router
-        |
-        +-- App Adapter Registry
-        |     +-- JD search semantics and snapshot policy
-        |     +-- future application adapters
-        |
-        +-- Provider Router
-              +-- AgentDeviceProvider
-              |     +-- executable identity
-              |     +-- capability/help fingerprint
-              |     +-- typed/CLI command compiler
-              |     +-- session and Runner lifecycle
-              |     +-- semantic snapshot and mutation APIs
-              |
-              +-- CoreDeviceProvider
-                    +-- paired-device facts
-                    +-- app lifecycle
-                    +-- screenshot evidence
-                    +-- no implicit mutation fallback
-```
-
-The normal trusted path is deterministic:
-
-```text
-intent -> App capability -> compiled semantic batch -> minimal assertion -> receipt
-```
-
-No model call, screenshot analysis or complete tree dump belongs on a known warm path.
-
-## Capability negotiation
-
-Provider readiness is based on:
-
-- resolved executable/configured path;
-- parsed semantic version within a reviewed compatibility range;
-- command help or typed contract for snapshot, fill, batch and keyboard;
-- runtime compatibility before resolving the optional typed module (`agent-device@0.20.2` requires Node 22.12 or newer while Repo Harness still supports Node 20);
-- a stable contract fingerprint cached with a short TTL and bound to executable, backend mode, Node runtime and PATH identity.
-
-A preferred version is useful for support, but it is not authority. Commands are emitted only when their capability is present. Unknown future minor versions fail closed until reviewed.
-
-## App adapters
-
-App adapters own semantic knowledge, not provider mechanics. A search adapter declares:
-
-- bundle ID;
-- bounded discovery snapshot policy;
-- stable selector candidates;
-- structured-node predicates;
-- submit and result assertions;
-- known interruption handlers in later phases.
-
-JD currently requires a depth-20 structured discovery because the real SearchField is nested around depth 14. Callers that supply a trusted selector skip discovery entirely.
-
-## Resource ownership and engine identity
-
-`ios-device` remains the single physical-iPhone ownership domain. CoreDevice/WDA and agent-device/XCTest must never create independent locks for the same target because that would permit concurrent input or cleanup against one phone.
-
-The interaction record therefore separates:
-
-- `provider`: the mutually exclusive resource domain (`ios-device` or `ios-simulator`);
-- `engine`: the execution implementation (`coredevice` or `agent-device`).
-
-New iOS interactions always write an explicit engine. Schema-v1 records created before this field existed remain readable only through bounded provider + interaction-prefix + reason inference. An explicit unknown or mismatched engine fails closed. Resource matching uses immutable, case-normalized target aliases rather than assuming CoreDevice `identifier`, agent-device provider ID and hardware UDID are the same string; CoreDevice records both its internal identifier and hardware UDID, while agent-device records its provider ID plus `ios.udid`/identifier aliases from inventory. An active legacy `ios-device` record without trustworthy aliases conservatively blocks another physical-device acquisition because the engines cannot prove that two differing internal IDs name different phones. Cross-engine conflicts are rejected before app launch or UI mutation, and conflict evidence reports both the resource provider and automation engine.
-
-## Session failure disposition
-
-Command failure and session failure are different facts.
-
-| Failure class | Session disposition |
-|---|---|
-| element/selector not found, stale ref, unsupported semantic action | preserve session |
-| Runner/DTX/transport/device disconnect, provider session absent | terminate or reconcile session |
-| timeout/cancel/unknown mutation outcome | fence as unknown; do not blindly retry |
-
-Only provider or transport death justifies automatic session teardown. Recoverable semantic failures return redacted diagnostics with `sessionPreserved: true`.
-
-## Evidence and privacy
-
-- Fill text is never returned or persisted.
-- Provider error code and sanitized message are retained.
-- Normal success stores bounded receipt data, not every full tree.
-- Failure fixtures are scrubbed and stored without account, badge or personalized product-history data.
-- Screen text is data, never executable instruction.
-
-## CoreDevice fallback
-
-CoreDevice is the source of truth for device inventory, pairing, connection, app installation/launch and screenshot capture. When XCTest is unavailable, Repo Harness may still open an allowlisted app and capture read-only evidence. It must not imply that screenshot-only mode can perform semantic mutations.
-
-## Upstream integration policy
-
-Prefer the official typed `createAgentDeviceClient` surface where package deployment and versioning can be made deterministic. The current integration uses it for read-only snapshots on compatible Node runtimes. Mutations remain on the cancellable CLI process path because the typed client does not currently expose an `AbortSignal`; this preserves the unknown-outcome fence instead of trading reliability for fewer argv calls. `auto` falls back to CLI only when the optional typed module is absent, unloadable, runtime-incompatible, or its package version does not exactly match the active CLI version. Every fallback returns a bounded `backendFallbackReason` plus typed/CLI versions; a real typed provider command failure is surfaced and never hidden by backend switching.
-
-Keep a CLI adapter for compatibility. A fork, if required, is a separate version-pinned provider package with:
-
-- upstream commit reference;
-- minimal patch set;
-- differential contract tests;
-- a documented removal path.
-
-Global installations are never edited in place.
-
-## Verification serialization
-
-Edit Session validation for this subsystem must be the sole owner of the checkout workspace and repository build-cache claims while its named checks run. Because the build cache is repository-scoped, the quiet window covers every checkout and managed worktree of the same repository, not only the checkout being verified. Focused tests or manually started package checks must finish and release their Process Runtime leases before `verify_edit_session` starts.
-
-A lease conflict is infrastructure and coordination failure evidence, not a source acceptance failure. `verify_task` returns `verification_deferred` before writing Task verification, exposes the bounded conflicting Process and a deterministic fresh retry request ID, and preserves real failed checks as authoritative. Existing Process receipts remain immutable; the fresh request ID prevents a retry from reusing the terminal conflicted Process. Edit Session verification also requires its orchestration receipt to be durably attached before a completed Process request may be reused after transport recovery; an orphaned completed request must not be silently treated as a failed source check. Recovery should advance to a newly reviewed revision or use an explicit receipt-reattachment protocol rather than reusing a request ID whose Process record exists without an Edit Session check result.
-
-## Migration phases
-
-1. Capability profile, command compiler, structured App adapters and failure disposition.
-2. Split the monolith into provider/session/semantic/workflow modules while retaining public action IDs.
-3. Introduce optional typed-client backend and differential tests against CLI.
-4. Separate interaction resource identity from backend identity and converge CoreDevice fallback routing. **Implemented:** shared `ios-device` ownership is retained while records declare `coredevice` or `agent-device` engine identity.
-5. Add upstream fork only for proven lower-layer defects.
-6. Re-run physical-device cold/warm benchmarks and publish p50/p95 phase evidence locally.

package/docs/architecture/requests/archive/2026/20260528-154740-ai-hooks-ai-hooks-hook-input-sh.md

@@ -1,59 +0,0 @@
-# Architecture Drift Request: 20260528-154740-ai-hooks-ai-hooks-hook-input-sh
-
-> **Status**: Superseded
-> **Detected**: 2026-05-28T15:47:40+0800
-> **Severity**: high
-> **Change Type**: workflow-surface
-> **File**: `.ai/hooks/hook-input.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, generate one standalone `$mermaid` architecture HTML file under `docs/architecture/diagrams/`.
-- 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/20260528-154740-ai-hooks-ai-hooks-hook-input-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-28T15:47:40+0800",
-  "file_path": ".ai/hooks/hook-input.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/20260528-154740-ai-hooks-ai-hooks-hook-input-sh.md",
-  "spawn_recommended": true,
-  "contract_sync_required": true
-}
-```
-
-## Archive Resolution
-
-- Status: Superseded
-- Archived: 2026-06-12T03:29:01+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/20260528-154816-assets-hooks-assets-hooks-hook-input-sh.md

@@ -1,59 +0,0 @@
-# Architecture Drift Request: 20260528-154816-assets-hooks-assets-hooks-hook-input-sh
-
-> **Status**: Superseded
-> **Detected**: 2026-05-28T15:48:16+0800
-> **Severity**: high
-> **Change Type**: workflow-surface
-> **File**: `assets/hooks/hook-input.sh`
-> **Functional Block**: `assets/hooks`
-> **Capability ID**: `runtime-harness-hook-adapters`
-> **Matched Prefix**: `assets/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, generate one standalone `$mermaid` architecture HTML file under `docs/architecture/diagrams/`.
-- 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/hooks" --request "docs/architecture/requests/20260528-154816-assets-hooks-assets-hooks-hook-input-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-28T15:48:16+0800",
-  "file_path": "assets/hooks/hook-input.sh",
-  "severity": "high",
-  "functional_block": "assets/hooks",
-  "capability_id": "runtime-harness-hook-adapters",
-  "matched_prefix": "assets/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/20260528-154816-assets-hooks-assets-hooks-hook-input-sh.md",
-  "spawn_recommended": true,
-  "contract_sync_required": true
-}
-```
-
-## Archive Resolution
-
-- Status: Superseded
-- Archived: 2026-06-12T03:29:01+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/20260528-161851-ai-harness-workflow-contract-json-ai-harness-workflow-contract-json.md

@@ -1,59 +0,0 @@
-# Architecture Drift Request: 20260528-161851-ai-harness-workflow-contract-json-ai-harness-workflow-contract-json
-
-> **Status**: Superseded
-> **Detected**: 2026-05-28T16:18:51+0800
-> **Severity**: high
-> **Change Type**: workflow-surface
-> **File**: `.ai/harness/workflow-contract.json`
-> **Functional Block**: `.ai/harness/workflow-contract.json`
-> **Capability ID**: `workflow-engine-contract-assets`
-> **Matched Prefix**: `.ai/harness/workflow-contract.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
-
-## 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, generate one standalone `$mermaid` architecture HTML file under `docs/architecture/diagrams/`.
-- 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/harness/workflow-contract.json" --request "docs/architecture/requests/20260528-161851-ai-harness-workflow-contract-json-ai-harness-workflow-contract-json.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-28T16:18:51+0800",
-  "file_path": ".ai/harness/workflow-contract.json",
-  "severity": "high",
-  "functional_block": ".ai/harness/workflow-contract.json",
-  "capability_id": "workflow-engine-contract-assets",
-  "matched_prefix": ".ai/harness/workflow-contract.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/20260528-161851-ai-harness-workflow-contract-json-ai-harness-workflow-contract-json.md",
-  "spawn_recommended": true,
-  "contract_sync_required": true
-}
-```
-
-## Archive Resolution
-
-- Status: Superseded
-- Archived: 2026-06-12T03:29:01+0800
-- Artifacts:
-- `docs/architecture/requests/workflow-engine-contract-assets.md`
-- Note: Merged into architecture queue card by triage --before 2026-06-01.

package/docs/architecture/requests/archive/2026/20260528-161853-scripts-check-task-workflow-sh-scripts-check-task-workflow-sh.md

@@ -1,59 +0,0 @@
-# Architecture Drift Request: 20260528-161853-scripts-check-task-workflow-sh-scripts-check-task-workflow-sh
-
-> **Status**: Superseded
-> **Detected**: 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
-
-## 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, generate one standalone `$mermaid` architecture HTML file under `docs/architecture/diagrams/`.
-- 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/20260528-161853-scripts-check-task-workflow-sh-scripts-check-task-workflow-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-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/20260528-161853-scripts-check-task-workflow-sh-scripts-check-task-workflow-sh.md",
-  "spawn_recommended": true,
-  "contract_sync_required": true
-}
-```
-
-## Archive Resolution
-
-- Status: Superseded
-- Archived: 2026-06-12T03:29:02+0800
-- Artifacts:
-- `docs/architecture/requests/verification-evals-checks.md`
-- Note: Merged into architecture queue card by triage --before 2026-06-01.

package/docs/architecture/requests/archive/2026/20260528-161911-assets-workflow-contract-v1-json-assets-workflow-contract-v1-json.md

@@ -1,59 +0,0 @@
-# Architecture Drift Request: 20260528-161911-assets-workflow-contract-v1-json-assets-workflow-contract-v1-json
-
-> **Status**: Superseded
-> **Detected**: 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
-
-## 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, generate one standalone `$mermaid` architecture HTML file under `docs/architecture/diagrams/`.
-- 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/20260528-161911-assets-workflow-contract-v1-json-assets-workflow-contract-v1-json.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-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/20260528-161911-assets-workflow-contract-v1-json-assets-workflow-contract-v1-json.md",
-  "spawn_recommended": true,
-  "contract_sync_required": true
-}
-```
-
-## Archive Resolution
-
-- Status: Superseded
-- Archived: 2026-06-12T03:29:02+0800
-- Artifacts:
-- `docs/architecture/requests/workflow-engine-contract-assets.md`
-- Note: Merged into architecture queue card by triage --before 2026-06-01.

package/docs/architecture/requests/archive/2026/20260528-222416-ai-hooks-ai-hooks-hook-input-sh.md

@@ -1,59 +0,0 @@
-# Architecture Drift Request: 20260528-222416-ai-hooks-ai-hooks-hook-input-sh
-
-> **Status**: Superseded
-> **Detected**: 2026-05-28T22:24:16+0800
-> **Severity**: high
-> **Change Type**: workflow-surface
-> **File**: `.ai/hooks/hook-input.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, generate one standalone `$mermaid` architecture HTML file under `docs/architecture/diagrams/`.
-- 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/20260528-222416-ai-hooks-ai-hooks-hook-input-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-28T22:24:16+0800",
-  "file_path": ".ai/hooks/hook-input.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/20260528-222416-ai-hooks-ai-hooks-hook-input-sh.md",
-  "spawn_recommended": true,
-  "contract_sync_required": true
-}
-```
-
-## Archive Resolution
-
-- Status: Superseded
-- Archived: 2026-06-12T03:29:02+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/20260528-222444-ai-hooks-ai-hooks-pre-edit-guard-sh.md

@@ -1,59 +0,0 @@
-# Architecture Drift Request: 20260528-222444-ai-hooks-ai-hooks-pre-edit-guard-sh
-
-> **Status**: Superseded
-> **Detected**: 2026-05-28T22:24:44+0800
-> **Severity**: high
-> **Change Type**: workflow-surface
-> **File**: `.ai/hooks/pre-edit-guard.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, generate one standalone `$mermaid` architecture HTML file under `docs/architecture/diagrams/`.
-- 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/20260528-222444-ai-hooks-ai-hooks-pre-edit-guard-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-28T22:24:44+0800",
-  "file_path": ".ai/hooks/pre-edit-guard.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/20260528-222444-ai-hooks-ai-hooks-pre-edit-guard-sh.md",
-  "spawn_recommended": true,
-  "contract_sync_required": true
-}
-```
-
-## Archive Resolution
-
-- Status: Superseded
-- Archived: 2026-06-12T03:29:02+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/20260528-222457-ai-hooks-ai-hooks-pre-edit-guard-sh.md

@@ -1,59 +0,0 @@
-# Architecture Drift Request: 20260528-222457-ai-hooks-ai-hooks-pre-edit-guard-sh
-
-> **Status**: Superseded
-> **Detected**: 2026-05-28T22:24:57+0800
-> **Severity**: high
-> **Change Type**: workflow-surface
-> **File**: `.ai/hooks/pre-edit-guard.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, generate one standalone `$mermaid` architecture HTML file under `docs/architecture/diagrams/`.
-- 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/20260528-222457-ai-hooks-ai-hooks-pre-edit-guard-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-28T22:24:57+0800",
-  "file_path": ".ai/hooks/pre-edit-guard.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/20260528-222457-ai-hooks-ai-hooks-pre-edit-guard-sh.md",
-  "spawn_recommended": true,
-  "contract_sync_required": true
-}
-```
-
-## Archive Resolution
-
-- Status: Superseded
-- Archived: 2026-06-12T03:29:02+0800
-- Artifacts:
-- `docs/architecture/requests/runtime-harness-hook-adapters.md`
-- Note: Merged into architecture queue card by triage --before 2026-06-01.