ace-task 0.31.0

data/handbook/workflow-instructions/task/review.wf.md

@@ -0,0 +1,351 @@
+---
+name: task-review
+allowed-tools: Bash, Read
+description: Review draft tasks for readiness, vertical slice quality, verification
+  plans, and promotion to pending
+doc-type: workflow
+purpose: Review draft tasks for readiness and quality before promotion
+ace-docs:
+  last-updated: '2026-03-21'
+---
+
+# Review Task Workflow Instruction
+
+## Goal
+
+Validate draft behavioral specifications and promote to pending when ready. This workflow acts as the readiness gate between drafting and implementation. It reviews draft tasks for completeness, conducts autonomous research to resolve open questions, generates critical questions for unresolved items, and either promotes validated drafts to `status: pending` or blocks with `needs_review: true` when questions remain.
+
+## Prerequisites
+
+- Task file exists, primarily with `status: draft`
+- Understanding of task's current state and content structure
+- Write access to task files in `.ace-tasks/`
+- Access to project documentation and codebase for research
+
+## Project Context Loading
+
+- Read and follow: `ace-bundle wfi://bundle`
+
+## Process Steps
+
+1. **Load and Analyze Draft Task:**
+   - **Task Selection:**
+     - If specific task provided: Use the provided task path
+     - If no task specified: Run `ace-task list --status draft` to view draft tasks
+   - **Load Task Content:**
+     - Read the task file from the identified path
+     - Verify the task has `status: draft`
+     - Detect whether the task is an orchestrator with subtasks
+     - If the task is an orchestrator:
+       - Enumerate child subtasks and their current statuses before any promotion
+       - Treat every child subtask still in `draft` as an additional review target
+       - Review draft subtasks first and defer any parent promotion decision until child review outcomes are known
+     - Parse the behavioral specification sections:
+       - User Experience (input, process, output)
+       - Expected Behavior
+       - Interface Contract
+       - Success Criteria
+       - Validation Questions
+       - Vertical Slice Decomposition (Task/Subtask Model)
+       - Verification Plan
+       - Frontmatter `bundle` block (`presets`, `files`, `commands`)
+     - Identify gaps, ambiguities, or assumptions that need clarification
+
+2. **Autonomous Research Phase:**
+   - **Attempt Self-Resolution First:**
+     - Search project documentation for answers
+     - Analyze similar implementations in codebase
+     - Review related tasks and their solutions
+     - Check architectural decisions and patterns
+     - Consult technical documentation and best practices
+   - **Web Search When Appropriate:**
+     - If WebSearch tool is available and needed:
+       - Search for industry standards or best practices
+       - Research security implications or vulnerabilities
+       - Find performance benchmarks or comparisons
+       - Look up API documentation or integration guides
+     - Only search when internal resources insufficient
+     - Focus searches on specific technical questions
+   - **Document Research Findings:**
+     - Note what was discovered through research
+     - Record reasonable assumptions based on evidence
+     - Include sources from web searches if used
+     - Identify truly unresolvable questions
+
+3. **Critical Question Generation:**
+   - **Analyze for Completeness:**
+     - Identify missing information that would block implementation
+     - Find ambiguous requirements that could lead to wrong implementations
+     - Spot assumptions that need validation
+     - Detect edge cases not covered in current specification
+     - Check for comprehensive renaming scope:
+       - If task involves renaming, are all related files identified?
+       - Are library directories, test files, and imports considered?
+       - Have module/class names been addressed?
+   - **Filter Questions by Resolution Status:**
+     - Questions answered through research (document the answer)
+     - Questions with reasonable defaults (document assumption)
+     - Questions requiring human input (escalate only these)
+   - **Generate Clarifying Questions:**
+     - Only include questions that truly need human decision
+     - Frame questions to be answerable asynchronously
+     - Make questions specific and actionable
+     - Include research context and suggested defaults
+
+4. **Readiness Checklist:**
+   Evaluate the draft against these readiness criteria:
+
+   - [ ] **Behavioral Spec Complete**: User Experience section defines input, process, and output
+   - [ ] **Expected Behavior Defined**: Clear description of what the system should do
+   - [ ] **Interface Contracts Specified**: CLI/API/UI contracts with examples
+   - [ ] **Success Criteria Measurable**: Observable, testable outcomes defined
+   - [ ] **Scope Boundaries Clear**: In-scope and out-of-scope explicitly stated
+   - [ ] **Validation Questions Addressed**: All validation questions either answered or documented as blocking
+   - [ ] **Vertical Slice Quality (Task/Subtask)**: Scope is decomposed into end-to-end capability slices (standalone task or orchestrator+subtasks), not horizontal layer-only work
+   - [ ] **Subtask Slice Clarity**: Each subtask has a distinct observable outcome and does not duplicate sibling scope
+   - [ ] **Child Readiness Complete** (orchestrators only): Every draft child subtask has been reviewed and either promoted to `pending` or blocked with documented questions
+   - [ ] **Tracer-First for Uncertain Architecture**: For uncertain/novel execution paths, first subtask is a tracer slice validating viability
+   - [ ] **Slice Size Signal Present**: Each slice includes advisory size (`small|medium|large`) for planning visibility
+   - [ ] **Decision-Complete Spec**: Implementer can execute without inventing missing behavioral decisions
+   - [ ] **Defaults Declared**: Ambiguous/unspecified behavior has explicit defaults
+   - [ ] **Verification Plan Present**: Spec includes explicit verification plan with concrete scenarios and commands/checks
+   - [ ] **Verification Coverage**: Verification includes unit/equivalent checks, integration/E2E checks when needed, and at least one failure/invalid-path check
+   - [ ] **Success Criteria ↔ Verification Mapping**: Each success criterion has corresponding verification evidence path
+   - [ ] **Bundle Frontmatter Present**: Task frontmatter includes `bundle` with keys `presets`, `files`, `commands` in canonical order
+   - [ ] **Bundle Context Completeness**: `bundle.files` includes all critical context artifacts required for fresh-session execution
+   - [ ] **No Contradictory Directives**: Scan spec for conflicting instructions (e.g., "replace X" and "preserve X" for same entity; "add" and "remove" same dependency). Flag any contradictions as HIGH priority questions
+   - [ ] **Consumer Packages Listed**: When interfaces change (CLI flags, config keys, protocol URIs), spec identifies which packages consume the interface and will need updates
+   - [ ] **Deliverables Match Scope**: Number of deliverables is proportional to scope -- flag if spec lists 3 deliverables but scope implies 15+ file changes
+   - [ ] **Operating Modes Covered**: Spec addresses relevant operating modes (dry-run, force, verbose, quiet) or explicitly marks them out-of-scope
+   - [ ] **Degenerate Inputs Covered**: Spec considers identity operations (X=Y), empty inputs, and self-referential calls where the same entity appears in both argument positions
+   - [ ] **Per-Path Variations Covered**: If spec says "same behavior for X and Y", it enumerates edge cases unique to each path (guard logic, error handling, parameter differences)
+   - [ ] **End-State Coherence** (orchestrator subtasks only): Concepts introduced by this subtask
+         (new fields, modes, formats) are expected to exist in the final deliverable --
+         not be removed by a later subtask. If this subtask adds a concept that a later
+         subtask will consolidate away, flag as SCOPE RISK and consider merging subtasks.
+   - [ ] **Title Length**: Title is max 80 characters
+   - [ ] **Folder Slug**: 3-5 word context slug for folder
+   - [ ] **File Slug**: 4-7 word action slug for spec file
+   - [ ] **No Slug Repetition**: Subtask slugs do not repeat words from parent folder slug
+   - [ ] **Usage Documentation Present**: If task changes CLI/API/workflow/config interfaces, `ux/usage.md` exists with concrete usage scenarios
+   - [ ] **No Blocking Questions Remain**: All HIGH priority questions resolved or have acceptable defaults
+
+   **Assessment:**
+   - If ALL checklist items pass: Task is ready for promotion
+   - If ANY checklist item fails: Task needs work, document what's missing
+   - `large` slice signal alone is advisory and does not block promotion
+
+5. **Promote or Block:**
+
+   **If Ready (all readiness criteria met):**
+   - **Orchestrator rule:** If the task is an orchestrator, only promote the parent after all draft child subtasks have been reviewed and promoted successfully.
+   - **Recursive promotion for orchestrators:**
+     - Review each draft child subtask using the same checklist
+     - Promote each child subtask that passes:
+       ```bash
+       ace-task update <child-ref> --set status=pending
+       ace-task update <child-ref> --set needs_review=false
+       ```
+     - For any child subtask that fails, keep it in `draft`, set `needs_review=true`, and do not promote the parent
+   - Promote the task status and clear any existing `needs_review` flag:
+     ```bash
+     ace-task update <ref> --set status=pending
+     ace-task update <ref> --set needs_review=false
+     ```
+   - Report promotion:
+     ```
+     Task <ref> promoted from draft to pending.
+     Readiness: All behavioral specs validated, no blocking questions.
+     Ready for implementation via ace-assign.
+     ```
+   - **Orchestrator summary requirement:**
+     - Report how many child subtasks were reviewed
+     - Report how many child subtasks were promoted
+     - Report whether parent promotion was deferred due to any blocked child
+
+   **If Not Ready (blocking questions or gaps remain):**
+   - Add `needs_review: true` to task metadata (`ace-task update <ref> --set needs_review=true`)
+   - Keep status as `draft`
+   - Report blocking status:
+     ```
+     Task <ref> remains draft.
+     needs_review: true -- N HIGH priority questions require human input.
+     See Review Questions section in task file.
+     ```
+
+6. **Question Documentation and Persistence:**
+   - **Persist Questions in Task File:**
+     - Add questions directly to the task file (not just review output)
+     - Place in dedicated section for easy access and tracking
+     - Questions remain until explicitly answered and removed
+     - Enable independent review/answering sessions
+   - **Question Section Placement:**
+     - For draft tasks: After metadata, before main content
+   - **Question Format with Research Context:**
+     ```markdown
+     ---
+     id: task-001
+     status: draft
+     priority: high
+     needs_review: true
+     ---
+
+     ## Review Questions (Pending Human Input)
+
+     ### [HIGH] Critical Implementation Questions
+     - [ ] How should we handle user sessions that exceed 24 hours?
+       - **Research conducted**: Checked auth patterns in codebase
+       - **Similar implementations**: Found session extension in API module
+       - **Suggested default**: Auto-extend if active, expire if idle >2h
+       - **Why needs human input**: Business policy decision required
+
+     ### [MEDIUM] Enhancement Questions
+     - [ ] Should we log all session extensions for audit purposes?
+       - **Research conducted**: Current logging practices reviewed
+       - **Suggested default**: Log only anomalous extensions (>5 per day)
+       - **Why needs human input**: Compliance requirements unclear
+     ```
+
+7. **Review Completion and Summary:**
+   - **Generate Review Summary:**
+     - List all questions generated with priorities
+     - Highlight critical blockers that need answers
+     - Report readiness checklist results
+     - State whether task was promoted or blocked
+   - **Summary Format:**
+     ```markdown
+     ## Review Summary
+
+     **Readiness Checklist:** X/N criteria met
+     **Questions Generated:** X total (Y high, Z medium)
+     **Critical Blockers:** [List HIGH priority questions]
+     **Advisories:** [List non-blocking advisories such as large slice size]
+     **Decision:** Promoted to pending / Remains draft (needs_review: true)
+     **Recommended Next Steps:** Based on current state...
+     ```
+   - **Orchestrator runs should also include:**
+     - `Subtasks Reviewed: X`
+     - `Subtasks Promoted: Y`
+     - `Subtasks Blocked: Z`
+     - `Parent Decision: promoted / deferred`
+
+## Secondary Support: Non-Draft Statuses
+
+While review-task primarily serves as the draft-to-pending gate, it can provide lightweight review for other statuses:
+
+- **Pending tasks**: Validate implementation plan completeness, check for stale assumptions
+- **In-progress tasks**: Document progress, identify blockers, update remaining steps
+- **Completed tasks**: Add retrospective notes, identify follow-up tasks
+
+For non-draft tasks, skip the Readiness Checklist and Promote/Block steps. Focus on content enhancement and question generation only.
+
+## Decision Guidance
+
+### When to Use This Workflow
+
+**Use review-task when:**
+- Validating a draft task for promotion to pending
+- Refining draft specifications before implementation
+- Researching answers to open questions on draft tasks
+- Checking if a draft is implementation-ready
+
+**Don't use review-task when:**
+- Creating new tasks (use draft-task)
+- Planning implementation details (use plan-task via ace-assign)
+- Executing implementation (use work-on-task)
+- Converting ideas to tasks (use draft-task with idea input)
+
+## Success Criteria
+
+- Draft task validated against readiness checklist
+- Critical questions generated and documented with research context
+- Questions prioritized by implementation impact
+- Default assumptions provided for all questions
+- Vertical slice quality validated using task/subtask model
+- Verification Plan quality validated against success criteria
+- Bundle frontmatter (`presets`, `files`, `commands`) validated for completeness
+- Task promoted to pending if ready, or blocked with `needs_review: true`
+- Orchestrator parents are promoted only after draft child subtasks have also passed review
+- Structure and formatting preserved
+- No loss of existing information
+- Clear improvement in task clarity or completeness
+- User receives actionable list of questions to answer (if any)
+
+## Task Management Integration
+
+### Finding Tasks Needing Review
+
+```bash
+# List all draft tasks ready for review
+ace-task list --status draft
+
+# List all tasks requiring human input (using preset)
+ace-task list needs-review
+
+# Alternative: use ace-search to find tasks with needs_review flag
+cd .ace-tasks && ace-search "needs_review: true" --content
+```
+
+### Review Workflow Patterns
+
+1. **Draft Validation Session:**
+   - Run filter to find draft tasks
+   - Review behavioral spec completeness
+   - Promote ready tasks, block incomplete ones
+
+2. **Question Resolution Session:**
+   - Run filter to find tasks needing review
+   - Answer questions in batch
+   - Remove `needs_review` flag as questions are resolved
+   - Re-run review-task to promote
+
+3. **Continuous Improvement:**
+   - AI agents autonomously research first
+   - Only escalate true blockers
+   - Questions persist for asynchronous handling
+
+## Error Handling
+
+### Common Issues and Solutions
+
+**"Task not found" Error:**
+- **Cause**: Invalid task path or ID
+- **Solution**: Use `ace-task list` to find correct path
+
+**"Task is not draft" Warning:**
+- **Cause**: Task has a non-draft status
+- **Solution**: Review-task primarily targets draft tasks. For other statuses, use lightweight review mode (skip readiness checklist and promotion)
+
+**"Structure validation failed" Error:**
+- **Cause**: Breaking required task structure
+- **Solution**: Preserve original section organization
+
+## Integration with Other Workflows
+
+### Upstream Workflows
+- **capture-idea**: Ideas that become tasks may need review for clarity
+- **draft-task**: New drafts are the primary input for review-task
+
+### Downstream Workflows
+- **plan-task (via ace-assign)**: JIT implementation planning for promoted pending tasks
+- **work-on-task**: Reviewed and promoted tasks are clearer to implement
+
+## Key Value: Draft-to-Pending Readiness Gate
+
+The review-task workflow serves as the quality gate between specification and implementation:
+
+1. **Research-First Approach**: AI agents attempt to find answers through documentation, codebase analysis, and pattern recognition before escalating
+2. **Readiness Checklist**: Systematic validation ensures behavioral specs are complete before promotion
+3. **Smart Question Filtering**: Only truly unresolvable questions requiring business/design decisions are escalated
+4. **Persistent Question Tracking**: Questions are saved in task files with `needs_review: true` metadata for easy filtering
+5. **Clear Lifecycle Decision**: Every review results in either promotion to pending or documented blocking questions
+
+This approach enables:
+- **Clear Lifecycle Gate**: Draft tasks must pass validation before entering the implementation pipeline
+- **Efficient Human Time**: Humans only address true decision points
+- **Better Quality**: Research context leads to more informed decisions
+- **Task Management Integration**: Easy tracking of tasks needing attention
+
+---
+
+This workflow ensures draft tasks are validated and promoted to pending when ready, or blocked with clear questions when not, serving as the quality gate between behavioral specification and implementation planning.

