Master Plans CLI next-stage guidance command

Problem

Agents working on task files have no automated way to know which narrative sections are incomplete or what to write next. They either skip sections entirely, write shallow placeholder content, or fill sections out of order — leading to inconsistent task records that are hard to review. The plans CLI has no content-completeness inspection, so the only quality check happens at PR review time when it's expensive to send the agent back. A lightweight advisory command that reports section completeness and prints stage-specific guidance would give agents (and human operators) a fast self-check without requiring a full workflow engine.

Context

The plans CLI (tasks/tools/task_cli.py) manages task lifecycle via plans task create|update|validate|.... Tasks use a narrative template with sections: Problem, Context, Possible Solutions, Plan, Implementation Progress, Review Feedback. The existing task validate command checks frontmatter only — there's no content-completeness check for the body sections.

Key files: - tasks/tools/task_cli.py — CLI implementation, task template body (lines 286-314) - tests/core/test_task_cli.py — test suite for the CLI - tasks/frontmatter.py — extract_frontmatter() utility

The task template already defines 6 narrative sections with HTML comment placeholders. _is_section_substantive() needs to distinguish real content from these placeholders.

Possible Solutions

Option A: Full workflow stepper — Build plans task next-stage with exit hooks, session tracking, and stage gates (like AgentTree's agenttree next). ~1000+ lines of workflow engine. Rejected: maintenance burden far exceeds the gain; the bottleneck is section quality, not section skipping.

Option B (Recommended): Advisory plans task check command — Add a lightweight check command that parses sections, reports completeness, and prints guidance for the next incomplete section. ~50 lines of core logic. Relies on existing review/CI gates for enforcement. Gives 90% of the "what should I do next?" value without the state-machine overhead.

Option C: Template-only improvement — Just enrich the task template with better placeholder text. No CLI command. Simpler but gives no runtime feedback to agents.

Plan

1. Define SECTION_GUIDANCE dict mapping each narrative section header to prompt/done_when guidance
2. Add _extract_sections() to parse markdown body into section header -> content map
3. Add _is_section_substantive() to detect real content vs placeholders (HTML comments, blank lines, checkbox-only lines)
4. Implement task_check() that walks sections in canonical order, reports filled/empty status, identifies next incomplete section, prints guidance, and exits 1 if incomplete
5. Wire check subcommand into argparse under task
6. Write tests covering: all-filled (exit 0), empty sections (exit 1 + next guidance), missing file, checkbox-only detection, parser routing

Implementation Progress

Added to tasks/tools/task_cli.py: - SECTION_GUIDANCE dict with prompt/done_when for all 6 narrative sections - _COMMENT_RE and _CHECKBOX_ONLY_RE patterns for placeholder detection - _is_section_substantive(text) — returns True if text has any non-blank, non-comment, non-checkbox-only lines - _extract_sections(body) — parses markdown body into {header: content} dict - task_check(args) — resolves path, extracts sections, walks canonical order, prints [+]/[-] report, prints guidance for next incomplete section, exits 0 (all complete) or 1 (incomplete) - Wired task check --path <file> subcommand into build_parser()

Added 6 tests in tests/core/test_task_cli.py: - test_task_check_all_filled_exits_zero — all substantive sections pass - test_task_check_empty_section_exits_nonzero — placeholder-only sections detected - test_task_check_reports_next_section_guidance — correct next section identified - test_task_check_missing_file_exits — nonexistent path handled - test_task_check_checkbox_only_not_substantive — checkbox-only lines not counted as content - test_parser_routes_task_check — argparse routing verified

All 66 tests pass.

Review Feedback

• [ ] Review cleared