dsh-ptc-plus 0.4.8 → 0.5.0

package/docs/adr/0028-attach-to-the-host-ptc-execution-seam.md

@@ -4,15 +4,15 @@
 
 PTC Plus supplies the session-bound REPL by taking over the program-execution
 seam DSH uses for `run_code`. DSH registers that seam as a Cordis service and
-has renamed it between releases: the preceding generation published
-`ctx.codeRuntime` (`@deepseek-ai/dsh-code-runtime`) and the current one publishes
+has renamed it between releases: the request-only contract publishes
+`ctx.codeRuntime` (`@deepseek-ai/dsh-code-runtime`) and the resolved-spec contract publishes
 `ctx.ptcRuntime` (`@deepseek-ai/dsh-ptc-runtime`). A plugin that declares the
-removed name as a required injection never applies on the current host. Cordis
+absent name as a required injection never applies on that host. Cordis
 does not fail such a plugin: the fiber stays pending, the plugin's entry points
 are never registered, and `run_code` silently keeps executing in the host's own
 runtime instead of the session REPL.
 
-The current seam also differs in more than its name. It resolves a request before
+The resolved-spec seam also differs in more than its name. It resolves a request before
 running it (`resolve(request)` → `run(spec)`), it publishes provider descriptors
 (`executionInstructions`, `sandboxMode`, `timeout`) that gate host inputs, and it
 reports file-confinement facts on the result. Its provider resolves a file policy
@@ -22,40 +22,75 @@ accepts a confinement request it cannot enforce silently weakens DSH's policy.
 
 ## Decision
 
-One owner attaches the plugin to the seam: `internal/execution-seam-compat.js`.
-It selects the seam from the registered service, not from a version string, and
-presents the same seam-neutral contract to the runtime bridge whatever the host
-generation is.
+`internal/execution-provider-owner.js` owns public provider composition;
+`internal/execution-seam-compat.js` owns live selection and the request/spec
+boundary. Selection uses the registered capability, not a version string.
+
+**Composition owns the routing relationship.** The shipped bundle preserves the
+original `ptc-runtime` row's module and configuration and gives its `ptcRuntime`
+service a named isolation. A separate execution-provider row observes that
+original entry through public Loader resolution and injection, then registers a
+plugin-owned global provider through Cordis. The main plugin installs its
+execution callback only in that provider's private entry. The original service
+is never modified and may be frozen or sealed. Custom compositions configure
+the original entry ID, service name and matching isolation explicitly. `codeRuntime` takes requests directly; `ptcRuntime` requires `resolve(request)` before `run(spec)`. The selected service contract, rather than release chronology, determines delegation. Entry IDs resolve in the
+provider row’s owning Loader tree, including the profile’s Include subtree;
+they are not assumed to be root-tree IDs.
+
+The execution-provider row remains present when the main plugin is disabled;
+without a callback it delegates native execution and capability getters to the
+original. Its stable adapter follows original-generation replacement, but a
+resolved spec remains bound to the generation that produced it and cannot run
+after that generation retires. Before bundle removal changes the original isolation,
+the public Loader lifecycle withdraws only the plugin's provider registration
+synchronously, leaving the global service slot available for the original to
+return. Cleanup cannot retire a newer registration. A plain, uncomposed provider
+is a deployment error, not a reason to fall back to descriptor mutation.
+
+Activation reads the current original generation's language through the live seam.
+The adapter's stable identity does not make its first language a permanent fact;
+an unsupported or unavailable current generation cannot authorize activation.
+The original-generation observer also notifies the installed controller after source
+replacement. An incompatible language retires the active PTC runtime without changing
+the user's enabled setting; returning to TypeScript reconciles it again. Descriptor,
+resolve/run and upstream delegation entries reject an installed-language mismatch
+while that cleanup is pending, so SDK preparation cannot describe a different
+language from the callback's execution. A TypeScript replacement retains the existing
+session runtime. The subscription and its disposer belong to the injected controller.
 
 **Selection is a live capability.** The plugin's static injection names only the
 services both generations provide; the seam owner waits through `inject` for
 whichever execution service the host registers, in a scope that also requires the
-plugin's own services, and owns one live attachment at a time. When both are registered, the current
-generation wins, including when it appears after a preceding-generation attachment.
+plugin's own services, and owns one live attachment at a time. When both are registered, the resolved-spec
+contract wins, including when it appears after a request-only attachment.
 That transition first disposes the legacy injected fiber and its complete effect
-tree, then attaches in the current service's scope; cleanup from the retired scope
-cannot clear the new owner. If that attach fails, the owner marks the current
-service object unusable, re-arms the preceding-generation attachment
+tree, then attaches in the resolved-spec service's scope; cleanup from the retired scope
+cannot clear the new owner. If that attach fails, the owner marks the resolved-spec
+service object unusable, re-arms the request-only attachment
 immediately, and reports the failure instead of leaving the plugin with no
-execution seam; the failed object is never retried, while a replacement current
-service supersedes the restored attachment. The preceding generation therefore
-attaches only when the current one is absent or is the recorded unusable object.
+execution seam; the failed object is never retried, while a replacement resolved-spec
+service supersedes the restored attachment. The request-only contract therefore
+attaches only when the resolved-spec one is absent or is the recorded unusable object.
 Attachment runs in the injected scope, so
 the plugin is unloaded when the host unregisters that service and reattaches when
 it is registered again. A service that satisfies the name but not the contract
 (`run` or `resolve` missing) follows the same path and is reported as a load
-failure naming the service; when a preceding-generation attachment exists, the
+failure naming the service; when a request-only attachment exists, the
 report accompanies its restoration so `run_code` never silently returns to the
 host provider.
 
-**Execution is one neutral call shape.** The owner publishes `invokeUpstream`,
+**New requests and resolved execution specs remain distinct.** The owner publishes `invokeUpstream`,
 which reproduces each generation's own call shape — directly for
 `run(request)`, and as `run(resolve(request))` for the two-step seam — and
-`takeOver(execute)`, which replaces the single execution entry and restores the
-exact descriptor it replaced. The plugin's entry receives exactly `program`,
-`bindings`, and `signal`: the fields PTC Plus has always consumed. A resolved
-spec's directory, deadline, and authority describe the provider whose execution
-was replaced; they are neither forwarded to the session kernel nor re-derived.
+`installExecute(execute)`, which owns only the plugin provider's private callback
+and returns its disposer. The plugin's entry receives the complete input.
+`runUpstream(spec)` delegates an already resolved spec directly to the original
+provider, retaining its object identity, cwd, deadline, sandbox policy and future
+execution fields. Non-session callers use this path without resolving again.
+Fresh isolated requests still use `invokeUpstream(request)`. Session cells consume
+their program, bindings, signal and resolved cwd under the session's own execution contract;
+[ADR 0041](0041-record-cell-execution-directories.md) records per-cell directory ownership;
+the boundary never drops fields before choosing which consumer owns execution.
 
 **The seam describes the execution the plugin performs.** While the plugin owns
 the seam it also answers the descriptors with its own behavior: no
