Docs: reconcile plugins-and-extensions.md and ARCHITECTURE.md with the shipped event model #99

Closed
opened 2026-10-27 13:34:56 +00:00 by sam · 0 comments
Owner

Separate bead so it is not lost once the feature lands.

  1. 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.

  2. 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.

  3. 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.

  4. 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

Separate bead so it is not lost once the feature lands. 1. 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. 2. 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. 3. 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. 4. 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_
sam added the mediumtask labels 2026-10-27 13:34:56 +00:00
sam self-assigned this 2026-10-27 13:34:56 +00:00
sam closed this issue 2026-10-27 13:34:56 +00:00
sam added a new dependency 2026-10-27 13:41:42 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#99