docs: generated cordis events + services catalog

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.

packages/AGENTS.md

@@ -13,6 +13,6 @@ 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 (see the plugin-export-shape rule above)
 - `src/types.ts` contain only types — no runtime code
 - Tests live at package level under `tests/`, not `src/__tests__/`
-- A package's README and module/JSDoc comments are part of the change: when you alter behavior (config keys, defaults, error codes, wire fields), update them in the same commit. CI runs `pnpm run doc-sync`, which typechecks fenced `ts` blocks in `packages/*/*.md`, verifies the event-taxonomy table, and checks markdown wrapping across this file too — but it does NOT catch prose drift (config keys, defaults, error codes), so those stay on the author.
+- A package's README and module/JSDoc comments are part of the change: when you alter behavior (config keys, defaults, error codes, wire fields), update them in the same commit. CI runs `pnpm run doc-sync`, which typechecks fenced `ts` blocks in `packages/*/*.md`, regenerates the cordis events/services catalog from the `interface Events` / `interface Context` declarations (failing if the committed copy is stale), and checks markdown wrapping across this file too — but it does NOT catch prose drift (config keys, defaults, error codes), so those stay on the author. A new event needs an `@mode` tag on its JSDoc (the catalog generator hard-errors without it — see the root AGENTS.md).
 
 Read the per-package README.md for package-specific details: service API, events, extension points, TODOs.

packages/agent/tests/gen-cordis-catalog.spec.ts

@@ -0,0 +1,83 @@
+/**
+ * Negative-path tests for the cordis catalog generator (`scripts/gen-cordis-catalog.ts`).
+ *
+ * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
+ * the freshness half is exercised by `pnpm run verify-cordis-catalog` in CI.
+ * What a freshness diff CANNOT prove is that the generator REJECTS malformed
+ * source the way it promises to — a missing `@mode` tag, or a tag that
+ * contradicts the signature shape. These tests drive `collectEvents()` against
+ * synthetic fixture packages to prove each guard fires (and that a well-formed
+ * event passes), mirroring the drift-guard negative tests for verify-type-equiv.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectEvents } from '../../../scripts/gen-cordis-catalog.ts'
+
+/** Write a fixture package exposing one `interface Events` block and return the
+ * scan root to hand `collectEvents`. */
+function fixtureRoot(eventsBlock: string): string {
+  const root = mkdtempSync(join(tmpdir(), 'cordis-catalog-'))
+  const dir = join(root, 'packages', 'fix', 'src')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(
+    join(dir, 'index.ts'),
+    `declare module 'cordis' {\n  interface Events {\n${eventsBlock}\n  }\n}\n`,
+  )
+  return root
+}
+
+const roots: string[] = []
+const make = (block: string): string => {
+  const r = fixtureRoot(block)
+  roots.push(r)
+  return r
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+describe('gen-cordis-catalog collectEvents', () => {
+  it('extracts a well-formed event with its @mode and JSDoc', () => {
+    const events = collectEvents(make(
+      '    /**\n     * A thing happened.\n     * @mode emit\n     */\n    \'fix/happened\'(id: string): void',
+    ))
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({ name: 'fix/happened', scope: 'fix', mode: 'emit', doc: 'A thing happened.' })
+  })
+
+  it('classifies a trailing-next signature as a waterfall', () => {
+    const events = collectEvents(make(
+      '    /**\n     * Intercept it.\n     * @mode waterfall\n     */\n    \'fix/intercept\'(x: number, next: () => Promise<number>): Promise<number>',
+    ))
+    expect(events[0]?.mode).toBe('waterfall')
+  })
+
+  it('accepts a parallel (awaited, no next) event by trusting the tag', () => {
+    const events = collectEvents(make(
+      '    /**\n     * Flush.\n     * @mode parallel\n     */\n    \'fix/flush\'(): Promise<void> | void',
+    ))
+    expect(events[0]?.mode).toBe('parallel')
+  })
+
+  it('hard-errors when an event is missing its @mode tag', () => {
+    expect(() => collectEvents(make(
+      '    /** No mode here. */\n    \'fix/untagged\'(id: string): void',
+    ))).toThrow(/missing an @mode tag/)
+  })
+
+  it('hard-errors when @mode contradicts a trailing-next (waterfall) shape', () => {
+    expect(() => collectEvents(make(
+      '    /**\n     * Mislabeled.\n     * @mode emit\n     */\n    \'fix/wrong\'(x: number, next: () => Promise<number>): Promise<number>',
+    ))).toThrow(/trailing 'next' parameter .* tagged '@mode emit'/)
+  })
+
+  it('hard-errors when @mode waterfall has no trailing next to delegate to', () => {
+    expect(() => collectEvents(make(
+      '    /**\n     * Not actually a waterfall.\n     * @mode waterfall\n     */\n    \'fix/nonext\'(id: string): void',
+    ))).toThrow(/tagged '@mode waterfall' but has no trailing 'next'/)
+  })
+})