From 9d9f7cc30d5cd3fd4843eb56da740d3e7dad06a2 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 30 Sep 2026 07:32:25 +1000 Subject: [PATCH] docs(prds): decide where per-workflow review settings live --- docs/data/generated/dev-docs.json | 10 +++ docs/prds/review-settings-resource.md | 123 ++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 docs/prds/review-settings-resource.md diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 064aa7d14..6cf09e497 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -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.go` case: it wraps `validateAs` with\nno rule, because no combination of the two booleans is invalid, and a case that\ncannot fail is a test the project then carries for nothing.\n\n## Rejected: extending workflow-execution-settings\n\nThat resource is `workflow.ExecutionSettings`, \"the limits captured when a\nworkflow execution starts\". Putting review policy in it makes the review feature\na field of the limits document, gives a boolean edit a ride on a document whose\ncandidate is validated and swapped as one unit with the budgets, and forces\nabsence-aware pointer fields onto booleans so a document stored before the fields\nexisted does not turn a file's `precision_gate = true` into `false`. It buys one\nless kind at the cost of the ownership rule the model is built on.\n\n## Out of scope\n\n- Per-repository, per-identity, or per-workflow review settings. A scope key is\n a later decision with its own resource shape.\n- Any other review knob. A field joins the document only with a consumer, the\n rule every config field carries.\n- The reviewer pipeline's behaviour. This document places the settings; it does\n not change what they do.\n" + }, { "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/" diff --git a/docs/prds/review-settings-resource.md b/docs/prds/review-settings-resource.md new file mode 100644 index 000000000..515fd9006 --- /dev/null +++ b/docs/prds/review-settings-resource.md @@ -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.