Implements the gate-consolidation Agent Note from the NIH dependency audit:
- Shared markdownFences helper in scripts/markdown.ts (mdast code-node visit);
doc-typecheck and verify-type-equiv extract fences through it; md-fences.ts
and the duplicated extractEquivBlocks regex scanner are deleted;
markdownProseLines derives fenced lines from parsed code-node positions
instead of a second fence regex.
- publint-all.ts and verify-built-package-invariants.mjs parse argv with
node:util parseArgs instead of hand-stepped parseOptions copies.
- Five straggler readdirSync walks become globSync: verify-runtime-closure,
dev-web discoverPluginDirs, verify-package-paths realPackageNames,
verify-client-domain-graph listSources, publint-all addPath. The
dirent-diagnostic walks in check-workspace-constraints.ts and clean.ts stay.
Behavior parity verified: pnpm run doc-sync and every rewritten gate produce
byte-identical output before and after on this tree.
Moves the owning Agent Note proposed -> implemented and re-records its pair.
Root tsconfig.json becomes a pure solution (files:[] + two references);
the former root host aggregate moves verbatim to tsconfig.host.json.
New tsconfig.base.client.json carries the shared client compiler shape
(jsx/DOM lib/types:[]), and tsconfig.client.json plus the 12
packages/client tsconfigs extend it instead of restating the trio.
tsconfig.build.json is deleted: the solution covers the full emit graph,
absorbing the command-goal typecheck/build drift.
Consumers migrate to the single graph: typecheck/build scripts and the
lefthook pre-push hook run bare `tsc -b` (pre-push now covers the client
side); the run-gates build gate needs typecheck so two concurrent tsc -b
runs cannot race the same tsbuildinfo; ts-project.ts and the standalone
doc-typecheck mode seed tsconfig.host.json explicitly (never the root
solution — flattening host+client into one program collides the cordis
Context merges); verify-cordis-config BFS seeds the root solution alone.
Per missions/tsconfig-single-graph-migration.md §2–§3.
Master's new duplication gate flagged 4 clones, all from the website scripts
reusing existing gate patterns by copy. Extracted the shared halves instead of
ignoring:
- scripts/cordis-walk.ts — cordisModuleBody / eventMembers / serviceClasses,
one AST walk consumed by both gen-cordis-catalog and gen-website-api (the
two renderers must agree on WHAT exists; now they structurally do).
- scripts/md-fences.ts — fence extractor with per-gate info-string
classification, consumed by doc-typecheck and verify-website-yaml.
Behavior-neutral: regenerated catalogs and website pages are byte-identical
(--check green), doc-typecheck/yaml block counts unchanged. jscpd now reports
0 clones; full pre-push run 34/34 green.
Conflict resolution notes:
- package.json/run-gates: both sides' new doc-sync gates kept (master's
scoped-events/readme gates + this branch's website-api/website-yaml);
js-yaml devDeps deduped (master added them independently).
- pnpm-workspace/knip: website AND python/sdk-runtime entries kept.
- doc-typecheck/verify-type-equiv: master's condensed headers kept, website
glob retained in both scan scopes.
- vendor/cordis/src/fiber.ts: master's lifecycle-hardening code taken; this
branch's richer FiberState JSDoc reapplied on top. vendor/README.md logs
both local modifications (hardening = 6, JSDoc enrichment = 7).
- pnpm-lock: regenerated from master's side (pnpm install).
Post-merge sync the gates forced (the system working as designed):
- verify-website-yaml caught 4 stale plugin names from master's package
reorg (dsh-stdio-agent -> dsh-stdio-demo, dsh-acp-agent -> dsh-acp-demo);
8 references fixed across guide/ and develop/.
- gen-website-api picked up master's 6 new services automatically
(ctx.approval/permission/sandbox/sessionQuery/skills/tasks -> 6 new pages
+ sidebar); api/index.md hub updated to list them.
- AGENTS.md budget ceiling 1370 -> 1400: the website rows (layout line + two
command lines) and master's own growth collided with the old ceiling; all
three website rows are load-bearing (new top-level dir, new CI command).
- website joins the pnpm workspace; root scripts website:dev/website:build;
run-gates gains a website-build gate (ci-primary + ci-static) — the
VitePress build doubles as the site's dead-link check; AGENTS.md documents
the commands.
- doc-typecheck + verify-type-equiv now scan website/zh-CN/**/*.md; every
```typescript fence converted to ```ts and made standalone-compilable
(55 compiled, 1 ignore-check). Phantom APIs the compiler caught are fixed:
invented event names (agent/turn-end, tool/call, llm/pre-request, ready,
dispose) replaced with real catalog events or per-plugin declare-module
merges; presentCall/inject/Config claims corrected to the real shapes.
- guide/config.md entry-fields table completed against loader EntryOptions;
its coding-agent example brought in line with examples/coding-agent.
execFileSync('node_modules/.bin/tsc') spawns an extensionless shim
that is not executable on Windows (the CVE-2024-27980 class the
sibling scripts hit); the catch treated the spawn failure as a compile
failure with empty diagnostics. The .cmd shim would need shell:true,
which concatenates args unescaped - a hazard for the temp project
path - so invoke typescript/bin/tsc through the current node instead;
identical behavior on every platform.
Note this gate had never actually run on this Windows checkout: with
the pre-eol=lf CRLF working copy the fence regex matched no ts blocks
('.' does not match \\r), so it reported 'no ts code blocks to check'
and exited green. The LF working tree surfaced the spawn bug; with
this fix the gate compiles all 21 blocks on Windows.
(cherry picked from commit b49993c28e068c2beb411eae1f0c8ac4985aa3ae)
scripts/gen-config-catalog.ts walks every packages/<group>/<pkg> entry with
the TypeScript compiler API and emits docs/config-catalog.md: per loadable
plugin, the verbatim config declaration (JSDoc included) its apply/constructor
receives in a ts config-catalog fence, the inject requirements, resolved links
for every referenced type (package-local types pasted transitively, other
plugins' config types as intra-page anchors, LINK_MAP names to
core-data-structures, workspace types to source), and terse classification
lists for config-free plugins, abstract seams, and libraries — classification
is total, so a new package cannot go undocumented.
The walk enforces per-field JSDoc prose on every pasted declaration and
statically cross-checks the schemastery schema (z.object keys, z.intersect
composition across packages): every schema-validated key must be a declared
member of the config type. One violation existed repo-wide — the agents[].id
field in dsh-agent-loop — fixed by adding its JSDoc (which shifts the
cordis-catalog services page's source pointers; regenerated).
verify-config-catalog (--check) joins doc-sync; doc-typecheck learns the
ts config-catalog fence; gen-cordis-catalog exports its JSDoc/pointer helpers
and LINK_MAP for reuse. Negative-path spec in
packages/core/agent-core/tests/gen-config-catalog.spec.ts mirrors the
gen-cordis-catalog spec. Decision record:
docs/rfc/implemented/process/2026-07-06-generated-config-catalog.md (includes
the deliberate acceptance of README ## Config overlap).
docs/persistence-catalog/log-events.md enumerates every SessionEventMap
member — the owning dsh-session vocabulary plus the dsh-compact and
dsh-hook-protocol declaration merges — with payload, surface/log-only badge,
JSDoc prose, and declaration site. scripts/gen-persistence-catalog.ts is a
pure AST pass in the gen-cordis-catalog mold: verify-persistence-catalog
(--check) joins doc-sync, so a stale committed catalog fails pre-push and CI.
The walk enforces JSDoc completeness (every member needs description prose;
@mode is rejected as a category error — log events do not dispatch on the
cordis bus), derives the surface badge from the SurfaceEventType union with a
stale-member cross-check, and hard-errors on duplicate declarations. Payloads
render through the TypeScript printer so newline-separated multi-line type
literals still emit valid one-line fragments.
Documented the five previously JSDoc-less core events (turn/step boundaries,
tool/call), removed the two stray @mode tags on the hook/* merges, and
replaced the hand-restated event enumerations (session.md hook/* table,
compact README table, hook-protocol README bullets, session README name-list
— whose merge note had already drifted) with links to the catalog. RFC:
docs/rfc/implemented/process/2026-07-04-persistence-log-catalog.md.
Move the 18 flat packages/<name> packages into role-grouped dirs:
core/, llm/, bash/, session-persistence/, ui/, support/. Group dirs are
pure containers; each package keeps its @deepseek-ai/dsh-* name.
Collapse the per-package tsconfig paths maps (base + typecheck) into one
@deepseek-ai/dsh-* wildcard with a candidate per group, and derive the
publint list from the hierarchy. Update all depth-coupled globs/configs
(workspace, tsdown, vitest, eslint, knip, tsconfig includes/refs,
per-package tsconfigs, generators, doc-script scopes, type-equiv manifest)
and the cross-package/script relative imports in tests.
Fix doc-typecheck's workspacePaths() to parse tsconfig JSONC via the
TypeScript API instead of a regex comment-strip, which corrupted the
new wildcard `/*/` path candidates.
WIP: doc cross-links and package/RFC docs still to update.
Add scripts/gen-cordis-catalog.ts: a fully-generated docs/cordis-catalog/
events-and-services.md cataloging every cordis event (exact signature + @mode)
and ctx.<key> service (exact interface), modeled on gen-module-graph's
--write/--check freshness gate. The harness tier renders in full from the
interface Events / interface Context declarations and their JSDoc; the inherited
cordis-core/loader/hmr/timer surface renders tersely from a curated table.
The generator hard-errors on a missing @mode tag and on a tag that contradicts
a conclusive signature shape (a trailing next param is structurally a
waterfall). Signature blocks use a ts cordis-catalog fence that doc-typecheck
skips. Type tokens cross-link to the core-data-structures catalog.
This supersedes the hand-maintained event-taxonomy table: verify-event-taxonomy
is deleted and verify-cordis-catalog joins doc-sync. architecture.md keeps the
Event taxonomy heading (TOC anchor) but points at the catalog; the Service-map
role table stays. RFC, AGENTS.md @mode authoring rule, and dependent doc/skill
references updated. Negative gate tests cover the missing-tag and
tag/shape-contradiction paths.
Co-locate the ACP feature support checklist with the bridge package
(packages/acp/acp-feature-support.md) and rewrite its relative links for
the new depth. Broaden the doc-sync globs (doc-typecheck, verify-md-wrap,
verify-md-links) from packages/*/README.md to packages/*/*.md so a
package-level doc beyond the README stays under the drift gates, and
update the AGENTS.md prose describing that scope.
Introduce a `ts type-equiv` Markdown fence: a verbatim paste of a source type
definition that `scripts/verify-type-equiv.ts` drift-checks against the source
symbol via the TypeScript parser, with provenance in a central
`scripts/type-equiv.manifest.json` kept 1:1 with the blocks. doc-typecheck
recognizes the same fence, skips compiling it (not standalone-compilable), and
excludes it from the opt-out ratio. Wired into the `doc-sync` chain.
Collapse docs/adr/ and docs/rfc/ into a single docs/rfc/ with proposed/,
implemented/, and rejected/ subfolders. Every file is renamed to
yyyy-mm-dd-topic-title.md, where the date is when the topic was first
proposed (from git history). ADRs and RFCs that covered exactly the same
topic are merged (property-based testing, session persistence); the
umbrella RFC 005 stays split across its three implemented decisions, and
RFC 006's deferred part-3 (API extractor reports) splits into its own
proposed RFC. All cross-references become machine-checkable relative
links instead of bare "ADR NNNN" / "RFC NNN" prose.
Add a verify-md-links doc-sync gate (scripts/verify-md-links.ts) that
checks every relative Markdown cross-link resolves, wired into doc-sync
alongside verify-md-wrap. This makes the reorganization self-verifying:
the same change that rewrote ~forty inter-doc links adds the check that
proves none dangle. Document the cross-link convention in a new
docs/AGENTS.md and record the gate as an implemented RFC.
doc-sync, typecheck, lint, and the full test suite (667) all pass.
Two tsx CI gates make doc/code drift fail fast:
- doc-typecheck extracts every fenced ts block from README/docs/package READMEs,
compiles them with tsc --noEmit against a temp project (vendor->lib, harness->src
paths from tsconfig.typecheck.json), and fails on errors. Deliberate sketches opt
out with ```ts ignore-check; the opt-out ratio is reported and capped.
- verify-event-taxonomy asserts the docs/architecture.md taxonomy table names
exactly the events declared in the interface Events blocks. This surfaced three
events the table had been missing (tools/change, llm/adapter-change,
system-prompt/change), now added.
Doc snippets made compilable with stub imports/declares (1 genuine sketch ignored).
Wired into CI after typecheck. API reports (RFC 006 pt 3) deferred. Graduates RFC
006 pts 1-2 -> ADR 0014.