@@ -68,11 +103,33 @@ resolution, and sandbox escalation on those descriptors, so withholding them kee
 DSH's authority decisions with DSH instead of accepting an input the plugin would
 then ignore. Withdrawal is unconditional rather than generation-conditional,
 because the rule belongs to the plugin's execution rather than to a generation:
-the preceding generation's contract defines none of these members and nothing in
-its install closure reads them, so withdrawing there is inert, while a provider
-that did publish them cannot outlive the takeover. Every takeover and every
-withheld descriptor is released together, and a release leaves a descriptor that
-another owner replaced in the meantime.
+the request-only contract defines none of these members and nothing in
+its install closure reads them, so withdrawing there is inert. These values are
+derived getters on the plugin provider, not replacement descriptors on the
+original. Releasing the private callback restores native delegation and its
+original capability values without any write to the original service.
+
+**The tool-result bridge has a separate accepted compatibility boundary.**
+`internal/runtime-bridge-owner.js` retains its wrappers on the registered
+`run_code` definition's `execute` and `output.presentationMeta`. The latter
+publishes execution-local journal, recovery, binding and presentation evidence;
+the former supplies derived execution arguments when an omitted description is
+generated, while the persisted model-authored arguments remain unchanged.
+This bounded use of a shared tool definition is accepted even though public
+lookup does not guarantee mutation support. It requires those properties to be
+redefinable: frozen definitions or outputs reject execution and are not a
+supported compatibility claim. Frozen original execution providers remain
+supported through the independent composition described above.
+
+The bridge retains call-local settlement isolation, native canonical values,
+output limits, original callback receivers, and descriptor/ownership restoration
+on rollback or disposal. DSH continues to own validation, policy, approval,
+cancellation and final result projection. Acceptance retains this bridge rather
+than claiming that a public per-execution metadata carrier or raw/derived input
+protocol has been implemented. Replacing it becomes necessary if an official
+Host changes this dependency or publishes an equivalent result/input contract.
+The direct-tool projection has its own accepted boundary in
+[ADR 0005](0005-temporary-rejected-cell-edit-transport.md).
 
 ## Alternatives considered
 
@@ -90,8 +147,12 @@ plugin would publish a service it does not implement, making this a provider
 rather than a consumer, and would have to model the wrapped provider's resolution
 semantics for callers that never reach its REPL.
 
-**Forward the resolved spec's directory, deadline, and policy to the session
-kernel.** The kernel has its own directory, budgets, and journal semantics; a
+**Replace descriptors on the registered original.** Public service lookup does
+not grant mutation ownership. Such attachment fails on frozen providers and
+cannot establish a durable extension contract; it is not a compatibility fallback.
+
+**Forward the resolved spec's deadline and policy to the session
+kernel.** Current directory is integrated separately by ADR 0041. The kernel has its own budgets and journal semantics; a
 per-call host deadline would have to be reconciled with the configured budget,
 and confinement the plugin cannot enforce would be reported as if it applied.
 
@@ -101,9 +162,14 @@ escalation it thinks it is offering.
 
 ## Consequences
 
