Skip to content

docs: realign documentation set with the authority map#1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Astro-Han merged 3 commits into from
Jul 16, 2026
Merged

docs: realign documentation set with the authority map #1060

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3a4be76
docs: retire tracked notes into the archive
Astro-Han Jul 16, 2026
eb3c616
docs: archive computer-use chronicles and research records
Astro-Han Jul 16, 2026
de991e3
docs: map current contracts in the documentation README
Astro-Han Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/desktop/src/main/__tests__/composer-mention-contract.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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
Expand Down
11 changes: 11 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand All@@ -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.
23 changes: 23 additions & 0 deletions docs/archive/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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.
0 notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md
View file
Open in desktop
File renamed without changes.
0 docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md
View file
Open in desktop
File renamed without changes.
0 docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md
View file
Open in desktop
File renamed without changes.
0 docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md
View file
Open in desktop
File renamed without changes.
0 docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md
View file
Open in desktop
File renamed without changes.
0 docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md
View file
Open in desktop
File renamed without changes.
0 docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md
View file
Open in desktop
File renamed without changes.
0 docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md
View file
Open in desktop
File renamed without changes.
0 docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md
View file
Open in desktop
File renamed without changes.
0 docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md
View file
Open in desktop
File renamed without changes.
0 docs/expert-team-plan.md → docs/archive/expert-team-plan.md
View file
Open in desktop
File renamed without changes.
0 ...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md
View file
Open in desktop
File renamed without changes.
2 changes: 2 additions & 0 deletions docs/computer-use-foundation-contract.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/expert-team-runtime.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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.

Expand Down
2 changes: 1 addition & 1 deletion packages/runtime/src/__tests__/ai-sdk-backend.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
Expand Down
2 changes: 1 addition & 1 deletion packages/ui/src/chat-input-behavior.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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).
Expand Down
2 changes: 1 addition & 1 deletion packages/ui/src/composer-mention-popup.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion packages/ui/src/composer.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
docs: realign documentation set with the authority map by Astro-Han · Pull Request #1060 · apache/maka · GitHub
Skip to content
docs: realign documentation set with the authority map#1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Jul 16, 2026
 Merged


docs: realign documentation set with the authority map
#1060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
3a4be76

docs: retire tracked notes into the archive


Astro-Han Jul 16, 2026
eb3c616

docs: archive computer-use chronicles and research records


Astro-Han Jul 16, 2026
de991e3

docs: map current contracts in the documentation README


Astro-Han Jul 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
apps/desktop/src/main/__tests__/composer-mention-contract.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

11 changes: 11 additions & 0 deletions
docs/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand All@@ -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.

23 changes: 23 additions & 0 deletions
docs/archive/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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.

0
notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-plan.md → docs/archive/expert-team-plan.md

View file


Open in desktop


File renamed without changes.


0
...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md

View file


Open in desktop


File renamed without changes.


2 changes: 2 additions & 0 deletions
docs/computer-use-foundation-contract.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Expand Down

2 changes: 1 addition & 1 deletion
docs/expert-team-runtime.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.

Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/chat-input-behavior.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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).
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer-mention-popup.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
docs: realign documentation set with the authority map by Astro-Han · Pull Request #1060 · apache/maka · GitHub
Skip to content
docs: realign documentation set with the authority map#1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Jul 16, 2026
 Merged


docs: realign documentation set with the authority map
#1060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
3a4be76

docs: retire tracked notes into the archive


Astro-Han Jul 16, 2026
eb3c616

docs: archive computer-use chronicles and research records


Astro-Han Jul 16, 2026
de991e3

docs: map current contracts in the documentation README


Astro-Han Jul 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
apps/desktop/src/main/__tests__/composer-mention-contract.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

11 changes: 11 additions & 0 deletions
docs/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand All@@ -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.

23 changes: 23 additions & 0 deletions
docs/archive/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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.

0
notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-plan.md → docs/archive/expert-team-plan.md

View file


Open in desktop


File renamed without changes.


0
...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md

View file


Open in desktop


File renamed without changes.


2 changes: 2 additions & 0 deletions
docs/computer-use-foundation-contract.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Expand Down

2 changes: 1 addition & 1 deletion
docs/expert-team-runtime.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.

Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/chat-input-behavior.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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).
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer-mention-popup.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
docs: realign documentation set with the authority map by Astro-Han · Pull Request #1060 · apache/maka · GitHub
Skip to content
docs: realign documentation set with the authority map#1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Jul 16, 2026
 Merged


docs: realign documentation set with the authority map
#1060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
3a4be76

docs: retire tracked notes into the archive


Astro-Han Jul 16, 2026
eb3c616

docs: archive computer-use chronicles and research records


Astro-Han Jul 16, 2026
de991e3

docs: map current contracts in the documentation README


Astro-Han Jul 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
apps/desktop/src/main/__tests__/composer-mention-contract.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

11 changes: 11 additions & 0 deletions
docs/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand All@@ -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.

23 changes: 23 additions & 0 deletions
docs/archive/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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.

0
notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-plan.md → docs/archive/expert-team-plan.md

View file


Open in desktop


File renamed without changes.


0
...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md

View file


Open in desktop


File renamed without changes.


2 changes: 2 additions & 0 deletions
docs/computer-use-foundation-contract.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Expand Down

2 changes: 1 addition & 1 deletion
docs/expert-team-runtime.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.

Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/chat-input-behavior.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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).
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer-mention-popup.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
docs: realign documentation set with the authority map by Astro-Han · Pull Request #1060 · apache/maka · GitHub
Skip to content
docs: realign documentation set with the authority map#1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Jul 16, 2026
 Merged


