Pine/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 1 Wiki Activity

docs(architecture): rewrite the system map to the 1,800-word budget

Browse Source 
architecture.md is the behavior map: layering, service map, seam
pattern, and the loop — everything else defers to its owning tier.

- Seam narrations compress to two-to-four sentences plus links to the
  RFC and type-catalog homes that carry the detail (turn-end variant
  semantics -> session.md, derivation mapping -> session.md, StreamChunk
  conventions -> llm-streaming.md + source).
- The MVP feature-to-mechanism checklist moves de-statused into the
  extension cookbook as 'The feature -> mechanism map' — mechanisms
  only, no implementation-status bolding to rot; the microkernel RFC's
  proof-obligation pointer follows it.
- The layering diagram describes layers by family instead of
  enumerating packages (the stale 'future plugins: hooks, compaction'
  row is gone); the dependency rule defers to packages/README.md.
- The loop pseudocode, the three externally-cited anchors (the
  vocabulary, event taxonomy, waterfall semantics), and the filename
  are unchanged.
- Budget ratchet: docs/architecture.md 3897 -> 1800 (now 1,797 words);
  the doc-tiers RFC's deferred list prunes the item this ships.
This commit is contained in:
Tianyi Cui
2026-07-04 14:43:48 +08:00
parent 65f28580f0
commit 6227cfd03d
5 changed files with 85 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/rfc/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
+1 -1
View File
@@ -20,7 +20,7 @@ The event vocabulary lives in interface packages (dsh-agent declares the agent/*
## Consequences
- Every MVP feature maps to a listener (the "plugin sanity checklist" in docs/architecture.md is the proof obligation, kept current).
- Every MVP feature maps to a listener (the [feature → mechanism map](../../../cookbook/extension-cookbook.md#the-feature--mechanism-map) is the proof obligation, kept current).
- HMR and disposal come free: listeners and registrations are Cordis effects.
- Waterfall semantics (call `next()` or short-circuit) are non-obvious and must be taught — documented in AGENTS.md and covered by composition tests.
- The loop must be defensive: plugin exceptions are contained at turn level, steering from any seam is never stranded (regression-tested).
docs/rfc/implemented/process/2026-07-04-doc-tiers-and-budgets.md
-1
View File
@@ -27,7 +27,6 @@ The repo's standing docs accrete. Root `AGENTS.md` reached 8,130 words through 5
The first audit cycle under the standard, in rough priority order (evidence gathered in the survey that motivated this RFC):
- `architecture.md` rewrite to the ≤ 1,800-word target: seam narration compressed to pointers, the MVP feature-to-mechanism checklist moved de-statused into [the extension cookbook](../../../cookbook/extension-cookbook.md), the stale layering-diagram row fixed.
- Package README trims where generated catalogs or JSDoc are restated or history is narrated: `packages/ui/acp`, `packages/core/tools`, `packages/bash/tool-bash`, `packages/core/session`, `packages/compact/compact-basic`, `packages/session-persistence/session-persistence`.
- [The web capability seam RFC](../architecture/2026-06-24-web-capability-seam.md) converted from spec-speak to shipped reality (drop the migration plan and test enumeration, "should" → "is").
- `docs/core-data-structures/core.md`: drop the JSDoc walls from the `Agent`/`GenerateOptions` type-equiv pastes per that page's own stated rule.