chore(stability): define the stability contract and graduate the proven core

[drewstone]

What this is

The repo has carried @stable/@experimental tags since 0.7.0 with no documented meaning, no graduation bar, no CI visibility, and a rendering gap that hid every module-level marker from the published docs. This PR turns the tags into a contract and applies it.

• docs/STABILITY.md — what the two tags mean for consumers and the graduation bar (tests + curated doc + real consumer + 30-day API quiet + CHANGELOG announcement), linked from README and the docs index.
• 8 graduations (@experimental→@stable, per-symbol and module-level, each with evidence recorded in the 0.130.0 CHANGELOG entry): the runAgentRounds kernel loop + its contract types, supervise/Scope/Supervisor, the personify combinators, the spawn-journal family, the /mcp delegation queue/stores/status tools, /intelligence (whose own doc already said "shipped"), the improvement generators, and streamAgentTurn/collectAgentTurn. Everything promoted was already tested, documented, and load-bearing on the repo's recommended paths — experimental in name only.
• Kept experimental, with reasons in the entry: resume/restart recovery, EventBus durability, the detached/worktree delegate leaves (unfinished resume paths documented in their own TSDoc), remote coordination MCP, lineage, and the unproven member extension points.
• Newly tagged the untagged-unfinished: define-agent (act not wired), strategy-evolution, the /candidate-execution barrel, plus explicit member tags on the not-implemented restart/durability surfaces.
• Rendering fix, root-caused: tsdoc.json replaced TypeDoc's tag set (no extends) and barrels lacked @module, so module maturity never rendered — fixed; Stable badges in docs/api went 70 → 165, proven by regeneration (docs:check green).

Verification

Full battery, real exit codes: lint (557 files), typecheck + examples, vitest 2,376 passed / 0 failed / 6 skipped (202 files), all six check:*/verify:* gates, docs:check, verify:package (publint + attw). Version 0.129.0 → 0.130.0 with the graduation entry. Operator spot-checks passed independently (remote sha, tag flips, new tags, rendered badges).

Companion in flight: the agent-dev-container migration off the deleted /loops subpath onto this stabilized surface.

[tangletools]

✅ Auto-approved drewstone PR — c99d4b5b

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-05T01:25:40Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	3 (1 low, 2 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	169.3s (2 bridge agents)
Total	169.3s

💰 Value — sound-with-nits

Defines a real stability contract (tags, graduation bar, demotion policy), graduates 8 already-load-bearing families to @stable with per-symbol evidence, newly tags 3 genuinely-unfinished surfaces @experimental, and root-causes a real TypeDoc rendering gap — ship.

• What it does: Three things in one PR. (1) Adds docs/STABILITY.md defining what @stable/@experimental promise consumers, the 5-gate graduation bar (substantive tests + curated doc + real consumer + 30-day quiet API + CHANGELOG entry), and the deprecation/removal policy; linked from README.md:532 and docs/README.md:35. (2) Flips @experimental→@stable on ~38 source files spanning 8 families (runAgentRounds kernel
• Goals it achieves: Turn the @stable/@experimental tags the repo has carried since 0.7.0 from decoration into a contract: consumers get a documented promise and a demotion policy; the graduation bar makes 'is this actually proven' a checklist rather than a vibe; the rendering fix makes the maturity level visible in the published docs/api reference (Stable badges reportedly went 70→165). Secondary goal: honestly mark
• Assessment: Sound and unusually rigorous for a doc-and-tags PR. Every graduated family is backed by CHANGELOG evidence I spot-checked: runAgentRounds is consumed by bench/src/research-shot.ts, bench/src/corpus.ts; streamAgentTurn/collectAgentTurn by bench/src/router-turn.ts, bench/src/benchmarks/appworld.ts, examples/chat-handler; the improve family by bench/src/swe-bench-env.ts, examples/improve; intelligenc
• Better / existing approach: none — this is the right approach. Searched for a pre-existing stability/maturity doc (git log on docs/STABILITY.md, docs/stability*, README); none exists. Checked for an alternate tagging mechanism (custom JSDoc, API report tooling, api-extractor); the repo uses TypeDoc with tsdoc.json, so extending that is the grain. The contract's shape (graduation bar + demotion cycle) mirrors how the repo alr
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: opencode: opencode error

🎯 Usefulness — sound-with-nits

Turns long-present-but-meaningless @stable/@experimental tags into a real, rendered, enforced contract with an honest first graduation — coherent and useful; only the graduation-bar enforcement is manual.

• Assessment: Net useful and will do its job. It takes tags that existed for six releases with no meaning and gives them a definition consumers can rely on, a graduation bar that names what 'proven' means, visible rendering that was previously broken (module-level badges literally never showed), and honest per-symbol state — including down-tagging three previously-untagged unfinished surfaces. It is contract wo
• Integration: Fully reachable. STABILITY.md is linked from the two highest-traffic entry points (README.md:532, docs/README.md:35). Tags render in the generated reference — verified directly: docs/api/intelligence.md:9 shows Stable under the title, docs/api/candidate-execution.md:9 shows Experimental. The rendering fix (tsdoc.json now extends typedoc/tsdoc.json + @module on each subpath barrel) is m
• Fit with existing patterns: Fits the codebase grain with no competing system. The two-tag maturity model (stable=contract / experimental=free-to-break, experimental-by-default) is the industry-standard pattern (Rust stable/nightly, Node-API stability, SemVer maturity) and matches how the repo already shipped tags since 0.7.0. The rendering fix root-causes correctly: TypeDoc only treats a leading doc comment as module-level w
• Real-world viability: Holds up on the paths that matter. The rendering gate catches the common rot (a tag that stops rendering or a stale docs/api regen). The honest-labeling of unfinished surface is accurate: define-agent.ts:195 ships unimplementedAgentRun whose output is Promise.reject, so tagging define-agent @experimental with that exact reason is truthful, not aspirational. strategy-evolution and candidate-e
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🔎 Heuristic Signals

🟡 Diff is 93% formatting/comments ``

+179 lines, 167 are whitespace/comments. Consider a separate formatting PR or confirm linting is the intent.

💰 Value Audit

🟡 @module added to only 6 of 17 barrels; PR body over-claims 'each subpath barrel carries @module' [maintenance] ``

The CHANGELOG and commit message state 'each subpath barrel carries @module, so docs/api subpath pages show the module-level badge'. Verified via git ls-files src/**/index.ts + @module grep: only src/candidate-execution, src/intelligence, src/mcp, src/profiles, src/runtime, src/tui have it. Eight public-subpath barrels listed in package.json exports still lack @module: ./agent, ./conversation, ./durable, ./analyst-loop, ./knowledge, ./platform, ./primeintellect, ./testing. Most relevant is ./dur

🎯 Usefulness Audit

🟡 Graduation bar is human-enforced, not CI-enforced — tags can rot silently below the rendering layer [robustness] ``

docs:check (package.json) enforces only that docs/api regen matches the commit and that signatures are fresh; scripts/check-docs-freshness.mjs does not check tag presence, the five graduation criteria, or that a @stable symbol still has a real consumer/tests. So the contract's substance (tests + consumer + 30-day quiet) relies on reviewer discipline each PR. The rendering gate catches a tag that stops rendering, which is the most common decay mode, so this is a reasonable scoping for an initial

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260805T013022Z}