# 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 |