feat: add flowspec doctor health-check command (TASK-606) by jpoley · Pull Request #1249 · jpoley/flowspec

jpoley · 2026-05-23T10:02:22Z

Summary

Adds flowspec doctor command with 8 environment health checks (Python version, flowspec version, backlog, beads, workflow config, agent naming convention, constitution.md, .flowspec dir)
Outputs Rich table with ✅/⚠️/❌ per check; exits non-zero on any FAIL
--fix flag auto-creates memory/constitution.md and runs flowspec upgrade-repo for fixable issues; re-runs checks post-fix so exit code reflects actual post-fix state
Module lives in src/flowspec_cli/doctor/ (checks.py + cli.py); registered via @app.command("doctor") in __init__.py

What was hardened post-review

After Copilot review (commit 2581270) and a GPT-5.5 harsh review (commit 047a821):

subprocess.run calls have timeout=5 with TimeoutExpired catch — hangs can't stall the command
yaml.safe_load() returning None or a list no longer crashes WorkflowValidator
File read catches OSError/UnicodeDecodeError, not just yaml.YAMLError
check_agent_naming, check_constitution, check_flowspec_dir use is_dir()/is_file() — file/dir mismatches handled correctly
_is_version_string() uses a strict regex (^\d+(\.\d+)*$) — rejects ".", "1..", "1.2."
_fix_constitution() requires at least one project marker (.flowspec dir or flowspec_workflow.yml) before writing files — prevents accidental creation in random directories
_fix_constitution() catches OSError on write
upgrade-repo subprocess runs with cwd=project_path

Test plan

uv run pytest tests/test_doctor.py -v — 41 tests, all pass
uv run pytest tests/ -x -q — 3514 passed, 0 failed
uv run ruff check . && uv run ruff format --check . — clean
flowspec doctor in a real project dir shows results table
flowspec doctor --fix in tmp dir with .flowspec present creates memory/constitution.md
flowspec doctor --fix in a dir with no project markers skips constitution creation

Closes #606

🤖 Generated with Claude Code

- Replace CLAUDE.md with cfix-style template personalised to flowspec-cli - Add AGENTS.md for Codex/compatible agents - Add .github/copilot-instructions.md for GitHub Copilot - Add .claude/workflow.md, stack.md, language.md, architecture.md, sourcecontrol.md, history.md support files - Add .claude/plans/task-606-flowspec-doctor.md implementation plan - Remove CLAUDE.md write-deny rule from settings.json (was blocking template) - Create TASK-606 backlog task for flowspec doctor command Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: jpoley <jason.poley@gmail.com>

Implements TASK-606 / closes #1221. Adds `flowspec doctor` (and `flowspec doctor --fix`) with 8 environment checks: Python version, flowspec vs latest release, backlog.md, beads, flowspec_workflow.yml validity, agent file naming, constitution.md presence, and .flowspec/ directory. Rich table output with ✅/⚠️/❌ symbols and actionable fix hints. 23 new unit tests; full suite passes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: jpoley <jason.poley@gmail.com>

- Version comparison: replace string equality with tuple parse so 0.4.008 and 0.4.8 are treated as equivalent - check_backlog_installed: validate stdout is a dotted-integer version string before reporting PASS (rejects unexpected output) - check_beads_installed: same version-string validation on extracted token - check_workflow_config: wire in WorkflowConfig schema validation and WorkflowValidator semantic checks; imports hoisted to module level for testability - --fix upgrade-repo: check returncode and report success/failure accurately instead of printing success unconditionally - run_doctor: replace bare except Exception with specific httpx.HTTPError / TimeoutException / OSError - Tests: add _parse_version unit tests, invalid-stdout FAIL test for backlog, CliRunner tests for exit codes and --fix constitution creation - Docs: remove stale TASK-606/branch refs from CLAUDE.md, AGENTS.md, copilot-instructions; fix inline-imports rule to match codebase reality Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: jpoley <jason.poley@gmail.com>

- Add timeout=5 and TimeoutExpired catch to backlog/beads subprocess calls - Guard WorkflowValidator against non-dict yaml.safe_load() return - Catch OSError/UnicodeDecodeError in workflow config file read - Use is_dir()/is_file() instead of exists() for .flowspec, constitution, agents - Tighten _is_version_string() with regex (rejects '1.2.', '.', '1..') - Replace ASCII non-printable chars in messages (>= and --) - Re-run checks after --fix and base exit code on post-fix state - Guard _fix_constitution(): skip if no project marker present - Catch OSError on constitution write; add cwd=project_path to upgrade-repo - Add 9 new tests: timeout, empty yaml, file-vs-dir edge cases, post-fix guard Signed-off-by: jpoley <jason.poley@gmail.com>

