super-dsh 0.3.0-a → 0.3.0-d

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/cheatsheet.md

@@ -1,67 +0,0 @@
-# Cheatsheet — dsh-dev-skill
-
-Decision rules and quick tables. Every line helps you decide something.
-
-## Which extension surface? (seam-selection)
-
-| You want to… | Use | Not |
-|---|---|---|
-| Add a model-facing tool | `defineTool` into `ctx.tools` | fork a core |
-| Change policy on existing tools | event gates (`tools/pre-execute`, monotonic guards) | rewrite tools |
-| Add policy w/o forking providers | companion plugin on `fs/*` or `tools/post-execute` | provider fork |
-| Swap a capability (shell/fs/llm) | provide at the seam (Definition+Provider+Consumer) | bundle a copy |
-| Contribute UI | `ctx.slots.inject` + fresh list id | runtime-import other plugins |
-| Change a plugin's config | later-layer row restatement (whole config) | field merge (doesn't exist) |
-| Iterate on a local plugin | `--patch` absolute-path insert row | install loops |
-| New provider backend | `LlmAdapter.stream()` + `registerAdapter` | wrap another adapter |
-| Stream to browser | Connection Fetch exact route | Remote method (unary only) |
-| Long-running tool work | `ctx.jobs.start` → `{kind:'background',jobId}` | prose ids |
-| Per-session derived state | `ProjectionDefinition` | manual `session/event` fold |
-| Plugin persistent data | `defineDomain` + `storageDomain.open` | ad-hoc files |
-| Model-visible input | extend `SessionEventMap` (log it) | inject outside the log |
-
-## Hard rules (fail-loud / fail-closed)
-
-- Sandbox mode unavailable ⇒ `SANDBOX_UNAVAILABLE` — never silent unconfined passthrough.
-- Approval absent/unanswerable ⇒ deny. Only `allowed-once` grants; escalation is one-shot, strictly wider.
-- `provide` throws on duplicate name within a scope — sibling shadowing doesn't exist (ancestor/isolate only).
-- Unrecognized session event type ⇒ treated required (refuse reconstruction); opt-in `ignorable:true` only for loss-safe records.
-- Non-JSON payload ⇒ rejected at `Session.append`.
-- Adapter can't honor a `GenerateOptions` field ⇒ throw `LlmError('UNSUPPORTED_OPTION')`, never drop silently.
-- Plugin reading undeclared optional service ⇒ `ctx.get(name)`, never `ctx.<name>` (ancestor-only walk throws).
-- Config row override ⇒ restate every key; whole-config replacement, no deep merge.
-- A config tree omitting an injected `Requires:` service fails to compose.
-- Model-visible means logged: model requests must be reconstructable from the session log.
-
-## Key defaults & thresholds
-
-| Thing | Default / value |
-|---|---|
-| `SandboxMode` | `read-only` |
-| `ApprovalPolicy` | `ask` (fail-closed); `never` for CI |
-| Retry policy | `ResolvedRetryPolicy` 5 retries, agent-level |
-| `dshHome` | `$DSH_HOME` → `~/.dsh` |
-| Session formats | v0 `session.jsonl[.zstd]`; v1+ `session.vN.jsonl[.zstd]`; committed paths never renamed |
-| Surface event types | exactly 3: `user/message`, `assistant/message`, `tool/result` |
-| Profiles | `web`, `headless`, `sdk`, `sdk-minimal`, `acp` |
-| Layer order | bundles → profile → home → `--patch`; later wins |
-| LLM usage counts | input + cacheRead + cacheWrite = billed input |
-| Env-var hygiene | scrub `*KEY*/*SECRET*/*TOKEN*/*PASSWORD*`; spill dirs 0700, files `'wx'` 0o600 |
-
-## Tells & smells
-
-- New plugin does nothing ⇒ check `FiberState.PENDING` (silent wait on missing service) and module-specifier spelling.
-- Plugin exports look dropped ⇒ `unwrapExports` trap: Loader prefers `exports.default` (postmortem 0001).
-- `!!js` in `disabled` always-truthy ⇒ expression objects are never falsy — silent permanent disable (postmortem 0002).
-- Tools suddenly ungated ⇒ observation-policy plugin not loaded beside fs tools.
-- Settings lost secrets ⇒ someone did `replace()` from a redacted descriptor.
-- Exit-code-based sandbox blame ⇒ use runnerFailureRules + denialSignatures, not exit status (postmortem 0004).
-- Git-installed plugin broke ⇒ missing `prepare` script or `allowBuilds` entry.
-
-## Workflow quickies
-
-- Verify composed config: `--dump-config` (grep your plugin).
-- Catalogs are generated: rerun `gen-tool-catalog`/`gen-config-catalog` style build steps; never hand-edit.
-- After changing client-visible signatures: rerun the strict build pipeline (`build:lib` faces) to regenerate Client declarations/codecs.
-- Stacked PR fix: fix the introducing PR, propagate up-stack.
-- i18n pair edited ⇒ update counterpart + re-record hashes in the same PR (CI red-flags drift).

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/glossary.md

