Every packages/*/* README now carries a canonical '## Known Limitations and
Deferred Work' section: condensed, evidence-backed bullets for consumer-visible
gaps (unimplemented features, platform caveats, MVP cuts) and consciously
postponed work (TODO/FIXME/XXX markers, RFC deferrals still open). The ten
pre-existing ad-hoc variants ('What is NOT here (TODO)', 'Deferred',
'Limitations (MVP)', 'Known limitations (tracked TODOs)', ...) are normalized
into the canonical heading.
A new doc-sync gate, scripts/verify-readme-limitations.ts, enforces the shape:
exactly one limitations-like heading per package README, byte-equal to the
canonical h2, with at least one bullet; near-miss headings fail so variants
cannot creep back. Packages with genuinely nothing to declare (dsh-brand,
dsh-timeout, dsh-subagent-mock, dsh-app-boot) are whitelisted in the script and
must NOT carry the section; whitelist entries are validated against the scanned
package set so a rename fails loud.
Wired into the doc-sync chain (package.json) and the run-gates doc-sync leaf
set; the standing rule lands in packages/AGENTS.md and the adding-a-package
cookbook; decision record in
docs/rfc/implemented/process/2026-07-10-readme-known-limitations-gate.md
(RFC index regenerated).
Also fixes two stale '(deferred)' markers claiming dsh-compact-basic is
unimplemented (the dsh-compact seam README's package table and the seam's
module doc comment).
Drain idle injection flushes before agent teardown, snapshot approval and subagent provider inputs, and gate subagent lifecycle events on real child readiness. Align the RFCs and generated contracts with the hardened behavior.
The keyless Loader-path smokes killed the child 10s after spawn, but a
loaded CI e2e runner routinely needs longer just to boot the unbuilt tsx
tree: on this branch's run the coding-agent smoke burned both retries and
failed at 30s wall-clock, and the sibling smokes passed only on retry x2
(master's latest run shows the same near-misses). The budget guards
against a HANG, not slowness — raise kill to 30s and the vitest test
timeout to 45s so a slow boot no longer masquerades as one.
formatSystemPromptSnapshot's insert-join ternary had its already-newline-
terminated arm unexercised (a delta whose insert ends in a blank line),
failing the per-file 100% branch gate on suite.ts (99.24%).
Two independent multipliers were pushing bare `pnpm run lint` past node's
default heap:
1. parserOptions.project expanded to every package tsconfig plus the root
one — each matched config built its OWN ts.Program, and the dev paths
map pulls sibling package SOURCES (plus the vendored Cordis stack) into
every such program, so resident memory grew as sum-of-closures, not
repo size: ~4.6 GB peak for 425 repo files. projectService shares one
tsserver-style graph: ~2.0 GB peak, ~28 s → ~14 s wall.
2. `eslint .` traversed .claude/ harness-local state — stale worktree
checkouts there carry tens of thousands of additional .ts files
(whole-repo copies), roughly tripling the work again even under the
project service. Other checkouts are not this one's sources; ignore
them like node_modules. (#169 carries the identical ignore line inside
its chain; the hunks dedupe on its next rebase.)
Type-aware rules verified live under the service: a floating-promise
probe still trips no-floating-promises.
Tianyi Cui
Hypatia May
Yichen Jiang
kingwl