data/handbook/workflow-instructions/task/update.wf.md

@@ -0,0 +1,118 @@
+---
+name: task-update
+description: Update task metadata, status, position, or location
+allowed-tools: Bash, Read
+argument-hint: "<ref> [--set K=V] [--move-to FOLDER] [--move-as-child-of PARENT|none]
+  [--position first|after:<ref>]"
+doc-type: workflow
+purpose: Update task fields, change status, move between folders, and manage hierarchy
+ace-docs:
+  last-updated: '2026-03-21'
+  last-checked: '2026-03-21'
+---
+
+# Update Task
+
+## Goal
+
+Provide a single canonical workflow for task updates, including status changes, metadata edits, and hierarchy movement operations, including promote/demote flows.
+
+## Prerequisites
+
+- A valid task reference (`<ref>`) for the target task/subtask
+- Target folder or parent references for moves (when provided)
+- Permissions to modify task files in the active repository context
+
+## Project Context Loading
+
+Load and follow:
+
+- `ace-bundle wfi://bundle`
+
+## Process Steps
+
+1. **Choose the update intent**
+
+   - Metadata updates (status, priority, tags, dependencies, notes)
+   - Lifecycle transitions (backlog/archive/done flows via `--set status=...`)
+   - Reparenting / hierarchy movement
+   - Sort order changes
+
+2. **Apply metadata updates**
+
+   Use focused `--set` operations:
+
+   ```bash
+   ace-task update <ref> --set status=in-progress
+   ace-task update <ref> --set status=done
+   ace-task update <ref> --set status=done,priority=high
+   ace-task update <ref> --add tags=shipped
+   ace-task update <ref> --remove tags=wip
+   ```
+
+3. **Apply hierarchy updates via `--move-as-child-of`**
+
+   - Promote a subtask to standalone
+
+   ```bash
+   ace-task update <ref> --move-as-child-of none
+   ace-task update <ref> --move-as-child-of none --dry-run
+   ```
+
+   - Demote a task to be a child of a parent orchestrator
+
+   ```bash
+   ace-task update <ref> --move-as-child-of <parent-ref>
+   ace-task update <ref> --move-as-child-of <parent-ref> --dry-run
+   ```
+
+   - Convert/restructure to parent-child shape when the command supports direct self-parenting in your CLI version
+
+   ```bash
+   ace-task update <ref> --move-as-child-of self
+   ```
+
+4. **Adjust sort position**
+
+   ```bash
+   ace-task update <ref> --position first
+   ace-task update <ref> --position after:<other-ref>
+   ```
+
+5. **Handle folder/location moves**
+
+   ```bash
+   ace-task update <ref> --move-to archive
+   ace-task update <ref> --move-to backlog
+   ```
+
+6. **Validate results immediately**
+
+   - Re-open target task: `ace-task show <ref>`
+   - Confirm metadata, location, parent/child relationship, and position
+   - Verify dry-run output before executing non-idempotent moves
+
+## Error Handling
+
+### Missing or invalid target reference
+
+- Symptom: command returns unresolved reference or file-not-found error
+- Fix: verify ref format and current ref status with `ace-task show` or `ace-task finder`
+
+### Invalid move target
+
+- Symptom: reparent command fails for non-orchestrator parent or circular relationship
+- Fix: confirm the target parent is the intended hierarchy node and re-run with valid `--move-as-child-of` value
+
+### Command-level validation failures
+
+- Symptom: argument parsing errors or rejected flags
+- Fix: rerun with a narrower set of flags and add one change at a time
+
+## Success Criteria
+
+- Target task is updated with expected status/metadata changes
+- Reparenting operations produce the intended hierarchy state
+- Sort position changes place the task at the requested location
+- Location moves place the task in the intended folder/release
+- Final `ace-task show <ref>` output matches expected target state

