apache · Astro-Han · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026
diff --git a/apps/desktop/src/main/__tests__/composer-mention-contract.test.ts b/apps/desktop/src/main/__tests__/composer-mention-contract.test.ts
@@ -1,6 +1,6 @@
 /**
  * Contract for the composer `@`/`/` mention popups
- * (feat/composer-mentions, notes/composer-mentions-spec-2026-07-14.md).
+ * (feat/composer-mentions, docs/archive/composer-mentions-spec-2026-07-14.md).
  *
  * Pins the fragile ordering + SSR-safety guarantees:
  *   1. The mention-popup keyboard branch runs BEFORE the Esc/drag branch and

diff --git a/docs/README.md b/docs/README.md
@@ -27,8 +27,18 @@ This page is the authority map for Maka documentation. Code and contract tests r
 - [Execution identity and evidence spine](./execution-evidence-spine.md)
 - [AHE target protocol and evidence export](./ahe-target-protocol.md)
 - [Skill catalog policy](./skill-catalog-policy.md)
+- [Expert teams runtime](./expert-team-runtime.md)
 - [Backend architecture chapters](./architecture/)
 
+### Computer use
+
+- [Foundation contract](./computer-use-foundation-contract.md)
+- [Model-loop foundation](./computer-use-model-loop-foundation.md)
+- [Evidence classes](./computer-use-evidence-classes.md)
+- [Provider evidence contract](./computer-use-provider-evidence.md)
+- [Host events contract](./computer-use-host-events-contract.md)
+- [cua-driver artifact integrity](./cua-driver-artifact-integrity.md)
+
 ### Frontend and validation
 
 - [Product design](../DESIGN.md)
@@ -54,3 +64,4 @@ This page is the authority map for Maka documentation. Code and contract tests r
 - Keep progress and TODOs in issues or pull requests instead of copying them into stable documents.
 - Move completed plans to `docs/archive/`; remove a document only after its unique references are updated or no longer needed.
 - Prefer updating an existing authority over adding a parallel document.
+- Keep PR follow-up records, incident investigations, and run logs in the pull request or `docs/archive/`, not as new current contracts. `notes/` and `docs/local/` are workspace-local scratch and stay untracked.
diff --git a/docs/archive/README.md b/docs/archive/README.md
@@ -23,6 +23,9 @@ The root `DESIGN.md` owns shared product design intent. `docs/frontend-css-gover
 
 Tracked `notes/` files were retired as an undocumented parallel authority. Point-in-time audits, migration plans, reference reverse-engineering, and design research remain here only for provenance. Current repository rules live in `ARCHITECTURE.md`, `DESIGN.md`, active cross-cutting contracts, local READMEs, source, and tests; workspace-specific agent instructions are supplied outside the tracked documentation set.
 
+- `frontend-simplification-map-2026-07-13.md` — baseline knip/size measurement for the frontend simplification rounds landed in #871–#887.
+- `composer-mentions-spec-2026-07-14.md` — the shipped v1 `@`/`/` composer mention-popup spec (#979); current behavior lives in `packages/ui` source and the composer-mention contract test.
+
 ## Security contract snapshots
 
 - `memory-threat-model-pr-memory-1.md` — the contract-only PR-MEMORY-1 boundary, superseded as a description of the current product.
@@ -42,3 +45,23 @@ The dated runtime and sandbox files are completed execution plans. Each file rec
 `runtime-v2-implementation-notes.md` records the initial Phase 1–4 runtime skeleton and is superseded by the backend architecture chapters and current source.
 
 `agent-runtime-codex-sandbox-alignment.md` and `agent-runtime-codex-sandbox-todo.md` preserve the original sandbox discussion and phased checklist. Stable boundaries now live beside the runtime implementation; remaining work is tracked in issue #843.
+
+## Computer use follow-up records
+
+The computer-use follow-up files are per-PR follow-up records, incident investigations, and run logs from the #857–#985 delivery chain. Current computer-use authority lives in the contracts listed in `../README.md` and in source and contract tests.
+
+- `computer-use-delivery-state.md` — `outcome_unknown` delivery-state follow-up; postcondition semantics are owned by the foundation contract and runtime tests.
+- `computer-use-evidence-hardening.md` — fail-closed report hardening; the current boundary is owned by the provider evidence contract and evidence classes.
+- `computer-use-executor-hardening.md` — post-merge review record of PR #893; durable decisions are folded into the foundation contract and the model-loop foundation, remaining work belongs in issues.
+- `computer-use-runtime-hardening.md` — lifecycle fix record of PR #892; current fencing is owned by runtime source and tests.
+- `computer-use-physical-input-guard.md` — physical-input interference incident and the guard policy it produced.
+- `computer-use-process-restart-e2e.md` — process-restart soak goal, investigation, and run logs; the PID-reuse non-claim is restated in the host events contract.
+- `computer-use-real-ax-model-e2e.md` — real-model AppKit AX harness record and provider run logs; current evidence classes and operator commands live in `../computer-use-evidence-classes.md`.
+
+## Reverse-engineering records
+
+- `expert-team-plan.md` and `expert-team-implementation.md` — WorkBuddy and QoderWork reverse-engineering and mapping notes behind the expert-teams feature. The shipped design contract is `../expert-team-runtime.md` (#971).
+
+## Benchmark logs
+
+- `economic-mechanisms-benchmark.md` — the first synthesis-cache benchmark entry for economic-mechanisms tracking issue #481 and slice #578. Current progress belongs in those issues.
diff --git a/notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md b/notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md
diff --git a/docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md b/docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md
diff --git a/docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md b/docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md
diff --git a/docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md b/docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md
diff --git a/docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md b/docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md
diff --git a/docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md b/docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md
diff --git a/docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md b/docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md
diff --git a/docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md b/docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md
diff --git a/docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md b/docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md
diff --git a/docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md b/docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md
diff --git a/docs/expert-team-plan.md → docs/archive/expert-team-plan.md b/docs/expert-team-plan.md → docs/archive/expert-team-plan.md
diff --git a/...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md b/...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md
diff --git a/docs/computer-use-foundation-contract.md b/docs/computer-use-foundation-contract.md
@@ -67,6 +67,8 @@
 
 `PASS`：当前证据直接覆盖；`PARTIAL`：组件证据存在但 production 闭环不足；`FAIL`：当前实现违反合同；`UNKNOWN`：缺少足够证据。
 
+本矩阵记录 #857 拆分链建立时的基线状态，用于界定各 stacked PR 的验证责任。拆分链合入后，各领域当前状态以源码与合同测试为准。
+
 | Contract area | 状态 | 当前证据 | 拆分链需要的证据 |
 |---|---|---|---|
 | Frame/window binding、duplicate rejection | PASS | frame state、bound-action、stale/duplicate tests | 在 Runtime slice 保留 focused tests |

diff --git a/docs/expert-team-runtime.md b/docs/expert-team-runtime.md
@@ -3,7 +3,7 @@
 Expert teams let a **lead** persona fan a task out to specialist **member** experts,
 each running as a tool-scoped child agent, then synthesize their results. It is the
 star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's
-sub-agent pipelines (see [expert-team-implementation.md](expert-team-implementation.md)),
+sub-agent pipelines (see [expert-team-implementation.md](archive/expert-team-implementation.md)),
 rebuilt entirely on Maka's existing child-agent machinery — no new orchestration
 engine, no mesh mailbox, no shared task board.
 

diff --git a/packages/runtime/src/__tests__/ai-sdk-backend.test.ts b/packages/runtime/src/__tests__/ai-sdk-backend.test.ts
@@ -1089,7 +1089,7 @@ describe('AiSdkBackend model history', () => {
     // is the synthesis cache's replay-token saving — no live model or network,
     // so the number is reproducible in CI. (Live Terminal-Bench runs can't drive
     // this: their single-long-turn shape never archives-then-retrieves a turn, so
-    // the write path stays source_missing — see docs/economic-mechanisms-benchmark.md.)
+    // the write path stays source_missing — see docs/archive/economic-mechanisms-benchmark.md.)
     const CHARS_PER_TOKEN = 1; // 1:1 so prompt chars are directly the token estimate
     const archivedResult = { body: 'RAW_SYNTHESIS_ARCHIVE_PAYLOAD '.repeat(80).trim() };
     const serialized = JSON.stringify(archivedResult);

diff --git a/packages/ui/src/chat-input-behavior.ts b/packages/ui/src/chat-input-behavior.ts
@@ -31,7 +31,7 @@ export function focusTextInputAtEnd(input: TextInputSelectionTarget): void {
  * Composer `@` / `/` mention trigger detection.
  *
  * Decompiled from the QoderWork/WorkBuddy composer bundles and adapted to our
- * plain-text v1 (see notes/composer-mentions-spec-2026-07-14.md). Pure so it
+ * plain-text v1 (see docs/archive/composer-mentions-spec-2026-07-14.md). Pure so it
  * can be unit-pinned without a DOM: given the current textarea value + caret
  * offset it reports the active trigger, the query typed after it, and the
  * trigger char's index (so the caller can splice `[start, caret)` on select).

diff --git a/packages/ui/src/composer-mention-popup.tsx b/packages/ui/src/composer-mention-popup.tsx
@@ -1,7 +1,7 @@
 /**
  * Composer `@` file / `/` skill mention popup — a presentational overlay
  * rendered by Composer while a trigger is active. See
- * notes/composer-mentions-spec-2026-07-14.md for the v1 plain-text model.
+ * docs/archive/composer-mentions-spec-2026-07-14.md for the v1 plain-text model.
  *
  * All state (which trigger, the filtered items, the highlighted index) lives in
  * Composer; this component only paints the list and forwards hover/click to

diff --git a/packages/ui/src/composer.tsx b/packages/ui/src/composer.tsx
@@ -232,7 +232,7 @@ export const Composer = forwardRef<
     onPermissionModeChange?(mode: PermissionMode): void | Promise<void>;
     /**
      * Composer mention popups (v1 plain-text tokens; see
-     * notes/composer-mentions-spec-2026-07-14.md). Both are optional and the
+     * docs/archive/composer-mentions-spec-2026-07-14.md). Both are optional and the
      * whole feature no-ops when absent (SSR contracts render Composer with
      * minimal props):
      *   - `mentionSkills` powers the `/` popup — pass only ENABLED skills; the