docs: realign documentation set with the authority map
#1060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
3a4be76

docs: retire tracked notes into the archive


Astro-Han Jul 16, 2026
eb3c616

docs: archive computer-use chronicles and research records


Astro-Han Jul 16, 2026
de991e3

docs: map current contracts in the documentation README


Astro-Han Jul 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
apps/desktop/src/main/__tests__/composer-mention-contract.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

11 changes: 11 additions & 0 deletions
docs/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand All@@ -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.

23 changes: 23 additions & 0 deletions
docs/archive/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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.

0
notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-plan.md → docs/archive/expert-team-plan.md

View file


Open in desktop


File renamed without changes.


0
...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md

View file


Open in desktop


File renamed without changes.


2 changes: 2 additions & 0 deletions
docs/computer-use-foundation-contract.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Expand Down

2 changes: 1 addition & 1 deletion
docs/expert-team-runtime.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.

Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/chat-input-behavior.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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).
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer-mention-popup.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
docs: realign documentation set with the authority map by Astro-Han · Pull Request #1060 · apache/maka · GitHub
Skip to content
docs: realign documentation set with the authority map#1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Jul 16, 2026
 Merged


docs: realign documentation set with the authority map
#1060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
3a4be76

docs: retire tracked notes into the archive


Astro-Han Jul 16, 2026
eb3c616

docs: archive computer-use chronicles and research records


Astro-Han Jul 16, 2026
de991e3

docs: map current contracts in the documentation README


Astro-Han Jul 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
apps/desktop/src/main/__tests__/composer-mention-contract.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

11 changes: 11 additions & 0 deletions
docs/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand All@@ -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.

23 changes: 23 additions & 0 deletions
docs/archive/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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.

0
notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-plan.md → docs/archive/expert-team-plan.md

View file


Open in desktop


File renamed without changes.


0
...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md

View file


Open in desktop


File renamed without changes.


2 changes: 2 additions & 0 deletions
docs/computer-use-foundation-contract.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Expand Down

2 changes: 1 addition & 1 deletion
docs/expert-team-runtime.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.

Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/chat-input-behavior.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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).
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer-mention-popup.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
docs: realign documentation set with the authority map by Astro-Han · Pull Request #1060 · apache/maka · GitHub
Skip to content
docs: realign documentation set with the authority map#1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Jul 16, 2026
 Merged


docs: realign documentation set with the authority map
#1060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
3a4be76

docs: retire tracked notes into the archive


Astro-Han Jul 16, 2026
eb3c616

docs: archive computer-use chronicles and research records


Astro-Han Jul 16, 2026
de991e3

docs: map current contracts in the documentation README


Astro-Han Jul 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
apps/desktop/src/main/__tests__/composer-mention-contract.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

11 changes: 11 additions & 0 deletions
docs/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand All@@ -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.

23 changes: 23 additions & 0 deletions
docs/archive/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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.

0
notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-plan.md → docs/archive/expert-team-plan.md

View file


Open in desktop


File renamed without changes.


0
...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md

View file


Open in desktop


File renamed without changes.


2 changes: 2 additions & 0 deletions
docs/computer-use-foundation-contract.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Expand Down

2 changes: 1 addition & 1 deletion
docs/expert-team-runtime.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.

Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/chat-input-behavior.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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).
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer-mention-popup.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
docs: realign documentation set with the authority map by Astro-Han · Pull Request #1060 · apache/maka · GitHub
Skip to content
docs: realign documentation set with the authority map#1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Jul 16, 2026
 Merged


docs: realign documentation set with the authority map
#1060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
3a4be76

docs: retire tracked notes into the archive


Astro-Han Jul 16, 2026
eb3c616

docs: archive computer-use chronicles and research records


Astro-Han Jul 16, 2026
de991e3

docs: map current contracts in the documentation README


Astro-Han Jul 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
apps/desktop/src/main/__tests__/composer-mention-contract.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

11 changes: 11 additions & 0 deletions
docs/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand All@@ -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.

23 changes: 23 additions & 0 deletions
docs/archive/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand All@@ -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.

0
notes/composer-mentions-spec-2026-07-14.md → ...hive/composer-mentions-spec-2026-07-14.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-delivery-state.md → docs/archive/computer-use-delivery-state.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-evidence-hardening.md → ...rchive/computer-use-evidence-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-executor-hardening.md → ...rchive/computer-use-executor-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-physical-input-guard.md → ...hive/computer-use-physical-input-guard.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-process-restart-e2e.md → ...chive/computer-use-process-restart-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-real-ax-model-e2e.md → ...archive/computer-use-real-ax-model-e2e.md

View file


Open in desktop


File renamed without changes.


0
docs/computer-use-runtime-hardening.md → ...archive/computer-use-runtime-hardening.md

View file


Open in desktop


File renamed without changes.


0
docs/economic-mechanisms-benchmark.md → .../archive/economic-mechanisms-benchmark.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-implementation.md → docs/archive/expert-team-implementation.md

View file


Open in desktop


File renamed without changes.


0
docs/expert-team-plan.md → docs/archive/expert-team-plan.md

View file


Open in desktop


File renamed without changes.


0
...frontend-simplification-map-2026-07-13.md → ...frontend-simplification-map-2026-07-13.md

View file


Open in desktop


File renamed without changes.


2 changes: 2 additions & 0 deletions
docs/computer-use-foundation-contract.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Expand Down

2 changes: 1 addition & 1 deletion
docs/expert-team-runtime.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.

Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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);
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/chat-input-behavior.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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).
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer-mention-popup.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand Down

2 changes: 1 addition & 1 deletion
packages/ui/src/composer.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading