📝 Make the architecture documents easier to read and navigate

[taras]

Why

Readers had to learn terminology and a large construct inventory before seeing how a document runs. Detailed rules were repeated across architecture and feature specifications, with several descriptions lagging behind shipped behavior.

Closes #911. Stacked on #910; this diff starts at its reviewed head, 1ef21a6f8fe659f25ea214eaecc5fff4af1c4b87.

What changes

Before: readers searched long documents and reconciled repeated explanations themselves.

After: README offers six question routes. Architecture starts with a write/read/delete execution and replay example, then follows ownership, execution, failures, workflow state, files, agents and extension boundaries. Terminology and the construct inventory serve as linked references after those concepts. Feature specifications retain their interfaces and conformance evidence while linking to the detailed architecture rules. The decision log distinguishes historical sequencing from current behavior.

The rewrite also corrects source-verified stale descriptions of workflow definitions, artifacts, protected components, generated evaluation, native session routes and diagnostic journals.

Review guide

Start with README's architecture links and architecture.md#reading-this-architecture. Follow the write/read/delete example, then inspect the relevant boundary rather than reading the moved diff linearly.

Review the shortened terminology and inventory alongside their linked owners. Check the Plan, workflow and native-session specifications for the preserved profile and compatibility exceptions. specs/decisions.md records Plan delivery history and the partial supersession of earlier durable-expansion decisions.

Look carefully at the separate settlement contracts: component invocation aggregates body and teardown failures; whole-document execution ranks its final Result; Plan retry requires successful cleanup.

What must stay true

• Resource lifetimes, cancellation, provider-owned enforcement and durable identity remain intact.
• Historical reads and completed effects restore from retained evidence; completed-root replay attaches no operational providers.
• Current serialized identities, diagnostics, conformance identifiers and existing boundary anchors survive the moves.
• Executable fences remain exact, except four enumerated obsolete documentation examples or comments corrected against shipped behavior.
• Both architecture corrections reviewed in 📝 Clarify execution contracts and repair compiled PR review #910 survive byte-identically.

How to verify it

Focused checks: git diff --check and node scripts/lint-architecture.js pass.

The scratch preservation audit accounts for all 7,486 baseline units across the 25-document corpus. Independent checks verify 7,113 exact retained units, 36 exact moved units, one unchanged-word reflow and 336 semantic transfers/corrections; every normalized canonical destination resolves. Existing anchors and conformance row identifiers survive. All 470 code fences are accounted for, with only the four enumerated stale-document exceptions.

Six advertised navigation tasks pass through actual links and explicitly recorded heading-outline browsing. The first walkthrough's route failure is retained separately from the repaired run. Four overlays run through the same verifier and reject a missing constraint, broken anchor, changed diagnostic fence and removed conformance ID.

Independent Planner (A1–A10) and Architect (six structural criteria) reviews pass on e3afc34f49bb3dfbf508bc4ae5091c941f35be40. The independent exact-commit audit reports zero failures. Delivery deno task lint exits 0; it emits warnings from unchanged source files. The committed branch diff also passes git diff --check.

Scope

Documentation and navigation only. The full 25-document survey corpus was assessed; files without a relevant correction or navigation improvement remain unchanged. No runtime, dependency, lockfile, generated output or executable-asset changes.

Risks and limitations

The substantive risk is losing a qualification while consolidating prose. A clause-transfer record and independent structural review check the destinations; exact comparisons protect unchanged material, fences, identifiers and the parent corrections. Six navigation exercises check the advertised routes. These are agent walkthroughs, not measurements of human comprehension or reading time.

Scope confirmation

• Every changed file supports the reading-path rewrite and settled documentation corrections.
• Unrelated cleanup and formatting changes are excluded.
• Mechanical moves and their preservation checks are identified above.
• The description matches the final diff and verification results.