chore: sanitize tests, add CONTEXT.md + ADRs, track tests/docs

2026-07-08 16:11:12 +08:00
parent d5d5df46fa
commit 1a34245618
19 changed files with 3880 additions and 31 deletions
@@ -0,0 +1,26 @@
+# The runtime contract is two-tier, with api-reference.md authoritative
+
+**Context.** Before the TypeScript migration and module extraction, we need to
+pin what "the contract" is so refactoring cannot silently change observable
+behavior. The four verbs (`build`/`search`/`query`/`attune`) are only the entry
+surface; agents actually depend on the *return shapes* of the sandbox helpers
+(`search`, `overview`, `memories`, …), which are already documented in
+`references/api-reference.md` and relied on by every example in
+`references/query-patterns.md`. Current behavior is good and there is no reason to
+change it during migration.
+
+**Decision.** Freeze the contract in two tiers. **Tier 1 (hard freeze, golden
+tests):** the four-verb CLI I/O envelope (file/args → pretty JSON on stdout,
+`{error, stack}` error envelope, exit codes) and the sandbox contract (`sql()`
+read-only enforcement, `attune` exposing only `remember`/`forget`, the set of
+globals/helpers available inside `query`/`attune`). **Tier 2 (locked to
+api-reference.md):** each helper's documented return shape — not frozen forever,
+but never allowed to drift silently; contract tests assert the live shape matches
+`references/api-reference.md`, so changing a helper forces a doc change plus a
+deliberate version bump. `references/api-reference.md` is therefore promoted from
+description to authoritative contract, and Phase 1 becomes "make it authoritative
+and enforce it," not "write a new contract doc."
+
+**Consequences.** Behavior is preserved across the TS/module refactor by
+construction: the golden and contract tests fail if any observable shape moves.
+The cost is that helper shapes can no longer be reshaped casually mid-migration.