PRD: Guarded Consensus Mode

PRD: Guarded Consensus Mode

Ver: 1.1

2/3/26

Trent Carter

Product: Verdict PAS (Code Lane) Status: Draft (peer review ready) Feature name (user-facing): Guarded Consensus Mode Internal name (suggested): guarded_consensus (policy) / validation_loop (engine)

⸻

1) Summary

Guarded Consensus Mode adds an optional, feature-gated workflow to the Verdict PAS Code Lane that enforces a deterministic Build → Validate → Retry loop and introduces two persistent workflow artifacts—spec.md (immutable input) and plan.md (the task-state ledger)—to prevent drift and “false completion.”

When disabled, the system behaves exactly as it does today, with near-zero blast radius (no new required fields, no extra tool calls, no artifact creation).

⸻

2) Problem

Verdict’s current multi-agent coding flow can produce “done” work that is not objectively correct:

• Code changes that _look_ correct but fail tests/lint/build/typecheck

• Long-running chats that drift from the original intent

• Implicit state living in chat history instead of an explicit, parseable workflow ledger

This causes reliability issues and makes it hard to reproduce, audit, or resume work.

⸻

3) Goals

Verified completion: Tasks only complete when validation gates pass (in balanced/strict).

State that survives context: The plan is stored in a deterministic, machine-parseable document (plan.md).

Immutable source of truth: The user’s requirements are captured once in spec.md and treated as immutable for the run.

Bounded retries with actionable feedback: Failures return structured evidence (logs, failing gate, retry count).

Feature-gated isolation: Turning the feature off does not change core PAS behavior or performance.

⸻

4) Non-goals

• No new permanent “Validator service” tier; reuse existing PAS roles and orchestration.

• No global DAG scheduler across all lanes (v1 is Code Lane only).

• No requirement to introduce a new sandbox platform in v1 (use existing safe execution path).

• No “auto-write perfect tests” guarantee (optional later).

⸻

5) Target users

• Power users who want reliable patches and reproducible runs.

• Teams who need auditability (what was intended, what was planned, what was validated).

• Developers who want a mode that prevents “it compiled in the agent’s imagination.”

⸻

6) Key concept: “Plan with Team” inside PAS

Guarded Consensus Mode borrows the “Plan with Team” concept (as seen in Claude-style multi-agent workflows) but maps it to PAS’s existing hierarchy:

• Architect/Manager creates the plan (plan.md)

• Programmer executes tasks (build)

• Manager enforces gates (validate + retry + completion authority)

Crucially: completion is not based on agent narrative; it is based on validation evidence.

⸻

7) Feature flagging and controls 7.1 Source of truth: RunPack

Guarded Consensus Mode is enabled/disabled per-run via RunPack configuration.

Required RunPack fields (names can be finalized in peer review):

• features.guarded_consensus.enabled (bool)

• features.guarded_consensus.level (speed | balanced | strict)

• features.guarded_consensus.max_retries (int)

• features.guarded_consensus.fail_open (bool; default false)

• features.guarded_consensus.gates (list of gate definitions)

7.2 Optional test UX: Chat checkbox

A chat UI checkbox may exist for testing/demos:

• It must apply only as a run override.

• It must display the resolved state (RunPack vs override).

• It must not create global configuration drift.

7.3 “Off means off”

When enabled=false:

• No spec/plan artifacts are created.

• No new orchestration states are emitted.

• No additional validation tool calls occur.

⸻

8) Workflow artifacts

Guarded Consensus Mode introduces a documented, mandatory artifact pair (plus an optional third):

8.1 Canonical storage location

To avoid polluting repos and to minimize conflicts, canonical paths are:

• .verdict/spec.md

• .verdict/plan.md

• .verdict/prime.md (optional)

(Compatibility aliases like repo-root spec.md/plan.md may exist only if explicitly enabled later; v1 does not require it.)

8.2 Artifact definitions Artifact Role Authority Mutability Purpose

spec.md Input Orchestrator creates snapshot Immutable for the run “Source of truth” requirements

plan.md Output + State Orchestrator writes state Mutable (checkbox progress only) Shared ledger of tasks & completion

prime.md (optional) Analysis Orchestrator creates Mutable Initial repo scan / risk notes

8.3 plan.md formatting requirement

plan.md must be formatted as a strict Markdown task list with [ ] / [x] checkboxes so it can be parsed deterministically:

• Unchecked task = next runnable work item

• Checked task = completed item

• The plan must remain stable and machine-readable across retries and partial runs

8.4 Write authority rule

To avoid concurrency conflicts:

• Only the orchestrator/manager authority may flip [ ] → [x] in plan.md.

