bug(sdd): SDD workflow does not enforce TDD, verify, or task completion — sub-agents report "done" with incomplete implementations #262

Pre-flight Checklist

• I have searched existing issues and this is not a duplicate
• I understand that PRs will be rejected if the linked issue does not have status:approved

📝 Bug Description

Summary

Three enforcement gaps in the SDD workflow combine to produce incomplete, unverified implementations that the orchestrator accepts as "done":

1. Strict TDD Mode is ignored — sdd-init enables it, sdd-apply never enforces it
2. Verify phase is silently skipped — nothing gates the next SDD on the current one's verification
3. Sub-agents report "done" without checking the spec — "tests pass" ≠ "spec satisfied"

These are not three independent bugs. They are three symptoms of one design flaw: the SDD workflow has no enforcement mechanism between phases — it relies entirely on sub-agent self-reporting.

The Evidence

A session implemented 7 SDDs (235 tasks) with Strict TDD Mode: enabled. After all 7 were marked "complete" by the orchestrator, formal verify was run for the first time. Results:

Pattern: The first 2 SDDs (smallest, freshest context) were complete. The last 5 (larger, degraded context) had 17+ CRITICALs combined.

What Went Wrong — Detailed Analysis

Problem 1: TDD Not Enforced

sdd-init detects testing capabilities and outputs Strict TDD Mode: enabled. This flag is stored but never read by sdd-apply. Sub-agents receive "Follow STRICT TDD" as text in their prompt, but:

• There's no mechanism to verify a test file was committed BEFORE the implementation
• The agent self-reports compliance — nobody checks
• As context pressure grows (SDD # 5, # 6, # 7), agents write tests and code together or skip tests entirely

Why this matters: Test-first development would have caught the method mismatch (enqueue vs store) because the test would have imported and called the real interface before the implementation existed.

Nuance: Not all tasks benefit from test-first. Moving a file between packages, updating import paths, or creating Dockerfiles don't have natural "write test first" entry points. The workflow doesn't distinguish between:

• BEHAVIORAL tasks (new logic) — TDD is valuable and should be enforced
• STRUCTURAL tasks (file moves, import rewiring) — existing tests are the safety net
• INFRASTRUCTURE tasks (config files, CI) — not unit-testable

Problem 2: Verify Phase Skipped

The SDD pipeline defines: apply → VERIFY → archive. In automatic mode with multiple SDDs, what happens:

SDD-A: apply → "done" → SDD-B: apply → "done" → SDD-C: apply → ... → verify never runs

Nothing in the orchestrator blocks proceeding without verify. The state machine has no transition requiring verified before the next SDD starts.

Why this matters: Verify reads the spec document and checks EACH requirement against the actual code. It catches things that tests and linters cannot:

• "This function was supposed to be deleted but it's still there with callers"
• "This architecture rule has a regex bug — it matches nothing"
• "4 features from the spec have zero corresponding code"

These are invisible to pytest (no test fails for a feature that doesn't exist) and invisible to linters (correct code that's simply missing isn't a lint violation).

Problem 3: "Tests Pass" ≠ "Spec Satisfied"

This is the core insight. Apply agents run pytest and ./check rules after each phase. Both verify CODE CORRECTNESS. Neither verifies SPEC COMPLETENESS.

• A function that should be deleted but wasn't → tests pass (function still works)
• A method name mismatch between two new components → tests pass (they're never called together in tests)
• An entire phase skipped → tests pass (no new tests exist for the skipped work)
• A regex bug in an architecture rule → rule reports PASS (matches nothing, so no violations found)

The spec defines WHAT SHOULD EXIST. Tests verify WHAT DOES EXIST WORKS. The gap between "what should exist" and "what does exist" is only caught by verify.

Problem 4: Context Degradation in Long Sessions

Sub-agents for later SDDs operate with compressed context from earlier phases. The agent knows "Phase 1-3 are done" abstractly but has lost the detailed task descriptions. When it runs final tests and they pass, it genuinely believes it's complete.

Evidence: strict correlation between session order and CRITICAL count. SDDs implemented first (fresh context, full attention) were complete. SDDs implemented last (compressed context, throughput pressure) had the most gaps.

Problem 5: Cross-SDD Integration Is Nobody's Job

When SDD-3 creates UnitOfWork.commit() calling self._outbox.enqueue(), and SDD-2 creates OutboxWriter.store(), the method name mismatch is invisible to both agents. Each only sees its own spec. The orchestrator doesn't verify integration points between SDDs.

Proposed Fixes

Fix 1: Mandatory verify gate (highest priority)

After each apply, the orchestrator MUST launch verify and block on 0 CRITICAL before proceeding. No exceptions in automatic mode.

SDD-A: apply → verify (0 CRITICAL?) → next SDD
                  ↓ (has CRITICALs)
              fix → re-verify → (0 CRITICAL?) → next SDD

Fix 2: Task classification in sdd-tasks

Each task gets a type: behavioral (TDD mandatory), structural (existing tests sufficient), infra (build validation). Apply agents enforce TDD only for behavioral tasks, eliminating the impractical "test-first for file moves" problem.

Fix 3: Task completion tracking

Apply agents use a structured tracker, not mental checkboxes. After returning, the orchestrator can see: "Completed 32/37 tasks. Skipped: T3.2, T3.5, T3.8, T4.1, T4.3" instead of just "done."

Fix 4: Executable acceptance criteria

Each task's AC (grep command, file existence check, test assertion) runs automatically after the task. Not just the global test suite — the SPECIFIC check for THAT task.

Fix 5: Session budget

Maximum N SDDs per session (default: 3). After N, save state and require a new session. Each session starts with fresh context. Prevents the quality gradient from session-order degradation.

Fix 6: Cross-SDD integration spec

When SDDs have dependencies, generate integration points: shared interfaces, method signatures, expected callers. The later SDD's verify checks these integration points against the earlier SDD's actual code.

🔄 Steps to Reproduce

✅ Expected Behavior

.

❌ Actual Behavior

.

Gentle AI Version

.

Operating System

macOS

AI Agent / Client

Claude Code

📋 Affected Area

CLI (commands, flags)

💡 Logs / Error Output

Additional Context

No response