flight-rules 0.13.7 → 0.13.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flight-rules",
-  "version": "0.13.7",
+  "version": "0.13.8",
   "description": "An opinionated framework for AI-assisted software development",
   "type": "module",
   "main": "dist/index.js",

package/payload/AGENTS.md

@@ -1,6 +1,6 @@
 # Flight Rules – Agent Guidelines
 
-flight_rules_version: 0.13.7
+flight_rules_version: 0.13.8
 
 This file defines how agents (Claude Code, Cursor, etc.) should work on software projects using the Flight Rules system.
 

package/payload/commands/impl.validate.md

@@ -0,0 +1,258 @@
+# Validate Implementation
+
+When the user invokes "impl.validate", audit completed tasks to verify that code actually matches what the implementation specs claim.
+
+Adopt the persona of a meticulous QA engineer who trusts specs as the source of truth and systematically verifies that completed work delivers what was promised.
+
+## 1. Check Prerequisites
+
+### Required: Implementation Structure Must Exist
+
+Check if `docs/implementation/overview.md` exists with defined areas. If not:
+
+> "I couldn't find implementation documentation at `docs/implementation/`. There's nothing to validate yet."
+
+Stop and wait for the user's response.
+
+## 2. Determine Scope
+
+Check if the user specified a scope with the command:
+- `/impl.validate` → Ask what scope they want
+- `/impl.validate 2-cli-core` → Validate that area
+- `/impl.validate 2.1` → Validate that task group
+- `/impl.validate 2.1.3` → Validate that specific task
+
+If no argument provided, analyze the implementation structure to identify areas with completed tasks:
+
+> **Implementation Areas with Completed Tasks:**
+>
+> [List areas and count of completed tasks in each]
+>
+> Which would you like to validate? You can specify:
+> - An area (e.g., `2-cli-core`)
+> - A task group (e.g., `2.1`)
+> - A specific task (e.g., `2.1.3`)
+> - `all` to validate everything
+
+Wait for the user to specify the scope.
+
+## 3. Gather Context
+
+Read the relevant implementation specs based on scope:
+
+### For Area Scope
+
+- Read `docs/implementation/{N}-{area}/index.md`
+- Read all task group files in the area
+- Build a list of all tasks marked ✅ Complete
+
+### For Task Group Scope
+
+- Read `docs/implementation/{N}-{area}/{N}.{M}-topic.md`
+- Build a list of all tasks marked ✅ Complete
+
+### For Task Scope
+
+- Read the specific task from its task group file
+- Verify it's marked ✅ Complete (if not, nothing to validate)
+
+Also read:
+- `docs/prd.md` for context on goals and constraints
+- `docs/tech-stack.md` if it exists, for understanding the codebase
+
+## 4. Validate Each Completed Task
+
+For each task marked ✅ Complete, perform these checks:
+
+### 4.1 File/Code Existence
+
+- Identify files or code mentioned in the task's Approach or Acceptance Criteria
+- Verify those files actually exist
+- Check that referenced functions, classes, or modules are present
+
+### 4.2 Implementation Match
+
+- Read the relevant code files
+- Compare implementation against what the spec describes
+- Check that the approach was followed (or document if a different approach was taken)
+
+### 4.3 Acceptance Criteria Verification
+
+For each acceptance criterion:
+- Determine how to verify it (code inspection, test existence, behavior check)
+- Verify the criterion is met
+- Document evidence of verification or failure
+
+### 4.4 Categorize Results
+
+For each task, categorize as:
+- **Verified** — All acceptance criteria met, implementation matches spec
+- **Partial** — Some criteria met, others missing or incomplete
+- **Mismatched** — Implementation exists but differs from spec
+- **Missing** — Code/files referenced don't exist
+
+## 5. Report Findings
+
+Present findings organized by task:
+
+> **Implementation Validation Report**
+>
+> **Scope:** [Area/Task Group/Task validated]
+> **Date:** [Current date]
+>
+> ---
+>
+> ## Summary
+>
+> | Status | Count |
+> |--------|-------|
+> | Verified | [N] |
+> | Partial | [N] |
+> | Mismatched | [N] |
+> | Missing | [N] |
+>
+> ---
+>
+> ## Verified Tasks
+>
+> - [N].[M].[X] [Task Name] — All criteria met
+>
+> ---
+>
+> ## Tasks with Discrepancies
+>
+> ### [N].[M].[Y] [Task Name]
+>
+> **Status:** [Partial/Mismatched/Missing]
+>
+> **Claimed:** [What the spec says was implemented]
+>
+> **Actual:** [What you found in the code]
+>
+> **Discrepancy:** [Specific gap or conflict]
+>
+> **Files examined:**
+> - [List of files checked]
+>
+> **Acceptance Criteria:**
+> - [Criterion 1]: ✅ Met / ❌ Not met — [Evidence]
+> - [Criterion 2]: ✅ Met / ❌ Not met — [Evidence]
+>
+> ---
+>
+> [Repeat for each task with issues]
+
+If all tasks are verified:
+
+> **All [N] completed tasks verified successfully.**
+>
+> No discrepancies found. The implementation matches the specs.
+
+## 6. Handle Discrepancies
+
+If discrepancies were found, ask how to proceed:
+
+> **[N] tasks have discrepancies.**
+>
+> Would you like me to:
+> 1. **Create discrepancy file** — Document issues in `docs/implementation/{area}/{N}.{M}-discrepancies.md`
+> 2. **Update task statuses** — Mark affected tasks as 🟡 In Progress for re-implementation
+> 3. **Both** — Create file and update statuses
+> 4. **Neither** — Just report, don't change anything
+
+Wait for the user's response.
+
+### 6.1 Create Discrepancy File
+
+If requested, create `docs/implementation/{N}-{area}/{N}.{M}-discrepancies.md`:
+
+```markdown
+# [Task Group Name] - Validation Discrepancies
+
+Validation date: [date]
+
+## [Task ID]: [Task Name]
+
+**Status:** [Partial/Mismatched/Missing]
+
+**Claimed:** [What the spec says was implemented]
+
+**Actual:** [What you found in the code]
+
+**Discrepancy:** [Specific gap or conflict]
+
+**Files examined:**
+- [List of files checked]
+
+**Acceptance Criteria:**
+- [Criterion]: [Met/Not met] — [Evidence]
+
+---
+
+[Repeat for each task with issues]
+```
+
+### 6.2 Update Task Statuses
+
+If requested, for each task with discrepancies:
+
+1. Update the task status in the task group file:
+   - Change `**Status**: ✅ Complete` to `**Status**: 🟡 In Progress`
+   - Add a note: `**Note**: Validation discrepancy found — see [{N}.{M}-discrepancies.md](./{N}.{M}-discrepancies.md)`
+
+2. Update `docs/progress.md` with an entry:
+   ```markdown
+   ### [Date] - Implementation Validation
+
+   - Validated [scope]
+   - Found [N] discrepancies
+   - Tasks marked for re-implementation: [list task IDs]
+   - See: `docs/implementation/{area}/{N}.{M}-discrepancies.md`
+   ```
+
+## 7. Context Management for Large Scopes
+
+When validating an entire area with multiple task groups:
+
+After completing each task group, output:
+
+> **Task Group [N].[M] Validation Complete**
+> - Tasks verified: [count]
+> - Discrepancies found: [count]
+> - Tasks needing re-implementation: [list or "none"]
+>
+> Ready to proceed to next task group. Continue?
+
+This allows context to be cleared between task groups if needed.
+
+## 8. Final Summary
+
+After all validation is complete:
+
+> **Validation Complete**
+>
+> **Scope validated:** [Area/Task Group/Task]
+>
+> **Results:**
+> - [N] tasks verified successfully
+> - [N] tasks with discrepancies
+>
+> **Actions taken:**
+> - [Created discrepancy file at X / Updated N task statuses / None]
+>
+> **Next steps:**
+> - Fix discrepancies and re-run `/impl.validate` to verify
+> - Run `/dev-session.start` to work on tasks marked for re-implementation
+
+## Key Behaviors
+
+Throughout this command, maintain these behaviors:
+
+- **Specs are source of truth** — You're checking if code matches specs, not the other way around
+- **Be thorough** — Check every acceptance criterion, not just the obvious ones
+- **Show evidence** — Every verification or failure should cite specific code or files
+- **Don't assume** — If you can't verify something, say so rather than guessing
+- **Preserve audit trail** — Discrepancy files create accountability
+- **One scope at a time** — For large validations, pause between task groups
+- **Flag uncertainty** — If a criterion is ambiguous and hard to verify, note that
+- **Respect existing discrepancy files** — Append to existing files rather than overwriting