github-actions · 2026-05-23T10:03:32Z

🟢 Security Scan Results (Advisory)

Note: Security scanning is advisory and does not block PR merges.

Total Findings: 12
Critical: 0
High: 0

No critical or high severity issues found.

How to remediate

# View detailed scan results
gh run download 26330939343 -n security-scan-results-042d902db2bc4931460a15da96077d5e4910e938

# Triage findings with AI assistance
specify security triage

# Generate fix suggestions
specify security fix

# Apply fixes and re-scan
flowspec security scan

See the Security tab for detailed findings.

Copilot

Pull request overview

Adds a new flowspec doctor CLI subcommand to perform environment/setup health checks for flowspec projects and guide users toward fixes, while also adding/refreshing agent/operator guidance docs for contributors.

Changes:

Introduces flowspec doctor with 8 checks, Rich table output, and --fix support.
Adds a dedicated flowspec_cli.doctor module (checks + CLI runner) and comprehensive pytest coverage.
Updates project/operator documentation and configuration files (Copilot/Claude guidance, backlog config).

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`src/flowspec_cli/doctor/checks.py`	Implements the 8 health checks and result model.
`src/flowspec_cli/doctor/cli.py`	Renders results, summarizes status, and implements `--fix` behaviors + re-check.
`src/flowspec_cli/doctor/__init__.py`	Exposes doctor module public API.
`src/flowspec_cli/__init__.py`	Registers the `doctor` Typer command wrapper.
`tests/test_doctor.py`	Adds unit/integration tests for checks and the CLI command behavior.
`backlog/config.yml`	Adds `task_prefix` configuration.
`CLAUDE.md`	Reworks Claude Code configuration/docs content.
`AGENTS.md`	Adds an entry point doc for Codex/compatible agents.
`.github/copilot-instructions.md`	Adds repo-specific GitHub Copilot contribution/runtime rules.
`.claude/workflow.md`	Adds workflow + DoD guidance.
`.claude/stack.md`	Documents stack/tooling expectations.
`.claude/sourcecontrol.md`	Documents branch/commit/PR rules.
`.claude/settings.json`	Adjusts Claude tool permissions guardrails.
`.claude/plans/task-606-flowspec-doctor.md`	Adds the implementation plan for TASK-606.
`.claude/language.md`	Adds Python language/tooling conventions.
`.claude/history.md`	Adds decision logging guidance.
`.claude/architecture.md`	Adds architecture/module-structure guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+            try:
+                proc = subprocess.run(
+                    ["flowspec", "upgrade-repo"], check=False, cwd=project_path
+                )


+    minimal = (
+        "# Project Constitution\n\n"
+        "**Version**: 1.0.0\n"
+        "**Ratified**: (set date)\n\n"
+        "<!-- NEEDS_VALIDATION: Update with your project details -->\n\n"
+        "## Purpose\n\nDescribe the purpose of this project.\n"
+    )


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

jpoley

ok

jpoley and others added 4 commits May 23, 2026 09:17

Copilot AI review requested due to automatic review settings May 23, 2026 10:02

github-actions Bot added documentation Improvements or additions to documentation config github backlog source tests claude labels May 23, 2026

Copilot started reviewing on behalf of jpoley May 23, 2026 10:02 View session

Copilot AI reviewed May 23, 2026

View reviewed changes

Apply suggestions from code review

db451ac

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

jpoley commented May 23, 2026

View reviewed changes

jpoley merged commit d83a43f into main May 23, 2026
14 of 15 checks passed

jpoley deleted the galway/task-606/flowspec-doctor branch May 23, 2026 11:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add flowspec doctor health-check command (TASK-606)#1249

feat: add flowspec doctor health-check command (TASK-606)#1249
jpoley merged 5 commits into
mainfrom
galway/task-606/flowspec-doctor

jpoley commented May 23, 2026

Uh oh!

github-actions Bot commented May 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jpoley left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jpoley commented May 23, 2026

Summary

What was hardened post-review

Test plan

Uh oh!

github-actions Bot commented May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Security Scan Results (Advisory)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jpoley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented May 23, 2026 •

edited

Loading