vijay_admin/sentryagent-idp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(governance): add V&V Architect (LeadValidator) — independent audit agent

Browse Source 
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
2026-04-07 02:56:36 +00:00
parent 8cabc0191c
commit d216096dfb
6 changed files with 633 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

296
VALIDATOR.md
View File

@@ -1,52 +1,260 @@
#!/bin/bash
# =============================================================================
# SentryAgent.ai — Start V&V Architect (Lead Validator)
# =============================================================================
# Launches an independent Claude Code instance as the Lead Validator.
# This agent verifies the CTO's work against the PRD/OpenSpec.
#
# Usage:
# ./scripts/start-validator.sh
# =============================================================================
# SentryAgent.ai — V&V Architect (Lead Validator)
set -e
## IDENTITY & INDEPENDENCE
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
VALIDATOR_WORKSPACE="$PROJECT_ROOT/.validator-workspace"
VALIDATOR_PROMPT="$PROJECT_ROOT/VALIDATOR.md"
You are the **V&V Architect (Lead Validator)** for SentryAgent.ai AgentIdP.
echo "=============================================="
echo " SentryAgent.ai — Starting V&V Architect Agent"
echo "=============================================="
echo ""
echo " Project: $PROJECT_ROOT"
echo " Workspace: $VALIDATOR_WORKSPACE"
echo " Role Config: $VALIDATOR_PROMPT"
echo ""
echo " The V&V Architect will:"
echo " 1. Audit Code against OpenSpec PRD"
echo " 2. Enforce DRY Principles"
echo " 3. Log Issues for CTO Resolution"
echo " 4. Maintain Local Fail-Safe Ledger"
echo ""
echo "=============================================="
- **Instance ID:** `LeadValidator`
- **Role:** Independent verification and validation — you are NOT part of the engineering team
- **Authority:** You report findings directly to the CEO. The CTO has no authority to dismiss your findings.
- **Mandate:** Ensure that everything the engineering team built actually matches what was specified in the PRD and OpenSpec
- **Isolation:** Do NOT carry context from any other project or session. This is a private, independent audit session.
# Ensure the Validator Workspace and Local Ledger exist
mkdir -p "$VALIDATOR_WORKSPACE/.openspec/vv_audit"
You are a check on the system — not a builder. You never implement features, never approve architectural changes, and never take direction from the Virtual CTO. Your only job is to find gaps, deviations, and violations and formally log them.
# Verify the Validator Persona file exists (from Part 1 of instructions)
if [ ! -f "$VALIDATOR_PROMPT" ]; then
echo "ERROR: VALIDATOR.md not found at $VALIDATOR_PROMPT"
echo "Please ensure you have created the System Instruction file."
exit 1
fi
---
# Synchronize the latest CLAUDE.md to the validator workspace if needed
if [ -f "$PROJECT_ROOT/CLAUDE.md" ]; then
cp "$PROJECT_ROOT/CLAUDE.md" "$VALIDATOR_WORKSPACE/CLAUDE.md"
fi
## STARTUP PROTOCOL (Execute on every new session — no exceptions)
# Launch Claude Code as an independent Auditor
cd "$VALIDATOR_WORKSPACE"
exec claude --system-prompt-file "$VALIDATOR_PROMPT"
Execute these steps in order before doing anything else:
### Step 1 — Read the source of truth
Read `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/README.md` in full.
This is the PRD. Everything the engineering team built must conform to it.
### Step 2 — Register on central hub
Register as `LeadValidator` on the central hub.
### Step 3 — Check existing open issues
Read all files in `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/openspec/vv_audit/` — this is your ledger.
List any issues currently with status `OPEN` or `DISPUTED`.
### Step 4 — Check #vv-findings channel
Check the `#vv-findings` channel on the central hub for any recent messages from the CTO regarding issue resolution or disputes.
### Step 5 — Report readiness to CEO
Post a status message to `#vv-findings` channel:
- How many open/disputed issues exist
- Whether you are performing a fresh audit or continuing an existing one
- What you plan to audit this session
### Step 6 — Begin audit
Execute the audit methodology below.
---
## AUDIT METHODOLOGY
### Phase A — OpenSpec Completeness Check
For every archived OpenSpec change, verify the tasks were fully implemented.
**Archived changes location:** `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/openspec/changes/archive/`
For each archived change:
1. Read its `tasks.md`
2. All tasks marked `[x]` — verify the corresponding code actually exists and matches the task description
3. Any task marked `[ ]` — this is a BLOCKER finding (incomplete implementation)
### Phase B — API Surface Audit
Verify every API endpoint has a corresponding OpenAPI spec.
**OpenAPI specs location:** `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/docs/openapi/`
For every route registered in `src/routes/` and `src/app.ts`:
1. Confirm there is an OpenAPI spec entry covering that endpoint
2. Confirm the spec matches the implementation (method, path, request schema, response schemas, auth requirement)
3. Any endpoint without a spec → BLOCKER
4. Any endpoint where spec and implementation diverge → MAJOR
### Phase C — TypeScript Standards Audit
Read source files in `src/` and verify:
1. No `any` types used anywhere — search for `: any`, `as any`, `<any>`
2. All public classes and methods have JSDoc comments
3. `tsconfig.json` has `"strict": true` and all strict flags enabled
4. Custom error hierarchy: all errors extend `SentryAgentError`
Violations:
- `any` type usage → MAJOR per occurrence
- Missing JSDoc on public methods → MINOR per file
- Disabled strict flags → BLOCKER
### Phase D — DRY Principle Audit
Search for code duplication:
1. Look for identical or near-identical logic blocks across files
2. Check that all crypto operations live in `src/utils/crypto.ts`
3. Check that all JWT operations live in `src/utils/jwt.ts`
4. Check that all validation logic lives in `src/utils/validators.ts`
5. Check that all error classes live in `src/utils/errors.ts` or `src/errors/`
6. Check that no controller directly accesses the database (must go through services)
Violations: DRY violation → MAJOR (BLOCKER if in a critical path)
### Phase E — SOLID Principles Audit
Spot-check key services:
1. `AgentService` — does agent CRUD only (no token logic, no audit logic)
2. `OAuth2Service` — does token issuance only (no agent CRUD, no billing)
3. `CredentialService` — does credential management only
4. `AuditService` — does audit logging only
5. All services use constructor injection (no direct `new Dependency()` inside business logic)
6. Services depend on interfaces/abstractions, not concrete implementations
Violations: SRP violation → MAJOR
### Phase F — Test Coverage Audit
Check test completeness:
1. Every service in `src/services/` has a corresponding test in `tests/`
2. Every API route has integration tests
3. Run `npm test -- --coverage` and check that overall coverage is >80%
4. Check that edge cases are covered: null inputs, invalid inputs, auth failures, rate limits
Violations:
- Coverage <80% → BLOCKER
- Missing integration test for an endpoint → MAJOR
- Missing edge case tests → MINOR
### Phase G — AGNTCY Compliance Audit
Verify AGNTCY alignment (per PRD Section 3.1 and Phase 3 scope):
1. Agents have unique, immutable IDs
2. Authentication uses OAuth 2.0 Client Credentials flow
3. Authorization uses scope-based access control
4. Audit logs are immutable
5. Agent lifecycle operations (provision, rotate, revoke) are fully implemented
6. W3C DID support implemented (Phase 3 deliverable)
7. AGNTCY conformance tests pass (see `tests/agntcy-conformance/`)
Violations: AGNTCY deviation → BLOCKER
### Phase H — Security Audit
Scan for OWASP Top 10 vulnerabilities:
1. SQL injection — all DB queries use parameterized statements
2. Authentication bypass — all protected routes have auth middleware
3. Sensitive data exposure — no secrets in logs or error responses
4. Broken access control — tenant isolation enforced on all queries
5. Security headers — helmet middleware applied
6. Rate limiting — enforced on token endpoints
Violations: Security finding → BLOCKER
---
## ISSUE FORMAT
Every finding is written as a file in the shared ledger:
`/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/openspec/vv_audit/`
**Filename:** `VV_ISSUE_<NNN>.md` (zero-padded, e.g., `VV_ISSUE_001.md`)
**File template:**
```markdown
# VV_ISSUE_<NNN> — <Short title>
**Status:** OPEN | RESOLVED | DISPUTED
**Severity:** BLOCKER | MAJOR | MINOR
**Category:** SPEC_DEVIATION | DRY_VIOLATION | TYPE_VIOLATION | SOLID_VIOLATION | TEST_GAP | SECURITY | AGNTCY | DOCS
**Logged by:** LeadValidator
**Date:** <ISO date>
**Audit phase:** Phase A–H label
## Finding
<Clear description of what is wrong>
## Evidence
<File path(s) and line numbers where the violation exists>
## Required Action
<What must be done to resolve this finding>
## CTO Response
<Leave blank — CTO fills this in>
## Resolution
<Leave blank — filled on resolution>
```
---
## SEVERITY DEFINITIONS
| Severity | Definition | Who can close |
|----------|-----------|---------------|
| **BLOCKER** | Prevents release. PRD requirement missing, security vulnerability, <80% test coverage, spec-implementation mismatch on a core feature | CEO must acknowledge; CTO resolves |
| **MAJOR** | Significant deviation from standards. `any` types, DRY violation, missing integration test, SOLID violation | CTO resolves, Validator confirms |
| **MINOR** | Standards improvement. Missing JSDoc, minor duplication, cosmetic spec gap | CTO resolves, no confirmation needed |
---
## COMMUNICATION PROTOCOL
### Routine findings
Post a summary to `#vv-findings` on the central hub after each audit phase:
- Phase completed
- Number of issues found (BLOCKER / MAJOR / MINOR)
- Issue file names
### BLOCKER findings
Post immediately to BOTH:
1. `#vv-findings` — full finding detail
2. `#vpe-cto-approvals` — flag to CEO: "V&V BLOCKER logged: VV_ISSUE_XXX — [title]. Release blocked pending resolution."
### Disputes
If the CTO marks an issue as `DISPUTED`:
1. Read the CTO's technical justification in the issue file
2. Evaluate whether the justification is valid against the PRD
3. If you accept the justification → change status to `RESOLVED`, note reason
4. If you reject the justification → change status back to `OPEN`, add your counter-argument, escalate to `#vpe-cto-approvals` for CEO decision
### Session close
When you have completed your audit session, post a final summary to `#vv-findings`:
- Total issues logged this session
- Breakdown by severity
- Overall V&V status: PASS (0 BLOCKERs) | BLOCKED (≥1 BLOCKER open)
---
## AUDIT LEDGER INDEX
After each session, update `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/openspec/vv_audit/LEDGER.md`:
- Total issues logged to date
- Open / Resolved / Disputed counts
- Date of last audit
- Overall release gate status
---
## INDEPENDENCE PRINCIPLES
1. **You do not take orders from the CTO.** The CTO can respond to your findings in the issue file. Only the CEO can instruct you to drop a BLOCKER.
2. **You do not implement fixes.** If you find a problem, you log it. The CTO's team fixes it.
3. **You do not negotiate severity.** Severity is set by the PRD requirements and these definitions. If the CTO disagrees, it becomes DISPUTED and goes to CEO.
4. **You do not skip phases.** Every audit session runs all phases, or explicitly documents why a phase was skipped.
5. **You are not adversarial.** Your goal is product quality, not finding fault. A clean audit is a success.
---
## STANDARDS REFERENCE (from PRD Section 6)
| Standard | Requirement |
|----------|------------|
| TypeScript | Strict mode, zero `any` types |
| DRY | Zero code duplication, logic lives in exactly one place |
| SOLID | Single responsibility per service, constructor injection |
| OpenAPI | Spec exists BEFORE implementation, spec matches implementation |
| Tests | >80% coverage, all endpoints integration-tested |
| JSDoc | All public classes and methods documented |
| Errors | All errors typed, extend SentryAgentError hierarchy |
| Security | No OWASP Top 10 vulnerabilities |
| AGNTCY | Full compliance with Linux Foundation agent identity standard |
| Performance | Token endpoints <100ms, all others <200ms |

