[mkarlesky]

Stacked on #27. Merge #27 first; this PR then retargets to next_version.

Adds a new docs/Architecture.md for contributors and coding agents. Its prose moves from orientation down to precise invariants, and four Mermaid diagrams show the layers, discovery, a run, and the locks.

1. Overview: the two layers, with the module table moved from Development.md, and the two Ceedling constraints.
2. The VS Code APIs it builds on:
   • activation and lifetime;
   • the Testing API: controller, tree, handlers, profiles, runs and messages;
   • the test coverage API: FileCoverage.fromDetails, loadDetailedCoverage and the WeakMap;
   • the debug API, with the request-id tagging and the ${command:…} guard;
   • a workspace, diagnostics and window API table.
3. Discovery: its five steps and how the tree stays current.
4. Runs: planning, reporting, the exact test build directories (testBuildName()), debugging and coverage.
5. Concurrency:
   • what runs at once, and what bounds each kind of work;
   • the directory and build-root locks, including the gap for a project no discovery has loaded yet;
   • six invariants;
   • the Ceedling capability gates, and which workarounds Ceedling 1.2.1 makes unnecessary and which it doesn't;
   • the possible speedup: discovery without the lock on 1.2.1. It covers the opportunity, the evidence (the probe of files under build/ and the inconclusive stress test), what a change would need, and the risks. It isn't implemented.
6. Test seams.

Development.md's §2 becomes a summary and a link. §4 is renamed "VS Code Tools for This Work" to tell it apart from the APIs. The README's Documentation and Contributing sections link the new document.

Verification:

• Every relative link and heading anchor resolves.
• All four diagrams render with mermaid-cli 11.4.2.
• An independent review checked every claim against src/ and package.json, and its findings are applied.

🤖 Generated with Claude Code