From b5ca1b889b6a7959524b3ce188fdb327e77d511a Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 3 Sep 2026 06:48:02 +1000 Subject: [PATCH] docs: reconcile plugins-and-extensions.md and ARCHITECTURE.md with shipped webhook intake ARCHITECTURE.md described forge intake as polling-only and listed Gitea as still "planned" despite internal/forge/gitea.go fully implementing it -- both stale since 7d5u.4/.2/.3 shipped forge webhook intake. Corrected the opening description, package map, Provenance-by-origin paragraph, [forge] config bullet, and Implemented/Planned lists; added a "Webhook intake" subsection documenting internal/forge/webhook as a separate HTTP receiver reusing the poller's TaskEnvelope/PublishTask path. CLAUDE.md gains the internal/forge/webhook/ trap: HMAC verification must precede payload parsing, and the webhook-built TaskEnvelope must keep its poll-compatible owner/repo/number idempotency key or poll/webhook double-dispatch returns. plugins-and-extensions.md gains a section cross-referencing 7d5u.1's decision (in-process typed families, no amendment needed) and naming the Module action position as the shipped instance -- Channel/Forge positions are correctly left as open investigation (t2db.19), not claimed as shipped. Closes archie-core-7d5u.6. --- .beads/issues.jsonl | 2 +- ARCHITECTURE.md | 46 ++++++++++++++++----- CLAUDE.md | 13 ++++++ docs/architecture/plugins-and-extensions.md | 16 +++++++ 4 files changed, 66 insertions(+), 11 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 76495b890..d112ee720 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -175,7 +175,7 @@ {"_type":"issue","id":"archie-core-1ysw.4","title":"Fail refresh when the configured base cannot resolve","description":"Prepared worktrees currently swallow every resolveBase error and report successful refresh against stale history.","acceptance_criteria":"Prepared-worktree refresh returns a contextual error for a missing, renamed, or invalid base; fresh and reused Prepare paths have consistent tests.","status":"closed","priority":2,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-08-22T11:01:45Z","created_by":"Sam Catlow","updated_at":"2026-08-24T07:00:23Z","started_at":"2026-08-22T11:52:19Z","closed_at":"2026-08-24T07:00:23Z","close_reason":"Fixed on main: prepared-worktree refresh now returns the resolveBase error instead of swallowing it (worktree.go:253-258, 'a missing base is configuration or repository drift and must fail closed'); resolveBase tries the qualified remote ref then origin/\u003cbase\u003e and errors otherwise.","external_ref":"https://github.com/samcharles93/archie-core/issues/601","metadata":null,"dependencies":[{"issue_id":"archie-core-1ysw.4","depends_on_id":"archie-core-1ysw","type":"parent-child","created_at":"2026-08-22T21:01:44Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-j8b4","title":"Implement persistent session memory and plugin storage","description":"Replace the PRD section 3 placeholder in internal/storage/storage.go with the specified persistent storage behavior for session.jsonl, memory.jsonl, and plugins.","status":"closed","priority":2,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-08-22T10:32:31Z","created_by":"Sam Catlow","updated_at":"2026-08-24T07:12:08Z","started_at":"2026-08-22T10:32:37Z","closed_at":"2026-08-24T07:12:08Z","close_reason":"Implemented persistent session transcript, cross-session memory, and staged plugin storage [Closure restored 2026-08-24: originally closed 2026-08-22, lost when the beads DB was rebuilt (.beads.backup-pre-recovery).]","external_ref":"https://github.com/samcharles93/archie-core/issues/602","metadata":null,"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-t2db.6","title":"Docs: document playbooks, bindings and the intake threat model","description":"Separate so it is not lost when the feature lands.\n\n- The playbook/binding model in docs/architecture/: what a binding is, where it is persisted, how matchers resolve, how versioning works.\n- The threat model, written down plainly: this is a public intake surface that can start agents. Record what protects it and what does not.\n- ARCHITECTURE.md task lifecycle: a task started by a playbook binding has a different provenance from a forge-issue task, and the lifecycle section should say so.\n- Operator docs: how to point an external app at archie and build a first playbook, end to end.\n\nCLAUDE.md's rule: a doc that contradicts its code is worse than none.\n\nPROGRESS 2026-09-03: three of four items done.\n- Binding model + threat model: docs/architecture/bindings.md (commit 41dffe3), every claim verified against actual code, not assumed.\n- ARCHITECTURE.md task lifecycle: provenance addendum landed (commit edb90e1), cross-referencing bindings.md. Also fixed a second, related staleness in the same section (the Routing table no longer reflects hardcoded-only behavior post t2db.9/.10).\n- Remaining (BLOCKED, not just unstarted): the end-to-end operator walkthrough. The epic's own pitch is a no-code, DASHBOARD-based flow ('point a webhook at archie, open the dashboard, map fields, bind, save'). Verified 2026-09-03: ui/src/ has zero binding-related files -- t2db.8's UI editor does not exist yet. Writing a walkthrough describing dashboard clicks that don't exist would itself be exactly the 'doc that contradicts its code' problem this ticket exists to prevent, just prospectively. Added a formal dependency on t2db.8 rather than write a curl-based workaround doc that misrepresents the intended no-code experience -- do the walkthrough after t2db.8's UI lands, describing what actually exists.","acceptance_criteria":"Operator walkthrough exists, end to end, describing the real dashboard UI (blocked on t2db.8). The other three acceptance items (binding model + threat model documented, ARCHITECTURE.md covers playbook-originated tasks) are done.","status":"closed","priority":2,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:46Z","created_by":"Sam Catlow","updated_at":"2026-09-02T20:20:15Z","closed_at":"2026-09-02T20:20:15Z","close_reason":"All four items done: binding model + threat model (bindings.md, 41dffe3), ARCHITECTURE.md task-lifecycle addendum (edb90e1), operator walkthrough (this commit). Unblocked once t2db.8's UI landed.","external_ref":"https://github.com/samcharles93/archie-core/issues/553","dependencies":[{"issue_id":"archie-core-t2db.6","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:45Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.6","depends_on_id":"archie-core-t2db.4","type":"blocks","created_at":"2026-08-21T23:45:53Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.6","depends_on_id":"archie-core-t2db.8","type":"blocks","created_at":"2026-09-02T18:41:43Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":0,"comment_count":0} -{"_type":"issue","id":"archie-core-7d5u.6","title":"Docs: reconcile plugins-and-extensions.md and ARCHITECTURE.md with the shipped event model","description":"Separate bead so it is not lost once the feature lands.\n\n1. 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.\n\n2. 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.\n\n3. 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.\n\n4. config.example.toml needs the intake flag documented with its default, alongside poll_interval.\n\nCLAUDE.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.","status":"open","priority":2,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:52Z","created_by":"Sam Catlow","updated_at":"2026-08-22T09:25:30Z","external_ref":"https://github.com/samcharles93/archie-core/issues/554","dependencies":[{"issue_id":"archie-core-7d5u.6","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:51Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.6","depends_on_id":"archie-core-7d5u.4","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"archie-core-7d5u.6","title":"Docs: reconcile plugins-and-extensions.md and ARCHITECTURE.md with the shipped event model","description":"Separate bead so it is not lost once the feature lands.\n\n1. 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.\n\n2. 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.\n\n3. 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.\n\n4. config.example.toml needs the intake flag documented with its default, alongside poll_interval.\n\nCLAUDE.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).","status":"in_progress","priority":2,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:52Z","created_by":"Sam Catlow","updated_at":"2026-09-02T20:47:54Z","started_at":"2026-09-02T20:43:26Z","lease_expires_at":"2026-09-02T20:48:26Z","heartbeat_at":"2026-09-02T20:43:26Z","external_ref":"https://github.com/samcharles93/archie-core/issues/554","dependencies":[{"issue_id":"archie-core-7d5u.6","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:51Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.6","depends_on_id":"archie-core-7d5u.4","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-h019.5","title":"Calibration: confirm findings adversarially before surfacing them","description":"The risk that kills this feature is a reviewer that cries wolf. A findings list padded with speculation trains the operator to skim past it, and then the feature is worse than nothing because it consumes attention while lowering trust.\n\nBefore a finding is surfaced, it must be independently checked and marked CONFIRMED or PLAUSIBLE, with only CONFIRMED able to block. The reviewer must also be able to return zero findings, and to state which properties it checked and cleared -- a review that reports nothing is a valid and welcome result, and saying so explicitly is what distinguishes 'I checked and it is fine' from 'I did not look'.\n\nPrior art from the 2026-08-20/21 sessions on PR #530: three passes each separated confirmed from plausible, one explicitly listed properties it had verified clean, and the confirmed findings were reproduced by mutation before being trusted. That calibration is the feature, not the finding count.","acceptance_criteria":"Only CONFIRMED findings block PR creation; a zero-finding review is representable and reported as such; the reviewer records which properties it checked and cleared; padding with style nits is explicitly out of contract.","status":"open","priority":2,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:03:15Z","created_by":"Sam Catlow","updated_at":"2026-08-22T09:25:30Z","external_ref":"https://github.com/samcharles93/archie-core/issues/555","dependencies":[{"issue_id":"archie-core-h019.5","depends_on_id":"archie-core-h019","type":"parent-child","created_at":"2026-08-21T13:03:15Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.5","depends_on_id":"archie-core-h019.1","type":"blocks","created_at":"2026-08-21T13:03:25Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.5","depends_on_id":"archie-core-h019.2","type":"blocks","created_at":"2026-08-21T13:03:25Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-h019.6","title":"Surface findings on the PR body and the dashboard","description":"The output has to land where the operator already looks, or the review is invisible work.\n\nOn the PR archie opens: a findings section stating what was checked, what was found, what was fixed, and what survived. A PR with zero findings should say the review ran and found nothing -- silence is indistinguishable from the review not running, which is the same unverified-claim problem the update-verification work (PR #530) was about.\n\nOn the dashboard and /api/tasks: a parked-for-findings task must show why, the same way a park reason is already surfaced today. An operator seeing waiting_human needs the findings without digging through logs.","acceptance_criteria":"PR body carries a findings section including the zero-finding case; a task parked on a surviving finding shows the findings as its park reason in the dashboard and /api/tasks; nothing requires reading task logs to learn why a PR was withheld.","status":"open","priority":2,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:03:15Z","created_by":"Sam Catlow","updated_at":"2026-08-22T09:25:31Z","external_ref":"https://github.com/samcharles93/archie-core/issues/556","dependencies":[{"issue_id":"archie-core-h019.6","depends_on_id":"archie-core-h019","type":"parent-child","created_at":"2026-08-21T13:03:15Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.6","depends_on_id":"archie-core-h019.1","type":"blocks","created_at":"2026-08-21T13:03:25Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.6","depends_on_id":"archie-core-h019.2","type":"blocks","created_at":"2026-08-21T13:03:26Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":1,"comment_count":0} {"_type":"issue","id":"archie-core-h019.7","title":"Docs: promote the shipped review stage into docs/architecture and reconcile CLAUDE.md","description":"Under the scope-discipline rule merged as PR #533, a design is promoted into docs/architecture/ only once it is built and true. This is that promotion, and it is deliberately a separate bead so it is not lost when the feature lands and attention moves on.\n\nDo three things once the stage ships:\n\n1. Promote the docs/prds/ decision into docs/architecture/, describing the review stage as it actually works -- not as designed. Cut anything a reader could learn from the code.\n2. Update ARCHITECTURE.md's task lifecycle: queued -\u003e running(workflow:stage) -\u003e pr_open -\u003e merged|rejected gains a review stage that can divert to waiting_human before pr_open. The current text does not mention it.\n3. Reconcile CLAUDE.md's Development Protocol. It currently tells a human or agent contributor to run the adversarial pass by hand. Once archied does this for the PRs it opens, that section needs to say which path applies to whom, or it will read as describing a manual step that is now automatic.\n\nCLAUDE.md's own rule: a comment or doc that contradicts its code is worse than none, because the next reader trusts it.","acceptance_criteria":"docs/architecture/ describes the shipped stage; ARCHITECTURE.md's lifecycle includes the review stage and the waiting_human diversion; CLAUDE.md distinguishes the manual contributor pass from archied's automated one; no doc still claims review is only manual.","status":"open","priority":2,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-08-21T13:03:15Z","created_by":"Sam Catlow","updated_at":"2026-08-22T09:25:32Z","external_ref":"https://github.com/samcharles93/archie-core/issues/557","dependencies":[{"issue_id":"archie-core-h019.7","depends_on_id":"archie-core-h019","type":"parent-child","created_at":"2026-08-21T13:03:15Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.7","depends_on_id":"archie-core-h019.4","type":"blocks","created_at":"2026-08-21T13:03:26Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.7","depends_on_id":"archie-core-h019.6","type":"blocks","created_at":"2026-08-21T13:03:26Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":0,"comment_count":0} diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 301894e67..8ea159147 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,9 +1,12 @@ # archie-core Architecture -**archied** is a resident daemon that polls its configured forges — GitHub and -Gitea — for issues assigned to its bot user, carrying its label, or either -(`dispatch` mode, per identity), works each one in an isolated worktree through -a routed workflow, and opens pull requests for human review. A single daemon can +**archied** is a resident daemon that discovers forge work — GitHub and Gitea +issues assigned to its bot user, carrying its label, or either (`dispatch` +mode, per identity) — by polling (the default) or, single-identity +deployments only, reacting to forge webhook events the instant they arrive +(`Forge.Intake` = `webhook`/`both`, see `docs/prds/event-sources-and- +reactions.md`), works each matched issue in an isolated worktree through a +routed workflow, and opens pull requests for human review. A single daemon can serve several identities across several forges, each with its own `bot_user`, label, and repository set. @@ -29,6 +32,8 @@ See `docs/architecture/organisation.md` for the target structure and | `internal/domain/workintake/`| `TaskEnvelope`, routing `Kind`, label vocabulary, task subjects | | `internal/agentexec/` | Worker-local stage protocol and ai-sdk loop runner | | `internal/forge/` | Forge interface: GitHub and Gitea implementations | +| `internal/forge/webhook/` | Optional forge webhook receiver: GitHub issue events → `workintake.TaskEnvelope`, same publish path as polling | +| `internal/webhookguard/` | Cross-cutting inbound-webhook mechanics: HMAC verification, per-source rate limiting | | `internal/worktree/` | Git operations: clone, branch, commit, push, diff, cleanup | | `internal/store/` | Task store interface and SQLite implementation; RPC clients proxy it | | `internal/events/` | In-process event bus: publish/subscribe for observability | @@ -65,9 +70,14 @@ dashboard and `/api/tasks`. Retries are an explicit operator action capped by **Provenance by origin:** a task's origin determines which enqueue path created it, though every origin converges on the same `tasks` table and the -same `Route`/`Run` lifecycle above once queued. Forge-polled tasks enqueue via -`workintake.TaskEnvelope` (see `docs/prds/event-sources-and- -reactions.md`'s decided contract); playbook-binding-dispatched tasks enqueue +same `Route`/`Run` lifecycle above once queued. Forge-sourced tasks — whether +discovered by polling or, single-identity only, delivered by the forge +webhook receiver (`internal/forge/webhook`) — enqueue via the same +`workintake.TaskEnvelope` and `PublishTask` path (see `docs/prds/event-sources- +and-reactions.md`'s decided contract); `TaskEnvelope.IdempotencyKey` is keyed +on `owner/repo/number`, not delivery source, so a webhook-delivered issue and +a later poll of the same issue dedup for free instead of double-enqueuing. +Playbook-binding-dispatched tasks enqueue via `EnqueueChatTask`/`EnqueueBindingTask` (`internal/store`), the same direct path chat-spawned tasks use, stamped with `binding_id`/`binding_version` for provenance. See `docs/architecture/bindings.md` for the binding model and its @@ -198,6 +208,17 @@ removed when transitioning. They report state; they do not drive it. Removing a label no longer retries a parked task -- retries are an explicit operator action from the dashboard or chat, capped by `max_retries`. +### Webhook intake (alternative to polling) + +`internal/forge/webhook` is a separate HTTP receiver, not a `Forge` method: it +verifies a GitHub webhook's HMAC signature (`internal/webhookguard.VerifyHMAC`), +decodes an `issues` event, applies the same dispatch predicate the poller +uses, and calls the same `PublishTask` the poller calls. It is opt-in via +`Forge.Intake` (`poll` default, `webhook`, `both`) and single-identity only -- +a deployment with `[[identities]]` configured keeps polling per identity +instead. See `docs/prds/event-sources-and-reactions.md` for why this stayed a +thin decode-and-reuse layer rather than a second intake mechanism. + ## Worktree Manager Every task gets a fresh clone -- no persistent state between runs. The model @@ -214,7 +235,10 @@ appears in `.git/config` or process argv. Daemon-level TOML (`~/.config/archie/config.toml`): -- `[forge]` -- type (github), host, token secret reference +- `[forge]` -- type (github/gitea), host, token secret reference; `intake` + (`poll` default, `webhook`, or `both`) with `webhook_secret`/`webhook_addr` + when reacting to forge events instead of, or alongside, polling + (single-identity deployments only) - `[dispatch]` -- trigger (assignee/label/either), labels, ack reaction - `[[repos]]` -- owner, name, base branch, gate commands, protected paths, ecosystem @@ -371,8 +395,10 @@ nor do they change the four required scopes documented in **Implemented:** - Daemon poll loop, enqueue, claim, process +- Forge webhook intake as a feature-flagged alternative/backstop pairing to + polling (single-identity deployments; see `internal/forge/webhook`) - Bootstrap, implement, TDD, feasibility workflows -- GitHub forge (issues, PRs, labels, comments, reactions) +- GitHub and Gitea forges (issues, PRs, labels, comments, reactions) - Worktree isolation (clone, branch, commit, push, diff, cleanup) - SQLite store with transition audit - Config with ecosystem support (go, python, node, rust) @@ -383,7 +409,7 @@ nor do they change the four required scopes documented in **Planned:** -- Gitea forge implementation +- Multi-identity webhook intake (currently single-identity only) - More ecosystems - Notification integrations beyond n8n webhook - Skills (SKILL.md support -- see `.archie/skills/`) diff --git a/CLAUDE.md b/CLAUDE.md index 81fbd6502..226574d6a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -182,6 +182,19 @@ structures found in legacy packages. - **MCP Providers:** Daemon registers providers as optional via `providerRegistry.RegisterOptional`. Missing or failed providers log warnings and degrade health without terminating the process. +- **`internal/forge/webhook/` (forge webhook receiver):** +- Verify HMAC (`webhookguard.VerifyHMAC` against `X-Hub-Signature-256`) before + parsing the payload, never after -- an unverified body must not reach + `github.ParseWebHook`. +- Do not give the webhook-built `workintake.TaskEnvelope` a delivery-source- + specific idempotency key. `IdempotencyKey()` is keyed on `owner/repo/number` + only so a webhook-delivered issue and a later poll of the same issue dedup + against each other via `PublishUnique`; adding an event ID or timestamp to + the key defeats that and reintroduces poll/webhook double-dispatch. +- Webhook intake refuses to start when `[[identities]]` is configured (one + receiver, one dispatch config). Do not silently enable it for multi-identity + deployments without first building per-identity routing -- see + `ARCHITECTURE.md`'s "Webhook intake" section. ## Development Protocol diff --git a/docs/architecture/plugins-and-extensions.md b/docs/architecture/plugins-and-extensions.md index bfff80c18..b6696c3b9 100644 --- a/docs/architecture/plugins-and-extensions.md +++ b/docs/architecture/plugins-and-extensions.md @@ -41,6 +41,22 @@ A plugin: Plugins may be internally cohesive like small services. They do not become network services without a concrete security or operational reason. +## Event sources and reactions + +`archie-core-7d5u.1` asked whether extensions should react to events +in-process through typed capability families (this document's model) or +out-of-process like a generic `DispatchEvent` dispatcher. Decided 2026-08-22 +in `docs/prds/event-sources-and-reactions.md`: in-process typed families, +confirming this document's model rather than amending it. The forge webhook +receiver (`internal/forge/webhook`, see `ARCHITECTURE.md`'s "Webhook intake" +section) and the EDA playbook engine's Module action position +(`docs/prds/eda-playbook-engine.md`, `internal/domain/eda/module`) are the +shipped instances of that decision -- each is a narrow typed contract with an +owning registry, not a generic event hook. The playbook engine's Channel and +Forge action positions are designed but not yet implemented (open +investigation `archie-core-t2db.19`); when they land they follow the same +model, not a new one. + ## Curator surprisal sampling (deferred) **Deferred by decision, 2026-08-05** — Archie has no embedding capability, and