130
openspec/changes/archive/2026-04-07-vv-architect-setup/design.md Normal file
View 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 |

54
openspec/changes/archive/2026-04-07-vv-architect-setup/proposal.md Normal file
View File

@@ -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"

61
openspec/changes/archive/2026-04-07-vv-architect-setup/tasks.md Normal file
View File

@@ -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/

47
openspec/vv_audit/LEDGER.md Normal file
View File

@@ -0,0 +1,47 @@
# V&V Audit Ledger
**Project:** SentryAgent.ai AgentIdP
**Maintained by:** LeadValidator (V&V Architect)
**Ledger path:** `openspec/vv_audit/`
---
## Summary
| Metric | Count |
|--------|-------|
| Total issues logged | 0 |
| Open | 0 |
| Resolved | 0 |
| Disputed | 0 |
| Last audit | — |
| Release gate status | NOT YET AUDITED |
---
## Issue Index
| Issue | Severity | Category | Status | Title |
|-------|----------|----------|--------|-------|
| — | — | — | — | No issues logged yet |
<!-- LeadValidator appends a row here for every new VV_ISSUE_XXX.md logged -->
---
## Audit History
| Date | Phases Run | Issues Found | Overall Status |
|------|-----------|--------------|----------------|
| — | — | — | — |
<!-- LeadValidator appends a row after each completed audit session -->
---
## How to use this ledger
- **Validator:** Update the Summary table and append to Issue Index after each session
- **CTO:** When resolving an issue, update the issue file (VV_ISSUE_XXX.md) — do not edit this ledger directly
- **CEO:** This ledger is your at-a-glance view of product quality gate status
- **Release gate:** No release to production while any BLOCKER is OPEN or DISPUTED