@@ -1,57 +0,0 @@
-# Glossary — dsh-dev-skill
-
-Alphabetical key terms. Format: **Term** — definition (Ch N).
-
-- **Activation** — process-local period a continuable child Agent is resident; one per live child Session (Ch 14)
-- **asOfSeq** — snapshot watermark: seq of the last event a projection value reflects; −1 = empty log (Ch 16)
-- **BlockAssembler** — shared fold turning a `StreamChunk` stream back into `ContentBlock`s; reassembly is never each adapter's job (Ch 17)
-- **Bundle** — distribution format for Cordis config rows + code (`dsh.bundle` manifest); stays patchable by layers above (Ch 6)
-- **Capability seam** — swappable capability with three mandatory roles: Service Definition, Provider, Consumer (Ch 7)
-- **Compat block** — per-provider request-shape corrections in settings (`supportsDeveloperRole`, `maxTokensField`, `thinkingFormat`) (Ch 1)
-- **ConfinedArgv** — wrapped argv + enforcement fact, denialSignatures, runnerFailureRules returned by `ctx.sandbox.confine` (Ch 15)
-- **Continuable child** — durable child Session with optional live Activation; steerable/resumable, unlike one-shot SubagentRun (Ch 14)
-- **Declaration merging** — TS-only augmentation of the Cordis `Context`/`Events` interfaces; how plugins extend event maps (Ch 4)
-- **Derived history** — model transcript is folded from the session log (`deriveMessages()`), never stored separately (Ch 13)
-- **DomainSpec / defineDomain** — typed plugin persistence spec (zod, layout, compatibleVersions) opened via `storageDomain.open` (Ch 16)
-- **EpochHeader** — logged request state (config+system+tools) reconstructed from the latest `request/header` snapshot (Ch 13)
-- **Execution world** — fs + subprocess + sandbox move together on one provider swap (Ch 7)
-- **Fiber** — per-plugin runtime lifecycle instance (PENDING→LOADING→ACTIVE→…); the unit the registry loads/reloads (Ch 4)
-- **Fail-closed approval** — `approval/request` waterfall; absent or unanswerable asker = deny, never silent allow (Ch 7, 15)
-- **finalizeContent** — ToolDefinition-owned last content-only invariant run on a snapshotted result (Ch 8)
-- **FsObservation** — present@version / absent record per owner session; drives guarded write/edit decisions (Ch 15)
-- **InboxTarget** — `'next-turn' | 'next-step'` pending-message lists steering the agent loop (Ch 13)
-- **inheritedEventCount** — exact fork-inherited prefix length stored beside the fork header (Ch 16)
-- **inject** — hard service requirements on a plugin; entries start concurrently, ordering comes from inject not YAML position (Ch 4)
-- **InvariantInstaller** — package-attributed check bundle run in a dedicated child fiber via `ctx.invariants` (Ch 13)
-- **isolate** — Context scope label; service visibility is ancestor/isolate only — sibling shadowing does not exist (Ch 5)
-- **Layer order** — bundles (listed order) → profile patch → home patch → `--patch` argv; later layers win by whole-row restatement (Ch 2, 6)
-- **Live-preferred corpus** — session query prefers live `ctx.sessions`, falls back to persisted logs (Ch 16)
-- **LlmAdapter** — abstract provider contract: `stream()` emits `StreamChunk`s; one adapter call = one attempt (Ch 3, 17)
-- **LlmError** — stable-code error type; preserved by the agent loop; use for UNSUPPORTED_OPTION etc. (Ch 3, 17)
-- **Monotonic guard** — deny-or-abstain check with protected identity, registered after pre-execute allow, before execute; can never force-allow (Ch 8, 15)
-- **Peer dependency** — requirement for the host's shared service instance; bundling your own copy breaks identity (Ch 8)
-- **Persist-before-event** — attachments are durable before the owning session event is appended (Ch 16)
-- **PreToolDecision** — allow | deny(reason) | ask from `tools/pre-execute`; only `allowed-once` approval grants (Ch 15)
-- **Profile** — named composition in harness home listing bundles + user `cordis.patch.yml` (`web`, `headless`, `sdk`, `sdk-minimal`, `acp`) (Ch 6)
-- **ProjectionDefinition** — pure synchronous per-session state unit the projection registry drives, backfolds, and checkpoints (Ch 16)
-- **Remote controller** — API controller projecting a seam onto the Remote namespace; redaction/refusal live there (Ch 7)
-- **RemoteResult<T>** — client-remote result discriminated by `code`, never rejected; branch `if(!result.ok)` (Ch 19)
-- **Rescope** — vendored Cordis published as `@deepseek-ai/*` to avoid squatting upstream registry names (Ch 6)
-- **Reserved transport** — `run_code` (`ptc`/`both`): only wire-contribution tool, excluded from filterable layers (Ch 11)
-- **Revision token** — opaque settings/storage stat token; equal ⇒ unchanged, unequal promises nothing (Ch 16)
-- **SandboxMode** — default `read-only`; escalation is one-shot, strictly wider, needs justification (Ch 10, 15)
-- **session/end-seed** — constructor-only marker separating fork-inherited seed history from live work (Ch 12, 13)
-- **SessionEvent / SessionEventMap** — typed append-only log entry `{type, seq, time, data}`; vocabulary is merge-extensible (Ch 12)
-- **SettingsDescriptor** — `{ns, schema, value, revision, base, user, applies}` with mandatory `redactSecrets` on wire (Ch 18)
-- **Shadow price** — compaction metering: `shadowedRange`/`shadowedSeqs`/`shadowedTokenCount` on the replace op (Ch 12)
-- **Slot cardinality / priority** — single/list/keyed/chain dispatch axis; lower priority renders first; cell-id reuse = replacement (Ch 18)
-- **SpillRef** — `{locator, bytes, retrievalHint}` for tool text exceeding inline budget; locator opaque (Ch 14)
-- **Step / Turn** — step = one model request plus its tool calls; turn = zero+ steps, opens at first claim, closes when nothing is owed (Ch 6)
-- **StreamChunk** — closed 7-variant wire union (block-start/delta/block-end/usage/finish/…) adapters emit (Ch 17)
-- **SurfaceEventType** — the only three message-producing log types: `user/message`, `assistant/message`, `tool/result` (Ch 12, 13)
-- **TypertLookupMap** — wire↔object identity table for complex Host params crossing the Remote boundary (Ch 9)
-- **Vendoring** — pinned source under `vendor/<dir>/`, published as a release member (Ch 19)
-- **Waterfall veto** — returning without calling `next()` short-circuits the chain; observers must always call `next()` (Ch 4)
-- **WebBootGraph** — composed module graph written to `window.__DSH_BOOT__` before parser-preloaded scripts (Ch 17, 18)
-- **Whole-value event rule** — state-carrying log events carry complete post-change state, never deltas (Ch 16)
-- **unwrapExports trap** — Loader prefers `exports.default`, dropping sibling `inject`/`name`/`Config` (Ch 21)

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/patterns.md

