ICM: make webhook-client ICM-ready

[sparck75]

What and why

This makes webhook-client ICM-ready to the ICM standard 1.1.0 (the one memoryrelay/api main runs). The repository had no instruction file of any kind. AGENTS.md is now the entry, a router: what the package is, where things live, a route table by what just happened, and the rules. CLAUDE.md is a one-line pointer to it. .github/icm/ holds the three jobs this repository repeats (fix, cover a new connector endpoint, release) and five shared facts. Each fact points at the file that owns it (path:line) and does not restate it.

The owner decided (2026-10-15) that this repository becomes its own MemoryRelay workspace, webhook-client, which the Alteriom hub will delegate to. No code changes. The release pipeline never publishes: a pushed v* tag publishes, and a person pushes it. The repository is public and Alteriom/alteriom-webhook-connector is private, so nothing here names the service's host or describes its internals. The generator and the CI job are vendored byte for byte from the standard.

Before / after

	Before	After
Instruction files an agent read whole	none: 0 tokens	entry AGENTS.md 52 lines, 5,370 B (~1,343 tokens); CLAUDE.md 1 line
Routes	none	11
Pipelines / stages	none	3 / 9, every stage 1 read from the entry
Stage load (check-tree)	n/a	median ~3,062 tokens, max ~3,240 (endpoint-spec)
Shared facts	none	5, dated, 23 pinned files in all

Before was zero, so nothing gets cheaper. What this adds is structure. An agent used to start from README.md (26.7 KB, ~6.7k tokens) and guess. Now it gets a route, a 3k-token stage, the group pattern every API method follows, and the traps the history shows: tags pushed from branches, a changelog behind the tags, and an optional peer that is not optional.

Inventory

Top level. src/: the REST client, receiver, framework adapters, WebSocket client, types, guards, errors. tests/: five jest suites. schemas/: an OpenAPI snapshot from the first commit. docs/superpowers/: the WebSocket design and plan. .github/workflows/: ci.yml, docs.yml, release.yml. The root also has README.md, CONTRIBUTING.md, CHANGELOG.md, LICENSE and the build configs (tsconfig.json, jest.config.js, eslint.config.js, a legacy .eslintrc.json).

Instruction files. None: no CLAUDE.md, AGENTS.md, .cursorrules, Copilot instructions, .claude/, .codex/ or GEMINI.md.

Documents a contributor is expected to read. README.md, CONTRIBUTING.md, CHANGELOG.md. They are not pinned as workspace nodes: the README and the WebSocket design name the service's host, CONTRIBUTING.md carries contact addresses, and the workspace serves pinned files to every reader. The facts cite their sections instead, and _shared/documents.md lists them.

Jobs people repeat, with evidence (gh pr list --state merged, 11 merged):

