feat(docs): split the published set by audience, public and development
The site's sidebar held the landing page and one guide next to seventeen architecture records, the migration register, the review procedure and five PRDs. Nothing there is secret -- every development page may be read by anyone -- but a reader who wants to know what Archie is and how to point an event at it was meeting contributor material with no signal that it was not for them. One source tree now yields two sets: public (index, guides/) under /docs/, and development (architecture/, prds/) under /dev/, each with its own artifact and its own derived sidebar. archive/, inspiration/, news/ and the credential notes stay out of both, unchanged. Selective PRD publication is gone rather than carried over. It existed only because settled architecture cites PRDs and a link to a held-back target fails the generator, so five PRDs published to keep those citations alive; with both halves of every such citation in the development set, the exception has no work left to do. Both sets are generated in one pass over one url map, so a citation that crosses between them resolves to the base its target is served under, and the refusal now fires only for a target genuinely in neither set. Widening the set exposed a scanner bug worth its own note: the link regex matched `Resolve[T](i, src, exportPath)` inside a code span and refused the page for a link to `i,`. Code spans and fenced blocks are now skipped, because what a renderer draws as a link is the only thing this tool may rewrite or refuse a page for. docs/prds/public-and-dev-docs.md records the decision. Draft: the three choices in it are the maintainer's, the write-up is not yet reviewed.
This commit is contained in:
1 parent
59ffcdf229
commit
28e85758ae
8 files changed
+1187
-453
No files matched your search
+19
-16
@@ -132,20 +132,23 @@ tasks:
|
||||
- go -C tools run -mod=readonly ./newsgen check --repo-root ..
|
||||
|
||||
docs:artifact:
|
||||
desc: Regenerate the canonical public-docs artifact from the Markdown sources
|
||||
desc: Regenerate the canonical docs artifacts from the Markdown sources
|
||||
summary: |
|
||||
Writes docs/data/generated/docs.json: every published page's url, title,
|
||||
section and raw Markdown body, plus the sidebar tree derived from the
|
||||
layout. The JSON is the canonical, host-neutral fact set a renderer reads;
|
||||
the Markdown stays the source. MkDocs was the first renderer and the Astro
|
||||
app is the second, so the artifact is the product.
|
||||
Writes docs/data/generated/docs.json and dev-docs.json: every published
|
||||
page's url, title, section and raw Markdown body, plus the sidebar tree
|
||||
derived from the layout, one file per set. The JSON is the canonical,
|
||||
host-neutral fact set a renderer reads; the Markdown stays the source.
|
||||
MkDocs was the first renderer and the Astro app is the second, so the
|
||||
artifact is the product.
|
||||
|
||||
The published set lives in tools/docsite/main.go with the reasons for what
|
||||
is held back -- archive/, inspiration/, news/, most of prds/ and the
|
||||
credential notes -- because a renderer reading the artifact cannot see why
|
||||
a page is absent.
|
||||
Two sets, split by audience: the public set (served under /docs/) is what a
|
||||
reader of the product needs, the development set (/dev/) is architecture/
|
||||
and prds/. The split and the reasons for what is held back entirely --
|
||||
archive/, inspiration/, news/ and the credential notes -- live in
|
||||
tools/docsite/main.go, because a renderer reading an artifact cannot see
|
||||
why a page is absent from it.
|
||||
|
||||
The file is committed, so this dirties the tree deliberately: review the
|
||||
The files are committed, so this dirties the tree deliberately: review the
|
||||
diff and commit it with the page that produced it.
|
||||
|
||||
The artifact's keys are a frozen contract: an application is built against
|
||||
@@ -154,14 +157,14 @@ tasks:
|
||||
- go -C tools run -mod=readonly ./docsite --repo-root ..
|
||||
|
||||
docs:artifact:check:
|
||||
desc: Verify the committed public-docs artifact matches the Markdown sources
|
||||
desc: Verify the committed docs artifacts match the Markdown sources
|
||||
summary: |
|
||||
Reproduces the artifact in a temporary directory and fails when the
|
||||
committed file differs, without modifying the working tree. Runs in
|
||||
`task check`, so a page edit cannot land without its regeneration.
|
||||
Reproduces both artifacts in memory and fails when a committed file
|
||||
differs, without modifying the working tree. Runs in `task check`, so a
|
||||
page edit cannot land without its regeneration.
|
||||
|
||||
The generated directory is accounted for by docsgen's generatedArtifacts,
|
||||
which names this file alongside contracts.json: one registry for the
|
||||
which names both files alongside contracts.json: one registry for the
|
||||
directory rather than one per writer.
|
||||
cmds:
|
||||
- go -C tools run -mod=readonly ./docsite check --repo-root ..
|
||||
|
||||
@@ -141,6 +141,7 @@ docs/
|
||||
catalog.json
|
||||
contracts.json
|
||||
docs.json
|
||||
dev-docs.json
|
||||
cli.json
|
||||
configuration.json
|
||||
messaging.json
|
||||
@@ -347,8 +348,10 @@ go -C tools run -mod=readonly ./docsgen check --repo-root ..
|
||||
|
||||
`docsgen all` is still target-only: `docsgen data` and `docsgen asyncapi` do not
|
||||
exist. Two artifacts are generated today: `contracts.json` from the Go
|
||||
contract types (`docsgen`) and `docs.json` from the Markdown sources
|
||||
(`docsite`, the published set a renderer reads) -- see `task docs:artifact`.
|
||||
contract types (`docsgen`) and, from the Markdown sources, `docs.json` and
|
||||
`dev-docs.json` (`docsite`, one artifact per published set: the public set a
|
||||
reader of the product gets, and the development set of architecture and design
|
||||
records) -- see `task docs:artifact`.
|
||||
|
||||
### Step 9: CI
|
||||
|
||||
|
||||
@@ -0,0 +1,683 @@
|
||||
{
|
||||
"pages": [
|
||||
{
|
||||
"url": "/dev/architecture/",
|
||||
"title": "Architecture",
|
||||
"section": "Architecture",
|
||||
"body": "# Architecture\n\nArchie is a personal agent platform built around six domain boundaries:\n\n- Identity tracks users and other actors responsible for actions.\n- Agent owns persistent assistants, specialisation, and continuity.\n- Messaging owns conversations, messages, branches, and channel correlation.\n- Workflow owns reusable, versioned behaviour definitions and their executions.\n- Work Intake admits optional durable work without constraining ordinary agent\n conversation or direct capability use.\n- Plugin owns generic extension discovery and lifecycle; each capability family\n owns its typed plugin contract.\n\nThe detailed architecture and migration decisions are maintained under\n`docs/architecture/` in the repository while this generated site is being\nassembled.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/adversarial-review/",
|
||||
"title": "Adversarial self-review",
|
||||
"section": "Architecture",
|
||||
"body": "# Adversarial self-review\n\nArchie runs a fresh adversarial review of the diff before it opens a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## Operator-triggered review\n\nThe same reviewer runs against an *existing* PR via the channel-neutral\n`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated\nreviewer, and return the structured findings. Authorization is identity-scoped\nto the operator's configured repositories; duplicate or concurrent reviews of\nthe same PR are deduplicated.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/agent-system/",
|
||||
"title": "Agent System",
|
||||
"section": "Architecture",
|
||||
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorized Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalization boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorizing explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/bindings/",
|
||||
"title": "Playbook bindings: model and threat model",
|
||||
"section": "Architecture",
|
||||
"body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the `ARCHITECTURE.md` task-lifecycle\naddendum or the operator walkthrough -- those remain separate, open pieces of\nthe same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // draft | pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (SQLite), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\n`Matcher.Source` is the only predicate today: the path segment a sender\nPOSTs to (e.g. a webhook hitting `.../sentry` matches bindings with\n`Matcher.Source == \"sentry\"`). The storage column is plain `TEXT`, so adding\npredicates later is non-breaking -- extend `Matcher`, don't invent a second\nmatcher shape.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. This\nis schema-by-example in practice: a mapping is authored by pointing at a\nreal captured payload in the dashboard, not by guessing a schema in advance.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ndraft ---\u003e pending_approval ---\u003e armed\n ^ ^ |\n | | |\n +--------------+-----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nModeled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); `draft` and `pending_approval` bindings are inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captured_events.authenticated` is a real column (`internal/store/\n captures.go`), set at capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose source has at least one armed binding** -- an\n unauthenticated capture is never even considered for dispatch.\n\n### 2. Human approval before a binding goes live\n\nCovered by the state machine above. Nothing self-arms: `pending_approval -\u003e\narmed` requires an explicit `Approve` call, and any edit to an armed\nbinding reverts it.\n\n### 3. Rate and volume limits per source\n\nCapture writes are bounded independently of the approval gate, so a flood\nof unauthenticated traffic cannot exhaust disk or drown the inspector:\n`InsertCapture` (`internal/store/captures.go`) prunes by both **retention\nwindow** (`WHERE received_Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/configuration/",
|
||||
"title": "Configuration",
|
||||
"section": "Architecture",
|
||||
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognized filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nindexing settings, provider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot chaLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/dependencies-and-contracts/",
|
||||
"title": "Dependencies and Contracts",
|
||||
"section": "Architecture",
|
||||
"body": "# Dependencies and Contracts\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Dependency direction\n\n```text\ndomain and shared application contracts \u003c- infrastructure implementations\n ^\n |\n application composition\n```\n\nThe following rules are strict:\n\n1. Domains MUST NOT import `internal/infrastructure`.\n2. A domain defines the smallest interfaces required to perform its work.\n3. Infrastructure implements those interfaces and translates external\n representations at the boundary.\n4. Only application composition chooses concrete implementations.\n5. A domain MUST NOT manipulate another domain's state or call its internal\n services.\n6. Cross-domain work uses an explicitly designed command, event, or approved\n shared contract.\n7. Implementation difficulty is not permission to violate a boundary.\n\nBroker messages, database rows, SDK response types, and configuration DTOs MUST\nNOT leak into domain models.\n\n## Commands and events\n\n- An event records something that happened and is owned by its publishing\n domain.\n- A command requests an action and is owned by the domain expected to handle it.\n- Consumers do not redefine an event's meaning.\n- Senders obey the receiving domain's command contract.\n- There is no generic package containing unrelated application messages.\n\n## Event bus\n\n`internal/eventbus` is an approved shared application contract. It defines only\nthe messaging behaviour Archie requires, including publication, subscription,\ndelivery outcomes, and required lifecycle semantics.\n\nIt MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer\ngroups, acknowledgements, reconnection, and serialization belong under\n`internal/infrastructure/eventbus/nats` unless Archie explicitly requires a\nsemantic guarantee in the shared contract.\n\nMessage schemas stay with their owning domains. The event bus transports\nmessages; it does not own their meaning.\n\n## Wire contracts and generation\n\nCanonical worker and service wire contracts and their authoritative generation\ninputs are owned by the domain or capability that defines their meaning. They\nMUST NOT be centralized in `internal/infrastructure/spec` or another generic\nschema package.\n\nInfrastructure owns:\n\n- generic contract-generation machinery;\n- transport-specific adapters and generated implementations;\n- RPC, REST, NATS, and other external encoding and delivery concerns.\n\nFor example, agent-worker requests and results belong to task execution.\nSubprocess, NATS, or HTTP representations are infrastructure implementations of\nthat contract. The same rule applies independently to forge, persistence,\nworkspace, and other service contracts.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/generated-documentation/",
|
||||
"title": "Generated Documentation",
|
||||
"section": "Architecture",
|
||||
"body": "# Generated Documentation\n\n**Status:** Generator scaffold in place; renderer and publishing removed\n**Date:** 2026-07-28 (revised 2026-09-12)\n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie's documentation-generation approach is:\n\n- production Go code, registries, configuration, and CLI behaviour remain the\n source of truth for published contracts;\n- a repository-local Go generator extracts and normalizes documentation data;\n- the generator writes deterministic JSON/data files and protocol schemas;\n- the rendering and publishing surface is an **open decision** — the VitePress\n site and its Pages deployment were removed on 2026-09-12 as an unnecessary\n build step (see \"Rendering and publishing\" below).\n\nHugo is not part of the target architecture.\n\nThe documentation system is rooted at:\n\n```text\ntools/\n go.mod\n go.sum\n docsgen/\n main.go\ndocs/\n data/generated/\n public/schemas/\n *.md\n```\n\n### Rendering and publishing — OPEN\n\nSuperseded 2026-09-12. The repository previously carried a VitePress site\n(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line\n`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub\nPages by `.github/workflows/docs.yml`. It was removed as an unnecessary build\nstep: the published site was never stood up, and the Pages target is not\nconfigured.\n\n`docs/` is now repository documentation only — markdown read in the repository,\nan editor, or a forge's file view. Nothing in the repository builds, renders, or\npublishes it.\n\nThe renderer for the generated `data/generated/*.json` is therefore **undecided**.\nConsequences that follow, and their current state:\n\n| Concern | State after removal |\n| --- | --- |\n| Reference-page rendering | Undecided; `data/generated/contracts.json` is committed but unrendered |\n| Internal link validation | Not enforced by any build; links are repository-relative (`../architecture/...`) and resolve on the filesystem |\n| Generated-data drift detection | Unchanged — `docsgen check` compares committed output, independent of any renderer |\n| Navigation/sidebar | The authoritative index is `docs/prds/01-project-management.md` |\n| Local authoring server | None; read markdown directly |\n\nA future renderer MUST NOT reintroduce a dead-link-blind build: VitePress\npreviously validated internal links during its production build, and no\nreplacement currently does.\n\n## Single source of truth\n\nEvery published capability has one authoritative machine-readable definition\nowned by its domain or application boundary. Generated documentation derives\nfrom those definitions.\n\nGenerated reference includes:\n\n- domain commands and events;\n- Messages and typed message content;\n- Agent and Workflow contracts;\n- WorkflowSteps and Workflow plugin capability contracts;\n- policies and their typed inputs and outcomes;\n- tools and capabilities;\n- CLI commands, arguments, flags, defaults, and help;\n- runtime settings, types, defaults, validation, and secret metadata;\n- public worker and transport contracts;\n- indexes of registered functionality;\n- deprecation information.\n\nHandwritten documents contain:\n\n- architecture decisions and rationale;\n- tutorials and operational guides;\n- examples and walkthroughs;\n- migration guidance;\n- conceptual explanations.\n\nHandwritten documents link to generated reference rather than copying\nauthoritative tables.\n\n## Target generation architecture\n\n`tools/docsgen` is Archie's documentation extractor and normalizer. It produces\nstructured documentation data and protocol specifications. It does not own\npage layout and MUST NOT generate Markdown pages or fragments.\n\nThe generator is divided internally into reusable stages:\n\n```text\nload registries and types\n -\u003e normalize documentation model\n -\u003e validate ownership and identifiers\n -\u003e serialize data and protocol artifacts\n -\u003e compare or write output\n```\n\nThe normalized documentation model prevents each output renderer from\nindependently interpreting Go types. It contains stable documentation IDs,\nowners, names, descriptions, source references, versions, deprecations, fields,\ndefaults, validation, secret classifications, and relationships.\n\nInitial generator targets:\n\n```text\ndocsgen data\ndocsgen asyncapi\ndocsgen all\ndocsgen check\n```\n\n- `data` writes the normalized JSON reference data.\n- `asyncapi` writes protocol schemas and envelopes.\n- `all` generates every committed artifact.\n- `check` generates into a temporary directory and fails on drift.\n\nThe command may use subcommands or an equivalent explicit `--target` flag. It\nMUST retain one normalization and validation path.\n\n## Target output\n\nDuring adaptation, `docs` remains the staging site. Generated outputs live in\na visibly owned subtree:\n\n```text\ndocs/\n data/\n generated/\n cataloLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/identity/",
|
||||
"title": "Identity",
|
||||
"section": "Architecture",
|
||||
"body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry; the older `token_env` field remains a compatibility fallback. Neither\nform changes the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active ideLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/messaging-and-work-intake/",
|
||||
"title": "Messaging and Work Intake",
|
||||
"section": "Architecture",
|
||||
"body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorized user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable SQLite round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletions,Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/migration-decisions/",
|
||||
"title": "Architecture Migration Decisions",
|
||||
"section": "Architecture",
|
||||
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/observability/",
|
||||
"title": "Task Observability",
|
||||
"section": "Architecture",
|
||||
"body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — *\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"* — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see *why*\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and pLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/organisation/",
|
||||
"title": "Repository Organisation",
|
||||
"section": "Architecture",
|
||||
"body": "# Repository Organisation\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Target structure\n\nArchie MUST be organised around cohesive application responsibilities:\n\n```tree\ncmd/\n archied/\n archie-agent/\n\ninternal/\n domain/\n \u003carea\u003e/\n eventbus/\n policy/\n infrastructure/\n configuration/\n eventbus/\n nats/\n forge/\n persistence/\n \u003cexternal-service\u003e/\n app/\n archied/\n agentworker/\n\nplugins/\n \u003cplugin\u003e/\ndeployments/\n \u003csupported-assembly\u003e/\ndocs/\n guides/\nexamples/\n \u003ccopyable-example\u003e/\nextras/\n \u003coptional-extension\u003e/\n```\n\nDomain names are chosen from application behaviour during package review.\nExisting names MUST NOT be retained merely to reduce migration work.\n\n## Domain areas\n\nA domain owns one cohesive job performed by Archie. It contains that job's\nlanguage, state, rules, operations, commands, events, policy implementations,\nruntime settings, and required service contracts.\n\nCode that changes together SHOULD live together. Empty or ceremonial `entities`,\n`repositories`, or `services` layers are prohibited.\n\n## Application composition\n\n`internal/app`:\n\n- constructs domains and infrastructure implementations;\n- translates external configuration into domain and plugin settings;\n- connects commands, events, and shared contracts;\n- starts services in dependency order;\n- owns health aggregation and shutdown ordering.\n\n`cmd/*` parses only process-level input and invokes the relevant application\ncomposition package. It MUST NOT contain substantive wiring or act as a service\nlocator.\n\n## Process boundaries\n\nArchie begins as a modular monolith even when capabilities run in separate\nprocesses. A domain becomes a separately deployed service only for a concrete\nneed such as security isolation, independent scaling, failure containment, or\nindependent operation.\n\nPossible future extraction does not justify premature network protocols or\nduplicated service scaffolding.\n\nA new command is not a reason for a new binary. `cmd/` entries are process\nboundaries: a binary earns its place when its surface fails independently of the\nfleet, or when one process may need to run in more than one location, such as a\nhigh-availability pair or across a NAT boundary. Operational commands over a\nsurface an existing binary already owns are subcommands of that binary. Offline\ndatabase maintenance belongs to `archie-state-store`, which owns the file and\nits path layout, not to a new recovery binary.\n\n## Optional and operational material\n\n- `extras/\u003cextension\u003e` contains a maintained optional extension with real\n behaviour. Core Archie MUST NOT import it, and removing `extras/` MUST NOT\n prevent the core application from building or running.\n- `deployments/\u003cassembly\u003e` contains a supported assembly, including deployment\n definitions and concise operational instructions.\n- `docs/guides/` contains handwritten explanation and links to generated\n reference material.\n- `examples/` contains copyable samples with explicit purpose, prerequisites,\n and support expectations.\n\nSupported assemblies SHOULD demonstrate that capabilities can be selected\nindependently.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/package-review/",
|
||||
"title": "Domain and Feature Review Procedure",
|
||||
"section": "Architecture",
|
||||
"body": "# Domain and Feature Review Procedure\n\n**Status:** Active \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchitecture work proceeds one domain or feature at a time. Before any design\nquestion, the selected area is researched across its complete live\nimplementation, consumers, tests, state, configuration, and runtime wiring.\n\nExisting packages are evidence, not the unit that drives the interview.\nPlacement follows behaviour and ownership, not the existing directory name.\n\nNo restructuring implementation begins until the relevant package decisions\nare agreed and recorded in the focused domain or requirement document.\n\n## Required research\n\nBefore design questions, the current-state report MUST identify:\n\n- entry points and runtime composition;\n- state, persistence, and lifecycle;\n- public and internal contracts;\n- commands, events, and policy enforcement;\n- configuration and defaults;\n- all consumers and cross-domain interactions;\n- process and infrastructure boundaries;\n- tests, failure behaviour, and known invariants;\n- duplicated or conflicting implementations;\n- documentation that disagrees with live code.\n\nDiscoverable facts MUST be investigated rather than presented to the user as\ndesign questions.\n\n## Required decisions\n\nEach package review records:\n\n| Decision | Required result |\n|---|---|\n| Owned behaviour | The cohesive job the code performs |\n| Domain ownership | The owner of the behaviour and vocabulary |\n| Final location | Its target path |\n| Public contracts | The smallest interfaces, commands, and events exposed |\n| Required services | Domain-defined interfaces implemented by infrastructure |\n| State ownership | The owner of each mutable record and transition |\n| Dependencies | Allowed imports and dependencies to remove |\n| Duplication | Code to consolidate, delete, or keep separate |\n| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |\n| Process boundary | In-process, or the concrete reason for isolation |\n| Configuration | Settings owned by the domain or plugin |\n| Policy | Definitions, evaluators, consequences, and shared mechanics used |\n| Documentation | Authoritative definitions and generated reference |\n| Migration constraints | Behaviour and data that must remain correct |\n\n## Interview method\n\nFor every selected domain or feature:\n\n1. Declare the single area under review.\n2. Complete the current-state research.\n3. Explain actual behaviour in plain technical language.\n4. Separate facts from design decisions and concerns.\n5. Resolve obvious consequences directly and ask only questions whose answer\n materially changes behaviour or structure.\n6. Record each confirmed decision in its focused document.\n7. Complete that area's handoff before selecting another.\n8. Keep unrelated domains outside the implementation scope.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/plugins-and-extensions/",
|
||||
"title": "Plugins and Extensions",
|
||||
"section": "Architecture",
|
||||
"body": "# Plugins and Extensions\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Plugin framework\n\nThe core plugin domain lives under `internal/domain/plugin`. It owns:\n\n- plugin identity and metadata;\n- discovery and registration contracts;\n- lifecycle rules;\n- capability registration;\n- validation and compatibility rules.\n\nThe generic plugin contract remains metadata-only. Functionality is exposed\nthrough narrow typed capability contracts with an owning registry or manager.\n\nWorkflow plugins belong to the Workflow capability family. The Workflow domain\nat `internal/domain/workflow` owns their typed registration, validation,\nversioning, definition, and execution contracts. The generic plugin domain may\nprovide plugin identity, discovery, compatibility, and lifecycle mechanics, but\nit MUST NOT define Workflow semantics or expose untyped Workflow hooks.\n\n## Plugin implementations\n\nFirst-party plugins are self-contained vertical modules under\n`plugins/\u003cplugin\u003e`.\n\nA plugin:\n\n- owns its implementation, settings, templates, assets, and tests;\n- receives only explicitly supplied contracts and services;\n- MUST NOT receive daemon internals, a service locator, or unrestricted\n application access;\n- MUST NOT import arbitrary infrastructure or application composition code;\n- MAY use approved domain and shared application contracts;\n- MUST remain removable without changes to unrelated domains.\n\nPlugins may be internally cohesive like small services. They do not become\nnetwork services without a concrete security or operational reason.\n\n## Event sources and reactions\n\n`archie-core-7d5u.1` asked whether extensions should react to events\nin-process through typed capability families (this document's model) or\nout-of-process like a generic `DispatchEvent` dispatcher. Decided 2026-08-22\nin `docs/prds/event-sources-and-reactions.md`: in-process typed families,\nconfirming this document's model rather than amending it. The forge webhook\nreceiver (`internal/forge/webhook`, see `ARCHITECTURE.md`'s \"Webhook intake\"\nsection) and the EDA playbook engine's Module action position\n(`docs/prds/eda-playbook-engine.md`, `internal/domain/eda/module`) are the\nshipped instances of that decision -- each is a narrow typed contract with an\nowning registry, not a generic event hook. The playbook engine's Channel and\nForge action positions are designed but not yet implemented (open\ninvestigation `archie-core-t2db.19`); when they land they follow the same\nmodel, not a new one.\n\n## Curator surprisal sampling\n\n**Decided 2026-08-05, wave 1 landed 2026-09-05** — the curator engine family\n(epic [#435](https://github.com/samcharles93/archie-core/issues/435)) selects which memories deserve agentic attention via\nsurprisal-based sampling: score memories by how surprising they are and\nspend the sampled reasoner's agentic budget on the most surprising items.\n\nThe prerequisites are built: the embeddings capability\n([#436](https://github.com/samcharles93/archie-core/issues/436), `internal/domain/embedding` contract +\n`internal/infrastructure/embedding` implementation, config-driven via\n`models.embedding`) and the wave-1 `Sampler` strategy seam\n(`internal/domain/sampling` -- not `internal/curator`, see\n`docs/prds/curator-sampler-wave1.md` for the settled design and tracking)\nwith four\ncheap, embedding-free strategies (recency, random, all, staleness proxy).\nNo curator consumes a `Sampler` yet, and the embeddings client is likewise\ndeliberately inert: `setupEmbeddings` constructs it at boot and holds it on\n`b.embeddings`, but no production code reads that field yet, so a resolved\n`models.embedding` role currently produces a client whose only observable\neffect is a boot log line. Both are prerequisites waiting on #437, not\nunwired defects.\n\nStill deferred: [#437](https://github.com/samcharles93/archie-core/issues/437), the embedding-backed surprisal strategy, which\ndepends on the above and on [#407](https://github.com/samcharles93/archie-core/issues/407). Requirements for that deferred work,\nso it can be picked up without re-deriving the design:\n\n- A `Sampler` implementation behind the same interface as the cheap\n strategies; selection deterministic given fixed inputs.\n- Algorithm: sample up to a candidate cap; build a k-NN graph over embedding\n vectors; row-normalize the adjacency with self-loops; power-iterate to the\n stationary distribution; surprisal = −log(stationary probability of the\n nearest point); select the highest-surprisal items.\n- Degradation: content without an embedding is skipped; an embedding failure\n aborts sampling and falls back to free exploration — a sampling failure\n must never fail or crash a curator pass.\n- Cost bound: the graph build is quadratic in the candidate cap; the cap must\n be a named constant with a documentLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/policy/",
|
||||
"title": "Policy System",
|
||||
"section": "Architecture",
|
||||
"body": "# Policy System\n\n**Status:** Approved foundation; exact API is deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nRetry limits, authorization, gates, commands, protected paths, tool\navailability, and similar rules define or constrain what Archie may do. They\nneed consistent consumption, composition, evidence, and audit without erasing\ntheir different domain meanings.\n\n## Ownership\n\n`internal/policy` is an explicitly approved shared application contract. It is\nnot infrastructure and it is not a generic domain that owns every rule.\n\nThe shared policy system owns:\n\n- policy identity, version, scope, and applicability;\n- typed evaluation invocation;\n- deterministic composition and precedence;\n- common evaluation states such as satisfied, violated, indeterminate, and not\n applicable;\n- reasons and evidence;\n- evaluation audit records;\n- registration, discovery, and lifecycle.\n\nEach consuming domain owns:\n\n- its policy vocabulary and typed inputs;\n- its concrete policy definitions;\n- its evaluators;\n- the meaning and consequence of an evaluation.\n\nAccess therefore owns principals, resources, actions, and authorization\nconsequences. Task lifecycle owns retry eligibility and exhaustion. Task\nexecution owns gate requirements. Workspace mutation owns protected-path\neffects. Tool execution owns tool and command constraints.\n\nThese policies use consistent evaluation mechanics without pretending their\ndecisions are semantically interchangeable.\n\n## Infrastructure\n\nInfrastructure MAY load, persist, distribute, and audit external policy\nrepresentations. It MUST NOT define what Archie allows or assign the meaning of\na domain policy result.\n\nThe exact Go API, composition operators, precedence rules, and representation\nformat require a focused policy design pass.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/safe-change-and-recovery/",
|
||||
"title": "Safe Change and Recovery",
|
||||
"section": "Architecture",
|
||||
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in `archie.db`.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure | Boot behaviour | Where the operator sees it |\n| --- | --- | --- |\n| State Store uLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/01-project-management/",
|
||||
"title": "Architecture Decision Index",
|
||||
"section": "PRDs",
|
||||
"body": "# Architecture Decision Index\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Beads issue:** `archie-core-5d7`\n\n## Purpose\n\nThis file is the navigation point for Archie's target architecture. It is\ndeliberately short. Architectural decisions are separated by domain or\nrequirement so an implementation task can load only the rules governing its\nscope.\n\nImplementers MUST read the decision document for the domain or requirement they\nare changing. They MUST NOT infer permission to change neighbouring domains from\na broader restructuring objective.\n\n## Global invariants\n\n- Organise code around cohesive application responsibilities, not generic\n technical mechanisms.\n- Domains own their behaviour, vocabulary, state, commands, events, policy\n implementations, runtime settings, and required service contracts.\n- Domains do not depend on infrastructure or manipulate another domain.\n- `internal/app` owns composition; `cmd/*` remains thin.\n- Cross-domain work uses an explicitly owned command, event, or approved shared\n contract.\n- Process boundaries are deployment choices and do not determine source-code\n ownership.\n- Existing package names and boundaries have no presumption of survival.\n\nThe words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.\n\n## Decision documents\n\n| Scope | Authoritative document |\n| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](/dev/architecture/organisation/) |\n| Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](/dev/architecture/dependencies-and-contracts/) |\n| External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](/dev/architecture/configuration/) |\n| Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](/dev/architecture/identity/) |\n| Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](/dev/architecture/agent-system/) |\n| Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](/dev/architecture/messaging-and-work-intake/) |\n| Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](/dev/architecture/policy/) |\n| Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/) |\n| Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](/dev/architecture/plugins-and-extensions/) |\n| Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](/dev/architecture/generated-documentation/) |\n| Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](/dev/architecture/migration-decisions/) |\n| Domain/feature research, design interview, and required handoff | [architecture/package-review.md](/dev/architecture/package-review/) |\n\n## Deferred decisions\n\nThe remaining package-placement, data-migration, shared-mechanics, process-\nboundary, and cutover decisions are maintained in\n[architecture/migration-decisions.md](/dev/architecture/migration-decisions/).\n\nEach decision is made in its focused document after code-grounded review.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/RULES/",
|
||||
"title": "PRD writing rules",
|
||||
"section": "PRDs",
|
||||
"body": "# PRD writing rules\n\nThese rules apply to every file in `docs/prds/`.\n\n- Search existing PRDs, issues, architecture records, and code first. Do not ask\n the maintainer to repeat recorded requirements.\n- A newer maintainer decision overrides an older design. Mark the old design as\n superseded instead of preserving or defending it.\n- Write plain English. Use a technical term only when the reader needs that\n exact contract or concept.\n- Use the shortest direct sentence. Write “When upgraded, existing instances\n are migrated to the database,” not a description of an importer seeding\n absent resources.\n- State each fact once. Do not repeat a heading, summarize a list before showing\n it, or restate a decision afterward.\n- Every sentence must add a decision, requirement, constraint, evidence, or\n verification step. Delete narration and explanations of obvious text.\n- Do not turn a requested outcome into extra product features. Keep inferences\n open until the maintainer or repository evidence settles them.\n- Do not create a process for a logical boundary. Add one only when it must\n deploy, scale, start, secure, or fail separately.\n- Describe working behavior, not explanatory UI around missing behavior. State\n what users can do and how success is proved.\n- Before approval, use independent read-only reviewers to check a cross-cutting\n PRD for missing behavior and exaggerated claims. Verify and synthesize their\n findings; do not copy their prose.\n- Before requesting approval, review every sentence for complexity, repetition,\n and unsupported scope.\n- Write nothing whose truth expires. No `file.go:123` citations (cite the file\n and the symbol), no progress reports on the work being designed, no dated\n status claims, and no record of how a finding was produced. A phased plan is\n durable design; which phase is finished is not. Do not refer to what this\n document used to say: the reader cannot see it. A supersede marker is fine\n when it names a file, a section or a symbol they can find. `task docs:prds`\n enforces this.\n- Every PRD carries one of three statuses, and nothing else in that field.\n `Draft` until the maintainer explicitly approves it, `Approved` once they\n have and while the work is being built, `Finalised` when the work is\n complete. A finalised PRD does not change; supersede it with a new one\n instead. A revision number belongs in `**Revision:**`, a pointer to the\n authoritative document in `**Authority:**`, and what a past revision changed\n belongs in git.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/adversarial-self-review/",
|
||||
"title": "Adversarial self-review stage -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Adversarial self-review stage -- decision\n\n**Status:** Finalised\n**Authority:** `docs/architecture/adversarial-review.md` describes the stage and is authoritative. This PRD remains the design-decision record.\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`\n\n\u003e **Section 1 is superseded by the decision below.**\n\u003e The original execution mechanism assumed daemon-owned in-process execution\n\u003e and a daemon-side second `Pool.Acquire`; `archie-core-q15y` removed both\n\u003e call sites, leaving one open question: how a fresh reviewer receives an\n\u003e isolated snapshot from inside the task-scoped worker, without a host\n\u003e executor or a nested container lifecycle. Section 1 below now answers it\n\u003e with `agent.Subagent`. Sections 2-5 were never invalidated and still hold;\n\u003e section 3's contract shipped as `archie-core-h019.2`.\n\nAnswers the five questions in `h019.1`'s description against the actual\nimplement workflow, not designed from scratch: the gate pattern, the\ncontainer pool, and the workflow engine's `Outcome` mechanism already answer\nmost of this.\n\n## 1. Where it runs: `agent.Subagent`, inside the task worker\n\nThe implement workflow's stage list\n(`internal/domain/workflow/implement.go`) already has the right slot:\nafter `StageDiffCap()`, before `StageOpenPR()` -- gates\nhave passed, the diff is final, and nothing has told the forge about this\nchange yet.\n\n**The reviewer is an `agent.Subagent` run, not a second container.** ai-sdk\n`v0.1.22` (already the pinned version) added `agent/subagent.go`: a nested,\nsynchronous `core.GenerateText` call in the same process, with its own model,\nsystem prompt, toolset and step budget. That is what makes this feature\nbuildable at all after `q15y` -- the reviewer runs inside the task-scoped\n`archie-agent` worker that is already executing the workflow, so there is no\nhost executor, no second `Pool.Acquire`, and no nested container lifecycle.\n\n**Two isolations are needed, and Subagent only provides one of them.**\n\n*Conversation isolation is structural, and free.* `Subagent.Run`\n(`agent/subagent.go`) calls `GenerateText` with `Prompt` set and\n`Messages` never populated. The implementer's history has no code path into\nthe nested run; only the prompt string crosses, and only text comes back.\nThis is the literal form of \"environmental enforcement over prompt rules\":\nthe reviewer is not told to ignore the implementer's reasoning, because\nnothing hands it any. `h019.3`'s required test asserts this as a construction\nfact.\n\n*Workspace isolation is still ours to build.* A sub-agent shares the parent's\nprocess, working directory and credentials. So the `.git`-free snapshot from\nthe original decision survives unchanged and is load-bearing: export the\nreviewed commit (`git archive \u003ccommit\u003e | tar -x`) into a fresh scratch\ndirectory beside, not inside, the task worktree, and write `diff.patch` (the\ndiff already computed for `StageYaegiGate`'s `Trees.Diff()`) and `issue.md`\n(the originating issue's title and body, nothing else) alongside it. Stripping\n`.git` is what makes commit messages, branch name and reflog -- the actual\nchannel a multi-commit implementer's reasoning leaks through -- structurally\nunreachable rather than merely undisclosed.\n\n`Subagent.Tools` therefore takes a **distinct read-only toolset rooted at the\nsnapshot**. Never the worker's own toolset: it carries the `worktreerpc`\npublication grant, so a reviewer holding it could push the branch it exists to\nblock.\n\n**Call `Run()`, not `Tool()`.** `Tool()` would register delegation as a tool\nthe *implementer's* model may choose to invoke -- self-certification by the\nimplementer, which is the exact failure this feature exists to prevent. The\nstage calls `Run()` unconditionally. That also sidesteps both of `Tool()`'s\ndocumented footguns: the parent's two-step minimum and the recursion risk of\npassing a toolset back to itself.\n\n**Findings return through a closure, not the return value.** `Run` yields only\nfinal text, so section 3's structured contract cannot ride the return. Because\nthe sub-agent is in-process, the capture tool's Go implementation appends\ndirectly to a `[]workflow.ReviewFinding` the stage owns. This preserves the\n\"cannot end its turn without calling a typed tool\" property, and it defeats\n`Subagent`'s documented \"no partial results on failure\" limitation: findings\nalready captured survive an error return, so **the stage reads the captured\nslice even when `Run` returns an error**. A reviewer that logged three defects\nand then hit its step limit still yields those three.\n\n## 2. What it's given, and what it must never be given\n\n**Given:** the clean file-content snapshot (so the reviewer can read whole\nfiles -- follow an import, check interface satisfaction, see a call site --\nnot just diff hunks, which the manual-read checklist in CLAUDE.md rLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/binding-secret-encryption/",
|
||||
"title": "Binding secret at-rest encryption -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Binding secret at-rest encryption -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db`\n\n## Problem\n\n`binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as\nplaintext in the `bindings.secret TEXT` column. Anyone with read access to the\nSQLite file -- the same access level as `captured_events.body` and `tasks.body`\n-- sees sender-side shared secrets. A leaked database file leaks secrets even\nwhen the filesystem ACLs were correct at rest.\n\n## Decision\n\nEncrypt the `secret` column at rest with **AES-256-GCM** (stdlib\n`crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the\nstore: encrypt on write, decrypt on read. The store is the data boundary; its\nconsumers (dispatch loop, HMAC verification) receive the plaintext secret\nexactly as and the webui already blanks `Secret` on every response.\n\n### Cipher parameters\n\n- **AEAD:** AES-256-GCM, 12-byte random nonce (`crypto/rand`), tag appended.\n- **Key length:** 32 bytes, derived as `SHA-256(resolved_material)`. Kept as\n SHA-256 (no Argon2id) because the source is a **32-byte high-entropy** value\n resolved through the secret registry, so re-deriving to 32 bytes merely\n re-shapes entropy rather than defending a weak passphrase.\n- **AAD:** a static domain separator, `[]byte(\"arcie-binding-secret\")`, so a\n ciphertext cannot be relocated to a different field/column and still\n authenticate. AAD is intentionally **not** row-bound: binding secrets are\n random HMAC keys and are never used as lookup keys, so cross-row swap is not\n a meaningful attack here.\n\n### Envelope format\n\n```\narcie-binding:v1:\u003ckeyFingerprint\u003e:\u003cbase64url(nonce || ciphertext || tag)\u003e\n```\n\n- `arcie-binding` -- domain marker\n- `v1` -- format version (future cipher/KDF change is a new version, old rows\n stay readable)\n- `\u003ckeyFingerprint\u003e` -- `hex(SHA-256(material))[:16]`, the identity of the key\n that sealed the row, enabling rotation without a one-shot rewrite\n- payload -- `base64url` of `nonce ‖ GCM.Seal(plaintext, aad)`\n\n### Key source (confirmed with maintainer)\n\nResolved through the existing secret registry (`internal/secret`), the\nestablished `SecretRef` pattern already used for `forge.webhook_secret`:\n\n```toml\n[bindings]\nencryption_key = { engine = \"env\", key = \"ARCHIE_BINDING_KEY\" }\n# Rotation: after swapping encryption_key to a new value, retain the previous\n# material so rows sealed under the old key still decrypt.\nprevious_encryption_keys = [ { engine = \"env\", key = \"ARCHIE_BINDING_KEY_OLD\" } ]\n```\n\nThe active key encrypts new writes; `previous_encryption_keys` are retained for\ndecrypt-only. Key identity is intrinsic to the material (the fingerprint), so\nno manual key IDs are configured.\n\n### Rotation story\n\nRotate by changing `encryption_key`, moving the old material into\n`previous_encryption_keys`. Rows sealed under the old key still decrypt via\ntheir embedded fingerprint; new writes use the new active key. Once no\nremaining row references an old fingerprint, remove it from the config. Losing\na fingerprint's material before all its rows are rewritten makes those rows\nunreadable -- the same operational rule as any key rotation, and the reason the\nold material must be retained.\n\n## Non-goals / deferred\n\n- **`captured_events.body` redaction hardening** was completed alongside this\n work (not deferred): `webhookguard.RedactPayload` now redacts an expanded set\n of secret key markers (compound names like `access_token`, `client_secret`,\n `signing_key`, `x_api_key`, …) as well as unambiguous value shapes (compact\n JWTs, PEM private-key blocks) under any key. `gateway.sensitiveParameterKey`\n was broadened identically to preserve the documented agreement. It remains\n best-effort per `docs/prds/webhook-intake-security.md` point 5 -- a sender\n that picks a name the heuristic misses is still captured.\n- **Key re-derivation on config reload** is a startup concern: the store holds\n the cipher for its lifetime, so a reload that changes `[bindings]` keys\n requires a daemon restart to take effect. Documented, accepted.\n\n## Wiring\n\n- `internal/config`: add `BindingsConfig` (`encryption_key SecretRef`,\n `previous_encryption_keys []SecretRef`) on `Config.Bindings`.\n- `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through\n the already-built `secrets` registry, pass the material to `store.Open` via a\n new option `store.WithBindingCipher(cipher)`.\n- `internal/store`: add a `BindingCipher` interface (concrete AES-GCM impl in\n `binding_cipher.go`), a `bindingCipher` field on `Store`, and the `Open`\n option. **Nil cipher = plaintext**, so existing call sites and tests change\n nothing and legacy deployments keep current behaviour until they set a key.\n\n## Back-compat \u0026 tests\n\n- `storLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/channel-forge-positions/",
|
||||
"title": "Channel and Forge action positions (resolves `t2db.19`)",
|
||||
"section": "PRDs",
|
||||
"body": "# Channel and Forge action positions (resolves `t2db.19`)\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Blocked on:** `archie-core-t2db.24` (the `playbook_dispatches` ledger) for\nimplementation of either position. Both are side-effecting, and `t2db.17`\nresolved the keying scheme in design only.\n\n## Forge\n\n`internal/forge.Forge` is already exactly the shape a native-Go action position\nneeds -- a real, typed, general-purpose interface, not something that needs a\nYaegi/Module-style schema-generation detour:\n\n```go\ntype Forge interface {\n IssueForge // AssignedIssues, IssuesWithLabel, CloseIssue, ...\n PullRequestForge // CreatePR, PRState\n RepoForge // AcceptInvitations, VerifyPush, LinkBranch, ...\n}\n```\n\n**Typed contract shape: native-Go-by-name, not a Module-kind.** Module's whole\nreason to exist is giving _Yaegi-authored, operator-supplied_ code a typed\ncontract to implement. `Forge` is already a typed Go interface with real, tested\nimplementations (GitHub, Gitea) selected at daemon startup by `forge.New(...)`.\nWrapping it in a Module-kind schema/`go:generate` detour would duplicate a\ncontract that already exists. A Forge action position should be: a small set of\nnamed operations (e.g. `close-issue`, `create-pr`, `link-branch`), each with a\ntyped `Args`/`Result` struct mirroring the matching method's parameters/return.\n\nThe dispatch target is `internal/domain/workflow.Forger`\n(`CloseIssue`/`CreatePR`/`LinkBranch` -- already exists, already exactly these\nthree operations), **not** `internal/forge.Forge` directly. `organisation.md`'s\ntarget structure places `forge/` under `internal/infrastructure/forge/`; the flat\n`internal/forge` is a flat, unmigrated legacy package in the same position\n`internal/workflow` was in before its own migration. A new domain package\ndepending on the flat package directly would create a domain-to-infrastructure\ndependency that breaks the moment `forge` migrates. `workflow.Forger` is the\nnarrow, already-domain-owned contract that exists for exactly this reason -- the\ndaemon's real `forge.Forge` client satisfies it at the wiring layer.\nDepend on `Forger`, not on `internal/forge`.\n\n**Operation scope for a first slice:** `close-issue` and `link-branch`\n(single-call, cleanly idempotent by event+issue identity) are the safe starting\nset. `create-pr` is explicitly a heavier case -- opening a PR is a\nharder-to-reverse action with its own dedup shape beyond \"did this event fire\nbefore\" (a redelivered event must not open a second PR for the same logical\nchange) -- defer it to a follow-up slice once the keying scheme is proven on the\nsimpler operations, don't design it blind now.\n\n**Host access:** the coordinator needs the same `Forge` instance\n`internal/daemon`'s poller already holds (constructed once at startup via\n`forge.New`). This is a daemon-composition wiring question (pass the existing\ninstance into the coordinator's constructor), not a new extensibility mechanism.\n\n## Channel\n\n### Constraints this satisfies\n\nMessaging is the root, Channel is the integration layer, an implementation such\nas Telegram sits under Channel. A channel is added by implementing one reusable\ninterface, and every channel must implement it. A notification mechanism belongs\nunder Messaging, and `channels.Channel` must not reach across into it.\n\n### Notification is a Messaging contract, not a channel type\n\nThe contract lives in `internal/domain/messaging`. A channel implementation\nsatisfies it by importing its own parent, which it already does, so the\ndependency stays `channels -\u003e messaging` and nothing points back.\n\n`channels.Channel` does not change. It gains no notification method and no\nimport, so the interface every channel must implement stays the lifecycle and\nconfig contract it is. `internal/channels/telegram` satisfying both\ncontracts is an implementation choosing to, not the Channel layer knowing about\nnotification.\n\nA notification is not a channel type because it has no lifecycle to start and\nstop, no inbound direction, and no configuration schema of its own. Modelling it\nas one would force `Start`/`Stop`/`ConfigSchema` onto something with no meaning\nfor them, and make every real channel declare whether it is a notification.\n\n### Destinations are configured, never named by a playbook\n\n`[notify]` becomes a set of named destinations. Each binds a name the operator\nchooses to a channel already registered in the Messaging composition\n(`internal/app/archiemessaging/compose.go` registers `telegram`, `email`,\n`webhook`) plus that channel's own address, such as a Telegram chat id. The\nexisting single-webhook form keeps working as a destination named `webhook`.\n\nA playbook action names a destination. It never names an address. Playbook\ntriggers are reachable from a public, unauthenticated intake surface, soLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/code-graph-mcp/",
|
||||
"title": "Code graph over MCP (`tools/codegraph`)",
|
||||
"section": "PRDs",
|
||||
"body": "# Code graph over MCP (`tools/codegraph`)\n\n**Status:** Draft\n**Supersedes:** `symbol-reference-index.md`, which scoped only the data layer.\n\n## The problem\n\nEstablishing what a change touches costs an agent eight to fifteen\ngreps, and the answers are wrong in specific ways. `grep -rn \"Register(\"`\ncannot separate `plugin.Registry.Register` from `captureintake.Receiver.Register`\nfrom `forgerpc.Server.Register`, all of which exist here. It also matches the\nsibling checkouts under `.worktrees/`, which are near-complete copies of the\nmodule, so every count is silently inflated.\n\nThat cost lands hardest in investigation, triage and the TDD loop, where the\nfirst question is always \"what does this touch\".\n\n## Decision: exact analysis, not semantic retrieval\n\nTools like Greptile parse with tree-sitter, summarise each node, embed the\nsummaries, and retrieve semantically. That design exists because they must\nserve any language. This repository is one Go module, and Go's type checker is\nground truth:\n\n| Question | Source of truth |\n| --- | --- |\n| Who references this symbol? | `go/packages` + `go/types`, resolved by identity |\n| What calls what? | `callgraph` RTA over SSA |\n| What imports what? | `go list -deps` |\n\nNo vector database, no embedding cost, no edges invented by a summary that\ndrifted from the code. For a single-language repository this is both cheaper\nand strictly more accurate. Copy the interface those tools expose, not their\narchitecture.\n\n**A code graph does not power a documentation chatbot.** It answers structural\nquestions about Go symbols. Answering \"how do I configure a second identity\"\nmeans retrieving prose from markdown, which needs chunking, embedding and\nsimilarity search over a different corpus entirely. That remains a separate\ncapability with its own design. Conflating the two would build one system that\ndoes neither well.\n\n## Interface: an MCP server\n\n`archied` already consumes MCP as a client (`internal/app/agentworker`\nstarts providers) and serves none. Exposing the graph over MCP reaches Claude\nCode, pi, codex and Archie's own agents through one surface, with no coupling\nto the daemon: it is configured like any other entry in `[[mcp_servers]]`.\n\nFour tools, each returning JSON with file:line citations:\n\n- `references(symbol)` — every reference site, classified `prod` / `test` /\n `generated` / `dynamic`\n- `callers(symbol, depth)` — inbound call edges\n- `callees(symbol, depth)` — outbound call edges\n- `blast_radius(file | symbol)` — the transitive neighbourhood a change reaches,\n which is the single call meant to replace the grep sequence\n\nDiagrams are deliberately not a tool. A model given an accurate subgraph writes\nits own Mermaid; a diagram endpoint would only fix the rendering of something\nthe model already has.\n\n## Decisions\n\n**Every answer declares what it could not see.** RTA over-approximates\ninterface dispatch, and reflection is invisible: every `reflect.ValueOf` entry\nin `wfextract`, `gateextract`, `pluginextract`, `secretextract` and\n`logextract` makes a symbol look reachable whether or not anything calls it.\nEach response carries a `dynamic_edges` field naming those boundaries. An agent\ntrusting a confident wrong graph is worse off than one that greps, so the graph\nstates its own limits rather than implying completeness.\n\n**Warm in memory, keyed on HEAD, never persisted to disk.** `deadcode` does\nwhole-program RTA in under seven seconds; this does less work. The server\nrebuilds when HEAD changes and refuses its cache outright when the tree is\ndirty. Nothing is written to disk, because a persisted index becomes a rendered\nview that outlives its evidence. That is the failure that made `STATUS.md`\nreport 90 of 91 findings re-verified while most statuses were 77 commits stale,\nand the same one that made `reachaudit` serve a previous tree's analysis from\n`/tmp` until its cache was keyed on HEAD.\n\n**`tools/codegraph`, not `internal/`.** It is developer tooling, not daemon\nruntime, so it belongs beside `docsgen`, `contractaudit` and `reachaudit` in\nthe `tools` module, which `task test:tools` already covers. Start as a single\nGo file; split only when it earns it.\n\n**No new dependency.** `golang.org/x/tools` is already in `go.sum` at v0.49.0.\n\n## How it is verified\n\nRed first. Table-driven tests against small fixture modules built in\n`t.TempDir()`, asserting the behaviour that distinguishes this from grep:\n\n1. Two methods spelled `Register` on different types resolve to two separate\n records, and a reference to one does not increment the other.\n2. A symbol referenced only from `_test.go` reports zero `prod` references.\n3. A symbol referenced only from a `reflect.ValueOf` table reports zero `prod`\n references and one `dynamic`, and names the table in `dynamic_edges`.\n4. A generated file's references land in `generated`, not `prod`.\n\nMutation-verify eachLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/config-example-drift/",
|
||||
"title": "Example-config and generated-config drift — decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Example-config and generated-config drift — decision\n\n**Status:** Approved\n**Date:** 2026-09-15\n**Closes:** the checked-in-config half of audit findings `config-1` and\n`repo-root-deployment-2`; strengthens `doc-drift` findings generally.\n**Authority:** extends `docs/architecture/generated-documentation.md` and\n`docs/prds/config-schema.md`; does not replace either.\n\n## Question\n\nShould `config.example.toml` and `deployments/*.toml` be *generated*, so they\ncannot drift from the config code?\n\n## Decision\n\n**No — do not generate them. Gate them instead.** Neither file is a projection\nof the schema, and generating either would destroy the thing that makes it\nuseful. Three verified reasons, in order of weight:\n\n1. **`config.example.toml`'s value is its comments.** It documents **137 keys**\n (measured: active *and* commented-out), and those hand-written comments are\n the file's purpose — `docs/architecture/configuration.md` states outright\n that \"`config.example.toml` carries documentation users are meant to\n hand-edit\". TOML round-tripping does not preserve comments, which is exactly\n why `tomlwrite` does line-oriented edits rather than decode/encode. A\n generator would emit a correct file with the documentation deleted.\n2. **`docs/prds/config-schema.md` forbids building on `config.Config`.** That PRD\n rejects \"a reflection-based schema over `config.Config`\" because the struct is\n \"scheduled for dissolution\". A generator deriving the example from its struct\n tags would build on a foundation this repo has already decided to remove.\n3. **`docs/architecture/generated-documentation.md` prohibits it.** \"Adding\n another hardcoded type list to `docsgen` is prohibited\" — so any generator\n must consume a domain-owned registry, which does not exist for configuration\n yet. Creating one is the config-domain migration's job, not this change's.\n\nThe deployment profiles are also not a projection: they set **3-46 keys** against\nthe example's 137, and they are curated overlays (\"a complete config, not an\noverlay\", per their own headers), not near-duplicates. Generating them would add\nmachinery to remove duplication that largely is not there.\n\n## The gap that is real\n\n**Unknown config keys are silently ignored.** Verified at\n`internal/infrastructure/configuration/decode.go`:\n\n```go\nif _, err := toml.DecodeFile(path, target); err != nil {\n```\n\nThere is no `MetaData.Undecoded()` check, so a typo — `max_concurrancy = 4` —\nparses clean, validates clean, and does nothing. That is the same failure shape\nthis repo's audit found repeatedly: a setting that looks applied and is not. It\nis also detectable **without any hand-maintained list**, because `BurntSushi/toml`\nreports exactly which keys the target did not consume.\n\nNote the second, separate gap already admitted in writing:\n`generated-documentation.md` — \"`task check` does not run `docs:check`, so\ngenerated drift is ungated.\"\n\n## What to build\n\n**1. Unknown-key detection at the loader (behaviour).** Decode with metadata and\ncollect `Undecoded()`. Report it as a warning at startup listing the offending\nkeys, and expose it so tests can assert emptiness.\n\n**Deliberately a warning, not a fatal error.** `configuration.md`'s settled\nstartup policy is \"a missing credential disables a capability; only an invalid\nconfig stops the daemon\". A stray key is far more likely to be an operator typo\nin a file they are otherwise happy with than a reason to refuse to boot, and\n`[web]` is documented as landing in a *different* binary\n(`internal/app/archieui`), so a key unknown to one process is legitimately known\nto another. Failing closed here would break working deployments on upgrade.\n\n**2. A checked-in-config contract test (gate).** Load `config.example.toml` and\nevery `deployments/*.toml` through the real loader and assert `Undecoded()` is\nempty, with an explicit allowlist for keys another binary owns. This is the\nmechanism that would have caught a renamed key left behind in an example, and it\nneeds no inventory.\n\n**3. Gate generated data in `task check`.** Done. `task docs:check` runs in the\ngate, closing the admitted \"generated drift is ungated\" hole. The\ncheck mode did not exist when this was written; it was added for issue #855,\nwhich also made the check non-destructive so the gate can never rewrite the\nartifact it is judging.\n\n**4. Explicitly NOT now: a generated key inventory.** `configuration.md`'s\ncompletion criteria want \"generated documentation lists every external key,\ndefault, constraint, mutability class, owner\". That is a real target and it is\nthe config domain's, once a domain-owned registry exists — the prohibition above\nmeans it cannot be bootstrapped from a list inside `docsgen`. Recorded as\ndeferred, not rejected.\n\n## Non-goals\n\n- No generation of `config.example.toml` or `deployments/*.toml`.\n- No reflection-baLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/config-schema/",
|
||||
"title": "Backend-owned configuration schema for the webui -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Backend-owned configuration schema for the webui -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-b6ew` (epic), with children `.1`-`.5`\n\n## Decision\n\nThe dashboard's Configuration page keeps reading a secret-free,\nhand-picked view of `config.Config` -- that allowlist is a safety\nboundary and stays exactly as it is. What changes is who defines the\npage around it: `ui/src/settings/settings.js` and\n`config-row.js` hardcode every row's label, section, type, and\neditability by hand; after this, the backend attaches that metadata to\neach field it already allows through, and the frontend renders\nsections and fields generically from what the backend sends.\n\nThis is **not** a reflection-based schema over `config.Config`.\n`internal/config/config.go`'s own package doc states it is \"scheduled\nfor dissolution: its types and methods are to be reassigned to the\ndomains whose behaviour they describe\" -- building a generic\nschema-from-struct-tags mechanism over a struct on its way out would be\nbuilding on a foundation this repo has already decided to remove.\nInstead, every field already in `ConfigView` (`internal/webui/api_config.go`)\ngot there because someone deliberately vetted it as safe to show; the\nschema adds a hand-authored descriptor to that same deliberate act,\nnot a new mechanism that re-derives safety automatically.\n\n## Why now\n\nTask #6's investigation (`/9/26`) found the concrete failure this\nproduces: `Repo.AllowConcurrent` and `Repo.MaxRetries` already reach\n`GET /api/config` (`RepoView` in `api_config.go`), but the\nrepositories card renders a static read-only table that never shows\nthem, so the fix for \"why isn't a second agent running\" required an\nagent tracing Go source instead of a checkbox on the dashboard.\n`Repo.ReviewEnabled` is worse: it never reaches the API at all. Both\nare symptoms of the same root cause -- the frontend decides what a\nfield means and whether it's shown, and nothing keeps that in sync\nwith what the backend actually allows.\n\n## Shape\n\n```go\n// internal/webui/config_schema.go (new)\n\ntype ConfigFieldType string\n\nconst (\n FieldString ConfigFieldType = \"string\"\n FieldInt ConfigFieldType = \"int\"\n FieldBool ConfigFieldType = \"bool\"\n FieldDuration ConfigFieldType = \"duration\"\n FieldEnum ConfigFieldType = \"enum\"\n FieldStructured ConfigFieldType = \"structured\" // repositories, models, providers\n)\n\ntype ConfigField struct {\n Key string `json:\"key\"` // dotted path, matches UpdateConfig's key space\n Label string `json:\"label\"`\n Description string `json:\"description,omitempty\"`\n Type ConfigFieldType `json:\"type\"`\n Value any `json:\"value\"`\n Editable bool `json:\"editable\"`\n LockedReason string `json:\"locked_reason,omitempty\"`\n Overridden bool `json:\"overridden\"`\n Options []string `json:\"options,omitempty\"` // enum only\n RestartRequired bool `json:\"restart_required\"`\n}\n\ntype ConfigSection struct {\n ID string `json:\"id\"`\n Label string `json:\"label\"`\n Fields []ConfigField `json:\"fields\"`\n}\n```\n\n`handleConfig` builds `[]ConfigSection` from the existing per-field\nvalues it already assembles, plus `overlay.DeniedKeys` for\n`LockedReason` and the existing `Overridden` list -- both already\ncomputed just re-attached per field instead of returned as\nside-channel maps the frontend cross-references by key string.\n`Locked`/`Overridden`/`Reload`/`Provenance` stay as top-level\n`ConfigView` fields; they describe runtime state (what happened on\nthe last reload, which keys the overlay refuses), not the field\ncatalog, and duplicating that logic per-field would be the same drift\nrisk this change exists to remove.\n\n`FieldStructured` fields (repositories, models, providers) carry\n`Value` as structured JSON and are rendered by dedicated\neditors, not the generic renderer -- see \"What this does not do\".\n\n## Sections\n\nMatches the cards the settings page already has: `identity`,\n`repositories`, `models`, `providers`, `budgets`, `storage`,\n`containers`, `web`. No new sections; this is metadata on existing\nrows, not new configuration surface.\n\n## Frontend\n\n`config-row.js`'s `row(label, value, opts)` becomes the renderer's\nprivate implementation detail, called generically:\n\n```js\nfor (const section of schema.sections) {\n const rows = section.fields\n .filter(f =\u003e f.type !== \"structured\")\n .map(f =\u003e row(f.label, f.value, {\n key: f.key, type: f.type, options: f.options,\n locked: f.locked_reason, overridden: f.overridden,\n restartRequired: f.restart_required,\n }));\n // structured fields render through their dedicated editor (b6ew.4)\n}Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/contract-conformance-audit/",
|
||||
"title": "Contract conformance audit — decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Contract conformance audit — decision\n\n**Status:** Finalised\n**Scope:** an **advisory** report, deliberately **not** part of `task check`.\n**Date:** 2026-09-15\n**Authority:** sibling to `archie-core-06ag` (standing reachability audit) and\n`docs/architecture/dependencies-and-contracts.md`. Replaces neither.\n**Open:** withdraw it, or rebuild it structurally. See \"Open decision\" — not to\nbe resolved by hardening the regexes.\n\n## Question\n\nDoes every declared contract surface have a consumer, or an explicit declaration\nthat it has none?\n\nReachability (`tools/reachaudit`) asks the complementary question — *is this code\nin a shipped binary?* — and cannot see a capability that is **reachable and\nunconsumed**. `ratelimit` was in the binary closure and called by nothing\n(`archie-core-6wxb`); reachability would not have found that.\n\n## Decision\n\nYes, as an advisory survey. `tools/contractaudit` classifies each subject of each\nsurface:\n\n| Classification | Meaning | Fails `--strict`? |\n| --- | --- | --- |\n| `CONSUMED` | a call site exercises it | no |\n| `DECLARED-UNCONSUMED` | allowlisted in `docs/contract-declarations.json`, with a reason and a tracker | no |\n| `UNDECLARED-UNCONSUMED` | nobody reaches it, nobody declared it | **yes** |\n| `STALE-DECLARATION` | an allowlist entry that is no longer true | **yes** |\n\nThere are **four** classes and **two** of them fail. The allowlist must match\nreality exactly, and it fails in both directions: a missing entry is a finding,\nand an entry that outlived its subject is a finding, because a stale allowlist is\nhow a check quietly stops checking anything.\n\n**Not gated.** `task contract` is advisory and `task check` does not run it,\nmatching `tools/reachaudit`. The surfaces are discovered by scanning source text,\nso a rename or a reformat elsewhere in the tree can change the output with nothing\nactually wrong. It has already produced 16 false \"unconsumed\" readings once, when\nthe dashboard's request helper was renamed. A check that can fail for reasons\nunrelated to what it measures must not be able to break a build.\n\n## Surfaces actually built — three, not five\n\n| Surface | Subjects | \"Consumed\" means |\n| --- | --- | --- |\n| `proto/state/v1` `StateStoreService` | **45 RPCs** | an adapter body calls `client.\u003cRpc\u003e(...)` |\n| `proto/gateway/v1` `ChatService` | **21 RPCs** | same |\n| `internal/webui` dashboard routes | **49 routes** | a path literal appears as a call argument under `ui/src` |\n\nConsumption for the gRPC surfaces is established by **scanning adapter source\ntext** for calls through the generated client, not by reflection. See the errata\nbelow: the first revision of this document claimed reflection, and the first\nimplementation did use it, but the shipped mechanism is a regex and the document\nwas not updated to match.\n\n## What this audit has actually found\n\n**Nothing actionable.** On the current tree it reports 0 undeclared and 0 stale.\nIts only allowlisted entries are two RPCs superseded by their streaming variants\n(`ListCaptures`, `ListUndispatchedCaptures`), which were already known from the\nsource comment on `staterpc.Client.ListCaptures`.\n\nEvery real defect found in the session that produced this tool was found by other\nmeans:\n\n- the three 415 refusals, by reading `authorizeTaskMutation` and reproducing the\n browser's exact headers against the real handler;\n- the dashboard client's duplicated request plumbing, by reading the module.\n\nRecorded plainly because a survey that has never found anything is evidence about\nthe survey, not about the tree.\n\n## Errata — claims in the first revision of this document that were false\n\n- **\"RPC coverage is derived by reflection over the exported client type.\"**\n It is not. `proto.go` regex-scans adapter bodies for `client.Method(` calls.\n The reflection version was replaced and the document was not updated. The unused\n `google.golang.org/grpc` family in `tools/go.mod` was residue from that\n iteration; `go mod tidy` removed it on 2026-09-15.\n- **Surface sizes of \"43 / 12 / 52\".** The real counts are 45 / 21 / 49.\n- **\"Three classifications, and the third is the only finding.\"** Four classes,\n two of which fail.\n- **\"Raw `fetch()` calls caused 401s to render as `refused`/`broken`.\"** Wrong.\n Every raw call site passed `res.status` to `ApiError`, so `classifyActionError`\n already mapped 401 to `session-expired`; the chat stream never classified at\n all. The real defect in that area was different (below).\n- **A five-surface \"Shape\" naming `surface.go`, `generated.go`,\n `declarations.go`, and `testdata/`.** None were written. The real files are\n `main.go`, `audit.go`, `proto.go`, `webui.go`.\n\n## The two gaps this was aimed at\n\n**1. `docsgen check` is documented and does not exist.** Closed by issue #855.\n(issue #855 / `archie-core-5gzx`). `tools/docsgen` now has a `check` subcommanLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/control-plane-apply-status/",
|
||||
"title": "Control-plane apply status",
|
||||
"section": "PRDs",
|
||||
"body": "# Control-plane apply status\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Tracking:** `archie-core-pskb`, and `archie-core-nwa0` which depends on it\n\n## Outcome\n\nAn operator who edits a control-plane resource can see which processes are\nrunning that version, which are still on an older one, which rejected it, and\nwhich have stopped reporting.\n\n`docs/prds/runtime-control-plane.md` requires this and does not say where the\nreport goes. This decides that.\n\n## Where the report goes\n\nApply status is a State Store contract surface. `ControlPlaneService` is the\nsurface for editing a resource, and a status report is not an edit. The\nprecedent is the config snapshot pair: a process publishes what it knows, the\nUI process reads it, and both RPCs are administrative, so a task-scoped grant\nreaches neither. That denial needs no new rule: `authorizesTaskScopedCall`\nnames three methods and denies everything else.\n\n`docs/prds/state-store-contract.md` gains the pair in its inventory, and its\nRPC count at two places moves from 45 to 47.\n\nThe read returns all records as a list, including an empty one. The\n`found=false` convention for absent single rows does not apply.\n\n## What is reported\n\nOne record per process and resource kind, replaced in place. It holds the\nprocess name, the resource kind, the version applied, the error if the process\ncould not apply it, and the time it reported.\n\nEach process re-stamps its records every 30 seconds. A record is stale once it\nis older than 90 seconds, and a stale record means the process that wrote it is\nno longer running. The report time is therefore a liveness signal, not only a\nwrite timestamp.\n\nA process reports at the point it applies a resource, so the record says what\nhappened rather than what was intended. Nothing probes.\n\nProcess names come from one shared constant naming `archied`, `archie-gateway`\nand `archie-messaging`. A deployment runs at most one of each. Writer and\nreader are bound to that constant by test, because a drifted name is\nindistinguishable from a process that never reported.\n\n## Which processes report\n\n- `archied` and `archie-gateway` apply every restart-required kind through\n `boot.runtimeConfig`, at boot and on SIGHUP.\n- `archied` also applies the live kinds it watches, and reports each update it\n applies.\n- `archie-messaging` applies channel settings at startup and reports that kind.\n\n## What can be reported, and what cannot\n\nA process reaches its apply point only after the State Store has answered it.\nWhen the State Store is unreachable, the process exits or refuses to start and\nwrites no record. An unreachable store is never reported as a failure by the\nprocess it affected. A record carries the other failure: the store answered,\nand the value would not validate.\n\nAbsence has two meanings and the UI never collapses them: no process applies\nthis kind, or a process that applies other kinds has not reported this one.\n\n## Relationship to the reload status\n\nApply status covers control-plane resource kinds. `ReloadStatus` covers the\nfile document and stays the only report for a SIGHUP that failed to resolve or\nvalidate it. Neither is derived from the other.\n\nWriting a record is best-effort. On the SIGHUP path it takes its own bounded\ncontext, separate from the budget the reload spends reading the control plane,\nand a failed write is logged rather than turned into a failed reload.\n\n## What the UI shows\n\nThe settings page shows, per resource, the stored version beside each process's\napplied version, error, and report time. A process on an older version of a\nrestart-required resource is pending a restart. A process with an error is\nfailed, with the error beside it. A process whose record is stale is unknown,\nnever current.\n\n## A record outlives the process that wrote it\n\nRecords are replaced in place, so a process that applies a version and then\nstops would otherwise leave a record asserting that version indefinitely, and\nthe settings page would show a dead process as current.\n`docs/prds/status-health-surface.md` faced the same choice and stamped the start\nof a poll pass so a wedged poller reads as stale rather than healthy.\n\nSettled: the re-stamp above. The alternatives considered were\ncarrying the instance identity generated at process start, which detects a\nrestart but not a death, and accepting the limitation with the page saying so.\n\n## Verification\n\n- A process that applies a resource writes a record carrying that version.\n- A process whose apply fails validation writes a record carrying the error and\n no new version.\n- A reload that fails leaves the previously applied version recorded.\n- A record written under a process name outside the shared constant fails the\n test binding writer to reader.\n- A task-scoped credential is refused by both RPCs.\n- A failed report does not fail the reload that produced it.\n- A record that stops being re-Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/curator-sampler-wave1/",
|
||||
"title": "Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision\n\n**Status:** Approved\n**Date:** 2026-09-05\n**Beads issue:** bead `archie-core-1786637500776-416-600a66e5` / GitHub #437\ncovers the embedding-backed follow-on strategy only. This PRD covers the\nprerequisite interface and the cheap strategies.\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** nothing shipped (this is itself a prerequisite)\n**Blocks:** the embedding-backed surprisal strategy (GitHub #437), which\nimplements this same interface once the embeddings capability\n(`internal/domain/embedding`, this change) lands\n\n## Problem\n\nA future curator that reviews a large body of content (memories, sessions,\nskills) cannot always afford to run its agentic budget over every candidate\nevery pass. It needs to pick a bounded subset first. GitHub #437's acceptance\ncriteria requires that subset-picking to sit \"behind a `Sampler` interface\nthat wave 1 of the curator epic ships (cheap strategies: recency, random,\nall, staleness proxy)\" and that the embedding-backed strategy implement \"the\nsame interface\" later. No such interface, and none of the four cheap\nstrategies, exist anywhere in the codebase (bead 434e5bb9's closure\nwithout a linked PR was the tracker being wrong, not the code existing) --\nthis PRD is the one-page settled design for it, per this repo's Scope\nDiscipline rule.\n\n## Decision\n\nA `Sampler` is a pure, call-scoped selection function: given a fixed slice of\ncandidates and a request, it returns a subset. No lifecycle, no host access,\nno I/O for the four wave-1 strategies -- they are computation only, so they\nlive directly in `internal/domain/sampling` (a domain package, not\n`internal/infrastructure/*`) alongside the contract, the same way\n`curator/activity.go`'s pure ring buffer sits next to `curator/contract.go`\nrather than in an infrastructure package.\n\n```go\n// Package sampling is the curator sampler family: given a bounded set of\n// candidates, pick a subset to spend a curator pass's agentic budget on.\n// See docs/prds/curator-sampler-wave1.md.\npackage sampling\n\n// Candidate is one item eligible for sampling. It is deliberately narrow:\n// an opaque identifier, the timestamp the timestamp-based strategies score\n// against, and an open Metadata bag for whatever a future strategy needs\n// (e.g. the embedding-backed surprisal strategy's vector) without widening\n// this struct for every strategy that comes after wave 1.\ntype Candidate struct {\n ID string\n At time.Time\n Metadata map[string]any\n}\n\n// Request carries the knobs every strategy shares: a selection cap and a\n// deterministic seed. Both are optional -- Cap 0 means unlimited (the \"all\"\n// strategy relies on this), Seed 0 is a valid seed, not \"unset\".\ntype Request struct {\n Cap int\n Seed int64\n}\n\n// Sampler selects a subset of candidates to spend a curator pass's agentic\n// budget on. Every implementation -- the four here and the future\n// embedding-backed surprisal strategy (GitHub #437) -- must be\n// deterministic given the same candidates and Request: same inputs, same\n// output, every time. That is what makes a pass reproducible and testable,\n// and is GitHub #437's stated acceptance criterion for the strategy it\n// adds behind this same interface.\ntype Sampler interface {\n // Name identifies the strategy for logging/attribution (e.g.\n // \"recency\", \"random\", \"all\", \"staleness\", later \"surprisal\").\n Name() string\n // Sample selects from candidates per req. Implementations must not\n // mutate candidates or rely on anything but candidates and req --\n // determinism depends on that.\n Sample(ctx context.Context, candidates []Candidate, req Request) ([]Candidate, error)\n}\n```\n\n### The four wave-1 strategies\n\nAll four are `internal/domain/sampling` types constructed with `NewX(...)`,\neach implementing `Sampler`:\n\n- **`recency`** (`NewRecency()`): sorts candidates newest-`At`-first (stable\n sort, ties keep input order so output is deterministic even when two\n candidates share a timestamp), then truncates to `req.Cap` (0 = all).\n- **`staleness`** (`NewStaleness()`): the mirror of recency -- sorts oldest-\n `At`-first, then truncates to `req.Cap`. This is explicitly a *proxy*:\n \"hasn't been touched in the longest time\" using whatever timestamp the\n caller populated `Candidate.At` with (created, updated, or\n last-reviewed -- the caller's choice, not this package's), never the\n embedding-based surprisal calculation GitHub #437 owns.\n- **`all`** (`NewAll()`): no filtering. Returns candidates in input order,\n truncated to `req.Cap` (0 = every candidate). Input order is the only\n order this strategy has an opinion about, and preserving it is what makes\n it deterministic.\n- **`random`** (`NewRandom()`): a uniform-random subset, sized to\n `req.Cap` (0 = every canLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-aware-chat-navigation/",
|
||||
"title": "Dashboard-aware chat: Archie sees the page, and points the operator there",
|
||||
"section": "PRDs",
|
||||
"body": "# Dashboard-aware chat: Archie sees the page, and points the operator there\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Compound:** the \"chat available on any page\" surface work (global chat presence)\n\n## Decision\n\nMake the web chat **dashboard-aware**: the agent is told which dashboard page\nthe operator has *open*, knows what each page is for, and can **point**\nthe operator to the relevant page with a **clickable destination chip** the UI\nrenders and follows - Option B (context + navigate), not just \"tell me in text.\"\n\nThree seams, each an existing extension point, one new tool and one message field:\n\n1. **Current page, into the prompt.** The browser sends its route with every\n chat message; the gateway threads it into the system prompt's runtime-metadata\n env block. Archie always knows where the operator is looking.\n2. **Page index.** A page_index tool lists the dashboard pages and what each one\n shows, so Archie knows what to point at - the agent \"has the map\".\n3. **Navigate.** A dashboard_navigate tool returns a structured path/label; the web\n UI renders it as a clickable chip that routes the operator there. This is the\n \"plenty of resources\" the requirement named.\n\nWe deliberately keep the agent's answer honest: the chip is *evidence* it can\nvalidly produce because dashboard_navigate is a real tool whose result is\nrendered, not a markdown link the model invents.\n\n## Why now\n\nThis is the natural next step of the \"chat on any page\" work, and the original\nrequest named it explicitly: *\"archie should be able to see what page you're on\ntoo. and point out where to go. so it needs plenty of resources.\"* The chat\nis a full-page route with no knowledge of the rest of the dashboard; the agent\ncannot see which page the operator is on and cannot reliably direct them anywhere.\nThe critique of the chat UI already identified \"chat is not available on any page\"\nas the largest structural gap (P1). This design is the capability that makes that\ngap worth closing.\n\n## Shape of the API\n\n### Message field (gateway.go)\n\nAdd Page to Message:\n\n```go\n// Page is the dashboard route the operator is on when they sent this message\n// (e.g. \"/tasks\", \"/logs\"). Empty for non-web channels, which have no page\n// context. It is per-message, not per-session: the operator navigates freely\n// while a conversation stays open.\nPage string\n```\n\n### Web request (api_chat.go)\n\nchatMessageRequest gains Page, decoded into Message.Page in decodeChatMessage.\n\n### System prompt config (prompt.go)\n\nSystemPromptConfig gains Page; BuildSystemPrompt passes it through to the template.\nThe env block of archie.md.tpl renders the current page when set.\n\n### Page index (dashboard_tools.go, new)\n\nA package-level registry mapping route to {Label, Description}. page_index returns\nthe list so the model knows what each page shows:\n\n```go\ntype DashboardPage struct {\n\tPath string // \"/tasks\"\n\tLabel string // \"Tasks\"\n\tDescription string // \"Issues Archie picked up, and where they stand.\"\n}\n```\n\n### Navigation tool (dashboard_tools.go)\n\ndashboard_navigate validates its path against the registry and returns the resolved\npath/label. Unknown path means a clear error, not a guess. The model must call the\ntool (not invent a link) to produce a chip, so the chip is honest.\n\n### Tool wiring (turn.go)\n\nextraTools already merges TaskTools + SessionTools. Add the dashboard tools alongside\nthem, gated on the channel being the web UI. The tool list is built from the same\nregistry the prompt's page line comes from, so the agent never points at a page it\nwas not told about.\n\n### Web UI (chat-render.js, chat-tools.js)\n\nA dashboard_navigate tool call renders as a **clickable chip**: an anchor with\nhref=\"/tasks\" and the label. The chip is a\nreal link that works from any page once the chat is a global presence. The chip is\nstyled as an action, not a code line, so it visibly invites a click.\n\n### Route transfer (chat.js)\n\nEach sendMessage includes the current location.hash route as page in the stream\nrequest body, so the backend gets the operator's live position.\n\n## What we deliberately do NOT do\n\n- **No navigation from a markdown link.** The model must use dashboard_navigate; a\n bare \"click here\" is not rendered as a trusted route.\n- **No full-page route hijack from the chat.** The chip sets location.hash.\n- **No page index for non-web channels.** Telegram/discord have no dashboard.\n- **No automatic history annotation.** Page is per-message from the browser.\n- **No change to the dangerous-action approval flow.** Separately tracked.\n\n## Acceptance criteria\n\n1. Chat messages from any page carry the current page to the agent's prompt.\n2. page_index returns every dashboard page with a plain-language description.\n3. dashboard_navigate renders a clickable chip that routes to the target page.\n4. dashboard_navLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-live-state/",
|
||||
"title": "Dashboard live state",
|
||||
"section": "PRDs",
|
||||
"body": "# Dashboard live state\n\n**Status:** Approved\n\n## Decision\n\nThe dashboard must not require passive **Refresh** buttons. One app-wide Pinia\nstore owns the existing `/events` EventSource and translates backend events\ninto resource revision counters. Pages load their authoritative HTTP projection\non entry and re-read it when the relevant revision changes. Event payloads are\ninvalidation signals, not substitute read models.\n\nSSE remains the transport. Dashboard updates are server-to-client only, and the\nexisting stream already provides replay, reconnect, and persisted ordering; a\nWebSocket would add a second transport without adding a capability.\n\nThe first slice covers resources for which the backend already emits a truthful\nsignal:\n\n- task events invalidate the dashboard, task board, workflow statistics, and\n the matching task-run page;\n- capture events invalidate the capture list;\n- curator events invalidate curator status, and curator actions also invalidate\n the skill catalogue;\n- update reports invalidate System status;\n- opening a page always loads its resource, and reopening the SSE stream\n invalidates mounted projections after a connection loss.\n\nLogs retain their dedicated SSE tail. Local mutations continue to re-read their\nown resource after success. Configuration, channels, and catalogues that have no\nbackend change event load on route entry; future write contracts must emit an\nowner-specific event rather than introduce polling or restore a button.\n\n## Boundaries\n\nThe Pinia store owns browser connection state and invalidation only. It does not\nbecome an alternate backend cache or copy domain state into a generic global\nobject. Existing feature modules continue to own their DTOs and API reads.\n\nOperational commands are not refresh controls. Channel **Reload** remains an\nexplicit adapter lifecycle action. Authentication recovery is also not a data\nrefresh: a 401 moves the application into shared authentication state; reloading\nthe same URL cannot restore Archie's missing or rotated token and must not be\noffered as a fix.\n\n## Verification\n\n- No passive page action renders the label **Refresh** or **Retry** for a read.\n- Only one shared `/events` EventSource is opened by the application.\n- Resource classification tests distinguish task, capture, curator, skill, and\n update invalidations.\n- UI tests, type checking, generated asset freshness, and `task check` pass.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-navigation-groups/",
|
||||
"title": "Dashboard navigation groups + Configuration split -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Dashboard navigation groups + Configuration split -- decision\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads issue:** `archie-core-ocfm`\n**Related:** `archie-core-gl96` (Logs absent from the nav -- subsumed here),\n`archie-core-ggqo` (Configuration's page width -- moot once it splits)\n\n## Problem\n\n`ui/src/main.jsx` declares eleven navigable routes in one flat bar. Three of\nthem (Skills, Curators, Channels) are capability-gated and hidden on the\nreference deployment, so the eight items normally visible are the best case,\nnot the worst: a composition that serves every section wraps the bar. Logs is\ndeclared but was never given a nav entry at all, reachable only from a\ndashboard link.\n\nThe labels compound it. \"Event inspector\", \"Field mappings\" and \"Playbook\nbindings\" are three long labels for three faces of one subject, and they sit\nbeside \"Dashboard\" and \"Tasks\" as though they were peers of equal weight.\n\nConfiguration is the other half. One route renders roughly ten sections --\nupdate status, work lifecycle, identity, budgets, storage, listen address,\nrepositories, models and providers, configuration sources, plus the operator\ncards rehomed in `archie-core-tf20` -- in a 4021px page with no in-page\nnavigation. There is no way to send someone to Repositories.\n\n## Decision\n\nFive top-level nav items. Dashboard is a link; the rest are dropdowns.\n\n| Group | Items |\n|---|---|\n| Dashboard | (link, `/`) |\n| Work | Tasks, Workflows |\n| Agent | Skills, Curators |\n| Events | Inspector, Mappings, Bindings |\n| System | Status, Logs, Appearance; **Settings:** Task settings, Models, Repositories, Channels, Advanced |\n\nItems are renamed because the group now carries the context: \"Event inspector\"\nbecomes \"Inspector\" under Events, and so on. A group renders only if at least\none of its children survives capability gating, and a group left with one\nchild still renders as a dropdown -- a bar whose shape changes per deployment\nis harder to learn than one with a predictable skeleton.\n\nThe System dropdown has two narratives. Status, Logs and Appearance describe\nthe running dashboard and sit first. A separator and visible **Settings** label\nintroduce Task settings, Models, Repositories, Channels and Advanced; those are\nconfiguration destinations, not awkward phrases such as \"System Models\" or\n\"System Advanced\".\n\n### Route map\n\nConfiguration dissolves into real routes. Anchors into one long page were\nrejected: they leave the 4021px page intact and a deep link lands the reader\nmid-scroll with no context above it.\n\n| Was | Becomes | Content |\n|---|---|---|\n| `/settings` | `/system/status` | Update status, configuration sources, daemon listen address |\n| -- | `/system/appearance` | Theme, and the density/motion preferences that follow it |\n| `/settings` | `/system/tasks` | Work lifecycle: statuses, operator actions, budgets |\n| `/settings` | `/system/models` | Model roles, providers |\n| `/settings` | `/system/repos` | Repositories and their per-repo gate overrides |\n| `/settings` | `/system/advanced` | Identity, storage and sandboxing, dangerous actions |\n| `/captures` | `/captures` | unchanged; label becomes \"Inspector\" |\n| `/mappings` | `/mappings` | unchanged; label becomes \"Mappings\" |\n| `/bindings` | `/bindings` | unchanged; label becomes \"Bindings\" |\n\n`/settings` is kept as a permanent redirect to `/system/status`. It is the URL\nin existing bookmarks, in `dashboardPages` (`internal/gateway/dashboard_tools.go`,\nwhich the chat agent navigates by), and in prior conversation history; breaking\nit to save one route entry is not a trade worth making.\n\n`dashboardPages` gains the new routes in the same change. That registry is\nguarded by `TestDashboardPagesRegistryCoversEveryRoute`, so a route added here\nand forgotten there fails the build -- which is how the deleted `/chat` entry\nwas caught.\n\n### Dropdown behaviour\n\nEach item carries a one-line description shown as a hover tooltip, using\nshadcn-vue's `Tooltip` rather than the `title` attribute, so it is keyboard\nreachable on focus and styled with the rest of the menu. Touch gets no tooltip,\nso no item may depend on one to be identifiable.\n\nThe menu is shadcn-vue's `DropdownMenu` (Reka UI underneath), which already\nsupplies the roving focus, ArrowDown/ArrowUp movement, Escape-closes-and-\nrestores-focus, and outside-pointerdown behaviour this would otherwise hand-\nroll. It opens on click, never on hover -- hover-opened menus on a control\nplane are a misclick away from a destructive page. The trigger keeps\n`aria-current` styling when any of its children is the active route, so the bar\nstill says where you are.\n\nThis section was written against the Preact dashboard; the decisions above\nsurvive the Vue migration unchanged, only the primitive supplying them\nchanged.\n\n### Scope boundaries\n\n- The daemon-backed configuration pages move sections between rLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-port-brief/",
|
||||
"title": "Dashboard port: what the agent delivers",
|
||||
"section": "PRDs",
|
||||
"body": "# Dashboard port: what the agent delivers\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation)\n**Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item),\n`docs/prds/dashboard-navigation-groups.md` (the approved nav design)\n\nThis is the standard the port is held to. The checklist says what to port; this\nsays how, and what counts as done. It exists because the first attempt ported\nthe flat topbar verbatim and invented a palette, both of which had already been\ndecided elsewhere.\n\n## The deliverable\n\nThe Preact dashboard, rebuilt in Vue 3 with shadcn-vue, feature complete\nagainst the checklist, gate clean, with `ui/dist` rebuilt and committed in the\nsame commit as the source it was built from.\n\n## Non-negotiables\n\n- **Vue 3 + shadcn-vue (Reka UI, Tailwind v4, Lucide).** A component that\n exists in shadcn-vue is not hand-rolled. Add it with the CLI\n (`npx shadcn-vue@latest add \u003cname\u003e`), do not paste it in.\n- **History routing.** `createWebHistory`, `base: \"/\"`. No hash routing.\n `src/legacy-hash-redirect.ts` handles old `#/path` links and stays.\n- **No test port.** 43 Preact test files are deliberately dropped.\n `task test:ui` is a `vue-tsc` typecheck. Write a test when there is a real\n failure to pin, not to re-assert a port.\n- **Do not downgrade TypeScript.** The target is TS 7 native, not TS 5.\n- **`ui/dist` is law.** Never hand-edit it, never omit it, never revert it.\n- **`task check` is the gate.** Not an assembled substitute for it.\n- **Beads, not markdown TODOs**, for anything that outlives the change.\n- **Conventional commits**, scoped `feat(webui):`. Commit gate-clean work\n without asking. Do not push without being told.\n\n## Componentisation\n\nOne component, one job, one file. A surface is composed from named components,\nnot assembled inside a single large file. The topbar is the worked example and\nthe required shape:\n\n```\ncomponents/topbar/\n Topbar.vue composes the header, owns nothing else\n Brand.vue Logo + BrandName, links to /\n Logo.vue\n BrandName.vue\n Nav.vue reads the nav model, renders links and groups\n NavTrigger.vue the shared top-level control, link or dropdown trigger\n NavGroup.vue one dropdown\n NavItem.vue one item inside a dropdown, with its tooltip\n SearchBar.vue\n SupportLink.vue\n ThemeToggle.vue\n ProfileDropdown.vue\n```\n\nThe same rule applies to every page ported after it. If a file is doing the\nwork of four named things, it is four files. Data and behaviour that more than\none component needs lives in `src/lib/`, not passed down through a chain of\nprops.\n\n## Ordering\n\nBuild the navigation restructure during the port, not after it. Porting the\nflat eleven-item bar first and restructuring later means writing the topbar\ntwice and touching the Go route registry twice. The approved design is five\ntop-level items (Dashboard, Work, Agent, Events, System), items renamed because\ntheir group carries the context, per-item descriptions shown as hover tooltips,\nConfiguration split into `/system/*`, `/settings` kept as a redirect, and Logs\nfinally given a nav entry.\n\n## Design authority\n\n- The approved documents win. Where a document decides something, implement it\n rather than re-deciding it.\n- **Do not invent a visual direction.** Palette, typography and density are the\n maintainer's call. A palette change is its own request, never a side effect\n of a port.\n- Contrast is AA against every surface the foreground lands on, hover states\n included. The corrected values (`--fg-subtle`, the dark\n `--primary-foreground`) came from a measured failure and must survive.\n- `color-scheme` follows the theme so the UA paints controls, scrollbars and\n overscroll to match.\n\n## Code style\n\nComment the non-obvious why: an invariant, a trap, a measurement, a contract\nanother file depends on. Do not narrate what the code plainly does, do not\nexplain a choice that was never in question, and do not write migration phase\nhistory into a diff. That history belongs in the commit message.\n\n## Done, per surface\n\n1. Renders with real data against `task dev`, not just typechecks.\n2. Keyboard reachable, focus visible, and the nav announces where you are.\n3. Works at 1440x900 and at 720px wide, with nothing clipped and no horizontal\n page scroll.\n4. Empty, loading, failed and unconfigured (501) states all say something true.\n A section that cannot load says so; it does not render blank.\n5. `task check` passes, `ui/dist` rebuilt, committed together.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/deep-research-capability/",
|
||||
"title": "Deep research capability — design",
|
||||
"section": "PRDs",
|
||||
"body": "# Deep research capability — design\n\n**Status:** Draft\n**Date:** 2026-09-14\n**Scope:** A deep-research capability in archie-core: an orchestrator that\nspawns 1..N subagents to explore and research in parallel, collates their\nfindings, and returns one cited report. Grounded in web search and web fetch.\n**Beads issue:** none yet (this document is the input to it)\n**Depends on:** nothing shipped for slice 1; slice 2 depends on slice 1.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |\n| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |\n| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |\n| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |\n| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |\n| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs *one* mission: \"orchestration across missions lives with the caller\". No caller does this yet |\n| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |\n| Per-result caps + spill-to-disk | **Implemented** | `internal/agentexec/toolset.go` `ToolLimits{MaxResultChars,SpillDir}`, applied in `toolExecute` via `tools.CapPayload` (`limit.go`); no **aggregate** turn cap by design (`toolset.go`). `config.ToolPolicy.SpillDir`; default cap 50k chars, spill dir deliberately not defaulted |\n| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go`) |\n| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |\n| Curator engine (interval, declared tool set, lifecycle) | **Implemented, tools broken** | `internal/domain/curator`; a curator declaring tools is **refused** at registration (`registry.go`, no `ToolBuilder` implementation) and `curatorLLMRunner` (`internal/app/archied/main.go`) drops `ChatRequest.Tools`. Budgets are time+concurrency only (`runtime.go`) — **no token budget** |\n| Cron / scheduling + delivery router | **Implemented, wired into no binary** | `internal/domain/scheduling`, `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), `internal/infrastructure/crondelivery` — all present and green, but `go list -deps` for every `cmd/` contains none of them, and `cron`-expression firing arithmetic is unimplemented (`schedule.go`, \"slice 2\"). `ARCHITECTURE.md` still asserts \"**No daemon-internal cron.**\" |\n| Workflow engines (multi-stage, resumable) | **Implemented, worktree-bound** | `internal/domain/workflow` — every non-triage workflow opens with `StagePrepareWorktree()` and mounts `tc.Dir` into a container; the task persists after every stage (`workflow.go`). `triage.go` documents there is \"no cheaper directory-less classification primitive\" |\n| Long-running chat-initiated work with progress | **Partial** | Chat turns run **once, synchronously**, inline in the channel's turn runner (`internal/gateway/turn.go`). Chat can spawn a *workflow task* (`task_spawn`) which is asynchronous — but that path is worktree/PR-shaped |\n| **Operator-push delivery of an async result** | **Aspirational — zero code** | Nothing pushes a finished result to a chat. No channel subscribes to the event bus (Telegram only *publishes* `KindTurnCompleted`); `crondelivery.Courier` is the intended seam but has **no implementation and no caller**; `send_file` works only inside theLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dynamic-curators/",
|
||||
"title": "Dynamically-defined curators -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Dynamically-defined curators -- decision\n\n**Status:** Approved\n**Date:** 2026-09-12\n**GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789)\n**Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed)\n**Depends on:** nothing shipping; this resolves the open question that epic #435's\n\"registered and configured declaratively, not hardcoded\" criterion left open.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| Curator engine family: typed contract, owning registry, start/health/stop, narrow host access | **Implemented** | `internal/domain/curator/{contract,registry,runtime,registrar,activity,wake}.go` |\n| Curator declared shape (`Manifest`: interval, cooldown, on_input, tools, skills, memory engine, conversations, model) | **Implemented** | `internal/domain/curator/contract.go`; `Validate()` requires `Interval \u003e 0` |\n| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |\n| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |\n| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |\n| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |\n| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `\"curator manifest: declares tools but the registrar has no ToolBuilder\"` |\n| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |\n| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |\n| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |\n| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `internal/config/config.go` |\n| Store/API as definition authority | **Aspirational -- zero code** | No curator persistence of any kind |\n| No live-path defaults for interval/cooldown/tools/model/memory engine | **Partial** | `skillcurator.DefaultInterval` / `sessioncurator.DefaultInterval` are Go consts read at registration; `curator.NewRuntime(..., RuntimeConfig{})` uses code defaults for pass timeout and concurrency |\n| Idle curators are observable in logs | **Partial** | `runtime.go` logs nothing when `Check` reports not-due; the session-memory curator's hourly pass is the only curator activity ever logged |\n| Sampler family | **Implemented** | `internal/domain/sampling`, shipped; no curator consumes a `Sampler` yet |\n| Forge/issue reach from chat | **Implemented** (via `shell`) | No dedicated issue tool exists, but the chat agent's `shell` is unconfined (`chat.unrestricted_filesystem = true`), so `gh issue edit|comment|create|close` works. Dedicated tools (#161) are convenience, not a blocker |\n\n\u003e **Target state, not current state.** Everything below marked aspirational is\n\u003e design, not a description of the daemon as it runs.\n\n## Problem\n\nA curator exists only if a Go package implements `curator.CuratorEngine`\nand `bootstrap.go/1025` names it in a `Register` call. Nothing about a\ncurator is definable as data. Worse, no curator can declare a tool set at all:\nthe `ToolBuilder` interface has no implementation in the repo, so the registry\nrefuses (correctly, fail-closed) any curator that declares tools -- and the\ndaemon's model adapter drops the tools even if it were bound. The curator family\ntherefore has exactly one shape (cheap, tool-less maintenance pass) and its only\nextension point is compiling Go.\n\nSam's requirement is the opposite: *\"Curators should be dynamically created and\ndefined, in addition to being able to be defined in code/config/webui\"* and *\"No\nconfiguration should ever be hard-coded.\"* The motivating consumer is a\nproject/orchestrator curator -- declared as data, given forge issue tools, and\npointed at a repo to review, refine, and propose issues.\n\n## Decision\n\n**A curator definition is data: a persisted entity whose declared shape is\nexactly `curator.Manifest` plus identity, free-form instructions, and an enabled\nflag. One generic engine interprets any definition.** The shape is not a second\ninvention -- `MLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dynamic-workflow-triage/",
|
||||
"title": "Dynamic workflow triage",
|
||||
"section": "PRDs",
|
||||
"body": "# Dynamic workflow triage\n\n**Status:** Finalised\n\nEpic: archie-core-enfj. Scope: give `workflow.Route()` a real, content-aware\nfallback instead of unconditionally defaulting every unlabeled task to the\nheaviest workflow.\n\n## Problem\n\n`Route()` (`internal/domain/workflow/workflow.go`) has exactly two real\nsignals: an explicit `t.Workflow`, and label matches via\n`workflowForLabels` (`routing.go`, `bug`→tdd, `feature`→feasibility,\nbootstrap→bootstrap). Anything else — which is every chat-spawned task,\nsince `task_spawn` rarely sets labels — falls straight through to\n`reg[\"implement\"]`, the full `prepare → baseline → plan → build →\ncommit-push → review → open-pr` pipeline, regardless of what the task\nactually asks for.\n\n`task_spawn`'s own tool schema overpromises: *\"workflow: … Omit to let the\ndaemon route it\"* (`internal/gateway/task_tools.go`) implies real\nrouting exists. It doesn't — \"route\" means \"check labels, then\ngive up and run the heaviest workflow anyway.\"\n\nConfirmed in production: a chat-spawned task whose\nentire content was \"this is just a test, close it when you receive it\" ran\nthe full `implement` pipeline end to end — 669,421 tokens, ~7 minutes —\nwhen nothing about the request needed a worktree-driven build at all. The\n`plan` stage's own LLM output *correctly* concluded no code change was\nneeded, but that conclusion arrives two expensive stages (`baseline`,\n`plan`) too late to save anything.\n\n## Decision\n\nAdd a **`triage` workflow**: cheap, classifies once, then either closes the\ntask immediately or hands off to the workflow the task actually needs.\n`Route()`'s final fallback (`reg[\"implement\"]`) becomes\n`reg[\"triage\"]` when a `triage` entry is registered, else the existing\n`implement` fallback — a two-line change, fully backward compatible when\n`triage` isn't wired up.\n\nTriage does **not** replace label-based routing. A labeled task\n(`bug`/`feature`/bootstrap) already has a free, reliable signal and goes\nstraight to its known workflow unchanged — spending a classification\ncall there would be pure waste. Triage only fires in the gap that\ndefaults to `implement` blindly: no explicit workflow, no label match.\n\n### Triage workflow shape\n\n```\nStagePrepareWorktree() -- still needed: AgentStage mounts tc.Dir into the\n agent container: internal/domain/workflow/agent.go:74\n passes tc.Dir straight through. No cheaper\n primitive exists in this codebase for a\n directory-less classification call.\nAgentStage \"classify\" -- ReadOnly, ONE cheap agent turn, no exploration\n tools required beyond what ReadOnly already\n grants. Mirrors feasibility.go's decideCaptureTools\n pattern: a structured capture tool, called\n exactly once, MaxCalls: 1.\n```\n\nMission: read the task's title/body/labels (already in `taskPromptBlock`)\nand decide, via a captured `decide` tool call:\n\n```json\n{\"needs_code_change\": bool, \"workflow\": \"implement\" | \"tdd\" | \"feasibility\", \"reasons\": \"...\"}\n```\n\n`needs_code_change: false` → close path: reuse `closeNoChangesIssue`\n(`steps.go`) directly — issue closed if forge-backed, task marked\n`StatusMerged`/`\"completed -- no changes required\"` otherwise. No baseline,\nno plan, no build, no commit, no PR. This is the actual fix for the\nproduction incident: a no-op request now costs one classification call\n(low thousands of tokens) instead of 669,421.\n\n`needs_code_change: true` → sets `tc.Task.Workflow` to the classifier's\nchosen workflow (`implement`/`tdd`/`feasibility`, defaulting to\n`implement` if the field is missing or unrecognized) and an Outcome that\nrequeues the task under it, the same requeue mechanism\n`chatTaskControllerAdapter.ApproveChatTask` already uses\n(`main.go`, `requeue(ctx, taskID, fromStatus, workflow)`). The task then\nre-enters `Route()` on its next claim with `t.Workflow` now set, and takes\nthe normal path for that workflow from there — triage never runs its\nclassification twice for the same task.\n\n### Non-goals (v1)\n\n- Full bug/feature intent classification quality — the classifier only\n needs to be *directionally* right; a wrong `tdd` vs `implement` call\n still produces a working PR, just via a slightly less-tailored pipeline.\n Tightening this is a follow-up, not a blocker.\n- Any change to label-based routing, `Route()`'s explicit-workflow branch,\n or `Bootstrap()`/`Feasibility()`/`TDD()` themselves.\n- Triage for forge-sourced (real GitHub issue) tasks with no labels —\n in scope structurally (same fallback branch), but the dominant case this\n fixes is chat-spawned tasks, which essentially never carry labels.\n\n## Testing\n\n- `workflow_test.go`: `Route()` picks `regLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/eda-playbook-engine/",
|
||||
"title": "EDA playbook engine -- design",
|
||||
"section": "PRDs",
|
||||
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `ARCHITECTURE.md#plugin-engine-rule-strict` governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalizes its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalog, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends through a named,\n already-registered Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/embedded-nats/",
|
||||
"title": "Embedded NATS execution -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Embedded NATS execution -- decision\n\n**Status:** Finalised\n\n**Date:** 2026-08-24\n\n**Beads epic:** `archie-core-q15y`\n\nThis decision supersedes the position that embedded NATS was only a\ndistribution mechanism and could not be an agent-execution topology. That was\ntrue only because the embedded listener was unauthenticated loopback. It left a\nsecond production architecture in which `archied` ran autonomous workflows in\nits own process, weakening the isolation boundary that managed task containers\nexist to provide.\n\n## One execution architecture, two broker deployments\n\nEvery autonomous repository workflow is handed over as one complete task via\nNATS and runs in a task-scoped `archie-agent` container. `archied` remains a\nnative, long-lived orchestration and interactive-chat process; its operator\nconfigured host filesystem access is unchanged. It owns task admission,\nstate, forge and worktree operations, container lifecycle, and the broker when\nthe embedded deployment is selected. It does not run an autonomous model loop.\n\nNATS has two supported deployment shapes:\n\n| mode | meaning |\n| --- | --- |\n| `embedded` | `archied` owns an in-process JetStream server (default). |\n| `external` | `archied` and workers connect to the configured NATS URL. |\n\nBoth shapes have identical task semantics: one container and one full-task\nrequest per workflow. Broker placement must not select a different executor.\nThe legacy `agent` section and `containers.enabled` key remain decode-only\nmigration inputs. `nats.mode = \"off\"`, per-stage NATS, in-process execution,\nand subprocess execution are not production choices.\n\nSQLite remains authoritative for task state. NATS is the sole autonomous work\nhandoff. SQLite recovery may identify work that needs republishing, but it must\nnot cause `archied` to call `workflow.Run` locally.\n\n## Embedded reachability and authentication\n\nAn embedded listener uses a cryptographically random bearer token generated for\neach daemon start. The token exists only in process memory and the environment\nof managed worker containers; it is never written to config or logs.\n\nFor a native daemon with managed containers, startup resolves the Docker bridge\nthe workers will join. The listener binds only to that bridge's host gateway\naddress on a random port. Both the native daemon and workers use that same\nreachable endpoint, and every client supplies the generated token. Binding a\nDocker bridge address keeps the listener off ordinary LAN interfaces without\npublishing a host port. A configured user bridge is respected; otherwise the\nDocker default bridge is used. A network without a usable local IPv4 gateway is\na startup error for autonomous execution.\n\nIf Docker is unavailable, interactive chat may still start and embedded NATS\nmay remain loopback-only, but autonomous tasks park with an explicit container\ncapability failure. They never fall back to host execution.\n\n## Ownership and lifecycle\n\n- `internal/infrastructure/eventbus/nats` owns the authenticated embedded\n server and exposes its runtime endpoint, not the server implementation.\n- `internal/container` resolves the worker bridge and gateway and owns task\n container lifecycle.\n- `internal/app` composition selects embedded or external broker deployment,\n freezes the connected runtime endpoint for worker environments, and wires the\n full-task handoff.\n- `cmd/archied` remains process input only as the domain migration reaches this\n composition path.\n\nThe daemon starts the embedded server before its client, closes clients before\nthe server, and keeps JetStream data beneath the daemon data directory. NATS URL\nand token are startup-built values: a reload cannot send new workers to a broker\ndifferent from the one the daemon is using.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/event-capture-storage/",
|
||||
"title": "Event capture storage -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Event capture storage -- decision\n\n**Status:** Finalised\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.1`\n\n`webhook-intake-security.md` decided points 1-5 (auth split, approval gate,\nrate limits, blast radius, retention/redaction) and explicitly left the\nstorage mechanism open, forward-pointing at \"`7d5u.2`, embedded NATS.\" That\npointer predates `7d5u.3`'s 2026-08-22 narrowing, which assigned capture\nstorage to this bead by name and told it to decide NATS-vs-SQLite itself\nrather than inherit an answer. This document is that decision.\n\n## Decision: SQLite, not NATS JetStream\n\nCaptured events are stored in archied's existing SQLite database, in a new\n`captured_events` table following the same shape as `internal/store/events.go`\n(`internal/store`, `*Store`, SQL migrations inline in Go). No JetStream\nstream is introduced for capture.\n\n### Why\n\n**NATS availability does not make capture a broker concern.** NATS is now\nunconditional for autonomous workflow handoff, including embedded mode, but\ncapture is also used by deployments with no repository workflow configured.\nSQLite is guaranteed present because it backs daemon state, and keeps\ncapture inspection independent of broker retention and consumer lifecycle.\nThe original version of this decision cited optional NATS as an additional\nreason; that premise was superseded by `archie-core-q15y`, while the storage\nfit and independence arguments remain.\n\n**Capture's access pattern doesn't need what JetStream is for.** JetStream\nearns its complexity for reaction delivery (`7d5u.2`) because multiple\nindependent consumers need fan-out, at-least-once redelivery, and Ack/Nak\nsemantics -- exactly the trap `CLAUDE.md` documents about `WorkQueuePolicy`\nand overlapping consumers. Capture has exactly one writer (the HTTP handler)\nand one reader (a human via the dashboard inspector, `t2db.2`). There is no\ncompeting-consumer problem to solve and no redelivery semantics to get right,\nso JetStream's core value proposition doesn't apply here. A bounded SQL\ntable is a better fit on the merits, not merely as a fallback.\n\n**Reusing `7d5u.2`'s stream, once it exists, would still be wrong.** That\nstream is provisioned for fan-out reaction delivery with its own retention\npolicy decision. Capture's retention need -- age- and count-bounded, prune\non write, no replay -- is a different shape. Building a second stream just\nfor capture, gated on an unrelated bead landing first, would trade a small\namount of duplication now for a hard dependency on `7d5u.2`'s timeline that\nthis bead's own acceptance criteria say not to accrue by accident.\n\nThis does not foreclose NATS later. If cross-daemon capture sharing or\ndurable replay becomes a real requirement, that is a new decision made\nagainst a real need, not now against a speculative one.\n\n## Storage shape\n\n`captured_events` table (`internal/store/captures.go`, mirrors\n`internal/store/events.go`'s pattern):\n\n| column | type | notes |\n|-----------------|---------|-------------------------------------------------|\n| id | INTEGER | primary key, autoincrement |\n| received_at | TEXT | RFC3339Nano |\n| source | TEXT | opaque path segment chosen by the sender's operator |\n| remote_addr | TEXT | `RemoteAddr` at capture time |\n| content_type | TEXT | `Content-Type` header |\n| headers | TEXT | JSON, redacted |\n| body | TEXT | JSON, redacted (`webhookguard.RedactPayload`) |\n| authenticated | INTEGER | 0/1; always 0 until a source registers a secret (future: `t2db.4`) |\n\nIndexed on `(source, id)` for per-source listing and pruning, and `id` alone\nfor the global cap.\n\n## Disk-bound mechanics\n\nThree independent bounds, composed, per `webhook-intake-security.md` point 5\nand this bead's own \"capture cannot exhaust disk\" criterion:\n\n1. **Per-request size cap.** The HTTP handler reads the body through\n `http.MaxBytesReader` (256 KiB default, configurable). A single oversized\n POST is rejected (413) before redaction or storage sees it.\n2. **Per-remote-address rate limit.** `webhookguard.RateLimiter`, keyed by\n the request's remote address, applied before the body is even read.\n *Not* keyed by the `source` path segment: `RateLimiter`'s own doc comment\n states its bucket map assumes a bounded, operator-registered key space,\n never evicted. `source` is exactly the opposite here -- an unregistered,\n attacker-chosen URL segment, since capturing senders with no registration\n yet is this endpoint's entire purpose. Keying on it would let one sender\n bypass the limit by rotating the segment every request (a fresh key\n always starts with a full burst) and grow the bucket map without bounLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/event-sources-and-reactions/",
|
||||
"title": "Event sources and reactions -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Event sources and reactions -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5`\n\nAnswers the four questions in `7d5u.1`'s description. Investigated against\nthe actual tree, not designed from scratch: three mechanisms already in this\ncodebase answer most of this, and the job here is picking the right one for\neach question and saying which packages change.\n\n## 1. In-process typed families, not out-of-process dispatch\n\nArchie has no out-of-process extension mechanism. The plugin engine\nrule (`ARCHITECTURE.md#plugin-engine-rule-strict`, mechanically checked by\n`internal/plugin/architecture_test.go`) keeps every capability family\nin-process behind a narrow typed registrar; NATS RPC exists for\ndaemon\u003c-\u003eagentexec, a different actor with a different trust boundary (task\nexecution, not third-party extension code), not a precedent for generic\nplugin dispatch. Neither epic's near-term payoff -- react to a labelled\nissue, bind a captured webhook to a workflow -- needs extension code in\nanother language or process. Building out-of-process dispatch now would be\ndesigning for a requirement neither epic states.\n\n`docs/architecture/plugins-and-extensions.md` does **not** need amending.\nThe line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes\nrecord the correction) is scoped to Workflow semantics specifically, and\nnothing decided here touches Workflow's ownership of its own contracts.\n\n## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream\n\n`internal/eventbus.Publisher`/`Consumer` already has everything a reaction\nneeds: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once\nwithout duplicate enqueue, `Ack`/`Nak` with \"a handler returning an error\ncauses redelivery.\" Do not design new delivery semantics; use this contract.\n\n**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and\n`Config.Subjects` are already composition-supplied (\"the bus must not know\nwhich subjects belong to which domain,\" `config.go`), but the\nretention policy is not parameterized: `New` hardcodes\n`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer\npolicy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by\nexactly one consumer -- and wrong for reactions. Two independent reactions\nboth wanting to see the same event under `WorkQueuePolicy` hit exactly the\ntrap `CLAUDE.md` already documents: overlapping filter subjects on a\nwork-queue stream mean the second consumer silently gets nothing. Reactions\nneed fan-out, not claim-once, so the client needs retention made a `Config`\nfield (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is\nunaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured\nunder a fan-out-capable policy, alongside the existing task-distribution\nstream -- not instead of it.\n\nThis is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS\ninstance backs `ARCHIE_TASKS` also backs the reaction stream. NATS is not\noptional as a technology -- the choice is only\nwhether it runs as an external server or embedded in-process\n(`github.com/nats-io/nats-server/v2` is already a direct, test-proven\ndependency, just never wired into production startup). `7d5u.2` wires that;\nthis document does not re-decide it.\n\n## 3. Reactions in these two epics are producer-only\n\nNo veto, no mutation of in-flight work. Two existing shapes cover everything\neither epic actually needs, and neither is a hook that can block something\nelse:\n\n- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s\n `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a\n runtime to check sooner; a dropped event only delays a check-in, never\n loses work, because the trigger decision is a deterministic state read at\n pass time, not the event payload. Model any \"check something sooner\"\n reaction on this, unchanged.\n- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -\u003e\n `publishTask` path is already exactly a reaction that observes forge state\n and produces a `workintake.TaskEnvelope`. A webhook source is a second\n producer into the same path, not a new capability -- see question 4.\n\nA reaction that can veto or mutate an *in-flight* task (block a PR from\nopening, alter a running stage) is a different, harder problem with its own\nordering and failure semantics, and belongs to `archie-core-h019` (adversarial\nself-review) if and when that epic needs one -- not here. Do not build a\ngeneral block-capable hook mechanism for either epic; nothing in their stated\nscope requires it, and it would duplicate whatever h019 eventually needs.\n\n## 4. No single generic intake interface; each domain keeps its own\n\nA `Source` interface generic enough to cover a forge issue, a chat message,\nand a cron tick would need an `any` payload -- theLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/extensions-center/",
|
||||
"title": "Extensions center",
|
||||
"section": "PRDs",
|
||||
"body": "# Extensions center\n\n**Status:** Draft\n\nEpic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` (\"Replace Skills\nwith a bundled Extensions center\").\n\nSkills, Workflows, and Tools/MCP already exist as separate, working\ninventories with their own APIs (`api_skills.go`, `api_workflows.go`,\nconfig-driven MCP servers) and their own family-owned controller pattern\n(`curator.Registry`, `health.Registry`, `image.Registry`,\n`workflow.Registry` all already prove this shape). `plugin.Plugin`\n(`internal/plugin/plugin.go`) is already metadata-only, per\n`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.\nWhat's missing, confirmed by grep, is: any config schema for enabling or\ndisabling a capability, any \"pending restart\" state tracking, and any single\ninventory that reconciles configured/bundled/discovered/active state across\nfamilies. This document decides those three things and the UI surface that\npresents them. It extends `plugins-and-extensions.md` rather than replacing\nit — that doc's decisions (metadata-only `Plugin`, typed capability\nfamilies, no generic dispatch) are unchanged.\n\nOut of scope: any remote or arbitrary-URL plugin installation path (the\nepic's own acceptance criteria forbid this, and `plugin.LoadDir`\n(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this\ndocument does not add a fetch-by-URL variant to it).\n\n## Problem\n\n`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no\n`enabled` field (confirmed by the investigation grep). `api_config.go`'s\n`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state\ndistinguishing \"saved, takes effect now\" from \"saved, needs restart\" — the\nonly existing reload path (`ReloadChannel`, `server.go`) is\nchannel-specific and explicitly does not cover plugins or MCP servers.\n`server.go` already wires five separate optional inventories\n(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as\nindependent fields with no unifying type — an operator has no single\nplace to see \"what's available, what's enabled, what's actually running,\nand what's degraded\" across all of them. `ui/src/` has `settings/`,\n`skills/`, and `workflows/` directories already; there is no\n`ui/src/extensions/`.\n\n## Design\n\n### Unified inventory type\n\n```go\npackage extensions // internal/domain/extensions — new, app-level aggregator\n\ntype State string\n\nconst (\n StateAvailable State = \"available\" // bundled, not configured\n StateEnabled State = \"enabled\" // configured on, not yet live\n StateActive State = \"active\" // configured on and running\n StateDegraded State = \"degraded\" // active but unhealthy\n StateSkipped State = \"skipped\" // optional, disabled by config\n StatePendingRestart State = \"pending_restart\" // config changed, not yet live\n)\n\ntype Entry struct {\n Family string // \"skill\" | \"workflow\" | \"tool\" | \"plugin\" | \"integration\"\n Name string\n Core bool // non-disableable\n State State\n Health string // reuses whatever the family's own registry already reports\n}\n\ntype Inventory interface {\n List(ctx context.Context) ([]Entry, error)\n}\n```\n\n**Decision.** `extensions.Inventory` is a read-only aggregator, not a new\ndomain that owns state. It queries each family's existing registry\n(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client\nset, `plugin.LoadDir`'s result) for live state, and compares that against\nthe config-desired state (below) to compute `StatePendingRestart` — the diff\nis computed on read, not persisted, so there is no new durable state to keep\nconsistent with the registries themselves. This follows\n`migration-decisions.md`'s rule that cross-cutting aggregation composes\nexisting domain-owned contracts rather than duplicating their state.\n\n**Call site.** New package `internal/domain/extensions/inventory.go`.\nComposed in `internal/app/archied` (wherever `server.go`'s other optional\nfields — Workflows, Skills, Curators — are wired) since it needs\nreferences to every family's registry, which only application-layer\ncomposition has.\n\n### Config-backed enablement\n\n**Decision.** Add `enabled bool` (default `true` for pre-existing configured\nentries, so no upgrade silently disables anything already configured) to\neach family's config element: `MCPServer.Enabled`, and equivalent fields on\nwhatever config types back skills/workflows/plugins if they don't already\nhave an on/off switch. Core capabilities (identity, workflow engine, State\nStore connectivity — named in `organisation.md`'s cross-cutting packages)\nhave no `enabled` field at all; a config value can't be added to something\nthat doesn't expose the toggle, which is the \"non-disableable\" property\nenforced structurally rathLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/image-capability-contract/",
|
||||
"title": "Image capability contract and configuration",
|
||||
"section": "PRDs",
|
||||
"body": "# Image capability contract and configuration\n\n**Status:** Approved\n\nEpic: archie-core-1786748942120-1-6636e629 / GitHub #496 (\"Image generation\ncapability: hosted API baseline plus local GPU workflows\").\n\nThe contract and configuration (#497) shipped first and is settled — see\n\"Package: `internal/domain/image`\" below. This document now covers the full\nfeature set: hosted provider (#498), local GPU provider (#499), `/image`\nrouting and clarification (#500), delivery through channels and web (#501).\nDocumentation (#502) and the cross-cutting test matrix (#503) are execution\nwork against the design below, not open design questions, so they are not\ngiven their own sections — each preceding section states its own test\nobligations inline.\n\n## Problem\n\nArchie needs a provider-neutral boundary for image generation/editing so a\nhosted API (gpt-image-2-class) and a future local GPU backend can both\nimplement it without either one leaking into the domain contract. Nothing\nin the repo defines this (`grep -ri image` over `internal/domain` and\n`internal/config` returns nothing image-specific).\n\n## Design\n\nFollows the plugin engine family shape already established by\n`internal/domain/curator` and `internal/domain/memory` (ARCHITECTURE.md\n\"plugin engine rule strict\"): a typed contract with real domain operations,\nan owning `Registry` (register/get/names, no start/stop lifecycle — see\nbelow), and narrow host access via a `Registrar`.\n\n### Package: `internal/domain/image`\n\n**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are\nlong-running — they hold a background cadence or a persistent connection\nworth health-checking. An image provider is call-scoped: it either serves a\n`Generate`/`Edit` request or it does not. Health here means \"is this\nprovider usable at call time\", which is exactly what `Generate`/`Edit`\nreturning a typed `ErrUnavailable` already communicates — a separate\n`Health()` poll would just duplicate that. `Registry` still owns\nregistration and lookup, so provider selection is testable with fakes per\nthe acceptance criteria, but there is no `Start`/`Stop` to orchestrate.\n\n```go\n// Capability declares what one provider supports, discoverable before a\n// request is built so a caller can reject an unsupported combination (e.g.\n// edit-with-mask on a generate-only provider) instead of sending it and\n// parsing a provider-specific error back out.\ntype Capability struct {\n Generate bool\n Edit bool // edit requires at least one input image\n Mask bool // edit supports a mask restricting the edited region\n MaxInputs int // 0 = Edit unsupported\n Sizes []string // provider-declared output sizes, e.g. \"1024x1024\"\n}\n\n// Provider is the typed contract every image backend implements — hosted\n// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is\n// call-scoped, not long-running (see design doc rationale).\ntype Provider interface {\n Name() string\n // Class distinguishes hosted (spends money/quota per call) from local\n // (spends host GPU/time). Selection logic and config validation key off\n // this, never off Name, so a new provider cannot silently slip through\n // the hosted-cost gate under an unrecognized name.\n Class() ProviderClass\n Capability() Capability\n Generate(ctx context.Context, req GenerateRequest) (Result, error)\n Edit(ctx context.Context, req EditRequest) (Result, error)\n}\n\ntype ProviderClass string\n\nconst (\n ClassHosted ProviderClass = \"hosted\"\n ClassLocal ProviderClass = \"local\"\n)\n```\n\nRequest/result types (provider-neutral, no OpenAI types):\n\n```go\ntype GenerateRequest struct {\n Prompt string\n Size string // \"\" = provider default\n N int // number of images; 0 = 1\n Options map[string]string // provider-specific overflow (e.g. \"quality\"),\n // deliberately untyped so the contract does not\n // grow a field per provider\n}\n\ntype EditRequest struct {\n Prompt string\n Inputs []ImageData // 1..Capability.MaxInputs\n Mask *ImageData // nil unless Capability.Mask\n Size string\n N int\n Options map[string]string\n}\n\n// ImageData carries image bytes in-process, never a path or URL: the\n// domain layer must not assume a filesystem or a fetchable location (mirrors\n// why curator's Registrar never receives *daemon.Daemon — no ambient host\n// access smuggled in through a \"just a string\" field).\ntype ImageData struct {\n Bytes []byte\n MIMEType string\n}\n\ntype Result struct {\n Images []ImageData\n Provider string\n Model string\n CreatedAt time.Time\n}\n```\n\n### Error taxonomy\n\n```go\nvar (\n ErrUnavailable = errors.New(\"image provider unavailable\") // missing credential, backend down\n ErrUnsupporteLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/inline-review/",
|
||||
"title": "Inline review -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): `` - `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e ``. That is a report *about* the code, not a review *of* it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n *conversation* (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\") has no line to attach to and stays in\nthe PR-body list. The body section keeps listing everything, so it remains the\ncomplete record and the fallback.\n\nFindings that block never reach this path: a surviving blocking finding parks\nthe task before `StageOpenPR`, so there is no PR to comment on. Inline comments\nare the non-blocking, line-anchored subset — which is exactly the set that would\notherwise be a body-only list the author has to map back to lines by hand.\n\n### 4. A best-effort stage after `StageOpenPR`\n\nNew `StagePostReviewComments`, after `StageOpenPR`:\n\n1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).\Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/mcp-tool-completion/",
|
||||
"title": "MCP client and tool-guardrail completion",
|
||||
"section": "PRDs",
|
||||
"body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serializes every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a\nparallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n|---|---|\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behavior), keep the single `callMu`\nserializing that server's calls exactly as now; when true, drop the mutex for\nthat server's `Client` instance entirely and let the caller's own\nconcurrency (already proven by the closed concurrent-dispatch bead, `#183`)\nhandle it. This is additive — no server's behavior changes unless an operator\nopts in.\n\n**Call site.** `internal/config/config.go` (struct field),\n`internal/tools/mcp/client.go` (make the mutex conditional on the\nfield), and wherever `MCPServer` configs are turned into `Client` instances\nat daemon startup (the constructor that reads `internal/config`'s MCP block).\n`config.example.toml`'s commented MCP block gets the new field documented\nwith its default.\n\n**Testing.** Unit test asserting two concurrent `Call`s to the same\n`Client` block on each other when the flag is false and don't when true —\nfakeable with a slow fake transport. `task check`.\n\n## Sandboxed MCP tool servers for the chat agent (`#178`) and Firecracker substLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/memory-engine-unification/",
|
||||
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n|---|---|---|---|\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n *does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\n string`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_sqlite.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and\n`ScopeAgent{b}` are different storage keys.\n\n`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing\nproduces one yet, but the contract models it because the read set includes it.\n\n### 2. CRUD, with revisions retained\n\n```go\ntype Store interface {\n Create(ctx context.Context, in NewRecord) (Record, error)\n Get(ctx context.Context,Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/messaging-service-boundary/",
|
||||
"title": "Messaging Service boundary and transport design",
|
||||
"section": "PRDs",
|
||||
"body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behavior, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections (`*store.Store` or SQLite), owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n|---|---|---|---|\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | `*store.Store`, `SessionStore` SQLite handles, direct database files |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n1. **Telegram long-polling**: Must call `dropPendingUpdates(ctx, b)` before `b.Start(ctx)` and on `/restart`.\n2. **Telegram command menus**: Must register command menus simultaneously to `default`, `all_private_chats`, and `all_group_chats` via `commands.go` to prevent menu shadowing.\n3. **No UI detour**: Turns and task actions route directly to Gateway's `ChatContract`; no HTTP request may ever be sent to `archie-ui` or `internal/webui`.\n4. **Sender Confinement**: Telegram sender checks against `allowed_user_ids` must continue to fail closed before initiating any turn dispatch.\n\n## Configuration Ownership\n\n`cmd/archie-messaging` reads only:\n- `[services.gateway].target` and `[services.gatewaLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/module-position/",
|
||||
"title": "Module position -- design",
|
||||
"section": "PRDs",
|
||||
"body": "# Module position -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n\n## Problem\n\n`eda-playbook-engine.md` names four logic positions a playbook action can\ntarget: Workflow, Module, Channel, Forge. Workflow (`t2db.9`/`.10`/`.11`)\nand the standalone lint tool (`t2db.12`) are shipped. Module -- the\nposition that makes an action \"not restricted to code-generation\" -- has\nnot started, because it needs a schema-generation mechanism the parent\ndoc deliberately deferred: \"This document does not attempt to design the\nfull generator.\" This is that design.\n\n## Do not invent a new mechanism -- generalize the one used three times\n\nYaegi-interpreted extension code with a fixed, resolved-by-name exported\nfunction already exists in this codebase for three surfaces, and all three\nfollow the identical shape:\n\n| Surface | Fixed signature | Export path | Symbol table |\n|---|---|---|---|\n| Custom gate (`internal/gate/gateeval`) | `func(gate.GateContext) []gate.Finding` | `\"gate.Check\"` | `gateextract.Symbols` |\n| Workflow stage plugin (`skillbuild`) | stage-specific | skill-declared | `wfextract.Symbols` |\n| Skill plugin (`internal/skill/plugin.go`) | `func(string) string` | `\"main.Run\"` | none (stdlib only) |\n\nEach is: read a `.go` file -\u003e `yaegiutil.New` with that surface's symbol\ntable -\u003e `yaegiutil.Resolve[T](i, src, exportPath)` -\u003e call the resolved\nfunction wrapped in `yaegiutil.Safe` for panic recovery. **Module is a\nfourth instance of this same shape**, parameterized by action kind instead\nof hardcoded to one fixed signature. No new interpreter construction, no\nnew panic-recovery mechanism, no new symbol-table generation tool --\n`go generate ... yaegi extract` is already how `wfextract`/`gateextract`\nare produced that way (see their `//go:generate` directives), and Module\nschema generation reuses that exact command.\n\n## No generic `Module` interface -- one typed contract per action kind\n\nThe plugin engine rule's invariant 1 requires \"real capability-specific\noperations,\" and invariant 5 forbids adding capability methods to a\ngeneric interface. A single `Module` interface with `Run(args any) (any,\nerror)` would be exactly the untyped hook the rule (and\n`event-sources-and-reactions.md`'s rejection of a generic `Source`\ninterface) exists to prevent -- restating the mistake the whole EDA\ndocument was written to move away from (`wfextract`'s hardcoded\n`reflect.ValueOf(workflow.Implement)` table is what a closed, un-typed-per-\ncase system already looks like in this repo).\n\nInstead, **each action kind is its own tiny package with its own\ngenerated contract**, exactly like `gate.GateContext`/`gate.Finding` are\none hand-written Go file that `gateextract` turns into a Yaegi symbol\ntable:\n\n```go\n// internal/domain/eda/module/notify/types.go (hand-written, the schema source)\npackage notify\n\n// SchemaVersion is independent of a playbook's own workflow_version, per\n// eda-playbook-engine.md's schema-versioning point.\nconst SchemaVersion = 1\n\ntype Args struct {\n Channel string\n Message string\n}\n\ntype Result struct {\n Delivered bool\n}\n\n//go:generate go run github.com/traefik/yaegi/cmd/yaegi extract -name notifyextract github.com/samcharles93/archie-core/internal/domain/eda/module/notify\n```\n\nA Yaegi module implementing this kind exports a fixed function name\nagainst these generated types, resolved the same way `gate.Check` is:\n\n```go\n// operator's notify.go, interpreted at load\npackage notify\n\nfunc Run(a notify.Args) notify.Result { ... }\n```\n\n`internal/domain/eda/module/notify` is the schema; `notifyextract.Symbols`\nis its generated Yaegi bridge; the operator's file is the implementation.\nThis is the same three-way split `internal/gate` / `gateextract` /\n`.archie/gate.go` already has.\n\n## The registry: `ModuleRegistry`, keyed by kind, not a service locator\n\nPer invariant 2 (owning family manager) and invariant 4 (narrow host\naccess): a `ModuleRegistry` in `internal/domain/eda/module` maps a kind\nname (`\"notify\"`, `\"image-gen\"`) to a resolved, type-erased invoker --\nthe same `map[string]reflect.Value`-shaped erasure `wfextract.Symbols`\nalready uses to bridge Yaegi and Go, not a new pattern and not exposed as\nthe plugin's contract with the daemon (the plugin still writes and is\nchecked against a fully typed `func(Args) Result`; the registry's\ninternal storage is the only place erasure appears, exactly as it already\ndoes inside `wfextract`).\n\n```go\ntype ModuleRegistry struct {\n // kind -\u003e (validate args against generated schema, invoke, marshal result)\n}\n\nfunc (r *ModuleRegistry) Register(kind string, dir string) error // discovers \u003ckind\u003e.go, resolves against that kind's generated symbols\nfunc (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[string]any) (map[string]aLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/multi-action-playbooks/",
|
||||
"title": "Multi-action playbooks and typed action results",
|
||||
"section": "PRDs",
|
||||
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define. Arg VALUE type-checking\n is tracked as `archie-core-t2db` debt, not shipped here.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo a load failure; arg value\ntype-checking is tracked as `archie-core-t2db` debt.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check. It\ndoes not invoke a Module kind. Invocation, the `playbook_dispatches` gate, and\nstop-on-first-failure across actions are `archie-core-t2db.31`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Settled: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.** Settled: one shape per playbook. A `workflow` action\nyields a task, not a rLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/news-and-releases/",
|
||||
"title": "Public news and per-version release notes -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Public news and per-version release notes -- decision\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Beads issue:** `archie-core-2ncm.2`\n\nA public news page and a release-notes page for every version. Both are derived\nfrom the changelogs the release process already produces, so publishing a\nrelease adds no writing. Part A is the derivation and the artifact any renderer\nconsumes; it is not tied to MkDocs. Part B is the MkDocs rendering that\npublishes them at `offloaded.dev/news/`.\n\n## Part A -- release facts and their derivation\n\n### Source of truth\n\nRelease notes come from `CHANGELOG.archied.md` and `CHANGELOG.archie.md`. Those\nare the release process's frozen notes: `tools/release.sh --prepare` writes a\nsection, the maintainer edits it, and `--tag` refuses to tag a version without\nits section. A page exists exactly for a release the process cut, and no second\ncopy of release prose can drift from the changelog.\n\nTags are not the source. CI and deployment check out shallow, so tags are absent\nfrom a site build; the changelogs are always present and their\n`## [\u003cversion\u003e] - \u003cdate\u003e` headings carry the same version and date the tags\ncarry. Raw commits are not the source either: the changelog is the edited text,\nnot the commit list.\n\n### What a version's notes contain\n\nThe version and date parsed from the section heading, and the section body\nunchanged. The body keeps the maintainer's headings and bullets; the generator\ndoes not regroup them into feature and fix categories, because those categories\nexist only on commits the edited changelog does not preserve.\n\n`## [Unreleased]` is skipped. Any other `## [` heading that is not\n`[version] - date` stops generation, so a malformed heading cannot silently drop\na release. A relative Markdown link in a body stops generation too: a rendered\npage sits at a different depth from the changelog, and a host's link checking\nwould fail on the dead link. Absolute links pass through.\n\n### Two components\n\n`archied` and `archie-agent` version independently and either can be held back,\nso the data carries the tag prefix (`archied`, `archie`), the product name\n(`archied`, `archie-agent`), and the version as separate fields. A release that\nmoved one component is one entry. The generator never pairs two component\nversions or invents a combined product version.\n\n### The canonical artifact\n\n`docs/news/releases.json` is the host hand-off: a committed, generated,\nnewest-first array of `{component, name, version, date, body}`. Every adapter\nrenders from this file rather than re-parsing a changelog. The JSON is the\ncontract; a host adapter may add markup, but not facts.\n\n### Zero per-release maintenance\n\n`task news` regenerates the JSON and the MkDocs pages from the changelogs.\n`task news:check` regenerates them in a temporary directory and fails when the\ncommitted files differ; it runs in `task check`, so a changelog edit cannot land\nwithout its regeneration. `tools/release.sh --tag` regenerates and stages them\nin the release commit, so a tag's tree carries its own facts.\n\nThe generator owns `docs/news/releases.json`, `docs/news/index.md` and the two\ncomponent directories end-to-end: it rewrites expected files and reports an\nunexpected file in a component directory as drift. It leaves every other file\nunder `docs/news/` alone, so a future hand-written announcement is not its\nbusiness.\n\n## Part B -- publishing\n\nMkDocs is the host. `docs/news/index.md` is the news page: date-grouped, newest\nfirst, one entry per release carrying the component, the version, and a link to\nits notes. `docs/news/archied/\u003cversion\u003e.md` and `docs/news/archie/\u003cversion\u003e.md`\nhold the notes. `site_url` is `https://offloaded.dev/`, so the pages are served\nat `offloaded.dev/news/`.\n\nThe version pages stay out of the derived navigation (`not_in_nav` in\n`mkdocs.yml`) while remaining published; the news page is their entry point, so\na version list that grows with every release cannot push the architecture tree\noff the screen.\n\nA different renderer would read `docs/news/releases.json` instead of these\nMarkdown files. That is a separate change in that renderer's repository and\ndoes not alter Part A; the JSON, not the Markdown, is the reusable half.\n\n## Not in scope\n\n- Generated summaries, categories, or section headings; the changelog has no\n structured summary field to derive one from.\n- Per-release download or install links; where to get the artifacts is\n documented once, not restated for every version.\n- Hand-written news items. The generated page lists releases.\n- Changes to `infra/ansible`. Serving the site at a hostname other than\n `offloaded.dev` is an infrastructure decision.\n\n## Verification\n\n- `go test ./tools/newsgen/...` covers parsing, ordering, rendering, the link\n and heading refusals, and check-mode drift.\n- `task news:check` passes inside `task check`.\nLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/operator-pr-review/",
|
||||
"title": "Operator-triggered PR review",
|
||||
"section": "PRDs",
|
||||
"body": "# Operator-triggered PR review\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.8`\n\nThis PRD reuses the adversarial-self-review contract\n(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /\n`workflow.ReviewReport` types from `internal/domain/workflow`. It decides\nonly what is new: how an operator asks for a review of an *existing* PR, and\nhow that PR's content reaches the reviewer.\n\n## Problem\n\nThe adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`\nand reviews the task's own worktree HEAD. There is no way to review a PR that\nalready exists: one archie opened, a human opened, or one whose findings the\noperator wants re-checked after a push.\n\n## Shape\n\nOne channel-neutral command — `review_pr` — accepts a repository and PR number\nand returns the structured `ReviewReport`. The Web UI chat and Telegram invoke\nthe same command; neither duplicates review behaviour. The reviewer model is\n`models.reviewer` (falling back to `models.builder`), already the rule the\nworkflow stage uses, so an operator configures it independently of\nplanner/builder.\n\n## Decisions\n\n1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a\n forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,\n BaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,\n implemented by GitHub and Gitea; the noop forge does not implement it, so\n the composition root type-asserts and refuses review with \"forge does not support PR\n review\". Adding to the fat `Forge` interface would churn every test fake for\n a capability the noop forge cannot honestly provide.\n\n2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,\n baseRef)` clones the repository fully and checks out `origin/\u003cheadRef\u003e`.\n `Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:\n `Diff` resolves `origin/\u003cbaseRef\u003e` via the existing `resolveBase`, and\n `Snapshot` strips `.git` exactly as the workflow stage does. The head must\n already be pushed to the same repository — archie's own PRs always are; a\n cross-repo or deleted head is refused with that reason, not half-reviewed.\n\n3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`\n builds the same `subagentReviewer` the stage uses, from daemon-level config\n rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`\n gate (the operator asked explicitly) and the task-run scaffolding.\n\n4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the\n channel's identity at construction — the model never names an identity,\n matching `task_spawn`/`task_action`. The Gateway process serves it: it\n composes the worktree manager it needs to materialise the PR head, and the\n composition root supplies `ChatPRReviewer`, a narrow gateway interface\n whose adapter maps `workflow.ReviewReport` into a gateway-owned result\n shape (gateway states what it needs, the composition root adapts — the\n `ChatTaskActor` pattern).\n\n5. **Authorization.** Identity-scoped repository allow-list, the\n `task_spawn` rule: a chat identity may only review a repo in its\n `TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard\n operator who may review any configured repository.\n\n6. **Determinism.** One review per (owner, repo, number) at a time: the\n Gateway holds an in-flight set; a concurrent request for the same PR returns\n \"review already in progress\" rather than launching a second reviewer and\n racing on the snapshot.\n\n## Files\n\n- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,\n `PullRequestReader`, `GetPullRequest`.\n- `internal/worktree/worktree.go` — `CheckoutPR`.\n- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.\n- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.\n- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.\n- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.\n- `internal/app/archied/{bootstrap.go,gateway.go,main.go}` — composition.\n\n## Not in scope\n\n- Surfacing findings on the PR body or the dashboard (h019.6).\n- Reviewer model per-invocation override: configuration via `models.reviewer`\n is the selection surface; a per-call override is a later knob.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/payload-field-mapping/",
|
||||
"title": "Payload field mapping -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Payload field mapping -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`\n\nAnswers what a \"mapping\" is, where it lives, and what \"resolve against a\nreal event\" means precisely enough to implement. `t2db.4` (binding: matcher\n+ mapping + workflow) is out of scope -- this bead ships the mapping\nconcept and its preview only, as a standalone entity `t2db.4` will later\nreference by ID.\n\n## Decision: a new `internal/domain/mapping` package, SQLite storage\n\n`internal/domain/mapping` owns the mapping vocabulary and the pure\nresolve/preview rule; `internal/store` persists it (mirrors\n`captures.go`'s shape exactly -- inline schema const, narrow store\ninterface, `*store.Store` implementation); `internal/webui/api_mapping.go`\nis the transport. This follows `docs/prds/event-capture-storage.md`'s own\nplacement precedent: `internal/store` is where this daemon's persistence\nalready lives, not `internal/infrastructure` (that layer holds\ncross-domain services -- config, eventbus, modelcatalog -- not this\ndaemon's primary store).\n\n### Why a domain package and not just a store table\n\nResolving a path against a payload and deciding \"missing vs null vs\ntype-changed\" is a rule, not a query -- CLAUDE.md's domain layer owns\n\"language, state, rules, operations\" precisely so this logic is testable\nwithout a database and reusable by `t2db.4`'s runtime trigger path without\neither package importing the other's transport concerns.\n\n## Mapping shape\n\n```go\ntype Mapping struct {\n\tID int64\n\tName string\n\tSourceHint string // free-text label (e.g. \"sentry\"), organisational only -- not enforced against Capture.Source\n\tFields []Field\n\tCreatedAt time.Time\n\tUpdatedAt time.Time\n}\n\ntype Field struct {\n\tName string // the name the workflow receives\n\tPath string // dot/bracket path into the payload, see below\n\tType FieldType // expected type, checked at resolve time\n\tRequired bool // Required=false + missing is not a failure; Required=false + wrong type still is\n}\n\ntype FieldType string // \"string\" | \"number\" | \"bool\" | \"object\" | \"array\" | \"any\"\n```\n\n`SourceHint` is advisory only: an operator authors a mapping by clicking\nthrough one example capture, but the mapping is not pinned to that\ncapture's exact source string, because `t2db.4`'s matcher (not this bead)\ndecides which events a binding applies to. Pinning here would duplicate\nthat decision in the wrong layer.\n\n## Path syntax\n\nDot-separated keys with `[N]` for array indices: `data.items[0].id`. No\nwildcards, no filters, no external library -- the grammar is exactly what a\nclick-through UI needs to express (this key, then this key, then this\nindex), and every path in a mapping was generated by clicking a value in a\nreal payload, never hand-written against a spec. A hand-rolled parser\n(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new\ndependency for a grammar this small.\n\n## Resolve semantics (the preview AND the future runtime path)\n\n```go\nfunc Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)\n\ntype Failure struct {\n\tFieldName string\n\tPath string\n\tReason string // \"missing\" | \"null\" | \"type_mismatch\"\n}\n```\n\nDecode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s\nexisting convention) so int/float distinction survives for type checking.\nWalk each field's path independently -- one field's failure does not stop\nresolution of the others, because the whole point of preview is showing\nthe operator every problem at once, not the first one.\n\n- Path segment doesn't exist, or indexes past an array's length -\u003e `missing`\n- Path resolves to JSON `null` -\u003e `null`\n- Path resolves to a value whose JSON type doesn't match `Field.Type`\n (`\"any\"` always matches) -\u003e `type_mismatch`\n- `Required: false` suppresses `missing` only, never `null` or\n `type_mismatch` -- a field that's present but the wrong shape is always\n worth surfacing, since silently coercing it is exactly the \"agent\n confabulates around a blank field\" failure this bead exists to prevent.\n\n**This is the same function both consumers use.** `t2db.3`'s preview calls\nit against an operator-picked capture and renders every result, pass or\nfail, in the UI -- that satisfies this bead's \"fail loudly\" acceptance\ncriterion, because at this stage the only runtime consumer of a mapping\n*is* the human previewing it. `t2db.4` will call the identical function\nwhen a live event triggers a binding and turn any non-empty `failures` into\na visible operator-facing failure (park the task / surface in the\ninspector) instead of starting a workflow with blank fields -- that wiring\nis `t2db.4`'s job, not duplicated here.\n\n## Storage\n\n`internal/store/mappings.go`, `field_mappings` tabLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/playbook-expression-syntax/",
|
||||
"title": "Playbook data-flow and condition syntax",
|
||||
"section": "PRDs",
|
||||
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\nUnbuilt decisions: `archie-core-t2db.25` (J1 action ids),\n`archie-core-t2db.26` (J2 args as CEL),\n`archie-core-t2db.27` (Result schemas declared to CEL).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a\ncondition deciding whether the action runs; (b) a later action's `args`\nvalues referencing an earlier action's `Result` and the triggering\nevent's fields. Both are **CEL expressions**, evaluated against one\nevaluation context. There is no separate interpolation syntax: CEL\nreads nested maps and fields natively, so `args` values that need data\nare written as CEL, and only plain literal args remain plain YAML\nscalars.\n\nBoth halves are read-only: expressions may read context values and\ncompute a result from them, never mutate, never call host functions,\nnever perform I/O. CEL enforces this structurally (no side effects,\nlinear evaluation when macros are bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: 'actions.build.result.written == true'\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged**\n-- the same tier as `ModuleDir`/`PluginDir`/`SecretEngineDir`\n(module-position.md's trust-boundary section): loaded from a configured\ndirectory at startup, never from a webhook body or task worktree. The\nschema-by-example flow uses live events to *design against*; the saved\nplaybook is operator-authored file content in an operator-configured\nlocation.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not\n attacker input; no sandboxing against a hostile expression string is\n required. If a future playbook source is less trusted (auto-generated\n bindings from unauthenticated captures), that is the playbook-file\n trust tier moving -- the loader's acceptance check is the right\n place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook\n body, prior results through the same pipeline). Robustness against\n hostile data is required: no panic on wrong-typed/missing fields,\n no unbounded cost on deep/cyclic maps, bounded evaluation time. CEL\n provides this structurally (cost limits, linear non-Turing-complete\n evaluation, error values instead of panics -- verified in the\n vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go\n(`.archie/gate.go`) as the repo's conditional-logic precedent. That is\nthe wrong precedent for playbook conditions because this document's\npremise is: **YAML is pure orchestration data; Yaegi is where\nimperative logic lives** (Problem section; module-position.md's\n\"no generic hook\" section). Yaegi snippets in YAML would move\nimperative logic into the data layer -- the inversion this design\nexists to prevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data,\nnot programs**. CEL is non-Turing-complete and side-effect-free, so it\ncannot become a program; a condition that needs real logic gets a\nModule kind (Yaegi), referenced by the action, not a stronger\nexpression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an\n`any` payload; it exists to keep static implementation contracts\ntyped. Evaluating CEL against runtime `map[string]any` is **not the\nsame problem**: the rule concerns *implementation contracts* (static\noperations a capability family exposes), not *runtime data values*\n(legitimately dynamic -- an event payload's shape is unknown until it\narrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the\nplaybook engine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch\ntime:\n\n| Name | Type | Source |\n|---|---|---|\n| `event` | `map(string, dyn)` | The triggering event's decoded payload (webhook body / forge issue / schedule tick). Field access via `event.\u003cfield\u003e`, map access via `event[\"field\"]`, presence via `has(eventLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/pr-review-remediation/",
|
||||
"title": "PR review comment remediation -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the adversarial review\nepic's isolation contract (`docs/prds/adversarial-self-review.md`) and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened *and still owns*.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/store/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyed on `(owner, repLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/progressive-tool-disclosure/",
|
||||
"title": "Progressive tool disclosure (bridge tools) — wiring",
|
||||
"section": "PRDs",
|
||||
"body": "# Progressive tool disclosure (bridge tools) — wiring\n\n**Status:** Finalised\n**Date:** 2026-08-15\n**Compound:** the \"keep the LLM tool schema small, give full access on demand\" work (issue #167)\n\n## Decision\n\nThe bridge-tool pattern is **implemented and tested** in\n`internal/tools/disclosure.go` (`tool_search`, `tool_describe`, `tool_call`\n+ `ContextPressureGate` + `DisclosureMode`, section 17.14/17.15) — but it is\n**never wired into the daemon**. `BridgeTools` and `ContextPressureGate` are\nreferenced only in `disclosure_test.go`. This task is therefore a **wiring**\ntask, not a feature build.\n\nWire the existing bridge into the per-chat-turn toolset:\n\n1. **Compose a per-turn registry** seeded from the base registry plus the\n per-turn extra tools, register the bridge tools into it, and hand it to both\n the bridge handlers and the `ContextPressureGate`.\n2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`)\n so it decides full-vs-bridge disclosure per turn, and build the\n `core.ToolSet` from the gate's filtered output.\n3. **Thread the model's context window** into the preparation seam so the gate\n has a real `ContextWindowSize` (it disables itself at 0, falling back to\n full disclosure).\n\n## Why the naive \"register extras into the base registry\" is wrong\n\n`BuildToolSetFrom` (`internal/agentexec/toolset.go`) documents the invariant:\n\n\u003e the task tools carry the calling gateway's identity, so there is one set of\n\u003e them per gateway and they **cannot live in the process-wide registry**.\n\nThis is confirmed by wiring: gateways are per-channel\n(`telegram_setup.go` build a `TurnRunner` per channel), and the extra\ntools (`task_*`, `session_*`, `dashboard_*`) close over that channel's identity\nvia `TurnRunnerConfig` (`turn.go`). Registering them into `b.toolReg` would\nlet channel A's session/identity-bound tools be invoked by channel B — a real\ncross-channel privilege bug. The bridge handlers iterate `reg.All()`\n(`disclosure.go`), so the extras must be discoverable; the fix is a\n**per-turn composed registry**, not a mutation of the process-wide one.\n\n## Shape of the change\n\n### 1. Per-turn composed registry + gate inside `chatGenerateOptions`\n\nReplace the current base-set + extra-set merge (`main.go`) with a single\ncomposed-registry pass:\n\n```go\n// new helper, in internal/tools/disclosure.go or the archied wiring package\nfunc ComposeForTurn(reg *tools.Registry, extra []tools.ToolEntry) (*tools.Registry, error) {\n composed := tools.NewRegistry()\n for _, e := range reg.All() {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n for _, e := range extra {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n if _, err := composed.RegisterBatch(tools.BridgeTools(composed)); err != nil {\n return nil, err\n }\n return composed, nil\n}\n```\n\n`chatGenerateOptions` then:\n\n```go\ncomposed, err := ComposeForTurn(registry, extra)\n// ...\ngate := tools.NewContextPressureGate(contextWindow)\ngate.SetAlwaysVisible(...) // e.g. session/session_resume, task/task_list\ndisclosed := gate.FilterTools(composed)\ntoolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)\n```\n\n`FilterTools` (`disclosure.go`) already returns `all` in full mode and\n`bridge + always-visible` in bridge mode, and `BuildToolSetFrom` re-applies\navailability/approval/schema rules, so the two layers compose cleanly.\n\n### 2. Thread context window through the preparation seam\n\n`ContextPressureGate` disables at `ContextWindowSize == 0`. The model context\nwindow is resolved in `TurnRunner.prepareTurn` (`turn.go`) but is not\npassed to `TurnModel.Prepare`. Extend the seam:\n\n```go\ntype TurnPrepareContext struct {\n Model string\n Extra []tools.ToolEntry\n ContextWindow int // model's context window in tokens; 0 = gate disabled\n}\n```\n\n`TurnModel.Prepare(ctx, context TurnPrepareContext)`; `prepareTurn` fills\n`ContextWindow` from `modelDetails.ContextWindow`. This touches one interface\n(`turn.go`), one production impl (`chat_turn_model.go`), and the test\nmock (`turn_test.go`).\n\n### 3. Bridge-handler parity note\n\n`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go`), bypassing\n`toolExecute` — so a `tool_call` invocation does **not** apply `CapPayload` /\n`MaxResultSizeChars` spilling or `OnToolCall` reporting, and it pre-refuses\n`RequiresApproval` tools (`disclosure.go`). This is acceptable for the\nfirst wiring (the bridge is read-discover/describe plus a guarded call), but a\nlater hardening should route the invoked tool through the same\ncap/approval path the model's direct call uses. Recorded as a follow-up, not a\nblocker for this task.\n\n## Files touched\n\n- `internal/app/archied/main.go` — `chatGenerateOptions` composes + gates.\n- `internal/app/archied/chat_turn_model.go` — `PreLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/public-and-dev-docs/",
|
||||
"title": "Public and development documentation -- design",
|
||||
"section": "PRDs",
|
||||
"body": "# Public and development documentation -- design\n\n**Status:** Draft\n**Date:** 2026-09-22\n\n## Problem\n\nOne published set carries both kinds of document. A reader who wants to know\nwhat Archie is and how to point an event at it lands in a sidebar that also\nholds the repository organisation rules, the migration decision register, the\npackage review procedure and five PRDs. The PRDs are there for a reason that\nhas nothing to do with the reader: settled architecture cites them, and the\ngenerator refuses a link whose target it holds back, so publishing them was the\nonly way to keep those citations alive.\n\nMixing them is not an exposure problem. Every one of these documents can be\npublic. It is a navigation problem: a customer reading the site meets\ncontributor material with no signal that it is not for them.\n\n## Decision\n\nOne source tree, two published sets, two artifacts, two URL bases.\n\n| Set | Holds | Served under | Artifact |\n|---|---|---|---|\n| Public | `index.md`, `guides/` | `/docs/` | `docs/data/generated/docs.json` |\n| Development | `architecture/`, `prds/` | `/dev/` | `docs/data/generated/dev-docs.json` |\n\n`archive/`, `inspiration/`, `news/` and `github-token.md` stay out of both, for\nthe reasons the generator already records.\n\nThe two artifacts have the same shape. A renderer reads a second file and\nserves it under a second base; it needs no new field and no set discriminator,\nbecause the file a page arrived in is the set it belongs to.\n\n## Consequences the design depends on\n\n**Every PRD publishes.** Selective PRD publication existed to keep citations\nfrom settled architecture working. With both cited and citing documents in the\ndevelopment set, that pressure is gone, and the rule that produced it goes with\nit: `prds/` is a development tree, not a list of exceptions.\n\n**Cross-set links resolve.** A link from a public page to an architecture page\nrewrites to the development set's absolute path, and the reverse works the same\nway. Both sets are generated in one pass over one url map, so a link and its\ntarget cannot disagree about where the target lives. The generator's refusal\nstill fires, now only for a target genuinely in neither set.\n\n**Assets keep the public base.** `docs/public/` is one file set, referenced\nfrom either set, and serving one file under two paths would invent a second\nlocation for it.\n\n**The sidebar stays derived from the directory layout**, per set. A page added\nunder a directory appears without a second edit, which is the property the\ncurrent generator has and the reason its tree mirrors the tree on disk.\n\n## The public set is thin, and that is the honest state\n\nTwo pages: the landing page and the playbook guide. Nothing is lost by the\nsplit, because a reader was never served by the seventeen architecture pages\nnext to them. The pages a public site needs (installation, configuration\nreference, the event sources, the actions a playbook can run) are written into\n`guides/` and a `reference/` tree as they are written, and each lands in the\npublic set with no generator change.\n\n## Verification\n\n- `task docs:artifact` writes both files; `task docs:artifact:check` fails on a\n stale copy of either, without touching the tree.\n- A link from the public set to a development page, and a link the other way,\n each resolve to the other set's base path in the generated body.\n- A link to a page in neither set fails the generator, naming the file, the\n line and the target.\n- `docsgen` accounts for both artifacts, so neither tool reports the other's\n file as unowned.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/review-calibration/",
|
||||
"title": "Review calibration -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\nDecides the half of calibration `docs/prds/adversarial-self-review.md` left\nopen: \"the adversarial-confirmation mechanism that keeps a finding from\nsurfacing on a single reviewer's say-so.\"\n\n## The problem, precisely\n\nThe shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)\nalready makes only a **confirmed** error-level finding block\n(`Blocking() == Verdict == confirmed \u0026\u0026 Level == error`), and a zero-finding\nreview is already distinguishable from one that never ran (`ReviewStatus`).\nWhat is missing is the other half: a reviewer can report *nothing*\nand say only \"I found nothing\" in free text. The operator cannot tell \"I\nchecked the five things that matter and they are clean\" from \"I did not look.\"\nThat is the failure the epic names -- a findings surface that consumes attention\nwithout earning trust.\n\n## Decisions\n\n### 1. \"Checked and cleared\" becomes structured, not prose\n\n`ReviewReport` gains `Checked []ReviewCheck`:\n\n```go\ntype ReviewCheck struct {\n Property string // what was verified clean, e.g. \"nil-safety of Foo callers\"\n Evidence string // how it was verified, e.g. \"read all 4 callers; each nil-checks\"\n}\n```\n\n`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:\na check without evidence is an assertion, and the whole point is to separate a\nverified property from an unexamined one. A zero-finding review is credible\nonly when it lists what it checked.\n\n### 2. Report checks through a typed tool, like findings\n\nThe reviewer calls a new capture tool `record_checked` (mirroring\n`record_finding`) once per property it verified clean. The same environmental\nargument as findings applies: the reviewer cannot end its turn having silently\nskipped the checklist. `ReviewReport.Summary` stays as the human overview.\n\n### 3. Style nits are out of contract\n\nA finding must describe wrong behaviour or a crash. Style, formatting, naming,\nand preference nits are explicitly out of contract -- they are the padding that\ntrains the operator to skim. Stated in the reviewer prompt and in the\n`ReviewFinding` type's own documentation. Not machine-enforced: deciding \"is\nthis a style nit\" from free text is unreliable, and a wrong rejection is worse\nthan a tolerated one. The category enum already has no style bucket; the rule\ncloses the gap that would otherwise let one hide under `other`.\n\n### 4. Surfacing\n\nThe PR-body findings section lists the cleared properties alongside findings,\nso \"ran and found nothing\" arrives with its evidence. (Park reasons keep\nrendering only blocking findings -- what a human needs to act on, not the full\nchecklist.)\n\n## What this does not decide\n\n- Adding a second, independent reviewer pass. The verdict distinction plus the\n recorded checks is the confirmation mechanism; a second model pass is a\n separate, heavier decision and nothing in `h019.5` requires it.\n- How many findings can survive before `MaxSteps` is exhausted (a budget\n question, already satisfied by the per-stage budget).\n\n## Packages this touches\n\n- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.\n- `internal/app/agentworker` -- `record_checked` tool, prompt rules.\n- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/runtime-control-plane/",
|
||||
"title": "Runtime control plane",
|
||||
"section": "PRDs",
|
||||
"body": "# Runtime control plane\n\n**Status:** Approved \n**Date:** 2026-09-20 \n**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`\n\n## Outcome\n\nArchie can be managed from the Web UI or a messaging channel. Both use the same\nAPI.\n\n## Model\n\nEach feature owns its settings and commands. The database stores them. There is\nno global configuration document.\n\nThis includes:\n\n- workflows;\n- identities and bindings;\n- providers and models;\n- repository policies;\n- channels and schedules;\n- capture mappings and bindings;\n- tool settings;\n- prompts and personas;\n- plugin settings.\n\nPlugin code remains installed code. Only its settings are stored in the\ndatabase.\n\nEach feature defines its data, validation, permissions, editor fields, and how\nchanges take effect. Each feature also defines its allowed actions. For example,\nidentities can be created, suspended, and retired.\n\nRepository and identity settings remain separate. They are not stored as large\nrecords that unrelated features must share.\n\nThe State Store process hosts the control-plane API on its existing gRPC server.\nNo new process is added. Feature code validates changes. Storage code only\nwrites versions and audit records.\n\nEvery write records who made it, where it came from, a request ID, and the\nversion being edited. The API layer sets the actor; the request body cannot.\nThe server validates the change, then writes it with its audit record. It rejects\nedits to an old version.\n\n## API\n\nThe API has four operations:\n\n1. **Catalog** tells clients what can be viewed or changed and how to edit it.\n2. **Query** reads data and versions without exposing secrets.\n3. **Command** asks the owning feature to make a change.\n4. **Watch** streams changes and errors to clients.\n\nComplex features can use custom screens. They still use the same commands.\n\nA dashboard session or channel sender must map to an Archie identity before it\ncan run a command. Messaging syntax maps to the same commands as the Web UI.\n\n`archie-ui` receives only an API client. It does not receive a database handle,\ndaemon pointer, global configuration object, or secret value.\n\nThe database stores the requested settings. Each process reports the version it\nis using or why it failed. The UI shows both.\n\nSome changes require a restart. The UI shows them as pending. When a live change\nreplaces a running component, Archie starts and checks the new one before\nswitching. If the check fails, the old one keeps running.\n\n## Bootstrap, migration, and recovery\n\nBootstrap contains only the database path, listen addresses, credentials, TLS,\nand encryption-key references. State Store and control-plane RPCs use the same\nendpoint.\n\nWhen upgraded, existing instances are migrated to the database. Existing\ndatabase values are not overwritten. After migration, settings in TOML are\nignored and cannot block State Store startup.\n\nThe Web UI remains available when `archied` or Gateway is down. It shows failed\nchanges and can correct or roll them back.\n\nOffline commands can back up, restore, validate, and roll back the database.\nRecovery does not require `archied` or the Web UI. The database stores secret\nreferences, not secret values.\n\n## Workflows\n\nUsers create and edit workflows in the Web UI. Workflows are stored as versioned\nYAML. Built-in workflows can be overridden and restored.\n\nA workflow is a list of steps. Each step has a known type and its own settings.\nPlugins can add step types. Each run keeps the workflow version it started with.\n\nYaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful\nbehavior must first be available as normal workflow steps.\n\n## First implementation\n\nThe first implementation makes task limits editable: maximum model steps,\nmaximum runtime, and maximum consecutive gate failures.\n\nIt includes:\n\n- validated task-limit fields;\n- version history and audit records;\n- the four API operations;\n- authenticated Web UI and messaging access;\n- live updates and apply status;\n- a Pinia-backed editor in the Web UI;\n- a messaging command using the same API;\n- migration of existing `[budgets]` values;\n- an end-to-end restart test.\n\nRunning tasks keep the limits they started with. New tasks use the latest applied\nversion. This replaces the old settings overlay instead of extending it.\n\n## Not included in the first implementation\n\n- Moving bootstrap or secret values into normal settings.\n- A generic JSON editor.\n- Rebuilding every settings screen at once.\n- Changing the limits of a running task.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/self-update-transaction/",
|
||||
"title": "Self-update: artifact install, topology migration, journaled transaction",
|
||||
"section": "PRDs",
|
||||
"body": "# Self-update: artifact install, topology migration, journaled transaction\n\n**Status:** Draft\n\nEpic: `archie-core-hj1t` / GitHub `#804` (\"[EPIC] Self-update: artifact\ninstall, topology migration, journaled transaction\").\n\nThe update *contract* (`internal/releaseupdate`: `Catalog.Check`,\n`Installer.Install`, plus defer/watchdog/verify) is settled and unchanged by\nthis document — it stays a thin Go interface shelling out to\n`CommandCatalog`/`CommandInstaller`. This document decides what the reference\nadapter scripts (`scripts/archie-update-{check,install,watchdog}`) and\n`install.sh` do behind that contract, and settles the one thing the epic's\nown description got wrong: the dist-zip **is** already attached to GitHub\nReleases (`.github/workflows/deploy.yml`, `gh release upload`), not\nActions-artifact-only. Artifact install is therefore a smaller change than\nthe epic assumed — pointing the installer at an existing asset, not standing\nup new CI publishing. Topology migration and the journaled transaction are\ngenuinely greenfield: no topology-detection or transaction-journal code\nexists anywhere in the tree.\n\nOut of scope: rewriting the `internal/releaseupdate` Go interfaces\nthemselves, and any UI for triggering updates (channel dispatch, e.g.\nTelegram `/update`, is unaffected — this only changes what happens once an\ninstall is triggered).\n\n## Problem\n\n`scripts/archie-update-install:139-160` clones and compiles from source on\nevery update — the only path that exists. `deploy.yml` already publishes a\nper-platform archive plus (implicitly) checksums as a release asset, so the\nscript not using it is a missed-reuse gap, not a missing-CI gap.\n`install.sh:414-445` writes only `archied.service` while every shipped\ndeployment profile (`deployments/*.toml`) declares `[services.state]` and\n`[services.gateway]` sections needing their own units — a fresh install\nalready reproduces the broken single-unit shape `deployment_contract_test.go`\ndoesn't even catch, because that test only checks profile\nsyntax, not installed topology. No code anywhere enumerates which systemd\nunits exist on a host or compares that against what a release requires — the\ndaemon fails at `bootstrap.go`'s `[services.state].target` check with no\nprior diagnosis. The self-refresh trap is confirmed at\n`scripts/archie-update-install:195-199`: new adapter copies land on disk but\nbash keeps executing the in-memory copy, so a pre-flight check added to the\nscript only protects the *next* update.\n\n## Design\n\n### Artifact install (`#804` item 1)\n\n**Decision.** `CommandInstaller`'s default script downloads the per-platform\narchive plus `SHA256SUMS` from the GitHub Release that `Catalog.Check`\nresolved (the same release `deploy.yml` already publishes to), verifies the\nchecksum, and stages it — it does not clone/compile. Source build\n(`scripts/archie-update-install`'s current clone+compile body) is kept as an\nopt-in path selected by an explicit `--from-source` flag or\n`ARCHIE_UPDATE_SOURCE_BUILD=1` env var, never the default, since a compile-on\nevery-host update is strictly slower and has a larger failure surface than\ndownloading a signed asset that CI already produced.\n\n**Call site.** `scripts/archie-update-install` — replace the clone+compile\nbody with a download-and-verify step; move the existing\nclone+compile body behind the opt-in flag rather than deleting it.\n`internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged —\nit already just shells out.\n\n**Reuse check.** `deploy.yml` already builds and publishes the\narchive and uploads it as both an Actions artifact and a release asset; no\nnew CI work is needed, only pointing the installer at what exists.\n\n**Testing.** Checksum-verification logic is a shell function, testable with\na fixture archive + `SHA256SUMS` pair — add to whatever test harness already\ncovers `scripts/`. Full download-from-real-release is a manual smoke command\n(document the exact `archie-update-check`/`--dry-run` invocation once built),\nnot `task check`.\n\n### Topology migration (`#804` item 2)\n\n**Decision.** Add a topology *observer* to the daemon, not the shell\nadapter — CLAUDE.md's own \"known trap\" note says the shell copy is defence\nin depth only, and the daemon is what \"knows the deployment and holds the\napproved snapshot.\" The observer inspects which systemd user units exist\n(`systemctl --user list-unit-files 'archie*.service'` or equivalent) and\nwhich config sections are present (`[services.state]`, `[services.gateway]`,\nUI service config), producing an `ObservedTopology` value with one field per\nunit: present/absent, and the config sections backing it. Each release's\n`release.json` (already produced by `deploy.yml` per the artifact-install\nwork above) gains a `required_topology` field naming the units and config\nsections that release's binaries need. `Catalog.Check` compares observed\nagainst requireLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/service-decomposition/",
|
||||
"title": "Service decomposition -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the *processes* running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n|---|---|---|\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/store` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n + EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHEL / Ansible Automation Platform\nmodel: one architecture, sold both ways. This PRD does not decide the\nbusiness model; it decides that the architecture must not foreclose\neither shape.\n\n## Why this shape\n\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`\nestablished that Archie's existing domain split already does what AWX's\nservice-decomposition post argues for -- boundaries exist. What didn't\nexist was deployability: `internal/webui` was not a passive frontend. The\nre-baselined coupling inventory is below, and the ratified boundary is\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n- Telegram task actions now call Gateway's `ChatContract` directly through\n `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.\n- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct\n `SessionStore`, `Router`, and `TurnHistory` access is historical.\n- The third coupling is closed. UI extraction shipped (`archie-core-8cda.5`,\n closed 2026-09-11): `cmd/archie-ui` serves the dashboard against remote\n Gateway and State Store contracts, holds Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/service-registry/",
|
||||
"title": "Service registry — one declaration per service",
|
||||
"section": "PRDs",
|
||||
"body": "# Service registry — one declaration per service\n\n**Status:** Draft\n**Supersedes:** `state-store-contract.md` §10's `State ServiceConnection`\nstruct-field instruction.\n\n**Base:** the `listen` field, `internal/app/archied/listen.go`, and the listen defaults cited\nbelow exist on `feat/attempt-attribution`, not on `main`. This design therefore lands on top of\nthat branch: `RegisterService`'s `listen` argument has nothing to carry without it.\n\n## Problem\n\nA service is already one Go type, `config.ServiceConnection`. What is duplicated is its\n**name**, in three layers:\n\n| Layer | Location | What is hard-coded |\n|---|---|---|\n| Declaration | `internal/config/services.go` | `Gateway` and `State` as struct fields |\n| Defaulting | `internal/infrastructure/configuration/defaults.go` | three `if cfg.Services.X.Y == \"\"` branches |\n| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go` | `cfg.Services.State` / `cfg.Services.Gateway` field access |\n\nAdding a service means editing all three. The drift this permits is already visible:\n`stateStoreResolvedToken` (`state_store_client.go`) and `gatewayResolvedToken`\n(`chat_service.go`) are byte-identical apart from the env var name, and\n`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing\nstating that asymmetry in one place.\n\n`resolveServiceListen(service, flagValue, configured)` (`listen.go`) is already\nname-parameterised. It is the shape the rest should follow.\n\n## Decision\n\n**Key services by name, and carry per-service asymmetry as registration data.**\n\n### 1. Declaration collapses to a map\n\n```go\n// internal/config/services.go\ntype Services map[string]ServiceConnection\n```\n\n`ServiceConnection` is unchanged. The TOML shape is unchanged, so no deployment profile,\n`config.example.toml`, or `install.sh` edit is required. An unrecognised `[services.foo]`\ndecodes without a code edit, satisfying criterion 5.\n\n### 2. Registration is the single entry point\n\n```go\n// internal/config/servicespec.go\nfunc RegisterService(context, name, target, listen, tokenEnv string)\n```\n\nregistered once per service, at package init in `internal/config`:\n\n```go\nRegisterService(\"both\", \"gateway\", \"127.0.0.1:8585\", \"127.0.0.1:8585\", \"GATEWAY_TOKEN\")\nRegisterService(\"client\", \"state\", \"\", \"127.0.0.1:9090\", \"STATE_STORE_TOKEN\")\n```\n\nPositional, five strings, as the story specifies. Each argument is data the current code\nstates in prose or in a branch:\n\n- `context` is `client`, `server`, or `both`, and decides which fields must resolve\n non-empty. `RegisterService` enforces it: an unknown context, or a hosted service with\n no default `listen`, panics at registration. Registrations come from this repository's\n own `init()`, never from operator input, so an invalid one is a programming error with\n no caller positioned to handle an error return. A documented-but-unread `Context` would\n be worse than no field at all.\n- `target` is the **default**, and an empty default means the operator must supply one.\n That single convention replaces the `state.target` required / `gateway.target` defaulted\n asymmetry with no branch: `state` registers `\"\"`, `gateway` registers an address.\n- `listen` is the default listen address, feeding the existing\n flag → `[services.\u003cname\u003e].listen` → default precedence unchanged.\n- `tokenEnv` names the fallback env var, replacing the two copied resolvers with one.\n\n### 3. Defaulting and consumption become loops and lookups\n\n`applyDefaults` iterates the registry instead of naming services. Consumers read\n`cfg.Services.Get(\"state\")`, returning a `ServiceConnection` plus the spec, so\n`stateStoreResolvedToken` and `gatewayResolvedToken` collapse into\n`Services.ResolvedToken(name, secrets)`.\n\n## Criteria satisfied\n\n1. Declared once, in the `RegisterService` call.\n2. No second location can contradict it; the map has no per-service fields to disagree with.\n3. Registration is the entry point, with the five fields a service has.\n4. A new service is one `RegisterService` line: no field, no default branch, no consumer edit.\n5. The set of services is registry data, not a struct definition.\n\n## Scope and risk\n\n- `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts\n its own ratified authority. Its summary (`:7`) already says `[services.\u003cname\u003e]`.\n- A typo'd `[services.gatway]` is **reported** (`UnknownKeys = [services.gatway,\n services.gatway.target]`), because the struct form leaves it in `toml.MetaData.Undecoded()`.\n A map decodes any section, so preserving that is a requirement, not an optional extra:\n `unregisteredServiceKeys` asks the registry which names exist. This costs nothing in\n extensibility, because the answer comes from registration data rather than a fixed list.\n TheLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/session-memory-curator/",
|
||||
"title": "Persistent session-memory curator (reference implementation) -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Persistent session-memory curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499114`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** `archie-core-1786637499636` (bind curators to memory\nengines, shipped) and the `domain/memory` engine family (shipped)\n\n## Decision\n\nEach pass: find sessions with activity since the last pass, ask the\nmodel to extract a short list of durable observations from each one's\nrecent messages, and write each through the curator's bound memory\nengine. Extraction is **scoped to one session** -- `Observation.Identity`\nis the session ID, not a user or cross-session identity. No\nconsolidation across sessions, no forgetting, no rewriting a prior\nextraction: every pass only adds.\n\nThis is the second contract consumer the epic asks for, and the one that\nexercises the curator/memory-engine binding\n(`archie-core-1786637499636`) for real, unlike the skill curator, which\ndeclares no memory engine at all.\n\n## Why session-scoped, not user- or agent-wide\n\n`docs/architecture/migration-decisions.md#5` lists the four required\nmemory scopes (global, agent-wide, user-wide, agent-user relationship)\nas **still open** -- there is no decided mapping yet from a chat session\nto a durable identity that would outlive that session (a Telegram chat\nID is not necessarily \"the same person\" as a web session; per-platform\nidentity resolution does not exist as a memory concern). Choosing\nsession-as-identity sidesteps a decision this issue has no business\nmaking unilaterally: it is the narrowest scope that is unambiguous\n(`gateway.SessionContext.SessionID` already exists, is already unique,\nand already has no cross-platform identity claim attached to it), and\nit is forward-compatible -- widening to a resolved user identity later\nis a change to what `Identity` is populated with, not to the\nextraction or write path.\n\n## Why a new `curator.ConversationSource`, not `gateway.SessionStore` directly\n\n`internal/domain/curator` is a domain package; `internal/gateway` is not\none of `internal/domain/*`'s dependencies by convention, and\n`gateway.SessionStore`'s full CRUD surface (branch, fork, replace,\nsearch) is far more than a curator needs or should be able to reach --\nthe same reasoning `ToolBuilder`/`SkillStore`/`MemoryEngineSource`\nalready established for every other host service this package depends\non. `curator.ConversationSource` is a two-method read-only interface;\n`internal/app/archied` adapts the real `gateway.SessionStore` to it, the\nsame shape `MemoryEngineSource` already uses for\n`domain/memory.Registry`.\n\n```go\n// ConversationSource is read-only conversation history, narrowed to\n// what a curator needs to review recent activity -- never the full\n// session CRUD/branch/search surface a chat gateway exposes.\ntype ConversationSource interface {\n // RecentSessions returns every session touched at or after since,\n // newest first.\n RecentSessions(ctx context.Context, since time.Time) ([]SessionSummary, error)\n // Messages returns the most recent n messages of one session, in\n // chronological order.\n Messages(ctx context.Context, sessionID string, n int) ([]ConversationMessage, error)\n}\n\ntype SessionSummary struct {\n ID string\n LastActive time.Time\n}\n\ntype ConversationMessage struct {\n Role string // \"user\" or \"assistant\"\n Content string\n At time.Time\n}\n```\n\n`Manifest` gains `Conversations bool`, gated exactly like `Skills`:\n`Registry.validateDeclared` requires a `ConversationSource` on the host\nwhen declared, `Registry.filter` clears it from a curator's view when\nnot. Role is derived the same way `gateway.compressTurnHistory` already\ndoes (`message.From == botUser` -\u003e `\"assistant\"`, else `\"user\"`) --\ncopied logic, not shared code, since the source type\n(`gateway.Message`) is exactly the thing this package must not import.\n\n## Extraction shape\n\n`Pass`:\n\n1. `Conversations.RecentSessions(ctx, effectiveSince(in.Since))` -- see\n below for the zero-`Since` default.\n2. For each session, `Conversations.Messages(ctx, id, 40)` -- the last\n 40 messages, not the full history. A session accumulates far more\n history than a skill file accumulates content; unlike the skill\n curator's \"re-read everything, it's cheap,\" a full-history read here\n is not cheap and is not needed -- durable facts worth keeping surface\n in recent exchanges, and a 40-message tail is deliberately generous\n against the model's own context rather than tuned tightly, since\n getting this number exactly right is not this issue's job.\n3. One model call per session: the message tail, plus an instruction to\n return a JSON array of short strings, each one fact/preference/\n correction worth keeping, or `[]` if nothing is. Capped at 5 items\n per session per passLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/skill-curator/",
|
||||
"title": "Skill curator (reference implementation) -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Skill curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499206`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n\n## Decision\n\nThe skill curator's v1 scope is **mechanical validation and safe\nnormalization only** -- it never rewrites skill prose, never deletes a\nskill, and never calls the model. Each pass:\n\n1. Lists every skill under one configured root.\n2. Reads each `SKILL.md` and attempts to parse its frontmatter\n (`internal/skill.Parse`).\n3. Records an `Action` for any structural problem: a parse failure, or a\n missing `name`/`description` in the frontmatter that parsed.\n4. Normalizes trivial whitespace (trailing whitespace per line, exactly\n one trailing newline) and writes back **only** when normalization\n actually changes the bytes, recording an `Action` for that write.\n\nNothing here needs judgment. \"Review, prune, and improve\" -- the epic's\nframing -- is real for v1 but deliberately narrow: review is structural\nvalidation, improve is whitespace normalization, and prune is *reporting*\na problem, never removing a skill. `Manifest.Skills = true` still marks\nthis curator agentic (existing `agentic()` rule), so it receives model\naccess from the registrar -- unused but nothing about the contract\nor the runtime needs to change to let a later version reason about\ncontent quality using it.\n\n## Why this scope, not more\n\nAn autonomous process that rewrites or deletes a user's skill content\nis a real risk with no undo path (no draft/approval flow for\ncurator writes exists yet, unlike the workflow engine's PR-based review).\nThe epic's own stated purpose for this issue is proving the curator\ncontract holds for a second, structurally different consumer than the\nsession-memory curator (files-as-skills vs. observations-as-memory), not\nsolving \"what makes a skill good.\" Mechanical validation is real,\nuseful, safe to run unattended, and fully exercises\nList/Read/Write -- every method `curator.SkillStore` declares except\n`Delete`, which this curator's Pass never has a safe reason to call in\nv1 (kept implemented on the store adapter regardless, since the\ninterface requires it and a future consumer may).\n\n## Why `internal/skill` isn't `curator.SkillStore` directly\n\n`internal/skill.Discover` parses every `SKILL.md` under a root and\nreturns an error for the **whole** call if any one of them fails to\nparse -- the read side was built for \"load the catalog to start the\ndaemon,\" where one bad skill failing the whole boot is arguably correct,\nnot for \"review each skill and report what's wrong with it\nindividually.\" A per-skill parse failure must become one `Action`, not\nabort the pass before any skill is reviewed. So\n`internal/infrastructure/skillcurator` gets its own thin store adapter\nthat lists raw directory names and reads/writes raw `SKILL.md` bytes\nper name; the skill curator itself calls `internal/skill.Parse` on each\none, isolated per skill.\n\n## Root scope\n\nOne root only, resolved the same way `loadWorkflows` already resolves\n`skillsBase` (`cfg.SkillsDir`, falling back to `cfg.WorkDir`) -- not\nevery root `skill.CatalogRoots`/`DefaultRoots` would read for a model\n(which layers a shared dir over the per-profile one). Write and Delete\nneed one unambiguous target; a curator that could write into a shared,\nmulti-tenant skills directory is a bigger decision than this issue\ncovers. The model still sees the full multi-root catalog through the\nexisting read path -- this curator only maintains the local one.\n\n## Shape\n\n### `internal/infrastructure/skillcurator/store.go`\n\n```go\n// Store implements curator.SkillStore over one root directory's\n// .agents/skills/*/SKILL.md files, tolerating a per-skill parse failure\n// as the curator's problem to report rather than this store's problem\n// to abort on.\ntype Store struct { root string }\n\nfunc NewStore(root string) *Store\n\nfunc (s *Store) List(ctx context.Context) ([]curator.SkillRef, error)\nfunc (s *Store) Read(ctx context.Context, name string) (curator.Skill, error)\nfunc (s *Store) Write(ctx context.Context, sk curator.Skill) error\nfunc (s *Store) Delete(ctx context.Context, name string) error\n```\n\n`Read` best-effort parses frontmatter for `Skill.Description` (empty on\nparse failure -- not this method's job to report that; `Pass` does, via\nits own `skill.Parse` call on `Skill.Content`). `Write` rejects a name\nthat does not already exist as a directory (this store curates existing\nskills; creating a new one is out of scope). `Delete` removes the whole\nskill directory, matching \"delete a skill,\" not just `SKILL.md`.\n\n### `internal/infrastructure/skillcurator/skillcurator.go`\n\n```go\n// Curator implements domain/curator.CuratorEngine. See\n// docs/prds/skill-curator.md for what a pass does and why.\ntype Curator struct { /* unexported: registrar view, interval */ }\Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/state-store-contract/",
|
||||
"title": "State Store — contract boundary \u0026 transport (ratification)",
|
||||
"section": "PRDs",
|
||||
"body": "# State Store — contract boundary \u0026 transport (ratification)\n\n**Status:** Approved\n**Revision:** 2e\n**Date:** 2026-09-06\n\nThis is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalize\n`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)\nimplement against.\n**Beads milestone:** archie-core-8cda.4.1\n**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)\n\nThis document fixes the **contract boundary** and **transport** for the State Store service.\nIt does not redesign Archie's domain model, does not invent a second store, and does **not**\nsplit `archie.db`. It records method ownership, DTO/wire representation, error semantics,\nlimits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that\n`.4.2` and `.4.3` have exactly one authoritative surface to build against.\n\n\u003e **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda.\n\u003e 4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in\n\u003e `internal/domain/workflow`, the six production workflow files import no `internal/store`\n\u003e symbol, and `storerpc`/the NATS transport assert against `workflow.Store` instead of\n\u003e `store.WorkflowStore`. The broader Phase 2 acceptance criterion (State Store as its own\n\u003e service behind gRPC) is still open — that is what `.4.2`/`.4.3` build next.\n\n\u003e **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/\n\u003e migration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →\n\u003e StepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)\n\u003e **remains the authoritative, open document for the long-term Workflow migration.** This PRD\n\u003e does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface\n\u003e relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);\n\u003e the rest of §4 stays its own migration and stays open.\n\n---\n\n## 1. Decision (the invariant everything follows)\n\nArchie is composed such that a single **`archie-state-store`** service owns the one existing\nSQLite file (`archie.db`) and exposes it over **gRPC behind narrow typed contracts**. There is\nexactly one store, one file, one service. No database-per-service, no distributed\ntransactions, no second store abstraction.\n\nTwo adapter families satisfy the contract interfaces:\n\n- **Local adapter** — `*store.Store` (the in-process SQLite implementation).\n- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).\n\nEach adapter carries an explicit compile-time assertion against the contract interfaces it\nserves. Composition picks local vs. remote by the presence of `[services.state].target`\n(empty = local; set = dial the gRPC service). Default is **local** (the State Store is not yet\nextracted), which is the PRD §3 posture; it differs from the gateway's remote-default only\nbecause the gateway is already a separate deployment and the State Store is not.\n\n\u003e **Contract-ownership fork, decided (rev. 2c — resolves the domain contradiction).**\n\u003e Ownership splits by the consumer's *layer*, per the dependency contract's rule #2\n\u003e (\"a domain defines the smallest interfaces required to perform its work\") and rule #7\n\u003e (\"database rows … MUST NOT leak into domain models\"):\n\u003e\n\u003e - The **workflow domain** (`internal/domain/workflow`) is the only domain-layer consumer of\n\u003e store state. It defines its own **consumer-owned** narrow `Store` interface\n\u003e (Update/Transition/InsertEvent) and its own **domain-owned** `Task` type plus\n\u003e `Status`/`Source` vocabulary. It imports **zero** `internal/store` symbols — satisfying the\n\u003e Phase 2 acceptance criterion. This is the minimal bound of migration-decisions §4\n\u003e (`store.Task → WorkflowExecution`), pulled forward **because** the acceptance criterion\n\u003e requires it.\n\u003e - The **daemon / webui / intake** store surfaces (`TaskStore`, `CaptureStore`,\n\u003e `MappingStore`, `BindingStore`, `BindingDispatcher`, `BindingTaskCreator`) stay\n\u003e **producer-owned** in `internal/store`, because those consumers are application and\n\u003e infrastructure layers, not domains — rule #2 does not apply to them.\n\nSo the State Store contract is **not** uniformly producer-owned: the domain-facing workflow\ncontract is consumer-owned (in the domain), while the daemon/webui store surfaces remain in\n`internal/store`. `internal/store` imports `internal/domain/workflow` for the `Task`/`Status`/\n`Source` types it persists (persistence → domain, the correct direction), and its `Store`\nimplementation satisfies `workflow.Store`. This is the single decision that makes the whole\nPhase 2 acceptance criterioLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/status-health-surface/",
|
||||
"title": "/status health surface",
|
||||
"section": "PRDs",
|
||||
"body": "# /status health surface\n\n**Status:** Finalised\n**Beads issue:** `archie-core-wp9s`\n\nA reported field must have a truthful source. `/status` reports broker\nconnectivity and the last chat-model call; the container pool, last poll and\nchannel state have no source in the process that answers the command, so they\nare left out rather than faked.\n\n## Background\n\n`archie-core-wp9s` (\"/status and /tasks have the wrong division of labour\")\nasked for two things: `/tasks` owning the live per-task work view, and\n`/status` owning daemon health -- \"broker connectivity, provider\nreachability, channel state, container pool, queue depth, last poll,\nversion\" -- with neither duplicating the other or static config available\nelsewhere (`/model` already lists active provider/model).\n\n## Phase 1\n\n- `/tasks`: new command, `gateway.ChatTaskSummary` extended with\n `Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on\n `store.Task`, zero new instrumentation), sorted actionable-first.\n- `/status`: itemized per-status task counts replaced with one aggregate\n `Queue: N in flight (...)` line (running/waiting/parked only -- queued and\n terminal states excluded as not a health concern). Runtime\n (provider/model) is temporarily left in place; see \"Runtime (provider/model)\"\n under Phase 2's \"Truthful or absent\" for where that stands now.\n\nNot touched: `/agents` (`gateway.AgentReader`/`Router.Agents`) is a separate,\npre-existing command that already has the right shape for \"list active\nwork\" but is never wired to a real implementation in any composition-root\ncall site (`bootstrap.go`, `telegram_setup.go`) -- it always answers \"Agent\nlisting is not configured.\" in production. That is a standalone bug\n(`archie-core-mxls`), not folded into this work: deciding whether to wire\nit, repurpose it, or delete it in favor of `/tasks` is Sam's call, not\nsomething to resolve by implication here.\n\n## Phase 2 -- health checks, verified against the actual tree\n\nEach bullet below was checked against real code before being called cheap\nor not; nothing here is guessed. Both open questions were settled (see \"The two\ndecisions\"). The health section reports the broker connection and the last\nchat-model call; the three facts the answering process cannot see are covered\nunder \"Truthful or absent\".\n\n### Verified as cheap against the tree\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`\n already exposes `CoreConn() (*nats.Conn, error)`\n (`client.go`). The underlying `nats.Conn` (nats.go) has its own\n `Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few\n lines.\n- **Container pool.** `container.Pool` already tracks `active int` under\n its own mutex (`pool.go`) but has no public accessor. A\n `Pool.Active() int` getter is a few lines.\n- **Last poll.** Nothing tracks this. The daemon's poll loop\n (`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or\n mutex-guarded, matching the pool's own pattern) set at the top of each\n poll tick, with a getter.\n- **Queue depth.** Covered by Phase 1.\n\n### The two decisions\n\n- **Provider reachability is last-known outcome, never a live probe.** A chat\n command must not perform a blocking network call in its handler, and a probe\n reports the probe's reachability rather than the daemon's. `/status` therefore\n prints what actually happened -- the last chat-model call's model, age and\n error, or \"no calls attempted yet\" when there has been none. Implemented as\n `providerOutcomeRecorder`, written once in `sendChatTurn` (the single point\n every chat-model call in the process passes through) and read back by\n `newStatusHealth`. Nothing on this path dials a provider. The existing live\n model reachability check (`readiness.go`'s `modelReachProbe`) is unchanged and\n stays where it belongs: on `/health/detailed`, off the chat path.\n- **Channel state comes from the existing ChannelManager.** `/status` reads\n `status.Manager.Snapshot()` -- the same ledger the dashboard and the readiness\n probe already use -- rather than re-deriving channel health from each adapter.\n No method was added to the `Channel`/`Gateway` contract.\n\n### Phase 2\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client` gained\n `Connected() bool`, which reads the connection the process already holds. The\n standalone Gateway (which dials NATS itself for task actions) reports the same\n fact from that connection.\n- **Container pool.** `container.Pool.Active()` and `Pool.Cap()` read the pool's\n own counter and configured `max_concurrency` -- not a Docker listing, which\n would include containers this pool does not own. A cap of zero means\n unlimited, so `/status` renders the count alone rather than \"1/0 active\".\n- **Last poll.** `daemon.Daemon.LastPollAt()` reports when the most recent poll\n pass *began*; both poll paths (`poll` for siLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/task-logs-pagination/",
|
||||
"title": "task_logs pagination and bounded retrieval -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# task_logs pagination and bounded retrieval -- decision\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Beads issue:** `archie-core-vq92`\n**Compounds with:** `archie-core-p1bl` (errors serialise as `{}`)\n\n## Decision\n\n`task_logs` becomes a *cursor-paginated, filterable* bounded read, not a\none-shot head-of-file window. The reader in `internal/logging` gains a\nsecond entry point (`Page`) that walks the file forward from a byte\noffset; the tool schema in `internal/gateway/task_tools.go` surfaces\nlevel, time-range and cursor parameters; the response carries an explicit\n\"more available\" signal so a model can either keep paging or hand the\nrest to `send_file` when the operator wants a complete archive.\n\nWe do NOT add an unbounded read path. A single response is still capped at\n`MaxTailLines` (2000) entries. What changes is that pagination makes the\ncap reachable in practice instead of silently terminal.\n\n## Why now\n\n`archie-core-vq92` is the right place to fix this: the chat tool is the\nuser-visible failure mode, but the same defect propagates to every caller\nof `internal/logging.Tail` (`internal/webui/api_logs.go` and the\n`chatTaskLogReaderAdapter` in `cmd/archied/main.go`). Patching the\nreader and the tool together is one change in two layers, not two\nchanges; CLAUDE.md's \"package owns its format end-to-end\" rule means the\nreader is the right place for cursor support regardless.\n\nThe compound with `p1bl` matters: a truncated window of uninformative\nerrors leaves an operator with nothing. Cursor pagination lets the model\nwalk the whole file when a level filter does not narrow enough, and the\nresponse's \"more available\" signal means it can honestly say \"I read N of\nM and stopped there\" instead of presenting the head as complete.\n\n## Shape of the API\n\n### Reader (`internal/logging`)\n\nAdd a second entry point next to `Tail`:\n\n```go\n// Page walks the log forward from cursor (a byte offset; 0 starts at\n// the beginning of the scanned window), applying the same filters as\n// Tail. PageResult.Cursor is the file offset just past the last line\n// the walk returned; pass it back as Cursor to continue, and stop when\n// MoreAvailable is false.\nfunc Page(path string, q Query, cursor int64) (PageResult, error)\n```\n\n`PageResult` carries `Entries`, `Truncated` (the existing meaning --\nolder entries exist that were not examined within `maxScanBytes`),\n`Cursor` (the byte offset the next page should resume from), and\n`MoreAvailable` (true iff the scan saw more matching entries beyond the\nreturned page within the same call).\n\n`Cursor` is a byte offset rather than an entry ID for two reasons.\nFirst, `TaskSink` writes JSONL through `slog.NewJSONHandler` directly --\nwithout routing through `FeedHandler` -- so the on-disk entries carry no\n`id` field and a per-task attempt monotonic counter would require\neither a sink-side change or a reader-side reconstruction that is\nbrittle against rotation. Second, the byte offset uniquely identifies\n\"the next unread position\" in a sequential scan, which is exactly what\nthe call pattern needs. A cursor that points at or past the file's\ncurrent size is treated as end-of-stream (empty page, `MoreAvailable`\nfalse).\n\nThe implementation is `readWindow` (reads the tail-most `maxScanBytes`\ninto a single in-memory buffer) plus `readLines` (clamps the cursor into\nthe window, drops a partial first line on the size-cap seek, then\ndelegates) plus `walkWindow` (walks the buffer line-by-line by exact\nslice offset). Offsets are into one contiguous buffer, so they are\ntrivially correct -- unlike an incremental reader over the file, whose\n`bufio.Reader` buffer-ahead would make its underlying file position\nunusable as a cursor.\n\n`Tail` is NOT a wrapper over `Page`: it keeps its legacy ring-buffer\nsemantics (newest `Limit` matches, oldest dropped, `Truncated` set on\nring overflow). They share `readWindow`/`walkWindow` but stay separate\nentry points precisely so Tail's established behaviour is unchanged.\n\n### `Query` gains two optional fields\n\n```go\nSince time.Time // inclusive lower bound on entry.Time\nUntil time.Time // inclusive upper bound on entry.Time\n```\n\n`Levels`, `Component`, `Contains`, `Limit` are unchanged. The existing\nfilter logic and tests move unchanged.\n\n### Tool schema (`internal/gateway/task_tools.go`)\n\n`ChatTaskLogQuery` gains three fields:\n\n- `Level []string` (forwarded to `Query.Levels`)\n- `Since time.Time` / `Until time.Time` (forwarded as `Query.Since/Until`)\n- `AfterID int64` (the cursor; 0 to start at the beginning)\n\n`ChatTaskLogResult` gains two fields:\n\n- `Cursor int64` -- highest ID in this page; pass back as `AfterID` to continue\n- `MoreAvailable bool` -- true iff the scan saw more matching entries that\n did not fit in this page\n\nThe tool description is updated to teach the model the pagination\nprotocol in one sentence: \"pass the previous `cursor` back as `Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/task-run-detail/",
|
||||
"title": "Per-run task detail: attempts, stages, changes, config, debug",
|
||||
"section": "PRDs",
|
||||
"body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --- | --- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted by `internal/store` as the `events.attempt`\ncolumn (`internal/store/events.go`, `eventsSchema`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstructure is exactly the false fidelity this surface exists to avoid; a column\nis durable, queryable and ordered by construction.\n\n**`0` means \"not attributable\".** It is every row written before this change\nplus the deliberately task-agnostic producers. It is not an attempt number and\nis never rendered as one. The attempts endpoint reports the count of\nunattributed events so the page can say so instead of presenting old history as\nattempt 1.\n\n## Migration against an existing `archie.db`\n\nThe store's migrator (`migrateTasks` in `internal/store/store.go`) already reads\n`PRAGMA table_info` through `tableColumns` and applies a presence-gated\n`ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a\n`tableColumns(ctx, tx, \"events\")` read beside the other two, and the entry\n`ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`.\n\nThree consequences a future maintainer must not get wrong:\n\n- `eventsSchema` is `CREATE TABLE IF NOT EXISTS` (`internal/store/events.go`),\n so on an existing database it is a **no-op**. The migrator arm is the only\n thing that adds the column there. This is why the red test builds a raw\n SQLite file with the pre-change `events` DDL and must fail before the arm\n exists: eveLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/ui-service-boundary/",
|
||||
"title": "UI Service boundary and configuration ownership",
|
||||
"section": "PRDs",
|
||||
"body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behavior, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n|---|---|---|---|\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviorally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status |\n|---|---|---|\n| `/api/chat/*` | Gateway `ChatContract` and its versioned client | contract seam exists; DTO and stream parity remain |\n| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains |\n| `/events` | State Store `EventsSince`, polled by one UI-process pump feeding `Server.Broadcast` | RESOLVED (`archie-core-za9f`): see migration-decisions, \"Dashboard live event delivery\". No new RPC; replay cursor and drop-recovery are the existing `since` watermark in `sse.go` |\n| `/api/logs`, `/api/logs/stream` | daemon diagnostic feed, host-local | unresolved: `logging.Feed` is in-process on the daemon host and has no contract. The per-task log routes moved off this row: see `/api/tasks/*` above |\n| `/api/tasks/{id}/logs`, `/api/tasks/{id}/logs/download` | State Store task-log read contract (`TaskLogStore`: `ReadTaskLog` + `StreamTaskLogContent`), read by the UI process from the service that owns the state directory | RESOLVED (`archie-core-iaqx`): the UI process composes `TaskLogStore` from its own State Store client and serves the attempt Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/vue-migration-checklist/",
|
||||
"title": "Preact → Vue 3 + shadcn-vue migration checklist",
|
||||
"section": "PRDs",
|
||||
"body": "# Preact → Vue 3 + shadcn-vue migration checklist\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Bead:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation restructure)\n**Bootstrap commit:** `e18fb8b2`\n\nThe Preact dashboard was deleted, not ported incrementally. This is the list of\nwhat has to exist again, what must not be lost on the way, and the contracts\nthat break silently if missed.\n\nDeleted source is recoverable at `git show e18fb8b2^:ui/src/\u003cpath\u003e`. Every\nclaim below was cross-checked against that tree; where a number is a live\nmeasurement rather than something recoverable from git, it says so.\n\n## Invariants that outlive the framework\n\nThese are not features; they are things other processes depend on. Breaking one\ndoes not show up as a broken page.\n\n- [ ] **Embed contract.** `ui/embed.go` embeds a committed `ui/dist`. The build\n must keep unhashed `assets/index.{js,css}`: dist/ lives in git, and\n hashed names orphan a file on every rebuild.\n- [ ] **Route registry.** `internal/gateway/dashboard_tools.go` hand-copies the\n route table and `TestDashboardPagesRegistryCoversEveryRoute` parses\n `ui/src/router/index.ts` to hold them in step. The parser needs\n `const routes = [` on its own line, `path: \"...\"` on a single line per\n route, and `nav: false` on any entry the registry should skip. That guard\n caught a stale `/chat` entry earlier.\n- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**\n `X-Archie-CSRF: 1` and `Content-Type: application/json`. The server\n returns 403 without the first and 415 without the second\n (`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends\n neither. This is the single most likely thing to silently break every\n write after the port.\n- [x] **History routing.** `createWebHistory`, `base: \"/\"`. Legacy `#/path`\n links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate\n chip should emit `/tasks`; the Go side already stores bare paths.\n- [ ] **Capability gating.** `GET /api/capabilities`\n (`internal/webui/api_capabilities.go`) returns a `sections` map of ten\n booleans: chat, logs, skills, curators, channels, captures, mappings,\n bindings, and workflows/settings which are always true. A route whose\n section is false must be hidden, not rendered empty. **Fail open**: on a\n failed or null response hide nothing — the old client used a bare\n `.catch(() =\u003e {})` for exactly this. A page that says \"unavailable\" is\n recoverable; a nav entry that vanished is not.\n- [ ] **`LOG_LEVELS`** in `base/log-row.jsx` is a wire contract, not a display\n list: the CSV level filter is matched server-side by `splitCSV` in\n `internal/webui/api_tasks_logs.go`. A value mismatch breaks filtering\n with no error.\n- [ ] **SSE lifecycle.** Three streams, all `id: \u003cn\u003e\\ndata: \u003cjson\u003e\\n\\n` except\n chat which omits the id:\n `/events` (task lifecycle, `sse.go`, supports `?since=` and\n `Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same\n resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed\n delta/tool/media/navigate). Each must be closed on unmount or the app\n leaks a connection per navigation. Preact used an `archie:teardown`\n event; Vue should use `onUnmounted`.\n\n\u003e **On tests.** Per Sam's call, the 43-file suite was not ported and tests\n\u003e return when there is behaviour worth pinning. Flagging one exception for when\n\u003e that moment comes: the deleted `ui/test/api-client.test.js` classified every\n\u003e API method as mutation/read/stream/url and asserted the right headers per\n\u003e class. It is the only cheap guard on the CSRF contract above. (It did **not**\n\u003e text-scan for a second `fetch()` — that check was deliberately removed\n\u003e upstream for testing the file's wording rather than its behaviour.)\n\n## Phase 1 — Foundation\n\n- [x] **Theme.** `css/tokens.css` was a complete two-theme semantic token set\n (`--fg-subtle`, `--accent`, `--ok/warn/danger`, surfaces, shadows). Mapped\n onto Tailwind v4's `@theme` in `src/style.css`; the second system was not\n kept.\n- [x] **`color-scheme`.** `[data-theme=\"dark\"] { color-scheme: dark }` and the\n light equivalent. Without it the UA paints light scrollbars and light\n native controls inside the dark app. Fixed; trivially lost.\n- [x] **Contrast values.** The violet palette moved these off the values pinned\n here, so they were recomputed against its own backgrounds instead of\n carried: `--fg-subtle` `#A99DBD` dark (7.67:1, AAA) / `#6E6577` light\n (4.87:1, AA), and `--fg-muted` `#B9AECB` / `#635B6B` (9.28:1 and 5.70:1).\n The invariant the pin existed for holds; the values are the palette's.\n- [x] **API client** (`base/api.jsx` → `src/lib/api.tLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/webhook-intake-security/",
|
||||
"title": "Webhook intake security -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Webhook intake security -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`\n\n## Why this is decided ahead of the code it constrains\n\n`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event\nsources) both land a public intake surface whose eventual output is an agent\nwith tool access and a repo. Neither capture (`t2db.1`) nor the intake family\n(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two\nepics build against, not a retrofit once the surface exists. A webhook URL\nthat can start an agent is remote code execution with extra steps if any of\nthe five points below is missing on day one.\n\n## 1. Per-source authentication\n\nReuse the per-route HMAC-SHA256 scheme already in\n`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source\nregisters with a shared secret; the signature is checked against the raw\nbody. Do not invent a second scheme for intake.\n\n**Capture and triggering split at the signature, not at a separate flag.** An\nevent with a missing or invalid signature is still captured (visible in the\ninspector, marked unauthenticated) so an operator can diagnose a\nmisconfigured sender -- but an unauthenticated event can never be matched\nagainst a binding. Authentication is what promotes an event from \"something\narrived\" to \"something that can run a workflow.\"\n\n## 2. Human approval before a binding arms\n\nA binding has three states: `draft -\u003e pending_approval -\u003e armed`. Only\n`armed` bindings are evaluated against incoming events. Creating or editing a\nbinding's matcher, mapping, or target workflow always sets it to\n`pending_approval`, including edits to an already-armed binding -- an edit is\nnot silently re-armed, or the approval gate is decorative. Approval requires\nan authenticated dashboard session; there is no unattended approval path.\n\nModel: `internal/channels/telegram`'s dangerous-command approval flow\n(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is\nthe existing precedent for \"a human decision gates code from running\" in this\ncodebase -- follow its shape rather than designing a new approval primitive.\n\n## 3. Rate and volume limits, per source\n\nA token-bucket limiter keyed by source ID, not global -- one noisy or hostile\nsender must not exhaust another source's capture budget. Precedent for\nper-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.\n\nOn limit exceeded, the request is rejected (HTTP 429), not silently dropped.\nA silently dropped event is indistinguishable from a sender that never fired\n-- the same invisible-failure shape the update-verification work\n(`archie-core-522`) exists to prevent. The rejection itself is observable in\nthe inspector as a distinct outcome from \"not received.\"\n\n## 4. Blast radius bounded by code, not by prompt wording\n\nA playbook-triggered task runs through exactly the same enforcement as every\nother task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the\nsandboxed per-task container (`internal/container`), worktree isolation, and\n\"the model never runs git.\" No new relaxation is introduced for\nplaybook-triggered work, and none is needed -- the existing constraints are\nthe control.\n\nMapped payload fields are treated as ordinary user-controlled text inside an\nagent prompt, exactly like an inbound chat message never as trusted\ninstructions. \"The agent should ignore instructions in the payload\" is not a\ncontrol and must not appear as one anywhere in this feature -- per\n`ARCHITECTURE.md`'s environmental-enforcement-over-prompt-rules principle,\nthe boundary is the gate and the sandbox, not a sentence in the system\nprompt.\n\n## 5. Retention and redaction of captured payloads\n\n**Retention:** captured events (bound or not) are purged after 7 days,\nconfigurable per deployment. Unbound events exist to be mapped against; nothing\njustifies keeping them indefinitely once that window has passed, and an\nunbounded capture store is the same disk-exhaustion risk item 3 addresses at\nthe request-rate level.\n\n**Redaction:** before a captured payload is persisted, apply the same\nkey-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`\nalready uses for tool-call parameters (matches `token`, `secret`, `password`,\n`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,\n`private_key` against normalized JSON keys) and replace matching values with\nthe same `[redacted]` marker. This is best-effort, not a guarantee -- a\nsender that names a secret field something the heuristic misses will still\nhave it captured. Document that limitation where captured payloads are\ndisplayed, rather than implying the redaction is complete.\n\n**Visibility:** captured payloads, redacted or not, are visible only to an\nauthenticated dashboard operator -- the same authorization bounLine truncated
|
||||
}
|
||||
],
|
||||
"nav": [
|
||||
{
|
||||
"title": "Architecture",
|
||||
"url": "/dev/architecture/",
|
||||
"items": [
|
||||
{
|
||||
"title": "Adversarial self-review",
|
||||
"url": "/dev/architecture/adversarial-review/"
|
||||
},
|
||||
{
|
||||
"title": "Agent System",
|
||||
"url": "/dev/architecture/agent-system/"
|
||||
},
|
||||
{
|
||||
"title": "Playbook bindings: model and threat model",
|
||||
"url": "/dev/architecture/bindings/"
|
||||
},
|
||||
{
|
||||
"title": "Configuration",
|
||||
"url": "/dev/architecture/configuration/"
|
||||
},
|
||||
{
|
||||
"title": "Dependencies and Contracts",
|
||||
"url": "/dev/architecture/dependencies-and-contracts/"
|
||||
},
|
||||
{
|
||||
"title": "Generated Documentation",
|
||||
"url": "/dev/architecture/generated-documentation/"
|
||||
},
|
||||
{
|
||||
"title": "Identity",
|
||||
"url": "/dev/architecture/identity/"
|
||||
},
|
||||
{
|
||||
"title": "Messaging and Work Intake",
|
||||
"url": "/dev/architecture/messaging-and-work-intake/"
|
||||
},
|
||||
{
|
||||
"title": "Architecture Migration Decisions",
|
||||
"url": "/dev/architecture/migration-decisions/"
|
||||
},
|
||||
{
|
||||
"title": "Task Observability",
|
||||
"url": "/dev/architecture/observability/"
|
||||
},
|
||||
{
|
||||
"title": "Repository Organisation",
|
||||
"url": "/dev/architecture/organisation/"
|
||||
},
|
||||
{
|
||||
"title": "Domain and Feature Review Procedure",
|
||||
"url": "/dev/architecture/package-review/"
|
||||
},
|
||||
{
|
||||
"title": "Plugins and Extensions",
|
||||
"url": "/dev/architecture/plugins-and-extensions/"
|
||||
},
|
||||
{
|
||||
"title": "Policy System",
|
||||
"url": "/dev/architecture/policy/"
|
||||
},
|
||||
{
|
||||
"title": "Safe Change and Recovery",
|
||||
"url": "/dev/architecture/safe-change-and-recovery/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "PRDs",
|
||||
"items": [
|
||||
{
|
||||
"title": "Architecture Decision Index",
|
||||
"url": "/dev/prds/01-project-management/"
|
||||
},
|
||||
{
|
||||
"title": "PRD writing rules",
|
||||
"url": "/dev/prds/RULES/"
|
||||
},
|
||||
{
|
||||
"title": "Adversarial self-review stage -- decision",
|
||||
"url": "/dev/prds/adversarial-self-review/"
|
||||
},
|
||||
{
|
||||
"title": "Binding secret at-rest encryption -- decision",
|
||||
"url": "/dev/prds/binding-secret-encryption/"
|
||||
},
|
||||
{
|
||||
"title": "Channel and Forge action positions (resolves `t2db.19`)",
|
||||
"url": "/dev/prds/channel-forge-positions/"
|
||||
},
|
||||
{
|
||||
"title": "Code graph over MCP (`tools/codegraph`)",
|
||||
"url": "/dev/prds/code-graph-mcp/"
|
||||
},
|
||||
{
|
||||
"title": "Example-config and generated-config drift — decision",
|
||||
"url": "/dev/prds/config-example-drift/"
|
||||
},
|
||||
{
|
||||
"title": "Backend-owned configuration schema for the webui -- decision",
|
||||
"url": "/dev/prds/config-schema/"
|
||||
},
|
||||
{
|
||||
"title": "Contract conformance audit — decision",
|
||||
"url": "/dev/prds/contract-conformance-audit/"
|
||||
},
|
||||
{
|
||||
"title": "Control-plane apply status",
|
||||
"url": "/dev/prds/control-plane-apply-status/"
|
||||
},
|
||||
{
|
||||
"title": "Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision",
|
||||
"url": "/dev/prds/curator-sampler-wave1/"
|
||||
},
|
||||
{
|
||||
"title": "Dashboard-aware chat: Archie sees the page, and points the operator there",
|
||||
"url": "/dev/prds/dashboard-aware-chat-navigation/"
|
||||
},
|
||||
{
|
||||
"title": "Dashboard live state",
|
||||
"url": "/dev/prds/dashboard-live-state/"
|
||||
},
|
||||
{
|
||||
"title": "Dashboard navigation groups + Configuration split -- decision",
|
||||
"url": "/dev/prds/dashboard-navigation-groups/"
|
||||
},
|
||||
{
|
||||
"title": "Dashboard port: what the agent delivers",
|
||||
"url": "/dev/prds/dashboard-port-brief/"
|
||||
},
|
||||
{
|
||||
"title": "Deep research capability — design",
|
||||
"url": "/dev/prds/deep-research-capability/"
|
||||
},
|
||||
{
|
||||
"title": "Dynamically-defined curators -- decision",
|
||||
"url": "/dev/prds/dynamic-curators/"
|
||||
},
|
||||
{
|
||||
"title": "Dynamic workflow triage",
|
||||
"url": "/dev/prds/dynamic-workflow-triage/"
|
||||
},
|
||||
{
|
||||
"title": "EDA playbook engine -- design",
|
||||
"url": "/dev/prds/eda-playbook-engine/"
|
||||
},
|
||||
{
|
||||
"title": "Embedded NATS execution -- decision",
|
||||
"url": "/dev/prds/embedded-nats/"
|
||||
},
|
||||
{
|
||||
"title": "Event capture storage -- decision",
|
||||
"url": "/dev/prds/event-capture-storage/"
|
||||
},
|
||||
{
|
||||
"title": "Event sources and reactions -- decision",
|
||||
"url": "/dev/prds/event-sources-and-reactions/"
|
||||
},
|
||||
{
|
||||
"title": "Extensions center",
|
||||
"url": "/dev/prds/extensions-center/"
|
||||
},
|
||||
{
|
||||
"title": "Image capability contract and configuration",
|
||||
"url": "/dev/prds/image-capability-contract/"
|
||||
},
|
||||
{
|
||||
"title": "Inline review -- decision",
|
||||
"url": "/dev/prds/inline-review/"
|
||||
},
|
||||
{
|
||||
"title": "MCP client and tool-guardrail completion",
|
||||
"url": "/dev/prds/mcp-tool-completion/"
|
||||
},
|
||||
{
|
||||
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
|
||||
"url": "/dev/prds/memory-engine-unification/"
|
||||
},
|
||||
{
|
||||
"title": "Messaging Service boundary and transport design",
|
||||
"url": "/dev/prds/messaging-service-boundary/"
|
||||
},
|
||||
{
|
||||
"title": "Module position -- design",
|
||||
"url": "/dev/prds/module-position/"
|
||||
},
|
||||
{
|
||||
"title": "Multi-action playbooks and typed action results",
|
||||
"url": "/dev/prds/multi-action-playbooks/"
|
||||
},
|
||||
{
|
||||
"title": "Public news and per-version release notes -- decision",
|
||||
"url": "/dev/prds/news-and-releases/"
|
||||
},
|
||||
{
|
||||
"title": "Operator-triggered PR review",
|
||||
"url": "/dev/prds/operator-pr-review/"
|
||||
},
|
||||
{
|
||||
"title": "Payload field mapping -- decision",
|
||||
"url": "/dev/prds/payload-field-mapping/"
|
||||
},
|
||||
{
|
||||
"title": "Playbook data-flow and condition syntax",
|
||||
"url": "/dev/prds/playbook-expression-syntax/"
|
||||
},
|
||||
{
|
||||
"title": "PR review comment remediation -- decision",
|
||||
"url": "/dev/prds/pr-review-remediation/"
|
||||
},
|
||||
{
|
||||
"title": "Progressive tool disclosure (bridge tools) — wiring",
|
||||
"url": "/dev/prds/progressive-tool-disclosure/"
|
||||
},
|
||||
{
|
||||
"title": "Public and development documentation -- design",
|
||||
"url": "/dev/prds/public-and-dev-docs/"
|
||||
},
|
||||
{
|
||||
"title": "Review calibration -- decision",
|
||||
"url": "/dev/prds/review-calibration/"
|
||||
},
|
||||
{
|
||||
"title": "Runtime control plane",
|
||||
"url": "/dev/prds/runtime-control-plane/"
|
||||
},
|
||||
{
|
||||
"title": "Self-update: artifact install, topology migration, journaled transaction",
|
||||
"url": "/dev/prds/self-update-transaction/"
|
||||
},
|
||||
{
|
||||
"title": "Service decomposition -- decision",
|
||||
"url": "/dev/prds/service-decomposition/"
|
||||
},
|
||||
{
|
||||
"title": "Service registry — one declaration per service",
|
||||
"url": "/dev/prds/service-registry/"
|
||||
},
|
||||
{
|
||||
"title": "Persistent session-memory curator (reference implementation) -- decision",
|
||||
"url": "/dev/prds/session-memory-curator/"
|
||||
},
|
||||
{
|
||||
"title": "Skill curator (reference implementation) -- decision",
|
||||
"url": "/dev/prds/skill-curator/"
|
||||
},
|
||||
{
|
||||
"title": "State Store — contract boundary \u0026 transport (ratification)",
|
||||
"url": "/dev/prds/state-store-contract/"
|
||||
},
|
||||
{
|
||||
"title": "/status health surface",
|
||||
"url": "/dev/prds/status-health-surface/"
|
||||
},
|
||||
{
|
||||
"title": "task_logs pagination and bounded retrieval -- decision",
|
||||
"url": "/dev/prds/task-logs-pagination/"
|
||||
},
|
||||
{
|
||||
"title": "Per-run task detail: attempts, stages, changes, config, debug",
|
||||
"url": "/dev/prds/task-run-detail/"
|
||||
},
|
||||
{
|
||||
"title": "UI Service boundary and configuration ownership",
|
||||
"url": "/dev/prds/ui-service-boundary/"
|
||||
},
|
||||
{
|
||||
"title": "Preact → Vue 3 + shadcn-vue migration checklist",
|
||||
"url": "/dev/prds/vue-migration-checklist/"
|
||||
},
|
||||
{
|
||||
"title": "Webhook intake security -- decision",
|
||||
"url": "/dev/prds/webhook-intake-security/"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -4,139 +4,13 @@
|
||||
"url": "/docs/",
|
||||
"title": "Archie",
|
||||
"section": "",
|
||||
"body": "# Archie\n\nEvent Driven Agentic Automation.\n\nArchie is an agent platform that reacts to events. A forge issue, a signed\nwebhook from any app you run, a message in a chat channel: each arrives as an\nevent, a playbook decides what a matching event sets off, and the work happens\nin an isolated git worktree. GitHub and Gitea issues were the first case. A\nforge is now one event source among several, and a pull request one outcome\namong several.\n\nNothing about that path is wired to a particular forge, channel, or sender.\nSources, the fields they carry, and the workflows they reach are configuration\nyou add without touching code or restarting anything.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) points an external app's webhook\n at archie, maps the fields of a real payload, and binds them to a workflow.\n- [Architecture](/docs/architecture/) is the authority for settled design:\n the domain boundaries, the workflow engine, the task lifecycle, and the\n invariants that hold the whole thing together.\n\n## What runs where\n\nA deployment is a set of services, each owning one typed contract. The Gateway\nserves conversation turns and sessions, the Messaging Service runs the\nchannels, the State Store owns the database outright, the dashboard is its own\nprocess, and `archied` admits work and drives each task through its workflow.\ngRPC carries the synchronous calls between them; NATS carries asynchronous\nfan-out. Agents execute in containers that receive a task-scoped credential,\nissued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/",
|
||||
"title": "Architecture",
|
||||
"section": "Architecture",
|
||||
"body": "# Architecture\n\nArchie is a personal agent platform built around six domain boundaries:\n\n- Identity tracks users and other actors responsible for actions.\n- Agent owns persistent assistants, specialisation, and continuity.\n- Messaging owns conversations, messages, branches, and channel correlation.\n- Workflow owns reusable, versioned behaviour definitions and their executions.\n- Work Intake admits optional durable work without constraining ordinary agent\n conversation or direct capability use.\n- Plugin owns generic extension discovery and lifecycle; each capability family\n owns its typed plugin contract.\n\nThe detailed architecture and migration decisions are maintained under\n`docs/architecture/` in the repository while this generated site is being\nassembled.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/adversarial-review/",
|
||||
"title": "Adversarial self-review",
|
||||
"section": "Architecture",
|
||||
"body": "# Adversarial self-review\n\nArchie runs a fresh adversarial review of the diff before it opens a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## Operator-triggered review\n\nThe same reviewer runs against an *existing* PR via the channel-neutral\n`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated\nreviewer, and return the structured findings. Authorization is identity-scoped\nto the operator's configured repositories; duplicate or concurrent reviews of\nthe same PR are deduplicated.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/agent-system/",
|
||||
"title": "Agent System",
|
||||
"section": "Architecture",
|
||||
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorized Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalization boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorizing explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/docs/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/docs/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\nLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/bindings/",
|
||||
"title": "Playbook bindings: model and threat model",
|
||||
"section": "Architecture",
|
||||
"body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the `ARCHITECTURE.md` task-lifecycle\naddendum or the operator walkthrough -- those remain separate, open pieces of\nthe same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // draft | pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (SQLite), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\n`Matcher.Source` is the only predicate today: the path segment a sender\nPOSTs to (e.g. a webhook hitting `.../sentry` matches bindings with\n`Matcher.Source == \"sentry\"`). The storage column is plain `TEXT`, so adding\npredicates later is non-breaking -- extend `Matcher`, don't invent a second\nmatcher shape.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. This\nis schema-by-example in practice: a mapping is authored by pointing at a\nreal captured payload in the dashboard, not by guessing a schema in advance.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ndraft ---\u003e pending_approval ---\u003e armed\n ^ ^ |\n | | |\n +--------------+-----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nModeled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); `draft` and `pending_approval` bindings are inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captured_events.authenticated` is a real column (`internal/store/\n captures.go`), set at capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose source has at least one armed binding** -- an\n unauthenticated capture is never even considered for dispatch.\n\n### 2. Human approval before a binding goes live\n\nCovered by the state machine above. Nothing self-arms: `pending_approval -\u003e\narmed` requires an explicit `Approve` call, and any edit to an armed\nbinding reverts it.\n\n### 3. Rate and volume limits per source\n\nCapture writes are bounded independently of the approval gate, so a flood\nof unauthenticated traffic cannot exhaust disk or drown the inspector:\n`InsertCapture` (`internal/store/captures.go`) prunes by both **retention\nwindow** (`WHERE received_Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/configuration/",
|
||||
"title": "Configuration",
|
||||
"section": "Architecture",
|
||||
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognized filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/docs/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nindexing settings, provider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot chLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/dependencies-and-contracts/",
|
||||
"title": "Dependencies and Contracts",
|
||||
"section": "Architecture",
|
||||
"body": "# Dependencies and Contracts\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Dependency direction\n\n```text\ndomain and shared application contracts \u003c- infrastructure implementations\n ^\n |\n application composition\n```\n\nThe following rules are strict:\n\n1. Domains MUST NOT import `internal/infrastructure`.\n2. A domain defines the smallest interfaces required to perform its work.\n3. Infrastructure implements those interfaces and translates external\n representations at the boundary.\n4. Only application composition chooses concrete implementations.\n5. A domain MUST NOT manipulate another domain's state or call its internal\n services.\n6. Cross-domain work uses an explicitly designed command, event, or approved\n shared contract.\n7. Implementation difficulty is not permission to violate a boundary.\n\nBroker messages, database rows, SDK response types, and configuration DTOs MUST\nNOT leak into domain models.\n\n## Commands and events\n\n- An event records something that happened and is owned by its publishing\n domain.\n- A command requests an action and is owned by the domain expected to handle it.\n- Consumers do not redefine an event's meaning.\n- Senders obey the receiving domain's command contract.\n- There is no generic package containing unrelated application messages.\n\n## Event bus\n\n`internal/eventbus` is an approved shared application contract. It defines only\nthe messaging behaviour Archie requires, including publication, subscription,\ndelivery outcomes, and required lifecycle semantics.\n\nIt MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer\ngroups, acknowledgements, reconnection, and serialization belong under\n`internal/infrastructure/eventbus/nats` unless Archie explicitly requires a\nsemantic guarantee in the shared contract.\n\nMessage schemas stay with their owning domains. The event bus transports\nmessages; it does not own their meaning.\n\n## Wire contracts and generation\n\nCanonical worker and service wire contracts and their authoritative generation\ninputs are owned by the domain or capability that defines their meaning. They\nMUST NOT be centralized in `internal/infrastructure/spec` or another generic\nschema package.\n\nInfrastructure owns:\n\n- generic contract-generation machinery;\n- transport-specific adapters and generated implementations;\n- RPC, REST, NATS, and other external encoding and delivery concerns.\n\nFor example, agent-worker requests and results belong to task execution.\nSubprocess, NATS, or HTTP representations are infrastructure implementations of\nthat contract. The same rule applies independently to forge, persistence,\nworkspace, and other service contracts.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/generated-documentation/",
|
||||
"title": "Generated Documentation",
|
||||
"section": "Architecture",
|
||||
"body": "# Generated Documentation\n\n**Status:** Generator scaffold in place; renderer and publishing removed\n**Date:** 2026-07-28 (revised 2026-09-12)\n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie's documentation-generation approach is:\n\n- production Go code, registries, configuration, and CLI behaviour remain the\n source of truth for published contracts;\n- a repository-local Go generator extracts and normalizes documentation data;\n- the generator writes deterministic JSON/data files and protocol schemas;\n- the rendering and publishing surface is an **open decision** — the VitePress\n site and its Pages deployment were removed on 2026-09-12 as an unnecessary\n build step (see \"Rendering and publishing\" below).\n\nHugo is not part of the target architecture.\n\nThe documentation system is rooted at:\n\n```text\ntools/\n go.mod\n go.sum\n docsgen/\n main.go\ndocs/\n data/generated/\n public/schemas/\n *.md\n```\n\n### Rendering and publishing — OPEN\n\nSuperseded 2026-09-12. The repository previously carried a VitePress site\n(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line\n`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub\nPages by `.github/workflows/docs.yml`. It was removed as an unnecessary build\nstep: the published site was never stood up, and the Pages target is not\nconfigured.\n\n`docs/` is now repository documentation only — markdown read in the repository,\nan editor, or a forge's file view. Nothing in the repository builds, renders, or\npublishes it.\n\nThe renderer for the generated `data/generated/*.json` is therefore **undecided**.\nConsequences that follow, and their current state:\n\n| Concern | State after removal |\n| --- | --- |\n| Reference-page rendering | Undecided; `data/generated/contracts.json` is committed but unrendered |\n| Internal link validation | Not enforced by any build; links are repository-relative (`../architecture/...`) and resolve on the filesystem |\n| Generated-data drift detection | Unchanged — `docsgen check` compares committed output, independent of any renderer |\n| Navigation/sidebar | The authoritative index is `docs/prds/01-project-management.md` |\n| Local authoring server | None; read markdown directly |\n\nA future renderer MUST NOT reintroduce a dead-link-blind build: VitePress\npreviously validated internal links during its production build, and no\nreplacement currently does.\n\n## Single source of truth\n\nEvery published capability has one authoritative machine-readable definition\nowned by its domain or application boundary. Generated documentation derives\nfrom those definitions.\n\nGenerated reference includes:\n\n- domain commands and events;\n- Messages and typed message content;\n- Agent and Workflow contracts;\n- WorkflowSteps and Workflow plugin capability contracts;\n- policies and their typed inputs and outcomes;\n- tools and capabilities;\n- CLI commands, arguments, flags, defaults, and help;\n- runtime settings, types, defaults, validation, and secret metadata;\n- public worker and transport contracts;\n- indexes of registered functionality;\n- deprecation information.\n\nHandwritten documents contain:\n\n- architecture decisions and rationale;\n- tutorials and operational guides;\n- examples and walkthroughs;\n- migration guidance;\n- conceptual explanations.\n\nHandwritten documents link to generated reference rather than copying\nauthoritative tables.\n\n## Target generation architecture\n\n`tools/docsgen` is Archie's documentation extractor and normalizer. It produces\nstructured documentation data and protocol specifications. It does not own\npage layout and MUST NOT generate Markdown pages or fragments.\n\nThe generator is divided internally into reusable stages:\n\n```text\nload registries and types\n -\u003e normalize documentation model\n -\u003e validate ownership and identifiers\n -\u003e serialize data and protocol artifacts\n -\u003e compare or write output\n```\n\nThe normalized documentation model prevents each output renderer from\nindependently interpreting Go types. It contains stable documentation IDs,\nowners, names, descriptions, source references, versions, deprecations, fields,\ndefaults, validation, secret classifications, and relationships.\n\nInitial generator targets:\n\n```text\ndocsgen data\ndocsgen asyncapi\ndocsgen all\ndocsgen check\n```\n\n- `data` writes the normalized JSON reference data.\n- `asyncapi` writes protocol schemas and envelopes.\n- `all` generates every committed artifact.\n- `check` generates into a temporary directory and fails on drift.\n\nThe command may use subcommands or an equivalent explicit `--target` flag. It\nMUST retain one normalization and validation path.\n\n## Target output\n\nDuring adaptation, `docs` remains the staging site. Generated outputs live in\na visibly owned subtree:\n\n```text\ndocs/\n data/\n generated/\n cataloLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/identity/",
|
||||
"title": "Identity",
|
||||
"section": "Architecture",
|
||||
"body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry; the older `token_env` field remains a compatibility fallback. Neither\nform changes the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active ideLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/messaging-and-work-intake/",
|
||||
"title": "Messaging and Work Intake",
|
||||
"section": "Architecture",
|
||||
"body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorized user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable SQLite round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletions,Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/migration-decisions/",
|
||||
"title": "Architecture Migration Decisions",
|
||||
"section": "Architecture",
|
||||
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/observability/",
|
||||
"title": "Task Observability",
|
||||
"section": "Architecture",
|
||||
"body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — *\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"* — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see *why*\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and pLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/organisation/",
|
||||
"title": "Repository Organisation",
|
||||
"section": "Architecture",
|
||||
"body": "# Repository Organisation\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Target structure\n\nArchie MUST be organised around cohesive application responsibilities:\n\n```tree\ncmd/\n archied/\n archie-agent/\n\ninternal/\n domain/\n \u003carea\u003e/\n eventbus/\n policy/\n infrastructure/\n configuration/\n eventbus/\n nats/\n forge/\n persistence/\n \u003cexternal-service\u003e/\n app/\n archied/\n agentworker/\n\nplugins/\n \u003cplugin\u003e/\ndeployments/\n \u003csupported-assembly\u003e/\ndocs/\n guides/\nexamples/\n \u003ccopyable-example\u003e/\nextras/\n \u003coptional-extension\u003e/\n```\n\nDomain names are chosen from application behaviour during package review.\nExisting names MUST NOT be retained merely to reduce migration work.\n\n## Domain areas\n\nA domain owns one cohesive job performed by Archie. It contains that job's\nlanguage, state, rules, operations, commands, events, policy implementations,\nruntime settings, and required service contracts.\n\nCode that changes together SHOULD live together. Empty or ceremonial `entities`,\n`repositories`, or `services` layers are prohibited.\n\n## Application composition\n\n`internal/app`:\n\n- constructs domains and infrastructure implementations;\n- translates external configuration into domain and plugin settings;\n- connects commands, events, and shared contracts;\n- starts services in dependency order;\n- owns health aggregation and shutdown ordering.\n\n`cmd/*` parses only process-level input and invokes the relevant application\ncomposition package. It MUST NOT contain substantive wiring or act as a service\nlocator.\n\n## Process boundaries\n\nArchie begins as a modular monolith even when capabilities run in separate\nprocesses. A domain becomes a separately deployed service only for a concrete\nneed such as security isolation, independent scaling, failure containment, or\nindependent operation.\n\nPossible future extraction does not justify premature network protocols or\nduplicated service scaffolding.\n\nA new command is not a reason for a new binary. `cmd/` entries are process\nboundaries: a binary earns its place when its surface fails independently of the\nfleet, or when one process may need to run in more than one location, such as a\nhigh-availability pair or across a NAT boundary. Operational commands over a\nsurface an existing binary already owns are subcommands of that binary. Offline\ndatabase maintenance belongs to `archie-state-store`, which owns the file and\nits path layout, not to a new recovery binary.\n\n## Optional and operational material\n\n- `extras/\u003cextension\u003e` contains a maintained optional extension with real\n behaviour. Core Archie MUST NOT import it, and removing `extras/` MUST NOT\n prevent the core application from building or running.\n- `deployments/\u003cassembly\u003e` contains a supported assembly, including deployment\n definitions and concise operational instructions.\n- `docs/guides/` contains handwritten explanation and links to generated\n reference material.\n- `examples/` contains copyable samples with explicit purpose, prerequisites,\n and support expectations.\n\nSupported assemblies SHOULD demonstrate that capabilities can be selected\nindependently.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/package-review/",
|
||||
"title": "Domain and Feature Review Procedure",
|
||||
"section": "Architecture",
|
||||
"body": "# Domain and Feature Review Procedure\n\n**Status:** Active \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchitecture work proceeds one domain or feature at a time. Before any design\nquestion, the selected area is researched across its complete live\nimplementation, consumers, tests, state, configuration, and runtime wiring.\n\nExisting packages are evidence, not the unit that drives the interview.\nPlacement follows behaviour and ownership, not the existing directory name.\n\nNo restructuring implementation begins until the relevant package decisions\nare agreed and recorded in the focused domain or requirement document.\n\n## Required research\n\nBefore design questions, the current-state report MUST identify:\n\n- entry points and runtime composition;\n- state, persistence, and lifecycle;\n- public and internal contracts;\n- commands, events, and policy enforcement;\n- configuration and defaults;\n- all consumers and cross-domain interactions;\n- process and infrastructure boundaries;\n- tests, failure behaviour, and known invariants;\n- duplicated or conflicting implementations;\n- documentation that disagrees with live code.\n\nDiscoverable facts MUST be investigated rather than presented to the user as\ndesign questions.\n\n## Required decisions\n\nEach package review records:\n\n| Decision | Required result |\n|---|---|\n| Owned behaviour | The cohesive job the code performs |\n| Domain ownership | The owner of the behaviour and vocabulary |\n| Final location | Its target path |\n| Public contracts | The smallest interfaces, commands, and events exposed |\n| Required services | Domain-defined interfaces implemented by infrastructure |\n| State ownership | The owner of each mutable record and transition |\n| Dependencies | Allowed imports and dependencies to remove |\n| Duplication | Code to consolidate, delete, or keep separate |\n| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |\n| Process boundary | In-process, or the concrete reason for isolation |\n| Configuration | Settings owned by the domain or plugin |\n| Policy | Definitions, evaluators, consequences, and shared mechanics used |\n| Documentation | Authoritative definitions and generated reference |\n| Migration constraints | Behaviour and data that must remain correct |\n\n## Interview method\n\nFor every selected domain or feature:\n\n1. Declare the single area under review.\n2. Complete the current-state research.\n3. Explain actual behaviour in plain technical language.\n4. Separate facts from design decisions and concerns.\n5. Resolve obvious consequences directly and ask only questions whose answer\n materially changes behaviour or structure.\n6. Record each confirmed decision in its focused document.\n7. Complete that area's handoff before selecting another.\n8. Keep unrelated domains outside the implementation scope.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/plugins-and-extensions/",
|
||||
"title": "Plugins and Extensions",
|
||||
"section": "Architecture",
|
||||
"body": "# Plugins and Extensions\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Plugin framework\n\nThe core plugin domain lives under `internal/domain/plugin`. It owns:\n\n- plugin identity and metadata;\n- discovery and registration contracts;\n- lifecycle rules;\n- capability registration;\n- validation and compatibility rules.\n\nThe generic plugin contract remains metadata-only. Functionality is exposed\nthrough narrow typed capability contracts with an owning registry or manager.\n\nWorkflow plugins belong to the Workflow capability family. The Workflow domain\nat `internal/domain/workflow` owns their typed registration, validation,\nversioning, definition, and execution contracts. The generic plugin domain may\nprovide plugin identity, discovery, compatibility, and lifecycle mechanics, but\nit MUST NOT define Workflow semantics or expose untyped Workflow hooks.\n\n## Plugin implementations\n\nFirst-party plugins are self-contained vertical modules under\n`plugins/\u003cplugin\u003e`.\n\nA plugin:\n\n- owns its implementation, settings, templates, assets, and tests;\n- receives only explicitly supplied contracts and services;\n- MUST NOT receive daemon internals, a service locator, or unrestricted\n application access;\n- MUST NOT import arbitrary infrastructure or application composition code;\n- MAY use approved domain and shared application contracts;\n- MUST remain removable without changes to unrelated domains.\n\nPlugins may be internally cohesive like small services. They do not become\nnetwork services without a concrete security or operational reason.\n\n## Event sources and reactions\n\n`archie-core-7d5u.1` asked whether extensions should react to events\nin-process through typed capability families (this document's model) or\nout-of-process like a generic `DispatchEvent` dispatcher. Decided 2026-08-22\nin `docs/prds/event-sources-and-reactions.md`: in-process typed families,\nconfirming this document's model rather than amending it. The forge webhook\nreceiver (`internal/forge/webhook`, see `ARCHITECTURE.md`'s \"Webhook intake\"\nsection) and the EDA playbook engine's Module action position\n(`docs/prds/eda-playbook-engine.md`, `internal/domain/eda/module`) are the\nshipped instances of that decision -- each is a narrow typed contract with an\nowning registry, not a generic event hook. The playbook engine's Channel and\nForge action positions are designed but not yet implemented (open\ninvestigation `archie-core-t2db.19`); when they land they follow the same\nmodel, not a new one.\n\n## Curator surprisal sampling\n\n**Decided 2026-08-05, wave 1 landed 2026-09-05** — the curator engine family\n(epic [#435](https://github.com/samcharles93/archie-core/issues/435)) selects which memories deserve agentic attention via\nsurprisal-based sampling: score memories by how surprising they are and\nspend the sampled reasoner's agentic budget on the most surprising items.\n\nThe prerequisites are built: the embeddings capability\n([#436](https://github.com/samcharles93/archie-core/issues/436), `internal/domain/embedding` contract +\n`internal/infrastructure/embedding` implementation, config-driven via\n`models.embedding`) and the wave-1 `Sampler` strategy seam\n(`internal/domain/sampling` -- not `internal/curator`, see\n`docs/prds/curator-sampler-wave1.md` for the settled design and tracking)\nwith four\ncheap, embedding-free strategies (recency, random, all, staleness proxy).\nNo curator consumes a `Sampler` yet, and the embeddings client is likewise\ndeliberately inert: `setupEmbeddings` constructs it at boot and holds it on\n`b.embeddings`, but no production code reads that field yet, so a resolved\n`models.embedding` role currently produces a client whose only observable\neffect is a boot log line. Both are prerequisites waiting on #437, not\nunwired defects.\n\nStill deferred: [#437](https://github.com/samcharles93/archie-core/issues/437), the embedding-backed surprisal strategy, which\ndepends on the above and on [#407](https://github.com/samcharles93/archie-core/issues/407). Requirements for that deferred work,\nso it can be picked up without re-deriving the design:\n\n- A `Sampler` implementation behind the same interface as the cheap\n strategies; selection deterministic given fixed inputs.\n- Algorithm: sample up to a candidate cap; build a k-NN graph over embedding\n vectors; row-normalize the adjacency with self-loops; power-iterate to the\n stationary distribution; surprisal = −log(stationary probability of the\n nearest point); select the highest-surprisal items.\n- Degradation: content without an embedding is skipped; an embedding failure\n aborts sampling and falls back to free exploration — a sampling failure\n must never fail or crash a curator pass.\n- Cost bound: the graph build is quadratic in the candidate cap; the cap must\n be a named constant with a documentLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/policy/",
|
||||
"title": "Policy System",
|
||||
"section": "Architecture",
|
||||
"body": "# Policy System\n\n**Status:** Approved foundation; exact API is deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nRetry limits, authorization, gates, commands, protected paths, tool\navailability, and similar rules define or constrain what Archie may do. They\nneed consistent consumption, composition, evidence, and audit without erasing\ntheir different domain meanings.\n\n## Ownership\n\n`internal/policy` is an explicitly approved shared application contract. It is\nnot infrastructure and it is not a generic domain that owns every rule.\n\nThe shared policy system owns:\n\n- policy identity, version, scope, and applicability;\n- typed evaluation invocation;\n- deterministic composition and precedence;\n- common evaluation states such as satisfied, violated, indeterminate, and not\n applicable;\n- reasons and evidence;\n- evaluation audit records;\n- registration, discovery, and lifecycle.\n\nEach consuming domain owns:\n\n- its policy vocabulary and typed inputs;\n- its concrete policy definitions;\n- its evaluators;\n- the meaning and consequence of an evaluation.\n\nAccess therefore owns principals, resources, actions, and authorization\nconsequences. Task lifecycle owns retry eligibility and exhaustion. Task\nexecution owns gate requirements. Workspace mutation owns protected-path\neffects. Tool execution owns tool and command constraints.\n\nThese policies use consistent evaluation mechanics without pretending their\ndecisions are semantically interchangeable.\n\n## Infrastructure\n\nInfrastructure MAY load, persist, distribute, and audit external policy\nrepresentations. It MUST NOT define what Archie allows or assign the meaning of\na domain policy result.\n\nThe exact Go API, composition operators, precedence rules, and representation\nformat require a focused policy design pass.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/architecture/safe-change-and-recovery/",
|
||||
"title": "Safe Change and Recovery",
|
||||
"section": "Architecture",
|
||||
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in `archie.db`.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure | Boot behaviour | Where the operator sees it |\n| --- | --- | --- |\n| State Store uLine truncated
|
||||
"body": "# Archie\n\nEvent Driven Agentic Automation.\n\nArchie is an agent platform that reacts to events. A forge issue, a signed\nwebhook from any app you run, a message in a chat channel: each arrives as an\nevent, a playbook decides what a matching event sets off, and the work happens\nin an isolated git worktree. GitHub and Gitea issues were the first case. A\nforge is now one event source among several, and a pull request one outcome\namong several.\n\nNothing about that path is wired to a particular forge, channel, or sender.\nSources, the fields they carry, and the workflows they reach are configuration\nyou add without touching code or restarting anything.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) points an external app's webhook\n at archie, maps the fields of a real payload, and binds them to a workflow.\n- [Architecture](/dev/architecture/) is the authority for settled design:\n the domain boundaries, the workflow engine, the task lifecycle, and the\n invariants that hold the whole thing together.\n\n## What runs where\n\nA deployment is a set of services, each owning one typed contract. The Gateway\nserves conversation turns and sessions, the Messaging Service runs the\nchannels, the State Store owns the database outright, the dashboard is its own\nprocess, and `archied` admits work and drives each task through its workflow.\ngRPC carries the synchronous calls between them; NATS carries asynchronous\nfan-out. Agents execute in containers that receive a task-scoped credential,\nissued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/guides/first-playbook/",
|
||||
"title": "Building your first playbook binding",
|
||||
"section": "Guides",
|
||||
"body": "# Building your first playbook binding\n\nThis walks through the whole no-code path the event-capture epic promises:\npoint an external app's webhook at archie, see the real payload it sends,\nmap the fields you care about, bind them to a workflow, and watch the next\nmatching event turn into a task -- no code, no redeploy, no restart. See\n`docs/architecture/bindings.md` for the model and threat model behind each\nstep below.\n\n## 1. Send a test event\n\nPoint whatever external app you want archie to react to at:\n\n```\nPOST http://\u003cyour-archied-host\u003e:8484/webhooks/capture/\u003csource\u003e\n```\n\n`\u003csource\u003e` is a name you choose for this sender (e.g. `sentry`, `github-ci`,\n`stripe`) -- it's just a URL path segment, not a preset list. Send one real\nevent however is easiest for a first test, e.g.:\n\n```bash\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -d '{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\n```\n\nThis event isn't signed yet, so it's captured but marked **unauthenticated**\n-- visible for you to design against, but incapable of triggering anything\n(`docs/architecture/bindings.md`'s threat-model section explains why: an\nunauthenticated event can never match a binding, no matter how it looks).\n\n## 2. Inspect the captured payload\n\nOpen the dashboard's **Event inspector** (`/captures`). Your test event\nappears there with its real body -- this is schema-by-example: you're\nlooking at an actual payload from the actual sender, not guessing at a\nschema in advance.\n\n## 3. Map the fields you care about\n\nOpen **Field mappings** (`/mappings`) → **New mapping**. Pick your captured\nevent from the dropdown, then click through its payload tree on the right --\nevery key and value is clickable. Clicking a value binds it as a field\n(name, JSON path, and an inferred type you can change). Add whichever fields\nyour workflow needs (e.g. the issue title), mark the ones that must be\npresent as **Required**, hit **Preview** to confirm they resolve correctly\nagainst the real payload, then **Save**.\n\n## 4. Create the binding\n\nOpen **Playbook bindings** (`/bindings`) → **New binding**:\n\n- **Name** -- anything descriptive.\n- **Source** -- the same `\u003csource\u003e` segment from step 1 (e.g. `sentry`).\n- **Field mapping** -- the one you just saved.\n- **Workflow** -- which registered workflow should run on a match.\n- **Repo pin** (optional) -- leave both blank to use the single configured\n repo; set owner/repo explicitly if you run a multi-repo deployment.\n- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The\n sender signs every request body with this via HMAC-SHA256 so archie can\n tell a genuine event from anyone who finds the URL.\n\nSave. The binding starts in **draft** -- nothing fires yet.\n\n## 5. Approve it\n\nA **draft** or freshly-**edited** binding needs an explicit human approval\nbefore it can ever match a live event -- this is deliberate, not a missing\nstep: an operator authoring a binding is a considered act, an event arriving\nis not, and nothing should self-arm (`docs/architecture/bindings.md`'s\nthreat-model section, point 2). Click **Approve**. Status becomes **armed**.\n\n## 6. Fire it for real\n\nSend the same kind of event again, this time **signed** with the binding's\nsecret:\n\n```bash\nBODY='{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\nSECRET=\"the-secret-you-set-in-step-4\"\nSIG=$(printf '%s' \"$BODY\" | openssl dgst -sha256 -hmac \"$SECRET\" | sed 's/^.* //')\n\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Hub-Signature-256: sha256=$SIG\" \\\n -d \"$BODY\"\n```\n\nThis event is captured as **authenticated**, matched against your armed\nbinding, and dispatched into a new task through the exact same\ngate/worktree/sandbox pipeline every other task goes through -- see\n`ARCHITECTURE.md`'s Task Lifecycle section, \"Provenance by origin.\" Check\nthe **Tasks** page; a new task should appear, its body built from the fields\nyour mapping resolved.\n\n## Editing a live binding\n\nAny edit to an armed binding -- even a typo fix -- drops it back to\n**pending_approval** automatically. This can't be bypassed by editing; it\nhas to be re-approved. When editing, leave the **Shared secret** field blank\nto keep the existing secret; only fill it in if you're deliberately\nrotating it.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/prds/config-schema/",
|
||||
"title": "Backend-owned configuration schema for the webui -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Backend-owned configuration schema for the webui -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-b6ew` (epic), with children `.1`-`.5`\n\n## Decision\n\nThe dashboard's Configuration page keeps reading a secret-free,\nhand-picked view of `config.Config` -- that allowlist is a safety\nboundary and stays exactly as it is. What changes is who defines the\npage around it: `ui/src/settings/settings.js` and\n`config-row.js` hardcode every row's label, section, type, and\neditability by hand; after this, the backend attaches that metadata to\neach field it already allows through, and the frontend renders\nsections and fields generically from what the backend sends.\n\nThis is **not** a reflection-based schema over `config.Config`.\n`internal/config/config.go`'s own package doc states it is \"scheduled\nfor dissolution: its types and methods are to be reassigned to the\ndomains whose behaviour they describe\" -- building a generic\nschema-from-struct-tags mechanism over a struct on its way out would be\nbuilding on a foundation this repo has already decided to remove.\nInstead, every field already in `ConfigView` (`internal/webui/api_config.go`)\ngot there because someone deliberately vetted it as safe to show; the\nschema adds a hand-authored descriptor to that same deliberate act,\nnot a new mechanism that re-derives safety automatically.\n\n## Why now\n\nTask #6's investigation (`/9/26`) found the concrete failure this\nproduces: `Repo.AllowConcurrent` and `Repo.MaxRetries` already reach\n`GET /api/config` (`RepoView` in `api_config.go`), but the\nrepositories card renders a static read-only table that never shows\nthem, so the fix for \"why isn't a second agent running\" required an\nagent tracing Go source instead of a checkbox on the dashboard.\n`Repo.ReviewEnabled` is worse: it never reaches the API at all. Both\nare symptoms of the same root cause -- the frontend decides what a\nfield means and whether it's shown, and nothing keeps that in sync\nwith what the backend actually allows.\n\n## Shape\n\n```go\n// internal/webui/config_schema.go (new)\n\ntype ConfigFieldType string\n\nconst (\n FieldString ConfigFieldType = \"string\"\n FieldInt ConfigFieldType = \"int\"\n FieldBool ConfigFieldType = \"bool\"\n FieldDuration ConfigFieldType = \"duration\"\n FieldEnum ConfigFieldType = \"enum\"\n FieldStructured ConfigFieldType = \"structured\" // repositories, models, providers\n)\n\ntype ConfigField struct {\n Key string `json:\"key\"` // dotted path, matches UpdateConfig's key space\n Label string `json:\"label\"`\n Description string `json:\"description,omitempty\"`\n Type ConfigFieldType `json:\"type\"`\n Value any `json:\"value\"`\n Editable bool `json:\"editable\"`\n LockedReason string `json:\"locked_reason,omitempty\"`\n Overridden bool `json:\"overridden\"`\n Options []string `json:\"options,omitempty\"` // enum only\n RestartRequired bool `json:\"restart_required\"`\n}\n\ntype ConfigSection struct {\n ID string `json:\"id\"`\n Label string `json:\"label\"`\n Fields []ConfigField `json:\"fields\"`\n}\n```\n\n`handleConfig` builds `[]ConfigSection` from the existing per-field\nvalues it already assembles, plus `overlay.DeniedKeys` for\n`LockedReason` and the existing `Overridden` list -- both already\ncomputed just re-attached per field instead of returned as\nside-channel maps the frontend cross-references by key string.\n`Locked`/`Overridden`/`Reload`/`Provenance` stay as top-level\n`ConfigView` fields; they describe runtime state (what happened on\nthe last reload, which keys the overlay refuses), not the field\ncatalog, and duplicating that logic per-field would be the same drift\nrisk this change exists to remove.\n\n`FieldStructured` fields (repositories, models, providers) carry\n`Value` as structured JSON and are rendered by dedicated\neditors, not the generic renderer -- see \"What this does not do\".\n\n## Sections\n\nMatches the cards the settings page already has: `identity`,\n`repositories`, `models`, `providers`, `budgets`, `storage`,\n`containers`, `web`. No new sections; this is metadata on existing\nrows, not new configuration surface.\n\n## Frontend\n\n`config-row.js`'s `row(label, value, opts)` becomes the renderer's\nprivate implementation detail, called generically:\n\n```js\nfor (const section of schema.sections) {\n const rows = section.fields\n .filter(f =\u003e f.type !== \"structured\")\n .map(f =\u003e row(f.label, f.value, {\n key: f.key, type: f.type, options: f.options,\n locked: f.locked_reason, overridden: f.overridden,\n restartRequired: f.restart_required,\n }));\n // structured fields render through their dedicated editor (b6ew.4)\n}Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/prds/memory-engine-unification/",
|
||||
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n|---|---|---|---|\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n *does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\n string`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_sqlite.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and\n`ScopeAgent{b}` are different storage keys.\n\n`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing\nproduces one yet, but the contract models it because the read set includes it.\n\n### 2. CRUD, with revisions retained\n\n```go\ntype Store interface {\n Create(ctx context.Context, in NewRecord) (Record, error)\n Get(ctx context.Context,Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/prds/messaging-service-boundary/",
|
||||
"title": "Messaging Service boundary and transport design",
|
||||
"section": "PRDs",
|
||||
"body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/docs/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behavior, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections (`*store.Store` or SQLite), owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n|---|---|---|---|\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | `*store.Store`, `SessionStore` SQLite handles, direct database files |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n1. **Telegram long-polling**: Must call `dropPendingUpdates(ctx, b)` before `b.Start(ctx)` and on `/restart`.\n2. **Telegram command menus**: Must register command menus simultaneously to `default`, `all_private_chats`, and `all_group_chats` via `commands.go` to prevent menu shadowing.\n3. **No UI detour**: Turns and task actions route directly to Gateway's `ChatContract`; no HTTP request may ever be sent to `archie-ui` or `internal/webui`.\n4. **Sender Confinement**: Telegram sender checks against `allowed_user_ids` must continue to fail closed before initiating any turn dispatch.\n\n## Configuration Ownership\n\n`cmd/archie-messaging` reads only:\n- `[services.gateway].target` and `[services.gatewLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/prds/service-decomposition/",
|
||||
"title": "Service decomposition -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/docs/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the *processes* running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n|---|---|---|\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/store` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n + EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHEL / Ansible Automation Platform\nmodel: one architecture, sold both ways. This PRD does not decide the\nbusiness model; it decides that the architecture must not foreclose\neither shape.\n\n## Why this shape\n\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`\nestablished that Archie's existing domain split already does what AWX's\nservice-decomposition post argues for -- boundaries exist. What didn't\nexist was deployability: `internal/webui` was not a passive frontend. The\nre-baselined coupling inventory is below, and the ratified boundary is\n[`ui-service-boundary.md`](/docs/prds/ui-service-boundary/).\n\n- Telegram task actions now call Gateway's `ChatContract` directly through\n `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.\n- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct\n `SessionStore`, `Router`, and `TurnHistory` access is historical.\n- The third coupling is closed. UI extraction shipped (`archie-core-8cda.5`,\n closed 2026-09-11): `cmd/archie-ui` serves the dashboard against remote\n Gateway and State Store contracts, holdLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/docs/prds/ui-service-boundary/",
|
||||
"title": "UI Service boundary and configuration ownership",
|
||||
"section": "PRDs",
|
||||
"body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/docs/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behavior, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n|---|---|---|---|\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviorally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status |\n|---|---|---|\n| `/api/chat/*` | Gateway `ChatContract` and its versioned client | contract seam exists; DTO and stream parity remain |\n| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains |\n| `/events` | State Store `EventsSince`, polled by one UI-process pump feeding `Server.Broadcast` | RESOLVED (`archie-core-za9f`): see migration-decisions, \"Dashboard live event delivery\". No new RPC; replay cursor and drop-recovery are the existing `since` watermark in `sse.go` |\n| `/api/logs`, `/api/logs/stream` | daemon diagnostic feed, host-local | unresolved: `logging.Feed` is in-process on the daemon host and has no contract. The per-task log routes moved off this row: see `/api/tasks/*` above |\n| `/api/tasks/{id}/logs`, `/api/tasks/{id}/logs/download` | State Store task-log read contract (`TaskLogStore`: `ReadTaskLog` + `StreamTaskLogContent`), read by the UI process from the service that owns the state directory | RESOLVED (`archie-core-iaqx`): the UI process composes `TaskLogStore` from its own State Store client and serves the attemptLine truncated
|
||||
}
|
||||
],
|
||||
"nav": [
|
||||
@@ -144,72 +18,6 @@
|
||||
"title": "Archie",
|
||||
"url": "/docs/"
|
||||
},
|
||||
{
|
||||
"title": "Architecture",
|
||||
"url": "/docs/architecture/",
|
||||
"items": [
|
||||
{
|
||||
"title": "Adversarial self-review",
|
||||
"url": "/docs/architecture/adversarial-review/"
|
||||
},
|
||||
{
|
||||
"title": "Agent System",
|
||||
"url": "/docs/architecture/agent-system/"
|
||||
},
|
||||
{
|
||||
"title": "Playbook bindings: model and threat model",
|
||||
"url": "/docs/architecture/bindings/"
|
||||
},
|
||||
{
|
||||
"title": "Configuration",
|
||||
"url": "/docs/architecture/configuration/"
|
||||
},
|
||||
{
|
||||
"title": "Dependencies and Contracts",
|
||||
"url": "/docs/architecture/dependencies-and-contracts/"
|
||||
},
|
||||
{
|
||||
"title": "Generated Documentation",
|
||||
"url": "/docs/architecture/generated-documentation/"
|
||||
},
|
||||
{
|
||||
"title": "Identity",
|
||||
"url": "/docs/architecture/identity/"
|
||||
},
|
||||
{
|
||||
"title": "Messaging and Work Intake",
|
||||
"url": "/docs/architecture/messaging-and-work-intake/"
|
||||
},
|
||||
{
|
||||
"title": "Architecture Migration Decisions",
|
||||
"url": "/docs/architecture/migration-decisions/"
|
||||
},
|
||||
{
|
||||
"title": "Task Observability",
|
||||
"url": "/docs/architecture/observability/"
|
||||
},
|
||||
{
|
||||
"title": "Repository Organisation",
|
||||
"url": "/docs/architecture/organisation/"
|
||||
},
|
||||
{
|
||||
"title": "Domain and Feature Review Procedure",
|
||||
"url": "/docs/architecture/package-review/"
|
||||
},
|
||||
{
|
||||
"title": "Plugins and Extensions",
|
||||
"url": "/docs/architecture/plugins-and-extensions/"
|
||||
},
|
||||
{
|
||||
"title": "Policy System",
|
||||
"url": "/docs/architecture/policy/"
|
||||
},
|
||||
{
|
||||
"title": "Safe Change and Recovery",
|
||||
"url": "/docs/architecture/safe-change-and-recovery/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Guides",
|
||||
"items": [
|
||||
@@ -218,31 +26,6 @@
|
||||
"url": "/docs/guides/first-playbook/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "PRDs",
|
||||
"items": [
|
||||
{
|
||||
"title": "Backend-owned configuration schema for the webui -- decision",
|
||||
"url": "/docs/prds/config-schema/"
|
||||
},
|
||||
{
|
||||
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
|
||||
"url": "/docs/prds/memory-engine-unification/"
|
||||
},
|
||||
{
|
||||
"title": "Messaging Service boundary and transport design",
|
||||
"url": "/docs/prds/messaging-service-boundary/"
|
||||
},
|
||||
{
|
||||
"title": "Service decomposition -- decision",
|
||||
"url": "/docs/prds/service-decomposition/"
|
||||
},
|
||||
{
|
||||
"title": "UI Service boundary and configuration ownership",
|
||||
"url": "/docs/prds/ui-service-boundary/"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,75 @@
|
||||
# Public and development documentation -- design
|
||||
|
||||
**Status:** Draft
|
||||
**Date:** 2026-09-22
|
||||
|
||||
## Problem
|
||||
|
||||
One published set carries both kinds of document. A reader who wants to know
|
||||
what Archie is and how to point an event at it lands in a sidebar that also
|
||||
holds the repository organisation rules, the migration decision register, the
|
||||
package review procedure and five PRDs. The PRDs are there for a reason that
|
||||
has nothing to do with the reader: settled architecture cites them, and the
|
||||
generator refuses a link whose target it holds back, so publishing them was the
|
||||
only way to keep those citations alive.
|
||||
|
||||
Mixing them is not an exposure problem. Every one of these documents can be
|
||||
public. It is a navigation problem: a customer reading the site meets
|
||||
contributor material with no signal that it is not for them.
|
||||
|
||||
## Decision
|
||||
|
||||
One source tree, two published sets, two artifacts, two URL bases.
|
||||
|
||||
| Set | Holds | Served under | Artifact |
|
||||
|---|---|---|---|
|
||||
| Public | `index.md`, `guides/` | `/docs/` | `docs/data/generated/docs.json` |
|
||||
| Development | `architecture/`, `prds/` | `/dev/` | `docs/data/generated/dev-docs.json` |
|
||||
|
||||
`archive/`, `inspiration/`, `news/` and `github-token.md` stay out of both, for
|
||||
the reasons the generator already records.
|
||||
|
||||
The two artifacts have the same shape. A renderer reads a second file and
|
||||
serves it under a second base; it needs no new field and no set discriminator,
|
||||
because the file a page arrived in is the set it belongs to.
|
||||
|
||||
## Consequences the design depends on
|
||||
|
||||
**Every PRD publishes.** Selective PRD publication existed to keep citations
|
||||
from settled architecture working. With both cited and citing documents in the
|
||||
development set, that pressure is gone, and the rule that produced it goes with
|
||||
it: `prds/` is a development tree, not a list of exceptions.
|
||||
|
||||
**Cross-set links resolve.** A link from a public page to an architecture page
|
||||
rewrites to the development set's absolute path, and the reverse works the same
|
||||
way. Both sets are generated in one pass over one url map, so a link and its
|
||||
target cannot disagree about where the target lives. The generator's refusal
|
||||
still fires, now only for a target genuinely in neither set.
|
||||
|
||||
**Assets keep the public base.** `docs/public/` is one file set, referenced
|
||||
from either set, and serving one file under two paths would invent a second
|
||||
location for it.
|
||||
|
||||
**The sidebar stays derived from the directory layout**, per set. A page added
|
||||
under a directory appears without a second edit, which is the property the
|
||||
current generator has and the reason its tree mirrors the tree on disk.
|
||||
|
||||
## The public set is thin, and that is the honest state
|
||||
|
||||
Two pages: the landing page and the playbook guide. Nothing is lost by the
|
||||
split, because a reader was never served by the seventeen architecture pages
|
||||
next to them. The pages a public site needs (installation, configuration
|
||||
reference, the event sources, the actions a playbook can run) are written into
|
||||
`guides/` and a `reference/` tree as they are written, and each lands in the
|
||||
public set with no generator change.
|
||||
|
||||
## Verification
|
||||
|
||||
- `task docs:artifact` writes both files; `task docs:artifact:check` fails on a
|
||||
stale copy of either, without touching the tree.
|
||||
- A link from the public set to a development page, and a link the other way,
|
||||
each resolve to the other set's base path in the generated body.
|
||||
- A link to a page in neither set fails the generator, naming the file, the
|
||||
line and the target.
|
||||
- `docsgen` accounts for both artifacts, so neither tool reports the other's
|
||||
file as unowned.
|
||||
@@ -40,14 +40,14 @@ const (
|
||||
// AsyncAPI output), which must not be reported as stale merely for existing.
|
||||
//
|
||||
// docs/data/generated is shared. docsgen writes contracts.json from the
|
||||
// Go contract types; tools/docsite writes docs.json from the Markdown sources.
|
||||
// Each tool verifies its OWN file, and both files are named here because this map
|
||||
// is the directory's ownership record: whichever tool runs first must not report
|
||||
// the other's artifact as an unaccounted file. docsgen does not verify docs.json,
|
||||
// and tools/docsite keeps no registry of its own for that reason -- one fact, one
|
||||
// home.
|
||||
// Go contract types; tools/docsite writes docs.json and dev-docs.json from the
|
||||
// Markdown sources, one per published set. Each tool verifies its OWN files, and
|
||||
// all three are named here because this map is the directory's ownership record:
|
||||
// whichever tool runs first must not report the others' artifacts as unaccounted
|
||||
// files. docsgen does not verify the docsite artifacts, and tools/docsite keeps no
|
||||
// registry of its own for that reason -- one fact, one home.
|
||||
var generatedArtifacts = map[string][]string{
|
||||
"docs/data/generated": {"contracts.json", "docs.json"},
|
||||
"docs/data/generated": {"contracts.json", "docs.json", "dev-docs.json"},
|
||||
}
|
||||
|
||||
// options is a parsed command line.
|
||||
|
||||
+224
-101
@@ -1,26 +1,28 @@
|
||||
// Command docsite derives the public documentation set into one canonical,
|
||||
// host-neutral artifact.
|
||||
// Command docsite derives the documentation sets into canonical, host-neutral
|
||||
// artifacts.
|
||||
//
|
||||
// The Markdown is the source; docs/data/generated/docs.json is the fact set every
|
||||
// renderer reads. MkDocs was the first renderer and the Astro app is the second,
|
||||
// so the artifact is the product and the Markdown stays the source --
|
||||
// tools/newsgen states the same principle for releases, where the JSON is
|
||||
// canonical and the Markdown is an adapter.
|
||||
// The Markdown is the source; the JSON is the fact set every renderer reads.
|
||||
// MkDocs was the first renderer and the Astro app is the second, so the artifact
|
||||
// is the product and the Markdown stays the source -- tools/newsgen states the
|
||||
// same principle for releases, where the JSON is canonical and the Markdown is an
|
||||
// adapter.
|
||||
//
|
||||
// The published set is declared here rather than in a site configuration, because
|
||||
// the exclusions are decisions rather than details: see publishRules. A renderer
|
||||
// that reads this artifact needs no copy of them.
|
||||
// One source tree yields two sets, each with its own artifact and its own url
|
||||
// base: see publishRules for the split and the reasons. A renderer reads both
|
||||
// files and serves each under its own base; the file a page arrives in is the set
|
||||
// it belongs to, so neither carries a discriminator.
|
||||
//
|
||||
// Output is generated and committed:
|
||||
//
|
||||
// docs/data/generated/docs.json
|
||||
// docs/data/generated/dev-docs.json
|
||||
//
|
||||
// `docsite check` regenerates the artifact in a temporary directory and fails when
|
||||
// the committed one differs, without touching the tree.
|
||||
// `docsite check` regenerates both in memory and fails when a committed one
|
||||
// differs, without touching the tree.
|
||||
//
|
||||
// This tool keeps no registry of the generated directory it writes into: that
|
||||
// directory is accounted for by docsgen's generatedArtifacts, which names this
|
||||
// file, so a second registry here would be a second home for one fact.
|
||||
// directory is accounted for by docsgen's generatedArtifacts, which names both
|
||||
// files, so a second registry here would be a second home for one fact.
|
||||
package main
|
||||
|
||||
import (
|
||||
@@ -40,16 +42,27 @@ import (
|
||||
"unicode"
|
||||
)
|
||||
|
||||
// artifactPath is the committed artifact this tool owns, relative to the
|
||||
// repository root.
|
||||
const artifactPath = "docs/data/generated/docs.json"
|
||||
|
||||
// docsDir is the Markdown source tree, relative to the repository root.
|
||||
const docsDir = "docs"
|
||||
|
||||
// urlPrefix is the path every page is served under. The directory-style paths
|
||||
// MkDocs produced are kept exactly, so existing links keep working.
|
||||
const urlPrefix = "/docs/"
|
||||
// docSet is one published set: the pages it holds, the path they are served
|
||||
// under, and the committed artifact this tool writes for it.
|
||||
type docSet struct {
|
||||
Name string
|
||||
URLPrefix string
|
||||
ArtifactPath string
|
||||
}
|
||||
|
||||
// The two sets. The public set keeps the directory-style paths MkDocs produced
|
||||
// exactly, so existing links keep working.
|
||||
var (
|
||||
publicDocs = docSet{Name: "public", URLPrefix: "/docs/", ArtifactPath: "docs/data/generated/docs.json"}
|
||||
developmentDocs = docSet{Name: "development", URLPrefix: "/dev/", ArtifactPath: "docs/data/generated/dev-docs.json"}
|
||||
|
||||
// sets is the write and check order, so a run reports its files the same way
|
||||
// every time.
|
||||
sets = []docSet{publicDocs, developmentDocs}
|
||||
)
|
||||
|
||||
type mode int
|
||||
|
||||
@@ -125,41 +138,46 @@ type navNode struct {
|
||||
Items []navNode `json:"items,omitempty"`
|
||||
}
|
||||
|
||||
// publishRules is the published set, and the reasons, carried from the site
|
||||
// configuration this replaces. Everything under docs/ is public except:
|
||||
// publishRules is the split, and the reasons. Everything under docs/ publishes,
|
||||
// in one set or the other, except:
|
||||
//
|
||||
// - archive/ superseded design. Publishing it competes with the current
|
||||
// architecture for a reader's attention, which is the exact failure this
|
||||
// repository already fights.
|
||||
// - inspiration/ research notes that discuss other products by name.
|
||||
// - prds/ open design decisions rather than settled architecture. Two
|
||||
// kinds of PRD are published anyway, and for different reasons:
|
||||
// · ui-service-boundary.md, service-decomposition.md and config-schema.md
|
||||
// are ratified and read as reference.
|
||||
// · memory-engine-unification.md and messaging-service-boundary.md are
|
||||
// cited by documents of record -- settled architecture and the migration
|
||||
// register -- so excluding them withheld nothing a reader was spared: it
|
||||
// broke citations. A blanket prds/* rule had left those links 404 on the
|
||||
// published site, which is worse than either publishing or not linking.
|
||||
// - news/ release notes, which tools/newsgen owns and a renderer reads
|
||||
// from releases.json.
|
||||
// - github-token.md setup notes about credentials.
|
||||
//
|
||||
// Widening the set means editing this list. The comment is the record: a renderer
|
||||
// that reads the artifact cannot see why a page is absent, and neither can the
|
||||
// next person deciding whether a citation should publish its target.
|
||||
// What remains divides by audience, not by sensitivity: every development page
|
||||
// may be read by anyone. architecture/ and prds/ are written for contributors --
|
||||
// the organisation rules, the migration register, the review procedure, the open
|
||||
// design decisions -- and a reader looking for what Archie is and how to point an
|
||||
// event at it is not served by meeting them in one sidebar. They are the
|
||||
// development set. Everything else is the public set.
|
||||
//
|
||||
// Selective PRD publication is gone with the split rather than carried into it: it
|
||||
// existed only because settled architecture cites PRDs and a link to a held-back
|
||||
// target fails this tool, so five PRDs published to keep citations alive. Both
|
||||
// halves of those citations are now in the development set.
|
||||
//
|
||||
// Changing either set means editing this list. The comment is the record: a
|
||||
// renderer that reads an artifact cannot see why a page is absent from it, and
|
||||
// neither can the next person deciding where a new page belongs.
|
||||
var (
|
||||
heldBackTrees = map[string]bool{"archive": true, "inspiration": true, "news": true}
|
||||
publishedPRDs = map[string]bool{
|
||||
"ui-service-boundary.md": true,
|
||||
"service-decomposition.md": true,
|
||||
"config-schema.md": true,
|
||||
"memory-engine-unification.md": true,
|
||||
"messaging-service-boundary.md": true,
|
||||
}
|
||||
heldBackPages = map[string]bool{"github-token.md": true}
|
||||
heldBackTrees = map[string]bool{"archive": true, "inspiration": true, "news": true}
|
||||
heldBackPages = map[string]bool{"github-token.md": true}
|
||||
developmentTree = map[string]bool{"architecture": true, "prds": true}
|
||||
)
|
||||
|
||||
// setFor is the set one published page belongs to, by its top-level directory.
|
||||
func setFor(relative string) docSet {
|
||||
if developmentTree[strings.Split(relative, "/")[0]] {
|
||||
return developmentDocs
|
||||
}
|
||||
return publicDocs
|
||||
}
|
||||
|
||||
// heldBack reports whether one path relative to docs/ is deliberately absent from
|
||||
// the published set. Links and pages are judged by this one rule, so a page is
|
||||
// never published while a link to it is refused, or the reverse.
|
||||
@@ -167,17 +185,10 @@ func heldBack(relative string) bool {
|
||||
if heldBackPages[relative] {
|
||||
return true
|
||||
}
|
||||
segments := strings.Split(relative, "/")
|
||||
if heldBackTrees[segments[0]] {
|
||||
return true
|
||||
}
|
||||
if segments[0] == "prds" && len(segments) > 1 && !publishedPRDs[strings.Join(segments[1:], "/")] {
|
||||
return true
|
||||
}
|
||||
return false
|
||||
return heldBackTrees[strings.Split(relative, "/")[0]]
|
||||
}
|
||||
|
||||
// published reports whether one path relative to docs/ is a page the artifact
|
||||
// published reports whether one path relative to docs/ is a page either artifact
|
||||
// carries.
|
||||
func published(relative string) bool {
|
||||
return strings.HasSuffix(relative, ".md") && !heldBack(relative)
|
||||
@@ -187,6 +198,53 @@ func published(relative string) bool {
|
||||
// part this tool rewrites; everything else in the match is preserved.
|
||||
var intraDocsLink = regexp.MustCompile(`\]\(\s*([^)\s]+)`)
|
||||
|
||||
// fenceDelimiter opens or closes a fenced code block.
|
||||
var fenceDelimiter = regexp.MustCompile("^\\s*(```|~~~)")
|
||||
|
||||
// maskCode blanks the code spans in one line, keeping its length and every other
|
||||
// byte, so a link match found in the masked line indexes the real one. Code is
|
||||
// prose to a Markdown renderer's link parser: `Resolve[T](i, src)` is a generic
|
||||
// call, not a link to `i,`, and the difference is the backticks.
|
||||
func maskCode(line string) string {
|
||||
masked := []byte(line)
|
||||
for index := 0; index < len(masked); {
|
||||
if masked[index] != '`' {
|
||||
index++
|
||||
continue
|
||||
}
|
||||
open := index
|
||||
for index < len(masked) && masked[index] == '`' {
|
||||
index++
|
||||
}
|
||||
run := index - open
|
||||
closed := -1
|
||||
for scan := index; scan < len(masked); {
|
||||
if masked[scan] != '`' {
|
||||
scan++
|
||||
continue
|
||||
}
|
||||
start := scan
|
||||
for scan < len(masked) && masked[scan] == '`' {
|
||||
scan++
|
||||
}
|
||||
if scan-start == run {
|
||||
closed = scan
|
||||
break
|
||||
}
|
||||
}
|
||||
// An unclosed run is literal text to a Markdown renderer, so it is literal
|
||||
// here too and the scan continues past it.
|
||||
if closed < 0 {
|
||||
continue
|
||||
}
|
||||
for blank := open; blank < closed; blank++ {
|
||||
masked[blank] = ' '
|
||||
}
|
||||
index = closed
|
||||
}
|
||||
return string(masked)
|
||||
}
|
||||
|
||||
// unresolvedLink names a link the artifact cannot honestly carry: its target is a
|
||||
// page or asset the published set holds back. It is reported rather than rewritten
|
||||
// to a hopeful URL or dropped, because such a link exists only because a site build
|
||||
@@ -299,11 +357,12 @@ func linkResolver(relative string, urls map[string]string, slugs map[string]map[
|
||||
}
|
||||
return url + fragment, ""
|
||||
}
|
||||
// An asset is served at its own path, when the set does not hold it back
|
||||
// and it is actually there.
|
||||
// An asset is served at its own path under the public base, whichever set
|
||||
// links to it: docs/public/ is one file set, and serving one file under two
|
||||
// paths would invent a second location for it.
|
||||
if !heldBack(resolved) {
|
||||
if _, err := os.Stat(filepath.Join(sourceDir, filepath.FromSlash(resolved))); err == nil {
|
||||
return urlPrefix + resolved + fragment, ""
|
||||
return publicDocs.URLPrefix + resolved + fragment, ""
|
||||
}
|
||||
}
|
||||
return "", whyTargetAbsent
|
||||
@@ -311,30 +370,47 @@ func linkResolver(relative string, urls map[string]string, slugs map[string]map[
|
||||
}
|
||||
|
||||
// resolveLinks rewrites every intra-docs link in body and reports the ones whose
|
||||
// target the published set holds back.
|
||||
// target neither set carries. Code is skipped, span and block alike: what a
|
||||
// Markdown renderer draws as a link is the only thing this tool may rewrite, and
|
||||
// the only thing it may refuse a page for.
|
||||
func resolveLinks(relative, body string, urls map[string]string, slugs map[string]map[string]bool, sourceDir string) (string, []unresolvedLink) {
|
||||
resolve := linkResolver(relative, urls, slugs, sourceDir)
|
||||
var unresolved []unresolvedLink
|
||||
lines := strings.Split(body, "\n")
|
||||
inFence := false
|
||||
for index, line := range lines {
|
||||
lines[index] = intraDocsLink.ReplaceAllStringFunc(line, func(match string) string {
|
||||
target := strings.TrimSpace(strings.TrimPrefix(match, "]("))
|
||||
if fenceDelimiter.MatchString(line) {
|
||||
inFence = !inFence
|
||||
continue
|
||||
}
|
||||
if inFence {
|
||||
continue
|
||||
}
|
||||
var rewritten strings.Builder
|
||||
end := 0
|
||||
for _, match := range intraDocsLink.FindAllStringSubmatchIndex(maskCode(line), -1) {
|
||||
target := line[match[2]:match[3]]
|
||||
replacement, why := resolve(target)
|
||||
if why != "" {
|
||||
unresolved = append(unresolved, unresolvedLink{File: relative, Line: index + 1, Target: target, Why: why})
|
||||
return match
|
||||
continue
|
||||
}
|
||||
return "](" + replacement
|
||||
})
|
||||
rewritten.WriteString(line[end:match[2]])
|
||||
rewritten.WriteString(replacement)
|
||||
end = match[3]
|
||||
}
|
||||
if end == 0 {
|
||||
continue
|
||||
}
|
||||
rewritten.WriteString(line[end:])
|
||||
lines[index] = rewritten.String()
|
||||
}
|
||||
return strings.Join(lines, "\n"), unresolved
|
||||
}
|
||||
|
||||
// load reads every published page and derives the sidebar from the layout, which
|
||||
// is how MkDocs derived it: a page added under a directory appears without a
|
||||
// second edit anywhere.
|
||||
func load(repoRoot string) (document, error) {
|
||||
sourceDir := filepath.Join(repoRoot, docsDir)
|
||||
// readPages reads the source of every page either set carries, keyed by its path
|
||||
// relative to docs/.
|
||||
func readPages(sourceDir string) (map[string]string, error) {
|
||||
bodies := map[string]string{}
|
||||
err := filepath.WalkDir(sourceDir, func(filename string, entry fs.DirEntry, err error) error {
|
||||
if err != nil {
|
||||
@@ -359,10 +435,29 @@ func load(repoRoot string) (document, error) {
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
return document{}, fmt.Errorf("walk %s: %w", docsDir, err)
|
||||
return nil, fmt.Errorf("walk %s: %w", docsDir, err)
|
||||
}
|
||||
if len(bodies) == 0 {
|
||||
return document{}, fmt.Errorf("no published pages under %s", docsDir)
|
||||
return nil, fmt.Errorf("no published pages under %s", docsDir)
|
||||
}
|
||||
return bodies, nil
|
||||
}
|
||||
|
||||
// setDocument pairs one set with the artifact generated for it.
|
||||
type setDocument struct {
|
||||
Set docSet
|
||||
Document document
|
||||
}
|
||||
|
||||
// load reads every published page and derives each set's sidebar from the layout,
|
||||
// which is how MkDocs derived it: a page added under a directory appears without a
|
||||
// second edit anywhere. Both sets are built in one pass over one url map, so a
|
||||
// link that crosses between them resolves to the base its target is served under.
|
||||
func load(repoRoot string) ([]setDocument, error) {
|
||||
sourceDir := filepath.Join(repoRoot, docsDir)
|
||||
bodies, err := readPages(sourceDir)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// Every page's url first, so a link resolves against the whole set rather than
|
||||
@@ -374,12 +469,13 @@ func load(repoRoot string) (document, error) {
|
||||
slugs[relative] = headingSlugs(body)
|
||||
}
|
||||
|
||||
var doc document
|
||||
pages := map[string][]page{}
|
||||
var unresolved []unresolvedLink
|
||||
for relative, body := range bodies {
|
||||
resolved, missing := resolveLinks(relative, body, urls, slugs, sourceDir)
|
||||
unresolved = append(unresolved, missing...)
|
||||
doc.Pages = append(doc.Pages, page{
|
||||
set := setFor(relative)
|
||||
pages[set.Name] = append(pages[set.Name], page{
|
||||
URL: urls[relative],
|
||||
Title: pageTitle(relative, body),
|
||||
Section: sectionFor(relative),
|
||||
@@ -397,28 +493,40 @@ func load(repoRoot string) (document, error) {
|
||||
for _, link := range unresolved {
|
||||
problems = append(problems, link.Error())
|
||||
}
|
||||
return document{}, fmt.Errorf(
|
||||
return nil, fmt.Errorf(
|
||||
"%d link(s) cannot be carried; see each reason:\n %s",
|
||||
len(unresolved), strings.Join(problems, "\n "))
|
||||
}
|
||||
|
||||
sort.Slice(doc.Pages, func(i, j int) bool { return doc.Pages[i].URL < doc.Pages[j].URL })
|
||||
doc.Nav = navFor(doc.Pages)
|
||||
return doc, nil
|
||||
generated := make([]setDocument, 0, len(sets))
|
||||
for _, set := range sets {
|
||||
entries := pages[set.Name]
|
||||
if len(entries) == 0 {
|
||||
return nil, fmt.Errorf("no pages in the %s set", set.Name)
|
||||
}
|
||||
sort.Slice(entries, func(i, j int) bool { return entries[i].URL < entries[j].URL })
|
||||
generated = append(generated, setDocument{
|
||||
Set: set,
|
||||
Document: document{Pages: entries, Nav: navFor(entries, set.URLPrefix)},
|
||||
})
|
||||
}
|
||||
return generated, nil
|
||||
}
|
||||
|
||||
// pageURL is the directory-style path a static site produces for one source file:
|
||||
// docs/index.md is the root, docs/a/index.md is the section's own landing page,
|
||||
// and docs/a/b.md is a page inside it.
|
||||
// pageURL is the directory-style path a static site produces for one source file,
|
||||
// under the base of the set the file belongs to: docs/index.md is the public
|
||||
// root, docs/a/index.md is a section's own landing page, and docs/a/b.md is a page
|
||||
// inside it.
|
||||
func pageURL(relative string) string {
|
||||
prefix := setFor(relative).URLPrefix
|
||||
if relative == "index.md" {
|
||||
return urlPrefix
|
||||
return prefix
|
||||
}
|
||||
dir, file := path.Split(relative)
|
||||
if file == "index.md" {
|
||||
return urlPrefix + dir // path.Split keeps the trailing slash
|
||||
return prefix + dir // path.Split keeps the trailing slash
|
||||
}
|
||||
return urlPrefix + dir + strings.TrimSuffix(file, ".md") + "/"
|
||||
return prefix + dir + strings.TrimSuffix(file, ".md") + "/"
|
||||
}
|
||||
|
||||
// pageTitle is the page's own first heading, which is the title its author chose,
|
||||
@@ -463,7 +571,7 @@ func readableName(name string) string {
|
||||
// navFor derives the sidebar tree from the pages. At each level the landing page
|
||||
// comes first and the rest follow alphabetically, so a reader meets the section's
|
||||
// own page before its children -- the order a static site's navigation uses.
|
||||
func navFor(pages []page) []navNode {
|
||||
func navFor(pages []page, urlPrefix string) []navNode {
|
||||
type node struct {
|
||||
title string
|
||||
url string
|
||||
@@ -536,14 +644,24 @@ func marshal(doc document) ([]byte, error) {
|
||||
return append(encoded, '\n'), nil
|
||||
}
|
||||
|
||||
// write regenerates the artifact, leaving the file untouched when its bytes
|
||||
// write regenerates every artifact, leaving a file untouched when its bytes
|
||||
// already match so a no-op run does not churn the tree.
|
||||
func write(repoRoot string) error {
|
||||
doc, err := load(repoRoot)
|
||||
generated, err := load(repoRoot)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
encoded, err := marshal(doc)
|
||||
for _, entry := range generated {
|
||||
if err := writeSet(repoRoot, entry); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func writeSet(repoRoot string, entry setDocument) error {
|
||||
artifactPath := entry.Set.ArtifactPath
|
||||
encoded, err := marshal(entry.Document)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
@@ -562,38 +680,43 @@ func write(repoRoot string) error {
|
||||
if err := os.WriteFile(target, encoded, 0o644); err != nil {
|
||||
return fmt.Errorf("write %s: %w", artifactPath, err)
|
||||
}
|
||||
fmt.Printf("docsite: wrote %s (%d pages)\n", artifactPath, len(doc.Pages))
|
||||
fmt.Printf("docsite: wrote %s (%d pages)\n", artifactPath, len(entry.Document.Pages))
|
||||
return nil
|
||||
}
|
||||
|
||||
// check regenerates into a temporary directory and compares, so a source edit that
|
||||
// has not been reflected in the committed artifact fails without the tree being
|
||||
// touched.
|
||||
// check regenerates in memory and compares, so a source edit that has not been
|
||||
// reflected in a committed artifact fails without the tree being touched.
|
||||
func check(repoRoot string) error {
|
||||
tmpDir, err := os.MkdirTemp("", "docsite-check-")
|
||||
if err != nil {
|
||||
return fmt.Errorf("create temporary directory: %w", err)
|
||||
}
|
||||
defer func() { _ = os.RemoveAll(tmpDir) }()
|
||||
|
||||
generated, err := load(repoRoot)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
expected, err := marshal(generated)
|
||||
for _, entry := range generated {
|
||||
if err := checkSet(repoRoot, entry); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
const regenerate = "regenerate it by running `go -C tools run ./docsite --repo-root ..` from the tools module"
|
||||
|
||||
func checkSet(repoRoot string, entry setDocument) error {
|
||||
artifactPath := entry.Set.ArtifactPath
|
||||
expected, err := marshal(entry.Document)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
committed, err := os.ReadFile(filepath.Join(repoRoot, artifactPath))
|
||||
if errors.Is(err, fs.ErrNotExist) {
|
||||
return fmt.Errorf("%s is missing; regenerate it by running `go -C tools run ./docsite --repo-root ..` from the tools module", artifactPath)
|
||||
return fmt.Errorf("%s is missing; %s", artifactPath, regenerate)
|
||||
}
|
||||
if err != nil {
|
||||
return fmt.Errorf("read %s: %w", artifactPath, err)
|
||||
}
|
||||
if bytes.Equal(expected, committed) {
|
||||
fmt.Printf("docsite: %s is up to date (%d pages)\n", artifactPath, len(generated.Pages))
|
||||
return nil
|
||||
if !bytes.Equal(expected, committed) {
|
||||
return fmt.Errorf("%s is stale; %s", artifactPath, regenerate)
|
||||
}
|
||||
return fmt.Errorf("%s is stale; regenerate it by running `go -C tools run ./docsite --repo-root ..` from the tools module", artifactPath)
|
||||
fmt.Printf("docsite: %s is up to date (%d pages)\n", artifactPath, len(entry.Document.Pages))
|
||||
return nil
|
||||
}
|
||||
+173
-109
@@ -7,26 +7,85 @@ import (
|
||||
"testing"
|
||||
)
|
||||
|
||||
// TestPublishedSetIsTheDecision pins the count against the real tree. The number
|
||||
// is the decision this tool carries: everything under docs/ is public except five
|
||||
// named exclusions, so a page added or removed on purpose has to be
|
||||
// acknowledged here rather than sliding into the published site.
|
||||
func TestPublishedSetIsTheDecision(t *testing.T) {
|
||||
doc, err := load("../..")
|
||||
// documentFor is the generated artifact for one set.
|
||||
func documentFor(t *testing.T, generated []setDocument, set docSet) document {
|
||||
t.Helper()
|
||||
for _, entry := range generated {
|
||||
if entry.Set.Name == set.Name {
|
||||
return entry.Document
|
||||
}
|
||||
}
|
||||
t.Fatalf("no %s set was generated", set.Name)
|
||||
return document{}
|
||||
}
|
||||
|
||||
// TestTheSplitIsByAudience pins the two sets against the real tree. The public
|
||||
// set is a decision page by page, so its contents are listed: a page joining or
|
||||
// leaving what a customer reads has to be acknowledged here rather than sliding
|
||||
// onto the site. The development set is a rule rather than a list, because a PRD
|
||||
// is added most weeks and pinning a count would make this test a chore that
|
||||
// teaches nothing.
|
||||
func TestTheSplitIsByAudience(t *testing.T) {
|
||||
generated, err := load("../..")
|
||||
if err != nil {
|
||||
t.Fatalf("load: %v", err)
|
||||
}
|
||||
if len(doc.Pages) != 23 {
|
||||
titles := make([]string, 0, len(doc.Pages))
|
||||
for _, entry := range doc.Pages {
|
||||
titles = append(titles, entry.URL)
|
||||
public := documentFor(t, generated, publicDocs)
|
||||
development := documentFor(t, generated, developmentDocs)
|
||||
|
||||
publicURLs := urlSet(t, public)
|
||||
if len(publicURLs) != 2 {
|
||||
t.Errorf("public set = %v, want the landing page and the guide", sortedKeys(publicURLs))
|
||||
}
|
||||
for _, want := range []string{"/docs/", "/docs/guides/first-playbook/"} {
|
||||
if !publicURLs[want] {
|
||||
t.Errorf("%s is not in the public set", want)
|
||||
}
|
||||
t.Fatalf("pages = %d, want the 21 the published set declares:\n %s", len(doc.Pages), strings.Join(titles, "\n "))
|
||||
}
|
||||
|
||||
published := map[string]bool{}
|
||||
developmentURLs := urlSet(t, development)
|
||||
for _, want := range []string{
|
||||
"/dev/architecture/",
|
||||
"/dev/architecture/organisation/",
|
||||
"/dev/prds/ui-service-boundary/",
|
||||
// Selective PRD publication is gone: an open PRD is a development page like
|
||||
// any other, which is what removes the pressure that published five of them
|
||||
// to keep citations from settled architecture alive.
|
||||
"/dev/prds/curator-sampler-wave1/",
|
||||
} {
|
||||
if !developmentURLs[want] {
|
||||
t.Errorf("%s is not in the development set", want)
|
||||
}
|
||||
}
|
||||
|
||||
// Neither set may carry the other's pages, and neither may carry a held-back
|
||||
// tree.
|
||||
for url := range publicURLs {
|
||||
if strings.HasPrefix(url, "/docs/architecture/") || strings.HasPrefix(url, "/docs/prds/") {
|
||||
t.Errorf("%s is in the public set; architecture/ and prds/ are development pages", url)
|
||||
}
|
||||
}
|
||||
for url := range developmentURLs {
|
||||
if !strings.HasPrefix(url, "/dev/") {
|
||||
t.Errorf("%s is in the development set but is not served under its base", url)
|
||||
}
|
||||
}
|
||||
for _, held := range []string{"archive/", "inspiration/", "news/", "github-token/"} {
|
||||
for _, url := range append(sortedKeys(publicURLs), sortedKeys(developmentURLs)...) {
|
||||
if strings.Contains(url, held) {
|
||||
t.Errorf("%s is published; it is held back deliberately", url)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// urlSet indexes a set's pages by url, asserting on the way that each carries the
|
||||
// body a renderer needs.
|
||||
func urlSet(t *testing.T, doc document) map[string]bool {
|
||||
t.Helper()
|
||||
urls := map[string]bool{}
|
||||
for _, entry := range doc.Pages {
|
||||
published[entry.URL] = true
|
||||
urls[entry.URL] = true
|
||||
if entry.Body == "" {
|
||||
t.Errorf("%s carries no body; the artifact is the source a renderer needs", entry.URL)
|
||||
}
|
||||
@@ -34,53 +93,34 @@ func TestPublishedSetIsTheDecision(t *testing.T) {
|
||||
t.Errorf("%s body does not start with a heading: %q", entry.URL, firstLine(entry.Body))
|
||||
}
|
||||
}
|
||||
for _, held := range []string{"/docs/archive/", "/docs/inspiration/", "/docs/news/", "/docs/github-token/"} {
|
||||
for url := range published {
|
||||
if strings.HasPrefix(url, held) {
|
||||
t.Errorf("%s is published; it is held back deliberately", url)
|
||||
}
|
||||
}
|
||||
}
|
||||
for _, want := range []string{
|
||||
"/docs/",
|
||||
"/docs/architecture/organisation/",
|
||||
"/docs/prds/ui-service-boundary/",
|
||||
"/docs/prds/service-decomposition/",
|
||||
"/docs/prds/config-schema/",
|
||||
// Cited by documents of record, so a blanket prds/* exclusion had left
|
||||
// these links 404 on the published site.
|
||||
"/docs/prds/memory-engine-unification/",
|
||||
"/docs/prds/messaging-service-boundary/",
|
||||
} {
|
||||
if !published[want] {
|
||||
t.Errorf("%s is not published; the set declares it", want)
|
||||
}
|
||||
}
|
||||
// An unpublished PRD is the common case, so one absence is asserted to keep the
|
||||
// rule from being satisfied by publishing everything.
|
||||
if published["/docs/prds/curator-sampler-wave1/"] {
|
||||
t.Error("an open PRD is published; prds/ is held back except the ratified and cited ones")
|
||||
return urls
|
||||
}
|
||||
|
||||
func sortedKeys(urls map[string]bool) []string {
|
||||
keys := make([]string, 0, len(urls))
|
||||
for url := range urls {
|
||||
keys = append(keys, url)
|
||||
}
|
||||
return keys
|
||||
}
|
||||
|
||||
func firstLine(body string) string {
|
||||
line := body
|
||||
if index := strings.IndexByte(body, '\n'); index >= 0 {
|
||||
line = body[:index]
|
||||
}
|
||||
line, _, _ := strings.Cut(body, "\n")
|
||||
return line
|
||||
}
|
||||
|
||||
// TestPageURLsAreTheStaticSitePaths: every existing link points at the
|
||||
// directory-style path a static site produces, so the artifact has to reproduce
|
||||
// it exactly rather than inventing a cleaner one.
|
||||
// it exactly rather than inventing a cleaner one. The base is the one its set is
|
||||
// served under.
|
||||
func TestPageURLsAreTheStaticSitePaths(t *testing.T) {
|
||||
for _, tc := range []struct{ relative, want string }{
|
||||
{"index.md", "/docs/"},
|
||||
{"architecture/index.md", "/docs/architecture/"},
|
||||
{"architecture/organisation.md", "/docs/architecture/organisation/"},
|
||||
{"prds/config-schema.md", "/docs/prds/config-schema/"},
|
||||
{"guides/first-playbook.md", "/docs/guides/first-playbook/"},
|
||||
{"guides/nested/deep.md", "/docs/guides/nested/deep/"},
|
||||
{"architecture/index.md", "/dev/architecture/"},
|
||||
{"architecture/organisation.md", "/dev/architecture/organisation/"},
|
||||
{"prds/config-schema.md", "/dev/prds/config-schema/"},
|
||||
} {
|
||||
if got := pageURL(tc.relative); got != tc.want {
|
||||
t.Errorf("pageURL(%q) = %q, want %q", tc.relative, got, tc.want)
|
||||
@@ -94,52 +134,54 @@ func TestPageURLsAreTheStaticSitePaths(t *testing.T) {
|
||||
func TestNavMirrorsTheLayout(t *testing.T) {
|
||||
nav := navFor([]page{
|
||||
{URL: "/docs/", Title: "Archie"},
|
||||
{URL: "/docs/architecture/", Title: "Architecture"},
|
||||
{URL: "/docs/architecture/organisation/", Title: "Organisation"},
|
||||
{URL: "/docs/architecture/policy/", Title: "Policy"},
|
||||
{URL: "/docs/guides/first-playbook/", Title: "Building your first playbook binding"},
|
||||
})
|
||||
if len(nav) != 3 {
|
||||
t.Fatalf("nav = %+v, want home plus two groups", nav)
|
||||
}, publicDocs.URLPrefix)
|
||||
if len(nav) != 2 {
|
||||
t.Fatalf("nav = %+v, want home plus one group", nav)
|
||||
}
|
||||
if nav[0].URL != "/docs/" {
|
||||
t.Errorf("first entry = %+v, want the home page", nav[0])
|
||||
}
|
||||
architecture := nav[1]
|
||||
if architecture.Title != "Architecture" || architecture.URL != "/docs/architecture/" {
|
||||
// A directory holding one page is still a group: collapsing it would be a
|
||||
// shape this artifact invented rather than one it reports.
|
||||
guides := nav[1]
|
||||
if guides.Title != "Guides" || len(guides.Items) != 1 || guides.Items[0].URL != "/docs/guides/first-playbook/" {
|
||||
t.Errorf("guides = %+v, want a group wrapping its single page", guides)
|
||||
}
|
||||
|
||||
// The development set has no page of its own at its base, so its sidebar opens
|
||||
// with the sections rather than a home link.
|
||||
devNav := navFor([]page{
|
||||
{URL: "/dev/architecture/", Title: "Architecture"},
|
||||
{URL: "/dev/architecture/organisation/", Title: "Organisation"},
|
||||
{URL: "/dev/architecture/policy/", Title: "Policy"},
|
||||
{URL: "/dev/prds/config-schema/", Title: "Config schema"},
|
||||
}, developmentDocs.URLPrefix)
|
||||
if len(devNav) != 2 {
|
||||
t.Fatalf("nav = %+v, want the two sections and no home entry", devNav)
|
||||
}
|
||||
architecture := devNav[0]
|
||||
if architecture.Title != "Architecture" || architecture.URL != "/dev/architecture/" {
|
||||
t.Errorf("group = %+v, want the section with its own landing page", architecture)
|
||||
}
|
||||
if len(architecture.Items) != 2 || architecture.Items[0].Title != "Organisation" {
|
||||
t.Errorf("items = %+v, want the section's pages in order", architecture.Items)
|
||||
}
|
||||
// A directory holding one page is still a group: collapsing it would be a
|
||||
// shape this artifact invented rather than one it reports.
|
||||
guides := nav[2]
|
||||
if guides.Title != "Guides" || len(guides.Items) != 1 || guides.Items[0].URL != "/docs/guides/first-playbook/" {
|
||||
t.Errorf("guides = %+v, want a group wrapping its single page", guides)
|
||||
}
|
||||
}
|
||||
|
||||
// TestCheckFailsOnAStaleArtifactAndLeavesTheTreeAlone: check is what runs in the
|
||||
// gate, so it has to fail on a source edit that never reached the artifact without
|
||||
// writing anything itself.
|
||||
// gate, so it has to fail on a source edit that never reached an artifact without
|
||||
// writing anything itself. A stale development artifact fails it exactly as a
|
||||
// stale public one does; before both were checked, a change to a development page
|
||||
// could land with no artifact carrying it.
|
||||
func TestCheckFailsOnAStaleArtifactAndLeavesTheTreeAlone(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
writeFile(t, filepath.Join(root, "docs", "index.md"), "# Archie\n\nHello.\n")
|
||||
writeFile(t, filepath.Join(root, "docs", "architecture", "policy.md"), "# Policy\n\nRules.\n")
|
||||
writeFile(t, filepath.Join(root, "docs", "archive", "old.md"), "# Old\n\nSuperseded.\n")
|
||||
stale := filepath.Join(root, "docs", "data", "generated", "docs.json")
|
||||
writeFile(t, stale, "{}\n")
|
||||
|
||||
if err := check(root); err == nil {
|
||||
t.Fatal("check(stale) = nil, want a failure: the committed artifact disagrees with the sources")
|
||||
}
|
||||
before, err := os.ReadFile(stale)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(before) != "{}\n" {
|
||||
t.Fatalf("check rewrote the artifact: %q", before)
|
||||
t.Fatal("check(missing) = nil, want a failure: no artifact is committed")
|
||||
}
|
||||
|
||||
if err := write(root); err != nil {
|
||||
@@ -149,12 +191,28 @@ func TestCheckFailsOnAStaleArtifactAndLeavesTheTreeAlone(t *testing.T) {
|
||||
t.Fatalf("check after write = %v, want it to pass", err)
|
||||
}
|
||||
|
||||
doc, err := load(root)
|
||||
stale := filepath.Join(root, "docs", "data", "generated", "dev-docs.json")
|
||||
writeFile(t, stale, "{}\n")
|
||||
if err := check(root); err == nil {
|
||||
t.Fatal("check(stale development artifact) = nil, want a failure")
|
||||
}
|
||||
before, err := os.ReadFile(stale)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(doc.Pages) != 2 {
|
||||
t.Fatalf("pages = %d, want the two published pages (archive/ is held back)", len(doc.Pages))
|
||||
if string(before) != "{}\n" {
|
||||
t.Fatalf("check rewrote the artifact: %q", before)
|
||||
}
|
||||
|
||||
generated, err := load(root)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if pages := documentFor(t, generated, publicDocs).Pages; len(pages) != 1 {
|
||||
t.Fatalf("public pages = %d, want the landing page alone", len(pages))
|
||||
}
|
||||
if pages := documentFor(t, generated, developmentDocs).Pages; len(pages) != 1 {
|
||||
t.Fatalf("development pages = %d, want the architecture page alone (archive/ is held back)", len(pages))
|
||||
}
|
||||
}
|
||||
|
||||
@@ -168,23 +226,24 @@ func writeFile(t *testing.T, path, content string) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestLinksResolveInsideTheSetAndFailOutside pins both halves of link handling.
|
||||
// TestLinksResolveAcrossSetsAndFailOutsideThem pins both halves of link handling.
|
||||
// An intra-docs link becomes the target page's url, using the same rule that
|
||||
// builds the target's url, and anchors and scheme-qualified links pass through. A
|
||||
// link whose target the set holds back fails the load, naming the file, the line
|
||||
// and the target: that refusal is what made a blanket prds/* exclusion visible,
|
||||
// because three citations from settled architecture had been 404s on the published
|
||||
// site, and a hopeful rewrite would have hidden them.
|
||||
func TestLinksResolveInsideTheSetAndFailOutside(t *testing.T) {
|
||||
// builds the target's url, so a citation that crosses from one set to the other
|
||||
// lands on the base its target is actually served under. Anchors and
|
||||
// scheme-qualified links pass through. A link whose target neither set carries
|
||||
// fails the load, naming the file, the line and the target, because a hopeful
|
||||
// rewrite would hide a 404 rather than report it.
|
||||
func TestLinksResolveAcrossSetsAndFailOutsideThem(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
writeFile(t, filepath.Join(root, "docs", "organisation.md"), "# Organisation\n\nBack [home](index.md).\n")
|
||||
writeFile(t, filepath.Join(root, "docs", "architecture", "organisation.md"),
|
||||
"# Organisation\n\nBack [home](../index.md).\n")
|
||||
writeFile(t, filepath.Join(root, "docs", "archive", "old.md"), "# Old\n")
|
||||
writeFile(t, filepath.Join(root, "docs", "index.md"),
|
||||
"# Archie\n\nSee [Organisation](organisation.md#organisation).\n\n[Old](archive/old.md) is held back.\n")
|
||||
"# Archie\n\nSee [Organisation](architecture/organisation.md#organisation).\n\n[Old](archive/old.md) is held back.\n")
|
||||
|
||||
_, err := load(root)
|
||||
if err == nil {
|
||||
t.Fatal("load = nil, want a refusal: a published page links into archive/, which the set holds back")
|
||||
t.Fatal("load = nil, want a refusal: a page links into archive/, which is held back")
|
||||
}
|
||||
for _, want := range []string{"index.md:5", "archive/old.md", "not in the published set"} {
|
||||
if !strings.Contains(err.Error(), want) {
|
||||
@@ -192,29 +251,39 @@ func TestLinksResolveInsideTheSetAndFailOutside(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// The same tree without the out-of-set link: the in-set link becomes the target
|
||||
// page's url, and the anchor rides along.
|
||||
// The same tree without the out-of-set link: each link becomes the target page's
|
||||
// url, under the target's own base.
|
||||
writeFile(t, filepath.Join(root, "docs", "index.md"),
|
||||
"# Archie\n\nSee [Organisation](organisation.md#organisation), [OpenAI](https://openai.com/) and [below](#anchors).\n")
|
||||
doc, err := load(root)
|
||||
"# Archie\n\nSee [Organisation](architecture/organisation.md#organisation), [OpenAI](https://openai.com/) and [below](#anchors).\n")
|
||||
generated, err := load(root)
|
||||
if err != nil {
|
||||
t.Fatalf("load: %v", err)
|
||||
}
|
||||
var index string
|
||||
for _, entry := range doc.Pages {
|
||||
if entry.URL == "/docs/" {
|
||||
index = entry.Body
|
||||
}
|
||||
}
|
||||
index := bodyOf(t, documentFor(t, generated, publicDocs), "/docs/")
|
||||
for _, want := range []string{
|
||||
"(/docs/organisation/#organisation)",
|
||||
"(/dev/architecture/organisation/#organisation)",
|
||||
"(https://openai.com/)",
|
||||
"(#anchors)",
|
||||
} {
|
||||
if !strings.Contains(index, want) {
|
||||
t.Errorf("resolved body = %q, want it to contain %q", index, want)
|
||||
t.Errorf("public body = %q, want it to contain %q", index, want)
|
||||
}
|
||||
}
|
||||
organisation := bodyOf(t, documentFor(t, generated, developmentDocs), "/dev/architecture/organisation/")
|
||||
if !strings.Contains(organisation, "(/docs/)") {
|
||||
t.Errorf("development body = %q, want the link back to the public landing page", organisation)
|
||||
}
|
||||
}
|
||||
|
||||
func bodyOf(t *testing.T, doc document, url string) string {
|
||||
t.Helper()
|
||||
for _, entry := range doc.Pages {
|
||||
if entry.URL == url {
|
||||
return entry.Body
|
||||
}
|
||||
}
|
||||
t.Fatalf("no page at %s", url)
|
||||
return ""
|
||||
}
|
||||
|
||||
// TestFragmentsAreValidatedAgainstTheTargetsHeadings: a link can resolve to a page
|
||||
@@ -224,10 +293,10 @@ func TestLinksResolveInsideTheSetAndFailOutside(t *testing.T) {
|
||||
// rendered page carries.
|
||||
func TestFragmentsAreValidatedAgainstTheTargetsHeadings(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
writeFile(t, filepath.Join(root, "docs", "decisions.md"),
|
||||
writeFile(t, filepath.Join(root, "docs", "architecture", "decisions.md"),
|
||||
"# Decisions\n\n## 5. Memory placement and storage\n\n## Bindings & secrets\n")
|
||||
writeFile(t, filepath.Join(root, "docs", "index.md"),
|
||||
"# Archie\n\n[Good](decisions.md#5-memory-placement-and-storage).\n\n[Bad](decisions.md#5).\n")
|
||||
"# Archie\n\n[Good](architecture/decisions.md#5-memory-placement-and-storage).\n\n[Bad](architecture/decisions.md#5).\n")
|
||||
|
||||
_, err := load(root)
|
||||
if err == nil {
|
||||
@@ -245,17 +314,12 @@ func TestFragmentsAreValidatedAgainstTheTargetsHeadings(t *testing.T) {
|
||||
// A fragment that does match, including one whose heading has punctuation and an
|
||||
// ampersand, passes and is carried verbatim.
|
||||
writeFile(t, filepath.Join(root, "docs", "index.md"),
|
||||
"# Archie\n\n[Good](decisions.md#5-memory-placement-and-storage).\n\n[Also](decisions.md#bindings-secrets).\n")
|
||||
doc, err := load(root)
|
||||
"# Archie\n\n[Good](architecture/decisions.md#5-memory-placement-and-storage).\n\n[Also](architecture/decisions.md#bindings-secrets).\n")
|
||||
generated, err := load(root)
|
||||
if err != nil {
|
||||
t.Fatalf("load: %v", err)
|
||||
}
|
||||
for _, entry := range doc.Pages {
|
||||
if entry.URL != "/docs/" {
|
||||
continue
|
||||
}
|
||||
if !strings.Contains(entry.Body, "(/docs/decisions/#bindings-secrets)") {
|
||||
t.Errorf("resolved body = %q, want the ampersand heading's slug", entry.Body)
|
||||
}
|
||||
if index := bodyOf(t, documentFor(t, generated, publicDocs), "/docs/"); !strings.Contains(index, "(/dev/architecture/decisions/#bindings-secrets)") {
|
||||
t.Errorf("resolved body = %q, want the ampersand heading's slug", index)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user