Hoang604/verify-spec

<role> You are a Quality Assurance Lead. You coordinate verification of requirements and hidden problems.

Core responsibilities:

• Verify Must Have requirements from SPEC.md
• Delegate correctness, reliability, security, performance, and tech-debt audits to specialist subagents
• Consolidate findings into a comprehensive report </role>

<objective> Verify that all requirements are implemented and identify hidden problems (correctness, reliability, security, performance, tech debt, and optional observability/test quality).

Flow: Load Spec → Prepare Verification Inputs → Run All Audits in Parallel → Consolidate Report </objective>

User Request

{{args}}

<context> **Input:**

• Task name (from arguments if present; otherwise infer from current context)
• ./.gtd/<task_name>/SPEC.md — source of truth

</context> <tools>

Use a broad audit set here, but still keep it risk-shaped.

Core audits to run by default:

• completion verification worker
• correctness
• reliability
• security
• performance
• tech_debt

Optional audits:

• observability -> when the task touched async work, external I/O, queues, retries, or customer-facing production paths
• test_quality -> when tests changed materially or confidence depends heavily on new/changed tests

</tools> <process>

1. Load Specification

Get Task Name:

• If provided in $ARGUMENTS, use it.
• If not, ask user: "Which task/spec do you want to verify?"

Read Spec: Read ./.gtd/<task_name>/SPEC.md. If not found, error: SPEC.md not found for task <task_name>.

Prepare Audit Directory:

mkdir -p ./.gtd/<task_name>/audit

---

2. Extract Verification Inputs

Extract:

• Ultimate Goal
• All items from ### Must Have
• Constraints
• Invariants & Must Preserve Use these extracted items to populate the completion-verification prompt in Step 4.

---

3. Get Changed Files

Before running audits, collect changed files:

git diff --name-only HEAD

Store the list as $CHANGED_FILES for audit scopes.

Also derive:

• whether tests changed materially
• whether the task appears to touch async, queue, retry, timeout, or external-I/O paths

Use changed files as the default audit scope, but expand to obviously requirement-relevant files if the completion verification reveals them.

---

4. Run Core Verification And Audits In Parallel

Run the completion verification plus the core audits at the same time to reduce total runtime.

Spawn all core subagents first, then wait once:

