diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index bae096f72..9376dcf69 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -412,7 +412,7 @@ "url": "/dev/prds/pr-review-agent/", "title": "PR review agent", "section": "PRDs", - "body": "# PR review agent\n\n**Status:** Draft\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake,\n anatomy and diff, each able to read the repository:\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags.\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n near-duplicates through a small classification call that keeps both\n when unsure;\n - map lines to the diff's coordinates, sort by score, cap at 25 inline\n comments.\n8. **Merge gate.** One classification call per finding decides blocking or\n advisory: blocking only for broken builds, security, data loss, contract\n breaks and regressions. A failed call means advisory.\n9. **Output.** One call per comment tightens its wording, keeping the\n original on failure. The review is posted as one forge review with inline\n comments. Any blocking finding requests changes; otherwise the review is a\n comment. Archie never posts an approval.\n\n## Precision dial\n\nWith `review.precision_gate = true`, a post-worthiness pass runs after phase 4\nand before the verification layer. It keeps every concrete, evidenced defect\nand drops nitpicks, style and unverifiable claims, keeping a finding when\nunsure. It trades recall for precision and cuts verification cost by\nfiltering early.\n\n## Operator approval\n\nWith `review.approve_before_post = true`, synthesis ends in\n`waiting_human`. The operator chooses which findings to post, rejects the\nreview, or asks for a re-review with instructions. A re-review reruns phases\n3 to 8 with the instructions added to the lens and reviewer prompts, at most\n2 times. A review with no findings posts nothing and does not wait.\n\n## Isolation\n\nEvery agent in the pipeline reads a `.git`-free snapshot of the PR head, with\nread-only tools rooted at it, and never the implementer's worktree or\ntranscript. No pipeline agent holds a forge credential; posting is code.\n\n## Budget\n\nA run has a cost cap and a wall-clock cap, split into per-phase shares. A\nphase whose share is spent is skipped and recorded on its StepExecution. The\nposted review names every skipped phase, so an exhausted run never reads as a\nclean one. A run whose review stage fails posts nothing and\nfails.\n\n## Triggers\n\n- **Watched repositories:** a PR opened or updated on a repository with\n `review.enabled` starts a run. An update cancels the in-flight run for the\n same PR.\n- **Operator:** a PR URL from the dashboard or chat starts a run on any\n repository the identity can read.\n- **Archie's own PRs:** the implement workflow runs the pipeline before\n opening its PR. A blocking finding the adversary did not challenge parks\n the task with the findings. A pipeline that fails parks the task. Advisory\n findings are posted after the PR opens.\n\n## Models\n\nEach agent phase names a model role. Lens, reviewer, verification,\nadversary, compound and consistency agents use the review role. Intake,\ncoverage, dedup, merge gate and polish calls use the classification role.\nEither role may run on the built-in runner or a harness.\n\n## Out of scope\n\n- SARIF and standalone report formats. The findings are StepExecution outputs\n and the forge review.\n- Reviewing a diff without a forge PR.\n- Self-consistency reruns.\n\n## Plan\n\n1. Deterministic core: diff parsing, clustering, blast radius, evidence\n extraction, scoring, dedup, line mapping, review event. Table-driven tests.\n2. The benchmark harness (Verification), run against the deterministic core\n with fixture findings.\n3. `pr-review` workflow: intake, anatomy, lenses, reviewers, synthesis,\n output, with the execution tree recording each call.\n4. Verification layer, coverage loop and consistency verification.\n5. Merge gate, polish, budget shares and skipped-phase reporting.\n6. Benchmark acceptance run.\n7. Triggers: operator, watched repositories, archie's own PRs replacing the\n single-reviewer stage.\n8. Precision dial and operator approval.\n\n## Verification\n\n- **Benchmark acceptance.** On the 38 runnable PRs of the Martian\n Code-Review-Bench offline set, one blind run per PR at `deep` with the\n review and classification roles on GLM-5.2, and an independent judge\n (`anthropic/claude-sonnet-4.6`) matching posted comments to golden\n comments: golden micro-recall is at least 0.70. Golden-only precision is\n reported alongside it. The run is reproducible from a script in the\n repository.\n- Scoring, thresholds, dedup and line mapping give identical output for\n identical findings.\n- A run whose phase share is exhausted posts a review naming the skipped\n phase.\n- An update to a PR under review cancels the running review and its child\n steps.\n- No pipeline agent can write to the snapshot, and none can reach a forge\n credential.\n- Archie's own PR with an unchallenged blocking finding is parked, not\n opened.\n- Archie never submits an approving review.\n" + "body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake,\n anatomy and diff, each able to read the repository:\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags.\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n near-duplicates through a small classification call that keeps both\n when unsure;\n - map lines to the diff's coordinates, sort by score, cap at 25 inline\n comments.\n8. **Merge gate.** One classification call per finding decides blocking or\n advisory: blocking only for broken builds, security, data loss, contract\n breaks and regressions. A failed call means advisory.\n9. **Output.** One call per comment tightens its wording, keeping the\n original on failure. The review is posted as one forge review with inline\n comments. Any blocking finding requests changes; otherwise the review is a\n comment. Archie never posts an approval.\n\n## Precision dial\n\nWith `review.precision_gate = true`, a post-worthiness pass runs after phase 4\nand before the verification layer. It keeps every concrete, evidenced defect\nand drops nitpicks, style and unverifiable claims, keeping a finding when\nunsure. It trades recall for precision and cuts verification cost by\nfiltering early.\n\n## Operator approval\n\nWith `review.approve_before_post = true`, synthesis ends in\n`waiting_human`. The operator chooses which findings to post, rejects the\nreview, or asks for a re-review with instructions. A re-review reruns phases\n3 to 8 with the instructions added to the lens and reviewer prompts, at most\n2 times. A review with no findings posts nothing and does not wait.\n\n## Isolation\n\nEvery agent in the pipeline reads a `.git`-free snapshot of the PR head, with\nread-only tools rooted at it, and never the implementer's worktree or\ntranscript. No pipeline agent holds a forge credential; posting is code.\n\n## Budget\n\nA run has a cost cap and a wall-clock cap, split into per-phase shares. A\nphase whose share is spent is skipped and recorded on its StepExecution. The\nposted review names every skipped phase, so an exhausted run never reads as a\nclean one. A run whose review stage fails posts nothing and\nfails.\n\n## Triggers\n\n- **Watched repositories:** a PR opened or updated on a repository with\n `review.enabled` starts a run. An update cancels the in-flight run for the\n same PR.\n- **Operator:** a PR URL from the dashboard or chat starts a run on any\n repository the identity can read.\n- **Archie's own PRs:** the implement workflow runs the pipeline before\n opening its PR. A blocking finding the adversary did not challenge parks\n the task with the findings. A pipeline that fails parks the task. Advisory\n findings are posted after the PR opens.\n\n## Models\n\nEach agent phase names a model role. Lens, reviewer, verification,\nadversary, compound and consistency agents use the review role. Intake,\ncoverage, dedup, merge gate and polish calls use the classification role.\nEither role may run on the built-in runner or a harness.\n\n## Out of scope\n\n- SARIF and standalone report formats. The findings are StepExecution outputs\n and the forge review.\n- Reviewing a diff without a forge PR.\n- Self-consistency reruns.\n\n## Plan\n\n1. Deterministic core: diff parsing, clustering, blast radius, evidence\n extraction, scoring, dedup, line mapping, review event. Table-driven tests.\n2. The benchmark harness (Verification), run against the deterministic core\n with fixture findings.\n3. `pr-review` workflow: intake, anatomy, lenses, reviewers, synthesis,\n output, with the execution tree recording each call.\n4. Verification layer, coverage loop and consistency verification.\n5. Merge gate, polish, budget shares and skipped-phase reporting.\n6. Benchmark acceptance run.\n7. Triggers: operator, watched repositories, archie's own PRs replacing the\n single-reviewer stage.\n8. Precision dial and operator approval.\n\n## Verification\n\n- **Benchmark acceptance.** On the 38 runnable PRs of the Martian\n Code-Review-Bench offline set, one blind run per PR at `deep` with the\n review and classification roles on GLM-5.2, and an independent judge\n (`anthropic/claude-sonnet-4.6`) matching posted comments to golden\n comments: golden micro-recall is at least 0.70. Golden-only precision is\n reported alongside it. The run is reproducible from a script in the\n repository.\n- Scoring, thresholds, dedup and line mapping give identical output for\n identical findings.\n- A run whose phase share is exhausted posts a review naming the skipped\n phase.\n- An update to a PR under review cancels the running review and its child\n steps.\n- No pipeline agent can write to the snapshot, and none can reach a forge\n credential.\n- Archie's own PR with an unchallenged blocking finding is parked, not\n opened.\n- Archie never submits an approving review.\n" }, { "url": "/dev/prds/pr-review-remediation/", @@ -492,6 +492,12 @@ "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`: itemised 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 favour 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 single-identity `Run`,\n `pollForIdentity` for `runIdentities`) stamp it. A pass that hangs leaves the\n stamp stale, which is the signal -- stamping completion instead would leave a\n wedged poller looking healthy.\n- **Queue depth.** Covered by Phase 1.\n- **Rendering.** `gateway.formatHealth` renders one line per reported fact\n (`Broker:`, `Containers:`, `Channels:`, `Chat model:`, `Last poll:`) between\n the queue line and the runtime block. A `/status` reply carries `Broker:` and\n `Chat model:`: the Gateway is the only process that serves a Router, and it\n holds neither a container pool, a poll loop nor a channel manager. The other\n three lines render when a report carries them. The broker source is a\n function rather than a captured value because the connection differs by\n composition: the daemon's shared eventbus client in one process, the\n Gateway's own task-actions connection in the other.\n\n### Truthful or absent -- what is deliberately not reported\n\n- **Version.** Still excluded: `/version` owns it, and duplicating it back into\n `/status` is the exact \"answers something available elsewhere in chat\"\n complaint this ticket exists to fix.\n- **Sections the standalone Gateway process cannot see.** The daemon owns the\n poll loop, the container pool and the channel manager; the Gateway process\n owns none of them. Its `/status` reports broker and chat-model health and\n omits pool, polling and channels rather than printing zeroes. Aggregating them\n across processes would need a new daemon RPC -- a new subsystem, out of scope\n here. For the same reason the chat-model line is per process: the daemon\n records the turns it runs (Telegram, email, webhook), the Gateway records the\n web chat's, and the two do not pool outcomes. Each line is true of the process\n answering the command. **Decided: they stay per-process.** Pooling\n them would mean a new daemon↔gateway health RPC for one status line, and a\n per-process line is true where an aggregate would be a claim about a process\n the answering one cannot see. The composition root therefore builds the\n health source from the broker connection and the chat-model recorder alone: a\n producer for a daemon-owned fact would build a section no reply can carry.\n- **A channel's failure reason can outlive the failure.** `status.Manager` keeps\n the last non-empty `Detail` across state changes, and that one field carries\n both a descriptor's standing caveat and a runtime failure reason, so a channel\n that failed and later recovered can still render the old reason. Splitting the\n two belongs at the producer (the manager and its descriptor), not in this\n reader, which reads the field exactly as the dashboard does.\n- **Container pool when Docker is unavailable.** Composition leaves\n `containerPool` nil, so the section is absent. Naming a reason would mean\n carrying Docker's startup error into the health surface.\n- **Runtime (provider/model).** Phase 1 left this block in place; it is still\n here. It is static config that `/model` and `/whoami` already answer, so it is\n the only line in `/status` that this ticket's own rule says should not be\n there -- but the maintainer reads `/status` daily to see the active model at a\n glance, and one command answering both \"is archie well\" and \"what is it\n running on\" is worth that duplication. **Decided: keep it.** It is\n a settled product decision, not an oversight; do not remove it as a\n mechanical follow-up.\n- **`/agents` copy.** The menu still advertises \"List tasks being\n worked\" while `Router.Agents` is never wired (`archie-core-mxls`), so that one\n published description does not match what its command does. Deleting,\n rewiring or redefining `/agents` is that bead's call and is not folded in here.\n\n## Packages this touches (Phase 2)\n\n- `internal/infrastructure/eventbus/nats`: `Client.Connected()`.\n- `internal/container`: `Pool.Active()`, `Pool.Cap()`.\n- `internal/daemon`: `lastPollAt`/`markPoll`/`LastPollAt()`.\n- `internal/gateway`: `health.go` (health contract + renderer), `Router.Health`,\n `formatStatus`.\n- `internal/app/archied`: `status_health.go` (the composition-root bridge),\n `ProviderOutcomes` threaded through `telegramSetup` into every turn runner,\n and `sendChatTurn` recording each call's outcome.\n- `internal/domain/messaging` + `internal/channels/telegram`: `/status` and\n `/tasks` descriptions, which now describe both commands' actual jobs on both\n published surfaces.\n" }, + { + "url": "/dev/prds/store/", + "title": "Store", + "section": "PRDs", + "body": "# Store\n\n**Status:** Approved\n**Authority:** `docs/architecture/plugins-and-extensions.md`; supersedes\n`docs/prds/extensions-center.md`, whose installed-inventory states are\nadopted below.\n**Compounds with:** `docs/prds/external-agent-harness.md` (harness Kits),\n`docs/prds/pr-review-agent.md` (the first package).\n\n## Decision\n\nOperators get capabilities from a store: browse, install, update and remove\npackages from the dashboard, with no config file editing. A package is an\nOCI image in a registry. A store catalogue is a list of package references.\nInstalling pins a digest. Every package declares the authority it needs, and\nan update that asks for more stops for the operator's approval.\n\n## Packages\n\nTwo kinds, both ordinary OCI images:\n\n- **Harness Kits.** Kit v3 images, resolved as\n `docs/prds/external-agent-harness.md` decides. Their authority is their\n Kit permission surface.\n- **Archie packages.** An image whose manifest annotation\n `dev.archie.package.v1` carries the descriptor and whose single layer\n carries files. A package contributes any of: workflow definitions,\n prompts, skills, MCP server definitions, and default settings for them.\n\nArchie packages are declarative. They carry no Go, Yaegi or script code that\narchie executes on the host. Anything that runs code ships as a Kit and runs\nin a sandbox. An archie package that references a Kit names it by digest,\nand installing the package installs the Kit.\n\nThe descriptor declares: display name, description, version, the families\nit contributes, the packages it requires, and its authority.\n\n## Authority\n\nA package's authority is the set of grants it needs to work:\n\n- credential services (from its Kits and MCP servers);\n- egress hosts (from its Kits);\n- forge permissions its workflows use: read, comment, review, push, open\n pull request;\n- triggers it registers: watched-repository events, schedules;\n- tools it enables for agents.\n\nInstall shows this list and records the operator's acceptance against the\ndigest. An update whose authority is equal or narrower applies under the\npackage's update policy. An update whose authority is wider waits for\napproval, showing only what widened. Nothing a package does at runtime can\nexceed its accepted authority: archie checks forge actions, triggers and\ntool grants against it, and the egress proxy enforces the Kit's grants.\n\n## Catalogues\n\nA catalogue is an OCI artifact listing package references with digests,\nsigned by the catalogue's key. Archie ships with the default catalogue and\nits public key configured. An operator can add catalogues, for example a\nprivate registry, by reference and public key. A catalogue without a key is\nrefused unless the operator marks it unsigned, which the dashboard shows on\nevery package it supplies.\n\nInstall and update verify the catalogue signature and the package digest.\nArchie never installs a tag it has not resolved to a digest through a\nverified catalogue.\n\n## Install, update, remove\n\n- Installed packages, their pinned digests, accepted authority and update\n policy are State Store resources. They apply without a restart.\n- **Update policy** per package: `manual` (default) or `auto`. `auto` applies\n non-widening updates when the catalogue lists them; widening updates always\n wait.\n- **Setup.** A package whose authority includes a credential with no binding\n installs as `needs_setup`, and links to the binding form or the harness\n setup terminal. Its triggers do not fire until setup completes.\n- **Remove** stops its triggers, removes its contributions, and leaves any\n credential bindings for the operator to delete. A package another\n installed package requires cannot be removed first.\n- Rolling back reinstalls the previously accepted digest.\n\n## Inventory\n\nThe installed view lists every package and every bundled capability with\none state, computed on read and never persisted:\n\n| State | Meaning |\n| ------------- | -------------------------------------------------------- |\n| `available` | in a catalogue or bundled, not installed |\n| `needs_setup` | installed, waiting for a credential binding |\n| `active` | installed and running |\n| `degraded` | active, and its family's health check reports a fault |\n| `pending` | an update waiting for approval of widened authority |\n\nCore capabilities (identity, workflow engine, State Store) are listed and\ncannot be removed.\n\n## Out of scope\n\n- Payment, licensing and paid packages.\n- Publishing from the dashboard. Packages are built and pushed with standard\n image tooling.\n- Ratings and reviews.\n\n## Plan\n\n1. Archie package descriptor and its validation, including declarative-only\n content.\n2. Installed-package resources, digest pinning, install and remove for\n archie packages from a local registry.\n3. Authority model: extraction from packages and Kits, acceptance records,\n runtime checks for forge actions, triggers and tools.\n4. Signed catalogues and verification; the default catalogue.\n5. Updates: widening detection, approval, `auto` policy, rollback.\n6. Kit packages through the same flow; `needs_setup`.\n7. Inventory states across packages and bundled capabilities.\n8. The PR review agent published as the first package.\n\n## Verification\n\n- Installing the PR review package from the default catalogue on a fresh\n instance, then binding a credential, reviews a PR without editing\n configuration.\n- An update adding a forge permission or egress host waits as `pending`,\n showing only the added grant, and does not apply under `auto`.\n- A workflow from a package that tries a forge action outside its accepted\n authority fails the step.\n- A tampered package digest or an unsigned catalogue refuses to install.\n- A package containing executable host code is rejected at validation.\n- Rolling back restores the prior digest and its accepted authority.\n" + }, { "url": "/dev/prds/task-logs-pagination/", "title": "task_logs pagination and bounded retrieval -- decision", @@ -865,6 +871,10 @@ "title": "/status health surface", "url": "/dev/prds/status-health-surface/" }, + { + "title": "Store", + "url": "/dev/prds/store/" + }, { "title": "task_logs pagination and bounded retrieval -- decision", "url": "/dev/prds/task-logs-pagination/" diff --git a/docs/prds/pr-review-agent.md b/docs/prds/pr-review-agent.md index 687c2a693..b2914834e 100644 --- a/docs/prds/pr-review-agent.md +++ b/docs/prds/pr-review-agent.md @@ -1,6 +1,6 @@ # PR review agent -**Status:** Draft +**Status:** Approved **Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer executor and blocking rule in `docs/architecture/adversarial-review.md`, and the designs in `docs/prds/operator-pr-review.md` and diff --git a/docs/prds/store.md b/docs/prds/store.md index 5413518d5..ec8899c92 100644 --- a/docs/prds/store.md +++ b/docs/prds/store.md @@ -1,6 +1,6 @@ # Store -**Status:** Draft +**Status:** Approved **Authority:** `docs/architecture/plugins-and-extensions.md`; supersedes `docs/prds/extensions-center.md`, whose installed-inventory states are adopted below.