0 Fork 0

Files

T

Tianyi Cui 7702a33531 docs(AGENTS): rewrite the root standing orders to the 1,500-word budget

Applies the documentation standard to its biggest offender. Every rule
survives as one to three lines plus a link to its durable home; the
stories, duplicate statements, and re-narrations go:

- Situational clusters evict to new homes: docs/testing.md (tiers,
  with-key policy, real-over-mock, world-verification, real-entry-path
  guards), docs/defensive-patterns.md (the bug-class rules), and
  docs/cookbook/responding-to-pr-review-on-a-stack.md (the stacked-PR
  review procedure).
- Doc-authoring rules consolidate into docs/AGENTS.md § Writing rules
  (current-state-never-history, md-wrap, ts-block compilation, @mode,
  catalog same-change, pair same-change).
- packages/README.md drops to the group table + the extension-vs-bundle
  dependency rule; the hand ASCII graph yields to the generated
  module-graph.md; group READMEs are the canonical per-package map.
- packages/AGENTS.md keeps only its packages-specific rules (export
  shape, ctx.get, real-Loader coverage); examples/AGENTS.md repoints
  its with-key-policy link; rfc/README.md loses a narrated-history
  aside; dsh-code-review / dsh-find-simplifications / verify-md-wrap
  references follow the moved content.
- Budget manifest ratchets: AGENTS.md 8200 -> 1500 (now 1,495 words),
  packages/README.md 1900 -> 600, packages/AGENTS.md 600 -> 450; the
  two new eviction docs join the budget set (testing 800, defensive
  550); docs/AGENTS.md raises 1000 -> 1250 for the absorbed writing
  rules (the one justified increase). The doc-tiers RFC's deferred list
  prunes the two items this change ships.

2026-07-04 14:22:47 +08:00

2.8 KiB

Raw Blame History

AGENTS.md — Harness Packages

This directory contains all @deepseek-ai/dsh-* harness packages. Repo-wide conventions (effects, declaration merging, waterfall semantics, ESM, testing policy) are in the root AGENTS.md § Conventions; the points below are packages-specific.

Plugin export shape — namespace OR default, never both. A service package exports the service class as export default (the Loader instantiates it). A function/namespace plugin exports name / inject / Config / apply as separate named exports and must NOT add export default — the cordis Loader's unwrapExports does exports.default ?? exports, so a stray default export collapses the module to the bare apply function and silently discards the inject/name/Config namespace, leaving the plugin with no injected services (it then throws cannot get property … without inject at load). See docs/postmortem/0001.
Read an optional (non-injected) service via ctx.get(name), not ctx.<name>. For a service a plugin reads opportunistically but deliberately leaves out of static inject (e.g. AgentLoop reading sessionPersistence), the ctx.<name> property proxy resolves by an ancestor-only fiber walk that throws when the call arrives through a foreign traceable shadow (the service lives on a sibling fiber). ctx.get(name) is the topology-independent global-store lookup, strict by default (an inactive/absent backend reads as undefined — prefer it over the ctx.get(name, false) overload, which also skips the active-state check). Services that ARE in static inject resolve fine via ctx.<name>. See docs/postmortem/0001.
A plugin shipped via cordis.yml needs at least one test through the REAL Loader/export path — hand-built ctx.plugin({...}) mounts bypass unwrapExports and cannot catch a broken export shape. Full testing policy (tiers, with-key generosity, real-entry-path guards): docs/testing.md.

Naming notes:

A service src/index.ts exports the service class as export default + all public types; a function/namespace plugin src/index.ts exports name/inject/Config/apply as named exports and NO default (the export-shape rule above).
src/types.ts contains only types — no runtime code.
Tests live at package level under tests/, not src/__tests__/.
A package's README and JSDoc are part of the change: altered behavior (config keys, defaults, error codes, wire fields) updates them in the same commit. doc-sync gates what it can; prose accuracy stays on the author (the documentation standard).

Read the per-package README.md for package-specific details: service API, events, extension points, TODOs.

2.8 KiB Raw Blame History

AGENTS.md — Harness Packages

2.8 KiB

Raw Blame History