@@ -1,88 +0,0 @@
-# Patterns — dsh-dev-skill
-
-Techniques and design patterns from the official docs. Format: name, when, how, trade-offs.
-
-## Three-Role Capability Seam
-**When to use**: a capability has ≥2 plausible implementations (shell backend, LLM provider, storage).
-**How**: abstract Service Definition (the seam, e.g. `ctx.fs`) + Provider subclass + thin provider-neutral Consumer tools. Keep model-facing tool names stable over providers.
-**Trade-offs**: more files/roles; pays off only for real replaceability — don't split a simple tool.
-
-## Request/Spec Split
-**When to use**: a seam has implementation defaults or caps.
-**How**: `resolve(request)` materializes a fully-resolved spec (workdir/timeout/stdoutMaxBytes…) before run/start; no hidden `??` inside execution.
-**Trade-offs**: one extra object; execution code becomes branch-free and testable.
-
-## Event-Gate Companion Plugin
-**When to use**: adding policy without forking providers (read-before-write, spill policy).
-**How**: listen at `fs/write-intent`/`fs/edit-intent` or `tools/post-execute` waterfalls instead of registering a provider.
-**Trade-offs**: policy lives beside, not inside, the provider — must be loaded alongside (bare fs tools lose the guard).
-
-## Framework-Drives-Domain-Computes (Projection)
-**When to use**: per-session derived state needed by host or clients.
-**How**: register a pure synchronous `ProjectionDefinition`; never subscribe to `session/event` and fold yourself.
-**Trade-offs**: constrained shape; the registry gives you backfolds, checkpoints, and `asOfSeq` for free.
-
-## Typed Domain over Routed Backend
-**When to use**: plugin persistence that is not a session event.
-**How**: `defineDomain` spec (zod, layout, compatibleVersions) + `storageDomain.open`; sync reads, write-chain durability before `domain/changed`.
-**Trade-offs**: schema discipline; backend routing becomes config (`storage-domain.backend`), not code.
-
-## One-Adapter-Call-One-Attempt
-**When to use**: writing an LLM adapter.
-**How**: disable provider-library retries; adapter `stream()` emits `StreamChunk`s; recovery happens at the agent-loop level; fold blocks with the shared `BlockAssembler`.
-**Trade-offs**: adapter stays thin; retry policy centralizes in `ResolvedRetryPolicy`.
-
-## Per-Operation Credential Read
-**When to use**: any code touching secrets.
-**How**: config holds a `CredentialRef` (env-var name); `resolve(ref)` on every call; never cache the value.
-**Trade-offs**: negligible cost; rotation reaches the next request with no restart.
-
-## Slot Injection with Fresh List Id
-**When to use**: contributing UI to a slot you don't own.
-**How**: `ctx.slots.inject(key, cb)` → `register({name, id, order}, Component)`; use a fresh list id; never runtime-import another plugin's client module.
-**Trade-offs**: single/keyed cells are replacement points — id reuse replaces, it does not merge.
-
-## Settings CAS Write
-**When to use**: any browser-side settings edit.
-**How**: `mutate()` with `SettingsPathOp` (set/unset) + expectedRevision; never `replace()` from a redacted view.
-**Trade-offs**: one extra round; wholesale replace from redacted descriptors silently deletes secrets.
-
-## Layer Restatement (Patch Override)
-**When to use**: changing a composed plugin's config.
-**How**: target the row by id in a later layer (profile/home/`--patch`) and restate every key — whole-config replacement, no deep merge.
-**Trade-offs**: verbose but explicit; partial restatement silently drops keys.
-
-## Dev Overlay via `--patch`
-**When to use**: iterating on a local plugin.
-**How**: absolute-path insert row + `--patch` flag (or persist in `cordis.patch.yml`); HMR hot-replaces on edit.
-**Trade-offs**: zero-install loop; remember it's a layer — shipping wants a bundle+profile.
-
-## Boot-and-Read Cataloging
-**When to use**: documenting tool/config surfaces.
-**How**: boot the real profile through the Loader and read `ctx.tools.schemas()` / generated catalogs; never hand-transcribe runtime-spread schemas.
-**Trade-offs**: needs a bootable environment; the generated+verified catalogs stay truthful.
-
-## Remote Non-Throw
-**When to use**: consuming client-remote calls.
-**How**: calls return `RemoteResult<T>`; branch `if(!result.ok)` and discriminate by `code`, never `instanceof`; assembly mistakes still crash loudly.
-**Trade-offs**: explicit error handling everywhere; no lost failures.
-
-## Background Job Gate
-**When to use**: a tool does long-running work.
-**How**: `ctx.jobs.start({kind, label, owner: exec.agent, run})` and return `{kind:'background', jobId}`; kill requests, never forces.
-**Trade-offs**: PTC mode must never parse prose for ids; job lifecycle (notices, `reported` flag) is managed.
-
-## Waterfall Discipline
-**When to use**: listening on any `@mode waterfall` event.
-**How**: observers always call `next()`; omitting it is a deliberate veto. Match the dispatch method to the event's declared mode.
-**Trade-offs**: misuse = accidental short-circuit; postmortem 0002 is the cautionary tale.
-
-## Dispose-to-Quiescence
-**When to use**: teardown of listeners + spawned work.
-**How**: close listener registries first, then kill → await done; keep ordered steps in ONE disposer (async disposers run concurrently).
-**Trade-offs**: returning early leaves orphans.
-
-## Conjunction-of-Evidence Classification
-**When to use**: attributing failed sandboxed runs.
-**How**: check `runnerFailureRules` first (runner never ran), then per-backend `denialSignatures` — never exit status or cross-backend unions.
-**Trade-offs**: requires exact signature tables; prevents SANDBOX_UNAVAILABLE mislabels (postmortem 0004).

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/AGENTS.md

