docs(prds): approve PR review agent and store PRDs
This commit is contained in:
3 files changed
+13
-3
No files matched your search
@@ -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-duLine truncated
|
||||
"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 nearLine truncated
|
||||
},
|
||||
{
|
||||
"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 sLine truncated
|
||||
},
|
||||
{
|
||||
"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 Line truncated
|
||||
},
|
||||
{
|
||||
"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/"
|
||||
|
||||
@@ -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
|
||||
|
||||
+1
-1
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user