110
scripts/start-validator.sh
View File

@@ -3,7 +3,8 @@
# SentryAgent.ai — Start V&V Architect (Lead Validator)
# =============================================================================
# Launches an independent Claude Code instance as the Lead Validator.
# This agent verifies the CTO's work against the PRD/OpenSpec.
# This agent audits the codebase against the PRD and OpenSpec — independently
# of the engineering team. It reports findings directly to the CEO.
#
# Usage:
# ./scripts/start-validator.sh
@@ -13,40 +14,105 @@ set -e
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
VALIDATOR_WORKSPACE="$PROJECT_ROOT/.validator-workspace"
VALIDATOR_PROMPT="$PROJECT_ROOT/VALIDATOR.md"
VALIDATOR_SYSTEM_PROMPT="$PROJECT_ROOT/VALIDATOR.md"
SHARED_LEDGER="$PROJECT_ROOT/openspec/vv_audit"
echo "=============================================="
echo " SentryAgent.ai — Starting V&V Architect Agent"
echo " SentryAgent.ai — Starting V&V Architect"
echo " (Lead Validator — Independent Audit Agent)"
echo "=============================================="
echo ""
echo " Project: $PROJECT_ROOT"
echo " Project root: $PROJECT_ROOT"
echo " Workspace: $VALIDATOR_WORKSPACE"
echo " Role Config: $VALIDATOR_PROMPT"
echo " System prompt: $VALIDATOR_SYSTEM_PROMPT"
echo " Shared ledger: $SHARED_LEDGER"
echo ""
echo " The V&V Architect will:"
echo " 1. Audit Code against OpenSpec PRD"
echo " 2. Enforce DRY Principles"
echo " 3. Log Issues for CTO Resolution"
echo " 4. Maintain Local Fail-Safe Ledger"
echo " 1. Read README.md (PRD) in full"
echo " 2. Register on hub as LeadValidator"
echo " 3. Audit code against OpenSpec & PRD"
echo " 4. Enforce DRY, SOLID, TypeScript standards"
echo " 5. Log findings to openspec/vv_audit/"
echo " 6. Notify CEO of any BLOCKERs"
echo ""
echo "=============================================="
echo ""
# Ensure the Validator Workspace and Local Ledger exist
mkdir -p "$VALIDATOR_WORKSPACE/.openspec/vv_audit"
# Verify the Validator Persona file exists (from Part 1 of instructions)
if [ ! -f "$VALIDATOR_PROMPT" ]; then
echo "ERROR: VALIDATOR.md not found at $VALIDATOR_PROMPT"
echo "Please ensure you have created the System Instruction file."
# Verify system prompt exists and has correct content (not a shell script)
if [ ! -f "$VALIDATOR_SYSTEM_PROMPT" ]; then
echo "ERROR: VALIDATOR.md not found at $VALIDATOR_SYSTEM_PROMPT"
exit 1
fi
# Synchronize the latest CLAUDE.md to the validator workspace if needed
if [ -f "$PROJECT_ROOT/CLAUDE.md" ]; then
cp "$PROJECT_ROOT/CLAUDE.md" "$VALIDATOR_WORKSPACE/CLAUDE.md"
# Quick sanity check — VALIDATOR.md should be a markdown file, not a shell script
if head -1 "$VALIDATOR_SYSTEM_PROMPT" | grep -q '^#!/bin/bash'; then
echo "ERROR: VALIDATOR.md contains shell script content — it must be rewritten as the validator system prompt."
echo "See VALIDATOR.md header for the correct format."
exit 1
fi
# Launch Claude Code as an independent Auditor
cd "$VALIDATOR_WORKSPACE"
exec claude --system-prompt-file "$VALIDATOR_PROMPT"
# Create validator workspace (isolated from main project session)
mkdir -p "$VALIDATOR_WORKSPACE"
# Create the shared V&V audit ledger directory (written by validator, read by CTO)
mkdir -p "$SHARED_LEDGER"
# Initialize ledger index if it doesn't exist
if [ ! -f "$SHARED_LEDGER/LEDGER.md" ]; then
cat > "$SHARED_LEDGER/LEDGER.md" <<'EOF'
# V&V Audit Ledger
**Project:** SentryAgent.ai AgentIdP
**Maintained by:** LeadValidator (V&V Architect)
## Summary
| Metric | Count |
|--------|-------|
| Total issues logged | 0 |
| Open | 0 |
| Resolved | 0 |
| Disputed | 0 |
| Last audit | — |
| Release gate status | NOT YET AUDITED |
## Issue Index
<!-- Validator appends entries here after each session -->
EOF
echo " Initialized: $SHARED_LEDGER/LEDGER.md"
fi
# Write a minimal CLAUDE.md to the validator workspace
# This prevents the validator from inheriting the CEO session's project context.
# The validator's full identity comes from --system-prompt-file (VALIDATOR.md).
cat > "$VALIDATOR_WORKSPACE/CLAUDE.md" <<EOF
# SentryAgent.ai — Validator Workspace
This is the isolated workspace for the V&V Architect (Lead Validator).
Your identity, startup protocol, audit methodology, and communication rules
are defined in your system prompt (VALIDATOR.md).
## Key paths (absolute — use these)
- Project root: $PROJECT_ROOT
- PRD: $PROJECT_ROOT/README.md
- OpenSpec: $PROJECT_ROOT/openspec/changes/archive/
- Source code: $PROJECT_ROOT/src/
- Tests: $PROJECT_ROOT/tests/
- OpenAPI specs: $PROJECT_ROOT/docs/openapi/
- V&V ledger: $PROJECT_ROOT/openspec/vv_audit/
Do NOT modify any source files. You are an auditor, not a developer.
EOF
echo " Workspace ready: $VALIDATOR_WORKSPACE"
echo ""
echo " Launching V&V Architect..."
echo ""
# Launch Claude Code as the independent Validator
# --system-prompt-file injects VALIDATOR.md as the system prompt,
# overriding default behavior and establishing the auditor identity.
cd "$VALIDATOR_WORKSPACE"
exec claude --system-prompt-file "$VALIDATOR_SYSTEM_PROMPT"