From d216096dfb83bf2f08b73f00dfb088e1199325b4 Mon Sep 17 00:00:00 2001 From: "SentryAgent.ai Developer" Date: Tue, 7 Apr 2026 02:56:36 +0000 Subject: [PATCH] =?UTF-8?q?feat(governance):=20add=20V&V=20Architect=20(Le?= =?UTF-8?q?adValidator)=20=E2=80=94=20independent=20audit=20agent?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- VALIDATOR.md | 296 +++++++++++++++--- .../2026-04-07-vv-architect-setup/design.md | 130 ++++++++ .../2026-04-07-vv-architect-setup/proposal.md | 54 ++++ .../2026-04-07-vv-architect-setup/tasks.md | 61 ++++ openspec/vv_audit/LEDGER.md | 47 +++ scripts/start-validator.sh | 112 +++++-- 6 files changed, 633 insertions(+), 67 deletions(-) create mode 100644 openspec/changes/archive/2026-04-07-vv-architect-setup/design.md create mode 100644 openspec/changes/archive/2026-04-07-vv-architect-setup/proposal.md create mode 100644 openspec/changes/archive/2026-04-07-vv-architect-setup/tasks.md create mode 100644 openspec/vv_audit/LEDGER.md diff --git a/VALIDATOR.md b/VALIDATOR.md index 476e036..3302ba0 100644 --- a/VALIDATOR.md +++ b/VALIDATOR.md @@ -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`, `` +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_.md` (zero-padded, e.g., `VV_ISSUE_001.md`) + +**File template:** +```markdown +# VV_ISSUE_ — + +**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:** +**Audit phase:** Phase A–H label + +## Finding + + + +## Evidence + + + +## Required Action + + + +## CTO Response + + + +## 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 | diff --git a/openspec/changes/archive/2026-04-07-vv-architect-setup/design.md b/openspec/changes/archive/2026-04-07-vv-architect-setup/design.md new file mode 100644 index 0000000..75b3b69 --- /dev/null +++ b/openspec/changes/archive/2026-04-07-vv-architect-setup/design.md @@ -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 | diff --git a/openspec/changes/archive/2026-04-07-vv-architect-setup/proposal.md b/openspec/changes/archive/2026-04-07-vv-architect-setup/proposal.md new file mode 100644 index 0000000..d6819df --- /dev/null +++ b/openspec/changes/archive/2026-04-07-vv-architect-setup/proposal.md @@ -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" diff --git a/openspec/changes/archive/2026-04-07-vv-architect-setup/tasks.md b/openspec/changes/archive/2026-04-07-vv-architect-setup/tasks.md new file mode 100644 index 0000000..f732e43 --- /dev/null +++ b/openspec/changes/archive/2026-04-07-vv-architect-setup/tasks.md @@ -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/ diff --git a/openspec/vv_audit/LEDGER.md b/openspec/vv_audit/LEDGER.md new file mode 100644 index 0000000..dc81309 --- /dev/null +++ b/openspec/vv_audit/LEDGER.md @@ -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 | + + + +--- + +## Audit History + +| Date | Phases Run | Issues Found | Overall Status | +|------|-----------|--------------|----------------| +| — | — | — | — | + + + +--- + +## 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 diff --git a/scripts/start-validator.sh b/scripts/start-validator.sh index 476e036..f84ecd9 100755 --- a/scripts/start-validator.sh +++ b/scripts/start-validator.sh @@ -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 " Workspace: $VALIDATOR_WORKSPACE" -echo " Role Config: $VALIDATOR_PROMPT" +echo " Project root: $PROJECT_ROOT" +echo " Workspace: $VALIDATOR_WORKSPACE" +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 + + +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" <