@@ -1,75 +0,0 @@
-# AGENTS.md — The documentation standard
-
-This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [doc-tiers Agent Note](../.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md) owns rationale.
-
-## Document structure
-
-These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
-
-Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
-
-Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
-
-Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
-
-## The tier taxonomy: one home per fact
-
-Each fact has one home: the tier whose job it is; elsewhere, link there.
-
-| Tier | Job | Does NOT belong there |
-|---|---|---|
-| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
-| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
-| [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
-| [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
-| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
-| [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
-| [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
-| [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
-| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
-| [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
-| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
-| Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
-
-Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
-
-## Writing rules
-
-- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence.
-- **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
-- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
-- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
-- **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
-- **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Write directly: name actors and facts ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
-
-## Wordcount Budgets
-
-[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
-
-When the gate goes red:
-
-1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
-2. **Condense** content that belongs here but can be shorter.
-3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
-
-Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
-
-## The slop checklist
-
-Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
-
-- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
-- Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
-- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
-- Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
-- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
-- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
-- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
-- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
-- Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
-
-## Cross-reference with machine-checkable links, never free prose
-
-Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/agent-lifecycle.md

@@ -1,84 +0,0 @@
-<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
-     Run `pnpm run gen-doc-graphs` to regenerate. -->
-
-# Agent Turn And Step Lifecycle
-
-This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant Agent
-  participant Driver
-  participant Hooks as hook listeners
-  participant Prompt as ctx.systemPrompt
-  participant LLM as ctx.llm
-  participant Tools as ctx.tools
-  participant Session
-  participant SDK as UI or SDK listener
-  User->>Agent: followup(content)
-  Agent-->>SDK: <code>agent/inbox/spliced</code>
-  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
-  Agent->>Driver: queued work wakes driver
-  Driver-->>SDK: <code>agent/status</code> running
-  Driver->>Session: <code>turn/start</code>
-  Note over Agent,Driver: claim pending next-step input plus one queued prompt
-  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
-  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-  Driver->>Hooks: <code>agent/pre-step</code> waterfall
-  Hooks-->>Driver: authoritative reject or enter(messages)
-  alt proposed step rejected or pre-step failed
-    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
-  else enter proposed step
-  Driver->>Session: <code>step/start</code>
-  Driver->>Session: <code>user/message</code> per entered message
-  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
-  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
-  LLM-->>Driver: StreamChunk*
-  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
-  alt final adapter or terminal in-band request failure
-    Driver->>Session: <code>assistant/attempt</code>
-    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-    Driver->>Session: <code>step/end</code>
-    Driver->>Hooks: <code>agent/request-error</code> waterfall
-    Hooks-->>Driver: return retry action or preserve the original error
-  else model request succeeded
-  Driver->>Session: <code>assistant/message</code>
-  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-  Driver->>Tools: classify pending call by executionMode
-  loop barriers and bounded rolling pool, reclassify before start
-    opt call starts
-      Driver->>Session: <code>tool/call</code>
-      Driver->>Tools: ordered pre, concurrent execute
-      Tools-->>Session: tool-owned events when applicable
-    end
-    opt next model-order result ready
-      Driver->>Tools: ordered post
-      Driver->>Session: <code>tool/result</code>
-    end
-  end
-  Driver->>Session: <code>step/end</code>
-  opt natural stop and next-step inbox empty
-    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
-  end
-  opt next-step input is pending
-    Driver-->>Driver: claim pending next-step input
-    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-    Driver->>Hooks: <code>agent/pre-step</code> waterfall
-    Hooks-->>Driver: authoritative reject or enter(messages)
-  end
-  end
-  end
-  Driver->>Session: <code>turn/end</code>
-  Driver-->>SDK: <code>agent/status</code> idle
-```
-
-The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes, and embeds the exact compact timed stream. Empty content stays out of derived history. A failed, retried, cancelled, or stream-error attempt that reaches settlement without a surface message records its stream as `assistant/attempt`. Live `agent/assistant-stream` chunk frames are transient; replay reads either durable settlement, and a hard process loss before settlement leaves no durable attempt stream.
-
-`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.
-
-The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages and `startsRequestSeries` unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.
-
-SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.
-
-Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/agent-lifecycle.zh.md

@@ -1,86 +0,0 @@
-<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
-     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/agent-lifecycle.md` 重新记录配对。 -->
-
-# Agent 轮次与步骤生命周期
-
-[English](agent-lifecycle.md) | 中文
-
-此时序图是 [architecture.md](architecture.zh.md#turn-flow) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant Agent
-  participant Driver
-  participant Hooks as hook listeners
-  participant Prompt as ctx.systemPrompt
-  participant LLM as ctx.llm
-  participant Tools as ctx.tools
-  participant Session
-  participant SDK as UI or SDK listener
-  User->>Agent: followup(content)
-  Agent-->>SDK: <code>agent/inbox/spliced</code>
-  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
-  Agent->>Driver: queued work wakes driver
-  Driver-->>SDK: <code>agent/status</code> running
-  Driver->>Session: <code>turn/start</code>
-  Note over Agent,Driver: claim pending next-step input plus one queued prompt
-  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
-  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-  Driver->>Hooks: <code>agent/pre-step</code> waterfall
-  Hooks-->>Driver: authoritative reject or enter(messages)
-  alt proposed step rejected or pre-step failed
-    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
-  else enter proposed step
-  Driver->>Session: <code>step/start</code>
-  Driver->>Session: <code>user/message</code> per entered message
-  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
-  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
-  LLM-->>Driver: StreamChunk*
-  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
-  alt final adapter or terminal in-band request failure
-    Driver->>Session: <code>assistant/attempt</code>
-    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-    Driver->>Session: <code>step/end</code>
-    Driver->>Hooks: <code>agent/request-error</code> waterfall
-    Hooks-->>Driver: return retry action or preserve the original error
-  else model request succeeded
-  Driver->>Session: <code>assistant/message</code>
-  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-  Driver->>Tools: classify pending call by executionMode
-  loop barriers and bounded rolling pool, reclassify before start
-    opt call starts
-      Driver->>Session: <code>tool/call</code>
-      Driver->>Tools: ordered pre, concurrent execute
-      Tools-->>Session: tool-owned events when applicable
-    end
-    opt next model-order result ready
-      Driver->>Tools: ordered post
-      Driver->>Session: <code>tool/result</code>
-    end
-  end
-  Driver->>Session: <code>step/end</code>
-  opt natural stop and next-step inbox empty
-    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
-  end
-  opt next-step input is pending
-    Driver-->>Driver: claim pending next-step input
-    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-    Driver->>Hooks: <code>agent/pre-step</code> waterfall
-    Hooks-->>Driver: authoritative reject or enter(messages)
-  end
-  end
-  end
-  Driver->>Session: <code>turn/end</code>
-  Driver-->>SDK: <code>agent/status</code> idle
-```
-
-`assistant/message` 事件会记录每次成功的提供方调用，包括返回空内容或以 `max-tokens` 结束的调用，并嵌入精确的紧凑带时间 stream。空内容不会进入派生历史。失败、重试、取消或 stream error attempt 到达 settlement 时，如果没有 surface message，就会把 stream 记录为 `assistant/attempt`。实时 `agent/assistant-stream` chunk frame 是瞬态数据；回放读取任一种持久 settlement，如果进程在 settlement 前硬中断，则不会留下持久 attempt stream。
-
-`dsh-compaction-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。
-
-以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息与 `startsRequestSeries`，除非有意替换。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
-
-需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。
-
-维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。