Feature: Headless Doctorow Gate for CI/automation environments

[mellanon]

Problem

The Doctorow Gate in specflow complete uses interactive readline prompts ([Y/n/s(kip)]) which blocks usage in:

• Background agents (Claude Code Task tool)
• CI/CD pipelines
• Headless automation workflows
• Any non-TTY environment

Currently the only workaround is --skip-doctorow, which bypasses the quality gate entirely.

Proposal

Add automatic headless mode that evaluates the Doctorow checks programmatically instead of skipping them.

Detection

• process.stdin.isTTY === false → automatic headless mode
• SPECFLOW_HEADLESS=true env var → explicit opt-in
• Interactive terminal → existing human prompts (no change)

Evaluator Interface

interface DoctorowEvaluator {
  evaluate(check: DoctorowCheck, artifacts: FeatureArtifacts): Promise<DoctorowCheckResult>;
}

Two built-in implementations:

1. AI Evaluator (recommended default): Uses claude -p or an inference API to read spec.md, plan.md, tasks.md, verify.md and the source code, then evaluates each Doctorow question against the actual artifacts. Returns pass/fail with reasoning.

2. Static Evaluator (fallback): Pattern-matches artifacts for evidence:

   • Failure Test → checks for error handling tests, try/catch patterns
   • Assumption Test → checks spec.md has ## Assumptions section
   • Rollback Test → checks for reversible patterns
   • Debt Recorded → checks for TODO/FIXME documentation

Results Format

Same DoctorowCheckResult structure, appended to verify.md with [AI-evaluated] or [Static-evaluated] tag.

Configuration

# .specflow/config.yaml
doctorow:
  headless: auto       # auto | always-interactive | always-headless
  evaluator: ai        # ai | static
  ai_command: "claude -p"  # or custom inference command

Why This Matters

SpecFlow's value proposition includes agent-driven development workflows. The Doctorow Gate is a great quality check, but it currently forces a choice between quality (interactive) and automation (skip). This proposal preserves quality in automated environments.

Current Workaround

specflow complete F-1 --skip-doctorow — bypasses the gate entirely.

Related

• PR Fix migrations not running in compiled binary #3: Fix migrations in compiled binary
• PR Allow N/A sections in verify.md for CLI-only features #4: Accept N/A sections in verify.md

[jcfischer]

This has been addressed in PR #12, which adds automatic headless mode for the Doctorow Gate. When a non-TTY environment is detected (or SPECFLOW_HEADLESS=true is set), the gate now evaluates checks programmatically using a static evaluator instead of blocking on interactive prompts. The existing interactive behavior in terminal sessions is unchanged. See the PR for full details on the implementation.