data/handbook/workflow-instructions/task/work.wf.md

@@ -0,0 +1,106 @@
+---
+name: task-work
+description: Execute task implementation against behavioral spec using pre-loaded
+  plan
+assign:
+  sub-steps:
+  - onboard-base
+  - task-load
+  - plan-task
+  - work-on-task
+  - pre-commit-review
+  - verify-test
+  - release-minor
+  - create-retro
+  context: fork
+doc-type: workflow
+purpose: Execute task implementation from plan with quality gates
+ace-docs:
+  last-updated: '2026-03-21'
+---
+
+# Work on Task
+
+## Start State
+
+You have context sources already loaded from prior sub-steps:
+- **Project** (`project-base`) — vision, architecture, CLI tools, conventions, and repo-level onboarding context
+- **Task** (`ace-bundle task://<ref>`) — behavioral spec, success criteria, interface contract
+- **Plan** (`ace-task plan <ref> --content`) — implementation checklist with steps, file paths, verification commands
+- **Pre-commit review** runs after implementation and before verification when enabled
+- **Verification** runs in-tree per-package only via `verify-test` before subtree release; no full suite is executed at this level
+
+If the plan is missing or stale: run `ace-task plan <ref> --content` and wait before proceeding.
+
+### Plan Retrieval Guard
+
+To avoid known `--content` stalls in some environments:
+1. Prefer `ace-task plan <ref>` first and read the returned plan path.
+2. Use `ace-task plan <ref> --content` only when inline output is explicitly required.
+3. If `--content` shows no progress after about 3 minutes, stop it and fall back to:
+   - `ace-task plan <ref>` (path mode, reuse cached plan when available)
+   - The most recent plan artifact plus current task spec, documented in the step report
+4. If stalls repeat, add a follow-up fix task and capture evidence in the retrospective.
+
+## Primary Directive
+
+Work through the plan checklist, step by step:
+1. Mark task in-progress: `ace-task update <ref> --set status=in-progress`
+2. For each plan step: implement → verify → commit → mark corresponding task checkbox done
+   - Plan steps include `path:line` anchors to spec sections — when satisfied, mark the corresponding Success Criteria or Deliverables checkbox as `[x]`
+3. Mark task done: `ace-task update <ref> --set status=done`
+
+## Principles
+
+**Spec adherence:**
+- Success Criteria are acceptance tests — every criterion must pass before done
+- Interface Contract defines inputs, outputs, and boundaries — don't invent outside it
+- If the spec says X, implement X — don't gold-plate, don't simplify away requirements
+- If spec and plan conflict, spec wins — the plan is a HOW, not a WHAT
+- If the spec is ambiguous or incomplete: stop and ask, don't assume
+
+**Prior implementation awareness:**
+- Before creating new modules, search for existing implementations of the same concern — especially spike or prototype code from prior subtasks
+- If a sibling task (same parent, earlier sequence) produced spike code: refactor and promote it rather than creating parallel "production" versions
+- Check dependency task reports and the task folder for prior work artifacts (concept inventories, spike reports)
+- When plan file paths point to locations where code already exists, integrate rather than duplicate
+
+**Execution discipline:**
+- Commit incrementally — one logical step per commit, use `ace-git-commit`
+- Test after every change — run `ace-test`; don't accumulate untested code
+- If a test fails: fix it before moving to the next step
+- If a test failure is undiagnosable after one attempt: stop and report
+
+**Task lifecycle:**
+- `draft` status: warn the user that the spec hasn't been reviewed, then continue only with explicit confirmation. In unattended/fork contexts where interactive confirmation is not possible, proceed after marking in-progress — the assignment creation layer is responsible for blocking draft tasks before they reach this point.
+- Mark in-progress before first change, done after last verification
+- Never modify task frontmatter directly — use `ace-task update <ref> --set key=value`
+
+## Code Conventions
+
+- Follow established project patterns — don't introduce new abstractions or styles
+- 2-space indentation (Ruby); keep lines under 120 characters
+- Write tests for all new logic; run `ace-test` before committing
+
+## Task Folder
+
+**Documents:** Task-specific docs (reports, findings, usage docs) go in the task folder — never in the project root.
+
+**Codemods** (scripts that transform files): create in `{task-folder}/codemods/`, never in `bin/`
+
+**Temporary files**: create in the system temp directory (`/tmp/`), never in the project root or task folder
+
+## Done
+
+All plan steps checked, all success criteria pass:
+
+1. **Verify working tree is clean** — no uncommitted changes:
+   ```bash
+   git status --short
+   ```
+   If dirty, commit remaining changes with `ace-git-commit` before proceeding.
+
+2. Mark task done:
+   ```bash
+   ace-task update <ref> --set status=done
+   ```

