Files
archie/docs/prds/image-capability-contract.md
T

491 lines
34 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Image capability contract and configuration
**Status:** Approved
Epic: archie-core-1786748942120-1-6636e629 / GitHub #496 ("Image generation
capability: hosted API baseline plus local GPU workflows").
The contract and configuration (#497) shipped first and is settled — see
"Package: `internal/domain/image`" below. This document now covers the full
feature set: hosted provider (#498), local GPU provider (#499), `/image`
routing and clarification (#500), delivery through channels and web (#501).
Documentation (#502) and the cross-cutting test matrix (#503) are execution
work against the design below, not open design questions, so they are not
given their own sections — each preceding section states its own test
obligations inline.
## Problem
Archie needs a provider-neutral boundary for image generation/editing so a
hosted API (gpt-image-2-class) and a future local GPU backend can both
implement it without either one leaking into the domain contract. Nothing
in the repo defines this (`grep -ri image` over `internal/domain` and
`internal/config` returns nothing image-specific).
## Design
Follows the plugin engine family shape already established by
`internal/domain/curator` and `internal/domain/memory`
(`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`): a
typed contract with real domain operations,
an owning `Registry` (register/get/names, no start/stop lifecycle — see
below), and narrow host access via a `Registrar`.
### Package: `internal/domain/image`
**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are
long-running — they hold a background cadence or a persistent connection
worth health-checking. An image provider is call-scoped: it either serves a
`Generate`/`Edit` request or it does not. Health here means "is this
provider usable at call time", which is exactly what `Generate`/`Edit`
returning a typed `ErrUnavailable` already communicates — a separate
`Health()` poll would just duplicate that. `Registry` still owns
registration and lookup, so provider selection is testable with fakes per
the acceptance criteria, but there is no `Start`/`Stop` to orchestrate.
```go
// Capability declares what one provider supports, discoverable before a
// request is built so a caller can reject an unsupported combination (e.g.
// edit-with-mask on a generate-only provider) instead of sending it and
// parsing a provider-specific error back out.
type Capability struct {
Generate bool
Edit bool // edit requires at least one input image
Mask bool // edit supports a mask restricting the edited region
MaxInputs int // 0 = Edit unsupported
Sizes []string // provider-declared output sizes, e.g. "1024x1024"
}
// Provider is the typed contract every image backend implements — hosted
// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is
// call-scoped, not long-running (see design doc rationale).
type Provider interface {
Name() string
// Class distinguishes hosted (spends money/quota per call) from local
// (spends host GPU/time). Selection logic and config validation key off
// this, never off Name, so a new provider cannot silently slip through
// the hosted-cost gate under an unrecognized name.
Class() ProviderClass
Capability() Capability
Generate(ctx context.Context, req GenerateRequest) (Result, error)
Edit(ctx context.Context, req EditRequest) (Result, error)
}
type ProviderClass string
const (
ClassHosted ProviderClass = "hosted"
ClassLocal ProviderClass = "local"
)
```
Request/result types (provider-neutral, no OpenAI types):
```go
type GenerateRequest struct {
Prompt string
Size string // "" = provider default
N int // number of images; 0 = 1
Options map[string]string // provider-specific overflow (e.g. "quality"),
// deliberately untyped so the contract does not
// grow a field per provider
}
type EditRequest struct {
Prompt string
Inputs []ImageData // 1..Capability.MaxInputs
Mask *ImageData // nil unless Capability.Mask
Size string
N int
Options map[string]string
}
// ImageData carries image bytes in-process, never a path or URL: the
// domain layer must not assume a filesystem or a fetchable location (mirrors
// why curator's Registrar never receives *daemon.Daemon — no ambient host
// access smuggled in through a "just a string" field).
type ImageData struct {
Bytes []byte
MIMEType string
}
type Result struct {
Images []ImageData
Provider string
Model string
CreatedAt time.Time
}
```
### Error taxonomy
```go
var (
ErrUnavailable = errors.New("image provider unavailable") // missing credential, backend down
ErrUnsupported = errors.New("image capability unsupported by provider") // e.g. Edit on generate-only
ErrInputTooLarge = errors.New("image input exceeds configured limit")
ErrTimeout = errors.New("image request timed out")
ErrCanceled = errors.New("image request canceled")
)
```
Every provider wraps these with `fmt.Errorf("%w: %s", ErrX, detail)` so
callers can `errors.Is` regardless of backend. `ErrUnavailable` is the
explicit instruction from the epic: "a missing credential or unavailable
backend must make the capability unavailable with a useful user-facing
error, not prevent Archie from starting or break text chat" — Register
never rejects the daemon's boot, only marks that one provider absent from
`Registry.Names()`.
### Registry
```go
type Registry struct { /* map[string]Provider, mutex, sorted Names() */ }
func NewRegistry() *Registry
func (r *Registry) Register(p Provider) error // ErrDuplicate on name clash
func (r *Registry) Get(name string) (Provider, bool)
func (r *Registry) Names() []string
func (r *Registry) ByClass(class ProviderClass) []string
```
No `Registrar`/host-injection type: unlike curator (needs `LLM`, `Skills`,
`Conversations`) and memory (needs `Clock`, `Events`), an image provider's
dependencies (HTTP client, API key, local backend handle) are entirely its
own construction-time concern in `internal/infrastructure/image/*`, not
daemon services it needs injected. Introducing an empty `Registrar` now
would be exactly the "field nobody sets" pattern to avoid.
### Configuration
Follows `MinimaxConfig`'s hosted-cost-guard convention exactly: absent
config or absent explicit `enabled = true` per provider means that
provider does not register, not "registers but errors on first call".
```go
// ImageConfig configures the image generation capability.
type ImageConfig struct {
// Default selects which registered provider name /image uses when the
// request/session has not already picked one. Empty means /image must
// always ask (the epic's stated default UX) — an empty Default is valid
// and is not a misconfiguration.
Default string `toml:"default"`
Hosted map[string]ImageHostedProvider `toml:"hosted"` // keyed by provider name
Local map[string]ImageLocalProvider `toml:"local"` // keyed by recipe name
}
// ImageHostedProvider configures one hosted (paid) provider. Mirrors
// MinimaxConfig: Enabled defaults false, spending real credits requires an
// explicit opt-in, never an inferred one from the presence of a key alone.
type ImageHostedProvider struct {
Enabled bool `toml:"enabled"`
Class string `toml:"class"` // "openai" today; provider-neutral field name
APIKeyEnv string `toml:"api_key_env"`
APIKey secret.SecretRef `toml:"api_key" json:"-"`
BaseURL string `toml:"base_url"`
}
// ImageLocalProvider configures one local GPU recipe. Enabled defaults
// false too: a local backend can still saturate the host GPU/CPU, which is
// its own kind of unwanted cost, so it gets the same explicit gate as a
// hosted provider rather than an on-by-default WebFetch-style treatment.
type ImageLocalProvider struct {
Enabled bool `toml:"enabled"`
Backend string `toml:"backend"` // recipe identifier, defined by the local-backend bead
}
```
Validation (`internal/infrastructure/configuration/validate.go`, alongside
`validateMemory`):
- `Default`, if set, must name a provider present (enabled) in `Hosted` or
`Local` — rejects a config that silently falls back to "always ask" when
the operator thought they'd pinned one.
- A `Hosted` entry with `Enabled = true` must have `Class` non-empty and
either `APIKeyEnv` or a resolvable `APIKey` — the same shape check
`Provider` (chat) already gets, not a new invention.
- No cross-field surprise: an _absent_ `[image]` section is valid and
produces zero registered providers, matching the epic's non-goal
("silently selecting a paid hosted provider" must never happen by
omission either).
### Capability discovery
`Registry.Names()` / `ByClass()` plus `Provider.Capability()` give a caller
(the future `/image` routing bead) everything needed to ask "what can I
offer this user" without a type switch on provider identity — this is the
whole point of the contract being provider-neutral.
### Timeouts, size limits, cancellation
- Every `Provider.Generate`/`Edit` call takes the caller's `ctx`; a
provider that ignores cancellation is a provider bug, not a contract gap
— mirrors every other Lifecycle-less call in the codebase (chat's
`runtime.Chat`).
- `ImageData` size limits are enforced by the _caller_ (the future routing
bead) before constructing a request, using a configured max — not by this
contract, which has no config surface for "current caller's limit". This
package only defines `ErrInputTooLarge` so a provider that discovers an
oversized input itself (rather than trusting the caller) has a typed way
to say so.
## Testing
- `internal/domain/image/{contract,registry}_test.go` mirror memory's test
suite shape: registration (duplicate, nil provider), `Names`/`ByClass`
filtering, `Get` miss, table-driven `Capability` checks via a fake
provider.
- `internal/infrastructure/configuration/validate_test.go` gains cases for
`ImageConfig`: absent section, valid hosted+local, missing `Class`,
missing credential, `Default` naming an unregistered/disabled provider.
- No provider implementation exists yet, so no live-call tests — those
belong to the hosted/local provider beads.
## Hosted provider (#498)
`github.com/samcharles93/ai-sdk` (already a repo dependency) has its own
provider-agnostic image facility: `image.Provider` (`Name`,
`GenerateImage(ctx, GenerateImageRequest) (GenerateImageResponse, error)`),
`image.Client`, and `registry.Registry.RegisterImage`/`.Image(name)` — the
same shape chat model registration already uses. Three backends implement it
(azure, togetherai, xai); OpenAI does not.
`internal/infrastructure/image.<name>Provider` wraps an `ai-sdk/image.Provider`
behind this package's `Provider` interface, the same way `curatorLLMRunner`
(`internal/app/archied/main.go`) adapts `runtime.Runtime` for chat rather
than the domain layer talking to ai-sdk directly.
**Decision: generation goes through ai-sdk, edit does not.** ai-sdk's
`image.GenerateImageRequest` is text-to-image only — no input-image or mask
fields — so there is nothing to adapt `EditRequest`/`Capability.Edit` onto.
Blocking the entire hosted provider on an upstream ai-sdk change is not
this epic's call to make on someone else's project's timeline. Instead:
- `Generate` wraps `ai-sdk/image.Client.GenerateImage` against whichever
backend `ImageHostedProvider.Class` names (azure/togetherai/xai).
- `Edit` is a direct HTTP client hitting the OpenAI-compatible
`/images/edits` multipart endpoint, built the same way `minimax.Client`
(`internal/tools/minimax/minimax.go`) is a direct client for an API
ai-sdk doesn't cover — not a second abstraction layer, one `http.Client`
call with request/response mapping into this contract's `EditRequest`/
`Result`.
- A provider that only wraps ai-sdk (no edit client configured) declares
`Capability{Generate: true, Edit: false}` truthfully rather than
returning `ErrUnsupported` at call time for something `Capability`
already said it couldn't do.
- If ai-sdk gains edit support upstream later, the direct client is deleted
and `Edit` moves onto it — recorded here so that's a known, not a
surprise, follow-up.
**Provider error mapping** (every ai-sdk/HTTP error translated at the
adapter boundary, never leaked as-is):
| ai-sdk / HTTP condition | contract error |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `image.ErrNoProvider`, `image.ErrAuthFailed`, missing/invalid credential, backend unreachable | `ErrUnavailable` |
| `image.ErrEditNotSupported`, request needs a `Capability` the provider didn't declare | `ErrUnsupported` |
| input image over configured byte limit (checked before the call, per "Timeouts, size limits, cancellation" above) | `ErrInputTooLarge` |
| `ctx.Err() == context.DeadlineExceeded` | `ErrTimeout` |
| `ctx.Err() == context.Canceled` | `ErrCanceled` |
| `image.ErrRateLimited`, `image.ErrContentFiltered`, any other 4xx/5xx | wrapped verbatim under `ErrUnavailable` with the provider's own message as detail — a rate limit or content filter is "unavailable for this request", not a new sentinel the caller needs to branch on differently |
**Testing**: `httptest.Server` fixtures for the edit client (request
multipart shape, response decoding, 4xx/5xx mapping); a fake `ai-sdk/image.Provider`
for the generate path so the adapter's translation is tested without a live
backend, matching #498's "no live API key needed for tests" criterion.
## Local GPU provider (#499)
**Decision: ComfyUI is the baseline recipe**, not a name this doc picked
arbitrarily — it is the de facto scriptable HTTP API for Stable-Diffusion-class
local generation, already shaped like the async submit/poll pattern
`minimax.Client.GenerateAndWait` established in this codebase (submit a
workflow, poll `/history/{id}` until the output node has files, download).
No other local backend is referenced anywhere in this repo or its docs, so
this decision has no competing prior art to reconcile — it is a fresh
choice, recorded here so the implementing bead does not re-litigate it.
```go
// internal/infrastructure/image/comfyui
type Config struct {
Enabled bool
BaseURL string // e.g. http://127.0.0.1:8188
Workflow string // path to a saved ComfyUI workflow JSON template
// (prompt/size/seed substituted at call time)
Timeout time.Duration
PollInterval time.Duration
MaxWait time.Duration
}
```
- `Generate`/`Edit` load `Workflow`, substitute the templated fields (prompt,
size, seed, and for `Edit` the input image as a base64 node input — ComfyUI
supports img2img/inpaint workflows natively, so `Capability.Edit`/`Mask`
can both be true for a correctly authored workflow, unlike the hosted
provider), POST to `/prompt`, then poll `/history/{prompt_id}` the same
shape MiniMax's poll loop already proves out in this codebase.
- `Capability.Sizes` is empty (ComfyUI workflows declare their own
resolution in the template, not a fixed enum) — the contract already
allows an empty `Sizes` to mean "provider does not constrain size".
- Backend-down (`BaseURL` unreachable) and workflow-missing are both
`ErrUnavailable`, not a startup failure — same "degrade the capability,
never break text chat" rule the contract already states.
- Per #499's own acceptance criteria, at least one recipe must be exercised
end-to-end on real hardware or a reproducible harness, and no model
weights are ever committed or fetched by Archie itself — the operator
points `Workflow`/`BaseURL` at their own running ComfyUI instance and
already-downloaded checkpoint, exactly like `[providers.ollama]` points at
an already-running Ollama rather than Archie managing the model.
**Testing**: a fake HTTP server standing in for ComfyUI's `/prompt` and
`/history` endpoints (submit, poll, malformed history, timeout, job
not-found); a real-hardware smoke test documented as a manual `task`
target per #503, not part of `task check` — the same reasoning `task vuln`
and `task deadcode` are excluded from the gate.
## `/image` routing and clarification flow (#500)
**Call site: `internal/gateway/gateway.go`'s `Router`**, following the
`/model` shape exactly — `/model`, `/spawn`, `/approve` etc. are already
"commands handled without the LLM" (`Router.handleModel`, dispatched via
`isLocalCommand`/`parseCmd` against `messaging.LocalCommandSpecs()`).
`/image` is a new entry in `internal/domain/messaging/commands.go`'s
`localCommandSpecs`, and a new `Router.handleImage(ctx, arg)` beside
`handleModel`, gated on a new `Router.Images *image.Registry` field (nil =
"/image not configured", the same pattern `Models`/`Tasks`/`Controller`
already use — not a new gating convention).
**Decision: mechanism selection is per-request, not session-persisted.**
The epic allows "a remembered preference only where existing session/config
conventions support it" — and checking `Router`'s actual fields
(`ModelPersist`, `Identity`, the rest) shows there is no generic per-session
key/value store the neutral command path can lean on; `/model`'s own
`--session`/`--global` scoping lives entirely in
`internal/channels/telegram/model.go`, a Telegram-specific enrichment, not
something `Router` provides generically. Inventing a new generic
session-preference store just for `/image` would be exactly the kind of
scaffolding CLAUDE.md's Architectural Simplicity rule warns against for one
caller. So: every `/image` invocation with no explicit mechanism produces
the clarification prompt; an explicit `--hosted`/`--local` flag (mirroring
`parseModelRest`'s `--provider` flag shape) skips it for that one call.
Revisit if a second command wants session-scoped preference too — that's
the point at which shared infra earns its cost.
**Flow**, matching `handleModel`'s reply-string shape (no separate state
machine object, since the whole exchange is "ask once, use the answer
inline in the next message" — the model-selector's own worked example):
1. `/image <prompt>` with no `--hosted`/`--local` → reply lists the
registered classes (from `Registry.ByClass`) and asks the user to repeat
the command with `--hosted` or `--local`. No provider is called.
2. `/image --hosted <prompt>` or `--local` → resolves to
`Registry.ByClass(class)`, picks `ImageConfig.Default` if it names a
provider of that class, else the sole registered provider of that class,
else (more than one, no default) asks which named provider.
3. Edit requests (`/image --edit <prompt>` with an attached image on the
inbound message) validate against `Capability.Edit`/`MaxInputs`/`Mask`
before calling — an edit request to a generate-only provider is a
clarification reply ("this provider doesn't support editing"), not a
provider call that returns `ErrUnsupported`.
4. A successful call returns a `Result`; delivery is the next section's
concern, not this one's — `handleImage` returns the same
`(string, error)` shape `handleModel` does for the text portion, and a
separate mechanism (below) carries the actual image bytes.
**Testing**: channel-neutral state-machine tests for `handleImage` against
a fake `*image.Registry` (mirrors `#500`'s own acceptance criterion); Telegram
adapter tests only for wiring, not for re-testing the state machine.
## Delivery through channels and web (#501)
This is the smallest section because most of the delivery path **already
exists and is already proven** — by `generate_video`
(`internal/tools/minimax`), which ships. Do not rebuild it.
The existing pipeline: a result carrying media returns
`tools.MultimodalResult{IsMultimodal: true, URLs: []tools.MediaRef{{Type: "image", ...}}}`
→ `multimodalMediaRefs` (`internal/app/archied/telegram_setup.go`) decodes
it → `TurnStream.Media(gateway.MediaEvent)` → each channel's own
`Media`/`MediaAttachment` handling. `MediaRef.Type` already documents
`"image"` as a valid value alongside `"video"`; nothing in the pipeline is
video-specific.
**Per-channel state, checked directly rather than assumed:**
| channel | image delivery | evidence |
| ----------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Telegram | **already works** | `internal/channels/telegram/media.go`'s `telegramMediaSender.dispatch` already branches on `att.Type` and calls `bot.SendPhoto` for `"image"` (`SendVideo` for `"video"` is the same function) |
| Dashboard (webui) | **tracked gap, not new** | `internal/webui/api_chat.go`'s `chatStreamSink.Media` has no inline rendering path yet and degrades to a link/error string — already tracked as archie-core-1786748942243-6-f109697e. This epic does not need to fix it, but #501's acceptance criterion ("unsupported paths report a clear limitation") is already met by the existing degrade-to-text behaviour; closing the dashboard gap is that bead's job, not this one's |
| Email | **no attachment sender exists** | `grep MediaAttachment internal/channels/email` returns nothing. Out of scope for this epic per #496's non-goals (no channel-abstraction rework) — email delivery of a generated image degrades the same way the dashboard does which is acceptable under #501's "or unsupported paths report a clear limitation" clause |
| Webhook | not applicable | webhook is an inbound intake channel (`internal/channels/webhook`), not an outbound chat reply target — no `/image` command can originate there in the first place |
**The only new work `internal/tools/minimax` didn't already need**: the
autonomous-tool call site. `/image` (previous section) calls a provider
directly and does not go through the model's tool-calling loop at all.
Separately, exposing `generate_image`/`edit_image` as an ordinary tool
(so an agent task can generate a diagram or illustration mid-task, not only
a human typing `/image`) is a thin wrapper — `internal/tools/image/tool.go`,
same shape as `internal/tools/minimax/tool.go`, calling
`image.Registry.Get(name).Generate/Edit` and returning the identical
`MultimodalResult` shape. Wired in `bootstrap.go` next to
`registerMinimaxTool`, gated the same way (registered only when a provider
resolved a working credential/backend, never advertised broken). This
reuses the entire delivery pipeline above with zero new plumbing — the tool
call site is what's new, not the delivery.
**Testing**: `multimodalMediaRefs` already has coverage for the shape;
add a table case for `Type: "image"` if one doesn't already exist. The tool
wrapper gets the same fake-provider test shape as the routing flow above.
No new delivery-path tests are needed — that pipeline's tests belong to
whichever change originally proved it out.
## Call site inventory
Every file a full implementation touches, so no bead re-derives this by
grep:
| concern | file | change |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| domain contract | `internal/domain/image/{contract,registry}.go` | done (#497) |
| config schema + validation | `internal/infrastructure/configuration/{types,validate}.go` | done (#497); extended here only if ComfyUI's `Workflow` field needs a new validation rule (path exists, non-empty when `Local.Enabled`) |
| hosted provider | `internal/infrastructure/image/openai/*.go` (or per `Class`) | new (#498) |
| local provider | `internal/infrastructure/image/comfyui/*.go` | new (#499) |
| `/image` command spec | `internal/domain/messaging/commands.go` | new entry in `localCommandSpecs` |
| `/image` routing | `internal/gateway/gateway.go` (`Router.Images`, `handleImage`) | new (#500) |
| autonomous tool | `internal/tools/image/tool.go` | new (#501) |
| tool registration | `internal/app/archied/bootstrap.go` (`registerImageTool`, beside `registerMinimaxTool`) | new (#501) |
| `Registry` wiring | `internal/app/archied/bootstrap.go` (construct `image.Registry`, register configured providers, hand to `Router.Images`) | new — this is the "nothing to wire until a real provider exists" step the original contract doc deferred |
| Telegram delivery | `internal/channels/telegram/media.go` | none — already handles `"image"` |
| Dashboard delivery | `internal/webui/api_chat.go` | none in this epic — tracked separately (archie-core-1786748942243-6-f109697e) |
| docs | `docs/` user-facing guide (#502) | new, against this design |
## Execution: multi-agent team breakdown
Each row is independently implementable from its own section above plus the
call-site inventory — an implementer does not need this whole document
re-explained, only its row. Lenses are picked from
`.claude/workflows/council.js` (`boundary`, `contract`, `deletionist`,
`operator`, `maintainer`) by what each slice actually risks getting wrong,
not all five by default.
| sub-feature | issue | implementer scope (call-site rows) | suggested lenses | why |
| -------------------------- | ----- | ------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hosted provider | #498 | `internal/infrastructure/image/openai/*.go` (generate via ai-sdk, edit via direct HTTP client) | `lens-contract`, `lens-operator` | contract: the error-mapping table must actually produce the sentinels it claims, not leak ai-sdk/HTTP errors raw; operator: a live paid API's rate-limit/timeout/auth-failure paths are exactly the 3am-unattended-host case this lens exists for |
| Local GPU provider | #499 | `internal/infrastructure/image/comfyui/*.go` (submit/poll against ComfyUI) | `lens-operator`, `lens-deletionist` | operator: backend-down, workflow-missing, and stuck-job failure modes on a host the operator's GPU actually runs; deletionist: a second, unevidenced "recipe" added later without real-hardware proof is exactly the speculative scaffolding this lens rejects |
| `/image` routing | #500 | `internal/domain/messaging/commands.go`, `internal/gateway/gateway.go` (`Router.Images`, `handleImage`) | `lens-boundary`, `lens-maintainer` | boundary: a new `Router` field and its dependency on `image.Registry` must respect the same layering `Models`/`Tasks`/`Controller` already do; maintainer: this is the first local command with an explicit ask-once clarification exchange, not a single-shot reply — legibility for the next person who adds a command matters here |
| Delivery + autonomous tool | #501 | `internal/tools/image/tool.go`, `internal/app/archied/bootstrap.go` (`registerImageTool`) | `lens-deletionist`, `lens-contract` | deletionist: the whole point of this section is "reuse `generate_video`'s pipeline, do not rebuild it" — this lens is the check that the implementation actually did that; contract: the new tool's `MultimodalResult`/`MediaRef{Type: "image"}` output must match the shape `multimodalMediaRefs` already decodes, not a near-miss |
Run `/council --lenses <picked>` once a row's implementation is gate-clean
(`task check` passing), before opening its PR — same timing as any other
open-decision residue at the end of a session, not a standing per-commit
gate.
## File and link the beads
`#498`–`#501` already exist (bd `archie-core-1786748942169-3-ae7cfaea`,
`…-219-5-9844a72e`, `…-193-4-5072b564`, `…-243-6-f109697e`), filed under
epic #496 before this document's decisions were made. Each one's
description now links back to its matching section above instead of
restating it, and carries its row from the Execution table above so picking
it up needs no round-trip back to this document.