• Builders may read plan/spec but do not directly edit plan state.

⸻

9) Validation model 9.1 Gate types (v1)

Supported validation gates should be restricted and explicit. v1 supports:

• Shell command gate (run a configured command in repo context)

• File exists gate

• Regex match gate

• (Optional) Syntax check gate if it’s materially different from shell commands in your environments

9.2 Gate execution environment (v1)

Gates run in the same controlled execution pathway already used for code operations in Verdict (local runner, service tool, or equivalent). v1 does not require a new sandbox platform, but must enforce:

• timeouts

• output truncation

• resource bounds where available

• command allowlisting/denylisting policy (see Security)

⸻

10) State machine

For each runnable plan task:

Select next unchecked task from plan.md

Build (Programmer executes the task)

Validate (Manager runs configured gates relevant to the task / plan level)

Retry (on failure, feed structured failure evidence back to builder; retry until pass or max retries)

Commit state (plan.md checkbox flip + run timeline state update)

Escalate if retries exhausted (error with evidence bundle)

⸻

11) Levels: speed, balanced, strict

• Speed

• Minimal gating (or gating disabled)

• May allow fail_open=true (record failures, still proceed)

• Intended for prototyping, not reliable delivery

• Balanced

• Fast, high-signal checks (lint + targeted tests)

• Default recommended mode for most users

• Strict

• Strong checks (tests + lint + typecheck/build as configured)

• fail_open=false default; completion requires passing evidence

(If you prefer, map these to your Parametric Equalizer naming so UX stays consistent.)

⸻

12) Observability and receipts

Each task lifecycle must produce an evidence bundle:

• Mode + level + retries configured

• Gates executed (names/types)

• Pass/fail per gate

• Command/pattern used (as configured)

• Exit codes, durations

• Truncated stdout/stderr (with pointers to full logs if stored)

• Retry count

• Final disposition (completed vs validation_failed_max_retries)

This evidence should be visible in the run timeline and available for audit/export.

⸻

13) Security and safety requirements

Shell-based validation is inherently risky. v1 must include a defensible stance:

• Command policy: allowlist/denylist (project or system level)

• Timeouts: per gate and per task lifecycle

• Output limits: avoid log flooding and token blowups

• Workspace isolation: ensure commands run only within intended repo scope

• No secret exfiltration: logs must redact known secret patterns where feasible

If a strict allowlist cannot be enforced in v1, then Guarded Consensus Mode must default to disabled unless the user explicitly enables it and configures gates.

⸻

14) Compatibility and performance

• When enabled, additional time cost is expected from validations and retries.

• When disabled, no measurable overhead should occur (no extra parsing, no artifact writes, no extra orchestration states).

• plan/spec artifacts must not interfere with normal developer workflows (kept under .verdict/).

⸻

15) Rollout plan Phase 0 (internal)

• Balanced level only

• Gate types: shell command + file exists

• Max retries default 2–3

• .verdict/spec.md + .verdict/plan.md created and used

Phase 1

• Strict level

• Better evidence bundling and UI surfacing

• Regex match gate

Phase 2

• Optional prime.md

• Optional semantic reviewer pass (style/security) as a separate, non-blocking gate type

• Optional hardened sandbox

⸻

16) Acceptance criteria

Feature-off parity: With Guarded Consensus disabled, behavior matches baseline (no new artifacts, no new required outputs, no extra tool calls).

Artifact creation: When enabled, .verdict/spec.md and .verdict/plan.md are created at run start.

Deterministic progression: Orchestrator can parse plan.md to select the next unchecked task and advance state by marking it complete.

Validation gating: In balanced/strict with fail_open=false, tasks cannot complete unless configured gates pass.

Structured failure feedback: On gate failure, builder receives actionable evidence (which gate failed + logs excerpt + retry count).

Bounded retry: After max retries, the run emits a deterministic error state with the evidence bundle.

Timeline visibility: Users can see Build/Validate/Retry states and durations in the run trace.

⸻

17) Open questions for peer review

Authority placement: Should “plan generation” live at Architect or Manager-Code (or both with a handshake)?

Gate granularity: Are gates per-plan only in v1, or per-task as well?

Command policy: Where does allowlisting live (system config vs project config vs RunPack)?

Artifact retention: Do we keep .verdict/ artifacts by default, or clean them automatically unless pinned?

Equalizer mapping: Do we rename levels to match the Parametric Equalizer exactly?

⸻

If you want, I’ll format this into your repo’s preferred PRD template style (section ordering, metadata header, naming conventions) while keeping it strictly non-code and review-ready.