• Cover the service: Add v1 API endpoint versioning to client #4, feat: v0.1.0 - Complete API coverage with 15+ new endpoint groups #6, feat: v1.0.0 — typed event shapes and command center filters #7, feat: WebSocketClient for real-time event streaming (#105) #8, feat: v1.1.0 — AgentSubscriptions client + fix delivery_mode types (#9, #10) #11, feat: v1.2.0 — agentSubscriptions.poll() helper for on_demand mode #12, test: add agentSubscriptions and poll() test coverage #13.
• Fixes: Fix: Update API paths to match current connector #1, Fix client API paths: remove /v1 prefix to match server endpoints #5, fix(deps): clear all 40 open Dependabot alerts (brace-expansion, axios, js-yaml, babel, socket.io-parser) #14 (40 advisories), docs: remove private repo links and internal names from README #15.
• Releases: 6 v* tags, 5 versions on npm, each through release.yml.
• No Dependabot version updates are configured; advisories are fixed by hand (fix(deps): clear all 40 open Dependabot alerts (brace-expansion, axios, js-yaml, babel, socket.io-parser) #14). That is a route into 01-fix, not a pipeline of its own.

Pipelines and routes

Pipeline	Stages	Why it exists
01-fix	reproduce → fix → verify	defects, wrong paths, advisories
02-endpoint	spec (the documented contract, names, version class) → implement (the group pattern, tests asserting what is sent) → verify (README section, changelog, PR)	the most common change here
03-release	plan → prepare (version via npm version --no-git-tag-version, changelog) → publish (the person tags main after the merge; the agent confirms npm and the release)	a tag publishes, so the tag is a person's act

Routes: triage, fix, ci-red, advisory, security (a private report as the contributing guide says), endpoint, fix-to-endpoint, release, publish-check, next, status.

Shared facts: architecture.md, build-and-test.md, release.md, gotchas.md, documents.md.

Reconciliation

There was no instruction file, so there is no section to carry over and nothing dropped. The facts come from the code, the workflows and the documents, each cited at 3e2e8fe.

Dropped as false

None: there were no instruction files. The documents' disagreements with the code are in _shared/documents.md "Known drift" (not edited here):

• CONTRIBUTING.md asks for 90% coverage; jest.config.js:11 enforces about 55%.
• CHANGELOG.md ends at 1.1.0 and misses AgentSubscriptions and 1.2.0.
• The src/index.ts header says @version 0.0.1.
• schemas/openapi.json is stale and unused.
• .eslintrc.json is ignored by ESLint 9.

Memories folded / skipped

None. The brief named no Claude Code memory directory for this repository.

Checks

$ python .github/icm/_system/generate.py
up to date
$ python .github/icm/_system/generate.py --check --strict
up to date; lint clean

$ python -m app.icm.cli check-tree <worktree> --source .github/icm/icm.source.json --repo Alteriom/webhook-client
ok   Every stage is easy to find: An agent reaches each stage from AGENTS.md in 1 reads at most (limit 2).
ok   Entry file stays short: 52 lines. Keep it under 60, it must stay under 120.
ok   Each stage gets a small context: Stage endpoint-spec hands the agent about 3,240 tokens, counting every file it must read. The method's guide is 2,000-8,000; a package is held to its own budget. Estimate: characters / 4.
ok   Every route lands somewhere: Each of the 11 rows of the routing table in AGENTS.md lands somewhere, 2 reads away at most.
ok   One entry file, not two drifting copies: CLAUDE.md and AGENTS.md (where both exist) do not drift.
ok   Every stage says what it reads and writes: Every stage names its inputs, outputs and human check; every package its inputs.
ok   The workspace has its form's shape: Each declared form has the shape the method expects.
ok   Every file is pinned and intact: Every file matches its pin.
entry AGENTS.md lines=52
routes: triage, fix, ci-red, advisory, security, endpoint, fix-to-endpoint, release, publish-check, next, status
stage fix-reproduce: hops=1 tokens~3230
stage fix-fix: hops=1 tokens~3128
stage fix-verify: hops=1 tokens~3052
stage endpoint-spec: hops=1 tokens~3240
stage endpoint-implement: hops=1 tokens~3131
stage endpoint-verify: hops=1 tokens~3012
stage release-plan: hops=1 tokens~3062
stage release-prepare: hops=1 tokens~2893
stage release-publish: hops=1 tokens~2395
release 5f62c4043c26f533ee8eee6a971b29f4cc5f75f8b3fa94bd250aac675c417260
pinned files=23 tokens~9820

CI on this pull request. Lint, Test (22), Build, CodeQL and the ICM check pass. Security Audit (npm audit --audit-level=moderate) fails, and the failure is unrelated to this change. The PR does not touch package.json or package-lock.json (git diff --stat origin/main -- package.json package-lock.json is empty). The same audit run on main's lockfile today reports 37 vulnerabilities (1 critical, 31 high, 5 moderate) in axios ≤ 1.19.0, brace-expansion, braces, handlebars and sprintf-js. The advisories were published after main's last green CI run (2026-09-28, 3e2e8fe). The next push to main will be red for the same reason.

The repository's own checks were run locally on the base commit: npm ci, npm test (5 suites, 99 tests), npm run lint (0 errors, 8 existing any warnings), npm run build. All passed. The generator was run on a clean tree, with no ignored build outputs on disk. This PR touches no code, test or lint input. No test enumerates workflows. icm-check.yml parses as YAML.

Left for a person

• Create the MemoryRelay workspace webhook-client (Git, this repository, branch main, root empty) and sync it; then the Alteriom hub delegates to it.
• Security Audit is red against main's lockfile (see CI above). axios is a runtime dependency, so its advisories reach consumers whose installs resolve 1.19.0 or older. This needs an advisory run (route advisory, the same shape as fix(deps): clear all 40 open Dependabot alerts (brace-expansion, axios, js-yaml, babel, socket.io-parser) #14).
• socket.io-client is not optional in practice. src/index.ts:126 re-exports WebSocketClient, and src/ws-client.ts:1 imports socket.io-client at module load. So require('@alteriom/webhook-client') without it fails with MODULE_NOT_FOUND: reproduced against a build of 3e2e8fe with only axios and zod installed. README.md tells REST-only users they do not need it. This is a 01-fix run (or a 02-endpoint one, if the fix is a separate entry point), recorded in _shared/gotchas.md.
• v1.1.0 and v1.2.0 point at feature-branch commits, not at the squash merges on main. Nothing to undo, but future tags go on main (_shared/release.md).
• CHANGELOG.md lags the tags. main has no src/ change since v1.2.0, so no release is owed.
• The receiver's duplicate key is subscription_id:<aggregate id>, or subscription_id:unknown without an aggregate (src/receiver.ts:80). So a second signed delivery for the same subscription with no aggregate counts as a duplicate. The Python SDK does the same, and I reproduced it there (ICM: make alteriom-webhook-client-python ICM-ready alteriom-webhook-client-python#3). Whether that is intended is a decision for both SDKs.
• src/client.ts.patch is an 18-line patch file committed inside src/ in the first commit. Keep or delete it.
• The other "Known drift" entries in _shared/documents.md, each a small docs PR.

No committed credential was found: the secret-looking strings in tests/ and README.md are placeholders such as test-secret and my-webhook-secret.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-10-15T17:14:02.213753Z	34b305d	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.