Bug Fixes & Feature Enhancements: PRD Validation Robustness, Rollback Safety, and YAML Frontmatter support

[vtnguyen04]

I have conducted a comprehensive review of the prd-taskmaster codebase (focusing on script.py, templates, and environment setups) and identified several bugs, edge cases, and design improvement opportunities.

Here is a detailed breakdown of the issues found and how they can be addressed:

1. Heading Parsing Substring Collisions

• Problem: The heading extractor in script.py (get_section_content()) uses simple substring matching (heading.lower() in heading_match.group(2).lower()). This leads to collisions, e.g., querying for "Functional Requirements" will accidentally match "Non-Functional Requirements" if it appears first in the file.
• Fix: Update the extractor to perform clean, exact matching first, and fallback to substring matching with explicit guards (e.g. preventing "functional requirements" from matching "non-functional").

2. Vague Language False Positives

• Problem: The validation check for vague words (like secure, safe, easy) is run on the entire raw text including code blocks. This results in false positives inside code configuration examples (e.g. matching secure: true in a config block).
• Fix: Clean markdown fenced and inline code blocks using re.sub before performing vague language scans.

3. Rigid Acceptance Criteria Check

• Problem: Check 5 splits user stories strictly on ### Story \d+. If stories are named differently (e.g. ### Story: User Login or ### User Story 1), the checks fail silently. Additionally, it only detects checkbox lists (- [ ]), so standard bulleted list points fail criteria validation.
• Fix: Split story blocks on level 3 headers within the User Stories section and count any standard bulleted or checkbox lists as criteria items.

4. Always-Passing Checks 11 & 12

• Problem: Global checks for "task breakdown" or "dependency" match text in the template TOC, headers, and comments, causing these checks to pass even if the user has deleted the actual content.
• Fix: Clean TOC links from the document before scanning, and utilize more specific requirement-to-requirement mapping patterns for checks.

5. Rollback Tag & Safety Discrepancies

• Problem: Commit tags are written as checkpoint-task-{task_id} (e.g., checkpoint-task-5), but rollback.sh strictly queries checkpoint-task-$(printf '%03d' "$TASK_NUM") (checkpoint-task-005), causing rollback execution to fail. Additionally, rollback.sh does a hard reset discard on dirty work trees without saving uncommitted local code changes.
• Fix: Update rollback.sh to check for both unpadded and padded tags, and perform a git stash to preserve local changes before resetting.

6. Granular .gitignore Checks

• Problem: setup-taskmaster.sh checks for .taskmaster/state.json and skips all other gitignore setups if found. It also fails to exclude the .taskmaster/state/ folder which stores time-tracking logs.
• Fix: Make exclusions check and append granularly for each file/folder individually, and add .taskmaster/state/ to ignored patterns.

7. YAML Frontmatter Support (Feature Suggestion)

• Enhancement: Adding a machine-readable YAML frontmatter block at the top of PRD templates would optimize them for AI agents, allowing them to programmatically parse task estimations, priority scales, and dependencies with 100% precision.

---

I have already created a local fork and implemented all the fixes detailed above on a feature branch (feat/validation-and-rollback-fixes). Let me know if you would like me to submit a Pull Request to address these issues!