feat(governance): add V&V Architect (LeadValidator) — independent audit agent
Fixes a critical bug where VALIDATOR.md contained a copy of start-validator.sh (making the validator unlaunchable). Introduces a fully independent V&V Architect agent that audits the codebase against the PRD and OpenSpec outside the CTO's chain of command. Changes: - VALIDATOR.md: rewritten as proper system prompt (8-phase audit methodology, issue format, severity model, communication protocol) - scripts/start-validator.sh: isolated workspace setup, sanity check, auto-init ledger, validator-specific CLAUDE.md (no CEO context contamination) - openspec/vv_audit/LEDGER.md: shared audit ledger index (CEO release gate view) - openspec/changes/archive/2026-04-07-vv-architect-setup/: full OpenSpec artifacts (proposal.md, design.md, tasks.md — 28 tasks, all complete) Note: .cto-workspace/CLAUDE.md updated (gitignored — persists on disk only). #vv-findings hub channel created for real-time validator notifications. CEO approved 2026-04-07. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SentryAgent.ai Developer
130
openspec/changes/archive/2026-04-07-vv-architect-setup/design.md
Normal file
130
openspec/changes/archive/2026-04-07-vv-architect-setup/design.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Design — vv-architect-setup
|
||||
|
||||
## Context
|
||||
|
||||
SentryAgent.ai uses a multi-agent Claude Code architecture:
|
||||
- **CEO-Session** — human-facing, governance and priorities
|
||||
- **VirtualCTO** — technical authority, directs engineering team
|
||||
- **Engineering Team** (Architect, Developer, QA) — spawned as subagents by CTO
|
||||
|
||||
All prior phases passed through the CTO's review and QA sign-off. No independent
|
||||
verification existed outside that chain. The V&V Architect adds a separate audit loop
|
||||
that operates with full read access to the codebase but no write authority over it.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Provide CEO-level assurance that the codebase matches the PRD and OpenSpec
|
||||
- Detect spec-implementation gaps, DRY violations, TypeScript violations, test gaps, and security issues
|
||||
- Create a formal, auditable issue trail (VV_ISSUE_NNN.md files)
|
||||
- Enable the CEO to see a release gate status at any time (LEDGER.md)
|
||||
|
||||
**Non-Goals:**
|
||||
- The validator does NOT fix code — it only reports findings
|
||||
- The validator does NOT block the CTO from working in parallel
|
||||
- The validator does NOT attend to new feature planning or business decisions
|
||||
- The validator does NOT replace the QA Engineer — QA tests functionality; V&V audits completeness and standards compliance
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
CEO (Human)
|
||||
├── CEO-Session (this Claude Code instance)
|
||||
│ └── VirtualCTO (separate terminal — .cto-workspace/)
|
||||
│ ├── Virtual Architect (subagent)
|
||||
│ ├── Virtual Developer (subagent)
|
||||
│ └── Virtual QA Engineer (subagent)
|
||||
└── LeadValidator (separate terminal — .validator-workspace/) ← NEW
|
||||
Reports findings to CEO via #vv-findings
|
||||
BLOCKER alerts also go to #vpe-cto-approvals
|
||||
```
|
||||
|
||||
The LeadValidator is the only agent in the system that:
|
||||
1. Reports directly to the CEO (not via CTO)
|
||||
2. Can issue a BLOCKER that prevents release
|
||||
3. Operates from an isolated workspace with no engineering team context
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: System Prompt Injection vs. CLAUDE.md Workspace
|
||||
|
||||
**Decision**: Use `--system-prompt-file VALIDATOR.md` to inject the validator's identity.
|
||||
|
||||
**Rationale**: The CTO uses `.cto-workspace/CLAUDE.md` for its identity because Claude Code
|
||||
reads CLAUDE.md as project context. For the validator, using `--system-prompt-file` is
|
||||
more explicit and harder to accidentally override — the validator's identity is injected
|
||||
at the OS level, not discovered by file-scan. This also prevents any future accidental
|
||||
CLAUDE.md conflicts if the workspace is updated.
|
||||
|
||||
**Alternative considered**: Give validator its own CLAUDE.md identity like the CTO — rejected
|
||||
because `--system-prompt-file` makes the validator identity non-negotiable and audit-grade.
|
||||
|
||||
### D2: Shared Ledger — Filesystem vs. Central Hub Only
|
||||
|
||||
**Decision**: Filesystem ledger (`openspec/vv_audit/`) as primary, central hub as notification layer.
|
||||
|
||||
**Rationale**: Issue files (`VV_ISSUE_NNN.md`) need to be persistent, versioned in git, and
|
||||
readable by humans without opening a terminal. The central hub is ephemeral session state.
|
||||
Filesystem issues survive session restarts; hub messages do not.
|
||||
|
||||
**Alternative considered**: Hub-only communication — rejected because hub messages are not
|
||||
committed to git and cannot be audited historically.
|
||||
|
||||
### D3: Issue Severity Model
|
||||
|
||||
**Decision**: Three-tier severity — BLOCKER / MAJOR / MINOR.
|
||||
|
||||
| Severity | Release impact | Who can close |
|
||||
|----------|---------------|---------------|
|
||||
| BLOCKER | Prevents release | CEO acknowledges; CTO resolves |
|
||||
| MAJOR | Must resolve before next phase | CTO resolves; Validator confirms |
|
||||
| MINOR | Best-effort improvement | CTO resolves; no re-audit needed |
|
||||
|
||||
**Rationale**: Binary pass/fail is too blunt for a mature codebase. Three tiers allow the
|
||||
team to ship with known MINOR issues while ensuring BLOCKERs are never silently bypassed.
|
||||
|
||||
### D4: Validator Workspace Isolation
|
||||
|
||||
**Decision**: Validator writes its own minimal CLAUDE.md to `.validator-workspace/` rather
|
||||
than copying the CEO session's CLAUDE.md.
|
||||
|
||||
**Rationale**: The CEO session CLAUDE.md defines multi-agent setup and CEO startup protocol —
|
||||
none of which applies to an auditor. Copying it would contaminate the validator context.
|
||||
The validator's workspace CLAUDE.md only provides absolute path references to project resources.
|
||||
|
||||
### D5: Audit Phases
|
||||
|
||||
**Decision**: 8 audit phases covering all PRD compliance dimensions.
|
||||
|
||||
| Phase | Scope |
|
||||
|-------|-------|
|
||||
| A | OpenSpec task completeness |
|
||||
| B | API surface vs OpenAPI specs |
|
||||
| C | TypeScript strict mode compliance |
|
||||
| D | DRY principle enforcement |
|
||||
| E | SOLID principle spot-checks |
|
||||
| F | Test coverage (>80% threshold) |
|
||||
| G | AGNTCY compliance |
|
||||
| H | Security (OWASP Top 10) |
|
||||
|
||||
All 8 phases must be run per audit session. A validator may document why a phase was
|
||||
skipped but cannot silently omit it.
|
||||
|
||||
## File Map
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `VALIDATOR.md` | System prompt for LeadValidator agent |
|
||||
| `scripts/start-validator.sh` | Launches validator, sets up workspace, sanity-checks VALIDATOR.md |
|
||||
| `.validator-workspace/` | Isolated workspace (gitignored) |
|
||||
| `.validator-workspace/CLAUDE.md` | Validator workspace context (absolute paths only) |
|
||||
| `openspec/vv_audit/LEDGER.md` | Audit ledger index — updated after each session |
|
||||
| `openspec/vv_audit/VV_ISSUE_NNN.md` | Individual issue files written by validator |
|
||||
| `.cto-workspace/CLAUDE.md` | Updated Peer-Review Protocol section |
|
||||
|
||||
## Hub Channels
|
||||
|
||||
| Channel | Purpose |
|
||||
|---------|---------|
|
||||
| `#vv-findings` | Validator → CEO + CTO: audit summaries, issue notifications |
|
||||
| `#vpe-cto-approvals` | Validator → CEO only: BLOCKER escalations |
|
||||
@@ -0,0 +1,54 @@
|
||||
# OpenSpec Proposal — vv-architect-setup
|
||||
|
||||
**Status:** Approved & Archived
|
||||
**Proposed:** 2026-04-07
|
||||
**Approved by:** CEO
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The SentryAgent.ai multi-agent engineering system has no independent quality gate.
|
||||
The Virtual CTO directs the engineering team (Architect, Developer, QA), which means
|
||||
the same chain of command that builds the software also signs off on its correctness.
|
||||
This creates a conflict of interest — the team grades its own homework.
|
||||
|
||||
Additionally, `VALIDATOR.md` existed in the repository but contained the wrong content:
|
||||
a copy of `scripts/start-validator.sh` (the shell script). If the validator had been
|
||||
launched, Claude would have received a bash script as its system prompt, producing
|
||||
a broken agent with no defined purpose or audit methodology.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Introduce a **V&V Architect (Lead Validator)** — a 4th independent Claude Code instance
|
||||
that runs outside the CTO's chain of command and reports directly to the CEO.
|
||||
|
||||
**WS1 — Fix VALIDATOR.md**
|
||||
Rewrite `VALIDATOR.md` as the proper system prompt for the Lead Validator agent.
|
||||
Must define: identity, independence principle, startup protocol, 8-phase audit
|
||||
methodology, issue format, severity definitions, and communication protocol.
|
||||
|
||||
**WS2 — Fix start-validator.sh**
|
||||
Update `scripts/start-validator.sh` to:
|
||||
- Build a validator-specific workspace (not inherit CEO session context)
|
||||
- Include a sanity check that aborts if VALIDATOR.md still contains shell script content
|
||||
- Auto-initialise the shared V&V audit ledger on first run
|
||||
|
||||
**WS3 — Shared V&V Issue Ledger**
|
||||
Create `openspec/vv_audit/` as the shared filesystem ledger accessible by both the
|
||||
Validator and the CTO via absolute paths. Create `LEDGER.md` as the audit index.
|
||||
|
||||
**WS4 — Central Hub Channel**
|
||||
Create `#vv-findings` channel on the central hub for real-time validator notifications
|
||||
to CEO and CTO. BLOCKER findings also escalate to `#vpe-cto-approvals`.
|
||||
|
||||
**WS5 — CTO Peer-Review Protocol Update**
|
||||
Update `.cto-workspace/CLAUDE.md` to reference the correct ledger path, hub channel,
|
||||
and dispute/resolution process so the CTO knows how to respond to validator findings.
|
||||
|
||||
## CEO Approval
|
||||
|
||||
Approved 2026-04-07 per CEO directive:
|
||||
"if possible — yes you have my approvals — as our technical and business consultant —
|
||||
please make the changes you need to make sure we have fully independent system to check
|
||||
we have fully implemented our PRD per OpenSpec protocols"
|
||||
@@ -0,0 +1,61 @@
|
||||
# Tasks — vv-architect-setup
|
||||
|
||||
## WS1 — Fix VALIDATOR.md (System Prompt)
|
||||
|
||||
- [x] 1.1 Identify the bug: `VALIDATOR.md` contained an exact copy of `scripts/start-validator.sh` (byte-for-byte identical — 1900 bytes each)
|
||||
- [x] 1.2 Rewrite `VALIDATOR.md` as the proper system prompt for the LeadValidator agent
|
||||
- [x] 1.3 Define validator identity and independence principle (not under CTO authority; reports to CEO)
|
||||
- [x] 1.4 Define 6-step startup protocol (read PRD → register hub → check ledger → check channel → report readiness → begin audit)
|
||||
- [x] 1.5 Define Phase A — OpenSpec task completeness check (verify all archived tasks.md `[x]` items have corresponding code)
|
||||
- [x] 1.6 Define Phase B — API surface audit (every route must have an OpenAPI spec; spec must match implementation)
|
||||
- [x] 1.7 Define Phase C — TypeScript standards audit (no `any`, strict mode, JSDoc, error hierarchy)
|
||||
- [x] 1.8 Define Phase D — DRY principle audit (no duplicated logic, utility files as single sources of truth)
|
||||
- [x] 1.9 Define Phase E — SOLID principles audit (SRP spot-checks on key services, constructor injection)
|
||||
- [x] 1.10 Define Phase F — Test coverage audit (>80% threshold, integration tests for all endpoints)
|
||||
- [x] 1.11 Define Phase G — AGNTCY compliance audit (agent identity model, lifecycle, DID, conformance tests)
|
||||
- [x] 1.12 Define Phase H — Security audit (OWASP Top 10 checks)
|
||||
- [x] 1.13 Define issue format: `VV_ISSUE_NNN.md` with Status, Severity, Category, Finding, Evidence, Required Action, CTO Response, Resolution
|
||||
- [x] 1.14 Define severity model: BLOCKER / MAJOR / MINOR with clear ownership and release impact
|
||||
- [x] 1.15 Define communication protocol: `#vv-findings` for routine findings, `#vpe-cto-approvals` for BLOCKER escalations
|
||||
- [x] 1.16 Define dispute resolution protocol: CTO writes justification → Validator evaluates → CEO as final arbiter
|
||||
- [x] 1.17 Define AUDIT LEDGER INDEX maintenance requirements
|
||||
|
||||
## WS2 — Fix scripts/start-validator.sh
|
||||
|
||||
- [x] 2.1 Remove the line that copies CEO's `CLAUDE.md` into the validator workspace (was contaminating validator with CEO-session context)
|
||||
- [x] 2.2 Add sanity check: abort with clear error if `VALIDATOR.md` first line is `#!/bin/bash` (prevents relaunching with wrong content)
|
||||
- [x] 2.3 Add `SHARED_LEDGER` variable pointing to `openspec/vv_audit/`
|
||||
- [x] 2.4 Add `mkdir -p "$SHARED_LEDGER"` to auto-create ledger directory on first run
|
||||
- [x] 2.5 Add auto-initialisation of `LEDGER.md` if it does not exist (idempotent — skipped if already present)
|
||||
- [x] 2.6 Write validator-specific `CLAUDE.md` to workspace (absolute paths only, no CEO-session context, no role-switching instructions)
|
||||
- [x] 2.7 Update echoed launch checklist to reflect validator's actual responsibilities
|
||||
- [x] 2.8 Ensure `exec claude --system-prompt-file "$VALIDATOR_SYSTEM_PROMPT"` uses the correct variable name
|
||||
|
||||
## WS3 — Shared V&V Issue Ledger
|
||||
|
||||
- [x] 3.1 Create `openspec/vv_audit/` directory in project root (accessible by both validator and CTO via absolute paths)
|
||||
- [x] 3.2 Create `openspec/vv_audit/LEDGER.md` — structured audit index with Summary table, Issue Index, Audit History, and usage instructions
|
||||
- [x] 3.3 Document who updates what: Validator updates Summary and Issue Index; CTO updates issue files; CEO reads for release gate status
|
||||
|
||||
## WS4 — Central Hub Channel
|
||||
|
||||
- [x] 4.1 Create `#vv-findings` channel on central hub with description: "V&V Architect findings — audit issues, BLOCKER notifications, resolution tracking"
|
||||
- [x] 4.2 Verify `#vpe-cto-approvals` (CEO channel) already exists — BLOCKER escalations go here
|
||||
|
||||
## WS5 — CTO Peer-Review Protocol Update
|
||||
|
||||
- [x] 5.1 Update `.cto-workspace/CLAUDE.md` Peer-Review Protocol section
|
||||
- [x] 5.2 Replace relative path `./specs/issues/` with absolute path `openspec/vv_audit/`
|
||||
- [x] 5.3 Add `#vv-findings` channel reference
|
||||
- [x] 5.4 Clarify CTO cannot dismiss validator findings — only resolve or dispute
|
||||
- [x] 5.5 Clarify BLOCKER resolution protocol: CEO automatically notified; CTO must not resolve without CEO awareness
|
||||
- [x] 5.6 Add instruction on how to start the validator (`./scripts/start-validator.sh`)
|
||||
|
||||
## WS6 — OpenSpec Documentation (this change)
|
||||
|
||||
- [x] 6.1 Create `openspec/changes/archive/2026-04-07-vv-architect-setup/` directory
|
||||
- [x] 6.2 Write `proposal.md` — problem statement, proposed solution, CEO approval
|
||||
- [x] 6.3 Write `design.md` — architecture, decisions (D1–D5), file map, hub channels
|
||||
- [x] 6.4 Write `tasks.md` (this file) — complete task breakdown with all items checked
|
||||
- [x] 6.5 Create `specs/` directory (no API specs needed — this is agent governance tooling, not an API change)
|
||||
- [x] 6.6 Commit all changes to git: VALIDATOR.md, scripts/start-validator.sh, openspec/vv_audit/, openspec/changes/archive/2026-04-07-vv-architect-setup/
|
||||
Reference in New Issue
Block a user