-The plugin activates on both the current and the preceding host generation, and
-one test owner covers the selection rules, the neutral call shape, the descriptor
-takeover, and the release semantics for both. A host that registers neither
+The default bundle and current official base profile use the `ptcRuntime`
+resolve/run shape, also exercised by the frozen Host graphs. Explicit
+`codeRuntime` request-only compositions retain public Loader fixture coverage
+for request identity, replacement and bundle removal. The evidence boundary is
+recorded in [Installation](../installation.md#compatibility-evidence).
+Seam tests cover selection and input preservation for both shapes. Real public
+Loader tests cover frozen originals, exact configuration and spec delegation,
+main-plugin activation, source replacement and bundle removal. A host that registers neither
 execution service cannot be served, and its activation settles with a bounded
 diagnostic naming the missing seam — `no host execution seam (ptcRuntime or
 codeRuntime) is registered` — after the attachment window instead of staying
@@ -111,8 +177,8 @@ pending: the host awaits loader settlement before it becomes usable, so an
 unbounded wait would park every agent, native tool, and unrelated plugin rather
 than failing this entry.
 
-A current-generation service that fails to attach cannot leave the plugin
-unattached while the preceding service is still registered: the preceding
+A resolved-spec service that fails to attach cannot leave the plugin
+unattached while the request-only service is still registered: the request-only
 attachment is restored and the failure is reported through the plugin's own
 logger in addition to the injected fiber's activation result.
 

package/docs/adr/0030-serve-both-typert-codec-generations-from-one-codec.md

@@ -4,7 +4,7 @@ Date: 2026-09-18
 
 ## Problem
 
-PTC Plus publishes its Remote services through DSH's TYPERT registry, and that registry validates every strict codec it is handed before any endpoint exists. The codec carries the decoder for one wire member, and DSH changed where the host reads it: the preceding generation keeps the decoder on `codec.schema` and evaluates `codec.schema.parse(value)`, while the current generation keeps a `create()` factory, rejects a codec without it, and evaluates `codec.create().parse(value)`. The plugin published only the preceding shape, so a release that requires `create` fails registration inside the plugin's own activation: the Host entry never activates and the Client entry reports a failed fiber, although every import, load check, and type-level use still succeeds.
+PTC Plus publishes its Remote services through DSH's TYPERT registry, and that registry validates every strict codec it is handed before any endpoint exists. The codec carries the decoder for one wire member, and DSH changed where the host reads it: a historical schema-based generation keeps the decoder on `codec.schema` and evaluates `codec.schema.parse(value)`, while the current generation keeps a `create()` factory, rejects a codec without it, and evaluates `codec.create().parse(value)`. The plugin published only the preceding shape, so a release that requires `create` fails registration inside the plugin's own activation: the Host entry never activates and the Client entry reports a failed fiber, although every import, load check, and type-level use still succeeds.
 
 ## Decision
 
@@ -12,7 +12,7 @@ PTC Plus publishes its Remote services through DSH's TYPERT registry, and that r
 
 Each generation validates only the member it owns and ignores the other, so one published contract serves whichever shape the installed host implements. Compatibility follows the live acceptance behavior of the registry rather than a release version, and the decoder is published once, so a host that reads both members cannot obtain two different decoders for one wire member.
 
-CI registers the packed contract with the installed host's own registry from the frozen official `latest` and `next` graphs (`scripts/dsh-rpc-contract-smoke.mjs`), so a generation that changes this validation fails the packaging check instead of reaching users.
+CI registers the packed contract with the installed host's own registry from the frozen official `latest` and `next` graphs (`scripts/dsh-rpc-contract-smoke.mjs`). Both frozen graphs read `create()`; they do not exercise a schema-only Host. Unit fixtures cover `schema.parse`, not a complete historical Host installation. The evidence boundary is [Installation: Compatibility Evidence](../installation.md#compatibility-evidence); passing two graphs must not be reported as packaging verification of both codec shapes.
 
 ## Alternatives Considered
 
@@ -24,4 +24,4 @@ CI registers the packed contract with the installed host's own registry from the
 
 ## Consequences
 
-One plugin build serves the preceding and current public codec generations for this surface, and the compatibility rule lives in a single module with the decoder published once. A future generation that requires another member, or that rejects a codec carrying a member it does not know, needs this owner updated; the regression test is CI's registration against the installed registry, which fails on the frozen Host graph that changed instead of on the user's machine. The decoder keeps the project's maintained schema runtime, so a host that validates payloads itself still evaluates the same semantics the plugin's own tests exercise through both members.
+One plugin build carries both the historical schema-based and factory-based codec shapes, and the compatibility rule lives in a single module with the decoder published once. A future generation that requires another member, or that rejects a codec carrying a member it does not know, needs this owner updated; the regression test is CI's registration against the installed registry, which fails on the frozen Host graph that changed instead of on the user's machine. The decoder keeps the project's maintained schema runtime, so a host that validates payloads itself still evaluates the same semantics the plugin's own tests exercise through both members.

package/docs/adr/0031-close-semantic-obligations-by-owner.md

@@ -8,7 +8,7 @@ Focused tests and coverage can prove their selected examples executed, but they
 
 `semantic-obligations.json` is the tracked graph of plugin-owned semantic boundaries. Each obligation records one semantic owner, exact implementation files, disposition, owning contract, preserved observables or declared differences, execution entries, lifecycle states, language or data generations, platform bounds, consumers, oracle, executable evidence and upstream obligations. Dispositions distinguish behavior preserved from an external owner, intentional PTC differences and bounded external surfaces; an omitted or uncertain obligation is unknown and fails validation rather than being relabeled as preserved.
 
-`scripts/semantic-obligations.mjs` validates the graph before build and coverage in `npm run verify`. The exact inventory covers every JavaScript implementation file in `internal/` and `src/`, the public `index.js` and `client.js` entries, and the journal migration entry, with exactly one semantic owner per file. Adding, removing or assigning a source twice fails closed until the graph changes. Contract and evidence files must exist, every obligation needs executable test evidence, dependencies must resolve without cycles, journal versions must remain a contiguous recorded range, and declared language and module generations must equal their executable owners. The command emits counts for preserved, intentional-difference, bounded-external and unknown obligations; zero unknown means closure over the declared plugin source boundary, not equivalence with all current or future Node or DSH behavior.
+`scripts/semantic-obligations.mjs` validates the graph before build and backend tests in `npm run verify`; release-only coverage scheduling is owned by [ADR 0035](0035-run-coverage-only-before-a-new-release.md). The exact inventory covers every JavaScript implementation file in `internal/` and `src/`, the public `index.js` and `client.cjs` entries, and the journal migration entry, with exactly one semantic owner per file. Adding, removing or assigning a source twice fails closed until the graph changes. Contract and evidence files must exist, every obligation needs executable test evidence, dependencies must resolve without cycles, journal versions must remain a contiguous recorded range, and declared language and module generations must equal their executable owners. The command emits counts for preserved, intentional-difference, bounded-external and unknown obligations; zero unknown means closure over the declared plugin source boundary, not equivalence with all current or future Node or DSH behavior.
 
 The graph complements, rather than replaces, focused tests, coverage and independent review lanes. A boundary-specific registry can enforce a stronger relation where the implementation supplies one: worker realm mutations use their classified installation entry and AST check, journal generations use their closed schema, and language/module generations use exported sets. Other records bind exact owner files and evidence so a new boundary cannot enter the tracked source inventory silently; review still evaluates whether an edit inside an existing owner changes its obligation or dependencies.
 

package/docs/adr/0032-own-session-log-facts-in-a-host-only-projection.md

@@ -0,0 +1,27 @@
+# Own session-log facts in a host-only projection
+
+## Problem
+
+Synchronous prompt consumers repeatedly folded the complete session log and separately scanned historical runtime snapshots and tips. Recovery also read an obsolete Session snapshot API, so removing that API could turn unavailable history into an apparently empty session. Independent caches at each consumer would retain duplicate semantic rules and cannot prove a common observation cut.
+
+## Decision
+
+`internal/session-journal-recovery.js` owns one synchronous event transition for the executable call/result timeline. Batch cold recovery and the host-only `ptcPlusSessionLog` projection use that same transition. The projection is registered through `sessionProjections` under its injected Cordis effect, has plain JSON state and an explicit state version, and publishes no Client wire view. Irrelevant log-only events return the previous reference.
+
+The state preserves pending and ambiguous call identities, turn scope, edit-target claims, prune windows, normalized journals and transcript counts. It stores minimal call evidence and deterministic non-content result identity digests, not a second raw event log. Runtime presentation adds the ordered surface sequence vector and recognized runtime records. Replacement follows surface positions, not numeric sequence ranges: a newly appended replacement can occupy an earlier surface position. Historical notice identity, per-trigger ordinal, cooldown and unresolved escalation counts are updated at event entry; synchronous consumers read those facts without scanning the historical arrays.
+
+Asynchronous consumers obtain an immutable cut from the public `sessionQuery.observeSession` reader, use `projectionMode: 'none'`, and release the observation lease. The captured cut is passed through recovery, call matching, no-op confirmation and derived edit execution. Its surface evidence is paired with that cut; a newer live surface cannot silently change an earlier observation. Historical array-backed sessions retain a read-only batch fallback over the shared transition. Missing current services or malformed historical arrays are diagnosed rather than represented as successful empty evidence. Cancellation and Host query failures remain authoritative errors.
+
+The log-fact owner belongs to the plugin/controller lifecycle rather than an enabled worker activation. Disabling the runtime therefore leaves this host-only unit available to retract previously delivered PTC messages, while releasing tools, workers and enabled-generation UI projections. Unloading the plugin releases the unit. This does not keep hidden computation alive or inject a model-visible binding projection.
+
+Result republication preserves the original settlement position and normalized evidence. A content-only prune clone, including a clone of another clone, is not a new execution, edit target, success or claim settlement. If the original result is absent, the original call position bounds the newly reconstructed chronology; later executions remain later. Tip identities retain their delivery positions so discovering an earlier success does not erase warnings delivered afterward.
+
+Projection checkpoints are fold shortcuts only. State version 8 retains each settlement's independent publication index, first-observed index, ordinary/reconstructed classification and normalized run evidence, including ordinary runs without journals. Ordinary-result deduplication retains the first observation's call, event sequence and timeline position; admission requires matching ordinary settlement evidence or an identity-conflict clear, and every ordinary settlement requires its observation. It also retains the processed timeline position and ordered selection clears for turn resets and invalidations. The current frontier must agree with that retained lifecycle history and remain within the processed cut. Latest and editable runs are derived from the newest current-scope publication beyond that frontier; the success index is derived from retained successful publications. Edit targets and claim eligibility at dispatch are reconstructed from first-observed settlements and clears, using the same selection and target capture rules as the live transition. Their source must match the eligible ordinary or derived publication, and both current claim tables must match the reconstructed lifecycle. A late prune reconstruction cannot establish a target for an earlier dispatch. Selected fields and redundant target copies cannot certify their own provenance or chronology, and clones cannot revive a selection across an invalidation frontier. Normalized event facts retain call identity/source, result identity digests and formal source/replacement relations, public prune and turn inputs, journal presence, normalized settlement and recovery-boundary outcomes, and validated rewrites. They retain no result content. Checkpoint admission reconstructs the complete timeline with the same single-event transition used by live folding, then compares every materialized field. Journal/derived/binding facts, ordinary observations, settlements, selection, claims, transcript counters, unavailable evidence, pending/seen identities and the active prune window therefore share one lifecycle interpretation. Typed payload validation and the existing journal/derived/boundary owners validate the retained normalized inputs. The projection also retains presentation input facts: public append/replacement intents, context-step source categories and recognized runtime-message protocol inputs. Ordinary user and assistant content is omitted. These facts align with timeline event identity and drive the same projection transition at admission. The complete reconstructed projection must agree with the checkpoint, including ordered surface nodes, visible records/facts, message indexes, context steps and notice history. A historical catalog record therefore cannot certify its own visibility, and removing all visibility caches cannot suppress an actual append. Prompt consumers continue reading incremental state without raw-log scans. Missing settlements or valid-shaped journal divergences cannot be hidden by deleting their dependent caches. The timeline representation owner validates these relations together with typed table payloads, call/entry identities, normalized journals, derived runs and transcript counts before projection admission. Obsolete v1–v7 state requires refolding the complete log; a nonzero-start suffix alone is rejected with a seq-0 reread diagnostic. The Host owns watermark validation, suffix restore, fork inheritance and refolding. Raw journal ancestry and exact model-visible source relations still own recovery evidence. UI facts, cached state and matching recorded completions are not substitutes.
+
+Submitting a cell reserves its memory configuration with the SessionRuntime owner before the first asynchronous observation on either the run or edit entry. The bridge and derived edit carry that same submission and its captured cut into execution rather than creating a second admission after reading. Runtime or session disposal invalidates that preparation, and an invalidated preparation cannot create a kernel or worker after the reader resumes. Reader failure releases the reservation; a genuinely new submission can use a fresh environment. Caller cancellation with an identified cut is settled by the existing cell owner as a no-op without starting a worker; it retains the caller's reason and does not create an unexplained recovery boundary.
+
+## Consequences
+
+pre-step and assembly read current projected facts rather than materializing history. Recovery and authoring receipt operations are explicit asynchronous reader consumers. Honest checkpoint restore and fork must preserve the same timeline, edit and runtime-message decisions as batch replay. Tests cover serialized transition boundaries, duplicate identities, prune replacement, observation/surface races, real SessionStore/query/registry composition and long unrelated histories.
+
+This migration does not change tool names, journal generations, Host policy authority, output governance or the selected PTC language contract. Public execution-provider composition is owned by [ADR 0028](0028-attach-to-the-host-ptc-execution-seam.md), not this projection. Successful-result metadata and two-tool collapse integration remain separate boundaries.

package/docs/adr/0033-gate-client-visual-usability-in-a-browser.md

@@ -0,0 +1,23 @@
+# Gate Client Visual Usability In A Browser
+
+## Problem
+
+JSDOM can verify component classes and callbacks while the browser paints unusable controls. Optional smoke scripts and saved screenshots leave key style regressions outside normal verification and provide no automatic verdict for focus or disabled feedback.
+
+## Decision
+
+The standard local and CI verification entries run one Client suite followed by deterministic browser layout and visual assertions against fresh actual-renderer fixtures. A shared bounded usability oracle owns contrast, action dimensions, reachability and state feedback. Fault counterexamples retain actual DOM classes and handlers and must be rejected. Browser prerequisites are explicit and absence fails verification. The coverage inventory and exceptions are owned by [the Client visual contract](../client-visual-contract.md).
+
+Packed official-DSH acceptance remains a separate integration obligation under [ADR 0017](0017-track-the-latest-dsh-public-surface.md). It reuses the oracle on actual Host theme surfaces; fixture palettes do not establish Host compatibility. These checks do not change DSH authority, runtime state, program values or the model's tool surface.
+
+## Alternatives considered
+
+**Keep browser checks opt-in.** This permits a standard green gate while CSS is absent or state feedback is lost, which does not satisfy the Client usability obligation.
+
+**Freeze full-page screenshot baselines.** Such baselines couple plugin acceptance to upstream typography and rendering pixels. Bounded computed-style and hit assertions directly test the product obligation, while screenshots remain useful diagnostics.
+
+**Run every browser script independently in the gate.** The layout script would rerun the complete Client suite. Sharing a single fresh fixture generation preserves current-source evidence without that duplication.
+
+## Consequences
+
+Contributors need the locked Playwright Chromium installation before the full gate. Browser checks add work to verification and fail when their prerequisites are unavailable. Their guarantee is bounded by the declared controls and states; extending a UI responsibility requires extending its inventory and counterexamples rather than promising all future styles.

package/docs/adr/0034-keep-program-values-separate-from-output-projections.md

@@ -0,0 +1,29 @@
+# Keep program values separate from output projections
+
+## Problem
+
+An isolated PTC computation can return a value that the parent must continue computing with. DSH's outer execution seam accepts JSON-safe output, so its readable rendering of a BigInt or cyclic graph cannot also be the parent program result. An unsupported transfer likewise has different consequences before dispatch, after a binding completes, and after a cell computes its result.
+
+## Decision
+
+Plugin-owned isolated `code.run` uses the canonical completion of its settled child runtime, decoded by the existing PTC Value V1 codec. The child owns an independent binding root and is disposed after settlement. The private `runTentative` program-completion option validates canonical graph admission without generating model presentation; a sparse graph may fit transfer limits while its unused rendering would exceed them. Only the native execution seam consumes its public JSON-safe projection. An explicit `return undefined` has a `result` property; a child without a return does not. Existing native `run_code` members retain their owner-defined result contract, including when their execution re-enters the plugin. Legacy upstream execution retains its previous contract.
+
+Journal calls already store canonical argument and result envelopes. Cold replay returns exactly the recorded value without redispatching child computation or external effects. Historical codec refusal diagnostics remain readable only when the actual refusal or a codec-owned legacy message exactly matches their recorded diagnostic; arbitrary errors do not acquire that compatibility. Historical strings remain strings; neither a language generation nor a wire migration is required because replay does not recompute the changed bridge result. Renderer text is never decoded or inspected to guess an encoding.
+
+PTC Value V1 retains its explicit support domain. Codec-owned failures retain private structured categories (`unsupported`, `shape`, `budget`) and paths. Native Node brand checks identify known excluded data types without consulting user getters, `toJSON`, constructor names or `Symbol.toStringTag`. Prototype admission uses data descriptors; a hostile or unknown prototype remains unsupported. Proxy reflection in actual encoding still belongs to worker execution and budgets; diagnostic classification does not perform additional reflection.
+
+Parameters reject before dispatch. Result encoding happens only after the owner call completes and reports that fact, possible effects and the absence of automatic retry. A completion encoding failure preserves the live worker and supplies category-specific help. Stable guidance distinguishes direct result transfer, live computation and native tool JSON contracts. Native JSON serialization and BigInt arithmetic retain their own errors.
+
+## Alternatives considered
+
+**Decode rendered strings.** Ordinary strings overlap with renderer output; parsing cannot recover value identity or distinguish a historical string from a canonical value.
+
+**Return rich values through the public DSH seam.** The seam's JSON-safe contract does not permit this. A private canonical child completion already exists and provides the necessary boundary without changing Host packages or public dispatch.
+
+**Expand V1 using structuredClone or Node v8 serialization.** Maintained platform serializers support more data types, but their semantics differ from V1: structured clone can read accessors, normalize class instances and descriptors, and v8 binary output does not provide this project's closed canonical JSON envelope and versioned admission guarantees. Type expansion requires a separately specified generation covering references, own properties, intrinsic state, budgets and historical decoding. Neither platform support nor a diagnostic repair proves those semantics. V1 is retained rather than silently widening or lossy-stringifying it.
+
+**Convert BigInt to Number or JSON text automatically.** Conversion can lose precision or turn computation into string concatenation. Native tool schemas remain authoritative; callers select meaningful explicit representations at those boundaries.
+
+## Consequences
+
+Supported child values retain their types and graph relationships across plugin IPC, while parent and child bindings stay isolated. Unsupported live values remain usable inside their worker, with actionable transfer diagnostics instead of undifferentiated budget advice. This does not add support for Date, Map, class instances or live resources, or imply that a failed transfer undoes an external effect. The wire format, native owner authority and historical recorded results remain unchanged.

package/docs/adr/0035-run-coverage-only-before-a-new-release.md

@@ -0,0 +1,27 @@
+# Run Coverage Only Before a New Release
+
+## Problem
+
+Collecting and merging instrumented coverage on every local verification and commit repeats release-readiness work during ordinary development. Behavioral verification, source-bound commit proof, and coverage thresholds establish different facts, so moving coverage must preserve the complete daily test suite and the independent-review gate.
+
+## Decision
+
+Coverage collection, coverage runner/report regression suites, and instrumented probes run only while preparing a new version for release. `npm run verify` and the `npm run check` proof path retain generated-build checks, syntax validation, Client verification, and the complete ordinary backend test suite without coverage instrumentation. Ordinary discovery selects root `test/*.test.js`; coverage-only suites and collection probes live under `test/coverage/`. The release coverage runner selects both inventories and owns `DSH_PTC_TEST_COVERAGE_SUITE=1` for mixed instrumented cases. Ordinary execution clears that marker. Both runners share the bounded concurrency calculation. Ordinary execution enables module mocks but does not preload coverage hooks or inherit coverage and temporary bytecode settings into the test process.
+
+The Release workflow runs `npm run coverage` against its verified annotated tag before packing or npm staging. The full coverage gate retains compiler source remapping, plugin-source closure checks, 100% line and function coverage, and at least 95% branch coverage. A failure prevents staging. Normal CI keeps its portable runtime and official-Host contracts without collecting coverage. During release preparation, maintainers may run the full gate locally and use `npm run coverage:focus` to diagnose a failed coverage threshold; focused evidence cannot replace the full release gate.
+
+This changes coverage scheduling, not findings-ledger readiness, independent review, source and index identity, or pre-commit authorization from [ADR 0016](0016-archive-resolved-review-findings.md) and [ADR 0026](0026-persist-the-delivery-verdict-against-the-verified-candidate.md). The release authority and immutable artifact path remain owned by [ADR 0022](0022-stage-npm-releases-with-oidc.md).
+
+## Alternatives considered
+
+**Keep coverage in every local verification and commit.** This preserves the old timing but forces development and review to pay the instrumentation and merge cost even when no new version is being prepared.
+
+**Remove the coverage command without retaining the complete backend suite.** This shortens daily verification by silently dropping behavioral evidence. Ordinary verification instead retains every ordinary behavioral case while coverage-specific cases remain in the release inventory.
+
+**Treat coverage regression fixtures as an exception to the daily prohibition.** Those test bodies can start collection or instrumentation even when the package command no longer invokes coverage. The scheduling boundary therefore owns test discovery and mixed-case selection as well as the top-level command.
+
+**Require coverage only in a human release checklist.** This records the intended timing but lets the automated staging path publish a candidate without meeting the thresholds. The Release workflow enforces the gate before creating and staging the artifact.
+
+## Consequences
+
+Daily verification and commit proof no longer establish coverage thresholds. Those thresholds remain a new-version release requirement, and the release job needs enough time for the instrumented suite and report merge. Behavioral regressions still fail daily verification, while coverage deficits may first be discovered during release preparation. The maintained command and diagnostic contracts live in [release coverage](../release-coverage.md), [focused verification](../verification-optimization-work.md), and [publishing](../publishing.md).

package/docs/adr/0036-separate-focused-development-from-delivery-verification.md

@@ -0,0 +1,29 @@
+# Separate Focused Development From Delivery Verification
+
+## Problem
+
+Requiring a complete deterministic gate after every executable development turn repeats long backend and browser matrices while the candidate is still changing. A focused command that silently defaults to all tests creates the same cost when an agent forgets a selection. Full behavioral validation and source-bound delivery proof remain necessary, but neither is a useful failure-localization loop.
+
+## Decision
+
+Development and independent review select the changed semantic owner and its bounded consumers. Executable edits alone do not trigger a complete gate. Backend and browser focused package entries require exact file or case selections before execution; listing the inventory is permitted without executing it. Client focused execution requires a test-name pattern. Independent layout diagnostics generate fresh HTML from only the two Client test owners that export all states. The complete visual gate retains the full Client suite once, followed by every layout and fallback case.
+
+Complete validation runs on a stable executable candidate when preparing delivery/commit proof, when explicitly requested for full validation or timing, or when a specific cross-suite risk cannot be settled with focused evidence. [ADR 0039](0039-verify-documentation-without-runtime-suites.md) selects documentation checks for a strictly classified documentation-only delivery candidate. Use `verify` with unresolved findings and `check` otherwise. A valid result for an unchanged candidate is reused rather than repeating its component suites. A full failure returns to a discriminating focused check before the next stable-candidate gate.
+
+These rules change scheduling, not test obligations, ordinary/release discovery, coverage thresholds, independent review, ledger readiness or pre-commit authorization. Focused evidence never becomes a commit proof. [ADR 0026](0026-persist-the-delivery-verdict-against-the-verified-candidate.md) retains the review/proof contract, [ADR 0033](0033-gate-client-visual-usability-in-a-browser.md) retains complete browser validation and [ADR 0035](0035-run-coverage-only-before-a-new-release.md) retains release-only coverage.
+
+Runners expose inventory, concurrency and elapsed stage time. Agents wait on the existing process in intervals no longer than 60 seconds, remain responsive to new input, and inspect stage output when elapsed time exceeds expectations. A slow complete run does not authorize retries or a second concurrent copy.
+
+## Alternatives considered
+
+**Run a complete gate at the end of every development turn.** This makes turn boundaries, rather than candidate stability or delivery needs, determine expensive work and repeatedly verifies intermediate trees.
+
+**Remove complete backend or browser cases.** This reduces time by weakening acceptance. Bounded concurrency, disjoint semantic partitions and eliminating duplicated fixture generation preserve the original obligations.
+
+**Rely only on an instruction to choose focused tests.** A missing selector can still start the entire suite. Selection-required package entries reject that error before starting any tests or browsers.
+
+**Treat focused success as delivery authorization.** This conflates selected behavioral evidence with complete validation and source/index identity. The final gate and pre-commit proof remain required for delivery.
+
+## Consequences
+
+Development results explicitly cover selected responsibilities. Cross-suite regressions may first appear at the stable-candidate gate or CI. Contributors must select relevant owners and consumers rather than claiming whole-tree correctness from samples. Maintained commands and examples live in [verification](../verification.md); the agent entry rules live in `AGENTS.md`.

package/docs/adr/0037-keep-tool-hover-previews-passive.md

@@ -0,0 +1,52 @@
+# 0037 Keep Tool Hover Previews Passive
+
+## Status
+
+Accepted
+
+## Context
+
+Execution rows occur inside the conversation's scrolling surface. A pointer can
+cross a row because content moves beneath it. An interactive hover portal with
+its own scrollbar then becomes the wheel target, changing the meaning of a
+gesture already being used to browse the conversation. A longer delay alone
+does not preserve scrolling once that portal opens.
+
+## Decision
+
+Execution-row hover is a passive quick peek. The plugin owns a compact preview
+with bounded recorded source and result excerpts, explicit truncation text and
+a hint to expand the row. Neither the preview nor its descendants participate
+in pointer hit testing. Its layout uses clipping, not a scroll container. Full
+source, result, Copy and Inspect remain in the explicitly expanded row.
+
+`src/client-tool-hover.js` owns the lifecycle. A shared passive wheel/scroll
+observer cancels pending and visible previews. Scrolling must be idle before a
+fresh pointer movement or entry can start the next dwell; a stationary pointer
+does not reopen a preview after scrolling. Keyboard focus is an explicit
+request to preview. Escape, blur, pointer departure, expansion, touch and
+unmount retain dismissal and original expansion semantics.
+
+Use the platform's manual Popover top layer, with a public React Portal fallback.
+Placement measures only the plugin's anchor, pointer and preview. Prefer the
+right of the pointer when the current viewport has enough room; otherwise
+place above or below the row. Observe live owned-anchor and viewport size changes.
+A default-enabled interface setting controls mouse and keyboard preview without
+removing explicit row expansion. The plugin does not
+inspect or write Host ancestors, cancel scrolling, forward synthetic wheel
+events, patch Host packages or add another authority boundary. The interactive
+public HoverCard remains available to other consumers; it does not own this
+passive tool preview.
+
+## Consequences
+
+Users see a short preview on deliberate hover and browse or copy full content
+by expanding the row. Small viewports may clip more preview text or provide
+insufficient room for a preview; the complete row remains available. Excerpts
+are UI presentation and establish no claim about canonical value completeness,
+model knowledge or state retention.
+
+Browser evidence must use real wheel gestures over a scrollable conversation,
+including pending preview, visible preview footprint and stationary-pointer
+continuation. It must preserve keyboard/touch expansion and complete recorded
+content. Theme and viewport checks cover both native Popover and Portal fallback.

package/docs/adr/0038-freeze-session-capability-plans.md

@@ -0,0 +1,71 @@
+# 0038 Keep Session Capability Plans Stable
+
+## Status
+
+Accepted and integrated through the public prompt and execution seams. Frozen plans, scoped execution projection, shared loaders, persistent family statistics, refresh, description recovery and result previews have focused executable evidence in the [public-interface coverage](../context-public-interface-coverage.md). This ADR does not claim demonstrated ordinary-task token savings; the [implementation plan](../context-optimization-plan.md) distinguishes deterministic implementation from paid task calibration.
+
+## Problem
+
+PTC Plus can improve continuous computation while increasing the context consumed to complete ordinary tasks. Retaining the full native SDK and adding discovery instructions does not itself provide progressive disclosure. Conversely, hiding descriptions without making capabilities discoverable can cause additional exploration or incorrect calls. Shorter individual requests therefore do not establish a useful optimization.
+
+Capabilities also constitute the model's working environment. Redistributing them whenever statistics or saved settings change makes that environment unpredictable, even if each new distribution looks efficient in isolation. A capability advertised as removed must be absent from the supplied discovery and execution surfaces; a callable placeholder that rejects later does not establish that absence.
+
+[ADR 0043](0043-compose-capability-and-context-policies.md) extends new environments with independent availability/disclosure rules, allocation inputs, collection, recovery and preview selections. The contracts below remain the historical v1/v2 recovery basis; freezing, authority and observation boundaries remain applicable.
+
+## Decision
+
+The managed domain is the task capabilities that DSH and its other plugins expose to the model, including tools, Skills and MCP resources or resource templates where public owner surfaces permit consistent integration. JavaScript/TypeScript, Node, the REPL, PTC Plus's own public APIs and Global User Bindings remain outside this management domain. DSH retains authorization, policy, dispatch and lifecycle ownership. The plugin uses published public extensions of the current official Host and does not create a parallel dispatch registry or patch Host packages.
+
+Capability management has a total switch, independent statistics settings and independent manual configuration. There is no separate automatic/manual/off mode state. An explicit per-capability full, on-demand or closed selection wins over statistics. Invalid, disabled or unusable statistics leave manual configuration and its editable baseline effective. Automatic selection can choose full or on-demand disclosure; it cannot close a capability. Turning management off removes this feature's contribution while retaining DSH's authority and PTC Plus's separately configured computation behavior.
+
+Full disclosure supplies the complete owner-defined calling contract. For a Skill it supplies the full catalog description, while the instruction body still loads on use according to the owner's model/user invocation eligibility. A user-only Skill remains configurable but advertises its user slash entry rather than the model loader. On-demand capabilities remain discoverable through bounded navigation and search, with matching full contracts preferably returned in one interaction. Closing a capability consistently removes its descriptions, discovery entries and applicable runtime exposure, including REPL members. Public integration gaps cannot be relabeled as successful closure or filled with a second permission system.
+
+Automatic allocation uses session-family coverage rather than raw call volume. A root session and all its descendant agents contribute at most one use of a given capability. The denominator includes only families in which that capability was actually available. A tool use is a real call admitted to DSH’s around-execution pipeline with a final canonical outcome, including failed calls and valid wrapper-provided outcomes. It does not prove that the registered body ran or that an external effect occurred. Calls without execution admission and explicit pre-dispatch cancellation or unknown-tool outcomes do not create uses. Description inspection and cold replay do not create uses. Each capability and statistical scope uses its most recent configurable N eligible families, without wall-clock decay. Workspace evidence is primary; user-global evidence is a cold-start reference when local evidence is insufficient. An editable initial common set supplies the baseline when useful statistical evidence is absent, without fabricating observations.
+
+Allocation considers both coverage and contract length within a configurable explanation budget. The directory has its own bound; every long-tail name need not remain in the prompt. Explicit full disclosure overrides the explanation budget, with an observable overage rather than silent truncation or demotion. A budget overage does not establish that a request fits a model's physical context limit.
+
+A session capability plan records the effective enablement and disclosure choices when the session begins. Statistics and saved configuration do not redistribute an existing session, including after restoration. A user-triggered slash command explicitly refreshes the session. Refresh synchronizes descriptions, discovery and runtime exposure and supplies a durable, model-visible notification consistent with what actually became effective. A UI receipt alone is insufficient. Refresh uses Host lifecycle boundaries and does not require a paid model request merely to execute the human command. A stored plan cannot preserve a capability that its Host owner has actually removed or forbidden. Symmetrically, a live Host member that the frozen plan has not yet allocated remains declared under the Host's own presentation — or under its explicit availability closure — until refresh folds it into the plan; a pending allocation boundary never removes the member's identity from the declaration, discovery or dispatch surfaces. The frozen choice does not freeze the calling contract. Live parameter, output, instruction-dependency and Skill invocation changes append a validated `ptc-capability-contracts/v1` notification at an accepted step, retaining the original plan digest and current revision vector. Full choices receive complete replacement contracts; on-demand choices receive a revision notice and current discovery; removed capabilities receive a withdrawal. Saved settings and statistics still cannot reallocate that session. Unchanged views do not repeat notifications, and recovery uses visible validated notifications without rewriting the initial plan or prefix.
+
+Explicit session choices and saved choices have separate owners. `/capabilities set session <encoded-id> <full|on-demand|closed|automatic|inherit>` changes only the current session. `automatic` explicitly removes that identity's saved manual override from the effective input; `inherit` removes its temporary override and resumes the adopted source choice. Ordinary `/capabilities refresh` adopts current saved configuration while retaining temporary choices. `/capabilities set global <encoded-id> <full|on-demand|closed|automatic>` saves through the public revision-checked settings writer and updates this session in the same Host maintenance operation, clearing only that identity's temporary choice. Other existing sessions remain frozen. Server choices allow only `closed`, `automatic` and session `inherit`; their closure precedes child choices, and reopening preserves children.
+
+An initialized session publishes the complete new snapshot through its real append-only plan message. Before the protected system head exists, the formal `/capabilities` command returns its validated pending proposal in the structured receipt inside `CommandResult.text`; the Host alone records the paired `command/run` and successful `command/done`. These log-only command facts are not model knowledge. The first accepted step publishes that proposal to the model. Restoration reads successful receipts with exact command identity and raw input pairing, and plan messages, in order after the most recent explicit provider disablement; a routine provider release (`unloaded`) is an infrastructure fact and keeps the recorded plan as the session's restored baseline, so saved configuration still does not redistribute a resumed session. Restoration validates source/effective equality and the planner result, and does not repeat a global write, load a Skill body or execute a historical effect. Failed, cancelled, unpaired or damaged command facts cannot prove a choice; an unconfirmed live proposal is discarded before a later accepted step, and a late handler result cannot revive it. External plugins must not call `appendPluginRecord`, even though it is exported. History observations use the public `sessionQuery` cut; new production reads do not use deprecated synchronous Session readers.
+
+All mutations use public `agent.runMaintenance`, which may reject a busy Agent. The plugin does not queue another session scheduler. Identity, inventory and management preflight precede a global write; the write uses the settings entry's actual namespace and revision. Global saving and session publication are different transactions: a saved choice remains saved if subsequent publication is refused or cancelled, while the old effective environment is retained and the receipt reports saved-but-not-applied. No automatic rollback overwrites a later settings writer. A committed operation followed by lost UI connectivity has an unknown UI outcome, so users inspect the actual plan before retrying. Target-specific read-only catalog commands include closed items for user re-enablement without publishing them to model discovery or counting them as use.
+
+The existing prefix contract remains in force: unchanged configuration, model route and native capability view produce byte-stable plugin system text and ordered tool schemas. Statistical observations and session-plan facts belong in source-backed, reconstructable session contexts; treating a different plan as a new exception to prefix stability is not permitted. Reducing the original native SDK requires an owner-compatible public composition path, not a duplicate catalog appended beneath the unchanged full SDK.
+
+Initial plans retain the v1 format. Explicit session choices use `ptc-capability-environment/v2`: `sourceSettings` is the adopted frozen saved configuration, `sessionOverrides` is the session-only input, and `settings` plus `plan` are validated derivatives. Plans are assembled before the first model request. Through the public accepted-step batch, the initial plan precedes task-dependent messages when no task history has been committed, after the Host-owned protected system head. Bounded navigation uses concise purpose guidance for available capability categories, rather than copying per-capability descriptions or selecting long-tail entries by identity and fit. It depends on configuration and inventory rather than automatic membership. Explicit full contracts precede selected baseline contracts and other automatic additions, with stable identity ordering and shared dependencies supplied once. Statistical counters and source digests do not enter rendered text. This extends reusable prefixes across different tasks and preserves earlier groups when statistics change; it does not promise provider cache hits. Full owner descriptions belong in full disclosure or requested discovery, not in the category directory. Existing sessions remain frozen, refresh and recovery append after retained history. Recovery validates the initial format, derived plan and exact rendered body. New snapshots record their navigation text; existing v1 snapshots without that field retain the previously emitted navigation contract.
+
+After compaction, a separate bounded description-recovery operation may restore recently actually used, previously expanded and still-valid API descriptions. It deduplicates against the model-visible surface, does not redistribute the session plan and does not automatically restore Skill bodies. This is not authorization to add a default REPL state projection or weaken binding provenance requirements.
+
+Large model-facing results and logs use bounded previews with retrieval of retained complete presentation content through existing Host facilities. Omission does not alter canonical program values or turn successful computation into failure, and retrieval does not rerun the original operation. Formatted retained text is not a substitute for canonical typed values.
+
+The acceptance target is non-regressing quality and lower complete-task token consumption than native PTC with PTC Plus disabled on representative ordinary tasks. Accounting includes actual descendant agents, exploration, retries and all observable model requests, with cached input, uncached input and output reported separately. Missing usage remains unknown. Plugin-specific success, fewer prompt bytes and a higher cache-hit rate cannot substitute for this target.
+
+MCP management has two levels. A `mcpServers.<server>: closed` manual control disables that server's tools and resource access before per-member disclosure choices are applied. Removing the server control restores the saved per-tool selections; it does not rewrite them. Membership is captured from the public MCP server directory or attributed MCP sections and the registered qualified tool namespace, and recorded as optional `mcpServer` evidence in the frozen inventory. Ambiguous namespaces cannot be closed by guessing an owner. Previously recorded inventories without this field retain their original per-member semantics. Server controls are configuration identities, not callable capabilities or new tool schemas. Settings can observe the Host's unprojected prompt sections through a plugin-defined public assembly context that bypasses PTC session preparation; observation neither freezes a plan nor loads binding inputs. Saving either level retains the existing new-session/explicit-refresh boundary.
+
+## Alternatives considered
+
+**Keep the full SDK and add more discovery guidance.** This preserves easy direct access, but adds an explanation path without removing the original context cost. Current discovery remains a useful implementation input; its existence is not evidence of progressive disclosure or savings.
+
+**Make every capability on demand.** This minimizes the initial catalog but can force repeated discovery for common work. A bounded common set with manual overrides and measured coverage addresses both initial cost and later interaction cost.
+
+**Continuously redistribute active sessions.** Reacting immediately to statistics or saved settings makes allocation current, but changes the environment beneath ongoing computation and harms prefix stability. New-session planning plus explicit refresh and deliberately scoped human choices preserves predictability.
+
+**Expose three mutually exclusive management modes.** Automatic, manual and off outcomes are already derived from the total switch, statistics and manual settings. Persisting another mode introduces redundant state and obscures the independent validity of manual configuration.
+
+**Hide descriptions and reject later calls.** This leaves the execution environment inconsistent with the advertised absence and adds a policy layer that DSH already owns. Closure requires removal from the supplied surfaces.
+
+**Rank raw calls globally with time decay.** Repeated calls and large agent families can dominate the ranking, project differences disappear, and an idle project loses its baseline without new evidence. Bounded family contributions, workspace-first scopes and eligible-family windows address those specific distortions; they do not claim to measure latent task demand without bias.
+
+**Restore every expanded contract or Skill after compaction.** This can recreate the context growth that compaction removed. Budgeted recovery of actual recent API use retains useful instructions while leaving other descriptions and Skill bodies on demand.
+
+**Lower execution-output limits to constrain prompts.** An execution or transport failure has different consequences from a presentation omission. Separate preview budgets preserve computation and retrieval semantics.
+
+**Conflate temporary choices with saved configuration.** It leaks one session's intent to new sessions and named configuration exports. Separate source settings and explicit temporary inputs preserve scope and reconstructable allocation.
+
+## Consequences
+
+The model receives a more predictable environment and users can inspect and override allocation. Implementation must jointly prove presentation, discovery, execution, refresh and restoration behavior rather than treating prompt editing as sufficient. Skills, shared MCP loaders, scoped tool registrations and retained runtime references require explicit public-surface evidence before complete coverage can be claimed.
+
+Statistics require durable identity, bounded family accounting and a usable fallback. The [component contracts](../capability-planning-components.md) define family settlement and capability revision handling; `/capabilities refresh` implements the explicit session transition, with evidence in the [public-interface coverage](../context-public-interface-coverage.md). Contract budgets and discovery can themselves affect observed usage, so calibration must measure quality and whole-task cost rather than optimize coverage scores alone. Default parameters still require ordinary-task calibration; no unmeasured numeric default is established by this ADR.

package/docs/adr/0039-verify-documentation-without-runtime-suites.md

@@ -0,0 +1,29 @@
+# Verify documentation without runtime suites
+
+## Problem
+
+A document-only commit previously ran every backend and browser test to obtain its source-bound proof. Those suites cannot establish whether prose, links or contributor instructions are correct, and unrelated environment failures can block a documentation correction. Moving procedures out of the default agent entry also has little benefit if every verification action reloads review coordination and release instrumentation details.
+
+## Decision
+
+`check` compares the complete source inventory against HEAD, including additions, deletions, untracked source files and Git modes. Only regular non-executable Markdown changes under `docs/` or in the four root documents `AGENTS.md`, `CONTEXT.md`, `README.md` and `README.en.md` select documentation verification. Every other change, an unborn HEAD or an unchanged candidate selects full verification. Templates and test fixtures are executable inputs to their consumers and are not classified by their Markdown extension alone.
+
+Documentation verification checks diff whitespace, local link target existence and literal npm script references in changed documents and their referrers. It does not execute examples or contact external services. Independent review establishes semantic accuracy, instruction routing and heading-anchor correctness. `verify:docs` exposes this path for development and rejects a mixed candidate before launching any runtime suite. `verify` continues to request full behavioral validation explicitly; `check --full` requests full validation with a source proof even for documentation changes.
+
+Both `check` branches retain ledger readiness and source/`HEAD` stability, but `check` does not enforce independent review or staged-tree identity. `review:finalize` enforces the recorded independent review plan and lane evidence after the proof exists, and pre-commit enforces exact prospective-index identity against the staged tree. The verification proof records the chosen scope as `documentation` or `full`; a documentation proof makes no claim about runtime test success. Existing proof identity and review invalidation rules remain in [ADR 0026](0026-persist-the-delivery-verdict-against-the-verified-candidate.md). This changes the documentation delivery branch of [ADR 0036](0036-separate-focused-development-from-delivery-verification.md); executable changes retain the complete delivery gate.
+
+The default agent entry routes verification selection to `docs/verification.md`, review-state actions to `docs/review-procedure.md`, and release coverage to `docs/release-coverage.md`. Applicable requirements stay mandatory at their action boundary. Old verification section links remain as short forwarding sections. Test descriptions state the operation and observed contract; exact APIs, source fixtures, diagnostics and security properties remain accurate.
+
+## Alternatives considered
+
+**Run all runtime suites for every document change.** This spends time on an unchanged implementation while leaving documentation correctness to the same review still needed afterward.
+
+**Permit manual hook skipping for documentation.** An exception can finish one commit but supplies no durable classification, source proof or repeatable validation path. The scoped check preserves those checks without requiring another exception.
+
+**Classify every Markdown file as documentation, or inspect only the staged diff.** Test fixtures, templates, modes and unstaged source changes can affect executable behavior. The complete source inventory and explicit path boundary keep these changes on full verification.
+
+**Automatically treat all test-name and comment edits as documentation.** Names participate in selectors and fixture exports, and source-looking comments or strings may themselves be test inputs. Development uses focused evidence; test-file changes retain full delivery verification.
+
+## Consequences
+
+Documentation delivery no longer depends on browser, runtime or cross-platform evaluation prerequisites. The checker proves mechanical references only; reviewers still need the affected contract owners. Executable changes can still expose cross-suite failures at the final gate. Reference routing reduces default reading without changing who owns a requirement, and does not establish provider acceptance rates or actual model-token savings.