Two files, one repository
deepseek-ai/deepseek-harness ships 1 format across 12 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 12 | 1 | 0% |
| Commands | 0 | 25 | 1 | 0% |
| Section tags | 2 | 12 | 0 | 14% |
What each file covers
Sections
0 shared · 12 only in A · 1 only in B- − AGENTS.md
- − Pre-release stance: foundation over blast radius
- − Repository layout
- − Commands
- − Host sandbox failures
- − Run relevant checks locally
- − Secrets / .env
- − Conventions
- − Defensive patterns
- − Type safety and documentation
- − Editing these instructions
- − Vendoring policy
- + AGENTS.md — Archived Agent Notes
Commands
0 shared · 25 only in A · 1 only in B- − bundle/ installable dsh --profile patch-layer bundles
- − python/ Python SDK and bundled runtime (see python/README.md)
- − pnpm install
- − pnpm run clean
- − pnpm run test
- − pnpm run test:coverage
- − pnpm run test:e2e
- − pnpm run test:snapshot
- − pnpm run test:snapshot:record
- − pnpm run typecheck
- − pnpm run lint
- − pnpm run duplication
- − pnpm run build
- − pnpm run hygiene
- − pnpm run check:windows-wine
- − pnpm run doc-sync
- − pnpm run website:build
- − pnpm dsh --profile headless "task"
- − pnpm run demo:cordis
- − pnpm run demo:acp
- − pnpm
- − gh stack sync
- − node --import tsx/esm
- − git diff --cached --check
- − pnpm run test && pnpm run build
- + pnpm run verify-archived-agent-notes --write
Section tags
2 shared · 12 only in A · 0 only in B- − setup
- − build
- − test
- − code-style
- − architecture
- − types
- − testing-strategy
- − security
- − dependencies
- − api
- − deployment
- − docs
- do-not
- agent-behaviour
Line diff
deepseek-ai/deepseek-harness · AGENTS.md
@@ −1 @@
1# AGENTS.md
2
3DeepSeek Harness is a plugin-based agent harness on vendored Cordis: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; follow [docs/AGENTS.md](docs/AGENTS.md) for documentation.
4
5## Pre-release stance: foundation over blast radius
6
7**Remove this section at the first tagged release.** With no external consumers, prefer the correct foundation over compatibility shims: rename or repackage freely and update every reference together. Backends reject old on-disk formats. SQLite uses monotonic `SCHEMA_VERSION`; `dsh-session` keeps `SESSION_FORMAT_VERSION` at `0` with no compatibility promise.
8
9## Repository layout
10
11```
12vendor/ Vendored Cordis source — manifest + sync procedure in vendor/README.md
13packages/ @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
14 core/ product API spine: session, system-prompt, tools, agent, agent-loop
15 api/ Remote BFF assembly and Typert RPC gateway
16 typert/ type graph generator, loader, and runtime registry
17 llm/ LLM capability: Service Definition/Consumer + DeepSeek providers
18 e2b/ E2B POC: sandbox + FS/subprocess adapters
19 shell/ bash capability: Service Definition + local/pwsh providers + shell Consumers
20 subprocess/ subprocess capability + local process-tree provider
21 terminal/ persistent sessions
22 fs/ filesystem capability + policy
23 lsp/ language-server capability
24 skill/ skill provider registry + local impl + catalog/loader tool
25 web/ web capability: Service Definition + search/fetch providers + tool Consumer
26 compaction/ compaction capability + basic provider
27 context/ request-context plugins
28 subagent/ subagent capability: Service Definition + providers + delegation Consumers
29 bundle/ installable dsh --profile patch-layer bundles
30 workflow/ workflow capability + worker-thread provider + tool Consumer
31 todo/ todo_write tool
32 plan/ plan mode as logged state
33 preset/ per-session agent composition from preset cordis.yml files
34 guard/ loop-hygiene + tool-timeout plugins
35 self-modification/ the agent inspects/mounts its own plugins
36 hooks/ Claude Code/Codex hook bridges + wire-protocol library
37 session/ durable session data: persistence, projection, titles, telemetry
38 identity/ anonymous identity
39 settings/ user-settings capability + file provider
40 credentials/ credential-reference capability + env/.env provider
41 acp/ automation-only Agent Client Protocol server
42 interaction/ approval/interaction capabilities, permission, commands, ask-user
43 boot/ shared app-bin glue
44 sdk/ JSON-RPC protocol, server, and TypeScript client
45 examples/ demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
46 support/ dev/test infrastructure
47 util/ zero-dependency utilities
48python/ Python SDK and bundled runtime (see python/README.md)
49native/ @deepseek-ai/node-addon-landlock-run source of record (see native/README.md)
50examples/ Runnable cordis.yml leaves over packages/examples bundles (see examples/AGENTS.md)
51.agents/ Agent workflows and Agent Notes (`notes/`)
52docs/ architecture, generated catalogs, postmortems, cookbook (see docs/AGENTS.md)
53scripts/ repo gates and generators
54website/ VitePress projection of selected bilingual docs/ sources
55```
56
57Package groups: [packages/README.md](packages/README.md).
58
59## Commands
60
61```sh
62pnpm install # pnpm workspaces, node ^22.19 || >=24
63pnpm run clean # remove build outputs and safe residue from deleted packages
64pnpm run test # vitest unit tests
65pnpm run test:coverage # CI coverage gate: per-file 100% on packages/*/*/src
66pnpm run test:e2e # real-API tests; self-skip without DEEPSEEK_API_KEY
67pnpm run test:snapshot # keyless ACP/headless replay vs expected outputs; filter: -t <name>
68pnpm run test:snapshot:record # re-record expected outputs (needs key)
69pnpm run typecheck
70pnpm run lint
71pnpm run duplication # cross-file TypeScript clone detection
72pnpm run build # tsc emits lib/types, tsdown bundles runtime
73pnpm run hygiene # knip + publint + workspace constraints + NodeNext consumer check
74pnpm run check:windows-wine # ONLY when diagnosing a known Windows failure (needs wine); CI owns this signal
75pnpm run doc-sync # all documentation gates; leaf list in scripts/run-gates.ts
76pnpm run website:build # VitePress build (doubles as dead-link check)
77pnpm dsh --profile headless "task" # run one task from source (needs DEEPSEEK_API_KEY)
78pnpm run demo:cordis # the agent modifies its own runtime (needs key)
79pnpm run demo:acp # ACP automation server (needs DEEPSEEK_API_KEY)
80```
81
82### Host sandbox failures
83
84When required `gh`, `pnpm`, build, test, or generator commands fail because the agent sandbox blocks credentials, network, IPC, file watching, or nested `sandbox-exec`, retry unchanged with the narrowest host escalation before diagnosing authentication or project failure. Require sandbox evidence; never bypass genuine test failures or the product sandbox under test.
85
86### Run relevant checks locally
87
88Run checks before pushes via [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md); report only commands run. After `gh stack sync`, validate immediately; do not merge before checks pass.
89
90- Match evidence to the surface: focused tests for behavior, snapshots for model or user output, `doc-sync` for docs, build/hygiene and built smokes for published paths, and real-API e2e for provider behavior.
91- Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
92- `test:coverage`, not `test`, is the CI coverage gate ([why](docs/testing.md)).
93
94## Secrets / .env
95
96Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and root `.env`. cordis.yml allows `!!js` (never `!js`) under plugin `config` and entry `disabled`; other metadata stays literal, so conditional composition also uses overlays ([primer](docs/cordis-primer.md#loader-configuration)). Never commit credentials. CI e2e skips without a key; [testing.md](docs/testing.md) owns key policy.
97
98## Conventions
99
100- Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages are rescoped ([mapping](docs/rescope.md)) and `private: true`. `@deepseek-ai/cordis` is a peerDependency (+ dev) of every harness package.
101- ESM everywhere (`"type": "module"`). Use package names across packages and `.ts` in local relative imports. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only exports) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
102- **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
103- **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. Without a plausible relationship, an explained empty companion is correct ([package invariant rules](packages/AGENTS.md)).
104- **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. A `SessionEventMap` member is required-on-read by default — builds that do not know its type refuse the log unless the event carries the envelope's `ignorable: true`; only structural format changes bump `SESSION_FORMAT_VERSION` ([mechanism](.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)).
105- **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
106- **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
107- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
108- **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md.
109- **A capability seam comprises Service Definition / Service Provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)).
110- **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
111- **Explicit > implicit at package boundaries**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-shell` request/spec split is the template).
112- **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test hook is not configurability. Protocol constants, external specs, and security invariants stay fixed.
113- **Misconfiguration fails loud** at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent.
114- **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
115- **Trust TypeScript at typed same-process boundaries.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
116- **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
117- **Keep compiler faces explicit.** Each package uses one aggregate except `api/remotes`; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
118- **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
119- Do not comment on facts obvious from code.
120- **Prefer symmetry for parallel values**; unexplained asymmetry usually signals a missed extraction.
121- **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR.
122- **Non-trivial changes MUST include an Agent Note in the same PR;** only mechanical/local edits are exempt ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
123- **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
124- **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
125- **Plan unit, e2e, and snapshot coverage** for capability seams, lifecycle paths, and transcript output; include missing snapshot-harness support in the same change.
126- **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
127- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
128- TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
129- Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
130
131## Defensive patterns
132
133Read [docs/defensive-patterns.md](docs/defensive-patterns.md) before lifecycle, concurrency, subprocess, or teardown work.
134
135## Type safety and documentation
136
137Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why narrowing is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring Service Definition, protocol, or class.
138
139Comments and docs state complete contracts and context, not reasoning transcripts. Use direct, concrete terms. Do not use metaphors. Before writing `contract`, `boundary`, or `shape`, ask whether a more exact term names the subject: write `response fields`, `JSON validation`, or `ESM exports` instead of `response shape`, `validation boundary`, or `module shape`. Keep `contract` for preconditions, postconditions, invariants, compatibility promises, and other obligations that callers, callees, implementers, providers, producers, or consumers rely on. Keep a literal process, wire, security, transaction, or lifecycle boundary. Do not narrate control flow or tests, preserve review history, or restate code. Keep behavior, failure, timing, ownership, and safe-use facts; link the rationale. Use [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md) for decisions. Wire mechanically checkable invariants into an executed top-level gate and prove each changed acceptance path rejects an invalid case. Use narrow, justified exceptions instead of disabling a rule globally.
140
141Docs accompany every code change: update affected README and JSDoc contracts together. Routine bilingual work follows [docs/AGENTS.md](docs/AGENTS.md); only explicit user invocation may run `dsh-translate-docs`. Current-state prose, one physical line per paragraph, one home per fact, and word budgets live there.
142
143## Editing these instructions
144
145`CLAUDE.md` symlinks `AGENTS.md` at root, `packages/`, and `examples/`; edit the real file. Keep each rule self-contained while linking high-level docs. Condense when clarity survives; raise a `verify-doc-budgets` ceiling when the required content genuinely needs more space.
146
147## Vendoring policy
148
149`vendor/` packages are pinned source copies (manifest with upstream SHAs in [vendor/README.md](vendor/README.md)). Update via the sync procedure there; re-apply or retire the logged local modifications; rerun `pnpm run test && pnpm run build`.
150
deepseek-ai/deepseek-harness · .agents/notes/archived/AGENTS.md
@@ +1 @@
1# AGENTS.md — Archived Agent Notes
2
3Archived Agent Note triplets under the kind directories are frozen historical snapshots, not current authority. Never edit, reformat, translate, repair, delete, or move a sealed artifact; use an active Agent Note or current documentation for new decisions and facts.
4
5The archival change may only relocate a complete English/Chinese/sidecar triplet, insert the identical `Archived: YYYY-MM-DD` line below both `Status: implemented` lines, re-record the sidecar, and repair or delete inbound links. Do not inspect, verify, or repair links out of archived notes.
6
7Run the [`dsh-archive-agent-notes`](../../skills/dsh-archive-agent-notes/SKILL.md) workflow and append new artifact hashes with `pnpm run verify-archived-agent-notes --write`. The normal verifier rejects changed or missing sealed artifacts, incomplete triplets, unknown kind folders, and invalid archive metadata.
8
@@ −1 +1 @@
1−# AGENTS.md
1+# AGENTS.md — Archived Agent Notes
22
3−DeepSeek Harness is a plugin-based agent harness on vendored Cordis: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; follow [docs/AGENTS.md](docs/AGENTS.md) for documentation.
3+Archived Agent Note triplets under the kind directories are frozen historical snapshots, not current authority. Never edit, reformat, translate, repair, delete, or move a sealed artifact; use an active Agent Note or current documentation for new decisions and facts.
44
5−## Pre-release stance: foundation over blast radius
5+The archival change may only relocate a complete English/Chinese/sidecar triplet, insert the identical `Archived: YYYY-MM-DD` line below both `Status: implemented` lines, re-record the sidecar, and repair or delete inbound links. Do not inspect, verify, or repair links out of archived notes.
66
7−**Remove this section at the first tagged release.** With no external consumers, prefer the correct foundation over compatibility shims: rename or repackage freely and update every reference together. Backends reject old on-disk formats. SQLite uses monotonic `SCHEMA_VERSION`; `dsh-session` keeps `SESSION_FORMAT_VERSION` at `0` with no compatibility promise.
8−
9−## Repository layout
10−
11−```
12−vendor/ Vendored Cordis source — manifest + sync procedure in vendor/README.md
13−packages/ @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
14− core/ product API spine: session, system-prompt, tools, agent, agent-loop
15− api/ Remote BFF assembly and Typert RPC gateway
16− typert/ type graph generator, loader, and runtime registry
17− llm/ LLM capability: Service Definition/Consumer + DeepSeek providers
18− e2b/ E2B POC: sandbox + FS/subprocess adapters
19− shell/ bash capability: Service Definition + local/pwsh providers + shell Consumers
20− subprocess/ subprocess capability + local process-tree provider
21− terminal/ persistent sessions
22− fs/ filesystem capability + policy
23− lsp/ language-server capability
24− skill/ skill provider registry + local impl + catalog/loader tool
25− web/ web capability: Service Definition + search/fetch providers + tool Consumer
26− compaction/ compaction capability + basic provider
27− context/ request-context plugins
28− subagent/ subagent capability: Service Definition + providers + delegation Consumers
29− bundle/ installable dsh --profile patch-layer bundles
30− workflow/ workflow capability + worker-thread provider + tool Consumer
31− todo/ todo_write tool
32− plan/ plan mode as logged state
33− preset/ per-session agent composition from preset cordis.yml files
34− guard/ loop-hygiene + tool-timeout plugins
35− self-modification/ the agent inspects/mounts its own plugins
36− hooks/ Claude Code/Codex hook bridges + wire-protocol library
37− session/ durable session data: persistence, projection, titles, telemetry
38− identity/ anonymous identity
39− settings/ user-settings capability + file provider
40− credentials/ credential-reference capability + env/.env provider
41− acp/ automation-only Agent Client Protocol server
42− interaction/ approval/interaction capabilities, permission, commands, ask-user
43− boot/ shared app-bin glue
44− sdk/ JSON-RPC protocol, server, and TypeScript client
45− examples/ demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
46− support/ dev/test infrastructure
47− util/ zero-dependency utilities
48−python/ Python SDK and bundled runtime (see python/README.md)
49−native/ @deepseek-ai/node-addon-landlock-run source of record (see native/README.md)
50−examples/ Runnable cordis.yml leaves over packages/examples bundles (see examples/AGENTS.md)
51−.agents/ Agent workflows and Agent Notes (`notes/`)
52−docs/ architecture, generated catalogs, postmortems, cookbook (see docs/AGENTS.md)
53−scripts/ repo gates and generators
54−website/ VitePress projection of selected bilingual docs/ sources
55−```
56−
57−Package groups: [packages/README.md](packages/README.md).
58−
59−## Commands
60−
61−```sh
62−pnpm install # pnpm workspaces, node ^22.19 || >=24
63−pnpm run clean # remove build outputs and safe residue from deleted packages
64−pnpm run test # vitest unit tests
65−pnpm run test:coverage # CI coverage gate: per-file 100% on packages/*/*/src
66−pnpm run test:e2e # real-API tests; self-skip without DEEPSEEK_API_KEY
67−pnpm run test:snapshot # keyless ACP/headless replay vs expected outputs; filter: -t <name>
68−pnpm run test:snapshot:record # re-record expected outputs (needs key)
69−pnpm run typecheck
70−pnpm run lint
71−pnpm run duplication # cross-file TypeScript clone detection
72−pnpm run build # tsc emits lib/types, tsdown bundles runtime
73−pnpm run hygiene # knip + publint + workspace constraints + NodeNext consumer check
74−pnpm run check:windows-wine # ONLY when diagnosing a known Windows failure (needs wine); CI owns this signal
75−pnpm run doc-sync # all documentation gates; leaf list in scripts/run-gates.ts
76−pnpm run website:build # VitePress build (doubles as dead-link check)
77−pnpm dsh --profile headless "task" # run one task from source (needs DEEPSEEK_API_KEY)
78−pnpm run demo:cordis # the agent modifies its own runtime (needs key)
79−pnpm run demo:acp # ACP automation server (needs DEEPSEEK_API_KEY)
80−```
81−
82−### Host sandbox failures
83−
84−When required `gh`, `pnpm`, build, test, or generator commands fail because the agent sandbox blocks credentials, network, IPC, file watching, or nested `sandbox-exec`, retry unchanged with the narrowest host escalation before diagnosing authentication or project failure. Require sandbox evidence; never bypass genuine test failures or the product sandbox under test.
85−
86−### Run relevant checks locally
87−
88−Run checks before pushes via [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md); report only commands run. After `gh stack sync`, validate immediately; do not merge before checks pass.
89−
90−- Match evidence to the surface: focused tests for behavior, snapshots for model or user output, `doc-sync` for docs, build/hygiene and built smokes for published paths, and real-API e2e for provider behavior.
91−- Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
92−- `test:coverage`, not `test`, is the CI coverage gate ([why](docs/testing.md)).
93−
94−## Secrets / .env
95−
96−Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and root `.env`. cordis.yml allows `!!js` (never `!js`) under plugin `config` and entry `disabled`; other metadata stays literal, so conditional composition also uses overlays ([primer](docs/cordis-primer.md#loader-configuration)). Never commit credentials. CI e2e skips without a key; [testing.md](docs/testing.md) owns key policy.
97−
98−## Conventions
99−
100−- Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages are rescoped ([mapping](docs/rescope.md)) and `private: true`. `@deepseek-ai/cordis` is a peerDependency (+ dev) of every harness package.
101−- ESM everywhere (`"type": "module"`). Use package names across packages and `.ts` in local relative imports. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only exports) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
102−- **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
103−- **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. Without a plausible relationship, an explained empty companion is correct ([package invariant rules](packages/AGENTS.md)).
104−- **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. A `SessionEventMap` member is required-on-read by default — builds that do not know its type refuse the log unless the event carries the envelope's `ignorable: true`; only structural format changes bump `SESSION_FORMAT_VERSION` ([mechanism](.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)).
105−- **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
106−- **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
107−- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
108−- **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md.
109−- **A capability seam comprises Service Definition / Service Provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)).
110−- **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
111−- **Explicit > implicit at package boundaries**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-shell` request/spec split is the template).
112−- **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test hook is not configurability. Protocol constants, external specs, and security invariants stay fixed.
113−- **Misconfiguration fails loud** at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent.
114−- **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
115−- **Trust TypeScript at typed same-process boundaries.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
116−- **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
117−- **Keep compiler faces explicit.** Each package uses one aggregate except `api/remotes`; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
118−- **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
119−- Do not comment on facts obvious from code.
120−- **Prefer symmetry for parallel values**; unexplained asymmetry usually signals a missed extraction.
121−- **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR.
122−- **Non-trivial changes MUST include an Agent Note in the same PR;** only mechanical/local edits are exempt ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
123−- **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
124−- **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
125−- **Plan unit, e2e, and snapshot coverage** for capability seams, lifecycle paths, and transcript output; include missing snapshot-harness support in the same change.
126−- **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
127−- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
128−- TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
129−- Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
130−
131−## Defensive patterns
132−
133−Read [docs/defensive-patterns.md](docs/defensive-patterns.md) before lifecycle, concurrency, subprocess, or teardown work.
134−
135−## Type safety and documentation
136−
137−Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why narrowing is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring Service Definition, protocol, or class.
138−
139−Comments and docs state complete contracts and context, not reasoning transcripts. Use direct, concrete terms. Do not use metaphors. Before writing `contract`, `boundary`, or `shape`, ask whether a more exact term names the subject: write `response fields`, `JSON validation`, or `ESM exports` instead of `response shape`, `validation boundary`, or `module shape`. Keep `contract` for preconditions, postconditions, invariants, compatibility promises, and other obligations that callers, callees, implementers, providers, producers, or consumers rely on. Keep a literal process, wire, security, transaction, or lifecycle boundary. Do not narrate control flow or tests, preserve review history, or restate code. Keep behavior, failure, timing, ownership, and safe-use facts; link the rationale. Use [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md) for decisions. Wire mechanically checkable invariants into an executed top-level gate and prove each changed acceptance path rejects an invalid case. Use narrow, justified exceptions instead of disabling a rule globally.
140−
141−Docs accompany every code change: update affected README and JSDoc contracts together. Routine bilingual work follows [docs/AGENTS.md](docs/AGENTS.md); only explicit user invocation may run `dsh-translate-docs`. Current-state prose, one physical line per paragraph, one home per fact, and word budgets live there.
142−
143−## Editing these instructions
144−
145−`CLAUDE.md` symlinks `AGENTS.md` at root, `packages/`, and `examples/`; edit the real file. Keep each rule self-contained while linking high-level docs. Condense when clarity survives; raise a `verify-doc-budgets` ceiling when the required content genuinely needs more space.
146−
147−## Vendoring policy
148−
149−`vendor/` packages are pinned source copies (manifest with upstream SHAs in [vendor/README.md](vendor/README.md)). Update via the sync procedure there; re-apply or retire the logged local modifications; rerun `pnpm run test && pnpm run build`.
7+Run the [`dsh-archive-agent-notes`](../../skills/dsh-archive-agent-notes/SKILL.md) workflow and append new artifact hashes with `pnpm run verify-archived-agent-notes --write`. The normal verifier rejects changed or missing sealed artifacts, incomplete triplets, unknown kind folders, and invalid archive metadata.
1508
