Docs: reconcile plugins-and-extensions.md and ARCHITECTURE.md with the shipped event model #99
Notifications
Due Date
No due date set.
Depends on
Reference: sam/archie#99
Reference in new issue
Block a user
Separate bead so it is not lost once the feature lands.
docs/architecture/plugins-and-extensions.md is an APPROVED foundation dated 2026-07-28 and currently describes only the plugin framework. If the design bead concluded that extensions may react to events, this doc has to say how -- and if it concluded that generic untyped dispatch is allowed after all, this doc must be amended deliberately rather than contradicted by code.
ARCHITECTURE.md describes work intake as polling. Once webhook intake ships, that is no longer the whole picture, and the task lifecycle section needs the new entry path.
CLAUDE.md's per-package traps section should gain whatever trap this work creates -- HMAC verification, replay windows, the poll/webhook double-dispatch hazard. That section exists precisely for things an agent will otherwise break.
config.example.toml needs the intake flag documented with its default, alongside poll_interval.
CLAUDE.md's own rule: a doc that contradicts its code is worse than none, because the next reader trusts it.
Acceptance criteria
plugins-and-extensions.md reflects the decided extension model; ARCHITECTURE.md documents webhook intake alongside polling; config.example.toml documents the intake flag and default; any new trap is recorded in CLAUDE.md.
Notes
Verified against actual code: config.example.toml already documented the intake flag/default (no change needed there). Made changes: ARCHITECTURE.md (opening description, package map rows for internal/forge/webhook and internal/webhookguard, Provenance-by-origin paragraph corrected from 'forge-polled' to 'forge-sourced (poll or webhook)', new 'Webhook intake' subsection under Forge Interface, [forge] config bullet, Implemented/Planned list -- also fixed an adjacent stale claim that Gitea forge was still 'planned' when internal/forge/gitea.go fully implements it); CLAUDE.md gained a new internal/forge/webhook/ trap entry (HMAC-before-parse, the idempotency-key poll/webhook dedup invariant, single-identity-only guard); docs/architecture/plugins-and-extensions.md gained an 'Event sources and reactions' section cross-referencing the 7d5u.1 decision, correctly scoped to only claim Module as shipped (Channel/Forge action positions are still open investigation t2db.19, not shipped).
Close reason
ARCHITECTURE.md and plugins-and-extensions.md reconciled with shipped webhook intake and the 7d5u.1 decision; config.example.toml already documented the intake flag/default; CLAUDE.md gained the internal/forge/webhook trap. Commit 8b53dc3.
Imported from beads
archie-core-7d5u.6· GitHub #554 · type task · priority P2 · created 2026-08-21 · closed 2026-09-02