ICM: make alteriom-webhook-client-python ICM-ready

[sparck75]

What and why

This makes alteriom-webhook-client-python 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 two pipelines, fix (which also covers models falling behind the deliveries) and 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, alteriom-webhook-client-python, which the Alteriom hub will delegate to. No code changes. The release pipeline never publishes: a published GitHub release uploads to PyPI, and a person publishes it. The repository is public and Alteriom/alteriom-webhook-connector is private, so nothing here describes the service. 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 48 lines, 4,722 B (~1,180 tokens); CLAUDE.md 1 line
Routes	none	9
Pipelines / stages	none	2 / 6, every stage 1 read from the entry
Stage load (check-tree)	n/a	median ~2,634 tokens, max ~3,379 (fix-reproduce)
Shared facts	none	5, dated, 19 pinned files in all

Before was zero, so nothing gets cheaper; the value is structure. The package is 278 lines of code, but its two real decisions were written down nowhere: what the receiver accepts, and how a release reaches PyPI. Now a route, a stage contract and a pointer to the owning line say each one. The traps are in _shared/gotchas.md: deliveries without an aggregate are taken as duplicates, signatures are over raw bytes, and trusted publishing depends on names that live on PyPI's side.

Inventory

Top level. src/alteriom_webhook_client/: signature, receiver, models, FastAPI helper, 278 lines. tests/: three pytest files, 18 tests. .github/workflows/: ci.yml, publish.yml. The root also has pyproject.toml, README.md and LICENSE.

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

Documents. README.md only, pinned through _shared/documents.md. There is no changelog, contributing guide or security policy file; private vulnerability reporting is enabled on the repository, and the security route uses it.

Jobs with evidence.

• Release: v0.1.0, the one tag and release, now on PyPI. publish.yml needed three runs (two failures) and four commits to reach trusted publishing.
• Fix: the publishing fixes, and docs: add MIT LICENSE and drop private repo link #2.
• Everything else is the initial build (feat: commits) and two PRs in all (ci: add GitHub Actions CI/CD for testing and PyPI publishing #1, docs: add MIT LICENSE and drop private repo link #2). Two pipelines is what the evidence supports; the third job the code implies, keeping the models level with the TypeScript client, is a route (model-drift) into 01-fix.

Pipelines and routes

Pipeline	Stages	Why it exists
01-fix	reproduce (the person decides here whether a behaviour change is wanted) → fix → verify	defects, model drift, red CI
02-release	plan → prepare (bump pyproject.toml, draft notes) → publish (the person publishes the GitHub release; the agent confirms PyPI and a clean install)	a published release uploads, so publishing is a person's act

Routes: triage, fix, ci-red, model-drift, security, 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, pyproject.toml, the workflows and the README, each cited at 337bb90.

Dropped as false

None: there were no instruction files. No drift was found between README.md and the code.

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/alteriom-webhook-client-python
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: 48 lines. Keep it under 60, it must stay under 120.
ok   Each stage gets a small context: Stage fix-reproduce hands the agent about 3,379 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 9 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=48
routes: triage, fix, ci-red, model-drift, security, release, publish-check, next, status
stage fix-reproduce: hops=1 tokens~3379
stage fix-fix: hops=1 tokens~2701
stage fix-verify: hops=1 tokens~2123
stage release-plan: hops=1 tokens~2749
stage release-prepare: hops=1 tokens~2567
stage release-publish: hops=1 tokens~2286
release 88309c07f8010544223675d624496559c5681b69bbf98948d9197fc33482b493
pinned files=19 tokens~7572

The repository's own tests were run locally on the base commit in a fresh virtual environment (pip install -e ".[dev]", pytest tests/): 18 passed. The generator was run on a clean tree, with no ignored files on disk. This PR touches no code or test. No test enumerates workflows. icm-check.yml parses as YAML.

Left for a person

• Create the MemoryRelay workspace alteriom-webhook-client-python (Git, this repository, branch main, root empty) and sync it; then the Alteriom hub delegates to it.
• Deliveries without an aggregate are rejected as duplicates. The duplicate key is subscription_id:none when aggregate is absent (src/alteriom_webhook_client/receiver.py:131). A second correctly signed delivery for the same subscription without an aggregate, within the one-hour TTL, gets "Duplicate delivery detected" (401). I reproduced it on 337bb90 with two deliveries whose delivered_at differed. The TypeScript receiver in Alteriom/webhook-client builds its key the same way (subscription_id:unknown). Whether that is intended is a decision for both SDKs, recorded in _shared/gotchas.md; it is not changed here.

No committed credential was found: the secret-looking strings in tests/ and README.md are placeholders such as test-secret and your-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:22.785226Z	6226027	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.