From 3a4be7623e10abc17337c8ed9791f01eb5a021f2 Mon Sep 17 00:00:00 2001 From: AstroHan Date: Thu, 16 Jul 2026 11:43:16 +0800 Subject: [PATCH 1/3] docs: retire tracked notes into the archive notes/ regrew tracked files after the archive README retired it as an undocumented parallel authority. Move the simplification baseline map (#871-#887) and the shipped composer-mentions v1 spec (#979) into docs/archive/, register them under Former repository notes, and point the citing source comments at the archived path. --- .../src/main/__tests__/composer-mention-contract.test.ts | 2 +- docs/archive/README.md | 3 +++ {notes => docs/archive}/composer-mentions-spec-2026-07-14.md | 0 .../archive}/frontend-simplification-map-2026-07-13.md | 0 packages/ui/src/chat-input-behavior.ts | 2 +- packages/ui/src/composer-mention-popup.tsx | 2 +- packages/ui/src/composer.tsx | 2 +- 7 files changed, 7 insertions(+), 4 deletions(-) rename {notes => docs/archive}/composer-mentions-spec-2026-07-14.md (100%) rename {notes => docs/archive}/frontend-simplification-map-2026-07-13.md (100%) diff --git a/apps/desktop/src/main/__tests__/composer-mention-contract.test.ts b/apps/desktop/src/main/__tests__/composer-mention-contract.test.ts index 0a40372795..1141d49457 100644 --- 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/archive/README.md b/docs/archive/README.md index 56a6fa3435..6119cac0eb 100644 --- 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. diff --git a/notes/composer-mentions-spec-2026-07-14.md b/docs/archive/composer-mentions-spec-2026-07-14.md similarity index 100% rename from notes/composer-mentions-spec-2026-07-14.md rename to docs/archive/composer-mentions-spec-2026-07-14.md diff --git a/notes/frontend-simplification-map-2026-07-13.md b/docs/archive/frontend-simplification-map-2026-07-13.md similarity index 100% rename from notes/frontend-simplification-map-2026-07-13.md rename to docs/archive/frontend-simplification-map-2026-07-13.md diff --git a/packages/ui/src/chat-input-behavior.ts b/packages/ui/src/chat-input-behavior.ts index 31d84ec405..de7420f091 100644 --- 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 index 8b9761275e..43d251173e 100644 --- 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 index c91a00221d..566e8229ee 100644 --- 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; /** * 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 From eb3c616344f1a3ce5bdbf8b51e83f0d143774b9f Mon Sep 17 00:00:00 2001 From: AstroHan Date: Thu, 16 Jul 2026 11:44:24 +0800 Subject: [PATCH 2/3] docs: archive computer-use chronicles and research records The #857-#985 computer-use chain left one root document per PR: follow-up fix records, an incident investigation, and run logs that duplicate the kept contracts. Archive the seven chronicles, mark the foundation contract validation matrix as the #857 split-gate baseline (current state lives in source and contract tests), and register each archived file in the archive README with a pointer to its current authority. Also archive the WorkBuddy/QoderWork reverse-engineering records (the shipped design contract stays at docs/expert-team-runtime.md) and the synthesis-cache benchmark log (progress belongs in issues #481/#578), and fix the two surviving links to the moved paths. --- docs/archive/README.md | 20 +++++++++++++++++++ .../computer-use-delivery-state.md | 0 .../computer-use-evidence-hardening.md | 0 .../computer-use-executor-hardening.md | 0 .../computer-use-physical-input-guard.md | 0 .../computer-use-process-restart-e2e.md | 0 .../computer-use-real-ax-model-e2e.md | 0 .../computer-use-runtime-hardening.md | 0 .../economic-mechanisms-benchmark.md | 0 .../expert-team-implementation.md | 0 docs/{ => archive}/expert-team-plan.md | 0 docs/computer-use-foundation-contract.md | 2 ++ docs/expert-team-runtime.md | 2 +- .../src/__tests__/ai-sdk-backend.test.ts | 2 +- 14 files changed, 24 insertions(+), 2 deletions(-) rename docs/{ => archive}/computer-use-delivery-state.md (100%) rename docs/{ => archive}/computer-use-evidence-hardening.md (100%) rename docs/{ => archive}/computer-use-executor-hardening.md (100%) rename docs/{ => archive}/computer-use-physical-input-guard.md (100%) rename docs/{ => archive}/computer-use-process-restart-e2e.md (100%) rename docs/{ => archive}/computer-use-real-ax-model-e2e.md (100%) rename docs/{ => archive}/computer-use-runtime-hardening.md (100%) rename docs/{ => archive}/economic-mechanisms-benchmark.md (100%) rename docs/{ => archive}/expert-team-implementation.md (100%) rename docs/{ => archive}/expert-team-plan.md (100%) diff --git a/docs/archive/README.md b/docs/archive/README.md index 6119cac0eb..d3f7b7160e 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -45,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/docs/computer-use-delivery-state.md b/docs/archive/computer-use-delivery-state.md similarity index 100% rename from docs/computer-use-delivery-state.md rename to docs/archive/computer-use-delivery-state.md diff --git a/docs/computer-use-evidence-hardening.md b/docs/archive/computer-use-evidence-hardening.md similarity index 100% rename from docs/computer-use-evidence-hardening.md rename to docs/archive/computer-use-evidence-hardening.md diff --git a/docs/computer-use-executor-hardening.md b/docs/archive/computer-use-executor-hardening.md similarity index 100% rename from docs/computer-use-executor-hardening.md rename to docs/archive/computer-use-executor-hardening.md diff --git a/docs/computer-use-physical-input-guard.md b/docs/archive/computer-use-physical-input-guard.md similarity index 100% rename from docs/computer-use-physical-input-guard.md rename to docs/archive/computer-use-physical-input-guard.md diff --git a/docs/computer-use-process-restart-e2e.md b/docs/archive/computer-use-process-restart-e2e.md similarity index 100% rename from docs/computer-use-process-restart-e2e.md rename to docs/archive/computer-use-process-restart-e2e.md diff --git a/docs/computer-use-real-ax-model-e2e.md b/docs/archive/computer-use-real-ax-model-e2e.md similarity index 100% rename from docs/computer-use-real-ax-model-e2e.md rename to docs/archive/computer-use-real-ax-model-e2e.md diff --git a/docs/computer-use-runtime-hardening.md b/docs/archive/computer-use-runtime-hardening.md similarity index 100% rename from docs/computer-use-runtime-hardening.md rename to docs/archive/computer-use-runtime-hardening.md diff --git a/docs/economic-mechanisms-benchmark.md b/docs/archive/economic-mechanisms-benchmark.md similarity index 100% rename from docs/economic-mechanisms-benchmark.md rename to docs/archive/economic-mechanisms-benchmark.md diff --git a/docs/expert-team-implementation.md b/docs/archive/expert-team-implementation.md similarity index 100% rename from docs/expert-team-implementation.md rename to docs/archive/expert-team-implementation.md diff --git a/docs/expert-team-plan.md b/docs/archive/expert-team-plan.md similarity index 100% rename from docs/expert-team-plan.md rename to docs/archive/expert-team-plan.md diff --git a/docs/computer-use-foundation-contract.md b/docs/computer-use-foundation-contract.md index 3d12937594..34f60617cc 100644 --- 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 index 9cb51d23d4..590f4b7f18 100644 --- 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 index 1b9a2aa4fa..fa7a647d7c 100644 --- 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); From de991e365991daa8bc67b33fd06bfaac39f7688a Mon Sep 17 00:00:00 2001 From: AstroHan Date: Thu, 16 Jul 2026 11:44:24 +0800 Subject: [PATCH 3/3] docs: map current contracts in the documentation README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Seventeen root documents existed outside the authority map with zero incoming links. After archiving the chronicles, list the surviving computer-use contracts and the expert-teams runtime contract, and write down the maintenance rule that PR follow-up records, incident investigations, and run logs belong in pull requests or the archive — with notes/ and docs/local/ as untracked local scratch. --- docs/README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/README.md b/docs/README.md index 771d989e58..52a0d0cc9b 100644 --- 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.