data/lib/ace/task/atoms/task_file_pattern.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Ace
+  module Task
+    module Atoms
+      # Glob patterns and matching logic for task spec files.
+      # Tasks use `.s.md` extension but exclude `.idea.s.md` (ideas).
+      # Subtask files are distinguished from primary files by their ID suffix.
+      module TaskFilePattern
+        # Pattern matching all spec files
+        SPEC_PATTERN = "*.s.md"
+
+        # Pattern to exclude idea spec files
+        IDEA_PATTERN = "*.idea.s.md"
+
+        # Subtask ID pattern: parent ID + dot + single char (e.g., "8pp.t.q7w.a")
+        SUBTASK_ID_REGEX = /^([0-9a-z]{3}\.[a-z]\.[0-9a-z]{3})\.([a-z0-9])$/
+
+        # Check if a spec file is the primary file for its containing folder.
+        # The primary file's ID prefix matches the folder's ID prefix exactly.
+        # Subtask files have an additional `.{char}` suffix.
+        #
+        # @param filename [String] Spec filename (e.g., "8pp.t.q7w-fix-login.s.md")
+        # @param folder_id [String] ID extracted from folder name (e.g., "8pp.t.q7w")
+        # @return [Boolean]
+        def self.primary_file?(filename, folder_id)
+          return false if filename.end_with?(".idea.s.md")
+
+          # Extract ID from filename: "8pp.t.q7w-fix-login.s.md" → "8pp.t.q7w"
+          # or subtask: "8pp.t.q7w.a-setup-db.s.md" → "8pp.t.q7w.a"
+          file_id = extract_id_from_filename(filename)
+          return false unless file_id
+
+          file_id == folder_id
+        end
+
+        # Check if a spec file is a subtask file.
+        #
+        # @param filename [String] Spec filename
+        # @return [Boolean]
+        def self.subtask_file?(filename)
+          return false if filename.end_with?(".idea.s.md")
+
+          file_id = extract_id_from_filename(filename)
+          return false unless file_id
+
+          file_id.match?(SUBTASK_ID_REGEX)
+        end
+
+        # Extract the task ID from a spec filename.
+        # "8pp.t.q7w-fix-login.s.md" → "8pp.t.q7w"
+        # "8pp.t.q7w.a-setup-db.s.md" → "8pp.t.q7w.a"
+        #
+        # @param filename [String] Spec filename
+        # @return [String, nil] Extracted ID or nil
+        def self.extract_id_from_filename(filename)
+          # Remove .s.md extension
+          base = filename.sub(/\.s\.md$/, "")
+          return nil if base == filename # No .s.md extension
+
+          # Match task ID at start: "8pp.t.q7w" or "8pp.t.q7w.a"
+          match = base.match(/^([0-9a-z]{3}\.[a-z]\.[0-9a-z]{3}(?:\.[a-z0-9])?)/)
+          match&.[](1)
+        end
+      end
+    end
+  end
+end