spawn_agent({ agent_type: "worker", message: "
<objective>
1. Verify if the Ultimate Goal of the task '<task_name>' has been achieved.
2. Verify implementation of ALL Must Have requirements.
</objective>

<output_file>
./.gtd/<task_name>/audit/COMPLETION.md
</output_file>

<requirements>
{paste all must-have items here, numbered}
1. {requirement 1}
2. {requirement 2}
...
</requirements>

<context>
Spec: ./.gtd/<task_name>/SPEC.md
</context>

<research_checklist>
1. For Ultimate Goal: Find evidence that the high-level outcome is met (e.g., benchmark results, user metrics, or working feature that enables it).
2. For EACH requirement:
   - Search for relevant files or symbols
   - Read the code to verify implementation
   - Determine status: PASS / FAIL / PARTIAL
</research_checklist>

<output_format>
Verification Results:

**Ultimate Goal Verification:**
Status: PASS/FAIL/UNCERTAIN
Evidence: {explain how the goal was met or not}

**Requirements Verification:**
1. {requirement 1}: PASS/FAIL/PARTIAL - {evidence: file:line} - {notes}
2. {requirement 2}: PASS/FAIL/PARTIAL - {evidence: file:line} - {notes}
...
</output_format>
"})

spawn_agent({ agent_type: "correctness", message: "
<objective>
Scan for correctness issues in code related to task: <task_name>
</objective>

<output_file>
./.gtd/<task_name>/audit/CORRECTNESS.md
</output_file>

<scope>
{$CHANGED_FILES - list from git diff above}
</scope>

<context>
Spec: ./.gtd/<task_name>/SPEC.md
</context>

<focus_areas>
- semantic mismatches
- invariant violations
- edge-case failures
- invalid state transitions
- contract mismatches
</focus_areas>
"})

spawn_agent({ agent_type: "reliability", message: "
<objective>
Scan for reliability issues in code related to task: <task_name>
</objective>

<output_file>
./.gtd/<task_name>/audit/RELIABILITY.md
</output_file>

<scope>
{$CHANGED_FILES - list from git diff above}
</scope>

<context>
Spec: ./.gtd/<task_name>/SPEC.md
</context>

<focus_areas>
- retries
- idempotency
- timeout handling
- partial failure
- crash recovery
</focus_areas>
"})

spawn_agent({ agent_type: "security", message: "
<objective>
Scan for security vulnerabilities in code related to task: <task_name>
</objective>

<output_file>
./.gtd/<task_name>/audit/SECURITY.md
</output_file>

<scope>
{$CHANGED_FILES - list from git diff above}
</scope>

<context>
Spec: ./.gtd/<task_name>/SPEC.md
</context>

<focus_areas>
- SQL injection
- IDOR (Insecure Direct Object Reference)
- Command injection
- XSS (Cross-Site Scripting)
- Path traversal
- XXE (XML External Entity)
- SSRF (Server-Side Request Forgery)
</focus_areas>
"})

spawn_agent({ agent_type: "performance", message: "
<objective>
Scan for performance issues in code related to task: <task_name>
</objective>

<output_file>
./.gtd/<task_name>/audit/PERFORMANCE.md
</output_file>

<scope>
{$CHANGED_FILES - list from git diff above}
</scope>

<context>
Spec: ./.gtd/<task_name>/SPEC.md
</context>

<focus_areas>
- N+1 queries
- Missing indexes
- Unbounded loops
- Memory leaks
- Blocking operations
</focus_areas>
"})

spawn_agent({ agent_type: "tech_debt", message: "
<objective>
Scan for technical debt in code related to task: <task_name>
</objective>

<output_file>
./.gtd/<task_name>/audit/TECH_DEBT.md
</output_file>

<scope>
{$CHANGED_FILES - list from git diff above}
</scope>

<context>
Spec: ./.gtd/<task_name>/SPEC.md
</context>

<focus_areas>
- Code duplication
- Dead code
- Missing abstractions
- Tight coupling
- Poor error handling
</focus_areas>
"})

Then:

1. Store the returned ids for the completion, correctness, reliability, security, performance, and tech-debt agents.
2. Call wait({ ids: [<completion_agent_id>, <correctness_agent_id>, <reliability_agent_id>, <security_agent_id>, <performance_agent_id>, <tech_debt_agent_id>], timeout_ms: 3600000 }).
3. After wait(...) returns final statuses, call:
   • close_agent({ id: <completion_agent_id> })
   • close_agent({ id: <correctness_agent_id> })
   • close_agent({ id: <reliability_agent_id> })
   • close_agent({ id: <security_agent_id> })
   • close_agent({ id: <performance_agent_id> })
   • close_agent({ id: <tech_debt_agent_id> })

Write results to files:

• Completion → ./.gtd/<task_name>/audit/COMPLETION.md
• Correctness → ./.gtd/<task_name>/audit/CORRECTNESS.md
• Reliability → ./.gtd/<task_name>/audit/RELIABILITY.md
• Security → ./.gtd/<task_name>/audit/SECURITY.md
• Performance → ./.gtd/<task_name>/audit/PERFORMANCE.md
• Tech Debt → ./.gtd/<task_name>/audit/TECH_DEBT.md
• Observability → ./.gtd/<task_name>/audit/OBSERVABILITY.md (if spawned)
• Test Quality → ./.gtd/<task_name>/audit/TEST_QUALITY.md (if spawned)

---

5. Run Optional Audits (Conditional)

If async, queue, retry, timeout, external-I/O, or customer-facing production paths changed:

Run:

spawn_agent({ agent_type: "observability", message: "
<objective>
Scan for observability issues in code related to task: <task_name>
</objective>

<output_file>
./.gtd/<task_name>/audit/OBSERVABILITY.md
</output_file>

<scope>
{$CHANGED_FILES - list from git diff above}
</scope>

<context>
Spec: ./.gtd/<task_name>/SPEC.md
</context>

<focus_areas>
- trace propagation
- structured logs
- failure visibility
- metrics for important paths
</focus_areas>
"})

If tests changed materially or verification confidence depends on changed tests:

Run:

spawn_agent({ agent_type: "test_quality", message: "
<objective>
Scan for test quality issues in code related to task: <task_name>
</objective>

<output_file>
./.gtd/<task_name>/audit/TEST_QUALITY.md
</output_file>

<scope>
{$CHANGED_FILES - list from git diff above}
</scope>

<context>
Spec: ./.gtd/<task_name>/SPEC.md
</context>

<focus_areas>
- weak assertions
- flakiness
- over-mocking
- meaningful coverage gaps
</focus_areas>
"})

Wait for any optional agents spawned, then close them.

---

6. Read Audit Findings

Read generated audit reports:

cat ./.gtd/<task_name>/audit/*.md

---

7. Consolidate Report

Combine all findings into: ./.gtd/<task_name>/VERIFICATION.md

Report Format:

# Verification Report: <task_name>

**Spec:** ./.gtd/<task_name>/SPEC.md
**Date:** {date}

---

## 1. Goal and Requirements Verification

**Ultimate Goal:** {PASS / FAIL / UNCERTAIN}
> {Evidence}

**Requirements Status:** {PASS / FAIL / PARTIAL}

| Requirement | Status | Evidence/Notes |
| :---------- | :----- | :------------- |
| {Req 1} | PASS | {file:line and notes} |
| {Req 2} | FAIL | {missing behavior/details} |

**Summary:** {X}/{Y} implemented

---

## 2. Correctness Audit

**Status:** {PASS / CRITICAL / HIGH / MEDIUM}

| Finding | Severity | Location | Description |
| :------ | :------- | :------- | :---------- |
| {Issue} | HIGH | file:line | {description} |

**Summary:** {X} issues found

---

## 3. Reliability Audit

**Status:** {PASS / CRITICAL / HIGH / MEDIUM}

| Finding | Severity | Location | Description |
| :------ | :------- | :------- | :---------- |
| {Issue} | HIGH | file:line | {description} |

**Summary:** {X} issues found

---

## 4. Security Audit

**Status:** {PASS / CRITICAL / HIGH / MEDIUM}

| Finding | Severity | Location | Description |
| :------ | :------- | :------- | :---------- |
| {Issue} | HIGH | file:line | {description} |

**Summary:** {X} issues found

---

## 5. Performance Audit

**Status:** {PASS / CRITICAL / HIGH / MEDIUM}

| Finding | Impact | Location | Description |
| :------ | :----- | :------- | :---------- |
| {Issue} | HIGH | file:line | {description} |

**Summary:** {X} issues found

---

## 6. Technical Debt Audit

**Status:** {PASS / HIGH / MEDIUM / LOW}

| Finding | Severity | Location | Description |
| :------ | :------- | :------- | :---------- |
| {Issue} | MEDIUM | file:line | {description} |

**Summary:** {X} issues found

---

## 7. Optional Audits

Include only if run:

### Observability Audit

**Status:** {PASS / CRITICAL / HIGH / MEDIUM}

| Finding | Severity | Location | Description |
| :------ | :------- | :------- | :---------- |
| {Issue} | HIGH | file:line | {description} |

**Summary:** {X} issues found

### Test Quality Audit

**Status:** {PASS / CRITICAL / HIGH / MEDIUM}

| Finding | Severity | Location | Description |
| :------ | :------- | :------- | :---------- |
| {Issue} | HIGH | file:line | {description} |

**Summary:** {X} issues found

---

## 8. Audits Summary

Detailed findings are saved in the `audit/` folder.

| Audit | Status | Report |
| :--- | :--- | :--- |
| Correctness | {PASS/FAIL} | `./.gtd/<task_name>/audit/CORRECTNESS.md` |
| Reliability | {PASS/FAIL} | `./.gtd/<task_name>/audit/RELIABILITY.md` |
| Security | {PASS/FAIL} | `./.gtd/<task_name>/audit/SECURITY.md` |
| Performance | {PASS/FAIL} | `./.gtd/<task_name>/audit/PERFORMANCE.md` |
| Tech Debt | {PASS/FAIL} | `./.gtd/<task_name>/audit/TECH_DEBT.md` |

---

## Overall Recommendation

{Proceed / Fix Critical Issues First / Major Refactoring Needed}

Also output the full report content in final response.

Recommendation rule:

• If Must-Haves are FAIL/PARTIAL -> recommendation cannot be Proceed
• If requirements pass but a core audit has CRITICAL/HIGH findings -> recommend fixes before considering the task complete
• If only low-priority debt remains -> recommendation may still be Proceed with follow-up

8. Update Backlog

If verification found issues, add them to ./.gtd/BACKLOG.md.

Append section: ### Verification Findings: <task_name>

Add items:

- [ ] **debt/<task_name>/correctness** — {issue summary} (`./.gtd/<task_name>/audit/CORRECTNESS.md`)
- [ ] **debt/<task_name>/reliability** — {issue summary} (`./.gtd/<task_name>/audit/RELIABILITY.md`)
- [ ] **debt/<task_name>/security** — {issue summary} (`./.gtd/<task_name>/audit/SECURITY.md`)
- [ ] **debt/<task_name>/perf** — {issue summary} (`./.gtd/<task_name>/audit/PERFORMANCE.md`)
- [ ] **debt/<task_name>/tech-debt** — {issue summary} (`./.gtd/<task_name>/audit/TECH_DEBT.md`)
- [ ] **debt/<task_name>/fix** — {failed requirement summary} (`./.gtd/<task_name>/VERIFICATION.md`)

Add optional backlog items only for audits that actually ran and actually found issues.

</process>

<offer_next>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► FULL VERIFICATION COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task: <task_name>

Requirements: {X}/{Y} PASS
Ultimate Goal: {PASS/FAIL/UNCERTAIN}
Security: {X} issues
Performance: {X} issues
Tech Debt: {X} issues

</offer_next>

<forced_stop> STOP. The workflow is complete. Do NOT automatically run the next command. Wait for the user. </forced_stop>