How gsd-build Handles Phase Verification and Goal Achievement: A Technical Deep Dive

gsd-build treats phase completion as a goal-backward verification problem where a phase is only marked achieved when the codebase delivers the promised outcome, not merely when tasks are checked off.

The gsd-build/get-shit-done repository implements a rigorous verification system that separates task completion from actual goal achievement. Unlike traditional project management tools that consider a phase done when checkboxes are marked, gsd-build uses automated verification to confirm that the codebase objectively delivers the outcomes promised in the roadmap.

The Goal-Backward Philosophy

gsd-build operates on a goal-backward principle: the phase is considered achieved only when the codebase actually delivers the outcome promised in the roadmap, not when the listed tasks are marked "done". This approach prevents stale placeholders and hidden gaps by forcing objective verification of deliverables.

The system deliberately separates task completion from goal achievement to ensure that closed phases represent functional, verified outcomes rather than administrative checkmarks.

The Verification Architecture

The gsd-verifier Sub-Agent

The verification process is orchestrated by the gsd-verifier sub-agent defined in agents/gsd-verifier.md. This specialized agent runs the verify-phase workflow and has authority to inspect the codebase, parse plan files, and determine verification status without human intervention for automated checks.

The verify-phase Workflow

The core logic resides in get-shit-done/workflows/verify-phase.md, which defines an 11-step verification pipeline. This workflow initializes the phase context, extracts requirements, verifies observable truths, checks artifacts, validates wiring, scans for anti-patterns, and generates the final report.

The 11-Step Verification Process

1. Load Context and Initialize

The workflow begins by initializing the phase using gsd-tools cjs init phase-op and pulling the phase's goal, requirements, and all *-PLAN.md and *-SUMMARY.md files.

# Initialize phase context

gsd-tools cjs init phase-op

2. Establish Must-Haves

The system determines verification criteria through three hierarchical options:

• Option A: Read must_haves from each *-PLAN.md front-matter (truths, artifacts, key-links)
• Option B: Fall back to Success Criteria defined in ROADMAP.md
• Option C: Derive truths/artifacts/key-links from the phase goal when no other source exists

# Extract must_haves from plan frontmatter

for plan in "$PHASE_DIR"/*-PLAN.md; do
  MUST_HAVES=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs \
                frontmatter get "$plan" --field must_haves)
  echo "=== $plan ==="
  echo "$MUST_HAVES"
done

3. Verify Observable Truths

For every truth defined in the must-haves, the system locates supporting artifacts and checks their existence, substantive implementation, and wiring. Results are categorized as ✓ VERIFIED, ✗ FAILED, or ? UNCERTAIN.

4. Verify Artifacts

Using gsd-tools verify artifacts, the system checks three levels:

• Exists: File is present
• Substantive: Not a stub (meets minimum line count, required patterns)
• Wired: Imported and used in the codebase (manual grep verification)

ARTIFACT_RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs \
                    verify artifacts "$plan")

# Result JSON → { path, exists, issues, passed }

5. Verify Key-Links (Wiring)

The gsd-tools verify key-links command validates connections between components:

LINKS_RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs \
                verify key-links "$plan")

# JSON → { from, to, via, verified, detail }

Status becomes NOT_WIRED, PARTIAL, or WIRED based on regex patterns matching component→API, API→DB, and other architectural connections.

6. Requirements Coverage

If .planning/REQUIREMENTS.md exists, each requirement is cross-checked against verified truths and artifacts to ensure traceability.

7. Anti-Pattern Scan

The workflow greps for TODO/FIXME comments, placeholder text, empty returns, log-only functions, and categorizes findings as 🛑 Blocker, ⚠️ Warning, or ℹ️ Info.

8. Human Verification Needs

The system flags items requiring visual checks, real-time behavior validation, external service integration testing, or any "uncertain" truth that cannot be auto-verified.

9. Determine Overall Status

The phase receives one of three statuses:

• passed: Every truth/artifact/key-link verified, no blockers
• gaps_found: Any failure or blocker detected
• human_needed: All automated checks pass but manual testing remains

10. Generate VERIFICATION.md

The workflow populates the verification-report template with front-matter, tables of truths, artifacts, links, requirements, anti-patterns, human checks, gap summary, and suggested fix plans.

REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-VERIFICATION.md"
cat <<'EOF' > "$REPORT_PATH"
---
phase: $PHASE_NAME
verified: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
status: $STATUS
score: $VERIFIED/$TOTAL
---

# Phase $PHASE_NUM: $PHASE_TITLE Verification Report

...
EOF

11. Return to Orchestrator

The workflow sends status, score, and report path back to the main orchestrator, which then updates the roadmap, creates fix plans, or requests human verification.

Determining Goal Achievement

Goal achievement is a computed property in gsd-build. A phase is marked achieved only when the verification status is passed (or when remaining "human_needed" items are satisfied by the user).

This strict separation between task completion and goal achievement ensures that closed phases represent verified, runnable functionality rather than administrative milestones. The system prevents "checkbox completion" where tasks are marked done but the underlying goal remains unfulfilled.

Summary

• gsd-build treats phase verification as a goal-backward problem, verifying outcomes rather than task checkboxes.
• The gsd-verifier sub-agent orchestrates verification through the verify-phase workflow defined in get-shit-done/workflows/verify-phase.md.
• Verification follows an 11-step pipeline: loading context, establishing must-haves, verifying truths/artifacts/key-links, checking requirements, scanning anti-patterns, identifying human verification needs, determining status, and generating reports.
• Goal achievement is computed based on verification status (passed, gaps_found, or human_needed), ensuring phases represent verified functionality.

Frequently Asked Questions

What is the difference between task completion and goal achievement in gsd-build?

Task completion refers to the administrative act of marking items as done in a plan file, while goal achievement is a computed property determined by the gsd-verifier agent. A phase only achieves its goal when the verification workflow confirms that the codebase actually delivers the outcomes promised in the roadmap, not merely when the listed tasks are checked off.

How does gsd-build determine if an artifact is substantive rather than a stub?

The gsd-tools verify artifacts command checks three levels: Exists (file presence), Substantive (minimum line count and required code patterns), and Wired (actual usage in the codebase through import statements). An artifact fails the substantive check if it contains only placeholder comments, empty function bodies, or insufficient implementation depth as defined in the verification patterns.

What happens when the verification workflow finds gaps or blockers?

When the workflow detects failures in truth verification, missing artifacts, unwired key-links, or anti-pattern blockers, it assigns the phase a gaps_found status. The workflow then generates a detailed VERIFICATION.md report documenting all failures, their severity (Blocker, Warning, or Info), and suggested fix plans. This report is returned to the orchestrator, which can trigger remediation workflows or request human intervention.

Can gsd-build verify phases that require external services or visual validation?

Yes, but these items are flagged as human_needed during the verification process. The workflow identifies truths, artifacts, or behaviors that require visual checks, real-time interaction, or external service integration testing—items that cannot be automatically verified through static analysis. When all automated checks pass but human verification items remain, the phase receives a human_needed status, prompting the user to manually validate these specific aspects before final goal achievement is granted.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}