merge: decide where per-workflow review settings live (0ry6)

This commit is contained in:
sam committed 2026-09-30 07:33:38 +10:00
commit 06b0dd224e
2 files changed
+133

No files matched your search

+10
View File
@@ -444,6 +444,12 @@
"section": "PRDs",
"body": "# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\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/review-settings-resource/",
"title": "Review settings resource",
"section": "PRDs",
"body": "# Review settings resource\n\n**Status:** Draft\n**Beads issue:** `archie-core-0ry6`\n**Authority:** `docs/prds/runtime-control-plane.md` for the resource model,\n`docs/architecture/configuration.md` for ownership, and\n`docs/prds/pr-review-agent.md` for what the two dials do.\n\n## Decision\n\n`review.precision_gate` and `review.approve_before_post` are one control-plane\nresource, `review-settings`. The file's `[review]` section seeds it, the stored\ndocument outranks the file from then on, and the dashboard writes it through the\nsame settings machinery as every other resource.\n\nThe resource is deployment-wide, like every definition the State Store seeds\n(`storecontract.DefaultOrgID`): not per-repository, per-identity, or per-run.\n\n## Why its own kind\n\nThe two dials are pr-review policy — what a review may post, and whether a human\ndecides — not a limit on a task run. The document that carries task limits\nbelongs to that feature. `runtime-control-plane.md` splits settings by feature\nand refuses documents unrelated features share; `configuration.md` puts a typed\nruntime setting with the domain whose behaviour it describes. One document per\nfeature is the rule, not one document per settings page.\n\nA new kind also has no legacy documents. Its first value is the seed derived\nfrom the file, so \"the store outranks the file\" begins from an explicit copy of\nboth fields rather than from a document that predates them.\n\n## Document\n\nNew file `internal/app/controlplane/review_settings.go`:\n\n```go\nconst ReviewSettingsKind = \"review-settings\"\n\ntype reviewSettings struct {\n PrecisionGate bool `json:\"precision_gate\"`\n ApproveBeforePost bool `json:\"approve_before_post\"`\n}\n```\n\nIts `Definition` sets `ApplyMode: \"live\"`, `Document: reviewSettings{}`, and a\n`Seed` returning `reviewSettings{cfg.Review.PrecisionGate, cfg.Review.ApproveBeforePost}`,\nand a `Validate` wrapping `validateAs`: both fields are free booleans with no cross-field\nrule, so the validator is a named place to put one rather than an inline no-op\n(`validatePluginSettings` is the precedent). No `Normalize`, because the kind\nhas no second wire shape to converge.\n\n## Seeding\n\n`ImportConfig`/`seededValues` write the seed for a kind the store does not hold,\nso a deployment that never edited the dials runs the values in `[review]`. Once\na document is stored, the file key stops mattering, which is the rule for every\ndatabase-owned setting.\n\n## Apply\n\n`runtimeConfigFrom` in `internal/app/controlplane/runtime_config.go` layers the\nstored document over the file's `Review`, assigning `out.Review.PrecisionGate`\nand `out.Review.ApproveBeforePost` field by field. Field-by-field, not\n`out.Review = ...`: a field added to `config.Review` later keeps the file's value\nuntil the document carries it.\n\n`ReviewSettingsKind` joins `runtimeResourceKinds` in\n`internal/app/archied/control_plane.go`, so a new stored version re-runs the\nlayering and republishes through `config.Holder`. Live rather than\nrestart-required, because every consumer re-reads it: `Review` is on\n`reloadableFields` in `internal/app/archied/reload.go`, and the value reaches a\nrun through `Daemon.configFor` → `Config.ForTask` → `TaskConfig.ToConfig` →\n`TaskContext.Cfg`, which `stagePRPrecisionGate` and `stagePROperatorApproval`\nread. The next task run uses the new value; a run in flight keeps the value it\nstarted with.\n\n## Projection and page\n\n`BuildConfigView` gains a plain `Review` field carrying both values out of\n`cfg.Review`, the way `BudgetsView` carries the layered budgets, so the published\nconfig snapshot tells any reader what is in force. The Review page renders the\ntwo toggles from the control-plane store's draft for `review-settings` — the\nshape `SystemTasksPage.vue` uses for `workflow-execution-settings` — and shows\nthe projected value beside them; a Settings route plus a `PAGE_RESOURCES` entry\n(`ui/src/stores/control-plane.ts`) bind the page to the kind.\n\nNothing else re-advertises them. `configFieldDescriptors` and `ConfigView.Schema`\ngain no `review.*` row: the config catalog's generic renderer was deleted, so a\ndescriptor row adds a field nothing can edit, which is the shape `becb0b5e`\nremoved.\n\n## What the test proves\n\n`internal/app/controlplane/runtime_config_test.go` adds the round trip that\nbuilds the effective config the way boot does: seed the kind from a file config\nwith both dials set one way, store a document with both flipped, layer it\nthrough `runtimeConfigFrom`, and assert the effective `cfg.Review` equals the\nstored document. A second case covers the absent kind, where the file's values\nstay in effect. The assertion is on `cfg.Review` — the value `TaskContext.Cfg`\ncarries into the two stages — not on a struct the test set directly.\n`TestRuntimeResourceKindsApplyLive` gains `review-settings` as live. The\nvalidator needs no `validators_agree_test.goLine truncated
},
{
"url": "/dev/prds/runtime-control-plane/",
"title": "Runtime control plane",
@@ -845,6 +851,10 @@
"title": "Review calibration -- decision",
"url": "/dev/prds/review-calibration/"
},
{
"title": "Review settings resource",
"url": "/dev/prds/review-settings-resource/"
},
{
"title": "Runtime control plane",
"url": "/dev/prds/runtime-control-plane/"
+123
View File
@@ -0,0 +1,123 @@
# Review settings resource
**Status:** Draft
**Beads issue:** `archie-core-0ry6`
**Authority:** `docs/prds/runtime-control-plane.md` for the resource model,
`docs/architecture/configuration.md` for ownership, and
`docs/prds/pr-review-agent.md` for what the two dials do.
## Decision
`review.precision_gate` and `review.approve_before_post` are one control-plane
resource, `review-settings`. The file's `[review]` section seeds it, the stored
document outranks the file from then on, and the dashboard writes it through the
same settings machinery as every other resource.
The resource is deployment-wide, like every definition the State Store seeds
(`storecontract.DefaultOrgID`): not per-repository, per-identity, or per-run.
## Why its own kind
The two dials are pr-review policy — what a review may post, and whether a human
decides — not a limit on a task run. The document that carries task limits
belongs to that feature. `runtime-control-plane.md` splits settings by feature
and refuses documents unrelated features share; `configuration.md` puts a typed
runtime setting with the domain whose behaviour it describes. One document per
feature is the rule, not one document per settings page.
A new kind also has no legacy documents. Its first value is the seed derived
from the file, so "the store outranks the file" begins from an explicit copy of
both fields rather than from a document that predates them.
## Document
New file `internal/app/controlplane/review_settings.go`:
```go
const ReviewSettingsKind = "review-settings"
type reviewSettings struct {
PrecisionGate bool `json:"precision_gate"`
ApproveBeforePost bool `json:"approve_before_post"`
}
```
Its `Definition` sets `ApplyMode: "live"`, `Document: reviewSettings{}`, and a
`Seed` returning `reviewSettings{cfg.Review.PrecisionGate, cfg.Review.ApproveBeforePost}`,
and a `Validate` wrapping `validateAs`: both fields are free booleans with no cross-field
rule, so the validator is a named place to put one rather than an inline no-op
(`validatePluginSettings` is the precedent). No `Normalize`, because the kind
has no second wire shape to converge.
## Seeding
`ImportConfig`/`seededValues` write the seed for a kind the store does not hold,
so a deployment that never edited the dials runs the values in `[review]`. Once
a document is stored, the file key stops mattering, which is the rule for every
database-owned setting.
## Apply
`runtimeConfigFrom` in `internal/app/controlplane/runtime_config.go` layers the
stored document over the file's `Review`, assigning `out.Review.PrecisionGate`
and `out.Review.ApproveBeforePost` field by field. Field-by-field, not
`out.Review = ...`: a field added to `config.Review` later keeps the file's value
until the document carries it.
`ReviewSettingsKind` joins `runtimeResourceKinds` in
`internal/app/archied/control_plane.go`, so a new stored version re-runs the
layering and republishes through `config.Holder`. Live rather than
restart-required, because every consumer re-reads it: `Review` is on
`reloadableFields` in `internal/app/archied/reload.go`, and the value reaches a
run through `Daemon.configFor` → `Config.ForTask` → `TaskConfig.ToConfig` →
`TaskContext.Cfg`, which `stagePRPrecisionGate` and `stagePROperatorApproval`
read. The next task run uses the new value; a run in flight keeps the value it
started with.
## Projection and page
`BuildConfigView` gains a plain `Review` field carrying both values out of
`cfg.Review`, the way `BudgetsView` carries the layered budgets, so the published
config snapshot tells any reader what is in force. The Review page renders the
two toggles from the control-plane store's draft for `review-settings` — the
shape `SystemTasksPage.vue` uses for `workflow-execution-settings` — and shows
the projected value beside them; a Settings route plus a `PAGE_RESOURCES` entry
(`ui/src/stores/control-plane.ts`) bind the page to the kind.
Nothing else re-advertises them. `configFieldDescriptors` and `ConfigView.Schema`
gain no `review.*` row: the config catalog's generic renderer was deleted, so a
descriptor row adds a field nothing can edit, which is the shape `becb0b5e`
removed.
## What the test proves
`internal/app/controlplane/runtime_config_test.go` adds the round trip that
builds the effective config the way boot does: seed the kind from a file config
with both dials set one way, store a document with both flipped, layer it
through `runtimeConfigFrom`, and assert the effective `cfg.Review` equals the
stored document. A second case covers the absent kind, where the file's values
stay in effect. The assertion is on `cfg.Review` — the value `TaskContext.Cfg`
carries into the two stages — not on a struct the test set directly.
`TestRuntimeResourceKindsApplyLive` gains `review-settings` as live. The
validator needs no `validators_agree_test.go` case: it wraps `validateAs` with
no rule, because no combination of the two booleans is invalid, and a case that
cannot fail is a test the project then carries for nothing.
## Rejected: extending workflow-execution-settings
That resource is `workflow.ExecutionSettings`, "the limits captured when a
workflow execution starts". Putting review policy in it makes the review feature
a field of the limits document, gives a boolean edit a ride on a document whose
candidate is validated and swapped as one unit with the budgets, and forces
absence-aware pointer fields onto booleans so a document stored before the fields
existed does not turn a file's `precision_gate = true` into `false`. It buys one
less kind at the cost of the ownership rule the model is built on.
## Out of scope
- Per-repository, per-identity, or per-workflow review settings. A scope key is
a later decision with its own resource shape.
- Any other review knob. A field joins the document only with a consumer, the
rule every config field carries.
- The reviewer pipeline's behaviour. This document places the settings; it does
not change what they do.