{ "meta": { "version": "1.0.0", "lastUpdated": "2025-11-26T06:27:26.161Z" }, "workUnits": { "EXMAP-001": { "id": "EXMAP-001", "title": "Redesign Example Mapping to match BDD technique", "status": "done", "createdAt": "2025-10-10T22:58:36.526Z", "updatedAt": "2025-10-10T23:20:00.252Z", "description": "Current implementation is wrong - operates on work units instead of stories. Need to redesign to follow 4-card system (yellow story, blue rules, green examples, red questions) that happens BEFORE writing feature files. Example Mapping should help discover what scenarios to write, not modify existing ones.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-10T22:58:42.985Z" }, { "state": "testing", "timestamp": "2025-10-10T23:05:16.853Z" }, { "state": "implementing", "timestamp": "2025-10-10T23:19:16.805Z" }, { "state": "validating", "timestamp": "2025-10-10T23:19:26.991Z" }, { "state": "done", "timestamp": "2025-10-10T23:20:00.252Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "INIT-001": { "id": "INIT-001", "title": "Add ensureWorkUnitsFile to ALL 48+ commands", "status": "done", "createdAt": "2025-10-10T23:23:00.738Z", "updatedAt": "2025-10-10T23:30:22.581Z", "description": "Following EXMAP-001 pattern, add ensureWorkUnitsFile/ensurePrefixesFile/ensureEpicsFile utilities to ALL commands that read JSON files. This prevents ENOENT errors and improves first-time user experience.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-10T23:23:13.046Z" }, { "state": "testing", "timestamp": "2025-10-10T23:24:25.195Z" }, { "state": "implementing", "timestamp": "2025-10-10T23:30:08.298Z" }, { "state": "validating", "timestamp": "2025-10-10T23:30:09.868Z" }, { "state": "done", "timestamp": "2025-10-10T23:30:22.581Z" } ], "rules": [ { "id": 0, "text": "ALL commands that read spec/work-units.json MUST use ensureWorkUnitsFile", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" }, { "id": 1, "text": "ALL commands that read spec/prefixes.json MUST use ensurePrefixesFile", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" }, { "id": 2, "text": "ALL commands that read spec/epics.json MUST use ensureEpicsFile", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" }, { "id": 3, "text": "Ensure utilities MUST be idempotent - safe to call multiple times", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" }, { "id": 4, "text": "NO command should fail with ENOENT errors when JSON files missing", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" } ], "examples": [ { "id": 0, "text": "Create epic command auto-creates spec/epics.json when missing", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" }, { "id": 1, "text": "Create prefix command auto-creates spec/prefixes.json when missing", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" }, { "id": 2, "text": "List work units command auto-creates spec/work-units.json when missing", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" }, { "id": 3, "text": "Update work unit command uses ensureWorkUnitsFile instead of direct readFile", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" }, { "id": 4, "text": "Calling ensureWorkUnitsFile multiple times returns same data without overwriting", "deleted": false, "createdAt": "2025-10-10T23:23:00.738Z" } ], "questions": [], "assumptions": [ "No - tags.json and foundation.json already auto-create via register-tag and add-diagram commands" ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-001": { "id": "CLI-001", "title": "Verify all CLI commands and help system complete", "status": "done", "createdAt": "2025-10-10T23:34:14.426Z", "updatedAt": "2025-10-11T02:09:46.737Z", "description": "VERIFIED: 84 commands registered, help system comprehensive and accurate, all validation checks passing", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T02:09:01.564Z" }, { "state": "testing", "timestamp": "2025-10-11T02:09:45.913Z" }, { "state": "implementing", "timestamp": "2025-10-11T02:09:46.189Z" }, { "state": "validating", "timestamp": "2025-10-11T02:09:46.463Z" }, { "state": "done", "timestamp": "2025-10-11T02:09:46.737Z" } ], "rules": [ { "id": 0, "text": "ALL 84 commands MUST be registered in src/index.ts with proper CLI bindings", "deleted": false, "createdAt": "2025-10-10T23:34:14.426Z" }, { "id": 1, "text": "MUST have comprehensive help text for each command", "deleted": false, "createdAt": "2025-10-10T23:34:14.426Z" }, { "id": 2, "text": "MUST pass all validation checks (build, validate, validate-tags)", "deleted": false, "createdAt": "2025-10-10T23:34:14.426Z" } ], "examples": [ { "id": 0, "text": "All commands registered and accessible", "deleted": false, "createdAt": "2025-10-10T23:34:14.426Z" }, { "id": 1, "text": "Help system shows all commands", "deleted": false, "createdAt": "2025-10-10T23:34:14.426Z" }, { "id": 2, "text": "Build succeeds with no errors", "deleted": false, "createdAt": "2025-10-10T23:34:14.426Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "DEP-001": { "id": "DEP-001", "title": "Work Unit Dependency Management", "status": "done", "createdAt": "2025-10-10T23:39:22.582Z", "updatedAt": "2025-10-10T23:47:00.473Z", "description": "Implement dependency tracking between work units including add-dependency, remove-dependency, and dependency validation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-10T23:39:38.913Z" }, { "state": "testing", "timestamp": "2025-10-10T23:42:11.831Z" }, { "state": "implementing", "timestamp": "2025-10-10T23:46:12.749Z" }, { "state": "validating", "timestamp": "2025-10-10T23:46:19.691Z" }, { "state": "done", "timestamp": "2025-10-10T23:47:00.473Z" } ], "rules": [ { "id": 0, "text": "MUST maintain bidirectional consistency (if A blocks B, then B blockedBy A)", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" }, { "id": 1, "text": "MUST detect circular dependencies before creating relationships", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" }, { "id": 2, "text": "MUST prevent deletion of work units that block other work", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" }, { "id": 3, "text": "MUST auto-transition to blocked state when blockedBy work exists", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" }, { "id": 4, "text": "Work units can have 4 relationship types: blocks, blockedBy, dependsOn, relatesTo", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" } ], "examples": [ { "id": 0, "text": "Add blocks relationship creates bidirectional link", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" }, { "id": 1, "text": "Remove dependency cleans up both sides of relationship", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" }, { "id": 2, "text": "Circular dependency detection prevents A→B→A loops", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" }, { "id": 3, "text": "Adding blockedBy dependency auto-sets work unit to blocked state", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" }, { "id": 4, "text": "Query dependency stats shows metrics across all work units", "deleted": false, "createdAt": "2025-10-10T23:39:22.582Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "EST-001": { "id": "EST-001", "title": "Work Unit Estimation and Metrics", "status": "done", "createdAt": "2025-10-10T23:39:24.324Z", "updatedAt": "2025-10-10T23:51:10.655Z", "description": "Implement estimation and metrics tracking including assign estimates, record tokens, calculate cycle time", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-10T23:47:18.974Z" }, { "state": "testing", "timestamp": "2025-10-10T23:48:44.204Z" }, { "state": "implementing", "timestamp": "2025-10-10T23:51:10.109Z" }, { "state": "validating", "timestamp": "2025-10-10T23:51:10.383Z" }, { "state": "done", "timestamp": "2025-10-10T23:51:10.655Z" } ], "rules": [ { "id": 0, "text": "MUST support Fibonacci story points (1,2,3,5,8,13,21) for estimation", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" }, { "id": 1, "text": "MUST track AI-specific metrics: actualTokens and iterations", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" }, { "id": 2, "text": "MUST calculate cycle time from stateHistory timestamps", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" }, { "id": 3, "text": "MUST compare estimate vs actual to provide accuracy feedback", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" }, { "id": 4, "text": "MUST provide pattern-based estimation recommendations", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" } ], "examples": [ { "id": 0, "text": "Update work unit with 5-point estimate", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" }, { "id": 1, "text": "Record 45k tokens consumed", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" }, { "id": 2, "text": "Increment iteration count", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" }, { "id": 3, "text": "Query estimate accuracy for work unit", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" }, { "id": 4, "text": "Get estimation guide with patterns", "deleted": false, "createdAt": "2025-10-10T23:39:24.324Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "QRY-001": { "id": "QRY-001", "title": "Work Unit Query and Reporting", "status": "done", "createdAt": "2025-10-10T23:39:26.221Z", "updatedAt": "2025-10-10T23:52:11.901Z", "description": "Implement query and reporting features including compound queries, statistical reports, and data export", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-10T23:51:24.531Z" }, { "state": "testing", "timestamp": "2025-10-10T23:52:11.067Z" }, { "state": "implementing", "timestamp": "2025-10-10T23:52:11.346Z" }, { "state": "validating", "timestamp": "2025-10-10T23:52:11.624Z" }, { "state": "done", "timestamp": "2025-10-10T23:52:11.901Z" } ], "rules": [ { "id": 0, "text": "MUST support compound queries combining multiple filters (status, prefix, epic, tags)", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" }, { "id": 1, "text": "MUST export query results to JSON, CSV, or Markdown formats", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" }, { "id": 2, "text": "MUST generate statistical summary reports across work units", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" }, { "id": 3, "text": "MUST support sorting and pagination for large result sets", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" }, { "id": 4, "text": "MUST provide machine-readable output for CI/CD integration", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" } ], "examples": [ { "id": 0, "text": "Query by status and prefix", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" }, { "id": 1, "text": "Export work units to JSON", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" }, { "id": 2, "text": "Generate summary report with statistics", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" }, { "id": 3, "text": "Query with sorting by updated date", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" }, { "id": 4, "text": "Export filtered results to CSV", "deleted": false, "createdAt": "2025-10-10T23:39:26.221Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "SPEC-001": { "id": "SPEC-001", "title": "Complete placeholder scenarios with proper Given/When/Then", "status": "done", "createdAt": "2025-10-11T02:11:53.337Z", "updatedAt": "2025-10-11T02:18:27.489Z", "description": "Fill in 24 placeholder scenarios across 6 feature files with concrete Given/When/Then steps", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T02:12:07.366Z" }, { "state": "testing", "timestamp": "2025-10-11T02:13:37.952Z" }, { "state": "implementing", "timestamp": "2025-10-11T02:18:26.932Z" }, { "state": "validating", "timestamp": "2025-10-11T02:18:27.212Z" }, { "state": "done", "timestamp": "2025-10-11T02:18:27.489Z" } ], "rules": [ { "id": 0, "text": "Each placeholder scenario MUST have concrete Given/When/Then steps", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 1, "text": "Steps MUST be specific and testable (no vague descriptions)", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 2, "text": "Scenarios MUST align with their example mapping source", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 3, "text": "All scenarios MUST follow Gherkin best practices", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 4, "text": "Completed scenarios MUST pass validation", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" } ], "examples": [ { "id": 0, "text": "Fill INIT-001 scenarios (5 scenarios)", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 1, "text": "Fill DEP-001 scenarios (5 scenarios)", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 2, "text": "Fill EST-001 scenarios (5 scenarios)", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 3, "text": "Fill QRY-001 scenarios (5 scenarios)", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 4, "text": "Fill CLI-001 scenarios (3 scenarios)", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" }, { "id": 5, "text": "Fill add-scenario scenarios (1 scenario)", "deleted": false, "createdAt": "2025-10-11T02:11:53.337Z" } ], "nextRuleId": 5, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "FEAT-001": { "id": "FEAT-001", "title": "Implement add-scenario and add-step commands", "status": "done", "createdAt": "2025-10-11T02:26:06.358Z", "updatedAt": "2025-10-11T02:34:00.512Z", "description": "Complete implementation of add-scenario and add-step commands for modifying feature files programmatically (phase3)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T02:26:56.216Z" }, { "state": "testing", "timestamp": "2025-10-11T02:28:39.953Z" }, { "state": "implementing", "timestamp": "2025-10-11T02:33:59.946Z" }, { "state": "validating", "timestamp": "2025-10-11T02:34:00.227Z" }, { "state": "done", "timestamp": "2025-10-11T02:34:00.512Z" } ], "rules": [ { "id": 0, "text": "MUST parse existing feature file without corrupting content", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" }, { "id": 1, "text": "MUST maintain proper Gherkin formatting and indentation", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" }, { "id": 2, "text": "MUST validate scenario/step syntax before adding", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" }, { "id": 3, "text": "MUST preserve existing tags and metadata", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" }, { "id": 4, "text": "MUST support adding to any position (append, prepend, after scenario)", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" } ], "examples": [ { "id": 0, "text": "Add scenario to feature file", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" }, { "id": 1, "text": "Add Given step to scenario", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" }, { "id": 2, "text": "Add When step to scenario", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" }, { "id": 3, "text": "Add Then step to scenario", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" }, { "id": 4, "text": "Add scenario with tags", "deleted": false, "createdAt": "2025-10-11T02:26:06.358Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "FEAT-002": { "id": "FEAT-002", "title": "Implement delete-scenario command", "status": "done", "createdAt": "2025-10-11T02:37:12.464Z", "updatedAt": "2025-10-11T02:43:37.355Z", "description": "Complete implementation of delete-scenario command for removing scenarios from feature files (phase4)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T02:37:48.826Z" }, { "state": "testing", "timestamp": "2025-10-11T02:40:58.673Z" }, { "state": "implementing", "timestamp": "2025-10-11T02:43:36.723Z" }, { "state": "validating", "timestamp": "2025-10-11T02:43:37.047Z" }, { "state": "done", "timestamp": "2025-10-11T02:43:37.355Z" } ], "rules": [ { "id": 0, "text": "MUST safely delete scenario without corrupting file", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" }, { "id": 1, "text": "MUST preserve other scenarios and structure", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" }, { "id": 2, "text": "MUST support deletion by scenario name or index", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" }, { "id": 3, "text": "MUST handle scenario tags properly during deletion", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" }, { "id": 4, "text": "MUST provide confirmation before deleting", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" } ], "examples": [ { "id": 0, "text": "Delete scenario by name", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" }, { "id": 1, "text": "Delete scenario by index", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" }, { "id": 2, "text": "Delete multiple scenarios by tag", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" }, { "id": 3, "text": "Confirm before deletion", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" }, { "id": 4, "text": "Preserve remaining scenarios intact", "deleted": false, "createdAt": "2025-10-11T02:37:12.464Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "FEAT-003": { "id": "FEAT-003", "title": "Implement scenario querying and filtering", "status": "done", "createdAt": "2025-10-11T02:37:12.740Z", "updatedAt": "2025-10-11T02:47:04.736Z", "description": "Implement get-scenarios and show-acceptance-criteria commands for querying scenarios by tag (phase4)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T02:43:45.616Z" }, { "state": "testing", "timestamp": "2025-10-11T02:44:45.290Z" }, { "state": "implementing", "timestamp": "2025-10-11T02:47:04.171Z" }, { "state": "validating", "timestamp": "2025-10-11T02:47:04.451Z" }, { "state": "done", "timestamp": "2025-10-11T02:47:04.736Z" } ], "rules": [ { "id": 0, "text": "MUST support querying scenarios by single or multiple tags", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" }, { "id": 1, "text": "MUST output scenario list with metadata (feature, tags, steps)", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" }, { "id": 2, "text": "MUST support JSON and plain text output formats", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" }, { "id": 3, "text": "MUST handle AND/OR logic for multiple tags", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" }, { "id": 4, "text": "MUST show acceptance criteria in readable format", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" } ], "examples": [ { "id": 0, "text": "Get scenarios by single tag", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" }, { "id": 1, "text": "Get scenarios by multiple tags (AND logic)", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" }, { "id": 2, "text": "Show acceptance criteria for tag", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" }, { "id": 3, "text": "Output scenarios as JSON", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" }, { "id": 4, "text": "Query with tag matching pattern", "deleted": false, "createdAt": "2025-10-11T02:37:12.740Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "FEAT-004": { "id": "FEAT-004", "title": "Implement bulk operations (delete-by-tag, retag)", "status": "done", "createdAt": "2025-10-11T02:49:30.896Z", "updatedAt": "2025-10-11T02:57:58.944Z", "description": "Implement bulk delete features/scenarios by tag and bulk retag operations (phase5 high priority)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T02:50:54.242Z" }, { "state": "testing", "timestamp": "2025-10-11T02:52:40.455Z" }, { "state": "implementing", "timestamp": "2025-10-11T02:57:58.367Z" }, { "state": "validating", "timestamp": "2025-10-11T02:57:58.656Z" }, { "state": "done", "timestamp": "2025-10-11T02:57:58.944Z" } ], "rules": [ { "id": 0, "text": "MUST support bulk deletion across multiple files", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" }, { "id": 1, "text": "MUST preview changes before executing bulk operations", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" }, { "id": 2, "text": "MUST handle tag renaming with bidirectional updates", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" }, { "id": 3, "text": "MUST preserve file structure during bulk operations", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" }, { "id": 4, "text": "MUST provide detailed summary of changes made", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" } ], "examples": [ { "id": 0, "text": "Delete all scenarios with @deprecated tag", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" }, { "id": 1, "text": "Delete feature files tagged @phase1", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" }, { "id": 2, "text": "Rename tag from @old-tag to @new-tag", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" }, { "id": 3, "text": "Preview bulk delete before confirmation", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" }, { "id": 4, "text": "Show summary of bulk changes", "deleted": false, "createdAt": "2025-10-11T02:49:30.896Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "FEAT-005": { "id": "FEAT-005", "title": "Implement update operations (scenario, step)", "status": "done", "createdAt": "2025-10-11T02:49:31.178Z", "updatedAt": "2025-10-11T03:01:38.306Z", "description": "Implement update-scenario and update-step commands for modifying existing content (phase5)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T02:58:07.304Z" }, { "state": "testing", "timestamp": "2025-10-11T03:00:04.811Z" }, { "state": "implementing", "timestamp": "2025-10-11T03:01:27.456Z" }, { "state": "validating", "timestamp": "2025-10-11T03:01:32.883Z" }, { "state": "done", "timestamp": "2025-10-11T03:01:38.306Z" } ], "rules": [ { "id": 0, "text": "MUST support updating scenario name/title", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" }, { "id": 1, "text": "MUST support updating step text", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" }, { "id": 2, "text": "MUST preserve tags and metadata during updates", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" }, { "id": 3, "text": "MUST validate new content before applying", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" }, { "id": 4, "text": "MUST maintain proper Gherkin syntax", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" } ], "examples": [ { "id": 0, "text": "Update scenario name", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" }, { "id": 1, "text": "Update Given step text", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" }, { "id": 2, "text": "Update When step text", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" }, { "id": 3, "text": "Update Then step text", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" }, { "id": 4, "text": "Update step preserving position", "deleted": false, "createdAt": "2025-10-11T02:49:31.178Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "INIT-002": { "id": "INIT-002", "title": "Add ensureFoundationFile and ensureTagsFile with proper auto-initialization", "status": "done", "createdAt": "2025-10-11T03:55:06.491Z", "updatedAt": "2025-10-11T04:29:23.795Z", "description": "Add ensureFoundationFile() and ensureTagsFile() functions to src/utils/ensure-files.ts and update ALL commands that read foundation.json or tags.json to use these functions instead of manual file checks", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T03:55:27.686Z" }, { "state": "testing", "timestamp": "2025-10-11T04:00:53.724Z", "reason": "Feature file tagged with @INIT-002, ready to write tests" }, { "state": "implementing", "timestamp": "2025-10-11T04:12:03.024Z", "reason": "Tests written, ready to implement ensureFoundationFile and ensureTagsFile" }, { "state": "validating", "timestamp": "2025-10-11T04:25:49.608Z", "reason": "All commands updated to use ensure functions, tests passing" }, { "state": "done", "timestamp": "2025-10-11T04:29:23.795Z", "reason": "Implementation complete: ensureFoundationFile() and ensureTagsFile() added, all commands updated, all tests passing" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-001": { "id": "BOARD-001", "title": "Implement board command with Ink + React visualization", "status": "done", "createdAt": "2025-10-11T04:32:31.325Z", "updatedAt": "2025-10-11T05:18:44.997Z", "description": "Create a Kanban board visualization using Ink + React that displays all work units across 7 workflow states. The board command replaces the old display-board implementation with a responsive terminal UI following React patterns.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-11T04:32:38.196Z", "reason": "Analyzing feature file scenarios and current broken implementation" }, { "state": "testing", "timestamp": "2025-10-11T04:43:24.069Z", "reason": "Example mapping complete, design agreed: box-drawing columns, 3-item limit, BLOCKED highlighted, all columns shown" }, { "state": "implementing", "timestamp": "2025-10-11T04:44:20.798Z", "reason": "Tests written and passing for data structure, now implementing visual output" }, { "state": "validating", "timestamp": "2025-10-11T05:11:08.352Z", "reason": "Implementation complete: BoardDisplay component using Ink + React, architecture docs updated, component follows React patterns with useStdout, ready for validation" }, { "state": "done", "timestamp": "2025-10-11T05:13:08.776Z", "reason": "Implementation validated: board command displays Kanban board correctly using Ink + React, all tests pass, follows React patterns, architecture docs updated, no issues found" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "SAFE-001": { "id": "SAFE-001", "title": "Prevent spec directory creation outside project root", "status": "done", "createdAt": "2025-10-12T03:27:57.082Z", "updatedAt": "2025-10-12T04:47:39.305Z", "description": "Add validation to check if current directory is within project root before creating spec directories", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T03:28:04.689Z" }, { "state": "testing", "timestamp": "2025-10-12T04:43:22.902Z" }, { "state": "implementing", "timestamp": "2025-10-12T04:45:14.668Z" }, { "state": "validating", "timestamp": "2025-10-12T04:47:23.341Z" }, { "state": "done", "timestamp": "2025-10-12T04:47:39.306Z" } ], "rules": [ { "id": 0, "text": "Project root is determined by finding a spec/ directory, but search must stop at a project boundary marker (.git, package.json, etc.)", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 1, "text": "Search algorithm walks upward from cwd, stopping at project boundary markers: .git, package.json, .gitignore, Cargo.toml, pyproject.toml", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 2, "text": "If spec/ directory exists within project boundary, use that directory as project root", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 3, "text": "If no spec/ directory found within project boundary, create spec/ at the project boundary location (not cwd)", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 4, "text": "If no project boundary marker found after searching to filesystem root, create spec/ in current working directory", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 5, "text": "Stop at first boundary marker found when searching upward (closest to cwd)", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 6, "text": "All spec directory creation must go through a centralized utility function that performs project root detection", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 7, "text": "Search upward with a maximum limit (e.g., 10 directories) to prevent excessive traversal", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 8, "text": "On permission errors or filesystem issues, gracefully fall back to creating spec/ in current working directory", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 9, "text": "Centralized utility should automatically create spec/ directory and return the spec path (not project root)", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 10, "text": "Defer testing refactored callers until core utility is complete. Critical: Do not break existing functionality - ensure backward compatibility so all current tests continue passing. Architecture must support both old and new code paths during transition.", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" } ], "examples": [ { "id": 0, "text": "User at /project/src/commands/, .git at /project/, no spec/ exists → create /project/spec/", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 1, "text": "User at /project/src/commands/, .git at /project/, spec/ exists at /project/spec/ → use /project/spec/", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 2, "text": "User at /tmp/random/, no boundary markers found → create /tmp/random/spec/", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 3, "text": "Monorepo: /monorepo/.git and /monorepo/packages/app/package.json, user at /monorepo/packages/app/src/ → use /monorepo/packages/app/ as root", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 4, "text": "User at /very/deep/nested/path/a/b/c/d/e/f/g/h/i/j/k/, no boundary within 10 dirs → create spec/ at cwd", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" }, { "id": 5, "text": "User at /project/src/, permission denied reading parent dirs → create spec/ at /project/src/", "deleted": false, "createdAt": "2025-10-12T03:27:57.082Z" } ], "questions": [], "assumptions": [ "Need to verify existing ensure-files.ts functions work with new project root detection - may need to refactor callers to use returned spec path instead of manually constructing it" ], "nextRuleId": 11, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-002": { "id": "CLI-002", "title": "Fix missing list-prefixes CLI command registration", "status": "done", "createdAt": "2025-10-12T03:48:03.694Z", "updatedAt": "2025-10-12T03:53:56.776Z", "description": "The list-prefixes command is documented in help but not registered in the CLI", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T03:48:12.204Z" }, { "state": "testing", "timestamp": "2025-10-12T03:50:18.426Z" }, { "state": "implementing", "timestamp": "2025-10-12T03:51:37.431Z" }, { "state": "validating", "timestamp": "2025-10-12T03:52:38.137Z" }, { "state": "done", "timestamp": "2025-10-12T03:53:56.776Z" } ], "questions": [], "rules": [ { "id": 0, "text": "Yes, consistent with list-epics behavior", "deleted": false, "createdAt": "2025-10-12T03:48:03.694Z" }, { "id": 1, "text": "Yes, output format should match list-epics for consistency", "deleted": false, "createdAt": "2025-10-12T03:48:03.694Z" }, { "id": 2, "text": "Yes, return empty list with yellow message if no prefixes.json exists", "deleted": false, "createdAt": "2025-10-12T03:48:03.694Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec list-prefixes' and sees all registered prefixes with their descriptions", "deleted": false, "createdAt": "2025-10-12T03:48:03.694Z" }, { "id": 1, "text": "User runs 'fspec list-prefixes' and sees work unit counts for each prefix (e.g., 'SAFE: 1/1 (100%)')", "deleted": false, "createdAt": "2025-10-12T03:48:03.694Z" }, { "id": 2, "text": "User runs 'fspec list-prefixes' when no prefixes.json exists, sees 'No prefixes found' in yellow", "deleted": false, "createdAt": "2025-10-12T03:48:03.694Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "DOC-001": { "id": "DOC-001", "title": "Add story point estimation guidance", "status": "done", "createdAt": "2025-10-12T05:13:30.172Z", "updatedAt": "2025-10-12T06:58:58.773Z", "description": "Add story point estimation guidelines to /fspec command including Fibonacci scale, estimation prompts, and best practices", "children": [], "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T06:57:57.344Z" }, { "state": "testing", "timestamp": "2025-10-12T06:58:57.916Z" }, { "state": "implementing", "timestamp": "2025-10-12T06:58:58.206Z" }, { "state": "validating", "timestamp": "2025-10-12T06:58:58.489Z" }, { "state": "done", "timestamp": "2025-10-12T06:58:58.773Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "REMIND-001": { "id": "REMIND-001", "title": "Implement system-reminder pattern", "status": "done", "createdAt": "2025-10-12T05:13:30.451Z", "updatedAt": "2025-10-12T05:29:04.618Z", "description": "Add system-reminder wrapper functions and trigger points to prevent AI drift during long conversations", "children": [], "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T05:17:36.967Z" }, { "state": "testing", "timestamp": "2025-10-12T05:20:47.043Z" }, { "state": "implementing", "timestamp": "2025-10-12T05:21:53.587Z" }, { "state": "validating", "timestamp": "2025-10-12T05:23:54.695Z" }, { "state": "implementing", "timestamp": "2025-10-12T05:24:11.995Z" }, { "state": "validating", "timestamp": "2025-10-12T05:24:29.001Z" }, { "state": "implementing", "timestamp": "2025-10-12T05:25:59.299Z" }, { "state": "validating", "timestamp": "2025-10-12T05:26:23.102Z" }, { "state": "implementing", "timestamp": "2025-10-12T05:26:44.204Z" }, { "state": "validating", "timestamp": "2025-10-12T05:27:04.588Z" }, { "state": "implementing", "timestamp": "2025-10-12T05:27:37.721Z" }, { "state": "validating", "timestamp": "2025-10-12T05:27:52.779Z" }, { "state": "done", "timestamp": "2025-10-12T05:29:04.618Z" } ], "rules": [ { "id": 0, "text": "System reminders must be wrapped in tags", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" }, { "id": 1, "text": "Reminders must be invisible to users but visible to Claude", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" }, { "id": 2, "text": "Reminders should only be injected after specific command executions", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" }, { "id": 3, "text": "Each reminder must be context-specific to the command executed", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" }, { "id": 4, "text": "Reminders must be conditional and context-aware - only show when relevant to the current situation", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" }, { "id": 5, "text": "Reminders should be appended AFTER main command output", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" } ], "examples": [ { "id": 0, "text": "After 'fspec update-work-unit-status UI-001 testing', output includes reminder: 'Write FAILING tests BEFORE any implementation code'", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" }, { "id": 1, "text": "After 'fspec update-work-unit-status UI-001 implementing', output includes reminder: 'Write ONLY enough code to make tests pass'", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" }, { "id": 2, "text": "After 'fspec update-work-unit-estimate UI-001' without an estimate value, output includes reminder: 'Use Fibonacci scale (1,2,3,5,8,13)'", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" }, { "id": 3, "text": "After 'fspec list-work-units --status=backlog' returns empty, output includes reminder: 'Consider creating new work units or checking priorities'", "deleted": false, "createdAt": "2025-10-12T05:13:30.451Z" } ], "questions": [], "nextRuleId": 6, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "TEST-002": { "id": "TEST-002", "title": "Test system reminders", "status": "done", "createdAt": "2025-10-12T05:24:45.522Z", "updatedAt": "2025-10-12T06:57:17.505Z", "description": "Testing if system reminders work correctly", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T05:24:53.211Z" }, { "state": "testing", "timestamp": "2025-10-12T06:56:43.819Z" }, { "state": "implementing", "timestamp": "2025-10-12T06:56:44.107Z" }, { "state": "validating", "timestamp": "2025-10-12T06:56:44.393Z" }, { "state": "done", "timestamp": "2025-10-12T06:57:17.505Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-003": { "id": "CLI-003", "title": "Initialize fspec slash command in Claude Code project", "status": "done", "createdAt": "2025-10-12T05:41:20.177Z", "updatedAt": "2025-10-12T06:53:58.304Z", "description": "Add 'fspec init' command that installs the /fspec slash command into a Claude Code project by creating/using .claude/commands/ directory and copying fspec.md command file. Should be idempotent and safe to run multiple times.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T05:42:05.997Z" }, { "state": "testing", "timestamp": "2025-10-12T05:54:31.892Z" }, { "state": "implementing", "timestamp": "2025-10-12T06:51:49.181Z" }, { "state": "validating", "timestamp": "2025-10-12T06:52:51.675Z" }, { "state": "done", "timestamp": "2025-10-12T06:53:58.304Z" } ], "rules": [ { "id": 0, "text": "Command must prompt user to choose: Claude Code or custom location", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 1, "text": "If Claude Code selected, install to .claude/commands/fspec.md automatically", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 2, "text": "If custom location selected, prompt for full file path where to save", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 3, "text": "Template must be generic and reusable across any project (not fspec-specific examples)", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 4, "text": "Success means file exists at specified location after command completes", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 5, "text": "Create parent directories if they don't exist", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 6, "text": "If target file exists, prompt for confirmation before overwriting", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 7, "text": "Template references fspec commands but uses generic project placeholders (not fspec-specific examples)", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 8, "text": "Use ink/react for interactive prompts (consistent with existing board UI)", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 9, "text": "Command works from any directory, installs relative to current working directory", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 10, "text": "Template uses same structure as .claude/commands/fspec.md but with generic project placeholders", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 11, "text": "If user cancels overwrite, display 'Installation cancelled' and exit with success (0)", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 12, "text": "Custom path must be relative to current directory (same or subdirectory, not parent or absolute)", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 13, "text": "On success, display both confirmation message and next steps for usage", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 14, "text": "On error (permission denied, disk full, etc), display error message and exit with non-zero code", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 15, "text": "Use example-project style (lowercase example placeholders)", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 16, "text": "Include all sections from current fspec.md (complete template with all ACDD workflow, example mapping, estimation, etc)", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 17, "text": "Allow: ./file.md, file.md, subdir/file.md, subdir/nested/file.md. Reject: ../file.md, /absolute/path, ~/home/path", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec init' in project root, selects Claude Code, file created at ./claude/commands/fspec.md", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 1, "text": "User runs 'fspec init', selects custom location, enters 'docs/ai/fspec.md', file created at ./docs/ai/fspec.md", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 2, "text": "User runs 'fspec init' when .claude/commands/fspec.md exists, prompted to confirm overwrite, user confirms, file is overwritten", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 3, "text": "User runs 'fspec init', selects custom location, enters 'some/deep/path/fspec.md', parent directories created automatically", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 4, "text": "User runs 'fspec init', selects custom location, enters '../parent/fspec.md', validation fails with error about path being outside current directory", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 5, "text": "User runs 'fspec init' when .claude/commands/fspec.md exists, declines overwrite, command exits with 'Installation cancelled'", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" }, { "id": 6, "text": "User runs 'fspec init', selects Claude Code, command succeeds, displays '✓ Installed /fspec command to .claude/commands/fspec.md' and 'Run /fspec in Claude Code to activate'", "deleted": false, "createdAt": "2025-10-12T05:41:20.177Z" } ], "questions": [], "estimate": 5, "nextRuleId": 18, "nextExampleId": 7, "nextQuestionId": 0, "nextNoteId": 0 }, "TEST-003": { "id": "TEST-003", "title": "Test answer-question with multiple questions", "status": "done", "createdAt": "2025-10-12T05:57:24.220Z", "updatedAt": "2025-10-12T06:57:49.173Z", "description": "Testing that answering multiple questions works correctly with proper index handling", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T05:57:25.745Z" }, { "state": "testing", "timestamp": "2025-10-12T06:57:48.309Z" }, { "state": "implementing", "timestamp": "2025-10-12T06:57:48.599Z" }, { "state": "validating", "timestamp": "2025-10-12T06:57:48.887Z" }, { "state": "done", "timestamp": "2025-10-12T06:57:49.173Z" } ], "questions": [], "rules": [ { "id": 0, "text": "Use option A for consistency", "deleted": false, "createdAt": "2025-10-12T05:57:24.220Z" }, { "id": 1, "text": "Edge case X should return error code 400", "deleted": false, "createdAt": "2025-10-12T05:57:24.220Z" }, { "id": 2, "text": "Not in phase 1, defer to backlog", "deleted": false, "createdAt": "2025-10-12T05:57:24.220Z" } ], "nextRuleId": 3, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "SAFE-002": { "id": "SAFE-002", "title": "Fix race condition in answer-question when run concurrently", "status": "done", "createdAt": "2025-10-12T06:01:08.064Z", "updatedAt": "2025-10-12T06:33:27.231Z", "description": "Add file locking or transaction mechanism to prevent race conditions when multiple answer-question commands run in parallel. Currently parallel executions can overwrite each other's changes causing data loss.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T06:01:09.809Z" }, { "state": "testing", "timestamp": "2025-10-12T06:07:32.863Z" }, { "state": "implementing", "timestamp": "2025-10-12T06:09:49.140Z" }, { "state": "validating", "timestamp": "2025-10-12T06:32:14.013Z" }, { "state": "done", "timestamp": "2025-10-12T06:33:27.232Z" } ], "rules": [ { "id": 0, "text": "Multiple concurrent writes to work-units.json must not corrupt data", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 1, "text": "When multiple answer-question commands run in parallel, all answers must be saved", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 2, "text": "Last write must not overwrite changes from earlier writes", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 3, "text": "Solution must work across platforms (macOS, Linux, Windows)", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 4, "text": "Question indices must remain stable even after questions are answered", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 5, "text": "YES - Use stable indices with 'selected' flag. Change questions from string array to object array: [{text: 'question', selected: false}, ...]. When answered, mark as selected:true and add answer field. This eliminates race condition without needing file locks.", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 6, "text": "Questions use 'selected' property to indicate if answered, not 'answered' property", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" } ], "examples": [ { "id": 0, "text": "User runs 3 answer-question commands in parallel, all 3 questions are answered and all 3 rules are added", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 1, "text": "User runs answer-question while another command modifies work-units.json, both changes are preserved", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 2, "text": "User adds 3 questions (indices 0,1,2), answers question 1, indices remain 0,1,2 but question 1 is marked as answered", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" }, { "id": 3, "text": "Question object structure: {text: '@human: Should we...?', selected: false} becomes {text: '@human: Should we...?', selected: true, answer: 'Yes because...'} when answered", "deleted": false, "createdAt": "2025-10-12T06:01:08.064Z" } ], "questions": [], "assumptions": [ "Not needed - stable indices approach eliminates race condition without file locking", "Not needed - stable indices approach can be used for all commands, but answer-question is the priority", "Not applicable - no lock acquisition with stable indices approach" ], "estimate": 3, "nextRuleId": 7, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-004": { "id": "CLI-004", "title": "Wire up init command to CLI program", "status": "done", "createdAt": "2025-10-12T07:09:52.763Z", "updatedAt": "2025-10-12T07:21:43.421Z", "children": [], "description": "The init command implementation exists in src/commands/init.ts but is NOT registered in src/index.ts. This means users cannot run 'fspec init'. Need to: 1) Register command in CLI, 2) Add to help system, 3) Update feature files with complete acceptance criteria, 4) Ensure tests cover end-to-end CLI invocation (not just unit tests), 5) Validate command actually works via CLI before marking done.", "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T07:10:05.831Z" }, { "state": "testing", "timestamp": "2025-10-12T07:12:12.711Z" }, { "state": "testing", "timestamp": "2025-10-12T07:20:18.251Z" }, { "state": "implementing", "timestamp": "2025-10-12T07:20:25.581Z" }, { "state": "validating", "timestamp": "2025-10-12T07:21:20.272Z" }, { "state": "done", "timestamp": "2025-10-12T07:21:43.421Z" } ], "rules": [ { "id": 0, "text": "Command must be registered in src/index.ts with .command('init')", "deleted": false, "createdAt": "2025-10-12T07:09:52.763Z" }, { "id": 1, "text": "Command must support interactive prompts using ink/react (option --type and --path flags)", "deleted": false, "createdAt": "2025-10-12T07:09:52.763Z" }, { "id": 2, "text": "Command must appear in 'fspec --help' output and 'fspec help setup' section", "deleted": false, "createdAt": "2025-10-12T07:09:52.763Z" }, { "id": 3, "text": "E2E tests must verify 'fspec init' actually works via CLI, not just unit tests of the function", "deleted": false, "createdAt": "2025-10-12T07:09:52.763Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec init' prompts for installation type (Claude Code or Custom)", "deleted": false, "createdAt": "2025-10-12T07:09:52.763Z" }, { "id": 1, "text": "Running 'fspec init --type=claude-code' installs to .claude/commands/fspec.md", "deleted": false, "createdAt": "2025-10-12T07:09:52.763Z" }, { "id": 2, "text": "Running 'fspec --help' shows init command in output", "deleted": false, "createdAt": "2025-10-12T07:09:52.763Z" } ], "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-001": { "id": "BUG-001", "title": "Scenario-level tagging rejects work unit tags", "status": "done", "createdAt": "2025-10-12T07:13:53.468Z", "updatedAt": "2025-10-12T07:17:29.244Z", "description": "add-tag-to-scenario command rejects work unit tags like @CLI-004 even though add-tag-to-feature accepts them. The scenario tagging uses /^@[a-z0-9-#]+$/ regex while feature tagging uses isWorkUnitTag() helper. Need to make scenario tagging use the same work unit tag validation as feature tagging.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T07:13:56.954Z" }, { "state": "testing", "timestamp": "2025-10-12T07:14:51.941Z" }, { "state": "implementing", "timestamp": "2025-10-12T07:15:26.562Z" }, { "state": "validating", "timestamp": "2025-10-12T07:15:58.002Z" }, { "state": "done", "timestamp": "2025-10-12T07:17:29.245Z" } ], "rules": [ { "id": 0, "text": "add-tag-to-scenario MUST use isWorkUnitTag() helper for validation, same as add-tag-to-feature", "deleted": false, "createdAt": "2025-10-12T07:13:53.468Z" }, { "id": 1, "text": "Work unit tags (@PREFIX-NNN format) MUST be accepted at both feature and scenario level", "deleted": false, "createdAt": "2025-10-12T07:13:53.468Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec add-tag-to-scenario file.feature \"Scenario\" @CLI-004' should succeed", "deleted": false, "createdAt": "2025-10-12T07:13:53.468Z" }, { "id": 1, "text": "Work unit tags like @AUTH-001, @BUG-001, @CLI-004 should be accepted", "deleted": false, "createdAt": "2025-10-12T07:13:53.468Z" } ], "nextRuleId": 2, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-002": { "id": "BUG-002", "title": "generate-scenarios displays 'undefined' instead of count", "status": "done", "createdAt": "2025-10-12T07:14:42.738Z", "updatedAt": "2025-10-12T07:19:58.352Z", "description": "When running 'fspec generate-scenarios ', the success message shows 'Generated undefined scenarios' instead of showing the actual count of scenarios generated. The command should display 'Generated N scenarios' where N is the number of scenarios created.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T07:18:37.948Z" }, { "state": "testing", "timestamp": "2025-10-12T07:18:52.782Z" }, { "state": "implementing", "timestamp": "2025-10-12T07:19:19.951Z" }, { "state": "validating", "timestamp": "2025-10-12T07:19:35.465Z" }, { "state": "done", "timestamp": "2025-10-12T07:19:58.353Z" } ], "rules": [ { "id": 0, "text": "generate-scenarios command MUST return the count of scenarios generated", "deleted": false, "createdAt": "2025-10-12T07:14:42.738Z" }, { "id": 1, "text": "Success message MUST display 'Generated N scenarios' where N is the actual count", "deleted": false, "createdAt": "2025-10-12T07:14:42.738Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec generate-scenarios WORK-001' should display 'Generated 3 scenarios' not 'Generated undefined scenarios'", "deleted": false, "createdAt": "2025-10-12T07:14:42.738Z" } ], "nextRuleId": 2, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "INIT-003": { "id": "INIT-003", "title": "Copy CLAUDE.md template to new spec directory", "status": "done", "createdAt": "2025-10-12T07:58:21.443Z", "updatedAt": "2025-10-12T08:20:05.866Z", "description": "When fspec init creates a new spec/ directory, it should copy the spec/CLAUDE.md file (bundled with the package) to the target project. This ensures new projects have the complete specification guidelines and workflow documentation from the start. The file is bundled from spec/CLAUDE.md to dist/spec/CLAUDE.md during build - no separate templates/ directory needed.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T07:58:34.774Z" }, { "state": "testing", "timestamp": "2025-10-12T08:05:45.263Z" }, { "state": "implementing", "timestamp": "2025-10-12T08:06:40.200Z" }, { "state": "validating", "timestamp": "2025-10-12T08:09:35.216Z" }, { "state": "done", "timestamp": "2025-10-12T08:10:49.918Z" } ], "rules": [ { "id": 0, "text": "CLAUDE.md template must be bundled with fspec package in a templates/ directory", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 1, "text": "CLAUDE.md file must be identical across all projects (no customization)", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 2, "text": "If spec/CLAUDE.md already exists, overwrite it with the latest template", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 3, "text": "fspec init command must set up complete spec directory structure with CLAUDE.md and /fspec slash command", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 4, "text": "Always overwrite - no version checking needed", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 5, "text": "Show confirmation message in /fspec slash command output (fspec.md), no separate message from fspec init CLI", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 6, "text": "Enhance existing 'fspec init' command to copy CLAUDE.md template", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec init' in empty directory, creates spec/ directory with CLAUDE.md and .claude/commands/fspec.md", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 1, "text": "User runs 'fspec init' in directory with existing spec/CLAUDE.md, overwrites with latest template", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 2, "text": "CLAUDE.md template is copied from fspec package's templates/CLAUDE.md to project's spec/CLAUDE.md", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 3, "text": "fspec init copies templates/CLAUDE.md to spec/CLAUDE.md preserving all content exactly", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 4, "text": "/fspec slash command shows 'Copied spec/CLAUDE.md specification guidelines' in output", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 5, "text": "Running 'fspec init' twice overwrites spec/CLAUDE.md with latest template (no prompt, no backup)", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" } ], "questions": [ { "id": 0, "text": "@human: Should 'fspec init' also check if the CLAUDE.md template in the package is newer than the one in the project and offer to update it?", "selected": true, "answer": "Always overwrite - no version checking needed", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 1, "text": "@human: What should happen if the templates/ directory is missing from the fspec package installation?", "selected": true, "answer": "Templates directory is bundled with package build - if missing, it's a build error (should never happen in production)", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 2, "text": "@human: Should there be any output message confirming CLAUDE.md was copied/updated?", "selected": true, "answer": "Show confirmation message in /fspec slash command output (fspec.md), no separate message from fspec init CLI", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" }, { "id": 3, "text": "@human: Looking at existing INIT-002 work unit, should this enhance the existing init command or be separate?", "selected": true, "answer": "Enhance existing 'fspec init' command to copy CLAUDE.md template", "deleted": false, "createdAt": "2025-10-12T07:58:21.443Z" } ], "assumptions": [ "Templates directory is bundled with package build - if missing, it's a build error (should never happen in production)" ], "estimate": 2, "nextRuleId": 7, "nextExampleId": 6, "nextQuestionId": 4, "nextNoteId": 0 }, "DOC-002": { "id": "DOC-002", "title": "Provide schema information for foundation.json", "status": "done", "createdAt": "2025-10-12T11:46:03.860Z", "updatedAt": "2025-10-12T23:11:14.375Z", "description": "Add schema information to foundation.json to help AI agents draft foundation documents more easily. May require relaxing some schema constraints to make it more flexible for agents.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T11:46:21.581Z" }, { "state": "testing", "timestamp": "2025-10-12T22:56:07.240Z" }, { "state": "implementing", "timestamp": "2025-10-12T22:59:39.116Z" }, { "state": "validating", "timestamp": "2025-10-12T23:11:14.091Z" }, { "state": "done", "timestamp": "2025-10-12T23:11:14.376Z" } ], "rules": [ { "id": 0, "text": "Schema must guide AI agents to write documentation in a specific format that preserves project meaning and prevents drift", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 1, "text": "Schema must be provided as a separate JSON Schema file (foundation.schema.json)", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 2, "text": "Schema file must be accessible via CLI command so AI agents can read it", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 3, "text": "Field names should be flexible (e.g., accept both camelCase and snake_case) while maintaining similar overall structure", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 4, "text": "Schema must include rich descriptions explaining the intent behind each section", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 5, "text": "Schema must include examples of good vs. bad content for each field", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 6, "text": "Schema must include validation rules (e.g., minimum array lengths, required fields)", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 7, "text": "Schema must include format instructions for structured fields", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 8, "text": "Must provide both 'fspec show-foundation-schema' to display schema and 'fspec validate-foundation-schema' to validate foundation.json", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 9, "text": "No backward compatibility required - existing foundation.json files may need migration to new format", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 10, "text": "Mermaid syntax validation should be handled by Mermaid library (mermaid.parse()), not by JSON Schema. Schema only validates that mermaidCode field exists and is a string.", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 11, "text": "Schema should allow AI agents to add custom sections beyond the standard ones (project, whatWeAreBuilding, whyWeAreBuildingIt). Use additionalProperties: true for extensibility.", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 12, "text": "Validation should check semantic content of descriptions. Schema descriptions should guide AI on what to write and what NOT to write (e.g., 'projectOverview should focus on WHAT/HOW, not WHY - business justification belongs in whyWeAreBuildingIt').", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 13, "text": "Schema should allow additional properties (additionalProperties: true) for future extensibility. AI agents can add custom sections as needed.", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" } ], "examples": [ { "id": 0, "text": "Schema for 'projectOverview' includes description: 'A comprehensive technical overview (2-4 sentences) describing: (1) what systems are being built, (2) who uses them (target users), (3) how the systems integrate. Focus on WHAT and HOW, not WHY. Example: A Kanban-based project management and specification tool for AI agents...'", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 1, "text": "Schema for 'problemDefinition.primary' includes validation: must contain 'title', 'description', and 'coreProblems' array with minimum 3 items describing distinct problem categories", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 2, "text": "Schema accepts both camelCase and snake_case for ALL field names. Examples: 'architectureDiagrams' OR 'architecture_diagrams', 'technicalRequirements' OR 'technical_requirements', 'projectOverview' OR 'project_overview'", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 3, "text": "AI agent runs 'fspec show-foundation-schema' and receives JSON Schema with rich descriptions and examples. Agent uses this to understand how to structure foundation.json sections when running 'fspec update-foundation'", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 4, "text": "AI agent runs 'fspec validate-foundation-schema' after updating foundation.json. Validation fails with message: 'Field problemDefinition.primary.coreProblems must have at least 3 items (found 2)'. Agent adds another problem and re-validates.", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" } ], "questions": [ { "id": 0, "text": "@human: Should the schema validate Mermaid syntax in architectureDiagrams array, or just validate that mermaidCode field is a string?", "selected": true, "answer": "Mermaid syntax validation should be handled by Mermaid library (mermaid.parse()), not by JSON Schema. Schema only validates that mermaidCode field exists and is a string.", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 1, "text": "@human: Should the schema enforce specific top-level section names (project, whatWeAreBuilding, whyWeAreBuildingIt) or allow AI agents to add custom sections?", "selected": true, "answer": "Schema should allow AI agents to add custom sections beyond the standard ones (project, whatWeAreBuilding, whyWeAreBuildingIt). Use additionalProperties: true for extensibility.", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 2, "text": "@human: How detailed should validation be? Should it validate the semantic content of descriptions (e.g., 'projectOverview should not mention business justification') or just structural rules (required fields, types, array lengths)?", "selected": true, "answer": "Validation should check semantic content of descriptions. Schema descriptions should guide AI on what to write and what NOT to write (e.g., 'projectOverview should focus on WHAT/HOW, not WHY - business justification belongs in whyWeAreBuildingIt').", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 3, "text": "@human: Should we provide a migration command (e.g., 'fspec migrate-foundation') to convert existing foundation.json to the new flexible format, or should users manually update?", "selected": true, "answer": "No migration command needed. No backward compatibility - users must manually update foundation.json to new format when schema is introduced.", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" }, { "id": 4, "text": "@human: Should the schema allow additional properties beyond the defined ones (additionalProperties: true) to support future extensibility, or be strict (additionalProperties: false)?", "selected": true, "answer": "Schema should allow additional properties (additionalProperties: true) for future extensibility. AI agents can add custom sections as needed.", "deleted": false, "createdAt": "2025-10-12T11:46:03.860Z" } ], "assumptions": [ "No migration command needed. No backward compatibility - users must manually update foundation.json to new format when schema is introduced." ], "estimate": 5, "nextRuleId": 14, "nextExampleId": 5, "nextQuestionId": 5, "nextNoteId": 0 }, "RSPEC-001": { "id": "RSPEC-001", "title": "Add rspec command for reverse ACDD", "status": "done", "createdAt": "2025-10-12T11:46:05.565Z", "updatedAt": "2025-10-13T00:20:55.500Z", "description": "Create new 'rspec' command that performs reverse ACDD by decomposing/reverse engineering existing applications. The command discovers user stories, personas, and acceptance criteria from existing code. Extends the /fspec slash command to tell Claude to read fspec.md and continue with reverse engineering workflow.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-12T23:11:24.854Z" }, { "state": "testing", "timestamp": "2025-10-13T00:20:36.464Z" }, { "state": "implementing", "timestamp": "2025-10-13T00:20:42.594Z" }, { "state": "validating", "timestamp": "2025-10-13T00:20:49.164Z" }, { "state": "done", "timestamp": "2025-10-13T00:20:55.501Z" } ], "rules": [ { "id": 0, "text": "Must identify user personas who interact with the system", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 1, "text": "Must identify high-level activities or goals users achieve with the software", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 2, "text": "Must break down high-level activities into smaller specific tasks or interactions that code supports", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 3, "text": "Analysis involves: (1) analyzing functionality and mapping to user goals, (2) examining UI elements/features/workflows, (3) grouping related features into epics/journeys, (4) decomposing into individual user stories", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 4, "text": "Must produce user story map organized visually along user journey (broad activities at top, detailed interactions underneath)", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 5, "text": "User stories must be expressed as user-centric narratives (As a [persona], I want [goal], So that [benefit])", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 6, "text": "fspec init must install rspec.md slash command (similar to how it installs fspec.md)", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 7, "text": "rspec.md first line (after title) must say 'fully read fspec.md' with markdown link to exact fspec.md location", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 8, "text": "Must create everything fspec can do: work units, epics, prefixes, example maps, features, foundation.json (particularly this, keep updating as it learns), diagrams, unit/integration tests (NOT implemented), test-to-feature links (header comments)", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 9, "text": "Must create user story map in feature file docstrings or foundation.json (wherever closest to where it needs to be)", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 10, "text": "Must ONLY create artifacts that use fspec or are tests - nothing else", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 11, "text": "When encountering incomplete/ambiguous code: reverse engineer as much as possible, then ask human to complete via Example Mapping session", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 12, "text": "foundation.json must be continuously updated as system learns more about the codebase", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 13, "text": "Unit tests and integration tests created must NOT be implemented (skeleton only) - AI/human implements them later following ACDD", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 14, "text": "/rspec is a Claude Code slash command (not CLI command) - user invokes it via /rspec in Claude Code", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 15, "text": "User story map should be one or more Mermaid diagrams (preferably) plus any supporting artifacts that help visualize the map", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" } ], "examples": [ { "id": 0, "text": "Skeleton test file header includes: /** Feature: spec/features/[name].feature\\n * This test validates acceptance criteria. Tests map to Gherkin scenarios.\\n */", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 1, "text": "User runs /rspec in Claude Code → AI reads .claude/commands/rspec.md → First line says 'fully read fspec.md' (with link) → AI follows fspec workflow while reverse engineering", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 2, "text": "User story map created as Mermaid diagram in foundation.json architectureDiagrams array with section='User Story Map'", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" }, { "id": 3, "text": "Reverse engineered Express.js app: creates epic 'api-management', prefix 'API', work units API-001 'User authentication', API-002 'Data validation', feature files with inferred scenarios, skeleton tests with describe/it blocks (no implementation)", "deleted": false, "createdAt": "2025-10-12T11:46:05.565Z" } ], "nextRuleId": 16, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-003": { "id": "BUG-003", "title": "Summary report shows 'undefined' instead of file path", "status": "done", "createdAt": "2025-10-13T05:18:30.471Z", "updatedAt": "2025-10-13T07:23:52.363Z", "description": "When running 'fspec generate-summary-report --format=markdown', the output shows 'Report generated: undefined' instead of the actual file path where the report was saved.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T05:18:44.355Z" }, { "state": "testing", "timestamp": "2025-10-13T05:22:07.396Z" }, { "state": "implementing", "timestamp": "2025-10-13T05:22:44.125Z" }, { "state": "validating", "timestamp": "2025-10-13T05:24:48.456Z" }, { "state": "done", "timestamp": "2025-10-13T05:25:46.597Z" } ], "rules": [ { "id": 0, "text": "Command output must show the actual file path where the report was generated", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 1, "text": "When --output option is provided, show that specific path", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 2, "text": "When --output option is NOT provided, show the default generated path", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 3, "text": "Function must return outputFile property containing the path where report was written", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 4, "text": "Function must accept format (markdown, json, html) and output (file path) options", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 5, "text": "Function must write report to file system in the specified format", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 6, "text": "Default output path should be spec/summary-report.{format}", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec generate-summary-report --format=markdown', sees 'Report generated: spec/summary-report.md'", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 1, "text": "User runs 'fspec generate-summary-report --format=markdown --output=custom.md', sees 'Report generated: custom.md'", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 2, "text": "Currently shows 'Report generated: undefined' instead of actual path", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 3, "text": "Function currently returns SummaryReport object without outputFile property", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 4, "text": "CLI calls result.outputFile which is undefined", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" }, { "id": 5, "text": "Function signature currently missing format and output parameters", "deleted": false, "createdAt": "2025-10-13T05:18:30.471Z" } ], "estimate": 2, "nextRuleId": 7, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-005": { "id": "CLI-005", "title": "Add --help support to all fspec commands", "status": "done", "createdAt": "2025-10-13T05:32:26.029Z", "updatedAt": "2025-10-13T05:56:38.745Z", "description": "Currently commands like 'fspec create-epic --help' fail with 'unknown option --help'. Every fspec command should support --help flag that displays detailed usage information, options, arguments, and practical examples for that specific command. This includes all ~80+ commands across specs, work, discovery, metrics, and setup groups.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T05:32:33.248Z" }, { "state": "testing", "timestamp": "2025-10-13T05:44:40.837Z" }, { "state": "implementing", "timestamp": "2025-10-13T05:46:16.843Z" }, { "state": "validating", "timestamp": "2025-10-13T05:55:36.370Z" }, { "state": "done", "timestamp": "2025-10-13T05:56:38.746Z" } ], "rules": [ { "id": 0, "text": "Help output must include: command description, all options with descriptions, required vs optional arguments, practical examples, and related commands", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 1, "text": "Help formatting must use custom colored output matching 'fspec help specs' style, optimized for AI agent readability", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 2, "text": "Number of examples should be contextually appropriate per command complexity", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 3, "text": "Individual command help (--help) must be separate from group help (fspec help specs/work/etc)", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 4, "text": "Main fspec --help output must mention that each command supports its own --help flag", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 5, "text": "Must use custom help system, not Commander.js built-in help (insufficient quality)", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 6, "text": "Help must include AI-optimized sections when applicable: WHEN TO USE, WHEN NOT TO USE, COMMON PATTERNS, TYPICAL WORKFLOW, PREREQUISITES, related workflow states", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 7, "text": "Examples must show both command and expected output for clarity", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 8, "text": "Help templates must vary by command complexity: Simple (1-2 examples), Medium (2-3 examples), Complex (4-5 examples showing different modes)", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 9, "text": "Help must include COMMON ERRORS section with error messages and fixes", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 10, "text": "Related commands section must only show highly related commands with whatever format makes sense (syntax/names/workflow context)", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 11, "text": "No validation or schema enforcement needed - help text should be inline in command code", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 12, "text": "Whatever is most elegant while retaining exact same functionality - ultrathink this", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 13, "text": "Create help infrastructure first, then implement each command help individually", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 14, "text": "Yes, refactor into shared help utilities module for consistency", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 15, "text": "Infrastructure first: build help system, then implement per command", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 16, "text": "Infrastructure first: build help system, then implement per command", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec create-epic --help' and sees: description, usage syntax, options (none), arguments ( ), 2 examples with output, related commands (list-epics, show-epic, create-work-unit)", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 1, "text": "User runs 'fspec list-work-units --help' and sees: WHEN TO USE section, all options (--status, --prefix, --epic), 3 examples showing different filters with sample output, TYPICAL WORKFLOW mentioning backlog → specifying flow", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 2, "text": "User runs 'fspec add-dependency --help' and sees: description explaining dependency types, 5 examples showing shorthand vs --blocks vs --blocked-by vs --depends-on vs --relates-to, COMMON ERRORS section for 'work unit not found', related commands (remove-dependency, dependencies, export-dependencies)", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 3, "text": "User runs 'fspec update-work-unit-status --help' and sees: PREREQUISITES (work unit must exist), WHEN TO USE (moving through ACDD workflow), valid status values listed, TYPICAL WORKFLOW showing backlog→specifying→testing→implementing→validating→done, example with output showing status change", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 4, "text": "User runs 'fspec --help' and sees updated main help with note: 'Get detailed help for any command with: fspec <command> --help'", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 5, "text": "User runs 'fspec add-question --help' and sees: WHEN TO USE (during Example Mapping in specifying phase), COMMON PATTERNS (use @human: prefix for questions directed at human), example showing question with answer flow, related commands (answer-question, add-rule, add-example, generate-scenarios)", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" } ], "questions": [ { "id": 0, "text": "@human: How should we handle the --help flag given the custom help system that overrides Commander?", "selected": true, "answer": "Whatever works best - could be smoke tests, integration tests, or manual testing", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 1, "text": "@human: Should we refactor existing help command formatting utilities into shared module?", "selected": true, "answer": "Integration tests that verify help output contains required sections and examples", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 2, "text": "@human: Should we implement help for all 80+ commands at once or incrementally?", "selected": true, "answer": "Infrastructure first: build help system, then implement per command", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" }, { "id": 3, "text": "@human: What testing strategy should we use for help output?", "selected": true, "answer": "Integration tests that verify help output contains required sections and examples", "deleted": false, "createdAt": "2025-10-13T05:32:26.029Z" } ], "assumptions": [ "Whatever works best given current setup and custom help system that overrides Commander's, and existing fspec --help", "Whatever works best - could be smoke tests, integration tests, or manual testing", "Integration tests that verify help output contains required sections and examples", "Integration tests that verify help output contains required sections and examples" ], "nextRuleId": 17, "nextExampleId": 6, "nextQuestionId": 4, "nextNoteId": 0 }, "CLI-006": { "id": "CLI-006", "title": "Implement scalable help system for all commands", "status": "done", "createdAt": "2025-10-13T06:06:34.397Z", "updatedAt": "2025-10-13T06:26:59.486Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T06:06:40.458Z" }, { "state": "testing", "timestamp": "2025-10-13T06:12:23.135Z" }, { "state": "implementing", "timestamp": "2025-10-13T06:13:25.161Z" }, { "state": "validating", "timestamp": "2025-10-13T06:25:58.574Z" }, { "state": "done", "timestamp": "2025-10-13T06:26:59.487Z" } ], "rules": [ { "id": 0, "text": "Help system must automatically discover and register help configs without manual registration in index.ts", "deleted": false, "createdAt": "2025-10-13T06:06:34.397Z" }, { "id": 1, "text": "Each command should have its help config in a dedicated file (command-name-help.ts) co-located with command implementation", "deleted": false, "createdAt": "2025-10-13T06:06:34.397Z" }, { "id": 2, "text": "Commander.js should automatically handle --help flag for all commands without explicit handlers in action callbacks", "deleted": false, "createdAt": "2025-10-13T06:06:34.397Z" }, { "id": 3, "text": "Help configs should use a naming convention that maps to command names (e.g., remove-tag-from-scenario -> remove-tag-from-scenario-help.ts)", "deleted": false, "createdAt": "2025-10-13T06:06:34.397Z" }, { "id": 4, "text": "Missing help config files should fall back to Commander.js default help (current behavior) rather than error", "deleted": false, "createdAt": "2025-10-13T06:06:34.397Z" } ], "examples": [ { "id": 0, "text": "When user runs 'fspec remove-tag-from-scenario --help' and help config exists at src/commands/remove-tag-from-scenario-help.ts, display detailed help from config", "deleted": false, "createdAt": "2025-10-13T06:06:34.397Z" }, { "id": 1, "text": "When user runs 'fspec some-command --help' and no help config file exists, fall back to Commander.js default help", "deleted": false, "createdAt": "2025-10-13T06:06:34.397Z" } ], "questions": [ { "id": 0, "text": "@human: Should we use Commander.js custom help configuration or a global --help interceptor to avoid modifying 91 command registrations?", "selected": true, "answer": "Use process-level help interceptor with registry Set. Intercept --help before Commander.js, use dynamic imports, graceful fallback for missing configs, zero modifications to 91 command registrations.", "deleted": false, "createdAt": "2025-10-13T06:06:34.397Z" } ], "nextRuleId": 5, "nextExampleId": 2, "nextQuestionId": 1, "nextNoteId": 0 }, "BUG-004": { "id": "BUG-004", "title": "Fix generate-scenarios to use capability-based feature file names", "status": "done", "createdAt": "2025-10-13T07:23:50.426Z", "updatedAt": "2025-10-13T07:31:08.560Z", "description": "The generate-scenarios command currently defaults to using work unit ID as feature file name (e.g., auth-001.feature) which violates the naming principle. Should require --feature flag or use work unit title as default.", "children": [], "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T07:24:10.294Z" }, { "state": "testing", "timestamp": "2025-10-13T07:26:43.645Z" }, { "state": "implementing", "timestamp": "2025-10-13T07:27:36.963Z" }, { "state": "validating", "timestamp": "2025-10-13T07:30:19.171Z" }, { "state": "done", "timestamp": "2025-10-13T07:31:08.561Z" } ], "rules": [ { "id": 0, "text": "Feature files must be named after capabilities, NOT work unit IDs", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" }, { "id": 1, "text": "Work unit title should be used as default suggestion when --feature not provided", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" }, { "id": 2, "text": "Command should fail with helpful error if --feature not provided and AI needs to choose name", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" }, { "id": 3, "text": "Auto-default to work unit title (kebab-cased). User can override with --feature flag if they want a different name.", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" }, { "id": 4, "text": "Throw error requiring --feature flag with helpful message suggesting capability-based name.", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec generate-scenarios AUTH-001', command suggests using work unit title as feature name", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" }, { "id": 1, "text": "User runs 'fspec generate-scenarios AUTH-001 --feature=user-authentication', creates spec/features/user-authentication.feature", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" }, { "id": 2, "text": "Work unit AUTH-001 has title 'User Login', defaults to spec/features/user-login.feature when --feature not provided", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" } ], "questions": [ { "id": 0, "text": "@human: Should we make --feature flag required, or auto-default to work unit title?", "selected": true, "answer": "Auto-default to work unit title (kebab-cased). User can override with --feature flag if they want a different name.", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" }, { "id": 1, "text": "@human: What should happen if work unit title is empty or not set?", "selected": true, "answer": "Throw error requiring --feature flag with helpful message suggesting capability-based name.", "deleted": false, "createdAt": "2025-10-13T07:23:50.426Z" } ], "nextRuleId": 5, "nextExampleId": 3, "nextQuestionId": 2, "nextNoteId": 0 }, "REMIND-002": { "id": "REMIND-002", "title": "Comprehensive System-Reminder Overhaul", "status": "done", "createdAt": "2025-10-13T07:56:29.390Z", "updatedAt": "2025-10-13T08:19:36.823Z", "description": "Audit existing system-reminders, expand to all critical commands based on analysis, add file naming detection, tag validation, and discovery phase reminders", "children": [ "REMIND-003", "REMIND-004", "REMIND-005", "REMIND-006", "REMIND-007" ], "estimate": 13, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T08:18:35.217Z" }, { "state": "testing", "timestamp": "2025-10-13T08:19:35.726Z" }, { "state": "implementing", "timestamp": "2025-10-13T08:19:36.092Z" }, { "state": "validating", "timestamp": "2025-10-13T08:19:36.462Z" }, { "state": "done", "timestamp": "2025-10-13T08:19:36.824Z" } ], "rules": [ { "id": 0, "text": "All child work units (REMIND-003, 004, 005, 006, 007) must be in done status", "deleted": false, "createdAt": "2025-10-13T07:56:29.390Z" }, { "id": 1, "text": "System-reminder functions implemented in src/utils/system-reminder.ts", "deleted": false, "createdAt": "2025-10-13T07:56:29.390Z" }, { "id": 2, "text": "System-reminders integrated into create-feature, add-tag-to-feature, generate-scenarios, show-work-unit, and update-work-unit-status commands", "deleted": false, "createdAt": "2025-10-13T07:56:29.390Z" } ], "examples": [ { "id": 0, "text": "All 5 child work units completed successfully with tests passing", "deleted": false, "createdAt": "2025-10-13T07:56:29.390Z" }, { "id": 1, "text": "Build passing with 843 tests, all system-reminder functionality working", "deleted": false, "createdAt": "2025-10-13T07:56:29.390Z" } ], "nextRuleId": 3, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "REMIND-003": { "id": "REMIND-003", "title": "File Naming Anti-Pattern Detection", "status": "done", "createdAt": "2025-10-13T07:56:47.607Z", "updatedAt": "2025-10-13T08:02:40.554Z", "description": "Add system-reminders to create-feature command to detect task-based naming (implement-, add-, create-, work-unit-ID) and remind to use capability-based naming", "parent": "REMIND-002", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T07:57:27.395Z" }, { "state": "testing", "timestamp": "2025-10-13T07:58:22.240Z" }, { "state": "implementing", "timestamp": "2025-10-13T07:58:32.755Z" }, { "state": "validating", "timestamp": "2025-10-13T08:01:48.189Z" }, { "state": "done", "timestamp": "2025-10-13T08:02:40.555Z" } ], "rules": [ { "id": 0, "text": "System-reminders must detect task-based file naming patterns (implement-, add-, create-, fix-, build-)", "deleted": false, "createdAt": "2025-10-13T07:56:47.607Z" }, { "id": 1, "text": "System-reminders must detect work unit ID patterns in file names (e.g., AUTH-001, REMIND-003)", "deleted": false, "createdAt": "2025-10-13T07:56:47.607Z" }, { "id": 2, "text": "Reminders must provide correct examples of capability-based naming", "deleted": false, "createdAt": "2025-10-13T07:56:47.607Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec create-feature implement-authentication', reminder shows '❌ WRONG: implement-authentication → ✅ CORRECT: user-authentication'", "deleted": false, "createdAt": "2025-10-13T07:56:47.607Z" }, { "id": 1, "text": "User runs 'fspec create-feature AUTH-001', reminder shows work unit IDs are not capability names", "deleted": false, "createdAt": "2025-10-13T07:56:47.607Z" }, { "id": 2, "text": "User runs 'fspec create-feature user-authentication', no reminder (correct naming)", "deleted": false, "createdAt": "2025-10-13T07:56:47.607Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "REMIND-004": { "id": "REMIND-004", "title": "Tag Validation Reminders", "status": "done", "createdAt": "2025-10-13T07:56:49.298Z", "updatedAt": "2025-10-13T13:01:25.736Z", "description": "Add reminders to add-tag-to-feature for unregistered tags and missing required tags", "parent": "REMIND-002", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T08:06:04.788Z" }, { "state": "testing", "timestamp": "2025-10-13T08:06:29.915Z" }, { "state": "implementing", "timestamp": "2025-10-13T08:06:31.632Z" }, { "state": "validating", "timestamp": "2025-10-13T08:07:43.185Z" }, { "state": "done", "timestamp": "2025-10-13T08:07:44.888Z" }, { "state": "testing", "timestamp": "2025-10-13T12:54:46.258Z" }, { "state": "implementing", "timestamp": "2025-10-13T13:00:50.474Z" }, { "state": "validating", "timestamp": "2025-10-13T13:01:07.724Z" }, { "state": "done", "timestamp": "2025-10-13T13:01:25.737Z" } ], "rules": [ { "id": 0, "text": "System-reminders must check if tag exists in tags.json before adding to feature file", "deleted": false, "createdAt": "2025-10-13T07:56:49.298Z" }, { "id": 1, "text": "System-reminders must check for missing required tags after adding a tag", "deleted": false, "createdAt": "2025-10-13T07:56:49.298Z" }, { "id": 2, "text": "Required tags are: phase tag, component tag, and feature-group tag", "deleted": false, "createdAt": "2025-10-13T07:56:49.298Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec add-tag-to-feature login.feature @unregistered-tag', reminder shows 'Tag not registered in tags.json'", "deleted": false, "createdAt": "2025-10-13T07:56:49.298Z" }, { "id": 1, "text": "User runs 'fspec add-tag-to-feature login.feature @phase1', no unregistered tag reminder but may show missing required tags reminder", "deleted": false, "createdAt": "2025-10-13T07:56:49.298Z" }, { "id": 2, "text": "User adds all required tags, no reminder shown", "deleted": false, "createdAt": "2025-10-13T07:56:49.298Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "REMIND-005": { "id": "REMIND-005", "title": "Discovery Phase Reminders", "status": "done", "createdAt": "2025-10-13T07:56:51.073Z", "updatedAt": "2025-10-13T13:01:28.324Z", "description": "Add reminders to generate-scenarios for unanswered questions, empty Example Mapping, and post-generation validation", "parent": "REMIND-002", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T08:08:01.105Z" }, { "state": "testing", "timestamp": "2025-10-13T08:08:14.931Z" }, { "state": "implementing", "timestamp": "2025-10-13T08:08:15.225Z" }, { "state": "validating", "timestamp": "2025-10-13T08:09:45.064Z" }, { "state": "done", "timestamp": "2025-10-13T08:09:45.355Z" }, { "state": "testing", "timestamp": "2025-10-13T12:54:55.259Z" }, { "state": "implementing", "timestamp": "2025-10-13T13:00:52.611Z" }, { "state": "validating", "timestamp": "2025-10-13T13:01:10.713Z" }, { "state": "done", "timestamp": "2025-10-13T13:01:28.325Z" } ], "rules": [ { "id": 0, "text": "System-reminders must check for unanswered questions before allowing scenario generation", "deleted": false, "createdAt": "2025-10-13T07:56:51.073Z" }, { "id": 1, "text": "System-reminders must check for empty Example Mapping (no rules AND no examples)", "deleted": false, "createdAt": "2025-10-13T07:56:51.073Z" }, { "id": 2, "text": "System-reminders must provide post-generation guidance after successful scenario generation", "deleted": false, "createdAt": "2025-10-13T07:56:51.073Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec generate-scenarios WORK-001' with unanswered questions, reminder blocks generation", "deleted": false, "createdAt": "2025-10-13T07:56:51.073Z" }, { "id": 1, "text": "User runs 'fspec generate-scenarios WORK-001' with no rules or examples, reminder suggests adding Example Mapping data", "deleted": false, "createdAt": "2025-10-13T07:56:51.073Z" }, { "id": 2, "text": "After successful generation, reminder shows next steps (validate, add tags, move to testing)", "deleted": false, "createdAt": "2025-10-13T07:56:51.073Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "REMIND-006": { "id": "REMIND-006", "title": "Show Work Unit Reminders", "status": "done", "createdAt": "2025-10-13T07:56:52.746Z", "updatedAt": "2025-10-13T13:01:30.534Z", "description": "Add reminders to show-work-unit for missing estimates, empty Example Mapping in specifying phase, and long duration warnings", "parent": "REMIND-002", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T08:10:17.524Z" }, { "state": "testing", "timestamp": "2025-10-13T08:16:22.073Z" }, { "state": "implementing", "timestamp": "2025-10-13T08:16:28.519Z" }, { "state": "validating", "timestamp": "2025-10-13T08:16:34.669Z" }, { "state": "done", "timestamp": "2025-10-13T08:17:10.348Z" }, { "state": "testing", "timestamp": "2025-10-13T12:54:55.554Z" }, { "state": "implementing", "timestamp": "2025-10-13T13:00:54.822Z" }, { "state": "validating", "timestamp": "2025-10-13T13:01:12.669Z" }, { "state": "done", "timestamp": "2025-10-13T13:01:30.535Z" } ], "rules": [ { "id": 0, "text": "Display system-reminder when work unit is missing estimate", "deleted": false, "createdAt": "2025-10-13T07:56:52.746Z" }, { "id": 1, "text": "Display system-reminder when work unit in specifying status has empty Example Mapping (no rules AND no examples)", "deleted": false, "createdAt": "2025-10-13T07:56:52.746Z" }, { "id": 2, "text": "Display system-reminder when work unit has been in current state for more than 24 hours", "deleted": false, "createdAt": "2025-10-13T07:56:52.746Z" } ], "examples": [ { "id": 0, "text": "Show work unit without estimate displays missing estimate reminder", "deleted": false, "createdAt": "2025-10-13T07:56:52.746Z" }, { "id": 1, "text": "Show work unit in specifying with no rules/examples displays Example Mapping reminder", "deleted": false, "createdAt": "2025-10-13T07:56:52.746Z" }, { "id": 2, "text": "Show work unit that has been in specifying for 25 hours displays long duration reminder", "deleted": false, "createdAt": "2025-10-13T07:56:52.746Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "REMIND-007": { "id": "REMIND-007", "title": "Update Status Reminder Enhancement", "status": "done", "createdAt": "2025-10-13T07:56:54.417Z", "updatedAt": "2025-10-13T13:01:32.609Z", "description": "Enhanced status reminders with blocked and done states - completed as part of REMIND-003", "parent": "REMIND-002", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T08:10:15.372Z" }, { "state": "testing", "timestamp": "2025-10-13T08:18:08.040Z" }, { "state": "implementing", "timestamp": "2025-10-13T08:18:08.403Z" }, { "state": "validating", "timestamp": "2025-10-13T08:18:08.765Z" }, { "state": "done", "timestamp": "2025-10-13T08:18:13.970Z" }, { "state": "testing", "timestamp": "2025-10-13T12:54:55.851Z" }, { "state": "implementing", "timestamp": "2025-10-13T13:00:56.856Z" }, { "state": "validating", "timestamp": "2025-10-13T13:01:15.325Z" }, { "state": "done", "timestamp": "2025-10-13T13:01:32.610Z" } ], "rules": [ { "id": 0, "text": "Enhance getStatusChangeReminder to include 'done' state reminder about feature file tag updates", "deleted": false, "createdAt": "2025-10-13T07:56:54.417Z" }, { "id": 1, "text": "Enhance getStatusChangeReminder to include 'blocked' state reminder about documenting blocker reasons", "deleted": false, "createdAt": "2025-10-13T07:56:54.417Z" } ], "examples": [ { "id": 0, "text": "Update status to 'done' displays reminder to update feature file tags", "deleted": false, "createdAt": "2025-10-13T07:56:54.417Z" }, { "id": 1, "text": "Update status to 'blocked' displays reminder to document blocker reason", "deleted": false, "createdAt": "2025-10-13T07:56:54.417Z" } ], "nextRuleId": 2, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "REMIND-008": { "id": "REMIND-008", "title": "Feature File Prefill Detection and CLI Enforcement", "status": "done", "createdAt": "2025-10-13T08:31:34.385Z", "updatedAt": "2025-10-13T08:52:57.425Z", "description": "Detect when feature files contain placeholder/prefill text and emit system-reminders instructing LLMs to use CLI commands. Block workflow state transitions if prefill remains.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T08:31:52.511Z" }, { "state": "testing", "timestamp": "2025-10-13T08:47:32.759Z" }, { "state": "implementing", "timestamp": "2025-10-13T08:52:11.546Z" }, { "state": "validating", "timestamp": "2025-10-13T08:52:44.911Z" }, { "state": "done", "timestamp": "2025-10-13T08:52:57.426Z" } ], "rules": [ { "id": 0, "text": "Example Mapping must capture the complete user story (role, action, benefit) as the yellow card", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 1, "text": "fspec generate-scenarios should generate complete user story from example map data, not placeholders", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 2, "text": "Prefill detection should identify ALL placeholder patterns: [role], [action], TODO:, @phase1, @component, etc.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 3, "text": "System-reminders must suggest specific CLI commands to fix detected prefill", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 4, "text": "Workflow state transitions must be blocked if linked feature files contain prefill placeholders", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 5, "text": "generate-scenarios should only run AFTER user story is complete (no [role], [action], [benefit] placeholders in Background)", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 6, "text": "Yes, add explicit userStory fields (role, action, benefit) to work-units.json schema and update JSON Schema validation", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 7, "text": "Write-time only, when all information has been collected. Detect prefill during fspec create-feature and fspec generate-scenarios, emit system-reminders with CLI commands to fix.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 8, "text": "Yes, BOTH write-time and read-time. Write-time for immediate feedback when creating/generating. Read-time for ongoing reminders when showing features, validating, or advancing work unit status.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 9, "text": "Until fixed - keep showing system-reminders every time a command interacts with a feature file that has prefill, until the prefill is completely removed.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 10, "text": "Hard error (exit 1) - Command must fail completely when trying to advance work unit status if linked feature file contains prefill. Forces LLM to fix prefill before proceeding.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 11, "text": "Hybrid approach - Try to intelligently extract Given/When/Then from example text (e.g., 'User logs in with valid credentials' → Given/When/Then steps). Fall back to prefill with system-reminders if parsing fails.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 12, "text": "Work units need CLI commands to set user story fields: fspec set-user-story <work-unit-id> --role='...' --action='...' --benefit='...'", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" } ], "examples": [ { "id": 0, "text": "LLM runs 'fspec create-feature Auth' and gets file with [role], [action], [benefit] placeholders. System-reminder tells LLM to use 'fspec add-background' instead of Edit tool", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 1, "text": "LLM runs 'fspec generate-scenarios AUTH-001' and gets scenarios with [precondition], [action], [expected outcome]. System-reminder tells LLM to use 'fspec add-step' instead of Write tool", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 2, "text": "Work unit AUTH-001 has user story in Example Mapping: role='developer', action='authenticate users', benefit='secure access'. generate-scenarios uses this data to create complete Background section without placeholders", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 3, "text": "LLM tries 'fspec update-work-unit-status AUTH-001 testing' but linked feature file has [role] placeholder. Command fails with error: 'Cannot advance: feature file contains prefill. Use fspec add-background to complete user story.'", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 4, "text": "LLM completes Example Mapping with user story fields. Runs 'fspec generate-scenarios AUTH-001'. Scenarios are generated BUT steps still have [precondition], [action], [outcome]. System-reminder tells LLM to use 'fspec add-step' for each scenario.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" } ], "questions": [ { "id": 0, "text": "@human: Should Example Mapping capture user story fields (role, action, benefit) as explicit fields in work-units.json?", "selected": true, "answer": "Yes, add explicit userStory fields (role, action, benefit) to work-units.json schema and update JSON Schema validation", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 1, "text": "@human: Should prefill detection happen at read-time (when showing feature) or write-time (when creating feature)?", "selected": true, "answer": "Write-time only, when all information has been collected. Detect prefill during fspec create-feature and fspec generate-scenarios, emit system-reminders with CLI commands to fix.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 2, "text": "@human: Should system-reminders for prefill appear every time or only once per session/work unit?", "selected": true, "answer": "Until fixed - keep showing system-reminders every time a command interacts with a feature file that has prefill, until the prefill is completely removed.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 3, "text": "@human: Should workflow blocking be a hard error (exits 1) or a warning (exits 0 with reminder)?", "selected": true, "answer": "Hard error (exit 1) - Command must fail completely when trying to advance work unit status if linked feature file contains prefill. Forces LLM to fix prefill before proceeding.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 4, "text": "@human: Should generate-scenarios create scenarios with prefill steps OR should it extract Given/When/Then from the example text itself?", "selected": true, "answer": "Hybrid approach - Try to intelligently extract Given/When/Then from example text (e.g., 'User logs in with valid credentials' → Given/When/Then steps). Fall back to prefill with system-reminders if parsing fails.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" }, { "id": 5, "text": "@human: Going back to question 1 - actually BOTH read-time and write-time?", "selected": true, "answer": "Yes, BOTH write-time and read-time. Write-time for immediate feedback when creating/generating. Read-time for ongoing reminders when showing features, validating, or advancing work unit status.", "deleted": false, "createdAt": "2025-10-13T08:31:34.385Z" } ], "estimate": 5, "userStory": { "role": "AI agent (LLM) using fspec", "action": "detect and fix feature file prefill using CLI commands", "benefit": "proper workflow enforcement and no direct file editing" }, "nextRuleId": 13, "nextExampleId": 5, "nextQuestionId": 6, "nextNoteId": 0 }, "COV-001": { "id": "COV-001", "title": "Feature-to-Code Coverage Tracking", "status": "done", "createdAt": "2025-10-13T09:49:22.476Z", "updatedAt": "2025-10-13T12:30:18.223Z", "description": "Create .coverage files that map Gherkin scenarios to test files and implementation code lines, with statistics and AI-assisted verification", "epic": "coverage-tracking", "children": [ "COV-002", "COV-003", "COV-004", "COV-005", "COV-006" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T09:49:22.866Z" }, { "state": "testing", "timestamp": "2025-10-13T12:24:55.611Z" }, { "state": "implementing", "timestamp": "2025-10-13T12:25:17.670Z" }, { "state": "implementing", "timestamp": "2025-10-13T12:30:17.638Z" }, { "state": "validating", "timestamp": "2025-10-13T12:30:17.932Z" }, { "state": "done", "timestamp": "2025-10-13T12:30:18.224Z" } ], "userStory": { "role": "developer using ACDD", "action": "track which test files and implementation code lines map to each Gherkin scenario", "benefit": "I can see exactly what code is covered by acceptance criteria and identify gaps" }, "rules": [ { "id": 0, "text": "Every .feature file must have a corresponding .feature.coverage file", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 1, "text": "Coverage files must be in JSON format with scenario-to-test-to-code mappings", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 2, "text": "Coverage files must include calculated statistics (total scenarios, covered scenarios, coverage percentage)", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 3, "text": "Automatically create .feature.coverage files when feature files are created via create-feature command", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 4, "text": "AI discovers test-to-scenario mappings using reverse ACDD (rspec.md) for existing code, or tracks mappings during forward ACDD. fspec provides CLI commands for AI to record these mappings", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 5, "text": "fspec prompts AI agent via interactive 'link-coverage' command (or similar name) to specify which implementation files and lines are covered by tests", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 6, "text": "Use 'audit-coverage' command that works with AI agent in a loop, prompting it to verify each file's mappings one by one. AI looks up current line numbers and updates coverage file", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 7, "text": "All statistics: coverage percentage, uncovered scenarios, number of test cases per scenario, implementation files touched, lines covered per file", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 8, "text": "Separate commands since coverage tracking is interactive and requires AI agent collaboration (link-coverage, audit-coverage, show-coverage, etc.)", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 9, "text": "JSON schema: {scenarios: [{name, testMappings: [{file, lines, implMappings: [{file, lines}]}]}], stats: {totalScenarios, coveredScenarios, coveragePercent, testFiles, implFiles, totalLinesCovered}}", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 10, "text": "Yes to both: scenarios can have multiple test files (array of testMappings), and test files can appear in multiple scenario mappings (many-to-many relationship)", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 11, "text": "Yes, show uncovered scenarios with empty testMappings array. Integrate with ACDD: block work units from moving to 'done' if linked feature has uncovered scenarios. Emit system-reminder to prompt AI to add coverage", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 12, "text": "Yes, validate file paths exist when linking coverage. Fail with clear error if test file or implementation file path is invalid", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" } ], "examples": [ { "id": 0, "text": "Feature file 'user-login.feature' has companion file 'user-login.feature.coverage' in same directory", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 1, "text": "Coverage file maps scenario 'Login with valid credentials' to test file 'src/__tests__/auth.test.ts' lines 45-62", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 2, "text": "Coverage file shows test at lines 45-62 covers implementation file 'src/auth/login.ts' lines 10,11,12,15,20", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 3, "text": "User runs 'fspec create-feature User Login', creates user-login.feature AND user-login.feature.coverage automatically", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 4, "text": "AI runs 'fspec link-coverage user-login --scenario \"Login with valid credentials\" --test-file src/__tests__/auth.test.ts --test-lines 45-62', fspec prompts AI for implementation files", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 5, "text": "AI runs 'fspec audit-coverage user-login', fspec shows first mapping and asks AI to verify line numbers are still correct, repeats for all mappings", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 6, "text": "Developer runs 'fspec show-coverage user-login', sees output: 5 scenarios, 4 covered (80%), 2 test files, 3 implementation files, 45 lines covered", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" } ], "questions": [ { "id": 0, "text": "@human: Should coverage files be created automatically when a feature file is created (via create-feature), or on-demand with a separate command (like init-coverage)?", "selected": true, "answer": "Automatically create .feature.coverage files when feature files are created via create-feature command", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 1, "text": "@human: How should the system discover which test files map to which scenarios? Should AI read test files and match them to scenario names, or should users manually link them with a command?", "selected": true, "answer": "AI discovers test-to-scenario mappings using reverse ACDD (rspec.md) for existing code, or tracks mappings during forward ACDD. fspec provides CLI commands for AI to record these mappings", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 2, "text": "@human: How should we track which implementation code lines are covered? Should AI parse test code to find which files are imported/used, or should this be manually specified?", "selected": true, "answer": "fspec prompts AI agent via interactive 'link-coverage' command (or similar name) to specify which implementation files and lines are covered by tests", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 3, "text": "@human: What happens when code changes and line numbers shift? Should we store line numbers at all, or use some other identifier (like function names, AST nodes, code hashes)?", "selected": true, "answer": "Use 'audit-coverage' command that works with AI agent in a loop, prompting it to verify each file's mappings one by one. AI looks up current line numbers and updates coverage file", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 4, "text": "@human: What does 'AI-assisted verification' mean exactly? Should the AI read coverage files and suggest corrections, or interactively ask the developer to confirm mappings?", "selected": true, "answer": "AI does all verification work during audit-coverage command by reading files, checking line numbers, and confirming mappings are correct", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 5, "text": "@human: What statistics are most important? Coverage percentage, uncovered scenarios, number of test cases, implementation files touched, something else?", "selected": true, "answer": "All statistics: coverage percentage, uncovered scenarios, number of test cases per scenario, implementation files touched, lines covered per file", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 6, "text": "@human: Should coverage validation be integrated into existing commands (like 'fspec check', 'fspec validate'), or be separate commands?", "selected": true, "answer": "Separate commands since coverage tracking is interactive and requires AI agent collaboration (link-coverage, audit-coverage, show-coverage, etc.)", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 7, "text": "@human: What should the JSON schema look like? Should it be: {scenarios: [{name, testMappings: [{file, lines, implMappings: [{file, lines}]}]}], stats: {...}}?", "selected": true, "answer": "JSON schema: {scenarios: [{name, testMappings: [{file, lines, implMappings: [{file, lines}]}]}], stats: {totalScenarios, coveredScenarios, coveragePercent, testFiles, implFiles, totalLinesCovered}}", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 8, "text": "@human: Can one scenario map to multiple test files? Can one test file cover multiple scenarios?", "selected": true, "answer": "Yes to both: scenarios can have multiple test files (array of testMappings), and test files can appear in multiple scenario mappings (many-to-many relationship)", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 9, "text": "@human: What if a scenario has no tests yet (ACDD testing phase not started)? Should coverage file show it as uncovered with empty test mappings?", "selected": true, "answer": "Yes, show uncovered scenarios with empty testMappings array. Integrate with ACDD: block work units from moving to 'done' if linked feature has uncovered scenarios. Emit system-reminder to prompt AI to add coverage", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 10, "text": "@human: Should we validate that test files and implementation files actually exist when linking coverage? Fail if file paths are invalid?", "selected": true, "answer": "Yes, validate file paths exist when linking coverage. Fail with clear error if test file or implementation file path is invalid", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" }, { "id": 11, "text": "@human: Should coverage files be formatted/validated like feature files? Should there be 'fspec validate-coverage' command?", "selected": true, "answer": "No validation command needed. Coverage files are only modified by fspec commands (link-coverage, audit-coverage), never manually edited. fspec maintains file integrity automatically", "deleted": false, "createdAt": "2025-10-13T09:49:22.476Z" } ], "assumptions": [ "AI does all verification work during audit-coverage command by reading files, checking line numbers, and confirming mappings are correct", "No validation command needed. Coverage files are only modified by fspec commands (link-coverage, audit-coverage), never manually edited. fspec maintains file integrity automatically" ], "estimate": 8, "nextRuleId": 13, "nextExampleId": 7, "nextQuestionId": 12, "nextNoteId": 0 }, "COV-002": { "id": "COV-002", "title": "Auto-create Coverage Files", "status": "done", "createdAt": "2025-10-13T10:04:49.597Z", "updatedAt": "2025-10-13T10:30:26.647Z", "description": "Modify create-feature command to automatically generate .feature.coverage JSON files alongside feature files with empty scenario mappings", "epic": "coverage-tracking", "children": [], "parent": "COV-001", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T10:08:21.423Z" }, { "state": "testing", "timestamp": "2025-10-13T10:22:20.882Z" }, { "state": "implementing", "timestamp": "2025-10-13T10:25:15.136Z" }, { "state": "validating", "timestamp": "2025-10-13T10:29:47.242Z" }, { "state": "done", "timestamp": "2025-10-13T10:30:26.647Z" } ], "userStory": { "role": "developer creating feature files", "action": "have .feature.coverage files automatically created when I run create-feature", "benefit": "I don't have to manually create coverage tracking files" }, "rules": [ { "id": 0, "text": "Coverage files must be auto-created when create-feature command runs", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 1, "text": "Coverage file must be named <feature-name>.feature.coverage (same name as .feature file with .coverage extension)", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 2, "text": "Coverage file must be in same directory as .feature file (spec/features/)", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 3, "text": "Coverage file must be valid JSON with schema: {scenarios: [{name, testMappings: []}], stats: {totalScenarios, coveredScenarios, coveragePercent, testFiles, implFiles, totalLinesCovered}}", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 4, "text": "Initial coverage file must have empty testMappings arrays (no coverage yet)", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 5, "text": "Scenarios array must be populated from feature file scenarios (read from Gherkin AST)", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 6, "text": "Stats must be calculated: totalScenarios=count, coveredScenarios=0, coveragePercent=0, testFiles=[], implFiles=[], totalLinesCovered=0", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 7, "text": "Display message: 'Created <filename>.feature.coverage' so user knows coverage file was generated", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 8, "text": "If .coverage file exists: read and validate JSON. If valid, skip creation (preserve existing coverage). If invalid JSON, overwrite with fresh coverage file", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 9, "text": "Scenario names must exactly match Gherkin scenario names (case-sensitive, preserve whitespace) for accurate mapping", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" } ], "examples": [ { "id": 0, "text": "Run 'fspec create-feature User Login', creates spec/features/user-login.feature AND spec/features/user-login.feature.coverage", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 1, "text": "Coverage file contains {scenarios: [{name: 'Login with valid credentials', testMappings: []}], stats: {totalScenarios: 1, coveredScenarios: 0, coveragePercent: 0, testFiles: [], implFiles: [], totalLinesCovered: 0}}", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 2, "text": "Feature file with 3 scenarios creates coverage file with 3 entries in scenarios array, totalScenarios: 3", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 3, "text": "If create-feature fails (invalid name), no .coverage file should be created", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 4, "text": "Coverage file exists with valid JSON, create-feature skips creation and displays 'Skipped user-login.feature.coverage (already exists)'", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 5, "text": "Coverage file exists with invalid JSON, create-feature overwrites it and displays 'Recreated user-login.feature.coverage (previous file was invalid)'", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" } ], "questions": [ { "id": 0, "text": "@human: Should coverage file creation be silent (no output), or should create-feature display 'Created user-login.feature.coverage'?", "selected": true, "answer": "Display message: 'Created <filename>.feature.coverage' so user knows coverage file was generated", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 1, "text": "@human: What if a .coverage file already exists? Should we overwrite it, skip it, or error?", "selected": true, "answer": "If .coverage file exists: read and validate JSON. If valid, skip creation (preserve existing coverage). If invalid JSON, overwrite with fresh coverage file", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" }, { "id": 2, "text": "@human: Should scenario names in coverage file exactly match Gherkin scenario names (including case/whitespace), or should they be normalized?", "selected": true, "answer": "Scenario names must exactly match Gherkin scenario names (case-sensitive, preserve whitespace) for accurate mapping", "deleted": false, "createdAt": "2025-10-13T10:04:49.597Z" } ], "nextRuleId": 10, "nextExampleId": 6, "nextQuestionId": 3, "nextNoteId": 0 }, "COV-003": { "id": "COV-003", "title": "Link Coverage Command", "status": "done", "createdAt": "2025-10-13T10:04:51.632Z", "updatedAt": "2025-10-13T11:25:03.758Z", "description": "Implement 'fspec link-coverage' command for mapping scenarios to test files and implementation files with interactive AI prompting and file path validation", "epic": "coverage-tracking", "children": [], "dependsOn": [ "COV-002" ], "parent": "COV-001", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T11:03:16.421Z" }, { "state": "testing", "timestamp": "2025-10-13T11:17:50.164Z" }, { "state": "implementing", "timestamp": "2025-10-13T11:19:34.215Z" }, { "state": "validating", "timestamp": "2025-10-13T11:24:59.487Z" }, { "state": "done", "timestamp": "2025-10-13T11:25:03.759Z" } ], "questions": [ { "id": 0, "text": "@human: Should one command support BOTH adding test mapping AND implementation mapping, or separate them into distinct operations?", "selected": true, "answer": "Non-interactive command-line interface. Support partial additions (test-only, or test+impl). After execution, display helpful message showing how to add more mappings or remove existing ones. No interactive prompts that wait for user input. All operations complete immediately with instructional output.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 1, "text": "@human: How should the link-coverage command be invoked? (all-in-one, two-step, or interactive prompting?)", "selected": true, "answer": "Single flexible link-coverage command. Support three modes: (1) test-only (--test-file + --test-lines), (2) impl-only (--impl-file + --impl-lines), (3) both at once (all four flags). Command validates required flag combinations and provides helpful error messages if incorrect combination provided.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 2, "text": "@human: When adding impl-only (no test flags), which test mapping should it attach to? Most recent test for that scenario, or require test file specification?", "selected": true, "answer": "Always require --test-file when adding implementation mappings. Implementation mappings attach to specific test mappings, so test file must be specified to identify which test mapping to update. This ensures explicit, unambiguous attachment.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 3, "text": "@human: For line numbers, should we support ranges (45-62), individual lines (10,11,12), or both? Should format be consistent between test and impl lines?", "selected": true, "answer": "Test lines: range format only (e.g., '45-62'). Implementation lines: comma-separated primary (e.g., '10,11,12,15,20'), but also accept ranges as convenience (e.g., '10-15' expands to [10,11,12,13,14,15]). This matches storage format and mirrors reality: tests are contiguous, impl can be scattered.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 4, "text": "@human: Should file paths be validated (check if they exist on disk) before adding to coverage? Error if missing, or allow with warning?", "selected": true, "answer": "Validate file paths by default (error if file doesn't exist). Support --skip-validation flag to bypass validation for forward planning scenarios. When validation fails, display clear error with file path and suggestion. When --skip-validation used, show warning that file doesn't exist but continue.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 5, "text": "@human: What happens if you try to link a test mapping that already exists (same scenario + same test file)? Overwrite, append, or error?", "selected": true, "answer": "Append mode: allow multiple test mappings for the same file in one scenario. Each mapping is independent with its own line range and impl mappings. Display message showing all mappings for that file. This supports scenarios where one scenario is tested multiple times in the same file (e.g., different test suites or contexts).", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 6, "text": "@human: When adding impl mapping to existing test, what if that test already has impl mappings? Append to the array or replace?", "selected": true, "answer": "Smart append: check if impl file already exists in the test mapping's implMappings array. If exists, update the line numbers for that file. If doesn't exist, append as new impl mapping. Display whether updated or added. This allows one test to cover multiple impl files while preventing duplicate entries.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 7, "text": "@human: Should the command support removing/unlinking mappings, or should that be a separate command (like unlink-coverage or remove-coverage)?", "selected": true, "answer": "Separate command for removal. link-coverage only adds/updates mappings. Display helpful message after linking showing how to remove: 'To remove this mapping: fspec unlink-coverage <feature> --scenario ... --test-file ...'. Removal command (unlink-coverage) is separate work unit, follows fspec pattern of separate add/remove commands.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" } ], "rules": [ { "id": 0, "text": "Non-interactive command-line interface. Support partial additions (test-only, or test+impl). After execution, display helpful message showing how to add more mappings or remove existing ones. No interactive prompts that wait for user input. All operations complete immediately with instructional output.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 1, "text": "Single flexible link-coverage command. Support three modes: (1) test-only (--test-file + --test-lines), (2) impl-only (--impl-file + --impl-lines), (3) both at once (all four flags). Command validates required flag combinations and provides helpful error messages if incorrect combination provided.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 2, "text": "Always require --test-file when adding implementation mappings. Implementation mappings attach to specific test mappings, so test file must be specified to identify which test mapping to update. This ensures explicit, unambiguous attachment.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 3, "text": "Test lines: range format only (e.g., '45-62'). Implementation lines: comma-separated primary (e.g., '10,11,12,15,20'), but also accept ranges as convenience (e.g., '10-15' expands to [10,11,12,13,14,15]). This matches storage format and mirrors reality: tests are contiguous, impl can be scattered.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 4, "text": "Validate file paths by default (error if file doesn't exist). Support --skip-validation flag to bypass validation for forward planning scenarios. When validation fails, display clear error with file path and suggestion. When --skip-validation used, show warning that file doesn't exist but continue.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 5, "text": "Append mode: allow multiple test mappings for the same file in one scenario. Each mapping is independent with its own line range and impl mappings. Display message showing all mappings for that file. This supports scenarios where one scenario is tested multiple times in the same file (e.g., different test suites or contexts).", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 6, "text": "Smart append: check if impl file already exists in the test mapping's implMappings array. If exists, update the line numbers for that file. If doesn't exist, append as new impl mapping. Display whether updated or added. This allows one test to cover multiple impl files while preventing duplicate entries.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 7, "text": "Separate command for removal. link-coverage only adds/updates mappings. Display helpful message after linking showing how to remove: 'To remove this mapping: fspec unlink-coverage <feature> --scenario ... --test-file ...'. Removal command (unlink-coverage) is separate work unit, follows fspec pattern of separate add/remove commands.", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec link-coverage user-login --scenario \"Login with valid credentials\" --test-file src/__tests__/auth.test.ts --test-lines 45-62', creates test mapping, displays success and helpful message", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 1, "text": "User runs 'fspec link-coverage user-login --scenario \"Login with valid credentials\" --test-file src/__tests__/auth.test.ts --impl-file src/auth/login.ts --impl-lines 10,11,12', adds impl mapping to existing test", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 2, "text": "User runs command with both test and impl flags at once, creates test mapping with impl mapping in one operation", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 3, "text": "Test file doesn't exist, validation fails with error and suggestion to use --skip-validation", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 4, "text": "User provides --skip-validation flag with non-existent file, command succeeds with warning message", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 5, "text": "Impl lines '10-15' (range format) expands to array [10,11,12,13,14,15] in coverage file", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 6, "text": "Adding impl file that already exists in test mapping updates line numbers instead of creating duplicate entry", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" }, { "id": 7, "text": "Adding test mapping with same test file but different lines appends as second mapping", "deleted": false, "createdAt": "2025-10-13T10:04:51.632Z" } ], "userStory": { "role": "developer tracking test coverage", "action": "link scenarios to test files and implementation files", "benefit": "I can track which code covers which acceptance criteria" }, "nextRuleId": 8, "nextExampleId": 8, "nextQuestionId": 8, "nextNoteId": 0 }, "COV-004": { "id": "COV-004", "title": "Show Coverage Statistics", "status": "done", "createdAt": "2025-10-13T10:04:53.307Z", "updatedAt": "2025-10-13T11:01:35.541Z", "description": "Implement 'fspec show-coverage' command to display coverage statistics including percentage, test files, implementation files, and line counts", "epic": "coverage-tracking", "children": [], "dependsOn": [ "COV-002" ], "parent": "COV-001", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T10:35:18.928Z" }, { "state": "testing", "timestamp": "2025-10-13T10:58:41.331Z" }, { "state": "implementing", "timestamp": "2025-10-13T10:59:49.378Z" }, { "state": "validating", "timestamp": "2025-10-13T11:01:24.285Z" }, { "state": "done", "timestamp": "2025-10-13T11:01:35.542Z" } ], "questions": [ { "id": 0, "text": "@human: What output format(s) should show-coverage support? (text/json/markdown, with --format flag?)", "selected": true, "answer": "Markdown and JSON output formats. Default to markdown. Use --format flag (--format=json for JSON output, --format=markdown or no flag for markdown)", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 1, "text": "@human: For text output, what level of detail by default? (summary only, full breakdown, or configurable with --verbose?)", "selected": true, "answer": "Full breakdown always shown by default in markdown. Include summary stats + scenario-by-scenario coverage details (test files, implementation files, line numbers). Show which scenarios are covered and uncovered.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 2, "text": "@human: Should uncovered scenarios be highlighted in red and/or listed separately?", "selected": true, "answer": "Use both visual symbols (✅ for covered, ❌ for uncovered) throughout scenario list AND create a separate 'Coverage Gaps' section at the end listing all uncovered scenarios with action items", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 3, "text": "@human: Should show-coverage work on single file, all files, or both? (Usage: fspec show-coverage [file])", "selected": true, "answer": "Support both modes: show all files when no argument provided, show specific file when file path is provided. File path can be relative (user-login.feature) or full path (spec/features/user-login.feature)", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 4, "text": "@human: If showing all files, display aggregated stats, per-feature breakdown, or both?", "selected": true, "answer": "Both: show aggregated project summary at top (overall coverage, total features/scenarios, features overview table), then full per-feature breakdowns with scenario details for each feature file", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 5, "text": "@human: How to calculate covered scenarios? (has test mapping, or test + impl mappings?)", "selected": true, "answer": "Three-tier coverage system: 'Fully Covered' (has test mapping AND implementation mappings), 'Partially Covered' (has test mapping but empty implMappings), 'Uncovered' (no test mappings). Statistics should count fully covered + partially covered as total covered scenarios.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 6, "text": "@human: For line counts, count impl lines only, or test + impl lines separately?", "selected": true, "answer": "Separate counts for test lines and implementation lines. Display 'Test Lines', 'Implementation Lines', and 'Total Lines' in statistics. Parse line ranges (e.g., '45-62' = 18 lines) and count individual lines in arrays.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 7, "text": "@human: Should we validate that mapped files/lines still exist? (always, never, or --validate flag?)", "selected": true, "answer": "Always validate file paths exist when displaying coverage. Check that test files and implementation files exist on disk. Display warnings for missing files but still show the coverage data. This ensures users are immediately aware of stale mappings.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 8, "text": "@human: What happens if .coverage file doesn't exist? (error, show 0% with message, or suggest creating?)", "selected": true, "answer": "Error and exit with code 1 when .coverage file doesn't exist. Display clear error message with suggestion to create coverage file using appropriate command (fspec create-feature or manually). This ensures explicit coverage tracking setup.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 9, "text": "@human: What happens if .coverage file has invalid JSON? (error, warning, or try to parse?)", "selected": true, "answer": "Error and exit with code 1 when .coverage file has invalid JSON. Display parse error details (line number, error message) and suggest validating/recreating the file. Keep error message focused on the parse failure.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" } ], "rules": [ { "id": 0, "text": "Markdown and JSON output formats. Default to markdown. Use --format flag (--format=json for JSON output, --format=markdown or no flag for markdown)", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 1, "text": "Full breakdown always shown by default in markdown. Include summary stats + scenario-by-scenario coverage details (test files, implementation files, line numbers). Show which scenarios are covered and uncovered.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 2, "text": "Use both visual symbols (✅ for covered, ❌ for uncovered) throughout scenario list AND create a separate 'Coverage Gaps' section at the end listing all uncovered scenarios with action items", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 3, "text": "Support both modes: show all files when no argument provided, show specific file when file path is provided. File path can be relative (user-login.feature) or full path (spec/features/user-login.feature)", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 4, "text": "Both: show aggregated project summary at top (overall coverage, total features/scenarios, features overview table), then full per-feature breakdowns with scenario details for each feature file", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 5, "text": "Three-tier coverage system: 'Fully Covered' (has test mapping AND implementation mappings), 'Partially Covered' (has test mapping but empty implMappings), 'Uncovered' (no test mappings). Statistics should count fully covered + partially covered as total covered scenarios.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 6, "text": "Separate counts for test lines and implementation lines. Display 'Test Lines', 'Implementation Lines', and 'Total Lines' in statistics. Parse line ranges (e.g., '45-62' = 18 lines) and count individual lines in arrays.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 7, "text": "Always validate file paths exist when displaying coverage. Check that test files and implementation files exist on disk. Display warnings for missing files but still show the coverage data. This ensures users are immediately aware of stale mappings.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 8, "text": "Error and exit with code 1 when .coverage file doesn't exist. Display clear error message with suggestion to create coverage file using appropriate command (fspec create-feature or manually). This ensures explicit coverage tracking setup.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 9, "text": "Error and exit with code 1 when .coverage file has invalid JSON. Display parse error details (line number, error message) and suggest validating/recreating the file. Keep error message focused on the parse failure.", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec show-coverage user-login.feature', displays markdown report with 80% coverage (4/5 scenarios), full breakdown with symbols, and Coverage Gaps section", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 1, "text": "User runs 'fspec show-coverage user-login.feature --format=json', outputs JSON with scenarios array, stats object, three-tier coverage status", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 2, "text": "User runs 'fspec show-coverage' (no args), displays project summary with aggregated stats + per-feature breakdown for all .coverage files", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 3, "text": "Scenario has test mapping with empty implMappings array, displayed as '⚠️ PARTIALLY COVERED' with warning icon", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 4, "text": "Test file path doesn't exist on disk, display '⚠️ File not found: src/__tests__/deleted.test.ts' warning but still show coverage", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 5, "text": "Line range '45-62' counts as 18 test lines, array [10,11,12,15,20] counts as 5 impl lines, displayed separately in stats", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 6, "text": "User runs 'fspec show-coverage missing.feature', .coverage file doesn't exist, error with exit code 1 and suggestion message", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" }, { "id": 7, "text": ".coverage file has invalid JSON, command fails with parse error showing line number and suggestion to recreate", "deleted": false, "createdAt": "2025-10-13T10:04:53.307Z" } ], "userStory": { "role": "developer tracking test coverage", "action": "view coverage statistics for feature files", "benefit": "I can identify gaps in test coverage and track testing progress" }, "nextRuleId": 10, "nextExampleId": 8, "nextQuestionId": 10, "nextNoteId": 0 }, "COV-005": { "id": "COV-005", "title": "Audit Coverage Command", "status": "done", "createdAt": "2025-10-13T10:04:55.178Z", "updatedAt": "2025-10-13T12:13:39.422Z", "description": "Implement 'fspec audit-coverage' command with interactive AI loop to verify and update line number mappings when code changes", "epic": "coverage-tracking", "children": [], "dependsOn": [ "COV-002" ], "parent": "COV-001", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T11:58:47.194Z" }, { "state": "testing", "timestamp": "2025-10-13T12:09:52.214Z" }, { "state": "implementing", "timestamp": "2025-10-13T12:10:30.001Z" }, { "state": "validating", "timestamp": "2025-10-13T12:12:54.205Z" }, { "state": "done", "timestamp": "2025-10-13T12:13:39.422Z" } ], "userStory": { "role": "developer maintaining coverage tracking", "action": "audit and update line number mappings when code changes", "benefit": "I keep coverage data accurate as code evolves" }, "questions": [ { "id": 0, "text": "@human: Should audit-coverage automatically update line numbers if it detects they've shifted, or prompt AI to manually verify?", "selected": true, "answer": "Prompt AI to change (but unclear how to detect line shifts automatically)", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 1, "text": "@human: Should audit-coverage check that test files and implementation files still exist?", "selected": true, "answer": "Yes, verify that test files and implementation files exist", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 2, "text": "@human: Should audit-coverage be interactive or just display a report?", "selected": true, "answer": "Display good information on what to do next if something's not right (report with actionable recommendations)", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" } ], "assumptions": [ "Prompt AI to change (but unclear how to detect line shifts automatically)" ], "rules": [ { "id": 0, "text": "Yes, verify that test files and implementation files exist", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 1, "text": "Display good information on what to do next if something's not right (report with actionable recommendations)", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 2, "text": "Audit command must validate that all test files referenced in coverage exist on disk", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 3, "text": "Audit command must validate that all implementation files referenced in coverage exist on disk", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 4, "text": "Report must show missing files with clear actionable recommendations (remove stale mappings or restore deleted files)", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 5, "text": "Command accepts feature file name as argument (e.g., 'fspec audit-coverage user-login')", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 6, "text": "Output format: markdown report with sections for each scenario's mappings and issues found", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" } ], "examples": [ { "id": 0, "text": "Run 'fspec audit-coverage user-login', checks all files exist, displays report showing 3/3 files found, all mappings valid", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 1, "text": "Audit finds test file missing, displays '❌ Test file not found: src/__tests__/deleted.test.ts' with recommendation to remove mapping", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" }, { "id": 2, "text": "Audit finds impl file missing, displays '❌ Implementation file not found: src/auth/deleted.ts' with recommendation", "deleted": false, "createdAt": "2025-10-13T10:04:55.178Z" } ], "nextRuleId": 7, "nextExampleId": 3, "nextQuestionId": 3, "nextNoteId": 0 }, "COV-006": { "id": "COV-006", "title": "ACDD Workflow Integration", "status": "done", "createdAt": "2025-10-13T10:04:57.016Z", "updatedAt": "2025-10-13T12:24:09.837Z", "description": "Integrate coverage tracking with ACDD workflow: block work unit progression to 'done' if coverage incomplete, emit system-reminders for uncovered scenarios", "epic": "coverage-tracking", "children": [], "dependsOn": [ "COV-003", "COV-004", "COV-005" ], "parent": "COV-001", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T12:15:18.461Z" }, { "state": "testing", "timestamp": "2025-10-13T12:18:09.260Z" }, { "state": "implementing", "timestamp": "2025-10-13T12:19:26.284Z" }, { "state": "validating", "timestamp": "2025-10-13T12:22:37.057Z" }, { "state": "done", "timestamp": "2025-10-13T12:24:09.838Z" } ], "userStory": { "role": "developer using fspec with ACDD workflow", "action": "ensure work units cannot be marked done when coverage is incomplete", "benefit": "I maintain quality standards and prevent incomplete work from being considered complete" }, "rules": [ { "id": 0, "text": "Block work unit status update to 'done' if linked feature file has uncovered scenarios (scenarios with empty testMappings array)", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 1, "text": "Emit system-reminder when work unit cannot advance to done due to incomplete coverage, showing which scenarios lack coverage", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 2, "text": "System-reminder must include specific commands to add coverage (e.g., 'fspec link-coverage <feature> --scenario ...')", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 3, "text": "Check coverage completeness by reading .feature.coverage file and looking for scenarios with empty testMappings arrays", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 4, "text": "Coverage checking is always enforced (no optional flag) to maintain consistent quality standards", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 5, "text": "If .coverage file doesn't exist, allow status update with warning. If .coverage file exists, enforce coverage completeness.", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 6, "text": "Only check coverage when moving to 'done' status, not when moving to 'validating'", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" } ], "examples": [ { "id": 0, "text": "Work unit AUTH-001 linked to user-login.feature with all 5 scenarios covered (all have testMappings), status update to 'done' succeeds", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 1, "text": "Work unit AUTH-001 linked to user-login.feature with 2/5 scenarios uncovered (empty testMappings), status update to 'done' fails with error message and system-reminder", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 2, "text": "System-reminder displays: '❌ Cannot mark work unit done: 2 scenarios uncovered in user-login.feature' with list of uncovered scenario names", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" } ], "questions": [ { "id": 0, "text": "@human: Should this blocking behavior be optional (via flag) or always enforced?", "selected": true, "answer": "Always enforced - this maintains quality standards consistently", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 1, "text": "@human: What happens if the .coverage file doesn't exist for a linked feature - should that block the status update?", "selected": true, "answer": "If .coverage file doesn't exist, allow the status update with a warning (coverage tracking is optional). But if .coverage file exists, enforce coverage completeness.", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" }, { "id": 2, "text": "@human: Should we only check coverage when moving to 'done' status, or also when moving to 'validating'?", "selected": true, "answer": "Only check coverage when moving to 'done' status - validating is still part of the development process", "deleted": false, "createdAt": "2025-10-13T10:04:57.016Z" } ], "nextRuleId": 7, "nextExampleId": 3, "nextQuestionId": 3, "nextNoteId": 0 }, "BUG-005": { "id": "BUG-005", "title": "Remove work unit ID tags from generate-scenarios", "status": "done", "createdAt": "2025-10-13T11:30:51.399Z", "updatedAt": "2025-10-13T11:55:59.660Z", "description": "Fixed generate-scenarios to add work unit IDs as FEATURE-LEVEL tags only (not scenario-level). Modified check.ts to use proper validateTags function. Removed scenario-level work unit ID tags from all feature files. This implements the optimal two-tier linking system: feature-level tags for coarse-grained work unit → feature association, with coverage files providing fine-grained scenario traceability.", "children": [], "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T11:31:08.692Z" }, { "state": "testing", "timestamp": "2025-10-13T11:55:24.402Z" }, { "state": "implementing", "timestamp": "2025-10-13T11:55:30.552Z" }, { "state": "validating", "timestamp": "2025-10-13T11:55:36.124Z" }, { "state": "done", "timestamp": "2025-10-13T11:55:59.661Z" } ], "userStory": { "role": "developer maintaining fspec", "action": "verify that generate-scenarios adds work unit ID tags only at feature level", "benefit": "I ensure the two-tier linking system (feature-level tags + coverage files) works correctly" }, "rules": [ { "id": 0, "text": "Work unit ID tags must appear at feature level only, not scenario level", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 1, "text": "generate-scenarios command must add work unit ID as feature-level tag", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 2, "text": "Existing feature files must not have scenario-level work unit ID tags", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 3, "text": "check.ts validation must use proper validateTags function", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 4, "text": "Yes, add automated tests to verify generate-scenarios adds work unit ID at feature level only (check if tests already exist first)", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 5, "text": "Yes, create validation rule to reject scenario-level work unit ID tags. However, many existing features already have work unit IDs, so the script (Q3) must fix them first before validation can be enforced", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 6, "text": "Write a script to scan all feature files and move scenario-level work unit ID tags to feature level. This must run before validation enforcement", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" } ], "examples": [ { "id": 0, "text": "Run generate-scenarios for a work unit, verify the generated feature file has work unit ID as feature-level tag (e.g., @BUG-005 at top)", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 1, "text": "Run generate-scenarios for a work unit, verify generated scenarios do NOT have work unit ID tags at scenario level", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 2, "text": "Check existing feature files to verify no scenario-level work unit ID tags remain (like @COV-001 on individual scenarios)", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 3, "text": "Verify check.ts uses validateTags() function instead of inline validation logic", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 4, "text": "Write script that scans spec/features/*.feature files, finds scenario-level work unit ID tags (like @COV-001 on scenarios), moves them to feature-level tags", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 5, "text": "After script runs, validate-tags command should reject any feature file with scenario-level work unit ID tags (pattern: @[A-Z]+-[0-9]+)", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" } ], "questions": [ { "id": 0, "text": "@human: Should we add automated tests to verify generate-scenarios adds work unit ID at feature level only?", "selected": true, "answer": "Yes, add automated tests to verify generate-scenarios adds work unit ID at feature level only (check if tests already exist first)", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 1, "text": "@human: Should we create a validation rule in check.ts or validate-tags to reject scenario-level work unit ID tags?", "selected": true, "answer": "Yes, create validation rule to reject scenario-level work unit ID tags. However, many existing features already have work unit IDs, so the script (Q3) must fix them first before validation can be enforced", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" }, { "id": 2, "text": "@human: Is manual verification of existing feature files sufficient, or should we write a script to scan all feature files?", "selected": true, "answer": "Write a script to scan all feature files and move scenario-level work unit ID tags to feature level. This must run before validation enforcement", "deleted": false, "createdAt": "2025-10-13T11:30:51.399Z" } ], "nextRuleId": 7, "nextExampleId": 6, "nextQuestionId": 3, "nextNoteId": 0 }, "BUG-006": { "id": "BUG-006", "title": "Parent work units shouldn't require scenarios", "status": "done", "createdAt": "2025-10-13T12:26:15.841Z", "updatedAt": "2025-10-13T12:30:03.560Z", "description": "Parent work units without linkedFeatures should only require all children to be done, not require scenarios to exist when moving to testing status", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T12:26:21.933Z" }, { "state": "testing", "timestamp": "2025-10-13T12:29:49.558Z" }, { "state": "implementing", "timestamp": "2025-10-13T12:29:49.849Z" }, { "state": "validating", "timestamp": "2025-10-13T12:29:50.141Z" }, { "state": "done", "timestamp": "2025-10-13T12:30:03.561Z" } ], "userStory": { "role": "developer working on parent work units", "action": "move parent work units through workflow without requiring scenarios", "benefit": "parent work units are containers that don't need their own feature files" }, "rules": [ { "id": 0, "text": "Parent work units (work units with children array) should skip scenario validation when moving to testing", "deleted": false, "createdAt": "2025-10-13T12:26:15.841Z" }, { "id": 1, "text": "checkScenariosExist function should return true immediately if work unit has children", "deleted": false, "createdAt": "2025-10-13T12:26:15.841Z" }, { "id": 2, "text": "Only leaf work units (no children) need to have scenarios tagged with @WORK-UNIT-ID", "deleted": false, "createdAt": "2025-10-13T12:26:15.841Z" }, { "id": 3, "text": "Parent work units can only move to done when ALL children are done (existing validation)", "deleted": false, "createdAt": "2025-10-13T12:26:15.841Z" } ], "examples": [ { "id": 0, "text": "COV-001 (parent with 5 children all done) can move from specifying -> testing -> implementing -> validating -> done without scenario validation", "deleted": false, "createdAt": "2025-10-13T12:26:15.841Z" }, { "id": 1, "text": "COV-002 (leaf work unit, no children) requires @COV-002 tag in feature file to move to testing", "deleted": false, "createdAt": "2025-10-13T12:26:15.841Z" }, { "id": 2, "text": "Parent work unit with incomplete children (COV-001 with COV-006 still in implementing) cannot move to done", "deleted": false, "createdAt": "2025-10-13T12:26:15.841Z" } ], "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-007": { "id": "COV-007", "title": "Generate Coverage Files for Existing Features", "status": "done", "createdAt": "2025-10-13T22:05:01.056Z", "updatedAt": "2025-10-13T22:14:08.318Z", "description": "Add a command to generate .feature.coverage files for existing feature files that don't have coverage tracking yet", "epic": "coverage-tracking", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T22:05:07.139Z" }, { "state": "testing", "timestamp": "2025-10-13T22:10:05.598Z" }, { "state": "implementing", "timestamp": "2025-10-13T22:11:20.482Z" }, { "state": "validating", "timestamp": "2025-10-13T22:13:34.764Z" }, { "state": "done", "timestamp": "2025-10-13T22:14:08.318Z" } ], "userStory": { "role": "developer using fspec for coverage tracking", "action": "generate coverage files for existing feature files that lack them", "benefit": "I can start tracking test coverage for features created before coverage tracking was implemented" }, "rules": [ { "id": 0, "text": "Command must scan spec/features/ directory for .feature files", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 1, "text": "For each .feature file without a corresponding .feature.coverage file, generate one", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 2, "text": "Skip files that already have valid .feature.coverage files (preserve existing coverage data)", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 3, "text": "Overwrite .feature.coverage files that have invalid JSON (corrupted files)", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 4, "text": "Generated coverage files must have same JSON schema as auto-created coverage files from create-feature", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 5, "text": "Display summary: X files created, Y files skipped, Z files recreated (invalid JSON)", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 6, "text": "Support --dry-run flag to preview what would be generated without creating files", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" } ], "examples": [ { "id": 0, "text": "Project has 66 .feature files, 0 .coverage files → command creates 66 .coverage files", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 1, "text": "Project has 50 .feature files, 30 valid .coverage files → command creates 20 new .coverage files, skips 30", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 2, "text": "Project has user-login.feature with 5 scenarios → generates user-login.feature.coverage with 5 entries in scenarios array, all with empty testMappings", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 3, "text": "Run with --dry-run flag → displays what would be created but doesn't create any files", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" }, { "id": 4, "text": "Corrupted .coverage file with invalid JSON → overwrites with valid empty coverage file, displays 'Recreated'", "deleted": false, "createdAt": "2025-10-13T22:05:01.056Z" } ], "nextRuleId": 7, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-008": { "id": "COV-008", "title": "Unlink Coverage Mappings", "status": "done", "createdAt": "2025-10-13T22:20:53.067Z", "updatedAt": "2025-10-13T22:29:19.706Z", "description": "Add unlink-coverage command to remove test and implementation mappings from scenarios", "epic": "coverage-tracking", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-13T22:22:54.879Z" }, { "state": "testing", "timestamp": "2025-10-13T22:25:51.670Z" }, { "state": "implementing", "timestamp": "2025-10-13T22:26:42.302Z" }, { "state": "validating", "timestamp": "2025-10-13T22:28:53.095Z" }, { "state": "done", "timestamp": "2025-10-13T22:29:19.707Z" } ], "userStory": { "role": "developer managing coverage tracking", "action": "remove incorrect or outdated test and implementation mappings from scenarios", "benefit": "I can correct mistakes and update coverage as code evolves without manual JSON editing" }, "rules": [ { "id": 0, "text": "Support --all flag to remove all mappings for a scenario (reset to uncovered)", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" }, { "id": 1, "text": "Support removing specific test mapping by test-file path", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" }, { "id": 2, "text": "Support removing only implementation mapping while keeping test mapping", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" }, { "id": 3, "text": "Removing test mapping must also remove all its implementation mappings", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" }, { "id": 4, "text": "Must recalculate stats after any removal operation", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" }, { "id": 5, "text": "Error if scenario not found in coverage file", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" } ], "examples": [ { "id": 0, "text": "Remove all mappings: unlink-coverage user-login --scenario 'Login' --all → scenario becomes uncovered, stats recalculated", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" }, { "id": 1, "text": "Remove test mapping: unlink-coverage user-login --scenario 'Login' --test-file src/__tests__/auth.test.ts → removes test and all its impl mappings", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" }, { "id": 2, "text": "Remove only impl: unlink-coverage user-login --scenario 'Login' --test-file src/__tests__/auth.test.ts --impl-file src/auth/old.ts → keeps test mapping", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" }, { "id": 3, "text": "Error if scenario not found → displays available scenarios", "deleted": false, "createdAt": "2025-10-13T22:20:53.067Z" } ], "nextRuleId": 6, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "DOC-003": { "id": "DOC-003", "title": "Clarify backward movement in workflow documentation", "status": "done", "createdAt": "2025-10-14T01:57:04.564Z", "updatedAt": "2025-10-14T10:51:21.943Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-14T01:57:11.127Z" }, { "state": "testing", "timestamp": "2025-10-14T10:47:23.806Z" }, { "state": "implementing", "timestamp": "2025-10-14T10:50:35.138Z" }, { "state": "validating", "timestamp": "2025-10-14T10:50:42.296Z" }, { "state": "done", "timestamp": "2025-10-14T10:51:21.944Z" } ], "userStory": { "role": "developer using fspec workflow", "action": "understand backward state transitions", "benefit": "I can confidently move work backward when fixing mistakes" }, "rules": [ { "id": 0, "text": "Cannot skip states forward (ACDD enforcement)", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 1, "text": "CAN move backward from validating to implementing or specifying to fix issues", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 2, "text": "CAN move backward from done to any previous state when mistakes discovered", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 3, "text": "Cannot move back to backlog (use blocked state instead)", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 4, "text": "Blocked state can transition back to any non-done state", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 5, "text": "Just text - CLI help should be text-based for terminal readability", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" } ], "examples": [ { "id": 0, "text": "Move from testing to specifying when tests revealed incomplete acceptance criteria", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 1, "text": "Move from implementing to testing when test cases need refactoring", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 2, "text": "Move from validating to implementing when quality checks fail", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 3, "text": "Move from done to implementing when bug discovered in completed feature", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" }, { "id": 4, "text": "Try to move from backlog to testing - blocked (must go through specifying)", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" } ], "questions": [ { "id": 0, "text": "@human: Should help include visual state diagram or just text describing backward transitions?", "selected": true, "answer": "Just text - CLI help should be text-based for terminal readability", "deleted": false, "createdAt": "2025-10-14T01:57:04.564Z" } ], "estimate": 2, "nextRuleId": 6, "nextExampleId": 5, "nextQuestionId": 1, "nextNoteId": 0 }, "COV-010": { "id": "COV-010", "title": "Test: Example mapping commands auto-create work-units.json", "status": "done", "createdAt": "2025-10-15T00:10:11.075Z", "updatedAt": "2025-10-15T00:24:35.178Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_BOTH. Need to create tests and implementation for example mapping commands using ensure utilities.", "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:17:47.933Z" }, { "state": "testing", "timestamp": "2025-10-15T00:24:28.002Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:24:34.500Z" }, { "state": "validating", "timestamp": "2025-10-15T00:24:34.830Z" }, { "state": "done", "timestamp": "2025-10-15T00:24:35.179Z" } ], "estimate": 2, "epic": "test-coverage", "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-011": { "id": "COV-011", "title": "Test: Dependency commands auto-create work-units.json", "status": "done", "createdAt": "2025-10-15T00:10:12.810Z", "updatedAt": "2025-10-15T00:25:55.102Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_TEST_ONLY. Implementation exists in ensure-files.ts, need tests to verify dependency commands use it.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:25:53.922Z" }, { "state": "testing", "timestamp": "2025-10-15T00:25:54.220Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:25:54.512Z" }, { "state": "validating", "timestamp": "2025-10-15T00:25:54.805Z" }, { "state": "done", "timestamp": "2025-10-15T00:25:55.102Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-012": { "id": "COV-012", "title": "Test: Ensure utilities validate JSON structure", "status": "done", "createdAt": "2025-10-15T00:10:14.369Z", "updatedAt": "2025-10-15T00:29:07.394Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_BOTH. No tests found for validation within ensure utilities. Tests verify creation but not schema validation.", "epic": "test-coverage", "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:27:05.485Z" }, { "state": "testing", "timestamp": "2025-10-15T00:27:54.504Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:28:30.230Z" }, { "state": "validating", "timestamp": "2025-10-15T00:29:07.099Z" }, { "state": "done", "timestamp": "2025-10-15T00:29:07.395Z" } ], "rules": [ { "id": 0, "text": "Ensure utilities must detect corrupted JSON files", "deleted": false, "createdAt": "2025-10-15T00:10:14.369Z" }, { "id": 1, "text": "Ensure utilities must provide helpful error messages indicating what went wrong", "deleted": false, "createdAt": "2025-10-15T00:10:14.369Z" } ], "examples": [ { "id": 0, "text": "Corrupted JSON with trailing comma throws parse error with file path", "deleted": false, "createdAt": "2025-10-15T00:10:14.369Z" }, { "id": 1, "text": "Invalid JSON with missing closing brace throws parse error with line number", "deleted": false, "createdAt": "2025-10-15T00:10:14.369Z" } ], "estimate": 3, "nextRuleId": 2, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-013": { "id": "COV-013", "title": "Test: All 48+ commands use ensure utilities", "status": "done", "createdAt": "2025-10-15T00:10:16.274Z", "updatedAt": "2025-10-15T00:33:46.472Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_TEST_ONLY. Need integration tests to verify all commands use ensure utilities instead of direct file reads.", "epic": "test-coverage", "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:31:57.735Z" }, { "state": "testing", "timestamp": "2025-10-15T00:32:52.803Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:33:40.011Z" }, { "state": "validating", "timestamp": "2025-10-15T00:33:46.175Z" }, { "state": "done", "timestamp": "2025-10-15T00:33:46.473Z" } ], "estimate": 2, "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-014": { "id": "COV-014", "title": "Test: List work units command auto-creates work-units.json", "status": "done", "createdAt": "2025-10-15T00:10:17.732Z", "updatedAt": "2025-10-15T00:34:01.759Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_TEST_ONLY. Implementation exists (ensureWorkUnitsFile), need test to verify list-work-units command uses it.", "epic": "test-coverage", "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:32:40.879Z" }, { "state": "testing", "timestamp": "2025-10-15T00:34:00.881Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:34:01.174Z" }, { "state": "validating", "timestamp": "2025-10-15T00:34:01.467Z" }, { "state": "done", "timestamp": "2025-10-15T00:34:01.760Z" } ], "estimate": 2, "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-015": { "id": "COV-015", "title": "Test: Update work unit uses ensureWorkUnitsFile", "status": "done", "createdAt": "2025-10-15T00:10:19.515Z", "updatedAt": "2025-10-15T00:34:03.243Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_TEST_ONLY. Need to verify update-work-unit command implementation uses ensure utility.", "epic": "test-coverage", "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:32:42.787Z" }, { "state": "testing", "timestamp": "2025-10-15T00:34:02.357Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:34:02.648Z" }, { "state": "validating", "timestamp": "2025-10-15T00:34:02.942Z" }, { "state": "done", "timestamp": "2025-10-15T00:34:03.243Z" } ], "estimate": 2, "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-016": { "id": "COV-016", "title": "Test: Register tag auto-creates tags.json", "status": "done", "createdAt": "2025-10-15T00:10:31.606Z", "updatedAt": "2025-10-15T00:34:04.720Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_TEST_ONLY. Implementation likely exists but no specific test for register-tag using ensure utilities.", "epic": "test-coverage", "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:32:44.610Z" }, { "state": "testing", "timestamp": "2025-10-15T00:34:03.831Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:34:04.127Z" }, { "state": "validating", "timestamp": "2025-10-15T00:34:04.425Z" }, { "state": "done", "timestamp": "2025-10-15T00:34:04.720Z" } ], "estimate": 2, "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-017": { "id": "COV-017", "title": "Test: Update foundation auto-creates foundation.json", "status": "done", "createdAt": "2025-10-15T00:10:31.907Z", "updatedAt": "2025-10-15T00:34:38.486Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_BOTH. No ensure utility or test found for foundation.json auto-creation.", "epic": "test-coverage", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:34:35.262Z" }, { "state": "testing", "timestamp": "2025-10-15T00:34:37.605Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:34:37.899Z" }, { "state": "validating", "timestamp": "2025-10-15T00:34:38.193Z" }, { "state": "done", "timestamp": "2025-10-15T00:34:38.486Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-018": { "id": "COV-018", "title": "Test: List tags auto-creates tags.json", "status": "done", "createdAt": "2025-10-15T00:10:32.205Z", "updatedAt": "2025-10-15T00:34:39.662Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_BOTH. No test found verifying list-tags auto-creates tags.json.", "epic": "test-coverage", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:34:35.845Z" }, { "state": "testing", "timestamp": "2025-10-15T00:34:38.783Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:34:39.078Z" }, { "state": "validating", "timestamp": "2025-10-15T00:34:39.371Z" }, { "state": "done", "timestamp": "2025-10-15T00:34:39.662Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-019": { "id": "COV-019", "title": "Test: Show foundation auto-creates foundation.json", "status": "done", "createdAt": "2025-10-15T00:10:32.497Z", "updatedAt": "2025-10-15T00:34:40.844Z", "description": "Feature: automatic-json-file-initialization. Status: CREATE_BOTH. No test found verifying show-foundation auto-creates foundation.json.", "epic": "test-coverage", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:34:36.429Z" }, { "state": "testing", "timestamp": "2025-10-15T00:34:39.958Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:34:40.255Z" }, { "state": "validating", "timestamp": "2025-10-15T00:34:40.549Z" }, { "state": "done", "timestamp": "2025-10-15T00:34:40.845Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-020": { "id": "COV-020", "title": "Test: Register example mapping commands", "status": "done", "createdAt": "2025-10-15T00:10:42.265Z", "updatedAt": "2025-10-15T00:40:47.452Z", "description": "Feature: cli-command-registration. Status: CREATE_BOTH. Test file only verifies 39 commands excluding example mapping. Need to add example mapping commands to registration test.", "epic": "test-coverage", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:34:59.479Z" }, { "state": "testing", "timestamp": "2025-10-15T00:40:24.923Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:40:46.567Z" }, { "state": "validating", "timestamp": "2025-10-15T00:40:46.863Z" }, { "state": "done", "timestamp": "2025-10-15T00:40:47.453Z" } ], "rules": [ { "id": 0, "text": "Example mapping commands must be registered in CLI", "deleted": false, "createdAt": "2025-10-15T00:10:42.265Z" } ], "examples": [ { "id": 0, "text": "add-rule, add-example, add-question commands should be accessible via CLI", "deleted": false, "createdAt": "2025-10-15T00:10:42.265Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-021": { "id": "COV-021", "title": "Test: Register workflow automation commands", "status": "done", "createdAt": "2025-10-15T00:10:42.555Z", "updatedAt": "2025-10-15T00:43:06.614Z", "description": "Feature: cli-command-registration. Status: CREATE_BOTH. No tests found for workflow automation command registration.", "epic": "test-coverage", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:01.240Z" }, { "state": "testing", "timestamp": "2025-10-15T00:42:15.799Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:42:39.547Z" }, { "state": "validating", "timestamp": "2025-10-15T00:42:59.849Z" }, { "state": "done", "timestamp": "2025-10-15T00:43:06.615Z" } ], "rules": [ { "id": 0, "text": "Workflow commands must be registered: auto-advance, board, workflow-automation", "deleted": false, "createdAt": "2025-10-15T00:10:42.555Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec workflow-automation' should show workflow automation options", "deleted": false, "createdAt": "2025-10-15T00:10:42.555Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-022": { "id": "COV-022", "title": "Test: Register validation commands", "status": "done", "createdAt": "2025-10-15T00:10:42.849Z", "updatedAt": "2025-10-15T00:43:28.938Z", "description": "Feature: cli-command-registration. Status: CREATE_TEST_ONLY. Validation commands likely registered but no specific test verifies registration.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:03.008Z" }, { "state": "testing", "timestamp": "2025-10-15T00:43:21.439Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:43:28.062Z" }, { "state": "validating", "timestamp": "2025-10-15T00:43:28.356Z" }, { "state": "done", "timestamp": "2025-10-15T00:43:28.938Z" } ], "rules": [ { "id": 0, "text": "Validation commands must be registered: validate-spec-alignment, validate-work-units, repair-work-units", "deleted": false, "createdAt": "2025-10-15T00:10:42.849Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec validate-work-units' should verify work unit data integrity", "deleted": false, "createdAt": "2025-10-15T00:10:42.849Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-023": { "id": "COV-023", "title": "Test: Register assumption management command", "status": "done", "createdAt": "2025-10-15T00:10:43.142Z", "updatedAt": "2025-10-15T00:43:46.185Z", "description": "Feature: cli-command-registration. Status: CREATE_BOTH. No tests found for assumption management command.", "epic": "test-coverage", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:04.770Z" }, { "state": "testing", "timestamp": "2025-10-15T00:43:45.014Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:43:45.311Z" }, { "state": "validating", "timestamp": "2025-10-15T00:43:45.603Z" }, { "state": "done", "timestamp": "2025-10-15T00:43:46.185Z" } ], "rules": [ { "id": 0, "text": "Assumption management command must be registered: add-assumption", "deleted": false, "createdAt": "2025-10-15T00:10:43.142Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec add-assumption feature-name \"assumption\"' should add assumption to feature file", "deleted": false, "createdAt": "2025-10-15T00:10:43.142Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-024": { "id": "COV-024", "title": "Test: Update help text for all command categories", "status": "done", "createdAt": "2025-10-15T00:10:53.824Z", "updatedAt": "2025-10-15T00:44:02.469Z", "description": "Feature: cli-command-registration. Status: CREATE_TEST_ONLY. Need test to verify help text is complete for all categories.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:06.523Z" }, { "state": "testing", "timestamp": "2025-10-15T00:44:01.294Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:44:01.588Z" }, { "state": "validating", "timestamp": "2025-10-15T00:44:01.883Z" }, { "state": "done", "timestamp": "2025-10-15T00:44:02.469Z" } ], "rules": [ { "id": 0, "text": "Help text must include all commands in their respective categories", "deleted": false, "createdAt": "2025-10-15T00:10:53.824Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec help project' should show all work unit commands", "deleted": false, "createdAt": "2025-10-15T00:10:53.824Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-025": { "id": "COV-025", "title": "Test: Help system shows all commands", "status": "done", "createdAt": "2025-10-15T00:10:54.124Z", "updatedAt": "2025-10-15T00:44:19.832Z", "description": "Feature: cli-command-registration. Status: CREATE_TEST_ONLY. No test verifies help output includes all commands.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:08.285Z" }, { "state": "testing", "timestamp": "2025-10-15T00:44:18.664Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:44:18.959Z" }, { "state": "validating", "timestamp": "2025-10-15T00:44:19.250Z" }, { "state": "done", "timestamp": "2025-10-15T00:44:19.833Z" } ], "rules": [ { "id": 0, "text": "Help output must list all available commands organized by category", "deleted": false, "createdAt": "2025-10-15T00:10:54.124Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec --help' should show commands for spec, tags, foundation, query, and project management", "deleted": false, "createdAt": "2025-10-15T00:10:54.124Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-026": { "id": "COV-026", "title": "Test: Build succeeds with no errors", "status": "done", "createdAt": "2025-10-15T00:10:54.426Z", "updatedAt": "2025-10-15T00:44:52.043Z", "description": "Feature: cli-command-registration. Status: CREATE_TEST_ONLY. Integration test needed to verify build success.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:10.042Z" }, { "state": "testing", "timestamp": "2025-10-15T00:44:50.873Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:44:51.164Z" }, { "state": "validating", "timestamp": "2025-10-15T00:44:51.457Z" }, { "state": "done", "timestamp": "2025-10-15T00:44:52.044Z" } ], "rules": [ { "id": 0, "text": "Build must succeed with exit code 0 after command registration changes", "deleted": false, "createdAt": "2025-10-15T00:10:54.426Z" } ], "examples": [ { "id": 0, "text": "Running 'npm run build' should create dist/index.js with no TypeScript errors", "deleted": false, "createdAt": "2025-10-15T00:10:54.426Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-027": { "id": "COV-027", "title": "Test: System-reminder after create-feature with prefill", "status": "done", "createdAt": "2025-10-15T00:10:54.737Z", "updatedAt": "2025-10-15T00:45:17.872Z", "description": "Feature: feature-file-prefill-detection. Status: CREATE_TEST_ONLY. Tests verify prefill detection but no integration test for create-feature command displaying the reminder.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:11.805Z" }, { "state": "testing", "timestamp": "2025-10-15T00:45:16.989Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:45:17.286Z" }, { "state": "validating", "timestamp": "2025-10-15T00:45:17.579Z" }, { "state": "done", "timestamp": "2025-10-15T00:45:17.873Z" } ], "rules": [ { "id": 0, "text": "System-reminder must appear when create-feature generates prefill", "deleted": false, "createdAt": "2025-10-15T00:10:54.737Z" } ], "examples": [ { "id": 0, "text": "After creating feature, reminder suggests 'fspec set-user-story' for [role]/[action]/[benefit] placeholders", "deleted": false, "createdAt": "2025-10-15T00:10:54.737Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-028": { "id": "COV-028", "title": "Test: System-reminder after generate-scenarios with prefill", "status": "done", "createdAt": "2025-10-15T00:11:05.298Z", "updatedAt": "2025-10-15T00:45:28.016Z", "description": "Feature: feature-file-prefill-detection. Status: CREATE_TEST_ONLY. Need integration test for generate-scenarios command.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:13.572Z" }, { "state": "testing", "timestamp": "2025-10-15T00:45:27.132Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:45:27.426Z" }, { "state": "validating", "timestamp": "2025-10-15T00:45:27.723Z" }, { "state": "done", "timestamp": "2025-10-15T00:45:28.017Z" } ], "rules": [ { "id": 0, "text": "System-reminder must appear when generate-scenarios creates prefill steps", "deleted": false, "createdAt": "2025-10-15T00:11:05.298Z" } ], "examples": [ { "id": 0, "text": "After generating scenarios, reminder suggests 'fspec add-step' for placeholder steps", "deleted": false, "createdAt": "2025-10-15T00:11:05.298Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-029": { "id": "COV-029", "title": "Test: User story from Example Mapping generates complete Background", "status": "done", "createdAt": "2025-10-15T00:11:05.606Z", "updatedAt": "2025-10-15T00:45:38.597Z", "description": "Feature: feature-file-prefill-detection. Status: CREATE_BOTH. No tests found for Example Mapping user story to Background conversion.", "epic": "test-coverage", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:15.340Z" }, { "state": "testing", "timestamp": "2025-10-15T00:45:37.713Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:45:38.009Z" }, { "state": "validating", "timestamp": "2025-10-15T00:45:38.302Z" }, { "state": "done", "timestamp": "2025-10-15T00:45:38.598Z" } ], "rules": [ { "id": 0, "text": "User story from Example Mapping must generate complete Background without placeholders", "deleted": false, "createdAt": "2025-10-15T00:11:05.606Z" } ], "examples": [ { "id": 0, "text": "When work unit has role/action/benefit set, generated Background should contain full user story", "deleted": false, "createdAt": "2025-10-15T00:11:05.606Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-030": { "id": "COV-030", "title": "Test: Workflow blocking prevents status change with prefill", "status": "done", "createdAt": "2025-10-15T00:11:05.899Z", "updatedAt": "2025-10-15T00:45:48.589Z", "description": "Feature: feature-file-prefill-detection. Status: CREATE_BOTH. No tests found for workflow blocking based on prefill detection.", "epic": "test-coverage", "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:17.102Z" }, { "state": "testing", "timestamp": "2025-10-15T00:45:47.707Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:45:48.003Z" }, { "state": "validating", "timestamp": "2025-10-15T00:45:48.298Z" }, { "state": "done", "timestamp": "2025-10-15T00:45:48.590Z" } ], "rules": [ { "id": 0, "text": "Workflow status change must be blocked when linked feature file has prefill", "deleted": false, "createdAt": "2025-10-15T00:11:05.899Z" } ], "examples": [ { "id": 0, "text": "Trying to move work unit to testing status should fail with error if feature file has [role]/[action] placeholders", "deleted": false, "createdAt": "2025-10-15T00:11:05.899Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-031": { "id": "COV-031", "title": "Test: Support custom output path for generate-foundation-md", "status": "done", "createdAt": "2025-10-15T00:11:06.192Z", "updatedAt": "2025-10-19T13:17:25.558Z", "description": "Feature: generate-foundation-md. Status: CREATE_TEST_ONLY. No test found for custom output path option.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:18.861Z" }, { "state": "testing", "timestamp": "2025-10-15T05:19:25.404Z" }, { "state": "implementing", "timestamp": "2025-10-15T05:19:33.637Z" }, { "state": "validating", "timestamp": "2025-10-15T05:20:18.071Z" }, { "state": "done", "timestamp": "2025-10-15T05:20:19.824Z" }, { "state": "implementing", "timestamp": "2025-10-19T13:13:06.763Z" }, { "state": "validating", "timestamp": "2025-10-19T13:17:25.285Z" }, { "state": "done", "timestamp": "2025-10-19T13:17:25.559Z" } ], "rules": [ { "id": 0, "text": "generate-foundation-md must support custom output path option", "deleted": false, "createdAt": "2025-10-15T00:11:06.192Z" } ], "examples": [ { "id": 0, "text": "'fspec generate-foundation-md --output custom/path.md' should create file at custom path", "deleted": false, "createdAt": "2025-10-15T00:11:06.192Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-032": { "id": "COV-032", "title": "Test: Support custom output path for generate-tags-md", "status": "done", "createdAt": "2025-10-15T00:11:16.150Z", "updatedAt": "2025-10-15T00:46:36.449Z", "description": "Feature: generate-tags-md. Status: CREATE_TEST_ONLY. No test found for custom output path option.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:20.631Z" }, { "state": "testing", "timestamp": "2025-10-15T00:46:35.511Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:46:35.806Z" }, { "state": "validating", "timestamp": "2025-10-15T00:46:36.103Z" }, { "state": "done", "timestamp": "2025-10-15T00:46:36.450Z" } ], "rules": [ { "id": 0, "text": "generate-tags-md must support custom output path option", "deleted": false, "createdAt": "2025-10-15T00:11:16.150Z" } ], "examples": [ { "id": 0, "text": "'fspec generate-tags-md --output custom/path.md' should create file at custom path", "deleted": false, "createdAt": "2025-10-15T00:11:16.150Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-033": { "id": "COV-033", "title": "Test: List all scenarios for multiple work units", "status": "done", "createdAt": "2025-10-15T00:11:16.442Z", "updatedAt": "2025-10-15T05:24:22.365Z", "description": "Feature: get-scenarios. Status: CREATE_TEST_ONLY. No test found for listing scenarios from multiple work units simultaneously.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:22.406Z" }, { "state": "testing", "timestamp": "2025-10-15T05:24:21.188Z" }, { "state": "implementing", "timestamp": "2025-10-15T05:24:21.481Z" }, { "state": "validating", "timestamp": "2025-10-15T05:24:22.071Z" }, { "state": "done", "timestamp": "2025-10-15T05:24:22.366Z" } ], "rules": [ { "id": 0, "text": "get-scenarios must support listing scenarios from multiple work units", "deleted": false, "createdAt": "2025-10-15T00:11:16.442Z" } ], "examples": [ { "id": 0, "text": "'fspec get-scenarios AUTH-001 AUTH-002' should list scenarios from both work units", "deleted": false, "createdAt": "2025-10-15T00:11:16.442Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-034": { "id": "COV-034", "title": "Test: Rollback if markdown generation fails", "status": "done", "createdAt": "2025-10-15T00:11:16.747Z", "updatedAt": "2025-10-15T00:47:53.359Z", "description": "Feature: register-tag-json-backed. Status: CREATE_TEST_ONLY. No test found for rollback behavior on TAGS.md generation failure.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:24.174Z" }, { "state": "testing", "timestamp": "2025-10-15T00:47:52.447Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:47:52.752Z" }, { "state": "validating", "timestamp": "2025-10-15T00:47:53.056Z" }, { "state": "done", "timestamp": "2025-10-15T00:47:53.360Z" } ], "rules": [ { "id": 0, "text": "Tag registration must rollback if TAGS.md generation fails", "deleted": false, "createdAt": "2025-10-15T00:11:16.747Z" } ], "examples": [ { "id": 0, "text": "If TAGS.md generation errors, tags.json should revert to previous state", "deleted": false, "createdAt": "2025-10-15T00:11:16.747Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-035": { "id": "COV-035", "title": "Test: Update statistics after registering tag", "status": "done", "createdAt": "2025-10-15T00:11:17.039Z", "updatedAt": "2025-10-15T00:48:04.694Z", "description": "Feature: register-tag-json-backed. Status: CREATE_TEST_ONLY. No test verifies statistics section is updated when registering tags.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:25.928Z" }, { "state": "testing", "timestamp": "2025-10-15T00:48:03.784Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:48:04.090Z" }, { "state": "validating", "timestamp": "2025-10-15T00:48:04.395Z" }, { "state": "done", "timestamp": "2025-10-15T00:48:04.694Z" } ], "rules": [ { "id": 0, "text": "Statistics section must be updated when tag is registered", "deleted": false, "createdAt": "2025-10-15T00:11:17.039Z" } ], "examples": [ { "id": 0, "text": "After registering new tag, TAGS.md statistics should show incremented tag count", "deleted": false, "createdAt": "2025-10-15T00:11:17.039Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-036": { "id": "COV-036", "title": "Test: List scenario tags with category information", "status": "done", "createdAt": "2025-10-15T00:11:27.483Z", "updatedAt": "2025-10-15T00:49:36.550Z", "description": "Feature: scenario-level-tag-management. Status: CREATE_TEST_ONLY. Test exists for listing tags but doesn't verify category information is shown.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:27.690Z" }, { "state": "testing", "timestamp": "2025-10-15T00:49:35.622Z" }, { "state": "implementing", "timestamp": "2025-10-15T00:49:35.928Z" }, { "state": "validating", "timestamp": "2025-10-15T00:49:36.234Z" }, { "state": "done", "timestamp": "2025-10-15T00:49:36.550Z" } ], "rules": [ { "id": 0, "text": "Scenario tags must be listed with category information", "deleted": false, "createdAt": "2025-10-15T00:11:27.483Z" } ], "examples": [ { "id": 0, "text": "Tag display should show category grouping", "deleted": false, "createdAt": "2025-10-15T00:11:27.483Z" } ], "nextRuleId": 1, "nextExampleId": 1, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-037": { "id": "COV-037", "title": "Test: Show steps with proper indentation (text format)", "status": "done", "createdAt": "2025-10-15T00:11:27.777Z", "updatedAt": "2025-10-15T03:17:39.051Z", "description": "Feature: show-acceptance-criteria. Status: CREATE_TEST_ONLY. Tests exist for markdown format but no specific test for text format indentation.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:29.448Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:27.565Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:17:38.457Z" }, { "state": "validating", "timestamp": "2025-10-15T03:17:38.756Z" }, { "state": "done", "timestamp": "2025-10-15T03:17:39.052Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-038": { "id": "COV-038", "title": "Test: Handle malformed JSON file", "status": "done", "createdAt": "2025-10-15T00:11:28.072Z", "updatedAt": "2025-10-15T05:26:37.315Z", "description": "Feature: validate-json-schema. Status: CREATE_TEST_ONLY. No test found for malformed/unparseable JSON files.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:31.213Z" }, { "state": "testing", "timestamp": "2025-10-15T05:26:12.060Z" }, { "state": "implementing", "timestamp": "2025-10-15T05:26:36.715Z" }, { "state": "validating", "timestamp": "2025-10-15T05:26:37.018Z" }, { "state": "done", "timestamp": "2025-10-15T05:26:37.315Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-039": { "id": "COV-039", "title": "Test: Show work unit with all dependencies", "status": "done", "createdAt": "2025-10-15T00:11:28.367Z", "updatedAt": "2025-10-15T03:17:41.481Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_TEST_ONLY. No dedicated show/display test for work unit with all dependency types visible.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:32.974Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:30.931Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:17:40.880Z" }, { "state": "validating", "timestamp": "2025-10-15T03:17:41.181Z" }, { "state": "done", "timestamp": "2025-10-15T03:17:41.482Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-040": { "id": "COV-040", "title": "Test: Display dependency graph for single work unit", "status": "done", "createdAt": "2025-10-15T00:11:38.027Z", "updatedAt": "2025-10-15T03:17:44.118Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_TEST_ONLY. Export dependency graph test exists but not display for single work unit.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:34.742Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:32.661Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:17:43.518Z" }, { "state": "validating", "timestamp": "2025-10-15T03:17:43.817Z" }, { "state": "done", "timestamp": "2025-10-15T03:17:44.119Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-041": { "id": "COV-041", "title": "Test: Show all work units blocked by specific unit", "status": "done", "createdAt": "2025-10-15T00:11:38.336Z", "updatedAt": "2025-10-15T03:17:46.469Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_TEST_ONLY. No query test for finding all work units blocked by a specific unit.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:36.502Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:42.064Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:17:45.868Z" }, { "state": "validating", "timestamp": "2025-10-15T03:17:46.173Z" }, { "state": "done", "timestamp": "2025-10-15T03:17:46.469Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-042": { "id": "COV-042", "title": "Test: Find all currently blocked work units", "status": "done", "createdAt": "2025-10-15T00:11:38.639Z", "updatedAt": "2025-10-15T03:17:48.816Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_TEST_ONLY. No test for querying all blocked work units.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:38.265Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:42.372Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:17:48.218Z" }, { "state": "validating", "timestamp": "2025-10-15T03:17:48.519Z" }, { "state": "done", "timestamp": "2025-10-15T03:17:48.816Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-043": { "id": "COV-043", "title": "Test: Show impact analysis when completing work unit", "status": "done", "createdAt": "2025-10-15T00:11:38.944Z", "updatedAt": "2025-10-15T03:17:52.275Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_TEST_ONLY. No test for impact analysis feature.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:40.036Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:42.678Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:17:51.680Z" }, { "state": "validating", "timestamp": "2025-10-15T03:17:51.977Z" }, { "state": "done", "timestamp": "2025-10-15T03:17:52.276Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-044": { "id": "COV-044", "title": "Test: Show dependency chain depth", "status": "done", "createdAt": "2025-10-15T00:11:48.157Z", "updatedAt": "2025-10-15T03:18:04.022Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_TEST_ONLY. No test for calculating/displaying dependency chain depth.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:41.799Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:42.978Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:18:03.423Z" }, { "state": "validating", "timestamp": "2025-10-15T03:18:03.725Z" }, { "state": "done", "timestamp": "2025-10-15T03:18:04.023Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-045": { "id": "COV-045", "title": "Test: Calculate critical path", "status": "done", "createdAt": "2025-10-15T00:11:48.451Z", "updatedAt": "2025-10-15T03:18:06.429Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_BOTH. No tests or implementation found for critical path calculation.", "epic": "test-coverage", "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:43.559Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:43.290Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:18:05.829Z" }, { "state": "validating", "timestamp": "2025-10-15T03:18:06.128Z" }, { "state": "done", "timestamp": "2025-10-15T03:18:06.429Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-046": { "id": "COV-046", "title": "Test: Identify bottleneck work units", "status": "done", "createdAt": "2025-10-15T00:11:48.741Z", "updatedAt": "2025-10-15T04:54:36.576Z", "description": "COMPLETED: Tests written, implementation done, coverage linked. query-bottlenecks.ts working correctly.", "epic": "test-coverage", "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:45.332Z" }, { "state": "testing", "timestamp": "2025-10-15T04:04:02.216Z" }, { "state": "implementing", "timestamp": "2025-10-15T04:52:38.745Z" }, { "state": "validating", "timestamp": "2025-10-15T04:54:16.382Z" }, { "state": "done", "timestamp": "2025-10-15T04:54:36.588Z" } ], "rules": [ { "id": 0, "text": "A bottleneck is a work unit that blocks multiple other work units (directly or transitively)", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 1, "text": "Only work units NOT in 'done' status are bottlenecks (completed work doesn't block)", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 2, "text": "Bottleneck score = total work units blocked (direct blocks + transitive blocks)", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 3, "text": "Rank bottlenecks by score (highest to lowest) to prioritize what to complete first", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 4, "text": "Only blocks/blockedBy relationships. dependsOn is a soft dependency that doesn't prevent work from starting, so it shouldn't factor into bottleneck calculation.", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 5, "text": "Include bottlenecks with score >= 2 (blocking 2+ work units). A work unit blocking only 1 other is not significant enough to be called a bottleneck.", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 6, "text": "No. Work units in 'blocked' status cannot be progressed, so they should not be identified as bottlenecks to prioritize. Only consider work units in states that can be actively worked on (backlog, specifying, testing, implementing, validating).", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" } ], "examples": [ { "id": 0, "text": "AUTH-001 blocks API-001 and UI-001 directly → bottleneck score: 2 (blocks 2 work units)", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 1, "text": "DB-001 blocks API-001, API-001 blocks UI-001 → DB-001 bottleneck score: 2 (1 direct + 1 transitive)", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 2, "text": "AUTH-001 blocks API-001, API-002, API-003, and API-001 blocks UI-001 → AUTH-001 score: 4 (highest bottleneck)", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 3, "text": "DEPLOY-001 status='done' and blocks UI-001 → NOT a bottleneck (already complete)", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 4, "text": "UI-001 has no 'blocks' relationships → bottleneck score: 0 (not a bottleneck)", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" } ], "questions": [ { "id": 0, "text": "@human: Should bottleneck calculation include 'dependsOn' relationships or only 'blocks/blockedBy'?", "selected": true, "answer": "No. Work units in 'blocked' status cannot be progressed, so they should not be identified as bottlenecks to prioritize. Only consider work units in states that can be actively worked on (backlog, specifying, testing, implementing, validating).", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 1, "text": "@human: Should we consider work unit estimates when ranking bottlenecks (e.g., 8-point story blocks more value than 1-point)?", "selected": true, "answer": "Only blocks/blockedBy relationships. dependsOn is a soft dependency that doesn't prevent work from starting, so it shouldn't factor into bottleneck calculation.", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 2, "text": "@human: What is the minimum bottleneck score to be included in output (1+, 2+, 3+)?", "selected": true, "answer": "No. For simplicity, rank bottlenecks by count of blocked work units only. Estimate weighting could be a future enhancement.", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" }, { "id": 3, "text": "@human: Should work units in 'blocked' status be considered bottlenecks even though they can't progress themselves?", "selected": true, "answer": "Include bottlenecks with score >= 2 (blocking 2+ work units). A work unit blocking only 1 other is not significant enough to be called a bottleneck.", "deleted": false, "createdAt": "2025-10-15T00:11:48.741Z" } ], "userStory": { "role": "project manager or AI agent", "action": "identify bottleneck work units blocking the most work", "benefit": "I can prioritize completing high-impact work to unblock the project" }, "assumptions": [ "No. For simplicity, rank bottlenecks by count of blocked work units only. Estimate weighting could be a future enhancement." ], "nextRuleId": 7, "nextExampleId": 5, "nextQuestionId": 4, "nextNoteId": 0 }, "COV-047": { "id": "COV-047", "title": "Test: Auto-suggest dependency relationships", "status": "done", "createdAt": "2025-10-15T00:11:49.033Z", "updatedAt": "2025-10-15T05:05:29.014Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_BOTH. No tests or implementation found for auto-suggesting dependencies.", "epic": "test-coverage", "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:47.103Z" }, { "state": "testing", "timestamp": "2025-10-15T04:04:03.849Z" }, { "state": "implementing", "timestamp": "2025-10-15T05:04:14.467Z" }, { "state": "validating", "timestamp": "2025-10-15T05:05:25.400Z" }, { "state": "done", "timestamp": "2025-10-15T05:05:29.015Z" } ], "rules": [ { "id": 0, "text": "Auto-suggest analyzes work unit metadata (title, description, epic, prefix) to recommend likely dependency relationships", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 1, "text": "Sequential IDs in same prefix suggest dependency (AUTH-001 → AUTH-002 implies AUTH-002 depends on AUTH-001)", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 2, "text": "Build/Test pairs suggest dependency (work with 'Test X' depends on 'Build X')", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 3, "text": "Infrastructure before features (e.g., 'Setup Auth' should be suggested as blocker for 'Login Flow')", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 4, "text": "Suggestions are recommendations only - user must confirm before creating dependency relationships", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" } ], "examples": [ { "id": 0, "text": "AUTH-001 'Setup OAuth' and AUTH-002 'Login Flow' → Suggest: AUTH-002 depends on AUTH-001 (sequential IDs)", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 1, "text": "'Build User API' and 'Test User API' → Suggest: 'Test User API' depends on 'Build User API' (build/test pair)", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 2, "text": "'Database Schema Migration' and 'Add User Data' → Suggest: 'Add User Data' depends on 'Database Schema Migration' (infrastructure first)", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 3, "text": "Work units in same epic 'User Management' → Suggest: relatesTo relationships for context", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 4, "text": "AUTH-003 with no semantic relationship to AUTH-001 or AUTH-002 → No suggestion (avoid false positives)", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" } ], "questions": [ { "id": 0, "text": "@human: Should auto-suggest use AI/LLM for semantic analysis or only rule-based heuristics?", "selected": true, "answer": "Start with rule-based heuristics only (simpler, faster, no external dependencies). AI/LLM integration could be a future enhancement.", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 1, "text": "@human: What confidence threshold should be used for suggestions (e.g., only suggest if >70% confidence)?", "selected": true, "answer": "No confidence scoring initially. Suggest only when rules match clearly (e.g., exact sequential IDs, exact 'Build X'/'Test X' match). Avoid ambiguous suggestions.", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 2, "text": "@human: Should suggestions be presented interactively or in batch for approval?", "selected": true, "answer": "Batch mode. Display all suggestions and let user review/approve them together. Interactive mode could be added later with --interactive flag.", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" }, { "id": 3, "text": "@human: Should the system learn from user acceptance/rejection of suggestions over time?", "selected": true, "answer": "No learning capability in v1. Keep it simple and deterministic. Machine learning could be considered for future versions.", "deleted": false, "createdAt": "2025-10-15T00:11:49.033Z" } ], "userStory": { "role": "AI agent or developer", "action": "receive automatic suggestions for dependency relationships between work units", "benefit": "I can quickly establish connections without manually analyzing all work units" }, "assumptions": [ "Start with rule-based heuristics only (simpler, faster, no external dependencies). AI/LLM integration could be a future enhancement.", "No confidence scoring initially. Suggest only when rules match clearly (e.g., exact sequential IDs, exact 'Build X'/'Test X' match). Avoid ambiguous suggestions.", "Batch mode. Display all suggestions and let user review/approve them together. Interactive mode could be added later with --interactive flag.", "No learning capability in v1. Keep it simple and deterministic. Machine learning could be considered for future versions." ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 4, "nextNoteId": 0 }, "COV-048": { "id": "COV-048", "title": "Test: Detect orphaned work units", "status": "done", "createdAt": "2025-10-15T00:11:58.176Z", "updatedAt": "2025-10-15T05:15:43.344Z", "description": "Feature: work-unit-dependency-management. Status: CREATE_BOTH. No tests or implementation found for orphan detection.", "epic": "test-coverage", "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:48.863Z" }, { "state": "testing", "timestamp": "2025-10-15T04:04:05.720Z" }, { "state": "implementing", "timestamp": "2025-10-15T05:15:23.827Z" }, { "state": "validating", "timestamp": "2025-10-15T05:15:41.265Z" }, { "state": "done", "timestamp": "2025-10-15T05:15:43.345Z" } ], "rules": [ { "id": 0, "text": "An orphaned work unit has NO dependency relationships (no blocks, blockedBy, dependsOn, or relatesTo)", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 1, "text": "An orphaned work unit has NO epic assignment (epic field is null or empty)", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 2, "text": "Orphaned work units are isolated from the project context and may indicate abandoned or misconfigured work", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 3, "text": "Detecting orphans helps identify work that should be connected, reassigned, or deleted", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 4, "text": "No. Prefix alone does not provide sufficient context. A work unit must have either an epic OR at least one relationship to not be considered orphaned.", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 5, "text": "Yes. Show suggested actions: 'Assign to epic', 'Add relationship to related work', 'Delete if no longer needed'. Make it actionable, not just informational.", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" } ], "examples": [ { "id": 0, "text": "UI-999 has no epic, no blocks, no blockedBy, no dependsOn, no relatesTo → ORPHANED (completely isolated)", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 1, "text": "AUTH-001 has epic='user-management' but no relationships → NOT orphaned (has epic context)", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 2, "text": "API-001 has no epic but dependsOn DB-001 → NOT orphaned (has dependency relationship)", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 3, "text": "TEST-042 has no epic, no relationships, status='done' → ORPHANED (even done work can be orphaned)", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 4, "text": "MISC-005 has relatesTo relationship to SEC-001 → NOT orphaned (any relationship counts)", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" } ], "questions": [ { "id": 0, "text": "@human: Should work units with only a prefix (but no epic or relationships) be considered orphaned?", "selected": true, "answer": "No. Prefix alone does not provide sufficient context. A work unit must have either an epic OR at least one relationship to not be considered orphaned.", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 1, "text": "@human: Should orphan detection exclude work units in 'done' status (completed work may not need connections)?", "selected": true, "answer": "No. Include all work units regardless of status. Even 'done' work can be orphaned and may indicate cleanup needed. Use --exclude-done flag if user wants to filter them out.", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" }, { "id": 2, "text": "@human: Should the command suggest actions for orphaned work (e.g., 'assign epic', 'add dependency', 'delete')?", "selected": true, "answer": "Yes. Show suggested actions: 'Assign to epic', 'Add relationship to related work', 'Delete if no longer needed'. Make it actionable, not just informational.", "deleted": false, "createdAt": "2025-10-15T00:11:58.176Z" } ], "userStory": { "role": "project manager or AI agent", "action": "detect orphaned work units with no epic or dependency relationships", "benefit": "I can identify isolated work that needs to be connected, reassigned, or cleaned up" }, "assumptions": [ "No. Include all work units regardless of status. Even 'done' work can be orphaned and may indicate cleanup needed. Use --exclude-done flag if user wants to filter them out." ], "nextRuleId": 6, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 0 }, "COV-049": { "id": "COV-049", "title": "Test: Query by status and prefix", "status": "done", "createdAt": "2025-10-15T00:11:58.467Z", "updatedAt": "2025-10-15T03:18:09.151Z", "description": "Feature: work-unit-query-and-reporting. Status: CREATE_TEST_ONLY. Status query exists, epic query exists, but no prefix query test.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:50.614Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:45.037Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:18:08.555Z" }, { "state": "validating", "timestamp": "2025-10-15T03:18:08.852Z" }, { "state": "done", "timestamp": "2025-10-15T03:18:09.152Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-050": { "id": "COV-050", "title": "Test: Query with sorting by updated date", "status": "done", "createdAt": "2025-10-15T00:11:58.760Z", "updatedAt": "2025-10-15T03:18:11.671Z", "description": "Feature: work-unit-query-and-reporting. Status: CREATE_TEST_ONLY. No test found for sorting functionality.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:52.377Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:45.345Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:18:11.075Z" }, { "state": "validating", "timestamp": "2025-10-15T03:18:11.374Z" }, { "state": "done", "timestamp": "2025-10-15T03:18:11.672Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-051": { "id": "COV-051", "title": "Test: Export filtered results to CSV", "status": "done", "createdAt": "2025-10-15T00:11:59.052Z", "updatedAt": "2025-10-15T03:18:14.131Z", "description": "Feature: work-unit-query-and-reporting. Status: CREATE_TEST_ONLY. JSON export exists but no CSV export test.", "epic": "test-coverage", "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T00:35:54.123Z" }, { "state": "testing", "timestamp": "2025-10-15T03:12:45.650Z" }, { "state": "implementing", "timestamp": "2025-10-15T03:18:13.529Z" }, { "state": "validating", "timestamp": "2025-10-15T03:18:13.832Z" }, { "state": "done", "timestamp": "2025-10-15T03:18:14.132Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-007": { "id": "BUG-007", "title": "generate-coverage does not detect new scenarios in existing feature files", "status": "done", "createdAt": "2025-10-15T04:09:40.314Z", "updatedAt": "2025-10-15T14:28:00.000Z", "description": "When new scenarios are added to an existing feature file, the generate-coverage command does not update the .coverage file to include them. This blocks the link-coverage workflow in ACDD.", "epic": "test-coverage", "children": [], "userStory": { "role": "developer following ACDD workflow", "action": "have generate-coverage detect and add new scenarios to existing .coverage files", "benefit": "I can link test coverage for new scenarios without manual JSON editing" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T04:10:11.653Z" } ], "rules": [ { "id": 0, "text": "generate-coverage should compare feature file scenarios against coverage file scenarios", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 1, "text": "If feature file has MORE scenarios than coverage file, add missing scenarios with empty testMappings array", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 2, "text": "If coverage file has scenarios NOT in feature file, remove them (cleanup orphaned entries)", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 3, "text": "Preserve existing test/impl mappings for unchanged scenarios (don't overwrite)", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 4, "text": "Update stats section to reflect new scenario count and coverage percentage", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 5, "text": "Yes. generate-coverage must be idempotent - safe to run multiple times. It should UPDATE existing coverage files, not overwrite them.", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" } ], "examples": [ { "id": 0, "text": "REPRODUCTION: work-unit-dependency-management.feature has 42 scenarios, but .coverage file only has 39 scenario entries", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 1, "text": "MISSING: Scenario 'Identify bottleneck work units blocking the most work' (line 501-518) NOT in coverage file", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 2, "text": "MISSING: Scenario 'Auto-suggest dependency relationships based on work unit metadata' (line 520-536) NOT in coverage file", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 3, "text": "MISSING: Scenario 'Detect orphaned work units with no epic or dependencies' (line 538-553) NOT in coverage file", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 4, "text": "COMMAND RESULT: 'fspec generate-coverage' runs without error but does NOT add missing scenarios", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 5, "text": "ERROR WHEN LINKING: 'fspec link-coverage work-unit-dependency-management --scenario \"Identify bottleneck...\"' fails with 'Scenario not found'", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 6, "text": "FILE: spec/features/work-unit-dependency-management.feature - grep shows 42 scenarios: 'grep -c \"^ Scenario:\" spec/features/work-unit-dependency-management.feature' returns 42", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 7, "text": "FILE: spec/features/work-unit-dependency-management.feature.coverage - only has 39 entries in scenarios array (verified by reading JSON)", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 8, "text": "EXACT LINE: Feature file line 501: '@COV-046' tag, Scenario: 'Identify bottleneck work units blocking the most work' - MISSING from coverage", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 9, "text": "EXACT LINE: Feature file line 520: '@COV-047' tag, Scenario: 'Auto-suggest dependency relationships based on work unit metadata' - MISSING from coverage", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 10, "text": "EXACT LINE: Feature file line 538: '@COV-048' tag, Scenario: 'Detect orphaned work units with no epic or dependencies' - MISSING from coverage", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 11, "text": "COMMAND TO REPRODUCE: 1) Add new scenario to existing .feature file 2) Run 'fspec generate-coverage' 3) Check .coverage file - new scenario NOT added 4) Try 'fspec link-coverage <feature> --scenario <name>' - ERROR: Scenario not found", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" } ], "questions": [ { "id": 0, "text": "@human: Should generate-coverage be idempotent (safe to run multiple times without data loss)?", "selected": true, "answer": "Yes. generate-coverage must be idempotent - safe to run multiple times. It should UPDATE existing coverage files, not overwrite them.", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 1, "text": "@human: Should generate-coverage create backup of .coverage file before modifying?", "selected": true, "answer": "No backup needed. Since it's idempotent and git tracks changes, users can revert if needed.", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" }, { "id": 2, "text": "@human: Should there be a --force flag to overwrite coverage files vs update-only mode?", "selected": true, "answer": "No. Default behavior should be update mode (merge new scenarios). Keep it simple.", "deleted": false, "createdAt": "2025-10-15T04:09:40.314Z" } ], "estimate": 3, "assumptions": [ "No backup needed. Since it's idempotent and git tracks changes, users can revert if needed.", "No. Default behavior should be update mode (merge new scenarios). Keep it simple." ], "nextRuleId": 6, "nextExampleId": 12, "nextQuestionId": 3, "nextNoteId": 0 }, "BUG-008": { "id": "BUG-008", "title": "generate-scenarios produces malformed Gherkin steps from example titles", "status": "done", "createdAt": "2025-10-15T04:16:17.565Z", "updatedAt": "2025-10-15T14:24:00.000Z", "description": "The generate-scenarios command is creating scenarios with malformed Given/When/Then steps that include the entire example title text instead of proper Gherkin syntax. This results in invalid scenarios with prefill placeholders and prevents moving work units through the workflow.", "children": [], "userStory": { "role": "developer using fspec with Example Mapping", "action": "have generate-scenarios create proper Gherkin Given/When/Then steps from example titles", "benefit": "generated scenarios are valid and don't block workflow progression with prefill errors" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T04:16:39.895Z" } ], "rules": [ { "id": 0, "text": "Example titles that start with keywords like 'REPRODUCTION:', 'MISSING:', 'ERROR WHEN:', 'COMMAND RESULT:' should be parsed to extract the actual scenario content, not used verbatim as Given steps", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 1, "text": "Generated scenarios must follow proper Gherkin structure: Given [precondition] / When [action] / Then [expected outcome]", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 2, "text": "Steps should never include the full example title - they should be semantically meaningful Given/When/Then statements", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 3, "text": "Scenario titles must be cleaned by removing common prefixes (REPRODUCTION, MISSING, ERROR WHEN, COMMAND RESULT, FILE, EXACT LINE, COMMAND TO REPRODUCE) to create readable scenario names", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 4, "text": "Original example text must be preserved as a comment (# Example: ...) above each scenario to maintain traceability to Example Mapping", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" } ], "examples": [ { "id": 0, "text": "CURRENT: Example 'REPRODUCTION: work-unit-dependency-management.feature has 42 scenarios' → Scenario with 'Given REPRODUCTION: work-unit-dependency-management.feature has 42 scenarios, but .coverage file only has 39 scenario entries' | EXPECTED: → Scenario with 'Given a feature file exists with 42 scenarios / When I check the coverage file / Then it should have 42 scenario entries'", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 1, "text": "CURRENT: Example 'MISSING: Scenario X (line 501-518) NOT in coverage file' → Generates 'Given [precondition] / When [action] / Then [expected outcome]' (placeholders\\!) | EXPECTED: → 'Given a scenario exists in feature file at lines 501-518 / When I run generate-coverage / Then the scenario should be added to the coverage file'", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 2, "text": "CURRENT: Example 'ERROR WHEN LINKING: fspec link-coverage fails with Scenario not found' → Generates 'Given I have an invalid condition / When I execute ERROR WHEN LINKING...' (malformed\\!) | EXPECTED: → 'Given a scenario is missing from coverage file / When I run fspec link-coverage with that scenario name / Then it should fail with error Scenario not found'", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 3, "text": "CURRENT: Example 'COMMAND RESULT: fspec generate-coverage runs without error but does NOT add missing scenarios' → 'Given I am COMMAND RESULT: fspec generate-coverage / When I runs without error...' (grammatically broken\\!) | EXPECTED: → 'Given I have a feature file with new scenarios / When I run fspec generate-coverage / Then it should run without error / And it should NOT add missing scenarios to existing coverage files' (documents the bug behavior)", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 4, "text": "CURRENT: Example 'FILE: spec/features/work-unit.feature - grep shows 42 scenarios' → 'Given I am FILE: spec/features... / When I shows 42 scenarios...' (nonsensical grammar\\!) | EXPECTED: → 'Given a feature file spec/features/work-unit.feature exists / When I count scenarios using grep / Then it should return 42 scenarios'", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 5, "text": "CURRENT: Example 'COMMAND TO REPRODUCE: 1) Add scenario 2) Run command 3) Check file 4) Try link' → 'Given I am COMMAND TO REPRODUCE: 1) / When I Add new scenario...' (truncated and malformed\\!) | EXPECTED: → 'Given I add a new scenario to an existing feature file / When I run fspec generate-coverage / And I check the coverage file / Then the new scenario should NOT be added / When I try to link coverage for the scenario / Then it should fail with Scenario not found'", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" } ], "questions": [ { "id": 0, "text": "Should generate-scenarios attempt to parse example titles to extract semantic meaning, or should users write proper Given/When/Then examples in the first place?", "selected": true, "answer": "Clean scenario titles by removing prefixes like 'REPRODUCTION:', 'MISSING:', etc. Keep full example as comment. Use existing extractStepsFromExample() for parsing.", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 1, "text": "If examples contain complex reproduction steps (multiple actions), should generate-scenarios create multiple Given/When/Then steps or a single scenario outline?", "selected": true, "answer": "Use existing extractStepsFromExample() which already generates multiple Given/When/Then steps based on pattern matching. No changes needed - current system handles this.", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" }, { "id": 2, "text": "What should happen if an example title doesn't fit the Given/When/Then structure at all (e.g., purely descriptive)?", "selected": true, "answer": "Fall back to [placeholders] which triggers prefill detection. This is already implemented in extractStepsFromExample(). No changes needed.", "deleted": false, "createdAt": "2025-10-15T04:16:17.565Z" } ], "estimate": 2, "nextRuleId": 5, "nextExampleId": 6, "nextQuestionId": 3, "nextNoteId": 0 }, "FEAT-006": { "id": "FEAT-006", "title": "Work unit type system - Core foundation", "status": "done", "createdAt": "2025-10-15T05:44:47.532Z", "updatedAt": "2025-10-25T19:37:42.828Z", "description": "Add support for different work unit types (story, task, bug) similar to JIRA, allowing better categorization of work units based on their nature (user-facing features vs operational work vs defects)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T05:54:25.542Z" }, { "state": "testing", "timestamp": "2025-10-15T06:06:59.919Z" }, { "state": "implementing", "timestamp": "2025-10-15T06:09:03.428Z" }, { "state": "specifying", "timestamp": "2025-10-15T06:15:05.862Z" }, { "state": "testing", "timestamp": "2025-10-15T06:25:53.799Z" }, { "state": "implementing", "timestamp": "2025-10-15T06:26:03.435Z" }, { "state": "validating", "timestamp": "2025-10-15T06:26:09.298Z" }, { "state": "validating", "timestamp": "2025-10-15T06:39:12.885Z", "reason": "All child work units complete (FEAT-007, 008, 009, 010 all done)" }, { "state": "done", "timestamp": "2025-10-15T06:39:15.377Z", "reason": "All child work units done, full test suite passes (1002/1002), build succeeds" }, { "state": "validating", "timestamp": "2025-10-25T12:34:02.868Z" }, { "state": "done", "timestamp": "2025-10-25T19:37:42.829Z" } ], "userStory": { "role": "AI agent managing project work with fspec", "action": "categorize work units by type (story, task, bug)", "benefit": "I can track meta-work and housekeeping through Kanban without violating ACDD discipline for user-facing features" }, "rules": [ { "id": 0, "text": "Work units must have a type field: 'story', 'task', or 'bug'", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 1, "text": "Default type is 'story' for backward compatibility with existing work units", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 2, "text": "Stories require full ACDD workflow: backlog → specifying → testing → implementing → validating → done", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 3, "text": "Tasks use simplified workflow: backlog → in-progress → done (+ blocked)", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 4, "text": "Bugs use same ACDD workflow as stories but may skip Example Mapping in favor of reproduction scenarios", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 5, "text": "Stories must have linked feature file before moving to testing state", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 6, "text": "Tasks do not require feature files or tests", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 7, "text": "Bugs must have reproduction scenario in feature file before moving to testing state", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 8, "text": "Yes, existing work units without type field automatically get type='story' (backward compatible). New work units default to 'story' unless --type specified.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 9, "text": "Tasks CANNOT have feature files. Feature files represent user stories with acceptance criteria, which makes them stories by definition. Tasks are for operational work without user-facing behavior.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 10, "text": "Bugs MUST link to an existing feature file. If no feature file exists for the buggy behavior, it's a story, not a bug. Bugs fix/update existing documented features. Validation error should explain: 'Bugs must link to existing feature file. If feature has no spec, create a story instead.'", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 11, "text": "Tasks support Example Mapping fields (rules, examples, questions) but they are OPTIONAL and only for clarity about what needs to be done. Unlike stories, tasks don't require these fields to be filled before progressing.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 12, "text": "Treat all estimates the same way (combined velocity), but reporting commands should have ability to break down metrics by type (--type=story, --type=task, --type=bug) or show combined.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 13, "text": "Type is immutable once set. If wrong, work unit must be deleted and recreated with correct type. This prevents confusion about workflow rules changing mid-flight.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 14, "text": "All work unit types can use 'in-progress' state. Stories map: specifying/testing/implementing/validating → all represent 'in-progress'. Tasks use 'in-progress' explicitly. Bugs follow story states. This provides consistency across types.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 15, "text": "Tasks use workflow: backlog → specifying → implementing → validating → done (+ blocked). They skip 'testing' state since no tests are required.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 16, "text": "Tasks in specifying state do NOT require feature files (unlike stories). Specifying is for internal clarity only - can use description, rules, examples fields.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 17, "text": "Yes, remove old rule #4. The corrected workflow is: backlog → specifying → implementing → validating → done. Tasks need 'specifying' for clarity but skip 'testing' since no tests required.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" } ], "examples": [ { "id": 0, "text": "Create story work unit: 'fspec create-story AUTH \"User Login\"' creates AUTH-XXX with type='story'", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 1, "text": "Create task work unit: 'fspec create-task CLEAN \"Audit coverage files\"' creates CLEAN-XXX with type='task'", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 2, "text": "Create bug work unit: 'fspec create-bug BUG \"Login fails with @ symbol\"' creates BUG-XXX with type='bug'", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 3, "text": "Default type: 'fspec create-story AUTH \"Feature\"' creates work unit with type='story' (backward compatible)", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 4, "text": "Filter by type: 'fspec list-work-units --type=task' shows only task work units", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 5, "text": "Task workflow: CLEAN-001 moves backlog → in-progress → done (skipping specifying/testing/implementing/validating)", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 6, "text": "Story validation: Moving AUTH-001 (type=story) to testing without feature file shows error 'Cannot move to testing: no feature file linked'", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 7, "text": "Task flexibility: CLEAN-001 (type=task) can move from backlog directly to done without any validation errors", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 8, "text": "Board visualization: 'fspec board' shows three sections: STORIES (full workflow), TASKS (simplified), BUGS (full workflow)", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 9, "text": "Task workflow detail: CLEAN-001 (type=task) moves backlog → specifying (clarify what to do) → implementing (do the work) → validating (verify done) → done", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 10, "text": "Task specifying phase: CLEAN-001 in specifying state can use optional Example Mapping (rules, examples) to clarify work scope before implementing", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" } ], "questions": [ { "id": 0, "text": "@human: Should existing work units without a type field automatically get type='story', or should we require manual migration?", "selected": true, "answer": "Yes, existing work units without type field automatically get type='story' (backward compatible). New work units default to 'story' unless --type specified.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 1, "text": "@human: Can a task optionally have a feature file linked for documentation purposes, or should tasks be completely prohibited from having feature files?", "selected": true, "answer": "Tasks CANNOT have feature files. Feature files represent user stories with acceptance criteria, which makes them stories by definition. Tasks are for operational work without user-facing behavior.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 2, "text": "@human: Should the board command show all three types together, or should it have separate views/sections for each type?", "selected": true, "answer": "No changes to board visualization. All types shown in same board view with their respective workflow states.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 3, "text": "@human: For bugs, should we enforce that they must link to an existing feature file (the one with the bug), or should they create a separate bug-fix feature file?", "selected": true, "answer": "Bugs MUST link to an existing feature file. If no feature file exists for the buggy behavior, it's a story, not a bug. Bugs fix/update existing documented features. Validation error should explain: 'Bugs must link to existing feature file. If feature has no spec, create a story instead.'", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 4, "text": "@human: Should tasks support Example Mapping fields (rules, examples, questions), or should those be story/bug-only features?", "selected": true, "answer": "Tasks support Example Mapping fields (rules, examples, questions) but they are OPTIONAL and only for clarity about what needs to be done. Unlike stories, tasks don't require these fields to be filled before progressing.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 5, "text": "@human: Should we track different velocity metrics for stories vs tasks vs bugs, or treat all estimates the same way?", "selected": true, "answer": "Treat all estimates the same way (combined velocity), but reporting commands should have ability to break down metrics by type (--type=story, --type=task, --type=bug) or show combined.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 6, "text": "@human: Can a work unit's type be changed after creation, or is it immutable once set?", "selected": true, "answer": "Type is immutable once set. If wrong, work unit must be deleted and recreated with correct type. This prevents confusion about workflow rules changing mid-flight.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 7, "text": "@human: Should 'in-progress' state be available for ALL work unit types, or should it remain task-only?", "selected": true, "answer": "All work unit types can use 'in-progress' state. Stories map: specifying/testing/implementing/validating → all represent 'in-progress'. Tasks use 'in-progress' explicitly. Bugs follow story states. This provides consistency across types.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" }, { "id": 8, "text": "@human: Should I remove the old rule #4 that says 'Tasks use simplified workflow: backlog → in-progress → done' since it's been superseded by the corrected workflow?", "selected": true, "answer": "Yes, remove old rule #4. The corrected workflow is: backlog → specifying → implementing → validating → done. Tasks need 'specifying' for clarity but skip 'testing' since no tests required.", "deleted": false, "createdAt": "2025-10-15T05:44:47.532Z" } ], "assumptions": [ "No changes to board visualization. All types shown in same board view with their respective workflow states." ], "estimate": 5, "epic": "work-item-types", "nextRuleId": 18, "nextExampleId": 11, "nextQuestionId": 9, "nextNoteId": 0 }, "FEAT-011": { "id": "FEAT-011", "title": "Prevent retroactive state walking - enforce temporal ordering", "type": "story", "status": "done", "createdAt": "2025-10-15T06:49:06.299Z", "updatedAt": "2025-10-15T07:07:46.452Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T06:49:30.983Z", "reason": "Need to add Example Mapping rules" }, { "state": "testing", "timestamp": "2025-10-15T07:06:20.805Z" }, { "state": "implementing", "timestamp": "2025-10-15T07:06:36.424Z" }, { "state": "validating", "timestamp": "2025-10-15T07:06:42.872Z" }, { "state": "done", "timestamp": "2025-10-15T07:07:46.453Z" } ], "rules": [ { "id": 0, "text": "System must prevent AI agents from doing all work first, then retroactively walking through states as theater", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" }, { "id": 1, "text": "When moving to testing state: system must verify tests were created AFTER entering testing state, not before", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" }, { "id": 2, "text": "When moving to implementing state: system must verify tests currently FAIL (red phase). Tests failing proves they actually test something.", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" }, { "id": 3, "text": "When moving to validating state: system must verify tests now PASS (green phase) and implementation was modified AFTER entering implementing", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" }, { "id": 4, "text": "If work unit has artifacts (specs/tests/code) all timestamped BEFORE entering testing state, then: either delete the work unit if it has no unique value OR move it back to backlog and require proper ACDD workflow", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" } ], "examples": [ { "id": 0, "text": "FEAT-007, FEAT-008, FEAT-009, FEAT-010: All work (specs, tests, code) completed in previous session. Current session: AI moved each through specifying→testing→implementing→validating→done in 5 seconds each. System allowed it because @WORK-UNIT-ID tags existed in feature file and tests passed. Result: ACDD completely bypassed.", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" }, { "id": 1, "text": "work-item-types-for-stories-tasks-and-bugs.feature: Created before any child work units. Tests written before testing state. Implementation completed before implementing state. Feature file tagged with @FEAT-007 @FEAT-008 @FEAT-009 @FEAT-010 retroactively. checkScenariosExist() found tags and allowed testing state entry.", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" }, { "id": 2, "text": "System checks: (1) Does @WORK-UNIT-ID exist? YES. (2) Is state transition valid? YES. (3) Are children done? YES. Missing checks: (1) When was feature file created? (2) When were tests written? (3) Did tests fail first? (4) Was implementation written after tests?", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" }, { "id": 3, "text": "AI behavior enabled by current system: (1) Write all code in one session. (2) Tag feature file with work unit IDs. (3) Run tests to ensure they pass. (4) Walk through states as formality. (5) System approves everything. This is the opposite of ACDD.", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" }, { "id": 4, "text": "Correct ACDD sequence: (1) Enter specifying: write feature file. (2) Enter testing: write FAILING tests. (3) Run tests: verify they fail. (4) Enter implementing: write minimal code. (5) Run tests: verify they pass. (6) Enter validating: run full suite. System must enforce this temporal ordering.", "deleted": false, "createdAt": "2025-10-15T06:49:06.299Z" } ], "userStory": { "role": "AI agent using fspec for ACDD workflow", "action": "ensure work is done in the correct temporal order", "benefit": "ACDD methodology is actually enforced, not just theatrical state walking" }, "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "DOC-004": { "id": "DOC-004", "title": "Validate Mermaid diagrams during foundation.json regeneration", "type": "story", "status": "done", "createdAt": "2025-10-15T07:36:09.439Z", "updatedAt": "2025-10-15T07:54:01.712Z", "description": "The generate-foundation-md command should validate all Mermaid diagrams in foundation.json before regenerating FOUNDATION.md. If any diagram has invalid syntax, the command should fail with detailed error information including the position in the JSON file and the specific Mermaid validation error, guiding the AI to fix and regenerate.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T07:36:16.916Z" }, { "state": "testing", "timestamp": "2025-10-15T07:45:13.894Z" }, { "state": "implementing", "timestamp": "2025-10-15T07:47:31.554Z" }, { "state": "validating", "timestamp": "2025-10-15T07:51:32.720Z" }, { "state": "done", "timestamp": "2025-10-15T07:54:01.712Z" } ], "userStory": { "role": "developer maintaining foundation.json documentation", "action": "validate all Mermaid diagrams when regenerating FOUNDATION.md", "benefit": "I catch syntax errors immediately with precise error locations and can fix them before the markdown file is written" }, "rules": [ { "id": 0, "text": "All Mermaid diagrams in foundation.json MUST be validated before writing FOUNDATION.md", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 1, "text": "Validation errors MUST include the JSON position (architectureDiagrams array index) of the failing diagram", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 2, "text": "Validation errors MUST include the diagram title for easy identification", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 3, "text": "Validation errors MUST include the detailed Mermaid error message from mermaid.parse()", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 4, "text": "The command MUST exit with code 1 if any diagram validation fails", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 5, "text": "Error output MUST guide the AI to fix the diagram in foundation.json and regenerate", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 6, "text": "Diagram validation MUST use the existing validateMermaidSyntax() function from add-diagram.ts", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 7, "text": "After JSON schema validation - validate diagrams after the schema check passes", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 8, "text": "Validate all diagrams at once and show all errors together - don't fail fast", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 9, "text": "Yes, extract validateMermaidSyntax to src/utils/mermaid-validation.ts for reuse", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec generate-foundation-md' with valid diagrams completes successfully and generates FOUNDATION.md", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 1, "text": "Running 'fspec generate-foundation-md' with an invalid diagram at architectureDiagrams[2] shows: 'Error at architectureDiagrams[2] (title: \"Data Flow\"): Invalid Mermaid syntax: unexpected token' and exits with code 1", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 2, "text": "Running 'fspec generate-foundation-md' with multiple invalid diagrams shows all failures with their positions, titles, and error messages", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 3, "text": "Error message includes guidance: 'Fix the diagram(s) in spec/foundation.json and run fspec generate-foundation-md again'", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 4, "text": "After fixing invalid diagrams in foundation.json and running 'fspec generate-foundation-md' again, the command succeeds and generates FOUNDATION.md", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" } ], "questions": [ { "id": 0, "text": "@human: Should validation happen BEFORE or AFTER JSON schema validation?", "selected": true, "answer": "After JSON schema validation - validate diagrams after the schema check passes", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 1, "text": "@human: Should we stop at the first invalid diagram or validate all diagrams and show all errors at once?", "selected": true, "answer": "Validate all diagrams at once and show all errors together - don't fail fast", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" }, { "id": 2, "text": "@human: Should the validateMermaidSyntax function be extracted to a shared utility file for reuse?", "selected": true, "answer": "Yes, extract validateMermaidSyntax to src/utils/mermaid-validation.ts for reuse", "deleted": false, "createdAt": "2025-10-15T07:36:09.439Z" } ], "estimate": 3, "nextRuleId": 10, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 0 }, "BUG-010": { "id": "BUG-010", "title": "fspec init performs unnecessary string replacements on generic slash command template", "type": "bug", "status": "done", "createdAt": "2025-10-15T08:07:58.029Z", "updatedAt": "2025-10-15T08:13:07.810Z", "description": "The init command replaces fspec-specific examples (user-authentication.feature, CLI-003, etc.) with generic placeholders (example-feature.feature, EXAMPLE-001). These replacements are unnecessary because the slash command file contains illustrative examples that work for any project. The replacements also cause issues when running init from fspec's own directory, overwriting the original examples. Solution: Remove all string replacement logic from generateTemplate() function.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T08:08:12.311Z" }, { "state": "testing", "timestamp": "2025-10-15T08:11:59.282Z" }, { "state": "implementing", "timestamp": "2025-10-15T08:12:08.189Z" }, { "state": "validating", "timestamp": "2025-10-15T08:12:08.484Z" }, { "state": "done", "timestamp": "2025-10-15T08:13:07.810Z" } ], "rules": [ { "id": 0, "text": "The slash command file is generic guidance that works for any project", "deleted": false, "createdAt": "2025-10-15T08:07:58.029Z" }, { "id": 1, "text": "Examples in the file are illustrative only - showing patterns not specific project details", "deleted": false, "createdAt": "2025-10-15T08:07:58.029Z" }, { "id": 2, "text": "String replacements provide no value and cause issues when run from fspec directory", "deleted": false, "createdAt": "2025-10-15T08:07:58.029Z" } ], "examples": [ { "id": 0, "text": "Running init from fspec dir overwrites original examples with generic ones", "deleted": false, "createdAt": "2025-10-15T08:07:58.029Z" }, { "id": 1, "text": "External projects see user-authentication.feature in examples which works fine as illustration", "deleted": false, "createdAt": "2025-10-15T08:07:58.029Z" } ], "nextRuleId": 3, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "EXMAP-002": { "id": "EXMAP-002", "title": "Preserve example mapping context as comments in generated feature files", "type": "story", "status": "done", "createdAt": "2025-10-15T08:34:45.292Z", "updatedAt": "2025-10-15T09:00:08.967Z", "description": "When generate-scenarios runs, embed full example mapping data (rules, examples, questions, assumptions) as comment blocks that persist through format cycles. This provides permanent context for AI and humans writing scenarios.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T08:34:53.790Z" }, { "state": "testing", "timestamp": "2025-10-15T08:39:15.384Z" }, { "state": "implementing", "timestamp": "2025-10-15T08:44:19.099Z" }, { "state": "validating", "timestamp": "2025-10-15T08:57:40.553Z" }, { "state": "done", "timestamp": "2025-10-15T09:00:08.967Z" } ], "userStory": { "role": "AI agent using fspec for ACDD workflow", "action": "see full example mapping context when writing scenarios", "benefit": "I can write meaningful Given/When/Then steps based on business rules and concrete examples" }, "rules": [ { "id": 0, "text": "Comments in Gherkin AST MUST be preserved through format cycles", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 1, "text": "Example mapping context embedded as comments MUST NOT conflict with add-architecture doc strings", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 2, "text": "Generated feature files MUST contain zero scenarios initially (context-only)", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 3, "text": "System-reminder MUST guide AI to write scenarios based on embedded examples", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 4, "text": "Comment blocks MUST be visually distinct and easy to locate", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 5, "text": "All example mapping data (rules, examples, questions, assumptions) MUST be embedded", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" } ], "examples": [ { "id": 0, "text": "FORMATTER PRESERVES COMMENTS: AI runs generate-scenarios, gets file with # comments, runs fspec format, comments are still present in file", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 1, "text": "COMMENTS DON'T CONFLICT WITH ARCHITECTURE: File has # example mapping comments AND \"\"\" architecture notes doc string, both coexist without overwriting", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 2, "text": "CONTEXT-ONLY GENERATION: generate-scenarios produces file with # comments + Background but ZERO scenarios, AI writes scenarios using Edit tool", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 3, "text": "USER STORY IN TWO PLACES: User story appears in # comments AND in Background section, both updated when set-user-story runs", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 4, "text": "SYSTEM-REMINDER GUIDES AI: After generate-scenarios, system-reminder tells AI 'write scenarios based on # EXAMPLES section', AI sees reminder and writes proper scenarios", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 5, "text": "RULES IN COMMENTS INFORM SCENARIOS: # BUSINESS RULES says 'password 8+ chars', AI writes scenario with Given step checking password length", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 6, "text": "ANSWERED QUESTIONS PRESERVED: # QUESTIONS section shows 'Q: OAuth support? A: Phase 2', developer reading file understands deferred decisions", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 7, "text": "ASSUMPTIONS DOCUMENTED: # ASSUMPTIONS says 'email verification external', AI doesn't write scenarios for email verification", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 8, "text": "VISUAL SEPARATION WITH BORDERS: Comment block has # === borders at top/bottom, easy to spot when scrolling through file", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 9, "text": "MULTIPLE EXAMPLES TO SCENARIOS: # EXAMPLES has 3 items, AI writes 3 separate scenarios OR combines related ones into single scenario", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 10, "text": "ADD-SCENARIO DOESN'T TOUCH COMMENTS: File has # example mapping comments, user runs add-scenario, comments remain untouched at top", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 11, "text": "ADD-BACKGROUND DOESN'T TOUCH COMMENTS: File has # comments before Background, user runs add-background to update user story, comments persist", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 12, "text": "PARSER PRESERVES COMMENTS IN AST: Gherkin parser reads file with # comments, ast.comments array contains comment objects with line numbers and text", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 13, "text": "FORMATTER OUTPUTS COMMENTS FROM AST: formatGherkinDocument receives AST with comments, inserts comment lines at correct positions in output", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 14, "text": "EMPTY EXAMPLE MAP HANDLED: Work unit has no rules/examples, generate-scenarios creates minimal comment block saying 'No example mapping data captured'", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 15, "text": "PREFILL DETECTION STILL WORKS: Generated Background has [role] placeholder, prefill detector emits system-reminder about using set-user-story", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 16, "text": "GIT DIFF SHOWS CONTEXT: Developer reviews PR, sees # example mapping comments in diff, understands why scenarios were written", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 17, "text": "EXISTING COMMENT HANDLING: Feature file already has some # comments, generate-scenarios appends its comment block without conflict", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 18, "text": "NO SCENARIOS MEANS FILE INCOMPLETE: generate-scenarios creates file with # comments + Background + zero scenarios, system-reminder says 'now write scenarios'", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" }, { "id": 19, "text": "AI USES EDIT TOOL WITH CONTEXT: AI reads file, sees # EXAMPLES: '1. User logs in with valid creds', writes Scenario with proper Given/When/Then using Edit tool", "deleted": false, "createdAt": "2025-10-15T08:34:45.292Z" } ], "assumptions": [ "Gherkin parser (@cucumber/gherkin) already captures comments in AST", "Current formatter (gherkin-formatter.ts) ignores ast.comments field", "Comments use # syntax (Gherkin standard)", "Doc strings use triple quotes (architecture notes)", "AI agents have Edit tool access to feature files" ], "estimate": 5, "nextRuleId": 6, "nextExampleId": 20, "nextQuestionId": 0, "nextNoteId": 0 }, "EXMAP-003": { "id": "EXMAP-003", "title": "Add system-reminder to generate-coverage command", "type": "story", "status": "done", "createdAt": "2025-10-15T08:49:29.798Z", "updatedAt": "2025-10-15T13:26:45.264Z", "description": "When generate-coverage creates coverage files, emit a system-reminder explaining that the LLM must manually link coverage using link-coverage command", "epic": "coverage-tracking", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T09:06:38.009Z" }, { "state": "testing", "timestamp": "2025-10-15T09:09:37.200Z" }, { "state": "implementing", "timestamp": "2025-10-15T09:10:49.274Z" }, { "state": "validating", "timestamp": "2025-10-15T09:13:24.474Z" }, { "state": "done", "timestamp": "2025-10-15T09:13:36.457Z" }, { "state": "specifying", "timestamp": "2025-10-15T09:22:46.765Z" }, { "state": "testing", "timestamp": "2025-10-15T13:24:08.180Z" }, { "state": "implementing", "timestamp": "2025-10-15T13:24:50.326Z" }, { "state": "validating", "timestamp": "2025-10-15T13:24:55.615Z" }, { "state": "done", "timestamp": "2025-10-15T13:26:45.266Z" } ], "rules": [ { "id": 0, "text": "Coverage files must be populated manually using link-coverage", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 1, "text": "System reminder must be displayed after generate-coverage command", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 2, "text": "Reminder must explain that coverage files are empty until linked", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 3, "text": "Reminder must show example link-coverage commands", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 4, "text": "Yes, reminder should be shown for both modes with contextual examples", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 5, "text": "Yes, should mention show-coverage as verification step", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 6, "text": "Yes, reminder should clearly explain generate-coverage creates empty files and link-coverage populates them", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 7, "text": "Yes, should mention show-coverage as verification step", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 8, "text": "Yes, reminder should clearly explain generate-coverage creates empty files and link-coverage populates them", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 9, "text": "Yes, reminder should clearly explain generate-coverage creates empty files and link-coverage populates them", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 10, "text": "Yes, reminder should clearly explain generate-coverage creates empty files and link-coverage populates them", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" } ], "examples": [ { "id": 0, "text": "User runs generate-coverage with no arguments and sees reminder", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 1, "text": "User runs generate-coverage --dry-run and sees reminder", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 2, "text": "User runs generate-coverage feature-name and sees reminder with feature-specific examples", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 3, "text": "Reminder includes link-coverage command syntax with test file example", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 4, "text": "Reminder includes link-coverage command syntax with implementation file example", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 5, "text": "Reminder explains three-step ACDD workflow: write specs → link tests → link implementation", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" } ], "questions": [ { "id": 0, "text": "Should the reminder be shown for both single-feature and all-features modes?", "selected": true, "answer": "Yes, reminder should clearly explain generate-coverage creates empty files and link-coverage populates them", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 1, "text": "Should the reminder include show-coverage command as next step?", "selected": true, "answer": "Yes, reminder should clearly explain generate-coverage creates empty files and link-coverage populates them", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 2, "text": "Should the reminder be suppressible with a --quiet flag?", "selected": true, "answer": "Yes, reminder should clearly explain generate-coverage creates empty files and link-coverage populates them", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" }, { "id": 3, "text": "Should the reminder explain the difference between generate-coverage and link-coverage?", "selected": true, "answer": "Yes, reminder should clearly explain generate-coverage creates empty files and link-coverage populates them", "deleted": false, "createdAt": "2025-10-15T08:49:29.798Z" } ], "assumptions": [ "No, reminder should always be shown as it's critical for ACDD workflow", "No, reminder should always be shown as it's critical for ACDD workflow", "No, reminder should always be shown as it's critical for ACDD workflow" ], "userStory": { "role": "developer using fspec with ACDD workflow", "action": "be reminded to manually link coverage after running generate-coverage", "benefit": "I don't forget the critical step of linking tests and implementation to scenarios" }, "nextRuleId": 11, "nextExampleId": 6, "nextQuestionId": 4, "nextNoteId": 0 }, "HOOK-001": { "id": "HOOK-001", "title": "Kanban Lifecycle Hooks System", "type": "story", "status": "done", "createdAt": "2025-10-15T10:55:43.651Z", "updatedAt": "2025-10-21T00:50:35.164Z", "description": "Implement a hooks system similar to Claude Code hooks that allows executing custom commands before/after Kanban state transitions. Hooks are configured in spec/fspec-hooks.json and scripts live in spec/hooks/ directory. Enables quality gates, test automation, notifications, and CI/CD integration at each ACDD workflow stage.", "children": [ "HOOK-002", "HOOK-003", "HOOK-004", "HOOK-005", "HOOK-006", "HOOK-007", "HOOK-008", "HOOK-009" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T10:55:52.838Z" }, { "state": "testing", "timestamp": "2025-10-15T13:28:29.038Z" }, { "state": "implementing", "timestamp": "2025-10-15T13:28:40.015Z" }, { "state": "validating", "timestamp": "2025-10-15T13:28:40.379Z" }, { "state": "done", "timestamp": "2025-10-15T13:28:40.739Z" }, { "state": "specifying", "timestamp": "2025-10-20T22:40:32.638Z" }, { "state": "testing", "timestamp": "2025-10-21T00:50:33.128Z" }, { "state": "implementing", "timestamp": "2025-10-21T00:50:34.521Z" }, { "state": "validating", "timestamp": "2025-10-21T00:50:34.844Z" }, { "state": "done", "timestamp": "2025-10-21T00:50:35.168Z" } ], "userStory": { "role": "developer using fspec", "action": "configure lifecycle hooks to run custom scripts at Kanban transition points", "benefit": "I can automate quality gates, testing, notifications, and CI/CD workflows throughout the ACDD process" }, "rules": [ { "id": 0, "text": "Hooks are configured in spec/fspec-hooks.json file", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 1, "text": "Hook scripts live in spec/hooks/ directory", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 2, "text": "Hooks trigger before and after Kanban state transitions (pre-* and post-*)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 3, "text": "Hooks can be blocking (prevent transition on failure) or non-blocking (run but don't block)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 4, "text": "Hooks receive work unit context as JSON via stdin", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 5, "text": "Hooks can trigger on Example Mapping actions (add-rule, add-example, add-question, answer-question)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 6, "text": "Hooks can trigger on generation commands (generate-scenarios, generate-coverage, generate-foundation-md, generate-tags-md)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 7, "text": "Hooks can trigger on coverage operations (link-coverage, unlink-coverage, audit-coverage)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 8, "text": "Hooks can block create operations (prevent resource creation if conditions not met)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 9, "text": "Hooks can block delete operations (prevent accidental deletion of critical resources)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 10, "text": "Hooks can return structured system messages that fspec passes back to the AI agent", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 11, "text": "Blocking hooks that fail will halt the command and return an error with the hook's system message", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 12, "text": "Hook system messages can include instructions, warnings, suggestions, or error details for the AI to act upon", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 13, "text": "Hooks can return structured feedback (JSON) that AI agents consume to improve ACDD workflow", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 14, "text": "Hooks enforce ACDD ordering by blocking transitions when prerequisites are not met", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 15, "text": "Hooks can spawn separate Claude Code sessions with specific personas (roles) for peer review and validation", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 16, "text": "Multi-agent hooks enable AI pair programming with different expertise (reviewer, QA, security, BDD expert, product owner)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 17, "text": "fspec provides the hooks framework and execution engine, users write their own hook scripts", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 18, "text": "Hook scripts can be in any language (bash, python, node, etc) as long as they are executable", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 19, "text": "fspec passes work unit context to hooks via stdin (JSON) and environment variables", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 20, "text": "Hook scripts return exit codes and optional JSON output to fspec for processing", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 21, "text": "Hooks can trigger on program lifecycle events (startup and exit)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 22, "text": "Startup hooks run before command logic executes (for setup, validation, or blocking)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 23, "text": "Exit hooks receive command output and can intercept, modify, or augment the response before returning to user", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 24, "text": "Sequential execution only. Hooks for the same event run one after another in the order defined in fspec-hooks.json. This provides predictable execution order, easier debugging, and allows later hooks to depend on earlier hooks' side effects.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 25, "text": "No skip mechanism. When a blocking hook fails, the command is blocked and the user must fix the issue. To bypass a hook, the user must edit spec/fspec-hooks.json to remove or disable it (more intentional than a flag). This maintains discipline and ensures hooks enforce their intended policies.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 26, "text": "Always run for all work units. No matcher system. This keeps the framework simple and predictable. If users need conditional execution, they can implement it inside their hook scripts by reading the work unit context and exiting early if conditions aren't met.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 27, "text": "Default timeout is 60 seconds (matching Claude Code). Hooks can override with 'timeout' field in fspec-hooks.json. Global default can be set in 'global.timeout'. When timeout is exceeded, the hook process is killed and an error is returned.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 28, "text": "Plain stdout/stderr only. Exit code determines success (0) or failure (non-zero). Hook output is displayed as-is to the user. If blocking hook fails (exit != 0), fspec shows stderr in a system-reminder block for AI agent consumption. This keeps hooks simple and works with any tool.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 29, "text": "No dry-run mode. Users can use 'fspec list-hooks' to see configured hooks and 'fspec validate-hooks' to validate configuration syntax. To test a hook, users can temporarily make it non-blocking or run it manually outside of fspec.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 30, "text": "CLI commands 'fspec add-hook' and 'fspec remove-hook' manage hooks in fspec-hooks.json programmatically", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 31, "text": "No chaining. Each hook receives the same original work unit context via stdin. Hooks execute sequentially but independently. If users need chaining logic, they can implement it inside their hook scripts (e.g., read files left by previous hooks or use pipes within the script).", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 32, "text": "No chaining for any hooks. All hooks (event hooks and exit hooks) receive the original context/output via stdin. Hooks execute sequentially but independently for side effects (validation, logging, notifications). The original command output is returned to the user unchanged by hooks.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 33, "text": "Hooks inherit the parent process environment naturally (as spawned child processes). fspec does NOT set custom FSPEC_* environment variables. Hooks receive all context via stdin as JSON. Hooks are independent programs that manage their own environment.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 34, "text": "Support optional conditions in hook configuration. Hooks can specify 'condition' object with fields like 'tags', 'prefix', 'epic', 'estimateMin', 'estimateMax'. If condition doesn't match, hook is skipped. If no condition specified, hook always runs. This allows context-aware hooks without requiring logic in every script.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 35, "text": "Support hooks for ANY fspec command using convention: 'pre-<command-name>' and 'post-<command-name>'. Examples: pre-create-work-unit, post-add-rule, pre-link-coverage, post-generate-scenarios. Plus special lifecycle hooks: pre-start (before any command) and pre-exit (before returning output). This makes the system extensible for current and future commands.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 36, "text": "Yes. When a blocking hook fails (exit code != 0), fspec wraps the stderr output in a <system-reminder> block for AI agent consumption. This allows hooks to provide guidance, suggestions, and instructions to AI through plain text stderr output. Non-blocking hooks just display output normally.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 37, "text": "No standard schema. Hooks output freeform text to stdout/stderr. AI agents read and interpret the text naturally. This maximizes flexibility for hook authors and keeps the framework simple. Documentation can provide examples of effective hook output patterns.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 38, "text": "No. fspec provides the hooks framework only. Users can implement multi-agent patterns (spawning multiple Claude sessions, parallel execution, etc.) in their hook scripts using standard shell tools. This keeps fspec focused and avoids framework bloat.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" } ], "examples": [ { "id": 0, "text": "Developer configures post-implementing hook to run ESLint before allowing transition to validating", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 1, "text": "Developer configures post-testing hook to run Playwright tests to verify E2E scenarios work", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 2, "text": "Developer configures post-done hook to send Slack notification that work unit is complete", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 3, "text": "Developer configures pre-validating hook to check test coverage is above 80%", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 4, "text": "Developer configures post-add-rule hook to check if rule needs clarification (AI analysis)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 5, "text": "Developer configures post-generate-scenarios hook to auto-format generated feature files", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 6, "text": "Developer configures post-generate-coverage hook to run test suite with coverage reporter and extract actual line mappings", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 7, "text": "Developer configures post-answer-question hook to automatically add answer as rule or assumption based on AI classification", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 8, "text": "Developer configures pre-generate-scenarios hook to validate that all questions are answered before allowing scenario generation", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 9, "text": "Developer configures post-link-coverage hook to verify linked files exist and line ranges are valid", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 10, "text": "Developer configures pre-create-work-unit hook to block creation if work unit title contains placeholder text like TODO or TBD", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 11, "text": "Developer configures pre-delete-work-unit hook to prevent deletion of work units with status 'implementing' or 'validating'", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 12, "text": "Developer configures pre-unlink-coverage hook to confirm before removing coverage mappings (safety check)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 13, "text": "Developer configures pre-delete-scenario hook to block deletion if scenario has existing test coverage", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 14, "text": "Code quality hook fails with message: 'BLOCKED: TypeScript errors in src/auth.ts:42. Fix type annotation for loginUser function before proceeding to validating state.'", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 15, "text": "Coverage hook returns: 'WARNING: Test coverage is 65%, below 80% threshold. Consider adding tests for edge cases in src/validator.ts:23-45 before moving to validating.'", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 16, "text": "Example mapping hook suggests: 'SUGGESTION: Question 0 contains implementation details. Consider rephrasing to focus on behavior: What should happen when... instead of How should we implement...'", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 17, "text": "AI uses post-testing hook to analyze test failures and suggest missing scenarios or edge cases", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 18, "text": "AI uses post-implementing hook to compare code against acceptance criteria and flag deviations", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 19, "text": "AI uses post-generate-scenarios hook to review generated Gherkin and suggest improvements for clarity", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 20, "text": "AI uses pre-implementing hook to verify all scenarios have corresponding test mappings before allowing code to be written", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 21, "text": "AI uses post-add-example hook to detect duplicate or conflicting examples and suggest consolidation", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 22, "text": "AI uses post-validating hook to analyze coverage gaps and suggest missing test scenarios", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 23, "text": "Developer configures post-implementing hook to spawn a separate Claude Code session as a 'code reviewer' persona to review implementation before validating", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 24, "text": "Developer configures post-generate-scenarios hook to spawn Claude Code as 'BDD expert' persona to critique Gherkin quality", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 25, "text": "Developer configures post-testing hook to spawn Claude Code as 'QA engineer' persona to review test coverage and suggest edge cases", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 26, "text": "Developer configures post-add-example hook to spawn Claude Code as 'product owner' persona to validate examples match business requirements", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 27, "text": "Developer configures pre-done hook to spawn Claude Code as 'security auditor' persona to review code for security vulnerabilities", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 28, "text": "User writes custom bash hook in spec/hooks/check-quality.sh that runs ESLint and returns JSON feedback", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 29, "text": "User writes Python hook in spec/hooks/analyze-coverage.py that uses pytest-cov to generate coverage reports", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 30, "text": "User writes Node.js hook in spec/hooks/validate-api.js that spawns separate Claude session for review", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 31, "text": "User configures startup hook to validate project configuration and block fspec execution if settings are invalid", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 32, "text": "User configures startup hook to initialize external services (database connection, API tokens) before fspec runs", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 33, "text": "User configures exit hook to send fspec command results to external dashboard or logging service", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 34, "text": "User configures exit hook to intercept validation errors and add project-specific troubleshooting guidance to AI agent", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 35, "text": "User configures exit hook to format fspec output for different consumers (JSON for CI, markdown for humans, structured for AI)", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 36, "text": "User runs 'fspec add-hook post-implementing code-quality spec/hooks/check-quality.sh --blocking' to add a new hook to configuration", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 37, "text": "User runs 'fspec remove-hook post-implementing code-quality' to remove a hook from configuration", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" } ], "questions": [ { "id": 0, "text": "@human: Should hooks for the same event run in parallel (all at once) or sequentially (one after another)? Claude Code runs them in parallel.", "selected": true, "answer": "Sequential execution only. Hooks for the same event run one after another in the order defined in fspec-hooks.json. This provides predictable execution order, easier debugging, and allows later hooks to depend on earlier hooks' side effects.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 1, "text": "@human: When a blocking hook fails, should we provide a way for the user to override and force the transition anyway (like --skip-hooks flag)?", "selected": true, "answer": "No skip mechanism. When a blocking hook fails, the command is blocked and the user must fix the issue. To bypass a hook, the user must edit spec/fspec-hooks.json to remove or disable it (more intentional than a flag). This maintains discipline and ensures hooks enforce their intended policies.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 2, "text": "@human: Should hooks be able to match specific work units (e.g., only run for AUTH-* prefixes or specific epics)? Or always run for all work units?", "selected": true, "answer": "Always run for all work units. No matcher system. This keeps the framework simple and predictable. If users need conditional execution, they can implement it inside their hook scripts by reading the work unit context and exiting early if conditions aren't met.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 3, "text": "@human: What should the default timeout be? Claude Code uses 60 seconds. Should we allow per-hook timeout overrides?", "selected": true, "answer": "Default timeout is 60 seconds (matching Claude Code). Hooks can override with 'timeout' field in fspec-hooks.json. Global default can be set in 'global.timeout'. When timeout is exceeded, the hook process is killed and an error is returned.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 4, "text": "@human: Should hook scripts be able to return structured output (JSON) that fspec displays to the user, or just stdout/stderr?", "selected": true, "answer": "Plain stdout/stderr only. Exit code determines success (0) or failure (non-zero). Hook output is displayed as-is to the user. If blocking hook fails (exit != 0), fspec shows stderr in a system-reminder block for AI agent consumption. This keeps hooks simple and works with any tool.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 5, "text": "@human: Do you want a dry-run mode to test hooks without actually running them (just show what would execute)?", "selected": true, "answer": "No dry-run mode. Users can use 'fspec list-hooks' to see configured hooks and 'fspec validate-hooks' to validate configuration syntax. To test a hook, users can temporarily make it non-blocking or run it manually outside of fspec.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 6, "text": "@human: Should we support hook chaining where one hook's output becomes the next hook's input?", "selected": true, "answer": "No chaining for any hooks. All hooks (event hooks and exit hooks) receive the original context/output via stdin. Hooks execute sequentially but independently for side effects (validation, logging, notifications). The original command output is returned to the user unchanged by hooks.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 7, "text": "@human: What environment variables should be available to hooks? (e.g., FSPEC_WORK_UNIT_ID, FSPEC_STATUS, FSPEC_FEATURE_FILES, etc.)", "selected": true, "answer": "Hooks inherit the parent process environment naturally (as spawned child processes). fspec does NOT set custom FSPEC_* environment variables. Hooks receive all context via stdin as JSON. Hooks are independent programs that manage their own environment.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 8, "text": "@human: Should we support hook conditions (e.g., only run if estimate > 5 points, or only for @critical tagged features)?", "selected": true, "answer": "Support optional conditions in hook configuration. Hooks can specify 'condition' object with fields like 'tags', 'prefix', 'epic', 'estimateMin', 'estimateMax'. If condition doesn't match, hook is skipped. If no condition specified, hook always runs. This allows context-aware hooks without requiring logic in every script.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 9, "text": "@human: Do you want hooks for non-transition events like create-work-unit, add-dependency, or link-coverage?", "selected": true, "answer": "Support hooks for ANY fspec command using convention: 'pre-<command-name>' and 'post-<command-name>'. Examples: pre-create-work-unit, post-add-rule, pre-link-coverage, post-generate-scenarios. Plus special lifecycle hooks: pre-start (before any command) and pre-exit (before returning output). This makes the system extensible for current and future commands.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 10, "text": "@human: Should we have hooks that run on commands like create-work-unit, add-dependency, or prioritize-work-unit for workflow automation?", "selected": true, "answer": "Yes - already answered in Question 9. All fspec commands support pre/post hooks including create-work-unit, add-dependency, prioritize-work-unit, etc. This enables workflow automation like auto-prioritizing critical work units or validating dependencies.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 11, "text": "@human: Should hooks be able to provide AI-consumable feedback that influences the next steps (e.g., suggest missing scenarios, recommend refactoring)?", "selected": true, "answer": "Yes. When a blocking hook fails (exit code != 0), fspec wraps the stderr output in a <system-reminder> block for AI agent consumption. This allows hooks to provide guidance, suggestions, and instructions to AI through plain text stderr output. Non-blocking hooks just display output normally.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 12, "text": "@human: Should we provide a standard schema for hook output that includes 'suggestions', 'warnings', 'blockers', and 'insights' for AI consumption?", "selected": true, "answer": "No standard schema. Hooks output freeform text to stdout/stderr. AI agents read and interpret the text naturally. This maximizes flexibility for hook authors and keeps the framework simple. Documentation can provide examples of effective hook output patterns.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" }, { "id": 13, "text": "@human: Should hooks support spawning multiple Claude Code sessions in parallel for multi-perspective review (e.g., security + performance + maintainability reviewers)?", "selected": true, "answer": "No. fspec provides the hooks framework only. Users can implement multi-agent patterns (spawning multiple Claude sessions, parallel execution, etc.) in their hook scripts using standard shell tools. This keeps fspec focused and avoids framework bloat.", "deleted": false, "createdAt": "2025-10-15T10:55:43.651Z" } ], "assumptions": [ "Yes - already answered in Question 9. All fspec commands support pre/post hooks including create-work-unit, add-dependency, prioritize-work-unit, etc. This enables workflow automation like auto-prioritizing critical work units or validating dependencies." ], "estimate": 13, "epic": "hooks-system", "nextRuleId": 39, "nextExampleId": 38, "nextQuestionId": 14, "nextNoteId": 0 }, "HOOK-002": { "id": "HOOK-002", "title": "Hook configuration schema and validation", "type": "story", "status": "done", "createdAt": "2025-10-15T11:44:40.720Z", "updatedAt": "2025-10-19T13:17:31.592Z", "description": "Create JSON schema for spec/fspec-hooks.json. Implement configuration loading, validation, and error handling. Support hook definition with name, command, blocking flag, timeout, and conditions.", "epic": "hooks-system", "children": [], "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T11:50:26.414Z" }, { "state": "testing", "timestamp": "2025-10-15T11:53:06.432Z" }, { "state": "implementing", "timestamp": "2025-10-15T11:55:57.393Z" }, { "state": "validating", "timestamp": "2025-10-15T11:56:34.878Z" }, { "state": "done", "timestamp": "2025-10-15T11:57:55.781Z" }, { "state": "implementing", "timestamp": "2025-10-19T13:13:13.128Z" }, { "state": "validating", "timestamp": "2025-10-19T13:17:31.318Z" }, { "state": "done", "timestamp": "2025-10-19T13:17:31.593Z" } ], "userStory": { "role": "fspec developer", "action": "define hook configuration in spec/fspec-hooks.json", "benefit": "the hooks system knows which scripts to execute at which events" }, "rules": [ { "id": 0, "text": "Configuration file is spec/fspec-hooks.json in JSON format", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 1, "text": "Each hook has: name (string), command (path to executable), blocking (boolean, default false), timeout (number in seconds, default 60)", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 2, "text": "Hooks can have optional condition object with: tags (array), prefix (array), epic (string), estimateMin (number), estimateMax (number)", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 3, "text": "Configuration must be valid JSON and conform to hooks schema", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 4, "text": "Hook command paths must point to executable files", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 5, "text": "Global defaults can be set in 'global' object: timeout, shell", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" } ], "examples": [ { "id": 0, "text": "Valid config with single hook: {hooks: {'post-implementing': [{name: 'lint', command: 'spec/hooks/lint.sh', blocking: true}]}}", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 1, "text": "Hook with timeout override: {name: 'e2e-tests', command: 'test.sh', timeout: 300}", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 2, "text": "Hook with conditions: {name: 'security', command: 'audit.sh', condition: {tags: ['@security'], prefix: ['AUTH']}}", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 3, "text": "Invalid JSON causes validation error with helpful message", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 4, "text": "Non-existent hook command path causes validation error", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" }, { "id": 5, "text": "Missing hook file returns clear error: 'Hook command not found: spec/hooks/missing.sh'", "deleted": false, "createdAt": "2025-10-15T11:44:40.720Z" } ], "nextRuleId": 6, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "HOOK-003": { "id": "HOOK-003", "title": "Hook execution engine", "type": "story", "status": "done", "createdAt": "2025-10-15T11:44:44.580Z", "updatedAt": "2025-10-15T12:09:58.633Z", "description": "Implement core hook execution: spawn processes, pass context via stdin JSON, collect stdout/stderr, handle exit codes, implement 60s default timeout with override support, sequential execution of hooks.", "epic": "hooks-system", "children": [], "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T12:00:26.203Z" }, { "state": "testing", "timestamp": "2025-10-15T12:03:56.276Z" }, { "state": "implementing", "timestamp": "2025-10-15T12:05:03.823Z" }, { "state": "validating", "timestamp": "2025-10-15T12:08:33.750Z" }, { "state": "done", "timestamp": "2025-10-15T12:09:58.633Z" } ], "userStory": { "role": "fspec developer", "action": "execute hook scripts at lifecycle events", "benefit": "I can run custom automation, quality gates, and notifications during fspec commands" }, "rules": [ { "id": 0, "text": "Hook execution engine spawns child processes for each hook script", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 1, "text": "Hook context is passed as JSON to stdin (workUnitId, event, timestamp, etc.)", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 2, "text": "stdout and stderr are captured and displayed to user/AI agent", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 3, "text": "Exit code 0 indicates success, non-zero indicates failure", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 4, "text": "Hooks timeout after configured duration (default 60s)", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 5, "text": "Blocking hooks halt command execution on failure (non-zero exit)", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 6, "text": "Hooks execute sequentially in the order defined in config", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 7, "text": "Hook processes inherit parent environment variables", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" } ], "examples": [ { "id": 0, "text": "Execute single non-blocking hook that succeeds (exit 0) - output shown, command continues", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 1, "text": "Execute single non-blocking hook that fails (exit 1) - warning shown, command continues", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 2, "text": "Execute blocking hook that fails - command halted, error returned to user/AI", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 3, "text": "Hook times out after 60s - process killed, timeout error shown", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 4, "text": "Hook receives context via stdin: {\"workUnitId\":\"AUTH-001\",\"event\":\"post-implementing\",\"timestamp\":\"2025-01-15T10:30:00Z\"}", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 5, "text": "Multiple hooks execute sequentially - first runs to completion, then second starts", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" }, { "id": 6, "text": "Hook stdout/stderr captured and displayed: 'Running tests...' visible to user", "deleted": false, "createdAt": "2025-10-15T11:44:44.580Z" } ], "nextRuleId": 8, "nextExampleId": 7, "nextQuestionId": 0, "nextNoteId": 0 }, "HOOK-004": { "id": "HOOK-004", "title": "Hook discovery and event naming", "type": "story", "status": "done", "createdAt": "2025-10-15T11:44:48.300Z", "updatedAt": "2025-10-15T12:17:01.555Z", "description": "Implement hook discovery for any command using pre-/post- convention. Support special lifecycle hooks: pre-start and pre-exit. Build event name from command name dynamically.", "epic": "hooks-system", "children": [], "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T12:11:00.282Z" }, { "state": "testing", "timestamp": "2025-10-15T12:14:07.598Z" }, { "state": "implementing", "timestamp": "2025-10-15T12:14:54.286Z" }, { "state": "validating", "timestamp": "2025-10-15T12:15:29.403Z" }, { "state": "done", "timestamp": "2025-10-15T12:17:01.555Z" } ], "userStory": { "role": "fspec system", "action": "discover and execute hooks for lifecycle events", "benefit": "hooks can be triggered at the right moments during command execution" }, "rules": [ { "id": 0, "text": "Event names follow pre-/post- convention: pre-<command-name>, post-<command-name>", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 1, "text": "Special lifecycle hooks: pre-start (before any command), pre-exit (before returning output)", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 2, "text": "Hook discovery searches config.hooks for matching event name", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 3, "text": "If no hooks match event name, return empty array (no error)", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 4, "text": "Event names are case-sensitive (pre-implementing != pre-Implementing)", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 5, "text": "Command name extraction: 'fspec update-work-unit-status' -> 'update-work-unit-status'", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" } ], "examples": [ { "id": 0, "text": "Discover hooks for 'post-implementing' event - returns array of matching hooks", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 1, "text": "Discover hooks for 'pre-start' special lifecycle event - returns global pre-start hooks", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 2, "text": "Discover hooks for non-existent event 'pre-xyz' - returns empty array (no error)", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 3, "text": "Event name for command 'update-work-unit-status' generates 'pre-update-work-unit-status' and 'post-update-work-unit-status'", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 4, "text": "Case-sensitive matching: 'post-implementing' finds hooks, 'post-Implementing' does not", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" }, { "id": 5, "text": "Multiple hooks for same event - returns all matching hooks in config order", "deleted": false, "createdAt": "2025-10-15T11:44:48.300Z" } ], "nextRuleId": 6, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "HOOK-005": { "id": "HOOK-005", "title": "Hook condition evaluation", "type": "story", "status": "done", "createdAt": "2025-10-15T11:44:52.221Z", "updatedAt": "2025-10-15T12:24:15.115Z", "description": "Implement optional condition matching: tags, prefix, epic, estimateMin, estimateMax. Skip hook if conditions don't match. Support no condition = always run.", "epic": "hooks-system", "children": [], "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T12:17:45.705Z" }, { "state": "testing", "timestamp": "2025-10-15T12:21:11.809Z" }, { "state": "implementing", "timestamp": "2025-10-15T12:22:27.203Z" }, { "state": "validating", "timestamp": "2025-10-15T12:23:05.811Z" }, { "state": "done", "timestamp": "2025-10-15T12:24:15.116Z" } ], "userStory": { "role": "hook execution system", "action": "evaluate hook conditions to determine if a hook should run", "benefit": "hooks only execute when their conditions match the current context" }, "rules": [ { "id": 0, "text": "Hooks with no condition always match (condition is optional)", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 1, "text": "Condition with tags: hook runs if work unit has ANY of the specified tags (OR logic)", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 2, "text": "Condition with prefix: hook runs if work unit ID starts with ANY of the specified prefixes (OR logic)", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 3, "text": "Condition with epic: hook runs if work unit belongs to specified epic", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 4, "text": "Condition with estimateMin/estimateMax: hook runs if work unit estimate is within range", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 5, "text": "Multiple condition fields use AND logic (all must match)", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 6, "text": "If context has no workUnitId, only hooks without conditions run", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" } ], "examples": [ { "id": 0, "text": "Hook with no condition matches any context - always runs", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 1, "text": "Hook with tags:[@security] matches work unit with @security tag", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 2, "text": "Hook with prefix:[AUTH,SEC] matches AUTH-001 but not DASH-001", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 3, "text": "Hook with epic:'user-management' matches work unit in that epic", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 4, "text": "Hook with estimateMin:5, estimateMax:13 matches work unit with estimate 8", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 5, "text": "Hook with tags:[@security] AND prefix:[AUTH] - both must match (AND logic)", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" }, { "id": 6, "text": "Context with no workUnitId - only unconditional hooks match", "deleted": false, "createdAt": "2025-10-15T11:44:52.221Z" } ], "nextRuleId": 7, "nextExampleId": 7, "nextQuestionId": 0, "nextNoteId": 0 }, "HOOK-006": { "id": "HOOK-006", "title": "System reminder formatting for AI", "type": "story", "status": "done", "createdAt": "2025-10-15T11:44:56.257Z", "updatedAt": "2025-10-15T12:32:11.238Z", "description": "When blocking hook fails, wrap stderr in <system-reminder> block for AI consumption. Display hook name, exit code, and error message. Include 'DO NOT mention this reminder to the user' footer.", "epic": "hooks-system", "children": [], "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T12:26:08.503Z" }, { "state": "testing", "timestamp": "2025-10-15T12:29:26.029Z" }, { "state": "implementing", "timestamp": "2025-10-15T12:30:18.689Z" }, { "state": "validating", "timestamp": "2025-10-15T12:30:56.713Z" }, { "state": "done", "timestamp": "2025-10-15T12:32:11.239Z" } ], "userStory": { "role": "fspec system", "action": "format blocking hook stderr as system-reminders for AI agents", "benefit": "AI agents receive actionable feedback when hooks fail" }, "rules": [ { "id": 0, "text": "Blocking hook stderr is wrapped in <system-reminder> tags", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" }, { "id": 1, "text": "Non-blocking hook stderr is displayed as-is (no wrapping)", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" }, { "id": 2, "text": "System-reminder content includes hook name, exit code, and stderr output", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" }, { "id": 3, "text": "Empty stderr produces no system-reminder (only if stderr has content)", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" }, { "id": 4, "text": "System-reminder is appended to command output (not replacing it)", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" } ], "examples": [ { "id": 0, "text": "Blocking hook fails with stderr 'Invalid config' - wrapped in system-reminder", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" }, { "id": 1, "text": "Non-blocking hook fails with stderr - displayed as-is, no wrapping", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" }, { "id": 2, "text": "Blocking hook succeeds - no system-reminder generated", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" }, { "id": 3, "text": "Blocking hook fails with empty stderr - no system-reminder", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" }, { "id": 4, "text": "System-reminder includes: hook name 'validate', exit code 1, stderr content", "deleted": false, "createdAt": "2025-10-15T11:44:56.257Z" } ], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "HOOK-007": { "id": "HOOK-007", "title": "Hook management CLI commands", "type": "story", "status": "done", "createdAt": "2025-10-15T11:45:00.480Z", "updatedAt": "2025-10-15T12:51:50.899Z", "description": "Implement: fspec list-hooks, fspec validate-hooks, fspec add-hook, fspec remove-hook. List shows all configured hooks. Validate checks config syntax. Add/remove modify fspec-hooks.json.", "epic": "hooks-system", "children": [], "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T12:42:06.760Z" }, { "state": "testing", "timestamp": "2025-10-15T12:47:49.741Z" }, { "state": "implementing", "timestamp": "2025-10-15T12:48:36.967Z" }, { "state": "validating", "timestamp": "2025-10-15T12:49:21.484Z" }, { "state": "done", "timestamp": "2025-10-15T12:51:50.899Z" } ], "userStory": { "role": "fspec user", "action": "manage hooks via CLI commands", "benefit": "I can list, validate, add, and remove hooks without manually editing JSON" }, "rules": [ { "id": 0, "text": "list-hooks command displays all configured hooks grouped by event", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 1, "text": "validate-hooks command checks config syntax and verifies hook scripts exist", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 2, "text": "add-hook command adds a hook to config and creates the event array if needed", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 3, "text": "remove-hook command removes a hook by name and event", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 4, "text": "Commands fail gracefully if spec/fspec-hooks.json does not exist", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 5, "text": "add-hook command requires: name, event, command (path to script)", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" } ], "examples": [ { "id": 0, "text": "list-hooks displays: post-implementing: lint, test", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 1, "text": "validate-hooks passes - all scripts exist, JSON valid", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 2, "text": "validate-hooks fails - missing script spec/hooks/missing.sh", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 3, "text": "add-hook --name lint --event post-implementing --command spec/hooks/lint.sh --blocking", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 4, "text": "remove-hook --name lint --event post-implementing - hook removed from config", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" }, { "id": 5, "text": "list-hooks when no config file - displays friendly message", "deleted": false, "createdAt": "2025-10-15T11:45:00.480Z" } ], "nextRuleId": 6, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "HOOK-008": { "id": "HOOK-008", "title": "Integrate hooks into all commands", "type": "story", "status": "done", "createdAt": "2025-10-15T11:45:04.467Z", "updatedAt": "2025-10-15T13:01:53.657Z", "description": "Add hook execution to every fspec command. Call runHooks() before/after command logic. Support pre-start lifecycle hook. Support pre-exit lifecycle hook. Pass appropriate context to each hook.", "epic": "hooks-system", "children": [], "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T12:56:41.998Z" }, { "state": "testing", "timestamp": "2025-10-15T12:58:43.162Z" }, { "state": "implementing", "timestamp": "2025-10-15T12:59:55.073Z" }, { "state": "validating", "timestamp": "2025-10-15T13:00:34.477Z" }, { "state": "done", "timestamp": "2025-10-15T13:01:53.657Z" } ], "userStory": { "role": "fspec CLI user", "action": "have hooks execute automatically with every command", "benefit": "I can enforce policies and automations without manually invoking hooks" }, "rules": [ { "id": 0, "text": "Commands execute pre- hooks before main logic and post- hooks after main logic", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 1, "text": "Hook event names follow pattern: pre-{command} and post-{command}", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 2, "text": "Hooks receive context with workUnitId (if applicable), event name, and timestamp", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 3, "text": "Blocking hook failures prevent command execution (pre-hooks) or prevent exit with success (post-hooks)", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 4, "text": "Non-blocking hook failures do not prevent command execution or success", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 5, "text": "Hooks are filtered by conditions before execution (tags, prefix, epic, estimate)", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 6, "text": "Hook output is displayed using formatHookOutput() with system-reminders for blocking failures", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" } ], "examples": [ { "id": 0, "text": "Command update-work-unit-status triggers pre-update-work-unit-status and post-update-work-unit-status hooks", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 1, "text": "Pre-hook validates work unit has feature file before allowing status change to testing", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 2, "text": "Post-hook runs tests after implementing status change", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 3, "text": "Blocking pre-hook failure prevents command from executing", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 4, "text": "Non-blocking post-hook failure allows command to succeed", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 5, "text": "Hook with tag condition only runs for work units with matching tag", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" }, { "id": 6, "text": "Hook output formatted with system-reminder shows blocking hook failure details", "deleted": false, "createdAt": "2025-10-15T11:45:04.467Z" } ], "nextRuleId": 7, "nextExampleId": 7, "nextQuestionId": 0, "nextNoteId": 0 }, "HOOK-009": { "id": "HOOK-009", "title": "Hook system documentation and examples", "type": "story", "status": "done", "createdAt": "2025-10-15T11:45:08.399Z", "updatedAt": "2025-10-15T13:08:41.103Z", "description": "Write comprehensive documentation: configuration format, hook script examples (bash/python/node), best practices for output, example hooks for common use cases (linting, testing, notifications).", "epic": "hooks-system", "children": [], "estimate": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T13:02:40.697Z" }, { "state": "testing", "timestamp": "2025-10-15T13:04:34.908Z" }, { "state": "implementing", "timestamp": "2025-10-15T13:05:21.697Z" }, { "state": "validating", "timestamp": "2025-10-15T13:07:19.458Z" }, { "state": "done", "timestamp": "2025-10-15T13:08:41.104Z" } ], "userStory": { "role": "fspec user writing hook scripts", "action": "have comprehensive documentation and working examples", "benefit": "I can quickly create custom hooks without trial and error" }, "rules": [ { "id": 0, "text": "Documentation explains hook configuration JSON schema with all fields", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 1, "text": "Example hooks provided for bash, python, and node.js", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 2, "text": "Documentation explains hook context JSON passed via stdin", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 3, "text": "Best practices documented for stdout/stderr usage and exit codes", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 4, "text": "Common use case examples: linting, testing, notifications, validation", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 5, "text": "Documentation includes troubleshooting section for common errors", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" } ], "examples": [ { "id": 0, "text": "Configuration doc shows complete fspec-hooks.json with global defaults and multiple hooks", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 1, "text": "Bash hook reads JSON context from stdin and validates work unit has feature file", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 2, "text": "Python hook parses JSON stdin and runs pytest on work unit tests", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 3, "text": "Node.js hook reads stdin and sends Slack notification about status change", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 4, "text": "Lint hook example shows proper exit codes: 0 for success, 1 for lint errors", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" }, { "id": 5, "text": "Troubleshooting doc explains 'Hook command not found' error and solution", "deleted": false, "createdAt": "2025-10-15T11:45:08.399Z" } ], "nextRuleId": 6, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-011": { "id": "BUG-011", "title": "generate-scenarios missing architecture docstring", "type": "story", "status": "done", "createdAt": "2025-10-15T22:51:07.833Z", "updatedAt": "2025-10-15T23:10:52.876Z", "description": "The generate-scenarios command creates feature files without architecture docstrings, violating CLAUDE.md requirements. Older files created with create-feature have docstrings, but newer files created with generate-scenarios are missing them.", "children": [], "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T22:51:16.440Z" }, { "state": "testing", "timestamp": "2025-10-15T22:53:06.162Z" }, { "state": "implementing", "timestamp": "2025-10-15T22:53:45.139Z" }, { "state": "validating", "timestamp": "2025-10-15T23:09:40.344Z" }, { "state": "done", "timestamp": "2025-10-15T23:10:52.876Z" } ], "userStory": { "role": "developer using generate-scenarios", "action": "have feature files with architecture docstrings", "benefit": "all feature files meet CLAUDE.md requirements and have consistent structure" }, "rules": [ { "id": 0, "text": "All feature files MUST have architecture docstrings (CLAUDE.md requirement)", "deleted": false, "createdAt": "2025-10-15T22:51:07.833Z" }, { "id": 1, "text": "generate-scenarios output MUST match create-feature template structure", "deleted": false, "createdAt": "2025-10-15T22:51:07.833Z" }, { "id": 2, "text": "Docstring MUST come before example mapping comments", "deleted": false, "createdAt": "2025-10-15T22:51:07.833Z" }, { "id": 3, "text": "Docstring MUST include TODO placeholders for architecture notes", "deleted": false, "createdAt": "2025-10-15T22:51:07.833Z" } ], "examples": [ { "id": 0, "text": "User runs generate-scenarios, file contains both docstring and example mapping comments", "deleted": false, "createdAt": "2025-10-15T22:51:07.833Z" }, { "id": 1, "text": "Generated file matches structure: tags → feature → docstring → comments → background", "deleted": false, "createdAt": "2025-10-15T22:51:07.833Z" }, { "id": 2, "text": "Existing tests pass with new docstring addition", "deleted": false, "createdAt": "2025-10-15T22:51:07.833Z" } ], "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "FEAT-012": { "id": "FEAT-012", "title": "Capture architecture notes during Example Mapping", "type": "story", "status": "done", "createdAt": "2025-10-15T22:58:05.227Z", "updatedAt": "2025-10-15T23:23:02.738Z", "description": "Add ability to capture architecture notes and non-functional requirements during Example Mapping discovery phase, and populate feature file docstrings with this information during generate-scenarios.", "children": [], "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T22:58:14.705Z" }, { "state": "testing", "timestamp": "2025-10-15T23:15:36.150Z" }, { "state": "implementing", "timestamp": "2025-10-15T23:16:21.173Z" }, { "state": "validating", "timestamp": "2025-10-15T23:21:08.805Z" }, { "state": "done", "timestamp": "2025-10-15T23:23:02.739Z" } ], "userStory": { "role": "AI agent doing Example Mapping", "action": "capture architecture notes and non-functional requirements", "benefit": "generated feature files have complete technical context in docstrings" }, "rules": [ { "id": 0, "text": "Architecture notes must be stored in WorkUnit during Example Mapping", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 1, "text": "Architecture notes must populate docstring in generate-scenarios output", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 2, "text": "Must support adding/removing/viewing architecture notes via CLI", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 3, "text": "Architecture notes should include: dependencies, performance reqs, security considerations, implementation constraints", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec add-architecture-note WORK-001 \"Uses @cucumber/gherkin parser\"' during Example Mapping", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 1, "text": "User runs 'fspec generate-scenarios WORK-001' and docstring contains captured architecture notes instead of TODO placeholders", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 2, "text": "User runs 'fspec show-work-unit WORK-001' and sees architecture notes section with all captured notes", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 3, "text": "Generated docstring includes sections for dependencies, performance, security based on captured notes", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" } ], "questions": [ { "id": 0, "text": "@human: Should architectureNotes be a separate array field in WorkUnit, or reuse assumptions field?", "selected": true, "answer": "Separate architectureNotes array field in WorkUnit (clearer separation from assumptions)", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 1, "text": "@human: Should we ask about architecture notes as a separate Example Mapping step (purple cards), or integrate with existing steps?", "selected": true, "answer": "Integrate with existing steps - ask architecture questions during Step 3 (Ask Questions phase) for natural flow", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 2, "text": "@human: What specific NFR questions should AI ask during discovery? (performance, security, dependencies, scalability, etc.)", "selected": true, "answer": "Ask about: libraries/dependencies, code that should be refactored/shared, code quality considerations, UI/UX examples (websites/screenshots), implementation patterns to follow", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" }, { "id": 3, "text": "@human: Should architecture notes have categories/types, or just be free-form strings?", "selected": true, "answer": "Free-form strings initially - users can prefix naturally (e.g., 'Dependency: ...', 'Refactoring: ...'). Add categorization later if needed.", "deleted": false, "createdAt": "2025-10-15T22:58:05.227Z" } ], "nextRuleId": 4, "nextExampleId": 4, "nextQuestionId": 4, "nextNoteId": 0 }, "FEAT-013": { "id": "FEAT-013", "title": "Attachment support for discovery process", "type": "story", "status": "done", "createdAt": "2025-10-15T23:42:01.192Z", "updatedAt": "2025-10-15T23:47:36.516Z", "description": "Add ability to attach files (diagrams, mockups, documents) to work units during Example Mapping to supplement architecture notes and NFRs", "children": [], "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-15T23:42:21.297Z" }, { "state": "testing", "timestamp": "2025-10-15T23:42:57.989Z" }, { "state": "implementing", "timestamp": "2025-10-15T23:43:10.317Z" }, { "state": "validating", "timestamp": "2025-10-15T23:43:11.875Z" }, { "state": "done", "timestamp": "2025-10-15T23:44:54.141Z" }, { "state": "specifying", "timestamp": "2025-10-15T23:46:00.822Z" }, { "state": "testing", "timestamp": "2025-10-15T23:46:24.484Z" }, { "state": "implementing", "timestamp": "2025-10-15T23:47:32.452Z" }, { "state": "validating", "timestamp": "2025-10-15T23:47:34.074Z" }, { "state": "done", "timestamp": "2025-10-15T23:47:36.517Z" } ], "userStory": { "role": "AI agent or developer using fspec", "action": "attach files to work units during Example Mapping", "benefit": "I can supplement architecture notes and NFRs with diagrams, mockups, and documents" }, "rules": [ { "id": 0, "text": "Attachments must be stored in spec/attachments/<work-unit-id>/ directory", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" }, { "id": 1, "text": "Attachment paths must be stored as relative paths from project root", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" }, { "id": 2, "text": "Source file must exist before copying to attachments directory", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec add-attachment AUTH-001 diagrams/auth-flow.png', file is copied to spec/attachments/AUTH-001/ and tracked in work unit", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" }, { "id": 1, "text": "User runs 'fspec list-attachments AUTH-001', sees all attached files with sizes and modification dates", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" }, { "id": 2, "text": "User runs 'fspec remove-attachment AUTH-001 diagram.png', file is deleted and tracking entry removed", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" } ], "architectureNotes": [ { "id": 0, "text": "Attachments array added to WorkUnit interface in src/types/index.ts", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" }, { "id": 1, "text": "Three new commands: add-attachment, list-attachments, remove-attachment", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" }, { "id": 2, "text": "Uses fs/promises for file operations (copyFile, stat, unlink)", "deleted": false, "createdAt": "2025-10-15T23:42:01.192Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 3 }, "HOOK-010": { "id": "HOOK-010", "title": "Migrate hook execution to use execa library", "type": "story", "status": "done", "createdAt": "2025-10-16T00:49:47.693Z", "updatedAt": "2025-10-16T01:18:17.009Z", "description": "Replace Node.js child_process.spawn with execa library for hook execution, following the patterns used in the cage project for better process management and cross-platform compatibility", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-16T00:49:52.619Z" }, { "state": "testing", "timestamp": "2025-10-16T00:55:20.542Z" }, { "state": "implementing", "timestamp": "2025-10-16T00:57:07.118Z" }, { "state": "validating", "timestamp": "2025-10-16T01:06:35.448Z" }, { "state": "done", "timestamp": "2025-10-16T01:18:17.009Z" } ], "userStory": { "role": "fspec developer", "action": "use execa for hook execution instead of child_process.spawn", "benefit": "better process management, improved error handling, and cross-platform compatibility" }, "rules": [ { "id": 0, "text": "Hook execution must maintain timeout behavior (default 60s)", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 1, "text": "Hook context must be passed to stdin as JSON", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 2, "text": "stdout and stderr must be captured separately", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 3, "text": "Hook execution results must include hookName, success, exitCode, stdout, stderr, timedOut, duration", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 4, "text": "execa library must be installed as a dependency", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 5, "text": "All existing hook tests must continue to pass", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 6, "text": "Non-detached behavior - hooks run attached to fspec process", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 7, "text": "Keep custom timeout implementation integrated with execa - use AbortController signal to cancel subprocess", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 8, "text": "Use execa's input option for passing JSON context - it's the best practice and handles stream management automatically", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" } ], "examples": [ { "id": 0, "text": "Hook executes successfully and returns exitCode 0 with captured stdout/stderr", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 1, "text": "Hook times out after configured timeout period and is killed", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 2, "text": "Hook fails with non-zero exit code and error message in stderr", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 3, "text": "Hook receives context via stdin as JSON string", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 4, "text": "Multiple hooks execute sequentially in order", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" } ], "architectureNotes": [ { "id": 0, "text": "Use execa library (same as cage project) for better process management", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 1, "text": "Modify src/hooks/executor.ts executeHook() function", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 2, "text": "Install execa as dependency in package.json", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 3, "text": "Reference cage's server.ts implementation for execa usage patterns", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" } ], "questions": [ { "id": 0, "text": "@human: Should we support detached processes like cage does for server.ts, or keep the current non-detached behavior?", "selected": true, "answer": "Non-detached behavior - hooks run attached to fspec process", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 1, "text": "@human: Should we use execa's built-in timeout option or keep the custom timeout implementation?", "selected": true, "answer": "Keep custom timeout implementation integrated with execa - use AbortController signal to cancel subprocess", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" }, { "id": 2, "text": "@human: Should we use execa's input option for passing context or stick with stdin.write()?", "selected": true, "answer": "Use execa's input option for passing JSON context - it's the best practice and handles stream management automatically", "deleted": false, "createdAt": "2025-10-16T00:49:47.693Z" } ], "estimate": 3, "nextRuleId": 9, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 4 }, "TEST-004": { "id": "TEST-004", "title": "Write missing tests for partially covered features", "type": "task", "status": "done", "createdAt": "2025-10-16T01:54:24.619Z", "updatedAt": "2025-10-16T11:07:03.554Z", "description": "Complete test coverage for 3 features: architecture-notes-in-example-mapping (2 scenarios), generate-scenarios-include-architecture-docstring (1 scenario), and preserve-example-mapping-context-as-comments-in-generated-feature-files (11 scenarios). Total: 14 uncovered scenarios that need tests.", "children": [], "estimate": 8, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-16T10:32:36.675Z" }, { "state": "implementing", "timestamp": "2025-10-16T10:40:42.515Z" }, { "state": "validating", "timestamp": "2025-10-16T10:50:27.809Z" }, { "state": "done", "timestamp": "2025-10-16T10:50:43.392Z" }, { "state": "implementing", "timestamp": "2025-10-16T10:57:29.589Z" }, { "state": "validating", "timestamp": "2025-10-16T11:07:03.243Z" }, { "state": "done", "timestamp": "2025-10-16T11:07:03.554Z" } ], "questions": [ { "id": 0, "text": "@human: For these uncovered scenarios, should I write (A) full test implementations (traditional forward ACDD) or (B) skeleton tests (reverse ACDD style - structure only with TODOs)?", "selected": true, "answer": "Forward ACDD where there's no implementation/tests, reverse ACDD where there's no tests/features", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" }, { "id": 1, "text": "@human: Should I examine the implementation files (e.g., generate-scenarios.ts, show-work-unit.ts) to infer what the tests should validate for scenarios that have existing code?", "selected": true, "answer": "Yes, examine implementation files to infer what the tests should validate. Figure out what code the test is running by analyzing existing implementation.", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" }, { "id": 2, "text": "@human: Are there any specific testing patterns or conventions in this codebase I should follow when writing tests for the generate-scenarios and example mapping commands?", "selected": true, "answer": "Follow the ACDD process - no special testing patterns beyond what's defined in CLAUDE.md", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" }, { "id": 3, "text": "@human: I see the third feature has 11 uncovered scenarios. Should I tackle all 14 scenarios (2 from architecture-notes + 1 from generate-scenarios-include-architecture + 11 from preserve-example-mapping) in this single work unit, or should I break this into smaller work units?", "selected": true, "answer": "Do all 14 scenarios in one work unit - don't break it up", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" } ], "rules": [ { "id": 0, "text": "Forward ACDD where there's no implementation/tests, reverse ACDD where there's no tests/features", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" }, { "id": 1, "text": "Yes, examine implementation files to infer what the tests should validate. Figure out what code the test is running by analyzing existing implementation.", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" }, { "id": 2, "text": "Do all 14 scenarios in one work unit - don't break it up", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" } ], "assumptions": [ "Follow the ACDD process - no special testing patterns beyond what's defined in CLAUDE.md" ], "examples": [ { "id": 0, "text": "For 'View architecture notes in work unit' scenario - check show-work-unit command displays architecture notes added during example mapping", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" }, { "id": 1, "text": "For scenarios in preserve-example-mapping feature - test that add-scenario and add-background commands don't remove existing example mapping comments", "deleted": false, "createdAt": "2025-10-16T01:54:24.619Z" } ], "nextRuleId": 3, "nextExampleId": 2, "nextQuestionId": 4, "nextNoteId": 0 }, "FOUND-001": { "id": "FOUND-001", "title": "Design Generic Foundation Schema", "type": "story", "status": "done", "createdAt": "2025-10-16T23:12:53.931Z", "updatedAt": "2025-10-17T00:05:44.115Z", "description": "Create new TypeScript types and JSON schema for generic PRD structure focusing on WHY and WHAT", "epic": "foundation-document-redesign", "children": [], "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-16T23:13:02.563Z" }, { "state": "testing", "timestamp": "2025-10-16T23:23:00.347Z" }, { "state": "implementing", "timestamp": "2025-10-17T00:00:17.011Z" }, { "state": "validating", "timestamp": "2025-10-17T00:05:04.272Z" }, { "state": "done", "timestamp": "2025-10-17T00:05:44.116Z" } ], "userStory": { "role": "developer using fspec for any project type", "action": "create a generic foundation document that captures WHY and WHAT", "benefit": "I have clear product requirements without mixing in implementation details" }, "questions": [], "assumptions": [ "Unlimited personas allowed, but suggest 3-7 in documentation as best practice. No hard limits enforced by schema." ], "rules": [ { "id": 0, "text": "Multiple problems supported. Complex products can have thousands of problems. Foundation.json can reference external sub-foundation documents for scalability (all built from single foundation.json). This creates a hierarchical PRD structure.", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 1, "text": "Broad capabilities only (3-7 high-level abilities). Granular features belong in .feature files. Example: 'User Authentication' is a capability in foundation.json, 'Login with OAuth' is a feature in user-authentication.feature.", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 2, "text": "REQUIRED: project identity, problem statement, solution overview. OPTIONAL: architecture diagrams, constraints, detailed personas. This ensures minimum viable PRD while allowing detailed documentation.", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 3, "text": "Schema must focus ONLY on WHY (problem) and WHAT (solution), never HOW (implementation)", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 4, "text": "Schema must work for ANY project type: web apps, CLI tools, libraries, services, mobile apps", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 5, "text": "Mermaid diagram validation must be preserved from current implementation", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 6, "text": "JSON Schema must use Ajv for validation with clear error messages", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" } ], "examples": [ { "id": 0, "text": "Web app foundation includes personas: 'End User', 'Admin', 'API Consumer'", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 1, "text": "CLI tool foundation includes persona: 'Developer using CLI in terminal'", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 2, "text": "Library foundation includes persona: 'Developer integrating library into their codebase'", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 3, "text": "Problem space includes multiple problems with impact ratings (high/medium/low)", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 4, "text": "Solution includes 3-7 high-level capabilities like 'User Authentication', 'Data Visualization', 'API Integration'", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 5, "text": "Foundation.json can reference sub-foundations: { 'subFoundations': ['spec/foundations/auth-subsystem.foundation.json'] }", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" } ], "architectureNotes": [ { "id": 0, "text": "TypeScript interfaces must map exactly to JSON Schema definitions", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 1, "text": "Use Ajv with ajv-formats for validation (uri, email, date-time formats)", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 2, "text": "Hierarchical foundations: parent foundation.json can reference child foundations in subFoundations array", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 3, "text": "Migration path needed: old schema → new schema with backward compatibility flag", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" }, { "id": 4, "text": "Mermaid validation must use mermaid.parse() with jsdom (existing pattern)", "deleted": false, "createdAt": "2025-10-16T23:12:53.931Z" } ], "nextRuleId": 7, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 5 }, "FOUND-002": { "id": "FOUND-002", "title": "Implement Automated Discovery - Code Analysis", "type": "story", "status": "done", "createdAt": "2025-10-16T23:19:35.741Z", "updatedAt": "2025-10-17T02:20:14.997Z", "description": "Scan existing codebase to infer project type, personas, and capabilities using reverse ACDD techniques", "epic": "foundation-document-redesign", "children": [], "estimate": 8, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T00:09:59.672Z" }, { "state": "testing", "timestamp": "2025-10-17T00:29:37.164Z" }, { "state": "implementing", "timestamp": "2025-10-17T00:34:52.164Z" }, { "state": "validating", "timestamp": "2025-10-17T00:37:07.269Z" }, { "state": "done", "timestamp": "2025-10-17T00:38:38.932Z" }, { "state": "implementing", "timestamp": "2025-10-17T02:04:30.871Z" }, { "state": "testing", "timestamp": "2025-10-17T02:05:39.193Z" }, { "state": "specifying", "timestamp": "2025-10-17T02:06:41.226Z" }, { "state": "testing", "timestamp": "2025-10-17T02:17:17.252Z" }, { "state": "implementing", "timestamp": "2025-10-17T02:18:45.665Z" }, { "state": "validating", "timestamp": "2025-10-17T02:19:03.302Z" }, { "state": "done", "timestamp": "2025-10-17T02:20:14.997Z" } ], "userStory": { "role": "developer using fspec to document an existing codebase", "action": "automatically discover project structure and infer personas/capabilities", "benefit": "I can quickly bootstrap a foundation document without manual analysis" }, "rules": [ { "id": 0, "text": "Code analysis must detect project type (web app, CLI tool, library, service, mobile app, desktop app, API)", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 1, "text": "Code analysis must infer personas from user-facing interactions (routes, commands, UI components, API endpoints)", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 2, "text": "Code analysis must infer capabilities from code structure (high-level features, not implementation details)", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 3, "text": "Analysis must be fast enough for interactive use (< 5 seconds for typical projects)", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 4, "text": "fspec provides GUIDANCE to AI, not implementation - AI decides how to analyze code", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 5, "text": "Discovery must infer: project type, personas, capabilities, AND problems/pain points", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 6, "text": "Support monorepos - AI analyzes all packages that are part of the same project", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" } ], "examples": [ { "id": 0, "text": "CLI tool with commander.js commands → project type: cli-tool, persona: Developer using CLI", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 1, "text": "Express.js with /api routes → project type: web-app, personas: API Consumer, End User", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 2, "text": "Package with exports in package.json → project type: library, persona: Developer integrating library", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 3, "text": "React components in src/ → capability: User Interface, not implementation detail like 'Uses React hooks'", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 4, "text": "AI discovers React app → infers problem: 'Users need interactive web UI' not 'Code needs React'", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" } ], "questions": [ { "id": 0, "text": "@human: Should code analysis support monorepos with multiple package.json files, or just single-project repositories?", "selected": true, "answer": "Yes, support monorepos - analyze all package.json files that are part of the same project", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 1, "text": "@human: What file patterns should we analyze to detect project type? (package.json, tsconfig.json, Cargo.toml, go.mod, etc.)", "selected": true, "answer": "AI decides file patterns - fspec guides AI to discover project type using available clues, not prescriptive tool list", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 2, "text": "@human: Should we infer problems/pain points from code, or only project type and personas?", "selected": true, "answer": "Yes, infer everything: project type, personas, capabilities, AND problems/pain points - all critical for complete foundation", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" }, { "id": 3, "text": "@human: How deep should directory traversal go? Should we limit to specific directories (src/, lib/, cmd/) or scan entire project?", "selected": true, "answer": "AI decides traversal depth - fspec guides AI to intelligently explore codebase, not prescriptive directory limits", "deleted": false, "createdAt": "2025-10-16T23:19:35.741Z" } ], "nextRuleId": 7, "nextExampleId": 5, "nextQuestionId": 4, "nextNoteId": 0 }, "FOUND-003": { "id": "FOUND-003", "title": "Implement Interactive Questionnaire", "type": "story", "status": "done", "createdAt": "2025-10-16T23:19:36.482Z", "updatedAt": "2025-10-17T00:55:12.776Z", "description": "Build Ink-based CLI questionnaire to gather WHY/WHAT information from users", "epic": "foundation-document-redesign", "children": [], "estimate": 5, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-16T23:20:17.487Z" }, { "state": "testing", "timestamp": "2025-10-17T00:45:42.074Z" }, { "state": "implementing", "timestamp": "2025-10-17T00:47:44.622Z" }, { "state": "validating", "timestamp": "2025-10-17T00:54:48.957Z" }, { "state": "done", "timestamp": "2025-10-17T00:55:12.776Z" } ], "architectureNotes": [ { "id": 0, "text": "Questionnaire must guide AI through structured discovery workflow with specific question templates", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 1, "text": "Section 1: Vision Questions - 'What is the core purpose?', 'Who are the primary users?', 'What problem does this solve?'", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 2, "text": "Section 2: Problem Space - 'What are the top 3-5 pain points?', 'What is the impact?', 'What is the frequency?'", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 3, "text": "Section 3: Solution Space - 'What are the 3-7 key capabilities?', 'What makes this solution unique?', 'What is out of scope?'", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 4, "text": "Section 4: Architecture - 'What is the tech stack?' (optional if detected), 'What are system boundaries?', 'What are external dependencies?'", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 5, "text": "Section 5: Constraints - 'Business constraints?', 'Technical constraints?', 'Timeline/budget constraints?'", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 6, "text": "Prefill mode: If code analysis detected values, show as defaults with [DETECTED] tag, allow AI to confirm/edit/skip", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 7, "text": "AI guidance: Each question includes HELP text explaining WHY it's asked and EXAMPLES of good answers", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" } ], "rules": [ { "id": 0, "text": "Questions must be grouped by section with progress indicator (Question 3 of 15)", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 1, "text": "Must support both prefilled mode (--from-discovery) and blank slate (--interactive)", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 2, "text": "Must validate answers before accepting (e.g. non-empty strings, valid format)", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" } ], "examples": [ { "id": 0, "text": "Vision question with help: 'What is the core purpose? [HELP: One sentence elevator pitch. Example: fspec helps AI agents follow ACDD workflow]'", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" }, { "id": 1, "text": "Prefilled answer: 'Primary user: Developer using CLI [DETECTED from code analysis] - Keep/Edit/Skip?'", "deleted": false, "createdAt": "2025-10-16T23:19:36.482Z" } ], "userStory": { "role": "developer using fspec with AI to bootstrap foundation documents", "action": "gather WHY/WHAT information through structured questionnaire", "benefit": "I can create complete foundation.json without manual analysis" }, "nextRuleId": 3, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 8 }, "FOUND-004": { "id": "FOUND-004", "title": "Implement discover-foundation Command", "type": "story", "status": "done", "createdAt": "2025-10-16T23:19:37.238Z", "updatedAt": "2025-10-17T02:15:18.183Z", "description": "Orchestrate code analysis + questionnaire to generate foundation.json with validation", "epic": "foundation-document-redesign", "children": [], "estimate": 8, "dependsOn": [ "FOUND-001", "FOUND-002", "FOUND-003" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-16T23:20:49.620Z" }, { "state": "testing", "timestamp": "2025-10-17T00:58:37.167Z" }, { "state": "implementing", "timestamp": "2025-10-17T00:59:52.936Z" }, { "state": "validating", "timestamp": "2025-10-17T01:01:33.811Z" }, { "state": "done", "timestamp": "2025-10-17T01:01:53.733Z" }, { "state": "implementing", "timestamp": "2025-10-17T02:04:31.237Z" }, { "state": "testing", "timestamp": "2025-10-17T02:05:39.561Z" }, { "state": "specifying", "timestamp": "2025-10-17T02:06:41.599Z" }, { "state": "testing", "timestamp": "2025-10-17T02:08:36.356Z" }, { "state": "implementing", "timestamp": "2025-10-17T02:11:49.901Z" }, { "state": "validating", "timestamp": "2025-10-17T02:13:55.861Z" }, { "state": "done", "timestamp": "2025-10-17T02:15:18.183Z" } ], "architectureNotes": [ { "id": 0, "text": "System-reminder integration: Wrap questionnaire output in <system-reminder> tags when running in AI context (detectable via environment)", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" }, { "id": 1, "text": "System-reminder triggers: (1) After code analysis completes - show detected personas/capabilities (2) During questionnaire - provide examples of good answers (3) After foundation.json generated - next steps guidance", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" }, { "id": 2, "text": "System-reminder content: 'Code analysis detected 3 personas [list]. Review and confirm during questionnaire. Focus on WHY/WHAT, not HOW. See CLAUDE.md for boundary guidance.'", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" } ], "rules": [ { "id": 0, "text": "Must emit system-reminders to guide AI through discovery process (persona review, WHY/WHAT boundary, next steps)", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" }, { "id": 1, "text": "The command should output all questions at once in a structured format. The AI (Claude) sees the questions, analyzes the codebase based on the guidance, and then the command collects answers through a partial foundation.json file that the AI edits.", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" }, { "id": 2, "text": "The command creates a partial foundation.json with prefilled [DETECTED] values and [QUESTION] placeholders. The AI edits this file directly using Write/Edit tools, filling in answers based on code analysis. Then running the command again validates and completes the foundation.", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" }, { "id": 3, "text": "Two-phase execution: (1) First run outputs questions and creates partial foundation.json with placeholders. AI edits the file. (2) Second run (or --finalize flag) validates the completed foundation.json and writes the final version.", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" } ], "examples": [ { "id": 0, "text": "After code analysis: <system-reminder>Detected 3 user personas from routes: End User, Admin, API Consumer. Review in questionnaire. Use 'fspec show-work-unit FOUND-002' for details.</system-reminder>", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" } ], "userStory": { "role": "developer using fspec with AI to bootstrap foundation documents", "action": "run discover-foundation command to orchestrate analysis and questionnaire", "benefit": "I get a complete validated foundation.json without manual work" }, "questions": [ { "id": 0, "text": "@human: How should the interactive questionnaire work? Does it output all questions at once and expect answers in a file, or does it prompt question-by-question?", "selected": true, "answer": "The command should output all questions at once in a structured format. The AI (Claude) sees the questions, analyzes the codebase based on the guidance, and then the command collects answers through a partial foundation.json file that the AI edits.", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" }, { "id": 1, "text": "@human: When the command outputs questions, how does the AI provide answers? Through command arguments, through editing a file, or through some other mechanism?", "selected": true, "answer": "The command creates a partial foundation.json with prefilled [DETECTED] values and [QUESTION] placeholders. The AI edits this file directly using Write/Edit tools, filling in answers based on code analysis. Then running the command again validates and completes the foundation.", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" }, { "id": 2, "text": "@human: Should the command run multiple times (once to output questions, again to collect answers), or should it be a single execution that somehow waits for input?", "selected": true, "answer": "Two-phase execution: (1) First run outputs questions and creates partial foundation.json with placeholders. AI edits the file. (2) Second run (or --finalize flag) validates the completed foundation.json and writes the final version.", "deleted": false, "createdAt": "2025-10-16T23:19:37.238Z" } ], "nextRuleId": 4, "nextExampleId": 1, "nextQuestionId": 3, "nextNoteId": 3 }, "FOUND-005": { "id": "FOUND-005", "title": "Migrate Existing foundation.json", "type": "story", "status": "done", "createdAt": "2025-10-16T23:19:38.001Z", "updatedAt": "2025-10-17T01:09:17.482Z", "description": "Extract WHY/WHAT from current fspec foundation.json, move HOW content elsewhere, automated migration", "epic": "foundation-document-redesign", "children": [], "estimate": 3, "dependsOn": [ "FOUND-001" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T01:03:24.343Z" }, { "state": "testing", "timestamp": "2025-10-17T01:05:56.004Z" }, { "state": "implementing", "timestamp": "2025-10-17T01:07:10.808Z" }, { "state": "validating", "timestamp": "2025-10-17T01:08:03.028Z" }, { "state": "done", "timestamp": "2025-10-17T01:09:17.482Z" } ], "userStory": { "role": "developer migrating fspec to generic foundation schema", "action": "migrate existing foundation.json to v2.0.0 format", "benefit": "foundation document follows the new generic schema and supports all project types" }, "rules": [ { "id": 0, "text": "Must preserve all existing architecture diagrams in architectureDiagrams array", "deleted": false, "createdAt": "2025-10-16T23:19:38.001Z" }, { "id": 1, "text": "WHY/WHAT content stays in foundation.json, HOW content moves to CLAUDE.md or other docs", "deleted": false, "createdAt": "2025-10-16T23:19:38.001Z" }, { "id": 2, "text": "Migration must be automated via CLI command 'fspec migrate-foundation'", "deleted": false, "createdAt": "2025-10-16T23:19:38.001Z" }, { "id": 3, "text": "Migrated foundation.json must pass generic foundation schema validation", "deleted": false, "createdAt": "2025-10-16T23:19:38.001Z" } ], "examples": [ { "id": 0, "text": "Current 'whatWeAreBuilding.projectOverview' maps to 'project.vision'", "deleted": false, "createdAt": "2025-10-16T23:19:38.001Z" }, { "id": 1, "text": "Current 'whyWeAreBuildingIt.problemDefinition.primary' maps to 'problemSpace.primaryProblem'", "deleted": false, "createdAt": "2025-10-16T23:19:38.001Z" }, { "id": 2, "text": "Current 'architectureDiagrams' array preserved as-is (already compatible)", "deleted": false, "createdAt": "2025-10-16T23:19:38.001Z" }, { "id": 3, "text": "HOW content like 'technicalRequirements.coreTechnologies' moves to CLAUDE.md", "deleted": false, "createdAt": "2025-10-16T23:19:38.001Z" } ], "nextRuleId": 4, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "FOUND-006": { "id": "FOUND-006", "title": "Update Documentation and Help", "type": "story", "status": "done", "createdAt": "2025-10-16T23:19:38.837Z", "updatedAt": "2025-10-17T01:23:48.715Z", "description": "Update CLAUDE.md, help system, and create discovery guide with examples", "epic": "foundation-document-redesign", "children": [], "estimate": 3, "dependsOn": [ "FOUND-004" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T01:09:42.788Z" }, { "state": "testing", "timestamp": "2025-10-17T01:11:37.151Z" }, { "state": "implementing", "timestamp": "2025-10-17T01:12:53.339Z" }, { "state": "validating", "timestamp": "2025-10-17T01:12:53.748Z" }, { "state": "done", "timestamp": "2025-10-17T01:14:09.494Z" }, { "state": "implementing", "timestamp": "2025-10-17T01:16:23.508Z" }, { "state": "validating", "timestamp": "2025-10-17T01:23:09.031Z" }, { "state": "done", "timestamp": "2025-10-17T01:23:48.716Z" } ], "userStory": { "role": "developer using fspec for foundation document discovery", "action": "have comprehensive documentation and help for discovery commands", "benefit": "I can effectively use discover-foundation, questionnaire, and code analysis features" }, "rules": [ { "id": 0, "text": "CLAUDE.md must document discover-foundation workflow with examples", "deleted": false, "createdAt": "2025-10-16T23:19:38.837Z" }, { "id": 1, "text": "Help system must have comprehensive --help output for discover-foundation command", "deleted": false, "createdAt": "2025-10-16T23:19:38.837Z" }, { "id": 2, "text": "Discovery guide must explain code analysis patterns (CLI tool, web app, library)", "deleted": false, "createdAt": "2025-10-16T23:19:38.837Z" }, { "id": 3, "text": "Documentation must show integration with Example Mapping workflow", "deleted": false, "createdAt": "2025-10-16T23:19:38.837Z" } ], "examples": [ { "id": 0, "text": "CLAUDE.md shows: 'Run discover-foundation to analyze codebase and generate foundation.json'", "deleted": false, "createdAt": "2025-10-16T23:19:38.837Z" }, { "id": 1, "text": "Help output includes WHEN TO USE, WORKFLOW, and EXAMPLES sections", "deleted": false, "createdAt": "2025-10-16T23:19:38.837Z" }, { "id": 2, "text": "Discovery guide explains CLI tool pattern: bin field in package.json, commander usage", "deleted": false, "createdAt": "2025-10-16T23:19:38.837Z" } ], "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-012": { "id": "BUG-012", "title": "Fix show-epic command returning undefined", "type": "bug", "status": "done", "createdAt": "2025-10-16T23:24:12.754Z", "updatedAt": "2025-10-16T23:28:27.652Z", "description": "The show-epic command accepts invalid epic IDs and returns 'undefined' for epic and title instead of showing proper error message or help text", "children": [], "estimate": 2, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-16T23:25:18.576Z" }, { "state": "testing", "timestamp": "2025-10-16T23:25:51.736Z" }, { "state": "implementing", "timestamp": "2025-10-16T23:26:50.136Z" }, { "state": "validating", "timestamp": "2025-10-16T23:27:29.673Z" }, { "state": "done", "timestamp": "2025-10-16T23:28:27.652Z" } ], "userStory": { "role": "developer using fspec", "action": "see a clear error when querying non-existent epics", "benefit": "I understand what went wrong and how to fix it" }, "rules": [ { "id": 0, "text": "Command must validate epic ID exists before attempting to display", "deleted": false, "createdAt": "2025-10-16T23:24:12.754Z" }, { "id": 1, "text": "Must show clear error message with epic ID when not found", "deleted": false, "createdAt": "2025-10-16T23:24:12.754Z" }, { "id": 2, "text": "Must exit with non-zero code on error", "deleted": false, "createdAt": "2025-10-16T23:24:12.754Z" } ], "examples": [ { "id": 0, "text": "Run 'fspec show-epic invalid-epic' shows error: Epic 'invalid-epic' not found", "deleted": false, "createdAt": "2025-10-16T23:24:12.754Z" }, { "id": 1, "text": "Error message suggests 'fspec list-epics' to see available epics", "deleted": false, "createdAt": "2025-10-16T23:24:12.754Z" }, { "id": 2, "text": "Valid epic ID works correctly: 'fspec show-epic user-management' displays epic details", "deleted": false, "createdAt": "2025-10-16T23:24:12.754Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-013": { "id": "BUG-013", "title": "Prevent story point estimation before feature file completion", "type": "story", "status": "done", "createdAt": "2025-10-16T23:34:28.036Z", "updatedAt": "2025-10-16T23:44:51.565Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-16T23:34:32.599Z" }, { "state": "testing", "timestamp": "2025-10-16T23:36:34.521Z" }, { "state": "implementing", "timestamp": "2025-10-16T23:37:23.155Z" }, { "state": "validating", "timestamp": "2025-10-16T23:44:34.790Z" }, { "state": "done", "timestamp": "2025-10-16T23:44:51.565Z" } ], "userStory": { "role": "AI agent using fspec", "action": "be prevented from estimating story points before feature file is complete", "benefit": "I follow ACDD properly and estimate based on actual acceptance criteria" }, "rules": [ { "id": 0, "text": "Story and Bug work units CANNOT be estimated until feature file exists and is complete (specifying phase finished)", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 1, "text": "Task work units CAN be estimated at any stage (tasks don't require feature files)", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 2, "text": "When AI attempts invalid estimation, emit system-reminder explaining ACDD estimation rules", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 3, "text": "Estimation requires completed feature file to understand complexity from acceptance criteria", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" } ], "examples": [ { "id": 0, "text": "Story work unit AUTH-001 in 'backlog' state with no feature file → estimation BLOCKED with system-reminder", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 1, "text": "Story work unit AUTH-001 in 'testing' state with completed feature file → estimation ALLOWED", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 2, "text": "Task work unit TASK-001 in 'backlog' state with no feature file → estimation ALLOWED (tasks exempt)", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 3, "text": "Bug work unit BUG-001 in 'specifying' state but feature file has placeholders → estimation BLOCKED until prefill removed", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" } ], "architectureNotes": [ { "id": 0, "text": "Check work unit type: if type='task', skip validation (tasks don't require feature files)", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 1, "text": "For story/bug types: find linked feature file via work unit ID tag (e.g., @AUTH-001)", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 2, "text": "If no feature file found OR file has prefill placeholders, block estimation and emit system-reminder", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 3, "text": "System-reminder should explain: ACDD requires feature file completion before estimation, suggest completing specifying phase first", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" }, { "id": 4, "text": "Reuse existing prefill detection logic from temporal validation (similar pattern)", "deleted": false, "createdAt": "2025-10-16T23:34:28.036Z" } ], "estimate": 2, "nextRuleId": 4, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 5 }, "FOUND-007": { "id": "FOUND-007", "title": "Foundation existence check in commands", "type": "story", "status": "done", "createdAt": "2025-10-17T01:22:59.515Z", "updatedAt": "2025-10-25T19:37:43.615Z", "description": "Add check for foundation.json existence in key commands (board, create-work-unit, etc.). Commands should exit with helpful message if foundation.json missing, directing user to run discover-foundation first. CRITICAL: System reminder must tell AI agent to return to the original task after completing discover-foundation command.", "epic": "foundation-document-redesign", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T01:25:10.420Z" }, { "state": "testing", "timestamp": "2025-10-17T01:30:47.830Z" }, { "state": "implementing", "timestamp": "2025-10-17T01:32:38.194Z" }, { "state": "validating", "timestamp": "2025-10-17T01:38:39.487Z" }, { "state": "done", "timestamp": "2025-10-17T01:38:58.984Z" }, { "state": "implementing", "timestamp": "2025-10-17T01:43:25.715Z" }, { "state": "validating", "timestamp": "2025-10-17T01:49:24.427Z" }, { "state": "done", "timestamp": "2025-10-17T01:49:42.199Z" }, { "state": "validating", "timestamp": "2025-10-25T12:34:11.337Z" }, { "state": "done", "timestamp": "2025-10-25T19:37:43.615Z" } ], "userStory": { "role": "AI agent using fspec", "action": "ensure foundation.json exists before running project management commands", "benefit": "I prevent work from proceeding without proper project foundation and can resume my original task after discovery" }, "rules": [ { "id": 0, "text": "Commands that manage work units MUST check for foundation.json existence before executing", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 1, "text": "If foundation.json is missing, command MUST exit with error code 1 and display helpful message", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 2, "text": "Error message MUST direct user to run 'fspec discover-foundation' command", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 3, "text": "System reminder MUST tell AI agent to return to original task after discover-foundation completes", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 4, "text": "Check applies to: fspec board, create-work-unit, update-work-unit-status, create-epic, and other PM commands", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 5, "text": "Yes, include exact command arguments. System reminders in Claude Code are used for actionable guidance - including the original command makes it clear what to retry after discover-foundation completes.", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 6, "text": "No, only create/modify commands need foundation.json. Read-only commands like show-foundation, list-features, validate can run without foundation.json.", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 7, "text": "Check only spec/foundation.json - this is the canonical location used by show-foundation, update-foundation, and generate-foundation-md commands.", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec board' without foundation.json → Command exits with error, displays message with discover-foundation instructions, system reminder tells AI to run board again after discovery", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 1, "text": "AI runs 'fspec create-story AUTH \"Login\"' without foundation.json → Command exits with error, system reminder includes original command to retry", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 2, "text": "AI runs 'fspec board' with foundation.json present → Command executes normally, no check triggered", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 3, "text": "AI runs 'fspec validate' (non-PM command) without foundation.json → Command executes normally, foundation check not required for spec-only commands", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" } ], "questions": [ { "id": 0, "text": "@human: Should the system reminder include the exact command arguments that were originally attempted?", "selected": true, "answer": "Yes, include exact command arguments. System reminders in Claude Code are used for actionable guidance - including the original command makes it clear what to retry after discover-foundation completes.", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 1, "text": "@human: Should read-only commands like 'fspec show-foundation' also require foundation.json, or only commands that create/modify work units?", "selected": true, "answer": "No, only create/modify commands need foundation.json. Read-only commands like show-foundation, list-features, validate can run without foundation.json.", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" }, { "id": 2, "text": "@human: Should the check look for BOTH foundation.json AND spec/foundation.json paths, or just spec/foundation.json?", "selected": true, "answer": "Check only spec/foundation.json - this is the canonical location used by show-foundation, update-foundation, and generate-foundation-md commands.", "deleted": false, "createdAt": "2025-10-17T01:22:59.515Z" } ], "estimate": 3, "nextRuleId": 8, "nextExampleId": 4, "nextQuestionId": 3, "nextNoteId": 0 }, "BUG-014": { "id": "BUG-014", "title": "validate-foundation-schema uses wrong schema for generic foundations", "type": "bug", "status": "done", "createdAt": "2025-10-17T02:39:24.338Z", "updatedAt": "2025-10-17T02:43:30.783Z", "description": "The validate-foundation-schema command validates against fspec-specific schema instead of detecting schema version and using appropriate validator (generic v2.0.0 or fspec-specific)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T02:39:28.719Z" }, { "state": "testing", "timestamp": "2025-10-17T02:40:53.846Z" }, { "state": "implementing", "timestamp": "2025-10-17T02:41:31.662Z" }, { "state": "validating", "timestamp": "2025-10-17T02:43:24.348Z" }, { "state": "done", "timestamp": "2025-10-17T02:43:30.783Z" } ], "userStory": { "role": "developer using fspec", "action": "validate foundation.json files", "benefit": "I get correct validation regardless of schema version" }, "rules": [ { "id": 0, "text": "Command must detect schema version from foundation.json 'version' field", "deleted": false, "createdAt": "2025-10-17T02:39:24.338Z" }, { "id": 1, "text": "Version 2.0.0 and above should use generic-foundation-validator", "deleted": false, "createdAt": "2025-10-17T02:39:24.338Z" }, { "id": 2, "text": "Version 1.x should use fspec-specific validator for backward compatibility", "deleted": false, "createdAt": "2025-10-17T02:39:24.338Z" } ], "examples": [ { "id": 0, "text": "Foundation with version: 2.0.0 validates using generic schema successfully", "deleted": false, "createdAt": "2025-10-17T02:39:24.338Z" }, { "id": 1, "text": "Foundation with version: 1.0.0 validates using fspec-specific schema", "deleted": false, "createdAt": "2025-10-17T02:39:24.338Z" } ], "nextRuleId": 3, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "TEST-005": { "id": "TEST-005", "title": "Update test fixtures to use generic foundation schema", "type": "task", "status": "done", "createdAt": "2025-10-17T02:53:51.917Z", "updatedAt": "2025-10-17T04:36:30.647Z", "description": "Update test fixtures in 9 test files that are currently using old fspec-specific schema format to use the new generic v2.0.0 schema format. This is cleanup work following BUG-014 where we simplified validate-foundation-schema to only use generic schema.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T04:36:22.446Z" }, { "state": "implementing", "timestamp": "2025-10-17T04:36:30.071Z" }, { "state": "validating", "timestamp": "2025-10-17T04:36:30.360Z" }, { "state": "done", "timestamp": "2025-10-17T04:36:30.647Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "REFAC-001": { "id": "REFAC-001", "title": "Migrate old fspec-specific schema commands to generic schema", "type": "task", "status": "done", "createdAt": "2025-10-17T03:12:44.169Z", "updatedAt": "2025-10-17T04:25:47.145Z", "description": "Complete migration from old foundation.schema.json (fspec-specific) to generic-foundation.schema.json. Update all commands and tests that still reference whatWeAreBuilding/whyWeAreBuildingIt fields.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T03:13:09.841Z" }, { "state": "implementing", "timestamp": "2025-10-17T03:13:10.534Z" }, { "state": "validating", "timestamp": "2025-10-17T04:18:34.350Z" }, { "state": "done", "timestamp": "2025-10-17T04:25:47.145Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "COV-052": { "id": "COV-052", "title": "Fix coverage gaps and align with foundation v2.0.0 migration", "type": "task", "status": "done", "createdAt": "2025-10-17T04:41:45.465Z", "updatedAt": "2025-10-17T04:50:39.148Z", "description": "Complete coverage mapping for all features, remove obsolete foundation-schema-guidance references, and ensure 100% coverage after REFAC-001 migration", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T04:41:57.147Z" }, { "state": "implementing", "timestamp": "2025-10-17T04:41:57.435Z" }, { "state": "validating", "timestamp": "2025-10-17T04:44:59.582Z" }, { "state": "done", "timestamp": "2025-10-17T04:46:21.862Z" }, { "state": "done", "timestamp": "2025-10-17T04:50:39.148Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "HELP-001": { "id": "HELP-001", "title": "Audit and sync all help files with command implementations", "type": "task", "status": "done", "createdAt": "2025-10-17T04:55:11.179Z", "updatedAt": "2025-10-17T05:24:40.447Z", "description": "Verify every command help file (src/commands/*-help.ts) accurately reflects the actual command arguments, options, and behavior registered with Commander.js. Ensure src/help.ts grouping is complete and accurate.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T04:55:17.079Z" }, { "state": "implementing", "timestamp": "2025-10-17T04:55:17.370Z" }, { "state": "validating", "timestamp": "2025-10-17T05:24:40.157Z" }, { "state": "done", "timestamp": "2025-10-17T05:24:40.447Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "HELP-002": { "id": "HELP-002", "title": "Register 7 missing commands with Commander", "type": "task", "status": "done", "createdAt": "2025-10-17T05:37:10.832Z", "updatedAt": "2025-10-17T05:42:41.825Z", "description": "7 fully-implemented commands with help files are not registered with Commander.js: add-hook, list-hooks, remove-hook, validate-hooks, dependencies, workflow-automation, migrate-foundation. Also remove 2 duplicate legacy help files (delete-features-help.ts, delete-scenarios-help.ts).", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T05:37:22.320Z" }, { "state": "implementing", "timestamp": "2025-10-17T05:37:27.623Z" }, { "state": "validating", "timestamp": "2025-10-17T05:42:41.537Z" }, { "state": "done", "timestamp": "2025-10-17T05:42:41.825Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "FOUND-009": { "id": "FOUND-009", "title": "Foundation missing error message is not imperative enough", "type": "bug", "status": "done", "createdAt": "2025-10-17T05:57:24.673Z", "updatedAt": "2025-10-17T06:04:32.745Z", "description": "When foundation.json is missing, the error message in src/utils/foundation-check.ts is not imperative or detailed enough. It must: (1) FORBID manual JSON creation, (2) Explain the complete interactive workflow, (3) Emphasize foundation.json is a detailed PRD not a summary, (4) Show exact command sequence for draft->finalize workflow", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T05:57:49.057Z" }, { "state": "testing", "timestamp": "2025-10-17T05:59:37.205Z" }, { "state": "specifying", "timestamp": "2025-10-17T06:01:14.358Z" }, { "state": "testing", "timestamp": "2025-10-17T06:02:04.914Z" }, { "state": "implementing", "timestamp": "2025-10-17T06:02:43.048Z" }, { "state": "validating", "timestamp": "2025-10-17T06:03:26.554Z" }, { "state": "done", "timestamp": "2025-10-17T06:04:32.745Z" } ], "userStory": { "role": "AI agent without foundation.json", "action": "receive imperative guidance on foundation discovery workflow", "benefit": "I follow the correct interactive workflow instead of manually creating JSON files" }, "rules": [ { "id": 0, "text": "Error message must FORBID manual creation of foundation.json files", "deleted": false, "createdAt": "2025-10-17T05:57:24.673Z" }, { "id": 1, "text": "Error message must explain foundation.json is a detailed PRD, not a quick summary", "deleted": false, "createdAt": "2025-10-17T05:57:24.673Z" }, { "id": 2, "text": "Error message must show exact command sequence: discover-foundation creates draft, AI fills placeholders, discover-foundation --finalize creates final file", "deleted": false, "createdAt": "2025-10-17T05:57:24.673Z" } ], "examples": [ { "id": 0, "text": "AI tries to create work unit, gets error saying 'NEVER manually create foundation.json - use discover-foundation workflow'", "deleted": false, "createdAt": "2025-10-17T05:57:24.673Z" }, { "id": 1, "text": "Error message shows: Step 1: fspec discover-foundation (creates draft), Step 2: Fill [QUESTION:] placeholders, Step 3: fspec discover-foundation --finalize", "deleted": false, "createdAt": "2025-10-17T05:57:24.673Z" } ], "estimate": 2, "nextRuleId": 3, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "FOUND-010": { "id": "FOUND-010", "title": "Project type detection incorrectly identifies CLI tools as web-apps", "type": "bug", "status": "done", "createdAt": "2025-10-17T05:57:26.180Z", "updatedAt": "2025-10-17T06:27:34.821Z", "description": "The discover-foundation command should NOT have automated project type detection. It must be 100% interactive questionnaire where AI asks human about project type, personas, capabilities. Remove all automated detection code from src/guidance/automated-discovery-code-analysis.ts", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T06:05:33.155Z" }, { "state": "testing", "timestamp": "2025-10-17T06:06:27.667Z" }, { "state": "specifying", "timestamp": "2025-10-17T06:07:40.429Z" }, { "state": "testing", "timestamp": "2025-10-17T06:08:47.536Z" }, { "state": "implementing", "timestamp": "2025-10-17T06:09:16.927Z" }, { "state": "specifying", "timestamp": "2025-10-17T06:17:17.434Z" }, { "state": "testing", "timestamp": "2025-10-17T06:20:43.565Z" }, { "state": "implementing", "timestamp": "2025-10-17T06:24:08.400Z" }, { "state": "validating", "timestamp": "2025-10-17T06:26:18.558Z" }, { "state": "done", "timestamp": "2025-10-17T06:27:34.821Z" } ], "userStory": { "role": "AI agent running discover-foundation", "action": "correctly detect CLI tool projects", "benefit": "foundation.json has accurate project type and personas" }, "rules": [ { "id": 0, "text": "foundation.json.draft IS the guidance file - it defines structure and what needs to be filled", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 1, "text": "Draft contains [QUESTION: text] placeholders for fields requiring human/AI input", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 2, "text": "Draft contains [DETECTED: value] for auto-detected fields that AI should verify with human", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 3, "text": "discover-foundation reads draft and identifies unfilled/placeholder fields", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 4, "text": "For each unfilled field, command emits system-reminder prompting AI to gather information", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 5, "text": "AI must analyze codebase AND ask human to gather accurate information", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 6, "text": "AI must use fspec update-foundation command to set values (NOT manual editing)", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 7, "text": "After each field is set, command re-reads draft and chains to next unfilled field", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 8, "text": "When all [QUESTION:] placeholders resolved, command validates against JSON schema", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 9, "text": "Final step: command creates foundation.json and deletes draft", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" } ], "examples": [ { "id": 0, "text": "Draft has projectType:[QUESTION: What type?] → Command prompts AI → AI analyzes commander.js usage → AI asks human 'Is this cli-tool, web-app, or library?' → Human: 'cli-tool' → AI runs: fspec update-foundation --field project.projectType --value cli-tool → Command re-reads draft and moves to next field", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 1, "text": "Draft has personas with [QUESTION: Describe persona] → Command prompts AI to gather persona info → AI analyzes CLI commands, no web UI → AI asks human 'Who uses this and their goals?' → Human: 'Developers in terminal managing specs' → AI runs: fspec update-foundation --field personas[0].description --value 'Developer using fspec to manage Gherkin specs' → Command chains to next field", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 2, "text": "Draft has all [QUESTION:] resolved → Command validates against schema → If valid: creates foundation.json, deletes draft → If invalid: shows validation errors, prompts AI to fix", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 3, "text": "AI tries to manually edit foundation.json.draft → Command detects file change outside fspec → Emits system-reminder: 'You must use fspec update-foundation commands, not manual editing'", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" }, { "id": 4, "text": "Draft has [DETECTED: web-app] for projectType → Command prompts AI to verify → AI asks human 'Detected web-app, is this correct?' → Human: 'No, it's cli-tool' → AI runs: fspec update-foundation --field project.projectType --value cli-tool", "deleted": false, "createdAt": "2025-10-17T05:57:26.180Z" } ], "estimate": 3, "nextRuleId": 10, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "DISC-001": { "id": "DISC-001", "title": "Implement draft-driven discovery workflow with AI chaining", "type": "story", "status": "done", "createdAt": "2025-10-17T06:32:17.502Z", "updatedAt": "2025-10-17T07:03:28.396Z", "description": "discover-foundation must read draft, identify next unfilled field, prompt AI with system-reminders, re-read after each fspec update-foundation command, chain to next field, validate when complete, and auto-regenerate FOUNDATION.md from foundation.json", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T06:32:29.265Z" }, { "state": "testing", "timestamp": "2025-10-17T06:49:02.418Z" }, { "state": "implementing", "timestamp": "2025-10-17T06:51:45.257Z" }, { "state": "validating", "timestamp": "2025-10-17T06:57:04.523Z" }, { "state": "done", "timestamp": "2025-10-17T06:57:23.540Z" }, { "state": "implementing", "timestamp": "2025-10-17T06:58:27.988Z" }, { "state": "validating", "timestamp": "2025-10-17T07:03:05.753Z" }, { "state": "done", "timestamp": "2025-10-17T07:03:28.396Z" } ], "userStory": { "role": "AI agent running discover-foundation", "action": "be guided step-by-step through filling foundation.json.draft", "benefit": "foundation.json is created accurately with all required fields and FOUNDATION.md is auto-generated" }, "rules": [ { "id": 0, "text": "discover-foundation creates foundation.json.draft with [QUESTION:] and [DETECTED:] placeholders", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 1, "text": "After creating draft, command scans for FIRST unfilled [QUESTION:] field", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 2, "text": "For each unfilled field, command emits system-reminder with: field path, guidance text, example values", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 3, "text": "System-reminder instructs AI to: analyze codebase, ask human, use fspec update-foundation command", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 4, "text": "After AI runs fspec update-foundation, command automatically re-runs to find NEXT unfilled field", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 5, "text": "Command must NOT advance if AI tries to manually edit draft - emit system-reminder to use commands", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 6, "text": "When all [QUESTION:] placeholders resolved, command validates draft against JSON schema", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 7, "text": "If validation passes: create foundation.json, delete draft, auto-run fspec generate-foundation-md", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 8, "text": "If validation fails: show errors, keep draft, prompt AI to fix and re-run", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 9, "text": "[DETECTED:] fields must be verified with human before accepting", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 10, "text": "Command tracks progress: shows N of M fields completed in each system-reminder", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 11, "text": "System-reminders must be actionable: specific field, specific command to run, example value", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 12, "text": "AI must NEVER skip fields - command enforces sequential field completion", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 13, "text": "Final FOUNDATION.md generation happens automatically without AI intervention", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 14, "text": "Command must detect if draft was manually edited between runs and reject with error", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" } ], "examples": [ { "id": 0, "text": "INITIAL RUN: Human runs 'fspec discover-foundation' → Command creates foundation.json.draft with structure → Draft has REQUIRED fields: project{name,vision,projectType}, problemSpace{primaryProblem{title,description,impact}}, solutionSpace{overview,capabilities[]}, personas[] → All fields contain [QUESTION: ...] or [DETECTED: ...] placeholders → Command emits system-reminder: 'Draft created. To complete foundation, you must ULTRATHINK the entire codebase. Analyze EVERYTHING: commands, routes, UI, tests, README, package.json. Understand HOW it works, then determine WHY it exists and WHAT users can do. I will guide you field-by-field. Field 1/9: project.name'", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 1, "text": "FIELD 1 (project.name): Command reads draft → Finds [QUESTION: What is the project name?] → Emits: 'Field 1/9: project.name. Analyze package.json name field. Confirm with human. Run: fspec update-foundation --field project.name --value <name>' → AI reads package.json, sees 'fspec' → AI asks human 'Package name is fspec, correct?' → Human confirms → AI runs 'fspec update-foundation --field project.name --value fspec' → Command detects update, re-scans draft, finds next unfilled field", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 2, "text": "FIELD 2 (project.vision): Command re-scans → Finds [QUESTION: What is the one-sentence vision?] → Emits: 'Field 2/9: project.vision (elevator pitch). ULTRATHINK: Read ALL code, understand the system deeply. What is the core PURPOSE? Focus on WHY this exists, not HOW it works. Ask human. Run: fspec update-foundation --field project.vision --value \"your vision\"' → AI reads README, analyzes commands (validate, format, list-features), understands it manages Gherkin specs → AI formulates: 'CLI tool for managing Gherkin specifications using ACDD' → AI asks human 'Is vision correct?' → Human confirms → AI updates field", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 3, "text": "FIELD 3 (project.projectType): Command re-scans → Finds [DETECTED: cli-tool] → Emits: 'Field 3/9: project.projectType. Auto-detected cli-tool from commander.js usage and bin field. Verify with human. Options: cli-tool, web-app, library, sdk, mobile-app, desktop-app, service, api, other. Run: fspec update-foundation --field project.projectType --value cli-tool' → AI analyzes code: sees commander.js imports, .command() calls, bin field in package.json → AI confirms: yes, this is cli-tool → AI asks human 'Detected cli-tool, correct?' → Human confirms → AI updates field → Command chains to problemSpace", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 4, "text": "FIELD 4 (problemSpace.primaryProblem): Command re-scans → Finds [QUESTION: What problem does this solve?] → Emits: 'Field 4/9: problemSpace.primaryProblem. CRITICAL: Think from USER perspective. WHO uses this (persona)? WHAT problem do THEY face? WHY do they need this solution? Analyze codebase to understand user pain, ask human. Required: title, description, impact (high/medium/low). Run: fspec update-foundation --field problemSpace.primaryProblem.title --value \"Problem Title\"' → AI analyzes: this is CLI for specs, users are developers, they need structured spec workflow → AI asks human 'Primary problem: Developers lack structured workflow for managing specifications?' → Human elaborates → AI updates title,description,impact", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 5, "text": "FIELD 5 (solutionSpace.capabilities): Command re-scans → Finds [QUESTION: What can users DO?] → Emits: 'Field 5/9: solutionSpace.capabilities. List 3-7 HIGH-LEVEL abilities users have. Focus on WHAT not HOW. Example: \"Spec Validation\" (WHAT), not \"Uses Cucumber parser\" (HOW). Analyze commands/features to identify user-facing capabilities. Run: fspec update-foundation --field solutionSpace.capabilities[0].name --value \"Capability Name\"' → AI analyzes commands: validate, format, list, create → Groups into capabilities: Spec Management, Validation, Work Unit Tracking → AI asks human → Human confirms → AI adds each capability with description", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 6, "text": "FIELD 6 (personas): Command re-scans → Finds [QUESTION: Who uses this?] → Emits: 'Field 6/9: personas. Identify ALL user types from interactions. CLI tools: who runs commands? Web apps: who uses UI + who calls API? Analyze ALL user-facing code. Ask human about goals and pain points. Run: fspec update-foundation --field personas[0].name --value \"Persona Name\"' → AI analyzes: CLI commands used by developers, no web UI, no API consumers → Identifies persona: \"Developer using CLI in terminal\" → AI asks human about goals: managing specs, following ACDD → AI asks about pain points: fragmented tools, no workflow → AI updates persona with name, description, goals, painPoints", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 7, "text": "COMPLETION: AI fills last required field → Command re-scans → ALL required fields complete (no [QUESTION:] in required fields) → Command validates draft against JSON schema → Schema validation PASSES → Command creates spec/foundation.json from draft → Command deletes spec/foundation.json.draft → Command AUTOMATICALLY runs 'fspec generate-foundation-md' (no AI action needed) → Command emits: 'Discovery complete\\! Created: spec/foundation.json, spec/FOUNDATION.md. Foundation is ready. You can now run fspec commands that require foundation.' → AI can now proceed with other work", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 8, "text": "ERROR: Manual Editing → AI uses Write tool to edit foundation.json.draft directly → Command detects: draft mtime changed without fspec command → Command compares last known state vs current → Command emits ERROR in system-reminder: 'CRITICAL: You manually edited foundation.json.draft. This violates the workflow. You MUST use: fspec update-foundation --field <path> --value <value>. Reverting your changes. Draft restored to last valid state. Try again with proper command.' → Draft is restored → AI must use fspec commands", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" }, { "id": 9, "text": "ERROR: Validation Failure → AI fills all fields → Command validates against schema → Validation FAILS: missing required field problemSpace.primaryProblem.description → Command emits: 'Schema validation failed. Missing required: problemSpace.primaryProblem.description. Draft NOT finalized. Fix by running: fspec update-foundation --field problemSpace.primaryProblem.description --value \"your description\". Then re-run discover-foundation to validate.' → Draft kept, foundation.json NOT created → AI fixes missing field and re-runs", "deleted": false, "createdAt": "2025-10-17T06:32:17.502Z" } ], "attachments": [ "spec/attachments/DISC-001/discovery-feedback-loop.mmd" ], "nextRuleId": 15, "nextExampleId": 10, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-015": { "id": "BUG-015", "title": "Foundation discovery workflow cannot update nested fields (capabilities, personas)", "type": "bug", "status": "done", "createdAt": "2025-10-17T07:18:39.226Z", "updatedAt": "2025-10-17T07:52:53.614Z", "description": "The discover-foundation workflow guides AI to use 'fspec update-foundation --field <path> --value <value>' syntax, but the actual update-foundation command uses '<section> <content>' syntax and cannot update nested array fields like capabilities[] and personas[]. This breaks the field-by-field discovery feedback loop.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T07:18:52.919Z" }, { "state": "testing", "timestamp": "2025-10-17T07:21:32.389Z" }, { "state": "implementing", "timestamp": "2025-10-17T07:22:28.653Z" }, { "state": "validating", "timestamp": "2025-10-17T07:24:04.760Z" }, { "state": "done", "timestamp": "2025-10-17T07:25:17.038Z" }, { "state": "implementing", "timestamp": "2025-10-17T07:25:48.358Z" }, { "state": "validating", "timestamp": "2025-10-17T07:37:31.310Z" }, { "state": "done", "timestamp": "2025-10-17T07:52:53.615Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec discover-foundation' → system-reminder says 'Run: fspec update-foundation --field project.name --value <name>' → AI tries command → Error: 'unknown option --field'", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 1, "text": "AI checks help with 'fspec update-foundation --help' → discovers actual syntax is '<section> <content>' not '--field <path> --value <value>'", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 2, "text": "AI successfully uses 'fspec update-foundation projectName \"fspec\"' for simple fields → works correctly", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 3, "text": "AI encounters foundation.json.draft with capabilities[] array placeholder → no CLI command exists to update array fields → workflow breaks", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 4, "text": "AI encounters personas[] array with nested structure → update-foundation command cannot handle nested JSON objects → must manually edit file (violates automation principle)", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" } ], "rules": [ { "id": 0, "text": "discover-foundation system-reminders MUST use syntax that matches actual update-foundation command implementation", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 1, "text": "update-foundation command MUST support updating nested array fields (capabilities[], personas[]) through CLI without manual file editing", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 2, "text": "Foundation discovery workflow MUST be fully automatable by AI without requiring manual JSON editing", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 3, "text": "All fields in foundation.json.draft MUST have corresponding CLI commands to update them programmatically", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" } ], "architectureNotes": [ { "id": 0, "text": "Root Cause: src/commands/discover-foundation.ts emits system-reminders with '--field <path> --value <value>' syntax, but src/commands/update-foundation.ts implements '<section> <content>' syntax with no --field option", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 1, "text": "Impact: Breaks field-by-field discovery feedback loop documented in CLAUDE.md 'Foundation Document Discovery' section. AI cannot complete foundation without manual file editing.", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 2, "text": "Current Workaround: AI must manually edit foundation.json or foundation.json.draft using Write tool, which violates the automation principle and bypasses validation", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 3, "text": "Affected Fields: capabilities[] (array of {name, description} objects), personas[] (array of {name, description, goals[]} objects), architectureDiagrams[] (array of Mermaid diagrams)", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 4, "text": "Schema Reference: src/schemas/generic-foundation.schema.json defines required structure - capabilities[] requires minItems:1, personas[] is optional but must follow persona definition structure", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" } ], "questions": [ { "id": 0, "text": "@human: Should update-foundation support JSON path syntax (e.g., 'capabilities[0].name') or add separate commands (e.g., 'add-capability', 'add-persona')?", "selected": true, "answer": "Add separate commands for better UX: 'fspec add-capability <name> <description>' and 'fspec add-persona <name> <description> --goal <goal>'. This follows existing command patterns (add-scenario, add-step) and is more intuitive than JSON path syntax.", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 1, "text": "@human: Should the fix update discover-foundation to emit correct syntax, or extend update-foundation to support --field flag?", "selected": true, "answer": "Create new commands (add-capability, add-persona) that update foundation.json programmatically. Update discover-foundation to emit system-reminders with correct command syntax. This is cleaner than retrofitting --field flag to update-foundation.", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" }, { "id": 2, "text": "@human: How should AI update array elements - append to array, or replace entire array?", "selected": true, "answer": "Append to arrays for add-capability and add-persona commands. This allows building up the foundation iteratively during discovery. Provide separate clear-capabilities and clear-personas commands if replacement is needed.", "deleted": false, "createdAt": "2025-10-17T07:18:39.226Z" } ], "assumptions": [ "Add separate commands for better UX: 'fspec add-capability <name> <description>' and 'fspec add-persona <name> <description> --goal <goal>'. This follows existing command patterns (add-scenario, add-step) and is more intuitive than JSON path syntax.", "Create new commands (add-capability, add-persona) that update foundation.json programmatically. Update discover-foundation to emit system-reminders with correct command syntax. This is cleaner than retrofitting --field flag to update-foundation.", "Append to arrays for add-capability and add-persona commands. This allows building up the foundation iteratively during discovery. Provide separate clear-capabilities and clear-personas commands if replacement is needed." ], "userStory": { "role": "AI agent using fspec discover-foundation workflow", "action": "update nested array fields in foundation.json through CLI commands", "benefit": "I can complete foundation discovery without manual file editing" }, "nextRuleId": 4, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 5 }, "BUG-016": { "id": "BUG-016", "title": "discover-foundation --finalize doesn't show validation errors", "type": "bug", "status": "done", "createdAt": "2025-10-17T08:37:12.330Z", "updatedAt": "2025-10-17T08:43:45.249Z", "description": "When 'fspec discover-foundation --finalize' fails validation, it only shows '✗ Foundation validation failed' without showing WHAT validation errors occurred. The validationErrors field is populated in the code (lines 132-139 in discover-foundation.ts) but never printed to the user in the CLI action handler (lines 280-288). This leaves users/AI with no feedback on what needs to be fixed.", "epic": "foundation-document-redesign", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T08:37:55.679Z" }, { "state": "testing", "timestamp": "2025-10-17T08:39:33.216Z" }, { "state": "implementing", "timestamp": "2025-10-17T08:40:43.274Z" }, { "state": "validating", "timestamp": "2025-10-17T08:41:42.645Z" }, { "state": "done", "timestamp": "2025-10-17T08:43:20.424Z" } ], "userStory": { "role": "AI agent using draft-driven discovery workflow", "action": "see detailed validation errors when finalize fails", "benefit": "I know exactly what fields to fix without guessing" }, "rules": [ { "id": 0, "text": "When finalize fails validation, MUST show detailed error messages", "deleted": false, "createdAt": "2025-10-17T08:37:12.330Z" }, { "id": 1, "text": "Error messages MUST list missing/invalid fields", "deleted": false, "createdAt": "2025-10-17T08:37:12.330Z" }, { "id": 2, "text": "Error messages MUST show commands to fix each type of issue", "deleted": false, "createdAt": "2025-10-17T08:37:12.330Z" }, { "id": 3, "text": "Error messages MUST be visible to both users and AI agents", "deleted": false, "createdAt": "2025-10-17T08:37:12.330Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec discover-foundation --finalize' with empty personas array, sees error: 'Missing required: personas[0].name' with command to fix", "deleted": false, "createdAt": "2025-10-17T08:37:12.330Z" }, { "id": 1, "text": "User runs finalize with placeholder persona data, sees error listing ALL missing fields in personas", "deleted": false, "createdAt": "2025-10-17T08:37:12.330Z" }, { "id": 2, "text": "User runs finalize with empty capabilities array, sees error: 'Missing required: solutionSpace.capabilities' with example command", "deleted": false, "createdAt": "2025-10-17T08:37:12.330Z" } ], "estimate": 2, "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-017": { "id": "BUG-017", "title": "update-foundation doesn't chain to next field during discovery", "type": "bug", "status": "done", "createdAt": "2025-10-17T08:52:34.641Z", "updatedAt": "2025-10-17T08:57:37.226Z", "description": "When AI runs 'fspec update-foundation' during draft-driven discovery, the command updates the draft but doesn't automatically scan for and emit the next field guidance. This breaks the automatic field-by-field chaining workflow, forcing AI to manually call discover-foundation again or guess what field comes next.", "epic": "foundation-document-redesign", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T08:52:50.903Z" }, { "state": "testing", "timestamp": "2025-10-17T08:54:25.470Z" }, { "state": "implementing", "timestamp": "2025-10-17T08:55:56.939Z" }, { "state": "validating", "timestamp": "2025-10-17T08:57:04.254Z" }, { "state": "done", "timestamp": "2025-10-17T08:57:36.662Z" } ], "userStory": { "role": "AI agent using draft-driven discovery", "action": "automatically see next field guidance after updating a field", "benefit": "I don't have to manually re-run discover-foundation or guess what comes next" }, "rules": [ { "id": 0, "text": "After updating draft field, MUST automatically scan draft for next field", "deleted": false, "createdAt": "2025-10-17T08:52:34.641Z" }, { "id": 1, "text": "MUST emit system-reminder with guidance for next unfilled field", "deleted": false, "createdAt": "2025-10-17T08:52:34.641Z" }, { "id": 2, "text": "If all fields complete, MUST tell AI to run finalize", "deleted": false, "createdAt": "2025-10-17T08:52:34.641Z" }, { "id": 3, "text": "Chaining MUST be automatic, no manual intervention required", "deleted": false, "createdAt": "2025-10-17T08:52:34.641Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec update-foundation projectName \"MyProject\"', sees success message PLUS system-reminder for Field 2/8: project.vision", "deleted": false, "createdAt": "2025-10-17T08:52:34.641Z" }, { "id": 1, "text": "AI runs 'fspec update-foundation projectVision \"My vision\"', sees success message PLUS system-reminder for Field 3/8: project.projectType", "deleted": false, "createdAt": "2025-10-17T08:52:34.641Z" }, { "id": 2, "text": "AI fills last field, sees success message PLUS system-reminder saying 'All fields complete. Run: fspec discover-foundation --finalize'", "deleted": false, "createdAt": "2025-10-17T08:52:34.641Z" } ], "estimate": 3, "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-018": { "id": "BUG-018", "title": "add-persona and add-capability don't work with foundation.json.draft", "type": "bug", "status": "done", "createdAt": "2025-10-17T09:08:55.578Z", "updatedAt": "2025-10-17T09:15:50.916Z", "description": "During draft-driven discovery workflow, add-persona and add-capability commands fail because they check for foundation.json instead of foundation.json.draft. This prevents AI from adding personas/capabilities during the discovery phase.", "epic": "foundation-document-redesign", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T09:09:00.995Z" }, { "state": "testing", "timestamp": "2025-10-17T09:11:14.730Z" }, { "state": "implementing", "timestamp": "2025-10-17T09:12:19.941Z" }, { "state": "validating", "timestamp": "2025-10-17T09:13:32.198Z" }, { "state": "done", "timestamp": "2025-10-17T09:15:50.917Z" } ], "userStory": { "role": "AI agent using draft-driven discovery", "action": "add personas and capabilities during discovery phase", "benefit": "I can complete all foundation fields without waiting for finalization" }, "rules": [ { "id": 0, "text": "add-persona MUST check for foundation.json.draft first, then foundation.json", "deleted": false, "createdAt": "2025-10-17T09:08:55.578Z" }, { "id": 1, "text": "add-capability MUST check for foundation.json.draft first, then foundation.json", "deleted": false, "createdAt": "2025-10-17T09:08:55.578Z" }, { "id": 2, "text": "Commands MUST prefer draft over final foundation.json (draft takes precedence)", "deleted": false, "createdAt": "2025-10-17T09:08:55.578Z" }, { "id": 3, "text": "Error messages MUST be helpful when neither file exists", "deleted": false, "createdAt": "2025-10-17T09:08:55.578Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec add-persona' during discovery, draft exists, persona added to draft", "deleted": false, "createdAt": "2025-10-17T09:08:55.578Z" }, { "id": 1, "text": "AI runs 'fspec add-capability' during discovery, draft exists, capability added to draft", "deleted": false, "createdAt": "2025-10-17T09:08:55.578Z" }, { "id": 2, "text": "AI runs 'fspec add-persona', no draft but foundation.json exists, persona added to foundation.json (backward compatibility)", "deleted": false, "createdAt": "2025-10-17T09:08:55.578Z" }, { "id": 3, "text": "AI runs 'fspec add-capability', neither file exists, shows helpful error with 'fspec discover-foundation' suggestion", "deleted": false, "createdAt": "2025-10-17T09:08:55.578Z" } ], "estimate": 3, "nextRuleId": 4, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "FEAT-014": { "id": "FEAT-014", "title": "Add remove-persona and remove-capability commands", "type": "feature", "status": "done", "createdAt": "2025-10-17T09:22:49.579Z", "updatedAt": "2025-10-17T09:30:23.946Z", "description": "Users need commands to remove personas and capabilities from foundation.json or foundation.json.draft. Currently they must manually edit JSON files to remove unwanted placeholder entries.", "epic": "foundation-document-redesign", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T09:22:55.289Z" }, { "state": "testing", "timestamp": "2025-10-17T09:25:00.500Z" }, { "state": "implementing", "timestamp": "2025-10-17T09:29:24.677Z" }, { "state": "validating", "timestamp": "2025-10-17T09:29:24.949Z" }, { "state": "done", "timestamp": "2025-10-17T09:30:23.946Z" } ], "userStory": { "role": "user managing foundation document", "action": "remove unwanted personas and capabilities", "benefit": "I can clean up placeholders without manually editing JSON" }, "rules": [ { "id": 0, "text": "remove-persona MUST work with both foundation.json and foundation.json.draft (same file priority as add-persona)", "deleted": false, "createdAt": "2025-10-17T09:22:49.579Z" }, { "id": 1, "text": "remove-capability MUST work with both foundation.json and foundation.json.draft (same file priority as add-capability)", "deleted": false, "createdAt": "2025-10-17T09:22:49.579Z" }, { "id": 2, "text": "Remove commands MUST match by exact name (case-sensitive)", "deleted": false, "createdAt": "2025-10-17T09:22:49.579Z" }, { "id": 3, "text": "If persona/capability not found, show error with list of available names", "deleted": false, "createdAt": "2025-10-17T09:22:49.579Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec remove-persona Developer', persona removed from draft", "deleted": false, "createdAt": "2025-10-17T09:22:49.579Z" }, { "id": 1, "text": "User runs 'fspec remove-capability \"Mind Mapping\"', capability removed from foundation.json", "deleted": false, "createdAt": "2025-10-17T09:22:49.579Z" }, { "id": 2, "text": "User runs 'fspec remove-persona NonExistent', shows error listing available personas", "deleted": false, "createdAt": "2025-10-17T09:22:49.579Z" } ], "estimate": 2, "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "FEAT-015": { "id": "FEAT-015", "title": "Validate Mermaid diagrams in attachments", "type": "story", "status": "done", "createdAt": "2025-10-17T10:13:18.110Z", "updatedAt": "2025-10-17T10:27:24.865Z", "description": "Add validation for Mermaid diagram attachments using the same validation logic as add-diagram command, providing detailed syntax error feedback when diagrams are invalid", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-17T10:13:25.228Z" }, { "state": "testing", "timestamp": "2025-10-17T10:20:44.838Z" }, { "state": "implementing", "timestamp": "2025-10-17T10:23:28.000Z" }, { "state": "validating", "timestamp": "2025-10-17T10:25:36.448Z" }, { "state": "done", "timestamp": "2025-10-17T10:27:24.865Z" } ], "userStory": { "role": "developer using fspec with AI agents", "action": "attach Mermaid diagrams to work units with automatic validation", "benefit": "I catch diagram syntax errors immediately and get helpful feedback to fix them" }, "rules": [ { "id": 0, "text": "Mermaid diagram attachments must be validated using the same mermaid.parse() logic as add-diagram command", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 1, "text": "Only files with .mmd or .mermaid extensions should trigger Mermaid validation", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 2, "text": "Invalid Mermaid syntax must prevent attachment with detailed error message including line numbers", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 3, "text": "Valid Mermaid diagrams should be attached successfully with confirmation message", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 4, "text": "Use similar error format to add-diagram but adapted for attachment context (e.g., 'Failed to attach diagram.mmd' instead of 'Failed to add diagram')", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 5, "text": "No --skip-validation flag - all Mermaid diagrams must pass validation before attachment", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 6, "text": "Yes, validate .md files that contain mermaid code blocks (triple-backtick mermaid syntax)", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" } ], "examples": [ { "id": 0, "text": "User attaches valid flowchart.mmd with 'graph TD' syntax - attachment succeeds with confirmation", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 1, "text": "User attaches sequence.mermaid with invalid syntax - attachment fails with detailed error message showing line number", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 2, "text": "User attaches diagram.png - no Mermaid validation performed (not .mmd or .mermaid extension)", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 3, "text": "User attaches erDiagram.mmd with valid ER diagram syntax - attachment succeeds", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" } ], "questions": [ { "id": 0, "text": "@human: Should we also validate .md files that contain mermaid code blocks?", "selected": true, "answer": "Yes, validate .md files that contain mermaid code blocks (triple-backtick mermaid syntax)", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 1, "text": "@human: Should the error message format match exactly with add-diagram errors for consistency?", "selected": true, "answer": "Use similar error format to add-diagram but adapted for attachment context (e.g., 'Failed to attach diagram.mmd' instead of 'Failed to add diagram')", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" }, { "id": 2, "text": "@human: Should we add a --skip-validation flag to allow attaching invalid diagrams for drafts?", "selected": true, "answer": "No --skip-validation flag - all Mermaid diagrams must pass validation before attachment", "deleted": false, "createdAt": "2025-10-17T10:13:18.110Z" } ], "estimate": 3, "nextRuleId": 7, "nextExampleId": 4, "nextQuestionId": 3, "nextNoteId": 0 }, "BUG-019": { "id": "BUG-019", "title": "Dependencies command throws 'Invalid action' error", "type": "story", "status": "done", "createdAt": "2025-10-18T23:33:40.052Z", "updatedAt": "2025-10-18T23:38:21.107Z", "description": "The 'fspec dependencies <work-unit-id>' command throws 'Error: Invalid action: <work-unit-id>' when invoked. The command registration expects an action argument first, but users/AI expect to pass work-unit-id directly to query dependencies.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-18T23:33:40.419Z" }, { "state": "testing", "timestamp": "2025-10-18T23:35:11.478Z" }, { "state": "implementing", "timestamp": "2025-10-18T23:36:33.004Z" }, { "state": "validating", "timestamp": "2025-10-18T23:38:08.835Z" }, { "state": "done", "timestamp": "2025-10-18T23:38:21.108Z" } ], "userStory": { "role": "AI agent using fspec CLI", "action": "query work unit dependencies with simple syntax", "benefit": "I can understand dependency relationships without parsing complex multi-action commands" }, "rules": [ { "id": 0, "text": "Command must accept work-unit-id as first positional argument", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" }, { "id": 1, "text": "Command must display all dependency types: blocks, blockedBy, dependsOn, relatesTo", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" }, { "id": 2, "text": "Command must provide AI-friendly error wrapped in system-reminder if work unit does not exist", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec dependencies MCP-001' and sees 'Dependencies for MCP-001:' with empty lists (no dependencies)", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" }, { "id": 1, "text": "AI runs 'fspec dependencies MCP-004' and sees 'Depends on: MCP-001, MCP-002'", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" }, { "id": 2, "text": "AI runs 'fspec dependencies INVALID-999' and gets system-reminder with suggestions to run 'fspec list-work-units'", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" } ], "architectureNotes": [ { "id": 0, "text": "Root cause: registerDependenciesCommand() uses multi-action router pattern with .argument('<action>') expecting 'list', 'add', 'remove', etc. but help docs suggest direct work-unit-id usage", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" }, { "id": 1, "text": "Solution: Simplify to single-purpose command accepting .command('dependencies <work-unit-id>') and call showDependencies() directly with AI-friendly error handling", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" }, { "id": 2, "text": "Error handling: Wrap errors in system-reminder tags to make failures highly visible to AI agents in Claude Code", "deleted": false, "createdAt": "2025-10-18T23:33:40.052Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 3 }, "DOCS-001": { "id": "DOCS-001", "title": "Clarify estimation timing in documentation and system-reminders", "type": "story", "status": "done", "createdAt": "2025-10-19T12:10:39.283Z", "updatedAt": "2025-10-19T12:34:31.582Z", "description": "System-reminders and documentation don't make it clear enough that story point estimation happens AFTER Example Mapping during the specifying phase, not before. AI agents are suggesting to add estimates before moving work units to specifying state, which violates ACDD workflow.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-19T12:10:47.439Z" }, { "state": "testing", "timestamp": "2025-10-19T12:18:22.138Z" }, { "state": "implementing", "timestamp": "2025-10-19T12:22:04.487Z" }, { "state": "validating", "timestamp": "2025-10-19T12:33:00.375Z" }, { "state": "done", "timestamp": "2025-10-19T12:34:31.583Z" } ], "userStory": { "role": "AI agent using fspec", "action": "understand when to estimate story points", "benefit": "I follow ACDD workflow correctly without suggesting premature estimation" }, "rules": [ { "id": 0, "text": "Story point estimation happens AFTER Example Mapping, during specifying state", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 1, "text": "Cannot estimate accurately without understanding scope from Example Mapping", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 2, "text": "System-reminders in backlog state must NOT suggest adding estimates", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 3, "text": "System-reminders in specifying state SHOULD remind to estimate after Example Mapping", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 4, "text": "System-reminders must align with ACDD violation enforcement (feature file required before estimation)", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" } ], "examples": [ { "id": 0, "text": "AI shows MCP epic with 5 work units in backlog, suggests adding estimates before moving to specifying (WRONG)", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 1, "text": "AI moves work unit to specifying, does Example Mapping, THEN suggests estimate based on discovered complexity (CORRECT)", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 2, "text": "AI reads show-work-unit output showing 'no estimate' reminder in backlog state, incorrectly offers to add estimate immediately (WRONG)", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 3, "text": "AI completes Example Mapping, generates scenarios, THEN sees reminder 'After generating scenarios, estimate based on feature file complexity' (CORRECT)", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" } ], "architectureNotes": [ { "id": 0, "text": "Files to check: src/commands/show-work-unit.ts (system-reminder logic), src/commands/update-work-unit-status.ts (state transition reminders), CLAUDE.md (workflow documentation), .claude/commands/fspec.md (slash command docs)", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 1, "text": "CRITICAL FIX: System-reminder in show-work-unit.ts currently says 'Use Example Mapping results to estimate story points' but should say 'After generating scenarios from Example Mapping, estimate story points based on feature file complexity' to match ACDD violation enforcement", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" }, { "id": 2, "text": "Also update .claude/commands/fspec.md Step 2.5 section to explicitly state: estimate AFTER generating scenarios from Example Mapping, not before", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" } ], "questions": [ { "id": 0, "text": "@human: Are there other places in the codebase besides system-reminders where estimation timing should be clarified?", "selected": true, "answer": "Yes - update help documentation for update-work-unit-estimate command, add workflow examples to README.md and spec/CLAUDE.md showing correct timing, and potentially add validation to prevent estimating work units not yet in specifying state", "deleted": false, "createdAt": "2025-10-19T12:10:39.283Z" } ], "estimate": 3, "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 1, "nextNoteId": 3 }, "FEAT-016": { "id": "FEAT-016", "title": "Warn AI when estimate is > 13 points to break down work unit", "type": "story", "status": "done", "createdAt": "2025-10-19T12:40:51.573Z", "updatedAt": "2025-10-19T13:17:50.986Z", "description": "When AI estimates a work unit at more than 13 points (21+), emit system-reminder warnings to guide breaking down into smaller work units (1-13 points each)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-19T12:40:58.524Z" }, { "state": "testing", "timestamp": "2025-10-19T13:03:29.376Z" }, { "state": "implementing", "timestamp": "2025-10-19T13:05:27.211Z" }, { "state": "validating", "timestamp": "2025-10-19T13:11:11.102Z" }, { "state": "done", "timestamp": "2025-10-19T13:17:50.986Z" } ], "userStory": { "role": "AI agent estimating work units", "action": "receive clear warnings and guidance when estimate is too large", "benefit": "I break down large work into manageable chunks without getting lost in the process" }, "rules": [ { "id": 0, "text": "Warning must include SPECIFIC step-by-step commands (not generic advice) to break down the work unit", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 1, "text": "Warning should guide AI to review feature file scenarios for natural split boundaries (not arbitrary splitting)", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 2, "text": "Warning is non-blocking (allows estimate to be set) but strongly recommends breaking down", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 3, "text": "Warning triggers IMMEDIATELY when estimate > 13 points (21 is too large, but 13 is acceptable)", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 4, "text": "Warning ONLY applies to story and bug types, NOT task types (tasks can legitimately be large)", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 5, "text": "Warning should suggest breaking into smaller stories (1-13 points each) for clear guidance", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 6, "text": "Warning persists in show-work-unit while estimate > 13 AND status is not done", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 7, "text": "Warning guidance adapts based on context: if feature file exists suggest reviewing it for natural boundaries, if no feature file exists suggest creating it first before breaking down", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" } ], "examples": [ { "id": 0, "text": "AI estimates BUG-005 at 21 points → warning shown → AI ignores and continues → runs show-work-unit BUG-005 → warning shown again in system-reminder section → AI finally breaks it down", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 1, "text": "AI estimates INFRA-001 (type=task, infrastructure setup) at 21 points → NO warning (task type exempt) → estimate accepted", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 2, "text": "AI sees warning → reads feature file → identifies natural scenario groupings → creates child work units for each group → estimates each child (all <= 13) → links with dependencies", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" } ], "architectureNotes": [ { "id": 0, "text": "TWO PLACEMENT POINTS: (1) update-work-unit-estimate.ts - immediate warning when estimate set, (2) show-work-unit.ts - persistent reminder via getLargeEstimateReminder() in system-reminder.ts", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 1, "text": "SYSTEM-REMINDER MUST BE HIGHLY SPECIFIC: Include exact fspec commands (create-story/create-bug/create-task, add-dependency, create-epic), not generic advice like 'break this down'", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 2, "text": "GUIDE FEATURE FILE ANALYSIS: Remind AI to 'Review feature file linked to this work unit. Look for scenario groupings that could be separate stories. Each group should deliver incremental value.'", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 3, "text": "PERSISTENCE STRATEGY: Warning appears in TWO contexts (immediate + show-work-unit) creating 'sticky' reminder. AI will see it multiple times, increasing likelihood of following through.", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" }, { "id": 4, "text": "STEP-BY-STEP WORKFLOW IN WARNING: (1) Review feature file (or create if missing), (2) Identify boundaries, (3) Create child work units with fspec create-story/create-bug/create-task, (4) Link with fspec add-dependency --depends-on, (5) Optionally create epic to group, (6) Delete original work unit or convert to epic using fspec create-epic", "deleted": false, "createdAt": "2025-10-19T12:40:51.573Z" } ], "questions": [], "estimate": 5, "nextRuleId": 8, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 5 }, "BUG-020": { "id": "BUG-020", "title": "remove-question command shows '[object Object]' instead of question text", "type": "bug", "status": "done", "createdAt": "2025-10-19T12:58:26.949Z", "updatedAt": "2025-10-20T20:43:10.871Z", "description": "When running 'fspec remove-question <id> <index>', the success message displays 'Removed question: [object Object]' instead of showing the actual question text that was removed", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-20T20:37:44.322Z" }, { "state": "testing", "timestamp": "2025-10-20T20:39:47.790Z" }, { "state": "implementing", "timestamp": "2025-10-20T20:41:22.510Z" }, { "state": "validating", "timestamp": "2025-10-20T20:42:02.948Z" }, { "state": "done", "timestamp": "2025-10-20T20:43:10.871Z" } ], "userStory": { "role": "developer using fspec", "action": "see the actual question text when removing a question", "benefit": "I can confirm I'm removing the correct question" }, "rules": [ { "id": 0, "text": "Success message must display the actual question text, not '[object Object]'", "deleted": false, "createdAt": "2025-10-19T12:58:26.949Z" }, { "id": 1, "text": "Message format should be 'Removed question: <question text>'", "deleted": false, "createdAt": "2025-10-19T12:58:26.949Z" } ], "examples": [ { "id": 0, "text": "Remove question 'Should we support OAuth?' displays 'Removed question: Should we support OAuth?'", "deleted": false, "createdAt": "2025-10-19T12:58:26.949Z" }, { "id": 1, "text": "Remove question with special characters '@human: What happens?' displays correctly", "deleted": false, "createdAt": "2025-10-19T12:58:26.949Z" } ], "estimate": 1, "nextRuleId": 2, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "REV-001": { "id": "REV-001", "title": "Interactive reverse ACDD strategy planning command", "type": "story", "status": "done", "createdAt": "2025-10-19T20:57:37.321Z", "updatedAt": "2025-10-26T01:00:29.839Z", "description": "Refactor reverse ACDD workflow from prescriptive /rspec command to interactive strategy planning session. Implement 'fspec reverse' command that analyzes project state, detects gaps (missing features, tests, coverage, work units), offers strategic options, and guides AI step-by-step through gap-filling process. This command is a planning/guidance tool only - it does NOT execute reverse ACDD work itself, but helps AI make informed decisions about the best approach based on project state. Similar to discover-foundation interactive session with system-reminders.", "epic": "reverse-acdd-refactor", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-19T20:57:42.682Z" }, { "state": "testing", "timestamp": "2025-10-19T21:06:32.964Z" }, { "state": "implementing", "timestamp": "2025-10-19T21:09:44.583Z" }, { "state": "specifying", "timestamp": "2025-10-19T21:18:12.503Z" }, { "state": "testing", "timestamp": "2025-10-19T21:39:19.514Z" }, { "state": "implementing", "timestamp": "2025-10-19T21:39:29.035Z" }, { "state": "validating", "timestamp": "2025-10-19T21:50:29.445Z" }, { "state": "done", "timestamp": "2025-10-19T21:51:43.661Z" }, { "state": "implementing", "timestamp": "2025-10-26T00:52:19.474Z" }, { "state": "validating", "timestamp": "2025-10-26T00:58:15.173Z" }, { "state": "done", "timestamp": "2025-10-26T01:00:29.839Z" } ], "userStory": { "role": "AI agent (Claude) working on legacy codebase", "action": "plan and execute reverse ACDD strategy to fill specification/test gaps", "benefit": "I can intelligently choose the right approach based on project state rather than following rigid instructions" }, "rules": [ { "id": 0, "text": "Command must be interactive like discover-foundation (session-based with system-reminders)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 1, "text": "Command analyzes project state but does NOT execute reverse ACDD itself - it only guides", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 2, "text": "Must detect gaps: missing features, missing tests, missing coverage mappings, missing work units", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 3, "text": "Must offer multiple strategies based on gap analysis (Spec Gap Filling, Test Gap Filling, Coverage Mapping, Full Reverse ACDD)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 4, "text": "Must emit step-by-step guidance via system-reminders (NOT execute the steps)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 5, "text": "Must replace /rspec command in .claude/commands/fspec.md and deprecate it", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 6, "text": "Must update spec/CLAUDE.md section on Reverse ACDD with new workflow", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 7, "text": "Session file must be deleted on completion (--complete) or reset (--reset)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 8, "text": "State machine phases: analyzing → gap-detection → strategy-planning → executing → complete", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 9, "text": "Show summary with counts, paginate detailed gap list, suggest --strategy to narrow scope", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 10, "text": "Yes - include story point estimates in strategy suggestions (helps AI prioritize)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 11, "text": "Yes - support --dry-run for preview analysis without creating session file", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 12, "text": "Must detect existing session and prevent overwrite - show status and suggest options (--continue, --status, --reset, --complete)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 13, "text": "Must persist session state in OS temp directory (tmpdir) using project-specific hash for filename isolation - ephemeral, OS-managed cleanup", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 14, "text": "Must support CLI flags: --continue, --strategy=X, --status, --reset, --complete, --dry-run", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec reverse' → command analyzes project → finds 3 test files without features → suggests Strategy A (Spec Gap Filling) via system-reminder", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 1, "text": "AI runs 'fspec reverse --strategy=A' → emits system-reminder with step 1 guidance → AI reads test file, creates feature, links coverage → AI runs 'fspec reverse --continue' → emits step 2 guidance", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 2, "text": "User runs 'fspec reverse --status' → shows current phase (executing), detected gaps (3 test files without features), chosen strategy (A), current step (2 of 3)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 3, "text": "User runs 'fspec reverse --reset' → deletes session file → outputs 'Session reset' → user can start fresh with 'fspec reverse'", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 4, "text": "Project has features but no tests → analysis detects 2 feature files without tests → suggests Strategy B (Test Gap Filling) → guides AI through creating test skeletons with --skip-validation", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 5, "text": "Project has both features and tests but unmapped → analysis detects 5 scenarios without coverage links → suggests Strategy C (Coverage Mapping) → guides AI through linking existing tests to scenarios", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 6, "text": "Project has raw implementation code only (no features, no tests) → analysis detects 10 implementation files → suggests Strategy D (Full Reverse ACDD) → guides through creating features, tests, and work units from scratch", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 7, "text": "AI completes all steps → runs 'fspec reverse --complete' → command validates work done → deletes session file → emits system-reminder with completion summary", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 8, "text": "User runs 'fspec reverse' while session exists → command detects existing session → exits with error → shows current status → suggests --continue, --status, --reset, --complete → does NOT overwrite session", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" } ], "questions": [ { "id": 0, "text": "@human: Should the session file be human-readable JSON or optimized binary format?", "selected": true, "answer": "Human-readable JSON - easier to debug, inspect, and aligns with foundation.json pattern", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 1, "text": "@human: Should we support parallel strategies (e.g., Strategy A + Strategy C simultaneously)?", "selected": true, "answer": "No parallel strategies in MVP - keep it simple. AI chooses one strategy, completes it, then can run reverse again for other gaps", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 2, "text": "@human: How should we handle very large projects (100+ gaps detected)? Paginate output?", "selected": true, "answer": "Show summary with counts, paginate detailed gap list, suggest --strategy to narrow scope", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 3, "text": "@human: Should --strategy=custom trigger an interactive Q&A session with the user?", "selected": true, "answer": "Defer --strategy=custom to Phase 2 - start with four predefined strategies (A, B, C, D)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 4, "text": "@human: Should we track time/effort estimates for each strategy in the guidance output?", "selected": true, "answer": "Yes - include story point estimates in strategy suggestions (helps AI prioritize)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 5, "text": "@human: Should the command support --dry-run mode to preview analysis without creating session?", "selected": true, "answer": "Yes - support --dry-run for preview analysis without creating session file", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" } ], "architectureNotes": [ { "id": 0, "text": "State machine phases: analyzing → gap-detection → strategy-planning → executing → complete (similar to discover-foundation feedback loop)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 1, "text": "System-reminders emitted at phase transitions and for step-by-step guidance (wrapped in <system-reminder> tags)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 2, "text": "Reuses existing analysis utilities: file scanners (Glob), Gherkin parser, test file pattern matching", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 3, "text": "NO execution logic in command - all work done by AI using existing fspec commands (create-feature, link-coverage, etc.)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 4, "text": "Integration point 1: .claude/commands/fspec.md must mention 'fspec reverse' and deprecate /rspec command", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 5, "text": "Integration point 2: spec/CLAUDE.md section 'Reverse ACDD for Existing Codebases' must be updated with new workflow", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 6, "text": "Strategy templates: A=Spec Gap Filling, B=Test Gap Filling, C=Coverage Mapping, D=Full Reverse ACDD (each has predefined guidance steps)", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" }, { "id": 7, "text": "Session state stored in tmpdir()/fspec-reverse-{hash}.json where hash=sha256(projectRoot).substring(0,12) - ephemeral, OS-managed cleanup, zero project pollution", "deleted": false, "createdAt": "2025-10-19T20:57:37.321Z" } ], "attachments": [ "spec/attachments/REV-001/reverse-session-state-machine.mmd", "spec/attachments/REV-001/strategy-decision-tree.mmd", "spec/attachments/REV-001/reverse-session-sequence.mmd" ], "assumptions": [ "Human-readable JSON - easier to debug, inspect, and aligns with foundation.json pattern", "No parallel strategies in MVP - keep it simple. AI chooses one strategy, completes it, then can run reverse again for other gaps", "Defer --strategy=custom to Phase 2 - start with four predefined strategies (A, B, C, D)" ], "estimate": 13, "nextRuleId": 15, "nextExampleId": 9, "nextQuestionId": 6, "nextNoteId": 8 }, "UX-001": { "id": "UX-001", "title": "System-reminder for missing scenarios in link-coverage", "type": "story", "status": "done", "createdAt": "2025-10-19T21:40:43.514Z", "updatedAt": "2025-10-19T22:00:01.065Z", "description": "When link-coverage fails because a scenario is not found in the coverage file but exists in the feature file, emit a system-reminder telling the AI to run generate-coverage first", "epic": "cli-ux-improvements", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-19T21:40:52.678Z" }, { "state": "testing", "timestamp": "2025-10-19T21:52:58.263Z" }, { "state": "implementing", "timestamp": "2025-10-19T21:54:10.182Z" }, { "state": "validating", "timestamp": "2025-10-19T21:59:49.858Z" }, { "state": "done", "timestamp": "2025-10-19T22:00:01.066Z" } ], "userStory": { "role": "AI agent (Claude) using fspec", "action": "receive helpful guidance when link-coverage fails due to missing scenarios", "benefit": "I can quickly fix the issue without trial and error" }, "rules": [ { "id": 0, "text": "When link-coverage fails with 'Scenario not found', check if scenario exists in feature file", "deleted": false, "createdAt": "2025-10-19T21:40:43.514Z" }, { "id": 1, "text": "If scenario exists in feature file but not in coverage file, emit system-reminder suggesting generate-coverage", "deleted": false, "createdAt": "2025-10-19T21:40:43.514Z" }, { "id": 2, "text": "System-reminder must be wrapped in <system-reminder> tags (visible to AI, invisible to user)", "deleted": false, "createdAt": "2025-10-19T21:40:43.514Z" }, { "id": 3, "text": "If scenario doesn't exist in feature file either, show normal error without system-reminder", "deleted": false, "createdAt": "2025-10-19T21:40:43.514Z" } ], "examples": [ { "id": 0, "text": "AI adds new scenario to feature file, runs link-coverage before generate-coverage → error with system-reminder: 'Run generate-coverage first'", "deleted": false, "createdAt": "2025-10-19T21:40:43.514Z" }, { "id": 1, "text": "AI tries to link non-existent scenario (typo in scenario name) → error without system-reminder, just shows available scenarios", "deleted": false, "createdAt": "2025-10-19T21:40:43.514Z" }, { "id": 2, "text": "Coverage file missing entirely → system-reminder suggests running generate-coverage to create it", "deleted": false, "createdAt": "2025-10-19T21:40:43.514Z" } ], "estimate": 3, "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "DOCS-002": { "id": "DOCS-002", "title": "Update all documentation to replace /rspec with fspec reverse", "type": "task", "status": "done", "createdAt": "2025-10-19T22:25:10.476Z", "updatedAt": "2025-10-22T00:19:11.595Z", "description": "REV-001 implementation is complete but documentation still references deprecated /rspec command. Update all docs to use 'fspec reverse' instead.", "epic": "reverse-acdd-refactor", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-19T22:25:15.775Z" }, { "state": "implementing", "timestamp": "2025-10-19T22:26:02.269Z" }, { "state": "validating", "timestamp": "2025-10-19T22:45:25.166Z" }, { "state": "done", "timestamp": "2025-10-19T22:51:53.017Z" }, { "state": "implementing", "timestamp": "2025-10-22T00:00:13.282Z" }, { "state": "validating", "timestamp": "2025-10-22T00:18:57.973Z" }, { "state": "done", "timestamp": "2025-10-22T00:19:11.595Z" } ], "rules": [ { "id": 0, "text": "All references to /rspec command must be replaced with 'fspec reverse'", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 1, "text": "File .claude/commands/rspec.md must be deleted as it is deprecated by fspec reverse", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 2, "text": "Command fspec reverse must have comprehensive help file at src/commands/reverse-help.ts following CommandHelpConfig pattern", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 3, "text": "File src/commands/help.ts must include reverse command in command list", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 4, "text": "File spec/foundation.json must include Interactive Reverse ACDD capability with proper description", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 5, "text": "After foundation.json changes, spec/FOUNDATION.md must be regenerated using fspec generate-foundation-md", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" } ], "examples": [ { "id": 0, "text": "Update .claude/commands/fspec.md: Replace '(see /rspec)' with '(see fspec reverse command)'", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 1, "text": "Update spec/CLAUDE.md section 'Reverse ACDD for Existing Codebases': Replace 'via /rspec command' with 'via fspec reverse command'", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 2, "text": "Update README.md: Replace '/rspec - For reverse engineering' with 'fspec reverse - Interactive strategy planning for reverse ACDD'", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 3, "text": "Create src/commands/reverse-help.ts with sections: name, description, usage, whenToUse, options (--continue, --strategy, --status, --reset, --complete, --dry-run), examples, commonErrors, typicalWorkflow", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" }, { "id": 4, "text": "Add to foundation.json capabilities: {name: 'Interactive Reverse ACDD Strategy Planning', description: 'Analyzes project gaps and guides AI through reverse ACDD workflow with step-by-step system-reminders'}", "deleted": false, "createdAt": "2025-10-19T22:25:10.476Z" } ], "nextRuleId": 6, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-021": { "id": "BUG-021", "title": "fspec --help displays hardcoded version 0.0.1 instead of package.json version", "type": "story", "status": "done", "createdAt": "2025-10-20T20:24:28.844Z", "updatedAt": "2025-10-20T20:35:39.022Z", "description": "The --help command shows 'Version 0.0.1' which appears to be hardcoded. It should dynamically read the version from package.json to stay in sync with releases.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-20T20:24:55.239Z" }, { "state": "testing", "timestamp": "2025-10-20T20:29:02.950Z" }, { "state": "implementing", "timestamp": "2025-10-20T20:30:35.528Z" }, { "state": "validating", "timestamp": "2025-10-20T20:34:32.979Z" }, { "state": "done", "timestamp": "2025-10-20T20:35:39.023Z" } ], "userStory": { "role": "developer using fspec", "action": "run fspec --help to check version", "benefit": "I see the current version from package.json, not a hardcoded value" }, "rules": [ { "id": 0, "text": "Version displayed in --help must match package.json version exactly", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" }, { "id": 1, "text": "Version should update automatically when package.json changes (no manual hardcoding)", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" }, { "id": 2, "text": "Build time - version embedded in dist bundle during build (typical for CLI tools)", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" }, { "id": 3, "text": "Don't display version string if unavailable", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" } ], "examples": [ { "id": 0, "text": "When package.json has version 0.2.1, running 'fspec --help' displays 'Version 0.2.1'", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" }, { "id": 1, "text": "After bumping package.json to version 0.3.0 and rebuilding, 'fspec --help' displays 'Version 0.3.0'", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" }, { "id": 2, "text": "Currently shows 'Version 0.0.1' regardless of package.json value (bug to fix)", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" } ], "questions": [ { "id": 0, "text": "@human: Should version be read at build time (embedded in dist bundle) or runtime (reading package.json when --help runs)? Build-time is typical for CLI tools.", "selected": true, "answer": "Build time - version embedded in dist bundle during build (typical for CLI tools)", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" }, { "id": 1, "text": "@human: If we can't read the version (edge case), should we show 'unknown' or fallback to a default value?", "selected": true, "answer": "Don't display version string if unavailable", "deleted": false, "createdAt": "2025-10-20T20:24:28.844Z" } ], "estimate": 2, "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 2, "nextNoteId": 0 }, "BUG-022": { "id": "BUG-022", "title": "Feature file naming for bug work units", "type": "bug", "status": "done", "createdAt": "2025-10-20T20:47:04.871Z", "updatedAt": "2025-10-20T20:59:44.477Z", "description": "When creating a bug work unit and generating scenarios, fspec creates feature files named after the bug description (task-oriented) instead of the capability being tested (capability-oriented). It should also check if an existing feature file covers the capability and either update that file or create a properly-named new file.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-20T20:47:35.812Z" }, { "state": "testing", "timestamp": "2025-10-20T20:53:30.604Z" }, { "state": "implementing", "timestamp": "2025-10-20T20:55:16.828Z" }, { "state": "validating", "timestamp": "2025-10-20T20:58:32.397Z" }, { "state": "done", "timestamp": "2025-10-20T20:59:44.477Z" } ], "userStory": { "role": "developer using fspec to fix bugs", "action": "create feature files with capability-oriented names", "benefit": "bug tests document capabilities, not problems" }, "questions": [ { "id": 0, "text": "@human: When generating feature files from bug work units, what rules should determine the capability name? Should we extract it from the bug description or ask the developer?", "selected": true, "answer": "AI should extract capability from bug context and search for existing feature files before creating new ones", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 1, "text": "@human: Should the system check for existing feature files covering the same capability before creating a new file? How should it determine if a match exists?", "selected": true, "answer": "AI agent should determine if an existing feature file is suitable for the bug scenario", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 2, "text": "@human: If an existing feature file is found that covers the capability, should we add a bug-fix scenario to that file or create a separate file?", "selected": true, "answer": "Add or update bug scenario in existing feature file (and update associated tests)", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" } ], "rules": [ { "id": 0, "text": "AI should extract capability from bug context and search for existing feature files before creating new ones", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 1, "text": "AI agent should determine if an existing feature file is suitable for the bug scenario", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 2, "text": "Add or update bug scenario in existing feature file (and update associated tests)", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 3, "text": "Feature file names must be capability-oriented (what the system CAN DO), not task-oriented (the bug description)", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 4, "text": "AI should analyze existing feature descriptions, scenarios, and tags to determine capability match", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 5, "text": "If no suitable existing feature file exists, create new file with capability-oriented name derived from bug context", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" } ], "examples": [ { "id": 0, "text": "Bug: 'fspec help displays hardcoded version 0.0.1' → AI searches features, finds 'help-command.feature' → Adds bug-fix scenario to existing file", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 1, "text": "Bug: 'fspec help displays hardcoded version 0.0.1' → AI searches features, no match found → Creates 'cli-version-display.feature' (capability-oriented name)", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 2, "text": "Bug: 'validate command crashes on empty file' → AI finds 'gherkin-validation.feature' → Adds edge-case scenario to existing file", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 3, "text": "Bug: 'format removes valid doc strings' → AI finds 'gherkin-formatting.feature' → Updates existing scenario or adds new regression scenario", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" } ], "architectureNotes": [ { "id": 0, "text": "Fix should be in src/commands/generate-scenarios.ts - the command responsible for creating feature files from work units", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 1, "text": "Need to add capability extraction logic - analyze bug description to identify underlying capability being tested", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 2, "text": "Need to add existing feature search - use fspec list-features or directly scan spec/features/ directory with feature file parsing", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" }, { "id": 3, "text": "When adding to existing file, use fspec add-scenario command to properly insert scenario with correct formatting and tags", "deleted": false, "createdAt": "2025-10-20T20:47:04.871Z" } ], "estimate": 5, "nextRuleId": 6, "nextExampleId": 4, "nextQuestionId": 3, "nextNoteId": 4 }, "SPEC-002": { "id": "SPEC-002", "title": "Scenario deduplication and refactoring detection during generation", "type": "story", "status": "done", "createdAt": "2025-10-20T21:05:14.096Z", "updatedAt": "2025-10-20T21:35:48.787Z", "description": "When generating scenarios from Example Mapping, detect if any scenarios are refactors of existing scenarios in other feature files. Update existing feature files for refactored scenarios, fix tests, regenerate coverage. Create new feature files only for truly new scenarios.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-20T21:05:19.135Z" }, { "state": "testing", "timestamp": "2025-10-20T21:19:22.664Z" }, { "state": "implementing", "timestamp": "2025-10-20T21:21:14.009Z" }, { "state": "validating", "timestamp": "2025-10-20T21:34:35.856Z" }, { "state": "done", "timestamp": "2025-10-20T21:35:48.788Z" } ], "userStory": { "role": "developer using fspec for ACDD workflow", "action": "detect and handle scenario refactoring during generation", "benefit": "I avoid duplicate scenarios across feature files and maintain proper test coverage" }, "rules": [ { "id": 0, "text": "When generating scenarios, check if any match existing scenarios in other feature files", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 1, "text": "If a scenario is a refactor of an existing scenario, update the existing feature file instead of creating a duplicate", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 2, "text": "When refactoring scenarios, update corresponding tests and regenerate coverage mappings", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 3, "text": "Create new feature files only for truly new scenarios that don't match existing ones", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 4, "text": "AI agent searches all feature files first, analyzes scenario titles and steps, takes hints from user's intent to determine if this is a refactor or genuinely new functionality", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 5, "text": "Old scenario should be updated (changed into the new scenario) because it already has associated test, implementation, and coverage mappings that should be preserved", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 6, "text": "System MUST automatically update tests and regenerate coverage when refactoring scenarios - this is enforced and non-negotiable", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 7, "text": "Detection happens during 'fspec generate-scenarios' command as primary workflow. Before generating scenarios, search existing features for matches, prompt user to confirm if refactor, then update existing feature OR create new. Also provide 'fspec audit-scenarios' as standalone command for finding duplicates across all features for maintenance/cleanup.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 8, "text": "When generating scenarios, check if any match existing scenarios in other feature files", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 9, "text": "If a scenario is a refactor of an existing scenario, update the existing feature file instead of creating a duplicate", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 10, "text": "When refactoring scenarios, update corresponding tests and regenerate coverage mappings", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 11, "text": "Create new feature files only for truly new scenarios that don't match existing ones", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 12, "text": "AI agent searches all feature files first, analyzes scenario titles and steps, takes hints from user's intent to determine if this is a refactor or genuinely new functionality", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 13, "text": "Old scenario should be updated (changed into the new scenario) because it already has associated test, implementation, and coverage mappings that should be preserved", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 14, "text": "System MUST automatically update tests and regenerate coverage when refactoring scenarios - this is enforced and non-negotiable", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 15, "text": "Detection happens during 'fspec generate-scenarios' command as primary workflow. Before generating scenarios, search existing features for matches, prompt user to confirm if refactor, then update existing feature OR create new. Also provide 'fspec audit-scenarios' as standalone command for finding duplicates across all features for maintenance/cleanup.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" } ], "questions": [ { "id": 0, "text": "@human: How should we detect if a scenario is a 'refactor' vs a 'new' scenario? Should we use semantic similarity, exact title matching, or analyze the Given-When-Then steps?", "selected": true, "answer": "AI agent searches all feature files first, analyzes scenario titles and steps, takes hints from user's intent to determine if this is a refactor or genuinely new functionality", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 1, "text": "@human: When we detect a refactored scenario, what should happen to the old scenario? Should it be marked as deprecated, deleted, or should we prompt the user to decide?", "selected": true, "answer": "Old scenario should be updated (changed into the new scenario) because it already has associated test, implementation, and coverage mappings that should be preserved", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 2, "text": "@human: Should the system automatically update tests when refactoring scenarios, or should it flag them for manual review? What about cases where tests might break?", "selected": true, "answer": "System MUST automatically update tests and regenerate coverage when refactoring scenarios - this is enforced and non-negotiable", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 3, "text": "@human: Should this detection happen during 'fspec generate-scenarios' command, or should it be a separate validation step that can be run independently?", "selected": true, "answer": "Detection happens during 'fspec generate-scenarios' command as primary workflow. Before generating scenarios, search existing features for matches, prompt user to confirm if refactor, then update existing feature OR create new. Also provide 'fspec audit-scenarios' as standalone command for finding duplicates across all features for maintenance/cleanup.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 4, "text": "@human: You mentioned 'similar to how the last bug story we fixed did' - which bug story are you referring to? Can you provide the work unit ID so I can review that approach?", "selected": true, "answer": "BUG-008: generate-scenarios produces malformed Gherkin steps from example titles. This bug fix improved how generate-scenarios parses example titles and creates proper Gherkin scenarios. The pattern we should follow is similar - analyzing example text and intelligently transforming it into proper scenarios.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 5, "text": "@human: How should we detect if a scenario is a 'refactor' vs a 'new' scenario? Should we use semantic similarity, exact title matching, or analyze the Given-When-Then steps?", "selected": true, "answer": "AI agent searches all feature files first, analyzes scenario titles and steps, takes hints from user's intent to determine if this is a refactor or genuinely new functionality", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 6, "text": "@human: When we detect a refactored scenario, what should happen to the old scenario? Should it be marked as deprecated, deleted, or should we prompt the user to decide?", "selected": true, "answer": "Old scenario should be updated (changed into the new scenario) because it already has associated test, implementation, and coverage mappings that should be preserved", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 7, "text": "@human: Should the system automatically update tests when refactoring scenarios, or should it flag them for manual review? What about cases where tests might break?", "selected": true, "answer": "System MUST automatically update tests and regenerate coverage when refactoring scenarios - this is enforced and non-negotiable", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 8, "text": "@human: Should this detection happen during 'fspec generate-scenarios' command, or should it be a separate validation step that can be run independently?", "selected": true, "answer": "Detection happens during 'fspec generate-scenarios' command as primary workflow. Before generating scenarios, search existing features for matches, prompt user to confirm if refactor, then update existing feature OR create new. Also provide 'fspec audit-scenarios' as standalone command for finding duplicates across all features for maintenance/cleanup.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 9, "text": "@human: You mentioned 'similar to how the last bug story we fixed did' - which bug story are you referring to? Can you provide the work unit ID so I can review that approach?", "selected": true, "answer": "BUG-022: Feature file naming for bug work units. AI searches existing feature files, extracts capability from bug context, and either updates existing feature file OR creates capability-oriented new file. This demonstrates the search-before-create pattern we need for scenario deduplication.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" } ], "assumptions": [ "BUG-008: generate-scenarios produces malformed Gherkin steps from example titles. This bug fix improved how generate-scenarios parses example titles and creates proper Gherkin scenarios. The pattern we should follow is similar - analyzing example text and intelligently transforming it into proper scenarios.", "CORRECTION: Reference work unit is BUG-022 (not BUG-008). BUG-022 'Feature file naming for bug work units' - AI searches existing feature files, extracts capability from bug context, and either updates existing feature file OR creates capability-oriented new file. This demonstrates the exact pattern we need: search before create, intelligently match scenarios, update existing features instead of duplicating.", "BUG-022 demonstrates the pattern: AI searches existing feature files, determines if scenario matches existing capability, and updates existing feature files instead of creating duplicates." ], "examples": [ { "id": 0, "text": "User runs 'fspec generate-scenarios AUTH-005' where examples describe login validation. System finds existing scenario 'Validate user credentials' in user-authentication.feature. System prompts: 'Scenario appears to refactor existing scenario in user-authentication.feature. Update existing? (y/n)'. User confirms 'y'. System updates existing scenario, updates test file header comment, regenerates coverage.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 1, "text": "User runs 'fspec generate-scenarios AUTH-006' where examples describe OAuth integration. System searches all feature files, finds no OAuth-related scenarios. System creates new feature file 'oauth-integration.feature' with new scenarios.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 2, "text": "User runs 'fspec generate-scenarios BUG-009' with 3 examples. System detects: Example 1 matches existing scenario in feature-validation.feature (refactor), Example 2 matches scenario in tag-management.feature (refactor), Example 3 is new. System prompts for each match, updates 2 existing features with refactored scenarios, creates new feature file for Example 3 only.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 3, "text": "User runs 'fspec audit-scenarios' after several months of development. System finds 5 duplicate scenarios across different feature files. System reports: 'Found 5 potential duplicates' with file names, scenario titles, and similarity scores. User can choose to merge duplicates interactively.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 4, "text": "User runs 'fspec generate-scenarios AUTH-005' where examples describe login validation. System finds existing scenario 'Validate user credentials' in user-authentication.feature. System prompts: 'Scenario appears to refactor existing scenario in user-authentication.feature. Update existing? (y/n)'. User confirms 'y'. System updates existing scenario, updates test file header comment, regenerates coverage.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 5, "text": "User runs 'fspec generate-scenarios AUTH-006' where examples describe OAuth integration. System searches all feature files, finds no OAuth-related scenarios. System creates new feature file 'oauth-integration.feature' with new scenarios.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 6, "text": "User runs 'fspec generate-scenarios BUG-009' with 3 examples. System detects: Example 1 matches existing scenario in feature-validation.feature (refactor), Example 2 matches scenario in tag-management.feature (refactor), Example 3 is new. System prompts for each match, updates 2 existing features with refactored scenarios, creates new feature file for Example 3 only.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" }, { "id": 7, "text": "User runs 'fspec audit-scenarios' after several months of development. System finds 5 duplicate scenarios across different feature files. System reports: 'Found 5 potential duplicates' with file names, scenario titles, and similarity scores. User can choose to merge duplicates interactively.", "deleted": false, "createdAt": "2025-10-20T21:05:14.096Z" } ], "architectureNotes": [], "estimate": 8, "nextRuleId": 16, "nextExampleId": 8, "nextQuestionId": 10, "nextNoteId": 0 }, "SPEC-003": { "id": "SPEC-003", "title": "Improve scenario similarity matching accuracy", "type": "story", "status": "done", "createdAt": "2025-10-20T21:44:50.450Z", "updatedAt": "2025-10-20T22:24:22.484Z", "description": "Replace simple Levenshtein distance with hybrid algorithm combining Jaro-Winkler, Token Set Ratio, Gherkin Structural analysis, Trigrams, and Jaccard similarity. Fix 7 critical bugs and improve accuracy from 60% to 88%.", "epic": "example-driven-discovery", "children": [], "attachments": [ "spec/attachments/SPEC-003/SIMILARITY_ANALYSIS.md", "spec/attachments/SPEC-003/ALGORITHM_ANALYSIS.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-20T21:48:29.525Z" }, { "state": "testing", "timestamp": "2025-10-20T22:02:09.310Z" }, { "state": "implementing", "timestamp": "2025-10-20T22:17:20.053Z" }, { "state": "validating", "timestamp": "2025-10-20T22:22:54.783Z" }, { "state": "done", "timestamp": "2025-10-20T22:24:22.484Z" } ], "userStory": { "role": "developer using fspec for scenario deduplication", "action": "have accurate scenario similarity matching that handles edge cases and different phrasings", "benefit": "I can confidently detect duplicate scenarios and refactoring opportunities without false positives or false negatives" }, "rules": [ { "id": 0, "text": "Similarity scoring must handle empty strings without division by zero crashes", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 1, "text": "Gherkin keywords (Given/When/Then/And/But) must be stripped from steps before similarity comparison", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 2, "text": "Keyword extraction must include numbers and special characters (OAuth2, SHA256, Base64, etc.)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 3, "text": "Division by zero must be prevented when comparing scenarios with empty keyword sets", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 4, "text": "Step reordering must not penalize similarity (Given A, Given B should match Given B, Given A)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 5, "text": "Partial step matching must be supported (3/4 identical steps should score high)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 6, "text": "Short scenario titles (< 20 chars) must use stricter thresholds to prevent false positives", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 7, "text": "Hybrid algorithm must combine at least 5 different similarity algorithms with weighted scoring", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 8, "text": "Overall accuracy must reach 88% (improvement from current 60%)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 9, "text": "Algorithm must handle word reordering without penalty (Token Set Ratio approach)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 10, "text": "Algorithm must handle typos and minor character variations (trigram similarity)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 11, "text": "Algorithm must respect Gherkin structure (Given/When/Then sections analyzed separately)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 12, "text": "Use 20 characters as threshold for short string detection (as recommended in attachments). Apply stricter threshold of 0.85 for short titles to prevent false positives.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 13, "text": "Yes - weight 'Then' steps 1.5x higher than 'Given/When' in Gherkin Structural analysis. Outcomes (Then) are more critical for determining scenario equivalence than preconditions/actions.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" } ], "examples": [ { "id": 0, "text": "BUG-1: Comparing two scenarios with empty titles should return 1.0 (both empty = identical) without division by zero crash", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 1, "text": "BUG-2: Steps 'Given user exists, When login, Then success' should have keywords stripped to 'user exists, login, success' before comparison", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 2, "text": "BUG-5: Technical terms like 'OAuth2', 'SHA256', 'Base64' must be extracted as keywords (regex must include numbers)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 3, "text": "BUG-4: Comparing scenarios with no extractable keywords should return 0 similarity without division by zero crash", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 4, "text": "ISSUE-1: 'Given user exists, Given database connected, When login' should match 100% with 'Given database connected, Given user exists, When login' (reordered steps)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 5, "text": "ISSUE-2: Scenario A with steps [X, Y, Z, W] should score 75% step similarity with Scenario B with steps [X, Y, Z, Q] (3/4 match)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 6, "text": "ISSUE-3: 'User login' vs 'User logout' should NOT score 83.3% (false positive due to short strings)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 7, "text": "Jaro-Winkler: 'User login validation' vs 'User login verification' should score ~0.92 (better than Levenshtein for prefix matching)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 8, "text": "Token Set Ratio: 'Given user exists and database connected' vs 'Given database connected and user exists' should score 1.0 (word order independence)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 9, "text": "Trigram: 'authenticate' vs 'authentcate' (typo) should score ~0.85 (typo tolerance)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 10, "text": "Gherkin Structural: Compare Given/When/Then sections separately with Jaccard similarity, weight Then steps higher (outcomes matter more)", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 11, "text": "Hybrid: Weighted combination of 5 algorithms (Jaro-Winkler 30%, Token Set 25%, Gherkin Structural 20%, Trigram 15%, Jaccard 10%) achieves 88% accuracy", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" } ], "questions": [ { "id": 0, "text": "@human: Should algorithm weights (Jaro-Winkler 30%, Token Set 25%, etc.) be configurable via options, or hardcoded based on the analysis recommendations?", "selected": true, "answer": "Configurable via options/parameters - allows dynamic tuning if results aren't optimal", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 1, "text": "@human: Should we implement Phase 1 only (80% accuracy, simpler) or both Phase 1 + Phase 2 (88% accuracy, more complex) in this work unit?", "selected": true, "answer": "Yes - implement both Phase 1 + Phase 2 for 88% accuracy target", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 2, "text": "@human: Are we okay with zero external dependencies (Phase 1+2 recommendation), or should we consider Phase 3 with Sentence-BERT ML library for 92% accuracy?", "selected": true, "answer": "Investigate semantic-chunking (https://www.npmjs.com/package/semantic-chunking) and other npm packages for semantic similarity as potential enhancement", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 3, "text": "@human: Should the similarity threshold (currently 0.7) be configurable per use case, or should we optimize it based on testing?", "selected": true, "answer": "No - threshold optimized based on testing, not user-configurable", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 4, "text": "@human: For short string bias handling, what should be the character threshold (attachments propose < 20 chars)? Should this be configurable?", "selected": true, "answer": "Use 20 characters as threshold for short string detection (as recommended in attachments). Apply stricter threshold of 0.85 for short titles to prevent false positives.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 5, "text": "@human: Should 'Then' steps (outcomes) be weighted higher than 'Given/When' steps in Gherkin Structural analysis, as proposed in the attachments?", "selected": true, "answer": "Yes - weight 'Then' steps 1.5x higher than 'Given/When' in Gherkin Structural analysis. Outcomes (Then) are more critical for determining scenario equivalence than preconditions/actions.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 6, "text": "@human: Should we prioritize speed or accuracy if there's a trade-off? (e.g., caching, two-stage filtering for large codebases)", "selected": true, "answer": "Prioritize accuracy over speed for Phase 1+2. All algorithms (Jaro-Winkler, Token Set, Gherkin Structural, Trigram, Jaccard) are O(n*m) or better. For 100+ scenarios, implement two-stage filtering: (1) fast keyword filtering, (2) full similarity on candidates.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 7, "text": "@human: Should we keep the old Levenshtein algorithm available via a flag for backward compatibility and comparison testing?", "selected": true, "answer": "Yes - keep old Levenshtein algorithm behind a flag for backward compatibility and A/B testing. Allows users to compare old vs new algorithm results during transition period.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" } ], "architectureNotes": [ { "id": 0, "text": "Current Implementation: src/utils/scenario-similarity.ts uses Levenshtein distance (character-level edit distance) with 70/30 weighted scoring (title vs steps). Has 7 critical bugs and achieves only 60% accuracy.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 1, "text": "Proposed Hybrid Algorithm: Combine 5 algorithms with weighted scoring - Jaro-Winkler (30% - title matching), Token Set Ratio (25% - word reordering), Gherkin Structural (20% - Given/When/Then awareness), Trigram Similarity (15% - fuzzy matching), Jaccard Similarity (10% - keyword overlap). Expected 88% accuracy.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 2, "text": "Bug Fixes Required: (1) Division by zero for empty strings/keywords, (2) Strip Gherkin keywords before comparison, (3) Include numbers in keyword regex for technical terms, (4) Fix keyword extraction for match objects, (5) Remove redundant lowercasing, (6) Handle step reordering, (7) Support partial step matching.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 3, "text": "Performance: All Phase 1+2 algorithms have no external dependencies and run in O(n*m) time or better. For large codebases (100+ scenarios), consider two-stage matching: (1) Fast keyword filtering, (2) Full similarity only on candidates.", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 4, "text": "Test Coverage: Must cover empty strings, empty steps, empty keywords, special characters, numbers in terms (OAuth2/SHA256), short titles, reordered steps, partial matches, typos, and performance with 100+ scenarios. See src/commands/__tests__/scenario-deduplication.test.ts", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" }, { "id": 5, "text": "References: (1) spec/attachments/SPEC-003/SIMILARITY_ANALYSIS.md - Bug analysis and test gaps, (2) spec/attachments/SPEC-003/ALGORITHM_ANALYSIS.md - Algorithm comparison and implementation guide, (3) Jaro-Winkler, Token Set Ratio, Trigram algorithms ~200 lines total with no dependencies", "deleted": false, "createdAt": "2025-10-20T21:44:50.450Z" } ], "assumptions": [ "Configurable via options/parameters - allows dynamic tuning if results aren't optimal", "Yes - implement both Phase 1 + Phase 2 for 88% accuracy target", "Investigate semantic-chunking (https://www.npmjs.com/package/semantic-chunking) and other npm packages for semantic similarity as potential enhancement", "No - threshold optimized based on testing, not user-configurable", "semantic-chunking provides semantic embeddings via ONNX models (all-MiniLM-L6-v2 at 23MB) and cosine similarity. Can be added as optional Phase 3 enhancement for semantic matching when higher accuracy needed beyond 88% target.", "Prioritize accuracy over speed for Phase 1+2. All algorithms (Jaro-Winkler, Token Set, Gherkin Structural, Trigram, Jaccard) are O(n*m) or better. For 100+ scenarios, implement two-stage filtering: (1) fast keyword filtering, (2) full similarity on candidates.", "Yes - keep old Levenshtein algorithm behind a flag for backward compatibility and A/B testing. Allows users to compare old vs new algorithm results during transition period." ], "estimate": 8, "nextRuleId": 14, "nextExampleId": 12, "nextQuestionId": 8, "nextNoteId": 6 }, "BUG-023": { "id": "BUG-023", "title": "commonPatterns displays [object Object] in help output", "type": "bug", "status": "done", "createdAt": "2025-10-21T00:28:59.162Z", "updatedAt": "2025-10-21T01:38:22.549Z", "children": [], "description": "Detailed bug analysis in spec/bugs/BUG-023-commonpatterns-formatting.md\n\nThe COMMON PATTERNS section in command help displays '[object Object]' instead of formatted pattern information. \n\nRoot cause: Type mismatch between CommandHelpConfig interface (expects string[]) and help file implementations (use objects with pattern/example/description).\n\nAffects: All help files including add-hook-help.ts and all 5 new virtual-hook help files.\n\nSee attached markdown for full analysis, reproduction steps, and recommended solutions.", "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T01:32:35.146Z" }, { "state": "testing", "timestamp": "2025-10-21T01:34:32.725Z" }, { "state": "implementing", "timestamp": "2025-10-21T01:35:33.322Z" }, { "state": "validating", "timestamp": "2025-10-21T01:38:06.003Z" }, { "state": "done", "timestamp": "2025-10-21T01:38:22.550Z" } ], "userStory": { "role": "AI agent using fspec CLI", "action": "view properly formatted COMMON PATTERNS in help output", "benefit": "I can understand usage patterns without seeing [object Object]" }, "rules": [ { "id": 0, "text": "Help formatter must support both string[] and object[] formats for commonPatterns (backward compatibility)", "deleted": false, "createdAt": "2025-10-21T00:28:59.162Z" }, { "id": 1, "text": "Object format commonPatterns must display pattern name, example command, and description", "deleted": false, "createdAt": "2025-10-21T00:28:59.162Z" }, { "id": 2, "text": "Interface must accept both formats: string[] | Array<{pattern,example,description}>", "deleted": false, "createdAt": "2025-10-21T00:28:59.162Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec add-virtual-hook --help' displays formatted patterns with name, example, and description instead of [object Object]", "deleted": false, "createdAt": "2025-10-21T00:28:59.162Z" }, { "id": 1, "text": "All 20+ affected help commands display COMMON PATTERNS section correctly after fix", "deleted": false, "createdAt": "2025-10-21T00:28:59.162Z" }, { "id": 2, "text": "Help commands still using string[] format continue to work (backward compatibility)", "deleted": false, "createdAt": "2025-10-21T00:28:59.162Z" } ], "estimate": 2, "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "HELP-003": { "id": "HELP-003", "title": "Regenerate help output for 20+ commands after BUG-023 fix", "type": "task", "status": "done", "createdAt": "2025-10-21T01:32:08.102Z", "updatedAt": "2025-10-21T01:41:10.513Z", "description": "After fixing the commonPatterns formatting bug (BUG-023), regenerate and verify help output for all affected commands to ensure proper display of COMMON PATTERNS section", "children": [], "attachments": [ "spec/attachments/HELP-003/affected-help-files.md", "spec/attachments/HELP-003/verification-report.md", "spec/attachments/HELP-003/verify-help-patterns.sh" ], "dependsOn": [ "BUG-023" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T01:39:35.953Z" }, { "state": "implementing", "timestamp": "2025-10-21T01:39:37.906Z" }, { "state": "validating", "timestamp": "2025-10-21T01:41:01.813Z" }, { "state": "done", "timestamp": "2025-10-21T01:41:10.514Z" } ], "estimate": 1, "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "GIT-001": { "id": "GIT-001", "title": "Replace git CLI usage with isomorphic-git library", "type": "story", "status": "done", "createdAt": "2025-10-21T01:48:10.185Z", "updatedAt": "2025-10-21T02:21:42.908Z", "description": "Replace all external git command calls with isomorphic-git, a pure JavaScript git implementation that can be bundled into fspec without external dependencies", "children": [], "attachments": [ "spec/attachments/GIT-001/isomorphic-git-research.md", "spec/attachments/GIT-001/testing-patterns.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T01:52:37.646Z" }, { "state": "testing", "timestamp": "2025-10-21T02:10:46.791Z" }, { "state": "implementing", "timestamp": "2025-10-21T02:14:18.345Z" }, { "state": "validating", "timestamp": "2025-10-21T02:20:14.711Z" }, { "state": "done", "timestamp": "2025-10-21T02:21:42.908Z" } ], "userStory": { "role": "developer maintaining fspec", "action": "replace git CLI calls with isomorphic-git library", "benefit": "fspec can be bundled as a single executable without external dependencies" }, "rules": [ { "id": 0, "text": "Must create comprehensive git abstraction layer in src/git/ with common operations (status, add, commit, log) following best practices patterns", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 1, "text": "Git abstraction layer must be architected as core shared infrastructure for all git operations across fspec", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 2, "text": "Keep execa dependency (used for lifecycle hooks execution) but replace all git CLI calls with isomorphic-git", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 3, "text": "Git abstraction layer must support configurable strict mode - callers can choose whether errors are thrown or silently return empty results", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 4, "text": "No barrel exports (index.ts) - consumers must import directly from specific modules like src/git/status.ts", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 5, "text": "Use modular structure with separate files per operation area: status.ts, add.ts, commit.ts, log.ts in src/git/ directory", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 6, "text": "Create semantic wrapper types that hide isomorphic-git implementation details - consumers should not depend on library-specific types like StatusRow", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 7, "text": "Internal modules can use isomorphic-git types internally but must transform to semantic types (e.g., FileStatus) at module boundaries", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 8, "text": "Use isomorphic-git testing patterns from official documentation - research and document mock filesystem approach for unit tests", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 9, "text": "No performance benchmarking required - isomorphic-git performance is acceptable for fspec use case", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 10, "text": "Complete replacement of git-context.ts implementation - no feature flags or parallel implementations", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 11, "text": "Must update existing feature file, tests, and coverage mappings to align with new isomorphic-git implementation", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" } ], "examples": [ { "id": 0, "text": "Virtual hook with git-context flag needs to get list of staged and unstaged files to pass to hook script (e.g., eslint only on changed files)", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 1, "text": "Checkpoint system (GIT-002 dependency) needs to detect all modified, staged, and untracked files before creating intelligent stash snapshot", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 2, "text": "Empty repository (git init, no commits yet) - should handle gracefully, treat all files as untracked without crashing", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 3, "text": "Repository with .gitignore - operations should respect .gitignore by default, exclude ignored files (node_modules, dist, etc.) from status results", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" }, { "id": 4, "text": "Clean repository (no changes) - returns empty arrays efficiently for staged, unstaged, and untracked files", "deleted": false, "createdAt": "2025-10-21T01:48:10.185Z" } ], "estimate": 8, "nextRuleId": 12, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "GIT-002": { "id": "GIT-002", "title": "Intelligent checkpoint system for workflow transitions", "type": "story", "status": "done", "createdAt": "2025-10-21T01:48:11.753Z", "updatedAt": "2025-10-21T03:59:02.614Z", "description": "Implement automatic git stash/restore checkpointing when work units move through Kanban states, capturing all file changes (including fspec-modified files) for rollback capability", "children": [], "dependsOn": [ "GIT-001" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T03:07:42.421Z" }, { "state": "testing", "timestamp": "2025-10-21T03:27:39.806Z" }, { "state": "implementing", "timestamp": "2025-10-21T03:30:42.709Z" }, { "state": "validating", "timestamp": "2025-10-21T03:57:36.338Z" }, { "state": "done", "timestamp": "2025-10-21T03:59:02.614Z" } ], "userStory": { "role": "developer using fspec", "action": "automatically save my work at each workflow transition", "benefit": "I can safely experiment without losing progress and recover from mistakes" }, "rules": [ { "id": 0, "text": "Checkpoints are automatically created when work unit status changes (before leaving current state)", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 1, "text": "Users can create named checkpoints manually at any time for experiments", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 2, "text": "Checkpoints capture all file changes including untracked files (respecting .gitignore)", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 3, "text": "Automatic checkpoints use pattern '{work-unit-id}-auto-{state}', manual use user-provided names", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 4, "text": "Checkpoints persist until explicitly deleted (no automatic expiration)", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 5, "text": "Checkpoints stored as git stashes with special message format for filtering", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 6, "text": "When restoration causes conflicts, AI receives system-reminder to resolve using Read/Edit tools", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 7, "text": "All tests must run and pass after checkpoint restoration with conflicts", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 8, "text": "Show all checkpoints by default with clear visual indicators (emoji like 🤖 for auto, 📌 for manual) so users feel confident in the safety net", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 9, "text": "Use 'fspec checkpoint' (short form) for AI efficiency - less verbose, faster to type in conversations", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 10, "text": "Ask user interactively when dirty working directory detected - present options (commit first, stash and restore, force restore with merge) and explain risks of each approach", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec update-work-unit-status GIT-002 implementing', system creates checkpoint 'GIT-002-auto-testing' before transition", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 1, "text": "User runs 'fspec create-checkpoint GIT-002 before-refactor', system creates named checkpoint for experimentation", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 2, "text": "User creates checkpoint 'baseline', tries approach A (fails), restores 'baseline', tries approach B (succeeds)", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 3, "text": "User restores checkpoint causing conflicts, AI receives system-reminder, reads conflicted files, resolves with Edit tool, tests run automatically, restoration completes when tests pass", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 4, "text": "User runs 'fspec list-checkpoints GIT-002', sees both automatic and manual checkpoints with timestamps", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 5, "text": "User runs 'fspec cleanup-checkpoints GIT-002 --keep-last 5', system deletes old checkpoints keeping 5 most recent", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" } ], "architectureNotes": [ { "id": 0, "text": "Git stash message format: fspec-checkpoint:{work-unit-id}:{checkpoint-name}:{timestamp}", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 1, "text": "Use 'git stash push -u -m message' to include untracked files respecting .gitignore", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 2, "text": "Use 'git stash apply stash@{N}' for restoration (preserves stash for re-restoration)", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 3, "text": "Conflict detection: parse git output for CONFLICT markers and identify affected files", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 4, "text": "AI conflict resolution: emit system-reminder with conflicted files, AI uses Read/Edit to resolve", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 5, "text": "Test validation: automatically run 'npm test' after conflict resolution, block completion if tests fail", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 6, "text": "Leverage existing isomorphic-git integration for git operations", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" } ], "questions": [ { "id": 0, "text": "@human: Should automatic checkpoints be hidden by default in 'fspec list-checkpoints GIT-002' (require --show-auto flag to display)?", "selected": true, "answer": "Show all checkpoints by default with clear visual indicators (emoji like 🤖 for auto, 📌 for manual) so users feel confident in the safety net", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 1, "text": "@human: Command naming preference: 'fspec checkpoint GIT-002 name' (short) or 'fspec create-checkpoint GIT-002 name' (explicit)?", "selected": true, "answer": "Use 'fspec checkpoint' (short form) for AI efficiency - less verbose, faster to type in conversations", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 2, "text": "@human: Should restoration fail if working directory is dirty (uncommitted changes) even without conflicts?", "selected": true, "answer": "Ask user interactively when dirty working directory detected - present options (commit first, stash and restore, force restore with merge) and explain risks of each approach", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" }, { "id": 3, "text": "@human: Should test command be configurable (package.json 'test' script vs hardcoded 'npm test')?", "selected": true, "answer": "fspec does NOT run tests - it emits system-reminder to AI agent that tests must be run. AI chooses test command (npm test, vitest, etc). This is about the system-reminder message content only.", "deleted": false, "createdAt": "2025-10-21T01:48:11.753Z" } ], "assumptions": [ "fspec does NOT run tests - it emits system-reminder to AI agent that tests must be run. AI chooses test command (npm test, vitest, etc). This is about the system-reminder message content only." ], "estimate": 8, "nextRuleId": 11, "nextExampleId": 6, "nextQuestionId": 4, "nextNoteId": 7 }, "GIT-003": { "id": "GIT-003", "title": "Fix GIT-001 critical bugs and logic errors", "type": "story", "status": "done", "createdAt": "2025-10-21T02:35:34.991Z", "updatedAt": "2025-10-21T03:03:08.487Z", "description": "Fix blocker test failure, critical logic bugs in getUnstagedFiles(), type safety violations, and add comprehensive test coverage for edge cases identified in ULTRATHINK analysis", "epic": "example-driven-discovery", "children": [], "attachments": [ "spec/attachments/GIT-003/git-001-critical-analysis.md" ], "dependsOn": [ "GIT-001" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T02:36:12.870Z" }, { "state": "testing", "timestamp": "2025-10-21T02:41:19.861Z" }, { "state": "implementing", "timestamp": "2025-10-21T03:02:35.465Z" }, { "state": "validating", "timestamp": "2025-10-21T03:02:43.916Z" }, { "state": "done", "timestamp": "2025-10-21T03:03:08.488Z" } ], "rules": [ { "id": 0, "text": "BLOCKER (S1): Fix failing test - getUnstagedFiles() returns empty array for modified files in memfs environment", "deleted": false, "createdAt": "2025-10-21T02:35:34.991Z" }, { "id": 1, "text": "CRITICAL (S2): Fix logic bug - getUnstagedFiles() misses files that are staged then modified again (partial staging scenario)", "deleted": false, "createdAt": "2025-10-21T02:35:34.991Z" }, { "id": 2, "text": "CRITICAL (S2): Fix FileStatus.modified semantic ambiguity - rename to hasUnstagedModifications or add separate hasUnstagedChanges field", "deleted": false, "createdAt": "2025-10-21T02:35:34.991Z" }, { "id": 3, "text": "HIGH (S3): Replace fs parameter type 'any' with proper IFs interface type for type safety", "deleted": false, "createdAt": "2025-10-21T02:35:34.991Z" }, { "id": 4, "text": "MEDIUM (S4): Add comprehensive test coverage for 14 missing scenarios including deleted files, nested directories, partial staging, and edge cases", "deleted": false, "createdAt": "2025-10-21T02:35:34.991Z" } ], "examples": [ { "id": 0, "text": "Failing test: File modified after commit in memfs not detected by getUnstagedFiles() - returns [] instead of ['modified.txt']", "deleted": false, "createdAt": "2025-10-21T02:35:34.991Z" }, { "id": 1, "text": "Partial staging miss: echo v2 > file.txt && git add file.txt && echo v3 >> file.txt results in file appearing in staged but NOT unstaged (should be in both)", "deleted": false, "createdAt": "2025-10-21T02:35:34.991Z" }, { "id": 2, "text": "Type safety violation: Passing { someMethod: () => {} } as fs option causes runtime error instead of compile-time error", "deleted": false, "createdAt": "2025-10-21T02:35:34.991Z" } ], "userStory": { "role": "developer maintaining fspec", "action": "fix critical bugs and logic errors in GIT-001 isomorphic-git integration", "benefit": "virtual hooks and checkpoint system work correctly with all git scenarios" }, "estimate": 8, "nextRuleId": 5, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "TECH-001": { "id": "TECH-001", "title": "JSONL format investigation for work-units.json scalability", "type": "story", "status": "done", "createdAt": "2025-10-21T05:25:29.539Z", "updatedAt": "2025-11-08T05:11:30.675Z", "description": "Investigate migrating from JSON to JSONL (JSON Lines) format for work-units.json to address file size limitations as projects scale. Research: 1) performance comparison for large datasets (1000+ work units), 2) append-only operations vs full file rewrites, 3) streaming read/write capabilities, 4) git diff friendliness, 5) backward compatibility strategies, 6) migration path from JSON to JSONL. Deliver recommendation with proof-of-concept if beneficial.", "children": [], "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T05:05:52.066Z" }, { "state": "testing", "timestamp": "2025-11-08T05:08:21.067Z" }, { "state": "implementing", "timestamp": "2025-11-08T05:10:12.511Z" }, { "state": "validating", "timestamp": "2025-11-08T05:11:12.276Z" }, { "state": "done", "timestamp": "2025-11-08T05:11:30.675Z" } ], "userStory": { "role": "developer working on large fspec projects", "action": "store work units efficiently without performance degradation", "benefit": "the system remains responsive even with 1000+ work units" }, "rules": [ { "id": 0, "text": "JSONL format must support append-only operations to avoid full file rewrites", "deleted": false, "createdAt": "2025-11-08T05:06:12.282Z" }, { "id": 1, "text": "JSONL must be backward compatible with existing JSON format or provide migration path", "deleted": false, "createdAt": "2025-11-08T05:06:13.820Z" }, { "id": 2, "text": "JSONL must provide better git diff output than monolithic JSON (show only changed lines)", "deleted": false, "createdAt": "2025-11-08T05:06:15.147Z" }, { "id": 3, "text": "JSONL streaming reads must handle large datasets (1000+ work units) without loading entire file in memory", "deleted": false, "createdAt": "2025-11-08T05:06:16.563Z" }, { "id": 4, "text": "Performance benchmarks must compare JSON vs JSONL for: read all, write one, update one, delete one operations", "deleted": false, "createdAt": "2025-11-08T05:06:18.020Z" } ], "examples": [ { "id": 0, "text": "Appending new work unit FEAT-100 to JSONL: write one line to file, no full rewrite needed", "deleted": false, "createdAt": "2025-11-08T05:06:28.708Z" }, { "id": 1, "text": "Streaming read of 1000 work units from JSONL: memory usage stays constant at ~10MB regardless of dataset size", "deleted": false, "createdAt": "2025-11-08T05:06:30.304Z" }, { "id": 2, "text": "Git diff shows: +{\"id\":\"FEAT-100\", ...} (one line added), not entire file change", "deleted": false, "createdAt": "2025-11-08T05:06:31.853Z" }, { "id": 3, "text": "Migration command: fspec migrate-to-jsonl converts work-units.json to work-units.jsonl with backup", "deleted": false, "createdAt": "2025-11-08T05:06:33.595Z" }, { "id": 4, "text": "Performance test: writing 1000 work units to JSONL takes 0.5s vs 10s for JSON (20x faster)", "deleted": false, "createdAt": "2025-11-08T05:06:34.972Z" } ], "estimate": 8, "questions": [], "architectureNotes": [], "updated": "2025-11-08T05:11:30.675Z" }, "BOARD-002": { "id": "BOARD-002", "title": "Interactive Kanban board CLI", "type": "story", "status": "done", "createdAt": "2025-10-21T05:25:48.725Z", "updatedAt": "2025-10-27T06:34:19.400Z", "description": "Create an interactive terminal interface for fspec board that allows keyboard navigation across columns and work units. Press Enter to view full work unit details including description, attachments, example mapping data, dependencies, metrics, and more. Support vim-style navigation (hjkl), arrow keys, tab to switch columns, and quick actions (e.g., 's' for status change, 'e' to edit, 'a' for attachments).", "epic": "interactive-cli", "children": [], "attachments": [ "spec/attachments/BOARD-002/interactive-kanban-board-design.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T05:23:40.679Z" }, { "state": "testing", "timestamp": "2025-10-27T05:27:12.661Z" }, { "state": "implementing", "timestamp": "2025-10-27T05:28:24.067Z" }, { "state": "validating", "timestamp": "2025-10-27T05:36:04.373Z" }, { "state": "done", "timestamp": "2025-10-27T05:38:17.307Z" }, { "state": "specifying", "timestamp": "2025-10-27T06:26:43.346Z" }, { "state": "testing", "timestamp": "2025-10-27T06:27:51.687Z" }, { "state": "implementing", "timestamp": "2025-10-27T06:28:29.902Z" }, { "state": "validating", "timestamp": "2025-10-27T06:30:19.984Z" }, { "state": "done", "timestamp": "2025-10-27T06:32:34.448Z" }, { "state": "specifying", "timestamp": "2025-10-27T06:33:08.185Z" }, { "state": "testing", "timestamp": "2025-10-27T06:34:16.054Z" }, { "state": "implementing", "timestamp": "2025-10-27T06:34:17.176Z" }, { "state": "validating", "timestamp": "2025-10-27T06:34:18.281Z" }, { "state": "done", "timestamp": "2025-10-27T06:34:19.400Z" } ], "userStory": { "role": "developer managing work units", "action": "navigate and interact with Kanban board using keyboard shortcuts", "benefit": "I can efficiently view, update, and manage work units without leaving the terminal" }, "rules": [ { "id": 0, "text": "Board must display 7 Kanban columns: backlog, specifying, testing, implementing, validating, done, blocked", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 1, "text": "Arrow keys (←→ or hjkl) navigate between columns, ↑↓ (or jk) navigate work units within column", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 2, "text": "Enter key opens detailed view of selected work unit", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 3, "text": "Work unit cards show: type icon (📖/🐛/⚙️), ID, estimate, priority indicator (🔴🟡🟢), truncated title", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 4, "text": "Selected work unit highlighted with cyan background, focused column has cyan border", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 5, "text": "Board loads work units from Zustand store (fspecStore.loadData() on mount)", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 6, "text": "Empty columns display 'No work units' message", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 7, "text": "Column headers show: status name, count, total story points", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 8, "text": "ESC key returns to previous view or exits board", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 9, "text": "Detail view must display: work unit ID, title, description, type, status, estimate, epic, rules, examples, questions, attachments, dependencies, and 'Press ESC to return' message", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" } ], "examples": [ { "id": 0, "text": "User presses → arrow - focus moves from BACKLOG to SPECIFYING column, first work unit in SPECIFYING is selected", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 1, "text": "User presses ↓ arrow - selection moves from RES-003 to RES-004 within BACKLOG column", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 2, "text": "User presses Enter on ITF-002 - opens detail view showing full description, Example Mapping data, attachments", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 3, "text": "BACKLOG column header shows: 'BACKLOG (26) - 78pts'", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 4, "text": "Work unit ITF-001 (story, 5pt estimate) displays as: 📖 ITF-001 5pt 🟡", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 5, "text": "Empty TESTING column shows 'No work units' message centered in column", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 6, "text": "Board loads on mount by calling fspecStore.loadData() and displaying work units grouped by status", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 7, "text": "Footer displays: '← → Columns | ↑↓ jk Work Units | ↵ Details | ESC Back'", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 8, "text": "User presses Enter on BOARD-002 (currently selected) → Detail view opens showing: 'BOARD-002', 'Interactive Kanban board CLI', full description, 9 rules, 8 examples, 3 questions (answered), 1 attachment, 'Press ESC to return'", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" } ], "questions": [ { "id": 0, "text": "Should column navigation wrap around (pressing → on BLOCKED goes to BACKLOG)?", "selected": true, "answer": "Yes - wrap around. Pressing → on BLOCKED wraps to BACKLOG, ← on BACKLOG wraps to BLOCKED. Same for work units: ↓ on last wraps to first, ↑ on first wraps to last.", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 1, "text": "Should work unit navigation within column wrap around (pressing ↓ on last item goes to first)?", "selected": true, "answer": "Yes - wrap around for seamless navigation. Pressing → on BLOCKED wraps to BACKLOG, pressing ← on BACKLOG wraps to BLOCKED.", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" }, { "id": 2, "text": "What happens when navigating to an empty column - skip it or allow focus with no selection?", "selected": true, "answer": "Yes - work unit navigation wraps. Pressing ↓ on last work unit selects first work unit, pressing ↑ on first selects last.", "deleted": false, "createdAt": "2025-10-21T05:25:48.725Z" } ], "estimate": 8, "nextRuleId": 10, "nextExampleId": 9, "nextQuestionId": 3, "nextNoteId": 0 }, "CLEAN-001": { "id": "CLEAN-001", "title": "Add ESLint and Prettier for code quality", "type": "story", "status": "done", "createdAt": "2025-10-21T05:53:29.407Z", "updatedAt": "2025-10-26T04:35:56.985Z", "description": "Set up ESLint and Prettier to enforce consistent code style and catch common errors. This includes configuration, fixing existing violations, and integrating with the development workflow.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-26T03:42:35.790Z" }, { "state": "testing", "timestamp": "2025-10-26T03:49:41.728Z" }, { "state": "specifying", "timestamp": "2025-10-26T04:03:22.774Z" }, { "state": "testing", "timestamp": "2025-10-26T04:05:17.712Z" }, { "state": "specifying", "timestamp": "2025-10-26T04:07:35.182Z" }, { "state": "testing", "timestamp": "2025-10-26T04:08:08.945Z" }, { "state": "implementing", "timestamp": "2025-10-26T04:10:45.800Z" }, { "state": "validating", "timestamp": "2025-10-26T04:13:53.425Z" }, { "state": "specifying", "timestamp": "2025-10-26T04:22:05.705Z" }, { "state": "testing", "timestamp": "2025-10-26T04:23:16.009Z" }, { "state": "specifying", "timestamp": "2025-10-26T04:24:15.665Z" }, { "state": "testing", "timestamp": "2025-10-26T04:25:18.384Z" }, { "state": "implementing", "timestamp": "2025-10-26T04:28:55.408Z" }, { "state": "validating", "timestamp": "2025-10-26T04:32:53.837Z" }, { "state": "done", "timestamp": "2025-10-26T04:35:56.985Z" } ], "userStory": { "role": "developer contributing to fspec", "action": "have ESLint and Prettier configured and running", "benefit": "code quality is consistent and common errors are caught automatically" }, "rules": [ { "id": 0, "text": "ESLint configuration MUST align with TypeScript strict mode and existing CLAUDE.md coding standards", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 1, "text": "Prettier MUST be configured to match existing code formatting (2-space indentation, single quotes, etc.)", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 2, "text": "All existing code violations MUST be fixed before integration (no warnings/errors in CI)", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 3, "text": "Integration MUST NOT break existing npm scripts (build, test, dev)", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 4, "text": "ESLint and Prettier MUST work together without conflicts (use eslint-config-prettier)", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'npm run lint' and all TypeScript files are checked with ESLint showing zero errors", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 1, "text": "Developer runs 'npm run format' and all files are formatted consistently with Prettier", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 2, "text": "Developer runs 'npm run build' and it completes successfully (lint doesn't break build)", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 3, "text": "Developer commits code and pre-commit hook runs ESLint+Prettier automatically", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 4, "text": "ESLint catches common TypeScript errors (unused vars, missing types, etc.) during development", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" }, { "id": 5, "text": "Prettier formats code on save in VSCode/IDE with consistent 2-space indentation and single quotes", "deleted": false, "createdAt": "2025-10-21T05:53:29.407Z" } ], "estimate": 5, "nextRuleId": 5, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "INIT-004": { "id": "INIT-004", "title": "Support multiple AI agents beyond Claude", "type": "story", "status": "done", "createdAt": "2025-10-21T05:58:37.972Z", "updatedAt": "2025-10-21T10:50:48.434Z", "description": "Support multiple AI agents beyond Claude by cloning other AI agent tools to understand their capabilities and configuration requirements. Research how agents like Cursor, Aider, and Continue.dev work to design fspec integration patterns.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T08:45:16.988Z" }, { "state": "testing", "timestamp": "2025-10-21T10:22:39.520Z" }, { "state": "implementing", "timestamp": "2025-10-21T10:31:02.888Z" }, { "state": "validating", "timestamp": "2025-10-21T10:37:36.334Z" }, { "state": "done", "timestamp": "2025-10-21T10:38:20.381Z" } ], "attachments": [ "spec/attachments/INIT-004/ai-coding-agents-october-2025.md", "spec/attachments/INIT-004/multi-agent-implementation-research.md", "spec/attachments/INIT-004/interactive-agent-selector-implementation.md", "spec/attachments/INIT-004/agent-auto-loading-capabilities-research.md", "spec/attachments/INIT-004/agent-instruction-mechanisms-research.md" ], "rules": [ { "id": 0, "text": "Each AI agent must have its own documentation template (e.g., CLAUDE.md, AIDER.md, CURSOR.md)", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 1, "text": "System-reminder tags are Claude Code specific and must be abstracted or made optional for other agents", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 2, "text": "fspec init command must support --agent flag to specify which AI agent to configure", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 3, "text": "Slash command directory paths vary by agent (e.g., .claude/commands/ vs .continue/commands/)", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 4, "text": "Documentation must avoid hardcoded references to 'Claude' or 'Claude Code' in agent-agnostic sections", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 5, "text": "Yes, support multiple agents: Allow 'fspec init --agent=aider --agent=cursor' to install configurations for multiple agents simultaneously. Generate spec/AGENT.md for each and install slash commands to respective directories", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 6, "text": "Agent-specific prompting vocabulary (like 'ultrathink' for Claude) must be translated or removed for each agent based on their capabilities", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 7, "text": "fspec init must create slash commands for ALL major fspec CLI commands (validate, format, list-features, create-work-unit, etc.), not just documentation", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 8, "text": "All agent templates must be bundled in fspec distribution using Vite copy plugin", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 9, "text": "Template directory structure must support both flat (cursor) and nested (claude) slash command paths", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 10, "text": "Generate on-the-fly using TemplateManager pattern: shared command body + agent-specific wrappers (frontmatter, path, argument placeholders). Avoids 360-540 template files, enables consistency across agents", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 11, "text": "Remove meta-cognitive prompts for CLI-only agents (Aider, Gemini CLI, Qwen CLI). Keep for IDE/extension-based agents (Cline, Windsurf, Cursor). Agent registry should have 'supportsMetaCognition' flag to control this", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 12, "text": "Support both: 'fspec init' (no flags) shows interactive selector by default. 'fspec init --agent=X' runs non-interactive mode for automation/scripts", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 13, "text": "Yes, auto-detect installed agents by checking for directories (.claude/, .cursor/, etc.). Sort list with: 1) Detected agents at top (pre-selected), 2) Popular agents (Claude Code, Codex, Copilot), 3) Remaining agents alphabetically", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 14, "text": "Support all 18 agents in v1. Use dynamic generation - ONE base template that gets transformed based on agent capabilities (system-reminder support, meta-cognition support, slash command format). No separate template files per agent.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 15, "text": "Install THREE files per agent: 1) Root stub (AGENTS.md or AGENT_NAME.md) for auto-loading, 2) Full doc (spec/AGENT_NAME.md) for comprehensive workflow, 3) Slash command (.agent/commands/fspec.md) for manual trigger. Most agents (Claude, Cursor, Cline, Windsurf, Copilot, etc.) auto-load root stubs; CLI-only tools need slash commands.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 16, "text": "fspec init is idempotent and supports agent switching. Running 'fspec init --agent=cursor' after 'fspec init --agent=claude' should remove Claude-specific files (CLAUDE.md, spec/CLAUDE.md, .claude/commands/) and install Cursor-specific files (CURSOR.md or AGENTS.md, spec/CURSOR.md, .cursor/commands/). All files are auto-generated, safe to replace.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 17, "text": "Interactive selector is SINGLE-SELECT: arrow keys to navigate/highlight, Enter to confirm the currently highlighted agent. No multi-select, no checkboxes. For multiple agents, user must run 'fspec init --agent=X --agent=Y' using CLI flags.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 18, "text": "Default highlighted agent should be the FIRST DETECTED agent (if any were auto-detected). If no agents detected, default to first agent in sorted list.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 19, "text": "No --no-interactive flag needed. Presence of --agent flags is sufficient to determine mode: if --agent present, use CLI mode; if no --agent, use interactive mode. A --no-interactive flag without --agent makes no sense.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 20, "text": "fspec init is NON-DESTRUCTIVE: if .cursor/commands/ already exists with custom files, create fspec.md alongside them. Never delete or overwrite user's custom files. Only manage fspec-specific files (AGENTS.md, spec/AGENT.md, .agent/commands/fspec.md).", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 21, "text": "Validate agent IDs against registry before installation. Check file permissions before writing. Create directories recursively (mkdir -p). Handle missing templates gracefully with error messages. Wrap blocking hook failures in <system-reminder> tags for AI visibility.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 22, "text": "Generate ONE comprehensive fspec.md per agent (1010-line pattern like current .claude/commands/fspec.md). NOT multiple smaller files. This file contains complete ACDD workflow, Example Mapping process, coverage tracking, etc. Format varies by agent: Markdown with YAML frontmatter (Claude, Cursor, Cline, etc.) or TOML (Gemini CLI, Qwen Code).", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 23, "text": "Invalid agent ID: Show error with list of valid agents, exit code 1. Missing templates: Check dist/spec/templates/ and fallback to spec/templates/. If both missing, show error explaining distribution may be corrupted. Suggest reinstalling fspec. Permission errors: Show clear message about directory permissions, suggest chmod/chown fixes.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 24, "text": "Research complete - see spec/attachments/INIT-004/agent-instruction-mechanisms-research.md. Finding: Claude Code's <system-reminder> tags are UNIQUE. All other agents use visible Markdown patterns: bold text (**IMPORTANT:**), headers (###), code blocks, blockquotes. Transformation required: <system-reminder> → **⚠️ IMPORTANT:** (IDE agents) or **IMPORTANT:** (CLI agents). No equivalent invisible mechanism exists for other agents.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec init --agent=aider' and gets Aider-specific documentation template copied to spec/AIDER.md", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 1, "text": "User runs 'fspec init --agent=cursor' and slash command is installed to .cursor/commands/fspec.md", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 2, "text": "User runs 'fspec init --agent=cline' and gets Cline-specific docs without system-reminder references", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 3, "text": "User runs 'fspec init --agent=cursor' and gets 20+ slash commands created (.cursor/commands/fspec-validate.md, .cursor/commands/fspec-format.md, etc.) plus spec/CURSOR.md", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 4, "text": "After 'npm install -g fspec', global installation contains bundled templates at node_modules/fspec/dist/spec/templates/cursor/CURSOR.md", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 5, "text": "CLAUDE.md contains 'ultrathink your next steps' but AIDER.md (CLI-based) removes meta-cognitive prompts entirely", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" } ], "questions": [ { "id": 0, "text": "@human: Should fspec init auto-detect which AI agent is being used, or always require explicit --agent flag?", "selected": true, "answer": "Support both: 'fspec init' (no flags) shows interactive selector by default. 'fspec init --agent=X' runs non-interactive mode for automation/scripts", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 1, "text": "@human: For agents without system-reminder support, should we strip those tags or replace with agent-specific patterns?", "selected": true, "answer": "Yes, auto-detect installed agents by checking for directories (.claude/, .cursor/, etc.). Sort list with: 1) Detected agents at top (pre-selected), 2) Popular agents (Claude Code, Codex, Copilot), 3) Remaining agents alphabetically", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 2, "text": "@human: Should 'fspec init' support multiple agents simultaneously (e.g., team with mixed Cursor + Aider users)?", "selected": true, "answer": "Support all 18 agents in v1. Use dynamic generation - ONE base template that gets transformed based on agent capabilities (system-reminder support, meta-cognition support, slash command format). No separate template files per agent.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 3, "text": "@human: Should we bundle ALL 18 agents' templates (increasing package size significantly) or allow dynamic generation?", "selected": true, "answer": "Research which agents support auto-loading project context files (AGENT.md pattern) vs requiring slash commands. Install both for v1 to maximize compatibility.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 4, "text": "@human: Should slash command templates be generated on-the-fly from shared logic or pre-built and bundled?", "selected": true, "answer": "Install THREE files per agent: 1) Root stub (AGENTS.md or AGENT_NAME.md) for auto-loading, 2) Full doc (spec/AGENT_NAME.md) for comprehensive workflow, 3) Slash command (.agent/commands/fspec.md) for manual trigger. Most agents (Claude, Cursor, Cline, Windsurf, Copilot, etc.) auto-load root stubs; CLI-only tools need slash commands.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 5, "text": "@human: How do we handle agents that don't support meta-cognitive prompts like 'ultrathink' (e.g., CLI-only Aider)?", "selected": true, "answer": "fspec init is idempotent and supports agent switching. Running 'fspec init --agent=cursor' after 'fspec init --agent=claude' should remove Claude-specific files (CLAUDE.md, spec/CLAUDE.md, .claude/commands/) and install Cursor-specific files (CURSOR.md or AGENTS.md, spec/CURSOR.md, .cursor/commands/). All files are auto-generated, safe to replace.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 6, "text": "@human: Should fspec init use interactive mode by default, or require explicit flags?", "selected": true, "answer": "Interactive selector is SINGLE-SELECT: arrow keys to navigate/highlight, Enter to confirm the currently highlighted agent. No multi-select, no checkboxes. For multiple agents, user must run 'fspec init --agent=X --agent=Y' using CLI flags.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 7, "text": "@human: Should interactive selector auto-detect installed agents and how should the list be sorted?", "selected": true, "answer": "Default highlighted agent should be the FIRST DETECTED agent (if any were auto-detected). If no agents detected, default to first agent in sorted list.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 8, "text": "@human: Should we support all 18 agents in v1, or start with a smaller set? Should we use separate template files or dynamic generation?", "selected": true, "answer": "No --no-interactive flag needed. Presence of --agent flags is sufficient to determine mode: if --agent present, use CLI mode; if no --agent, use interactive mode. A --no-interactive flag without --agent makes no sense.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 9, "text": "@human: Should we install both AGENT.md (for auto-load on startup) AND a slash command (for manual trigger), or just one? Which agents support auto-loading project context files?", "selected": true, "answer": "fspec init is NON-DESTRUCTIVE: if .cursor/commands/ already exists with custom files, create fspec.md alongside them. Never delete or overwrite user's custom files. Only manage fspec-specific files (AGENTS.md, spec/AGENT.md, .agent/commands/fspec.md).", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 10, "text": "@human: Should fspec init be idempotent? If user runs 'fspec init --agent=cursor' after already running 'fspec init --agent=claude', what should happen?", "selected": true, "answer": "Single base template with dynamic transformations based on agent.supportsSystemReminders, agent.supportsMetaCognition, and agent.category flags. Use TemplateManager pattern: ONE base template transformed via regex replacement and formatting functions.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 11, "text": "@human: Is the interactive selector single-select (arrow to highlight, enter to confirm) or multi-select (space to toggle checkboxes, enter to confirm multiple)?", "selected": true, "answer": "System-reminders: <system-reminder> → **⚠️ IMPORTANT:** (IDE agents with emoji) or **IMPORTANT:** (CLI agents). Meta-cognitive prompts: 'ultrathink', 'deeply consider' → removed for CLI-only agents. Use regex patterns. Agent placeholders: {{AGENT_NAME}}, {{SLASH_COMMAND_PATH}}, {{AGENT_ID}} replaced via string.replace().", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 12, "text": "@human: In interactive selector, which agent should be highlighted by default when the UI opens?", "selected": true, "answer": "ONE comprehensive fspec.md file per agent (like current 1010-line pattern), NOT multiple smaller files. Different formats: Markdown with YAML frontmatter (Claude, Cursor, Cline) or TOML (Gemini CLI, Qwen Code). Generate using TemplateManager pattern: shared body + agent-specific wrapper.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 13, "text": "@human: Do we need a --no-interactive flag, or is presence of --agent flags sufficient to disable interactive mode?", "selected": true, "answer": "Validate agent IDs against registry before installation. Check file permissions before writing. Create directories recursively (mkdir -p). Handle missing templates gracefully with error messages. Wrap blocking hook failures in <system-reminder> tags for AI visibility.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 14, "text": "@human: If target directories already exist with user's custom files (e.g., .cursor/commands/my-command.md), should fspec init be destructive or non-destructive?", "selected": true, "answer": "Use viteStaticCopy plugin to copy base template files (spec/templates/base/*.md) into dist/ during build. Templates bundled into dist/spec/templates/base/. Component code bundled normally by Vite. Template resolver tries production path first, falls back to dev path.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 15, "text": "@human: How do we transform the base template for different agents? Single base template with dynamic transformations based on agent.supportsSystemReminders, agent.supportsMetaCognition flags? Or multiple template tiers?", "selected": true, "answer": "id: string, name: string, description: string, slashCommandPath: string, slashCommandFormat: 'markdown' | 'toml', supportsSystemReminders: boolean, supportsMetaCognition: boolean, docTemplate: string, rootStubFile: string, detectionPaths: string[], available: boolean, category: 'ide' | 'cli' | 'extension'", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 16, "text": "@human: What exact patterns need transformation? 'ultrathink' → 'carefully consider'? '<system-reminder>' → '<\\!-- IMPORTANT: -->'? Any others? Should we use regex, string replacement, or AST parsing?", "selected": true, "answer": "Transform 'ultrathink' → removed (CLI agents) or kept (IDE agents). System-reminder: '<system-reminder>' → '**⚠️ IMPORTANT:**' (IDE with emoji) or '**IMPORTANT:**' (CLI). Also transform: 'deeply consider', 'take a moment to reflect' → removed for CLI agents. Use regex replacement: /<system-reminder>([\\s\\S]*?)<\\/system-reminder>/g. Placeholders: {{AGENT_NAME}}, {{SLASH_COMMAND_PATH}} via string.replace().", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 17, "text": "@human: Current .claude/commands/fspec.md is 1010 lines (comprehensive workflow guide). Should we generate ONE comprehensive fspec.md per agent (same pattern), or MULTIPLE smaller commands (fspec-validate.md, fspec-format.md, etc.)?", "selected": true, "answer": "Generate ONE comprehensive fspec.md per agent (1010-line pattern like current .claude/commands/fspec.md). NOT multiple smaller files. This file contains complete ACDD workflow, Example Mapping process, coverage tracking, etc. Format varies by agent: Markdown with YAML frontmatter (Claude, Cursor, Cline, etc.) or TOML (Gemini CLI, Qwen Code).", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 18, "text": "@human: Error handling: What should happen if user runs 'fspec init --agent=invalid-id'? Show list of valid agents? Exit with error code? What if template files missing from dist/?", "selected": true, "answer": "Invalid agent ID: Show error with list of valid agents, exit code 1. Missing templates: Check dist/spec/templates/ and fallback to spec/templates/. If both missing, show error explaining distribution may be corrupted. Suggest reinstalling fspec. Permission errors: Show clear message about directory permissions, suggest chmod/chown fixes.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 19, "text": "@human: Vite bundling: Should we bundle base template files (spec/templates/base/AGENT.md) in dist/, or bundle transformation logic as compiled code? What's the dist/ structure after build?", "selected": true, "answer": "Bundle base template files using viteStaticCopy plugin. Structure: dist/spec/templates/base/AGENT.md (ONE base template with placeholders). Runtime: templateGenerator.ts reads from dist/spec/templates/base/, transforms based on agent config, outputs to spec/AGENT.md. Dev mode: reads from spec/templates/base/. Template resolver tries production path first, falls back to dev.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 20, "text": "@human: Agent registry structure: Confirm complete AgentConfig interface fields (id, name, description, category, rootStubFile, fullDocFile, slashCommandPath, slashCommandFormat, detectionPaths, supportsSystemReminders, supportsMetaCognition, popularity for sorting). Missing any fields?", "selected": true, "answer": "AgentConfig fields confirmed: id (string), name (string), description (string), slashCommandPath (string), slashCommandFormat ('markdown' | 'toml'), supportsSystemReminders (boolean), supportsMetaCognition (boolean), docTemplate (string, e.g. 'CLAUDE.md'), rootStubFile (string, e.g. 'CLAUDE.md' or 'AGENTS.md'), detectionPaths (string[], e.g. ['.claude/', '.claude/commands/']), available (boolean), category ('ide' | 'cli' | 'extension'). Optional: popularity (number) for sorting.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 21, "text": "@human: Claude Code uses <system-reminder> tags for invisible-to-user workflow guidance. What equivalent mechanisms do other agents have for getting attention and providing hidden instructions? Need research on all 18 agents' attention/instruction mechanisms.", "selected": true, "answer": "Research complete - see spec/attachments/INIT-004/agent-instruction-mechanisms-research.md. Finding: Claude Code's <system-reminder> tags are UNIQUE. All other agents use visible Markdown patterns: bold text (**IMPORTANT:**), headers (###), code blocks, blockquotes. Transformation required: <system-reminder> → **⚠️ IMPORTANT:** (IDE agents) or **IMPORTANT:** (CLI agents). No equivalent invisible mechanism exists for other agents.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" } ], "architectureNotes": [ { "id": 0, "text": "Create agent registry in spec/agents.json mapping agent names to configuration (doc template, slash command path, system-reminder support, etc.)", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 1, "text": "Refactor init command: add --agent flag, read agent config from registry, copy appropriate templates, generate agent-specific documentation", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 2, "text": "Create template system: templates/{agent-name}/AGENT.md and templates/{agent-name}/slash-command.md with variable substitution", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 3, "text": "Add agent detection: check for .claude/, .cursor/, .continue/ directories or environment variables to auto-detect active agent", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 4, "text": "Update vite.config.ts to copy spec/templates/{agent}/**/*.md to dist/spec/templates/{agent}/ for bundled distribution", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 5, "text": "Template matrix challenge: 20-30 fspec commands × 18 agents = 360-540 template files. Consider shared template body + agent-specific wrappers to reduce duplication", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 6, "text": "Init command must locate templates from bundled distribution (handle both dev: spec/templates/ and production: dist/spec/templates/ paths)", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" }, { "id": 7, "text": "ink/react Integration Architecture: Refactor fspec to use ink/react for ALL interactive commands (not just init). Create shared component library in src/components/ (AgentSelector, Spinner, ErrorMessage, SuccessMessage, ConfirmPrompt, etc.) and shared hooks in src/hooks/ (useKeyboardNavigation, useSafeInput, useAgentSelection). Follow DRY principles - reuse cage patterns (MainMenu navigation, keyboard input handling, visual feedback). Commands like 'fspec reverse', 'fspec board', future interactive commands should all use shared ink/react components. Vite build handles React/JSX compilation.", "deleted": false, "createdAt": "2025-10-21T05:58:37.972Z" } ], "userStory": { "role": "developer using any AI coding agent", "action": "initialize fspec in my project with agent-specific configuration", "benefit": "I get properly formatted documentation and setup tailored to my agent without manual editing" }, "assumptions": [ "Auto-detect with fallback to explicit flag: Check for agent directories (.claude/, .cursor/, .continue/) and environment variables first, but allow --agent flag to override. Default to Claude Code if no detection", "Strip system-reminder tags for non-Claude agents: Use agent registry to check 'supportsSystemReminders' flag. For agents without support, strip tags but preserve content as comments or agent-specific annotations", "Bundle ALL 18 agents in v1 for simplicity and feature completeness. Future optimization: lazy-download popular agents on first use to reduce package size", "Research which agents support auto-loading project context files (AGENT.md pattern) vs requiring slash commands. Install both for v1 to maximize compatibility.", "Single base template with dynamic transformations based on agent.supportsSystemReminders, agent.supportsMetaCognition, and agent.category flags. Use TemplateManager pattern: ONE base template transformed via regex replacement and formatting functions.", "System-reminders: <system-reminder> → **⚠️ IMPORTANT:** (IDE agents with emoji) or **IMPORTANT:** (CLI agents). Meta-cognitive prompts: 'ultrathink', 'deeply consider' → removed for CLI-only agents. Use regex patterns. Agent placeholders: {{AGENT_NAME}}, {{SLASH_COMMAND_PATH}}, {{AGENT_ID}} replaced via string.replace().", "ONE comprehensive fspec.md file per agent (like current 1010-line pattern), NOT multiple smaller files. Different formats: Markdown with YAML frontmatter (Claude, Cursor, Cline) or TOML (Gemini CLI, Qwen Code). Generate using TemplateManager pattern: shared body + agent-specific wrapper.", "Use viteStaticCopy plugin to copy base template files (spec/templates/base/*.md) into dist/ during build. Templates bundled into dist/spec/templates/base/. Component code bundled normally by Vite. Template resolver tries production path first, falls back to dev path.", "id: string, name: string, description: string, slashCommandPath: string, slashCommandFormat: 'markdown' | 'toml', supportsSystemReminders: boolean, supportsMetaCognition: boolean, docTemplate: string, rootStubFile: string, detectionPaths: string[], available: boolean, category: 'ide' | 'cli' | 'extension'", "Transform 'ultrathink' → removed (CLI agents) or kept (IDE agents). System-reminder: '<system-reminder>' → '**⚠️ IMPORTANT:**' (IDE with emoji) or '**IMPORTANT:**' (CLI). Also transform: 'deeply consider', 'take a moment to reflect' → removed for CLI agents. Use regex replacement: /<system-reminder>([\\s\\S]*?)<\\/system-reminder>/g. Placeholders: {{AGENT_NAME}}, {{SLASH_COMMAND_PATH}} via string.replace().", "Bundle base template files using viteStaticCopy plugin. Structure: dist/spec/templates/base/AGENT.md (ONE base template with placeholders). Runtime: templateGenerator.ts reads from dist/spec/templates/base/, transforms based on agent config, outputs to spec/AGENT.md. Dev mode: reads from spec/templates/base/. Template resolver tries production path first, falls back to dev.", "AgentConfig fields confirmed: id (string), name (string), description (string), slashCommandPath (string), slashCommandFormat ('markdown' | 'toml'), supportsSystemReminders (boolean), supportsMetaCognition (boolean), docTemplate (string, e.g. 'CLAUDE.md'), rootStubFile (string, e.g. 'CLAUDE.md' or 'AGENTS.md'), detectionPaths (string[], e.g. ['.claude/', '.claude/commands/']), available (boolean), category ('ide' | 'cli' | 'extension'). Optional: popularity (number) for sorting." ], "estimate": 8, "nextRuleId": 25, "nextExampleId": 6, "nextQuestionId": 22, "nextNoteId": 8 }, "RES-001": { "id": "RES-001", "title": "Interactive research command with multiple backend support", "type": "story", "status": "done", "createdAt": "2025-10-21T07:32:19.749Z", "updatedAt": "2025-11-08T02:10:56.865Z", "description": "Implement 'fspec research' command that provides AI agents with interactive choice of registered research endpoints during specifying phase (example mapping, architecture planning). Support multiple backends: (1) Perplexity via MCP (https://github.com/jsonallen/perplexity-mcp) for web search, (2) Nanobrowser via MCP for browser automation and web scraping, (3) Mindstrike via CLI for AI-powered knowledge queries. Command should register available endpoints, present interactive selection to AI agent, execute research query, and return formatted results.", "epic": "example-driven-discovery", "children": [], "nextRuleId": 9, "nextExampleId": 8, "nextQuestionId": 0, "nextNoteId": 0, "dependsOn": [ "RES-002", "RES-003", "RES-004", "RES-005" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T01:48:44.751Z" }, { "state": "testing", "timestamp": "2025-11-08T01:51:46.774Z" }, { "state": "implementing", "timestamp": "2025-11-08T01:54:28.344Z" }, { "state": "validating", "timestamp": "2025-11-08T02:07:05.651Z" }, { "state": "done", "timestamp": "2025-11-08T02:10:56.866Z" } ], "userStory": { "role": "AI agent or developer using fspec", "action": "research questions interactively during Example Mapping", "benefit": "I can choose from multiple research backends and get formatted results" }, "rules": [ { "id": 0, "text": "Command lists available research tools when run without arguments", "deleted": false, "createdAt": "2025-11-08T01:49:07.076Z" }, { "id": 1, "text": "Auto-discover tools from spec/research-scripts/ directory by scanning for executable files", "deleted": false, "createdAt": "2025-11-08T01:49:07.588Z" }, { "id": 2, "text": "Tool name derived from filename (e.g., perplexity → 'perplexity')", "deleted": false, "createdAt": "2025-11-08T01:49:08.092Z" }, { "id": 3, "text": "Execute research tool with --tool and --query flags", "deleted": false, "createdAt": "2025-11-08T01:49:08.602Z" }, { "id": 4, "text": "Prompt user to attach results to work unit after research completes", "deleted": false, "createdAt": "2025-11-08T01:49:09.108Z" }, { "id": 5, "text": "Display tool usage examples when listing available tools", "deleted": false, "createdAt": "2025-11-08T01:49:18.197Z" }, { "id": 6, "text": "Return error with helpful message if tool not found", "deleted": false, "createdAt": "2025-11-08T01:49:18.703Z" }, { "id": 7, "text": "Save research results as attachment in spec/attachments/WORK-ID/ directory", "deleted": false, "createdAt": "2025-11-08T01:49:19.202Z" }, { "id": 8, "text": "Support all research scripts: perplexity, jira, confluence, and future tools", "deleted": false, "createdAt": "2025-11-08T01:49:19.708Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'fspec research' without args, sees list of available tools with descriptions and usage examples", "deleted": false, "createdAt": "2025-11-08T01:49:29.377Z" }, { "id": 1, "text": "Developer runs 'fspec research --tool=perplexity --query=\"How does OAuth2 work?\"', perplexity script executes and returns formatted results", "deleted": false, "createdAt": "2025-11-08T01:49:29.881Z" }, { "id": 2, "text": "Developer runs 'fspec research --tool=jira --issue AUTH-123', jira script fetches issue details", "deleted": false, "createdAt": "2025-11-08T01:49:30.379Z" }, { "id": 3, "text": "After research completes, system prompts 'Attach results to work unit? (y/n)', user says yes, results saved to spec/attachments/AUTH-001/perplexity-oauth2-2025-11-08.md", "deleted": false, "createdAt": "2025-11-08T01:49:30.882Z" }, { "id": 4, "text": "Developer runs 'fspec research --tool=confluence --page \"Authentication Guide\"', confluence script fetches page content", "deleted": false, "createdAt": "2025-11-08T01:49:38.994Z" }, { "id": 5, "text": "Developer runs 'fspec research --tool=invalid', command returns error 'Error: Research tool not found: invalid'", "deleted": false, "createdAt": "2025-11-08T01:49:39.501Z" }, { "id": 6, "text": "Developer adds new research script spec/research-scripts/github with executable permissions, runs 'fspec research', sees github in available tools list", "deleted": false, "createdAt": "2025-11-08T01:49:40.017Z" }, { "id": 7, "text": "During Example Mapping, developer answers no to attachment prompt, research results displayed but not saved", "deleted": false, "createdAt": "2025-11-08T01:49:40.521Z" } ], "estimate": 5, "questions": [], "architectureNotes": [], "updated": "2025-11-08T02:10:56.865Z" }, "BUG-024": { "id": "BUG-024", "title": "Fix dependencies command error with work unit ID argument", "type": "story", "status": "done", "createdAt": "2025-10-21T07:33:29.645Z", "updatedAt": "2025-10-21T07:50:38.438Z", "description": "The 'fspec dependencies <id>' command throws 'Invalid action: <id>' error instead of showing dependency tree. Error occurs at dist/index.js:8359. Command should accept work unit ID as argument and display dependency relationships (dependsOn, blocks, blockedBy, relatesTo).", "children": [], "attachments": [ "spec/attachments/BUG-024/bug-024-error-details.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T07:35:58.546Z" }, { "state": "testing", "timestamp": "2025-10-21T07:38:45.398Z" }, { "state": "implementing", "timestamp": "2025-10-21T07:49:54.638Z" }, { "state": "validating", "timestamp": "2025-10-21T07:50:09.592Z" }, { "state": "done", "timestamp": "2025-10-21T07:50:38.438Z" } ], "rules": [ { "id": 0, "text": "Legacy dependencies() function must be removed to prevent CLI routing conflicts", "deleted": false, "createdAt": "2025-10-21T07:33:29.645Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec dependencies RES-001' and receives dependency list instead of 'Invalid action' error", "deleted": false, "createdAt": "2025-10-21T07:33:29.645Z" }, { "id": 1, "text": "Command shows 'Dependencies for RES-001:' followed by relationship lists (blocks, blockedBy, dependsOn, relatesTo)", "deleted": false, "createdAt": "2025-10-21T07:33:29.645Z" } ], "architectureNotes": [ { "id": 0, "text": "Root Cause: Legacy dependencies() function (line 1017-1072 in src/commands/dependencies.ts) is still exported and callable. This function expects (action, workUnitId, options) but CLI passes (workUnitId, options) directly to it. Solution: Remove the legacy function since registerDependenciesCommand() now uses showDependencies() instead.", "deleted": false, "createdAt": "2025-10-21T07:33:29.645Z" } ], "userStory": { "role": "AI agent using fspec for project management", "action": "view work unit dependencies using 'fspec dependencies <id>'", "benefit": "I can understand dependency relationships and plan work order" }, "nextRuleId": 1, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 1 }, "INIT-005": { "id": "INIT-005", "title": "Fix multi-agent support critical issues", "type": "story", "status": "done", "createdAt": "2025-10-21T10:50:08.007Z", "updatedAt": "2025-10-21T11:03:45.953Z", "description": "Address 25 bugs and anti-patterns discovered during INIT-004 implementation code review. Includes 3 critical issues (destructive file deletion, path traversal vulnerability, duplicate agent directories), 4 high priority, 6 medium, and 12 low priority issues.", "children": [], "attachments": [ "spec/attachments/INIT-005/post-implementation-issues.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T10:51:51.424Z" }, { "state": "testing", "timestamp": "2025-10-21T10:55:38.963Z" }, { "state": "implementing", "timestamp": "2025-10-21T10:58:21.113Z" }, { "state": "validating", "timestamp": "2025-10-21T11:03:12.454Z" }, { "state": "done", "timestamp": "2025-10-21T11:03:45.953Z" } ], "userStory": { "role": "developer using fspec with multiple AI agents", "action": "have critical bugs and anti-patterns from INIT-004 implementation fixed", "benefit": "multi-agent support is production-ready, secure, and follows best practices" }, "rules": [ { "id": 0, "text": "Agent switching must ONLY delete fspec-specific files (AGENT.md, spec/AGENT.md, .agent/commands/fspec.md), never entire directories or user's custom files", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 1, "text": "Agent registry slashCommandPath must be validated to prevent path traversal attacks (no ../, no absolute paths, must be relative to project root)", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 2, "text": "Each agent must have unique slashCommandPath and rootStubFile to avoid conflicts (e.g., codex and codex-cli cannot both use .codex/commands/)", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 3, "text": "System-reminder regex transformation must handle nested tags, multiline content, and edge cases without breaking content", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 4, "text": "Meta-cognitive prompt removal must use word boundaries to avoid corrupting valid words containing 'think' (e.g., 'rethink', 'thinking')", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 5, "text": "Invalid agent ID errors must include list of valid agent IDs to help users discover available options", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" } ], "examples": [ { "id": 0, "text": "Critical: User runs 'fspec init --agent=cursor' after 'fspec init --agent=claude', system deletes .claude/commands/fspec.md only (not entire .claude/commands/ directory with user's custom commands)", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 1, "text": "Critical: Agent registry contains malicious slashCommandPath '../../../etc/passwd', validation rejects it before creating files", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 2, "text": "Critical: codex and codex-cli agents both try to use .codex/commands/, installation detects conflict and shows clear error message", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 3, "text": "High: Template contains nested system-reminders, transformation correctly handles both levels without breaking content structure", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 4, "text": "High: Template contains 'rethinking' and 'thinking', meta-cognitive removal only strips 'ultrathink' and 'deeply consider', preserves valid words", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" }, { "id": 5, "text": "High: User runs 'fspec init --agent=invalid-agent', error message lists all 18 valid agent IDs with descriptions", "deleted": false, "createdAt": "2025-10-21T10:50:08.007Z" } ], "estimate": 5, "nextRuleId": 6, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "INIT-006": { "id": "INIT-006", "title": "Wire up multi-agent support to fspec init command", "type": "story", "status": "done", "createdAt": "2025-10-21T11:10:11.887Z", "updatedAt": "2025-10-21T13:14:07.492Z", "description": "Update registerInitCommand to use new multi-agent system (installAgents, agent registry, interactive selector). Deprecate and remove old single-agent code (init function, generateTemplate, copyClaudeTemplate). The new infrastructure exists but isn't being called - fspec init still defaults to Claude-only installation.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T11:10:26.993Z" }, { "state": "testing", "timestamp": "2025-10-21T11:13:42.750Z" }, { "state": "implementing", "timestamp": "2025-10-21T11:14:27.089Z" }, { "state": "validating", "timestamp": "2025-10-21T11:17:31.868Z" }, { "state": "done", "timestamp": "2025-10-21T11:39:48.433Z" }, { "state": "implementing", "timestamp": "2025-10-21T11:49:45.027Z" }, { "state": "specifying", "timestamp": "2025-10-21T11:50:30.315Z" }, { "state": "specifying", "timestamp": "2025-10-21T12:01:28.869Z" }, { "state": "testing", "timestamp": "2025-10-21T12:04:45.819Z" }, { "state": "implementing", "timestamp": "2025-10-21T12:05:34.971Z" }, { "state": "validating", "timestamp": "2025-10-21T12:07:20.322Z" }, { "state": "done", "timestamp": "2025-10-21T12:13:16.564Z" }, { "state": "specifying", "timestamp": "2025-10-21T12:16:35.634Z" }, { "state": "testing", "timestamp": "2025-10-21T12:19:06.529Z" }, { "state": "implementing", "timestamp": "2025-10-21T12:21:12.211Z" }, { "state": "validating", "timestamp": "2025-10-21T12:31:51.329Z" }, { "state": "done", "timestamp": "2025-10-21T12:34:59.166Z" }, { "state": "implementing", "timestamp": "2025-10-21T12:36:46.905Z" }, { "state": "validating", "timestamp": "2025-10-21T12:45:27.354Z" }, { "state": "done", "timestamp": "2025-10-21T12:45:47.085Z" }, { "state": "specifying", "timestamp": "2025-10-21T12:47:53.774Z" }, { "state": "testing", "timestamp": "2025-10-21T12:49:29.009Z" }, { "state": "implementing", "timestamp": "2025-10-21T12:49:35.452Z" }, { "state": "validating", "timestamp": "2025-10-21T12:52:10.515Z" }, { "state": "done", "timestamp": "2025-10-21T12:52:18.545Z" }, { "state": "specifying", "timestamp": "2025-10-21T13:09:33.571Z" }, { "state": "testing", "timestamp": "2025-10-21T13:10:54.118Z" }, { "state": "implementing", "timestamp": "2025-10-21T13:12:16.851Z" }, { "state": "validating", "timestamp": "2025-10-21T13:12:24.992Z" }, { "state": "done", "timestamp": "2025-10-21T13:14:07.492Z" } ], "rules": [ { "id": 0, "text": "registerInitCommand must call installAgents() with interactive selector when no --agent flag provided", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 1, "text": "Old init() function, generateTemplate(), and copyClaudeTemplate() must be removed after migration", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 2, "text": "Command must accept --agent flag (can be repeated) for non-interactive mode", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 3, "text": "Interactive selector must use agent auto-detection to pre-select detected agents", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 4, "text": "fspec init must work after global npm install without requiring local files", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 5, "text": "Generated files must be customized for each agent (agent-specific names, paths, features)", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 6, "text": "Interactive selector uses single-select navigation (arrow keys + ENTER), NOT checkboxes", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 7, "text": "Cursor highlights currently selected agent, ENTER key immediately installs that agent", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 8, "text": "NO multi-select - user can only select ONE agent at a time in interactive mode", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec init' with no flags, sees interactive agent selector with auto-detected agents pre-selected", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 1, "text": "User runs 'fspec init --agent=cursor', skips interactive selector and installs Cursor directly", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 2, "text": "After migration, old init(), generateTemplate(), copyClaudeTemplate() functions are deleted from init.ts", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 3, "text": "User installs fspec globally with 'npm install -g fspec', then runs 'fspec init' in new project - command works without errors", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 4, "text": "After running 'fspec init --agent=cursor', generated files contain 'Cursor' not 'Claude Code' in agent names", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 5, "text": "After completing migration, old code paths (reading from project's .claude/commands/fspec.md) are completely removed", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 6, "text": "User runs 'fspec init', sees list with cursor on first agent, presses down arrow twice to move cursor to Cline, presses ENTER, Cline is selected and installation starts", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" }, { "id": 7, "text": "User runs 'fspec init' in a directory with .claude/ folder, cursor starts on Claude Code (auto-detected), user presses ENTER, Claude Code is installed", "deleted": false, "createdAt": "2025-10-21T11:10:11.887Z" } ], "userStory": { "role": "developer using any AI coding agent", "action": "run 'fspec init' and get an interactive agent selector", "benefit": "I can choose my agent and get proper setup without needing to know the --agent flag syntax" }, "estimate": 3, "nextRuleId": 9, "nextExampleId": 8, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-025": { "id": "BUG-025", "title": "Intermittent test failure: command-help-system main help test", "type": "bug", "status": "done", "createdAt": "2025-10-21T11:38:00.009Z", "updatedAt": "2025-10-22T01:46:07.007Z", "description": "The test 'Feature: Command Help System > Scenario: Main help mentions individual command help availability' fails intermittently in the full test suite with exit code 1, but passes when run individually. This suggests a test isolation or timing issue. The test has been temporarily skipped in src/commands/__tests__/command-help-system.test.ts:198.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T01:38:08.404Z" }, { "state": "testing", "timestamp": "2025-10-22T01:42:10.310Z" }, { "state": "implementing", "timestamp": "2025-10-22T01:42:20.544Z" }, { "state": "validating", "timestamp": "2025-10-22T01:45:20.920Z" }, { "state": "done", "timestamp": "2025-10-22T01:45:54.840Z" } ], "rules": [ { "id": 0, "text": "Tests must not rebuild dist/index.js during execution as it causes race conditions", "deleted": false, "createdAt": "2025-10-21T11:38:00.009Z" } ], "examples": [ { "id": 0, "text": "version-display.test.ts runs 'npm run build' while command-help-system.test.ts executes node dist/index.js --help, causing exit code 1 or undefined", "deleted": false, "createdAt": "2025-10-21T11:38:00.009Z" }, { "id": 1, "text": "Test passes when run in isolation but fails when run with full suite due to dist/index.js being rebuilt by version-display.test.ts", "deleted": false, "createdAt": "2025-10-21T11:38:00.009Z" } ], "architectureNotes": [ { "id": 0, "text": "Root cause: version-display.test.ts rebuilds dist/index.js during test execution, causing race condition with command-help-system.test.ts", "deleted": false, "createdAt": "2025-10-21T11:38:00.009Z" }, { "id": 1, "text": "Solution: Mark version-display.test.ts with test.sequential() to prevent parallel execution with other CLI tests", "deleted": false, "createdAt": "2025-10-21T11:38:00.009Z" } ], "userStory": { "role": "developer running fspec test suite", "action": "run all tests concurrently without race conditions", "benefit": "tests are reliable and pass consistently" }, "estimate": 2, "nextRuleId": 1, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 2 }, "BUG-026": { "id": "BUG-026", "title": "Flaky tests: command-help-system and foundation-existence-check fail in full suite but pass individually", "type": "bug", "status": "done", "createdAt": "2025-10-21T13:01:16.689Z", "updatedAt": "2025-10-22T01:54:20.584Z", "description": "Two test files pass when run individually but fail in full suite - indicates test isolation issues.\n\nCOMMAND HELP TEST:\n- File: src/commands/__tests__/command-help-system.test.ts:223\n- Scenario: Display help for Example Mapping command with patterns\n- Expected: exitCode 0, Actual: exitCode 1 (full suite) | exitCode 0 (isolated)\n- Command: node dist/index.js add-question --help\n\nFOUNDATION EXISTENCE CHECK TEST:\n- File: src/commands/__tests__/foundation-existence-check.test.ts:172\n- Scenario: Run validate command without foundation.json (read-only exempt)\n- Expected: exitCode 0, Actual: exitCode undefined (full suite) | exitCode 0 (isolated)\n- Command: fspec validate (using execa)\n\nROOT CAUSE HYPOTHESIS:\n- Global state pollution from earlier tests\n- Async cleanup issues (tests completing out of order)\n- File system state not properly isolated\n- CLI process state leaking between tests\n\nNEXT STEPS:\n1. Add beforeEach/afterEach hooks for clean state\n2. Check for process.exit() calls affecting exit codes\n3. Investigate test execution order to find polluting tests\n4. Use vitest --sequence.shuffle to identify order dependencies", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T01:47:09.811Z" }, { "state": "testing", "timestamp": "2025-10-22T01:54:05.760Z" }, { "state": "implementing", "timestamp": "2025-10-22T01:54:07.340Z" }, { "state": "validating", "timestamp": "2025-10-22T01:54:09.258Z" }, { "state": "done", "timestamp": "2025-10-22T01:54:09.990Z" } ], "rules": [ { "id": 0, "text": "Tests that execute dist/index.js must not run in parallel with tests that rebuild it", "deleted": false, "createdAt": "2025-10-21T13:01:16.689Z" } ], "examples": [ { "id": 0, "text": "command-help-system.test.ts executes 'node dist/index.js add-question --help' and gets exit code 1 when version-display.test.ts rebuilds dist/index.js in parallel", "deleted": false, "createdAt": "2025-10-21T13:01:16.689Z" }, { "id": 1, "text": "foundation-existence-check.test.ts executes 'fspec validate' and gets exit code undefined when version-display.test.ts rebuilds dist/index.js in parallel", "deleted": false, "createdAt": "2025-10-21T13:01:16.689Z" }, { "id": 2, "text": "After fixing BUG-025 (marking version-display.test.ts as sequential), both tests pass consistently in full suite", "deleted": false, "createdAt": "2025-10-21T13:01:16.689Z" } ], "architectureNotes": [ { "id": 0, "text": "Root cause: Same as BUG-025 - version-display.test.ts rebuilding dist/index.js created race conditions with ALL CLI tests", "deleted": false, "createdAt": "2025-10-21T13:01:16.689Z" }, { "id": 1, "text": "Solution: Fixed by BUG-025 solution - marking version-display.test.ts with describe.sequential() prevents parallel execution", "deleted": false, "createdAt": "2025-10-21T13:01:16.689Z" }, { "id": 2, "text": "Impact: Both command-help-system.test.ts:223 and foundation-existence-check.test.ts:172 now pass consistently in full suite (verified across multiple runs)", "deleted": false, "createdAt": "2025-10-21T13:01:16.689Z" } ], "userStory": { "role": "developer running full test suite", "action": "have all CLI tests pass reliably", "benefit": "I can trust test results without intermittent failures" }, "estimate": 1, "nextRuleId": 1, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 3 }, "INIT-008": { "id": "INIT-008", "title": "Agent runtime detection for context-aware CLI output", "type": "story", "status": "done", "createdAt": "2025-10-21T13:28:51.970Z", "updatedAt": "2025-10-22T08:46:47.154Z", "description": "WHAT ALREADY EXISTS:\n1. Template generation time transformations (during 'fspec init'):\n - removeMetaCognitivePrompts() strips 'ultrathink', 'deeply consider' for CLI agents\n - stripSystemReminders() transforms <system-reminder> tags to bold text for non-Claude\n - Agent registry has supportsMetaCognition and supportsSystemReminders flags\n - This works great for generated files (AGENT.md, slash commands)\n\n2. Environment variable:\n - FSPEC_DISABLE_REMINDERS=1 disables system-reminders entirely\n\nWHAT'S MISSING (THE ACTUAL PROBLEM):\n1. Runtime detection: fspec commands don't know which agent is running them\n - 'fspec validate' emits <system-reminder> for ALL agents (only Claude understands)\n - 'fspec update-work-unit-status' uses system-reminders regardless of agent\n - Error messages don't adapt (all use <system-reminder> tags)\n - Help commands don't tailor output based on agent\n\n2. CLI output adaptation:\n - Commands should emit <system-reminder> for Claude Code\n - Commands should emit **⚠️ IMPORTANT:** for Cursor/Cline/IDE agents \n - Commands should emit **IMPORTANT:** for CLI-only agents (Aider, Gemini)\n - Currently everything uses <system-reminder> by default\n\n3. No detection mechanism:\n - Can't tell if it's Claude vs Cursor vs Aider running the command\n - No FSPEC_AGENT environment variable\n - No config file (~/.fspec/config.json)\n - No auto-detection from project files (.claude/, .cursor/)\n\nDetection strategies to implement:\n1. Environment variable: FSPEC_AGENT=claude (highest priority)\n2. Config file: ~/.fspec/config.json with {\"defaultAgent\": \"claude\"}\n3. Auto-detect from project: Check for .claude/, .cursor/, etc. in cwd\n4. Fallback: Safe default (plain text, no system-reminders)\n\nAcceptance Criteria:\n- Runtime agent detection using priority chain (env > config > auto-detect > default)\n- All CLI commands adapt output based on detected agent\n- System-reminders only emitted for Claude Code at runtime\n- Other agents get transformed output (bold text + emoji or plain)\n- Detection works across all 18 supported agents\n- Fallback to safe defaults if detection fails\n- Documentation for FSPEC_AGENT env var and ~/.fspec/config.json", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T08:28:46.801Z" }, { "state": "testing", "timestamp": "2025-10-22T08:41:15.717Z" }, { "state": "implementing", "timestamp": "2025-10-22T08:44:03.360Z" }, { "state": "validating", "timestamp": "2025-10-22T08:45:18.471Z" }, { "state": "done", "timestamp": "2025-10-22T08:46:47.154Z" } ], "rules": [ { "id": 0, "text": "Detection must use priority chain: FSPEC_AGENT env var > config file > auto-detect from project files > safe default", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 1, "text": "System-reminders only emitted for Claude Code at runtime", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 2, "text": "Cursor/Cline/IDE agents receive **⚠️ IMPORTANT:** with bold text and emoji", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 3, "text": "CLI-only agents (Aider, Gemini) receive **IMPORTANT:** plain text without emoji", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 4, "text": "Must support all 18 agents defined in existing agent registry", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 5, "text": "Must fallback to safe default (plain text, no system-reminders) if detection fails", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 6, "text": "Per-project config file at spec/fspec-config.json (consistent with other fspec config files like spec/fspec-hooks.json)", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 7, "text": "No runtime auto-detection needed. Agent is detected during 'fspec init' (using existing detection logic) and written to spec/fspec-config.json. All subsequent commands read from config file.", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 8, "text": "Agent registry already exists with all needed metadata. 'fspec init' detects agent and writes to config. Runtime commands read config to determine output format (system-reminder for Claude, bold+emoji for IDE agents, plain for CLI agents).", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" } ], "examples": [ { "id": 0, "text": "User sets FSPEC_AGENT=claude, runs 'fspec validate', output contains <system-reminder> tags", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 1, "text": "Cursor user (no env var) runs 'fspec validate' in project with .cursor/ directory, output contains **⚠️ IMPORTANT:** with emoji", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 2, "text": "Aider user runs 'fspec validate' with no env var or config, auto-detects CLI-only agent, output contains **IMPORTANT:** plain text", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 3, "text": "User has ~/.fspec/config.json with defaultAgent=cursor but FSPEC_AGENT=claude is set, Claude is used (env var takes priority)", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 4, "text": "Unknown environment with no detection clues, system falls back to safe default (plain text output, no system-reminders)", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" } ], "questions": [ { "id": 0, "text": "@human: Should config file be global (~/.fspec/config.json) or per-project (.fspec/config.json) or both with priority?", "selected": true, "answer": "Per-project config file at spec/fspec-config.json (consistent with other fspec config files like spec/fspec-hooks.json)", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 1, "text": "@human: What are the exact directory/file patterns for auto-detection (e.g., .claude/, .cursor/, .aider/config)?", "selected": true, "answer": "No runtime auto-detection needed. Agent is detected during 'fspec init' (using existing detection logic) and written to spec/fspec-config.json. All subsequent commands read from config file.", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" }, { "id": 2, "text": "@human: Should the agent registry be extended with output format preferences (system-reminder vs bold vs plain)?", "selected": true, "answer": "Agent registry already exists with all needed metadata. 'fspec init' detects agent and writes to config. Runtime commands read config to determine output format (system-reminder for Claude, bold+emoji for IDE agents, plain for CLI agents).", "deleted": false, "createdAt": "2025-10-21T13:28:51.970Z" } ], "userStory": { "role": "AI agent (Claude Code, Cursor, Aider, etc.) running fspec commands", "action": "have CLI output adapted to my capabilities (system-reminders, bold text, plain text)", "benefit": "I can understand and act on fspec guidance effectively without confusion or unsupported syntax" }, "estimate": 5, "nextRuleId": 9, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 0 }, "TECH-002": { "id": "TECH-002", "title": "Audit AI agent files for .gitignore exclusions", "type": "task", "status": "done", "createdAt": "2025-10-21T13:50:11.071Z", "updatedAt": "2025-10-22T06:55:51.180Z", "description": "Review all supported AI agents/tools and identify which files should be excluded from version control via .gitignore. Agents to investigate: Claude Code, Cursor, Windsurf, Copilot, and any other AI coding assistants we support. Look for: 1) Agent-specific configuration files, 2) Temporary files, 3) Cache directories, 4) Session state files, 5) Any generated files that shouldn't be committed. Create comprehensive .gitignore entries to prevent these files from being tracked.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T06:52:28.874Z" }, { "state": "implementing", "timestamp": "2025-10-22T06:52:35.525Z" }, { "state": "validating", "timestamp": "2025-10-22T06:55:49.589Z" }, { "state": "done", "timestamp": "2025-10-22T06:55:51.180Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-027": { "id": "BUG-027", "title": "Stash system not adding files before creating stash", "type": "bug", "status": "done", "createdAt": "2025-10-21T13:51:56.223Z", "updatedAt": "2025-10-22T01:07:49.222Z", "description": "The stash/restore checkpoint system appears to not be stashing any files. Investigation suggests that files are not being added to git before creating the stash, resulting in empty stashes. Need to verify: 1) Are files being staged with 'git add' before 'git stash'? 2) Are untracked files being included? 3) Are there any error messages being suppressed? 4) Test with actual file modifications to confirm stash behavior.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T00:27:04.797Z" }, { "state": "testing", "timestamp": "2025-10-22T00:52:31.871Z" }, { "state": "implementing", "timestamp": "2025-10-22T00:54:13.903Z" }, { "state": "validating", "timestamp": "2025-10-22T01:07:08.885Z" }, { "state": "done", "timestamp": "2025-10-22T01:07:49.222Z" } ], "questions": [ { "id": 0, "text": "@human: What is the stash system currently doing wrong? When I create a checkpoint, what files should be saved and what actually gets saved?", "selected": true, "answer": "The stash system is using isomorphic-git which doesn't support git stash. It tries to simulate stashing with git.commit() but never stages files first with git.add(), resulting in empty commits that capture nothing. Files should be stashed using real 'git stash push -u -m message' command via execa (which the project already uses elsewhere).", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 1, "text": "@human: Should the checkpoint system stash both tracked modified files AND untracked new files? Or only tracked files?", "selected": true, "answer": "Yes, both tracked modified files AND untracked new files should be included using 'git stash push -u' where -u flag includes untracked files while respecting .gitignore. This matches the feature specification line 11.", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 2, "text": "@human: Should we update the feature specification (intelligent-checkpoint-system-for-workflow-transitions.feature line 11) to document that files must be staged before stashing, not using native git -u flag?", "selected": true, "answer": "Yes, update the feature spec to document that isomorphic-git requires staging untracked files with git.add() before git.stash({ op: 'create' }) can capture them. This is a limitation of isomorphic-git, not native git.", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 3, "text": "@human: For checkpoint restoration, should we attempt to detect and handle merge conflicts (if user modified files since checkpoint), or simply overwrite with checkpoint contents?", "selected": true, "answer": "Detect and handle conflicts. Compare file contents byte-by-byte. If conflicts detected, emit system-reminder with conflicted files and recommend creating new checkpoint first. Do NOT overwrite without user awareness.", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 4, "text": "@human: Should checkpoint restoration preserve file permissions and timestamps, or just content?", "selected": true, "answer": "Just content. File permissions and timestamps are not critical for checkpoint use case (experimentation and rollback). Focus on content restoration only.", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" } ], "rules": [ { "id": 0, "text": "isomorphic-git HAS native git.stash() API with 'create' operation that creates stash commit without modifying working directory or refs", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 1, "text": "isomorphic-git stash only handles TRACKED files - untracked files must be staged with git.add() BEFORE creating checkpoint for them to be captured", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 2, "text": "Must reset index after checkpoint creation to avoid polluting user's staging area", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 3, "text": "Store checkpoint refs in custom namespace (refs/fspec-checkpoints/{work-unit-id}/{checkpoint-name}) for organization and easy listing", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 4, "text": "Checkpoints must capture both modified tracked files AND new untracked files (respecting .gitignore)", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 5, "text": "Restoration reads checkpoint from custom ref (refs/fspec-checkpoints/{work-unit-id}/{checkpoint-name}) then manually restores files using git.readBlob() and fs.writeFile()", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 6, "text": "Conflict detection compares working directory file contents vs checkpoint file contents byte-by-byte - if different, file is marked as conflicted", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 7, "text": "If conflicts detected, emit system-reminder with conflicted files list and recommended actions (create new checkpoint first) - do NOT modify any files", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 8, "text": "Files in checkpoint but not in working directory are restored (recreated) - files in working directory but not in checkpoint are ignored (left untouched)", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 9, "text": "Cannot use git.stash({ op: 'apply' }) because our custom ref namespace (refs/fspec-checkpoints) is incompatible with isomorphic-git's reflog-based stash access", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 10, "text": "Detect and handle conflicts. Compare file contents byte-by-byte. If conflicts detected, emit system-reminder with conflicted files and recommend creating new checkpoint first. Do NOT overwrite without user awareness.", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" } ], "examples": [ { "id": 0, "text": "Current bug: git.commit() called without git.add(), creates empty commit that captures nothing", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 1, "text": "User modifies tracked file README.md, runs checkpoint, file is staged then stashed with git.stash({ op: 'create' }), working directory unchanged", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 2, "text": "User creates new untracked file auth.test.ts, runs checkpoint, file is staged with git.add() then captured by stash, working directory unchanged", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 3, "text": "User modifies README.md and creates new.ts, runs checkpoint, both files staged and captured, index reset afterward, working directory unchanged", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 4, "text": "User restores checkpoint, files from stash commit are read and written back to working directory, all files (tracked + previously-staged untracked) restored", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 5, "text": "User creates checkpoint 'baseline', modifies files more, runs restore, all files read from checkpoint commit using git.readBlob() and written to working directory", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 6, "text": "User creates checkpoint with file A (v1), modifies file A to v2, runs restore, conflict detected (contents differ), system-reminder emitted, file A NOT overwritten (stays v2)", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 7, "text": "User creates checkpoint with file A, deletes file A from working directory, runs restore, file A is recreated from checkpoint (no conflict)", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 8, "text": "User creates checkpoint, adds new file B (not in checkpoint), runs restore, file B is left untouched (ignored), only checkpoint files restored", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" }, { "id": 9, "text": "User tries to restore non-existent checkpoint name, git.resolveRef() throws error, restoration returns success=false with 'checkpoint not found' message", "deleted": false, "createdAt": "2025-10-21T13:51:56.223Z" } ], "attachments": [ "spec/attachments/BUG-027/checkpoint-implementation-strategy.md", "spec/attachments/BUG-027/checkpoint-restoration-strategy.md" ], "assumptions": [ "Yes, update the feature spec to document that isomorphic-git requires staging untracked files with git.add() before git.stash({ op: 'create' }) can capture them. This is a limitation of isomorphic-git, not native git.", "Just content. File permissions and timestamps are not critical for checkpoint use case (experimentation and rollback). Focus on content restoration only." ], "userStory": { "role": "developer using fspec checkpoints", "action": "create and restore checkpoints that actually capture all file changes", "benefit": "I can safely experiment and rollback without losing work" }, "estimate": 5, "nextRuleId": 11, "nextExampleId": 10, "nextQuestionId": 5, "nextNoteId": 0 }, "CLI-007": { "id": "CLI-007", "title": "Replace generic create-work-unit with type-specific commands", "type": "story", "status": "done", "createdAt": "2025-10-21T13:51:58.078Z", "updatedAt": "2025-10-25T07:29:27.515Z", "description": "Remove create-work-unit command entirely. Add 3 type-specific commands: create-story, create-bug, create-task. Each command emits intelligent system-reminders that guide AI agents to the appropriate discovery workflow: stories use Example Mapping, bugs use research commands (search-scenarios, search-implementation, show-coverage), tasks have minimal requirements. Breaking change (v2.0).", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-25T06:10:08.668Z" }, { "state": "testing", "timestamp": "2025-10-25T06:48:17.495Z" }, { "state": "implementing", "timestamp": "2025-10-25T07:00:50.409Z" }, { "state": "specifying", "timestamp": "2025-10-25T07:03:27.023Z" }, { "state": "testing", "timestamp": "2025-10-25T07:15:24.663Z" }, { "state": "implementing", "timestamp": "2025-10-25T07:21:44.896Z" }, { "state": "validating", "timestamp": "2025-10-25T07:26:45.712Z" }, { "state": "done", "timestamp": "2025-10-25T07:29:27.515Z" } ], "userStory": { "role": "AI agent using fspec", "action": "create work units with appropriate guidance for each type", "benefit": "I follow the correct discovery workflow for stories, bugs, and tasks" }, "rules": [ { "id": 0, "text": "The generic create-work-unit command must be completely removed (breaking change)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 1, "text": "Each command must emit a type-specific system-reminder after creation guiding AI to the appropriate workflow", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 2, "text": "create-bug must guide AI to research commands: search-scenarios, search-implementation, show-coverage", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 3, "text": "create-story must guide AI to Example Mapping commands: add-rule, add-example, add-question, set-user-story", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 4, "text": "create-task must indicate minimal requirements (optional feature file, optional tests)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 5, "text": "The generic create-work-unit command must be completely removed (breaking change)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 6, "text": "Each command must emit type-specific system-reminder after creation guiding AI to appropriate workflow", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 7, "text": "create-story must guide AI to Example Mapping commands (add-rule, add-example, add-question, set-user-story)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 8, "text": "create-bug must guide AI to research commands (search-scenarios, search-implementation, show-coverage)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 9, "text": "create-task must indicate minimal requirements (optional feature file, optional tests)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 10, "text": "The group help in src/help.ts must be updated to reference create-story/bug/task instead of create-work-unit", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 11, "text": "All command help files in src/commands/*-help.ts must be updated to remove create-work-unit references and add new command help files", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 12, "text": "README.md must be updated to replace all create-work-unit examples with type-specific command examples", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 13, "text": "spec/CLAUDE.md (auto-generated) must be regenerated to reflect new commands in all workflow examples", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 14, "text": "All documentation files in docs/ directory must be searched and updated to replace create-work-unit with type-specific commands", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 15, "text": "All system-reminders in source code must be found and updated to reference new commands (search for 'create-work-unit' in all .ts files)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 16, "text": "All test files must be updated to test new commands and verify old command is removed", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 17, "text": "Commander.js registration in main CLI file must remove create-work-unit and register 3 new commands", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 18, "text": "Complete example commands (Option A) - more helpful for AI agents because they provide concrete patterns, reduce cognitive load, and enable immediate action", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 19, "text": "All options supported (Option A) - create-story/bug/task all support --epic, --description, --parent for consistency and because all types can legitimately have hierarchical relationships", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 20, "text": "ALL mentions of 'work unit' terminology must be replaced with type-specific terminology (stories, bugs, tasks) throughout the ENTIRE codebase", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 21, "text": "File names containing 'work-unit' must be evaluated for renaming to 'work-item' or type-specific names", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 22, "text": "Hard breaking change (Option A) - v2.0.0 immediately removes create-work-unit and all work unit terminology. Clean break, no deprecation period.", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 23, "text": "Variables named 'workUnit' must be renamed to contextually appropriate names (story, bug, task, or workUnit for generic cases)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 24, "text": "User-facing text saying 'work unit' must be replaced with 'story', 'bug', 'task', or collective term like 'work units'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec create-story AUTH \"User login\"' and sees system-reminder: 'Next steps - Example Mapping: 1. fspec add-rule AUTH-001 ..., 2. fspec add-example AUTH-001 ...'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 1, "text": "AI runs 'fspec create-bug BUG \"Login validation broken\"' and sees system-reminder: 'CRITICAL: Research existing code FIRST: 1. fspec search-scenarios --query=\"login\", 2. fspec search-implementation --function=\"validateLogin\"'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 2, "text": "AI runs 'fspec create-task TASK \"Setup CI/CD pipeline\"' and sees system-reminder: 'Task created. Tasks can skip feature files and tests for operational work.'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 3, "text": "AI runs 'fspec create-story AUTH \"User login\"' and sees system-reminder: 'Next steps - Example Mapping: 1. fspec add-rule AUTH-001 ..., 2. fspec add-example AUTH-001 ...'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 4, "text": "AI runs 'fspec create-bug BUG \"Login validation broken\"' and sees system-reminder: 'CRITICAL: Research existing code FIRST: 1. fspec search-scenarios --query=\"login\", 2. fspec search-implementation --function=\"validateLogin\"'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 5, "text": "AI runs 'fspec create-task TASK \"Setup CI/CD pipeline\"' and sees system-reminder: 'Task created. Tasks can skip feature files and tests for operational work.'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 6, "text": "In src/help.ts, replace 'fspec create-work-unit PREFIX \"Title\"' with 'fspec create-story PREFIX \"Title\"' in work management help", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 7, "text": "Delete src/commands/create-work-unit-help.ts completely (breaking change)", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 8, "text": "In README.md Quick Start section, replace 'fspec create-work-unit AUTH \"Login\"' with 'fspec create-story AUTH \"Login\"'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 9, "text": "Search all .ts files for 'create-work-unit' string and update to appropriate type-specific command based on context", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 10, "text": "In spec/CLAUDE.md examples, replace all 'fspec create-work-unit' occurrences with context-appropriate create-story/bug/task", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 11, "text": "Grep for system-reminder tags containing 'create-work-unit' and update each to reference new commands with type guidance", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 12, "text": "Replace 'Work unit CLI-007' with 'Story CLI-007' in show-work-unit output", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 13, "text": "Rename function updateWorkUnitStatus() to updateWorkUnitStatus() for generic cases, or updateStoryStatus() for type-specific", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 14, "text": "In docs, change 'work unit management' to 'work unit management' or 'managing stories, bugs, and tasks'", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" } ], "questions": [ { "id": 0, "text": "@human: Should the system-reminders include complete example commands or just command templates?", "selected": true, "answer": "Complete example commands (Option A) - more helpful for AI agents because they provide concrete patterns, reduce cognitive load, and enable immediate action", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 1, "text": "@human: Should create-story/bug/refactor/task support all the same options as create-work-unit (--epic, --description, --parent)?", "selected": true, "answer": "All options supported (Option A) - create-story/bug/refactor/task all support --epic, --description, --parent for consistency and because all types can legitimately have hierarchical relationships", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 2, "text": "@human: When AI tries to use the old create-work-unit command, should it show a migration guide in the error message?", "selected": true, "answer": "No migration guide (Option B) - Command should simply not exist. AI will adapt by using available commands.", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" }, { "id": 3, "text": "@human: Should there be a deprecation period with warnings, or is this a hard breaking change (v2.0) that immediately removes create-work-unit?", "selected": true, "answer": "Hard breaking change (Option A) - v2.0.0 immediately removes create-work-unit and all work unit terminology. Clean break, no deprecation period.", "deleted": false, "createdAt": "2025-10-21T13:51:58.078Z" } ], "assumptions": [ "No migration guide (Option B) - Command should simply not exist. AI will adapt by using available commands." ], "estimate": 5, "nextRuleId": 25, "nextExampleId": 15, "nextQuestionId": 4, "nextNoteId": 0 }, "BUG-028": { "id": "BUG-028", "title": "spec/AGENT.md files contain stub instead of comprehensive workflow", "type": "story", "status": "done", "createdAt": "2025-10-21T21:09:20.138Z", "updatedAt": "2025-10-21T23:15:31.966Z", "description": "The spec/AGENT.md files (spec/CLAUDE.md, spec/CURSOR.md, etc.) currently contain only a 17-line stub that creates circular references. According to INIT-004 Rule 16, these files should contain the full ACDD workflow documentation (same 1019-line content as slash commands) with agent-specific transformations applied. Current implementation in templateGenerator.ts uses BASE_AGENT_TEMPLATE (17 lines) instead of getSlashCommandTemplate() content (1019 lines).", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-21T21:09:59.327Z" }, { "state": "testing", "timestamp": "2025-10-21T21:12:13.806Z" }, { "state": "implementing", "timestamp": "2025-10-21T21:13:36.561Z" }, { "state": "validating", "timestamp": "2025-10-21T21:15:04.083Z" }, { "state": "done", "timestamp": "2025-10-21T21:23:57.337Z" }, { "state": "specifying", "timestamp": "2025-10-21T21:44:02.148Z" }, { "state": "testing", "timestamp": "2025-10-21T22:28:44.231Z" }, { "state": "implementing", "timestamp": "2025-10-21T22:31:32.902Z" }, { "state": "validating", "timestamp": "2025-10-21T22:49:52.538Z" }, { "state": "done", "timestamp": "2025-10-21T23:15:31.966Z" } ], "rules": [ { "id": 0, "text": "spec/AGENT.md files must contain full Project Management Guidelines (2069 lines), not a 17-line stub", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 1, "text": "generateAgentDoc() must use getProjectManagementTemplate() as base content, not BASE_AGENT_TEMPLATE", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 2, "text": "Agent-specific transformations (stripSystemReminders, removeMetaCognitivePrompts, replacePlaceholders) must be applied to Project Management template", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 3, "text": "Create projectManagementTemplate.ts following same pattern as slashCommandTemplate.ts with section files", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 4, "text": "Keep BASE_AGENT_TEMPLATE only for root stub generation (CURSOR.md, AGENTS.md), use projectManagementTemplate for spec/AGENT.md", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 5, "text": "Slash command generation (generateSlashCommandContent) is ALREADY CORRECT and should not be changed", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" } ], "examples": [ { "id": 0, "text": "Current spec/CLAUDE.md has 17 lines with circular reference: 'For using fspec commands and ACDD workflow: See spec/CLAUDE.md'", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 1, "text": "Expected spec/CLAUDE.md should have ~2069 lines with full Project Management Guidelines including work unit management, ACDD workflow, coverage tracking, hooks, checkpoints", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 2, "text": "Restored spec/CLAUDE.md (from GitHub) has 2069 lines titled 'Project Management and Specification Guidelines for fspec' - this content should be templated", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 3, "text": "Slash command file .claude/commands/fspec.md has 1019 lines of ACDD workflow - this is DIFFERENT from spec/CLAUDE.md and should NOT be changed", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 4, "text": "projectManagementTemplate.ts should follow same pattern as slashCommandTemplate.ts with section imports (getIntroSection, getProjectManagementSection, etc.)", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" } ], "userStory": { "role": "AI agent (Cursor, Aider, etc.) reading spec/AGENT.md", "action": "read comprehensive ACDD workflow documentation", "benefit": "I understand the full fspec process without needing to read slash commands" }, "architectureNotes": [ { "id": 0, "text": "Create src/utils/projectManagementTemplate.ts following same pattern as slashCommandTemplate.ts", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 1, "text": "Break spec/CLAUDE.md (2069 lines) into section files in src/utils/projectManagementSections/ directory", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 2, "text": "Update generateAgentDoc() in src/utils/templateGenerator.ts to use getProjectManagementTemplate() instead of getSlashCommandTemplate()", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 3, "text": "generateSlashCommandContent() is ALREADY CORRECT - it uses getSlashCommandTemplate() for .claude/commands/fspec.md (1019 lines)", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" }, { "id": 4, "text": "After fix, spec/CLAUDE.md should have ~2069 lines (Project Management Guidelines), .claude/commands/fspec.md should remain ~1019 lines (ACDD workflow)", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" } ], "estimate": 2, "questions": [ { "id": 0, "text": "@human: Should spec/CLAUDE.md contain the 'Project Management Guidelines' (current 139 lines) or the 'ACDD workflow from slash command' (1019 lines)? What is the actual bug we're fixing?", "selected": true, "answer": "spec/CLAUDE.md should contain 'Project Management and Specification Guidelines' (2069 lines), NOT the ACDD workflow from slash command (1019 lines). My original implementation was WRONG - I copied the slash command template instead of using the Project Management Guidelines template.", "deleted": false, "createdAt": "2025-10-21T21:09:20.138Z" } ], "attachments": [ "spec/attachments/BUG-028/BUG-028-implementation-plan.md" ], "nextRuleId": 6, "nextExampleId": 5, "nextQuestionId": 1, "nextNoteId": 5 }, "BUG-029": { "id": "BUG-029", "title": "Fix failing tests after phase tag removal", "type": "bug", "status": "done", "createdAt": "2025-10-22T06:13:05.750Z", "updatedAt": "2025-10-22T06:47:21.878Z", "description": "14 tests are failing after removing phase tags from the codebase. Tests in feature-level-tag-management.test.ts, get-scenarios.test.ts, register-tag.test.ts, retag.test.ts, show-acceptance-criteria.test.ts, and hooks tests need to be updated to reflect that phase tags no longer exist and are not required.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T06:13:31.902Z" }, { "state": "testing", "timestamp": "2025-10-22T06:31:30.323Z" }, { "state": "implementing", "timestamp": "2025-10-22T06:31:44.751Z" }, { "state": "validating", "timestamp": "2025-10-22T06:44:27.847Z" }, { "state": "done", "timestamp": "2025-10-22T06:47:21.878Z" } ], "rules": [ { "id": 0, "text": "All test features must have both @component and @feature-group tags to pass validation", "deleted": false, "createdAt": "2025-10-22T06:13:05.750Z" }, { "id": 1, "text": "Test expectations for TAGS.md must not check for Usage column (removed)", "deleted": false, "createdAt": "2025-10-22T06:13:05.750Z" }, { "id": 2, "text": "Remove or update scenarios in feature files that test phase tag validation or usage metadata", "deleted": false, "createdAt": "2025-10-22T06:13:05.750Z" } ], "examples": [ { "id": 0, "text": "feature-level-tag-management.test.ts expects result.success=true but gets false because validation fails", "deleted": false, "createdAt": "2025-10-22T06:13:05.750Z" }, { "id": 1, "text": "generate-tags-md.test.ts and tags-md.test.ts check for Usage column in output but it no longer exists", "deleted": false, "createdAt": "2025-10-22T06:13:05.750Z" }, { "id": 2, "text": "get-scenarios.test.ts expects 1 scenario but gets 3 because test features now have more tags after adding required @component/@feature-group", "deleted": false, "createdAt": "2025-10-22T06:13:05.750Z" }, { "id": 3, "text": "retag.test.ts expects '@critical' in output but feature now has @cli @validation instead of @critical", "deleted": false, "createdAt": "2025-10-22T06:13:05.750Z" } ], "userStory": { "role": "developer maintaining test suite", "action": "fix failing tests after removing phase tags and usage metadata", "benefit": "all 1360 tests pass and the codebase is clean" }, "estimate": 3, "nextRuleId": 3, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-030": { "id": "BUG-030", "title": "Agent-specific activation message not customized in fspec init success output", "type": "story", "status": "done", "createdAt": "2025-10-22T08:19:08.142Z", "updatedAt": "2025-10-22T08:54:43.782Z", "description": "The 'Run /fspec in your AI agent to activate' message appears in 2 places in the fspec init command output. This message is generic and doesn't provide agent-specific instructions. For example, Claude Code users see this message, but Gemini users would also see the same message, which may not be applicable. The message should be customized based on the detected AI agent (Claude Code, Gemini, Cursor, etc.) to provide relevant activation instructions. Related to INIT-008 (agent runtime detection).", "children": [], "dependsOn": [ "INIT-008" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T08:49:32.630Z" }, { "state": "testing", "timestamp": "2025-10-22T08:51:50.634Z" }, { "state": "implementing", "timestamp": "2025-10-22T08:52:50.210Z" }, { "state": "validating", "timestamp": "2025-10-22T08:53:24.438Z" }, { "state": "done", "timestamp": "2025-10-22T08:54:43.782Z" } ], "rules": [ { "id": 0, "text": "Activation message must be customized based on detected agent (from INIT-008 implementation)", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 1, "text": "Message appears in 2 places in fspec init output and both must be updated", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 2, "text": "Claude Code users should see: 'Run /fspec in Claude Code to activate'", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 3, "text": "CLI agents (Aider, Gemini) should see agent-specific command format", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 4, "text": "IDE agents (Cursor, Cline) should see instructions relevant to their IDE integration", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 5, "text": "Default/unknown agents should see generic fallback message", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 6, "text": "Two places: (1) src/commands/init.ts:234 in CLI success message (2) src/components/AgentSelector.tsx:56 in UI component", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec init' with Claude Code detected, sees 'Run /fspec in Claude Code to activate' in 2 places in output", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 1, "text": "User runs 'fspec init' with Cursor detected, sees 'Open .cursor/commands/ in Cursor to activate' in output", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 2, "text": "User runs 'fspec init' with Aider detected, sees 'Add .aider/ to your Aider configuration to activate' in output", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" }, { "id": 3, "text": "User runs 'fspec init' with unknown agent, sees generic fallback: 'Refer to your AI agent documentation to activate fspec'", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" } ], "questions": [ { "id": 0, "text": "@human: Where exactly are the 2 places in the init command output where this message appears?", "selected": true, "answer": "Two places: (1) src/commands/init.ts:234 in CLI success message (2) src/components/AgentSelector.tsx:56 in UI component", "deleted": false, "createdAt": "2025-10-22T08:19:08.142Z" } ], "userStory": { "role": "developer running fspec init", "action": "see agent-specific activation instructions in the success message", "benefit": "I know exactly how to activate fspec in my specific AI agent" }, "estimate": 2, "nextRuleId": 7, "nextExampleId": 4, "nextQuestionId": 1, "nextNoteId": 0 }, "BUG-031": { "id": "BUG-031", "title": "No support for ULTRATHINK in discovery-driven feedback loop", "type": "story", "status": "done", "createdAt": "2025-10-22T08:19:09.971Z", "updatedAt": "2025-10-24T05:36:24.012Z", "description": "The discover-foundation command uses the term 'ULTRATHINK' in its guidance system-reminders to instruct AI agents to perform deep analysis. However, not all AI agents support extended thinking or use this terminology. Claude Code may understand 'ULTRATHINK', but Gemini, Cursor, and other agents do not. The discovery-driven feedback loop needs agent-specific language that adapts to the capabilities of the detected AI agent. For agents without extended thinking support, the term should be removed and replaced with standard instructions. This should integrate with INIT-008 (agent runtime detection) to provide appropriate guidance per agent.", "children": [], "dependsOn": [ "INIT-008" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T05:17:04.908Z" }, { "state": "testing", "timestamp": "2025-10-24T05:24:00.191Z" }, { "state": "implementing", "timestamp": "2025-10-24T05:25:56.326Z" }, { "state": "validating", "timestamp": "2025-10-24T05:31:49.250Z" }, { "state": "done", "timestamp": "2025-10-24T05:36:24.012Z" } ], "attachments": [ "spec/attachments/BUG-031/bug-031-investigation-findings.md" ], "userStory": { "role": "AI agent (non-Claude) using fspec discover-foundation", "action": "receive guidance in language my agent understands", "benefit": "I can successfully complete foundation discovery without confusion" }, "rules": [ { "id": 0, "text": "Claude Code is the only agent that supports 'ULTRATHINK' terminology (supportsMetaCognition flag)", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 1, "text": "Non-Claude agents must receive generic 'analyze' or 'examine' language instead of ULTRATHINK", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 2, "text": "Agent detection must use existing INIT-008 infrastructure (getAgentConfig from agentRuntimeConfig.ts)", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 3, "text": "Output format must match agent type: system-reminder for Claude, bold+emoji for IDE agents, plain bold for CLI agents", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 4, "text": "ULTRATHINK appears in exactly 2 locations: initial draft reminder and project.vision field guidance", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 5, "text": "Focus only on locations with ULTRATHINK (initial draft + project.vision). Other fields don't have Claude-specific language. Keep scope minimal for quick fix (Option 1).", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" } ], "examples": [ { "id": 0, "text": "Claude Code agent runs discover-foundation, sees 'ULTRATHINK: Read ALL code, understand deeply' in system-reminder", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 1, "text": "Cursor agent runs discover-foundation, sees 'Carefully analyze the entire codebase' with **⚠️ IMPORTANT:** format", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 2, "text": "Aider CLI agent runs discover-foundation, sees 'Thoroughly examine the codebase' with **IMPORTANT:** plain text format", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 3, "text": "Unknown/default agent runs discover-foundation, sees safe generic language without system-reminder tags", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 4, "text": "discover-foundation initial draft creation uses agent.supportsMetaCognition to conditionally include ULTRATHINK", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 5, "text": "project.vision field guidance checks agent capabilities before using ULTRATHINK terminology", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" } ], "questions": [ { "id": 0, "text": "@human: Should we add agent-specific variations for ALL field guidance prompts, or just focus on project.vision which currently has ULTRATHINK?", "selected": true, "answer": "Focus only on locations with ULTRATHINK (initial draft + project.vision). Other fields don't have Claude-specific language. Keep scope minimal for quick fix (Option 1).", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" }, { "id": 1, "text": "@human: Should help documentation (discover-foundation-help.ts) also be updated to remove ULTRATHINK references, or can we keep it as an example of Claude-specific guidance?", "selected": true, "answer": "Update help docs to mention this is Claude-specific and explain agent-aware messaging. Add note: 'Non-Claude agents will see generic analysis language.' Documentation should reflect multi-agent reality.", "deleted": false, "createdAt": "2025-10-22T08:19:09.971Z" } ], "assumptions": [ "Update help docs to mention this is Claude-specific and explain agent-aware messaging. Add note: 'Non-Claude agents will see generic analysis language.' Documentation should reflect multi-agent reality." ], "estimate": 3, "nextRuleId": 6, "nextExampleId": 6, "nextQuestionId": 2, "nextNoteId": 0 }, "FEAT-017": { "id": "FEAT-017", "title": "Duplicate scenario detection in generate-scenarios command", "type": "story", "status": "done", "createdAt": "2025-10-22T08:26:22.211Z", "updatedAt": "2025-10-24T06:14:55.109Z", "description": "When 'fspec generate-scenarios' is run, it should check for existing scenarios across all feature files that might be duplicates. Existing code already exists to search for duplicate scenarios and provide results back to the LLM. This work unit refactors generate-scenarios to:\n\n1. Search for possible duplicate scenarios before generating new ones\n2. If duplicates reach a similarity threshold, display them with clear instructions\n3. Emit a system-reminder with:\n - List of existing feature files that contain similar scenarios\n - Guidance on what to investigate\n - Instructions on how to ignore the warning if it's a false positive\n4. Add '--ignore-possible-duplicates' flag to bypass the check and continue generation\n5. Ensure the warning is actionable and prevents accidental duplication\n\nAcceptance Criteria:\n- Search existing feature files for similar scenarios during generate-scenarios\n- Display duplicate matches if similarity threshold is met\n- Emit system-reminder with clear next steps (investigate files, or use --ignore flag)\n- Add '--ignore-possible-duplicates' flag to skip duplicate check\n- Document the duplicate detection behavior in command help\n- Ensure existing duplicate search code is properly integrated", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T08:27:15.376Z" }, { "state": "testing", "timestamp": "2025-10-24T06:02:21.610Z" }, { "state": "implementing", "timestamp": "2025-10-24T06:04:39.773Z" }, { "state": "validating", "timestamp": "2025-10-24T06:10:06.521Z" }, { "state": "done", "timestamp": "2025-10-24T06:14:55.109Z" } ], "rules": [ { "id": 0, "text": "Existing code already exists to search for duplicate scenarios and provide results to LLM", "deleted": false, "createdAt": "2025-10-22T08:26:22.211Z" }, { "id": 1, "text": "System-reminder must provide CLEAR instructions on what to do next", "deleted": false, "createdAt": "2025-10-22T08:26:22.211Z" }, { "id": 2, "text": "Must show which existing feature files to investigate when duplicates are detected", "deleted": false, "createdAt": "2025-10-22T08:26:22.211Z" }, { "id": 3, "text": "Must provide instructions on how to ignore warning if it's not valid", "deleted": false, "createdAt": "2025-10-22T08:26:22.211Z" }, { "id": 4, "text": "Command must accept --ignore-possible-duplicates flag to bypass duplicate check", "deleted": false, "createdAt": "2025-10-22T08:26:22.211Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec generate-scenarios WORK-001', duplicate scenarios are found above threshold, system-reminder shows list of feature files to investigate with clear next steps", "deleted": false, "createdAt": "2025-10-22T08:26:22.211Z" }, { "id": 1, "text": "User reviews system-reminder, investigates suggested feature files, determines it's a false positive, runs 'fspec generate-scenarios WORK-001 --ignore-possible-duplicates' to proceed", "deleted": false, "createdAt": "2025-10-22T08:26:22.211Z" }, { "id": 2, "text": "User runs 'fspec generate-scenarios WORK-001', no duplicates found, scenarios are generated normally without any warnings", "deleted": false, "createdAt": "2025-10-22T08:26:22.211Z" } ], "userStory": { "role": "developer using fspec", "action": "detect duplicate scenarios before generating new ones", "benefit": "I avoid creating duplicate scenarios across feature files" }, "estimate": 3, "nextRuleId": 5, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-032": { "id": "BUG-032", "title": "INIT-008 and BUG-030 implementation not integrated into actual codebase", "type": "story", "status": "done", "createdAt": "2025-10-22T09:02:16.255Z", "updatedAt": "2025-10-22T09:34:09.061Z", "description": "CRITICAL: The implementations for INIT-008 (agent runtime detection) and BUG-030 (agent-specific activation messages) exist as isolated utility functions with passing tests, but are NOT integrated into the actual codebase where they should be used.\n\nSYMPTOMS:\n1. BUG-030: getActivationMessage() function exists but init.ts:234 and AgentSelector.tsx:56 still show hardcoded generic message\n2. INIT-008: agentRuntimeConfig.ts functions (getAgentConfig, writeAgentConfig, formatAgentOutput) exist but are never called by any commands\n3. spec/fspec-config.json is never created during fspec init\n4. All commands still emit <system-reminder> tags unconditionally (formatAgentOutput not used)\n\nIMPACT:\n- Tests pass but user-facing functionality unchanged\n- Original bugs still exist in production code\n- 7 story points marked as 'done' but features not actually delivered\n- Integration gap between unit tests and real behavior\n\nROOT CAUSE:\n- TDD practiced at unit level only (isolated functions)\n- Missing integration/E2E tests showing actual command behavior\n- Work units marked 'done' without verifying end-to-end functionality\n- ACDD followed for isolated modules but not for system integration\n\nACCEPTANCE CRITERIA:\n- getActivationMessage() called from init.ts and AgentSelector.tsx\n- writeAgentConfig() called during fspec init (creates spec/fspec-config.json)\n- formatAgentOutput() used by all commands emitting system-reminders\n- Integration tests prove E2E functionality works\n- Manual testing confirms bugs are actually fixed\n\nRelated: INIT-008, BUG-030", "children": [], "attachments": [ "spec/attachments/BUG-032/bug-032-integration-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T09:06:49.671Z" }, { "state": "testing", "timestamp": "2025-10-22T09:10:29.488Z" }, { "state": "implementing", "timestamp": "2025-10-22T09:11:30.623Z" }, { "state": "testing", "timestamp": "2025-10-22T09:13:17.184Z" }, { "state": "implementing", "timestamp": "2025-10-22T09:14:43.250Z" }, { "state": "validating", "timestamp": "2025-10-22T09:23:11.940Z" }, { "state": "done", "timestamp": "2025-10-22T09:23:19.872Z" }, { "state": "testing", "timestamp": "2025-10-22T09:32:51.649Z" }, { "state": "implementing", "timestamp": "2025-10-22T09:33:43.933Z" }, { "state": "validating", "timestamp": "2025-10-22T09:33:49.940Z" }, { "state": "done", "timestamp": "2025-10-22T09:34:09.061Z" } ], "userStory": { "role": "developer who completed INIT-008 and BUG-030", "action": "have the utility functions actually integrated into the codebase", "benefit": "the features work for end users instead of just passing unit tests" }, "rules": [ { "id": 0, "text": "getActivationMessage() must be called from src/commands/init.ts:234 to show agent-specific activation instructions", "deleted": false, "createdAt": "2025-10-22T09:02:16.255Z" }, { "id": 1, "text": "getActivationMessage() must be called from src/components/AgentSelector.tsx:56 to show agent-specific UI text", "deleted": false, "createdAt": "2025-10-22T09:02:16.255Z" }, { "id": 2, "text": "writeAgentConfig() must be called during fspec init to create spec/fspec-config.json with detected agent", "deleted": false, "createdAt": "2025-10-22T09:02:16.255Z" }, { "id": 3, "text": "Integration tests must verify end-to-end behavior, not just unit test isolation", "deleted": false, "createdAt": "2025-10-22T09:02:16.255Z" } ], "examples": [ { "id": 0, "text": "Before: init.ts shows generic 'Run /fspec in your AI agent to activate'. After: init.ts calls getActivationMessage() and shows 'Run /fspec in Claude Code to activate' for Claude users", "deleted": false, "createdAt": "2025-10-22T09:02:16.255Z" }, { "id": 1, "text": "Before: AgentSelector.tsx shows hardcoded text. After: AgentSelector calls getActivationMessage() and dynamically renders agent-specific text", "deleted": false, "createdAt": "2025-10-22T09:02:16.255Z" }, { "id": 2, "text": "Before: fspec init completes but no spec/fspec-config.json created. After: init calls writeAgentConfig() and creates {'agent': 'claude'}", "deleted": false, "createdAt": "2025-10-22T09:02:16.255Z" } ], "estimate": 5, "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "INIT-009": { "id": "INIT-009", "title": "Remove initialization files", "type": "story", "status": "done", "createdAt": "2025-10-22T09:49:27.541Z", "updatedAt": "2025-10-22T10:15:04.951Z", "description": "Command to remove fspec init files from AI editors", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T09:49:34.506Z" }, { "state": "testing", "timestamp": "2025-10-22T10:10:31.908Z" }, { "state": "implementing", "timestamp": "2025-10-22T10:11:52.764Z" }, { "state": "validating", "timestamp": "2025-10-22T10:13:14.706Z" }, { "state": "done", "timestamp": "2025-10-22T10:15:04.951Z" } ], "userStory": { "role": "developer who wants to remove fspec files or switch agents", "action": "remove all fspec init files", "benefit": "my project is clean when I switch agents or remove fspec entirely" }, "questions": [ { "id": 0, "text": "@human: Should fspec remove-init-files remove spec/fspec-config.json, or only agent-specific files (spec/AGENT.md and slash command files)?", "selected": true, "answer": "Use an interactive prompt (similar to agent selector in fspec init) to ask user if they want to keep or remove spec/fspec-config.json", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 1, "text": "@human: Should fspec remove-init-files prompt for confirmation before deleting, or support a --force flag?", "selected": true, "answer": "No additional confirmation needed - the interactive prompt about keeping/removing config serves as the confirmation step. Delete immediately after user makes their choice.", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 2, "text": "@human: Should fspec remove-init-files auto-detect installed agents (from spec/fspec-config.json or detection) and only remove those files, or remove all known agent files regardless?", "selected": true, "answer": "Auto-detect installed agents using spec/fspec-config.json or file detection, and only remove files for detected agents (not all known agents)", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 3, "text": "@human: If some init files don't exist (e.g., .claude/commands/fspec.md is missing), should the command fail with an error, or silently skip and report what was removed?", "selected": true, "answer": "Silently skip missing files and continue removing what exists. No error if files are already deleted.", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" } ], "rules": [ { "id": 0, "text": "Use an interactive prompt (similar to agent selector in fspec init) to ask user if they want to keep or remove spec/fspec-config.json", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 1, "text": "No additional confirmation needed - the interactive prompt about keeping/removing config serves as the confirmation step. Delete immediately after user makes their choice.", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 2, "text": "Auto-detect installed agents using spec/fspec-config.json or file detection, and only remove files for detected agents (not all known agents)", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 3, "text": "Silently skip missing files and continue removing what exists. No error if files are already deleted.", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec remove-init-files', interactive prompt asks 'Keep spec/fspec-config.json?', user selects 'No', all files removed including config", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 1, "text": "User runs 'fspec remove-init-files', interactive prompt asks 'Keep spec/fspec-config.json?', user selects 'Yes', only agent files removed (spec/CLAUDE.md, .claude/commands/fspec.md), config preserved", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 2, "text": "User runs 'fspec remove-init-files', spec/fspec-config.json contains 'claude' agent, only Claude files removed (not Cursor or other agents)", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" }, { "id": 3, "text": "User runs 'fspec remove-init-files', .claude/commands/fspec.md already missing, command silently skips and removes other files without error", "deleted": false, "createdAt": "2025-10-22T09:49:27.541Z" } ], "estimate": 3, "nextRuleId": 4, "nextExampleId": 4, "nextQuestionId": 4, "nextNoteId": 0 }, "INIT-010": { "id": "INIT-010", "title": "Agent switching prompt in fspec init", "type": "story", "status": "done", "createdAt": "2025-10-22T09:53:36.556Z", "updatedAt": "2025-10-22T11:32:17.078Z", "description": "When fspec init detects existing agent files, prompt user to switch agents (replacing old files except spec/fspec-config.json)", "children": [], "dependsOn": [ "INIT-009" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T10:19:28.647Z" }, { "state": "testing", "timestamp": "2025-10-22T11:26:40.105Z" }, { "state": "implementing", "timestamp": "2025-10-22T11:30:20.262Z" }, { "state": "validating", "timestamp": "2025-10-22T11:31:55.506Z" }, { "state": "done", "timestamp": "2025-10-22T11:32:17.079Z" } ], "userStory": { "role": "developer switching between AI coding agents", "action": "be prompted to switch agents when running fspec init with existing agent files", "benefit": "I can easily switch from one agent to another without manual cleanup" }, "questions": [ { "id": 0, "text": "@human: When should the agent switching prompt appear - always, or only when installing a different agent than currently installed?", "selected": true, "answer": "Detect current agent using BOTH spec/fspec-config.json AND file detection (like remove-init-files does), then prompt only if the new agent being installed is different from the detected agent", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 1, "text": "@human: What options should the agent switching prompt offer to the user?", "selected": true, "answer": "Two options: 'Switch to [NewAgent]' (removes old agent files, installs new agent) or 'Cancel' (keeps existing setup, aborts installation)", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 2, "text": "@human: Should spec/fspec-config.json be deleted, updated, or left unchanged when switching agents?", "selected": true, "answer": "Update spec/fspec-config.json to reflect the new agent ID (e.g., from {\"agent\": \"claude\"} to {\"agent\": \"cursor\"}) so runtime detection works correctly", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 3, "text": "@human: What happens in interactive mode when an existing agent is detected?", "selected": true, "answer": "Pre-select the detected agent in interactive selector. If user chooses the same agent, reinstall/refresh files (no prompt). If user chooses a different agent, show switch prompt ('Switch from Claude to Cursor?')", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" } ], "rules": [ { "id": 0, "text": "Detect current agent using BOTH spec/fspec-config.json AND file detection (like remove-init-files does), then prompt only if the new agent being installed is different from the detected agent", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 1, "text": "Two options: 'Switch to [NewAgent]' (removes old agent files, installs new agent) or 'Cancel' (keeps existing setup, aborts installation)", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 2, "text": "Update spec/fspec-config.json to reflect the new agent ID (e.g., from {\"agent\": \"claude\"} to {\"agent\": \"cursor\"}) so runtime detection works correctly", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 3, "text": "Pre-select the detected agent in interactive selector. If user chooses the same agent, reinstall/refresh files (no prompt). If user chooses a different agent, show switch prompt ('Switch from Claude to Cursor?')", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec init --agent=cursor', Claude files detected, prompt shows 'Switch from Claude to Cursor?', user selects 'Switch', Claude files removed, Cursor files installed, config updated to cursor", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 1, "text": "User runs 'fspec init --agent=cursor', Claude files detected, prompt shows 'Switch from Claude to Cursor?', user selects 'Cancel', Claude files remain, Cursor not installed, exit code 0", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 2, "text": "User runs 'fspec init' (interactive), Claude files detected and pre-selected, user selects Cursor instead, prompt shows 'Switch from Claude to Cursor?', user confirms, switch happens", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 3, "text": "User runs 'fspec init' (interactive), Claude files detected and pre-selected, user presses Enter (keeps Claude), files reinstalled/refreshed without prompt", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" }, { "id": 4, "text": "User runs 'fspec init --agent=claude', Claude files already exist, no prompt shown (same agent), files reinstalled/refreshed (idempotent behavior)", "deleted": false, "createdAt": "2025-10-22T09:53:36.556Z" } ], "estimate": 5, "nextRuleId": 4, "nextExampleId": 5, "nextQuestionId": 4, "nextNoteId": 0 }, "DOC-005": { "id": "DOC-005", "title": "Update documentation for remove-init-files and agent switching", "type": "task", "status": "done", "createdAt": "2025-10-22T10:21:21.357Z", "updatedAt": "2025-10-22T11:42:59.691Z", "description": "Update help files, README, and docs to document fspec remove-init-files command and agent switching prompt in fspec init. Files to update: src/commands/*-help.ts, src/help.ts, README.md, docs/*", "children": [], "dependsOn": [ "INIT-009", "INIT-010" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T11:35:49.247Z" }, { "state": "implementing", "timestamp": "2025-10-22T11:35:51.701Z" }, { "state": "specifying", "timestamp": "2025-10-22T11:36:36.909Z" }, { "state": "implementing", "timestamp": "2025-10-22T11:37:20.647Z" }, { "state": "validating", "timestamp": "2025-10-22T11:42:50.318Z" }, { "state": "done", "timestamp": "2025-10-22T11:42:59.691Z" } ], "rules": [ { "id": 0, "text": "Update src/help.ts to include remove-init-files in setup commands section", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" }, { "id": 1, "text": "Create src/commands/remove-init-files-help.ts with comprehensive help documentation", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" }, { "id": 2, "text": "Update init-help.ts to document agent switching behavior", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" }, { "id": 3, "text": "Update README.md with remove-init-files command and agent switching examples", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" }, { "id": 4, "text": "Update docs/getting-started.md and docs/user-guide.md with new commands", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" } ], "examples": [ { "id": 0, "text": "Help file follows same structure as other command help files (WHEN TO USE, PREREQUISITES, USAGE, EXAMPLES, etc.)", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" }, { "id": 1, "text": "README shows 'fspec remove-init-files' in CLI commands section with brief description", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" }, { "id": 2, "text": "init-help.ts includes note about agent switching prompt when different agent detected", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" }, { "id": 3, "text": "docs/getting-started.md shows how to remove fspec if user wants to uninstall", "deleted": false, "createdAt": "2025-10-22T10:21:21.357Z" } ], "estimate": 2, "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-033": { "id": "BUG-033", "title": "Incomplete implementation of INIT-009 and INIT-010 features", "type": "story", "status": "done", "createdAt": "2025-10-22T11:58:47.689Z", "updatedAt": "2025-10-22T13:00:23.524Z", "description": "Agent switching and remove-init-files features have passing tests but incomplete implementations. Interactive prompts missing, agent detection not integrated into action handlers, misleading help documentation.", "children": [], "attachments": [ "spec/attachments/BUG-033/incomplete-implementation-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T11:59:56.902Z" }, { "state": "testing", "timestamp": "2025-10-22T12:08:47.604Z" }, { "state": "implementing", "timestamp": "2025-10-22T12:14:46.380Z" }, { "state": "validating", "timestamp": "2025-10-22T12:59:13.127Z" }, { "state": "done", "timestamp": "2025-10-22T13:00:23.524Z" } ], "userStory": { "role": "developer using fspec", "action": "have complete implementations of remove-init-files and init agent switching", "benefit": "the CLI actually works as documented and passes real user acceptance tests" }, "rules": [ { "id": 0, "text": "remove-init-files MUST prompt user with interactive Yes/No for keeping spec/fspec-config.json", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 1, "text": "init command MUST detect existing agent before installation and compare with requested agent", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 2, "text": "init command MUST prompt for agent switch confirmation when existing agent differs from requested agent", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 3, "text": "Success messages MUST show detailed list of files removed/installed to match help documentation", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 4, "text": "Agent config MUST be written only once (remove duplicate writeAgentConfig calls)", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 5, "text": "Create a generic ConfirmPrompt.tsx component that can be reused for both cases (and future confirmations). Interface: ConfirmPrompt({ message, confirmLabel?, cancelLabel?, onSubmit }) returns boolean. This follows DRY principle and keeps components focused.", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 6, "text": "Unit test the action handlers (not just internal functions). Mock ConfirmPrompt component responses. This is sufficient and provides faster feedback than E2E tests.", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 7, "text": "Add --keep-config and --no-keep-config flags for explicit control in non-interactive environments. When flags are provided, skip the interactive prompt. When no flag provided, show interactive prompt (normal behavior). This is clear and unambiguous.", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec remove-init-files', sees interactive prompt 'Keep spec/fspec-config.json?', selects 'Yes', config remains, agent files removed", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 1, "text": "User runs 'fspec remove-init-files', sees interactive prompt, selects 'No', all files including config removed, detailed output shown", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 2, "text": "User runs 'fspec init --agent=cursor' when Claude is installed, sees 'Switch from Claude to Cursor?' prompt, selects 'Switch', Claude files removed, Cursor installed", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 3, "text": "User runs 'fspec init --agent=cursor' when Claude is installed, sees switch prompt, selects 'Cancel', Claude files remain, process exits cleanly", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 4, "text": "User runs 'fspec init --agent=claude' when Claude is already installed, no prompt shown, files reinstalled idempotently", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" } ], "questions": [ { "id": 0, "text": "@human: Should we create new React/Ink components (KeepConfigPrompt.tsx, AgentSwitchPrompt.tsx) or integrate into existing AgentSelector component?", "selected": true, "answer": "Create a generic ConfirmPrompt.tsx component that can be reused for both cases (and future confirmations). Interface: ConfirmPrompt({ message, confirmLabel?, cancelLabel?, onSubmit }) returns boolean. This follows DRY principle and keeps components focused.", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 1, "text": "@human: Should we add E2E tests that spawn actual CLI processes, or is unit testing the action handlers sufficient?", "selected": true, "answer": "Unit test the action handlers (not just internal functions). Mock ConfirmPrompt component responses. This is sufficient and provides faster feedback than E2E tests.", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 2, "text": "@human: What should happen if user runs remove-init-files in non-interactive environment (CI/CD)? Should we have a --yes flag to skip prompts?", "selected": true, "answer": "Add --keep-config and --no-keep-config flags for explicit control in non-interactive environments. When flags are provided, skip the interactive prompt. When no flag provided, show interactive prompt (normal behavior). This is clear and unambiguous.", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" } ], "architectureNotes": [ { "id": 0, "text": "Implementation requires: 1) Create src/components/ConfirmPrompt.tsx (reusable Yes/No prompt), 2) Update remove-init-files action handler to use ConfirmPrompt, 3) Update init action handler to detect existing agent and show switch prompt, 4) Remove duplicate writeAgentConfig call in init.ts, 5) Update success messages to show detailed file lists", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 1, "text": "Testing strategy: Unit test action handlers (not internal functions). Mock ConfirmPrompt component responses using vitest. Ensure tests call the actual action handler path that real users trigger.", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" }, { "id": 2, "text": "Files to modify: src/commands/remove-init-files.ts (action handler), src/commands/init.ts (action handler + remove duplicate), src/components/ConfirmPrompt.tsx (create new), src/commands/__tests__/remove-init-files.test.ts (fix tests), src/commands/__tests__/init-agent-switching.test.ts (fix tests)", "deleted": false, "createdAt": "2025-10-22T11:58:47.689Z" } ], "estimate": 5, "nextRuleId": 8, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 3 }, "BUG-034": { "id": "BUG-034", "title": "Double prompt and missing success message in interactive init mode", "type": "story", "status": "done", "createdAt": "2025-10-22T13:08:50.031Z", "updatedAt": "2025-10-22T13:29:07.162Z", "description": "Interactive mode shows confusing double prompts (AgentSelector + switch confirmation) and no success message after installation. Users select agent, then must confirm again, then see no feedback about success.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T13:08:57.055Z" }, { "state": "testing", "timestamp": "2025-10-22T13:17:16.070Z" }, { "state": "implementing", "timestamp": "2025-10-22T13:21:32.203Z" }, { "state": "validating", "timestamp": "2025-10-22T13:23:47.459Z" }, { "state": "done", "timestamp": "2025-10-22T13:29:07.163Z" } ], "attachments": [ "spec/attachments/BUG-034/bug-034-analysis.md" ], "userStory": { "role": "developer using fspec init", "action": "select an agent and see clear confirmation", "benefit": "I know the installation succeeded and what to do next" }, "rules": [ { "id": 0, "text": "Interactive mode MUST NOT show double prompts (AgentSelector selection IS user confirmation)", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" }, { "id": 1, "text": "Interactive mode MUST show success message with file list and activation instructions", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" }, { "id": 2, "text": "CLI mode (--agent flag) SHOULD still show agent switch confirmation prompt", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" }, { "id": 3, "text": "Both interactive and CLI modes MUST show identical success messages", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec init', selects Cursor from menu, sees NO second confirmation prompt, sees success message with file list", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" }, { "id": 1, "text": "User runs 'fspec init --agent=cursor' when Claude installed, sees 'Switch from Claude to Cursor?' prompt, confirms, sees success message", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" }, { "id": 2, "text": "User runs 'fspec init', selects same agent (Claude), sees NO prompt, sees success message showing reinstallation", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" }, { "id": 3, "text": "Success message shows: checkmark, agent name, indented file list, activation instructions - identical format for both modes", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" } ], "architectureNotes": [ { "id": 0, "text": "Fix 1: Pass promptAgentSwitch parameter to executeInit() in interactive mode that returns true (auto-confirm). This skips the second prompt while preserving CLI mode behavior.", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" }, { "id": 1, "text": "Fix 2: Change success message condition from 'if (options.agent.length > 0)' to 'if (result.success)' so both interactive and CLI modes show feedback.", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" }, { "id": 2, "text": "Files to modify: src/commands/init.ts (action handler lines 366 and 375). NO changes needed to executeInit(), installAgents(), or AgentSelector component.", "deleted": false, "createdAt": "2025-10-22T13:08:50.031Z" } ], "estimate": 3, "nextRuleId": 4, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 3 }, "GIT-004": { "id": "GIT-004", "title": "Interactive checkpoint viewer with diff and commit capabilities", "type": "story", "status": "done", "createdAt": "2025-10-22T13:35:44.893Z", "updatedAt": "2025-10-29T08:18:27.983Z", "description": "Add an interactive TUI for viewing checkpoints, examining file changes, seeing diffs, viewing staged/unstaged files, generating conventional commits, and performing git operations directly from the checkpoint view", "children": [], "dependsOn": [ "GIT-002" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-22T13:36:02.558Z" }, { "state": "testing", "timestamp": "2025-10-29T08:06:51.781Z" }, { "state": "implementing", "timestamp": "2025-10-29T08:08:12.909Z" }, { "state": "validating", "timestamp": "2025-10-29T08:17:44.335Z" }, { "state": "done", "timestamp": "2025-10-29T08:18:27.984Z" } ], "questions": [ { "id": 0, "text": "@human: How should users access the interactive checkpoint viewer? New command, integrated into kanban board, or integrated into show-work-unit?", "selected": true, "answer": "Integrated into kanban board TUI using C key (checkpoints) and F key (changed files)", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" } ], "rules": [ { "id": 0, "text": "Integrated into kanban board TUI using C key (checkpoints) and F key (changed files)", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 1, "text": "View must use unified keybindings consistent with other TUI views (e.g., j/k for scrolling, q to quit)", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 2, "text": "View must display two panes: file list (left) and diff view (right), both independently scrollable", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 3, "text": "Layout must use flexbox with both file list and diff area using flex to grow proportionally", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 4, "text": "Scrolling implementation must follow the same pattern as work unit details view in TUI", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 5, "text": "C key opens checkpoint files view, F key opens changed files view", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 6, "text": "No vim-style keybindings (j/k/g/G) - use only arrow keys, PgUp/PgDn, Home/End for navigation", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" } ], "examples": [ { "id": 0, "text": "User presses C in kanban board → checkpoint files view opens with file list on left and diff on right", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 1, "text": "User presses F in kanban board → changed files view opens with file list on left and diff on right", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 2, "text": "User uses j/k to scroll through file list, selects file, then uses j/k to scroll through diff content", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 3, "text": "User presses q in checkpoint/changed files view → returns to kanban board", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" }, { "id": 4, "text": "File list and diff view both resize proportionally when terminal window resizes (flexbox behavior)", "deleted": false, "createdAt": "2025-10-22T13:35:44.893Z" } ], "userStory": { "role": "developer using fspec TUI", "action": "view and navigate checkpoint/changed files with diffs", "benefit": "I can quickly understand what changed and restore work if needed" }, "estimate": 8, "updated": "2025-10-29T08:18:27.983Z", "nextRuleId": 7, "nextExampleId": 5, "nextQuestionId": 1, "nextNoteId": 0 }, "BOARD-003": { "id": "BOARD-003", "title": "Real-time board updates with git stash and file inspection", "type": "story", "status": "done", "createdAt": "2025-10-22T13:42:12.487Z", "updatedAt": "2025-10-27T08:06:18.898Z", "description": "Add real-time board updates to the interactive Kanban CLI. Display git stashes and changed files (staged/unstaged) that users can click to inspect. Board should refresh automatically when work unit status changes. Support keyboard navigation to inspect stash details and file diffs.", "epic": "interactive-cli", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T05:38:39.225Z" }, { "state": "testing", "timestamp": "2025-10-27T05:41:53.905Z" }, { "state": "specifying", "timestamp": "2025-10-27T05:43:07.455Z" }, { "state": "testing", "timestamp": "2025-10-27T05:44:53.992Z" }, { "state": "implementing", "timestamp": "2025-10-27T05:46:34.390Z" }, { "state": "specifying", "timestamp": "2025-10-27T05:58:46.491Z" }, { "state": "testing", "timestamp": "2025-10-27T05:59:52.547Z" }, { "state": "implementing", "timestamp": "2025-10-27T06:00:33.304Z" }, { "state": "validating", "timestamp": "2025-10-27T06:02:39.451Z" }, { "state": "done", "timestamp": "2025-10-27T06:07:24.261Z" }, { "state": "specifying", "timestamp": "2025-10-27T06:07:53.144Z" }, { "state": "testing", "timestamp": "2025-10-27T06:08:56.316Z" }, { "state": "implementing", "timestamp": "2025-10-27T06:09:00.977Z" }, { "state": "validating", "timestamp": "2025-10-27T06:09:15.768Z" }, { "state": "done", "timestamp": "2025-10-27T06:09:25.356Z" }, { "state": "implementing", "timestamp": "2025-10-27T07:57:49.474Z" }, { "state": "validating", "timestamp": "2025-10-27T08:06:05.321Z" }, { "state": "done", "timestamp": "2025-10-27T08:06:18.898Z" } ], "userStory": { "role": "developer managing work units", "action": "see real-time status of work in progress", "benefit": "I can quickly inspect changes and stash state without leaving the terminal" }, "rules": [ { "id": 0, "text": "Board must display git stashes with timestamps and message previews", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 1, "text": "Board must show changed files with staged/unstaged indicators (green/yellow)", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 2, "text": "User can inspect stash details by selecting with Enter key", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 3, "text": "User can view file diffs for changed files by selecting with Enter key", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 4, "text": "Board refreshes automatically when work unit status changes", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 5, "text": "Keyboard navigation: tab/shift-tab to switch between board/stash/files panels", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 6, "text": "ESC key returns from detail view to board view", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 7, "text": "CRITICAL: NEVER use git CLI commands (git status, git diff, git stash) - ONLY use isomorphic-git library", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 8, "text": "Use existing utilities: getStagedFiles(), getUnstagedFiles() from src/git/status.ts", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 9, "text": "Stash operations use git.log() with ref 'refs/stash' to list stashes via isomorphic-git", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 10, "text": "File diffs generated using git.readBlob() and manual diff logic (NOT git diff CLI)", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" } ], "examples": [ { "id": 0, "text": "User opens board with 2 stashes: shows 'GIT-001-auto-testing (2 hours ago)' and 'baseline (3 days ago)'", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 1, "text": "Board shows 3 staged files (green) and 2 unstaged files (yellow) in files panel", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 2, "text": "User presses Enter on stash: detail view shows stash message, timestamp, and changed files", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 3, "text": "User presses Enter on src/auth.ts: diff view shows +5 -2 lines with syntax highlighting", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 4, "text": "Status changes from implementing to validating: board automatically refreshes and updates column", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 5, "text": "User presses tab: focus switches from board to stash panel, border changes to cyan", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 6, "text": "User presses ESC in diff view: returns to board view with previous focus restored", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 7, "text": "Get staged files: import { getStagedFiles } from 'src/git/status'; const staged = await getStagedFiles(cwd); // ['src/auth.ts', 'README.md']", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 8, "text": "Get unstaged files: import { getUnstagedFiles } from 'src/git/status'; const unstaged = await getUnstagedFiles(cwd); // ['src/utils.ts']", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 9, "text": "List stashes: const logs = await git.log({ fs, dir: cwd, ref: 'refs/stash', depth: 10 }); // Returns stash commits", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 10, "text": "Read file from stash: const { blob } = await git.readBlob({ fs, dir: cwd, oid: stashOid, filepath: 'src/auth.ts' }); // Get file content", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" }, { "id": 11, "text": "Generate diff: const headBlob = await git.readBlob({ fs, dir: cwd, oid: 'HEAD', filepath }); const workdirContent = await fs.readFile(filepath); const diff = computeDiff(headBlob, workdirContent);", "deleted": false, "createdAt": "2025-10-22T13:42:12.487Z" } ], "estimate": 8, "nextRuleId": 11, "nextExampleId": 12, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-035": { "id": "BUG-035", "title": "Duplicate 'Next steps' message in fspec init output", "type": "story", "status": "done", "createdAt": "2025-10-22T13:52:15.040Z", "updatedAt": "2025-10-23T01:24:23.529Z", "description": "When running 'fspec init', the success message displays 'Next steps: Run /fspec in Claude Code to activate' twice - once after claude installation and once after Claude Code installation. Should only display once at the end.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T01:16:17.617Z" }, { "state": "testing", "timestamp": "2025-10-23T01:19:53.264Z" }, { "state": "implementing", "timestamp": "2025-10-23T01:22:36.653Z" }, { "state": "validating", "timestamp": "2025-10-23T01:23:50.179Z" }, { "state": "done", "timestamp": "2025-10-23T01:24:23.530Z" } ], "userStory": { "role": "developer using fspec init interactively", "action": "complete the initialization process", "benefit": "I see clear next steps only once" }, "rules": [ { "id": 0, "text": "Next steps message should only appear once in init output", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" }, { "id": 1, "text": "AgentSelector component shows success message with Next steps in interactive mode", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" }, { "id": 2, "text": "Action handler also shows success message with Next steps for all modes", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" }, { "id": 3, "text": "CLI mode should not be affected by this fix", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'fspec init' interactively, selects Claude, sees 'Next steps' message twice", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" }, { "id": 1, "text": "Developer runs 'fspec init --agent=claude' in CLI mode, sees 'Next steps' message once", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" }, { "id": 2, "text": "After fix: interactive mode should show success message only once with Next steps at the end", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" } ], "architectureNotes": [ { "id": 0, "text": "AgentSelector component (src/components/AgentSelector.tsx:58-61) displays success message with 'Next steps' when agent is selected", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" }, { "id": 1, "text": "Action handler in init.ts (line 394) also displays success message with 'Next steps' after executeInit completes", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" }, { "id": 2, "text": "Solution: Remove 'Next steps' section from AgentSelector component (lines 60-61), keep only in action handler", "deleted": false, "createdAt": "2025-10-22T13:52:15.040Z" } ], "estimate": 1, "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 3 }, "AGENT-001": { "id": "AGENT-001", "title": "Test Cursor agent compatibility", "type": "story", "status": "specifying", "createdAt": "2025-10-22T13:55:09.683Z", "updatedAt": "2025-11-08T05:15:06.333Z", "description": "Verify fspec init --agent=cursor works correctly: creates .cursor/commands/fspec.md, creates spec/CURSOR.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 4, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T05:11:54.646Z" }, { "state": "testing", "timestamp": "2025-11-08T05:13:22.121Z" }, { "state": "specifying", "timestamp": "2025-11-08T05:15:06.333Z" } ], "userStory": { "role": "developer using Cursor AI agent", "action": "initialize fspec with Cursor-specific configuration", "benefit": "I can use fspec's ACDD workflow within Cursor environment" }, "rules": [ { "id": 0, "text": "fspec init --agent=cursor must create .cursor/commands/fspec.md file with fspec command integration", "deleted": false, "createdAt": "2025-11-08T05:12:12.061Z" }, { "id": 1, "text": "fspec init --agent=cursor must create spec/CURSOR.md with agent-specific instructions and ACDD workflow", "deleted": false, "createdAt": "2025-11-08T05:12:13.545Z" }, { "id": 2, "text": "Cursor activation instructions must be displayed after successful initialization", "deleted": false, "createdAt": "2025-11-08T05:12:15.700Z" }, { "id": 3, "text": "All core fspec commands must work in Cursor environment (create-story, add-scenario, generate-scenarios, etc.)", "deleted": false, "createdAt": "2025-11-08T05:12:17.239Z" } ], "examples": [ { "id": 0, "text": "Run 'fspec init --agent=cursor' in empty project → creates .cursor/commands/fspec.md and spec/CURSOR.md", "deleted": false, "createdAt": "2025-11-08T05:12:26.971Z" }, { "id": 1, "text": "After init, activation message shows: 'Cursor: open command palette and select fspec command'", "deleted": false, "createdAt": "2025-11-08T05:12:28.558Z" }, { "id": 2, "text": "Created .cursor/commands/fspec.md contains fspec CLI command invocations and ACDD workflow instructions", "deleted": false, "createdAt": "2025-11-08T05:12:30.107Z" }, { "id": 3, "text": "Created spec/CURSOR.md contains Cursor-specific ACDD guidelines and Example Mapping workflow", "deleted": false, "createdAt": "2025-11-08T05:12:31.570Z" } ], "estimate": 5 }, "AGENT-002": { "id": "AGENT-002", "title": "Test Cline agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:11.528Z", "updatedAt": "2025-10-22T13:55:11.528Z", "description": "Verify fspec init --agent=cline works correctly: creates .cline/commands/fspec.md, creates spec/CLINE.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-003": { "id": "AGENT-003", "title": "Test Aider agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:13.162Z", "updatedAt": "2025-10-22T13:55:13.162Z", "description": "Verify fspec init --agent=aider works correctly: creates .aider/ files, creates spec/AIDER.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-004": { "id": "AGENT-004", "title": "Test Windsurf agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:14.682Z", "updatedAt": "2025-10-22T13:55:14.682Z", "description": "Verify fspec init --agent=windsurf works correctly: creates .windsurf/workflows/fspec.md, creates spec/WINDSURF.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-005": { "id": "AGENT-005", "title": "Test GitHub Copilot agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:15.899Z", "updatedAt": "2025-10-22T13:55:15.899Z", "description": "Verify fspec init --agent=copilot works correctly: creates .github/prompts/fspec.md, creates spec/COPILOT.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-006": { "id": "AGENT-006", "title": "Test Gemini CLI agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:17.120Z", "updatedAt": "2025-10-22T13:55:17.120Z", "description": "Verify fspec init --agent=gemini works correctly: creates .gemini/commands/fspec.toml (TOML format), creates spec/GEMINI.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-007": { "id": "AGENT-007", "title": "Test Qwen Code agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:19.348Z", "updatedAt": "2025-10-22T13:55:19.348Z", "description": "Verify fspec init --agent=qwen works correctly: creates .qwen/commands/fspec.toml (TOML format), creates spec/QWEN.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-008": { "id": "AGENT-008", "title": "Test Kilo Code agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:20.666Z", "updatedAt": "2025-10-22T13:55:20.666Z", "description": "Verify fspec init --agent=kilocode works correctly: creates .kilocode/rules/fspec.md, creates spec/KILOCODE.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-009": { "id": "AGENT-009", "title": "Test Roo Code agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:22.053Z", "updatedAt": "2025-10-22T13:55:22.053Z", "description": "Verify fspec init --agent=roo works correctly: creates .roo/rules/fspec.md, creates spec/ROO.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-010": { "id": "AGENT-010", "title": "Test CodeBuddy agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:36.893Z", "updatedAt": "2025-10-22T13:55:36.893Z", "description": "Verify fspec init --agent=codebuddy works correctly: creates .codebuddy/commands/fspec.md, creates spec/CODEBUDDY.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-011": { "id": "AGENT-011", "title": "Test Amazon Q agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:38.297Z", "updatedAt": "2025-10-22T13:55:38.297Z", "description": "Verify fspec init --agent=amazonq works correctly: creates .amazonq/prompts/fspec.md, creates spec/AMAZONQ.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-012": { "id": "AGENT-012", "title": "Test Auggie agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:39.680Z", "updatedAt": "2025-10-22T13:55:39.680Z", "description": "Verify fspec init --agent=auggie works correctly: creates .auggie/ files, creates spec/AUGGIE.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-013": { "id": "AGENT-013", "title": "Test OpenCode agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:41.011Z", "updatedAt": "2025-10-22T13:55:41.011Z", "description": "Verify fspec init --agent=opencode works correctly: creates .opencode/command/fspec.md, creates spec/OPENCODE.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-014": { "id": "AGENT-014", "title": "Test Codex agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:42.525Z", "updatedAt": "2025-10-22T13:55:42.525Z", "description": "Verify fspec init --agent=codex works correctly: creates .codex/commands/fspec.md, creates spec/CODEX.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-015": { "id": "AGENT-015", "title": "Test Factory Droid agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:43.848Z", "updatedAt": "2025-10-22T13:55:43.848Z", "description": "Verify fspec init --agent=factory works correctly: creates .factory/commands/fspec.md, creates spec/FACTORY.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-016": { "id": "AGENT-016", "title": "Test Crush agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:45.836Z", "updatedAt": "2025-10-22T13:55:45.836Z", "description": "Verify fspec init --agent=crush works correctly: creates .crush/commands/fspec.md, creates spec/CRUSH.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "AGENT-017": { "id": "AGENT-017", "title": "Test Codex CLI agent compatibility", "type": "story", "status": "backlog", "createdAt": "2025-10-22T13:55:47.125Z", "updatedAt": "2025-10-22T13:55:47.125Z", "description": "Verify fspec init --agent=codex-cli works correctly: creates .codex/commands/fspec.md, creates spec/CODEX-CLI.md, shows correct activation instructions, and supports full ACDD workflow", "epic": "agent-testing", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "DEP-002": { "id": "DEP-002", "title": "Upgrade Vitest from 2.1.8 to 4.0.0", "type": "story", "status": "done", "createdAt": "2025-10-23T05:55:26.427Z", "updatedAt": "2025-10-23T06:02:38.051Z", "description": "Upgrade Vitest testing framework to version 4.0.0 (released October 22, 2025) which includes browser mode stabilization, visual regression testing support, and improved stability. This upgrade requires migration guide review, configuration updates, and comprehensive testing to ensure no breaking changes affect existing test suite.", "epic": "test-coverage", "children": [], "architectureNotes": [ { "id": 0, "text": "Vitest 4.0 Release Notes (Oct 22, 2025):\n- Browser Mode stabilization (no longer experimental)\n- Visual regression testing with toMatchScreenshot assertion\n- Context import changed from @vitest/browser/context to vitest/browser\n- Pool default remains 'forks' (introduced in 2.0)\n- Migration guide: https://vitest.dev/blog/vitest-4", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" } ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T05:56:09.489Z" }, { "state": "testing", "timestamp": "2025-10-23T05:59:48.049Z" }, { "state": "implementing", "timestamp": "2025-10-23T05:59:52.769Z" }, { "state": "validating", "timestamp": "2025-10-23T06:02:34.367Z" }, { "state": "done", "timestamp": "2025-10-23T06:02:38.051Z" } ], "rules": [ { "id": 0, "text": "All existing tests must pass after upgrade with no modifications", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" }, { "id": 1, "text": "Configuration changes must maintain safety settings (singleFork, fileParallelism: false)", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" }, { "id": 2, "text": "Must review official Vitest 4.0 migration guide before upgrading", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" } ], "examples": [ { "id": 0, "text": "Run npm install -D vitest@^4.0.0 to upgrade package", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" }, { "id": 1, "text": "Update vitest.config.ts if breaking changes affect configuration syntax", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" }, { "id": 2, "text": "Run full test suite with npm test to verify compatibility", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" }, { "id": 3, "text": "Check npm run build to ensure TypeScript compilation still works", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" } ], "questions": [ { "id": 0, "text": "@human: Should we explore browser mode features in Vitest 4.0 or keep using node environment only?", "selected": true, "answer": "Keep node environment only - fspec is a CLI tool with no browser requirements", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" }, { "id": 1, "text": "@human: Do we want to adopt visual regression testing features or defer for future work?", "selected": true, "answer": "Defer visual regression testing - not applicable to CLI tools", "deleted": false, "createdAt": "2025-10-23T05:55:26.427Z" } ], "userStory": { "role": "fspec developer", "action": "upgrade Vitest to version 4.0 for improved stability and latest features", "benefit": "I benefit from bug fixes, performance improvements, and maintain compatibility with the latest testing ecosystem" }, "estimate": 2, "nextRuleId": 3, "nextExampleId": 4, "nextQuestionId": 2, "nextNoteId": 1 }, "BUG-037": { "id": "BUG-037", "title": "Fix 2 failing test suites (version-display and cli-command-registration timeout)", "type": "story", "status": "done", "createdAt": "2025-10-23T06:29:08.901Z", "updatedAt": "2025-10-23T06:34:40.910Z", "description": "Test suite failures preventing npm test from passing: 1) version-display.test.ts has no active tests (all commented out), 2) cli-command-registration.test.ts times out after 30s because it executes 93+ CLI commands sequentially using execSync", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T06:29:24.460Z" }, { "state": "testing", "timestamp": "2025-10-23T06:31:23.142Z" }, { "state": "implementing", "timestamp": "2025-10-23T06:31:49.455Z" }, { "state": "validating", "timestamp": "2025-10-23T06:32:39.053Z" }, { "state": "done", "timestamp": "2025-10-23T06:34:40.910Z" } ], "userStory": { "role": "developer running npm test", "action": "have all tests pass successfully", "benefit": "I can verify code quality and ensure CI/CD pipeline succeeds" }, "rules": [ { "id": 0, "text": "All test files must contain at least one active test suite or be removed", "deleted": false, "createdAt": "2025-10-23T06:29:08.901Z" }, { "id": 1, "text": "CLI command registration tests must complete within 30 seconds", "deleted": false, "createdAt": "2025-10-23T06:29:08.901Z" }, { "id": 2, "text": "Tests that execute many CLI commands should use parallelization or mocking to reduce execution time", "deleted": false, "createdAt": "2025-10-23T06:29:08.901Z" } ], "examples": [ { "id": 0, "text": "version-display.test.ts has all tests commented out, causing Vitest to report 'No test suite found in file'", "deleted": false, "createdAt": "2025-10-23T06:29:08.901Z" }, { "id": 1, "text": "cli-command-registration.test.ts executes 93+ commands sequentially with execSync, taking over 30 seconds and timing out", "deleted": false, "createdAt": "2025-10-23T06:29:08.901Z" }, { "id": 2, "text": "After fixing version-display.test.ts, running 'npm test' should not show 'No test suite found' error", "deleted": false, "createdAt": "2025-10-23T06:29:08.901Z" }, { "id": 3, "text": "After optimizing cli-command-registration.test.ts, the test should complete in under 30 seconds", "deleted": false, "createdAt": "2025-10-23T06:29:08.901Z" } ], "estimate": 2, "nextRuleId": 3, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-038": { "id": "BUG-038", "title": "show-feature test failures - Work Units display assertions failing", "type": "bug", "status": "done", "createdAt": "2025-10-23T06:49:57.837Z", "updatedAt": "2025-10-23T07:05:47.975Z", "description": "Three tests in show-feature.test.ts are failing with toContain assertions even though the expected content appears to be present in the output. Tests: 1) Display work units linked to feature (feature-level tags), 2) Display multiple work units from scenario-level tags, 3) Display work units when feature has no work unit tag. The content IS in the output but toContain is failing.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T06:50:51.336Z" }, { "state": "testing", "timestamp": "2025-10-23T06:59:18.606Z" }, { "state": "implementing", "timestamp": "2025-10-23T07:03:12.372Z" }, { "state": "validating", "timestamp": "2025-10-23T07:03:48.010Z" }, { "state": "done", "timestamp": "2025-10-23T07:05:47.975Z" } ], "userStory": { "role": "developer running tests", "action": "verify show-feature output contains expected work unit information", "benefit": "I can validate the command output without ANSI escape codes interfering with assertions" }, "rules": [ { "id": 0, "text": "Test assertions must work on plain text output without ANSI escape codes", "deleted": false, "createdAt": "2025-10-23T06:49:57.837Z" }, { "id": 1, "text": "showFeature function must return content that can be tested with .toContain() assertions", "deleted": false, "createdAt": "2025-10-23T06:49:57.837Z" }, { "id": 2, "text": "ANSI codes should only be present in stdout display, not in returned content for testing", "deleted": false, "createdAt": "2025-10-23T06:49:57.837Z" }, { "id": 3, "text": "Option C: Remove chalk from showFeature() function. This is architecturally correct (separation of concerns), fixes the file-writing bug, makes tests pass without changes, and follows Single Responsibility Principle - the function generates data, the command handles display.", "deleted": false, "createdAt": "2025-10-23T06:49:57.837Z" } ], "examples": [ { "id": 0, "text": "Test checks for 'AUTH-001 (feature-level)' and it matches without ANSI codes", "deleted": false, "createdAt": "2025-10-23T06:49:57.837Z" }, { "id": 1, "text": "Test checks for 'Work Units: None' and it matches exactly", "deleted": false, "createdAt": "2025-10-23T06:49:57.837Z" }, { "id": 2, "text": "Running showFeature with format=text returns plain text in result.content", "deleted": false, "createdAt": "2025-10-23T06:49:57.837Z" } ], "questions": [ { "id": 0, "text": "@human: Should we strip ANSI codes from result.content (option A), or return both raw and formatted content with a flag (option B)?", "selected": true, "answer": "Option C: Remove chalk from showFeature() function. This is architecturally correct (separation of concerns), fixes the file-writing bug, makes tests pass without changes, and follows Single Responsibility Principle - the function generates data, the command handles display.", "deleted": false, "createdAt": "2025-10-23T06:49:57.837Z" } ], "estimate": 1, "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 1, "nextNoteId": 0 }, "BUG-040": { "id": "BUG-040", "title": "Duplicate installation success message in fspec init", "type": "story", "status": "done", "createdAt": "2025-10-23T21:04:30.882Z", "updatedAt": "2025-10-23T21:39:37.842Z", "description": "fspec init displays two similar messages: '✓ Installed fspec for claude' and '✓ Installed fspec for Claude Code'. The last message is redundant and should be removed.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T21:04:35.481Z" }, { "state": "testing", "timestamp": "2025-10-23T21:33:27.411Z" }, { "state": "implementing", "timestamp": "2025-10-23T21:36:15.622Z" }, { "state": "validating", "timestamp": "2025-10-23T21:36:51.749Z" }, { "state": "done", "timestamp": "2025-10-23T21:39:37.842Z" } ], "userStory": { "role": "developer using fspec", "action": "see clear non-duplicate success messages after initialization", "benefit": "I understand installation status without confusion" }, "rules": [ { "id": 0, "text": "Only one success message should be displayed after installation completes", "deleted": false, "createdAt": "2025-10-23T21:04:30.882Z" }, { "id": 1, "text": "The success message should include agent name, installed files, and next steps", "deleted": false, "createdAt": "2025-10-23T21:04:30.882Z" }, { "id": 2, "text": "The duplicate final message (\"✓ Installed fspec for Claude Code\") should be removed", "deleted": false, "createdAt": "2025-10-23T21:04:30.882Z" } ], "examples": [ { "id": 0, "text": "Running 'fspec init' for Claude Code shows: '✓ Installed fspec for claude' with file list and next steps, then '✓ Installed fspec for Claude Code' (CURRENT BEHAVIOR - duplicate)", "deleted": false, "createdAt": "2025-10-23T21:04:30.882Z" }, { "id": 1, "text": "Running 'fspec init' for Claude Code should show: '✓ Installed fspec for claude' with file list and next steps, WITHOUT the final duplicate message (EXPECTED BEHAVIOR)", "deleted": false, "createdAt": "2025-10-23T21:04:30.882Z" }, { "id": 2, "text": "Other agents (Cursor, Cline, Windsurf, etc.) should also show only one success message without duplicates", "deleted": false, "createdAt": "2025-10-23T21:04:30.882Z" } ], "estimate": 2, "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "RES-002": { "id": "RES-002", "title": "Research framework with custom script integration", "type": "story", "status": "done", "createdAt": "2025-10-23T21:16:17.909Z", "updatedAt": "2025-10-24T12:45:54.713Z", "description": "Create core research framework that allows users to select from available research endpoints (custom scripts like hooks) during Example Mapping. Should prompt users to research questions before/during Example Mapping sessions, display available tools, and execute selected research scripts.", "epic": "research-tools", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T21:16:48.878Z" }, { "state": "testing", "timestamp": "2025-10-24T12:41:20.597Z" }, { "state": "implementing", "timestamp": "2025-10-24T12:42:53.619Z" }, { "state": "validating", "timestamp": "2025-10-24T12:43:43.757Z" }, { "state": "done", "timestamp": "2025-10-24T12:45:54.713Z" } ], "userStory": { "role": "developer using fspec during Example Mapping", "action": "research questions using external tools before defining acceptance criteria", "benefit": "I make informed decisions based on external knowledge sources" }, "questions": [ { "id": 0, "text": "@human: Should the research command be interactive (prompts user step-by-step) or CLI-based with flags (e.g., fspec research --tool=perplexity --query='question')?", "selected": true, "answer": "CLI-based with flags. Running 'fspec research' without flags displays instructional output for AI agents: lists available tools, their descriptions, and usage examples with --tool= flag. Example: 'fspec research --tool=perplexity --query=\"question\"'. The instructional output guides AI to use the correct tool and syntax.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 1, "text": "@human: How should research scripts be stored? Should we use a similar structure to hooks (e.g., spec/research-scripts/)?", "selected": true, "answer": "Yes, use similar structure to hooks. Research scripts stored in spec/research-scripts/ directory. Each tool is a script file (e.g., spec/research-scripts/perplexity.sh, spec/research-scripts/jira.sh, spec/research-scripts/confluence.sh).", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 2, "text": "@human: Should research results be automatically attached to work units, or should the user manually decide what to attach?", "selected": true, "answer": "Prompt user to attach research results. After research completes, ask: 'Attach research results to work unit RES-XXX? (y/n)'. If yes, save as attachment and optionally add to architecture notes/example mapping data. If no, display results only (user can refine query or run additional research).", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 3, "text": "@human: Should fspec prompt to research during Example Mapping automatically, or should it be manually invoked with 'fspec research'?", "selected": true, "answer": "Automatically prompt during Example Mapping. When user adds a question with 'fspec add-question', system asks: 'Would you like to research this question? (y/n)'. If yes, display available research tools and guide user to run 'fspec research --tool=<name> --query=\"question\"'. User can also manually invoke 'fspec research' anytime.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 4, "text": "@human: What should the research script interface look like? Should scripts receive JSON context via stdin (like hooks) and return JSON results via stdout?", "selected": true, "answer": "Research scripts are standalone CLI tools (like fspec). Each script defines its own interface, flags, and output format. When 'fspec research' lists tools, it shows how to get help (e.g., 'perplexity --help'). AI agents learn tool usage from tool's own documentation/help output. Tools return results in their chosen format (JSON, text, markdown, etc.), and AI interprets the response. No mandated stdin/stdout contract.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 5, "text": "@human: Should there be a registry of available research tools (similar to tags.json), or should tools be auto-discovered from the research-scripts directory?", "selected": true, "answer": "Auto-discover tools from spec/research-scripts/ directory. No registry file needed. fspec scans directory for executable scripts, lists them when running 'fspec research' without flags. Tool names derived from filenames (e.g., perplexity.sh → 'perplexity'). Discovery happens dynamically at runtime.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" } ], "rules": [ { "id": 0, "text": "CLI-based with flags. Running 'fspec research' without flags displays instructional output for AI agents: lists available tools, their descriptions, and usage examples with --tool= flag. Example: 'fspec research --tool=perplexity --query=\"question\"'. The instructional output guides AI to use the correct tool and syntax.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 1, "text": "Yes, use similar structure to hooks. Research scripts stored in spec/research-scripts/ directory. Each tool is a script file (e.g., spec/research-scripts/perplexity.sh, spec/research-scripts/jira.sh, spec/research-scripts/confluence.sh).", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 2, "text": "Yes, automatically attach research results to work units. Results saved as attachments and referenced in example mapping data. Architecture notes in feature files should reference research findings where appropriate. Example: 'Research via Perplexity on 2025-10-24: [summary]' in architecture notes section.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 3, "text": "Prompt user to attach research results. After research completes, ask: 'Attach research results to work unit RES-XXX? (y/n)'. If yes, save as attachment and optionally add to architecture notes/example mapping data. If no, display results only (user can refine query or run additional research).", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 4, "text": "Automatically prompt during Example Mapping. When user adds a question with 'fspec add-question', system asks: 'Would you like to research this question? (y/n)'. If yes, display available research tools and guide user to run 'fspec research --tool=<name> --query=\"question\"'. User can also manually invoke 'fspec research' anytime.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 5, "text": "Research scripts are standalone CLI tools (like fspec). Each script defines its own interface, flags, and output format. When 'fspec research' lists tools, it shows how to get help (e.g., 'perplexity --help'). AI agents learn tool usage from tool's own documentation/help output. Tools return results in their chosen format (JSON, text, markdown, etc.), and AI interprets the response. No mandated stdin/stdout contract.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 6, "text": "Auto-discover tools from spec/research-scripts/ directory. No registry file needed. fspec scans directory for executable scripts, lists them when running 'fspec research' without flags. Tool names derived from filenames (e.g., perplexity.sh → 'perplexity'). Discovery happens dynamically at runtime.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 7, "text": "Auto-discover research tools by scanning spec/research-scripts/ for ANY executable files (not just .sh - could be .py, .js, compiled binaries, etc.). Check executable bit, not file extension.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'fspec research' without flags, sees list of available tools: perplexity, jira, confluence, with descriptions and usage examples for each", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 1, "text": "Developer runs 'fspec research --tool=perplexity --query=\"How does OAuth2 work?\"', tool executes and returns formatted results, system asks 'Attach research results to work unit? (y/n)'", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 2, "text": "During Example Mapping, developer runs 'fspec add-question AUTH-001 \"@human: Should we support OAuth2?\"', system prompts 'Would you like to research this question? (y/n)'", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 3, "text": "Developer chooses to attach results, research output saved to spec/attachments/AUTH-001/perplexity-oauth2-research-2025-10-24.md and referenced in work unit", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" }, { "id": 4, "text": "Research directory contains perplexity.py (Python), jira (compiled binary), confluence.js (Node). fspec auto-discovers all three by executable bit, derives names: 'perplexity', 'jira', 'confluence'.", "deleted": false, "createdAt": "2025-10-23T21:16:17.909Z" } ], "estimate": 5, "nextRuleId": 8, "nextExampleId": 5, "nextQuestionId": 6, "nextNoteId": 0 }, "RES-003": { "id": "RES-003", "title": "Perplexity research tool integration", "type": "story", "status": "done", "createdAt": "2025-10-23T21:16:30.953Z", "updatedAt": "2025-11-08T01:46:08.882Z", "description": "Create custom script for Perplexity API integration. Allows users to research questions using Perplexity during Example Mapping. Script should accept question input, call Perplexity API, and return formatted research results.", "epic": "research-tools", "children": [], "dependsOn": [ "RES-002" ], "nextRuleId": 8, "nextExampleId": 10, "nextQuestionId": 0, "nextNoteId": 0, "attachments": [ "spec/attachments/RES-003/RES-003-perplexity-integration-design.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T00:37:33.164Z" }, { "state": "testing", "timestamp": "2025-11-08T00:50:01.770Z" }, { "state": "implementing", "timestamp": "2025-11-08T01:33:40.342Z" }, { "state": "validating", "timestamp": "2025-11-08T01:44:23.149Z" }, { "state": "done", "timestamp": "2025-11-08T01:46:08.882Z" } ], "userStory": { "role": "AI agent or developer using fspec", "action": "research questions using Perplexity during Example Mapping", "benefit": "I get real-time AI-powered search results to inform acceptance criteria" }, "rules": [ { "id": 0, "text": "Script must be auto-discoverable in spec/research-scripts/ with executable bit set (framework scans for any executable file, not just .sh)", "deleted": false, "createdAt": "2025-11-08T00:38:04.851Z" }, { "id": 1, "text": "Script must be standalone with its own CLI interface supporting flags: --query (required), --help, --format (markdown/json/text), --model", "deleted": false, "createdAt": "2025-11-08T00:38:12.943Z" }, { "id": 2, "text": "API key must be stored in user-level config ~/.fspec/fspec-config.json under research.perplexity.apiKey (NOT project-level)", "deleted": false, "createdAt": "2025-11-08T00:38:13.450Z" }, { "id": 3, "text": "Script must support multiple output formats: markdown (default), json, text", "deleted": false, "createdAt": "2025-11-08T00:38:13.957Z" }, { "id": 4, "text": "Script must provide comprehensive help text with --help flag showing usage, options, examples, configuration, and exit codes", "deleted": false, "createdAt": "2025-11-08T00:38:14.468Z" }, { "id": 5, "text": "Script must handle errors with proper exit codes: 1 (missing args), 2 (config errors), 3 (API/network errors)", "deleted": false, "createdAt": "2025-11-08T00:38:21.698Z" }, { "id": 6, "text": "Script uses Perplexity API POST /chat/completions endpoint with Bearer token authentication", "deleted": false, "createdAt": "2025-11-08T00:38:22.201Z" }, { "id": 7, "text": "Default model is llama-3.1-sonar-small-128k-online (overridable via --model flag or config)", "deleted": false, "createdAt": "2025-11-08T00:38:22.712Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'perplexity --query \"How does OAuth2 work?\"', receives markdown-formatted research results with source, date, answer, and token usage", "deleted": false, "createdAt": "2025-11-08T00:38:34.724Z" }, { "id": 1, "text": "Developer runs 'perplexity --query \"What is BDD?\" --format json', receives JSON output with query, source, model, timestamp, answer, and usage fields", "deleted": false, "createdAt": "2025-11-08T00:38:35.240Z" }, { "id": 2, "text": "Developer runs 'perplexity --query \"Explain ACDD\" --format text', receives plain text answer without metadata", "deleted": false, "createdAt": "2025-11-08T00:38:35.748Z" }, { "id": 3, "text": "Developer runs 'perplexity --help', sees comprehensive help text with usage, options, examples, configuration instructions, and exit codes", "deleted": false, "createdAt": "2025-11-08T00:38:43.627Z" }, { "id": 4, "text": "Developer runs 'perplexity' without --query flag, script exits with code 1 and error message: 'Error: Missing required flag --query'", "deleted": false, "createdAt": "2025-11-08T00:38:44.138Z" }, { "id": 5, "text": "Developer runs perplexity but ~/.fspec/fspec-config.json doesn't exist, script exits with code 2 and shows config setup instructions", "deleted": false, "createdAt": "2025-11-08T00:38:44.642Z" }, { "id": 6, "text": "Developer runs perplexity with invalid API key, Perplexity API returns 401, script exits with code 3 and shows API error details", "deleted": false, "createdAt": "2025-11-08T00:38:53.500Z" }, { "id": 7, "text": "Developer hits rate limit, Perplexity API returns 429, script exits with code 3 and shows 'Rate limit exceeded. Retry after 60s' message", "deleted": false, "createdAt": "2025-11-08T00:38:54.008Z" }, { "id": 8, "text": "fspec research framework scans spec/research-scripts/, finds executable perplexity file, auto-discovers it as available tool", "deleted": false, "createdAt": "2025-11-08T00:38:54.517Z" }, { "id": 9, "text": "Developer runs 'fspec research --tool=perplexity --query \"OAuth2 token refresh\"', framework executes script and prompts 'Attach results to work unit? (y/n)', results saved to spec/attachments/AUTH-001/perplexity-oauth2-refresh-2025-11-07.md", "deleted": false, "createdAt": "2025-11-08T00:39:02.162Z" } ], "estimate": 5, "questions": [], "architectureNotes": [], "updated": "2025-11-08T01:46:08.882Z" }, "RES-004": { "id": "RES-004", "title": "JIRA research tool integration", "type": "story", "status": "done", "createdAt": "2025-10-23T21:16:31.444Z", "updatedAt": "2025-11-08T01:46:17.324Z", "description": "Create custom script for JIRA API integration. Allows users to search JIRA issues, tickets, and documentation during Example Mapping. Script should support querying by project, labels, status, and return relevant issue details.", "epic": "research-tools", "children": [], "dependsOn": [ "RES-002", "RES-003" ], "nextRuleId": 8, "nextExampleId": 10, "nextQuestionId": 0, "nextNoteId": 0, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T00:44:14.787Z" }, { "state": "testing", "timestamp": "2025-11-08T00:53:51.966Z" }, { "state": "implementing", "timestamp": "2025-11-08T01:38:40.823Z" }, { "state": "validating", "timestamp": "2025-11-08T01:44:35.122Z" }, { "state": "done", "timestamp": "2025-11-08T01:46:17.325Z" } ], "userStory": { "role": "AI agent or developer using fspec", "action": "search JIRA issues and tickets during Example Mapping", "benefit": "I can reference existing work items and requirements from JIRA" }, "rules": [ { "id": 0, "text": "Script must be auto-discoverable in spec/research-scripts/ with executable bit set", "deleted": false, "createdAt": "2025-11-08T00:44:34.993Z" }, { "id": 1, "text": "Script must be standalone with CLI interface supporting flags: --query (JQL query), --issue (issue key), --project (project key), --help, --format (markdown/json/text)", "deleted": false, "createdAt": "2025-11-08T00:44:35.523Z" }, { "id": 2, "text": "JIRA credentials (URL, username, API token) must be stored in user-level config ~/.fspec/fspec-config.json under research.jira (NOT project-level)", "deleted": false, "createdAt": "2025-11-08T00:44:36.040Z" }, { "id": 3, "text": "Script must support multiple output formats: markdown (default), json, text", "deleted": false, "createdAt": "2025-11-08T00:44:36.555Z" }, { "id": 4, "text": "Script must provide comprehensive help text with --help flag showing usage, options, JQL examples, configuration, and exit codes", "deleted": false, "createdAt": "2025-11-08T00:44:44.867Z" }, { "id": 5, "text": "Script must handle errors with proper exit codes: 1 (missing args/invalid input), 2 (config/auth errors), 3 (API/network errors)", "deleted": false, "createdAt": "2025-11-08T00:44:45.399Z" }, { "id": 6, "text": "Script uses JIRA REST API v2 or v3 with Basic authentication (username + API token)", "deleted": false, "createdAt": "2025-11-08T00:44:45.917Z" }, { "id": 7, "text": "Script must support JQL (JIRA Query Language) for advanced issue filtering", "deleted": false, "createdAt": "2025-11-08T00:44:46.435Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'jira --issue AUTH-123', receives markdown-formatted issue details with key, summary, description, status, assignee, labels", "deleted": false, "createdAt": "2025-11-08T00:44:55.289Z" }, { "id": 1, "text": "Developer runs 'jira --project MYPROJ --format json', receives JSON array of issues in the project with key, summary, status fields", "deleted": false, "createdAt": "2025-11-08T00:44:55.828Z" }, { "id": 2, "text": "Developer runs 'jira --query \"project = AUTH AND status = Open\"', receives issues matching JQL query in markdown format", "deleted": false, "createdAt": "2025-11-08T00:44:56.339Z" }, { "id": 3, "text": "Developer runs 'jira --help', sees comprehensive help with usage, JQL examples, config instructions, exit codes", "deleted": false, "createdAt": "2025-11-08T00:45:04.619Z" }, { "id": 4, "text": "Developer runs 'jira' without any flags, script exits with code 1 and error: 'Error: At least one of --query, --issue, or --project is required'", "deleted": false, "createdAt": "2025-11-08T00:45:05.132Z" }, { "id": 5, "text": "Developer runs jira but ~/.fspec/fspec-config.json is missing JIRA config, script exits with code 2 and shows config setup instructions with jiraUrl, username, apiToken fields", "deleted": false, "createdAt": "2025-11-08T00:45:05.650Z" }, { "id": 6, "text": "Developer runs jira with invalid API token, JIRA API returns 401 Unauthorized, script exits with code 2 and shows authentication error", "deleted": false, "createdAt": "2025-11-08T00:45:16.368Z" }, { "id": 7, "text": "Developer runs 'jira --issue INVALID-999', JIRA API returns 404 Not Found, script exits with code 3 and shows 'Issue not found' error", "deleted": false, "createdAt": "2025-11-08T00:45:16.875Z" }, { "id": 8, "text": "fspec research framework scans spec/research-scripts/, finds executable jira file, auto-discovers it as available tool", "deleted": false, "createdAt": "2025-11-08T00:45:17.385Z" }, { "id": 9, "text": "Developer runs 'fspec research --tool=jira --query=\"project = AUTH\" during Example Mapping, framework executes script, prompts to attach results, saves to spec/attachments/WORK-001/jira-auth-issues-{date}.md", "deleted": false, "createdAt": "2025-11-08T00:45:17.901Z" } ], "estimate": 5, "questions": [], "architectureNotes": [], "updated": "2025-11-08T01:46:17.324Z" }, "RES-005": { "id": "RES-005", "title": "Confluence research tool integration", "type": "story", "status": "done", "createdAt": "2025-10-23T21:16:31.938Z", "updatedAt": "2025-11-08T01:46:24.106Z", "description": "Create custom script for Confluence API integration. Allows users to search Confluence pages and documentation during Example Mapping. Script should support full-text search and return page summaries with links.", "epic": "research-tools", "children": [], "dependsOn": [ "RES-002", "RES-003" ], "nextRuleId": 8, "nextExampleId": 10, "nextQuestionId": 0, "nextNoteId": 0, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T00:46:27.848Z" }, { "state": "testing", "timestamp": "2025-11-08T00:57:28.280Z" }, { "state": "implementing", "timestamp": "2025-11-08T01:39:40.966Z" }, { "state": "validating", "timestamp": "2025-11-08T01:44:48.083Z" }, { "state": "done", "timestamp": "2025-11-08T01:46:24.106Z" } ], "userStory": { "role": "AI agent or developer using fspec", "action": "search Confluence pages and documentation during Example Mapping", "benefit": "I can reference existing documentation and knowledge base articles" }, "rules": [ { "id": 0, "text": "Script must be auto-discoverable in spec/research-scripts/ with executable bit set", "deleted": false, "createdAt": "2025-11-08T00:46:44.335Z" }, { "id": 1, "text": "Script must be standalone with CLI interface supporting flags: --query (full-text search), --space (space key), --page (page title), --help, --format (markdown/json/text)", "deleted": false, "createdAt": "2025-11-08T00:46:44.842Z" }, { "id": 2, "text": "Confluence credentials (URL, username, API token) must be stored in user-level config ~/.fspec/fspec-config.json under research.confluence (NOT project-level)", "deleted": false, "createdAt": "2025-11-08T00:46:45.353Z" }, { "id": 3, "text": "Script must support multiple output formats: markdown (default), json, text", "deleted": false, "createdAt": "2025-11-08T00:46:45.863Z" }, { "id": 4, "text": "Script must provide comprehensive help text with --help flag showing usage, options, search examples, configuration, and exit codes", "deleted": false, "createdAt": "2025-11-08T00:46:55.125Z" }, { "id": 5, "text": "Script must handle errors with proper exit codes: 1 (missing args/invalid input), 2 (config/auth errors), 3 (API/network errors)", "deleted": false, "createdAt": "2025-11-08T00:46:55.669Z" }, { "id": 6, "text": "Script uses Confluence REST API v2 with Basic authentication (username + API token)", "deleted": false, "createdAt": "2025-11-08T00:46:56.213Z" }, { "id": 7, "text": "Script must support CQL (Confluence Query Language) for advanced page searching and full-text search", "deleted": false, "createdAt": "2025-11-08T00:46:56.722Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'confluence --query \"API documentation\"', receives markdown-formatted list of pages with titles, space keys, excerpts, and URLs", "deleted": false, "createdAt": "2025-11-08T00:47:05.500Z" }, { "id": 1, "text": "Developer runs 'confluence --space DOCS --format json', receives JSON array of pages in the DOCS space with id, title, excerpt, url fields", "deleted": false, "createdAt": "2025-11-08T00:47:06.021Z" }, { "id": 2, "text": "Developer runs 'confluence --page \"Authentication Guide\"', receives full page content in markdown format with title, body, last modified date", "deleted": false, "createdAt": "2025-11-08T00:47:06.537Z" }, { "id": 3, "text": "Developer runs 'confluence --help', sees comprehensive help with usage, search examples, CQL syntax, config instructions, exit codes", "deleted": false, "createdAt": "2025-11-08T00:47:15.117Z" }, { "id": 4, "text": "Developer runs 'confluence' without any flags, script exits with code 1 and error: 'Error: At least one of --query, --space, or --page is required'", "deleted": false, "createdAt": "2025-11-08T00:47:15.623Z" }, { "id": 5, "text": "Developer runs confluence but ~/.fspec/fspec-config.json is missing Confluence config, script exits with code 2 and shows config setup instructions with confluenceUrl, username, apiToken fields", "deleted": false, "createdAt": "2025-11-08T00:47:16.142Z" }, { "id": 6, "text": "Developer runs confluence with invalid API token, Confluence API returns 401 Unauthorized, script exits with code 2 and shows authentication error", "deleted": false, "createdAt": "2025-11-08T00:47:27.742Z" }, { "id": 7, "text": "Developer runs 'confluence --page \"NonExistent Page\"', Confluence API returns 404 or empty results, script exits with code 3 and shows 'Page not found' error", "deleted": false, "createdAt": "2025-11-08T00:47:28.262Z" }, { "id": 8, "text": "fspec research framework scans spec/research-scripts/, finds executable confluence file, auto-discovers it as available tool", "deleted": false, "createdAt": "2025-11-08T00:47:28.773Z" }, { "id": 9, "text": "Developer runs 'fspec research --tool=confluence --query=\"OAuth implementation\" during Example Mapping, framework executes script, prompts to attach results, saves to spec/attachments/WORK-001/confluence-oauth-docs-{date}.md", "deleted": false, "createdAt": "2025-11-08T00:47:29.287Z" } ], "estimate": 5, "questions": [], "architectureNotes": [], "updated": "2025-11-08T01:46:24.106Z" }, "BOARD-004": { "id": "BOARD-004", "title": "Work unit ordering across all Kanban columns", "type": "story", "status": "done", "createdAt": "2025-10-23T22:15:34.560Z", "updatedAt": "2025-10-24T00:03:50.764Z", "description": "Enable prioritize-work-unit command to work on all Kanban columns (backlog, specifying, testing, implementing, validating, blocked) except done. Currently limited to backlog only.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T22:15:39.164Z" }, { "state": "testing", "timestamp": "2025-10-23T23:50:36.338Z" }, { "state": "implementing", "timestamp": "2025-10-23T23:54:44.248Z" }, { "state": "validating", "timestamp": "2025-10-24T00:03:35.959Z" }, { "state": "done", "timestamp": "2025-10-24T00:03:50.764Z" } ], "rules": [ { "id": 0, "text": "Currently: prioritize-work-unit only works for backlog status, throws error for other statuses", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 1, "text": "Change: Allow prioritize-work-unit to work on backlog, specifying, testing, implementing, validating, blocked statuses (NOT done)", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 2, "text": "CRITICAL: prioritize-work-unit can ONLY reorder within the same column (same status). Cannot move work units between columns or reference work units in different columns.", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 3, "text": "If --before or --after references a work unit in a different column, throw error with clear message", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 4, "text": "If work unit is in done status, throw error AND emit system-reminder explaining done work units cannot be reordered", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 5, "text": "Files requiring updates: src/commands/prioritize-work-unit.ts (lines 36-41, 91), src/commands/prioritize-work-unit-help.ts (lines 5, 8, 9, 25, 29, examples, commonErrors 66-67, typicalWorkflow 76, notes 96+100), src/help.ts (prioritize section), spec/features/kanban-workflow-state-management.feature (prioritize scenarios and validation)", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 6, "text": "Update command description to: 'Reorder work units in any Kanban column except done'", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 7, "text": "If work unit is the only item in its column, allow prioritization and succeed as no-op (idempotent operation)", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 8, "text": "Update spec/features/kanban-workflow-state-management.feature: modify existing prioritize scenarios to test multi-column prioritization, remove validation scenario that tests 'Can only prioritize work units in backlog state' error (no longer valid)", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 9, "text": "Update test files (src/commands/__tests__/kanban-workflow-state-management.test.ts and others): modify tests to cover multi-column prioritization, remove tests that specifically validate 'backlog-only' constraint (no longer valid)", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec prioritize-work-unit FEAT-017 --position top' where FEAT-017 is in specifying status. Command reorders FEAT-017 to top of specifying column (states.specifying array).", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 1, "text": "User runs 'fspec prioritize-work-unit FEAT-017 --before AUTH-001' where FEAT-017 is in specifying and AUTH-001 is in testing. Command throws error: 'Cannot prioritize across columns. FEAT-017 (specifying) and AUTH-001 (testing) are in different columns.'", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 2, "text": "User runs 'fspec prioritize-work-unit AUTH-001 --position top' where AUTH-001 is in done status. Command throws error and emits: '<system-reminder>Cannot prioritize work units in done column. Done items are ordered by completion time and cannot be manually reordered. Only backlog, specifying, testing, implementing, validating, blocked can be prioritized.</system-reminder>'", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 3, "text": "Help text shows: 'fspec prioritize-work-unit - Reorder work units in any Kanban column except done'", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 4, "text": "AUTH-001 is only item in implementing column. User runs 'fspec prioritize-work-unit AUTH-001 --position top'. Command succeeds with message: '✓ Work unit AUTH-001 prioritized successfully' (no error, no-op).", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 5, "text": "Old scenario: 'Attempt to prioritize work not in backlog' tests error when implementing work unit is prioritized. REMOVE this scenario (no longer an error). Add new scenarios testing prioritization in specifying, testing, implementing, validating, blocked columns.", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" }, { "id": 6, "text": "Old test: 'should throw error when prioritizing work unit in implementing status' - REMOVE (no longer an error). Add new tests: 'should prioritize work unit in specifying column', 'should prioritize work unit in implementing column', etc.", "deleted": false, "createdAt": "2025-10-23T22:15:34.560Z" } ], "userStory": { "role": "developer managing work priorities", "action": "reorder work units in any Kanban column except done", "benefit": "I can adjust priorities throughout the workflow, not just in backlog" }, "nextRuleId": 10, "nextExampleId": 7, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-008": { "id": "CLI-008", "title": "Release command for reviewing changes and creating tagged releases", "type": "story", "status": "done", "createdAt": "2025-10-23T22:43:00.893Z", "updatedAt": "2025-10-24T00:50:36.088Z", "description": "Add /release slash command that: 1) Reviews all code changes since last git tag, 2) Creates commit with Roland Quast <rquast@rolandquast.com> details (not Claude's), 3) Tags the release, 4) Does NOT push (manual step). Command analyzes commit history and code changes for release notes.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T22:43:08.685Z" }, { "state": "testing", "timestamp": "2025-10-24T00:47:26.404Z" }, { "state": "implementing", "timestamp": "2025-10-24T00:47:47.538Z" }, { "state": "validating", "timestamp": "2025-10-24T00:49:56.096Z" }, { "state": "done", "timestamp": "2025-10-24T00:50:36.088Z" } ], "rules": [ { "id": 0, "text": "Implement as slash command for Claude Code in .claude/commands/release.md (NOT an fspec CLI command)", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 1, "text": "Commit author must be Roland Quast <rquast@rolandquast.com>, NOT Claude's default author", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 2, "text": "Review all git commits since last tag using git log", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 3, "text": "Analyze code changes in those commits for release notes", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 4, "text": "Create git tag for the release version", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 5, "text": "Do NOT push to remote (user must push manually)", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 6, "text": "Use conventional commits to determine semver bump: BREAKING CHANGE = major, feat = minor, fix = patch", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 7, "text": "Review ALL code changes line-by-line since last tag (not just commit messages)", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 8, "text": "Combine conventional commit analysis with actual code diff review to generate comprehensive release notes", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 9, "text": "Update package.json version field to match the new release version", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 10, "text": "Release commit message format: 'chore(release): v{version}' with full release notes in commit body (breaking changes, features, fixes sections)", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 11, "text": "If no previous git tag exists, use current package.json version as base for semver bump", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 12, "text": "Before creating release: 1) Stage and commit all uncommitted changes with descriptive message, 2) Run npm test, 3) Run npm run build, 4) Abort release if tests or build fail", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 13, "text": "When committing uncommitted changes before release: analyze changes and generate appropriate conventional commit message (not generic message)", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" } ], "examples": [ { "id": 0, "text": "Last tag is v0.3.0. Commits since: 'feat: add new command', 'fix: resolve bug'. Code diff shows 500 lines added. Claude reviews line-by-line, determines minor bump (feat), creates v0.3.1 tag with release notes combining commit analysis + code review.", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 1, "text": "Last tag v0.3.0, new version v0.3.1 determined. Command updates package.json from 'version: 0.3.0' to 'version: 0.3.1', creates commit with updated package.json, then creates v0.3.1 tag.", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 2, "text": "Commit message: 'chore(release): v0.3.1' with body containing '## Breaking Changes\\n(none)\\n\\n## Features\\n- Add new command\\n\\n## Fixes\\n- Resolve critical bug'", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 3, "text": "No previous tag. package.json shows 'version: 0.3.0'. Commits contain 'feat: new feature'. Bump to v0.4.0 (minor bump from package.json version).", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 4, "text": "User runs /release with uncommitted files. Command commits changes first, runs npm test (passes), runs npm run build (passes), then proceeds with release. If either fails, release is aborted with error message.", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" }, { "id": 5, "text": "Uncommitted changes include new test file and bug fix. Pre-release commit message: 'fix: resolve authentication bug and add test coverage' before proceeding with release commit.", "deleted": false, "createdAt": "2025-10-23T22:43:00.893Z" } ], "userStory": { "role": "developer using Claude Code", "action": "create tagged releases with comprehensive release notes", "benefit": "I can automate version bumping and release documentation based on conventional commits" }, "estimate": 5, "nextRuleId": 14, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-009": { "id": "CLI-009", "title": "Publish command for conditional npm publishing", "type": "story", "status": "done", "createdAt": "2025-10-23T22:43:01.389Z", "updatedAt": "2025-10-24T00:50:36.869Z", "description": "Add /publish slash command that: 1) Checks npm registry for @sengac/fspec current version, 2) Compares with local release tag, 3) Only publishes if version differs, 4) Prevents accidental duplicate publishing. Depends on release command being available.", "children": [], "dependsOn": [ "CLI-008" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T22:50:47.930Z" }, { "state": "testing", "timestamp": "2025-10-24T00:47:27.186Z" }, { "state": "implementing", "timestamp": "2025-10-24T00:47:48.316Z" }, { "state": "validating", "timestamp": "2025-10-24T00:49:56.870Z" }, { "state": "done", "timestamp": "2025-10-24T00:50:36.869Z" } ], "rules": [ { "id": 0, "text": "Implement as slash command for Claude Code in .claude/commands/publish.md (NOT an fspec CLI command)", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" }, { "id": 1, "text": "Verify git tag matches package.json version before comparing with npm registry (fail if mismatch)", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" }, { "id": 2, "text": "Compare package.json version with npm registry for @sengac/fspec - only publish if different", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" }, { "id": 3, "text": "If version already exists on npm registry, show message and exit successfully (not an error)", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" }, { "id": 4, "text": "No pre-publish testing or building - assume /release already validated. Only check version differences before publishing.", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" } ], "examples": [ { "id": 0, "text": "Git tag: v0.3.1, package.json: 0.3.1, npm registry: 0.3.0. Versions match locally, differs from npm. Command proceeds with npm publish.", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" }, { "id": 1, "text": "Git tag: v0.3.1, package.json: 0.3.0, npm registry: 0.3.0. Mismatch detected. Command fails with error: 'Version mismatch: git tag (v0.3.1) does not match package.json (0.3.0). Run /release first.'", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" }, { "id": 2, "text": "Git tag: v0.3.0, package.json: 0.3.0, npm registry: 0.3.0. Command shows: 'Version 0.3.0 already published to npm. Skipping.' and exits successfully (exit code 0).", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" }, { "id": 3, "text": "User runs /publish after /release. Command checks: git tag (v0.3.1) matches package.json (0.3.1), differs from npm (0.3.0). Runs npm publish directly without tests/build.", "deleted": false, "createdAt": "2025-10-23T22:43:01.389Z" } ], "userStory": { "role": "developer using Claude Code", "action": "publish releases to npm only if version differs from registry", "benefit": "I prevent accidental duplicate publishing" }, "estimate": 3, "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-010": { "id": "CLI-010", "title": "Commit command with conventional commits and custom author", "type": "story", "status": "done", "createdAt": "2025-10-23T22:44:53.779Z", "updatedAt": "2025-10-24T00:50:37.643Z", "description": "Add /commit slash command that: 1) Analyzes all unstaged and staged files, 2) Stages all unstaged files, 3) Generates conventional commit message based on changes, 4) Creates commit with Roland Quast <rquast@rolandquast.com> author details (not Claude's), 5) Does NOT push (manual step).", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T22:53:59.997Z" }, { "state": "testing", "timestamp": "2025-10-24T00:47:27.962Z" }, { "state": "implementing", "timestamp": "2025-10-24T00:47:49.117Z" }, { "state": "validating", "timestamp": "2025-10-24T00:49:57.642Z" }, { "state": "done", "timestamp": "2025-10-24T00:50:37.643Z" } ], "rules": [ { "id": 0, "text": "Implement as slash command for Claude Code in .claude/commands/commit.md (NOT an fspec CLI command)", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" }, { "id": 1, "text": "Commit author must be Roland Quast <rquast@rolandquast.com>, NOT Claude's default author", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" }, { "id": 2, "text": "Stage all unstaged files before committing (git add .)", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" }, { "id": 3, "text": "Generate conventional commit message by analyzing staged files and changes", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" }, { "id": 4, "text": "Do NOT push to remote (user must push manually)", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" }, { "id": 5, "text": "If no unstaged or staged files exist (clean working directory), show message and exit successfully (not an error)", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" }, { "id": 6, "text": "Follow strict conventional commits spec: type(scope): description. Include body with detailed changes and footer with BREAKING CHANGE if applicable.", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" } ], "examples": [ { "id": 0, "text": "User runs /commit with clean working directory. Command shows: 'Nothing to commit, working directory clean.' and exits successfully.", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" }, { "id": 1, "text": "Unstaged files: src/commands/new-feature.ts (new file), src/types.ts (modified). Generated commit: 'feat(commands): add new feature command\\n\\nImplement new-feature command with TypeScript types and CLI integration.'", "deleted": false, "createdAt": "2025-10-23T22:44:53.779Z" } ], "userStory": { "role": "developer using Claude Code", "action": "create conventional commits with automated message generation", "benefit": "I maintain consistent commit history without manual message writing" }, "estimate": 3, "nextRuleId": 7, "nextExampleId": 2, "nextQuestionId": 0, "nextNoteId": 0 }, "RES-006": { "id": "RES-006", "title": "Stakeholder communication research script for unanswered questions", "type": "story", "status": "done", "createdAt": "2025-10-23T23:34:32.464Z", "updatedAt": "2025-11-08T05:05:12.614Z", "description": "Create research script that contacts stakeholders via chat platforms (Teams, Slack) when questions arise during Example Mapping that require human input. Integrates with fspec research framework to send questions and receive answers from project stakeholders.", "epic": "research-tools", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-23T23:34:38.818Z" }, { "state": "testing", "timestamp": "2025-11-08T03:42:11.645Z" }, { "state": "implementing", "timestamp": "2025-11-08T03:48:07.146Z" }, { "state": "validating", "timestamp": "2025-11-08T05:04:14.704Z" }, { "state": "done", "timestamp": "2025-11-08T05:05:12.614Z" } ], "rules": [ { "id": 0, "text": "Use plugin architecture where communication platforms (Teams, Slack, etc.) can be added dynamically without modifying core script", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 1, "text": "Main script stored in spec/research-scripts/stakeholder.sh, platform plugins stored in spec/research-scripts/plugins/ directory", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 2, "text": "Script is one-way notification only: sends message to stakeholders and exits. Does NOT wait for response or handle callbacks.", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 3, "text": "Message sender identity should be configurable (who the message appears to come from)", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 4, "text": "Store platform credentials and settings in user-level config: ~/.fspec/fspec-config.json (NOT project-level spec/fspec-config.json)", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 5, "text": "Message should include full context: question text, work unit ID, work unit title, epic (if any), existing rules, existing examples, and all questions/answers so far from Example Mapping", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 6, "text": "AI asks human which platform(s) to use. If no preference specified, default to all configured platforms in ~/.fspec/fspec-config.json", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 7, "text": "Auto-discover platform plugins by scanning spec/research-scripts/plugins/ directory for .sh files (no manifest/registry required)", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 8, "text": "Auto-discover platform plugins by scanning spec/research-scripts/plugins/ directory for ANY executable files (not just .sh - could be .py, .js, compiled binaries, etc.)", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=stakeholder --platform=teams --question=\"Should we support OAuth2?\"'. Main script loads spec/research-scripts/plugins/teams.sh and sends question via Teams API.", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 1, "text": "AI runs 'fspec research --tool=stakeholder --platform=slack --question=\"OAuth support needed?\"'. Script sends message to configured Slack channel from configured user, then exits. Stakeholder sees notification and responds manually later in Claude Code session.", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 2, "text": "User-level config at ~/.fspec/fspec-config.json contains Slack token and Teams webhook URL. Script reads from user config (not project config) to send stakeholder notifications.", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 3, "text": "Message sent to Slack: 'Question for AUTH-001 (User Login, epic: user-management)\\n\\nQuestion: Should we support OAuth2?\\n\\nRules:\\n1. Password must be 8+ chars\\n\\nExamples:\\n1. Valid login with email/password\\n\\nPrevious Q&A:\\nQ: Support 2FA? A: Yes, in phase 2'", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 4, "text": "AI asks: 'Send to Teams, Slack, or both?' Human says 'both'. Script sends to both platforms. If human doesn't specify, script checks config and sends to all configured platforms by default.", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 5, "text": "Plugins directory contains teams.sh and slack.sh. Main script auto-discovers both platforms and can send to either/both based on config and user preference.", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" }, { "id": 6, "text": "Plugins directory contains teams.py (Python), slack (compiled Go binary), and discord.js (Node script). Main script auto-discovers all three by checking executable bit, not file extension.", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" } ], "dependsOn": [ "CONFIG-001" ], "questions": [ { "id": 0, "text": "@human: How should multiple stakeholders work? (A) Single destination per invocation, (B) Multiple destinations via repeated --platform flags, (C) Send to all configured platforms at once?", "selected": true, "answer": "AI asks human which platform(s) to use. If no preference specified, default to all configured platforms in ~/.fspec/fspec-config.json", "deleted": false, "createdAt": "2025-10-23T23:34:32.464Z" } ], "nextRuleId": 9, "nextExampleId": 7, "nextQuestionId": 1, "nextNoteId": 0, "userStory": { "role": "AI agent or developer using fspec during Example Mapping", "action": "contact stakeholders via chat platforms when questions arise", "benefit": "I can get human input on unclear requirements without blocking progress" }, "estimate": 8, "architectureNotes": [], "updated": "2025-11-08T05:05:12.614Z" }, "CONFIG-001": { "id": "CONFIG-001", "title": "Shared configuration management utilities for user and project config files", "type": "story", "status": "done", "createdAt": "2025-10-23T23:38:52.558Z", "updatedAt": "2025-10-24T13:10:08.190Z", "description": "Create shared code/functions to manage config files: user-level (~/.fspec/fspec-config.json) and project-level (spec/fspec-config.json). Utilities should handle reading, writing, merging, validating config across both scopes with proper precedence rules.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T12:51:18.003Z" }, { "state": "testing", "timestamp": "2025-10-24T13:06:27.440Z" }, { "state": "implementing", "timestamp": "2025-10-24T13:08:19.621Z" }, { "state": "validating", "timestamp": "2025-10-24T13:08:20.311Z" }, { "state": "done", "timestamp": "2025-10-24T13:10:08.190Z" } ], "questions": [ { "id": 0, "text": "@human: What format should the config files use? Should both user-level and project-level use the same format?", "selected": true, "answer": "JSON format for both user-level (~/.fspec/fspec-config.json) and project-level (spec/fspec-config.json)", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 1, "text": "@human: When both user-level and project-level config files have the same setting, which takes precedence?", "selected": true, "answer": "Project-level config overrides user-level config (for project-specific overrides)", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 2, "text": "@human: How should nested config objects be merged? Deep merge (recursive) or shallow merge (replace entire objects)?", "selected": true, "answer": "Deep merge - merge nested objects recursively. This preserves user defaults while allowing project-specific overrides without duplication.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 3, "text": "@human: What types of settings should the config support? Specific schemas or generic JSON structure?", "selected": true, "answer": "Keep it generic - accept any JSON structure and let different features define their own config namespaces. No schema enforcement at the config utility level.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 4, "text": "@human: What should happen when config file doesn't exist, has invalid JSON, or is empty?", "selected": true, "answer": "File doesn't exist or is empty: return empty object {} (silent fallback). Invalid JSON syntax: throw error with helpful message (fail fast). Be lenient with absence, strict with mistakes.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" } ], "rules": [ { "id": 0, "text": "JSON format for both user-level (~/.fspec/fspec-config.json) and project-level (spec/fspec-config.json)", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 1, "text": "Project-level config overrides user-level config (for project-specific overrides)", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 2, "text": "Deep merge - merge nested objects recursively. This preserves user defaults while allowing project-specific overrides without duplication.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 3, "text": "Keep it generic - accept any JSON structure and let different features define their own config namespaces. No schema enforcement at the config utility level.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 4, "text": "File doesn't exist or is empty: return empty object {} (silent fallback). Invalid JSON syntax: throw error with helpful message (fail fast). Be lenient with absence, strict with mistakes.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" } ], "examples": [ { "id": 0, "text": "User has no config files. Call loadConfig() returns empty object {}. No errors thrown.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 1, "text": "User has ~/.fspec/fspec-config.json with {\"timeout\": 60}. Project has no config. loadConfig() returns {\"timeout\": 60}.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 2, "text": "User has {\"research\": {\"timeout\": 60, \"tools\": [\"perplexity\"]}}. Project has {\"research\": {\"tools\": [\"jira\"]}}. loadConfig() returns {\"research\": {\"timeout\": 60, \"tools\": [\"jira\"]}} via deep merge.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 3, "text": "Project config has invalid JSON syntax (missing bracket). loadConfig() throws error with message: 'Invalid JSON in spec/fspec-config.json: Unexpected token...'.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" }, { "id": 4, "text": "Developer calls writeConfig('user', {\"newSetting\": true}) and it writes to ~/.fspec/fspec-config.json with proper formatting.", "deleted": false, "createdAt": "2025-10-23T23:38:52.558Z" } ], "userStory": { "role": "developer using fspec", "action": "manage configuration across user-level and project-level scopes", "benefit": "I can set personal defaults and project-specific overrides without duplication" }, "estimate": 3, "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 5, "nextNoteId": 0 }, "BUG-041": { "id": "BUG-041", "title": "Data integrity validation missing in prioritize-work-unit", "type": "bug", "status": "done", "createdAt": "2025-10-24T00:13:14.350Z", "updatedAt": "2025-10-24T00:23:53.471Z", "description": "prioritize-work-unit doesn't validate that work unit ID exists in the states array matching its status field, which could cause duplicates or silent failures if data is corrupted", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T00:13:42.487Z" }, { "state": "testing", "timestamp": "2025-10-24T00:16:25.424Z" }, { "state": "implementing", "timestamp": "2025-10-24T00:17:51.849Z" }, { "state": "validating", "timestamp": "2025-10-24T00:23:51.839Z" }, { "state": "done", "timestamp": "2025-10-24T00:23:53.471Z" } ], "userStory": { "role": "developer using prioritize-work-unit", "action": "detect data corruption early with clear error messages", "benefit": "I can fix corrupted data before it causes silent failures or duplicates" }, "rules": [ { "id": 0, "text": "Work unit status field MUST match which states array it's in (e.g., status='specifying' must be in states.specifying)", "deleted": false, "createdAt": "2025-10-24T00:13:14.350Z" }, { "id": 1, "text": "If work unit status doesn't match its array location, throw error with repair suggestion", "deleted": false, "createdAt": "2025-10-24T00:13:14.350Z" }, { "id": 2, "text": "Validate work unit's own status matches its array before prioritizing", "deleted": false, "createdAt": "2025-10-24T00:13:14.350Z" }, { "id": 3, "text": "When using --before or --after, validate target work unit is in the same states array", "deleted": false, "createdAt": "2025-10-24T00:13:14.350Z" } ], "examples": [ { "id": 0, "text": "AUTH-001 has status='specifying' but is in states.testing array. User runs 'fspec prioritize-work-unit AUTH-001 --position top'. Command throws: 'Data integrity error: Work unit AUTH-001 has status specifying but is not in states.specifying array. Run fspec repair-work-units'", "deleted": false, "createdAt": "2025-10-24T00:13:14.350Z" }, { "id": 1, "text": "FEAT-017 is in specifying (correct). User runs 'fspec prioritize-work-unit FEAT-017 --before AUTH-001' where AUTH-001 status='specifying' but AUTH-001 is NOT in states.specifying. Command throws: 'Data integrity error: Work unit AUTH-001 has status specifying but is not in states.specifying array'", "deleted": false, "createdAt": "2025-10-24T00:13:14.350Z" }, { "id": 2, "text": "Work unit AUTH-001 has status='implementing' and IS in states.implementing array. User runs 'fspec prioritize-work-unit AUTH-001 --position top'. Command succeeds (data is valid)", "deleted": false, "createdAt": "2025-10-24T00:13:14.350Z" } ], "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-042": { "id": "BUG-042", "title": "1-based indexing not implemented in prioritize-work-unit", "type": "bug", "status": "done", "createdAt": "2025-10-24T00:13:20.575Z", "updatedAt": "2025-10-24T00:23:54.289Z", "description": "Help text says numeric positions are 1-based (e.g., position 3 = third item) but code uses 0-based array indices, causing off-by-one errors", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T00:15:09.744Z" }, { "state": "testing", "timestamp": "2025-10-24T00:16:26.241Z" }, { "state": "implementing", "timestamp": "2025-10-24T00:17:52.689Z" }, { "state": "validating", "timestamp": "2025-10-24T00:23:52.660Z" }, { "state": "done", "timestamp": "2025-10-24T00:23:54.289Z" } ], "userStory": { "role": "user running prioritize-work-unit with numeric positions", "action": "use intuitive 1-based positions matching help text", "benefit": "position 3 means third item as documented, not fourth item" }, "rules": [ { "id": 0, "text": "Help text says numeric positions are 1-based (position 1 = first item, position 3 = third item)", "deleted": false, "createdAt": "2025-10-24T00:13:20.575Z" }, { "id": 1, "text": "Code must convert 1-based user input to 0-based array indices (position - 1)", "deleted": false, "createdAt": "2025-10-24T00:13:20.575Z" }, { "id": 2, "text": "Position must be >= 1 (reject position 0 or negative)", "deleted": false, "createdAt": "2025-10-24T00:13:20.575Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec prioritize-work-unit AUTH-001 --position 1' expecting AUTH-001 to be first. AUTH-001 becomes first item (index 0).", "deleted": false, "createdAt": "2025-10-24T00:13:20.575Z" }, { "id": 1, "text": "User runs 'fspec prioritize-work-unit AUTH-001 --position 3' expecting AUTH-001 to be third. AUTH-001 becomes third item (index 2).", "deleted": false, "createdAt": "2025-10-24T00:13:20.575Z" }, { "id": 2, "text": "User runs 'fspec prioritize-work-unit AUTH-001 --position 0'. Command throws: 'Invalid position: 0. Position must be >= 1 (1-based index)'", "deleted": false, "createdAt": "2025-10-24T00:13:20.575Z" } ], "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "REFAC-002": { "id": "REFAC-002", "title": "Remove unused rootStubFile property from AgentConfig", "type": "task", "status": "done", "createdAt": "2025-10-24T02:43:22.040Z", "updatedAt": "2025-10-24T02:50:36.405Z", "description": "The rootStubFile property in AgentConfig interface and all agent definitions is dead code. It was used by installRootStub() function which was removed in commit 9286b71 to fix the CLAUDE.md deletion bug. Property is defined but never used anywhere in the codebase.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T02:43:37.519Z" }, { "state": "implementing", "timestamp": "2025-10-24T02:43:44.078Z" }, { "state": "validating", "timestamp": "2025-10-24T02:50:12.988Z" }, { "state": "done", "timestamp": "2025-10-24T02:50:36.405Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "GIT-005": { "id": "GIT-005", "title": "Wire up checkpoint CLI commands", "type": "bug", "status": "done", "createdAt": "2025-10-24T06:28:46.772Z", "updatedAt": "2025-10-24T06:35:23.743Z", "description": "Checkpoint commands (checkpoint, list-checkpoints, restore-checkpoint, cleanup-checkpoints) exist but are not registered in src/index.ts, making them inaccessible from CLI", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T06:28:52.895Z" }, { "state": "testing", "timestamp": "2025-10-24T06:31:20.857Z" }, { "state": "implementing", "timestamp": "2025-10-24T06:31:56.619Z" }, { "state": "validating", "timestamp": "2025-10-24T06:33:16.613Z" }, { "state": "done", "timestamp": "2025-10-24T06:35:23.743Z" } ], "userStory": { "role": "developer using fspec", "action": "use checkpoint commands from the CLI", "benefit": "I can create, list, restore, and cleanup checkpoints for safe experimentation" }, "rules": [ { "id": 0, "text": "All checkpoint command files must export a registerXCommand function that takes a Commander program instance", "deleted": false, "createdAt": "2025-10-24T06:28:46.772Z" }, { "id": 1, "text": "All checkpoint commands must be imported and registered in src/index.ts", "deleted": false, "createdAt": "2025-10-24T06:28:46.772Z" }, { "id": 2, "text": "Command registration must follow existing patterns (checkpoint, list-checkpoints, restore-checkpoint, cleanup-checkpoints)", "deleted": false, "createdAt": "2025-10-24T06:28:46.772Z" } ], "examples": [ { "id": 0, "text": "Running './dist/index.js checkpoint AUTH-001 baseline' creates a checkpoint named 'baseline' for work unit AUTH-001", "deleted": false, "createdAt": "2025-10-24T06:28:46.772Z" }, { "id": 1, "text": "Running './dist/index.js list-checkpoints AUTH-001' shows all checkpoints for AUTH-001 with emoji indicators", "deleted": false, "createdAt": "2025-10-24T06:28:46.772Z" }, { "id": 2, "text": "Running './dist/index.js restore-checkpoint AUTH-001 baseline' restores the baseline checkpoint for AUTH-001", "deleted": false, "createdAt": "2025-10-24T06:28:46.772Z" }, { "id": 3, "text": "Running './dist/index.js cleanup-checkpoints AUTH-001 --keep-last 5' deletes old checkpoints, keeping only the 5 most recent", "deleted": false, "createdAt": "2025-10-24T06:28:46.772Z" } ], "estimate": 2, "nextRuleId": 3, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-043": { "id": "BUG-043", "title": "Auto-checkpoints not working - lazy import fails in bundled dist", "type": "bug", "status": "done", "createdAt": "2025-10-24T06:47:47.525Z", "updatedAt": "2025-10-26T00:45:17.530Z", "description": "Automatic checkpoints are not being created during work unit status transitions. Root cause: Vite bundler incorrectly optimizes the conditional checkpoint logic, transforming 'const isDirty = await isWorkingDirectoryDirty(cwd); if (isDirty && currentStatus \\!== backlog)' into 'await Zn(t) && i \\!== backlog && (...)' which breaks execution flow. The checkpoint code never runs even when working directory is dirty.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T06:48:03.903Z" }, { "state": "testing", "timestamp": "2025-10-24T06:49:38.213Z" }, { "state": "implementing", "timestamp": "2025-10-24T06:52:17.885Z" }, { "state": "validating", "timestamp": "2025-10-24T06:55:32.218Z" }, { "state": "done", "timestamp": "2025-10-24T07:02:17.679Z" }, { "state": "specifying", "timestamp": "2025-10-26T00:28:54.282Z" }, { "state": "testing", "timestamp": "2025-10-26T00:30:49.092Z" }, { "state": "specifying", "timestamp": "2025-10-26T00:32:08.535Z" }, { "state": "testing", "timestamp": "2025-10-26T00:32:47.543Z" }, { "state": "implementing", "timestamp": "2025-10-26T00:33:06.146Z" }, { "state": "validating", "timestamp": "2025-10-26T00:36:50.075Z" }, { "state": "done", "timestamp": "2025-10-26T00:36:53.705Z" }, { "state": "specifying", "timestamp": "2025-10-26T00:37:48.477Z" }, { "state": "testing", "timestamp": "2025-10-26T00:37:50.459Z" }, { "state": "testing", "timestamp": "2025-10-26T00:39:44.883Z" }, { "state": "testing", "timestamp": "2025-10-26T00:39:57.483Z" }, { "state": "specifying", "timestamp": "2025-10-26T00:40:38.852Z" }, { "state": "testing", "timestamp": "2025-10-26T00:40:39.568Z" }, { "state": "specifying", "timestamp": "2025-10-26T00:41:05.034Z" }, { "state": "testing", "timestamp": "2025-10-26T00:41:11.762Z" }, { "state": "specifying", "timestamp": "2025-10-26T00:41:53.750Z" }, { "state": "testing", "timestamp": "2025-10-26T00:41:54.498Z" }, { "state": "specifying", "timestamp": "2025-10-26T00:42:23.020Z" }, { "state": "testing", "timestamp": "2025-10-26T00:42:24.107Z" }, { "state": "implementing", "timestamp": "2025-10-26T00:43:20.525Z" }, { "state": "validating", "timestamp": "2025-10-26T00:43:24.415Z" }, { "state": "done", "timestamp": "2025-10-26T00:45:17.530Z" } ], "userStory": { "role": "AI agent using fspec for ACDD workflow", "action": "have automatic checkpoints created reliably during work unit transitions", "benefit": "I can safely experiment and recover from mistakes without manual checkpoint creation" }, "rules": [ { "id": 0, "text": "Auto-checkpoints must be created before EVERY state transition (except from backlog)", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 1, "text": "Lazy imports must work after Vite bundling into single dist/index.js file", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 2, "text": "Auto-checkpoints must be created before EVERY state transition (except from backlog)", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 3, "text": "Checkpoint creation logic must survive Vite bundler optimization without breaking execution flow", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 4, "text": "Tests must validate BUNDLED distribution (dist/index.js), not just source code", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 5, "text": "No dynamic imports (await import()) allowed in checkpoint-related code - ONLY static imports at top of file", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" } ], "examples": [ { "id": 0, "text": "User transitions from backlog to specifying with dirty working directory, sees '🤖 Auto-checkpoint created' message", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 1, "text": "User transitions from specifying to testing with uncommitted changes, checkpoint saved before transition", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 2, "text": "User has uncommitted changes, runs 'fspec update-work-unit-status TEST-001 implementing' (from testing state), sees '🤖 Auto-checkpoint: TEST-001-auto-testing created before transition' message", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 3, "text": "User runs 'fspec list-checkpoints TEST-001' after transition, sees the auto-checkpoint in the list", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 4, "text": "User has clean working directory, runs status transition, NO checkpoint created (expected behavior)", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 5, "text": "User transitions FROM backlog state with uncommitted changes, NO checkpoint created (rule: except from backlog)", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 6, "text": "Integration test runs 'npm run build' then executes './dist/index.js update-work-unit-status' and verifies checkpoint is actually created", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" }, { "id": 7, "text": "Static analysis test scans update-work-unit-status.ts for 'await import' and fails if found", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" } ], "estimate": 3, "questions": [ { "id": 0, "text": "@human: Should we fix this by refactoring the conditional logic (Option 1: if-else chain), using explicit boolean assignment (Option 2), or configuring Vite to disable optimization (Option 3)?", "selected": true, "answer": "Use Option 2: explicit boolean assignment - clearest intent, prevents optimizer issues, maintains readability", "deleted": false, "createdAt": "2025-10-24T06:47:47.525Z" } ], "assumptions": [ "Use Option 2: explicit boolean assignment - clearest intent, prevents optimizer issues, maintains readability" ], "nextRuleId": 6, "nextExampleId": 8, "nextQuestionId": 1, "nextNoteId": 0 }, "CLI-011": { "id": "CLI-011", "title": "Slash command for critical story review with ULTRATHINK", "type": "story", "status": "done", "createdAt": "2025-10-24T13:23:11.621Z", "updatedAt": "2025-10-24T22:55:40.235Z", "description": "Create /review slash command in .claude/commands that critically analyzes stories using ULTRATHINK to identify logical flaws, bugs, anti-patterns, and refactoring opportunities", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T13:23:18.623Z" }, { "state": "testing", "timestamp": "2025-10-24T22:37:39.740Z" }, { "state": "implementing", "timestamp": "2025-10-24T22:40:01.575Z" }, { "state": "validating", "timestamp": "2025-10-24T22:41:43.753Z" }, { "state": "done", "timestamp": "2025-10-24T22:55:40.235Z" } ], "userStory": { "role": "developer using Claude Code with fspec", "action": "critically review a story's acceptance criteria, tests, implementation, and coverage", "benefit": "I can identify logical flaws, bugs, anti-patterns, and refactoring opportunities before they become problems" }, "rules": [ { "id": 0, "text": "Command must prompt user to specify work unit ID if none provided as argument", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 1, "text": "Must use ULTRATHINK mode for deep critical analysis of the story", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 2, "text": "Must analyze all aspects: acceptance criteria (feature file), tests, implementation code, and coverage mappings", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 3, "text": "Must identify: logical flaws, bugs introduced/created, anti-patterns, and refactoring opportunities", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 4, "text": "Must check if existing architecture/utilities could be reused instead of new code", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 5, "text": "Should read work unit metadata, linked feature file(s), test files from coverage, and implementation files from coverage", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 6, "text": "Review output should be structured: Issues Found, Recommendations, Refactoring Opportunities, ACDD Compliance", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 7, "text": "Yes, review should compare against similar completed stories using fspec query commands (get-scenarios, show-coverage, query-work-units) to identify inconsistencies in approach, naming conventions, and architectural patterns. If existing commands don't provide sufficient search capability, create a new story for enhanced search/comparison functionality as a dependency.", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 8, "text": "Yes, review must validate consistency with CLAUDE.md coding standards (no 'any' types, ES modules, proper imports, etc.) and FOUNDATION.md project requirements (alignment with project goals, personas, capabilities)", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 9, "text": "Yes, review must check if ACDD workflow was followed properly: verify temporal ordering (feature files created during specifying, tests before implementation), check for Example Mapping data (rules, examples, answered questions), validate state history timestamps align with file modification times", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 10, "text": "Yes, review output must include specific actionable next steps for each issue: show the problem, suggest the fix, and provide concrete commands or actions to resolve it (e.g., 'Issue: Using any type in file.ts:42 → Fix: Replace with proper interface. Action: Edit file.ts line 42 to use UserInterface type')", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 11, "text": "Yes, support reviewing multiple work units at once. Allow '/review CLI-001 CLI-002 CLI-003' syntax to review multiple stories in one go. Output should be structured per work unit with clear separators between reviews.", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" } ], "examples": [ { "id": 0, "text": "User runs '/review CLI-011', command loads work unit, reads feature file, analyzes tests and implementation, outputs structured review with identified issues", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 1, "text": "User runs '/review' without arguments, command asks 'Which work unit would you like me to review? Please provide the work unit ID (e.g., CLI-011)'", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 2, "text": "Review finds test that doesn't actually test the scenario it claims to test, suggests rewriting test to properly validate acceptance criteria", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 3, "text": "Review finds implementation using manual file operations when existing utility function in src/utils/ should be used instead, suggests refactoring", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 4, "text": "Review finds feature file scenario that doesn't have corresponding test coverage, flags as gap in coverage mapping", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 5, "text": "Review detects anti-pattern where code violates CLAUDE.md coding standards (using 'any' type instead of proper types), suggests specific fix", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" } ], "questions": [ { "id": 0, "text": "@human: Should the review compare against similar completed stories to identify inconsistencies or patterns?", "selected": true, "answer": "Yes, review should compare against similar completed stories using fspec query commands (get-scenarios, show-coverage, query-work-units) to identify inconsistencies in approach, naming conventions, and architectural patterns. If existing commands don't provide sufficient search capability, create a new story for enhanced search/comparison functionality as a dependency.", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 1, "text": "@human: Should it validate consistency with CLAUDE.md coding standards and FOUNDATION.md project requirements?", "selected": true, "answer": "Yes, review must validate consistency with CLAUDE.md coding standards (no 'any' types, ES modules, proper imports, etc.) and FOUNDATION.md project requirements (alignment with project goals, personas, capabilities)", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 2, "text": "@human: Should it check if the ACDD workflow was followed properly (temporal ordering, Example Mapping before specs, tests before implementation)?", "selected": true, "answer": "Yes, review must check if ACDD workflow was followed properly: verify temporal ordering (feature files created during specifying, tests before implementation), check for Example Mapping data (rules, examples, answered questions), validate state history timestamps align with file modification times", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 3, "text": "@human: Should the review output include specific actionable next steps, or just identify issues for the developer to address?", "selected": true, "answer": "Yes, review output must include specific actionable next steps for each issue: show the problem, suggest the fix, and provide concrete commands or actions to resolve it (e.g., 'Issue: Using any type in file.ts:42 → Fix: Replace with proper interface. Action: Edit file.ts line 42 to use UserInterface type')", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" }, { "id": 4, "text": "@human: Should it support reviewing multiple work units at once, or always single work unit reviews?", "selected": true, "answer": "Yes, support reviewing multiple work units at once. Allow '/review CLI-001 CLI-002 CLI-003' syntax to review multiple stories in one go. Output should be structured per work unit with clear separators between reviews.", "deleted": false, "createdAt": "2025-10-24T13:23:11.621Z" } ], "estimate": 8, "dependsOn": [ "QRY-002" ], "nextRuleId": 12, "nextExampleId": 6, "nextQuestionId": 5, "nextNoteId": 0 }, "LANG-001": { "id": "LANG-001", "title": "Internationalization and localization support for multiple languages", "type": "story", "status": "specifying", "createdAt": "2025-10-24T22:27:50.151Z", "updatedAt": "2025-10-24T22:28:24.595Z", "description": "Add i18n framework to fspec to support multiple languages for all user-facing text including CLI output, error messages, help text, and system-reminders", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T22:27:54.064Z" } ], "userStory": { "role": "developer or AI agent using fspec in a non-English language environment", "action": "see all CLI output, error messages, and help text in my preferred language", "benefit": "I can use fspec effectively without language barriers" }, "questions": [ { "id": 0, "text": "@human: Which languages should be supported initially? (e.g., Spanish, French, German, Japanese, Chinese, etc.)", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 1, "text": "@human: How should locale/language be configured? Environment variable (LANG), config file setting, CLI flag (--lang=es), or all three with precedence order?", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 2, "text": "@human: Should Gherkin feature files remain in English (industry standard), or should they also be localizable?", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 3, "text": "@human: Should system-reminders (for AI agents) be localized, or always remain in English since AI models typically understand English best?", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 4, "text": "@human: What i18n library should be used? (e.g., i18next, FormatJS/react-intl for CLI, or custom solution)", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 5, "text": "@human: Should translation files be JSON (easy to edit), YAML (human-readable), or .po/.pot files (professional translation tooling)?", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 6, "text": "@human: Where should translation files be stored? Project-level (spec/i18n/), user-level (~/.fspec/i18n/), or both with merging?", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 7, "text": "@human: Should date/time formatting, number formatting, and pluralization rules be supported (full i18n), or just text translation?", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 8, "text": "@human: How should missing translations be handled? Fallback to English, show translation key, or throw error?", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" }, { "id": 9, "text": "@human: Should there be a command to extract translatable strings from source code (like 'fspec extract-translations')?", "selected": false, "deleted": false, "createdAt": "2025-10-24T22:27:50.151Z" } ], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 10, "nextNoteId": 0 }, "QRY-002": { "id": "QRY-002", "title": "Enhanced search and comparison commands for similar story analysis", "type": "story", "status": "done", "createdAt": "2025-10-24T22:53:07.974Z", "updatedAt": "2025-10-25T00:21:50.918Z", "description": "Create advanced query commands that allow /review to search for similar completed stories by analyzing patterns, naming conventions, architectural approaches, and implementation strategies to enable cross-story consistency checking", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-24T23:32:29.028Z" }, { "state": "testing", "timestamp": "2025-10-24T23:35:23.604Z" }, { "state": "implementing", "timestamp": "2025-10-24T23:36:56.856Z" }, { "state": "validating", "timestamp": "2025-10-24T23:46:15.218Z" }, { "state": "done", "timestamp": "2025-10-24T23:46:24.889Z" }, { "state": "implementing", "timestamp": "2025-10-25T00:14:57.808Z" }, { "state": "validating", "timestamp": "2025-10-25T00:19:45.669Z" }, { "state": "done", "timestamp": "2025-10-25T00:21:50.918Z" } ], "userStory": { "role": "developer using /review command", "action": "search for similar completed stories to compare patterns and approaches", "benefit": "I can identify inconsistencies and ensure architectural consistency across the codebase" }, "rules": [ { "id": 0, "text": "Search must support filtering by work unit type (story, bug, task)", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 1, "text": "Search must support filtering by status (done, backlog, implementing, etc.)", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 2, "text": "Search must support filtering by tags (single or multiple tags)", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 3, "text": "Search must support filtering by feature group (e.g., all CLI features, all authentication features)", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 4, "text": "Search results must show coverage information (test files and implementation files)", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 5, "text": "Search must support text search across scenario names, feature descriptions, and work unit titles", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 6, "text": "Search results must be sortable by date, story points, or work unit ID", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 7, "text": "both - return work unit IDs for traceability and feature file paths for direct access to specs", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 8, "text": "yes - side-by-side comparison helps identify pattern divergence and best practices", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 9, "text": "table for human readability with --json flag option for programmatic use", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 10, "text": "both - literal by default with --regex flag for advanced patterns", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 11, "text": "yes - automatic highlighting of naming convention differences (camelCase vs snake_case, different prefixes, etc.)", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" } ], "examples": [ { "id": 0, "text": "Search for all completed CLI stories: fspec query-work-units --type=story --status=done --tag=@cli", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 1, "text": "Find scenarios with 'validation' in the name across all features: fspec search-scenarios --query=validation", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 2, "text": "Compare implementation approaches for authentication stories: fspec compare-implementations --tag=@authentication --show-coverage", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 3, "text": "Find all work units using a specific utility function: fspec search-implementation --function=loadConfig --show-work-units", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 4, "text": "List test patterns for high-priority features: fspec show-test-patterns --tag=@high --include-coverage", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" } ], "questions": [ { "id": 0, "text": "@human: Should search commands return work unit IDs, feature file paths, or both?", "selected": true, "answer": "both - return work unit IDs for traceability and feature file paths for direct access to specs", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 1, "text": "@human: Should comparison commands show side-by-side diffs of implementation approaches?", "selected": true, "answer": "yes - side-by-side comparison helps identify pattern divergence and best practices", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 2, "text": "@human: What output format should search results use (table, JSON, plain text)?", "selected": true, "answer": "table for human readability with --json flag option for programmatic use", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 3, "text": "@human: Should search support regex patterns or just literal string matching?", "selected": true, "answer": "both - literal by default with --regex flag for advanced patterns", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" }, { "id": 4, "text": "@human: Should comparison commands highlight naming convention differences automatically?", "selected": true, "answer": "yes - automatic highlighting of naming convention differences (camelCase vs snake_case, different prefixes, etc.)", "deleted": false, "createdAt": "2025-10-24T22:53:07.974Z" } ], "estimate": 13, "nextRuleId": 12, "nextExampleId": 5, "nextQuestionId": 5, "nextNoteId": 0 }, "FEAT-018": { "id": "FEAT-018", "title": "Multi-Tool Bootstrap System", "type": "story", "status": "backlog", "createdAt": "2025-10-24T23:48:22.326Z", "updatedAt": "2025-10-24T23:48:22.326Z", "description": "Extend fspec init to bootstrap multiple tools (fspec, mindstrike CLI, future tools) for AI agents. Centralize agent detection logic (Claude Code, Cursor, Windsurf, etc.) and template management in fspec instead of duplicating per tool. Allow tools to register templates with fspec via tool registry. When running 'fspec init', detect agent and copy bootstrap files for ALL registered tools (fspec.md, mindstrike.md, etc.). This makes fspec the universal bootstrap manager for AI coding tools, eliminating duplicate agent detection logic across projects.", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "CLI-012": { "id": "CLI-012", "title": "Review command with done status integration", "type": "story", "status": "done", "createdAt": "2025-10-25T00:26:55.548Z", "updatedAt": "2025-10-25T00:47:19.259Z", "description": "Add 'fspec review' command that provides context for reviewing completed work units, and integrate system-reminder into done status transition to suggest reviews", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-25T00:27:02.445Z" }, { "state": "testing", "timestamp": "2025-10-25T00:35:37.381Z" }, { "state": "implementing", "timestamp": "2025-10-25T00:43:30.816Z" }, { "state": "validating", "timestamp": "2025-10-25T00:43:31.567Z" }, { "state": "done", "timestamp": "2025-10-25T00:47:19.259Z" } ], "userStory": { "role": "developer or AI agent completing work", "action": "review completed work units before finalizing them", "benefit": "I ensure quality and completeness before marking work as truly done" }, "questions": [ { "id": 0, "text": "@human: When exactly should the system-reminder to suggest review appear? (A) When transitioning TO done status, (B) When work unit IS IN done status and user runs another command, or (C) Both scenarios?", "selected": true, "answer": "A - When transitioning TO done status. Emit system-reminder suggesting 'fspec review <work-unit-id>' to review the work before finalizing.", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 1, "text": "@human: What information should 'fspec review' provide? (A) Work unit summary, (B) Linked test/impl files from coverage, (C) Git diff for this work unit, (D) Validation checklist, (E) All of the above, or (F) Something else?", "selected": true, "answer": "E - All of the above. Use the same comprehensive review system from CLI-011's /review slash command, including work unit summary, coverage analysis, test/impl files, ACDD compliance, and coding standards validation.", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 2, "text": "@human: Should review be (A) Informational only - just display data for manual review, (B) Interactive checklist - with items to mark complete, or (C) Automated - run validation commands and report results?", "selected": true, "answer": "A - Informational only. Display comprehensive review data using the same ULTRATHINK analysis from /review command, but let user manually assess. The review command provides context and guidance.", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 3, "text": "@human: Should reviews be tracked/recorded? (A) Keep record that work unit was reviewed, (B) Require review confirmation before allowing done status, or (C) Optional review with reminder only (not mandatory)?", "selected": true, "answer": "C - Optional review with reminder only (not mandatory). System-reminder suggests using 'fspec review' when moving to done, but doesn't block the transition. Keeps workflow flexible.", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 4, "text": "@human: What about work units already in done status? Should they support 'fspec review <work-unit-id>' for retrospective review? Can review be run multiple times?", "selected": true, "answer": "Yes - 'fspec review <work-unit-id>' should work for any work unit in any status (backlog, specifying, testing, implementing, validating, done, blocked). Can be run multiple times. Provides context-aware analysis based on current state.", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" } ], "rules": [ { "id": 0, "text": "Review command must be 'fspec review <work-unit-id>' CLI command, not just a slash command", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 1, "text": "System-reminder must be emitted when transitioning to 'done' status in update-work-unit-status command", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 2, "text": "Review command must use same analysis approach as CLI-011's /review slash command (ULTRATHINK, coverage, ACDD compliance)", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 3, "text": "Review must work for work units in ANY status (not just done)", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 4, "text": "System-reminder must include exact command: 'fspec review <work-unit-id>' with actual work unit ID", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec update-work-unit-status AUTH-001 done', system-reminder suggests 'Consider reviewing before finalizing: fspec review AUTH-001'", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 1, "text": "User runs 'fspec review CLI-011', output shows: Issues Found (critical/warnings), ACDD Compliance, Coverage Analysis, Summary with priority actions", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 2, "text": "User runs 'fspec review SPEC-001' (work unit in testing status), review shows current progress, missing test coverage, suggests next steps", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" }, { "id": 3, "text": "User runs 'fspec review BUG-007' (completed bug fix), review validates fix quality, checks regression test coverage, confirms coding standards", "deleted": false, "createdAt": "2025-10-25T00:26:55.548Z" } ], "estimate": 5, "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 5, "nextNoteId": 0 }, "TEST-006": { "id": "TEST-006", "title": "Docstring-based test-to-scenario linking system", "type": "story", "status": "done", "createdAt": "2025-10-25T00:26:56.043Z", "updatedAt": "2025-10-25T05:38:32.645Z", "description": "Create a docstring-based system for linking test scenarios/steps to Gherkin acceptance criteria, with tooling to sync and migrate existing unlinked tests", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-25T00:30:22.828Z" }, { "state": "testing", "timestamp": "2025-10-25T05:09:31.531Z" }, { "state": "specifying", "timestamp": "2025-10-25T05:14:08.430Z" }, { "state": "testing", "timestamp": "2025-10-25T05:27:18.828Z" }, { "state": "implementing", "timestamp": "2025-10-25T05:29:29.947Z" }, { "state": "validating", "timestamp": "2025-10-25T05:33:15.238Z" }, { "state": "done", "timestamp": "2025-10-25T05:38:32.646Z" } ], "userStory": { "role": "developer using fspec for ACDD workflow", "action": "link test step comments to Gherkin feature file steps using @step prefix", "benefit": "I maintain Cucumber-style step-level traceability and get validation when steps don't match" }, "questions": [ { "id": 0, "text": "@human: What should the docstring format look like? Should it reference scenario names, Given/When/Then steps, or both? Should it include feature file paths?", "selected": true, "answer": "Coverage tracking uses scenario-level traceability in .feature.coverage files, NOT step-level @step docstrings. This system complements scenario-level coverage, not replaces it.", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 1, "text": "@human: How should the tool detect existing tests without docstring links? Should it scan all test files in the project, or specific directories?", "selected": true, "answer": "Coverage files (.feature.coverage) are created automatically when create-feature command runs. Detection is implicit through show-coverage command which shows uncovered scenarios.", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 2, "text": "@human: What should the migration tool do? (A) Interactive prompt for each unlinked test, (B) Batch analysis and suggested mappings, (C) Automatic linking based on test names, or (D) Something else?", "selected": true, "answer": "No migration tool exists. Coverage tracking is done manually via link-coverage command after writing tests and implementation. This is intentional - explicit linking ensures accuracy.", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 3, "text": "@human: Should the sync tool validate that docstring references match actual scenarios in feature files? What happens if they're out of sync?", "selected": true, "answer": "Audit-coverage command validates file paths exist. Out-of-sync links can be detected (broken paths) and auto-fixed with --fix flag. Line number validation is NOT performed.", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 4, "text": "@human: Should this integrate with existing .feature.coverage files, or be a separate system? Should it replace or complement coverage tracking?", "selected": true, "answer": "This IS the .feature.coverage system. Coverage files store scenario-to-test-to-implementation mappings. This complements feature files (acceptance criteria) with traceability data.", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" } ], "rules": [ { "id": 0, "text": "Every scenario must track which test file validates it and which implementation file implements it", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 1, "text": "Coverage files (.feature.coverage) are auto-created by create-feature command and store scenario-to-test-to-implementation mappings", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 2, "text": "Link coverage IMMEDIATELY after writing tests or code (do not batch)", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 3, "text": "Coverage tracking uses line ranges for tests (e.g., 45-62) and specific line numbers for implementation (e.g., 10,11,12,23,24)", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 4, "text": "Audit-coverage verifies file paths exist and can auto-fix broken links with --fix flag", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 5, "text": "Coverage files (.feature.coverage) are created automatically when create-feature command runs. Detection is implicit through show-coverage command which shows uncovered scenarios.", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 6, "text": "Audit-coverage command validates file paths exist. Out-of-sync links can be detected (broken paths) and auto-fixed with --fix flag. Line number validation is NOT performed.", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 7, "text": "This IS the .feature.coverage system. Coverage files store scenario-to-test-to-implementation mappings. This complements feature files (acceptance criteria) with traceability data.", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 8, "text": "Test files use comments (// Given, // When, // Then) that must match actual steps in feature file scenarios", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 9, "text": "System validates that test comments match feature file steps exactly (Cucumber-style step matching)", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 10, "text": "Step matching supports parameterized steps using hybrid similarity algorithm for fuzzy matching (e.g., '// Given I have 5 items' matches 'Given I have {int} items')", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 11, "text": "Existing fspec coverage commands (link-coverage, show-coverage, audit-coverage) are enhanced to validate step comments match feature file steps", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 12, "text": "Step comment validation is a HARD ERROR by default - command fails if test comments don't match feature steps", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 13, "text": "Override flag --skip-step-validation allows linking even when step comments don't match (escape hatch for edge cases)", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 14, "text": "When step validation fails, emit <system-reminder> showing: (1) which steps are missing/mismatched, (2) exact step text from feature file to copy, (3) how to override with --skip-step-validation flag", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 15, "text": "Step comments use '@step' prefix for fast searching: '// @step Given I am on the login page'", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 16, "text": "System is backward compatible - also recognizes plain step comments without @step prefix (e.g., '// Given I am on the login page')", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 17, "text": "show-coverage displays step-level validation status showing which steps have matching comments (✓ matched) vs missing (✗ MISSING STEP COMMENT)", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 18, "text": "Step matching uses existing hybrid similarity algorithm with adaptive thresholds: <10 chars=0.85, 10-20=0.80, 20-40=0.75, 40+=0.70", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" } ], "examples": [ { "id": 0, "text": "Developer writes test for 'Login with valid credentials' scenario at lines 45-62 in auth.test.ts, runs link-coverage command, coverage file updated with test mapping", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 1, "text": "Developer implements login function at lines 10-24 in login.ts, runs link-coverage to add implementation mapping to existing test, coverage file shows full traceability", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 2, "text": "Developer runs show-coverage for user-authentication feature, sees 50% coverage (1 of 2 scenarios covered), identifies uncovered scenario to work on next", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 3, "text": "Developer refactors codebase and moves test files, runs audit-coverage, discovers broken file paths, runs audit-coverage --fix to remove stale mappings", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 4, "text": "Developer runs show-coverage with no arguments, sees project-wide report showing 65% overall coverage across all features, identifies features needing attention", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 5, "text": "Test has '// Given I have 5 items', feature has 'Given I have {int} items', hybrid similarity matches them with high confidence", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 6, "text": "Running 'fspec link-coverage user-auth --scenario Login...' validates that test file contains matching step comments for all Given/When/Then steps in the scenario", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 7, "text": "Test missing '// When I click login', link-coverage fails with system-reminder showing exact text to add: '// When I click the login button' and override option '--skip-step-validation'", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 8, "text": "Test file with '// @step Given I am on the login page' matches feature step 'Given I am on the login page'", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 9, "text": "Legacy test with '// Given I am logged in' (no @step prefix) still matches feature step 'Given I am logged in' for backward compatibility", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 10, "text": "show-coverage output shows: 'Scenario: Login (FULLY COVERED)' with step breakdown '✓ Given I am on login page (matched)' and '✗ Then I should be logged in (MISSING STEP COMMENT)'", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" }, { "id": 11, "text": "Step '// @step Given I have 5 items' matches 'Given I have {int} items' using hybrid similarity with threshold 0.75 (medium length step)", "deleted": false, "createdAt": "2025-10-25T00:26:56.043Z" } ], "assumptions": [ "Coverage tracking uses scenario-level traceability in .feature.coverage files, NOT step-level @step docstrings. This system complements scenario-level coverage, not replaces it.", "No migration tool exists. Coverage tracking is done manually via link-coverage command after writing tests and implementation. This is intentional - explicit linking ensures accuracy." ], "estimate": 5, "nextRuleId": 19, "nextExampleId": 12, "nextQuestionId": 5, "nextNoteId": 0 }, "REV-002": { "id": "REV-002", "title": "Add agent-agnostic ultrathink to review command and update documentation", "type": "story", "status": "done", "createdAt": "2025-10-25T00:51:44.299Z", "updatedAt": "2025-10-25T01:30:13.576Z", "description": "Make review command use shared agent detection code (getAgentConfig) for agent-agnostic ultrathink support. Update all documentation (src/help.ts, command help files, CLAUDE.md autogenerator templates, README.md, docs/). Remove obsolete .claude/commands/review.md file.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-25T00:51:54.870Z" }, { "state": "testing", "timestamp": "2025-10-25T01:00:30.260Z" }, { "state": "implementing", "timestamp": "2025-10-25T01:01:16.304Z" }, { "state": "validating", "timestamp": "2025-10-25T01:02:15.518Z" }, { "state": "done", "timestamp": "2025-10-25T01:30:13.576Z" } ], "userStory": { "role": "AI agent (any type: Claude, Cursor, Aider, etc.)", "action": "use the review command with agent-specific metacognition formatting", "benefit": "I get properly formatted output that works with my capabilities" }, "rules": [ { "id": 0, "text": "Review command must use shared agent detection code (getAgentConfig) from src/utils/agentRuntimeConfig.ts", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" }, { "id": 1, "text": "Agent-specific formatting must use formatAgentOutput() for system-reminders (Claude) or bold text (other agents)", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" }, { "id": 2, "text": "Documentation must be updated in: src/help.ts, src/commands/review-help.ts (if exists), autogenerator templates, README.md, and docs/ directory", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" }, { "id": 3, "text": "Obsolete .claude/commands/review.md file must be removed (no longer used)", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" }, { "id": 4, "text": "Yes - Review command help should detect agent using getAgentConfig() and show agent-specific examples (e.g., <system-reminder> for Claude, **⚠️ IMPORTANT:** for Cursor). If no agent configured, show generic examples.", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" } ], "examples": [ { "id": 0, "text": "Claude Code agent runs 'fspec review AUTH-001' and gets output with <system-reminder> tags for ULTRATHINK guidance", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" }, { "id": 1, "text": "Cursor agent runs 'fspec review API-005' and gets output with **⚠️ IMPORTANT:** bold text formatting", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" }, { "id": 2, "text": "Aider CLI agent runs 'fspec review DASH-003' and gets output with **IMPORTANT:** plain bold text", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" }, { "id": 3, "text": "Review command detects agent from FSPEC_AGENT env var or spec/fspec-config.json or defaults to safe plain text", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" } ], "questions": [ { "id": 0, "text": "@human: Should the review command help include examples for different agent types (Claude, Cursor, Aider)?", "selected": true, "answer": "Yes - Review command help should detect agent using getAgentConfig() and show agent-specific examples (e.g., <system-reminder> for Claude, **⚠️ IMPORTANT:** for Cursor). If no agent configured, show generic examples.", "deleted": false, "createdAt": "2025-10-25T00:51:44.299Z" } ], "estimate": 3, "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 1, "nextNoteId": 0 }, "REMIND-009": { "id": "REMIND-009", "title": "Context-aware system-reminders for workflow state transitions", "type": "story", "status": "done", "createdAt": "2025-10-25T11:29:04.049Z", "updatedAt": "2025-10-25T19:37:44.391Z", "description": "When work units transition to a new workflow state (backlog→specifying→testing→implementing→validating), emit a system-reminder showing the most commonly used commands for that state, helping AI agents discover the right commands without guessing. Each reminder should be concise, action-oriented, and include pointers to help documentation.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-25T11:29:23.862Z" }, { "state": "testing", "timestamp": "2025-10-25T11:41:40.734Z" }, { "state": "implementing", "timestamp": "2025-10-25T11:42:57.867Z" }, { "state": "validating", "timestamp": "2025-10-25T11:46:23.443Z" }, { "state": "done", "timestamp": "2025-10-25T11:46:40.414Z" }, { "state": "validating", "timestamp": "2025-10-25T12:34:19.526Z" }, { "state": "done", "timestamp": "2025-10-25T19:37:44.391Z" } ], "userStory": { "role": "AI agent working on fspec project", "action": "see relevant commands when entering a new workflow state", "benefit": "I can discover and use the right commands without guessing or searching documentation" }, "rules": [ { "id": 0, "text": "System-reminders should appear when work unit status changes via update-work-unit-status command", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 1, "text": "Each workflow state (backlog, specifying, testing, implementing, validating) has its own set of commonly used commands", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 2, "text": "Reminders must be concise - show only 5-7 most common commands per state, not every possible command", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 3, "text": "Each command should have brief syntax example showing arguments (e.g., 'fspec remove-rule <id> <index>' not just 'remove-rule')", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 4, "text": "Include pointer to help documentation at end (e.g., 'For complete reference: fspec help discovery' or 'fspec <command> --help')", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 5, "text": "Done and blocked states do not need command reminders (blocked needs issue resolution, done is complete)", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" } ], "examples": [ { "id": 0, "text": "When work unit moves to SPECIFYING, AI sees reminder: 'Common commands: fspec add-rule <id> \"rule\" | fspec remove-rule <id> <index> | fspec add-example <id> \"example\" | fspec remove-example <id> <index> | fspec add-question <id> \"@human: question?\" | fspec answer-question <id> <index> --answer \"...\" | fspec generate-scenarios <id>. For more: fspec help discovery'", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 1, "text": "When work unit moves to TESTING, AI sees reminder: 'Common commands: fspec link-coverage <feature> --scenario \"...\" --test-file <path> --test-lines <range> | fspec show-coverage <feature> | fspec show-feature <name>. Write tests that map to Gherkin scenarios. For more: fspec link-coverage --help'", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 2, "text": "When work unit moves to IMPLEMENTING, AI sees reminder: 'Common commands: fspec link-coverage <feature> --scenario \"...\" --impl-file <path> --impl-lines <lines> | fspec checkpoint <id> <name> | fspec restore-checkpoint <id> <name> | fspec list-checkpoints <id>. Write minimal code to pass tests. For more: fspec checkpoint --help'", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 3, "text": "When work unit moves to VALIDATING, AI sees reminder: 'Common commands: fspec validate | fspec validate-tags | fspec check | fspec audit-coverage <feature> | npm test | npm run check. Run ALL tests to ensure nothing broke. For more: fspec check --help'", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 4, "text": "When work unit moves to BACKLOG (deprioritization), no command reminder is shown since backlog is a waiting state with no active work", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" } ], "questions": [ { "id": 0, "text": "@human: Should the reminder show full command syntax with <placeholders> for arguments, or just command names with brief descriptions?", "selected": true, "answer": "Full command syntax with <placeholders> for arguments (e.g., 'fspec remove-rule <id> <index>') because it provides immediate usability and reduces ambiguity about argument order", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 1, "text": "@human: Should commands be shown one per line (vertical list) or separated by pipe | (horizontal compact)?", "selected": true, "answer": "One per line (vertical list) because it's easier to scan, maintains clean structure in system-reminders, and remains readable regardless of command count", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 2, "text": "@human: Should BACKLOG state show a reminder about prioritization commands (prioritize-work-unit, show-work-unit), or skip reminders entirely since it's a waiting state?", "selected": true, "answer": "Skip reminders entirely for BACKLOG state because it's a waiting state with no active work, and prioritization happens at board level rather than when transitioning individual work units", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 3, "text": "@human: Should VALIDATING state include non-fspec commands (npm test, npm run check) in the reminder, or only fspec commands?", "selected": true, "answer": "Only fspec commands - no external commands (npm test, npm run check, etc.) because fspec is platform and language agnostic", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" }, { "id": 4, "text": "@human: Should the reminder appear every time status changes, or only the first time entering each state (cached per work unit)?", "selected": true, "answer": "Every time status changes because context switches between work units, backward movement in ACDD workflow, different conversation sessions, and low cost with high value for always having command context", "deleted": false, "createdAt": "2025-10-25T11:29:04.049Z" } ], "estimate": 5, "nextRuleId": 6, "nextExampleId": 5, "nextQuestionId": 5, "nextNoteId": 0 }, "FEAT-019": { "id": "FEAT-019", "title": "Reverse ACDD Strategy D Not Detecting Implementation Files", "type": "bug", "status": "done", "createdAt": "2025-10-25T11:51:54.504Z", "updatedAt": "2025-10-25T12:29:06.438Z", "description": "When running 'fspec reverse' on a project with implementation files but no tests or features (like MusicPlayer.tsx, usePlaylistStore.ts), Strategy D (Full Reverse ACDD) is not detected. The tool only detects Strategy B (features without tests) based on unrelated feature files in the project. Expected: Strategy D should analyze implementation files in src/ and guide creation of feature files + tests. Actual: Strategy D not offered, manual specification fails with 'No active reverse session'.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-25T11:52:22.171Z" }, { "state": "testing", "timestamp": "2025-10-25T12:20:26.361Z" }, { "state": "implementing", "timestamp": "2025-10-25T12:23:23.010Z" }, { "state": "validating", "timestamp": "2025-10-25T12:26:31.287Z" }, { "state": "done", "timestamp": "2025-10-25T12:29:06.438Z" } ], "rules": [ { "id": 0, "text": "Strategy D guides AI agents through outside-in BDD: Context → Personas → User Behavior → Example Maps → Features → Test Skeletons → Implementation Links", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 1, "text": "Strategy D uses foundation.json personas to help AI understand WHO uses the system and WHAT they want to accomplish (not HOW it's implemented)", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 2, "text": "AI provides implementation context as input, Strategy D helps transform it into user-centric feature specifications and example maps", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 3, "text": "Strategy D should fill gaps backward from behavior to implementation: Example Maps → Features → Tests → Coverage Links to existing code", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 4, "text": "Yes. Strategy D should actively prompt with persona-based questions using system-reminders to guide AI thinking. Example: 'WHO uses this? (Check foundation.json personas)' and 'WHAT does [persona] want to accomplish?'. This provides cognitive scaffolding to help AI shift from inside-out code-thinking to outside-in behavior-thinking. Prompts should be guiding (not blocking), conditional on foundation.json existence, and include examples of good persona-driven thinking.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 5, "text": "Foundation.json must exist (run 'fspec discover-foundation' if missing as one-time setup). During Strategy D, when persona is needed but missing, prompt AI to add it incrementally via 'fspec add-persona <name> <description> --goal <goal>'. For granular code (APIs, functions), guide AI to identify which human persona BENEFITS (not which system calls it) using system-reminders: 'Not who calls calculateDiscount() but who benefits from accurate discounts? Answer: Shopper'. Skip feature files for pure utilities (formatDate, parseJSON) - test-only coverage.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 6, "text": "Yes. Strategy D should provide transformation templates via system-reminders to help AI translate implementation → behavior. Templates: (1) UI Elements → User Actions (button → 'User clicks/taps [action]', input → 'User enters [data]'), (2) State → User Expectations (useState → 'User sees [state]', loading → 'User waits for [process]'), (3) API Endpoints → User Needs (POST /orders → 'User completes order'). Templates accelerate mental shift, ensure consistency, and reinforce outside-in thinking.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 7, "text": "Pause for review with guided prompts. After AI creates example map, Strategy D emits system-reminder with review checklist: 'Do rules cover examples?', 'Are examples concrete?', 'All questions answered?', 'Examples map to personas?'. Then offers explicit choice: (1) Generate features now: fspec generate-scenarios, (2) Add more examples/rules. AI explicitly chooses when to generate (not automatic). Example Mapping is a conversation requiring reflection, not a form-filling exercise. Quality gate prevents garbage-in-garbage-out.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 8, "text": "Semi-automatic with educational system-reminder. Strategy D auto-links coverage by default using 'fspec link-coverage --skip-validation' but emits system-reminder showing: (1) What was linked (scenario → test skeleton → implementation), (2) Exact command that was run (educational), (3) How to verify: 'fspec show-coverage', (4) How to fix if wrong: 'fspec unlink-coverage' then re-link manually. Balances low friction (automatic) with transparency (not a black box) and learning (AI sees the mechanism).", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 9, "text": "Feature-scoped sessions (multiple related files allowed). Strategy D allows multiple implementation files in one session if they deliver the SAME user-facing feature. System-reminder guides AI: 'Do these files deliver same user behavior?' YES → One work unit, one example map, one feature file, multiple test files (one per implementation). NO → Separate sessions. BDD focuses on user behavior which often spans multiple files. Track all files in work unit metadata under 'reverseSession.implementationFiles[]'. Link all via coverage to same feature file.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" } ], "examples": [ { "id": 0, "text": "AI: 'I have MusicPlayer.tsx with play/pause/skip buttons' → Strategy D: 'Who uses this?' → AI sees foundation.json personas: Music Listener persona → Strategy D guides: 'What does Music Listener want?' → AI creates example map: 'Music Listener plays song', 'Music Listener pauses playback' → Generates feature file + test skeletons → Links coverage to MusicPlayer.tsx", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 1, "text": "AI: 'I have usePlaylistStore.ts with addSong(), removeSong(), clearPlaylist()' → Strategy D: 'What user behavior does this support?' → AI identifies: Managing playlists → Creates example map with rules: 'User can add songs', 'User can remove songs' → Generates playlist-management.feature → Creates test skeleton → Links to usePlaylistStore.ts implementation", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 2, "text": "Project has foundation.json with 'Mobile App User' persona (goal: Stream music on the go) → AI provides AudioPlayer.tsx context → Strategy D prompts: 'How does Mobile App User stream music?' → AI creates example map: 'User taps play', 'User adjusts volume', 'User sees album art' → Feature file generated with user-centric scenarios", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" } ], "questions": [ { "id": 0, "text": "@human: Should Strategy D scan src/ for files lacking feature files in spec/features?", "selected": true, "answer": "No. Strategy D should NOT scan src/ automatically. Instead, it should guide the AI agent through a context-driven discovery process: AI provides implementation context → Tool uses foundation.json personas → AI understands user behavior → Creates example maps → Generates features → Generates test skeletons → Links to implementation. This is outside-in BDD, not inside-out code scanning.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 1, "text": "@human: When AI provides implementation context (e.g., 'MusicPlayer.tsx has play/pause buttons'), should Strategy D prompt with persona-based questions like 'Which persona from foundation.json uses this feature?' or 'What does [persona] want to accomplish?'", "selected": true, "answer": "Yes. Strategy D should actively prompt with persona-based questions using system-reminders to guide AI thinking. Example: 'WHO uses this? (Check foundation.json personas)' and 'WHAT does [persona] want to accomplish?'. This provides cognitive scaffolding to help AI shift from inside-out code-thinking to outside-in behavior-thinking. Prompts should be guiding (not blocking), conditional on foundation.json existence, and include examples of good persona-driven thinking.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 2, "text": "@human: If foundation.json is missing or has no personas, should Strategy D guide AI through creating foundation first via 'fspec discover-foundation', or allow manual persona specification for this reverse session only?", "selected": true, "answer": "Foundation.json must exist (run 'fspec discover-foundation' if missing as one-time setup). During Strategy D, when persona is needed but missing, prompt AI to add it incrementally via 'fspec add-persona <name> <description> --goal <goal>'. For granular code (APIs, functions), guide AI to identify which human persona BENEFITS (not which system calls it) using system-reminders: 'Not who calls calculateDiscount() but who benefits from accurate discounts? Answer: Shopper'. Skip feature files for pure utilities (formatDate, parseJSON) - test-only coverage.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 3, "text": "@human: Should Strategy D provide templates or prompts to help AI transform implementation details (buttons, functions, state) into user behavior descriptions (plays song, pauses playback, manages playlist)?", "selected": true, "answer": "Yes. Strategy D should provide transformation templates via system-reminders to help AI translate implementation → behavior. Templates: (1) UI Elements → User Actions (button → 'User clicks/taps [action]', input → 'User enters [data]'), (2) State → User Expectations (useState → 'User sees [state]', loading → 'User waits for [process]'), (3) API Endpoints → User Needs (POST /orders → 'User completes order'). Templates accelerate mental shift, ensure consistency, and reinforce outside-in thinking.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 4, "text": "@human: After AI creates example maps (rules, examples, questions), should Strategy D automatically generate feature files and test skeletons, or should it prompt AI to review/refine the example map first?", "selected": true, "answer": "Pause for review with guided prompts. After AI creates example map, Strategy D emits system-reminder with review checklist: 'Do rules cover examples?', 'Are examples concrete?', 'All questions answered?', 'Examples map to personas?'. Then offers explicit choice: (1) Generate features now: fspec generate-scenarios, (2) Add more examples/rules. AI explicitly chooses when to generate (not automatic). Example Mapping is a conversation requiring reflection, not a form-filling exercise. Quality gate prevents garbage-in-garbage-out.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 5, "text": "@human: Should Strategy D guide AI to link test skeletons to existing implementation using 'fspec link-coverage --skip-validation' automatically, or require AI to manually create coverage links?", "selected": true, "answer": "Semi-automatic with educational system-reminder. Strategy D auto-links coverage by default using 'fspec link-coverage --skip-validation' but emits system-reminder showing: (1) What was linked (scenario → test skeleton → implementation), (2) Exact command that was run (educational), (3) How to verify: 'fspec show-coverage', (4) How to fix if wrong: 'fspec unlink-coverage' then re-link manually. Balances low friction (automatic) with transparency (not a black box) and learning (AI sees the mechanism).", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" }, { "id": 6, "text": "@human: Should Strategy D track multiple implementation files in a single reverse session (e.g., MusicPlayer.tsx + usePlaylistStore.ts together), or require separate sessions per file?", "selected": true, "answer": "Feature-scoped sessions (multiple related files allowed). Strategy D allows multiple implementation files in one session if they deliver the SAME user-facing feature. System-reminder guides AI: 'Do these files deliver same user behavior?' YES → One work unit, one example map, one feature file, multiple test files (one per implementation). NO → Separate sessions. BDD focuses on user behavior which often spans multiple files. Track all files in work unit metadata under 'reverseSession.implementationFiles[]'. Link all via coverage to same feature file.", "deleted": false, "createdAt": "2025-10-25T11:51:54.504Z" } ], "userStory": { "role": "AI agent using fspec for reverse ACDD", "action": "be guided through outside-in BDD discovery when I have implementation files without features", "benefit": "I create user-centric specifications that trace behavior back to existing code, rather than just scanning files inside-out" }, "estimate": 5, "nextRuleId": 10, "nextExampleId": 3, "nextQuestionId": 7, "nextNoteId": 0 }, "REV-003": { "id": "REV-003", "title": "Strategy D processes existing feature files instead of scanning src/ for implementation files", "type": "bug", "status": "done", "createdAt": "2025-10-25T12:34:33.055Z", "updatedAt": "2025-10-25T23:57:33.345Z", "description": "When 'fspec reverse --strategy=D' is run, it processes existing .feature files in spec/features/ directory rather than scanning src/ directory for implementation files (.tsx, .ts, .jsx, .js) that lack corresponding feature files. Expected: Strategy D should discover implementation files in src/ (like MusicPlayer.tsx, usePlaylistStore.ts) and guide creation of feature files for them. Actual: Strategy D iterates through existing feature files (e.g., cli-command-interface-for-ai-agent-control.feature) with guidance to 'Read test file... Then create feature file' which is confusing since the feature file already exists.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-25T12:34:33.733Z" }, { "state": "testing", "timestamp": "2025-10-25T23:35:11.086Z" }, { "state": "implementing", "timestamp": "2025-10-25T23:39:25.827Z" }, { "state": "validating", "timestamp": "2025-10-25T23:44:24.297Z" }, { "state": "implementing", "timestamp": "2025-10-25T23:48:46.955Z" }, { "state": "validating", "timestamp": "2025-10-25T23:52:57.267Z" }, { "state": "done", "timestamp": "2025-10-25T23:57:33.345Z" } ], "rules": [ { "id": 0, "text": "Strategy D should scan src/ directory recursively for .tsx, .ts, .jsx, .js files", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" }, { "id": 1, "text": "For each implementation file found, Strategy D should check if a corresponding feature file exists in spec/features/", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" }, { "id": 2, "text": "Strategy D should only process implementation files that have NO corresponding feature file", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" }, { "id": 3, "text": "Yes, use tinyglobby with pattern 'src/**/*.{ts,tsx,js,jsx}' to recursively find all implementation files, excluding test directories (__tests__, tests, test) and test files (*.test.ts, *.spec.ts)", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" }, { "id": 4, "text": "Use filename similarity with kebab-case conversion algorithm: deriveFeatureName() converts camelCase/PascalCase implementation filenames to kebab-case (e.g., MusicPlayer.tsx → music-player.feature, usePlaylistStore.ts → use-playlist-store.feature). Then check if spec/features/{kebab-name}.feature exists. This is simpler and more predictable than import/export analysis.", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" } ], "examples": [ { "id": 0, "text": "MindStrike project has MusicPlayer.tsx (1532 lines) with no feature file. Strategy D should detect this and guide: 'Analyze MusicPlayer.tsx implementation → Create feature file → Create test file → Link coverage'", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" }, { "id": 1, "text": "Running 'fspec reverse --strategy=D' outputs: 'Step 1 of 7: Read test file: spec/features/cli-command-interface-for-ai-agent-control.feature. Then create feature file.' This is wrong - it's reading a feature file (not implementation), and the feature already exists.", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" } ], "questions": [ { "id": 0, "text": "@human: Should Strategy D use glob patterns to find implementation files (e.g., src/**/*.{ts,tsx,js,jsx})?", "selected": true, "answer": "Yes, use tinyglobby with pattern 'src/**/*.{ts,tsx,js,jsx}' to recursively find all implementation files, excluding test directories (__tests__, tests, test) and test files (*.test.ts, *.spec.ts)", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" }, { "id": 1, "text": "@human: How should Strategy D match implementation files to feature files? By filename similarity (MusicPlayer.tsx → music-player.feature) or by analyzing imports/exports?", "selected": true, "answer": "Use filename similarity with kebab-case conversion algorithm: deriveFeatureName() converts camelCase/PascalCase implementation filenames to kebab-case (e.g., MusicPlayer.tsx → music-player.feature, usePlaylistStore.ts → use-playlist-store.feature). Then check if spec/features/{kebab-name}.feature exists. This is simpler and more predictable than import/export analysis.", "deleted": false, "createdAt": "2025-10-25T12:34:33.055Z" } ], "userStory": { "role": "AI agent using fspec reverse for codebases without prior fspec usage", "action": "have Strategy D automatically discover implementation files in src/ and guide me through creating feature files for them", "benefit": "I can apply outside-in BDD to existing codebases without manually specifying which files need features" }, "estimate": 8, "nextRuleId": 5, "nextExampleId": 2, "nextQuestionId": 2, "nextNoteId": 0 }, "BUG-044": { "id": "BUG-044", "title": "AI agents skip docstring step validation by using --skip-step-validation flag", "type": "bug", "status": "done", "createdAt": "2025-10-26T01:14:51.328Z", "updatedAt": "2025-10-26T01:29:52.666Z", "description": "AI agents frequently use the --skip-step-validation flag to bypass docstring step comment validation in link-coverage command, defeating the purpose of test-to-scenario traceability. The flag should ONLY be available for task work units (which don't require feature files). For story and bug work units, docstring validation must be MANDATORY with NO skip option. System must enforce this strictly and provide clear warnings that attempting to skip will result in having to go back and fix the docstrings when detected.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-26T01:14:56.087Z" }, { "state": "testing", "timestamp": "2025-10-26T01:18:43.166Z" }, { "state": "implementing", "timestamp": "2025-10-26T01:21:17.987Z" }, { "state": "validating", "timestamp": "2025-10-26T01:25:08.566Z" }, { "state": "done", "timestamp": "2025-10-26T01:29:52.666Z" } ], "userStory": { "role": "developer using fspec with AI agents", "action": "enforce mandatory docstring step validation for test-to-scenario traceability", "benefit": "AI agents cannot skip critical validation and bypass the ACDD workflow discipline" }, "rules": [ { "id": 0, "text": "The --skip-step-validation flag must ONLY be available when linking coverage for task work units", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" }, { "id": 1, "text": "For story and bug work units, docstring step validation is MANDATORY with NO skip option", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" }, { "id": 2, "text": "If --skip-step-validation is used on a story/bug work unit, the command must fail with a strict error message", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" }, { "id": 3, "text": "Error message must clearly warn that skipping validation will be detected and require going back to fix docstrings", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" }, { "id": 4, "text": "All documentation referencing --skip-step-validation must be updated to explain the task-only restriction", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" }, { "id": 5, "text": "Step validation error system-reminders must be updated to remove mention of --skip-step-validation for story/bug work units", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" } ], "examples": [ { "id": 0, "text": "AI agent tries 'fspec link-coverage user-login --scenario Login --test-file auth.test.ts --test-lines 10-20 --skip-step-validation' on story work unit → command fails with error explaining skip is only for tasks", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" }, { "id": 1, "text": "AI agent links coverage for task work unit with 'fspec link-coverage infrastructure-setup --scenario Setup --test-file setup.test.ts --test-lines 5-15 --skip-step-validation' → command succeeds (tasks don't require feature files)", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" }, { "id": 2, "text": "AI agent links coverage for story without step comments in test file → receives system-reminder with exact steps to add, NO mention of skip flag", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" }, { "id": 3, "text": "Documentation shows --skip-step-validation with note: 'Only available for task work units. Story and bug work units require mandatory step validation.'", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" } ], "architectureNotes": [ { "id": 0, "text": "Must detect work unit type by looking up the feature file tag (e.g., @BUG-044) in work-units.json to determine if it's a story, bug, or task. If feature file doesn't exist or tag not found, assume story/bug (strictest validation).", "deleted": false, "createdAt": "2025-10-26T01:14:51.328Z" } ], "estimate": 5, "nextRuleId": 6, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 1 }, "REV-004": { "id": "REV-004", "title": "AI-Driven Deep Code Review", "type": "story", "status": "done", "createdAt": "2025-10-26T01:45:50.383Z", "updatedAt": "2025-10-26T02:17:37.712Z", "description": "Enhance fspec review to use conversational AI-driven analysis for bug detection, architecture pattern validation, anti-pattern detection, refactoring suggestions, and FOUNDATION.md alignment checks", "epic": "cli-ux-improvements", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-26T01:45:55.459Z" }, { "state": "testing", "timestamp": "2025-10-26T01:51:45.416Z" }, { "state": "implementing", "timestamp": "2025-10-26T01:54:09.558Z" }, { "state": "specifying", "timestamp": "2025-10-26T02:00:06.864Z" }, { "state": "testing", "timestamp": "2025-10-26T02:01:43.060Z" }, { "state": "implementing", "timestamp": "2025-10-26T02:01:48.739Z" }, { "state": "validating", "timestamp": "2025-10-26T02:08:44.259Z" }, { "state": "done", "timestamp": "2025-10-26T02:17:37.712Z" } ], "userStory": { "role": "AI agent using fspec for code quality", "action": "get deep analysis and actionable guidance on code quality issues", "benefit": "I can fix bugs, refactor code, and align with project architecture before marking work as done" }, "rules": [ { "id": 0, "text": "Review must use <system-reminder> tags for conversational AI-driven guidance (like fspec reverse)", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 1, "text": "Review must instruct AI to read all implementation files linked to work unit coverage", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 2, "text": "Review must instruct AI to analyze code for bugs, edge cases, race conditions, and logic errors", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 3, "text": "Review must check code alignment with FOUNDATION.md goals and architectural principles", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 4, "text": "Review must detect anti-patterns (duplicated code, God objects, tight coupling, etc.)", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 5, "text": "Review must suggest refactoring opportunities for code sharing and DRY principle", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 6, "text": "Review must preserve existing static checks (ACDD compliance, coverage, coding standards)", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 7, "text": "Review system-reminder must be agent-aware (use getAgentConfig and formatAgentOutput)", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec review AUTH-001' with implementation files in coverage → system-reminder appears after Summary section with implementation file paths listed", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 1, "text": "Review work unit with 3 implementation files → system-reminder lists all 3 file paths from coverage data", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 2, "text": "Review work unit with FOUNDATION.md present → system-reminder mentions FOUNDATION.md as reference document", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 3, "text": "Review work unit with no implementation files in coverage → system-reminder still appears but without file list section", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" }, { "id": 4, "text": "Review preserves existing static checks → output contains both static issues section AND system-reminder section", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" } ], "architectureNotes": [ { "id": 0, "text": "Review output must include system-reminder with AI instructions for deep analysis. Pattern similar to fspec reverse: build systemReminder string, wrap with wrapSystemReminder(), include in result. AI instructions: 1) Read all implementation files from coverage data 2) Analyze code deeply for bugs/patterns 3) Check FOUNDATION.md alignment 4) Report findings conversationally. Preserve existing static analysis (lines 188-229 check for 'any', require, file extensions). Add new section after static checks for AI-driven deep analysis guidance.", "deleted": false, "createdAt": "2025-10-26T01:45:50.383Z" } ], "estimate": 8, "nextRuleId": 8, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 1 }, "REV-005": { "id": "REV-005", "title": "Conversational Review Prompt Before Done", "type": "story", "status": "done", "createdAt": "2025-10-26T01:48:22.493Z", "updatedAt": "2025-10-26T02:35:46.151Z", "description": "When AI moves work unit to 'done' status, emit system-reminder prompting AI to ask user if they want to run 'fspec review' for quality checks before marking complete", "epic": "cli-ux-improvements", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-26T01:48:27.129Z" }, { "state": "testing", "timestamp": "2025-10-26T02:22:27.444Z" }, { "state": "implementing", "timestamp": "2025-10-26T02:30:30.399Z" }, { "state": "validating", "timestamp": "2025-10-26T02:33:13.196Z" }, { "state": "done", "timestamp": "2025-10-26T02:35:46.151Z" } ], "userStory": { "role": "AI agent completing work units", "action": "proactively suggest running quality review before marking work as done", "benefit": "users catch quality issues early and maintain high code standards" }, "rules": [ { "id": 0, "text": "System-reminder must appear when moving work unit to 'done' status (pre-done trigger)", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" }, { "id": 1, "text": "System-reminder must prompt AI to ask user about running fspec review", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" }, { "id": 2, "text": "Prompt must be conversational and non-blocking (AI asks user, not hard requirement)", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" }, { "id": 3, "text": "System-reminder must suggest exact command: 'fspec review <work-unit-id>'", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" }, { "id": 4, "text": "Only trigger for story and bug work units (tasks don't need deep review)", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" }, { "id": 5, "text": "System-reminder must use agent-aware formatting (getAgentConfig, formatAgentOutput)", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec update-work-unit-status AUTH-001 done' and receives system-reminder: 'Before marking complete, consider asking: Would you like me to run fspec review AUTH-001 to check for quality issues?'", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" }, { "id": 1, "text": "User says yes, AI runs 'fspec review AUTH-001', finds 2 issues, fixes them, then marks done", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" }, { "id": 2, "text": "User says no, AI proceeds to mark work unit as done without review", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" }, { "id": 3, "text": "AI moves task work unit TASK-001 to done, NO review prompt appears (tasks exempt)", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" } ], "architectureNotes": [ { "id": 0, "text": "Implementation location: src/commands/update-work-unit-status.ts. Add system-reminder emission when transitioning to 'done' status. Check workUnit.type: if story or bug, emit formatted system-reminder using formatAgentOutput(). Template: 'QUALITY CHECK OPPORTUNITY\\n\\nBefore marking {id} as done, consider running a quality review.\\n\\nSuggested action:\\n1. Ask user: Would you like me to run fspec review {id} to check for bugs, anti-patterns, and FOUNDATION.md alignment?\\n2. If yes: Run fspec review {id}, address findings, then mark done\\n3. If no: Proceed to mark done\\n\\nCommand: fspec review {id}'. Use existing getAgentConfig() for agent detection.", "deleted": false, "createdAt": "2025-10-26T01:48:22.493Z" } ], "estimate": 3, "nextRuleId": 6, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 1 }, "CONFIG-002": { "id": "CONFIG-002", "title": "Conversational Test and Quality Check Tool Detection", "type": "story", "status": "done", "createdAt": "2025-10-26T02:51:30.219Z", "updatedAt": "2025-10-26T12:28:53.072Z", "description": "Make fspec platform-agnostic by detecting test and quality check tools conversationally (like fspec review/reverse), replacing hardcoded npm references with AI-driven detection and setup via system-reminders", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-26T02:51:34.424Z" }, { "state": "specifying", "timestamp": "2025-10-26T03:26:58.970Z" }, { "state": "specifying", "timestamp": "2025-10-26T03:31:00.609Z" }, { "state": "testing", "timestamp": "2025-10-26T03:34:23.791Z" }, { "state": "implementing", "timestamp": "2025-10-26T03:36:29.773Z" }, { "state": "validating", "timestamp": "2025-10-26T03:37:39.211Z" }, { "state": "done", "timestamp": "2025-10-26T03:39:47.276Z" }, { "state": "specifying", "timestamp": "2025-10-26T04:42:53.351Z" }, { "state": "testing", "timestamp": "2025-10-26T04:45:19.349Z" }, { "state": "implementing", "timestamp": "2025-10-26T04:47:16.364Z" }, { "state": "validating", "timestamp": "2025-10-26T04:56:19.983Z" }, { "state": "done", "timestamp": "2025-10-26T04:58:48.749Z" }, { "state": "specifying", "timestamp": "2025-10-26T05:00:07.697Z" }, { "state": "testing", "timestamp": "2025-10-26T05:02:49.611Z" }, { "state": "implementing", "timestamp": "2025-10-26T07:05:49.052Z" }, { "state": "validating", "timestamp": "2025-10-26T10:58:41.547Z" }, { "state": "done", "timestamp": "2025-10-26T10:59:06.521Z" }, { "state": "specifying", "timestamp": "2025-10-26T12:21:55.414Z" }, { "state": "testing", "timestamp": "2025-10-26T12:23:09.222Z" }, { "state": "implementing", "timestamp": "2025-10-26T12:24:01.294Z" }, { "state": "validating", "timestamp": "2025-10-26T12:25:40.035Z" }, { "state": "done", "timestamp": "2025-10-26T12:28:53.072Z" } ], "userStory": { "role": "AI agent using fspec across different platforms", "action": "detect and configure test and quality check tools conversationally", "benefit": "fspec works on any platform (Node.js, Python, Rust, Go, etc.) without hardcoded assumptions" }, "rules": [ { "id": 0, "text": "fspec MUST NOT execute semantic code analysis - ALL detection done via system-reminders guiding AI", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 1, "text": "Tool detection MUST be conversational like fspec review and fspec reverse", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 2, "text": "Configuration MUST use same lookup system as system-reminder style detection", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 3, "text": "AI MUST detect existing tools OR guide setup if none exist using current best practices", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 4, "text": "All hardcoded npm test and npm check references MUST be replaced with platform-agnostic commands", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 5, "text": "Store in spec/fspec-config.json with a 'tools' section (extend existing file that already stores agent config)", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 6, "text": "One-time setup via explicit 'fspec configure-tools' command (like fspec init). Commands emit system-reminder if config missing, telling AI to run configure-tools. Detection happens once, used many times.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 7, "text": "Yes - 'fspec configure-tools' supports both initial setup AND reconfiguration. Includes --reconfigure flag for re-detection, manual override flags for explicit commands. Handles tool changes (switching frameworks, adding quality checks) conversationally.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 8, "text": "ALL documentation MUST be updated: src/help.ts, src/commands/*-help.ts, spec/CLAUDE.md, docs/, README.md for every aspect of tool configuration", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 9, "text": "When AI detects multiple frameworks, chain them with && (e.g., '<framework1> && <framework2>'). All detected tools run sequentially.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 10, "text": "Include date-aware search queries in system-reminders (e.g., 'best <platform> testing tools 2025'). Platform placeholder filled by fspec based on project detection.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 11, "text": "Yes, ALL hardcoded npm commands in documentation and help files MUST be replaced with dynamic placeholders like <test-command> and <quality-check-commands> that system-reminders will fill in based on fspec configure-tools configuration. This is required by Rule #9.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 12, "text": "Placeholders like <test-command> and <quality-check-commands> in documentation MUST be dynamically replaced with actual configured commands when spec/CLAUDE.md is generated", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 13, "text": "When spec/fspec-config.json has tools.test.command configured, all <test-command> placeholders in generated spec/CLAUDE.md should be replaced with the actual command", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 14, "text": "When spec/fspec-config.json has tools.qualityCheck.commands configured, all <quality-check-commands> placeholders in generated spec/CLAUDE.md should be replaced with the chained command (joined with &&)", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 15, "text": "configure-tools command MUST be registered in src/index.ts via registerConfigureToolsCommand() function", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 16, "text": "Registration function MUST follow existing pattern: export async function registerConfigureToolsCommand(program: Command)", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 17, "text": "Command MUST appear in --help output after registration", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" } ], "examples": [ { "id": 0, "text": "AI in validating phase, fspec checks spec/fspec-config.json for tools.test.command, finds none, emits system-reminder: 'No test command configured. Use Read/Glob to detect test framework, then run: fspec configure-tools --test-command <cmd>'", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 1, "text": "AI receives system-reminder, uses Read/Glob tools to detect test framework, runs: fspec configure-tools --test-command '<detected-command>', fspec writes to spec/fspec-config.json", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 2, "text": "Next validation, fspec reads spec/fspec-config.json, finds tools.test.command='<command>', emits system-reminder: 'Run tests: <command>'", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 3, "text": "AI uses Read/Glob to detect multiple test frameworks, chains them: fspec configure-tools --test-command '<framework1> && <framework2>', fspec stores chained command", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 4, "text": "No test tools detected: system-reminder includes date-aware search query 'best <platform> testing tools 2025', AI searches, configures result", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 5, "text": "AI detects quality check tools via Glob, runs: fspec configure-tools --quality-commands '<tool1>' '<tool2>' '<tool3>', fspec stores as array", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 6, "text": "AI runs 'fspec configure-tools --reconfigure', fspec re-emits system-reminder for detection, AI updates config with new tools", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 7, "text": "AI reads slash command section with '<test-command>' placeholder, fspec generates spec/CLAUDE.md, replaces <test-command> with 'npm test' from fspec-config.json", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 8, "text": "Python project with 'pytest' configured, <test-command> in documentation becomes 'pytest' in generated spec/CLAUDE.md", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 9, "text": "Rust project with 'cargo test' configured, quality commands ['cargo clippy', 'cargo fmt --check'], <quality-check-commands> becomes 'cargo clippy && cargo fmt --check' in spec/CLAUDE.md", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 10, "text": "User runs 'fspec configure-tools --help' and sees usage documentation with --test-command and --quality-commands options", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 11, "text": "User runs 'fspec configure-tools --test-command \"npm test\"' and spec/fspec-config.json is updated with tools.test.command", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 12, "text": "User runs 'fspec --help' and configure-tools appears in the command list alphabetically", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 13, "text": "User runs 'fspec configure-tools --quality-commands \"npm run lint\" \"npm run typecheck\"' and spec/fspec-config.json has tools.qualityCheck.commands array", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" } ], "questions": [ { "id": 0, "text": "@human: Should fspec store detected tool configuration in spec/fspec-config.json or spec/.fspec/tools.json?", "selected": true, "answer": "Store in spec/fspec-config.json with a 'tools' section (extend existing file that already stores agent config)", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 1, "text": "@human: Should the conversational detection happen ONLY on first run, or re-detect on every command if config is missing?", "selected": true, "answer": "One-time setup via explicit 'fspec configure-tools' command (like fspec init). Commands emit system-reminder if config missing, telling AI to run configure-tools. Detection happens once, used many times.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 2, "text": "@human: Should there be an explicit 'fspec configure-tools' command for manual reconfiguration, or only automatic detection?", "selected": true, "answer": "Yes - 'fspec configure-tools' supports both initial setup AND reconfiguration. Includes --reconfigure flag for re-detection, manual override flags for explicit commands. Handles tool changes (switching frameworks, adding quality checks) conversationally.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 3, "text": "@human: When multiple test frameworks detected (e.g., both Vitest and Jest), should AI ask which to use, or use heuristics to pick?", "selected": true, "answer": "Conversational approach - emit system-reminder with analysis (test file counts, config freshness), provide data-driven recommendation, AI asks human to choose via AskUserQuestion. Prevents silent wrong choices, respects human context.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 4, "text": "@human: Should system-reminders include search queries for best practices (e.g., 'Search for best Rust testing tools 2025') or just guide AI to search?", "selected": true, "answer": "Include specific, actionable search queries in system-reminders with current year (e.g., 'Query: best Rust testing frameworks 2025'). Provides date-aware guidance, reduces AI guesswork, ensures current best practices discovered.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" }, { "id": 5, "text": "@human: I found hardcoded 'npm test' and 'npm run' commands still in help files, slash command sections, project management sections, CLAUDE.md, and spec/CLAUDE.md. Should these ALL be replaced with dynamic placeholders like <test-command> that get filled in by system-reminders from fspec configure-tools?", "selected": true, "answer": "Yes, ALL hardcoded npm commands in documentation and help files MUST be replaced with dynamic placeholders like <test-command> and <quality-check-commands> that system-reminders will fill in based on fspec configure-tools configuration. This is required by Rule #9.", "deleted": false, "createdAt": "2025-10-26T02:51:30.219Z" } ], "estimate": 8, "nextRuleId": 18, "nextExampleId": 14, "nextQuestionId": 6, "nextNoteId": 0 }, "INIT-011": { "id": "INIT-011", "title": "Automatic version check and update for slash command files", "type": "story", "status": "done", "createdAt": "2025-10-26T11:23:10.274Z", "updatedAt": "2025-10-27T02:52:57.441Z", "description": "Add version check to fspec.md slash command that automatically detects outdated files and replaces them with latest version", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-26T11:23:15.359Z" }, { "state": "testing", "timestamp": "2025-10-26T11:37:48.248Z" }, { "state": "implementing", "timestamp": "2025-10-26T11:41:22.057Z" }, { "state": "validating", "timestamp": "2025-10-26T11:49:28.700Z" }, { "state": "done", "timestamp": "2025-10-26T11:55:42.486Z" }, { "state": "specifying", "timestamp": "2025-10-27T01:21:55.146Z" }, { "state": "testing", "timestamp": "2025-10-27T02:52:31.627Z" }, { "state": "implementing", "timestamp": "2025-10-27T02:52:37.347Z" }, { "state": "validating", "timestamp": "2025-10-27T02:52:43.856Z" }, { "state": "done", "timestamp": "2025-10-27T02:52:57.441Z" } ], "userStory": { "role": "developer who upgrades fspec to a new version", "action": "have slash command files automatically update to match the new version", "benefit": "I don't need to manually reinstall or update fspec configuration files" }, "questions": [ { "id": 0, "text": "@human: When the user runs /fspec, should version check happen BEFORE loading any help docs, or only when they try to execute fspec commands?", "selected": true, "answer": "Version check should happen as the FIRST command in fspec.md, before any help docs load. If version mismatch detected, it should STOP execution (exit 1) and tell the user to restart their AI agent.", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 1, "text": "@human: Where should the version number be stored in fspec.md? At the very top as a comment, or in a specific section?", "selected": true, "answer": "Version should be embedded as the first argument to fspec --sync-version command at the top of fspec.md. Example: 'fspec --sync-version 0.6.0'. No HTML comments, just plain markdown command call.", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 2, "text": "@human: Which files need version tracking and auto-replacement? Just .claude/commands/fspec.md, or also spec/CLAUDE.md, or both?", "selected": true, "answer": "Both files need tracking: .claude/commands/fspec.md (or equivalent for other agents) AND spec/CLAUDE.md. Both are updated when version mismatch detected.", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 3, "text": "@human: Should the auto-update be silent, or should it notify the user that files were updated?", "selected": true, "answer": "Show agent-specific restart instructions. Use agent detection from spec/fspec-config.json and generate appropriate message using similar logic to getActivationMessage(). Claude Code: 'Exit and start new conversation', Cursor: 'Restart Cursor', etc.", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 4, "text": "@human: What should happen if the version check command fails (network issue, file permissions, etc.)? Continue anyway or block execution?", "selected": true, "answer": "If version check fails (permissions, missing config, etc.), print warning but continue (exit 0). Only exit 1 for version mismatch. Include fallback: if can't detect agent, show generic 'Restart your AI agent' message.", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" } ], "rules": [ { "id": 0, "text": "Version check command must be the FIRST line executed in fspec.md before any help commands", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 1, "text": "Version embedded in fspec.md must match package.json version for check to pass", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 2, "text": "On version mismatch, command must update BOTH slash command file AND spec doc file", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 3, "text": "Exit code 1 on version mismatch (stops workflow), exit code 0 on match (continues workflow)", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 4, "text": "Restart instructions must be agent-specific using agent detection from fspec-config.json", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" } ], "examples": [ { "id": 0, "text": "User upgrades: npm install -g @sengac/fspec@0.7.0, runs /fspec in Claude Code, sees 'fspec --sync-version 0.6.0' execute, command detects mismatch, updates files, prints 'Updated to v0.7.0. Exit this conversation and start new one. Run /fspec again.', exits with code 1", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 1, "text": "User with current version runs /fspec, 'fspec --sync-version 0.7.0' executes silently (versions match), exits 0, AI continues loading help commands normally", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 2, "text": "Cursor user upgrades to v0.7.0, runs /fspec, version check detects mismatch, updates .cursor/commands/fspec.md and spec/CURSOR.md, prints 'Updated to v0.7.0. Restart Cursor and run /fspec again.'", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 3, "text": "User deletes spec/fspec-config.json, version check can't detect agent, updates files anyway, shows generic message: 'Updated to v0.7.0. Restart your AI agent and run /fspec again.'", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" }, { "id": 4, "text": "fspec init command automatically embeds current package.json version into generated fspec.md: 'fspec --sync-version 0.7.0'", "deleted": false, "createdAt": "2025-10-26T11:23:10.274Z" } ], "estimate": 5, "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 5, "nextNoteId": 0 }, "CONFIG-003": { "id": "CONFIG-003", "title": "Tool detection check functions not integrated into workflow", "type": "bug", "status": "done", "createdAt": "2025-10-26T16:13:38.381Z", "updatedAt": "2025-10-27T00:10:36.712Z", "description": "The checkTestCommand and checkQualityCommands functions exist and are tested but are never called during workflow transitions, preventing the conversational tool detection system from working as designed", "children": [], "attachments": [ "spec/attachments/CONFIG-003/CONFIG-003-integration-gap-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-26T16:15:07.361Z" }, { "state": "testing", "timestamp": "2025-10-26T16:34:33.358Z" }, { "state": "implementing", "timestamp": "2025-10-26T16:36:19.862Z" }, { "state": "validating", "timestamp": "2025-10-26T16:40:04.023Z" }, { "state": "done", "timestamp": "2025-10-26T16:42:47.394Z" }, { "state": "implementing", "timestamp": "2025-10-26T16:43:23.827Z" }, { "state": "validating", "timestamp": "2025-10-26T16:43:29.425Z" }, { "state": "done", "timestamp": "2025-10-26T16:43:37.697Z" }, { "state": "specifying", "timestamp": "2025-10-26T17:00:19.675Z" }, { "state": "testing", "timestamp": "2025-10-26T17:01:33.756Z" }, { "state": "implementing", "timestamp": "2025-10-26T17:02:54.595Z" }, { "state": "validating", "timestamp": "2025-10-26T17:05:26.255Z" }, { "state": "done", "timestamp": "2025-10-26T17:08:02.459Z" }, { "state": "specifying", "timestamp": "2025-10-26T17:13:20.043Z" }, { "state": "testing", "timestamp": "2025-10-26T17:13:39.812Z" }, { "state": "implementing", "timestamp": "2025-10-26T17:15:30.069Z" }, { "state": "validating", "timestamp": "2025-10-26T17:17:00.559Z" }, { "state": "done", "timestamp": "2025-10-26T17:19:52.814Z" }, { "state": "specifying", "timestamp": "2025-10-26T23:50:27.625Z" }, { "state": "testing", "timestamp": "2025-10-26T23:54:20.061Z" }, { "state": "implementing", "timestamp": "2025-10-26T23:56:33.276Z" }, { "state": "validating", "timestamp": "2025-10-26T23:58:58.093Z" }, { "state": "done", "timestamp": "2025-10-27T00:10:36.712Z" } ], "rules": [ { "id": 0, "text": "Check functions MUST be called during status transitions to 'validating' state", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 1, "text": "System-reminders MUST be emitted when config is missing to guide AI to run fspec configure-tools", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 2, "text": "System-reminders MUST be emitted when config exists to tell AI what commands to run", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 3, "text": "Integration MUST use existing checkTestCommand and checkQualityCommands functions without modification", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 4, "text": "sync-version MUST fail (exit 1) when tool configuration is missing to prevent AI from continuing workflow without proper setup", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 5, "text": "sync-version MUST fail (exit 1) when version is incorrect to prevent AI from continuing with wrong version", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 6, "text": "sync-version MUST emit system-reminder about configure-tools when tool configuration is completely missing (file does not exist)", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 7, "text": "configure-tools MUST regenerate agent templates (spec/CLAUDE.md, .claude/commands/fspec.md, etc.) after updating config to ensure templates reflect latest version", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 8, "text": "configure-tools MUST regenerate templates silently (no output to user about template regeneration) to avoid cluttering the output with implementation details", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" } ], "examples": [ { "id": 0, "text": "AI runs 'fspec update-work-unit-status AUTH-001 validating' with no config, sees system-reminder: 'NO TEST COMMAND CONFIGURED'", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 1, "text": "AI runs 'fspec update-work-unit-status AUTH-001 validating' with config present, sees system-reminder: 'Run tests: npm test'", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 2, "text": "AI receives reminder, runs 'fspec configure-tools --test-command npm test', then validation emits actual command", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 3, "text": "Integration test verifies checkTestCommand and checkQualityCommands are called during status transition", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 4, "text": "AI runs 'fspec --sync-version 0.6.0' with no tool config, sees system-reminder, command exits with code 1, AI cannot continue until tools are configured", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 5, "text": "AI runs 'fspec --sync-version 0.5.0' when actual version is 0.6.0, sees version mismatch error, command exits with code 1, AI cannot continue until correct version used", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 6, "text": "AI runs 'fspec --sync-version 0.6.0' when spec/fspec-config.json does not exist, sees system-reminder to run configure-tools, command exits with code 1, AI runs configure-tools then re-runs sync-version", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 7, "text": "AI runs 'fspec configure-tools --test-command npm test', command saves config AND regenerates spec/CLAUDE.md and .claude/commands/fspec.md with latest templates, ensuring AI has up-to-date documentation", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" }, { "id": 8, "text": "AI runs 'fspec configure-tools --test-command npm test', sees only '✓ Tool configuration saved to spec/fspec-config.json' output, templates regenerated silently in background without additional messages", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" } ], "questions": [ { "id": 0, "text": "@human: Should --sync-version also emit tool configuration checks to help onboard new AI agents?", "selected": true, "answer": "Yes - sync-version should emit tool config checks. This helps onboard new AI agents by guiding them to configure tools immediately after version update, ensuring they have complete workflow setup.", "deleted": false, "createdAt": "2025-10-26T16:13:38.381Z" } ], "assumptions": [ "Yes - sync-version should emit tool config checks. This helps onboard new AI agents by guiding them to configure tools immediately after version update, ensuring they have complete workflow setup." ], "userStory": { "role": "AI agent using fspec for ACDD workflow", "action": "receive automatic guidance about tool configuration and version sync", "benefit": "I can complete proper workflow setup without manual intervention and avoid continuing with incorrect configuration" }, "estimate": 2, "nextRuleId": 9, "nextExampleId": 9, "nextQuestionId": 1, "nextNoteId": 0 }, "INIT-012": { "id": "INIT-012", "title": "Dynamic bootstrap command for slash command template", "type": "story", "status": "done", "createdAt": "2025-10-27T01:21:53.487Z", "updatedAt": "2025-10-27T03:11:29.158Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T01:22:04.407Z" }, { "state": "testing", "timestamp": "2025-10-27T01:46:45.501Z" }, { "state": "implementing", "timestamp": "2025-10-27T01:56:24.108Z" }, { "state": "validating", "timestamp": "2025-10-27T01:56:28.682Z" }, { "state": "done", "timestamp": "2025-10-27T01:59:15.192Z" }, { "state": "specifying", "timestamp": "2025-10-27T02:06:07.106Z" }, { "state": "testing", "timestamp": "2025-10-27T02:06:46.604Z" }, { "state": "specifying", "timestamp": "2025-10-27T02:07:31.010Z" }, { "state": "testing", "timestamp": "2025-10-27T02:08:41.504Z" }, { "state": "implementing", "timestamp": "2025-10-27T02:09:25.151Z" }, { "state": "validating", "timestamp": "2025-10-27T02:11:45.377Z" }, { "state": "done", "timestamp": "2025-10-27T02:15:08.725Z" }, { "state": "specifying", "timestamp": "2025-10-27T02:18:30.120Z" }, { "state": "testing", "timestamp": "2025-10-27T02:20:59.216Z" }, { "state": "specifying", "timestamp": "2025-10-27T02:21:38.797Z" }, { "state": "testing", "timestamp": "2025-10-27T02:23:58.730Z" }, { "state": "implementing", "timestamp": "2025-10-27T02:24:46.688Z" }, { "state": "specifying", "timestamp": "2025-10-27T02:26:53.055Z" }, { "state": "testing", "timestamp": "2025-10-27T02:27:27.561Z" }, { "state": "implementing", "timestamp": "2025-10-27T02:27:32.491Z" }, { "state": "validating", "timestamp": "2025-10-27T02:34:11.257Z" }, { "state": "done", "timestamp": "2025-10-27T02:37:03.622Z" }, { "state": "specifying", "timestamp": "2025-10-27T02:40:19.361Z" }, { "state": "testing", "timestamp": "2025-10-27T02:41:58.310Z" }, { "state": "implementing", "timestamp": "2025-10-27T02:42:37.378Z" }, { "state": "validating", "timestamp": "2025-10-27T02:43:15.910Z" }, { "state": "done", "timestamp": "2025-10-27T02:45:24.124Z" }, { "state": "specifying", "timestamp": "2025-10-27T02:59:07.597Z" }, { "state": "testing", "timestamp": "2025-10-27T03:01:51.903Z" }, { "state": "implementing", "timestamp": "2025-10-27T03:02:42.242Z" }, { "state": "validating", "timestamp": "2025-10-27T03:04:05.920Z" }, { "state": "done", "timestamp": "2025-10-27T03:11:29.158Z" } ], "userStory": { "role": "AI agent using fspec", "action": "load documentation dynamically via bootstrap command", "benefit": "slash command template stays lightweight and content is always fresh" }, "questions": [ { "id": 0, "text": "@human: Should 'fspec bootstrap' output be identical to what's currently in the template after fspec --sync-version, or can we improve/reorganize it?", "selected": true, "answer": "'fspec bootstrap' command executes ALL section-generating functions internally (getHeaderSection(), getAcddConceptSection(), etc.) and outputs the combined template content. Uses existing slashCommandTemplate.ts functions. AI agent runs ONE Bash command (fspec bootstrap) instead of 8 separate help commands. See attachment: bootstrap-command-behavior.md", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 1, "text": "@human: Should 'fspec bootstrap' be mandatory (fail if not run), or optional (gracefully handle if skipped)?", "selected": true, "answer": "Bootstrap is ABSOLUTELY MANDATORY. If skipped, fspec commands MUST FAIL with clear error message instructing user to run 'fspec bootstrap' first. No fspec workflow commands should work until bootstrap completes successfully.", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 2, "text": "@human: Should the bootstrap command check if documentation is already loaded (avoid duplicate loading in same session)?", "selected": true, "answer": "No need to track or prevent duplicate runs. If user runs 'fspec bootstrap' multiple times, it just outputs documentation again. No harm done.", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 3, "text": "@human: What should happen to existing .claude/commands/fspec.md files when users upgrade? Auto-migrate to new format, or require manual deletion?", "selected": true, "answer": "No special migration logic needed. Existing --sync-version mechanism handles it automatically. When version mismatch detected, installAgentFiles() regenerates template with new 2-command format. Clean, simple, follows existing architectural pattern.", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 4, "text": "@human: Should 'fspec bootstrap' accept arguments (like --skip-help or --minimal) to customize what gets loaded?", "selected": true, "answer": "NO customization allowed. 'fspec bootstrap' MUST output everything with NO options to skip sections. No --skip-help, no --minimal, no --skip-sections flags. Bootstrap outputs complete documentation ALWAYS.", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" } ], "rules": [ { "id": 0, "text": "The slash command template must contain ONLY two commands: 'fspec --sync-version X.X.X' and 'fspec bootstrap'", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 1, "text": "All documentation content currently after 'fspec --sync-version' must be moved to dynamically generated output of 'fspec bootstrap'", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 2, "text": "'fspec bootstrap' must execute the same help commands that are currently hardcoded (fspec --help, fspec help specs, etc.)", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 3, "text": "Keep output identical to current template. Use existing template generation functions (with string replacement for <test-command> and <quality-check-commands> placeholders)", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 4, "text": "Bootstrap is ABSOLUTELY MANDATORY. If skipped, fspec commands MUST FAIL with clear error message instructing user to run 'fspec bootstrap' first. No fspec workflow commands should work until bootstrap completes successfully.", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 5, "text": "NO customization allowed. 'fspec bootstrap' MUST output everything with NO options to skip sections. No --skip-help, no --minimal, no --skip-sections flags. Bootstrap outputs complete documentation ALWAYS.", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 6, "text": "Bootstrap command MUST internally execute these specific help commands that were removed from the template: 'fspec --help', 'fspec help specs', 'fspec help work', 'fspec help discovery', 'fspec help metrics', 'fspec help setup', 'fspec help hooks'", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 7, "text": "Bootstrap output MUST be byte-for-byte identical to what previously appeared in the template after running all 7 help commands (fspec --help, fspec help specs, fspec help work, fspec help discovery, fspec help metrics, fspec help setup, fspec help hooks)", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 8, "text": "The get*HelpContent() functions in src/help.ts MUST return the EXACT SAME content as their corresponding display*Help() functions, but as a string instead of console.log output", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 9, "text": "getSpecsHelpContent() currently returns 6-line stub text, but MUST return the full 333 lines from displaySpecsHelp() function (lines 164-496 in help.ts)", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 10, "text": "getWorkHelpContent() currently returns 6-line stub text, but MUST return the full 308 lines from displayWorkHelp() function (lines 498-805 in help.ts)", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 11, "text": "getDiscoveryHelpContent(), getMetricsHelpContent(), getSetupHelpContent(), and getHooksHelpContent() all return stub text and MUST return their full display function content", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 12, "text": "The display*Help() functions use console.log() and chalk for colored output - the get*HelpContent() functions MUST strip chalk formatting and return plain text strings", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 13, "text": "The get*HelpContent() functions MUST NOT duplicate code - they should call the existing display*Help() functions, capture the console.log output, strip chalk formatting, and return the plain text string", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 14, "text": "Use console interception or mock console.log to capture output from display*Help() functions, then strip ANSI escape codes (chalk formatting) using a utility function or regex", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 15, "text": "BEFORE the help command outputs, bootstrap MUST display an explainer section that tells the AI agent: (1) what the following content is (output from fspec help commands), (2) WHY this information is critical (complete command reference for all fspec features), (3) HOW to access specific sections again (run individual help commands like 'fspec help specs', 'fspec help work', etc. - NOT 'fspec bootstrap')", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 16, "text": "The explainer MUST appear immediately after the header sections (Step 1 and Step 1.5) and BEFORE the help command outputs (Step 2), so AI agents see it before reading the command documentation", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 17, "text": "The slash command template file (.claude/commands/fspec.md) MUST contain ONLY the header instruction block (lines 1-10: title, IMMEDIATELY section with two commands, fspec CLI note, YOU MUST RUN warning). Everything after line 10 MUST BE REMOVED from the template because it is output by 'fspec bootstrap'", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 18, "text": "The 'fspec bootstrap' command output MUST contain the complete workflow documentation starting from the persona/role description paragraph ('You are a master of project management...') through all ACDD workflow sections, Example Mapping, Kanban workflow, and complete help command outputs", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 19, "text": "The template generation function getSlashCommandTemplate() in src/utils/slashCommandTemplate.ts MUST return ONLY the minimal header (title + IMMEDIATELY section + two commands). Remove all content after 'YOU MUST RUN THOSE COMMANDS...' - that content is now generated by bootstrap command", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" } ], "attachments": [ "spec/attachments/INIT-012/bootstrap-command-behavior.md" ], "examples": [ { "id": 0, "text": "User runs 'fspec board' without running 'fspec bootstrap' first, command exits with error: 'ERROR: fspec bootstrap must be run first. Run: fspec bootstrap'", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 1, "text": "User runs 'fspec --sync-version 0.6.0' then 'fspec bootstrap' successfully, then runs 'fspec board' - command executes normally", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 2, "text": "AI runs 'fspec bootstrap', command internally calls getHeaderSection(), getAcddConceptSection(), etc., combines output, applies string replacement, prints to stdout", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 3, "text": "AI runs 'fspec bootstrap' which internally executes: getHelpOutput(), getSpecsHelpOutput(), getWorkHelpOutput(), getDiscoveryHelpOutput(), getMetricsHelpOutput(), getSetupHelpOutput(), getHooksHelpOutput(), then combines and outputs all results", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 4, "text": "When AI runs 'fspec bootstrap', the output MUST include complete 'fspec --help' content showing all command groups (specs, work, discovery, metrics, setup, hooks)", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 5, "text": "When AI runs 'fspec bootstrap', the output MUST include complete 'fspec help specs' content with ALL commands: create-feature, add-scenario, add-step, validate, format, link-coverage, add-tag-to-feature, etc.", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 6, "text": "When AI runs 'fspec bootstrap', the output MUST include complete 'fspec help work' content with ALL commands: create-story, create-bug, create-task, update-work-unit-status, board, checkpoint, restore-checkpoint, list-checkpoints, cleanup-checkpoints, etc.", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 7, "text": "Currently 'fspec bootstrap' outputs stub text like 'Commands for creating and managing Gherkin feature files: create-feature, add-scenario, add-step, validate, format, and more.' This is WRONG - it must output the FULL command documentation", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 8, "text": "getSpecsHelpContent() calls displaySpecsHelp() internally, captures all console.log output into a string array, joins it with newlines, strips chalk ANSI codes, returns plain text", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 9, "text": "The explainer section should say something like: 'The following sections contain complete fspec command documentation. This is the output from running: fspec --help, fspec help specs, fspec help work, fspec help discovery, fspec help metrics, fspec help setup, fspec help hooks. You can run these commands individually at any time to refresh specific sections.'", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" }, { "id": 10, "text": "The .claude/commands/fspec.md file should contain ONLY these 10 lines: '# fspec Command - Kanban-Based Project Management\\n\\nIMMEDIATELY - run these commands...\\n\\n1. fspec --sync-version 0.6.0\\n2. fspec bootstrap\\n\\nfspec is a CLI program...\\n\\nYOU MUST RUN THOSE COMMANDS...' - Everything else (persona description, ACDD cycle, Example Mapping, etc.) is output by bootstrap command", "deleted": false, "createdAt": "2025-10-27T01:21:53.487Z" } ], "assumptions": [ "No need to track or prevent duplicate runs. If user runs 'fspec bootstrap' multiple times, it just outputs documentation again. No harm done.", "No special migration logic needed. Existing --sync-version mechanism handles it automatically. When version mismatch detected, installAgentFiles() regenerates template with new 2-command format. Clean, simple, follows existing architectural pattern." ], "estimate": 5, "nextRuleId": 20, "nextExampleId": 11, "nextQuestionId": 5, "nextNoteId": 0 }, "HELP-004": { "id": "HELP-004", "title": "Add comprehensive help documentation for bootstrap and configure-tools commands", "type": "story", "status": "done", "createdAt": "2025-10-27T03:16:30.302Z", "updatedAt": "2025-10-27T03:31:31.655Z", "description": "Add missing help documentation for fspec bootstrap and fspec configure-tools commands. This includes: creating help functions in src/help.ts and src/commands/*-help.ts, updating README.md with command documentation, updating template autogenerators that generate spec/CLAUDE.md and bootstrap output, and updating relevant documentation in the docs directory to ensure consistency across all documentation sources.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T03:17:14.097Z" }, { "state": "testing", "timestamp": "2025-10-27T03:21:12.976Z" }, { "state": "implementing", "timestamp": "2025-10-27T03:22:27.036Z" }, { "state": "validating", "timestamp": "2025-10-27T03:25:26.871Z" }, { "state": "done", "timestamp": "2025-10-27T03:31:31.655Z" } ], "userStory": { "role": "developer or AI agent using fspec", "action": "access comprehensive help documentation for bootstrap and configure-tools commands", "benefit": "I understand how to use these commands effectively without consulting source code" }, "rules": [ { "id": 0, "text": "Each command must have a comprehensive help file following the CommandHelpConfig pattern", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 1, "text": "Help files must include whenToUse, prerequisites, typicalWorkflow, commonErrors, and relatedCommands sections", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 2, "text": "Bootstrap command output must be auto-generated from help content functions", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 3, "text": "README.md must document both commands with usage examples and options", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 4, "text": "Documentation in docs directory must be synchronized with help content", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'fspec bootstrap --help' and sees comprehensive help with whenToUse, prerequisites, typicalWorkflow sections", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 1, "text": "Developer runs 'fspec configure-tools --help' and sees comprehensive help with platform-agnostic examples", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 2, "text": "AI agent runs 'fspec bootstrap' and receives complete workflow documentation with all command help sections", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 3, "text": "Developer searches README.md for configure-tools and finds complete documentation with all options and examples", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 4, "text": "Documentation in docs/commands/bootstrap.md matches help content with no inconsistencies", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" } ], "questions": [ { "id": 0, "text": "@human: Should bootstrap command help be added to src/help.ts main help output, or only accessible via --help flag?", "selected": true, "answer": "Only accessible via --help flag, following existing pattern", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 1, "text": "@human: Do we need separate documentation files in docs/ directory, or should we rely on generated help from the help config files?", "selected": true, "answer": "Update existing docs files that reference these commands, use generated help from config files", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" }, { "id": 2, "text": "@human: Should configure-tools help include specific examples for Node.js, Python, Rust, and Go, or keep it generic?", "selected": true, "answer": "Include specific examples for Node.js, Python, Rust, and Go to match existing platform-agnostic guidance", "deleted": false, "createdAt": "2025-10-27T03:16:30.302Z" } ], "estimate": 5, "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 0 }, "ITF-001": { "id": "ITF-001", "title": "Scaffold TUI infrastructure with Ink and cage components", "type": "story", "status": "done", "createdAt": "2025-10-27T04:16:56.752Z", "updatedAt": "2025-10-27T04:38:23.326Z", "description": "Install Ink, @inkjs/ui, Zustand dependencies. Copy cage's shared components (VirtualList, FullScreenLayout, InputContext, useSafeInput). Create ViewManager, App.tsx, fspecStore. Add TUI command. Make 'fspec' with no args launch TUI.", "epic": "interactive-tui-foundation", "children": [], "attachments": [ "spec/attachments/ITF-001/tui-foundation-architecture.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T04:19:50.184Z" }, { "state": "testing", "timestamp": "2025-10-27T04:28:41.448Z" }, { "state": "implementing", "timestamp": "2025-10-27T04:31:32.718Z" }, { "state": "validating", "timestamp": "2025-10-27T04:34:11.761Z" }, { "state": "done", "timestamp": "2025-10-27T04:38:23.326Z" } ], "userStory": { "role": "developer building fspec's interactive TUI", "action": "scaffold core TUI infrastructure with Ink, Zustand, and reusable components from cage", "benefit": "I can build the interactive Kanban board and other TUI features on a solid, tested foundation" }, "rules": [ { "id": 0, "text": "TUI infrastructure must use Ink (React for CLIs) as the rendering engine", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 1, "text": "State management must use Zustand with Immer for immutable updates", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 2, "text": "Component library must include @inkjs/ui for pre-built UI primitives", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 3, "text": "Components must be TypeScript with strict type safety (no 'any' types)", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 4, "text": "All components must be tested with ink-testing-library", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 5, "text": "Components must follow cage's architectural patterns (ViewManager, FullScreenLayout, modal input modes)", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" } ], "examples": [ { "id": 0, "text": "Developer imports FullScreenLayout from src/tui/layouts and wraps a simple Text component - renders with title bar and footer", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 1, "text": "Developer uses ViewManager to navigate between two views - navigation works, back button returns to previous view", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 2, "text": "Developer creates Zustand store with fspec work units data - updates trigger re-renders in Ink components", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 3, "text": "Developer writes test with ink-testing-library's render() - can query rendered output and assert on text content", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 4, "text": "Developer creates modal input mode component - switches between normal and insert modes with 'i' key", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" } ], "questions": [ { "id": 0, "text": "@human: Should we copy components directly from cage or create similar components inspired by cage's patterns?", "selected": true, "answer": "Create similar components inspired by cage's patterns (not direct copies). This ensures fspec has full control over the codebase, follows fspec's TypeScript standards, and avoids cage-specific dependencies. Adapt patterns but write fresh TypeScript code.", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 1, "text": "@human: Do we need VirtualList component in Phase 1 scaffold or should it wait for ITF-002 (performance optimization)?", "selected": true, "answer": "VirtualList should be in Phase 1 scaffold. It's a foundational component needed for Kanban columns and work unit lists. Starting without it would require refactoring later. Include it in the initial scaffold.", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" }, { "id": 2, "text": "@human: Should the scaffold include basic keyboard navigation hooks or just the component structure?", "selected": true, "answer": "Include basic keyboard navigation hooks (useSafeInput, InputModeContext) in scaffold. These are foundational and needed for all interactive components. Without them, every component would need to reinvent input handling.", "deleted": false, "createdAt": "2025-10-27T04:16:56.752Z" } ], "estimate": 8, "nextRuleId": 6, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 0 }, "ITF-002": { "id": "ITF-002", "title": "Zustand state management setup for fspec data", "type": "story", "status": "done", "createdAt": "2025-10-27T04:16:57.254Z", "updatedAt": "2025-10-27T05:10:30.340Z", "description": "Create fspecStore with work units, epics, features, tags state. Add actions: loadWorkUnits, updateWorkUnit, createWorkUnit, deleteWorkUnit. Integrate with existing JSON file operations. Handle real-time updates with file watchers or polling.", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T04:58:56.621Z" }, { "state": "testing", "timestamp": "2025-10-27T05:01:58.555Z" }, { "state": "implementing", "timestamp": "2025-10-27T05:03:46.531Z" }, { "state": "validating", "timestamp": "2025-10-27T05:08:22.056Z" }, { "state": "done", "timestamp": "2025-10-27T05:10:30.340Z" } ], "userStory": { "role": "developer building interactive TUI", "action": "have Zustand store automatically load and sync all fspec data from JSON files", "benefit": "the TUI can display real work units, epics, and features without manual data loading" }, "rules": [ { "id": 0, "text": "Store must load data from spec/work-units.json, spec/epics.json, spec/features/ directory", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 1, "text": "Store must use Zustand with Immer for immutable state updates", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 2, "text": "Store actions must integrate with existing loadWorkUnits, loadEpics utility functions", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 3, "text": "Store must provide selectors for filtering work units by status, epic, prefix", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 4, "text": "Store initialization must be async to load JSON files from disk", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" } ], "examples": [ { "id": 0, "text": "Store initializes and loads 206 work units from work-units.json - workUnits array has 206 items", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 1, "text": "Store loads 13 epics from epics.json - epics array has correct data structure with id, title, workUnits", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 2, "text": "Component calls useWorkUnitsByStatus('backlog') - returns filtered array of work units in backlog status", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 3, "text": "Component updates work unit status via store action - state updates immutably and component re-renders", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 4, "text": "Store provides getWorkUnitsByEpic selector - returns work units filtered by epic ID", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" } ], "questions": [ { "id": 0, "text": "@human: Should the store poll for file changes or use file watchers for real-time updates?", "selected": true, "answer": "For ITF-002, keep it simple: no file watchers or polling yet. Just load once on initialization. Real-time updates will be handled in BOARD-003.", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 1, "text": "@human: Should store initialization happen automatically on import or require explicit init() call?", "selected": true, "answer": "Require explicit init() call. This gives TUI control over when to load data and allows error handling during startup.", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" }, { "id": 2, "text": "@human: Should the store cache data in memory or reload from disk on every access?", "selected": true, "answer": "Cache in memory after loading. TUI needs fast access to data for rendering. BOARD-003 will handle refreshing when files change.", "deleted": false, "createdAt": "2025-10-27T04:16:57.254Z" } ], "estimate": 5, "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 3, "nextNoteId": 0 }, "ITF-003": { "id": "ITF-003", "title": "Launch interactive TUI when running fspec with no arguments", "type": "story", "status": "done", "createdAt": "2025-10-27T06:11:30.017Z", "updatedAt": "2025-10-27T06:23:02.545Z", "description": "Running 'fspec' with no arguments should launch the interactive Kanban board TUI instead of showing help text. This provides immediate visual feedback and makes the TUI the default interface.", "epic": "interactive-tui-foundation", "children": [], "userStory": { "role": "developer using fspec", "action": "see my work units visually when I run fspec", "benefit": "I get immediate visual feedback and can navigate my work interactively" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T06:11:45.400Z" }, { "state": "testing", "timestamp": "2025-10-27T06:13:52.454Z" }, { "state": "implementing", "timestamp": "2025-10-27T06:14:51.816Z" }, { "state": "validating", "timestamp": "2025-10-27T06:19:05.928Z" }, { "state": "done", "timestamp": "2025-10-27T06:21:27.950Z" }, { "state": "specifying", "timestamp": "2025-10-27T06:21:52.480Z" }, { "state": "testing", "timestamp": "2025-10-27T06:22:59.197Z" }, { "state": "implementing", "timestamp": "2025-10-27T06:23:00.321Z" }, { "state": "validating", "timestamp": "2025-10-27T06:23:01.434Z" }, { "state": "done", "timestamp": "2025-10-27T06:23:02.545Z" } ], "rules": [ { "id": 0, "text": "Running 'fspec' with no arguments MUST launch the interactive TUI (BoardView component)", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" }, { "id": 1, "text": "Running 'fspec --help' MUST still show help text (not launch TUI)", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" }, { "id": 2, "text": "Running 'fspec help' MUST still show help text (not launch TUI)", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" }, { "id": 3, "text": "TUI MUST be rendered using existing BoardView component (DRY - reuse BOARD-002 implementation)", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" }, { "id": 4, "text": "TUI MUST exit cleanly when user presses ESC or q key", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" } ], "examples": [ { "id": 0, "text": "Developer runs 'fspec' → BoardView TUI launches → Shows Kanban board with work units", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" }, { "id": 1, "text": "Developer runs 'fspec --help' → Help text displays → TUI does NOT launch", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" }, { "id": 2, "text": "Developer runs 'fspec validate' → Validation executes → TUI does NOT launch", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" }, { "id": 3, "text": "Developer in TUI presses ESC → TUI exits cleanly → Returns to shell prompt", "deleted": false, "createdAt": "2025-10-27T06:11:30.017Z" } ], "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "ITF-004": { "id": "ITF-004", "title": "Fix TUI Kanban column layout to match table style", "type": "story", "status": "done", "createdAt": "2025-10-27T06:40:55.477Z", "updatedAt": "2025-10-27T07:56:53.007Z", "description": "Update interactive TUI Kanban columns to use table layout instead of boxed columns, matching the visual style of fspec board command", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T06:41:00.684Z" }, { "state": "testing", "timestamp": "2025-10-27T06:51:25.894Z" }, { "state": "implementing", "timestamp": "2025-10-27T06:53:34.347Z" }, { "state": "validating", "timestamp": "2025-10-27T07:01:49.813Z" }, { "state": "done", "timestamp": "2025-10-27T07:06:36.436Z" }, { "state": "specifying", "timestamp": "2025-10-27T07:10:44.985Z" }, { "state": "testing", "timestamp": "2025-10-27T07:13:11.960Z" }, { "state": "implementing", "timestamp": "2025-10-27T07:14:34.345Z" }, { "state": "validating", "timestamp": "2025-10-27T07:15:49.906Z" }, { "state": "done", "timestamp": "2025-10-27T07:19:38.141Z" }, { "state": "implementing", "timestamp": "2025-10-27T07:21:15.684Z" }, { "state": "specifying", "timestamp": "2025-10-27T07:24:45.644Z" }, { "state": "testing", "timestamp": "2025-10-27T07:25:29.339Z" }, { "state": "implementing", "timestamp": "2025-10-27T07:26:07.700Z" }, { "state": "validating", "timestamp": "2025-10-27T07:28:26.199Z" }, { "state": "done", "timestamp": "2025-10-27T07:28:36.178Z" }, { "state": "specifying", "timestamp": "2025-10-27T07:30:54.143Z" }, { "state": "testing", "timestamp": "2025-10-27T07:31:53.126Z" }, { "state": "implementing", "timestamp": "2025-10-27T07:31:54.238Z" }, { "state": "validating", "timestamp": "2025-10-27T07:54:01.324Z" }, { "state": "done", "timestamp": "2025-10-27T07:56:53.007Z" } ], "userStory": { "role": "developer using the interactive TUI", "action": "view the Kanban board with a consistent table layout", "benefit": "the interface is clean, familiar, and matches the fspec board command style" }, "rules": [ { "id": 0, "text": "Columns must be part of a unified table with box-drawing characters (┌┬┐ ├┼┤ └┴┘), not individual bordered boxes", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 1, "text": "Column headers must show: STATUS (count) - Xpts format", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 2, "text": "Work units within columns must show: typeIcon ID Xpt priorityIcon", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 3, "text": "The table layout must adapt to terminal width like fspec board does", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 4, "text": "Focused column must be highlighted with cyan color", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 5, "text": "Selected work unit within focused column must be highlighted", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 6, "text": "All panels (Git Stashes, Changed Files, Kanban columns, footer) should be integrated into a single unified table layout to avoid duplicate borders", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 7, "text": "Footer should be integrated into the unified table layout", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 8, "text": "Support scrolling through ALL items with Page Up/Down. Show up arrow indicator above first visible item if scrolled past start. Show down arrow indicator below last visible item if more items exist beyond viewport. No artificial limit.", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 9, "text": "Arrow up/down keys scroll one item at a time within focused column", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 10, "text": "Page Up/Page Down keys scroll by full page (viewport height) of items at a time for faster navigation", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 11, "text": "Component MUST register resize listener on stdout.on('resize', handler) to detect terminal dimension changes", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 12, "text": "Terminal dimensions MUST be stored in React state to trigger re-renders when terminal resizes", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 13, "text": "Component MUST cleanup resize listener with stdout.off('resize', handler) in useEffect cleanup to prevent memory leaks", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 14, "text": "Column width calculation MUST be reactive using useMemo with terminal dimensions as dependency", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 15, "text": "Layout MUST provide fallback dimensions (80 columns, 24 rows) when stdout dimensions unavailable", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 16, "text": "MUST use useStdout directly and read stdout.columns (same pattern as BoardDisplay), NOT a custom useTerminalSize hook with state", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 17, "text": "Column width calculation MUST be wrapped in useMemo with terminalWidth as dependency to recalculate on terminal changes", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 18, "text": "Table row building MUST also be wrapped in useMemo with colWidth as dependency so entire table rebuilds on resize", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 19, "text": "Focused column header MUST be highlighted in cyan color to show which column is active", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 20, "text": "Selected work unit within focused column MUST be highlighted with cyan background to show which item is active", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 21, "text": "Column headers and work unit rows MUST use Ink Text components with color/backgroundColor props, NOT plain strings, to support highlighting", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" } ], "examples": [ { "id": 0, "text": "User opens TUI, sees table with ┌┬┐ top border connecting all columns", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 1, "text": "User navigates right with arrow key, sees focused column header turn cyan while others stay gray", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 2, "text": "User navigates down within a column, sees selected work unit highlighted with cyan background", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 3, "text": "User resizes terminal, table columns adjust width proportionally like fspec board", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 4, "text": "Column shows AUTH-001 3pt 🟡 format with type icon and priority indicator", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 5, "text": "User has 20 work units in backlog, presses Page Down, sees viewport scroll showing items 11-20 with up arrow indicator at top", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 6, "text": "User scrolls to middle of long column, sees both up arrow at top and down arrow at bottom indicating more items in both directions", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 7, "text": "User presses Page Up at top of column, nothing happens (already at start, no up arrow shown)", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 8, "text": "Git Stashes panel integrated as table row above Kanban columns with proper ├┼┤ junction characters", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 9, "text": "User presses arrow down, selected item moves down by 1 work unit", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 10, "text": "User presses Page Down with 30 items and viewport showing 10 items, viewport jumps to show items 11-20", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 11, "text": "User opens TUI at 120 columns wide, sees table with properly aligned borders. User resizes terminal to 80 columns, table instantly reflows with recalculated column widths and borders still properly aligned", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 12, "text": "Component mounts, registers resize listener on stdout. Component unmounts, cleanup function removes resize listener to prevent memory leak", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 13, "text": "Terminal resizes from 100 to 140 columns, column width recalculates from 12 chars to 18 chars, all work units and headers fit properly without truncation", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 14, "text": "BoardDisplay uses: const { stdout } = useStdout(); const terminalWidth = stdout?.columns || 80; const colWidth = useMemo(() => calculateColumnWidth(terminalWidth), [terminalWidth]); - This pattern works perfectly", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 15, "text": "UnifiedBoardLayout initially tried custom useTerminalSize hook with useState and resize listeners - This caused stale initial values and didn't match fspec board behavior", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 16, "text": "User presses right arrow, BACKLOG header shows in gray, SPECIFYING header changes to cyan (focused). Work units in SPECIFYING column are visible, first one has cyan background (selected)", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 17, "text": "User presses down arrow, first work unit in focused column loses cyan background, second work unit gets cyan background (selection moved)", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" } ], "questions": [ { "id": 0, "text": "@human: Should the Git Stashes and Changed Files panels also use table layout, or keep their current bordered box style?", "selected": true, "answer": "All panels (Git Stashes, Changed Files, Kanban columns, footer) should be integrated into a single unified table layout to avoid duplicate borders", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 1, "text": "@human: Should the footer with keyboard shortcuts also use table borders, or keep its current style?", "selected": true, "answer": "Footer should be integrated into the unified table layout", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" }, { "id": 2, "text": "@human: Do you want the same column limit behavior (showing first 5 items + overflow count) as fspec board?", "selected": true, "answer": "Support scrolling through ALL items with Page Up/Down. Show up arrow indicator above first visible item if scrolled past start. Show down arrow indicator below last visible item if more items exist beyond viewport. No artificial limit.", "deleted": false, "createdAt": "2025-10-27T06:40:55.477Z" } ], "estimate": 5, "nextRuleId": 22, "nextExampleId": 18, "nextQuestionId": 3, "nextNoteId": 0 }, "ITF-005": { "id": "ITF-005", "title": "Real-time file and git status watching in TUI", "type": "story", "status": "done", "createdAt": "2025-10-27T08:14:53.044Z", "updatedAt": "2025-10-27T08:34:33.724Z", "description": "Add fs.watch watchers for .git/refs/stash and .git/index to detect real-time changes to git stashes and file status (staged/unstaged). Update Zustand store reactively when changes are detected, similar to the existing work-units.json watcher. Reuse existing isomorphic-git functions and follow DRY principles.", "epic": "interactive-tui-foundation", "children": [], "userStory": { "role": "developer using fspec TUI", "action": "see real-time updates to git stashes and file status", "benefit": "the board reflects current state without manual refresh" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T08:15:22.144Z" }, { "state": "testing", "timestamp": "2025-10-27T08:18:48.076Z" }, { "state": "implementing", "timestamp": "2025-10-27T08:20:07.365Z" }, { "state": "validating", "timestamp": "2025-10-27T08:28:13.409Z" }, { "state": "done", "timestamp": "2025-10-27T08:34:33.724Z" } ], "rules": [ { "id": 0, "text": "TUI must watch .git/refs/stash for real-time git stash changes", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 1, "text": "TUI must watch .git/index for real-time file status changes (staged/unstaged)", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 2, "text": "Watchers must update Zustand store state to trigger React re-renders", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 3, "text": "MUST reuse existing isomorphic-git functions: getStagedFiles, getUnstagedFiles from src/git/status.ts", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 4, "text": "MUST reuse existing git.log({ ref: 'refs/stash' }) pattern for loading stashes (DRY principle)", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 5, "text": "Watchers must be cleaned up on component unmount to prevent memory leaks", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 6, "text": "Store must provide actions: loadStashes(), loadFileStatus() to be called by watchers", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 7, "text": "TUI must watch .git/HEAD for branch changes and commits on current branch", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" } ], "examples": [ { "id": 0, "text": "User opens TUI, creates git stash via terminal, TUI automatically updates stash panel without restart", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 1, "text": "User stages a file with git add, TUI immediately shows file in staged section (green)", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 2, "text": "User unstages a file with git reset, TUI moves file from staged to unstaged section (yellow)", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 3, "text": "User creates checkpoint via fspec command, TUI stash panel updates showing new stash", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 4, "text": "User modifies work-units.json AND stages a file, both panels update in real-time", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 5, "text": "User exits TUI, watchers are cleaned up and don't leak memory", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" } ], "questions": [ { "id": 0, "text": "@human: Should watchers debounce rapid changes (e.g., multiple git add commands in quick succession)?", "selected": true, "answer": "No debouncing needed - let React handle re-render optimization naturally", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" }, { "id": 1, "text": "@human: Should we also watch HEAD ref for branch changes or commits?", "selected": true, "answer": "Watch HEAD ref for current branch changes and commits", "deleted": false, "createdAt": "2025-10-27T08:14:53.044Z" } ], "nextRuleId": 8, "nextExampleId": 6, "nextQuestionId": 2, "nextNoteId": 0 }, "BOARD-005": { "id": "BOARD-005", "title": "Test data leak: BOARD-TEST-001 appearing in real board", "type": "bug", "status": "done", "createdAt": "2025-10-27T08:35:47.413Z", "updatedAt": "2025-10-27T08:44:09.956Z", "description": "Some test is creating BOARD-TEST-001 work unit without proper mocking, causing it to appear in the real board view. Tests should use isolated temporary directories or proper mocking to prevent test data from leaking into actual project data.", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T08:36:17.521Z" }, { "state": "testing", "timestamp": "2025-10-27T08:40:04.483Z" }, { "state": "implementing", "timestamp": "2025-10-27T08:40:12.336Z" }, { "state": "validating", "timestamp": "2025-10-27T08:43:42.872Z" }, { "state": "done", "timestamp": "2025-10-27T08:44:09.956Z" } ], "userStory": { "role": "developer running tests", "action": "run tests without polluting real project data", "benefit": "I can trust that tests are isolated and won't affect my actual work units" }, "rules": [ { "id": 0, "text": "Tests MUST use temporary directories created with mkdtemp() to avoid polluting real project files", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" }, { "id": 1, "text": "Tests MUST clean up temporary directories in afterEach() hooks using rm(dir, { recursive: true, force: true })", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" }, { "id": 2, "text": "Tests that write to work-units.json MUST use testDir as cwd parameter, NOT process.cwd()", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" }, { "id": 3, "text": "BoardView-realtime-updates.test.tsx lines 209-223 are the problematic code that writes to real spec/work-units.json", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" }, { "id": 4, "text": "Tests MUST restore original file state if they absolutely must modify real files (use cleanup in try-finally blocks)", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" } ], "examples": [ { "id": 0, "text": "BoardView test creates BOARD-TEST-001 in real spec/work-units.json, causing it to appear in actual board view", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" }, { "id": 1, "text": "update-work-unit-ensure.test.ts correctly uses mkdtemp() to create isolated test directory in tmpdir()", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" }, { "id": 2, "text": "Test cleanup restores original work-units.json content at lines 260-262, but damage is already done", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" }, { "id": 3, "text": "Fix involves using mkdtemp() in beforeEach, passing testDir to loadData(), cleaning up in afterEach", "deleted": false, "createdAt": "2025-10-27T08:35:47.413Z" } ], "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-006": { "id": "BOARD-006", "title": "Incorrect column dividers in non-columnar TUI sections", "type": "bug", "status": "done", "createdAt": "2025-10-27T08:48:01.553Z", "updatedAt": "2025-10-27T10:21:53.879Z", "description": "The TUI board displays column divider characters in separator lines that should only have them on one side or not at all. Need to distinguish between three separator types:\n\n1. NO COLUMNS (full-width sections):\n - Line ABOVE Git Stashes: ├─────────┤ (no columns above or below)\n - Line BETWEEN Git Stashes and Changed Files: ├─────────┤ (no columns above or below)\n \n2. TRANSITION TO COLUMNS (from full-width to columnar):\n - Line BETWEEN Changed Files and Kanban board: ├────┬────┬────┤ (no columns above, columns below)\n \n3. COLUMNS (Kanban board section):\n - Lines within Kanban board: ├────┼────┼────┤ (columns above and below)\n \n4. TRANSITION FROM COLUMNS (from columnar to full-width):\n - Line BETWEEN Kanban board and key mapping footer: ├────┴────┴────┤ (columns above, no columns below)\n - Line BELOW key mapping footer: └────────────┘ (terminal edge)\n\nCurrent bug: All separators use column dividers (┼) regardless of context. Need to use ┬ (top junction), ┼ (cross junction), ┴ (bottom junction), or plain ─ (horizontal) based on what's above and below each line.", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T08:50:13.394Z" }, { "state": "testing", "timestamp": "2025-10-27T08:52:50.126Z" }, { "state": "implementing", "timestamp": "2025-10-27T08:53:04.322Z" }, { "state": "validating", "timestamp": "2025-10-27T09:00:59.508Z" }, { "state": "done", "timestamp": "2025-10-27T09:01:27.183Z" }, { "state": "specifying", "timestamp": "2025-10-27T09:46:06.139Z" }, { "state": "testing", "timestamp": "2025-10-27T09:48:02.287Z" }, { "state": "implementing", "timestamp": "2025-10-27T09:48:08.530Z" }, { "state": "validating", "timestamp": "2025-10-27T09:50:58.482Z" }, { "state": "done", "timestamp": "2025-10-27T09:51:05.396Z" }, { "state": "specifying", "timestamp": "2025-10-27T10:05:35.951Z" }, { "state": "testing", "timestamp": "2025-10-27T10:06:39.027Z" }, { "state": "implementing", "timestamp": "2025-10-27T10:06:44.833Z" }, { "state": "validating", "timestamp": "2025-10-27T10:09:34.435Z" }, { "state": "done", "timestamp": "2025-10-27T10:09:40.651Z" }, { "state": "specifying", "timestamp": "2025-10-27T10:10:15.806Z" }, { "state": "testing", "timestamp": "2025-10-27T10:10:55.206Z" }, { "state": "implementing", "timestamp": "2025-10-27T10:10:56.274Z" }, { "state": "validating", "timestamp": "2025-10-27T10:13:23.836Z" }, { "state": "done", "timestamp": "2025-10-27T10:13:25.497Z" }, { "state": "specifying", "timestamp": "2025-10-27T10:14:26.919Z" }, { "state": "testing", "timestamp": "2025-10-27T10:15:05.810Z" }, { "state": "implementing", "timestamp": "2025-10-27T10:15:06.875Z" }, { "state": "validating", "timestamp": "2025-10-27T10:21:48.954Z" }, { "state": "done", "timestamp": "2025-10-27T10:21:53.879Z" } ], "userStory": { "role": "developer viewing TUI board", "action": "see correct box-drawing separators between sections", "benefit": "the interface looks visually correct and separators match their context" }, "rules": [ { "id": 0, "text": "Line 184 (after Git Stashes): Use ├──┤ with NO column dividers (no columns above or below)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 1, "text": "Line 202 (after Changed Files): Use ├──┬──┤ with TOP junctions (no columns above, columns start below)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 2, "text": "Line 252 (before key mapping footer): Use ├──┴──┤ with BOTTOM junctions (columns end above, no columns below)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 3, "text": "Lines 155 and 214: Keep ├──┼──┤ for actual Kanban board section (columns above and below)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 4, "text": "buildBorderRow helper must accept separator type parameter to distinguish between ─ (plain), ┬ (top), ┼ (cross), ┴ (bottom)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 5, "text": "Top border (┌─┐) should use plain horizontal separator (no columns above it)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 6, "text": "Bottom border (└─┘) should use plain horizontal separator (no columns below it)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 7, "text": "Footer row content should NOT have pipe characters separating command help text", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 8, "text": "Footer help text should be centered horizontally within the total table width", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 9, "text": "Footer help text should use diamond separator (◆) instead of pipe character (|) between command groups", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 10, "text": "Column headers should display ONLY the state name in uppercase (e.g., BACKLOG, DONE, etc.) with no counts or story points", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" } ], "examples": [ { "id": 0, "text": "Line 184 currently shows ├──┼──┤ but should show ├────────┤ (no column dividers between Git Stashes and Changed Files)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 1, "text": "Line 202 currently shows ├──┼──┤ but should show ├──┬──┬──┤ (top junctions where Kanban columns start)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 2, "text": "Line 252 currently shows ├──┼──┤ but should show ├──┴──┴──┤ (bottom junctions where Kanban columns end)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 3, "text": "Lines 155 and 214 correctly use ├──┼──┤ for the Kanban board header separator", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 4, "text": "Top border should show ┌────────┐ with NO column dividers (plain horizontal only)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 5, "text": "Bottom border should show └────────┘ with NO column dividers (plain horizontal only)", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 6, "text": "Footer text '← → Columns | ↑↓ jk Work Units | ↵ Details | ESC Back' should have pipe characters as CONTENT, not column dividers", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 7, "text": "Footer text '← → Columns | ↑↓ jk Work Units | ↵ Details | ESC Back' should have equal padding on left and right to center it", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 8, "text": "Footer should display '← → Columns ◆ ↑↓ jk Work Units ◆ ↵ Details ◆ ESC Back' with diamond separators", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" }, { "id": 9, "text": "Headers should show 'BACKLOG', 'SPECIFYING', 'TESTING', 'IMPLEMENTING', 'VALIDATING', 'DONE', 'BLOCKED' without any additional text", "deleted": false, "createdAt": "2025-10-27T08:48:01.553Z" } ], "nextRuleId": 11, "nextExampleId": 10, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-007": { "id": "BOARD-007", "title": "Consolidate Git info and add work unit details panel", "type": "story", "status": "done", "createdAt": "2025-10-27T10:26:36.107Z", "updatedAt": "2025-10-27T10:35:14.760Z", "description": "Merge Git Stashes and Changed Files into single panel, replace Changed Files section with work unit details panel showing type, title, description, dependencies for selected work unit", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T10:26:40.856Z" }, { "state": "testing", "timestamp": "2025-10-27T10:29:02.609Z" }, { "state": "implementing", "timestamp": "2025-10-27T10:29:58.305Z" }, { "state": "validating", "timestamp": "2025-10-27T10:35:07.683Z" }, { "state": "done", "timestamp": "2025-10-27T10:35:14.760Z" } ], "userStory": { "role": "developer using TUI board", "action": "see git context and selected work unit details in one view", "benefit": "I can understand my current work context without switching views" }, "rules": [ { "id": 0, "text": "Git Stashes and Changed Files must be combined into single 'Git Context' panel", "deleted": false, "createdAt": "2025-10-27T10:26:36.107Z" }, { "id": 1, "text": "Changed Files section must be replaced with Work Unit Details panel", "deleted": false, "createdAt": "2025-10-27T10:26:36.107Z" }, { "id": 2, "text": "Work Unit Details panel shows type icon, title, description, dependencies, and other metadata", "deleted": false, "createdAt": "2025-10-27T10:26:36.107Z" }, { "id": 3, "text": "Description must be truncated after few lines with indicator to press Enter for full details", "deleted": false, "createdAt": "2025-10-27T10:26:36.107Z" }, { "id": 4, "text": "When no work unit selected, display user-friendly message like 'No work unit selected'", "deleted": false, "createdAt": "2025-10-27T10:26:36.107Z" } ], "examples": [ { "id": 0, "text": "Git Context panel shows 'Git Stashes (2)' followed by stash list, then 'Changed Files (3 staged, 1 unstaged)' with file list", "deleted": false, "createdAt": "2025-10-27T10:26:36.107Z" }, { "id": 1, "text": "Work unit BOARD-001 selected: shows 📖 story icon, title, truncated description, dependencies list", "deleted": false, "createdAt": "2025-10-27T10:26:36.107Z" }, { "id": 2, "text": "No work unit selected in empty column: shows 'No work unit selected' message", "deleted": false, "createdAt": "2025-10-27T10:26:36.107Z" } ], "estimate": 5, "nextRuleId": 5, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-008": { "id": "BOARD-008", "title": "Color-coded work units without shimmer or priority icons", "type": "story", "status": "done", "createdAt": "2025-10-27T10:41:03.150Z", "updatedAt": "2025-10-27T12:09:46.733Z", "description": "Display work units with color-coding by type. Story=white, Bug=red, Task=blue, Selected=green background (no shimmer). Story points format: [N] when >0, hidden when 0. No priority emoticons.", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T10:41:09.156Z" }, { "state": "testing", "timestamp": "2025-10-27T10:43:46.573Z" }, { "state": "implementing", "timestamp": "2025-10-27T10:44:54.050Z" }, { "state": "validating", "timestamp": "2025-10-27T11:04:50.427Z" }, { "state": "done", "timestamp": "2025-10-27T11:05:05.468Z" }, { "state": "specifying", "timestamp": "2025-10-27T11:28:43.485Z" }, { "state": "testing", "timestamp": "2025-10-27T11:57:25.619Z" }, { "state": "specifying", "timestamp": "2025-10-27T12:04:39.836Z" }, { "state": "testing", "timestamp": "2025-10-27T12:06:10.449Z" }, { "state": "implementing", "timestamp": "2025-10-27T12:06:52.396Z" }, { "state": "validating", "timestamp": "2025-10-27T12:07:10.279Z" }, { "state": "done", "timestamp": "2025-10-27T12:09:46.733Z" } ], "userStory": { "role": "developer viewing TUI board", "action": "identify work unit types by color instead of emoji", "benefit": "I can quickly scan the board and distinguish stories, bugs, and tasks at a glance" }, "rules": [ { "id": 0, "text": "Story work units must display in white color", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 1, "text": "Bug work units must display in red color", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 2, "text": "Task work units must display in blue color", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 3, "text": "Selected work unit must display with green background (overrides type color)", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 4, "text": "Story points must be hidden when estimate is 0 or undefined", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 5, "text": "Story points must display as [N] format when estimate > 0", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 6, "text": "No priority emoticons must be displayed", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 7, "text": "No shimmer animation on selected work units", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 8, "text": "Story points must be hidden when estimate is 0 or undefined", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 9, "text": "Story points must display as [N] format when estimate > 0", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 10, "text": "No priority emoticons must be displayed", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 11, "text": "No shimmer animation on selected work units", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" } ], "examples": [ { "id": 0, "text": "Story TECH-001 with 0 estimate displays as 'TECH-001' in white (no story points shown)", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 1, "text": "Story FEAT-002 with 5 estimate displays as 'FEAT-002 [5]' in white", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 2, "text": "Bug BUG-001 with 3 estimate displays as 'BUG-001 [3]' in red", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 3, "text": "Task TASK-001 with no estimate displays as 'TASK-001' in blue", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 4, "text": "Selected story displays with green background, no shimmer, no priority icons", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 5, "text": "Story TECH-001 with 0 estimate displays as 'TECH-001' in white (no story points shown)", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 6, "text": "Story FEAT-002 with 5 estimate displays as 'FEAT-002 [5]' in white", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 7, "text": "Bug BUG-001 with 3 estimate displays as 'BUG-001 [3]' in red", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 8, "text": "Task TASK-001 with no estimate displays as 'TASK-001' in blue", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" }, { "id": 9, "text": "Selected story displays with green background, no shimmer, no priority icons", "deleted": false, "createdAt": "2025-10-27T10:41:03.150Z" } ], "estimate": 5, "nextRuleId": 12, "nextExampleId": 10, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-009": { "id": "BOARD-009", "title": "Animated shimmer on last changed work unit", "type": "story", "status": "done", "createdAt": "2025-10-27T11:33:13.499Z", "updatedAt": "2025-10-27T13:22:11.715Z", "description": "Highlight the most recently modified work unit with green text color and animated left-to-right shimmer effect every 5 seconds", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T11:33:18.483Z" }, { "state": "testing", "timestamp": "2025-10-27T11:47:08.680Z" }, { "state": "implementing", "timestamp": "2025-10-27T11:50:59.702Z" }, { "state": "validating", "timestamp": "2025-10-27T11:53:28.774Z" }, { "state": "done", "timestamp": "2025-10-27T11:56:01.740Z" }, { "state": "specifying", "timestamp": "2025-10-27T11:58:23.414Z" }, { "state": "testing", "timestamp": "2025-10-27T11:59:20.940Z" }, { "state": "implementing", "timestamp": "2025-10-27T11:59:50.434Z" }, { "state": "validating", "timestamp": "2025-10-27T12:00:15.328Z" }, { "state": "done", "timestamp": "2025-10-27T12:03:13.711Z" }, { "state": "specifying", "timestamp": "2025-10-27T12:51:51.932Z" }, { "state": "testing", "timestamp": "2025-10-27T12:54:54.129Z" }, { "state": "implementing", "timestamp": "2025-10-27T12:56:23.041Z" }, { "state": "testing", "timestamp": "2025-10-27T12:57:20.561Z" }, { "state": "implementing", "timestamp": "2025-10-27T13:00:51.119Z" }, { "state": "validating", "timestamp": "2025-10-27T13:08:42.196Z" }, { "state": "done", "timestamp": "2025-10-27T13:09:02.580Z" }, { "state": "specifying", "timestamp": "2025-10-27T13:13:46.293Z" }, { "state": "testing", "timestamp": "2025-10-27T13:17:04.125Z" }, { "state": "implementing", "timestamp": "2025-10-27T13:18:38.247Z" }, { "state": "validating", "timestamp": "2025-10-27T13:21:53.297Z" }, { "state": "done", "timestamp": "2025-10-27T13:22:11.715Z" } ], "userStory": { "role": "developer viewing TUI board", "action": "see which work unit was most recently changed", "benefit": "I can quickly identify where recent activity occurred" }, "questions": [ { "id": 0, "text": "@human: What constitutes a 'change' to a work unit?", "selected": true, "answer": "Compute last-changed work unit by finding max(updated) timestamp across all work units. Don't store separately in Zustand - use existing updated field. Track only shimmer animation toggle state in component state.", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 1, "text": "@human: How should the shimmer animation work exactly?", "selected": true, "answer": "Alternate between shades of green (green → bright green → green), with pauses between 5-second cycles. No gradient sweep.", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 2, "text": "@human: What happens if multiple work units changed columns at the same time?", "selected": true, "answer": "Pick the work unit with the most recent timestamp change (use work unit's updated field to determine recency).", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 3, "text": "@human: What happens when the last changed work unit is also the currently selected work unit?", "selected": true, "answer": "Shimmer the selector/background instead, from left to right in shades of green (bgGreen → bgGreenBright → bgGreen), with black text.", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 4, "text": "@human: Should the shimmer override the work unit type color (white/red/blue) or shimmer the existing type color?", "selected": true, "answer": "Shimmer the existing type color. Story (white → whiteBright → white), Bug (red → redBright → red), Task (blue → blueBright → blue).", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 5, "text": "@human: When does the shimmer start and stop?", "selected": true, "answer": "On TUI startup, identify the work unit with the most recent 'updated' timestamp and start shimmering it immediately.", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 6, "text": "@human: How should Zustand track status changes?", "selected": true, "answer": "Compute last-changed work unit by finding max(updated) timestamp across all work units. Don't store separately in Zustand - use existing updated field. Track only shimmer animation toggle state in component state.", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 7, "text": "@human: Should we use the last stateHistory timestamp (only status changes) or add a dedicated lastStatusChange field to work units?", "selected": true, "answer": "Use the last stateHistory timestamp - this is the correct approach because it only tracks actual status/column changes (what users care about), not other field modifications like estimate changes. The stateHistory array is already part of the work unit data structure and is the source of truth for state transitions.", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" } ], "rules": [ { "id": 0, "text": "Last changed work unit is determined by status/column change, not other field updates", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 1, "text": "Find last changed work unit by computing max(updated) timestamp across all work units", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 2, "text": "When multiple work units have same timestamp, pick the one with most recent updated field", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 3, "text": "Shimmer starts on TUI startup for the most recently changed work unit from history", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 4, "text": "Shimmer continues indefinitely until another work unit changes status", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 5, "text": "Zustand store WorkUnit interface must include updated and estimate fields to pass data from work-units.json to components", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 6, "text": "At any given frame, one character is at peak brightness (whiteBright/redBright/blueBright), with darker gradient on both sides", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 7, "text": "Gradient uses 3 brightness levels: dim (gray), base color (white/red/blue), bright (whiteBright/redBright/blueBright)", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 8, "text": "Shimmer wave moves one character position per frame at smooth animation speed", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 9, "text": "When shimmer reaches end of string, it loops back to the beginning continuously", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 10, "text": "The Zustand store must transform updatedAt field from work-units.json to updated field when loading work units", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 11, "text": "The lastChangedWorkUnit algorithm should use the most recent state transition timestamp from stateHistory array, not the updatedAt field which tracks any field modification", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 12, "text": "Find last changed work unit by getting the most recent stateHistory timestamp across all work units", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 13, "text": "Zustand store must include stateHistory array when loading work units so components can access state transition timestamps", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" } ], "examples": [ { "id": 0, "text": "Story TECH-001 with most recent timestamp displays with shimmering white text (white→whiteBright every 5s)", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 1, "text": "Bug BUG-007 with most recent timestamp displays with shimmering red text (red→redBright every 5s)", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 2, "text": "Task TASK-003 with most recent timestamp displays with shimmering blue text (blue→blueBright every 5s)", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 3, "text": "Selected work unit AUTH-001 that is also last-changed displays with shimmering green background (bgGreen→bgGreenBright) and black text", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 4, "text": "On TUI startup, BOARD-008 with updated='2025-10-27T21:30:00Z' is most recent, starts shimmering immediately", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 5, "text": "User moves FEAT-002 from testing to implementing, shimmer stops on BOARD-008 and starts on FEAT-002", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 6, "text": "Zustand store loads work unit with updated='2025-10-27T22:00:00Z' from work-units.json and passes it to UnifiedBoardLayout", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 7, "text": "String 'FEAT-001' with shimmer at position 0: [F]EAT-001 where F is whiteBright, E is white, A is gray", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 8, "text": "String 'FEAT-001' with shimmer at position 3: FEA[T]-001 where T is whiteBright, A and - are white, E and 0 are gray", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 9, "text": "Bug work unit 'BUG-007' uses red gradient: gray → red → redBright → red → gray", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 10, "text": "Task work unit 'TASK-003' uses blue gradient: gray → blue → blueBright → blue → gray", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 11, "text": "Animation speed: shimmer moves 1 character position every 100ms for smooth visual wave effect", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 12, "text": "For selected work unit that is also last-changed: apply shimmer gradient to background color (bgGreen → bgGreenBright → bgGreen) with black text", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 13, "text": "Work unit BOARD-009 has stateHistory entry with timestamp 2025-10-27T13:13:46.292Z (most recent transition), should shimmer", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" }, { "id": 14, "text": "Work unit EXMAP-001 has updatedAt 2025-10-10T23:20:00.252Z but last stateHistory entry is older than BOARD-009, should NOT shimmer", "deleted": false, "createdAt": "2025-10-27T11:33:13.499Z" } ], "estimate": 5, "nextRuleId": 14, "nextExampleId": 15, "nextQuestionId": 8, "nextNoteId": 0 }, "BUG-045": { "id": "BUG-045", "title": "Work items in columns don't scroll", "type": "bug", "status": "done", "createdAt": "2025-10-27T12:13:55.515Z", "updatedAt": "2025-10-27T21:46:37.078Z", "description": "Work items in a column should scroll like the virtual lists in ~/projects/cage project, but currently they don't scroll at all. Need to implement scrollable list functionality similar to the cage project's virtual list implementation.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T12:14:59.940Z" }, { "state": "testing", "timestamp": "2025-10-27T12:20:01.437Z" }, { "state": "implementing", "timestamp": "2025-10-27T12:21:58.025Z" }, { "state": "validating", "timestamp": "2025-10-27T12:23:05.935Z" }, { "state": "done", "timestamp": "2025-10-27T12:25:14.138Z" }, { "state": "specifying", "timestamp": "2025-10-27T12:27:25.459Z" }, { "state": "testing", "timestamp": "2025-10-27T12:29:50.004Z" }, { "state": "implementing", "timestamp": "2025-10-27T12:30:44.993Z" }, { "state": "validating", "timestamp": "2025-10-27T12:31:48.192Z" }, { "state": "done", "timestamp": "2025-10-27T12:31:56.470Z" }, { "state": "specifying", "timestamp": "2025-10-27T12:36:07.963Z" }, { "state": "testing", "timestamp": "2025-10-27T12:38:34.207Z" }, { "state": "implementing", "timestamp": "2025-10-27T12:40:09.876Z" }, { "state": "validating", "timestamp": "2025-10-27T12:41:07.048Z" }, { "state": "done", "timestamp": "2025-10-27T12:44:23.419Z" }, { "state": "implementing", "timestamp": "2025-10-27T21:43:55.395Z" }, { "state": "specifying", "timestamp": "2025-10-27T21:44:23.525Z" }, { "state": "testing", "timestamp": "2025-10-27T21:46:27.634Z" }, { "state": "implementing", "timestamp": "2025-10-27T21:46:34.888Z" }, { "state": "validating", "timestamp": "2025-10-27T21:46:35.998Z" }, { "state": "done", "timestamp": "2025-10-27T21:46:37.078Z" } ], "userStory": { "role": "user navigating the fspec board TUI", "action": "scroll through work items using arrow keys", "benefit": "I can see all work items in a column without manually pressing Page Up/Down" }, "rules": [ { "id": 0, "text": "Arrow key navigation (up/down) should automatically scroll the viewport when selection moves beyond visible area", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 1, "text": "Scrolling should follow the selected item, keeping it visible at all times", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 2, "text": "Implementation should match VirtualList pattern from cage project (navigateTo helper function)", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 3, "text": "Scroll indicators (↑ ↓) should show when there are items above/below visible viewport", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 4, "text": "No, only arrow keys should trigger automatic scrolling. Do not use j/k vim-style navigation.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 5, "text": "Preserve scroll position per column. Each column maintains its own scroll offset state.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 6, "text": "Yes, wrap-around navigation should work (down on last item goes to first, up on first item goes to last).", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 7, "text": "Scroll indicators (arrows) replace work items in viewport rows, reducing actual visible item count", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 8, "text": "Visible work item count = VIEWPORT_HEIGHT - (number of arrows shown: 0, 1, or 2)", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 9, "text": "Tests should verify rendering at different scroll positions. The component should calculate scroll offset based on selectedWorkUnitIndex prop and render accordingly. Tests pass selectedWorkUnitIndex and verify the correct items are visible.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 10, "text": "Tests should verify rendering logic. Component receives selectedWorkUnitIndex as prop and calculates scroll offset to keep that item visible. Tests pass different selectedWorkUnitIndex values and verify correct items are visible in output.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" } ], "examples": [ { "id": 0, "text": "User presses down arrow 11 times in a column with 20 items (viewport shows 10). Selection moves to item 11, viewport scrolls to show items 2-11 with selection visible.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 1, "text": "User at item 15 presses up arrow to item 5. Viewport scrolls up to show items 1-10 with item 5 selected.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 2, "text": "Column with 5 items and viewport height 10: no scroll indicators show, all items visible.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 3, "text": "Column with 20 items: ↓ indicator shows at bottom row when scrollOffset < (20 - 10), ↑ indicator shows at top row when scrollOffset > 0.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 4, "text": "Column with 15 items, scrollOffset=5, VIEWPORT_HEIGHT=10: Shows up arrow at row 0, items 6-14 in rows 1-9, down arrow at row 9 (only 8 items visible)", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 5, "text": "Column with 25 items, scrollOffset=10, VIEWPORT_HEIGHT=10: Shows up arrow at row 0, items 11-19 in rows 1-9, but row 9 should show down arrow, so only items 11-18 visible (8 items total)", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" } ], "questions": [ { "id": 0, "text": "@human: Should vim-style navigation (j/k keys) also trigger automatic scrolling, matching the cage VirtualList pattern?", "selected": true, "answer": "Tests should verify rendering at different scroll positions. The component should calculate scroll offset based on selectedWorkUnitIndex prop and render accordingly. Tests pass selectedWorkUnitIndex and verify the correct items are visible.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 1, "text": "@human: When switching columns with left/right arrows, should we reset scroll offset to 0 for the new column, or preserve scroll position per column?", "selected": true, "answer": "Preserve scroll position per column. Each column maintains its own scroll offset state.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 2, "text": "@human: Should wrap-around navigation work (pressing down on last item goes to first item)?", "selected": true, "answer": "Yes, wrap-around navigation should work (down on last item goes to first, up on first item goes to last).", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" }, { "id": 3, "text": "@human: The tests render with selectedWorkUnitIndex but don't simulate arrow key presses. Should tests actually press arrow keys to trigger scrolling, or just verify rendering at different scroll positions?", "selected": true, "answer": "Tests should verify rendering logic. Component receives selectedWorkUnitIndex as prop and calculates scroll offset to keep that item visible. Tests pass different selectedWorkUnitIndex values and verify correct items are visible in output.", "deleted": false, "createdAt": "2025-10-27T12:13:55.515Z" } ], "estimate": 5, "nextRuleId": 11, "nextExampleId": 6, "nextQuestionId": 4, "nextNoteId": 0 }, "BOARD-010": { "id": "BOARD-010", "title": "Keyboard priority reordering with bracket keys", "type": "story", "status": "done", "createdAt": "2025-10-27T13:26:34.333Z", "updatedAt": "2025-10-28T00:50:41.136Z", "description": "Allow users to reorder work units within a column using [ and ] keys to move items up/down in priority", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T13:26:34.982Z" }, { "state": "specifying", "timestamp": "2025-10-28T00:01:07.899Z" }, { "state": "testing", "timestamp": "2025-10-28T00:03:35.764Z" }, { "state": "implementing", "timestamp": "2025-10-28T00:20:50.787Z" }, { "state": "specifying", "timestamp": "2025-10-28T00:22:23.137Z" }, { "state": "testing", "timestamp": "2025-10-28T00:23:47.930Z" }, { "state": "implementing", "timestamp": "2025-10-28T00:23:49.101Z" }, { "state": "specifying", "timestamp": "2025-10-28T00:35:42.604Z" }, { "state": "testing", "timestamp": "2025-10-28T00:37:09.629Z" }, { "state": "implementing", "timestamp": "2025-10-28T00:37:17.345Z" }, { "state": "specifying", "timestamp": "2025-10-28T00:40:31.237Z" }, { "state": "testing", "timestamp": "2025-10-28T00:41:35.209Z" }, { "state": "implementing", "timestamp": "2025-10-28T00:41:40.893Z" }, { "state": "validating", "timestamp": "2025-10-28T00:45:08.520Z" }, { "state": "done", "timestamp": "2025-10-28T00:50:41.136Z" } ], "userStory": { "role": "developer using TUI board", "action": "reorder work units within a column using bracket keys", "benefit": "I can quickly adjust priorities without leaving the keyboard" }, "rules": [ { "id": 0, "text": "Press [ key to move selected work unit up one position in the current column", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 1, "text": "Press ] key to move selected work unit down one position in the current column", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 2, "text": "Work unit order changes are persisted to work-units.json immediately", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 3, "text": "Cannot move work unit up if it's already at the top of the column (first position)", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 4, "text": "Cannot move work unit down if it's already at the bottom of the column (last position)", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 5, "text": "Manual reordering with [ and ] keys is only allowed in backlog, specifying, testing, implementing, validating, and blocked columns (not done column)", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 6, "text": "Work unit position is determined by its index in the states[columnName] array in work-units.json", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 7, "text": "To move work unit up: swap its position with the previous work unit ID in the states array", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 8, "text": "To move work unit down: swap its position with the next work unit ID in the states array", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 9, "text": "Key bindings [ and ] must be displayed in help text at bottom of TUI board", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 10, "text": "All keyboard input should be handled in a single unified location to prevent conflicts between multiple useInput hooks", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 11, "text": "Bracket key handlers should be in UnifiedBoardLayout's useInput hook (where arrow keys and Enter are handled), NOT in BoardView's useInput hook", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 12, "text": "UnifiedBoardLayout should call onMoveUp() and onMoveDown() callbacks (passed as props) when bracket keys are pressed", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 13, "text": "loadData() in fspecStore MUST load work units by iterating states arrays (not Object.values(workUnits)) to preserve display order", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 14, "text": "When moving work unit up or down, the selection cursor MUST follow the work unit to its new position", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" } ], "examples": [ { "id": 0, "text": "User selects BOARD-002 in backlog column (position 2), presses [, work unit moves to position 1", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 1, "text": "User selects BOARD-001 in backlog column (position 1), presses [, nothing happens (already at top)", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 2, "text": "User selects BOARD-003 in backlog column (position 2), presses ], work unit moves to position 3", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 3, "text": "User selects last work unit in done column, presses ], nothing happens (already at bottom)", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 4, "text": "After moving work unit, order persists when restarting TUI (loaded from work-units.json)", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 5, "text": "User in done column presses [ or ], nothing happens (done column order is automatic by completion time)", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 6, "text": "BoardView has useInput hook for ESC and Tab keys, UnifiedBoardLayout has useInput for arrow keys - bracket keys added to BoardView but not working, likely due to hook conflicts", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 7, "text": "User selects BOARD-002 at position 2, presses [, BOARD-002 moves to position 1 AND selection cursor moves to position 1", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 8, "text": "User selects BOARD-002 at position 2, presses ], BOARD-002 moves to position 3 AND selection cursor moves to position 3", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" } ], "estimate": 5, "questions": [ { "id": 0, "text": "@human: Where should the bracket key input handlers live - in BoardView or UnifiedBoardLayout? Currently we have useInput in BOTH components which might be causing conflicts.", "selected": true, "answer": "Bracket key handlers should live in UnifiedBoardLayout's useInput hook (where arrow keys and Enter are already handled). UnifiedBoardLayout will call onMoveUp/onMoveDown callbacks passed as props from BoardView.", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" }, { "id": 1, "text": "CRITICAL ARCHITECTURE: How should loadData() load work units to respect states array order? Currently loads Object.values(workUnits) which is unordered!", "selected": true, "answer": "loadData() MUST build workUnits array from states arrays! Algorithm: 1) Iterate each column in states object 2) For each ID in states[column], lookup workUnit from workUnits object 3) Push to result array IN ORDER. This ensures display order matches states array order.", "deleted": false, "createdAt": "2025-10-27T13:26:34.333Z" } ], "nextRuleId": 15, "nextExampleId": 9, "nextQuestionId": 2, "nextNoteId": 0 }, "BOARD-011": { "id": "BOARD-011", "title": "Order done column by completion time", "type": "story", "status": "done", "createdAt": "2025-10-27T13:28:41.647Z", "updatedAt": "2025-10-27T13:38:04.064Z", "description": "Display work units in the done column with most recently completed items at the top, ordered by when they were moved to done status", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T13:28:42.315Z" }, { "state": "testing", "timestamp": "2025-10-27T13:30:21.761Z" }, { "state": "implementing", "timestamp": "2025-10-27T13:33:16.619Z" }, { "state": "validating", "timestamp": "2025-10-27T13:37:45.870Z" }, { "state": "done", "timestamp": "2025-10-27T13:38:04.064Z" } ], "userStory": { "role": "developer viewing the board", "action": "see completed work units ordered by completion time", "benefit": "I can quickly see what was finished most recently" }, "rules": [ { "id": 0, "text": "Done column displays work units with most recently completed at the top", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" }, { "id": 1, "text": "Completion time is determined by the timestamp when work unit was moved to done status (last stateHistory entry with state=done)", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" }, { "id": 2, "text": "Work units are sorted in descending order by completion timestamp (newest first)", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" }, { "id": 3, "text": "When a work unit is moved back to done from another state, it uses the new timestamp (appears at top again)", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" }, { "id": 4, "text": "Other columns (backlog, specifying, testing, implementing, validating, blocked) maintain existing order behavior", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" } ], "examples": [ { "id": 0, "text": "BOARD-005 completed at 10:00, BOARD-003 completed at 11:00, BOARD-007 completed at 09:00 → done column shows: BOARD-003, BOARD-005, BOARD-007", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" }, { "id": 1, "text": "BOARD-001 moved to done on Monday, BOARD-002 moved to done on Tuesday → BOARD-002 appears above BOARD-001", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" }, { "id": 2, "text": "BOARD-003 completed yesterday, user moves it back to implementing, then back to done today → BOARD-003 now appears at top of done column with today's timestamp", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" }, { "id": 3, "text": "On TUI startup, done column loads work units sorted by completion time from stateHistory timestamps", "deleted": false, "createdAt": "2025-10-27T13:28:41.647Z" } ], "estimate": 3, "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-046": { "id": "BUG-046", "title": "Fix failing BoardView TUI tests", "type": "bug", "status": "done", "createdAt": "2025-10-27T14:39:22.122Z", "updatedAt": "2025-10-27T14:49:22.499Z", "description": "Fix multiple failing tests in BoardView components: done column filtering, work unit details display, and shimmer color handling", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T14:39:29.608Z" }, { "state": "testing", "timestamp": "2025-10-27T14:42:31.674Z" }, { "state": "implementing", "timestamp": "2025-10-27T14:42:39.259Z" }, { "state": "validating", "timestamp": "2025-10-27T14:48:50.171Z" }, { "state": "done", "timestamp": "2025-10-27T14:49:22.499Z" } ], "rules": [ { "id": 0, "text": "BoardView tests must use the test directory's work-units.json, not the project's work-units.json", "deleted": false, "createdAt": "2025-10-27T14:39:22.122Z" }, { "id": 1, "text": "Tests create temporary directories with test data but components load from process.cwd()", "deleted": false, "createdAt": "2025-10-27T14:39:22.122Z" }, { "id": 2, "text": "The fspecStore must accept an optional cwd parameter to support test isolation", "deleted": false, "createdAt": "2025-10-27T14:39:22.122Z" } ], "examples": [ { "id": 0, "text": "Test creates BOARD-001 in temp dir, but component shows TECH-001 from project dir", "deleted": false, "createdAt": "2025-10-27T14:39:22.122Z" }, { "id": 1, "text": "Test expects 'No work unit selected' but component shows TECH-001 details from project data", "deleted": false, "createdAt": "2025-10-27T14:39:22.122Z" }, { "id": 2, "text": "BoardView accepts optional cwd prop, passes to store for test directory isolation", "deleted": false, "createdAt": "2025-10-27T14:39:22.122Z" } ], "userStory": { "role": "developer running TUI tests", "action": "test BoardView component in isolation", "benefit": "tests use test data not project data" }, "estimate": 3, "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-012": { "id": "BOARD-012", "title": "Column scrolling tests fail - tests don't trigger scrolling logic", "type": "bug", "status": "done", "createdAt": "2025-10-27T21:46:45.776Z", "updatedAt": "2025-10-27T22:04:31.655Z", "description": "Tests in BoardView-column-scrolling.test.tsx don't actually simulate arrow key presses to trigger scrolling. They just render with selectedWorkUnitIndex but never call stdin.write() to press keys. Component needs to calculate scroll offset based on selectedWorkUnitIndex prop and auto-scroll viewport.", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T21:46:51.477Z" }, { "state": "testing", "timestamp": "2025-10-27T21:50:03.890Z" }, { "state": "implementing", "timestamp": "2025-10-27T21:50:11.238Z" }, { "state": "validating", "timestamp": "2025-10-27T22:04:03.943Z" }, { "state": "done", "timestamp": "2025-10-27T22:04:31.655Z" } ], "userStory": { "role": "developer running tests", "action": "verify BoardView scrolling behavior", "benefit": "I can confirm viewport auto-scrolls to keep selected items visible" }, "rules": [ { "id": 0, "text": "Component must calculate scroll offset based on selectedWorkUnitIndex prop to keep selected item visible", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 1, "text": "When selectedWorkUnitIndex is beyond visible viewport, viewport must scroll to show that item", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 2, "text": "Scroll indicators (↑ ↓) show when there are items above/below visible viewport", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 3, "text": "Scroll indicators consume viewport rows: visible items = VIEWPORT_HEIGHT - number_of_arrows", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 4, "text": "Each column maintains its own scroll offset when switching between columns", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" } ], "examples": [ { "id": 0, "text": "Column has 20 items, viewport height 10, selectedWorkUnitIndex=10 (item 11): viewport scrolls to show items 2-11 with item 11 visible", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 1, "text": "Column has 20 items, viewport height 10, selectedWorkUnitIndex=14 (item 15): viewport scrolls down, item 15 visible, items 1-5 scrolled out", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 2, "text": "Column has 5 items, viewport height 10: no scroll indicators shown, all items visible", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 3, "text": "Column has 20 items, selectedWorkUnitIndex=15: up arrow (↑) shown at top, down arrow (↓) shown at bottom", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 4, "text": "Column has 15 items, viewport height 10, both arrows visible: only 8 items visible (10 - 2 arrows = 8)", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" }, { "id": 5, "text": "User at item 15 in column A, switches to column B, then back to column A: scroll position preserved, still at item 15", "deleted": false, "createdAt": "2025-10-27T21:46:45.776Z" } ], "estimate": 5, "nextRuleId": 5, "nextExampleId": 6, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-013": { "id": "BOARD-013", "title": "Full-Screen TUI Layout", "type": "story", "status": "done", "createdAt": "2025-10-27T22:17:54.321Z", "updatedAt": "2025-10-27T22:33:11.994Z", "description": "Make the Kanban board TUI fill the entire terminal screen like CAGE does, using responsive layout hooks and proper screen clearing", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T22:18:57.660Z" }, { "state": "testing", "timestamp": "2025-10-27T22:21:48.927Z" }, { "state": "implementing", "timestamp": "2025-10-27T22:25:46.915Z" }, { "state": "validating", "timestamp": "2025-10-27T22:30:56.175Z" }, { "state": "done", "timestamp": "2025-10-27T22:33:11.994Z" } ], "userStory": { "role": "developer using fspec board", "action": "view the Kanban board in a full-screen TUI", "benefit": "I can see all work units clearly without wasted screen space" }, "rules": [ { "id": 0, "text": "Board must fill entire terminal width and height", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" }, { "id": 1, "text": "Board must respond to terminal resize events automatically", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" }, { "id": 2, "text": "Screen must be cleared before rendering to start from position (0,0)", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" }, { "id": 3, "text": "Layout must use Ink Box with width and height set to terminal dimensions", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" }, { "id": 4, "text": "No whitespace or padding should appear outside the board borders", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" } ], "examples": [ { "id": 0, "text": "User opens board in 80x24 terminal, board fills entire 80x24 space", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" }, { "id": 1, "text": "User opens board in 120x40 terminal, board fills entire 120x40 space", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" }, { "id": 2, "text": "User resizes terminal from 80x24 to 120x40 while board is open, board automatically resizes to 120x40", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" }, { "id": 3, "text": "Board renders with no extra whitespace above, below, left, or right of borders", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" }, { "id": 4, "text": "Board uses useStdout hook to detect terminal dimensions and updates on resize", "deleted": false, "createdAt": "2025-10-27T22:17:54.321Z" } ], "estimate": 5, "nextRuleId": 5, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-014": { "id": "BOARD-014", "title": "Stretch board content to fill available viewport height", "type": "story", "status": "done", "createdAt": "2025-10-27T22:35:08.114Z", "updatedAt": "2025-10-28T02:55:49.519Z", "description": "Make the work unit table expand vertically to use all available space within FullScreenWrapper. Currently the table has a fixed height and doesn't stretch to fill the terminal.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T22:35:47.315Z" }, { "state": "testing", "timestamp": "2025-10-27T22:37:34.167Z" }, { "state": "implementing", "timestamp": "2025-10-27T22:38:36.675Z" }, { "state": "specifying", "timestamp": "2025-10-27T22:49:40.611Z" }, { "state": "testing", "timestamp": "2025-10-27T22:51:24.491Z" }, { "state": "implementing", "timestamp": "2025-10-27T22:59:56.714Z" }, { "state": "validating", "timestamp": "2025-10-27T23:00:02.325Z" }, { "state": "done", "timestamp": "2025-10-27T23:00:28.691Z" }, { "state": "specifying", "timestamp": "2025-10-27T23:03:32.890Z" }, { "state": "testing", "timestamp": "2025-10-27T23:04:50.702Z" }, { "state": "implementing", "timestamp": "2025-10-27T23:04:51.787Z" }, { "state": "validating", "timestamp": "2025-10-27T23:04:52.850Z" }, { "state": "done", "timestamp": "2025-10-27T23:04:57.476Z" }, { "state": "specifying", "timestamp": "2025-10-27T23:05:46.204Z" }, { "state": "specifying", "timestamp": "2025-10-27T23:13:35.550Z" }, { "state": "testing", "timestamp": "2025-10-28T02:55:35.532Z" }, { "state": "implementing", "timestamp": "2025-10-28T02:55:39.841Z" }, { "state": "validating", "timestamp": "2025-10-28T02:55:44.186Z" }, { "state": "done", "timestamp": "2025-10-28T02:55:49.520Z" } ], "userStory": { "role": "developer using fspec board", "action": "see the work unit table fill the entire terminal vertically", "benefit": "I can view more work units at once without wasted screen space" }, "rules": [ { "id": 0, "text": "Work unit table must expand to fill all available vertical space within FullScreenWrapper", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" }, { "id": 1, "text": "Column height must be calculated based on available viewport height minus headers and borders", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" }, { "id": 2, "text": "No empty space should appear between the work unit rows and the bottom border", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" }, { "id": 3, "text": "Table must respond to terminal resize by recalculating available height", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" }, { "id": 4, "text": "Work unit columns area must use Ink Box component with flexGrow=1 to automatically fill available vertical space", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" }, { "id": 5, "text": "Header panels (Git Stashes, Changed Files, Work Unit Details) must render separately from work unit table to minimize fixed height overhead", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" } ], "examples": [ { "id": 0, "text": "In 80x24 terminal with 3-row header and 1-row footer, columns should have 20 rows for work units", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" }, { "id": 1, "text": "In 120x40 terminal with same headers, columns should have 36 rows for work units", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" }, { "id": 2, "text": "When terminal resizes from 24 to 40 rows, column height increases from 20 to 36 rows", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" } ], "questions": [ { "id": 0, "text": "@human: Current unified table layout (ITF-004) uses 10 fixed rows for headers/footers, leaving only 13 work unit rows in a 24-row terminal. To achieve 20 work unit rows as specified, should we: A) Restructure to use Ink's Box/flexGrow for dynamic stretching with separate header panels, B) Simplify headers to use fewer rows while keeping unified table, or C) Adjust test expectations to match current layout?", "selected": true, "answer": "Option A: Restructure to use Ink's Box/flexGrow. Separate header panels (Git Stashes, Changed Files, Work Unit Details) from the work unit table. Use <Box flexGrow={1}> for the columns area to automatically fill available vertical space. This aligns with React/Ink best practices and eliminates manual row calculations.", "deleted": false, "createdAt": "2025-10-27T22:35:08.114Z" } ], "updated": "2025-10-28T02:55:49.519Z", "nextRuleId": 6, "nextExampleId": 3, "nextQuestionId": 1, "nextNoteId": 0 }, "BOARD-015": { "id": "BOARD-015", "title": "Fix work unit details panel to be static 4 lines high", "type": "story", "status": "done", "createdAt": "2025-10-27T23:13:42.715Z", "updatedAt": "2025-10-27T23:26:22.707Z", "description": "The work unit details panel was dynamically sized, causing the third line (metadata) to disappear. Make it static 4 lines: title, description, metadata, empty spacing.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-27T23:13:47.864Z" }, { "state": "testing", "timestamp": "2025-10-27T23:17:16.407Z" }, { "state": "implementing", "timestamp": "2025-10-27T23:21:12.308Z" }, { "state": "validating", "timestamp": "2025-10-27T23:24:34.686Z" }, { "state": "done", "timestamp": "2025-10-27T23:26:22.707Z" } ], "userStory": { "role": "developer viewing the TUI Kanban board", "action": "see work unit details in a consistent layout", "benefit": "the metadata line doesn't disappear when viewport calculations change" }, "rules": [ { "id": 0, "text": "Work Unit Details panel must always be exactly 4 content lines high (plus 1 header line)", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" }, { "id": 1, "text": "Line 1 must show: work unit ID and title", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" }, { "id": 2, "text": "Line 2 must show: first line of description (or empty if no description)", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" }, { "id": 3, "text": "Line 3 must show: metadata (Epic, Estimate, Status separated by |)", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" }, { "id": 4, "text": "Line 4 must be: empty spacing line", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" }, { "id": 5, "text": "Panel height must not change based on content - always 4 lines", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" }, { "id": 6, "text": "Viewport height calculation must account for the 5-line Work Unit Details section (1 header + 4 content)", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" } ], "examples": [ { "id": 0, "text": "Work unit TECH-001 with long description shows: Line 1: ID+title, Line 2: first desc line, Line 3: Status: backlog, Line 4: empty", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" }, { "id": 1, "text": "Work unit with no description shows: Line 1: ID+title, Line 2: empty, Line 3: Epic: x | Estimate: 5pts | Status: implementing, Line 4: empty", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" }, { "id": 2, "text": "No work unit selected shows: Line 1: 'No work unit selected' (centered), Lines 2-4: empty", "deleted": false, "createdAt": "2025-10-27T23:13:42.715Z" } ], "nextRuleId": 7, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "LOG-001": { "id": "LOG-001", "title": "Add winston universal logger for fspec", "type": "story", "status": "done", "createdAt": "2025-10-28T00:29:38.433Z", "updatedAt": "2025-10-28T09:37:30.636Z", "description": "Add winston logging library as the universal logging solution for fspec. Configure winston with file transport (/tmp/fspec.log) and console transport. Support log levels (error, warn, info, debug). Replace all console.error calls with logger.error. Provide singleton logger instance importable throughout codebase.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T09:14:42.459Z" }, { "state": "testing", "timestamp": "2025-10-28T09:29:52.250Z" }, { "state": "implementing", "timestamp": "2025-10-28T09:32:46.981Z" }, { "state": "validating", "timestamp": "2025-10-28T09:35:14.151Z" }, { "state": "done", "timestamp": "2025-10-28T09:37:30.637Z" } ], "userStory": { "role": "fspec developer", "action": "have a universal logging system with winston", "benefit": "I can debug issues, track command execution, and maintain consistent logging across the codebase" }, "rules": [ { "id": 0, "text": "Log file must be stored in ~/.fspec/fspec.log (platform-agnostic home directory)", "deleted": false, "createdAt": "2025-10-28T00:29:38.433Z" }, { "id": 1, "text": "Winston must use append-only file transport (safe for concurrent writes)", "deleted": false, "createdAt": "2025-10-28T00:29:38.433Z" }, { "id": 2, "text": "Support log levels: error, warn, info, debug", "deleted": false, "createdAt": "2025-10-28T00:29:38.433Z" }, { "id": 3, "text": "Replace all console.error calls with logger.error throughout codebase", "deleted": false, "createdAt": "2025-10-28T00:29:38.433Z" }, { "id": 4, "text": "Provide singleton logger instance importable throughout codebase", "deleted": false, "createdAt": "2025-10-28T00:29:38.433Z" } ], "examples": [ { "id": 0, "text": "Developer imports logger and calls logger.error('message') - logs to ~/.fspec/fspec.log", "deleted": false, "createdAt": "2025-10-28T00:29:38.433Z" }, { "id": 1, "text": "Multiple fspec processes run concurrently - all append to same log file without corruption", "deleted": false, "createdAt": "2025-10-28T00:29:38.433Z" }, { "id": 2, "text": "Developer calls logger.debug('debug message') - logged only if debug level enabled", "deleted": false, "createdAt": "2025-10-28T00:29:38.433Z" } ], "estimate": 3, "updated": "2025-10-28T09:37:30.636Z", "nextRuleId": 5, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-016": { "id": "BOARD-016", "title": "Work unit details panel shows incorrect work unit after reordering", "type": "bug", "status": "done", "createdAt": "2025-10-28T01:27:18.527Z", "updatedAt": "2025-10-28T02:48:17.334Z", "description": "When using bracket keys to reorder work units, the Work Unit Details panel at the top of the board displays the wrong work unit. The selection cursor moves correctly, but the details panel doesn't update to show the newly selected work unit's information.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T01:27:53.427Z" }, { "state": "testing", "timestamp": "2025-10-28T01:28:34.324Z" }, { "state": "implementing", "timestamp": "2025-10-28T01:28:40.250Z" }, { "state": "validating", "timestamp": "2025-10-28T01:29:40.013Z" }, { "state": "specifying", "timestamp": "2025-10-28T01:43:50.612Z" }, { "state": "testing", "timestamp": "2025-10-28T01:49:11.783Z" }, { "state": "implementing", "timestamp": "2025-10-28T01:55:52.760Z" }, { "state": "validating", "timestamp": "2025-10-28T02:03:26.775Z" }, { "state": "done", "timestamp": "2025-10-28T02:06:16.024Z" }, { "state": "validating", "timestamp": "2025-10-28T02:09:27.574Z" }, { "state": "done", "timestamp": "2025-10-28T02:09:33.745Z" }, { "state": "specifying", "timestamp": "2025-10-28T02:10:31.576Z" }, { "state": "testing", "timestamp": "2025-10-28T02:12:46.156Z" }, { "state": "implementing", "timestamp": "2025-10-28T02:13:30.750Z" }, { "state": "validating", "timestamp": "2025-10-28T02:21:43.109Z" }, { "state": "done", "timestamp": "2025-10-28T02:26:14.882Z" }, { "state": "validating", "timestamp": "2025-10-28T02:36:05.973Z" }, { "state": "done", "timestamp": "2025-10-28T02:36:17.431Z" }, { "state": "specifying", "timestamp": "2025-10-28T02:37:36.529Z" }, { "state": "testing", "timestamp": "2025-10-28T02:38:42.857Z" }, { "state": "implementing", "timestamp": "2025-10-28T02:39:42.279Z" }, { "state": "validating", "timestamp": "2025-10-28T02:40:35.699Z" }, { "state": "done", "timestamp": "2025-10-28T02:40:40.356Z" }, { "state": "validating", "timestamp": "2025-10-28T02:44:41.136Z" }, { "state": "done", "timestamp": "2025-10-28T02:44:46.378Z" }, { "state": "specifying", "timestamp": "2025-10-28T02:46:10.033Z" }, { "state": "testing", "timestamp": "2025-10-28T02:46:44.961Z" }, { "state": "implementing", "timestamp": "2025-10-28T02:47:25.221Z" }, { "state": "validating", "timestamp": "2025-10-28T02:48:16.575Z" }, { "state": "done", "timestamp": "2025-10-28T02:48:17.336Z" } ], "rules": [ { "id": 0, "text": "Done column work units are sorted by 'updated' timestamp in DESCENDING order (most recent first)", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 1, "text": "groupedWorkUnits for done column MUST apply sort BEFORE passing units to UnifiedBoardLayout", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 2, "text": "Work Unit Details panel selectedWorkUnit MUST match the visual position in the sorted done column display", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 3, "text": "When moving work unit TO done status, insert work unit ID into states.done array at CORRECT sorted position (most recent 'updated' timestamp first)", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 4, "text": "update-work-unit-status command MUST set 'updated' field to current ISO timestamp when transitioning TO done status", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 5, "text": "Display order in TUI should match file order - NO runtime sorting in BoardView or UnifiedBoardLayout", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 6, "text": "Use SHARED utility function for inserting/moving work units in states arrays (similar to moveWorkUnitUp/Down) - do NOT duplicate array manipulation logic", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 7, "text": "REFACTOR moveWorkUnitUp/Down into shared utility function for array manipulation, then reuse for sorted insertion into done column", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 8, "text": "When moving ANY work unit to done status, the ENTIRE states.done array MUST be sorted by 'updated' timestamp (most recent first), not just the newly inserted work unit", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 9, "text": "Find and REMOVE any runtime sorting logic in TUI components (BoardView, UnifiedBoardLayout, groupedWorkUnits) - the file order IS the display order", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 10, "text": "When sorting done array, use 'updated' field if present, otherwise fall back to 'createdAt' field for timestamp comparison", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" } ], "examples": [ { "id": 0, "text": "Done column has 3 work units: BOARD-001 (updated 10:00), BOARD-002 (updated 11:00), BOARD-003 (updated 09:00). Display order is BOARD-002, BOARD-001, BOARD-003. User selects position 0 (BOARD-002), details panel shows BOARD-002.", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 1, "text": "BOARD-005 currently in implementing status (updated: 2025-10-28T10:00:00Z). User runs 'fspec update-work-unit-status BOARD-005 done'. States.done array has [BOARD-003, BOARD-001]. BOARD-003.updated=11:00, BOARD-001.updated=09:00. BOARD-005 inserted at position 1 (after BOARD-003, before BOARD-001). Final states.done: [BOARD-003, BOARD-005, BOARD-001].", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 2, "text": "Done column states.done array: [BOARD-003, BOARD-005, BOARD-001]. TUI displays in exact file order: position 0=BOARD-003, position 1=BOARD-005, position 2=BOARD-001. User selects position 1, details panel shows BOARD-005 (NOT BOARD-001).", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 3, "text": "Done array has [BOARD-003 (11:00), BOARD-001 (09:00), BOARD-005 (12:00)] in wrong order. When BOARD-007 (10:00) moves to done, ENTIRE array is sorted to [BOARD-005, BOARD-003, BOARD-007, BOARD-001]", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 4, "text": "File has done array: [BOARD-005, BOARD-003, BOARD-001]. TUI displays in EXACT file order without any sorting. Position 0 shows BOARD-005, position 1 shows BOARD-003, position 2 shows BOARD-001.", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 5, "text": "Work unit has updated='2025-10-28T12:00:00Z' and createdAt='2025-10-27T09:00:00Z'. Sorting uses updated (12:00) because it exists.", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 6, "text": "Work unit has NO updated field but has createdAt='2025-10-27T10:00:00Z'. Sorting falls back to createdAt (10:00).", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 7, "text": "Done array: [A (updated=12:00), B (no updated, createdAt=11:00), C (updated=10:00)]. After sorting: [A (12:00), B (11:00), C (10:00)] - all sorted by timestamp with fallback.", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" } ], "questions": [ { "id": 0, "text": "@human: Should the sorting be applied in the groupedWorkUnits computation in BoardView.tsx, or somewhere else?", "selected": true, "answer": "Sort should be applied when WRITING to work-units.json states.done array, NOT at display time. When work unit moves to done, insert it in the correct position based on updated timestamp (most recent first).", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 1, "text": "@human: Are there any other columns besides 'done' that need special sorting, or is it only the done column?", "selected": true, "answer": "Only the done column needs special sorting. All other columns (backlog, specifying, testing, implementing, validating, blocked) maintain manual order from states arrays.", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" }, { "id": 2, "text": "@human: The 'updated' field is optional in the WorkUnit interface - should we handle work units without an 'updated' timestamp? If so, how should they be sorted?", "selected": true, "answer": "Work units MUST have 'updated' field set when moving to done. The update-work-unit-status command should set 'updated' field to current timestamp when transitioning to done.", "deleted": false, "createdAt": "2025-10-28T01:27:18.527Z" } ], "userStory": { "role": "developer using TUI board", "action": "see correct work unit details for selected item in done column", "benefit": "I can verify completed work matches what's displayed on screen" }, "estimate": 5, "updated": "2025-10-28T02:48:17.335Z", "nextRuleId": 11, "nextExampleId": 8, "nextQuestionId": 3, "nextNoteId": 0 }, "LOCK-001": { "id": "LOCK-001", "title": "Implement file locking for concurrent access safety", "type": "story", "status": "done", "createdAt": "2025-10-28T03:12:16.122Z", "updatedAt": "2025-10-28T05:32:31.219Z", "description": "Add three-layer file locking (proper-lockfile + readers-writer + atomic writes) to prevent JSON file corruption when multiple fspec instances run concurrently", "children": [], "userStory": { "role": "developer running multiple fspec instances concurrently", "action": "prevent JSON file corruption from race conditions", "benefit": "I can safely run multiple commands and TUI simultaneously without data loss" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T03:12:31.138Z" }, { "state": "testing", "timestamp": "2025-10-28T04:30:21.953Z" }, { "state": "specifying", "timestamp": "2025-10-28T04:31:18.647Z" }, { "state": "testing", "timestamp": "2025-10-28T05:16:06.302Z" }, { "state": "implementing", "timestamp": "2025-10-28T05:21:37.588Z" }, { "state": "validating", "timestamp": "2025-10-28T05:23:57.599Z" }, { "state": "done", "timestamp": "2025-10-28T05:32:31.219Z" } ], "rules": [ { "id": 0, "text": "File locking MUST use three-layer architecture: (1) proper-lockfile for inter-process coordination, (2) readers-writer pattern for in-process optimization, (3) atomic write-replace for safe writes", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 1, "text": "Multiple readers can read the same file concurrently (readers-writer pattern allows parallel reads)", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 2, "text": "Only ONE writer can modify a file at a time (exclusive write lock blocks all readers and other writers)", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 3, "text": "All file writes MUST use atomic write-replace pattern (write to temp file + rename) to prevent partial writes", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 4, "text": "proper-lockfile MUST use stale lock detection (10 second timeout) to prevent deadlocks from crashed processes", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 5, "text": "Lock acquisition MUST use retry logic with exponential backoff (10 retries, 50-500ms timeout range)", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 6, "text": "LockedFileManager MUST be a singleton to ensure in-process lock coordination across all file operations", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 7, "text": "All JSON file operations (work-units.json, tags.json, foundation.json, etc.) MUST use LockedFileManager", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 8, "text": "Read-modify-write operations MUST use transaction() method to ensure atomicity of the entire operation", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 9, "text": "Lock release MUST happen in finally block to prevent lock leaks on errors", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 10, "text": "YES - Support network filesystems. proper-lockfile's mkdir strategy is atomic on both local and network filesystems (NFS, SMB). No additional implementation cost, works in CI/CD and team environments.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 11, "text": "Throw error immediately after 10 retries with exponential backoff (50-500ms, ~5 seconds total). Simple, clean error message: 'Failed to acquire file lock. Check for stuck fspec processes.' Exit code 1.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 12, "text": "NEVER cache file contents. Always read from disk for consistency. Files are small (~200KB max), reads are fast (~3-5ms), caching adds complexity and risk of stale data across processes. Correctness > speed.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 13, "text": "Optional debug metrics via FSPEC_DEBUG_LOCKS environment variable. Logs lock acquisition time, wait time, retries, hold duration. Ties into LOG-001 logging infrastructure. Silent by default, verbose when debugging.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 14, "text": "All-at-once migration (NOT incremental). MUST work 100% perfectly the first time. Complete implementation: LockedFileManager + refactor utilities + refactor all ~50 commands + refactor TUI store + comprehensive tests. No partial states, no gradual rollout.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 15, "text": "ensure* functions use read-lock-first pattern: attempt read with READ lock, on ENOENT upgrade to WRITE lock with double-check before creating file", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 16, "text": "READ locks released immediately after JSON.parse() completes - data is in memory, lock no longer needed, allows other operations to proceed", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 17, "text": "transaction() method uses mutation-based API: callback receives data, mutates in place, returns void - fileManager writes mutated data automatically on completion", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 18, "text": "transaction() errors cause rollback: if callback throws error, no write occurs and file remains unchanged - error propagates to caller for proper logging and exit codes", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 19, "text": "Multi-file operations use sequential transactions (not atomic): each file gets separate transaction, if later transaction fails earlier transactions already committed - acceptable due to denormalized data, defensive querying, and repair utilities", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 20, "text": "Debug metrics enabled via FSPEC_DEBUG_LOCKS environment variable: logs lock type, file path, wait time, hold duration, retry count - silent by default, verbose when debugging - ties into LOG-001 logging infrastructure when available", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" } ], "examples": [ { "id": 0, "text": "User runs 'fspec list-work-units' in terminal 1 AND 'fspec update-work-unit-status BOARD-001 done' in terminal 2 simultaneously - Both commands acquire proper-lockfile locks, list-work-units reads while update-work-unit-status waits for write lock, no corruption occurs", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 1, "text": "TUI board is running (refreshing every 2 seconds) AND user runs 'fspec create-story PREFIX Title' - TUI's read lock and command's write lock coordinate via proper-lockfile, work-units.json is never corrupted, TUI sees new work unit after refresh", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 2, "text": "Three fspec commands run concurrently: (1) list-work-units, (2) show-work-unit BOARD-001, (3) update-work-unit-status BOARD-002 done - Commands 1 and 2 read concurrently with in-process readers lock, command 3 waits for exclusive write lock, all succeed without corruption", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 3, "text": "Process 1 acquires write lock on work-units.json and crashes mid-write - proper-lockfile's stale lock detection (10 second timeout) allows Process 2 to acquire lock after timeout, preventing permanent deadlock", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 4, "text": "Command writes to work-units.json using atomic pattern: (1) writes to work-units.json.tmp.abc123, (2) renames to work-units.json - If crash occurs during step 1, original file is intact; if during step 2, rename is atomic", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 5, "text": "Reader 1 and Reader 2 both call fileManager.readJSON('work-units.json') - Both acquire in-process read locks simultaneously (readers-writer pattern), both acquire proper-lockfile locks with retry, both read file concurrently", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 6, "text": "Writer calls fileManager.writeJSON('work-units.json', data) while Reader is active - Writer waits for Reader's in-process read lock to release, then acquires exclusive write lock, prevents read-during-write corruption", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 7, "text": "Command refactoring minimal change: Replace 'const data = await ensureWorkUnitsFile(cwd); ... await writeFile(file, JSON.stringify(data, 2))' with 'await fileManager.transaction(file, async (data) => { ... })' - same 400 lines of mutation logic unchanged", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 8, "text": "Transaction rollback on error: 'await fileManager.transaction(file, async (data) => { if (\\!valid) throw new Error(\"bad\"); data.x = 1; })' - Error thrown, no write occurs, file unchanged, error propagates to command catch block", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 9, "text": "Multi-file sequential transactions: 'await fileManager.transaction(workUnitsFile, async (data) => { data.workUnits[id] = newWorkUnit; }); await fileManager.transaction(epicsFile, async (data) => { data.epics[epicId].workUnits.push(id); });' - If second fails first committed, run fspec repair-work-units to fix", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 10, "text": "Debug metrics output: 'FSPEC_DEBUG_LOCKS=1 fspec update-work-unit-status AUTH-001 done' logs '[LOCK] Acquired WRITE lock on work-units.json (waited 2ms, held 15ms, retries 0)' - helps diagnose performance issues and lock contention", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" } ], "architectureNotes": [ { "id": 0, "text": "Three-Layer Lock Architecture: Layer 1 (Inter-Process) = proper-lockfile with mkdir strategy for cross-process coordination; Layer 2 (In-Process) = Readers-writer pattern using promises and queues for concurrent reads; Layer 3 (Atomic Writes) = Temp file + rename for POSIX atomic write guarantees", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 1, "text": "LockedFileManager Singleton Pattern: Single instance coordinates all in-process locks via Map<string, number> for read counts and Set<string> for write locks, with separate waiting queues (Array<() => void>) for blocked readers and writers", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 2, "text": "proper-lockfile Configuration: stale=10000ms (10 second timeout for crashed processes), retries={retries:10, minTimeout:50ms, maxTimeout:500ms} for exponential backoff, realpath=false for symlink support and performance", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 3, "text": "Affected Files: work-units.json (230+ work units, high contention), foundation.json, tags.json, prefixes.json, epics.json, example-map.json, fspec-hooks.json - ALL must use LockedFileManager", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 4, "text": "Migration Strategy: (1) Create src/utils/file-manager.ts with LockedFileManager class, (2) Refactor ensure-files.ts to use fileManager singleton, (3) Update all commands to use fileManager.transaction() for read-modify-write, (4) Add comprehensive concurrency tests", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" } ], "attachments": [ "spec/attachments/LOCK-001/file-locking-architecture.md" ], "questions": [ { "id": 0, "text": "@human: Should the file locking system handle network filesystems (NFS, SMB) or only local filesystems?", "selected": true, "answer": "All-at-once migration (NOT incremental). MUST work 100% perfectly the first time. Complete implementation: LockedFileManager + refactor utilities + refactor all ~50 commands + refactor TUI store + comprehensive tests. No partial states, no gradual rollout.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 1, "text": "@human: What should happen if lock acquisition fails after all retries - throw error immediately or offer user option to retry/abort?", "selected": true, "answer": "Throw error immediately with clear message. The retry logic (10 retries with exponential backoff) already provides sufficient resilience. After retries exhausted, command should fail fast with actionable error message suggesting user check for stuck processes.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 2, "text": "@human: Should LockedFileManager cache file contents to reduce disk I/O, or always read from disk for consistency?", "selected": true, "answer": "Always read from disk for consistency. Caching introduces cache invalidation complexity and potential stale reads in concurrent scenarios. File I/O performance is acceptable (3-5ms reads) and correctness is more important than speed.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 3, "text": "@human: Do we need metrics/logging for lock performance (acquisition time, wait time, contentions) or keep it simple?", "selected": true, "answer": "Keep it simple initially, add metrics later if needed. Start with basic error logging only. Can add FSPEC_DEBUG_LOCKS environment variable for verbose lock debugging in future iterations (Phase 2 enhancement).", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" }, { "id": 4, "text": "@human: Should the migration happen in one phase (all-at-once) or incrementally (file by file, command by command)?", "selected": true, "answer": "Incremental migration is safer. Phase 1: Create LockedFileManager + refactor ensure-files.ts. Phase 2: Migrate high-risk commands (update-work-unit-status, create-story). Phase 3: Migrate remaining commands. Phase 4: TUI store. This allows testing at each phase.", "deleted": false, "createdAt": "2025-10-28T03:12:16.122Z" } ], "estimate": 8, "updated": "2025-10-28T05:32:31.219Z", "nextRuleId": 21, "nextExampleId": 11, "nextQuestionId": 5, "nextNoteId": 5 }, "LOCK-002": { "id": "LOCK-002", "title": "Implement file locking system (LockedFileManager + refactoring)", "type": "story", "status": "done", "createdAt": "2025-10-28T05:44:02.203Z", "updatedAt": "2025-10-28T09:25:02.968Z", "children": [], "dependsOn": [ "LOCK-001" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T05:44:53.719Z" }, { "state": "testing", "timestamp": "2025-10-28T06:11:09.325Z" }, { "state": "implementing", "timestamp": "2025-10-28T06:17:19.377Z" }, { "state": "validating", "timestamp": "2025-10-28T09:10:46.579Z" }, { "state": "done", "timestamp": "2025-10-28T09:11:11.518Z" }, { "state": "validating", "timestamp": "2025-10-28T09:24:57.645Z" }, { "state": "done", "timestamp": "2025-10-28T09:25:02.968Z" } ], "userStory": { "role": "developer implementing file locking", "action": "refactor all JSON file operations to use LockedFileManager", "benefit": "all file operations are protected by the three-layer locking system" }, "rules": [ { "id": 0, "text": "Create src/utils/file-manager.ts with LockedFileManager singleton class (proper-lockfile + readers-writer pattern + atomic writes)", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 1, "text": "Refactor src/utils/ensure-files.ts to use LockedFileManager for all ensure* functions (ensureWorkUnitsFile, ensureTagsFile, ensureFoundationFile, ensurePrefixesFile, ensureEpicsFile, ensureExampleMapFile, ensureHooksFile)", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 2, "text": "Refactor all 54 command files that import from ensure-files.ts to use fileManager.transaction() for read-modify-write operations", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 3, "text": "Refactor src/tui/store/fspecStore.ts to use LockedFileManager for all JSON file reads (TUI refresh operations)", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 4, "text": "All read-modify-write operations MUST use fileManager.transaction() with mutation-based callback API", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 5, "text": "ensure* functions MUST use read-lock-first pattern: attempt READ lock, on ENOENT upgrade to WRITE lock with double-check", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" } ], "examples": [ { "id": 0, "text": "NEW FILE: src/utils/file-manager.ts - Create LockedFileManager singleton with readJSON(), writeJSON(), transaction() methods", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 1, "text": "REFACTOR: src/utils/ensure-files.ts - All ensure* functions use fileManager.transaction() internally", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 2, "text": "REFACTOR: src/tui/store/fspecStore.ts - TUI store uses fileManager.readJSON() for all JSON reads (no writes, TUI is read-only)", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 3, "text": "REFACTOR: Work unit commands (20 files): update-work-unit.ts, update-work-unit-status.ts, create-task.ts, create-story.ts, create-bug.ts, delete-work-unit.ts, prioritize-work-unit.ts, repair-work-units.ts, validate-work-units.ts, set-user-story.ts, add-dependency.ts, remove-dependency.ts, clear-dependencies.ts, add-attachment.ts, remove-attachment.ts, add-architecture-note.ts, remove-architecture-note.ts, add-rule.ts, remove-rule.ts, add-example.ts, remove-example.ts, add-question.ts, remove-question.ts, answer-question.ts, add-assumption.ts", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 4, "text": "REFACTOR: Virtual hook commands (4 files): add-virtual-hook.ts, remove-virtual-hook.ts, clear-virtual-hooks.ts, copy-virtual-hooks.ts, list-virtual-hooks.ts", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 5, "text": "REFACTOR: Prefix and epic commands (2 files): update-prefix.ts, create-prefix.ts", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 6, "text": "REFACTOR: Tag commands (3 files): register-tag.ts, validate-tags.ts, list-tags.ts", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 7, "text": "REFACTOR: Foundation commands (3 files): update-foundation.ts, show-foundation.ts, add-diagram.ts", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 8, "text": "REFACTOR: Example mapping commands (3 files): generate-scenarios.ts, export-example-map.ts, import-example-map.ts", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 9, "text": "REFACTOR: Query/reporting commands (4 files): query-example-mapping-stats.ts, query-orphans.ts, query-dependency-stats.ts, suggest-dependencies.ts, export-dependencies.ts, list-work-units.ts, list-attachments.ts", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 10, "text": "REFACTOR: Board command (1 file): display-board.ts", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 11, "text": "CHECK: src/index.ts - May have direct JSON file access that needs refactoring", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 12, "text": "CHECK: src/utils/work-unit-tags.ts - May have direct JSON file access that needs refactoring", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 13, "text": "NEW TEST: src/utils/__tests__/file-manager.test.ts - Comprehensive unit tests for LockedFileManager (concurrency, retries, timeouts, atomic writes, readers-writer pattern)", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 14, "text": "UPDATE TEST: src/utils/__tests__/ensure-files.test.ts - Update tests to verify ensure* functions use fileManager.transaction()", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 15, "text": "UPDATE TEST: All command test files (50+ files) - Update mocks to use fileManager instead of direct file operations", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 16, "text": "UPDATE TEST: src/tui/__tests__/fspecStore-*.test.ts - Update TUI store tests to verify fileManager.readJSON() usage", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 17, "text": "UPDATE: package.json - Add proper-lockfile dependency (~4.1.2)", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 18, "text": "UPDATE: package.json - Add @types/proper-lockfile dev dependency", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 19, "text": "CHECK: src/hooks/integration.ts, src/hooks/config.ts, src/hooks/script-generation.ts - May have JSON file access that needs refactoring", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 20, "text": "CHECK: src/validators/validate-json-schema.ts, src/validators/generic-foundation-validator.ts, src/validators/json-schema.ts - May have JSON file access that needs refactoring", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" } ], "attachments": [ "spec/attachments/LOCK-002/file-locking-architecture.md", "spec/attachments/LOCK-002/remaining-refactoring-checklist.md" ], "architectureNotes": [ { "id": 0, "text": "CRITICAL: This is an all-at-once migration. MUST work 100% perfectly the first time. Complete implementation includes: LockedFileManager + refactor utilities + refactor all ~50-60 commands + refactor TUI store + comprehensive concurrency tests. NO partial states, NO gradual rollout.", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" }, { "id": 1, "text": "Implementation phases: (1) Create LockedFileManager singleton 2-3h, (2) Refactor ensure-files.ts 1-2h, (3) Refactor all commands 3-4h, (4) Refactor TUI store 1h, (5) Comprehensive testing 2-3h. Total estimate: 9-13 hours.", "deleted": false, "createdAt": "2025-10-28T05:44:02.203Z" } ], "estimate": 13, "updated": "2025-10-28T09:25:02.968Z", "nextRuleId": 6, "nextExampleId": 21, "nextQuestionId": 0, "nextNoteId": 2 }, "BUG-047": { "id": "BUG-047", "title": "Type mismatches in record-metric and record-tokens commands", "type": "bug", "status": "done", "createdAt": "2025-10-28T07:39:54.123Z", "updatedAt": "2025-10-28T10:22:09.061Z", "description": "# Bug Report: BUG-047\n\n## Type Mismatches in record-metric and record-tokens Commands\n\n**Discovered during**: LOCK-002 file locking refactoring\n**Date**: 2025-10-28\n**Reporter**: Claude (AI Assistant)\n\n---\n\n## Summary\n\nTwo command files have type mismatches between their function signatures and how they're called in command registration:\n- `src/commands/record-metric.ts`\n- `src/commands/record-tokens.ts`\n\nThese bugs existed **before** the LOCK-002 refactoring work began.\n\n---\n\n## Detailed Findings\n\n### File 1: `src/commands/record-metric.ts`\n\n**Function Signature** (lines 19-23):\n```typescript\nexport async function recordMetric(options: {\n workUnitId: string;\n tokens: number;\n cwd?: string;\n}): Promise<{ success: boolean; totalTokens?: number }>\n```\n\n**Command Registration Call** (lines 66-70):\n```typescript\nawait recordMetric({\n metric, // ❌ Not in function signature\n value: parseFloat(value), // ❌ Not in function signature\n unit: options.unit, // ❌ Not in function signature\n});\n```\n\n**Command Arguments** (lines 60-62):\n```typescript\n.argument('<metric>', 'Metric name')\n.argument('<value>', 'Metric value')\n.option('--unit <unit>', 'Unit of measurement')\n```\n\n**Problem**: The function expects `{ workUnitId, tokens, cwd }` but is called with `{ metric, value, unit }`. These are completely different parameter sets.\n\n---\n\n### File 2: `src/commands/record-tokens.ts`\n\n**Function Signature** (lines 19-23):\n```typescript\nexport async function recordTokens(options: {\n workUnitId: string;\n tokens: number;\n cwd?: string;\n}): Promise<{ success: boolean; totalTokens?: number }>\n```\n\n**Command Registration Call** (lines 76-79):\n```typescript\nawait recordTokens({\n workUnitId,\n tokens: parseInt(tokens, 10),\n operation: options.operation, // ❌ Not in function signature\n});\n```\n\n**Command Option** (lines 65-68):\n```typescript\n.option(\n '--operation <operation>',\n 'Operation type (e.g., specification, implementation)'\n)\n```\n\n**Problem**: The function doesn't accept an `operation` parameter but the command tries to pass it anyway.\n\n---\n\n## Impact Analysis\n\n### Current State\n- TypeScript compilation may be passing due to the `[key: string]: unknown` index signature in the options interface\n- Commands may be silently failing or ignoring parameters\n- Tests may not be covering these code paths\n\n### Expected Behavior\nThe function signatures should match the command registration calls exactly.\n\n### Potential Fixes\n\n#### Option A: Update Function Signatures (Recommended)\nMatch the functions to what the commands actually need:\n\n**record-metric.ts:**\n```typescript\nexport async function recordMetric(options: {\n metric: string;\n value: number;\n unit?: string;\n cwd?: string;\n}): Promise<{ success: boolean }>\n```\n\n**record-tokens.ts:**\n```typescript\nexport async function recordTokens(options: {\n workUnitId: string;\n tokens: number;\n operation?: string;\n cwd?: string;\n}): Promise<{ success: boolean; totalTokens?: number }>\n```\n\n#### Option B: Update Command Registration\nChange how commands call the functions to match existing signatures (may require rethinking command purpose).\n\n---\n\n## Discovery Context\n\nThese bugs were discovered during LOCK-002 refactoring when:\n1. Systematically refactoring command files to use `fileManager.transaction()`\n2. Applied standard pattern to these files\n3. Ran full test suite: **103 tests failed**\n4. Investigated failures and found pre-existing type mismatches\n5. Reverted changes to these files to isolate the issue\n\n**Git References:**\n- Last good commit before discovery: `efee27c`\n- Files were at HEAD~1 when bug discovered\n\n---\n\n## Reproduction Steps\n\n1. Review `src/commands/record-metric.ts` lines 19-23 and 66-70\n2. Review `src/commands/record-tokens.ts` lines 19-23 and 76-79\n3. Note the parameter mismatch between function signatures and calls\n4. Run: `npm run build` - TypeScript may pass due to index signature\n5. Run: `npm test` - Tests may fail or pass if not covering these paths\n\n---\n\n## Recommended Actions\n\n1. **Investigate Intent**: Determine what these commands are supposed to do\n - Are they for recording metrics OR token usage?\n - Should they operate on work units?\n\n2. **Fix Type Signatures**: Align function signatures with command usage\n\n3. **Add Tests**: Ensure test coverage for these commands\n\n4. **Update Documentation**: Clarify command purpose and usage\n\n5. **Continue LOCK-002**: These files can be refactored after types are fixed\n\n---\n\n## Notes\n\n- These bugs existed **before LOCK-002 refactoring**\n- Type system may not catch due to index signature: `[key: string]: unknown`\n- May need to check if similar patterns exist in other command files\n- Should verify if commands are actually used in production\n\n---\n\n## Related Work Units\n\n- **LOCK-002**: File locking refactoring (blocked by this bug for these 2 files)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T09:01:37.784Z" }, { "state": "testing", "timestamp": "2025-10-28T10:09:49.374Z" }, { "state": "implementing", "timestamp": "2025-10-28T10:12:30.550Z" }, { "state": "validating", "timestamp": "2025-10-28T10:21:42.113Z" }, { "state": "done", "timestamp": "2025-10-28T10:22:09.061Z" } ], "rules": [ { "id": 0, "text": "record-metric command accepts <metric> <value> arguments but function signature expects workUnitId and tokens", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 1, "text": "record-tokens command passes 'operation' option but function signature doesn't accept it", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 2, "text": "Function signatures must match their command action calls exactly", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 3, "text": "TypeScript compilation passes due to index signature [key: string]: unknown allowing extra properties", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 4, "text": "record-metric command accepts <metric> <value> arguments but function signature expects workUnitId and tokens", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 5, "text": "record-tokens command passes 'operation' option but function signature doesn't accept it", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 6, "text": "Function signatures must match their command action calls exactly", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 7, "text": "TypeScript compilation passes due to index signature [key: string]: unknown allowing extra properties", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" } ], "examples": [ { "id": 0, "text": "record-metric.ts: Function expects {workUnitId, tokens, cwd} but action calls with {metric, value, unit}", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 1, "text": "record-metric.ts line 63-66: Passes 'metric', 'value', 'unit' but function doesn't accept these parameters", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 2, "text": "record-tokens.ts: Function accepts {workUnitId, tokens, cwd} but action passes 'operation' which is not in signature", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 3, "text": "record-tokens.ts line 76: Passes 'operation' option but function signature at line 18-22 doesn't have operation parameter", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 4, "text": "record-metric.ts: Function expects {workUnitId, tokens, cwd} but action calls with {metric, value, unit}", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 5, "text": "record-metric.ts line 63-66: Passes 'metric', 'value', 'unit' but function doesn't accept these parameters", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 6, "text": "record-tokens.ts: Function accepts {workUnitId, tokens, cwd} but action passes 'operation' which is not in signature", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" }, { "id": 7, "text": "record-tokens.ts line 76: Passes 'operation' option but function signature at line 18-22 doesn't have operation parameter", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" } ], "questions": [ { "id": 0, "text": "@human: Looking at record-metric.ts, it seems there are TWO conflicting purposes: (1) The function implementation records token usage on work units, but (2) The command arguments suggest it should record arbitrary metrics (metric name, value, unit). Which behavior is intended? Should we align the function to match the command (generic metrics), or align the command to match the function (token tracking)?", "selected": true, "answer": "The function implementation in record-metric.ts actually records token usage on work units (identical to record-tokens). The command arguments suggesting generic metrics (metric name, value, unit) are incorrect. We should align the command to match the function: it should accept workUnitId and tokens, just like record-tokens does. The 'record-metric' command appears to be a duplicate/misnamed version of 'record-tokens' and should either be removed or fixed to match its actual implementation.", "deleted": false, "createdAt": "2025-10-28T07:39:54.123Z" } ], "userStory": { "role": "fspec developer", "action": "fix type mismatches in record-metric and record-tokens commands", "benefit": "commands work correctly with proper type safety" }, "assumptions": [ "The function implementation in record-metric.ts actually records token usage on work units (identical to record-tokens). The command arguments suggesting generic metrics (metric name, value, unit) are incorrect. We should align the command to match the function: it should accept workUnitId and tokens, just like record-tokens does. The 'record-metric' command appears to be a duplicate/misnamed version of 'record-tokens' and should either be removed or fixed to match its actual implementation.", "record-metric is a duplicate of record-tokens and should be deleted entirely. All references in documentation, tests, coverage files, and command registration must be removed." ], "estimate": 3, "updated": "2025-10-28T10:22:09.061Z", "nextRuleId": 8, "nextExampleId": 8, "nextQuestionId": 1, "nextNoteId": 0 }, "LOG-002": { "id": "LOG-002", "title": "Wire LockedFileManager errors to winston logger", "type": "story", "status": "done", "createdAt": "2025-10-28T09:39:57.419Z", "updatedAt": "2025-10-28T10:06:54.998Z", "description": "Integrate winston logger from LOG-001 with LockedFileManager from LOCK-001/LOCK-002. Log all file locking errors, timeouts, and lock compromises to ~/.fspec/fspec.log. Replace console.error calls in file-manager.ts with logger.error. Add structured logging with context (file path, operation type, lock metrics).", "children": [], "dependsOn": [ "LOG-001", "LOCK-002" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T09:40:36.413Z" }, { "state": "testing", "timestamp": "2025-10-28T09:43:22.192Z" }, { "state": "implementing", "timestamp": "2025-10-28T09:46:32.326Z" }, { "state": "validating", "timestamp": "2025-10-28T09:49:02.658Z" }, { "state": "done", "timestamp": "2025-10-28T09:51:28.248Z" } ], "userStory": { "role": "fspec developer", "action": "have file locking errors logged to winston", "benefit": "I can debug concurrency issues and lock failures in production" }, "rules": [ { "id": 0, "text": "Replace all console.error/console.log calls in file-manager.ts with logger.error/logger.debug", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" }, { "id": 1, "text": "Log lock errors with context: file path, lock type (READ/WRITE), error message", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" }, { "id": 2, "text": "Log lock metrics (wait time, hold duration, retries) at debug level when FSPEC_DEBUG_LOCKS enabled", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" }, { "id": 3, "text": "Log lock compromises at error level with file path and details", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" }, { "id": 4, "text": "Continue using existing logMetrics() function but route through winston instead of console.log", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" } ], "examples": [ { "id": 0, "text": "Lock timeout occurs - logs 'Lock timeout for work-units.json (WRITE lock) after 10s' to winston at error level", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" }, { "id": 1, "text": "Lock compromised during transaction - logs 'Lock compromised for epics.json' to winston at error level with stack trace", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" }, { "id": 2, "text": "FSPEC_DEBUG_LOCKS=1 enabled - logs lock metrics 'Acquired READ lock on work-units.json (waited 50ms, held 100ms, retries 0)' at debug level", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" }, { "id": 3, "text": "JSON parse error in readJSON - logs 'Failed to parse work-units.json: Unexpected token' at error level", "deleted": false, "createdAt": "2025-10-28T09:39:57.419Z" } ], "estimate": 2, "updated": "2025-10-28T09:51:28.247Z", "actualTokens": 140000, "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-017": { "id": "BOARD-017", "title": "Remove 'No work units' placeholder from empty board columns", "type": "story", "status": "done", "createdAt": "2025-10-28T10:57:16.187Z", "updatedAt": "2025-10-28T11:08:10.538Z", "description": "Remove the 'No work units' text from empty Kanban columns in the TUI board view. Users prefer clean empty columns without placeholder text.", "children": [], "userStory": { "role": "developer using fspec board", "action": "see clean empty columns without placeholder text", "benefit": "the board looks cleaner and less cluttered" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T10:57:37.239Z" }, { "state": "testing", "timestamp": "2025-10-28T11:00:24.671Z" }, { "state": "implementing", "timestamp": "2025-10-28T11:02:21.622Z" }, { "state": "validating", "timestamp": "2025-10-28T11:02:52.959Z" }, { "state": "done", "timestamp": "2025-10-28T11:08:10.538Z" } ], "rules": [ { "id": 0, "text": "Empty columns should display nothing, not 'No work units'", "deleted": false, "createdAt": "2025-10-28T10:57:16.187Z" }, { "id": 1, "text": "Only the column header should be visible for empty columns", "deleted": false, "createdAt": "2025-10-28T10:57:16.187Z" } ], "examples": [ { "id": 0, "text": "Backlog column has 5 work units, Testing column is empty → Testing column shows only header", "deleted": false, "createdAt": "2025-10-28T10:57:16.187Z" }, { "id": 1, "text": "All columns are empty → All columns show only headers with no placeholder text", "deleted": false, "createdAt": "2025-10-28T10:57:16.187Z" }, { "id": 2, "text": "Done column has work units, all other columns empty → Only Done shows work units, others show just headers", "deleted": false, "createdAt": "2025-10-28T10:57:16.187Z" } ], "estimate": 2, "updated": "2025-10-28T11:08:10.538Z", "nextRuleId": 2, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "INIT-013": { "id": "INIT-013", "title": "Replace hardcoded CLAUDE.md references with agent-agnostic placeholders", "type": "story", "status": "done", "createdAt": "2025-10-28T11:14:32.062Z", "updatedAt": "2025-10-28T11:23:28.182Z", "description": "Template files contain 3 hardcoded references to 'CLAUDE.md' instead of using {{DOC_TEMPLATE}} placeholder, causing all 18 agents to see incorrect references to CLAUDE.md in their generated documentation", "children": [], "userStory": { "role": "developer using any of the 18 supported AI agents", "action": "see correct references to my agent's documentation file in generated templates", "benefit": "I'm not confused by incorrect references to CLAUDE.md when using Cursor, Aider, or other agents" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T11:14:53.439Z" }, { "state": "testing", "timestamp": "2025-10-28T11:17:10.175Z" }, { "state": "implementing", "timestamp": "2025-10-28T11:18:00.100Z" }, { "state": "validating", "timestamp": "2025-10-28T11:18:49.657Z" }, { "state": "done", "timestamp": "2025-10-28T11:23:28.183Z" } ], "rules": [ { "id": 0, "text": "All template files must use {{DOC_TEMPLATE}} placeholder instead of hardcoded 'CLAUDE.md'", "deleted": false, "createdAt": "2025-10-28T11:14:32.062Z" }, { "id": 1, "text": "Template placeholders are replaced during generation by templateGenerator.ts replacePlaceholders() function", "deleted": false, "createdAt": "2025-10-28T11:14:32.062Z" }, { "id": 2, "text": "References to FOUNDATION.md and TAGS.md should remain hardcoded as they are universal across all agents", "deleted": false, "createdAt": "2025-10-28T11:14:32.062Z" } ], "examples": [ { "id": 0, "text": "File: src/utils/slashCommandSections/bootstrapFoundation.ts:62 contains 'spec/CLAUDE.md' → should be 'spec/{{DOC_TEMPLATE}}'", "deleted": false, "createdAt": "2025-10-28T11:14:32.062Z" }, { "id": 1, "text": "File: src/utils/projectManagementSections/fileStructure.ts:10 contains '├── CLAUDE.md' → should be '├── {{DOC_TEMPLATE}}'", "deleted": false, "createdAt": "2025-10-28T11:14:32.062Z" }, { "id": 2, "text": "File: src/utils/projectManagementSections/enforcement.ts:9 contains 'CLAUDE.md' → should be '{{DOC_TEMPLATE}}'", "deleted": false, "createdAt": "2025-10-28T11:14:32.062Z" }, { "id": 3, "text": "When Cursor user runs 'fspec init --agent=cursor', generated spec/CURSOR.md should reference 'spec/CURSOR.md' not 'spec/CLAUDE.md'", "deleted": false, "createdAt": "2025-10-28T11:14:32.062Z" }, { "id": 4, "text": "When Aider user runs 'fspec init --agent=aider', generated spec/AIDER.md should reference 'spec/AIDER.md' not 'spec/CLAUDE.md'", "deleted": false, "createdAt": "2025-10-28T11:14:32.062Z" } ], "estimate": 2, "updated": "2025-10-28T11:23:28.182Z", "nextRuleId": 3, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "INIT-014": { "id": "INIT-014", "title": "Replace hardcoded npm test in git-checkpoint conflict resolution with configured test command", "type": "story", "status": "done", "createdAt": "2025-10-28T11:32:32.262Z", "updatedAt": "2025-10-28T11:42:23.885Z", "description": "The detectConflicts function in git-checkpoint.ts generates system-reminders with hardcoded 'npm test' reference. This should use the configured test command from spec/fspec-config.json to support platform-agnostic workflows (pytest, cargo test, go test, etc.)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T11:32:37.741Z" }, { "state": "testing", "timestamp": "2025-10-28T11:35:31.967Z" }, { "state": "implementing", "timestamp": "2025-10-28T11:37:36.594Z" }, { "state": "validating", "timestamp": "2025-10-28T11:39:10.910Z" }, { "state": "done", "timestamp": "2025-10-28T11:42:23.885Z" } ], "userStory": { "role": "AI agent", "action": "see platform-agnostic test commands in git conflict resolution guidance", "benefit": "I can resolve conflicts and run the correct test command for my project (pytest, cargo test, go test, npm test, etc.)" }, "rules": [ { "id": 0, "text": "The detectConflicts function must load fspec config to get the configured test command", "deleted": false, "createdAt": "2025-10-28T11:32:32.262Z" }, { "id": 1, "text": "System-reminder text must use the configured test command instead of hardcoded 'npm test'", "deleted": false, "createdAt": "2025-10-28T11:32:32.262Z" }, { "id": 2, "text": "If config loading fails or test command is not configured, fallback to generic language 'your configured test command'", "deleted": false, "createdAt": "2025-10-28T11:32:32.262Z" } ], "examples": [ { "id": 0, "text": "Python project with 'pytest' configured - system-reminder shows 'Run: pytest' not 'npm test'", "deleted": false, "createdAt": "2025-10-28T11:32:32.262Z" }, { "id": 1, "text": "Rust project with 'cargo test' configured - system-reminder shows 'Run: cargo test'", "deleted": false, "createdAt": "2025-10-28T11:32:32.262Z" }, { "id": 2, "text": "Go project with 'go test ./...' configured - system-reminder shows 'Run: go test ./...'", "deleted": false, "createdAt": "2025-10-28T11:32:32.262Z" }, { "id": 3, "text": "Project without fspec-config.json - system-reminder shows 'Run: your configured test command' as fallback", "deleted": false, "createdAt": "2025-10-28T11:32:32.262Z" }, { "id": 4, "text": "JavaScript project with 'npm test' configured - system-reminder correctly shows 'Run: npm test' (proving config loading works)", "deleted": false, "createdAt": "2025-10-28T11:32:32.262Z" } ], "updated": "2025-10-28T11:42:23.885Z", "nextRuleId": 3, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-018": { "id": "BOARD-018", "title": "Git file watchers broken due to direct file watching and atomic operations", "type": "bug", "status": "done", "createdAt": "2025-10-28T11:52:37.856Z", "updatedAt": "2025-10-28T12:18:30.493Z", "description": "CRITICAL: fs.watch implementation for git files (.git/refs/stash, .git/index, .git/HEAD) is broken due to watching files directly instead of directories. Git uses atomic file operations (write temp, rename to final) which create new inodes, breaking file-based watchers. Additionally missing event type filtering (only checks 'change', misses 'rename'), error handling, and platform-specific behavior handling.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T11:52:53.607Z" }, { "state": "testing", "timestamp": "2025-10-28T11:55:35.656Z" }, { "state": "implementing", "timestamp": "2025-10-28T11:56:51.863Z" }, { "state": "specifying", "timestamp": "2025-10-28T11:57:42.331Z" }, { "state": "testing", "timestamp": "2025-10-28T12:00:12.348Z" }, { "state": "implementing", "timestamp": "2025-10-28T12:01:23.058Z" }, { "state": "validating", "timestamp": "2025-10-28T12:02:31.717Z" }, { "state": "done", "timestamp": "2025-10-28T12:05:12.522Z" }, { "state": "specifying", "timestamp": "2025-10-28T12:12:01.716Z" }, { "state": "testing", "timestamp": "2025-10-28T12:15:22.839Z" }, { "state": "implementing", "timestamp": "2025-10-28T12:16:35.944Z" }, { "state": "validating", "timestamp": "2025-10-28T12:18:11.576Z" }, { "state": "done", "timestamp": "2025-10-28T12:18:30.494Z" } ], "rules": [ { "id": 0, "text": "Git file watchers MUST watch parent directories (not files directly) to handle atomic rename operations", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 1, "text": "Watchers MUST have error event handlers to prevent silent failures", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 2, "text": "Implementation MUST follow the working pattern from work-units.json watcher (BoardView.tsx:81-102)", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 3, "text": "Git file watchers MUST use chokidar library for cross-platform compatibility (fs.watch filename parameter unreliable on macOS)", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 4, "text": "Chokidar watchers MUST watch specific files (.git/refs/stash, .git/index, .git/HEAD) not directories", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 5, "text": "Chokidar configuration MUST use ignoreInitial: true to prevent initial file scan triggering change events", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" } ], "examples": [ { "id": 0, "text": "Watcher encounters permission error on .git/index, error handler logs warning, continues monitoring other files", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 1, "text": "Directory watcher filters events: only responds when filename='index' or 'stash' or 'HEAD', ignores other .git files", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 2, "text": "User runs TUI on Linux, atomic rename triggers 'rename' event (not 'change'), watcher correctly handles both event types", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 3, "text": "User runs 'git stash push', watcher detects event in .git/refs/ directory for filename='stash', triggers loadStashes()", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" }, { "id": 4, "text": "User runs 'git stash push', chokidar detects change to .git/refs/stash file, triggers loadStashes() on macOS", "deleted": false, "createdAt": "2025-10-28T11:52:37.856Z" } ], "userStory": { "role": "developer using fspec TUI", "action": "see real-time git status updates that actually work", "benefit": "the TUI reflects changes without missing events due to atomic file operations" }, "estimate": 3, "updated": "2025-10-28T12:18:30.493Z", "nextRuleId": 6, "nextExampleId": 5, "nextQuestionId": 0, "nextNoteId": 0 }, "BOARD-019": { "id": "BOARD-019", "title": "Add fspec logo to TUI header", "type": "story", "status": "done", "createdAt": "2025-10-28T20:49:12.586Z", "updatedAt": "2025-10-28T22:22:27.144Z", "description": "Display fspec ASCII logo in top-left corner of TUI, with Git Stashes and Changed Files panels positioned to the right of the logo in a separate container", "children": [], "userStory": { "role": "developer using fspec TUI", "action": "see the fspec logo in the TUI header", "benefit": "I have clear visual branding and better understand which tool I'm using" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T20:49:39.367Z" }, { "state": "testing", "timestamp": "2025-10-28T20:52:52.804Z" }, { "state": "implementing", "timestamp": "2025-10-28T20:54:00.928Z" }, { "state": "specifying", "timestamp": "2025-10-28T21:00:08.420Z" }, { "state": "testing", "timestamp": "2025-10-28T21:06:39.503Z" }, { "state": "specifying", "timestamp": "2025-10-28T21:07:43.276Z" }, { "state": "testing", "timestamp": "2025-10-28T21:28:09.971Z" }, { "state": "specifying", "timestamp": "2025-10-28T21:37:58.292Z" }, { "state": "testing", "timestamp": "2025-10-28T21:40:04.955Z" }, { "state": "implementing", "timestamp": "2025-10-28T21:41:04.647Z" }, { "state": "validating", "timestamp": "2025-10-28T21:51:14.177Z" }, { "state": "done", "timestamp": "2025-10-28T22:22:27.145Z" } ], "rules": [ { "id": 0, "text": "Logo MUST be ASCII art positioned in top-left corner of TUI", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 1, "text": "Logo container MUST be separate from Git Stashes/Changed Files container", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 2, "text": "Git Stashes and Changed Files panels MUST be positioned to the right of the logo", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 3, "text": "Logo format: 3 lines of ASCII art: ┏┓┏┓┏┓┏┓┏┓ / ┣ ┗┓┃┃┣ ┃ / ┻ ┗┛┣┛┗┛┗┛", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 4, "text": "Component structure: Logo (left fixed width) | GitPanels (right flex) | Board (below, full width)", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 5, "text": "UnifiedBoardLayout MUST keep state management: scroll offsets per column, shimmer animation state, terminal dimensions", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 6, "text": "UnifiedBoardLayout MUST keep computed values: column width calculation, viewport height, work unit grouping by status, last changed work unit", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 7, "text": "UnifiedBoardLayout MUST keep effects: auto-scroll to keep selection visible (lines 281-350), shimmer animation interval (lines 258-277)", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 8, "text": "UnifiedBoardLayout MUST keep keyboard input handling: arrow keys, Page Up/Down, Enter, bracket keys (lines 353-402)", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 9, "text": "HYBRID APPROACH: KEEP buildBorderRow() (lines 168-183) for table borders, KEEP border Text rows, REPLACE content rows with Box components", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 10, "text": "KEEP fitToWidth() (lines 94-99) for border alignment, REMOVE centerText() and logo injection hack (lines 593-615)", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 11, "text": "Content components (GitStashesPanel, ChangedFilesPanel, WorkUnitDetailsPanel, StatusColumn, WorkUnitCard, FooterPanel) return Box or Text with NO borders - borders added by UnifiedBoardLayout", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" } ], "examples": [ { "id": 0, "text": "TUI displays logo in left container (3 lines tall), Git Stashes panel in right container beside it", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 1, "text": "Logo takes up minimal width (approx 11 characters), leaving maximum space for git panels", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 2, "text": "TUI layout: [Logo Container | Git Info Container] where Git Info contains stashes + changed files vertically stacked", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 3, "text": "TUI uses flexDirection='row' for Logo|GitPanels horizontal layout, flexDirection='column' for vertical stacking", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 4, "text": "Logo component: Box with width=11, contains 3 Text elements (logo lines)", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 5, "text": "WorkUnitCards: Individual Box components per work unit, not pre-rendered text strings", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 6, "text": "Terminal width handling: Use <Box width={terminalWidth}> as root container, Ink handles responsive layout automatically", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 7, "text": "StatusColumn receives props: status (string), units (WorkUnit[]), scrollOffset (number), focusedColumnIndex, selectedWorkUnitIndex, shimmerPosition, lastChangedWorkUnit", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 8, "text": "WorkUnitCard receives props: workUnit (WorkUnit), isSelected (boolean), isLastChanged (boolean), shimmerPosition (number) for character-by-character animation", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 9, "text": "GitStashesPanel receives props: stashes (array), displays first 3 stashes with checkpoint name and relative time (e.g., '2 days ago')", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 10, "text": "ChangedFilesPanel receives props: stagedFiles (string[]), unstagedFiles (string[]), displays first 3 files with '+' for staged and 'M' for unstaged", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 11, "text": "WorkUnitDetailsPanel receives props: selectedWorkUnit (WorkUnit | null), displays title, description (first line), metadata (epic, estimate, status)", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 12, "text": "UnifiedBoardLayout renders hybrid: Text rows for borders (┌─┬─┐, ├─┼─┤, └─┴─┘), Box components for content between borders", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 13, "text": "Content components render content ONLY with │ characters for side borders (if needed), no top/bottom borders - those are rendered by UnifiedBoardLayout as separate Text rows", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 14, "text": "Column width calculation (lines 59-67) MUST be kept - used by buildBorderRow() for correct table border alignment and passed to StatusColumn for content width", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" } ], "estimate": 13, "questions": [ { "id": 0, "text": "@human: Should StatusColumn manage its own scroll state internally, or should scroll state be kept in UnifiedBoardLayout and passed down as props?", "selected": true, "answer": "Keep character-by-character chalk colors - existing shimmer animation works well and is already implemented (lines 114-165). Ink color props would require complete rewrite of shimmer logic.", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 1, "text": "@human: Should shimmer animation continue using character-by-character chalk colors, or use Ink color props?", "selected": true, "answer": "Calculate column width and pass to StatusColumn props - needed for proper alignment with table borders rendered by buildBorderRow(). Cannot rely on flex={1} alone because borders require exact widths.", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 2, "text": "@human: Should column width be calculated and passed to StatusColumn props, or let Ink flex={1} distribute space automatically?", "selected": true, "answer": "Keep selection state (focusedColumnIndex + selectedWorkUnitIndex) in UnifiedBoardLayout and pass isSelected boolean to WorkUnitCard. UnifiedBoardLayout needs central state to coordinate auto-scroll (lines 281-350) and keyboard navigation.", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 3, "text": "@human: Should work unit selection state (focusedColumnIndex + selectedWorkUnitIndex) remain in UnifiedBoardLayout, or pass isSelected boolean to each WorkUnitCard?", "selected": true, "answer": "YES - keep existing buildBorderRow() system and render borders as Text lines, with Box components BETWEEN the border rows. HYBRID APPROACH confirmed. This maintains the exact table borders (┌─┬─┐ ├─┼─┤ └─┴─┘) while allowing component-based content rendering.", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" }, { "id": 4, "text": "@human: Should we keep the existing buildBorderRow() system and render borders as Text lines, with Box components BETWEEN the border rows? Or do you want a completely different approach for borders with flexbox?", "selected": true, "answer": "YES - keep existing buildBorderRow() system and render borders as Text lines, with Box components BETWEEN the border rows. HYBRID APPROACH confirmed. This maintains the exact table borders (┌─┬─┐ ├─┼─┤ └─┴─┘) while allowing component-based content rendering.", "deleted": false, "createdAt": "2025-10-28T20:49:12.586Z" } ], "updated": "2025-10-28T22:22:27.144Z", "nextRuleId": 12, "nextExampleId": 15, "nextQuestionId": 5, "nextNoteId": 0 }, "ITF-006": { "id": "ITF-006", "title": "Replace Git Stashes with Checkpoint Component", "type": "story", "status": "done", "createdAt": "2025-10-28T22:30:11.734Z", "updatedAt": "2025-10-28T23:28:14.899Z", "description": "Remove Git Stashes component and replace with Checkpoint component that dynamically tracks checkpoint count using fs.watch and updates keybindings (S→C for checkpoints, C→F for changed files)", "children": [], "userStory": { "role": "developer using fspec TUI", "action": "see checkpoint count dynamically in the status bar", "benefit": "I know how many checkpoints are available for rollback" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T22:30:41.578Z" }, { "state": "testing", "timestamp": "2025-10-28T22:39:28.337Z" }, { "state": "implementing", "timestamp": "2025-10-28T22:41:35.780Z" }, { "state": "testing", "timestamp": "2025-10-28T22:51:42.422Z" }, { "state": "implementing", "timestamp": "2025-10-28T23:04:40.849Z" }, { "state": "testing", "timestamp": "2025-10-28T23:08:26.189Z" }, { "state": "implementing", "timestamp": "2025-10-28T23:10:53.704Z" }, { "state": "testing", "timestamp": "2025-10-28T23:12:17.984Z" }, { "state": "implementing", "timestamp": "2025-10-28T23:14:20.380Z" }, { "state": "validating", "timestamp": "2025-10-28T23:27:50.526Z" }, { "state": "done", "timestamp": "2025-10-28T23:28:14.899Z" } ], "rules": [ { "id": 0, "text": "Git Stashes component must be completely removed from TUI", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 1, "text": "Checkpoint component must replace Git Stashes in the same position", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 2, "text": "Checkpoint count must be tracked dynamically using fs.watch", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 3, "text": "Display format must be 'Checkpoints: None' (0), 'Checkpoints: 1' (1), 'Checkpoints: N' (N>1)", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 4, "text": "Keybinding 'S View Stashes' must change to 'C View Checkpoints'", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 5, "text": "Keybinding 'C View Changed Files' must change to 'F View Changed Files'", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 6, "text": "Checkpoints stored in two places: (1) Git refs at refs/fspec-checkpoints/{workUnitId}/{checkpointName}, (2) Index files at .git/fspec-checkpoints-index/{workUnitId}.json. For TUI watching, use chokidar to watch .git/fspec-checkpoints-index/ directory (cross-platform compatible, handles atomic operations like fs.rename). Example: chokidar.watch(path.join(cwd, '.git', 'fspec-checkpoints-index'), { ignoreInitial: true, persistent: false })", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 7, "text": "Checkpoints are git commit objects (in .git/objects/) referenced by git refs (refs/fspec-checkpoints/{workUnitId}/{checkpointName}). Index files are JSON at .git/fspec-checkpoints-index/{workUnitId}.json with format: {checkpoints: [{name, message}]}. To count: read all *.json files in index directory, parse each, sum checkpoint array lengths.", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 8, "text": "Count separately with labels. Display format: 'Manual: 2, Auto: 3'. When both are zero: 'Checkpoints: None'. When only one type exists, show both anyway for clarity (e.g., 'Manual: 0, Auto: 3' or 'Manual: 2, Auto: 0').", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 9, "text": "Real-time updates, no debouncing. Update checkpoint count immediately when chokidar detects changes in .git/fspec-checkpoints-index/ directory.", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 10, "text": "Show both auto (🤖) and manual (📌) checkpoints together in the list view when pressing 'C' key. Display them with their respective icons to distinguish between types.", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" } ], "examples": [ { "id": 0, "text": "TUI starts with no checkpoints, displays 'Checkpoints: None'", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 1, "text": "User creates one checkpoint via CLI, TUI automatically updates to 'Checkpoints: 1'", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 2, "text": "User creates second checkpoint, TUI updates to 'Checkpoints: 2'", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 3, "text": "User presses 'C' key, checkpoint list view opens (not stashes)", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 4, "text": "User presses 'F' key, changed files view opens", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 5, "text": "Checkpoint directory is watched with fs.watch, changes trigger count update automatically", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" } ], "questions": [ { "id": 0, "text": "@human: Where exactly are checkpoints stored? Is it .fspec/checkpoints/<work-unit-id>/ directory?", "selected": true, "answer": "Checkpoints stored in two places: (1) Git refs at refs/fspec-checkpoints/{workUnitId}/{checkpointName}, (2) Index files at .git/fspec-checkpoints-index/{workUnitId}.json. For TUI watching, use chokidar to watch .git/fspec-checkpoints-index/ directory (cross-platform compatible, handles atomic operations like fs.rename). Example: chokidar.watch(path.join(cwd, '.git', 'fspec-checkpoints-index'), { ignoreInitial: true, persistent: false })", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 1, "text": "@human: What file format are checkpoints? Individual JSON files, directories, or something else?", "selected": true, "answer": "Checkpoints are git commit objects (in .git/objects/) referenced by git refs (refs/fspec-checkpoints/{workUnitId}/{checkpointName}). Index files are JSON at .git/fspec-checkpoints-index/{workUnitId}.json with format: {checkpoints: [{name, message}]}. To count: read all *.json files in index directory, parse each, sum checkpoint array lengths.", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 2, "text": "@human: Should we count auto checkpoints (🤖) and manual checkpoints (📌) separately or together in the count?", "selected": true, "answer": "Count separately with labels. Display format: 'Manual: 2, Auto: 3'. When both are zero: 'Checkpoints: None'. When only one type exists, show both anyway for clarity (e.g., 'Manual: 0, Auto: 3' or 'Manual: 2, Auto: 0').", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 3, "text": "@human: Should checkpoint count update in real-time or with a debounce to avoid excessive updates?", "selected": true, "answer": "Real-time updates, no debouncing. Update checkpoint count immediately when chokidar detects changes in .git/fspec-checkpoints-index/ directory.", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" }, { "id": 4, "text": "@human: When pressing 'C' to view checkpoints, should we show both auto and manual checkpoints in the list?", "selected": true, "answer": "Show both auto (🤖) and manual (📌) checkpoints together in the list view when pressing 'C' key. Display them with their respective icons to distinguish between types.", "deleted": false, "createdAt": "2025-10-28T22:30:11.734Z" } ], "estimate": 5, "updated": "2025-10-28T23:28:14.899Z", "nextRuleId": 11, "nextExampleId": 6, "nextQuestionId": 5, "nextNoteId": 0 }, "ITF-007": { "id": "ITF-007", "title": "Fix stale tests and changed files watcher after ITF-006", "type": "bug", "status": "done", "createdAt": "2025-10-28T23:31:02.790Z", "updatedAt": "2025-10-28T23:45:29.163Z", "description": "After replacing Git Stashes with Checkpoints (ITF-006), 12 tests fail expecting old 'Git Stashes' text. Also, changed files panel shows stale counts (14 staged, 0 unstaged) after commit when it should show 0/0. Need to update tests to expect 'Checkpoints' and fix chokidar watcher to refresh file counts after git operations.", "epic": "interactive-tui-foundation", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-28T23:31:08.509Z" }, { "state": "testing", "timestamp": "2025-10-28T23:35:34.052Z" }, { "state": "implementing", "timestamp": "2025-10-28T23:36:22.132Z" }, { "state": "validating", "timestamp": "2025-10-28T23:44:22.885Z" }, { "state": "done", "timestamp": "2025-10-28T23:45:29.163Z" } ], "rules": [ { "id": 0, "text": "All tests expecting 'Git Stashes' text must be updated to expect 'Checkpoints' instead", "deleted": false, "createdAt": "2025-10-28T23:31:02.790Z" }, { "id": 1, "text": "Changed files watcher must refresh counts immediately after git commit operations", "deleted": false, "createdAt": "2025-10-28T23:31:02.790Z" }, { "id": 2, "text": "Failing tests: BoardView-git-watcher-fix (4), BoardView-interactive-kanban (2), BoardView-realtime-updates (2), BoardView-table-layout (2), BoardView-git-context-work-unit-details (1) - total 11 tests", "deleted": false, "createdAt": "2025-10-28T23:31:02.790Z" } ], "examples": [ { "id": 0, "text": "After git commit, changed files panel shows '14 staged, 0 unstaged' but should show '0 staged, 0 unstaged' (clean working directory)", "deleted": false, "createdAt": "2025-10-28T23:31:02.790Z" }, { "id": 1, "text": "Test expects 'Git Stashes (2)' but component now displays 'Checkpoints: X Manual, Y Auto'", "deleted": false, "createdAt": "2025-10-28T23:31:02.790Z" }, { "id": 2, "text": "Test expects keybinding 'S View Stashes' but panel now shows 'C View Checkpoints'", "deleted": false, "createdAt": "2025-10-28T23:31:02.790Z" } ], "userStory": { "role": "developer running tests", "action": "have all tests pass after ITF-006 checkpoint integration", "benefit": "I can verify the TUI works correctly with the new checkpoint system" }, "updated": "2025-10-28T23:45:29.163Z", "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "ITF-008": { "id": "ITF-008", "title": "Improve work unit details panel formatting", "type": "story", "status": "done", "createdAt": "2025-10-29T00:29:02.308Z", "updatedAt": "2025-10-29T00:45:01.629Z", "description": "Remove 'Work Unit Details' header line, expand description to 3 lines max with truncation indicator, and remove left padding from content lines", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T00:30:21.124Z" }, { "state": "testing", "timestamp": "2025-10-29T00:34:51.089Z" }, { "state": "implementing", "timestamp": "2025-10-29T00:37:18.487Z" }, { "state": "validating", "timestamp": "2025-10-29T00:40:44.849Z" }, { "state": "done", "timestamp": "2025-10-29T00:45:01.629Z" } ], "userStory": { "role": "developer using fspec TUI", "action": "view work unit details with better formatting", "benefit": "I can read descriptions more easily without visual clutter" }, "rules": [ { "id": 0, "text": "The 'Work Unit Details' header line MUST be removed from the panel", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 1, "text": "Description MUST display up to 3 lines maximum (not 1 line)", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 2, "text": "If description exceeds 3 lines, the third line MUST end with '...' to indicate truncation", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 3, "text": "Left padding (currently 2 spaces) MUST be removed from all content lines", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 4, "text": "Panel MUST remain static at 4 lines total height (existing BOARD-015 constraint)", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 5, "text": "Option A: Line 1 = ID+Title, Lines 2-3 = Description (max 2 lines), Line 4 = Metadata", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 6, "text": "With Option A layout, description uses lines 2-3 (max 2 lines), metadata always on line 4. If description has 3+ lines, truncate on line 3.", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 7, "text": "Truncation '...' should replace the last 3 characters of line 3 to fit within available width (standard truncation pattern)", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 8, "text": "Truncation '...' should replace the last 3 characters of line 3 to fit within available width (standard truncation pattern)", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" } ], "examples": [ { "id": 0, "text": "Work unit with short description (1 line): Shows ID, title on line 1, description on line 2, metadata on line 3, empty line 4. NO header line. NO left padding.", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 1, "text": "No work unit selected: Shows 'No work unit selected' centered on line 1, empty lines 2-4. NO header line.", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 2, "text": "Work unit with no description: Shows ID, title on line 1, empty line 2, metadata on line 3, empty line 4", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 3, "text": "Work unit with long description (5 lines): Line 1 = ID+Title, Line 2 = first desc line, Line 3 = second desc line ending with '...', Line 4 = Metadata", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 4, "text": "Work unit with exactly 2 lines of description: Line 1 = ID+Title, Line 2 = first desc line, Line 3 = second desc line (NO '...'), Line 4 = Metadata", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 5, "text": "Work unit with no description: Line 1 = ID+Title, Line 2 = empty, Line 3 = empty, Line 4 = Metadata", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" } ], "questions": [ { "id": 0, "text": "@human: For long descriptions, should the truncation '...' replace the last 3 characters of line 3, or be appended after available width?", "selected": true, "answer": "Truncation '...' should replace the last 3 characters of line 3 to fit within available width (standard truncation pattern)", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" }, { "id": 1, "text": "@human: What should the line layout be? Option A: [1: ID+Title, 2-3: Description, 4: Metadata] or Option B: [1: ID+Title, 2: Desc line 1, 3: Desc line 2, 4: Desc line 3 OR Metadata]?", "selected": true, "answer": "Option A: Line 1 = ID+Title, Lines 2-3 = Description (max 2 lines), Line 4 = Metadata", "deleted": false, "createdAt": "2025-10-29T00:29:02.308Z" } ], "estimate": 3, "updated": "2025-10-29T00:45:01.629Z", "nextRuleId": 9, "nextExampleId": 6, "nextQuestionId": 2, "nextNoteId": 0 }, "AGENT-018": { "id": "AGENT-018", "title": "Codex loads fspec prompt from user home directory", "type": "story", "status": "done", "createdAt": "2025-10-29T04:25:59.776Z", "updatedAt": "2025-10-29T07:33:12.903Z", "description": "Codex should copy fspec.md into the user's ~/.codex/prompts directory using a cross-platform home directory lookup", "children": [], "userStory": { "role": "Codex CLI maintainer", "action": "ensure fspec prompt files install into the global Codex prompts directory", "benefit": "Codex can load fspec guidance without relying on project-level prompt folders" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T04:26:31.759Z" }, { "state": "testing", "timestamp": "2025-10-29T04:41:53.257Z" }, { "state": "implementing", "timestamp": "2025-10-29T04:51:42.455Z" }, { "state": "specifying", "timestamp": "2025-10-29T05:03:17.092Z" }, { "state": "testing", "timestamp": "2025-10-29T05:04:47.532Z" }, { "state": "implementing", "timestamp": "2025-10-29T05:07:44.213Z" }, { "state": "validating", "timestamp": "2025-10-29T07:32:00.289Z" }, { "state": "done", "timestamp": "2025-10-29T07:33:12.904Z" } ], "rules": [ { "id": 0, "text": "fspec.md must be copied into the user's global ~/.codex/prompts directory rather than the project-level .codex/prompts", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" }, { "id": 1, "text": "Home directory resolution must use a cross-platform API (e.g., Node os.homedir()) instead of hard-coded paths or environment assumptions", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" }, { "id": 2, "text": "If ~/.codex/prompts does not exist it must be created before copying fspec.md", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" }, { "id": 3, "text": "The fspec prompt auto-generation routine must write fspec.md directly into the resolved ~/.codex/prompts directory", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" }, { "id": 4, "text": "No changes to existing project-level prompt; fspec init only needs to generate the home-directory copy.", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" }, { "id": 5, "text": "Codex prompt documentation must instruct agents to run /prompts:fspec instead of /fspec", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" } ], "examples": [ { "id": 0, "text": "Given a Linux user with HOME=/home/sam, running the Codex fspec prompt setup copies ./.codex/prompts/fspec.md to /home/sam/.codex/prompts/fspec.md", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" }, { "id": 1, "text": "Given a Windows user with USERPROFILE=C:\\Users\\Riley, the setup writes fspec.md to C:\\Users\\Riley\\.codex\\prompts\\fspec.md by resolving the home directory rather than hard-coding ~", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" }, { "id": 2, "text": "When fspec init --agent=codex completes, the generated instructions tell the user to run /prompts:fspec rather than /fspec", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" } ], "questions": [ { "id": 0, "text": "@human: Should we delete the project-level .codex/prompts/fspec.md after copying to the user directory, or keep it for backward compatibility?", "selected": true, "answer": "No changes to existing project-level prompt; fspec init only needs to generate the home-directory copy.", "deleted": false, "createdAt": "2025-10-29T04:25:59.776Z" } ], "assumptions": [ "Codex has write permissions to create ~/.codex/prompts in the user's home directory" ], "estimate": 3, "updated": "2025-10-29T07:33:12.903Z", "nextRuleId": 6, "nextExampleId": 3, "nextQuestionId": 1, "nextNoteId": 0 }, "BUG-048": { "id": "BUG-048", "title": "ULTRATHINK discovery reminders failing tests", "type": "bug", "status": "done", "createdAt": "2025-10-29T05:21:57.290Z", "updatedAt": "2025-10-29T06:37:31.102Z", "description": "draft-driven-discovery-feedback-loop.test.ts scenarios expecting ULTRATHINK messaging need review and code update; full vitest run also hits loadStashes spy restore error", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T05:36:46.675Z" }, { "state": "testing", "timestamp": "2025-10-29T06:03:06.554Z" }, { "state": "implementing", "timestamp": "2025-10-29T06:04:54.372Z" }, { "state": "validating", "timestamp": "2025-10-29T06:11:53.084Z" }, { "state": "done", "timestamp": "2025-10-29T06:37:31.102Z" } ], "rules": [ { "id": 0, "text": "Only agents with supportsMetaCognition true (currently Claude) should display ULTRATHINK terminology in discovery system-reminders", "deleted": false, "createdAt": "2025-10-29T05:21:57.290Z" }, { "id": 1, "text": "Legacy ULTRATHINK scenarios should execute under FSPEC_AGENT=claude so conditional messaging remains valid", "deleted": false, "createdAt": "2025-10-29T05:21:57.290Z" }, { "id": 2, "text": "Cursor reminders should use its strongest supported phrasing 'think a lot' when prompting deep analysis", "deleted": false, "createdAt": "2025-10-29T05:21:57.290Z" }, { "id": 3, "text": "Run those scenarios with FSPEC_AGENT=claude so ULTRATHINK expectations stay valid.", "deleted": false, "createdAt": "2025-10-29T05:21:57.290Z" }, { "id": 4, "text": "All non-Claude agents (including Cursor) must use the phrase 'think a lot' instead of ULTRATHINK in discovery reminders", "deleted": false, "createdAt": "2025-10-29T05:21:57.290Z" } ], "examples": [ { "id": 0, "text": "When no agent is detected (default), discover-foundation should emit generic analysis guidance without the word 'ULTRATHINK'", "deleted": false, "createdAt": "2025-10-29T05:21:57.290Z" }, { "id": 1, "text": "Each supported agent (claude, cursor, aider, default) has a dedicated test verifying the expected reminder phrasing", "deleted": false, "createdAt": "2025-10-29T05:21:57.290Z" } ], "questions": [ { "id": 0, "text": "@human: Should legacy scenarios that expect ULTRATHINK be updated to run under a Claude context, or should they change expectations to generic guidance?", "selected": true, "answer": "Run those scenarios with FSPEC_AGENT=claude so ULTRATHINK expectations stay valid.", "deleted": false, "createdAt": "2025-10-29T05:21:57.290Z" } ], "updated": "2025-10-29T06:37:31.102Z", "nextRuleId": 5, "nextExampleId": 2, "nextQuestionId": 1, "nextNoteId": 0 }, "CLEAN-002": { "id": "CLEAN-002", "title": "Resolve outstanding ESLint violations", "type": "task", "status": "backlog", "createdAt": "2025-10-29T06:36:51.817Z", "updatedAt": "2025-10-29T06:36:51.817Z", "description": "Track cleanup of existing warnings/errors reported by npm run lint (unused variables, unexpected any, global references, etc.).", "children": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-049": { "id": "BUG-049", "title": "show-coverage crashes with undefined coveragePercent", "type": "bug", "status": "done", "createdAt": "2025-10-29T07:34:51.779Z", "updatedAt": "2025-10-29T07:40:42.522Z", "description": "Running 'fspec show-coverage codex-init-writes-prompt-to-home-directory' throws TypeError: Cannot read properties of undefined (reading 'coveragePercent'). The coverage file exists and has valid structure with scenarios and mappings, but the stats object appears to be missing or undefined.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T07:35:28.898Z" }, { "state": "testing", "timestamp": "2025-10-29T07:37:31.652Z" }, { "state": "implementing", "timestamp": "2025-10-29T07:38:33.873Z" }, { "state": "validating", "timestamp": "2025-10-29T07:39:17.289Z" }, { "state": "done", "timestamp": "2025-10-29T07:40:42.523Z" } ], "rules": [ { "id": 0, "text": "show-coverage must handle coverage files missing stats object gracefully without crashing", "deleted": false, "createdAt": "2025-10-29T07:34:51.779Z" }, { "id": 1, "text": "When stats object is missing, show-coverage should calculate stats from scenarios array before displaying coverage", "deleted": false, "createdAt": "2025-10-29T07:34:51.779Z" }, { "id": 2, "text": "Calculated stats must match CoverageStats interface: totalScenarios, coveredScenarios, coveragePercent, testFiles, implFiles, totalLinesCovered", "deleted": false, "createdAt": "2025-10-29T07:34:51.779Z" } ], "examples": [ { "id": 0, "text": "Given coverage file with 4 scenarios (all with testMappings), when stats missing, show-coverage calculates coveragePercent as 100%", "deleted": false, "createdAt": "2025-10-29T07:34:51.779Z" }, { "id": 1, "text": "Given coverage file with 2 scenarios (1 with testMappings, 1 without), when stats missing, show-coverage calculates coveragePercent as 50%", "deleted": false, "createdAt": "2025-10-29T07:34:51.779Z" }, { "id": 2, "text": "Given coverage file with scenarios array but no stats, show-coverage extracts unique test files and impl files for stats.testFiles and stats.implFiles arrays", "deleted": false, "createdAt": "2025-10-29T07:34:51.779Z" } ], "userStory": { "role": "developer using fspec show-coverage", "action": "view coverage statistics for features with legacy coverage files missing stats object", "benefit": "the command works reliably without crashing on older coverage file formats" }, "updated": "2025-10-29T07:40:42.522Z", "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "GIT-006": { "id": "GIT-006", "title": "Pure flexbox layout for checkpoint and changed files viewers", "type": "story", "status": "done", "createdAt": "2025-10-29T08:58:53.999Z", "updatedAt": "2025-10-29T09:44:08.082Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T09:01:05.781Z" }, { "state": "testing", "timestamp": "2025-10-29T09:25:13.789Z" }, { "state": "implementing", "timestamp": "2025-10-29T09:28:17.081Z" }, { "state": "validating", "timestamp": "2025-10-29T09:42:29.894Z" }, { "state": "done", "timestamp": "2025-10-29T09:44:08.083Z" } ], "userStory": { "role": "developer using checkpoint/changed files viewers", "action": "have all layout use pure flexbox without any hardcoded dimensions", "benefit": "views resize properly and work correctly on any terminal size" }, "rules": [ { "id": 0, "text": "No percentage-based widths or heights (e.g., no width='30%', no height='100%')", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 1, "text": "Use flexGrow exclusively for dynamic sizing", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 2, "text": "Fixed widths must be character-based minimums only (e.g., 30 characters for file list)", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 3, "text": "VirtualList height prop must be optional, calculate from useTerminalSize if not provided", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 4, "text": "ChangedFilesViewer must load actual git diffs using getFileDiff function (not mock data)", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 5, "text": "Show loading state while diff is being fetched to prevent flickering", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 6, "text": "No, VirtualList should NOT accept height prop at all. It must be pure flexbox - use flexGrow to fill container completely and calculate visible items from useTerminalSize internally.", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 7, "text": "File list should use flexbox proportional sizing (e.g., flexBasis with flexGrow/flexShrink) to take approximately 1/4 of container width, with 30 characters as minimum. Use minWidth for character minimum.", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 8, "text": "CheckpointViewer diff view must also load REAL git diffs from checkpoint stash data, not placeholder text.", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" } ], "questions": [ { "id": 0, "text": "@human: Should VirtualList still accept an explicit height prop for cases where the parent wants to control it?", "selected": true, "answer": "No, VirtualList should NOT accept height prop at all. It must be pure flexbox - use flexGrow to fill container completely and calculate visible items from useTerminalSize internally.", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 1, "text": "@human: Should the file list width be exactly 30 characters, or is that just a minimum with flexShrink?", "selected": true, "answer": "File list should use flexbox proportional sizing (e.g., flexBasis with flexGrow/flexShrink) to take approximately 1/4 of container width, with 30 characters as minimum. Use minWidth for character minimum.", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 2, "text": "@human: Does the diff view in CheckpointViewer also need real git diff loading, or can it stay as placeholder for now?", "selected": true, "answer": "CheckpointViewer diff view must also load REAL git diffs from checkpoint stash data, not placeholder text.", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" } ], "examples": [ { "id": 0, "text": "VirtualList with 100 items in 80x24 terminal: renders with flexGrow=1, calculates visibleHeight from terminalHeight, shows only items that fit", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 1, "text": "CheckpointViewer in 120 column terminal: file list takes ~30 columns (1/4 with minWidth=30), diff pane takes remaining ~90 columns with flexGrow=1", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 2, "text": "ChangedFilesViewer selects 'src/auth.ts': shows 'Loading diff...' immediately, then displays real git diff with +/- lines from getFileDiff()", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" }, { "id": 3, "text": "Terminal resizes from 80x24 to 120x40: all components adjust automatically using flexbox, no re-render glitches", "deleted": false, "createdAt": "2025-10-29T08:58:53.999Z" } ], "estimate": 5, "updated": "2025-10-29T09:44:08.082Z", "nextRuleId": 9, "nextExampleId": 4, "nextQuestionId": 3, "nextNoteId": 0 }, "GIT-007": { "id": "GIT-007", "title": "Diff loading system has rendering bugs and performance issues", "type": "bug", "status": "done", "createdAt": "2025-10-29T09:56:03.859Z", "updatedAt": "2025-10-29T10:03:03.309Z", "description": "ChangedFilesViewer diff loading causes flickering, shows wrong files, and hangs UX. Need to refactor with proper dependency management, loading states, and potentially worker threads for git operations.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T09:56:13.407Z" }, { "state": "testing", "timestamp": "2025-10-29T10:00:06.607Z" }, { "state": "implementing", "timestamp": "2025-10-29T10:01:08.707Z" }, { "state": "validating", "timestamp": "2025-10-29T10:02:56.740Z" }, { "state": "done", "timestamp": "2025-10-29T10:03:03.309Z" } ], "rules": [ { "id": 0, "text": "useEffect dependency on selectedFile object causes infinite re-renders because allFiles array is recreated on every render with new object instances", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" }, { "id": 1, "text": "Race conditions: multiple getFileDiff calls can run simultaneously when user navigates quickly, last one to complete wins but might show wrong file's diff", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" }, { "id": 2, "text": "Git operations (isomorphic-git file I/O) run on main thread blocking React rendering and causing UX hangs", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" }, { "id": 3, "text": "No debouncing: every arrow key press triggers immediate diff load, should debounce rapid file navigation", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" }, { "id": 4, "text": "FIX: useEffect should depend on selectedFileIndex and derive file path, not selectedFile object", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" }, { "id": 5, "text": "FIX: Implement AbortController or cancellation token to cancel previous diff loads when selection changes", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" }, { "id": 6, "text": "FIX: Consider worker threads (worker_threads module) to offload git diff operations from main thread", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" } ], "examples": [ { "id": 0, "text": "User navigates to file1.ts, sees diff loading, presses down arrow to file2.ts immediately - both diffs load simultaneously, file1.ts diff might display even though file2.ts is selected", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" }, { "id": 1, "text": "User opens ChangedFilesViewer with 10 files - diff pane flickers constantly showing 'Loading diff...' over and over because useEffect runs on every render", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" }, { "id": 2, "text": "SOLUTION: useEffect depends on [selectedFileIndex, stagedFiles, unstagedFiles, cwd], AbortController cancels previous loads, diff loads once per file selection without flicker", "deleted": false, "createdAt": "2025-10-29T09:56:03.859Z" } ], "userStory": { "role": "developer using diff viewer", "action": "see accurate, non-flickering diffs without UX lag", "benefit": "I can efficiently review code changes" }, "estimate": 5, "updated": "2025-10-29T10:03:03.309Z", "nextRuleId": 7, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "GIT-008": { "id": "GIT-008", "title": "Enhanced line-by-line diff with background colors", "type": "story", "status": "done", "createdAt": "2025-10-29T10:48:19.229Z", "updatedAt": "2025-10-29T10:58:32.876Z", "description": "Implement visual diff with red background for removed lines and green background for added lines, pairing consecutive changes as replacements", "children": [], "userStory": { "role": "developer reviewing changes", "action": "see line-by-line diffs with clear background colors showing replacements, additions, and deletions", "benefit": "I can quickly understand what changed without parsing diff symbols" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T10:49:09.122Z" }, { "state": "testing", "timestamp": "2025-10-29T10:50:52.895Z" }, { "state": "implementing", "timestamp": "2025-10-29T10:51:51.616Z" }, { "state": "validating", "timestamp": "2025-10-29T10:53:52.411Z" }, { "state": "done", "timestamp": "2025-10-29T10:58:32.877Z" } ], "rules": [ { "id": 0, "text": "Replaced lines (old version) display with RED background and WHITE text", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 1, "text": "Replaced lines (new version) display with GREEN background and WHITE text", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 2, "text": "Pure deletions (no matching addition) display with RED background and WHITE text", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 3, "text": "Pure additions (no matching deletion) display with GREEN background and WHITE text", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 4, "text": "Context lines (unchanged) display with default styling (no background color)", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 5, "text": "Hunk headers (@@ lines) display with CYAN text", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 6, "text": "Consecutive - lines followed by consecutive + lines are paired as replacements", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 7, "text": "Unpaired - lines (not followed by + lines) are pure deletions", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 8, "text": "Unpaired + lines (not preceded by - lines) are pure additions", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" } ], "examples": [ { "id": 0, "text": "Simple replacement: '-const y = 2;' followed by '+const y = 3;' displays with red bg (old) and green bg (new)", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 1, "text": "Multi-line replacement: 3 consecutive - lines followed by 3 consecutive + lines all paired with matching colors", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 2, "text": "Pure addition: '+const y = 2;' with no preceding - line shows only green background", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 3, "text": "Pure deletion: '-const y = 2;' with no following + line shows only red background", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 4, "text": "Mixed changes: replacement pair (red+green), then pure addition (green only), then pure deletion (red only)", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 5, "text": "Unbalanced many-to-one: 3 - lines followed by 1 + line, all displayed as a grouped replacement", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" }, { "id": 6, "text": "Unbalanced one-to-many: 1 - line followed by 3 + lines, all displayed as a grouped replacement", "deleted": false, "createdAt": "2025-10-29T10:48:19.229Z" } ], "estimate": 5, "updated": "2025-10-29T10:58:32.876Z", "nextRuleId": 9, "nextExampleId": 7, "nextQuestionId": 0, "nextNoteId": 0 }, "BUG-050": { "id": "BUG-050", "title": "Diff display not showing line-by-line changes properly", "type": "bug", "status": "done", "createdAt": "2025-10-29T11:01:14.558Z", "updatedAt": "2025-10-29T11:20:26.544Z", "description": "The ChangedFilesViewer is using the 'diff' library but it doesn't properly show line-by-line changes. When there's only 1 line difference in a file, it shows many unrelated lines as changed instead of just the actual changed line.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T11:02:19.472Z" }, { "state": "testing", "timestamp": "2025-10-29T11:05:12.776Z" }, { "state": "implementing", "timestamp": "2025-10-29T11:05:28.763Z" }, { "state": "validating", "timestamp": "2025-10-29T11:06:28.461Z" }, { "state": "done", "timestamp": "2025-10-29T11:20:26.544Z" } ], "rules": [ { "id": 0, "text": "Diff viewer must show only the lines that actually changed, not entire blocks", "deleted": false, "createdAt": "2025-10-29T11:01:14.558Z" }, { "id": 1, "text": "When comparing package.json with structural changes, show line-by-line differences not block-level differences", "deleted": false, "createdAt": "2025-10-29T11:01:14.558Z" }, { "id": 2, "text": "Context lines (unchanged) should be clearly separated from changed lines", "deleted": false, "createdAt": "2025-10-29T11:01:14.558Z" } ], "examples": [ { "id": 0, "text": "User changes 'typescript': '^5.9.2' to 'vite': '^7.1.5' in package.json devDependencies. Diff should show ONLY the 2 changed lines (old removed, new added), not the entire devDependencies block", "deleted": false, "createdAt": "2025-10-29T11:01:14.558Z" }, { "id": 1, "text": "Currently showing: many lines with '-' prefix (prettier, typescript, vite, vitest, lint-staged) followed by many lines with '+' prefix (execa, immer, ink, etc.). This makes it look like all lines changed when only 1 line did", "deleted": false, "createdAt": "2025-10-29T11:01:14.558Z" }, { "id": 2, "text": "Expected: Show only the actual line that changed with proper context (e.g., 3 lines before and after)", "deleted": false, "createdAt": "2025-10-29T11:01:14.558Z" } ], "questions": [ { "id": 0, "text": "@human: Should we use a proper diff algorithm (like Myers algorithm from 'diff' library) to replace the naive line-by-line comparison in generateUnifiedDiff()?", "selected": true, "answer": "Yes, we should use the Myers algorithm from the 'diff' library (already imported in diff-parser.ts) to replace the naive comparison in generateUnifiedDiff(). The diff library's diffLines() function properly aligns lines and detects insertions, deletions, and unchanged blocks.", "deleted": false, "createdAt": "2025-10-29T11:01:14.558Z" } ], "userStory": { "role": "developer reviewing code changes", "action": "see only the lines that actually changed in diffs", "benefit": "I can quickly understand what was modified without being confused by unrelated lines" }, "estimate": 3, "updated": "2025-10-29T11:20:26.544Z", "nextRuleId": 3, "nextExampleId": 3, "nextQuestionId": 1, "nextNoteId": 0 }, "TUI-001": { "id": "TUI-001", "title": "Mouse scroll wheel and trackpad support for VirtualList", "type": "story", "status": "done", "createdAt": "2025-10-29T11:24:57.029Z", "updatedAt": "2025-10-29T12:22:43.047Z", "description": "Add mouse scroll wheel and trackpad scrolling support to ALL VirtualList instances in the TUI application using Ink's useInput hook and mouse event handling. Support both scroll up/down and ensure proper throttling for performance.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T11:25:03.887Z" }, { "state": "testing", "timestamp": "2025-10-29T11:30:34.722Z" }, { "state": "implementing", "timestamp": "2025-10-29T11:33:34.647Z" }, { "state": "validating", "timestamp": "2025-10-29T11:38:10.889Z" }, { "state": "done", "timestamp": "2025-10-29T12:22:43.047Z" } ], "userStory": { "role": "developer using fspec TUI", "action": "scroll through lists using mouse wheel or trackpad", "benefit": "I can navigate more efficiently without relying on keyboard arrow keys" }, "rules": [ { "id": 0, "text": "Mouse scroll events detected via useInput hook checking key.mouse.button === 'none' for scroll actions", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 1, "text": "Scroll events MUST be throttled to prevent performance degradation from high-frequency events", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 2, "text": "All VirtualList instances in the application MUST support mouse scrolling consistently", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 3, "text": "Terminal must have mouse tracking enabled for scroll events to work", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 4, "text": "Traditional scrolling behavior: scroll wheel down moves viewport down (shows items below), scroll wheel up moves viewport up (shows items above)", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 5, "text": "Use 100ms throttle interval for scroll events", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 6, "text": "Scroll events only handled when pane containing VirtualList has focus", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 7, "text": "Vertical scrolling only - no horizontal scrolling support needed", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" } ], "examples": [ { "id": 0, "text": "User scrolls down with mouse wheel in Kanban board file list → selected item moves down one item", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 1, "text": "User scrolls up with mouse wheel in CheckpointViewer file list → selected item moves up one item", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 2, "text": "User scrolls with trackpad (two-finger gesture) on Mac → behaves identically to mouse wheel scroll", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 3, "text": "User rapidly scrolls mouse wheel → throttled events prevent UI lag and maintain smooth navigation", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" } ], "questions": [ { "id": 0, "text": "@human: Should scroll wheel down move selection down (natural scrolling) or scroll the viewport down showing items above (traditional scrolling)?", "selected": true, "answer": "Traditional scrolling: scroll wheel down shows items below, scroll wheel up shows items above", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 1, "text": "@human: What throttle interval should be used for scroll events? (e.g., 50ms, 100ms, 150ms)", "selected": true, "answer": "100ms throttle interval (appropriate balance between responsiveness and performance)", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 2, "text": "@human: Should scrolling work when ANY pane is active, or only when specific panes (like file list) have focus?", "selected": true, "answer": "Scrolling works when ANY pane that has VirtualList is focused", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" }, { "id": 3, "text": "@human: Should holding Shift+ScrollWheel enable horizontal scrolling, or is vertical-only sufficient?", "selected": true, "answer": "Vertical scrolling only - no horizontal scrolling needed", "deleted": false, "createdAt": "2025-10-29T11:24:57.029Z" } ], "estimate": 5, "updated": "2025-10-29T12:22:43.047Z", "nextRuleId": 8, "nextExampleId": 4, "nextQuestionId": 4, "nextNoteId": 0 }, "TUI-002": { "id": "TUI-002", "title": "Checkpoint Viewer Three-Pane Layout", "type": "story", "status": "done", "createdAt": "2025-10-29T12:33:28.912Z", "updatedAt": "2025-10-29T21:16:52.799Z", "description": "Implement three-pane checkpoint viewer with checkpoint list (top-left), files list (bottom-left), and diff view (right), organized by time with most recent checkpoints first", "children": [], "userStory": { "role": "developer using fspec", "action": "view and navigate checkpoints with their files and diffs", "benefit": "I can review checkpoint history and restore previous states efficiently" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T12:33:50.314Z" }, { "state": "testing", "timestamp": "2025-10-29T20:53:01.128Z" }, { "state": "implementing", "timestamp": "2025-10-29T20:56:56.356Z" }, { "state": "validating", "timestamp": "2025-10-29T21:06:28.489Z" }, { "state": "done", "timestamp": "2025-10-29T21:10:12.478Z" }, { "state": "specifying", "timestamp": "2025-10-29T21:14:01.904Z" }, { "state": "testing", "timestamp": "2025-10-29T21:16:01.967Z" }, { "state": "implementing", "timestamp": "2025-10-29T21:16:26.680Z" }, { "state": "validating", "timestamp": "2025-10-29T21:16:28.090Z" }, { "state": "done", "timestamp": "2025-10-29T21:16:52.799Z" } ], "rules": [ { "id": 0, "text": "Checkpoint viewer must have three panes: checkpoint list (top-left), file list (bottom-left), and diff view (right)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 1, "text": "Checkpoints must be organized by time with most recent first", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 2, "text": "Left side has two vertically stacked panes (checkpoints above, files below)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 3, "text": "Selecting a checkpoint updates the file list to show that checkpoint's files", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 4, "text": "Selecting a file shows its diff in the right pane", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 5, "text": "Yes - show timestamp, work unit ID, and number of files in checkpoint list", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 6, "text": "Tab key cycles through all three panes (checkpoints -> files -> diff -> checkpoints)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 7, "text": "Load actual git diffs using worker threads (same as ChangedFilesViewer) - no mocks!", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 8, "text": "Display appropriate message when checkpoint has no files", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 9, "text": "Yes - reuse VirtualList with scroll acceleration and mouse wheel support (DRY principle)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 10, "text": "Use flexbox layout matching ChangedFilesViewer - NO PERCENTAGES! Use flexBasis, flexGrow, flexShrink, minWidth", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 11, "text": "Must reuse shared diff-loading utilities from ChangedFilesViewer (DRY principle)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 12, "text": "Must reuse VirtualList component for all three panes (checkpoints, files, diff)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 13, "text": "Checkpoint list must display: name, timestamp, work unit ID, and file count", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 14, "text": "ESC key exits checkpoint viewer and returns to previous view", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 15, "text": "CRITICAL: Extract file list and diff viewer into a shared reusable component (FileDiffViewer) to avoid duplication between ChangedFilesViewer and CheckpointViewer", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 16, "text": "ChangedFilesViewer must be refactored to use the new shared FileDiffViewer component", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 17, "text": "CheckpointViewer should render checkpoint list on left (top-left pane only) and FileDiffViewer component fills the right side (which internally handles file list + diff as dual-pane)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 18, "text": "CheckpointViewer must NOT render its own file list pane - FileDiffViewer already has a file list pane built-in", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" } ], "questions": [ { "id": 0, "text": "@human: Should the checkpoint list show any metadata besides the checkpoint name (e.g., timestamp, work unit ID, number of files)?", "selected": true, "answer": "Yes - show timestamp, work unit ID, and number of files in checkpoint list", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 1, "text": "@human: How should keyboard navigation work between the three panes (Tab to cycle through all three, or something else)?", "selected": true, "answer": "Tab key cycles through all three panes (checkpoints -> files -> diff -> checkpoints)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 2, "text": "@human: Should we load actual git diffs like ChangedFilesViewer does (using worker threads), or is mock data acceptable initially?", "selected": true, "answer": "Load actual git diffs using worker threads (same as ChangedFilesViewer) - no mocks!", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 3, "text": "@human: What should happen when a checkpoint has no files (empty state)?", "selected": true, "answer": "Display appropriate message when checkpoint has no files", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 4, "text": "@human: Should we support the same scroll acceleration and mouse wheel support that VirtualList has?", "selected": true, "answer": "Yes - reuse VirtualList with scroll acceleration and mouse wheel support (DRY principle)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 5, "text": "@human: Should the pane sizes be fixed or adjustable (like 30% top-left, 30% bottom-left, 40% right)?", "selected": true, "answer": "Use flexbox layout matching ChangedFilesViewer - NO PERCENTAGES! Use flexBasis, flexGrow, flexShrink, minWidth", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" } ], "examples": [ { "id": 0, "text": "User opens checkpoint viewer with 5 checkpoints, sees most recent checkpoint selected by default with timestamp and file count", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 1, "text": "User navigates down in checkpoint list using arrow keys, file list updates to show files for newly selected checkpoint", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 2, "text": "User presses Tab to switch focus from checkpoint list to file list, border color changes to indicate active pane", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 3, "text": "User selects a file in file list, diff pane loads and displays git diff using worker thread (same as ChangedFilesViewer)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 4, "text": "User presses Tab again to focus diff pane, can scroll through diff with arrow keys and PgUp/PgDn", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 5, "text": "User encounters checkpoint with no files, sees 'No files in this checkpoint' message in file list pane", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 6, "text": "User scrolls rapidly in checkpoint list using mouse wheel, scroll acceleration kicks in for smooth navigation", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 7, "text": "Refactor ChangedFilesViewer to use new shared FileDiffViewer component (file list + diff pane logic extracted)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 8, "text": "CheckpointViewer uses shared FileDiffViewer component, adds checkpoint list pane on top-left", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 9, "text": "When baseline checkpoint is selected, FileDiffViewer shows the files from that checkpoint (src/auth.ts, src/login.ts) in its left pane and diff in its right pane", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" } ], "architectureNotes": [ { "id": 0, "text": "Reuse existing diff utilities: src/git/diff-worker.ts (worker thread), src/git/diff-parser.ts (parsing), src/git/diff.ts (git commands)", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" }, { "id": 1, "text": "Create shared FileDiffViewer component (file list pane + diff pane) to be used by both ChangedFilesViewer and CheckpointViewer - eliminates code duplication", "deleted": false, "createdAt": "2025-10-29T12:33:28.912Z" } ], "estimate": 8, "updated": "2025-10-29T21:16:52.799Z", "nextRuleId": 19, "nextExampleId": 10, "nextQuestionId": 6, "nextNoteId": 2 }, "TUI-004": { "id": "TUI-004", "title": "Fix three-pane layout with proper flex properties", "type": "story", "status": "done", "createdAt": "2025-10-29T21:21:50.157Z", "updatedAt": "2025-10-29T21:42:38.201Z", "description": "The CheckpointViewer should have 3 panes total: (1) Checkpoints list at top-left, (2) Changed files list at bottom-left (both with same width restrictions as FilesView using minWidth and flex properties), (3) Diff viewer on the right. Use minWidth, flexBasis, flexGrow, flexShrink - NO PERCENTAGES!", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T21:22:27.952Z" }, { "state": "testing", "timestamp": "2025-10-29T21:29:07.069Z" }, { "state": "implementing", "timestamp": "2025-10-29T21:31:21.019Z" }, { "state": "validating", "timestamp": "2025-10-29T21:34:37.942Z" }, { "state": "done", "timestamp": "2025-10-29T21:42:38.201Z" } ], "userStory": { "role": "developer using the CheckpointViewer", "action": "view checkpoints, changed files, and diffs in a three-pane layout", "benefit": "I can efficiently navigate through checkpoint data with proper flex-based responsive layout" }, "rules": [ { "id": 0, "text": "The CheckpointViewer must have exactly 3 panes: checkpoint list (top-left), file list (bottom-left), diff viewer (right)", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 1, "text": "The two left panes (checkpoint list and file list) must use the same width properties as FileDiffViewer: minWidth, flexBasis, flexGrow, flexShrink - NO percentages", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 2, "text": "The checkpoint list and file list must be stacked vertically on the left side, with both panes using flexGrow to split the vertical space", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 3, "text": "The diff viewer pane on the right must use flexGrow to fill remaining horizontal space", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 4, "text": "Both panes use flexGrow={1} to split the vertical space equally (50/50), matching the horizontal behavior of FileDiffViewer", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 5, "text": "Use EXACTLY the same values as FileDiffViewer: minWidth={30}, flexBasis='25%', flexShrink={1} for the left column container", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" } ], "examples": [ { "id": 0, "text": "When user opens CheckpointViewer, they see checkpoint list at top-left (30 char minWidth), file list at bottom-left (30 char minWidth), and diff viewer on right (grows to fill space)", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 1, "text": "When terminal is narrow (80 chars), left panes respect 30 char minimum width, diff pane shrinks but remains visible", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 2, "text": "When terminal is wide (200 chars), left panes maintain proportional width using flexBasis and flexGrow (no percentage values), diff pane expands to use remaining space", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" } ], "questions": [ { "id": 0, "text": "@human: Should the checkpoint list and file list panes split the left side 50/50 vertically, or should one be weighted larger?", "selected": true, "answer": "Both panes use flexGrow={1} to split the vertical space equally (50/50), matching the horizontal behavior of FileDiffViewer", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 1, "text": "@human: What specific flexBasis and flexGrow values should the left panes use? Should they match FileDiffViewer's values exactly (minWidth=30, flexBasis='25%', flexShrink=1) or use different values without percentages?", "selected": true, "answer": "Use EXACTLY the same values as FileDiffViewer: minWidth={30}, flexBasis='25%', flexShrink={1} for the left column container", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" }, { "id": 2, "text": "@human: The current FileDiffViewer uses flexBasis='25%' which IS a percentage. Should I remove percentages from FileDiffViewer too, or just ensure CheckpointViewer matches whatever FileDiffViewer uses?", "selected": true, "answer": "Keep FileDiffViewer as-is with flexBasis='25%'. The work unit description saying 'NO PERCENTAGES' was incorrect - we should match FileDiffViewer exactly, which does use a percentage", "deleted": false, "createdAt": "2025-10-29T21:21:50.157Z" } ], "assumptions": [ "Keep FileDiffViewer as-is with flexBasis='25%'. The work unit description saying 'NO PERCENTAGES' was incorrect - we should match FileDiffViewer exactly, which does use a percentage" ], "estimate": 3, "updated": "2025-10-29T21:42:38.201Z", "nextRuleId": 6, "nextExampleId": 3, "nextQuestionId": 3, "nextNoteId": 0 }, "TUI-005": { "id": "TUI-005", "title": "Checkpoint Viewer loads actual checkpoint data", "type": "story", "status": "done", "createdAt": "2025-10-29T21:52:06.500Z", "updatedAt": "2025-10-29T21:55:51.386Z", "description": "The CheckpointViewer component should load actual checkpoints from the git checkpoint system instead of using stub data. The top-left pane lists all checkpoints, the bottom-left pane lists files in the selected checkpoint, and the right pane shows diffs between checkpoint files and HEAD.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T21:52:25.343Z" }, { "state": "testing", "timestamp": "2025-10-29T21:55:22.686Z" }, { "state": "implementing", "timestamp": "2025-10-29T21:55:30.785Z" }, { "state": "validating", "timestamp": "2025-10-29T21:55:37.436Z" }, { "state": "done", "timestamp": "2025-10-29T21:55:51.387Z" } ], "userStory": { "role": "developer viewing checkpoint data", "action": "see actual checkpoints with their files and diffs", "benefit": "I can inspect real checkpoint state instead of stub data" }, "rules": [ { "id": 0, "text": "Checkpoint list must load from .git/fspec-checkpoints-index/ directory", "deleted": false, "createdAt": "2025-10-29T21:52:06.500Z" }, { "id": 1, "text": "File list must be loaded using git.listFiles() with checkpoint OID", "deleted": false, "createdAt": "2025-10-29T21:52:06.500Z" }, { "id": 2, "text": "Diff pane must compare checkpoint file version with HEAD version", "deleted": false, "createdAt": "2025-10-29T21:52:06.500Z" }, { "id": 3, "text": "Top-left pane shows only checkpoints, bottom-left pane shows only files, right pane shows only diff", "deleted": false, "createdAt": "2025-10-29T21:52:06.500Z" } ], "examples": [ { "id": 0, "text": "User opens checkpoint viewer (C key), sees list of 3 checkpoints sorted by timestamp", "deleted": false, "createdAt": "2025-10-29T21:52:06.500Z" }, { "id": 1, "text": "User selects checkpoint 'baseline', file list shows ['src/auth.ts', 'src/login.ts'] from that checkpoint", "deleted": false, "createdAt": "2025-10-29T21:52:06.500Z" }, { "id": 2, "text": "User selects 'src/auth.ts' from checkpoint, diff pane shows changes between checkpoint version and HEAD", "deleted": false, "createdAt": "2025-10-29T21:52:06.500Z" } ], "estimate": 5, "updated": "2025-10-29T21:55:51.386Z", "nextRuleId": 4, "nextExampleId": 3, "nextQuestionId": 0, "nextNoteId": 0 }, "TUI-006": { "id": "TUI-006", "title": "VirtualList text wrapping inconsistency", "type": "bug", "status": "done", "createdAt": "2025-10-29T22:51:32.401Z", "updatedAt": "2025-10-29T23:05:56.425Z", "description": "VirtualList component has inconsistent text wrapping behavior. In CheckpointViewer, the file list wraps text correctly but the checkpoint list does not wrap, even though both use identical Box/Text structures. Likely caused by VirtualList using percentage-based flexBasis internally instead of flexGrow properties for proper flexbox layout.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-29T22:53:10.978Z" }, { "state": "testing", "timestamp": "2025-10-29T22:56:13.759Z" }, { "state": "implementing", "timestamp": "2025-10-29T22:58:23.630Z" }, { "state": "validating", "timestamp": "2025-10-29T23:02:04.711Z" }, { "state": "done", "timestamp": "2025-10-29T23:05:56.425Z" } ], "userStory": { "role": "developer using VirtualList component", "action": "display text content in list items", "benefit": "text wraps properly regardless of which VirtualList instance is used" }, "rules": [ { "id": 0, "text": "VirtualList must use flexGrow/flexShrink properties instead of percentage-based flexBasis", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" }, { "id": 1, "text": "All components using VirtualList must use flexGrow/flexShrink for container widths", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" }, { "id": 2, "text": "Text components within VirtualList items must have wrap='wrap' attribute for proper wrapping", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" }, { "id": 3, "text": "Item render functions must return Box with flexGrow=1 wrapping Text components", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" }, { "id": 4, "text": "Yes, ALL components using VirtualList must be converted to use flexGrow/flexShrink to ensure consistent behavior", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" } ], "examples": [ { "id": 0, "text": "CheckpointViewer checkpoint list: long checkpoint names wrap to multiple lines within pane width", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" }, { "id": 1, "text": "CheckpointViewer file list: long file paths wrap to multiple lines within pane width", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" }, { "id": 2, "text": "BoardView work units: long work unit titles wrap to multiple lines within column width", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" }, { "id": 3, "text": "FileDiffViewer file list: long file names wrap to multiple lines within pane width", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" } ], "questions": [ { "id": 0, "text": "@human: Should we also fix FileDiffViewer.tsx which currently uses flexBasis='25%', even though it seems to work?", "selected": true, "answer": "Yes, ALL components using VirtualList must be converted to use flexGrow/flexShrink to ensure consistent behavior", "deleted": false, "createdAt": "2025-10-29T22:51:32.401Z" } ], "updated": "2025-10-29T23:05:56.425Z", "nextRuleId": 5, "nextExampleId": 4, "nextQuestionId": 1, "nextNoteId": 0 }, "TUI-007": { "id": "TUI-007", "title": "Container Focus Indication with Headings", "type": "story", "status": "done", "createdAt": "2025-10-30T00:13:29.067Z", "updatedAt": "2025-10-30T00:40:05.318Z", "description": "Refactor checkpoint and change files views to show focused container using colored heading backgrounds instead of top-level page headings", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-30T00:13:36.821Z" }, { "state": "testing", "timestamp": "2025-10-30T00:22:46.724Z" }, { "state": "implementing", "timestamp": "2025-10-30T00:25:55.876Z" }, { "state": "validating", "timestamp": "2025-10-30T00:29:06.699Z" }, { "state": "done", "timestamp": "2025-10-30T00:40:05.318Z" } ], "userStory": { "role": "developer using fspec TUI", "action": "see which container is currently focused when navigating with Tab", "benefit": "I can navigate between containers more effectively" }, "questions": [ { "id": 0, "text": "@human: Which specific containers exist in the checkpoint view and change files view? (You mentioned file list and diff - are there others?)", "selected": true, "answer": "Three containers: checkpoint list, file list, and diff pane", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 1, "text": "@human: What color should the heading background be when a container is focused? What about when it's not focused?", "selected": true, "answer": "Focused: green background with black text. Unfocused: bold white text with no background", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 2, "text": "@human: What text should each container heading display? (e.g., 'File List', 'Diff View', etc.)", "selected": true, "answer": "Container headings: 'Checkpoints' for checkpoint list, 'Files' for file list, 'Diff' for diff pane", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 3, "text": "@human: You mentioned removing the top-level page heading completely - what heading is this currently and where does it appear? Should it be completely removed or replaced with something else?", "selected": true, "answer": "CheckpointViewer (line 363): 'Checkpoints: {count} available'. ChangedFilesViewer (line 76): 'Changed Files: {staged} staged, {unstaged} unstaged'. Both should be completely removed.", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 4, "text": "@human: Should the focused heading show any additional information besides the colored background? (e.g., keyboard shortcuts, help text, focus indicator icon?)", "selected": true, "answer": "No additional information needed - just the heading text with colored background when focused", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 5, "text": "@human: Should the checkpoint view and change files view have identical behavior and styling for the container headings, or are there any differences between them?", "selected": true, "answer": "Yes - identical behavior and styling across both checkpoint view and change files view", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" } ], "rules": [ { "id": 0, "text": "Container headings must show green background with black text when focused", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 1, "text": "Container headings must show bold white text with no background when not focused", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 2, "text": "Top-level page headings must be completely removed from both CheckpointViewer and ChangedFilesViewer", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 3, "text": "Container headings must appear inside each container (checkpoint list, file list, diff pane)", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 4, "text": "Tab key navigation must update heading background to show which container is currently focused", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 5, "text": "Both CheckpointViewer and ChangedFilesViewer must have identical heading behavior and styling", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" } ], "examples": [ { "id": 0, "text": "User opens CheckpointViewer - checkpoint list heading shows green background with black text 'Checkpoints', file list and diff headings show bold white text", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 1, "text": "User presses Tab once in CheckpointViewer - checkpoint list heading changes to bold white text, file list heading shows green background with black text 'Files'", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 2, "text": "User presses Tab twice in CheckpointViewer - diff pane heading shows green background with black text 'Diff', other headings show bold white text", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 3, "text": "User opens ChangedFilesViewer - no top-level 'Changed Files: X staged, Y unstaged' heading, file list heading shows green background with black text 'Files'", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" }, { "id": 4, "text": "User opens CheckpointViewer - no top-level 'Checkpoints: X available' heading visible, checkpoint list has heading 'Checkpoints' with green background", "deleted": false, "createdAt": "2025-10-30T00:13:29.067Z" } ], "estimate": 3, "updated": "2025-10-30T00:40:05.318Z", "nextRuleId": 6, "nextExampleId": 5, "nextQuestionId": 6, "nextNoteId": 0 }, "TUI-008": { "id": "TUI-008", "title": "Vertical layout for changed files viewer", "type": "story", "status": "done", "createdAt": "2025-10-30T03:17:59.181Z", "updatedAt": "2025-10-30T03:34:02.058Z", "description": "Reposition the files list to be above the diff view instead of to the left, maintaining 33%/67% proportions", "children": [], "userStory": { "role": "developer using the changed files viewer", "action": "view files list above the diff instead of to the left", "benefit": "the layout better fits narrower terminal windows while maintaining the same proportional space allocation" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-30T03:18:31.717Z" }, { "state": "testing", "timestamp": "2025-10-30T03:25:57.985Z" }, { "state": "implementing", "timestamp": "2025-10-30T03:27:23.037Z" }, { "state": "validating", "timestamp": "2025-10-30T03:33:13.631Z" }, { "state": "done", "timestamp": "2025-10-30T03:34:02.058Z" } ], "rules": [ { "id": 0, "text": "Files list must be positioned above the diff view in vertical layout", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 1, "text": "Height proportions must remain 33% for files list and 67% for diff view", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 2, "text": "Layout changes from horizontal (row) to vertical (column) flexbox direction", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 3, "text": "Yes, vertical border between panes becomes horizontal border", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 4, "text": "Both viewers get vertical layout. CheckpointViewer's left-side components also change to opposite direction (vertical)", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" } ], "questions": [ { "id": 0, "text": "@human: Should the section headings ('Files' and 'Diff') remain in the same style with the same focus indication (green background)?", "selected": true, "answer": "Yes, section headings maintain same style with green background focus indication", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 1, "text": "@human: Should the keyboard navigation (Tab to switch panes, arrow keys to navigate) remain exactly the same?", "selected": true, "answer": "Yes, keyboard navigation (Tab, arrow keys) remains exactly the same", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 2, "text": "@human: Should the border styling change? Currently there's a vertical border between panes - should this become a horizontal border?", "selected": true, "answer": "Yes, vertical border between panes becomes horizontal border", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 3, "text": "@human: This change affects FileDiffViewer which is used by both ChangedFilesViewer and CheckpointViewer. Should BOTH viewers get the vertical layout, or just the ChangedFilesViewer?", "selected": true, "answer": "Both viewers get vertical layout. CheckpointViewer's left-side components also change to opposite direction (vertical)", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" } ], "assumptions": [ "Yes, section headings maintain same style with green background focus indication", "Yes, keyboard navigation (Tab, arrow keys) remains exactly the same" ], "examples": [ { "id": 0, "text": "FileDiffViewer changes from horizontal (files left, diff right) to vertical (files top, diff bottom)", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 1, "text": "CheckpointViewer left column changes from vertical stack (checkpoints top, files bottom) to horizontal row (checkpoints left, files right)", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 2, "text": "FileDiffViewer: Files pane maintains 33% height, diff pane maintains 67% height", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 3, "text": "CheckpointViewer: Checkpoints pane gets 33% width, files pane gets 67% width in top row", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 4, "text": "Vertical border in FileDiffViewer becomes horizontal border separating top and bottom", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" }, { "id": 5, "text": "CheckpointViewer maintains top row at 33% height and bottom diff pane at 67% height", "deleted": false, "createdAt": "2025-10-30T03:17:59.181Z" } ], "estimate": 5, "updated": "2025-10-30T03:34:02.058Z", "nextRuleId": 5, "nextExampleId": 6, "nextQuestionId": 4, "nextNoteId": 0 }, "TUI-009": { "id": "TUI-009", "title": "Arrow Key Navigation for Component Selection", "type": "story", "status": "done", "createdAt": "2025-10-30T04:35:03.764Z", "updatedAt": "2025-10-30T05:21:15.299Z", "description": "Add left/right arrow key navigation (in addition to tab/shift-tab) for component selections in both checkpoints view and changed files view. Currently only tab moves forward between selections.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-30T04:49:02.643Z" }, { "state": "testing", "timestamp": "2025-10-30T05:11:09.368Z" }, { "state": "implementing", "timestamp": "2025-10-30T05:15:48.707Z" }, { "state": "validating", "timestamp": "2025-10-30T05:16:46.100Z" }, { "state": "done", "timestamp": "2025-10-30T05:21:15.299Z" } ], "userStory": { "role": "user navigating the TUI", "action": "use arrow keys (left/right) to move between component selections", "benefit": "navigation feels more intuitive and matches common UI patterns" }, "rules": [ { "id": 0, "text": "Left/right arrow navigation applies ONLY to CheckpointViewer and ChangedFilesViewer", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 1, "text": "Arrow navigation wraps around: right arrow on rightmost pane goes to leftmost pane, left arrow on leftmost pane goes to rightmost pane", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 2, "text": "Left/right arrow keys always navigate between panes at parent level (horizontal layout matches horizontal keys). No child components capture these keys in current implementation.", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 3, "text": "Arrow keys work alongside Tab navigation: right arrow and Tab both move forward, left arrow and Shift-Tab both move backward. Both methods remain available for user preference.", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" } ], "examples": [ { "id": 0, "text": "In CheckpointViewer, user on 'checkpoints' pane presses right arrow → focus moves to 'files' pane", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 1, "text": "In CheckpointViewer, user on 'files' pane presses left arrow → focus moves to 'checkpoints' pane", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 2, "text": "In CheckpointViewer, user on 'diff' pane (rightmost) presses right arrow → focus wraps around to 'checkpoints' pane (leftmost)", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 3, "text": "In CheckpointViewer, user on 'checkpoints' pane (leftmost) presses left arrow → focus wraps around to 'diff' pane (rightmost)", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 4, "text": "In ChangedFilesViewer, user on 'files' pane presses right arrow → focus moves to 'diff' pane", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 5, "text": "In ChangedFilesViewer, user on 'diff' pane presses right arrow → focus wraps around to 'files' pane", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 6, "text": "In CheckpointViewer, user on 'checkpoints' pane presses Tab → focus moves to 'files' pane (same as right arrow)", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" }, { "id": 7, "text": "In CheckpointViewer, user on 'checkpoints' pane presses up/down arrows → navigates between checkpoint items within the pane (existing behavior preserved)", "deleted": false, "createdAt": "2025-10-30T04:35:03.764Z" } ], "estimate": 3, "updated": "2025-10-30T05:21:15.299Z", "nextRuleId": 4, "nextExampleId": 8, "nextQuestionId": 0, "nextNoteId": 0 }, "TUI-010": { "id": "TUI-010", "title": "Mouse Scrolling for Kanban Columns", "type": "story", "status": "done", "createdAt": "2025-10-30T04:35:05.167Z", "updatedAt": "2025-10-30T07:21:42.708Z", "description": "Add mouse scrolling support to kanban columns using the same mouse scrolling code as VirtualList", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-30T05:24:15.062Z" }, { "state": "testing", "timestamp": "2025-10-30T05:29:27.602Z" }, { "state": "implementing", "timestamp": "2025-10-30T05:34:36.671Z" }, { "state": "validating", "timestamp": "2025-10-30T05:36:21.286Z" }, { "state": "done", "timestamp": "2025-10-30T05:39:17.074Z" }, { "state": "implementing", "timestamp": "2025-10-30T05:47:34.565Z" }, { "state": "validating", "timestamp": "2025-10-30T07:21:21.145Z" }, { "state": "done", "timestamp": "2025-10-30T07:21:42.708Z" } ], "userStory": { "role": "user navigating the kanban board", "action": "scroll through work units in columns using mouse wheel or trackpad", "benefit": "I can quickly navigate long lists without using keyboard" }, "rules": [ { "id": 0, "text": "Mouse scrolling applies ONLY to the focused column in the kanban board", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 1, "text": "Mouse scroll down increases the column's scroll offset by 1, showing work units below", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 2, "text": "Mouse scroll up decreases the column's scroll offset by 1, showing work units above", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 3, "text": "Mouse scrolling must parse both raw escape sequences (button codes 96/97) and Ink-parsed mouse events (wheelUp/wheelDown) for terminal compatibility", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 4, "text": "Scroll offset cannot go below 0 or exceed (column length - viewport height)", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" } ], "examples": [ { "id": 0, "text": "User has backlog column focused with 20 work units, viewport shows items 0-9 → user scrolls mouse down → viewport shows items 1-10 (scroll offset becomes 1)", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 1, "text": "User has backlog column focused at scroll offset 5 → user scrolls mouse up → viewport shows items from offset 4 (scrolls up by 1)", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 2, "text": "User at scroll offset 0 (top of column) → user scrolls mouse up → scroll offset remains 0 (cannot scroll above top)", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 3, "text": "User has 15 work units, viewport height is 10, at scroll offset 5 (showing last 10 items) → user scrolls mouse down → scroll offset remains 5 (cannot scroll below bottom)", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 4, "text": "User has backlog column focused and scrolls down to offset 3 → user switches focus to testing column → backlog remains at offset 3, testing starts at offset 0 (per-column scroll offsets)", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 5, "text": "User scrolls backlog column to offset 2 → top row shows ↑ indicator, bottom row shows ↓ indicator (visual feedback that more items exist above and below)", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" }, { "id": 6, "text": "User uses Page Down key to scroll backlog to offset 10 → user uses mouse wheel to scroll down by 1 → offset becomes 11 (mouse and keyboard scrolling work together)", "deleted": false, "createdAt": "2025-10-30T04:35:05.167Z" } ], "estimate": 3, "updated": "2025-10-30T07:21:42.708Z", "nextRuleId": 5, "nextExampleId": 7, "nextQuestionId": 0, "nextNoteId": 0 }, "MIG-001": { "id": "MIG-001", "title": "Build Migration System", "type": "story", "status": "done", "createdAt": "2025-10-31T07:02:00.522Z", "updatedAt": "2025-11-01T05:40:33.359Z", "description": "Implement formal migration system for schema changes in work-units.json. Provides infrastructure for versioned migrations, automatic migration on load, backup creation, and migration history tracking. This is a dependency for stable indices implementation.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-31T07:05:00.814Z" }, { "state": "testing", "timestamp": "2025-10-31T07:27:42.492Z" }, { "state": "implementing", "timestamp": "2025-10-31T10:34:23.237Z" }, { "state": "testing", "timestamp": "2025-10-31T22:31:57.908Z" }, { "state": "implementing", "timestamp": "2025-11-01T05:11:49.645Z" }, { "state": "validating", "timestamp": "2025-11-01T05:23:02.333Z" }, { "state": "done", "timestamp": "2025-11-01T05:31:07.209Z" }, { "state": "implementing", "timestamp": "2025-11-01T05:34:56.591Z" }, { "state": "validating", "timestamp": "2025-11-01T05:40:14.679Z" }, { "state": "done", "timestamp": "2025-11-01T05:40:33.359Z" } ], "rules": [ { "id": 0, "text": "Migrations must execute in version order (0.6.0 → 0.7.0 → 0.8.0)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 1, "text": "Each migration must create a timestamped backup before modifying work-units.json", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 2, "text": "Migration history must be tracked in work-units.json with version, timestamp, and backup path", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 3, "text": "Failed migrations must not corrupt work-units.json (atomic operations)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 4, "text": "Migrations must be idempotent (running twice produces same result as running once)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 5, "text": "Version field must be added to work-units.json root level", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 6, "text": "Auto-migration must run transparently on first command after upgrade", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 7, "text": "Manual migration command must be available: fspec migrate --version X.Y.Z", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 8, "text": "Migration runner must detect current version from work-units.json (or default to v0.6.0 if missing)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 9, "text": "Console output must show migration progress (backup path, migration name, success/failure)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 10, "text": "Migration registry must be extensible (easy to add future migrations)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 11, "text": "Backup files must use format: work-units.json.backup-{version}-{timestamp}", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 12, "text": "Create src/commands/migrate-help.ts with CommandHelpConfig for 'fspec migrate' command (auto-loaded by help-registry.ts)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 13, "text": "Update src/commands/bootstrap.ts and src/utils/slashCommandTemplate.ts to document the migration system and version tracking", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 14, "text": "Add migration system section to bootstrap output explaining version field, auto-migration, and manual migration command", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 15, "text": "Manual restore - migration failure throws error with backup path, user can restore manually if needed. No automatic rollback.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 16, "text": "Fail immediately with clear error message if work-units.json is corrupted or invalid JSON. Do not attempt automatic repair.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 17, "text": "Show progress output only (backup path, migration name, success). No warning prompts - auto-migration is expected behavior after upgrade.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 18, "text": "Yes, support 'fspec migrate --rollback' to undo last migration if down() function exists. Error if down() not implemented.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" } ], "examples": [ { "id": 0, "text": "User upgrades fspec from 0.6.0 to 0.7.0, runs 'fspec show-work-unit AUTH-001', migration runs automatically with backup, work-units.json updated with version field", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 1, "text": "User runs command when already at v0.7.0, no migrations run (idempotent check), command proceeds normally", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 2, "text": "Migration fails due to invalid JSON structure, error message shown, work-units.json unchanged (backup not restored automatically)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 3, "text": "User with no version field in work-units.json (v0.6.0 format), migration adds version: '0.7.0' and migrationHistory array", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 4, "text": "User runs manual migration: 'fspec migrate --version 0.7.0', explicit migration with progress output, backup created at spec/work-units.json.backup-0.7.0-1738329600000", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 5, "text": "Multiple migrations needed (v0.6.0 → v0.8.0), both v0.7.0 and v0.8.0 migrations run in sequence, two backups created, final version is 0.8.0", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 6, "text": "Migration history tracking: after migration, work-units.json contains migrationHistory: [{version: '0.7.0', applied: '2025-01-31T12:00:00Z', backupPath: '...'}]", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 7, "text": "User checks migration status: 'fspec migrate --status', output shows current version, migration history, and available migrations", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" } ], "questions": [ { "id": 0, "text": "@human: Should migration failure trigger automatic rollback from backup, or should user manually restore?", "selected": true, "answer": "Manual restore - migration failure throws error with backup path, user can restore manually if needed. No automatic rollback.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 1, "text": "@human: Should we support downgrade migrations (down() function), or only forward migrations?", "selected": true, "answer": "Support optional down() function for rollback, but not required for all migrations. Document as 'probably not needed' for most cases.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 2, "text": "@human: How many backup files should be kept? Should old backups be auto-deleted after N days?", "selected": true, "answer": "Keep all backup files indefinitely. No auto-deletion. Users can manually delete old backups from spec/ directory if disk space is concern.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 3, "text": "@human: If work-units.json is corrupted/invalid, should migration fail immediately or attempt repair?", "selected": true, "answer": "Fail immediately with clear error message if work-units.json is corrupted or invalid JSON. Do not attempt automatic repair.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 4, "text": "@human: Should migration warnings be shown to user (e.g., 'This will modify your work-units.json'), or run silently with just progress output?", "selected": true, "answer": "Show progress output only (backup path, migration name, success). No warning prompts - auto-migration is expected behavior after upgrade.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 5, "text": "@human: Should 'fspec migrate --rollback' be supported to undo last migration using the down() function?", "selected": true, "answer": "Yes, support 'fspec migrate --rollback' to undo last migration if down() function exists. Error if down() not implemented.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" } ], "architectureNotes": [ { "id": 0, "text": "File structure: src/migrations/ with index.ts (runner), registry.ts (version tracking), types.ts (interfaces), migrations/ subfolder for individual migration files, __tests__/ for tests", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 1, "text": "Migration interface: {version: string, name: string, description: string, up: (data) => data, down?: (data) => data}. Each migration has unique version number.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 2, "text": "Registry pattern: migrations array in registry.ts exports all migrations in version order. getMigrationsToApply(currentVersion, targetVersion) returns migrations to run.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 3, "text": "Auto-migration integration: ensureWorkUnitsFile() in src/utils/ensure-files.ts calls ensureLatestVersion(cwd, CURRENT_VERSION) before returning data", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 4, "text": "Backup naming: work-units.json.backup-{version}-{timestamp} (e.g., work-units.json.backup-0.7.0-1738329600000). Stored in same directory as work-units.json.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 5, "text": "Version comparison: Use semver-compatible compareVersions(v1, v2) function. Returns -1 (v1 < v2), 0 (equal), or 1 (v1 > v2).", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 6, "text": "Migration history structure in work-units.json: migrationHistory: [{version: '0.7.0', applied: '2025-01-31T12:00:00Z', backupPath: 'spec/work-units.json.backup-0.7.0-1738329600000'}]", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 7, "text": "Error handling: Migration failure throws error with migration version, does NOT automatically restore backup. User can manually restore from backup file if needed.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 8, "text": "Console output: Use chalk.yellow for warnings, chalk.blue for migration names, chalk.green for success, chalk.red for errors, chalk.dim for backup paths. Show progress for each migration.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 9, "text": "Transaction safety: Each migration runs atomically - backup created first, then migration up() called, then data saved. If up() throws, data is not saved.", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 10, "text": "Version field location: Add 'version' field at root level of work-units.json (same level as 'workUnits' and 'states'). Default to undefined for old files (treated as v0.6.0).", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" }, { "id": 11, "text": "Manual command structure: 'fspec migrate' with options: --version X.Y.Z (migrate to specific version), --status (show migration info), --rollback (undo last migration if down() exists)", "deleted": false, "createdAt": "2025-10-31T07:02:00.522Z" } ], "userStory": { "role": "fspec developer", "action": "safely evolve the work-units.json schema across versions", "benefit": "future schema changes can be deployed without data loss or manual migration steps" }, "assumptions": [ "Support optional down() function for rollback, but not required for all migrations. Document as 'probably not needed' for most cases.", "Keep all backup files indefinitely. No auto-deletion. Users can manually delete old backups from spec/ directory if disk space is concern." ], "estimate": 5, "nextRuleId": 19, "nextExampleId": 8, "nextQuestionId": 6, "nextNoteId": 12, "updated": "2025-11-01T05:40:33.359Z" }, "IDX-001": { "id": "IDX-001", "title": "Implement Stable Indices with Soft Delete", "type": "story", "status": "done", "createdAt": "2025-10-31T07:02:20.816Z", "updatedAt": "2025-11-01T07:27:00.887Z", "description": "Convert string-based collections (rules, examples, questions, architectureNotes) to object-based collections with immutable IDs and soft-delete flags. Prevents data loss during sequential AI removal operations. Uses migration system from MIG-001.", "children": [], "dependsOn": [ "MIG-001" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-10-31T07:13:04.806Z" }, { "state": "testing", "timestamp": "2025-10-31T07:27:44.771Z" }, { "state": "implementing", "timestamp": "2025-10-31T10:39:01.808Z" }, { "state": "testing", "timestamp": "2025-10-31T22:31:59.206Z" }, { "state": "implementing", "timestamp": "2025-11-01T06:03:35.299Z" }, { "state": "specifying", "timestamp": "2025-11-01T07:04:43.000Z" }, { "state": "testing", "timestamp": "2025-11-01T07:05:15.979Z" }, { "state": "implementing", "timestamp": "2025-11-01T07:07:58.727Z" }, { "state": "testing", "timestamp": "2025-11-01T07:08:33.202Z" }, { "state": "implementing", "timestamp": "2025-11-01T07:09:16.866Z" }, { "state": "testing", "timestamp": "2025-11-01T07:14:22.873Z" }, { "state": "implementing", "timestamp": "2025-11-01T07:15:25.578Z" }, { "state": "testing", "timestamp": "2025-11-01T07:16:33.083Z" }, { "state": "implementing", "timestamp": "2025-11-01T07:20:30.604Z" }, { "state": "validating", "timestamp": "2025-11-01T07:23:29.437Z" }, { "state": "done", "timestamp": "2025-11-01T07:27:00.887Z" } ], "rules": [ { "id": 0, "text": "Indices must never shift when items are removed (stable IDs preserved)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 1, "text": "Remove operations must set deleted: true instead of splicing from array", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 2, "text": "Display commands must filter deleted items and show stable IDs", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 3, "text": "Item IDs must be auto-incrementing integers starting from 0", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 4, "text": "Collections must use structure: {id: number, text: string, deleted: boolean, createdAt: string, deletedAt?: string}", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 5, "text": "Work units must track nextRuleId, nextExampleId, nextQuestionId, nextNoteId counters", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 6, "text": "Restore commands must set deleted: false and clear deletedAt timestamp", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 7, "text": "Compact command must permanently remove deleted items and renumber IDs sequentially", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 8, "text": "Auto-compact work unit when status changes to done (remove deleted items permanently)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 9, "text": "Questions must have both id and deleted fields (align with rules/examples/notes)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 10, "text": "Remove operations on already-deleted items must be idempotent (no error, return success)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 11, "text": "Migration script 001-stable-indices.ts must convert string arrays to object arrays with stable IDs", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 12, "text": "Add commands must create objects with nextId++, deleted: false, createdAt: now()", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 13, "text": "Display must show gaps in indices (e.g., [0], [2], [3] if [1] deleted) with deleted count", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 14, "text": "Create restore command help files: src/commands/restore-rule-help.ts, restore-example-help.ts, restore-question-help.ts, restore-architecture-note-help.ts with CommandHelpConfig (auto-loaded by help-registry.ts)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 15, "text": "Create src/commands/compact-work-unit-help.ts with CommandHelpConfig for 'fspec compact-work-unit' command (auto-loaded by help-registry.ts)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 16, "text": "Update src/commands/bootstrap.ts to document stable indices, restore commands, compact command, and auto-compact behavior in workflow documentation", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 17, "text": "Update src/help.ts and related help files to explain stable indices concept (items have IDs, removal is soft-delete, indices shown in display)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 18, "text": "Restore operations on non-deleted items must be idempotent (no error, return success with message 'Item ID already active')", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 19, "text": "Restore operations on non-existent IDs must fail with clear error message 'Item ID does not exist'", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 20, "text": "Compact operation must preserve chronological order of remaining items (sort by createdAt timestamp)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 21, "text": "ID counters (nextRuleId, etc.) must reset to count of remaining items after compaction (e.g., 5 items → nextId = 5)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 22, "text": "Display commands must show item count with format: 'X active items (Y deleted)' when deleted items exist", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 23, "text": "Migration from v0.6.0 must initialize all ID counters to array.length (nextRuleId = rules.length, etc.)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 24, "text": "Type definitions must be updated: RuleItem, ExampleItem, QuestionItem, ArchitectureNoteItem interfaces with {id, text, deleted, createdAt, deletedAt?}", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 25, "text": "All commands using .splice() must be replaced with soft-delete pattern (set deleted: true, deletedAt: ISO timestamp)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 26, "text": "WorkUnit interface must add nextRuleId, nextExampleId, nextQuestionId, nextNoteId fields (all number type, default 0)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 27, "text": "Update commands (update-rule, update-example, update-question, update-architecture-note) must use stable IDs instead of indices", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 28, "text": "Yes, create 'fspec show-deleted <work-unit-id>' command showing deleted items with IDs, text, and deletedAt timestamps for debugging and selective restoration", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 29, "text": "Require confirmation with --force flag to skip. Compaction is permanent and destructive - user should confirm before proceeding", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 30, "text": "Yes, support bulk restore with comma-separated IDs: 'fspec restore-rule AUTH-001 2,5,7'. Validates all IDs before restoring any", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 31, "text": "Yes, add --verbose flag to show-work-unit displaying createdAt and deletedAt timestamps for all items (active and deleted)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" } ], "examples": [ { "id": 0, "text": "AI removes rules at indices 1 and 2 sequentially: First removal sets rules[1].deleted=true (index stays), second removal sets rules[2].deleted=true (correct item removed, no shift)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 1, "text": "Work unit has 5 rules [0-4], AI removes indices 1 and 3, display shows: [0] Rule A, [2] Rule C, [4] Rule E with '3 active items (2 deleted)'", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 2, "text": "User runs 'fspec restore-rule AUTH-001 2', rule[2].deleted changes from true to false, deletedAt field cleared, rule reappears in display at original index [2]", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 3, "text": "Work unit with 10 rules (IDs 0-9), 4 deleted, user runs 'fspec compact-work-unit AUTH-001', deleted items removed permanently, remaining 6 rules renumbered to IDs 0-5, nextRuleId reset to 6", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 4, "text": "Work unit at 'implementing' status has 3 deleted rules, user runs 'fspec update-work-unit-status AUTH-001 done', auto-compact triggers before status change, deleted rules removed, IDs renumbered, then status updated", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 5, "text": "Migration converts rules: ['Rule A', 'Rule B'] to [{id: 0, text: 'Rule A', deleted: false, createdAt: '2025-01-31T12:00:00Z'}, {id: 1, text: 'Rule B', deleted: false, createdAt: '2025-01-31T12:00:00Z'}], nextRuleId set to 2", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 6, "text": "User runs 'fspec add-rule AUTH-001 \"New rule\"', system creates {id: nextRuleId, text: 'New rule', deleted: false, createdAt: now()}, increments nextRuleId by 1", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 7, "text": "User runs 'fspec remove-rule AUTH-001 2' twice, first call sets deleted=true, second call succeeds with message 'Item ID 2 already deleted' (idempotent)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 8, "text": "User runs 'fspec restore-rule AUTH-001 2' on non-deleted item, command succeeds with message 'Item ID 2 already active' (idempotent)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 9, "text": "User runs 'fspec restore-rule AUTH-001 99', command fails with error 'Item ID 99 does not exist' (validation)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" } ], "questions": [ { "id": 0, "text": "@human: Should we provide a 'show-deleted' command to view deleted items (with IDs and deletedAt timestamps) for debugging and recovery purposes?", "selected": true, "answer": "Yes, create 'fspec show-deleted <work-unit-id>' command showing deleted items with IDs, text, and deletedAt timestamps for debugging and selective restoration", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 1, "text": "@human: Should compact-work-unit require confirmation prompt or run silently? Compaction is permanent and removes deleted items forever.", "selected": true, "answer": "Require confirmation with --force flag to skip. Compaction is permanent and destructive - user should confirm before proceeding", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 2, "text": "@human: Should we warn or auto-compact when deleted item count exceeds a threshold (e.g., >50% of total items)? Or leave compaction entirely manual/on-done?", "selected": true, "answer": "No automatic threshold-based compaction. Only auto-compact on 'done' status. User has full control over when to compact via manual command", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 3, "text": "@human: Should restore commands support bulk operations (e.g., 'fspec restore-rule AUTH-001 2,5,7' to restore multiple IDs at once)?", "selected": true, "answer": "Yes, support bulk restore with comma-separated IDs: 'fspec restore-rule AUTH-001 2,5,7'. Validates all IDs before restoring any", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 4, "text": "@human: Should we provide a 'purge' command to permanently delete specific items by ID before compaction (for removing sensitive data immediately)?", "selected": true, "answer": "No separate purge command. Use compact-work-unit for permanent deletion. Simpler API with fewer commands to maintain", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 5, "text": "@human: Should display commands show creation/deletion timestamps in verbose mode (e.g., 'fspec show-work-unit AUTH-001 --verbose')?", "selected": true, "answer": "Yes, add --verbose flag to show-work-unit displaying createdAt and deletedAt timestamps for all items (active and deleted)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" } ], "assumptions": [ "No automatic threshold-based compaction. Only auto-compact on 'done' status. User has full control over when to compact via manual command", "No separate purge command. Use compact-work-unit for permanent deletion. Simpler API with fewer commands to maintain" ], "architectureNotes": [ { "id": 0, "text": "Type definitions in src/types.ts: RuleItem, ExampleItem, QuestionItem, ArchitectureNoteItem interfaces extend base ItemWithId { id: number; text: string; deleted: boolean; createdAt: string; deletedAt?: string }", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 1, "text": "Update WorkUnit interface in src/types.ts: Add nextRuleId: number, nextExampleId: number, nextQuestionId: number, nextNoteId: number fields (default 0 for backward compatibility)", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 2, "text": "Remove command pattern: find item by ID, check if deleted, set deleted=true and deletedAt=new Date().toISOString(). Commands: remove-rule, remove-example, remove-question, remove-architecture-note, remove-attachment", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 3, "text": "Add command pattern: create object { id: workUnit.nextRuleId++, text, deleted: false, createdAt: new Date().toISOString() }. Commands: add-rule, add-example, add-question, add-architecture-note", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 4, "text": "Display filtering helper: filterActive(items) returns items.filter(item => !item.deleted). Used in show-work-unit, list-work-units, and all display commands", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 5, "text": "Restore command structure: src/commands/restore-{rule,example,question,architecture-note}.ts. Find item by ID, validate exists, set deleted=false, delete deletedAt field. Support bulk IDs via comma-separated string", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 6, "text": "Compact command: src/commands/compact-work-unit.ts. Filter out deleted items, sort by createdAt, renumber IDs sequentially (0, 1, 2...), reset ID counters to array.length. Require confirmation unless --force flag provided", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 7, "text": "Show-deleted command: src/commands/show-deleted.ts. Display deleted items with IDs, text, deletedAt timestamps. Format: '[ID] text (deleted: timestamp)'. Useful for debugging and selective restoration", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 8, "text": "Update show-work-unit command: Add --verbose flag to display createdAt and deletedAt timestamps. Show item count as 'X active items (Y deleted)' when deleted items exist. Display indices with gaps: [0], [2], [3] if [1] deleted", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 9, "text": "Migration integration: Depends on MIG-001 migration system. Migration script src/migrations/migrations/001-stable-indices.ts converts string[] to ItemWithId[]. Called automatically by ensureLatestVersion() in src/utils/ensure-files.ts", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 10, "text": "Auto-compact on done: Update src/commands/update-work-unit-status.ts. Before setting status='done', call compactWorkUnit(workUnit) to remove deleted items and renumber IDs. Ensures clean final state", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" }, { "id": 11, "text": "Help file structure: Create restore-{rule,example,question,architecture-note}-help.ts, compact-work-unit-help.ts, show-deleted-help.ts in src/commands/. Each exports CommandHelpConfig with comprehensive usage, examples, and AI guidance. Auto-loaded by help-registry.ts", "deleted": false, "createdAt": "2025-10-31T07:02:20.816Z" } ], "userStory": { "role": "AI agent or developer using fspec for Example Mapping", "action": "remove multiple items from collections (rules, examples, questions, notes) without index shifts", "benefit": "sequential removals target correct items and no data is lost due to array splicing" }, "estimate": 8, "nextRuleId": 32, "nextExampleId": 10, "nextQuestionId": 6, "nextNoteId": 12, "attachments": [ "spec/attachments/IDX-001/IDX-001-migration-plan.md" ], "updated": "2025-11-01T07:27:00.887Z" }, "IDX-002": { "id": "IDX-002", "title": "Critical fixes for stable indices field naming and state sorting", "type": "bug", "status": "done", "createdAt": "2025-11-01T07:44:35.052Z", "updatedAt": "2025-11-01T08:09:38.721Z", "description": "Fix critical bugs: (1) nextNoteId vs nextArchitectureNoteId mismatch causes ID collisions, (2) state sorting lost during auto-compact causes data loss", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T07:44:42.715Z" }, { "state": "testing", "timestamp": "2025-11-01T07:50:18.105Z" }, { "state": "implementing", "timestamp": "2025-11-01T07:52:43.741Z" }, { "state": "validating", "timestamp": "2025-11-01T08:00:28.145Z" }, { "state": "done", "timestamp": "2025-11-01T08:01:12.152Z" }, { "state": "implementing", "timestamp": "2025-11-01T08:07:53.367Z" }, { "state": "validating", "timestamp": "2025-11-01T08:09:08.922Z" }, { "state": "done", "timestamp": "2025-11-01T08:09:38.721Z" } ], "rules": [ { "id": 0, "text": "Architecture note ID counter MUST use field name 'nextNoteId' consistently across all operations (migration, add, compact, restore)", "deleted": false, "createdAt": "2025-11-01T07:44:57.312Z" }, { "id": 1, "text": "compact-work-unit.ts MUST set 'nextNoteId' not 'nextArchitectureNoteId' to prevent ID collision after compaction", "deleted": false, "createdAt": "2025-11-01T07:45:07.703Z" }, { "id": 2, "text": "State sorting changes MUST be preserved when auto-compact is triggered during status transition to 'done'", "deleted": false, "createdAt": "2025-11-01T07:45:09.325Z" }, { "id": 3, "text": "Auto-compact MUST NOT discard state sorting by re-reading from disk after compaction saves", "deleted": false, "createdAt": "2025-11-01T07:45:10.984Z" }, { "id": 4, "text": "Help documentation MUST use 'nextNoteId' not 'nextArchitectureNoteId' in stable indices examples", "deleted": false, "createdAt": "2025-11-01T07:45:12.541Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User compacts AUTH-001 with 3 architecture notes remaining. compact-work-unit sets nextArchitectureNoteId=3 instead of nextNoteId=3. Next add-architecture-note uses nextNoteId=0, creating ID collision with existing note at index 0", "deleted": false, "createdAt": "2025-11-01T07:45:32.841Z" }, { "id": 1, "text": "User moves BOARD-001 to 'done' with specific sort order. update-work-unit-status sorts states, calls compactWorkUnit, then re-reads from disk. State sorting changes are lost because compactWorkUnit saved without the sorted states", "deleted": false, "createdAt": "2025-11-01T07:45:34.443Z" }, { "id": 2, "text": "After fixing compact-work-unit.ts line 136 to use nextNoteId, architecture note IDs increment correctly after compaction (no collision)", "deleted": false, "createdAt": "2025-11-01T07:45:36.890Z" }, { "id": 3, "text": "After preserving sorted states through auto-compact, work units maintain user-defined sort order when transitioning to 'done' status", "deleted": false, "createdAt": "2025-11-01T07:45:38.426Z" } ], "nextExampleId": 4, "attachments": [ "spec/attachments/IDX-002/IDX-002-critical-bug-analysis.md" ], "userStory": { "role": "developer using stable indices system", "action": "fix critical field naming and data loss bugs", "benefit": "architecture note IDs don't collide and state sorting is preserved during auto-compact" }, "updated": "2025-11-01T08:09:38.721Z", "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0 }, "GIT-009": { "id": "GIT-009", "title": "Restore individual files or all files from checkpoint in checkpoint viewer", "type": "story", "status": "done", "createdAt": "2025-11-01T17:36:19.264Z", "updatedAt": "2025-11-04T10:31:31.714Z", "description": "Add ability to selectively restore individual files or restore all files from a checkpoint through the TUI checkpoint viewer interface", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T17:36:26.698Z" }, { "state": "specifying", "timestamp": "2025-11-04T07:33:50.667Z" }, { "state": "testing", "timestamp": "2025-11-04T10:09:00.056Z" }, { "state": "implementing", "timestamp": "2025-11-04T10:11:51.380Z" }, { "state": "validating", "timestamp": "2025-11-04T10:26:26.600Z" }, { "state": "done", "timestamp": "2025-11-04T10:31:31.715Z" } ], "userStory": { "role": "developer using checkpoint viewer", "action": "restore individual files or all files from a checkpoint", "benefit": "I can recover specific file versions without restoring the entire checkpoint" }, "rules": [ { "id": 0, "text": "Checkpoint viewer currently has three panes: checkpoints list (left), files in checkpoint (middle), and diff viewer (right)", "deleted": false, "createdAt": "2025-11-01T17:36:52.048Z" }, { "id": 1, "text": "Checkpoint viewer currently only allows viewing/browsing checkpoints - no restore functionality exists", "deleted": false, "createdAt": "2025-11-01T17:36:53.614Z" }, { "id": 2, "text": "restoreCheckpoint() function already exists in git-checkpoint.ts and handles conflict detection", "deleted": false, "createdAt": "2025-11-01T17:36:55.138Z" }, { "id": 3, "text": "Current restoreCheckpoint() only restores ALL files at once. Single-file restore requires new utility function restoreCheckpointFile()", "deleted": false, "createdAt": "2025-11-04T09:59:07.661Z" }, { "id": 4, "text": "Checkpoint viewer displays all checkpoints from all work units (loaded from .git/fspec-checkpoints-index/*.json), sorted by timestamp (most recent first), limited to 200 for performance", "deleted": false, "createdAt": "2025-11-04T09:59:09.148Z" }, { "id": 5, "text": "After successful restore, IPC message {type: 'checkpoint-changed'} must be sent to notify other components (BoardView, CheckpointPanel)", "deleted": false, "createdAt": "2025-11-04T09:59:10.819Z" }, { "id": 6, "text": "Current keybindings: D=delete single, A=delete ALL. Restore needs different keys to avoid conflicts. Must use different keybindings for restore operations.", "deleted": false, "createdAt": "2025-11-04T09:59:12.479Z" }, { "id": 7, "text": "Files in checkpoint viewer show CHANGED files only (compared against checkpoint parent), not all files in repo", "deleted": false, "createdAt": "2025-11-04T09:59:13.910Z" } ], "nextRuleId": 8, "questions": [ { "id": 0, "text": "@human: How should the user trigger restore? (A) Press 'R' key while file is selected to restore single file, (B) Press 'A' key to restore all files from checkpoint, (C) Show a restore menu with options, (D) other approach?", "deleted": false, "createdAt": "2025-11-01T17:37:07.411Z", "selected": true, "answer": "Superseded by Question 4: R key for single file, T key for restore all" }, { "id": 1, "text": "@human: What should happen if restoring would overwrite uncommitted changes? (A) Show warning and require confirmation, (B) Block restore and show error, (C) Auto-create checkpoint before restore, (D) other approach?", "deleted": false, "createdAt": "2025-11-01T17:37:09.144Z", "selected": true, "answer": "Show warning and require confirmation" }, { "id": 2, "text": "@human: After a successful restore, what should happen? (A) Show success message and stay in viewer, (B) Exit viewer and return to board, (C) Show updated diff comparing restored version vs previous, (D) other?", "deleted": false, "createdAt": "2025-11-01T17:37:11.034Z", "selected": true, "answer": "Show success message and stay in viewer" }, { "id": 3, "text": "@human: Should there be visual indicators showing which files have conflicts/would be overwritten before restore? (yes/no)", "deleted": false, "createdAt": "2025-11-01T17:37:12.323Z", "selected": true, "answer": "No - visual indicators not needed because we are overwriting files, not merging. Question 1 already handles warning about uncommitted changes." }, { "id": 4, "text": "@human: What keybindings should trigger restore? (A) R key for single file + T key for restore all files, (B) R key for single file + Shift+R for restore all, (C) Enter key for single file + T key for restore all, (D) other approach?", "deleted": false, "createdAt": "2025-11-04T09:59:23.437Z", "selected": true, "answer": "R key for single file + T key for restore all files" }, { "id": 5, "text": "@human: Should single-file restore show a confirmation dialog? (A) Yes, always confirm (safety first), (B) Only if conflicts detected, (C) No confirmation for single files (faster UX), (D) other approach?", "deleted": false, "createdAt": "2025-11-04T09:59:24.802Z", "selected": true, "answer": "Yes, always confirm (safety first)" }, { "id": 6, "text": "@human: When restoring a file that doesn't exist in current working directory (was deleted), should we: (A) Create the file and all parent directories automatically, (B) Show warning and require confirmation, (C) Skip the file and show error, (D) other approach?", "deleted": false, "createdAt": "2025-11-04T09:59:26.309Z", "selected": true, "answer": "Create the file and all parent directories automatically" }, { "id": 7, "text": "@human: Should the diff pane update after restore to show the NEW diff (checkpoint vs new HEAD)? (A) Yes, refresh diff automatically, (B) No, keep showing old diff, (C) Exit viewer after restore, (D) other approach?", "deleted": false, "createdAt": "2025-11-04T09:59:27.845Z", "selected": true, "answer": "Yes, refresh diff automatically" } ], "nextQuestionId": 8, "examples": [ { "id": 0, "text": "User selects checkpoint 'AUTH-001-baseline' with 3 files (src/auth.ts, src/login.ts, src/utils.ts), presses R key on src/auth.ts, confirmation dialog appears (if enabled), after confirmation file is restored from checkpoint, diff pane refreshes showing new comparison", "deleted": false, "createdAt": "2025-11-04T09:59:44.701Z" }, { "id": 1, "text": "User selects checkpoint 'TUI-001-auto-testing', presses T key (or other chosen keybinding), confirmation dialog appears 'Restore ALL 15 files from checkpoint?', user confirms, all 15 files are restored, IPC message sent, CheckpointPanel updates", "deleted": false, "createdAt": "2025-11-04T09:59:46.288Z" }, { "id": 2, "text": "User attempts to restore src/deleted-file.ts that no longer exists in working directory, system either: (A) creates file + parent dirs, (B) shows warning + confirmation, or (C) shows error (depending on answer to Question 6)", "deleted": false, "createdAt": "2025-11-04T09:59:47.898Z" }, { "id": 3, "text": "User restores src/config.ts which has uncommitted changes in working directory, conflict detected, confirmation dialog shows: 'Overwrite src/config.ts? Current changes will be LOST.' with high-risk warning, user must explicitly confirm", "deleted": false, "createdAt": "2025-11-04T09:59:50.519Z" }, { "id": 4, "text": "User in files pane (middle), presses R key on selected file, restore dialog appears. User in checkpoints pane (left), presses T key, restore all dialog appears. User in diff pane (right), R/T keys do nothing (no file selected)", "deleted": false, "createdAt": "2025-11-04T09:59:52.128Z" } ], "nextExampleId": 5, "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-04T10:31:31.714Z" }, "BUG-053": { "id": "BUG-053", "title": "Checkpoint restore shows confusing 'merge' terminology when it actually overwrites files", "type": "bug", "status": "done", "createdAt": "2025-11-01T17:38:41.001Z", "updatedAt": "2025-11-04T04:15:33.397Z", "description": "The restore-checkpoint command offers 'Force restore with merge' option but doesn't actually merge - it just overwrites files when force=true. User wants simple overwrite without merge terminology.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T17:38:47.615Z" }, { "state": "testing", "timestamp": "2025-11-04T04:07:09.402Z" }, { "state": "implementing", "timestamp": "2025-11-04T04:09:36.391Z" }, { "state": "validating", "timestamp": "2025-11-04T04:11:17.311Z" }, { "state": "done", "timestamp": "2025-11-04T04:15:33.397Z" } ], "userStory": { "role": "developer using fspec", "action": "restore a checkpoint and overwrite my files", "benefit": "I don't get confused by merge terminology when I just want to replace files" }, "rules": [ { "id": 0, "text": "Current behavior: restore-checkpoint shows 3 options when working directory is dirty: (1) Commit changes first, (2) Stash changes and restore, (3) Force restore with merge", "deleted": false, "createdAt": "2025-11-01T17:38:59.844Z" }, { "id": 1, "text": "Option 3 'Force restore with merge' is misleading - it doesn't actually merge, it just overwrites files when force=true is passed", "deleted": false, "createdAt": "2025-11-01T17:39:01.297Z" }, { "id": 2, "text": "The restoreCheckpointUtil in git-checkpoint.ts with force=true overwrites files directly without any merge logic (lines 329-366)", "deleted": false, "createdAt": "2025-11-01T17:39:02.614Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "User has uncommitted changes, runs 'fspec restore-checkpoint AUTH-001 checkpoint-name', sees confusing 'Force restore with merge' option, expects simpler 'Overwrite files' language", "deleted": false, "createdAt": "2025-11-01T17:39:13.515Z" } ], "nextExampleId": 1, "questions": [ { "id": 0, "text": "@human: What should option 3 be renamed to? Suggestions: 'Force overwrite files', 'Discard changes and restore', 'Overwrite with checkpoint', or something else?", "deleted": false, "createdAt": "2025-11-01T17:39:15.150Z", "selected": true, "answer": "Rename to 'Overwrite files (discard changes)' - be brutally honest about what happens" }, { "id": 1, "text": "@human: Should the risk level stay 'High' for the overwrite option? Or change to something else?", "deleted": false, "createdAt": "2025-11-01T17:39:16.772Z", "selected": true, "answer": "Keep risk level as 'High' - data loss is permanent and serious" }, { "id": 2, "text": "@human: Should the description explain data loss risk? E.g., 'Overwrites working directory with checkpoint. Current changes will be lost forever unless committed or stashed.'", "deleted": false, "createdAt": "2025-11-01T17:39:18.682Z", "selected": true, "answer": "Yes - description should clearly warn: 'Overwrites working directory with checkpoint. Current changes will be LOST FOREVER unless committed or stashed.'" } ], "nextQuestionId": 3, "estimate": 2, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-04T04:15:33.397Z" }, "GIT-010": { "id": "GIT-010", "title": "Delete checkpoint or all checkpoints from checkpoint viewer with confirmation", "type": "story", "status": "done", "createdAt": "2025-11-01T17:40:52.075Z", "updatedAt": "2025-11-04T07:56:56.436Z", "description": "Add ability to delete a single checkpoint or all checkpoints from the TUI checkpoint viewer interface with confirmation dialogs to prevent accidental deletion", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T17:41:03.713Z" }, { "state": "specifying", "timestamp": "2025-11-04T07:33:53.568Z" }, { "state": "testing", "timestamp": "2025-11-04T07:40:27.852Z" }, { "state": "implementing", "timestamp": "2025-11-04T07:43:36.890Z" }, { "state": "validating", "timestamp": "2025-11-04T07:53:25.940Z" }, { "state": "done", "timestamp": "2025-11-04T07:56:56.436Z" } ], "userStory": { "role": "TUI developer managing checkpoints", "action": "delete unwanted checkpoints from the checkpoint viewer", "benefit": "I can clean up old experiments and maintain a tidy checkpoint history" }, "rules": [ { "id": 0, "text": "Checkpoint viewer currently has read-only functionality - no delete operations exist in the TUI", "deleted": false, "createdAt": "2025-11-01T17:41:26.410Z" }, { "id": 1, "text": "cleanup-checkpoints CLI command exists but only keeps last N checkpoints, doesn't allow selective deletion", "deleted": false, "createdAt": "2025-11-01T17:41:27.921Z" }, { "id": 2, "text": "Checkpoint deletion must remove both the git ref (refs/fspec-checkpoints/{workUnitId}/{checkpointName}) and the index file entry", "deleted": false, "createdAt": "2025-11-01T17:41:29.463Z" }, { "id": 3, "text": "User wants confirmation dialogs to prevent accidental deletion", "deleted": false, "createdAt": "2025-11-01T17:41:31.201Z" }, { "id": 4, "text": "Delete operation must remove both the git ref (refs/fspec-checkpoints/{workUnitId}/{checkpointName}) AND the checkpoint entry from the index file (.git/fspec-checkpoints-index/{workUnitId}.json)", "deleted": false, "createdAt": "2025-11-04T07:38:08.685Z" }, { "id": 5, "text": "Single checkpoint deletion uses D key and ConfirmationDialog with confirmMode='yesno' and riskLevel='medium' (yellow border)", "deleted": false, "createdAt": "2025-11-04T07:38:10.266Z" }, { "id": 6, "text": "Delete ALL uses Shift+D key and ConfirmationDialog with confirmMode='typed', typedPhrase='DELETE ALL', riskLevel='high' (red border)", "deleted": false, "createdAt": "2025-11-04T07:38:12.338Z" }, { "id": 7, "text": "After successful deletion, viewer stays open with next checkpoint selected (or exits to board if no checkpoints remain)", "deleted": false, "createdAt": "2025-11-04T07:38:13.726Z" }, { "id": 8, "text": "Deletion triggers IPC message (sendIPCMessage({ type: 'checkpoint-changed' })) to update CheckpointPanel counts in real-time", "deleted": false, "createdAt": "2025-11-04T07:38:15.510Z" } ], "nextRuleId": 9, "examples": [ { "id": 0, "text": "User navigates to checkpoint viewer, selects an old checkpoint they don't need, presses Delete key, sees confirmation dialog, confirms, checkpoint is deleted", "deleted": false, "createdAt": "2025-11-01T17:41:47.483Z" }, { "id": 1, "text": "User has 50 old checkpoints, wants to delete them all at once, presses key combination, sees 'Delete ALL checkpoints?' warning, confirms with typed confirmation, all deleted", "deleted": false, "createdAt": "2025-11-01T17:41:49.326Z" }, { "id": 2, "text": "User presses D key while viewing checkpoint, yellow dialog appears asking 'Delete checkpoint AUTH-001-baseline?', user presses Y, checkpoint deleted, viewer selects next checkpoint", "deleted": false, "createdAt": "2025-11-04T07:38:25.135Z" }, { "id": 3, "text": "User presses D key, sees yellow dialog, presses N, deletion cancelled, viewer returns to normal state", "deleted": false, "createdAt": "2025-11-04T07:38:26.523Z" }, { "id": 4, "text": "User presses Shift+D, red dialog appears 'Delete ALL 47 checkpoints for AUTH-001?', user types 'DELETE ALL' and presses Enter, all checkpoints deleted, viewer exits to board", "deleted": false, "createdAt": "2025-11-04T07:38:28.433Z" }, { "id": 5, "text": "User deletes last remaining checkpoint in viewer, viewer automatically exits to board (empty state)", "deleted": false, "createdAt": "2025-11-04T07:38:29.746Z" } ], "nextExampleId": 6, "questions": [ { "id": 0, "text": "@human: What key should trigger single checkpoint deletion? (D)elete, (X) remove, (Backspace), or other?", "deleted": false, "createdAt": "2025-11-01T17:42:04.782Z", "selected": true, "answer": "D key (Delete)" }, { "id": 1, "text": "@human: What key/combination should trigger delete ALL? Shift+D, Ctrl+D, separate menu option, or other?", "deleted": false, "createdAt": "2025-11-01T17:42:06.628Z", "selected": true, "answer": "Shift+D (natural extension of D key with modifier for more destructive action)" }, { "id": 2, "text": "@human: For single checkpoint deletion, what should the confirmation look like? Simple Y/N prompt, or require typing checkpoint name, or other?", "deleted": false, "createdAt": "2025-11-01T17:42:08.075Z", "selected": true, "answer": "Simple Y/N prompt using ConfirmationDialog in yesno mode with medium risk level (yellow border)" }, { "id": 3, "text": "@human: For delete ALL confirmation, should it require typing a specific phrase like DELETE ALL to prevent accidents?", "deleted": false, "createdAt": "2025-11-01T17:42:09.817Z", "selected": true, "answer": "Yes, require typing DELETE ALL phrase to prevent accidents (using ConfirmationDialog typed mode with high risk level red border)" }, { "id": 4, "text": "@human: After deleting a checkpoint, what should happen? Stay in viewer with next checkpoint selected, exit viewer, show success message, or other?", "deleted": false, "createdAt": "2025-11-01T17:42:11.337Z", "selected": true, "answer": "Stay in viewer with next checkpoint selected (or exit to board if no checkpoints remain)" } ], "nextQuestionId": 5, "blockedBy": [ "TUI-011" ], "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-04T07:56:56.436Z" }, "TUI-011": { "id": "TUI-011", "title": "Reusable confirmation dialog component for destructive TUI actions", "type": "story", "status": "done", "createdAt": "2025-11-01T17:42:40.323Z", "updatedAt": "2025-11-04T06:46:16.212Z", "description": "Create a reusable confirmation dialog component in the TUI that can be used for any destructive action requiring user confirmation (delete, overwrite, etc.)", "children": [], "blocks": [ "GIT-010" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T17:43:09.062Z" }, { "state": "testing", "timestamp": "2025-11-04T06:18:17.731Z" }, { "state": "specifying", "timestamp": "2025-11-04T06:19:33.209Z" }, { "state": "testing", "timestamp": "2025-11-04T06:20:09.369Z" }, { "state": "implementing", "timestamp": "2025-11-04T06:21:55.418Z" }, { "state": "specifying", "timestamp": "2025-11-04T06:22:47.158Z" }, { "state": "testing", "timestamp": "2025-11-04T06:33:10.167Z" }, { "state": "implementing", "timestamp": "2025-11-04T06:35:47.501Z" }, { "state": "validating", "timestamp": "2025-11-04T06:43:01.845Z" }, { "state": "done", "timestamp": "2025-11-04T06:46:16.212Z" } ], "userStory": { "role": "TUI developer", "action": "use a reusable confirmation dialog for destructive actions", "benefit": "I can implement consistent, safe confirmation flows without duplicating code" }, "rules": [ { "id": 0, "text": "No existing confirmation dialog component exists in the TUI - each feature would need to implement their own", "deleted": false, "createdAt": "2025-11-01T17:43:31.318Z" }, { "id": 1, "text": "Confirmation dialog must be non-blocking and integrate with Ink component lifecycle", "deleted": false, "createdAt": "2025-11-01T17:43:32.843Z" }, { "id": 2, "text": "Dialog must support different confirmation modes: simple Y/N, typed confirmation phrase, single key press", "deleted": false, "createdAt": "2025-11-01T17:43:34.558Z" }, { "id": 3, "text": "Dialog must clearly display the action being confirmed and its consequences", "deleted": false, "createdAt": "2025-11-01T17:43:36.071Z" }, { "id": 4, "text": "Dialog must support cancellation with ESC key", "deleted": false, "createdAt": "2025-11-01T17:43:37.608Z" }, { "id": 5, "text": "Modal overlay in the center of the screen", "deleted": false, "createdAt": "2025-11-04T06:14:01.148Z" }, { "id": 6, "text": "Yes, support custom styling/colors for different risk levels (low=green, medium=yellow, high=red) as an optional prop", "deleted": false, "createdAt": "2025-11-04T06:14:27.314Z" }, { "id": 7, "text": "Component API: Props should include: message (required), onConfirm callback (required), onCancel callback (required), confirmMode ('yesno' | 'typed' | 'keypress', default 'yesno'), typedPhrase (required if confirmMode='typed'), riskLevel ('low' | 'medium' | 'high', optional), description (optional additional details)", "deleted": false, "createdAt": "2025-11-04T06:15:11.429Z" }, { "id": 8, "text": "Default dialog appearance is a white/neutral modal without risk level styling", "deleted": false, "createdAt": "2025-11-04T06:19:38.378Z" }, { "id": 9, "text": "ConfirmationDialog extends a base Dialog component that provides modal overlay infrastructure", "deleted": false, "createdAt": "2025-11-04T06:22:58.661Z" }, { "id": 10, "text": "Dialog component (base): Handles ONLY modal overlay infrastructure - centering, borders, ESC key, layout. No business logic.", "deleted": false, "createdAt": "2025-11-04T06:24:18.494Z" }, { "id": 11, "text": "ConfirmationDialog component: Handles ONLY confirmation-specific logic - modes (yesno/typed/keypress), validation, onConfirm/onCancel. Uses Dialog for rendering.", "deleted": false, "createdAt": "2025-11-04T06:24:28.265Z" }, { "id": 12, "text": "ConfirmationDialog can override or extend Dialog's key handlers - Dialog provides base ESC handling, ConfirmationDialog adds mode-specific key handling", "deleted": false, "createdAt": "2025-11-04T06:27:05.125Z" }, { "id": 13, "text": "Dialog component's useInput handler must not interfere with parent TUI component key handlers - uses isActive prop pattern to control when it captures input", "deleted": false, "createdAt": "2025-11-04T06:27:35.968Z" } ], "nextRuleId": 14, "examples": [ { "id": 0, "text": "User presses Delete on checkpoint, dialog shows 'Delete checkpoint AUTH-001-auto-testing? [y/N]', user presses Y, checkpoint deleted", "deleted": false, "createdAt": "2025-11-01T17:43:51.613Z" }, { "id": 1, "text": "User presses Shift+D to delete all checkpoints, dialog shows 'Type DELETE ALL to confirm:', user types DELETE ALL, all checkpoints deleted", "deleted": false, "createdAt": "2025-11-01T17:43:53.170Z" }, { "id": 2, "text": "User presses R to restore file, dialog shows 'Restore file will overwrite uncommitted changes. Continue? [y/N]', user presses ESC, action cancelled", "deleted": false, "createdAt": "2025-11-01T17:43:54.487Z" }, { "id": 3, "text": "Developer shows dialog for non-destructive confirmation (e.g., 'Save changes?'), no riskLevel prop provided, dialog displays with standard white/neutral styling", "deleted": false, "createdAt": "2025-11-04T06:19:43.886Z" }, { "id": 4, "text": "Developer creates custom InfoDialog extending Dialog with just a message and OK button - Dialog provides modal overlay, InfoDialog provides OK logic", "deleted": false, "createdAt": "2025-11-04T06:24:34.379Z" }, { "id": 5, "text": "Dialog component renders centered modal with red border when borderColor='red' prop provided, handles ESC to call onClose - no confirmation logic", "deleted": false, "createdAt": "2025-11-04T06:24:40.706Z" }, { "id": 6, "text": "User is in BoardDisplay with active keyboard navigation, opens confirmation dialog - dialog captures ALL input, board navigation suspended until dialog closes", "deleted": false, "createdAt": "2025-11-04T06:27:42.198Z" } ], "nextExampleId": 7, "questions": [ { "id": 0, "text": "@human: Should the dialog be a modal overlay (center of screen) or inline at the bottom like a prompt bar?", "deleted": false, "createdAt": "2025-11-01T17:44:06.744Z", "selected": true, "answer": "Modal overlay in the center of the screen" }, { "id": 1, "text": "@human: Should the dialog support custom styling/colors for different risk levels (low=green, medium=yellow, high=red)?", "deleted": false, "createdAt": "2025-11-01T17:44:08.166Z", "selected": true, "answer": "Yes, support custom styling/colors for different risk levels (low=green, medium=yellow, high=red) as an optional prop" }, { "id": 2, "text": "@human: What should the component API look like? Props: message, confirmMode, onConfirm callback, onCancel callback, riskLevel?", "deleted": false, "createdAt": "2025-11-01T17:44:09.767Z", "selected": true, "answer": "Component API: Props should include: message (required), onConfirm callback (required), onCancel callback (required), confirmMode ('yesno' | 'typed' | 'keypress', default 'yesno'), typedPhrase (required if confirmMode='typed'), riskLevel ('low' | 'medium' | 'high', optional), description (optional additional details)" } ], "nextQuestionId": 3, "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-04T06:46:16.212Z" }, "EXMAP-004": { "id": "EXMAP-004", "title": "Event Storming discovery phase for domain understanding and tag naming", "type": "story", "status": "specifying", "createdAt": "2025-11-01T17:50:17.784Z", "updatedAt": "2025-11-17T02:06:12.648Z", "description": "Add Event Storming as a discovery technique done before Example Mapping to identify domain events, commands, aggregates, and bounded contexts that inform tag naming and domain structure", "children": [ "EXMAP-005", "EXMAP-006", "EXMAP-007", "EXMAP-010" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T17:50:25.622Z" } ], "userStory": { "role": "AI agent using fspec for domain-driven development", "action": "perform Event Storming discovery before Example Mapping", "benefit": "I identify bounded contexts, aggregates, and domain events that inform tag naming and domain structure" }, "rules": [ { "id": 0, "text": "Event Storming uses colored sticky notes to represent different concepts: Orange=Domain Events, Blue=Commands, Yellow=Aggregates, Pink=External Systems, Purple=Policies, Green=Read Models, Red=Hotspots/Questions", "deleted": false, "createdAt": "2025-11-01T17:50:42.948Z" }, { "id": 1, "text": "Event Storming happens BEFORE Example Mapping in the discovery workflow", "deleted": false, "createdAt": "2025-11-01T17:50:44.464Z" }, { "id": 2, "text": "Event Storming identifies domain events (things that happened in past tense) which can inform tag naming and bounded contexts", "deleted": false, "createdAt": "2025-11-01T17:50:45.802Z" }, { "id": 3, "text": "Current fspec workflow has no Event Storming support - discovery goes straight to Example Mapping", "deleted": false, "createdAt": "2025-11-01T17:50:47.248Z" }, { "id": 4, "text": "Event Storming data stored in both foundation.json (Big Picture ES with bounded contexts) and work-units.json (Process/Design ES per story). Tags.json gets enhanced relationships section.", "deleted": false, "createdAt": "2025-11-15T12:15:28.140Z" }, { "id": 5, "text": "Yes, fspec commands: add-domain-event, add-command, add-aggregate, add-policy, add-hotspot, add-external-system, add-bounded-context, suggest-tags-from-events, sync-tags-with-event-storm, add-tag-relationship, show-tag-relationships", "deleted": false, "createdAt": "2025-11-15T12:15:33.932Z" }, { "id": 6, "text": "Yes, domain events visible during Example Mapping via transformation (policies→rules, hotspots→questions). Also used for tag suggestions when generating scenarios.", "deleted": false, "createdAt": "2025-11-15T12:15:40.454Z" }, { "id": 7, "text": "Both. Big Picture ES done at foundation level (foundation.json) for strategic bounded contexts. Process/Design ES done per epic/feature (work-units.json) for tactical discovery.", "deleted": false, "createdAt": "2025-11-15T12:15:46.013Z" }, { "id": 8, "text": "Track all: domain events, commands, aggregates, policies, external systems, bounded contexts, hotspots. This provides complete domain model for tag discovery and transformation to Example Mapping.", "deleted": false, "createdAt": "2025-11-15T12:15:51.477Z" } ], "nextRuleId": 9, "examples": [ { "id": 0, "text": "Team runs Event Storming session, identifies domain events like 'UserRegistered', 'CheckpointCreated', 'WorkUnitStatusChanged', then creates tags based on these events and bounded contexts", "deleted": false, "createdAt": "2025-11-01T17:51:03.855Z" }, { "id": 1, "text": "AI runs Event Storming discovery command, asks questions about domain events, captures events in structured format, suggests tag names based on event clusters and bounded contexts", "deleted": false, "createdAt": "2025-11-01T17:51:05.271Z" } ], "nextExampleId": 2, "questions": [ { "id": 0, "text": "@human: How should Event Storming data be stored? New section in foundation.json, separate event-storm.json file, or in work units themselves?", "deleted": false, "createdAt": "2025-11-01T17:51:20.313Z", "selected": true, "answer": "Event Storming data stored in both foundation.json (Big Picture ES with bounded contexts) and work-units.json (Process/Design ES per story). Tags.json gets enhanced relationships section." }, { "id": 1, "text": "@human: Should there be fspec commands for Event Storming? E.g., fspec add-domain-event, fspec add-command, fspec add-aggregate, fspec suggest-tags-from-events?", "deleted": false, "createdAt": "2025-11-01T17:51:21.657Z", "selected": true, "answer": "Yes, fspec commands: add-domain-event, add-command, add-aggregate, add-policy, add-hotspot, add-external-system, add-bounded-context, suggest-tags-from-events, sync-tags-with-event-storm, add-tag-relationship, show-tag-relationships" }, { "id": 2, "text": "@human: How should Event Storming integrate with Example Mapping? Should domain events from Event Storming be visible when doing Example Mapping for a story?", "deleted": false, "createdAt": "2025-11-01T17:51:23.300Z", "selected": true, "answer": "Yes, domain events visible during Example Mapping via transformation (policies→rules, hotspots→questions). Also used for tag suggestions when generating scenarios." }, { "id": 3, "text": "@human: Should Event Storming be part of foundation discovery (done once at project start) or per-epic/feature discovery (done multiple times)?", "deleted": false, "createdAt": "2025-11-01T17:51:25.922Z", "selected": true, "answer": "Both. Big Picture ES done at foundation level (foundation.json) for strategic bounded contexts. Process/Design ES done per epic/feature (work-units.json) for tactical discovery." }, { "id": 4, "text": "@human: What Event Storming elements should be tracked? Just domain events and commands, or also aggregates, policies, external systems, hotspots?", "deleted": false, "createdAt": "2025-11-01T17:51:27.304Z", "selected": true, "answer": "Track all: domain events, commands, aggregates, policies, external systems, bounded contexts, hotspots. This provides complete domain model for tag discovery and transformation to Example Mapping." } ], "nextQuestionId": 5, "blocks": [ "QUERY-001" ], "attachments": [ "spec/attachments/EXMAP-004/event-storming-tag-integration-no-colors.md", "spec/attachments/EXMAP-004/implementation-gap-analysis.md" ], "estimate": 5 }, "QUERY-001": { "id": "QUERY-001", "title": "Tag graph visualization for DDD domain relationships", "type": "story", "status": "blocked", "createdAt": "2025-11-01T17:53:09.076Z", "updatedAt": "2025-11-01T17:55:17.191Z", "description": "Create a tag graph that visualizes relationships between tags representing DDD domains, bounded contexts, and domain events discovered through Event Storming", "children": [], "userStory": { "role": "developer or architect", "action": "visualize domain relationships using a tag graph", "benefit": "I can understand bounded contexts and domain boundaries discovered through Event Storming" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T17:54:17.397Z" } ], "rules": [ { "id": 0, "text": "Tag graph should visualize relationships between tags that represent DDD concepts (domains, bounded contexts, aggregates, events)", "deleted": false, "createdAt": "2025-11-01T17:54:27.605Z" }, { "id": 1, "text": "Graph depends on Event Storming data (EXMAP-004) to discover domain boundaries and relationships", "deleted": false, "createdAt": "2025-11-01T17:54:28.213Z" }, { "id": 2, "text": "Current fspec has export-dependencies command for work unit dependency graphs, but no tag relationship graph", "deleted": false, "createdAt": "2025-11-01T17:54:28.812Z" }, { "id": 3, "text": "Tag relationships could be inferred from: tags used together on features, domain events from Event Storming, bounded context boundaries, or explicit relationships", "deleted": false, "createdAt": "2025-11-01T17:54:29.413Z" }, { "id": 4, "text": "Graph output should support multiple formats: Mermaid (for markdown), DOT (for Graphviz), JSON (for tools)", "deleted": false, "createdAt": "2025-11-01T17:54:31.102Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Run 'fspec export-tag-graph mermaid', outputs graph showing Auth domain linked to User domain, Checkpoint domain linked to Git domain, etc.", "deleted": false, "createdAt": "2025-11-01T17:54:47.314Z" }, { "id": 1, "text": "Event Storming identifies domain events UserRegistered, CheckpointCreated, tag graph shows these events clustered by bounded context (User Management, Git Operations)", "deleted": false, "createdAt": "2025-11-01T17:54:49.026Z" }, { "id": 2, "text": "Tags AUTH, USER, LOGIN appear together on 5 feature files, graph shows strong relationship between these tags suggesting a bounded context", "deleted": false, "createdAt": "2025-11-01T17:54:50.582Z" } ], "nextExampleId": 3, "questions": [ { "id": 0, "text": "@human: How should tag relationships be defined? Automatically inferred from co-occurrence, explicitly defined with commands, or derived from Event Storming data?", "deleted": false, "createdAt": "2025-11-01T17:55:04.586Z", "selected": false }, { "id": 1, "text": "@human: What should nodes represent? Individual tags, or grouped bounded contexts/domains containing multiple tags?", "deleted": false, "createdAt": "2025-11-01T17:55:06.230Z", "selected": false }, { "id": 2, "text": "@human: What should edges represent? Generic relationships, or typed relationships (contains, depends-on, communicates-with, etc.)?", "deleted": false, "createdAt": "2025-11-01T17:55:07.638Z", "selected": false }, { "id": 3, "text": "@human: Should the command be fspec export-tag-graph or fspec query-tag-graph to match existing query commands?", "deleted": false, "createdAt": "2025-11-01T17:55:09.200Z", "selected": false }, { "id": 4, "text": "@human: Should the graph be filterable by tag category, epic, or bounded context?", "deleted": false, "createdAt": "2025-11-01T17:55:10.791Z", "selected": false } ], "nextQuestionId": 5, "blockedBy": [ "EXMAP-004" ], "blockedReason": "Blocked by EXMAP-004" }, "INIT-015": { "id": "INIT-015", "title": "fspec init deletes config and templates instead of preserving them", "type": "bug", "status": "done", "createdAt": "2025-11-01T17:59:31.251Z", "updatedAt": "2025-11-01T19:06:05.014Z", "description": "fspec init should: (1) retain existing config in spec/fspec-config.json and only change the agent, (2) NOT delete existing templates for agents already installed (previous requirement that needs removal)", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T18:00:19.510Z" }, { "state": "testing", "timestamp": "2025-11-01T18:58:16.049Z" }, { "state": "implementing", "timestamp": "2025-11-01T19:00:05.841Z" }, { "state": "validating", "timestamp": "2025-11-01T19:01:47.478Z" }, { "state": "done", "timestamp": "2025-11-01T19:06:05.014Z" } ], "userStory": { "role": "developer using fspec", "action": "switch between AI agents using fspec init", "benefit": "my existing configuration and templates are preserved" }, "rules": [ { "id": 0, "text": "writeAgentConfig in agentRuntimeConfig.ts (lines 65-77) creates new config object with only agent field, overwriting existing config", "deleted": false, "createdAt": "2025-11-01T18:00:33.813Z" }, { "id": 1, "text": "removeOtherAgentFiles in init.ts (lines 193-223) deletes doc templates and slash commands for agents not being installed", "deleted": false, "createdAt": "2025-11-01T18:00:35.462Z" }, { "id": 2, "text": "Config file may contain: agent, tools.test.command, tools.qualityCheck.commands, and other user settings", "deleted": false, "createdAt": "2025-11-01T18:00:37.035Z" }, { "id": 3, "text": "Template deletion was a previous requirement that needs to be removed - users want to keep templates for all installed agents", "deleted": false, "createdAt": "2025-11-01T18:00:38.661Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "User has config with tools configured, runs fspec init to switch from claude to cursor, config is overwritten with only {agent: cursor}, tool config lost", "deleted": false, "createdAt": "2025-11-01T18:00:52.738Z" }, { "id": 1, "text": "User has both Claude and Cursor templates installed, switches to Aider, Claude and Cursor templates are deleted", "deleted": false, "createdAt": "2025-11-01T18:00:54.125Z" }, { "id": 2, "text": "CORRECT: User has config {agent: claude, tools: {...}}, runs fspec init cursor, config becomes {agent: cursor, tools: {...}}, templates preserved", "deleted": false, "createdAt": "2025-11-01T18:00:55.784Z" } ], "nextExampleId": 3, "questions": [ { "id": 0, "text": "@human: Should writeAgentConfig merge with existing config or read-modify-write? Current behavior is complete overwrite.", "deleted": false, "createdAt": "2025-11-01T18:01:08.478Z", "selected": true, "answer": "Read-modify-write: Read existing config, update only the 'agent' field, write back all other fields unchanged. This matches the existing pattern in configure-tools.ts and preserves user tool configurations." }, { "id": 1, "text": "@human: Should removeOtherAgentFiles be removed entirely, or modified to only remove when explicitly requested?", "deleted": false, "createdAt": "2025-11-01T18:01:10.288Z", "selected": true, "answer": "Remove the function entirely (never delete templates). Users should be able to have multiple agent templates installed simultaneously (e.g., both Claude and Cursor). No backward compatibility needed - breaking change is acceptable." }, { "id": 2, "text": "@human: Are there tests that expect template deletion behavior that will need to be updated or removed?", "deleted": false, "createdAt": "2025-11-01T18:01:11.805Z", "selected": true, "answer": "Yes, tests exist and need removal. Remove all tests, scenarios, and feature file content related to removeOtherAgentFiles and template deletion behavior. No backward compatibility preservation needed." } ], "nextQuestionId": 3, "estimate": 3, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-01T19:06:05.014Z" }, "BOARD-020": { "id": "BOARD-020", "title": "System reminder for backward transitions to specifying with cleanup guidance", "type": "story", "status": "specifying", "createdAt": "2025-11-01T18:04:36.021Z", "updatedAt": "2025-11-01T18:05:52.910Z", "description": "When a work unit moves backward from done/validating/implementing/testing to specifying, emit system-reminder to guide removal of outdated examples, scenarios, and tests to maintain consistency", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T18:04:43.437Z" } ], "userStory": { "role": "developer changing specifications", "action": "receive guidance for cleaning up outdated scenarios and tests", "benefit": "I maintain consistency when requirements change and work moves backward" }, "rules": [ { "id": 0, "text": "Backward transitions from done/validating/implementing/testing to specifying indicate requirement changes that may invalidate existing work", "deleted": false, "createdAt": "2025-11-01T18:04:56.585Z" }, { "id": 1, "text": "System-reminder should guide removal of: examples from work unit, scenarios from feature files, and associated test files", "deleted": false, "createdAt": "2025-11-01T18:04:58.126Z" }, { "id": 2, "text": "Related work units that depend on deprecated scenarios may also need to move back to specifying for consistency", "deleted": false, "createdAt": "2025-11-01T18:04:59.678Z" }, { "id": 3, "text": "Current update-work-unit-status allows backward transitions but provides no cleanup guidance", "deleted": false, "createdAt": "2025-11-01T18:05:01.204Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Work unit AUTH-001 in done state, requirements change, move back to specifying, system-reminder says: Remove examples from AUTH-001, delete scenarios from user-authentication.feature, remove test file user-authentication.test.ts", "deleted": false, "createdAt": "2025-11-01T18:05:18.611Z" }, { "id": 1, "text": "Work unit API-005 in implementing state, design flaw discovered, move back to specifying, system-reminder says: Remove outdated examples, update feature file to remove deprecated scenarios, check for tests that need removal", "deleted": false, "createdAt": "2025-11-01T18:05:20.158Z" }, { "id": 2, "text": "Work unit UI-010 depends on API-005 scenarios, API-005 moves back to specifying, system-reminder includes: Consider moving UI-010 back to specifying if it depends on deprecated API-005 scenarios", "deleted": false, "createdAt": "2025-11-01T18:05:21.893Z" } ], "nextExampleId": 3, "questions": [ { "id": 0, "text": "@human: Should the system-reminder list specific files to remove (scenarios, tests), or just provide general guidance?", "deleted": false, "createdAt": "2025-11-01T18:05:46.763Z", "selected": false }, { "id": 1, "text": "@human: Should fspec commands help with cleanup? E.g., fspec cleanup-work-unit AUTH-001 to remove linked scenarios/tests?", "deleted": false, "createdAt": "2025-11-01T18:05:48.102Z", "selected": false }, { "id": 2, "text": "@human: Should the reminder only appear when moving TO specifying, or also when moving to backlog?", "deleted": false, "createdAt": "2025-11-01T18:05:49.673Z", "selected": false }, { "id": 3, "text": "@human: Should the reminder automatically detect dependent work units and list them, or just provide general warning about checking dependencies?", "deleted": false, "createdAt": "2025-11-01T18:05:51.063Z", "selected": false }, { "id": 4, "text": "@human: What if no scenarios/tests exist yet (e.g., moving from testing back to specifying before tests written)? Skip reminder or show modified message?", "deleted": false, "createdAt": "2025-11-01T18:05:52.910Z", "selected": false } ], "nextQuestionId": 5 }, "CLI-013": { "id": "CLI-013", "title": "Validation script to check all commands are linked and help files exist", "type": "task", "status": "done", "createdAt": "2025-11-01T18:08:13.702Z", "updatedAt": "2025-11-01T18:38:23.364Z", "description": "Create a script that validates all fspec commands have corresponding help files and are properly linked in the command registry, returning list of issues if any exist", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T18:08:21.169Z" }, { "state": "implementing", "timestamp": "2025-11-01T18:16:07.948Z" }, { "state": "validating", "timestamp": "2025-11-01T18:26:56.434Z" }, { "state": "done", "timestamp": "2025-11-01T18:38:23.364Z" } ], "rules": [ { "id": 0, "text": "Script should check that every registered command has a corresponding help file (e.g., command 'foo' has 'foo-help.ts')", "deleted": false, "createdAt": "2025-11-01T18:08:31.732Z" }, { "id": 1, "text": "Script should check that every help file has a corresponding command registered in commander", "deleted": false, "createdAt": "2025-11-01T18:08:33.284Z" }, { "id": 2, "text": "Script should verify help files export the correct function signature expected by the help system", "deleted": false, "createdAt": "2025-11-01T18:08:35.130Z" }, { "id": 3, "text": "Script should return exit code 0 if all checks pass, non-zero if issues found", "deleted": false, "createdAt": "2025-11-01T18:08:36.817Z" }, { "id": 4, "text": "Script should output clear list of issues with file paths and what needs fixing", "deleted": false, "createdAt": "2025-11-01T18:08:38.366Z" }, { "id": 5, "text": "Script should be a standalone JavaScript file, not integrated into fspec CLI", "deleted": false, "createdAt": "2025-11-01T18:11:37.608Z" }, { "id": 6, "text": "Script should check src/commands/*-help.ts files specifically", "deleted": false, "createdAt": "2025-11-01T18:11:39.126Z" }, { "id": 7, "text": "Script should validate consistency in help content formatting across all help files", "deleted": false, "createdAt": "2025-11-01T18:11:40.709Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "Command 'add-diagram' exists but 'add-diagram-help.ts' is missing, script reports: Missing help file for command: add-diagram", "deleted": false, "createdAt": "2025-11-01T18:08:52.353Z" }, { "id": 1, "text": "File 'delete-foo-help.ts' exists but 'delete-foo' command not registered, script reports: Orphaned help file: delete-foo-help.ts", "deleted": false, "createdAt": "2025-11-01T18:08:53.883Z" }, { "id": 2, "text": "All commands properly linked with help files, script outputs: All commands validated successfully (checked 150 commands) and exits with code 0", "deleted": false, "createdAt": "2025-11-01T18:08:56.655Z" }, { "id": 3, "text": "Help file has empty USAGE section, script reports: Inconsistent help format in add-rule-help.ts: USAGE section is empty", "deleted": false, "createdAt": "2025-11-01T18:11:42.102Z" } ], "nextExampleId": 4, "questions": [ { "id": 0, "text": "@human: Should this be a standalone script in scripts/ directory, or a new fspec command like fspec validate-commands?", "deleted": false, "createdAt": "2025-11-01T18:08:58.574Z", "selected": true, "answer": "Standalone JavaScript file in scripts/ directory, NOT a fspec command" }, { "id": 1, "text": "@human: Should the script run automatically in CI/CD pipeline, or only manually when developing?", "deleted": false, "createdAt": "2025-11-01T18:09:00.664Z", "selected": true, "answer": "Can run both automatically in CI/CD and manually during development" }, { "id": 2, "text": "@human: Should it also check that help content is non-empty and properly formatted?", "deleted": false, "createdAt": "2025-11-01T18:09:02.360Z", "selected": true, "answer": "Yes, validate that help content is non-empty and properly formatted with consistent structure" } ], "nextQuestionId": 3, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-01T18:38:23.364Z" }, "BUG-054": { "id": "BUG-054", "title": "answer-question command pushes strings instead of RuleItem objects causing data corruption", "type": "bug", "status": "done", "createdAt": "2025-11-01T18:14:24.736Z", "updatedAt": "2025-11-01T18:37:38.978Z", "description": "answer-question with --add-to rule pushes raw string to rules array instead of RuleItem object with {id, text, deleted, createdAt}, causing display to show [undefined] undefined", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T18:31:20.620Z" }, { "state": "testing", "timestamp": "2025-11-01T18:34:04.678Z" }, { "state": "implementing", "timestamp": "2025-11-01T18:36:22.085Z" }, { "state": "validating", "timestamp": "2025-11-01T18:37:31.738Z" }, { "state": "done", "timestamp": "2025-11-01T18:37:38.978Z" } ], "rules": [ { "id": 0, "text": "answer-question command must create RuleItem objects with {id, text, deleted, createdAt} structure, NOT raw strings", "deleted": false, "createdAt": "2025-11-01T18:31:56.696Z" }, { "id": 1, "text": "RuleItem id must use workUnit.nextRuleId++ for unique sequential IDs", "deleted": false, "createdAt": "2025-11-01T18:32:03.159Z" }, { "id": 2, "text": "Same fix must apply to assumptions array when using --add-to assumption", "deleted": false, "createdAt": "2025-11-01T18:33:14.472Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Running 'fspec answer-question CLI-013 0 --answer \"Yes\" --add-to rule' pushes string \"Yes\" instead of {id: N, text: \"Yes\", deleted: false, createdAt: ...}", "deleted": false, "createdAt": "2025-11-01T18:33:20.899Z" }, { "id": 1, "text": "After fix, answer-question creates proper RuleItem: {id: 5, text: \"Script should be standalone\", deleted: false, createdAt: \"2025-11-01T18:11:37.608Z\"}", "deleted": false, "createdAt": "2025-11-01T18:33:27.435Z" }, { "id": 2, "text": "show-work-unit displays corrupt data as '[undefined] undefined' when rules array contains raw strings", "deleted": false, "createdAt": "2025-11-01T18:33:33.173Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-01T18:37:38.978Z" }, "TUI-012": { "id": "TUI-012", "title": "Display attachments in work unit details panel", "type": "story", "status": "done", "createdAt": "2025-11-01T19:20:32.473Z", "updatedAt": "2025-11-04T11:57:00.385Z", "description": "Show list of attachments in the TUI details view when user presses Enter on a work unit in the interactive Kanban board", "children": [], "userStory": { "role": "developer using fspec TUI", "action": "view attachments associated with a work unit", "benefit": "I can see what supporting materials are available without leaving the board view" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T19:20:53.951Z" }, { "state": "testing", "timestamp": "2025-11-04T11:08:42.086Z" }, { "state": "implementing", "timestamp": "2025-11-04T11:11:31.650Z" }, { "state": "specifying", "timestamp": "2025-11-04T11:14:44.252Z" }, { "state": "testing", "timestamp": "2025-11-04T11:37:04.283Z" }, { "state": "implementing", "timestamp": "2025-11-04T11:41:05.306Z" }, { "state": "validating", "timestamp": "2025-11-04T11:43:08.545Z" }, { "state": "done", "timestamp": "2025-11-04T11:46:37.731Z" } ], "rules": [ { "id": 0, "text": "When a work unit has no attachments, show 'No attachments'", "deleted": false, "createdAt": "2025-11-04T11:25:26.396Z" }, { "id": 1, "text": "When a work unit has attachments, show each filename extracted from the path", "deleted": false, "createdAt": "2025-11-04T11:25:28.298Z" }, { "id": 2, "text": "Attachments section should fit within the existing 5-line details panel layout", "deleted": false, "createdAt": "2025-11-04T11:25:30.480Z" }, { "id": 3, "text": "Attachments appear on line 4 of the details panel, reducing description from 3 lines to 2 lines", "deleted": false, "createdAt": "2025-11-04T11:31:25.886Z" }, { "id": 4, "text": "When attachments don't fit on line 4, truncate with ellipsis showing count (e.g., 'mockup.png, diagram.png, ...3 more')", "deleted": false, "createdAt": "2025-11-04T11:32:47.312Z" }, { "id": 5, "text": "Display keybinding hint showing which key opens the full attachments dialog (TUI-013)", "deleted": false, "createdAt": "2025-11-04T11:32:49.063Z" }, { "id": 6, "text": "Attachments appear on line 3 of description area (replacing the 3rd description line), reducing description from 3 lines to 2 lines", "deleted": false, "createdAt": "2025-11-04T11:33:34.570Z" } ], "nextRuleId": 7, "examples": [ { "id": 0, "text": "Work unit TUI-012 has no attachments → Details panel shows 'No attachments'", "deleted": false, "createdAt": "2025-11-04T11:29:03.449Z" }, { "id": 1, "text": "Work unit TUI-012 has one attachment at spec/attachments/TUI-012/mockup.png → Details panel shows 'mockup.png'", "deleted": false, "createdAt": "2025-11-04T11:29:05.386Z" }, { "id": 2, "text": "Work unit AUTH-001 has two attachments (spec/attachments/AUTH-001/login-flow.png and spec/attachments/AUTH-001/requirements.pdf) → Details panel shows both 'login-flow.png' and 'requirements.pdf'", "deleted": false, "createdAt": "2025-11-04T11:29:08.075Z" }, { "id": 3, "text": "Work unit has 5 attachments but line 4 only fits 2 filenames → Shows 'file1.png, file2.pdf, ...3 more' with keybinding hint", "deleted": false, "createdAt": "2025-11-04T11:32:58.300Z" } ], "nextExampleId": 4, "estimate": 5, "questions": [ { "id": 0, "text": "@human: If there are many attachments that don't fit in the available space, should we truncate the list (e.g., show first 3 and '...2 more') or make the section scrollable?", "deleted": false, "createdAt": "2025-11-04T11:31:17.136Z", "selected": true, "answer": "Show attachments inline on line 4, truncate if too many (e.g., 'mockup.png, diagram.png, ...3 more'), and display keybinding hint to open full list dialog" }, { "id": 1, "text": "@human: TUI-013 mentions 'selecting an attachment and pressing o to open' - should TUI-012 include selection UI (highlighting attachments with arrow keys), or is selection UI part of TUI-013?", "deleted": false, "createdAt": "2025-11-04T11:31:19.111Z", "selected": true, "answer": "TUI-012 is display-only (no selection). Show attachments list on line 4 with keybinding hint. TUI-013 will add the dialog/VirtualList/selection/opening functionality" } ], "nextQuestionId": 2, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-04T11:46:37.730Z", "attachments": [ "spec/attachments/TUI-012/test-diagram.png" ] }, "TUI-013": { "id": "TUI-013", "title": "Open attachments in browser from details panel", "type": "story", "status": "done", "createdAt": "2025-11-01T19:24:10.959Z", "updatedAt": "2025-11-04T12:01:58.369Z", "description": "Allow users to open attachment files in the default browser when viewing work unit details in the TUI, using the same 'open' package that cage uses for launching API docs", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T19:24:18.440Z" }, { "state": "testing", "timestamp": "2025-11-04T11:52:22.255Z" }, { "state": "implementing", "timestamp": "2025-11-04T11:53:38.277Z" }, { "state": "validating", "timestamp": "2025-11-04T12:00:40.646Z" }, { "state": "done", "timestamp": "2025-11-04T12:01:58.370Z" } ], "userStory": { "role": "developer viewing work unit attachments in fspec TUI", "action": "open an attachment file in my default browser", "benefit": "I can quickly view diagrams, mockups, and documents without leaving the TUI workflow" }, "rules": [ { "id": 0, "text": "User should be able to select an attachment and press 'o' to open it", "deleted": false, "createdAt": "2025-11-01T19:24:35.544Z" }, { "id": 1, "text": "Opening attachment should use 'open' npm package for cross-platform browser launching", "deleted": false, "createdAt": "2025-11-01T19:24:36.046Z" }, { "id": 2, "text": "Attachment file path should be converted from relative to absolute path before opening", "deleted": false, "createdAt": "2025-11-01T19:24:36.536Z" }, { "id": 3, "text": "Opening should use file:// protocol for local files", "deleted": false, "createdAt": "2025-11-01T19:24:37.024Z" }, { "id": 4, "text": "TUI should remain open after launching browser (non-blocking)", "deleted": false, "createdAt": "2025-11-01T19:24:37.550Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User selects 'diagram.png' attachment and presses 'o', browser opens file:///path/to/spec/attachments/TUI-012/diagram.png", "deleted": false, "createdAt": "2025-11-01T19:24:45.395Z" }, { "id": 1, "text": "User opens PDF attachment, browser opens it in default PDF viewer", "deleted": false, "createdAt": "2025-11-01T19:24:45.892Z" }, { "id": 2, "text": "After opening attachment, TUI remains active and user can continue working", "deleted": false, "createdAt": "2025-11-01T19:24:46.387Z" }, { "id": 3, "text": "Opening works on macOS (open command), Windows (start), and Linux (xdg-open)", "deleted": false, "createdAt": "2025-11-01T19:24:46.885Z" } ], "nextExampleId": 4, "dependsOn": [ "TUI-012" ], "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-04T12:01:58.369Z" }, "RES-007": { "id": "RES-007", "title": "AST code researcher for pattern detection and deep analysis", "type": "story", "status": "done", "createdAt": "2025-11-01T19:31:38.476Z", "updatedAt": "2025-11-08T03:29:15.188Z", "description": "Create an AST-based code research backend that analyzes code structure, detects patterns, finds similar code, and provides deep insights using TypeScript/JavaScript AST parsing. Integrates with fspec research command as a registered backend.", "epic": "example-driven-discovery", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-01T19:31:51.335Z" }, { "state": "testing", "timestamp": "2025-11-08T03:16:59.543Z" }, { "state": "implementing", "timestamp": "2025-11-08T03:20:34.976Z" }, { "state": "validating", "timestamp": "2025-11-08T03:28:46.318Z" }, { "state": "done", "timestamp": "2025-11-08T03:29:15.189Z" } ], "dependsOn": [ "RES-001" ], "userStory": { "role": "AI agent or developer using fspec", "action": "analyze code structure using AST parsing during Example Mapping", "benefit": "I can discover patterns, find similar code, and get deep insights without manual code review" }, "rules": [ { "id": 0, "text": "Use tree-sitter as the AST parsing foundation (supports 40+ languages including TypeScript, JavaScript, Python, Go, Rust, Java, C++)", "deleted": false, "createdAt": "2025-11-01T19:34:20.601Z" }, { "id": 1, "text": "Use tree-sitter query language for pattern matching (find specific code constructs across syntax trees)", "deleted": false, "createdAt": "2025-11-01T19:34:22.081Z" }, { "id": 2, "text": "Support error-tolerant parsing (analyze incomplete or broken code without failing)", "deleted": false, "createdAt": "2025-11-01T19:34:23.458Z" }, { "id": 3, "text": "Integrate as 'ast' research backend in 'fspec research' command (auto-discovered from spec/research-scripts/)", "deleted": false, "createdAt": "2025-11-01T19:34:25.165Z" }, { "id": 4, "text": "Support common pattern queries: function definitions, class declarations, imports, exports, variable assignments, conditionals, loops", "deleted": false, "createdAt": "2025-11-01T19:34:26.843Z" }, { "id": 5, "text": "Analyze code complexity metrics: cyclomatic complexity, nesting depth, function length, parameter count", "deleted": false, "createdAt": "2025-11-01T19:34:28.478Z" }, { "id": 6, "text": "Find structurally similar code using AST pattern matching (not text-based regex)", "deleted": false, "createdAt": "2025-11-01T19:34:29.985Z" }, { "id": 7, "text": "Return structured JSON results with file paths, line numbers, matched code snippets, and AST node types", "deleted": false, "createdAt": "2025-11-01T19:34:31.366Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "AI agent runs 'fspec research --tool=ast --query=\"find all async functions\"', gets JSON results with file paths and line numbers for every async function in the codebase", "deleted": false, "createdAt": "2025-11-01T19:34:44.532Z" }, { "id": 1, "text": "Developer researches 'functions with more than 5 parameters', AST tool analyzes complexity and returns list of functions exceeding parameter count threshold", "deleted": false, "createdAt": "2025-11-01T19:34:46.139Z" }, { "id": 2, "text": "During Example Mapping, AI needs to find similar authentication code, queries 'find code patterns similar to src/auth/login.ts', gets structurally similar functions across Python, TypeScript, and Go files", "deleted": false, "createdAt": "2025-11-01T19:34:47.807Z" }, { "id": 3, "text": "AI agent analyzes incomplete code file with syntax errors, tree-sitter parses what it can and returns partial AST for the valid portions", "deleted": false, "createdAt": "2025-11-01T19:34:49.183Z" }, { "id": 4, "text": "Developer queries 'classes implementing interface UserRepository', AST tool uses tree-sitter queries to find all implementing classes with file locations and code snippets", "deleted": false, "createdAt": "2025-11-01T19:34:50.752Z" }, { "id": 5, "text": "AI searches for functions with high cyclomatic complexity (>10) to identify refactoring candidates, gets JSON with file paths and complexity scores", "deleted": false, "createdAt": "2025-11-08T03:14:58.477Z" }, { "id": 6, "text": "Developer queries for all exported functions to generate API documentation, AST tool extracts function signatures and JSDoc comments", "deleted": false, "createdAt": "2025-11-08T03:14:59.011Z" }, { "id": 7, "text": "AI agent looks for unused imports across TypeScript files, tree-sitter parses import statements and checks for usage in AST", "deleted": false, "createdAt": "2025-11-08T03:14:59.524Z" } ], "nextExampleId": 8, "architectureNotes": [ { "id": 0, "text": "Uses tree-sitter Node.js bindings (node-tree-sitter or web-tree-sitter) for AST parsing across 40+ languages", "deleted": false, "createdAt": "2025-11-08T03:15:05.875Z" }, { "id": 1, "text": "Implements as Node.js script (#!/usr/bin/env node) in spec/research-scripts/ast with executable permissions for auto-discovery", "deleted": false, "createdAt": "2025-11-08T03:15:18.672Z" }, { "id": 2, "text": "Uses tree-sitter S-expression queries for pattern matching (similar to AST-grep but more powerful)", "deleted": false, "createdAt": "2025-11-08T03:15:19.213Z" }, { "id": 3, "text": "Supports --query, --file, --format (json/markdown/text), --language flags for CLI interface", "deleted": false, "createdAt": "2025-11-08T03:15:19.755Z" }, { "id": 4, "text": "Returns JSON schema: {matches: [{file, startLine, endLine, code, nodeType, metadata}], stats: {filesScanned, matchCount}}", "deleted": false, "createdAt": "2025-11-08T03:15:20.312Z" }, { "id": 5, "text": "Includes FSPEC_TEST_MODE=1 support for testing without actual AST parsing (returns mock data)", "deleted": false, "createdAt": "2025-11-08T03:15:20.843Z" } ], "nextNoteId": 6, "estimate": 8, "questions": [], "nextQuestionId": 0, "updated": "2025-11-08T03:29:15.188Z" }, "CLEAN-003": { "id": "CLEAN-003", "title": "Remove token recording functionality", "type": "story", "status": "done", "createdAt": "2025-11-02T01:08:11.490Z", "updatedAt": "2025-11-02T03:08:34.173Z", "description": "Remove unreliable token tracking code including record-tokens command, actualTokens field, feature files, and all related infrastructure. Token tracking proved impractical due to self-reporting inaccuracy (estimated 30-40% reliability).", "children": [], "userStory": { "role": "developer maintaining fspec", "action": "remove all token recording functionality", "benefit": "the codebase is cleaner and doesn't contain unreliable features" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-02T01:08:29.643Z" }, { "state": "testing", "timestamp": "2025-11-02T02:59:55.823Z" }, { "state": "implementing", "timestamp": "2025-11-02T03:01:09.198Z" }, { "state": "validating", "timestamp": "2025-11-02T03:03:19.401Z" }, { "state": "done", "timestamp": "2025-11-02T03:08:34.173Z" } ], "rules": [ { "id": 0, "text": "MUST remove src/commands/record-tokens.ts and src/commands/record-tokens-help.ts", "deleted": false, "createdAt": "2025-11-02T01:08:39.923Z" }, { "id": 1, "text": "MUST remove actualTokens field from WorkUnit interface in src/types/index.ts", "deleted": false, "createdAt": "2025-11-02T01:08:40.405Z" }, { "id": 2, "text": "MUST remove record-tokens import and registration from src/index.ts", "deleted": false, "createdAt": "2025-11-02T01:08:40.886Z" }, { "id": 3, "text": "MUST remove record-tokens examples from src/help.ts", "deleted": false, "createdAt": "2025-11-02T01:08:41.364Z" }, { "id": 4, "text": "MUST remove or update tests that reference actualTokens or recordTokens", "deleted": false, "createdAt": "2025-11-02T01:08:41.848Z" }, { "id": 5, "text": "MUST remove spec/features/ai-token-usage-tracking.feature and its .coverage file", "deleted": false, "createdAt": "2025-11-02T01:08:42.327Z" }, { "id": 6, "text": "MUST preserve record-iteration and query-metrics commands (they're separate from token tracking)", "deleted": false, "createdAt": "2025-11-02T01:08:42.819Z" }, { "id": 7, "text": "MUST update any documentation that mentions token recording", "deleted": false, "createdAt": "2025-11-02T01:08:43.304Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "Delete src/commands/record-tokens.ts file (102 lines)", "deleted": false, "createdAt": "2025-11-02T01:08:52.393Z" }, { "id": 1, "text": "Delete src/commands/record-tokens-help.ts file (36 lines)", "deleted": false, "createdAt": "2025-11-02T01:08:52.875Z" }, { "id": 2, "text": "Remove 'actualTokens?: number' from WorkUnit interface", "deleted": false, "createdAt": "2025-11-02T01:08:53.357Z" }, { "id": 3, "text": "Remove line 109 from src/index.ts: import { registerRecordTokensCommand } from './commands/record-tokens'", "deleted": false, "createdAt": "2025-11-02T01:08:53.854Z" }, { "id": 4, "text": "Remove lines 1079-1081 from src/help.ts showing record-tokens examples", "deleted": false, "createdAt": "2025-11-02T01:08:54.367Z" }, { "id": 5, "text": "Update work-unit-estimation-and-metrics.test.ts to remove token recording scenario (lines 138-173)", "deleted": false, "createdAt": "2025-11-02T01:08:54.862Z" }, { "id": 6, "text": "Delete spec/features/ai-token-usage-tracking.feature (55 lines)", "deleted": false, "createdAt": "2025-11-02T01:08:55.349Z" }, { "id": 7, "text": "Delete spec/features/ai-token-usage-tracking.feature.coverage", "deleted": false, "createdAt": "2025-11-02T01:08:55.830Z" } ], "nextExampleId": 8, "architectureNotes": [ { "id": 0, "text": "Removal rationale: Token tracking via AI self-reporting is unreliable (30-40% accuracy). AI agents don't have access to actual token counts and would be guessing. Automatic extraction from Claude Code logs is not feasible without reverse engineering. API-level tracking only works if we control the API calls, which we don't in Claude Code. The feature adds maintenance burden without providing reliable data.", "deleted": false, "createdAt": "2025-11-02T01:09:03.934Z" } ], "nextNoteId": 1, "estimate": 2, "questions": [], "nextQuestionId": 0, "updated": "2025-11-02T03:08:34.173Z" }, "BUG-055": { "id": "BUG-055", "title": "Attachment files duplicated in spec/attachments/ and spec/attachments/[ID]/", "type": "bug", "status": "done", "createdAt": "2025-11-02T06:29:11.069Z", "updatedAt": "2025-11-03T01:40:52.218Z", "description": "When adding an attachment to a work unit, files appear in both spec/attachments/ (root) and spec/attachments/[WORK-UNIT-ID]/ directories. Expected behavior: attachments should only be stored in the work unit specific directory (spec/attachments/[WORK-UNIT-ID]/).", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T01:30:24.872Z" }, { "state": "testing", "timestamp": "2025-11-03T01:32:15.277Z" }, { "state": "implementing", "timestamp": "2025-11-03T01:33:13.951Z" }, { "state": "validating", "timestamp": "2025-11-03T01:33:53.178Z" }, { "state": "done", "timestamp": "2025-11-03T01:40:52.219Z" } ], "rules": [ { "id": 0, "text": "Attachments MUST be stored ONLY in spec/attachments/{work-unit-id}/ directory", "deleted": false, "createdAt": "2025-11-03T01:30:40.730Z" }, { "id": 1, "text": "Attachments MUST NOT appear in spec/attachments/ root directory", "deleted": false, "createdAt": "2025-11-03T01:30:42.143Z" }, { "id": 2, "text": "When copying attachments from spec/attachments/ root, the source file MUST be deleted after successful copy", "deleted": false, "createdAt": "2025-11-03T01:30:43.394Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "File created in spec/attachments/CONFIG-003-integration-gap-analysis.md, then fspec add-attachment called, results in duplication in both root and CONFIG-003/ subdirectory", "deleted": false, "createdAt": "2025-11-03T01:30:52.445Z" }, { "id": 1, "text": "User adds attachment from external path (e.g., /tmp/diagram.png), file copied to spec/attachments/{work-unit-id}/diagram.png, original stays in /tmp (correct behavior)", "deleted": false, "createdAt": "2025-11-03T01:30:54.103Z" }, { "id": 2, "text": "After fix, files in spec/attachments/ root that get attached should be moved (not copied) to work unit subdirectory", "deleted": false, "createdAt": "2025-11-03T01:30:55.388Z" } ], "nextExampleId": 3, "userStory": { "role": "developer using fspec", "action": "add attachments to work units", "benefit": "files are stored in the correct location without duplication" }, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-03T01:40:52.218Z" }, "BUG-056": { "id": "BUG-056", "title": "Work unit IDs reused after deletion violating immutability principle", "type": "bug", "status": "done", "createdAt": "2025-11-02T08:41:34.297Z", "updatedAt": "2025-11-02T09:54:32.702Z", "children": [], "attachments": [ "spec/attachments/BUG-056/bug-056-ultrathink-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-02T09:29:35.027Z" }, { "state": "testing", "timestamp": "2025-11-02T09:33:21.875Z" }, { "state": "implementing", "timestamp": "2025-11-02T09:39:40.042Z" }, { "state": "validating", "timestamp": "2025-11-02T09:53:47.815Z" }, { "state": "done", "timestamp": "2025-11-02T09:54:32.702Z" } ], "userStory": { "role": "developer using fspec", "action": "create work units with guaranteed unique IDs", "benefit": "IDs are never reused and git history remains unambiguous" }, "rules": [ { "id": 0, "text": "Work unit IDs must never be reused after deletion", "deleted": false, "createdAt": "2025-11-02T09:29:51.863Z" }, { "id": 1, "text": "Each prefix maintains a high water mark counter that never decreases", "deleted": false, "createdAt": "2025-11-02T09:29:53.391Z" }, { "id": 2, "text": "High water mark persists in work-units.json as prefixCounters field", "deleted": false, "createdAt": "2025-11-02T09:29:54.893Z" }, { "id": 3, "text": "Migration calculates initial high water marks from existing IDs for backward compatibility", "deleted": false, "createdAt": "2025-11-02T09:29:56.216Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Create BUG-001, BUG-002, BUG-003. Delete BUG-003. Next bug gets ID BUG-004 (not BUG-003)", "deleted": false, "createdAt": "2025-11-02T09:30:08.108Z" }, { "id": 1, "text": "Create AUTH-001, DASH-005, TASK-010. High water marks: BUG=0, AUTH=1, DASH=5, TASK=10", "deleted": false, "createdAt": "2025-11-02T09:30:09.738Z" }, { "id": 2, "text": "Load work-units.json without prefixCounters field. Migration scans existing IDs and sets counters automatically", "deleted": false, "createdAt": "2025-11-02T09:30:11.368Z" }, { "id": 3, "text": "Existing project with BUG-054 as highest bug. Migration sets prefixCounters.BUG=54. Next bug gets BUG-055", "deleted": false, "createdAt": "2025-11-02T09:30:12.837Z" } ], "nextExampleId": 4, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-02T09:54:32.702Z" }, "CLI-014": { "id": "CLI-014", "title": "Report bug to GitHub with AI assistance", "type": "story", "status": "done", "createdAt": "2025-11-02T11:00:09.621Z", "updatedAt": "2025-11-03T02:22:09.154Z", "description": "Interactive command to report bugs using browser launcher and AI-driven analysis similar to fspec review", "children": [], "attachments": [ "spec/attachments/CLI-014/REPORT-BUG-FEATURE-SPEC.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T01:54:34.346Z" }, { "state": "testing", "timestamp": "2025-11-03T01:58:41.491Z" }, { "state": "implementing", "timestamp": "2025-11-03T02:04:30.838Z" }, { "state": "validating", "timestamp": "2025-11-03T02:18:05.010Z" }, { "state": "done", "timestamp": "2025-11-03T02:22:09.154Z" } ], "userStory": { "role": "developer using fspec who encounters a bug", "action": "report it to GitHub through an interactive guided process", "benefit": "I can provide comprehensive bug information without manually writing issue reports" }, "rules": [ { "id": 0, "text": "Bug reports must include system context (fspec version, node version, OS, platform)", "deleted": false, "createdAt": "2025-11-03T01:55:03.793Z" }, { "id": 1, "text": "All content must be properly URL-encoded for GitHub query parameters", "deleted": false, "createdAt": "2025-11-03T01:55:05.133Z" }, { "id": 2, "text": "Browser must be accessible to open GitHub issue creation page", "deleted": false, "createdAt": "2025-11-03T01:55:06.641Z" }, { "id": 3, "text": "Markdown formatting must be preserved when rendered in GitHub", "deleted": false, "createdAt": "2025-11-03T01:55:08.060Z" }, { "id": 4, "text": "Default labels should be 'bug,needs-triage' for new bug reports", "deleted": false, "createdAt": "2025-11-03T01:55:09.600Z" }, { "id": 5, "text": "Users must confirm before opening browser", "deleted": false, "createdAt": "2025-11-03T01:55:10.853Z" }, { "id": 6, "text": "Work unit context should be included if user is working on a work unit", "deleted": false, "createdAt": "2025-11-03T01:55:12.239Z" }, { "id": 7, "text": "Git context (branch, uncommitted changes) should be included if available", "deleted": false, "createdAt": "2025-11-03T01:55:13.932Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "User runs 'fspec report-bug-to-github', answers AI questions about the bug, sees formatted preview, confirms, and browser opens to GitHub with pre-filled issue form", "deleted": false, "createdAt": "2025-11-03T01:55:31.176Z" }, { "id": 1, "text": "User working on AUTH-001 encounters bug, runs report command, generated issue includes work unit ID, title, status, and link to feature file", "deleted": false, "createdAt": "2025-11-03T01:55:32.890Z" }, { "id": 2, "text": "User with uncommitted git changes reports bug, issue includes current branch name and note about uncommitted changes", "deleted": false, "createdAt": "2025-11-03T01:55:34.340Z" }, { "id": 3, "text": "fspec command crashes with ENOENT error, user runs report-bug-to-github, command detects recent error log and includes stack trace in bug report", "deleted": false, "createdAt": "2025-11-03T01:55:35.965Z" }, { "id": 4, "text": "AI generates bug report preview, user decides to edit title, command allows editing, user confirms, browser opens with edited content", "deleted": false, "createdAt": "2025-11-03T01:55:37.786Z" }, { "id": 5, "text": "Bug report contains code with special characters (\", &, <, >) and markdown code blocks, GitHub URL properly encodes everything, markdown renders correctly in GitHub issue", "deleted": false, "createdAt": "2025-11-03T01:55:39.523Z" } ], "nextExampleId": 6, "estimate": 8, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-03T02:22:09.154Z" }, "HELP-005": { "id": "HELP-005", "title": "Complete Command Help Documentation", "type": "task", "status": "done", "createdAt": "2025-11-02T11:41:51.933Z", "updatedAt": "2025-11-02T11:54:19.498Z", "description": "Ensure all fspec commands have properly formatted help documentation. Fix 8 format inconsistencies (missing USAGE sections, empty EXAMPLES), create 6 missing help files (add-capability, add-persona, remove-capability, remove-persona, display-board, tag), and resolve 3 orphaned help files (board-help.ts, help-help.ts, register-tag-help.ts).", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-02T11:42:36.502Z" }, { "state": "implementing", "timestamp": "2025-11-02T11:42:51.322Z" }, { "state": "validating", "timestamp": "2025-11-02T11:50:09.015Z" }, { "state": "done", "timestamp": "2025-11-02T11:54:19.499Z" } ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-02T11:54:19.498Z" }, "BUG-057": { "id": "BUG-057", "title": "Fix incorrect command name in discover-foundation system reminder for problemSpace.primaryProblem.title", "type": "bug", "status": "done", "createdAt": "2025-11-03T00:26:16.571Z", "updatedAt": "2025-11-03T00:35:51.673Z", "description": "The discover-foundation command emits incorrect system reminder on line 132. For field 'problemSpace.primaryProblem.title', it says 'Run: fspec update-foundation problemDefinition' but should say 'Run: fspec update-foundation problemTitle'. The problemDefinition command updates the description field, not the title field. See: src/commands/discover-foundation.ts:132 and src/commands/update-foundation.ts:151-164", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T00:27:17.432Z" }, { "state": "testing", "timestamp": "2025-11-03T00:29:44.698Z" }, { "state": "implementing", "timestamp": "2025-11-03T00:31:48.686Z" }, { "state": "validating", "timestamp": "2025-11-03T00:32:20.289Z" }, { "state": "done", "timestamp": "2025-11-03T00:35:51.674Z" } ], "userStory": { "role": "AI agent using fspec discover-foundation", "action": "receive correct command name in system reminder for problemSpace.primaryProblem.title field", "benefit": "I can successfully update the correct field without confusion" }, "rules": [ { "id": 0, "text": "System reminder for problemSpace.primaryProblem.title must instruct to use 'problemTitle' command, not 'problemDefinition'", "deleted": false, "createdAt": "2025-11-03T00:27:42.202Z" }, { "id": 1, "text": "Command name 'problemTitle' updates problemSpace.primaryProblem.title field", "deleted": false, "createdAt": "2025-11-03T00:27:43.968Z" }, { "id": 2, "text": "Command name 'problemDefinition' updates problemSpace.primaryProblem.description field", "deleted": false, "createdAt": "2025-11-03T00:27:45.473Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "AI agent receives system reminder for 'problemSpace.primaryProblem.title' field with instruction: 'Run: fspec update-foundation problemTitle \"Problem Title\"'", "deleted": false, "createdAt": "2025-11-03T00:27:46.990Z" }, { "id": 1, "text": "AI agent runs 'fspec update-foundation problemTitle \"User Authentication Issues\"' and foundation.json.draft shows problemSpace.primaryProblem.title updated correctly", "deleted": false, "createdAt": "2025-11-03T00:27:48.441Z" }, { "id": 2, "text": "Before fix: System reminder says 'fspec update-foundation problemDefinition' for title field (incorrect)", "deleted": false, "createdAt": "2025-11-03T00:27:49.845Z" }, { "id": 3, "text": "After fix: System reminder says 'fspec update-foundation problemTitle' for title field (correct)", "deleted": false, "createdAt": "2025-11-03T00:27:51.332Z" } ], "nextExampleId": 4, "estimate": 2, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-03T00:35:51.673Z" }, "DISC-002": { "id": "DISC-002", "title": "Template persona with placeholders remains in finalized foundation.json", "type": "bug", "status": "done", "createdAt": "2025-11-03T00:43:30.456Z", "updatedAt": "2025-11-03T00:56:48.982Z", "description": "When using discover-foundation workflow, template personas with [QUESTION:] placeholders persist in the finalized foundation.json file even after adding real personas with add-persona command. Root cause: discover-foundation --finalize doesn't check allFieldsComplete before writing foundation.json.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T00:43:59.392Z" }, { "state": "testing", "timestamp": "2025-11-03T00:46:26.016Z" }, { "state": "implementing", "timestamp": "2025-11-03T00:48:38.260Z" }, { "state": "validating", "timestamp": "2025-11-03T00:49:38.880Z" }, { "state": "done", "timestamp": "2025-11-03T00:56:48.982Z" } ], "rules": [ { "id": 0, "text": "The discover-foundation --finalize command MUST check if allFieldsComplete is false before writing foundation.json", "deleted": false, "createdAt": "2025-11-03T00:44:10.576Z" }, { "id": 1, "text": "If allFieldsComplete is false (placeholder fields remain), finalization MUST fail with a clear error message listing which fields still have placeholders", "deleted": false, "createdAt": "2025-11-03T00:44:11.087Z" }, { "id": 2, "text": "Template personas contain [QUESTION:] markers in name, description, or goals fields", "deleted": false, "createdAt": "2025-11-03T00:44:13.063Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "User runs discover-foundation (creates draft with template persona containing [QUESTION:]), then runs add-persona 'AI Agent' 'description' --goal 'goal', then runs add-capability 'Capability' 'desc', then runs discover-foundation --finalize. Currently: finalization succeeds with template persona still in file. Expected: finalization should fail with error about unfilled personas field.", "deleted": false, "createdAt": "2025-11-03T00:44:14.667Z" }, { "id": 1, "text": "Draft contains personas: [{name: '[QUESTION: Who?]', description: '[QUESTION: Who?]', goals: ['[QUESTION: What?]']}, {name: 'Real Person', description: 'A real user', goals: ['Achieve things']}]. scanDraftForNextField detects placeholder in personas array, sets allFieldsComplete=false. Finalize should check this flag and reject with error.", "deleted": false, "createdAt": "2025-11-03T00:44:16.068Z" } ], "nextExampleId": 2, "architectureNotes": [ { "id": 0, "text": "Root cause in discover-foundation.ts:287-383. The finalize process computes allFieldsComplete (line 297) but never checks it before writing foundation.json (line 352). Fix: Add check after line 297 to reject finalization if allFieldsComplete is false.", "deleted": false, "createdAt": "2025-11-03T00:44:28.860Z" }, { "id": 1, "text": "scanDraftForNextField() at lines 31-87 correctly detects placeholders by checking if stringified field values contain '[QUESTION:' or '[DETECTED:'. For personas array, it stringifies the entire array, so template personas with placeholders are correctly flagged.", "deleted": false, "createdAt": "2025-11-03T00:44:30.242Z" }, { "id": 2, "text": "Schema validation (validateGenericFoundationObject) only checks structure, not content. A persona with name='[QUESTION: Who?]' passes validation because it's a valid string with minLength>1. This is why we need the allFieldsComplete check.", "deleted": false, "createdAt": "2025-11-03T00:44:31.579Z" } ], "nextNoteId": 3, "userStory": { "role": "developer using fspec for project foundation setup", "action": "finalize the foundation draft with discover-foundation --finalize", "benefit": "I receive clear error messages when placeholder fields remain unfilled" }, "estimate": 3, "questions": [], "nextQuestionId": 0, "updated": "2025-11-03T00:56:48.982Z" }, "COV-053": { "id": "COV-053", "title": "Step validation system-reminder doesn't explain proper comment placement and deduplication", "type": "bug", "status": "done", "createdAt": "2025-11-03T01:00:51.400Z", "updatedAt": "2025-11-03T01:10:50.578Z", "description": "The system-reminder for step validation failures only says 'Add to test file: // @step ...' without explaining that AI should remove duplicate Given/When/Then comments and place step comments near the code that executes each step.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T01:00:59.024Z" }, { "state": "testing", "timestamp": "2025-11-03T01:03:51.191Z" }, { "state": "implementing", "timestamp": "2025-11-03T01:05:39.525Z" }, { "state": "validating", "timestamp": "2025-11-03T01:07:18.584Z" }, { "state": "done", "timestamp": "2025-11-03T01:10:50.579Z" } ], "userStory": { "role": "AI agent using fspec for test coverage linking", "action": "receive clear guidance about step comment placement", "benefit": "I correctly place step comments near relevant code and avoid duplicating existing comments" }, "rules": [ { "id": 0, "text": "Step validation system-reminder MUST explain that step comments should be placed near the code that executes each step, not just anywhere in the test", "deleted": false, "createdAt": "2025-11-03T01:01:13.815Z" }, { "id": 1, "text": "Step validation system-reminder MUST explain that AI should remove duplicate Given/When/Then comments before adding @step comments to avoid redundancy", "deleted": false, "createdAt": "2025-11-03T01:01:15.254Z" }, { "id": 2, "text": "Step validation system-reminder should provide an example showing proper step comment placement with context about which line of code executes that step", "deleted": false, "createdAt": "2025-11-03T01:01:16.595Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Current behavior: System-reminder says 'Add to test file: // @step When the scanDraftForNextField function processes the draft'. AI adds comment without understanding where to place it or that existing Given/When/Then comments might be duplicates.", "deleted": false, "createdAt": "2025-11-03T01:01:28.714Z" }, { "id": 1, "text": "Expected behavior: System-reminder explains 'Place step comments NEAR the code that executes each step. If you have duplicate Given/When/Then comments, remove them first. Example: Place \"// @step When the scanDraftForNextField function processes the draft\" right before the line that calls scanDraftForNextField() or discoverFoundation() which internally calls it.'", "deleted": false, "createdAt": "2025-11-03T01:01:30.162Z" }, { "id": 2, "text": "AI receives step validation error, reads test file, sees existing '// Given I have a foundation.json.draft' comments, doesn't realize these might conflict with '@step Given' comments, adds @step comments without removing duplicates, creates confusing redundant comments", "deleted": false, "createdAt": "2025-11-03T01:01:31.709Z" } ], "nextExampleId": 3, "architectureNotes": [ { "id": 0, "text": "The step validation system-reminder is generated in the link-coverage command when validating step comments in test files. The error message format is currently just 'Add to test file: // @step [step text]' without additional context.", "deleted": false, "createdAt": "2025-11-03T01:01:41.981Z" }, { "id": 1, "text": "The fix should enhance the system-reminder message to include: 1) Instruction to place comments near executing code, 2) Instruction to check for and remove duplicate comments, 3) Example showing proper placement with context about which line executes the step.", "deleted": false, "createdAt": "2025-11-03T01:01:43.594Z" } ], "nextNoteId": 2, "estimate": 2, "questions": [], "nextQuestionId": 0, "updated": "2025-11-03T01:10:50.578Z" }, "BUG-058": { "id": "BUG-058", "title": "report-bug-to-github crashes with 'path must be string' error", "type": "bug", "status": "done", "createdAt": "2025-11-03T02:45:01.366Z", "updatedAt": "2025-11-03T02:52:22.204Z", "description": "The report-bug-to-github command fails when findProjectRoot() returns undefined, causing Node.js to throw 'The path argument must be of type string. Received undefined' error when trying to join paths in gatherContext function", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T02:47:11.593Z" }, { "state": "testing", "timestamp": "2025-11-03T02:49:20.245Z" }, { "state": "implementing", "timestamp": "2025-11-03T02:50:19.180Z" }, { "state": "validating", "timestamp": "2025-11-03T02:51:21.167Z" }, { "state": "done", "timestamp": "2025-11-03T02:52:22.204Z" } ], "userStory": { "role": "developer using fspec", "action": "run report-bug-to-github command without errors", "benefit": "I can successfully report bugs to GitHub" }, "rules": [ { "id": 0, "text": "findProjectRoot() requires a cwd parameter of type string", "deleted": false, "createdAt": "2025-11-03T02:47:36.186Z" }, { "id": 1, "text": "When no projectRoot option is provided, the command must use process.cwd() as the current working directory", "deleted": false, "createdAt": "2025-11-03T02:47:37.572Z" }, { "id": 2, "text": "The gatherContext function must receive a valid string path for projectRoot", "deleted": false, "createdAt": "2025-11-03T02:47:39.054Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "User runs 'fspec report-bug-to-github' without --project-root flag, command crashes with 'path must be string. Received undefined'", "deleted": false, "createdAt": "2025-11-03T02:47:47.967Z" }, { "id": 1, "text": "User runs 'fspec report-bug-to-github --bug-description \"test\"', command crashes before gathering context", "deleted": false, "createdAt": "2025-11-03T02:47:49.463Z" }, { "id": 2, "text": "User runs 'fspec report-bug-to-github --project-root /path/to/project', command works correctly because projectRoot is provided", "deleted": false, "createdAt": "2025-11-03T02:47:51.232Z" }, { "id": 3, "text": "After fix, user runs 'fspec report-bug-to-github' from any directory, command gathers context successfully using process.cwd()", "deleted": false, "createdAt": "2025-11-03T02:47:52.876Z" } ], "nextExampleId": 4, "estimate": 2, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-03T02:52:22.204Z" }, "BUG-059": { "id": "BUG-059", "title": "search-scenarios returns no results when it should find matching scenarios", "type": "bug", "status": "done", "createdAt": "2025-11-03T02:46:20.741Z", "updatedAt": "2025-11-03T04:05:20.615Z", "description": "Running 'fspec search-scenarios --query=\"report-bug\"' returns 0 scenarios, but there is a feature file 'spec/features/report-bug-to-github-with-ai-assistance.feature' that should match this query. The search function appears to not be working correctly.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T02:59:40.086Z" }, { "state": "testing", "timestamp": "2025-11-03T03:51:30.327Z" }, { "state": "implementing", "timestamp": "2025-11-03T03:53:52.435Z" }, { "state": "validating", "timestamp": "2025-11-03T03:58:13.807Z" }, { "state": "done", "timestamp": "2025-11-03T04:05:20.616Z" } ], "userStory": { "role": "developer using fspec", "action": "search for scenarios across feature files", "benefit": "I can quickly find relevant scenarios without reading all feature files" }, "rules": [ { "id": 0, "text": "Search must check scenario names for matches", "deleted": false, "createdAt": "2025-11-03T03:00:37.979Z" }, { "id": 1, "text": "Business Rule 6 from QRY-002 states: 'Search must support text search across scenario names, feature descriptions, and work unit titles'", "deleted": false, "createdAt": "2025-11-03T03:03:07.399Z" }, { "id": 2, "text": "Yes - feature descriptions should be searched. Already specified in QRY-002 BR6. Useful for finding features by technical details (technology names, architecture patterns, implementation approaches). Even if match is in description, returning scenarios from that feature is valuable.", "deleted": false, "createdAt": "2025-11-03T03:05:45.810Z" }, { "id": 3, "text": "Yes - feature names should be searched. Feature name is the primary identifier for a feature, parallel to scenario names for scenarios. User's bug report expected this behavior. Low noise, high relevance results. Searching 'authentication' should find all scenarios from 'Feature: User Authentication'.", "deleted": false, "createdAt": "2025-11-03T03:06:46.703Z" }, { "id": 4, "text": "Yes - feature file names should be searched. File names use kebab-case while feature names use spaces - substring matching won't catch both. Users see filenames in filesystem (ls spec/features/), natural to search by what they see. Low cost, already have filePath. User's bug report explicitly mentioned filename matching.", "deleted": false, "createdAt": "2025-11-03T03:07:43.577Z" }, { "id": 5, "text": "Yes - work unit titles should be searched. Already in QRY-002 BR6 spec. Work unit titles often differ from feature names (bug descriptions vs feature titles). Users think in work units (BUG-059, AUTH-001). Infrastructure already exists (extract IDs from tags). One JSON read, cacheable. Strengthens traceability.", "deleted": false, "createdAt": "2025-11-03T03:09:28.859Z" } ], "nextRuleId": 6, "questions": [ { "id": 0, "text": "@human: The existing spec (QRY-002 Business Rule 6) says search should cover 'feature descriptions' (the triple-quoted doc strings at the top of features). Should we implement this?", "deleted": false, "createdAt": "2025-11-03T03:03:28.925Z", "selected": true, "answer": "Yes - feature descriptions should be searched. Already specified in QRY-002 BR6. Useful for finding features by technical details (technology names, architecture patterns, implementation approaches). Even if match is in description, returning scenarios from that feature is valuable." }, { "id": 1, "text": "@human: The spec doesn't mention searching feature names (e.g., 'Report bug to GitHub with AI assistance'), but your bug example expects this. Should we search feature names in addition to scenario names?", "deleted": false, "createdAt": "2025-11-03T03:03:36.424Z", "selected": true, "answer": "Yes - feature names should be searched. Feature name is the primary identifier for a feature, parallel to scenario names for scenarios. User's bug report expected this behavior. Low noise, high relevance results. Searching 'authentication' should find all scenarios from 'Feature: User Authentication'." }, { "id": 2, "text": "@human: Should we also search feature file names (e.g., 'report-bug-to-github-with-ai-assistance.feature')? This is NOT in the spec, but could be useful for finding features by filename patterns.", "deleted": false, "createdAt": "2025-11-03T03:03:42.655Z", "selected": true, "answer": "Yes - feature file names should be searched. File names use kebab-case while feature names use spaces - substring matching won't catch both. Users see filenames in filesystem (ls spec/features/), natural to search by what they see. Low cost, already have filePath. User's bug report explicitly mentioned filename matching." }, { "id": 3, "text": "@human: Should we search within scenario step text (Given/When/Then)? This is NOT in the spec but could help find scenarios by their implementation details (e.g., search 'browser' to find scenarios that open browsers).", "deleted": false, "createdAt": "2025-11-03T03:03:49.646Z", "selected": true, "answer": "No - step text should NOT be searched. Steps describe HOW (implementation), not WHAT (capability). High noise from verbose text with common words. search-implementation exists for finding by HOW it works. Not in QRY-002 spec (likely intentional). Keep search-scenarios focused on capabilities." }, { "id": 4, "text": "@human: The existing spec says search should cover 'work unit titles' (from spec/work-units.json). Should we search the work unit title field when a feature has a work unit tag like @BUG-059?", "deleted": false, "createdAt": "2025-11-03T03:03:56.591Z", "selected": true, "answer": "Yes - work unit titles should be searched. Already in QRY-002 BR6 spec. Work unit titles often differ from feature names (bug descriptions vs feature titles). Users think in work units (BUG-059, AUTH-001). Infrastructure already exists (extract IDs from tags). One JSON read, cacheable. Strengthens traceability." } ], "nextQuestionId": 5, "examples": [ { "id": 0, "text": "User searches for 'report-bug', expects to find scenarios from 'report-bug-to-github-with-ai-assistance.feature', but gets 0 results because search only checks scenario names", "deleted": false, "createdAt": "2025-11-03T03:01:03.575Z" }, { "id": 1, "text": "User searches for 'authentication', should find scenarios from features with 'authentication' in feature name, file name, or scenario names", "deleted": false, "createdAt": "2025-11-03T03:01:09.744Z" }, { "id": 2, "text": "Current implementation only searches scenario names (line 104-107 in feature-parser.ts), but Business Rule 6 says it should also search feature descriptions and work unit titles", "deleted": false, "createdAt": "2025-11-03T03:03:13.886Z" } ], "nextExampleId": 3, "assumptions": [ "No - step text should NOT be searched. Steps describe HOW (implementation), not WHAT (capability). High noise from verbose text with common words. search-implementation exists for finding by HOW it works. Not in QRY-002 spec (likely intentional). Keep search-scenarios focused on capabilities." ], "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-03T04:05:20.615Z" }, "BUG-060": { "id": "BUG-060", "title": "generate-scenarios counts deleted questions as unanswered", "type": "bug", "status": "done", "createdAt": "2025-11-03T03:11:53.173Z", "updatedAt": "2025-11-03T03:51:18.447Z", "description": "The validation in generate-scenarios.ts:308-311 filters questions by \\!questionItem.selected but doesn't check \\!questionItem.deleted. This causes it to count deleted questions as unanswered, blocking scenario generation even when all active questions are answered. The filter should be: \\!questionItem.deleted && \\!questionItem.selected", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T03:12:01.925Z" }, { "state": "testing", "timestamp": "2025-11-03T03:13:43.841Z" }, { "state": "implementing", "timestamp": "2025-11-03T03:14:46.807Z" }, { "state": "validating", "timestamp": "2025-11-03T03:15:12.485Z" }, { "state": "done", "timestamp": "2025-11-03T03:18:21.679Z" }, { "state": "specifying", "timestamp": "2025-11-03T03:47:16.228Z" }, { "state": "testing", "timestamp": "2025-11-03T03:48:07.504Z" }, { "state": "implementing", "timestamp": "2025-11-03T03:49:48.203Z" }, { "state": "validating", "timestamp": "2025-11-03T03:51:16.281Z" }, { "state": "done", "timestamp": "2025-11-03T03:51:18.447Z" } ], "userStory": { "role": "AI agent using fspec", "action": "generate scenarios from Example Mapping", "benefit": "I can proceed after answering all questions, without being blocked by deleted questions" }, "rules": [ { "id": 0, "text": "Validation must only count questions that are NOT deleted AND NOT answered (selected=false)", "deleted": false, "createdAt": "2025-11-03T03:12:15.308Z" }, { "id": 1, "text": "Deleted questions (deleted=true) must be ignored in all validation checks", "deleted": false, "createdAt": "2025-11-03T03:12:21.494Z" }, { "id": 2, "text": "Answered questions have selected=true (answer field populated)", "deleted": false, "createdAt": "2025-11-03T03:12:27.386Z" }, { "id": 3, "text": "Validation must filter out deleted questions (questions with deleted=true property) before counting unanswered questions", "deleted": false, "createdAt": "2025-11-03T03:47:29.041Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Work unit has 3 deleted questions (deleted=true, selected=false) and 5 answered questions (deleted=false, selected=true). Current code counts 3 unanswered, blocks generation. Correct behavior: 0 unanswered, allows generation.", "deleted": false, "createdAt": "2025-11-03T03:12:34.936Z" }, { "id": 1, "text": "Work unit has 2 unanswered questions (deleted=false, selected=false). Current code correctly counts 2 unanswered, blocks generation. Behavior is correct.", "deleted": false, "createdAt": "2025-11-03T03:12:40.957Z" }, { "id": 2, "text": "Work unit has no questions. Current code correctly counts 0 unanswered, allows generation. Behavior is correct.", "deleted": false, "createdAt": "2025-11-03T03:12:47.267Z" }, { "id": 3, "text": "User deletes 3 questions, validation counts them as unanswered, blocks state transition", "deleted": false, "createdAt": "2025-11-03T03:47:22.955Z" } ], "nextExampleId": 4, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-03T03:51:18.447Z" }, "BUG-061": { "id": "BUG-061", "title": "Missing validation for test file @step docstring completeness", "type": "bug", "status": "done", "createdAt": "2025-11-03T03:19:44.791Z", "updatedAt": "2025-11-03T03:43:53.600Z", "description": "Test files must have Given, When, AND Then @step docstring comments mapping to Gherkin scenarios. Validation should occur: a) when moving work unit to implementing status (tests must be complete), b) when moving work unit to validating status. Currently work can progress without proper test-to-scenario traceability through step docstrings. Example: // Given ..., // When ..., // Then ... comments in test files.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T03:21:50.534Z" }, { "state": "testing", "timestamp": "2025-11-03T03:24:21.564Z" }, { "state": "implementing", "timestamp": "2025-11-03T03:25:34.149Z" }, { "state": "specifying", "timestamp": "2025-11-03T03:29:19.104Z" }, { "state": "testing", "timestamp": "2025-11-03T03:30:28.694Z" }, { "state": "implementing", "timestamp": "2025-11-03T03:35:32.207Z" }, { "state": "validating", "timestamp": "2025-11-03T03:41:17.659Z" }, { "state": "done", "timestamp": "2025-11-03T03:41:51.875Z" }, { "state": "implementing", "timestamp": "2025-11-03T03:43:03.224Z" }, { "state": "validating", "timestamp": "2025-11-03T03:43:40.652Z" }, { "state": "done", "timestamp": "2025-11-03T03:43:53.600Z" } ], "userStory": { "role": "AI agent following ACDD", "action": "ensure test files have complete Given/When/Then step docstrings before implementation", "benefit": "test-to-scenario traceability is maintained and scenarios are properly tested" }, "rules": [ { "id": 0, "text": "Step validation logic exists in src/utils/step-validation.ts with validateSteps() and formatValidationError() functions", "deleted": false, "createdAt": "2025-11-03T03:22:09.393Z" }, { "id": 1, "text": "Step validation is currently ONLY used in link-coverage command (src/commands/link-coverage.ts), NOT in update-work-unit-status", "deleted": false, "createdAt": "2025-11-03T03:22:16.067Z" }, { "id": 2, "text": "Test files MUST have Given, When, AND Then @step docstrings when moving work unit from testing to implementing", "deleted": false, "createdAt": "2025-11-03T03:22:22.291Z" }, { "id": 3, "text": "Test files MUST have Given, When, AND Then @step docstrings when moving work unit to validating state", "deleted": false, "createdAt": "2025-11-03T03:22:28.274Z" }, { "id": 4, "text": "Tasks (type=task) are exempt from step validation since they don't have tests", "deleted": false, "createdAt": "2025-11-03T03:22:35.255Z" }, { "id": 5, "text": "CRITICAL: Test files MUST be discovered from .feature.coverage files, NOT hard-coded file patterns. Coverage files are language-agnostic and track actual test-to-scenario mappings.", "deleted": false, "createdAt": "2025-11-03T03:29:27.963Z" }, { "id": 6, "text": "If no .feature.coverage file exists for a feature, validation should fail with clear message to use 'fspec link-coverage' command", "deleted": false, "createdAt": "2025-11-03T03:29:35.208Z" } ], "nextRuleId": 7, "examples": [ { "id": 0, "text": "Work unit BUG-060 moves from testing to implementing. Test file has complete Given/When/Then @step comments. Currently allowed (correct behavior, should continue working after fix).", "deleted": false, "createdAt": "2025-11-03T03:22:42.265Z" }, { "id": 1, "text": "Work unit STORY-001 moves from testing to implementing. Test file exists but has NO @step docstrings. Currently ALLOWED (bug), should be BLOCKED with system-reminder showing missing steps.", "deleted": false, "createdAt": "2025-11-03T03:22:49.858Z" }, { "id": 2, "text": "Work unit moves to validating. Test file has Given and When steps but missing Then step. Currently ALLOWED (bug), should be BLOCKED showing which steps are missing.", "deleted": false, "createdAt": "2025-11-03T03:22:56.088Z" }, { "id": 3, "text": "Feature file test-feature.feature has coverage file test-feature.feature.coverage with testMappings array listing test files. Validation reads coverage file, extracts test file paths, validates those specific files regardless of language/framework.", "deleted": false, "createdAt": "2025-11-03T03:29:43.094Z" } ], "nextExampleId": 4, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-03T03:43:53.600Z" }, "BUG-062": { "id": "BUG-062", "title": "Kanban TUI keyboard navigation - Page Up/Down and Home/End key bindings", "type": "bug", "status": "done", "createdAt": "2025-11-03T04:37:35.085Z", "updatedAt": "2025-11-03T05:06:25.025Z", "description": "Page Up/Down should move the selector a page up/down (moving the list via the selector), not scroll the list while keeping selector stationary. Home and End keys should move selector to top/bottom of current list. These keys don't need to appear in the key map guide.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T04:38:30.402Z" }, { "state": "testing", "timestamp": "2025-11-03T04:44:04.796Z" }, { "state": "implementing", "timestamp": "2025-11-03T04:46:34.213Z" }, { "state": "validating", "timestamp": "2025-11-03T05:03:06.451Z" }, { "state": "done", "timestamp": "2025-11-03T05:06:25.026Z" } ], "questions": [ { "id": 0, "text": "@human: When you press Page Down, what currently happens? Does the selector stay in the same visual position on screen while the list scrolls, or does the selector jump down but the list doesn't scroll to follow it?", "deleted": false, "createdAt": "2025-11-03T04:38:43.800Z", "selected": true, "answer": "Page Up/Down currently just scrolls the list up/down without moving the selector (green bar)" }, { "id": 1, "text": "@human: What is the desired Page Down behavior? Should the selector move down one full page of items (e.g., if 10 items visible, move selector down 10 items), and the list scrolls to keep selector visible?", "deleted": false, "createdAt": "2025-11-03T04:38:45.168Z", "selected": true, "answer": "The selector (green bar) should move down/up one full page of items (like arrow keys but a page at a time), and the list should scroll to keep the selector visible" }, { "id": 2, "text": "@human: For Home/End keys - the code shows they ARE bound (key.home/key.end) but also 'g' and 'G' are vim-style alternatives. Are Home/End keys not working for you, or is it a different issue?", "deleted": false, "createdAt": "2025-11-03T04:38:46.767Z", "selected": true, "answer": "Home/End keys aren't actually bound/working despite appearing in VirtualList code. Need to review all keyboard handling code in this area to understand why." } ], "nextQuestionId": 3, "rules": [ { "id": 0, "text": "Page Up/Down should move the selector (selectedWorkUnitIndex) by VIEWPORT_HEIGHT, not manipulate scrollOffsets directly", "deleted": false, "createdAt": "2025-11-03T04:40:57.053Z" }, { "id": 1, "text": "Home/End keys must be bound in UnifiedBoardLayout to move selector to first/last item in current column", "deleted": false, "createdAt": "2025-11-03T04:40:58.588Z" }, { "id": 2, "text": "Auto-scroll logic (lines 320-391 in UnifiedBoardLayout) automatically adjusts scrollOffsets to keep selector visible", "deleted": false, "createdAt": "2025-11-03T04:40:59.955Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "User on item 5 of 20, presses Page Down, selector moves to item 15 (assuming VIEWPORT_HEIGHT=10), list scrolls to show items around 15", "deleted": false, "createdAt": "2025-11-03T04:41:09.625Z" }, { "id": 1, "text": "User on item 15, presses Page Up, selector moves to item 5, list scrolls to show items around 5", "deleted": false, "createdAt": "2025-11-03T04:41:11.135Z" }, { "id": 2, "text": "User on item 15, presses Home, selector moves to item 0 (first item), list scrolls to top", "deleted": false, "createdAt": "2025-11-03T04:41:12.513Z" }, { "id": 3, "text": "User on item 5, presses End, selector moves to item 19 (last item of 20), list scrolls to bottom", "deleted": false, "createdAt": "2025-11-03T04:41:13.817Z" } ], "nextExampleId": 4, "architectureNotes": [ { "id": 0, "text": "Root cause in UnifiedBoardLayout.tsx:430-458 - Page Up/Down directly manipulate scrollOffsets instead of calling onWorkUnitChange", "deleted": false, "createdAt": "2025-11-03T04:41:24.010Z" }, { "id": 1, "text": "Missing Home/End key bindings in UnifiedBoardLayout.tsx useInput handler (lines 404-478)", "deleted": false, "createdAt": "2025-11-03T04:41:25.309Z" }, { "id": 2, "text": "Fix: Change Page Down to call onWorkUnitChange(VIEWPORT_HEIGHT), Page Up to call onWorkUnitChange(-VIEWPORT_HEIGHT)", "deleted": false, "createdAt": "2025-11-03T04:41:26.526Z" }, { "id": 3, "text": "Fix: Add Home key handler to call onWorkUnitChange with movement to index 0, End key to call onWorkUnitChange with movement to last index", "deleted": false, "createdAt": "2025-11-03T04:41:27.882Z" } ], "nextNoteId": 4, "userStory": { "role": "user navigating the Kanban TUI", "action": "use Page Up/Down and Home/End keys", "benefit": "I can quickly navigate through long lists without my muscle memory being broken" }, "estimate": 2, "updated": "2025-11-03T05:06:25.025Z" }, "TUI-014": { "id": "TUI-014", "title": "Remove file watching from TUI main screen and lazy-load changed files view", "type": "story", "status": "done", "createdAt": "2025-11-03T10:12:35.436Z", "updatedAt": "2025-11-03T11:24:33.612Z", "description": "Remove file watching for changed files from the main TUI board display. Keep the 'F View Changed Files' keyboard shortcut and view, but calculate changed files only when the view is opened (lazy loading). Remove all associated code, tests, and features for file watching and changed file count display on main board.", "children": [], "userStory": { "role": "developer viewing the TUI board", "action": "remove file watching overhead and see changed files only when needed", "benefit": "the main board loads faster and file system watchers don't consume resources unnecessarily" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T10:12:49.726Z" }, { "state": "testing", "timestamp": "2025-11-03T10:34:50.547Z" }, { "state": "implementing", "timestamp": "2025-11-03T10:40:17.894Z" }, { "state": "validating", "timestamp": "2025-11-03T11:09:22.595Z" }, { "state": "done", "timestamp": "2025-11-03T11:24:33.612Z" } ], "questions": [ { "id": 0, "text": "@human: What specific UI elements on the main TUI board display changed files information currently (counter, list, etc.)?", "deleted": false, "createdAt": "2025-11-03T10:13:09.434Z", "selected": true, "answer": "The main TUI board displays: (1) Counter: 'Changed Files (X staged, Y unstaged)' (2) File preview showing up to 3 files with status indicators (+ for staged, M for unstaged) (3) Empty state: 'No changes' when no files changed. This appears in the header panel at lines 532-545 of UnifiedBoardLayout.tsx." }, { "id": 1, "text": "@human: When user presses 'F View Changed Files', should it calculate changed files using git status at that moment (lazy loading)?", "deleted": false, "createdAt": "2025-11-03T10:13:11.517Z", "selected": true, "answer": "Yes, when user presses 'F View Changed Files', it should calculate changed files at that moment using the exact same mechanism: Call Promise.all([getStagedFiles(cwd), getUnstagedFiles(cwd)]) from src/git/status.ts. This uses isomorphic-git to read .git/index directly (no git CLI subprocess). The same functions, same parameters, just triggered on-demand instead of by file watchers." }, { "id": 2, "text": "@human: Are there file watchers currently running in the background, and should ALL file watching be removed from the TUI?", "deleted": false, "createdAt": "2025-11-03T10:13:13.309Z", "selected": true, "answer": "There are file watchers currently running. Remove ONLY the .git/index and .git/HEAD watcher (BoardView.tsx lines 143-188) that watches for changed files. KEEP the git stash watcher (BoardView.tsx lines 112-141) which displays checkpoints in the header, and KEEP the checkpoint panel watcher (CheckpointPanel.tsx lines 64-92) which shows checkpoint counts." }, { "id": 3, "text": "@human: What code files, test files, and feature files need to be removed or refactored as part of this cleanup?", "deleted": false, "createdAt": "2025-11-03T10:13:14.641Z", "selected": true, "answer": "MODIFY 5 source files: (1) BoardView.tsx - remove .git/index/.git/HEAD watcher lines 143-188, remove loadFileStatus calls (2) UnifiedBoardLayout.tsx - remove changed files section lines 532-545 (3) ChangedFilesPanel.tsx - remove file counts, keep only keyboard shortcuts (4) ChangedFilesViewer.tsx - add lazy loading on mount via loadFileStatus (5) fspecStore.ts - KEEP unchanged. MODIFY 3 test files: BoardView-file-watchers.test.tsx and BoardView-git-watcher-fix.test.tsx (remove .git/index/.git/HEAD scenarios, keep checkpoint tests), ChangedFilesViewer.test.tsx (switch to store-based testing). MODIFY 1 feature file: ITF-005 (remove 3 scenarios about file watching). KEEP unchanged: GIT-004 feature file (F key behavior unchanged). Total: 12 files modified, 0 deleted, ~270 net lines removed." } ], "nextQuestionId": 4, "rules": [ { "id": 0, "text": "The main TUI board displays: (1) Counter: 'Changed Files (X staged, Y unstaged)' (2) File preview showing up to 3 files with status indicators (+ for staged, M for unstaged) (3) Empty state: 'No changes' when no files changed. This appears in the header panel at lines 532-545 of UnifiedBoardLayout.tsx.", "deleted": false, "createdAt": "2025-11-03T10:19:04.447Z" }, { "id": 1, "text": "Yes, when user presses 'F View Changed Files', it should calculate changed files at that moment using the exact same mechanism: Call Promise.all([getStagedFiles(cwd), getUnstagedFiles(cwd)]) from src/git/status.ts. This uses isomorphic-git to read .git/index directly (no git CLI subprocess). The same functions, same parameters, just triggered on-demand instead of by file watchers.", "deleted": false, "createdAt": "2025-11-03T10:22:39.205Z" }, { "id": 2, "text": "There are file watchers currently running. Remove ONLY the .git/index and .git/HEAD watcher (BoardView.tsx lines 143-188) that watches for changed files. KEEP the git stash watcher (BoardView.tsx lines 112-141) which displays checkpoints in the header, and KEEP the checkpoint panel watcher (CheckpointPanel.tsx lines 64-92) which shows checkpoint counts.", "deleted": false, "createdAt": "2025-11-03T10:26:47.889Z" }, { "id": 3, "text": "MODIFY 5 source files: (1) BoardView.tsx - remove .git/index/.git/HEAD watcher lines 143-188, remove loadFileStatus calls (2) UnifiedBoardLayout.tsx - remove changed files section lines 532-545 (3) ChangedFilesPanel.tsx - remove file counts, keep only keyboard shortcuts (4) ChangedFilesViewer.tsx - add lazy loading on mount via loadFileStatus (5) fspecStore.ts - KEEP unchanged. MODIFY 3 test files: BoardView-file-watchers.test.tsx and BoardView-git-watcher-fix.test.tsx (remove .git/index/.git/HEAD scenarios, keep checkpoint tests), ChangedFilesViewer.test.tsx (switch to store-based testing). MODIFY 1 feature file: ITF-005 (remove 3 scenarios about file watching). KEEP unchanged: GIT-004 feature file (F key behavior unchanged). Total: 12 files modified, 0 deleted, ~270 net lines removed.", "deleted": false, "createdAt": "2025-11-03T10:31:17.640Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "User opens TUI board → Header shows 'Git Stashes (2)' with checkpoint names → NO 'Changed Files' counter visible", "deleted": false, "createdAt": "2025-11-03T10:31:32.924Z" }, { "id": 1, "text": "User presses F key → ChangedFilesViewer opens → Component calls loadFileStatus() on mount → Displays '2 staged, 1 unstaged' with file list and diffs", "deleted": false, "createdAt": "2025-11-03T10:31:34.543Z" }, { "id": 2, "text": "User stages file externally (git add) → Main board header does NOT update automatically → User presses F key → Viewer loads fresh git status showing newly staged file", "deleted": false, "createdAt": "2025-11-03T10:31:36.187Z" }, { "id": 3, "text": "User creates checkpoint via 'fspec checkpoint' → Git stashes section updates automatically (watcher still active) → Changed files section removed entirely from header", "deleted": false, "createdAt": "2025-11-03T10:31:37.738Z" }, { "id": 4, "text": "BoardView-file-watchers.test.tsx: Remove test 'TUI auto-updates when file is staged via git add' → Keep test 'TUI auto-updates stash panel when git stash is created externally'", "deleted": false, "createdAt": "2025-11-03T10:31:39.231Z" } ], "nextExampleId": 5, "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-03T11:24:33.612Z" }, "TUI-015": { "id": "TUI-015", "title": "Refactor header and details to component-based flexbox", "type": "story", "status": "done", "createdAt": "2025-11-03T12:11:24.928Z", "updatedAt": "2025-11-03T15:07:56.023Z", "children": [], "attachments": [ "spec/attachments/TUI-015/REWORK.md", "spec/attachments/TUI-015/VISUAL-RULES-GUIDE.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T12:13:01.627Z" }, { "state": "testing", "timestamp": "2025-11-03T12:40:18.238Z" }, { "state": "testing", "timestamp": "2025-11-03T13:00:39.318Z" }, { "state": "implementing", "timestamp": "2025-11-03T13:08:36.436Z" }, { "state": "validating", "timestamp": "2025-11-03T13:28:52.457Z" }, { "state": "done", "timestamp": "2025-11-03T15:07:56.024Z" } ], "userStory": { "role": "developer using fspec TUI", "action": "view header and work unit details as pure Ink components", "benefit": "the layout is maintainable, testable, and uses proper flexbox instead of string injection" }, "rules": [ { "id": 0, "text": "NO string injection - all content must be rendered as Ink components", "deleted": false, "createdAt": "2025-11-03T12:13:24.977Z" }, { "id": 1, "text": "Use ONLY flexbox (flexGrow/flexShrink) and static heights - NEVER percentages", "deleted": false, "createdAt": "2025-11-03T12:13:26.421Z" }, { "id": 2, "text": "Header container must have internal height of 4 lines (Logo + CheckpointStatus + KeybindingShortcuts)", "deleted": false, "createdAt": "2025-11-03T12:13:28.951Z" }, { "id": 3, "text": "Work unit details container must have internal height of 5 lines (Title[1] + Description[3] + Metadata[1])", "deleted": false, "createdAt": "2025-11-03T12:13:30.580Z" }, { "id": 4, "text": "Logo component width is 12 characters with flexShrink, InfoContainer uses flexGrow", "deleted": false, "createdAt": "2025-11-03T12:13:33.981Z" }, { "id": 5, "text": "WorkUnitDescription component height is 3 lines using flexGrow with bold cyan text", "deleted": false, "createdAt": "2025-11-03T12:13:36.942Z" }, { "id": 6, "text": "InfoContainer must use flexGrow to fill remaining horizontal space after Logo (12ch fixed width)", "deleted": false, "createdAt": "2025-11-03T12:16:03.359Z" }, { "id": 7, "text": "CheckpointStatus and KeybindingShortcuts must use flexGrow to distribute vertical space within InfoContainer (no static heights)", "deleted": false, "createdAt": "2025-11-03T12:16:28.629Z" }, { "id": 8, "text": "All text rendering in header and details must be Text components - NEVER string concatenation in rows array", "deleted": false, "createdAt": "2025-11-03T12:16:31.463Z" }, { "id": 9, "text": "HeaderContainer uses Box with borderStyle='single' for all four borders (top, right, bottom, left)", "deleted": false, "createdAt": "2025-11-03T12:16:33.228Z" }, { "id": 10, "text": "Logo component width MUST be exactly 12 characters (4 rows of 12ch each, currently implemented correctly)", "deleted": false, "createdAt": "2025-11-03T12:16:34.738Z" }, { "id": 11, "text": "WorkUnitTitle must truncate text WITHOUT ellipsis (...) if exceeds container width", "deleted": false, "createdAt": "2025-11-03T12:16:36.310Z" }, { "id": 12, "text": "WorkUnitDescription must truncate line 3 WITH ellipsis (...) if description exceeds 3 lines", "deleted": false, "createdAt": "2025-11-03T12:16:37.566Z" }, { "id": 13, "text": "WorkUnitMetadata displays available fields only, joined with ' | ' separator (Epic | Estimate | Status)", "deleted": false, "createdAt": "2025-11-03T12:16:39.510Z" }, { "id": 14, "text": "When no work unit selected: WorkUnitTitle shows 'No work unit selected' centered, lines 2-5 empty (not 'No description')", "deleted": false, "createdAt": "2025-11-03T12:16:41.047Z" }, { "id": 15, "text": "WorkUnitDescription MUST be bold cyan text (chalk.cyan.bold) wrapping across 3 lines maximum", "deleted": false, "createdAt": "2025-11-03T12:16:47.722Z" }, { "id": 16, "text": "Header total height is 6 lines (1 top border from Box + 4 content lines + 1 bottom border from Box)", "deleted": false, "createdAt": "2025-11-03T12:18:20.270Z" }, { "id": 17, "text": "Details total height is 5 content lines (borders rendered by separators, NOT counted in content height)", "deleted": false, "createdAt": "2025-11-03T12:18:21.857Z" }, { "id": 18, "text": "WorkUnitTitle and WorkUnitMetadata must have height={1} (static, single line each)", "deleted": false, "createdAt": "2025-11-03T12:18:23.314Z" }, { "id": 19, "text": "WorkUnitDescription must use flexGrow={1} to fill 3 lines (NOT static height={3})", "deleted": false, "createdAt": "2025-11-03T12:18:24.800Z" }, { "id": 20, "text": "Text wrapping in WorkUnitDescription must split on spaces, NOT character-by-character (word-wrap, not char-wrap)", "deleted": false, "createdAt": "2025-11-03T12:18:26.266Z" }, { "id": 21, "text": "When description text contains newlines, they must be normalized to spaces before wrapping (join all lines into single text)", "deleted": false, "createdAt": "2025-11-03T12:18:27.990Z" }, { "id": 22, "text": "Component hierarchy: HeaderContainer(Box) → Row(Box) → [Logo, InfoContainer(Box)] → Column → [CheckpointStatus, KeybindingShortcuts]", "deleted": false, "createdAt": "2025-11-03T12:18:30.057Z" }, { "id": 23, "text": "Component hierarchy: WorkUnitDetailsContainer(Box) → Column → [WorkUnitTitle(Box), WorkUnitDescription(Box), WorkUnitMetadata(Box)]", "deleted": false, "createdAt": "2025-11-03T12:18:31.641Z" }, { "id": 24, "text": "All component text content must be wrapped in Text components - Box components handle layout only", "deleted": false, "createdAt": "2025-11-03T12:18:33.194Z" }, { "id": 25, "text": "String injection lines (rows.push) removed from lines 496-617, replaced with component rendering at lines 707-740", "deleted": false, "createdAt": "2025-11-03T12:18:34.859Z" }, { "id": 26, "text": "Column viewport height is DYNAMIC: calculated as terminalHeight minus actual heights of all static components (header Box 6, separator 1, details 5, separator 1, column headers 2, footer separator 1, footer text 1, bottom border 1)", "deleted": false, "createdAt": "2025-11-03T12:19:27.749Z" }, { "id": 27, "text": "Static component heights are derived from their actual structure (NOT magic numbers): HeaderContainer.height, separators.count, WorkUnitDetailsContainer.height, footerRows.count", "deleted": false, "createdAt": "2025-11-03T12:19:29.558Z" }, { "id": 28, "text": "Terminal resize MUST recalculate column viewport height - columns fill remaining space after static components are rendered", "deleted": false, "createdAt": "2025-11-03T12:19:30.930Z" }, { "id": 29, "text": "NEVER hardcode total fixed rows as magic number (e.g., fixedRows = 19) - calculate from sum of static component heights", "deleted": false, "createdAt": "2025-11-03T12:19:32.228Z" }, { "id": 30, "text": "Each separator line counts as 1 row (buildBorderRow output), column header row is 1, header separator is 1", "deleted": false, "createdAt": "2025-11-03T12:20:00.598Z" }, { "id": 31, "text": "InfoContainer height={4} is STATIC (matches 4 internal lines in Logo), NOT flexible - ensures header vertical alignment", "deleted": false, "createdAt": "2025-11-03T12:20:02.218Z" }, { "id": 32, "text": "WorkUnitDetailsContainer must have explicit height={5} to ensure 5 content rows regardless of description length", "deleted": false, "createdAt": "2025-11-03T12:20:03.984Z" }, { "id": 33, "text": "Current calculateViewportHeight at line 79-99 uses hardcoded fixedRows=17 (WRONG) - must calculate from component structure", "deleted": false, "createdAt": "2025-11-03T12:20:05.416Z" }, { "id": 34, "text": "wrapText helper (lines 110-133) must be used internally by WorkUnitDescription component for 3-line wrapping logic", "deleted": false, "createdAt": "2025-11-03T12:20:39.584Z" }, { "id": 35, "text": "fitToWidth helper (lines 102-107) used for padding/truncation must be replaced by Ink Text wrap='truncate' prop in components", "deleted": false, "createdAt": "2025-11-03T12:20:42.210Z" }, { "id": 36, "text": "centerText helper (lines 136-144) must be used by WorkUnitTitle when selectedWorkUnit is null ('No work unit selected' centered)", "deleted": false, "createdAt": "2025-11-03T12:20:44.232Z" }, { "id": 37, "text": "String injection pattern rows.push('│' + content + '│') at lines 504-616 MUST BE DELETED and replaced with component hierarchy", "deleted": false, "createdAt": "2025-11-03T12:20:46.230Z" }, { "id": 38, "text": "Hybrid rendering at lines 707-740 splits rows into sections (header components + separator string + rest strings) - must be fully component-based", "deleted": false, "createdAt": "2025-11-03T12:20:47.901Z" }, { "id": 39, "text": "Current implementation: rows[0-4] = header strings (DELETE), rows[5] = separator (KEEP), rows[6-11] = details strings (DELETE), rows[12+] = columns (KEEP)", "deleted": false, "createdAt": "2025-11-03T12:20:49.834Z" }, { "id": 40, "text": "Separators use buildBorderRow which calculates width based on colWidth and colRemainder - must match column widths exactly for border alignment", "deleted": false, "createdAt": "2025-11-03T12:21:23.406Z" }, { "id": 41, "text": "WorkUnitDetailsContainer width must match totalWidth calculation (sum of column widths + separators) to align with table borders", "deleted": false, "createdAt": "2025-11-03T12:21:25.084Z" }, { "id": 42, "text": "WorkUnitDescription empty/whitespace-only strings must display 3 blank lines (lines 2-4 empty) - NO 'No description' text", "deleted": false, "createdAt": "2025-11-03T12:21:26.824Z" }, { "id": 43, "text": "WorkUnitMetadata fields must be joined with ' | ' ONLY between present fields (no leading/trailing separators)", "deleted": false, "createdAt": "2025-11-03T12:21:28.787Z" }, { "id": 44, "text": "Current CheckpointPanel (lines 1-105 of CheckpointPanel.tsx) must be replaced with simpler CheckpointStatus component receiving counts as props", "deleted": false, "createdAt": "2025-11-03T12:21:30.956Z" }, { "id": 45, "text": "Current ChangedFilesPanel (lines 1-19 of ChangedFilesPanel.tsx) displays keyboard shortcuts - rename to KeybindingShortcuts, add borderTop", "deleted": false, "createdAt": "2025-11-03T12:21:32.348Z" }, { "id": 46, "text": "Borders use hybrid border system: HeaderContainer Box borderStyle='single' creates top/sides/bottom, then junction separators (├┤┬┼┴) extend vertical borders to connect Details and Columns - ONE continuous structure", "deleted": false, "createdAt": "2025-11-03T12:34:39.159Z" }, { "id": 47, "text": "KeybindingShortcuts component has borderTop only (INSIDE InfoContainer, not separate line) - extends as internal horizontal line within HeaderContainer", "deleted": false, "createdAt": "2025-11-03T12:34:42.392Z" }, { "id": 48, "text": "WorkUnitDetailsContainer must NOT use Box borderStyle - only borderLeft and borderRight (junction separators ├┤ render top/bottom as part of continuous border structure)", "deleted": false, "createdAt": "2025-11-03T12:34:45.838Z" }, { "id": 49, "text": "KeybindingShortcuts component MUST render its own borderTop separator as part of its Box (borderTop: true, all others: false) - this is INSIDE HeaderContainer, part of internal layout", "deleted": false, "createdAt": "2025-11-03T12:34:49.088Z" }, { "id": 50, "text": "Separator after header must use buildBorderRow with 'plain' separator type (├─...─┤) - creates junction that extends HeaderContainer borders to connect with Details", "deleted": false, "createdAt": "2025-11-03T12:34:53.158Z" }, { "id": 51, "text": "Junction characters form continuous border: ├ (left extend), ┤ (right extend), ┬ (top T-junction), ┼ (cross junction), ┴ (bottom T-junction) - NEVER two separate lines", "deleted": false, "createdAt": "2025-11-03T12:35:41.096Z" } ], "nextRuleId": 52, "examples": [ { "id": 0, "text": "Header Box renders with Logo (12ch width) on left and InfoContainer (flexGrow) on right, total internal height 4 lines", "deleted": false, "createdAt": "2025-11-03T12:13:53.047Z" }, { "id": 1, "text": "CheckpointStatus shows 'Checkpoints: 3 Manual, 5 Auto' when checkpoints exist", "deleted": false, "createdAt": "2025-11-03T12:13:54.641Z" }, { "id": 2, "text": "CheckpointStatus shows 'Checkpoints: None' when no checkpoints exist", "deleted": false, "createdAt": "2025-11-03T12:13:56.302Z" }, { "id": 3, "text": "KeybindingShortcuts displays 'C View Checkpoints ◆ F View Changed Files' with borderTop only", "deleted": false, "createdAt": "2025-11-03T12:13:57.956Z" }, { "id": 4, "text": "WorkUnitTitle displays 'BOARD-001: Feature Title' on single line, truncates if too long", "deleted": false, "createdAt": "2025-11-03T12:13:59.951Z" }, { "id": 5, "text": "WorkUnitDescription wraps text across 3 lines, truncates line 3 with '...' if description exceeds 3 lines", "deleted": false, "createdAt": "2025-11-03T12:14:01.958Z" }, { "id": 6, "text": "WorkUnitMetadata displays 'Epic: auth | Estimate: 5pts | Status: implementing' on single line", "deleted": false, "createdAt": "2025-11-03T12:14:03.379Z" }, { "id": 7, "text": "HeaderContainer renders as Box with borderStyle='single', containing flexDirection='row' with Logo (12ch, flexShrink) and InfoContainer (flexGrow)", "deleted": false, "createdAt": "2025-11-03T12:17:20.061Z" }, { "id": 8, "text": "InfoContainer has flexDirection='column', height={4}, contains CheckpointStatus (flexGrow) and KeybindingShortcuts (flexGrow with borderTop)", "deleted": false, "createdAt": "2025-11-03T12:17:21.672Z" }, { "id": 9, "text": "CheckpointStatus displays checkpoint counts with NO border (all border props false or undefined)", "deleted": false, "createdAt": "2025-11-03T12:17:23.264Z" }, { "id": 10, "text": "KeybindingShortcuts renders Box with borderTop={true}, borderBottom={false}, borderLeft={false}, borderRight={false}", "deleted": false, "createdAt": "2025-11-03T12:17:24.883Z" }, { "id": 11, "text": "WorkUnitDetailsContainer renders between two separators (├─...─┤), has borderLeft={true}, borderRight={true}, borderTop={false}, borderBottom={false}", "deleted": false, "createdAt": "2025-11-03T12:17:26.356Z" }, { "id": 12, "text": "WorkUnitTitle 'BOARD-001: Very Long Feature Title That Exceeds Width' truncates to 'BOARD-001: Very Long Feature Title' (no ellipsis)", "deleted": false, "createdAt": "2025-11-03T12:17:28.252Z" }, { "id": 13, "text": "WorkUnitDescription with 5 lines of text wraps to lines 1-2 fully, line 3 truncates with '...' at end (lines 4-5 discarded)", "deleted": false, "createdAt": "2025-11-03T12:17:29.804Z" }, { "id": 14, "text": "WorkUnitDescription wraps 'This is a long description that needs to wrap' into line 1: 'This is a long', line 2: 'description that', line 3: 'needs to wrap'", "deleted": false, "createdAt": "2025-11-03T12:17:31.477Z" }, { "id": 15, "text": "WorkUnitMetadata with epic='auth', estimate=5, status='implementing' displays: 'Epic: auth | Estimate: 5pts | Status: implementing'", "deleted": false, "createdAt": "2025-11-03T12:17:33.257Z" }, { "id": 16, "text": "WorkUnitMetadata with only estimate=3 (no epic, no status) displays: 'Estimate: 3pts' (no extra separators)", "deleted": false, "createdAt": "2025-11-03T12:17:35.212Z" }, { "id": 17, "text": "When selectedWorkUnit is null: WorkUnitTitle shows 'No work unit selected' centered on line 1, lines 2-5 are empty spaces (NOT 'No description')", "deleted": false, "createdAt": "2025-11-03T12:17:37.084Z" }, { "id": 18, "text": "WorkUnitDescription empty string displays 3 blank lines (lines 2-4 are empty, no 'No description' text)", "deleted": false, "createdAt": "2025-11-03T12:17:44.112Z" }, { "id": 19, "text": "Logo component renders 4 rows of exactly 12 characters each (includes padding), occupies 12ch width with flexShrink={0}", "deleted": false, "createdAt": "2025-11-03T12:17:46.130Z" }, { "id": 20, "text": "Very narrow terminal (60 cols) causes Logo flexShrink to compress, InfoContainer maintains flexGrow to fill remaining space", "deleted": false, "createdAt": "2025-11-03T12:17:50.975Z" }, { "id": 21, "text": "WorkUnitDescription with exactly 3 lines of text displays all 3 lines without truncation (no ellipsis needed)", "deleted": false, "createdAt": "2025-11-03T12:17:52.732Z" }, { "id": 22, "text": "Current implementation uses rows.push('│' + content + '│') for header/details (lines 496-617) - MUST BE REMOVED", "deleted": false, "createdAt": "2025-11-03T12:18:37.263Z" }, { "id": 23, "text": "Refactored implementation renders HeaderContainer as <Box borderStyle='single'>...</Box> BEFORE separator (no string injection)", "deleted": false, "createdAt": "2025-11-03T12:18:39.361Z" }, { "id": 24, "text": "Refactored implementation renders WorkUnitDetailsContainer as <Box borderLeft borderRight>...</Box> BETWEEN separators", "deleted": false, "createdAt": "2025-11-03T12:18:41.729Z" }, { "id": 25, "text": "WorkUnitDescription component receives description prop, wraps internally using wrapText helper, renders 3 Text components", "deleted": false, "createdAt": "2025-11-03T12:18:43.713Z" }, { "id": 26, "text": "Terminal height 24 → fixedRows 19 → viewport 5 → columns display 5 work units max per column", "deleted": false, "createdAt": "2025-11-03T12:18:45.171Z" }, { "id": 27, "text": "WorkUnitMetadata with epic='authentication' (no estimate, no status) displays: 'Epic: authentication' (single field, no separators)", "deleted": false, "createdAt": "2025-11-03T12:18:46.864Z" }, { "id": 28, "text": "Terminal 24 rows: Header(6) + Sep(1) + Details(5) + Sep(1) + ColHeaders(2) + FooterSep(1) + Footer(1) + Bottom(1) = 18 static → 6 rows for columns", "deleted": false, "createdAt": "2025-11-03T12:19:33.552Z" }, { "id": 29, "text": "Terminal 40 rows: Same 18 static rows → 22 rows for columns (grows with terminal height)", "deleted": false, "createdAt": "2025-11-03T12:19:35.145Z" }, { "id": 30, "text": "HeaderContainer Box renders with height implicit from content (4 internal lines + 2 border lines = 6 total rows)", "deleted": false, "createdAt": "2025-11-03T12:19:36.586Z" }, { "id": 31, "text": "WorkUnitDetailsContainer renders 5 content rows (Title 1 + Description 3 + Metadata 1), borders from separators (NOT counted in container height)", "deleted": false, "createdAt": "2025-11-03T12:19:38.389Z" }, { "id": 32, "text": "InfoContainer with height={4} contains CheckpointStatus (flexGrow, takes ~2 lines) and KeybindingShortcuts (flexGrow with borderTop, takes ~2 lines)", "deleted": false, "createdAt": "2025-11-03T12:20:06.868Z" }, { "id": 33, "text": "WorkUnitDetailsContainer with height={5} renders Title(1) + Description(3 via flexGrow) + Metadata(1) = 5 lines total", "deleted": false, "createdAt": "2025-11-03T12:20:08.676Z" }, { "id": 34, "text": "CheckpointStatus 'Checkpoints: 10 Manual, 20 Auto' wraps if width insufficient, uses flexGrow to take available vertical space", "deleted": false, "createdAt": "2025-11-03T12:20:10.341Z" }, { "id": 35, "text": "KeybindingShortcuts renders Text with borderTop separator above it, content 'C View Checkpoints ◆ F View Changed Files' on single line", "deleted": false, "createdAt": "2025-11-03T12:20:12.218Z" }, { "id": 36, "text": "Current line 714-722: Header Box contains Logo + CheckpointPanel + ChangedFilesPanel (already component-based, borderStyle='single' works)", "deleted": false, "createdAt": "2025-11-03T12:20:52.070Z" }, { "id": 37, "text": "Refactor needed: Replace CheckpointPanel with CheckpointStatus component (uses checkpoint counts text, NO file watching in component)", "deleted": false, "createdAt": "2025-11-03T12:20:53.540Z" }, { "id": 38, "text": "Refactor needed: Replace ChangedFilesPanel with KeybindingShortcuts component (shows keyboard shortcuts, has borderTop)", "deleted": false, "createdAt": "2025-11-03T12:20:54.956Z" }, { "id": 39, "text": "Refactor needed: Insert WorkUnitDetailsContainer between separators (after line 725 separator, before column rendering)", "deleted": false, "createdAt": "2025-11-03T12:20:56.344Z" }, { "id": 40, "text": "WorkUnitDescription receives fullDescription string, calls wrapText(fullDescription, totalWidth, 3), renders up to 3 Text components with bold cyan", "deleted": false, "createdAt": "2025-11-03T12:20:57.940Z" }, { "id": 41, "text": "WorkUnitTitle with id='BOARD-001', title='Feature' renders Text: 'BOARD-001: Feature' with wrap='truncate' (no manual truncation)", "deleted": false, "createdAt": "2025-11-03T12:20:59.603Z" }, { "id": 42, "text": "totalWidth calculated as: STATES.reduce((sum, _, idx) => sum + getColumnWidth(idx, colWidth, colRemainder), 0) + (STATES.length - 1)", "deleted": false, "createdAt": "2025-11-03T12:21:34.010Z" }, { "id": 43, "text": "WorkUnitMetadata with epic='auth', estimate=undefined, status='done' displays: 'Epic: auth | Status: done' (skips missing estimate)", "deleted": false, "createdAt": "2025-11-03T12:21:35.727Z" }, { "id": 44, "text": "WorkUnitDescription with description='\\n\\n\\n' (only newlines) normalizes to empty string, displays 3 blank lines (no text)", "deleted": false, "createdAt": "2025-11-03T12:21:37.669Z" }, { "id": 45, "text": "WorkUnitTitle with very short title 'TUI-001: Fix' fits entirely, displays as-is with no truncation (wrap='truncate' allows full text)", "deleted": false, "createdAt": "2025-11-03T12:21:39.340Z" }, { "id": 46, "text": "HeaderContainer paddingX={1} adds internal padding, Logo width={12} reserves space, InfoContainer flexGrow={1} fills remaining width", "deleted": false, "createdAt": "2025-11-03T12:21:40.873Z" }, { "id": 47, "text": "Header Box corners (┌┐└┘) connect via junctions to separators (├┤) which extend vertical borders to connect Details (│) and Columns - ONE continuous structure using junction characters (├┤┬┼┴)", "deleted": false, "createdAt": "2025-11-03T12:35:12.188Z" }, { "id": 48, "text": "Separator after header uses buildBorderRow(..., 'plain') producing ├─────┤ junction (no column dividers) that extends HeaderContainer vertical borders", "deleted": false, "createdAt": "2025-11-03T12:35:15.277Z" }, { "id": 49, "text": "Separator before columns uses buildBorderRow(..., 'top') producing ├─┬─┤ junction (with column dividers ┬) connecting Details to Columns", "deleted": false, "createdAt": "2025-11-03T12:35:18.245Z" }, { "id": 50, "text": "Separator after header buildBorderRow(colWidth, colRemainder, '├', '─', '┤', 'plain') creates junction line connecting HeaderContainer bottom border to Details top via left/right junctions", "deleted": false, "createdAt": "2025-11-03T12:35:21.850Z" }, { "id": 51, "text": "Separator buildBorderRow(..., 'cross') at line 631 creates ├─┼─┤ junction with cross junctions (┼) at column header separator (columns above AND below)", "deleted": false, "createdAt": "2025-11-03T12:35:25.633Z" }, { "id": 52, "text": "Complete 23-row structure: Row 1-6 Header Box (┌│└), Row 6-7 Junction (├┤), Row 7-11 Details (│), Row 12 Junction with dividers (├┬┤), Row 13-14 Column headers, Row 14 Cross junction (├┼┤), Row 15-20 Dynamic columns, Row 21 Bottom junction (├┴┤), Row 22-23 Footer - ALL connected as ONE border structure", "deleted": false, "createdAt": "2025-11-03T12:35:39.420Z" }, { "id": 53, "text": "WRONG: Two lines '└─┘' then '├─┤' creates gap. CORRECT: Single junction line '├─┤' extends vertical borders from section above to section below", "deleted": false, "createdAt": "2025-11-03T12:35:42.620Z" } ], "nextExampleId": 54, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-03T15:07:56.023Z" }, "TUI-016": { "id": "TUI-016", "title": "Refactor checkpoint counts to be command-triggered instead of file-watching", "type": "story", "status": "done", "createdAt": "2025-11-03T15:08:07.097Z", "updatedAt": "2025-11-03T23:56:24.398Z", "description": "Currently, the TUI watches the .git/fspec-checkpoints-index directory using chokidar to detect when checkpoint counts change. This should be refactored to update checkpoint counts when checkpoint commands are executed instead. This applies to both manual checkpoints (fspec checkpoint) and automatic checkpoints. The TUI should receive events or updates when checkpoints are created or restored, eliminating the need for file system watching.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T21:50:52.207Z" }, { "state": "testing", "timestamp": "2025-11-03T22:24:55.201Z" }, { "state": "specifying", "timestamp": "2025-11-03T22:31:54.206Z" }, { "state": "testing", "timestamp": "2025-11-03T22:32:06.180Z" }, { "state": "specifying", "timestamp": "2025-11-03T22:44:18.072Z" }, { "state": "testing", "timestamp": "2025-11-03T23:32:14.278Z" }, { "state": "testing", "timestamp": "2025-11-03T23:34:49.241Z" }, { "state": "implementing", "timestamp": "2025-11-03T23:43:52.007Z" }, { "state": "validating", "timestamp": "2025-11-03T23:52:39.492Z" }, { "state": "done", "timestamp": "2025-11-03T23:56:24.398Z" } ], "rules": [ { "id": 0, "text": "CheckpointPanel must update counts when manual checkpoints are created via 'fspec checkpoint' command", "deleted": false, "createdAt": "2025-11-03T21:51:42.991Z" }, { "id": 1, "text": "CheckpointPanel must update counts when automatic checkpoints are created during status transitions", "deleted": false, "createdAt": "2025-11-03T21:51:48.003Z" }, { "id": 2, "text": "CheckpointPanel must update counts when checkpoints are restored via 'fspec restore-checkpoint' command", "deleted": false, "createdAt": "2025-11-03T21:51:53.261Z" }, { "id": 3, "text": "CheckpointPanel must update counts when checkpoints are cleaned up via 'fspec cleanup-checkpoints' command", "deleted": false, "createdAt": "2025-11-03T21:51:58.651Z" }, { "id": 4, "text": "Chokidar file-watching dependency must be removed from CheckpointPanel", "deleted": false, "createdAt": "2025-11-03T21:52:05.093Z" }, { "id": 5, "text": "Yes, TUI performs initial checkpoint counting on mount by calling useFspecStore.getState().loadCheckpointCounts(). This loads current state from disk. Subsequent updates come from IPC notifications.", "deleted": false, "createdAt": "2025-11-03T22:18:50.740Z" }, { "id": 6, "text": "IPC solves this. When checkpoint commands execute in another terminal, they send IPC message to TUI's server (net.connect to socket/pipe). If TUI not running, send fails silently. No file-watching needed.", "deleted": false, "createdAt": "2025-11-03T22:18:58.306Z" }, { "id": 7, "text": "Shared IPC utility (src/utils/ipc.ts) provides getIPCPath(), createIPCServer(), sendIPCMessage(), and cleanupIPCServer() functions", "deleted": false, "createdAt": "2025-11-03T22:19:05.550Z" }, { "id": 8, "text": "Zustand store must have checkpointCounts state and loadCheckpointCounts() action that reads from .git/fspec-checkpoints-index", "deleted": false, "createdAt": "2025-11-03T22:19:11.768Z" }, { "id": 9, "text": "IPC server must start when BoardView mounts and cleanup when unmounts (socket unlink on Unix, auto-cleanup on Windows)", "deleted": false, "createdAt": "2025-11-03T22:19:18.377Z" }, { "id": 10, "text": "CheckpointPanel must ALWAYS render from zustand store state (useFspecStore) to ensure reactivity - never read directly from filesystem", "deleted": false, "createdAt": "2025-11-03T22:21:03.950Z" } ], "nextRuleId": 11, "examples": [ { "id": 0, "text": "User creates manual checkpoint 'baseline' for TUI-016, CheckpointPanel shows updated manual count immediately", "deleted": false, "createdAt": "2025-11-03T21:52:12.078Z" }, { "id": 1, "text": "User moves work unit from testing to implementing, auto checkpoint created, CheckpointPanel shows updated auto count immediately", "deleted": false, "createdAt": "2025-11-03T21:52:17.540Z" }, { "id": 2, "text": "User runs 'fspec cleanup-checkpoints TUI-016', checkpoints deleted, CheckpointPanel shows updated counts immediately", "deleted": false, "createdAt": "2025-11-03T21:52:22.977Z" }, { "id": 3, "text": "TUI starts on Linux, IPC server listens at /tmp/fspec-tui.sock, user creates checkpoint in another terminal, command sends message to socket, TUI updates counts", "deleted": false, "createdAt": "2025-11-03T22:19:25.531Z" }, { "id": 4, "text": "TUI starts on Windows, IPC server listens at \\\\.\\pipe\\fspec-tui, user creates checkpoint, command connects to named pipe, sends message, TUI updates counts", "deleted": false, "createdAt": "2025-11-03T22:19:32.064Z" }, { "id": 5, "text": "TUI not running, user creates checkpoint in terminal, IPC send fails silently (connection refused), checkpoint command completes successfully without error", "deleted": false, "createdAt": "2025-11-03T22:20:57.039Z" } ], "nextExampleId": 6, "questions": [ { "id": 0, "text": "@human: Should we use an event emitter pattern to notify the TUI of checkpoint changes, or should CheckpointPanel poll for updates at regular intervals?", "deleted": false, "createdAt": "2025-11-03T21:52:29.294Z", "selected": true, "answer": "Use cross-platform IPC (Unix domain sockets on Linux/Mac, named pipes on Windows) via Node.js net module. TUI runs IPC server, checkpoint commands send messages. No event emitter pattern, no polling - direct IPC communication." }, { "id": 1, "text": "@human: When checkpoint commands are executed from within the TUI (if that's possible), should updates be synchronous or asynchronous?", "deleted": false, "createdAt": "2025-11-03T21:52:35.798Z", "selected": true, "answer": "Updates are asynchronous. IPC messages trigger zustand store loadCheckpointCounts() which updates state asynchronously, causing CheckpointPanel to re-render via React hooks." }, { "id": 2, "text": "@human: Should the TUI continue to perform initial checkpoint counting on mount (like current implementation), or should all counts come from command-triggered updates?", "deleted": false, "createdAt": "2025-11-03T21:52:42.698Z", "selected": true, "answer": "Yes, TUI performs initial checkpoint counting on mount by calling useFspecStore.getState().loadCheckpointCounts(). This loads current state from disk. Subsequent updates come from IPC notifications." }, { "id": 3, "text": "@human: If checkpoint commands are executed outside the TUI (in another terminal), how should the TUI detect those changes without file-watching?", "deleted": false, "createdAt": "2025-11-03T21:52:47.990Z", "selected": true, "answer": "IPC solves this. When checkpoint commands execute in another terminal, they send IPC message to TUI's server (net.connect to socket/pipe). If TUI not running, send fails silently. No file-watching needed." } ], "nextQuestionId": 4, "attachments": [ "spec/attachments/TUI-016/tui-016-ipc-architecture.md" ], "assumptions": [ "Use cross-platform IPC (Unix domain sockets on Linux/Mac, named pipes on Windows) via Node.js net module. TUI runs IPC server, checkpoint commands send messages. No event emitter pattern, no polling - direct IPC communication.", "Updates are asynchronous. IPC messages trigger zustand store loadCheckpointCounts() which updates state asynchronously, causing CheckpointPanel to re-render via React hooks." ], "userStory": { "role": "developer viewing the TUI board", "action": "see checkpoint counts update immediately when checkpoint commands execute", "benefit": "I have real-time visibility into checkpoints without file-watching overhead" }, "estimate": 8, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-03T23:56:24.398Z" }, "BUG-063": { "id": "BUG-063", "title": "@step validation hardcoded to JavaScript comment syntax, should be language-agnostic", "type": "bug", "status": "done", "createdAt": "2025-11-03T23:16:54.325Z", "updatedAt": "2025-11-03T23:27:50.704Z", "children": [], "description": "The @step validation in src/utils/step-validation.ts is hardcoded to match only JavaScript-style // comments. It should be language-agnostic and match @step annotations regardless of the comment syntax used (e.g., //, #, --, %, ', /* */, etc.). Currently it uses regex patterns like /^\\/\\/\\s*@step\\s+(Given|When|Then|And|But)\\s+(.+)$/ which only match // comments.", "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-03T23:17:14.357Z" }, { "state": "testing", "timestamp": "2025-11-03T23:20:18.421Z" }, { "state": "implementing", "timestamp": "2025-11-03T23:22:19.206Z" }, { "state": "validating", "timestamp": "2025-11-03T23:24:18.727Z" }, { "state": "done", "timestamp": "2025-11-03T23:27:50.705Z" } ], "rules": [ { "id": 0, "text": "@step validation must be language-agnostic and support all comment syntaxes", "deleted": false, "createdAt": "2025-11-03T23:17:22.383Z" }, { "id": 1, "text": "Must match @step anywhere in a comment line, not just at the start after //", "deleted": false, "createdAt": "2025-11-03T23:17:23.689Z" }, { "id": 2, "text": "Must extract only the step text between keyword and end of step, ignoring comment delimiters", "deleted": false, "createdAt": "2025-11-03T23:17:25.107Z" }, { "id": 3, "text": "Must support block comments like /* @step Given text */ and line comments like // @step, # @step, -- @step, % @step, ' @step", "deleted": false, "createdAt": "2025-11-03T23:17:26.803Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "JavaScript: // @step Given a dog shits in the woods → should extract 'Given a dog shits in the woods'", "deleted": false, "createdAt": "2025-11-03T23:17:36.638Z" }, { "id": 1, "text": "Python: # @step When I click the button → should extract 'When I click the button'", "deleted": false, "createdAt": "2025-11-03T23:17:38.213Z" }, { "id": 2, "text": "SQL: -- @step Then I see the result → should extract 'Then I see the result'", "deleted": false, "createdAt": "2025-11-03T23:17:39.717Z" }, { "id": 3, "text": "Block comment: /* @step Given a dog shits in the woods */ → should extract 'Given a dog shits in the woods'", "deleted": false, "createdAt": "2025-11-03T23:17:41.133Z" }, { "id": 4, "text": "MATLAB: % @step And the database is updated → should extract 'And the database is updated'", "deleted": false, "createdAt": "2025-11-03T23:17:42.461Z" }, { "id": 5, "text": "Visual Basic: ' @step But the error is logged → should extract 'But the error is logged'", "deleted": false, "createdAt": "2025-11-03T23:17:44.225Z" } ], "nextExampleId": 6, "architectureNotes": [ { "id": 0, "text": "Current implementation in src/utils/step-validation.ts uses hardcoded regex: /^\\/\\/\\s*@step\\s+(Given|When|Then|And|But)\\s+(.+)$/ on line 53-54", "deleted": false, "createdAt": "2025-11-03T23:17:54.307Z" }, { "id": 1, "text": "Function extractStepComments() needs to be refactored to use language-agnostic regex that matches @step pattern anywhere in the line", "deleted": false, "createdAt": "2025-11-03T23:17:55.928Z" }, { "id": 2, "text": "New regex should match: .*@step\\s+(Given|When|Then|And|But)\\s+(.+?)(?:\\s*\\*\\/)?$ to capture step text and ignore trailing comment delimiters", "deleted": false, "createdAt": "2025-11-03T23:17:57.411Z" } ], "nextNoteId": 3, "userStory": { "role": "developer using fspec with any programming language", "action": "use @step comments in my test files", "benefit": "the validation works regardless of my language's comment syntax" }, "estimate": 3, "questions": [], "nextQuestionId": 0, "updated": "2025-11-03T23:27:50.704Z" }, "BUG-064": { "id": "BUG-064", "title": "Duplicate work unit IDs in state arrays when moving backward or to same state", "type": "bug", "status": "done", "createdAt": "2025-11-03T23:36:55.910Z", "updatedAt": "2025-11-04T00:28:24.069Z", "description": "The update-work-unit-status command creates duplicate entries in the states arrays when moving a work unit backward (e.g., testing → specifying) or when moving to the same state it's already in. The removal logic fails to properly remove the work unit ID from the previous state array before adding it to the new state array.", "children": [], "attachments": [ "spec/attachments/BUG-064/bug-064-details.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T00:17:48.711Z" }, { "state": "testing", "timestamp": "2025-11-04T00:21:43.317Z" }, { "state": "implementing", "timestamp": "2025-11-04T00:23:23.564Z" }, { "state": "validating", "timestamp": "2025-11-04T00:25:05.324Z" }, { "state": "done", "timestamp": "2025-11-04T00:28:24.069Z" } ], "userStory": { "role": "developer using fspec", "action": "move work units backward or to the same state", "benefit": "state arrays remain consistent without duplicates" }, "rules": [ { "id": 0, "text": "Each work unit ID must appear in exactly one state array at a time", "deleted": false, "createdAt": "2025-11-04T00:18:06.219Z" }, { "id": 1, "text": "Work unit ID must be removed from previous state array before adding to new state array", "deleted": false, "createdAt": "2025-11-04T00:18:11.176Z" }, { "id": 2, "text": "Moving to the same state should be idempotent (no duplicate entries)", "deleted": false, "createdAt": "2025-11-04T00:18:15.632Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Moving work unit from testing to specifying to testing should result in only one entry in testing array", "deleted": false, "createdAt": "2025-11-04T00:18:20.890Z" }, { "id": 1, "text": "Moving work unit to the same state it's already in should not create a duplicate entry", "deleted": false, "createdAt": "2025-11-04T00:18:28.903Z" }, { "id": 2, "text": "After any state transition, querying the states should return the work unit in only one state", "deleted": false, "createdAt": "2025-11-04T00:18:33.669Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-04T00:28:24.069Z" }, "BUG-065": { "id": "BUG-065", "title": "TUI-016 incomplete: CheckpointPanel using chokidar instead of IPC+Zustand", "type": "bug", "status": "done", "createdAt": "2025-11-04T00:40:56.152Z", "updatedAt": "2025-11-04T02:33:01.248Z", "description": "TUI-016 IPC infrastructure is complete but not connected. CheckpointPanel still uses chokidar file-watching which must be REMOVED. Three components need connection: Zustand store checkpoint state, BoardView IPC server, and CheckpointPanel refactor.", "children": [], "attachments": [ "spec/attachments/BUG-065/tui-016-incomplete-implementation.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T00:42:05.236Z" }, { "state": "testing", "timestamp": "2025-11-04T00:47:49.495Z" }, { "state": "testing", "timestamp": "2025-11-04T00:49:50.302Z" }, { "state": "implementing", "timestamp": "2025-11-04T00:53:10.346Z" }, { "state": "validating", "timestamp": "2025-11-04T00:55:43.493Z" }, { "state": "done", "timestamp": "2025-11-04T01:03:08.239Z" }, { "state": "implementing", "timestamp": "2025-11-04T01:12:43.887Z" }, { "state": "validating", "timestamp": "2025-11-04T02:32:59.095Z" }, { "state": "done", "timestamp": "2025-11-04T02:33:01.248Z" } ], "userStory": { "role": "TUI user monitoring checkpoint counts", "action": "see real-time checkpoint updates via IPC", "benefit": "checkpoint display stays accurate without file-watching overhead" }, "rules": [ { "id": 0, "text": "CheckpointPanel MUST NOT use chokidar file-watching", "deleted": false, "createdAt": "2025-11-04T00:42:19.753Z" }, { "id": 1, "text": "CheckpointPanel MUST read checkpoint counts from Zustand store", "deleted": false, "createdAt": "2025-11-04T00:42:25.009Z" }, { "id": 2, "text": "Zustand store MUST have checkpointCounts state with manual and auto counts", "deleted": false, "createdAt": "2025-11-04T00:42:30.283Z" }, { "id": 3, "text": "Zustand store MUST have loadCheckpointCounts() action to read from .git/fspec-checkpoints-index/", "deleted": false, "createdAt": "2025-11-04T00:42:36.264Z" }, { "id": 4, "text": "BoardView MUST create IPC server on mount to listen for checkpoint-changed messages", "deleted": false, "createdAt": "2025-11-04T00:42:42.260Z" }, { "id": 5, "text": "BoardView MUST call loadCheckpointCounts() when receiving checkpoint-changed IPC message", "deleted": false, "createdAt": "2025-11-04T00:42:47.437Z" }, { "id": 6, "text": "BoardView MUST cleanup IPC server on unmount", "deleted": false, "createdAt": "2025-11-04T00:42:52.710Z" } ], "nextRuleId": 7, "examples": [ { "id": 0, "text": "User runs 'fspec checkpoint TUI-016 baseline' in terminal A, TUI in terminal B sees count update from 20 to 21 manual checkpoints immediately", "deleted": false, "createdAt": "2025-11-04T00:42:59.430Z" }, { "id": 1, "text": "User runs 'fspec update-work-unit-status TUI-016 implementing' triggering auto checkpoint, TUI shows count update from 58 to 59 auto checkpoints immediately", "deleted": false, "createdAt": "2025-11-04T00:43:05.363Z" }, { "id": 2, "text": "User starts TUI, CheckpointPanel loads initial counts from filesystem showing 21 manual and 59 auto checkpoints", "deleted": false, "createdAt": "2025-11-04T00:43:10.967Z" }, { "id": 3, "text": "User runs 'fspec cleanup-checkpoints TUI-016 --keep-last 5' deleting 15 checkpoints, TUI shows counts drop from 21 to 6 manual and 59 to 49 auto immediately", "deleted": false, "createdAt": "2025-11-04T00:43:17.703Z" }, { "id": 4, "text": "CheckpointPanel imports from Zustand store, NOT chokidar - no chokidar import exists in file", "deleted": false, "createdAt": "2025-11-04T00:43:24.783Z" }, { "id": 5, "text": "Zustand store has checkpointCounts state accessible via useFspecStore(state => state.checkpointCounts)", "deleted": false, "createdAt": "2025-11-04T00:43:30.133Z" } ], "nextExampleId": 6, "estimate": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-04T02:33:01.248Z" }, "TUI-017": { "id": "TUI-017", "title": "Replace shimmer with fast-forward emojis for active work unit", "type": "story", "status": "done", "createdAt": "2025-11-04T02:35:55.203Z", "updatedAt": "2025-11-04T03:01:31.946Z", "description": "Replace the current shimmer effect on the active work unit in the TUI with fast-forward emojis (⏩) placed on both left and right sides. Format: ⏩ WORK-UNIT-ID [points] ⏩", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T02:36:10.236Z" }, { "state": "testing", "timestamp": "2025-11-04T02:38:29.037Z" }, { "state": "implementing", "timestamp": "2025-11-04T02:41:58.783Z" }, { "state": "validating", "timestamp": "2025-11-04T02:43:21.103Z" }, { "state": "done", "timestamp": "2025-11-04T02:44:10.189Z" }, { "state": "implementing", "timestamp": "2025-11-04T02:45:29.942Z" }, { "state": "validating", "timestamp": "2025-11-04T03:00:34.274Z" }, { "state": "done", "timestamp": "2025-11-04T03:01:31.946Z" } ], "userStory": { "role": "developer using the TUI", "action": "see which work unit is currently active with fast-forward emojis", "benefit": "I can quickly identify the active work without visual distraction from shimmer effects" }, "rules": [ { "id": 0, "text": "Active work unit must display fast-forward emoji (⏩) on both left and right sides", "deleted": false, "createdAt": "2025-11-04T02:36:25.062Z" }, { "id": 1, "text": "Shimmer effect must be completely removed from active work unit display", "deleted": false, "createdAt": "2025-11-04T02:36:26.356Z" }, { "id": 2, "text": "Format must be: ⏩ WORK-UNIT-ID [points] ⏩ with single spaces between elements", "deleted": false, "createdAt": "2025-11-04T02:36:27.758Z" }, { "id": 3, "text": "Non-active work units must not display the fast-forward emojis", "deleted": false, "createdAt": "2025-11-04T02:36:29.306Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "When TUI-015 [3] is active, display shows: ⏩ TUI-015 [3] ⏩", "deleted": false, "createdAt": "2025-11-04T02:36:38.426Z" }, { "id": 1, "text": "When TUI-016 [5] is not active, display shows: TUI-016 [5] (no emojis)", "deleted": false, "createdAt": "2025-11-04T02:36:39.837Z" }, { "id": 2, "text": "When switching from TUI-015 to TUI-016, emojis move from TUI-015 to TUI-016", "deleted": false, "createdAt": "2025-11-04T02:36:41.426Z" }, { "id": 3, "text": "Shimmer animation that previously highlighted active work unit is no longer visible", "deleted": false, "createdAt": "2025-11-04T02:36:43.379Z" } ], "nextExampleId": 4, "architectureNotes": [ { "id": 0, "text": "Replace shimmer animation with static emoji indicators (⏩) in checkpoint panel", "deleted": false, "createdAt": "2025-11-04T02:37:13.054Z" }, { "id": 1, "text": "Modify WorkUnitRow component in dev-tui.tsx to conditionally render emojis around active work unit", "deleted": false, "createdAt": "2025-11-04T02:37:14.285Z" }, { "id": 2, "text": "Remove gradient and shimmer effect logic from Ink Box component styling", "deleted": false, "createdAt": "2025-11-04T02:37:15.608Z" } ], "nextNoteId": 3, "estimate": 2, "questions": [], "nextQuestionId": 0, "updated": "2025-11-04T03:01:31.946Z" }, "BUG-066": { "id": "BUG-066", "title": "Auto-checkpoints not cleaned up when work unit moves to done", "type": "bug", "status": "done", "createdAt": "2025-11-04T04:22:44.627Z", "updatedAt": "2025-11-04T04:37:22.179Z", "description": "When a work unit transitions to done status, automatic checkpoints (created during state transitions) should be cleaned up, but manual checkpoints should be preserved. Currently, auto-compact runs but does NOT clean up any checkpoints (automatic or manual).", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T04:22:50.290Z" }, { "state": "testing", "timestamp": "2025-11-04T04:29:00.858Z" }, { "state": "implementing", "timestamp": "2025-11-04T04:32:31.579Z" }, { "state": "validating", "timestamp": "2025-11-04T04:34:35.212Z" }, { "state": "done", "timestamp": "2025-11-04T04:37:22.179Z" } ], "rules": [ { "id": 0, "text": "Auto-checkpoints are created with naming pattern: {workUnitId}-auto-{fromState} (e.g., AUTH-001-auto-specifying)", "deleted": false, "createdAt": "2025-11-04T04:23:00.647Z" }, { "id": 1, "text": "Manual checkpoints are created by user with custom names and should NEVER be deleted automatically", "deleted": false, "createdAt": "2025-11-04T04:23:01.981Z" }, { "id": 2, "text": "When work unit moves to done status, ONLY auto-checkpoints for that work unit should be deleted", "deleted": false, "createdAt": "2025-11-04T04:23:03.347Z" }, { "id": 3, "text": "Checkpoints are stored in git refs (refs/fspec-checkpoints/{workUnitId}/{checkpointName}) and index files (.git/fspec-checkpoints-index/{workUnitId}.json)", "deleted": false, "createdAt": "2025-11-04T04:23:05.191Z" }, { "id": 4, "text": "CURRENT BUG: cleanupCheckpoints() function exists in git-checkpoint.ts but is a STUB that does not actually delete anything (lines 514-515: 'For now, just return the split')", "deleted": false, "createdAt": "2025-11-04T04:25:33.407Z" }, { "id": 5, "text": "CURRENT BUG: cleanupCheckpoints() is NEVER called from update-work-unit-status.ts when work unit moves to done status", "deleted": false, "createdAt": "2025-11-04T04:25:35.294Z" }, { "id": 6, "text": "CURRENT IMPLEMENTATION FLAW: cleanupCheckpoints() uses keepLast parameter which would delete BOTH manual and auto checkpoints - needs to filter by isAutomatic flag instead", "deleted": false, "createdAt": "2025-11-04T04:25:36.708Z" }, { "id": 7, "text": "listCheckpoints() already identifies automatic checkpoints using isAutomatic flag (line 465-467: checks if name starts with {workUnitId}-auto-)", "deleted": false, "createdAt": "2025-11-04T04:25:38.621Z" }, { "id": 8, "text": "To delete checkpoint: (1) delete git ref file at .git/refs/fspec-checkpoints/{workUnitId}/{checkpointName} using fs.unlink, (2) remove entry from index file at .git/fspec-checkpoints-index/{workUnitId}.json", "deleted": false, "createdAt": "2025-11-04T04:25:40.142Z" }, { "id": 9, "text": "FIX LOCATION: In update-work-unit-status.ts after auto-compact completes (around line 489), need to call cleanup function to delete auto-checkpoints for the work unit", "deleted": false, "createdAt": "2025-11-04T04:25:47.287Z" } ], "nextRuleId": 10, "examples": [ { "id": 0, "text": "Work unit AUTH-001 has auto-checkpoints: AUTH-001-auto-specifying, AUTH-001-auto-testing, and manual checkpoint: before-major-refactor. When AUTH-001 moves to done, only the 2 auto-checkpoints should be deleted, before-major-refactor should remain", "deleted": false, "createdAt": "2025-11-04T04:23:13.334Z" }, { "id": 1, "text": "Work unit BUG-027 has only manual checkpoints: before-fix, after-tests. When BUG-027 moves to done, no checkpoints should be deleted", "deleted": false, "createdAt": "2025-11-04T04:23:14.752Z" }, { "id": 2, "text": "Work unit FEAT-010 has only auto-checkpoints: FEAT-010-auto-backlog, FEAT-010-auto-specifying. When FEAT-010 moves to done, all auto-checkpoints should be deleted", "deleted": false, "createdAt": "2025-11-04T04:23:16.202Z" } ], "nextExampleId": 3, "attachments": [ "spec/attachments/BUG-066/bug-066-code-analysis.md" ], "userStory": { "role": "developer using fspec", "action": "have auto-checkpoints cleaned up when work unit is done", "benefit": "checkpoint storage doesn't accumulate indefinitely and manual checkpoints are preserved" }, "estimate": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-04T04:37:22.179Z" }, "REFAC-003": { "id": "REFAC-003", "title": "Improve @step workflow clarity to prevent wrong test file and missing comments", "type": "story", "status": "done", "createdAt": "2025-11-04T05:12:00.095Z", "updatedAt": "2025-11-04T05:32:44.160Z", "description": "AI agents frequently miss @step comments or add them to wrong test files. Make requirement more prominent, clarify ONE scenario = ONE test mapping, and guide recreation when tests written incorrectly.", "children": [], "attachments": [ "spec/attachments/REFAC-003/step-workflow-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T05:12:11.270Z" }, { "state": "testing", "timestamp": "2025-11-04T05:20:40.027Z" }, { "state": "implementing", "timestamp": "2025-11-04T05:22:37.043Z" }, { "state": "testing", "timestamp": "2025-11-04T05:23:25.673Z" }, { "state": "implementing", "timestamp": "2025-11-04T05:25:55.501Z" }, { "state": "validating", "timestamp": "2025-11-04T05:27:11.948Z" }, { "state": "testing", "timestamp": "2025-11-04T05:29:59.285Z" }, { "state": "implementing", "timestamp": "2025-11-04T05:30:32.495Z" }, { "state": "validating", "timestamp": "2025-11-04T05:32:00.839Z" }, { "state": "done", "timestamp": "2025-11-04T05:32:44.160Z" } ], "rules": [ { "id": 0, "text": "@step requirement currently buried in 42-line testing state reminder (lines 94-113 of system-reminder.ts)", "deleted": false, "createdAt": "2025-11-04T05:12:24.426Z" }, { "id": 1, "text": "AI adds @step comments to WRONG test file, causing validation to fail even though comments exist", "deleted": false, "createdAt": "2025-11-04T05:12:26.429Z" }, { "id": 2, "text": "ONE scenario must map to ONE test with ALL @step comments in THAT test (not spread across files)", "deleted": false, "createdAt": "2025-11-04T05:12:27.909Z" }, { "id": 3, "text": "@step comments must be added DURING test writing, not as separate step after", "deleted": false, "createdAt": "2025-11-04T05:12:29.353Z" }, { "id": 4, "text": "When AI creates tests without @step comments, it should DELETE and RECREATE tests correctly rather than editing", "deleted": false, "createdAt": "2025-11-04T05:12:30.580Z" }, { "id": 5, "text": "Validation error already shows missing steps with exact text (formatValidationError in step-validation.ts:243-248)", "deleted": false, "createdAt": "2025-11-04T05:12:32.323Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "JOURNAL.md BUG-064: AI only learned about @step requirement when blocked, said requirement was 'buried in long message'", "deleted": false, "createdAt": "2025-11-04T05:12:43.842Z" }, { "id": 1, "text": "AI writes tests without @step, link-coverage fails, AI then adds @step comments but to wrong test file, validation still fails", "deleted": false, "createdAt": "2025-11-04T05:12:45.118Z" }, { "id": 2, "text": "JOURNAL.md BUG-065: User told AI to 'just recreate the test' instead of editing when @step placement was wrong structurally", "deleted": false, "createdAt": "2025-11-04T05:12:46.739Z" }, { "id": 3, "text": "Correct workflow: AI creates test WITH @step comments from the start, validation passes immediately", "deleted": false, "createdAt": "2025-11-04T05:12:48.247Z" } ], "nextExampleId": 4, "userStory": { "role": "AI agent using fspec ACDD workflow", "action": "understand @step requirements clearly before writing tests", "benefit": "I create tests correctly the first time with proper @step comments in the right test file" }, "estimate": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-04T05:32:44.160Z" }, "BUG-068": { "id": "BUG-068", "title": "fspec add-step appends instead of replacing prefill placeholders", "type": "bug", "status": "done", "createdAt": "2025-11-04T05:17:12.022Z", "updatedAt": "2025-11-04T05:59:08.187Z", "description": "When using fspec add-step to add Given/When/Then steps, it appends new steps instead of replacing existing [precondition]/[action]/[expected outcome] placeholders. Since we already parse the AST with @cucumber/gherkin for formatting, we should detect and replace placeholders instead of appending.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T05:18:05.161Z" }, { "state": "testing", "timestamp": "2025-11-04T05:46:33.475Z" }, { "state": "implementing", "timestamp": "2025-11-04T05:48:29.066Z" }, { "state": "validating", "timestamp": "2025-11-04T05:49:33.668Z" }, { "state": "done", "timestamp": "2025-11-04T05:59:08.187Z" } ], "rules": [ { "id": 0, "text": "fspec add-step currently appends new steps AFTER existing placeholder steps [precondition]/[action]/[expected outcome]", "deleted": false, "createdAt": "2025-11-04T05:18:17.935Z" }, { "id": 1, "text": "Placeholders [precondition]/[action]/[expected outcome] are generated by fspec add-scenario and fspec generate-scenarios commands", "deleted": false, "createdAt": "2025-11-04T05:18:20.254Z" }, { "id": 2, "text": "fspec already uses @cucumber/gherkin parser for formatting (format command in feature-formatter.ts), so AST parsing infrastructure exists", "deleted": false, "createdAt": "2025-11-04T05:18:21.762Z" }, { "id": 3, "text": "Expected behavior: fspec add-step should REPLACE matching placeholder ([precondition] → Given, [action] → When, [expected outcome] → Then) instead of appending", "deleted": false, "createdAt": "2025-11-04T05:18:23.275Z" }, { "id": 4, "text": "Placeholder mapping: [precondition] maps to Given, [action] maps to When, [expected outcome] maps to Then", "deleted": false, "createdAt": "2025-11-04T05:18:24.878Z" }, { "id": 5, "text": "If no matching placeholder exists, fspec add-step should append as current behavior (backward compatibility)", "deleted": false, "createdAt": "2025-11-04T05:18:26.858Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "REFAC-003: ran 'fspec add-step ... given \"work unit moves to testing state\"' and it created BOTH 'Given [precondition]' placeholder AND 'Given work unit moves to testing state', resulting in duplicate Given steps in scenario", "deleted": false, "createdAt": "2025-11-04T05:18:41.343Z" }, { "id": 1, "text": "Expected: 'fspec add-step ... given \"text\"' should detect and REPLACE 'Given [precondition]' with 'Given text', not append", "deleted": false, "createdAt": "2025-11-04T05:18:43.020Z" }, { "id": 2, "text": "Edge case: scenario already has 'Given actual step', then 'fspec add-step ... given \"another step\"' should append (no placeholder to replace)", "deleted": false, "createdAt": "2025-11-04T05:18:44.481Z" }, { "id": 3, "text": "Multiple placeholders: scenario has 'Given [precondition]', 'When [action]', 'Then [expected outcome]'. Running add-step for each keyword should replace each placeholder in order.", "deleted": false, "createdAt": "2025-11-04T05:18:46.221Z" } ], "nextExampleId": 4, "userStory": { "role": "developer using fspec CLI", "action": "add steps to scenarios with placeholders", "benefit": "new steps replace placeholders instead of creating duplicates" }, "estimate": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-04T05:59:08.187Z" }, "TUI-018": { "id": "TUI-018", "title": "Base Dialog modal infrastructure component", "type": "story", "status": "done", "createdAt": "2025-11-04T06:30:10.718Z", "updatedAt": "2025-11-04T06:46:13.826Z", "description": "Create a reusable base Dialog component that provides modal overlay infrastructure for all dialog types in the TUI", "children": [], "userStory": { "role": "TUI developer", "action": "use a reusable base Dialog component for modal overlays", "benefit": "I can create consistent dialogs without duplicating modal infrastructure code" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T06:30:30.028Z" }, { "state": "testing", "timestamp": "2025-11-04T06:33:08.032Z" }, { "state": "implementing", "timestamp": "2025-11-04T06:34:45.464Z" }, { "state": "validating", "timestamp": "2025-11-04T06:42:59.612Z" }, { "state": "done", "timestamp": "2025-11-04T06:46:13.826Z" } ], "rules": [ { "id": 0, "text": "Dialog handles ONLY modal overlay infrastructure - centering, borders, ESC key, layout. No business logic.", "deleted": false, "createdAt": "2025-11-04T06:30:45.129Z" }, { "id": 1, "text": "Dialog uses isActive prop to control useInput hook - when active, captures all keyboard input", "deleted": false, "createdAt": "2025-11-04T06:30:45.565Z" }, { "id": 2, "text": "Dialog accepts children prop for content - implements composition pattern", "deleted": false, "createdAt": "2025-11-04T06:30:46.000Z" }, { "id": 3, "text": "Dialog provides borderColor prop for customization (red/yellow/green/undefined)", "deleted": false, "createdAt": "2025-11-04T06:30:46.438Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Dialog component renders centered modal with red border when borderColor='red' prop provided, handles ESC to call onClose", "deleted": false, "createdAt": "2025-11-04T06:30:54.227Z" }, { "id": 1, "text": "User is in BoardDisplay, opens dialog - dialog captures ALL input, board navigation suspended until dialog closes", "deleted": false, "createdAt": "2025-11-04T06:30:54.672Z" }, { "id": 2, "text": "Developer creates InfoDialog wrapping Dialog with custom OK button - Dialog provides modal, InfoDialog provides button logic", "deleted": false, "createdAt": "2025-11-04T06:30:55.114Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-04T06:46:13.826Z" }, "TUI-019": { "id": "TUI-019", "title": "Attachment selection dialog with keyboard navigation", "type": "story", "status": "done", "createdAt": "2025-11-04T21:16:55.022Z", "updatedAt": "2025-11-04T21:41:38.370Z", "description": "Replace single-attachment opening with a dialog that lists all attachments in a virtual list, allowing users to select which attachment to open", "children": [], "dependsOn": [ "TUI-013" ], "userStory": { "role": "developer viewing work unit attachments in fspec TUI", "action": "select which attachment to open from a list", "benefit": "I can choose the specific file I want to view when there are multiple attachments" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T21:17:29.483Z" }, { "state": "testing", "timestamp": "2025-11-04T21:22:08.784Z" }, { "state": "implementing", "timestamp": "2025-11-04T21:25:00.414Z" }, { "state": "validating", "timestamp": "2025-11-04T21:41:05.042Z" }, { "state": "done", "timestamp": "2025-11-04T21:41:38.370Z" } ], "rules": [ { "id": 0, "text": "Pressing 'o' key opens attachment selection dialog (only if attachments exist)", "deleted": false, "createdAt": "2025-11-04T21:17:35.424Z" }, { "id": 1, "text": "If no attachments exist, pressing 'o' does nothing (no dialog opens)", "deleted": false, "createdAt": "2025-11-04T21:17:41.040Z" }, { "id": 2, "text": "Dialog displays all attachments in a virtual list (scrollable if more than viewport)", "deleted": false, "createdAt": "2025-11-04T21:17:47.007Z" }, { "id": 3, "text": "Arrow up/down keys navigate through attachment list", "deleted": false, "createdAt": "2025-11-04T21:17:52.866Z" }, { "id": 4, "text": "Pressing Enter opens the currently selected attachment in default browser", "deleted": false, "createdAt": "2025-11-04T21:17:59.238Z" }, { "id": 5, "text": "Pressing Esc closes the dialog without opening any attachment", "deleted": false, "createdAt": "2025-11-04T21:18:05.152Z" }, { "id": 6, "text": "Must reuse existing openInBrowser utility function", "deleted": false, "createdAt": "2025-11-04T21:18:11.402Z" }, { "id": 7, "text": "Remove old TUI-013 single-attachment opening code from UnifiedBoardLayout", "deleted": false, "createdAt": "2025-11-04T21:18:17.167Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "User presses 'o' on work unit with 3 attachments, dialog opens showing list of all 3 files", "deleted": false, "createdAt": "2025-11-04T21:18:33.291Z" }, { "id": 1, "text": "User navigates with arrow keys, presses Enter on 'diagram.png', file opens in browser, dialog closes", "deleted": false, "createdAt": "2025-11-04T21:18:40.268Z" }, { "id": 2, "text": "User presses 'o', dialog opens, user presses Esc, dialog closes without opening anything", "deleted": false, "createdAt": "2025-11-04T21:18:47.347Z" }, { "id": 3, "text": "User presses 'o' on work unit with no attachments, nothing happens (no dialog)", "deleted": false, "createdAt": "2025-11-04T21:18:54.720Z" }, { "id": 4, "text": "Work unit has 10 attachments, dialog shows scrollable list with scroll indicators", "deleted": false, "createdAt": "2025-11-04T21:19:01.318Z" } ], "nextExampleId": 5, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-04T21:41:38.370Z" }, "TUI-020": { "id": "TUI-020", "title": "Local web server for attachment viewing with markdown and mermaid rendering", "type": "story", "status": "done", "createdAt": "2025-11-04T22:52:22.879Z", "updatedAt": "2025-11-04T23:26:45.628Z", "description": "Server runs when TUI runs to render markdown attachments with mermaid diagram support in browser", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T22:52:29.720Z" }, { "state": "testing", "timestamp": "2025-11-04T23:10:16.746Z" }, { "state": "implementing", "timestamp": "2025-11-04T23:12:22.439Z" }, { "state": "validating", "timestamp": "2025-11-04T23:23:12.198Z" }, { "state": "done", "timestamp": "2025-11-04T23:26:45.628Z" } ], "userStory": { "role": "developer viewing work unit attachments in TUI", "action": "open markdown files with mermaid diagrams in my browser", "benefit": "I can view formatted documentation and diagrams without leaving my workflow" }, "rules": [ { "id": 0, "text": "Server must only run when TUI is active (BoardView mounted)", "deleted": false, "createdAt": "2025-11-04T22:52:43.759Z" }, { "id": 1, "text": "Server must serve markdown files as HTML with rendered content", "deleted": false, "createdAt": "2025-11-04T22:52:49.141Z" }, { "id": 2, "text": "Mermaid code blocks must be rendered as diagrams in the browser", "deleted": false, "createdAt": "2025-11-04T22:52:53.783Z" }, { "id": 3, "text": "Server must prevent directory traversal attacks with path validation", "deleted": false, "createdAt": "2025-11-04T22:52:58.939Z" }, { "id": 4, "text": "Server must integrate with TUI-019 attachment dialog to open files via http:// URLs", "deleted": false, "createdAt": "2025-11-04T22:53:03.759Z" }, { "id": 5, "text": "Server must serve non-markdown files (images, PDFs, etc) with appropriate content types", "deleted": false, "createdAt": "2025-11-04T22:57:15.720Z" }, { "id": 6, "text": "Server uses random port allocation (port=0) to avoid conflicts", "deleted": false, "createdAt": "2025-11-04T22:57:45.514Z" }, { "id": 7, "text": "Server failure must be non-fatal - TUI continues working without attachment viewing", "deleted": false, "createdAt": "2025-11-04T22:57:50.432Z" }, { "id": 8, "text": "Viewer must detect OS theme preference using window.matchMedia('prefers-color-scheme: dark')", "deleted": false, "createdAt": "2025-11-04T22:59:25.342Z" }, { "id": 9, "text": "Viewer must provide theme toggle button to override OS preference", "deleted": false, "createdAt": "2025-11-04T22:59:30.279Z" }, { "id": 10, "text": "Viewer must store theme preference in localStorage and restore on page load", "deleted": false, "createdAt": "2025-11-04T22:59:40.461Z" }, { "id": 11, "text": "Markdown renderer must support syntax-highlighted code blocks (reuse MindStrike pattern)", "deleted": false, "createdAt": "2025-11-04T23:00:38.664Z" }, { "id": 12, "text": "Server architecture must be extensible to support future content types (example maps, event storming boards)", "deleted": false, "createdAt": "2025-11-04T23:00:43.658Z" } ], "nextRuleId": 13, "examples": [ { "id": 0, "text": "User opens TUI, server starts automatically on random port", "deleted": false, "createdAt": "2025-11-04T22:53:09.453Z" }, { "id": 1, "text": "User presses 'o' on work unit with markdown attachment, browser opens showing formatted HTML with mermaid diagram", "deleted": false, "createdAt": "2025-11-04T22:53:16.395Z" }, { "id": 2, "text": "User exits TUI, server stops automatically", "deleted": false, "createdAt": "2025-11-04T22:53:21.170Z" }, { "id": 3, "text": "Malicious user tries ../../../etc/passwd path, server blocks with 403 Forbidden", "deleted": false, "createdAt": "2025-11-04T22:53:26.353Z" }, { "id": 4, "text": "User opens PNG attachment, browser displays image directly", "deleted": false, "createdAt": "2025-11-04T22:57:21.042Z" }, { "id": 5, "text": "User with dark OS theme opens attachment, sees dark mermaid diagrams. Toggles to light theme, preference saved. Reopens attachment later, light theme restored from localStorage", "deleted": false, "createdAt": "2025-11-04T22:59:46.651Z" }, { "id": 6, "text": "User opens markdown with Python code block, browser shows syntax-highlighted code with copy button and language badge", "deleted": false, "createdAt": "2025-11-04T23:04:36.393Z" } ], "nextExampleId": 7, "questions": [ { "id": 0, "text": "@human: Should the server also handle non-markdown files (like images, PDFs) or only markdown?", "deleted": false, "createdAt": "2025-11-04T22:55:27.800Z", "selected": true, "answer": "Yes - server should handle images, PDFs, and other file types, not just markdown" }, { "id": 1, "text": "@human: What should happen if the server fails to start (port conflict, permission error)? Should TUI still work without it?", "deleted": false, "createdAt": "2025-11-04T22:55:33.597Z", "selected": true, "answer": "Use random port allocation (port=0) to let OS choose available port, avoiding conflicts. If server completely fails to start, TUI should continue working but log error (non-fatal)" }, { "id": 2, "text": "@human: Should mermaid diagrams use light theme or dark theme to match TUI aesthetics?", "deleted": false, "createdAt": "2025-11-04T22:55:39.360Z", "selected": true, "answer": "Match OS theme using window.matchMedia('prefers-color-scheme: dark'). Provide toggle button to override preference. Store user preference in localStorage and restore on page load" }, { "id": 3, "text": "@human: You mentioned future support for example maps and event storming boards - should the server architecture support rendering different content types beyond markdown?", "deleted": false, "createdAt": "2025-11-04T22:55:45.569Z", "selected": true, "answer": "Yes - architecture should support multiple content types: markdown with mermaid, code blocks with syntax highlighting (use MindStrike pattern), and future support for example maps/event storming boards. Use extensible renderer pattern" }, { "id": 4, "text": "@human: Should we reuse the existing mermaid validation utilities from the codebase, or is the client-side rendering enough?", "deleted": false, "createdAt": "2025-11-04T22:55:52.154Z", "selected": true, "answer": "Reuse existing mermaid validation utilities from src/utils/mermaid-validation.ts for server-side validation before sending to client. This catches syntax errors early and provides better error messages" } ], "nextQuestionId": 5, "attachments": [ "spec/attachments/TUI-020/code-block-implementation-guide.md" ], "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-04T23:26:45.628Z" }, "REFAC-004": { "id": "REFAC-004", "title": "Integrate attachment server with TUI (BoardView lifecycle)", "type": "story", "status": "done", "createdAt": "2025-11-04T23:36:35.063Z", "updatedAt": "2025-11-05T02:43:10.131Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-04T23:36:42.765Z" }, { "state": "testing", "timestamp": "2025-11-04T23:41:11.930Z" }, { "state": "implementing", "timestamp": "2025-11-04T23:43:58.684Z" }, { "state": "validating", "timestamp": "2025-11-04T23:59:19.916Z" }, { "state": "done", "timestamp": "2025-11-05T00:09:31.575Z" } ], "userStory": { "role": "TUI user", "action": "view attachments in a browser with rendered markdown and mermaid", "benefit": "I can see formatted documentation instead of raw markdown files" }, "rules": [ { "id": 0, "text": "The attachment server must start when BoardView mounts", "deleted": false, "createdAt": "2025-11-04T23:37:01.478Z" }, { "id": 1, "text": "The attachment server must stop when BoardView unmounts", "deleted": false, "createdAt": "2025-11-04T23:37:01.913Z" }, { "id": 2, "text": "The server port must be stored in BoardView state and accessible to child components", "deleted": false, "createdAt": "2025-11-04T23:37:02.351Z" }, { "id": 3, "text": "AttachmentDialog must construct http://localhost:PORT/view/PATH URLs instead of file:// URLs", "deleted": false, "createdAt": "2025-11-04T23:37:02.787Z" }, { "id": 4, "text": "The server must use the project root (process.cwd()) as the base directory", "deleted": false, "createdAt": "2025-11-04T23:37:03.223Z" }, { "id": 5, "text": "Server startup failures must be logged but not crash the TUI", "deleted": false, "createdAt": "2025-11-04T23:37:03.661Z" }, { "id": 6, "text": "The server must only run when the TUI is active (not during CLI commands)", "deleted": false, "createdAt": "2025-11-04T23:37:04.102Z" } ], "nextRuleId": 7, "examples": [ { "id": 0, "text": "When I open the TUI and press 'o' on a work unit with an attachment, the browser opens with http://localhost:XXXX/view/spec/attachments/...", "deleted": false, "createdAt": "2025-11-04T23:37:14.269Z" }, { "id": 1, "text": "When I exit the TUI, the attachment server stops and releases the port", "deleted": false, "createdAt": "2025-11-04T23:37:14.705Z" }, { "id": 2, "text": "When the server fails to start (port conflict), I see a warning in the logs but the TUI continues working", "deleted": false, "createdAt": "2025-11-04T23:37:15.141Z" }, { "id": 3, "text": "When I open a markdown attachment, the browser shows rendered HTML with working mermaid diagrams", "deleted": false, "createdAt": "2025-11-04T23:37:15.576Z" }, { "id": 4, "text": "When I open an image attachment, the browser displays the image directly", "deleted": false, "createdAt": "2025-11-04T23:37:16.012Z" } ], "nextExampleId": 5, "virtualHooks": [], "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-05T00:09:31.575Z", "attachments": [] }, "TUI-021": { "id": "TUI-021", "title": "Font size controls for attachment viewer", "type": "story", "status": "done", "createdAt": "2025-11-05T00:00:57.744Z", "updatedAt": "2025-11-05T00:39:32.623Z", "children": [], "userStory": { "role": "TUI user viewing markdown attachments", "action": "adjust code block font sizes and persist preferences", "benefit": "I can read documentation comfortably and have my settings remembered" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T00:01:27.573Z" }, { "state": "testing", "timestamp": "2025-11-05T00:12:00.490Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:13:45.466Z" }, { "state": "validating", "timestamp": "2025-11-05T00:16:29.588Z" }, { "state": "done", "timestamp": "2025-11-05T00:20:50.975Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:22:46.862Z" }, { "state": "validating", "timestamp": "2025-11-05T00:24:00.706Z" }, { "state": "done", "timestamp": "2025-11-05T00:24:09.595Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:25:13.169Z" }, { "state": "validating", "timestamp": "2025-11-05T00:25:51.428Z" }, { "state": "done", "timestamp": "2025-11-05T00:25:55.083Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:27:43.581Z" }, { "state": "validating", "timestamp": "2025-11-05T00:28:11.732Z" }, { "state": "done", "timestamp": "2025-11-05T00:28:15.441Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:29:11.610Z" }, { "state": "validating", "timestamp": "2025-11-05T00:29:41.575Z" }, { "state": "done", "timestamp": "2025-11-05T00:29:45.226Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:30:19.463Z" }, { "state": "validating", "timestamp": "2025-11-05T00:30:40.240Z" }, { "state": "done", "timestamp": "2025-11-05T00:30:43.859Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:32:06.539Z" }, { "state": "validating", "timestamp": "2025-11-05T00:32:26.063Z" }, { "state": "done", "timestamp": "2025-11-05T00:32:29.660Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:34:10.721Z" }, { "state": "validating", "timestamp": "2025-11-05T00:34:33.252Z" }, { "state": "done", "timestamp": "2025-11-05T00:34:35.728Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:35:11.669Z" }, { "state": "validating", "timestamp": "2025-11-05T00:38:03.431Z" }, { "state": "done", "timestamp": "2025-11-05T00:38:06.063Z" }, { "state": "implementing", "timestamp": "2025-11-05T00:38:58.298Z" }, { "state": "validating", "timestamp": "2025-11-05T00:39:30.089Z" }, { "state": "done", "timestamp": "2025-11-05T00:39:32.623Z" } ], "rules": [ { "id": 0, "text": "Code blocks must have significantly larger base font size than current implementation", "deleted": false, "createdAt": "2025-11-05T00:01:36.283Z" }, { "id": 1, "text": "Font size controls must be in top right corner next to dark mode toggle", "deleted": false, "createdAt": "2025-11-05T00:01:36.862Z" }, { "id": 2, "text": "Font size must be persisted in localStorage", "deleted": false, "createdAt": "2025-11-05T00:01:37.442Z" }, { "id": 3, "text": "Font size controls must use plus/minus buttons with displayed pixel size", "deleted": false, "createdAt": "2025-11-05T00:01:38.942Z" }, { "id": 4, "text": "Font size must have min/max bounds (10px - 24px) with 2px increment/decrement", "deleted": false, "createdAt": "2025-11-05T00:01:40.330Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User opens markdown attachment and code blocks display at 16px (larger than current)", "deleted": false, "createdAt": "2025-11-05T00:01:49.414Z" }, { "id": 1, "text": "User clicks plus button and font increases from 16px to 18px", "deleted": false, "createdAt": "2025-11-05T00:01:51.427Z" }, { "id": 2, "text": "User clicks minus button at 10px and size stays at 10px (minimum bound)", "deleted": false, "createdAt": "2025-11-05T00:01:53.530Z" }, { "id": 3, "text": "User closes browser and reopens attachment, font size remains at previously set 20px", "deleted": false, "createdAt": "2025-11-05T00:01:54.980Z" } ], "nextExampleId": 4, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-05T00:39:32.623Z" }, "TUI-022": { "id": "TUI-022", "title": "Anchor links not working in markdown attachment viewer", "type": "bug", "status": "done", "createdAt": "2025-11-05T04:36:45.635Z", "updatedAt": "2025-11-05T04:48:32.638Z", "description": "Table of contents anchor links in rendered markdown don't navigate to headings because heading elements lack id attributes", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T04:37:35.851Z" }, { "state": "testing", "timestamp": "2025-11-05T04:40:36.423Z" }, { "state": "implementing", "timestamp": "2025-11-05T04:45:17.735Z" }, { "state": "validating", "timestamp": "2025-11-05T04:45:25.361Z" }, { "state": "done", "timestamp": "2025-11-05T04:48:32.639Z" } ], "rules": [ { "id": 0, "text": "All markdown headings (h1-h6) must have unique id attributes for anchor link navigation", "deleted": false, "createdAt": "2025-11-05T04:37:47.142Z" }, { "id": 1, "text": "Heading IDs must be GitHub-compatible slugs: lowercase, hyphenated, special chars removed", "deleted": false, "createdAt": "2025-11-05T04:37:48.603Z" }, { "id": 2, "text": "Duplicate headings must get numbered suffixes (-1, -2, etc.) to ensure uniqueness", "deleted": false, "createdAt": "2025-11-05T04:37:50.181Z" }, { "id": 3, "text": "Mermaid diagram rendering must continue to work (no regression)", "deleted": false, "createdAt": "2025-11-05T04:37:51.602Z" }, { "id": 4, "text": "Code block rendering must continue to work with syntax highlighting (no regression)", "deleted": false, "createdAt": "2025-11-05T04:37:52.963Z" }, { "id": 5, "text": "Tests must test renderMarkdown() directly without starting the HTTP server", "deleted": false, "createdAt": "2025-11-05T04:37:54.520Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "Heading '## Tag System' becomes <h2 id=\"tag-system\">Tag System</h2>", "deleted": false, "createdAt": "2025-11-05T04:38:07.237Z" }, { "id": 1, "text": "Heading '## Domain-to-Tag Mapping Rules' becomes <h2 id=\"domain-to-tag-mapping-rules\">Domain-to-Tag Mapping Rules</h2>", "deleted": false, "createdAt": "2025-11-05T04:38:08.918Z" }, { "id": 2, "text": "Two headings '## Summary' become <h2 id=\"summary\">Summary</h2> and <h2 id=\"summary-1\">Summary</h2>", "deleted": false, "createdAt": "2025-11-05T04:38:10.672Z" }, { "id": 3, "text": "Heading with special chars '## What's New?' becomes <h2 id=\"whats-new\">What's New?</h2>", "deleted": false, "createdAt": "2025-11-05T04:38:13.392Z" }, { "id": 4, "text": "Anchor link [Jump to summary](#summary) navigates to heading with id=\"summary\"", "deleted": false, "createdAt": "2025-11-05T04:38:15.120Z" }, { "id": 5, "text": "Mermaid code block still renders as <pre class=\"mermaid\"> with diagram content", "deleted": false, "createdAt": "2025-11-05T04:38:17.012Z" } ], "nextExampleId": 6, "architectureNotes": [ { "id": 0, "text": "Use marked-gfm-heading-id extension (official GitHub-compatible heading ID generator for marked library) - handles slug generation, duplicates, and special characters automatically", "deleted": false, "createdAt": "2025-11-05T04:38:28.578Z" }, { "id": 1, "text": "Create new test file markdown-renderer.test.ts that tests renderMarkdown() directly (unit tests, no server startup) - faster, simpler, more focused than integration tests", "deleted": false, "createdAt": "2025-11-05T04:38:29.940Z" }, { "id": 2, "text": "Existing TUI-020 integration tests should continue to pass - this is additive enhancement, not breaking change", "deleted": false, "createdAt": "2025-11-05T04:38:31.774Z" } ], "nextNoteId": 3, "userStory": { "role": "developer viewing markdown attachments in TUI", "action": "navigate using table of contents anchor links", "benefit": "I can quickly jump to specific sections in long documents" }, "questions": [], "nextQuestionId": 0, "updated": "2025-11-05T04:48:32.638Z" }, "VIEW-001": { "id": "VIEW-001", "title": "Fullscreen Mermaid Diagram Viewer with Zoom and Pan Controls", "type": "story", "status": "done", "createdAt": "2025-11-05T05:34:31.745Z", "updatedAt": "2025-11-05T06:03:26.956Z", "description": "Add a fullscreen modal viewer for mermaid diagrams in the attachment viewer with zoom and pan controls matching mindstrike's implementation. Users can click a button on any mermaid diagram to open it fullscreen, then use mouse wheel to zoom (centered on cursor) and modifier key + scroll to pan. Visual indicator shows current mode (Zoom Mode / Pan Mode).", "children": [], "attachments": [ "spec/attachments/VIEW-001/fullscreen-mermaid-viewer-research.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T05:36:01.207Z" }, { "state": "testing", "timestamp": "2025-11-05T05:47:48.977Z" }, { "state": "implementing", "timestamp": "2025-11-05T05:52:27.498Z" }, { "state": "validating", "timestamp": "2025-11-05T06:00:26.232Z" }, { "state": "done", "timestamp": "2025-11-05T06:03:26.957Z" } ], "userStory": { "role": "developer or user viewing mermaid diagrams in fspec attachment viewer", "action": "view mermaid diagrams in fullscreen with zoom and pan controls", "benefit": "I can examine complex diagrams in detail without leaving the viewer" }, "rules": [ { "id": 0, "text": "Fullscreen button must appear on hover over mermaid diagram", "deleted": false, "createdAt": "2025-11-05T05:36:25.350Z" }, { "id": 1, "text": "Fullscreen modal must cover entire viewport with semi-transparent backdrop", "deleted": false, "createdAt": "2025-11-05T05:36:27.159Z" }, { "id": 2, "text": "Modal must close on ESC key press or backdrop click", "deleted": false, "createdAt": "2025-11-05T05:36:28.647Z" }, { "id": 3, "text": "Vertical scroll wheel must zoom in/out centered on cursor position", "deleted": false, "createdAt": "2025-11-05T05:36:30.129Z" }, { "id": 4, "text": "Horizontal scroll wheel must pan diagram left/right", "deleted": false, "createdAt": "2025-11-05T05:36:32.365Z" }, { "id": 5, "text": "Holding modifier key (Space/Shift/Alt) must switch vertical scroll from zoom to pan", "deleted": false, "createdAt": "2025-11-05T05:36:33.888Z" }, { "id": 6, "text": "Visual indicator must show current mode (Zoom Mode or Pan Mode)", "deleted": false, "createdAt": "2025-11-05T05:36:35.462Z" }, { "id": 7, "text": "Zoom range must be limited between 0.5x and 5.0x", "deleted": false, "createdAt": "2025-11-05T05:36:37.000Z" }, { "id": 8, "text": "Download button must export diagram as SVG file", "deleted": false, "createdAt": "2025-11-05T05:36:38.632Z" } ], "nextRuleId": 9, "examples": [ { "id": 0, "text": "User hovers over mermaid diagram, fullscreen button fades in at top-right corner", "deleted": false, "createdAt": "2025-11-05T05:37:01.028Z" }, { "id": 1, "text": "User clicks fullscreen button, modal opens with smooth scale/fade animation covering entire viewport", "deleted": false, "createdAt": "2025-11-05T05:37:02.517Z" }, { "id": 2, "text": "User presses ESC key while modal is open, modal closes with fade-out animation", "deleted": false, "createdAt": "2025-11-05T05:37:05.133Z" }, { "id": 3, "text": "User clicks dark backdrop outside diagram, modal closes", "deleted": false, "createdAt": "2025-11-05T05:37:06.596Z" }, { "id": 4, "text": "User scrolls mouse wheel up over diagram, diagram zooms in centered on cursor position", "deleted": false, "createdAt": "2025-11-05T05:37:08.189Z" }, { "id": 5, "text": "User scrolls mouse wheel down, diagram zooms out centered on cursor position", "deleted": false, "createdAt": "2025-11-05T05:37:09.773Z" }, { "id": 6, "text": "User scrolls horizontally (trackpad two-finger swipe), diagram pans left or right", "deleted": false, "createdAt": "2025-11-05T05:37:11.571Z" }, { "id": 7, "text": "User holds Space key and scrolls vertically, diagram pans up/down instead of zooming", "deleted": false, "createdAt": "2025-11-05T05:37:13.181Z" }, { "id": 8, "text": "Mode indicator shows 'Zoom Mode (hold Space for Pan)' at bottom-left, fades to 50% opacity after 2 seconds of inactivity", "deleted": false, "createdAt": "2025-11-05T05:37:14.767Z" }, { "id": 9, "text": "User holds Space key, mode indicator changes to 'Pan Mode' with 100% opacity and accent color background", "deleted": false, "createdAt": "2025-11-05T05:37:16.306Z" }, { "id": 10, "text": "User clicks zoom in button (+), diagram zooms in by fixed increment", "deleted": false, "createdAt": "2025-11-05T05:37:17.821Z" }, { "id": 11, "text": "User clicks reset button, diagram returns to 100% zoom (1.0x) centered in modal", "deleted": false, "createdAt": "2025-11-05T05:37:19.263Z" }, { "id": 12, "text": "User clicks download button, SVG file downloads with filename 'mermaid-diagram-{timestamp}.svg'", "deleted": false, "createdAt": "2025-11-05T05:37:21.178Z" }, { "id": 13, "text": "User tries to zoom beyond 5.0x, zoom stops at maximum (5.0x)", "deleted": false, "createdAt": "2025-11-05T05:37:22.836Z" }, { "id": 14, "text": "User tries to zoom below 0.5x, zoom stops at minimum (0.5x)", "deleted": false, "createdAt": "2025-11-05T05:37:24.305Z" } ], "nextExampleId": 15, "questions": [ { "id": 0, "text": "@human: Should the pan modifier key be configurable in the UI (like mindstrike) or hardcoded to Space?", "deleted": false, "createdAt": "2025-11-05T05:37:38.182Z", "selected": true, "answer": "Hardcode to Space key only - no configuration UI needed. Keep implementation simple." }, { "id": 1, "text": "@human: Should zoom level be persisted across sessions (localStorage) or reset to 1.0x each time?", "deleted": false, "createdAt": "2025-11-05T05:37:39.941Z", "selected": true, "answer": "Always reset to 1.0x (100%) each time modal opens - no persistence needed." }, { "id": 2, "text": "@human: Should there be keyboard shortcuts for zoom (+ - 0 keys) in addition to mouse wheel?", "deleted": false, "createdAt": "2025-11-05T05:37:41.228Z", "selected": true, "answer": "No keyboard shortcuts for zoom - mouse wheel and zoom buttons only." }, { "id": 3, "text": "@human: Should body scroll be locked when modal is open to prevent background scrolling?", "deleted": false, "createdAt": "2025-11-05T05:37:43.064Z", "selected": true, "answer": "Yes - lock body scroll when modal is open (document.body.style.overflow = 'hidden') to prevent background scrolling." }, { "id": 4, "text": "@human: Should the fullscreen button also include a download button (two buttons on hover) or keep download only in modal header?", "deleted": false, "createdAt": "2025-11-05T05:37:45.284Z", "selected": true, "answer": "Show both fullscreen AND download buttons in hover overlay (like mindstrike) for quick access to both features." } ], "nextQuestionId": 5, "estimate": 8, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-05T06:03:26.956Z" }, "GIT-011": { "id": "GIT-011", "title": "Checkpoint creation fails when deleted files exist", "type": "bug", "status": "done", "createdAt": "2025-11-05T06:51:18.899Z", "updatedAt": "2025-11-05T07:10:37.942Z", "description": "Checkpoint creation attempts to stage deleted files using git.add() which fails because the files no longer exist. Should use git.remove() for deleted files and git.add() for modified/added files. Root cause: src/utils/git-checkpoint.ts lines 216-219 call git.add() for all changed files without checking if files are deleted.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T06:51:39.121Z" }, { "state": "testing", "timestamp": "2025-11-05T06:53:46.992Z" }, { "state": "implementing", "timestamp": "2025-11-05T06:55:26.955Z" }, { "state": "validating", "timestamp": "2025-11-05T07:03:43.095Z" }, { "state": "done", "timestamp": "2025-11-05T07:10:37.942Z" } ], "userStory": { "role": "developer using fspec checkpoints", "action": "create checkpoints when deleted files exist", "benefit": "I can safely experiment and rollback changes including file deletions" }, "rules": [ { "id": 0, "text": "Checkpoint creation must detect file status using git.statusMatrix to determine if files are modified, added, or deleted", "deleted": false, "createdAt": "2025-11-05T06:51:52.959Z" }, { "id": 1, "text": "Deleted files must be staged using git.remove() instead of git.add()", "deleted": false, "createdAt": "2025-11-05T06:51:58.536Z" }, { "id": 2, "text": "Modified and added files must continue using git.add() for staging", "deleted": false, "createdAt": "2025-11-05T06:52:04.358Z" }, { "id": 3, "text": "Checkpoint must capture all changed files (modified, added, and deleted) in a single stash commit", "deleted": false, "createdAt": "2025-11-05T06:52:10.374Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Developer deletes README.md and runs 'fspec checkpoint DOC-001 baseline' - checkpoint is created successfully with deleted file tracked", "deleted": false, "createdAt": "2025-11-05T06:52:16.930Z" }, { "id": 1, "text": "Developer has mixed changes (modified src/app.ts, deleted docs/old.md, added tests/new.test.ts) - checkpoint captures all three types of changes", "deleted": false, "createdAt": "2025-11-05T06:52:23.721Z" }, { "id": 2, "text": "Developer deletes multiple files in docs/ directory - all deletions are staged using git.remove() and captured in checkpoint", "deleted": false, "createdAt": "2025-11-05T06:52:29.909Z" }, { "id": 3, "text": "Restoring checkpoint that includes deleted files recreates those files in working directory", "deleted": false, "createdAt": "2025-11-05T06:52:36.514Z" } ], "nextExampleId": 4, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-05T07:10:37.942Z" }, "TUI-023": { "id": "TUI-023", "title": "Update checkpoint view keybinding information", "type": "task", "status": "done", "createdAt": "2025-11-05T08:23:41.632Z", "updatedAt": "2025-11-05T08:32:18.719Z", "description": "Display keybinding help text in checkpoint view: 'D: Delete Checkpoint | A: Delete All Checkpoints | T: Restore Checkpoint Files'", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T08:24:34.408Z" }, { "state": "implementing", "timestamp": "2025-11-05T08:24:47.349Z" }, { "state": "validating", "timestamp": "2025-11-05T08:31:50.808Z" }, { "state": "done", "timestamp": "2025-11-05T08:32:18.719Z" } ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-05T08:32:18.719Z" }, "TUI-024": { "id": "TUI-024", "title": "Filter checkpoint view to show only files different from HEAD", "type": "task", "status": "done", "createdAt": "2025-11-05T08:42:42.549Z", "updatedAt": "2025-11-05T08:48:42.959Z", "description": "In checkpoint viewer, filter the file list to only display files that have differences compared to HEAD. Files that are identical to HEAD should be hidden from the list to reduce noise and focus on actual changes.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T08:43:18.786Z" }, { "state": "implementing", "timestamp": "2025-11-05T08:43:25.425Z" }, { "state": "validating", "timestamp": "2025-11-05T08:48:34.896Z" }, { "state": "done", "timestamp": "2025-11-05T08:48:42.959Z" } ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-05T08:48:42.959Z" }, "TUI-025": { "id": "TUI-025", "title": "Replace diff headers with user-friendly restore explanations", "type": "task", "status": "done", "createdAt": "2025-11-05T09:16:27.331Z", "updatedAt": "2025-11-05T09:23:15.455Z", "description": "Replace the standard git diff header (lines 1-4) with 2 clear lines: (1) Red line explaining lines added after checkpoint will be REMOVED on restore (with count), (2) Green line explaining lines removed since checkpoint will be ADDED on restore (with count). Remove the 'diff --git' and '@@ @@' hunk headers - users don't need git internals, they need restore clarity. Also update the Diff pane heading from 'Diff' to 'Diff: filename' with truncate-end if the line is too long.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T09:18:32.739Z" }, { "state": "implementing", "timestamp": "2025-11-05T09:18:40.024Z" }, { "state": "validating", "timestamp": "2025-11-05T09:23:05.756Z" }, { "state": "done", "timestamp": "2025-11-05T09:23:15.455Z" } ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-05T09:23:15.455Z" }, "TUI-026": { "id": "TUI-026", "title": "Update Files pane header to show checkpoint name with truncate-end", "type": "task", "status": "done", "createdAt": "2025-11-05T09:26:58.616Z", "updatedAt": "2025-11-05T09:31:30.668Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T09:27:17.952Z" }, { "state": "implementing", "timestamp": "2025-11-05T09:27:19.377Z" }, { "state": "validating", "timestamp": "2025-11-05T09:31:29.284Z" }, { "state": "done", "timestamp": "2025-11-05T09:31:30.668Z" } ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-05T09:31:30.668Z" }, "GIT-012": { "id": "GIT-012", "title": "Checkpoint restore shows 'File not found' but doesn't delete files added after checkpoint", "type": "bug", "status": "done", "createdAt": "2025-11-05T09:55:05.055Z", "updatedAt": "2025-11-05T10:16:40.803Z", "description": "When restoring a checkpoint, files that exist in HEAD but not in the checkpoint are shown with 'File not found in checkpoint' message, but they are not actually deleted during restore. This means the restore doesn't truly restore to the checkpoint state.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T09:55:12.539Z" }, { "state": "testing", "timestamp": "2025-11-05T10:00:23.249Z" }, { "state": "implementing", "timestamp": "2025-11-05T10:04:34.987Z" }, { "state": "validating", "timestamp": "2025-11-05T10:08:45.276Z" }, { "state": "done", "timestamp": "2025-11-05T10:09:30.004Z" }, { "state": "implementing", "timestamp": "2025-11-05T10:12:28.092Z" }, { "state": "validating", "timestamp": "2025-11-05T10:16:16.309Z" }, { "state": "done", "timestamp": "2025-11-05T10:16:40.804Z" } ], "rules": [ { "id": 0, "text": "Checkpoint restore must fully restore working directory to exact state at checkpoint creation time", "deleted": false, "createdAt": "2025-11-05T09:55:33.128Z" }, { "id": 1, "text": "Files that exist in HEAD but not in checkpoint must be deleted during restore", "deleted": false, "createdAt": "2025-11-05T09:55:38.566Z" }, { "id": 2, "text": "Diff viewer must clearly indicate when files will be deleted on restore (not just 'File not found in checkpoint')", "deleted": false, "createdAt": "2025-11-05T09:55:46.134Z" }, { "id": 3, "text": "File deletion happens automatically as part of normal restore operation. No force flag required since restoring to checkpoint state inherently means removing files added after checkpoint.", "deleted": false, "createdAt": "2025-11-05T09:57:57.013Z" }, { "id": 4, "text": "Only tracked files should be considered for deletion. Gitignored files and node_modules are not affected by checkpoint restore.", "deleted": false, "createdAt": "2025-11-05T09:58:03.265Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Checkpoint created at T1 contains [A.txt, B.txt], then C.txt is added at T2. Restoring checkpoint should delete C.txt and restore A.txt, B.txt to T1 state.", "deleted": false, "createdAt": "2025-11-05T09:55:52.303Z" }, { "id": 1, "text": "Diff viewer shows file D.txt with message 'Will be deleted on restore' instead of 'File not found in checkpoint' when D.txt exists in HEAD but not in checkpoint", "deleted": false, "createdAt": "2025-11-05T09:55:58.393Z" }, { "id": 2, "text": "Restoring checkpoint deletes 3 files [new-feature.ts, test.spec.ts, README-draft.md] that were added after checkpoint, and restores 2 modified files [main.ts, config.json] to checkpoint state", "deleted": false, "createdAt": "2025-11-05T09:56:05.815Z" } ], "nextExampleId": 3, "questions": [ { "id": 0, "text": "@human: Should deleted files be backed up somewhere (e.g., temporary checkpoint) before deletion, or rely on user to create manual checkpoint first?", "deleted": false, "createdAt": "2025-11-05T09:56:13.509Z", "selected": true, "answer": "No backup needed - files are in HEAD so user can restore with git if needed. Existing warning to create manual checkpoint first is sufficient." }, { "id": 1, "text": "@human: Should file deletion count as a 'conflict' that requires --force flag, or should it happen automatically since it's part of restoring to checkpoint state?", "deleted": false, "createdAt": "2025-11-05T09:56:20.063Z", "selected": true, "answer": "File deletion happens automatically as part of normal restore operation. No force flag required since restoring to checkpoint state inherently means removing files added after checkpoint." }, { "id": 2, "text": "@human: What about files that are gitignored or in node_modules? Should those be considered for deletion, or only tracked files?", "deleted": false, "createdAt": "2025-11-05T09:56:25.888Z", "selected": true, "answer": "Only tracked files should be considered for deletion. Gitignored files and node_modules are not affected by checkpoint restore." } ], "nextQuestionId": 3, "assumptions": [ "No backup needed - files are in HEAD so user can restore with git if needed. Existing warning to create manual checkpoint first is sufficient." ], "userStory": { "role": "developer using fspec checkpoints", "action": "restore a checkpoint to recover previous work state", "benefit": "I get an exact restoration of the working directory as it was when the checkpoint was created" }, "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-05T10:16:40.803Z" }, "TUI-027": { "id": "TUI-027", "title": "Checkpoint Restore Progress Dialog", "type": "story", "status": "done", "createdAt": "2025-11-05T10:35:38.781Z", "updatedAt": "2025-11-05T12:08:20.756Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T10:35:45.812Z" }, { "state": "testing", "timestamp": "2025-11-05T10:44:20.339Z" }, { "state": "implementing", "timestamp": "2025-11-05T10:45:55.605Z" }, { "state": "validating", "timestamp": "2025-11-05T10:51:57.297Z" }, { "state": "specifying", "timestamp": "2025-11-05T10:57:39.236Z" }, { "state": "testing", "timestamp": "2025-11-05T10:58:36.676Z" }, { "state": "implementing", "timestamp": "2025-11-05T12:06:55.604Z" }, { "state": "validating", "timestamp": "2025-11-05T12:08:19.301Z" }, { "state": "done", "timestamp": "2025-11-05T12:08:20.757Z" } ], "userStory": { "role": "developer using checkpoint restore", "action": "see real-time progress during file restoration", "benefit": "I understand what's happening and when the restore is complete" }, "rules": [ { "id": 0, "text": "Dialog must appear when user confirms restore (single file or all files)", "deleted": false, "createdAt": "2025-11-05T10:36:11.654Z" }, { "id": 1, "text": "Dialog must show the current file being restored in real-time", "deleted": false, "createdAt": "2025-11-05T10:36:13.598Z" }, { "id": 2, "text": "Dialog must show count of remaining files to restore", "deleted": false, "createdAt": "2025-11-05T10:36:15.280Z" }, { "id": 3, "text": "Dialog must auto-close 3 seconds after all files are restored", "deleted": false, "createdAt": "2025-11-05T10:36:17.294Z" }, { "id": 4, "text": "StatusDialog component must be reusable for other progress operations", "deleted": false, "createdAt": "2025-11-05T10:36:19.028Z" }, { "id": 5, "text": "Display only the current file being processed (not a scrollable list)", "deleted": false, "createdAt": "2025-11-05T10:39:30.530Z" }, { "id": 6, "text": "Yes, show progress indicator with format 'X/Y files' or percentage", "deleted": false, "createdAt": "2025-11-05T10:39:32.443Z" }, { "id": 7, "text": "Show error state in dialog with manual dismissal required", "deleted": false, "createdAt": "2025-11-05T10:39:33.907Z" }, { "id": 8, "text": "No cancellation allowed once restore starts", "deleted": false, "createdAt": "2025-11-05T10:39:35.332Z" }, { "id": 9, "text": "Allow early dismissal with ESC during 3-second completion notice", "deleted": false, "createdAt": "2025-11-05T10:39:36.767Z" }, { "id": 10, "text": "Dialog appears for both single and multi-file restores", "deleted": false, "createdAt": "2025-11-05T10:39:38.382Z" }, { "id": 11, "text": "StatusDialog must appear immediately after user confirms restore (presses Y)", "deleted": false, "createdAt": "2025-11-05T10:57:52.074Z" }, { "id": 12, "text": "CheckpointViewer handleRestoreConfirm must render StatusDialog during restore loop", "deleted": false, "createdAt": "2025-11-05T10:57:53.807Z" } ], "nextRuleId": 13, "questions": [ { "id": 0, "text": "@human: Should the dialog show a scrollable list of ALL files being restored, or just display the current file name being processed?", "deleted": false, "createdAt": "2025-11-05T10:36:30.896Z", "selected": true, "answer": "Display only the current file being processed (not a scrollable list)" }, { "id": 1, "text": "@human: Should there be a progress bar or percentage indicator (e.g., '3/10 files' or '30%')?", "deleted": false, "createdAt": "2025-11-05T10:36:33.253Z", "selected": true, "answer": "Yes, show progress indicator with format 'X/Y files' or percentage" }, { "id": 2, "text": "@human: What should happen if an error occurs during restore? Should the dialog show an error state and require manual dismissal?", "deleted": false, "createdAt": "2025-11-05T10:36:34.888Z", "selected": true, "answer": "Show error state in dialog with manual dismissal required" }, { "id": 3, "text": "@human: Should users be able to cancel the restore operation in progress, or is it non-cancellable once started?", "deleted": false, "createdAt": "2025-11-05T10:36:36.435Z", "selected": true, "answer": "No cancellation allowed once restore starts" }, { "id": 4, "text": "@human: During the 3-second completion notice, should the user be able to dismiss it early with ESC, or must they wait the full 3 seconds?", "deleted": false, "createdAt": "2025-11-05T10:36:38.013Z", "selected": true, "answer": "Allow early dismissal with ESC during 3-second completion notice" }, { "id": 5, "text": "@human: For single file restore, should the dialog still appear (showing 1/1 file), or only for multi-file restores?", "deleted": false, "createdAt": "2025-11-05T10:36:39.921Z", "selected": true, "answer": "Dialog appears for both single and multi-file restores" } ], "nextQuestionId": 6, "examples": [ { "id": 0, "text": "User restores 5 files: dialog shows 'Restoring src/foo.ts (1/5)', then 'Restoring src/bar.ts (2/5)', etc.", "deleted": false, "createdAt": "2025-11-05T10:39:50.687Z" }, { "id": 1, "text": "User restores single file: dialog shows 'Restoring src/test.ts (1/1)', then shows completion notice for 3 seconds", "deleted": false, "createdAt": "2025-11-05T10:39:52.203Z" }, { "id": 2, "text": "All files restored: dialog changes to 'Restore Complete\\! Closing in 3 seconds...' with countdown, user can press ESC to close early", "deleted": false, "createdAt": "2025-11-05T10:39:53.759Z" }, { "id": 3, "text": "Error during restore: dialog shows 'Error: Failed to restore src/config.ts' with red styling, user must press ESC to dismiss", "deleted": false, "createdAt": "2025-11-05T10:39:55.804Z" }, { "id": 4, "text": "StatusDialog component can be reused: accepts props like currentItem, totalItems, status, errorMessage", "deleted": false, "createdAt": "2025-11-05T10:39:57.955Z" }, { "id": 5, "text": "User in CheckpointViewer presses T to restore all files, presses Y to confirm, StatusDialog appears showing 'Restoring file1.ts (1/3)'", "deleted": false, "createdAt": "2025-11-05T10:57:55.315Z" }, { "id": 6, "text": "During restore, StatusDialog updates for each file, then shows completion notice, then auto-closes, CheckpointViewer returns to normal view", "deleted": false, "createdAt": "2025-11-05T10:57:57.002Z" } ], "nextExampleId": 7, "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-05T12:08:20.756Z" }, "BUG-069": { "id": "BUG-069", "title": "Changed files view doesn't show deleted files correctly", "type": "bug", "status": "done", "createdAt": "2025-11-05T19:50:50.840Z", "updatedAt": "2025-11-05T21:54:46.321Z", "description": "In the changed files view (F key), deleted files don't show as 'D' with red writing, and the Diff panel says 'No changes to display' instead of 'File was deleted'", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T19:51:51.715Z" }, { "state": "testing", "timestamp": "2025-11-05T21:24:22.339Z" }, { "state": "implementing", "timestamp": "2025-11-05T21:27:27.561Z" }, { "state": "validating", "timestamp": "2025-11-05T21:31:30.024Z" }, { "state": "done", "timestamp": "2025-11-05T21:54:46.322Z" } ], "rules": [ { "id": 0, "text": "Deleted files should show 'D' status indicator in red color", "deleted": false, "createdAt": "2025-11-05T19:51:58.632Z" }, { "id": 1, "text": "Diff panel should show 'File was deleted' message for deleted files instead of 'No changes to display'", "deleted": false, "createdAt": "2025-11-05T19:52:05.073Z" }, { "id": 2, "text": "Status indicators should follow git conventions: A (added/green), M (modified/yellow), D (deleted/red), R (renamed/cyan)", "deleted": false, "createdAt": "2025-11-05T19:52:35.473Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "User deletes a file (rm somefile.txt), opens changed files view (F key), sees 'D somefile.txt' in red", "deleted": false, "createdAt": "2025-11-05T19:52:13.028Z" }, { "id": 1, "text": "User deletes and stages file (git rm somefile.txt), changed files view shows staged 'D somefile.txt' in red", "deleted": false, "createdAt": "2025-11-05T19:52:21.232Z" }, { "id": 2, "text": "User selects deleted file in changed files view, diff panel shows 'File was deleted' instead of 'No changes to display'", "deleted": false, "createdAt": "2025-11-05T19:52:28.199Z" } ], "nextExampleId": 3, "userStory": { "role": "developer using fspec", "action": "view deleted files in the changed files view", "benefit": "I can see which files were deleted and review the deletion in the diff panel" }, "estimate": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-05T21:54:46.321Z" }, "BUG-070": { "id": "BUG-070", "title": "work-units.json not stamped with current version on initial creation", "type": "bug", "status": "done", "createdAt": "2025-11-07T01:45:00.000Z", "updatedAt": "2025-11-07T02:13:07.755Z", "description": "When work-units.json is created for the first time (doesn't exist in spec/ directory), it's not stamped with the current version (0.7.0). Instead, the migration system detects it as version 0.6.0 and has to migrate it, creating unnecessary backup files and console warnings. Root cause: ensureWorkUnitsFile() in src/utils/ensure-files.ts creates initialData without the root-level 'version' field. CRITICAL: Fix must use DRY principles - centralize version management in shared code to avoid repeating version strings across multiple files.", "children": [], "rules": [ { "id": 0, "text": "New work-units.json files MUST be stamped with current version immediately on creation", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" }, { "id": 1, "text": "Version string MUST be managed using DRY principles - NO version string repetition across files", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" }, { "id": 2, "text": "MUST create/use a shared version constant that both ensure-files.ts and migrations use", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" }, { "id": 3, "text": "The single source of truth for current version MUST be accessible to all version-dependent code", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" }, { "id": 4, "text": "Hardcoded version strings like '0.7.0' MUST NOT appear in multiple files", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User creates new project, runs first fspec command, work-units.json created with version: '0.7.0', no migration runs", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" }, { "id": 1, "text": "User deletes spec/work-units.json, runs fspec command, file recreated with current version, no backup created", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" }, { "id": 2, "text": "Version constant updated to 0.8.0 in shared file, both ensure-files and migrations automatically use new version", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" } ], "nextExampleId": 3, "questions": [], "nextQuestionId": 0, "architectureNotes": [ { "id": 0, "text": "Current implementation has CURRENT_VERSION defined separately in src/utils/ensure-files.ts and DEFAULT_VERSION in src/migrations/registry.ts - this violates DRY", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" }, { "id": 1, "text": "Solution: Create src/utils/version.ts with single export const CURRENT_VERSION = '0.7.0', import from both files", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" }, { "id": 2, "text": "Alternatively: Export CURRENT_VERSION from migrations/registry.ts and import in ensure-files.ts (reuse existing constant)", "deleted": false, "createdAt": "2025-11-07T01:45:00.000Z" } ], "nextNoteId": 3, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-07T02:03:13.489Z" }, { "state": "testing", "timestamp": "2025-11-07T02:05:07.125Z" }, { "state": "implementing", "timestamp": "2025-11-07T02:07:41.749Z" }, { "state": "validating", "timestamp": "2025-11-07T02:09:36.397Z" }, { "state": "done", "timestamp": "2025-11-07T02:13:07.755Z" } ], "userStory": { "role": "developer using fspec for the first time", "action": "initialize a new project with work-units.json", "benefit": "I don't see unnecessary migration warnings or backup files" }, "updated": "2025-11-07T02:13:07.755Z" }, "FEAT-020": { "id": "FEAT-020", "title": "Auto-update check on startup", "type": "story", "status": "backlog", "createdAt": "2025-11-05T21:12:48.746Z", "updatedAt": "2025-11-05T21:12:48.746Z", "description": "Check npm registry on fspec startup to notify users when a newer version is available, with option to auto-install or prompt for manual update", "children": [] }, "TUI-028": { "id": "TUI-028", "title": "Changed files view missing unstaged files", "type": "bug", "status": "done", "createdAt": "2025-11-05T21:59:19.471Z", "updatedAt": "2025-11-05T22:14:37.801Z", "children": [], "description": "The changed files view in the TUI is not displaying unstaged files. Currently, when viewing the changed files screen, only a subset of modified files appear. The view should show all files that have been modified (both staged and unstaged), including deleted files, to give users a complete picture of their working directory state.", "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T22:01:57.569Z" }, { "state": "testing", "timestamp": "2025-11-05T22:06:47.053Z" }, { "state": "implementing", "timestamp": "2025-11-05T22:09:17.978Z" }, { "state": "validating", "timestamp": "2025-11-05T22:10:10.240Z" }, { "state": "done", "timestamp": "2025-11-05T22:14:37.802Z" } ], "userStory": { "role": "developer using fspec TUI", "action": "see all changed files including unstaged and untracked files", "benefit": "I have a complete view of my working directory changes" }, "rules": [ { "id": 0, "text": "Changed files view must show staged files (files added with git add)", "deleted": false, "createdAt": "2025-11-05T22:02:16.387Z" }, { "id": 1, "text": "Changed files view must show unstaged modifications to tracked files", "deleted": false, "createdAt": "2025-11-05T22:02:17.880Z" }, { "id": 2, "text": "Changed files view must show untracked files (new files not yet added to git)", "deleted": false, "createdAt": "2025-11-05T22:02:19.408Z" }, { "id": 3, "text": "Changed files view must show deleted files with proper status indicators", "deleted": false, "createdAt": "2025-11-05T22:02:20.678Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "User creates new file newfile.txt (untracked), opens changed files view with F key, sees newfile.txt listed with 'A' indicator in green", "deleted": false, "createdAt": "2025-11-05T22:02:31.271Z" }, { "id": 1, "text": "User modifies existing file src/index.ts (unstaged), opens changed files view, sees src/index.ts with 'M' indicator in yellow", "deleted": false, "createdAt": "2025-11-05T22:02:33.189Z" }, { "id": 2, "text": "User stages file with git add README.md, opens changed files view, sees README.md under staged section with appropriate indicator", "deleted": false, "createdAt": "2025-11-05T22:02:34.560Z" }, { "id": 3, "text": "User deletes file oldfile.ts (unstaged deletion), opens changed files view, sees oldfile.ts with 'D' indicator in red", "deleted": false, "createdAt": "2025-11-05T22:02:36.164Z" } ], "nextExampleId": 4, "questions": [ { "id": 0, "text": "@human: Should untracked files appear in a separate 'Untracked' section, or should they be mixed with unstaged files?", "deleted": false, "createdAt": "2025-11-05T22:02:47.056Z", "selected": true, "answer": "Untracked files should be mixed with unstaged files, not separated into a different section" }, { "id": 1, "text": "@human: The current code excludes untracked files from the unstaged list. Should we combine them or keep them separate in the data model?", "deleted": false, "createdAt": "2025-11-05T22:02:48.389Z", "selected": true, "answer": "Combine untracked files with unstaged files in the data model" }, { "id": 2, "text": "@human: Should the files be sorted in any particular order (alphabetical, by status, by type)?", "deleted": false, "createdAt": "2025-11-05T22:02:49.736Z", "selected": true, "answer": "No particular sorting order needed" } ], "nextQuestionId": 3, "estimate": 2, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-05T22:14:37.801Z" }, "VIEW-002": { "id": "VIEW-002", "title": "Mermaid diagram zoom not centered on mouse and trackpad causes jittering", "type": "bug", "status": "done", "createdAt": "2025-11-05T22:25:58.886Z", "updatedAt": "2025-11-05T22:36:06.022Z", "description": "The fullscreen mermaid diagram viewer zoom feature has two critical issues: 1) Zoom does not zoom FROM the mouse position (should keep point under cursor fixed), 2) Trackpad scrolling causes jitter instead of smooth zoom. The implementation relies on panzoom.zoomToPoint() which doesn't match mindstrike's working manual zoom-to-point formula. Trackpad events need debouncing/smoothing.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-05T22:26:06.997Z" }, { "state": "testing", "timestamp": "2025-11-05T22:29:50.805Z" }, { "state": "implementing", "timestamp": "2025-11-05T22:31:51.240Z" }, { "state": "validating", "timestamp": "2025-11-05T22:33:12.260Z" }, { "state": "done", "timestamp": "2025-11-05T22:36:06.023Z" } ], "rules": [ { "id": 0, "text": "Zoom must be centered on cursor position (point under cursor stays fixed during zoom)", "deleted": false, "createdAt": "2025-11-05T22:26:18.490Z" }, { "id": 1, "text": "Mouse wheel events must use deltaMode to correctly calculate zoom delta (supports LINE=1, PAGE=2, PIXEL=0 modes)", "deleted": false, "createdAt": "2025-11-05T22:26:19.804Z" }, { "id": 2, "text": "Trackpad scroll events must be smoothed/debounced to prevent jittering from rapid tiny deltas", "deleted": false, "createdAt": "2025-11-05T22:26:21.421Z" }, { "id": 3, "text": "Horizontal scroll (deltaX) must always pan left/right regardless of pan mode", "deleted": false, "createdAt": "2025-11-05T22:26:23.685Z" }, { "id": 4, "text": "Manual zoom-to-point calculation: newX = viewport.x + (mouseX - viewport.x) * (1 - zoomRatio)", "deleted": false, "createdAt": "2025-11-05T22:26:25.831Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User positions mouse at top-right corner of diagram, scrolls up with mouse wheel, diagram zooms in but shifts position (point under cursor moves)", "deleted": false, "createdAt": "2025-11-05T22:26:38.201Z" }, { "id": 1, "text": "User positions mouse at center of diagram, scrolls up with mouse wheel, diagram zooms in and point under cursor stays fixed (correct behavior like mindstrike)", "deleted": false, "createdAt": "2025-11-05T22:26:39.643Z" }, { "id": 2, "text": "User scrolls with trackpad (vertical two-finger swipe), diagram jitters rapidly instead of smooth zoom (many tiny deltaY events cause rapid state changes)", "deleted": false, "createdAt": "2025-11-05T22:26:41.199Z" }, { "id": 3, "text": "User scrolls with trackpad (horizontal two-finger swipe), diagram pans smoothly left/right (deltaX events work correctly)", "deleted": false, "createdAt": "2025-11-05T22:26:42.889Z" }, { "id": 4, "text": "User scrolls mouse wheel down, diagram zooms out centered on cursor position (same zoom-to-point formula applies)", "deleted": false, "createdAt": "2025-11-05T22:26:44.397Z" } ], "nextExampleId": 5, "attachments": [ "spec/attachments/VIEW-002/fullscreen-mermaid-viewer-research.md" ], "architectureNotes": [ { "id": 0, "text": "Root cause analysis: fspec implementation uses panzoom.zoomToPoint() method which doesn't correctly implement zoom-to-cursor behavior. Mindstrike manually calculates viewport offset using formula: newX = viewport.x + (mouseX - viewport.x) * (1 - zoomRatio). This keeps the point under the cursor fixed during zoom. Current implementation passes clientX/clientY to panzoom but library's zoomToPoint doesn't work as expected.", "deleted": false, "createdAt": "2025-11-05T22:27:03.644Z" }, { "id": 1, "text": "Trackpad jitter cause: Trackpads send many rapid scroll events with tiny deltaY values. Each event triggers immediate zoom state change. Solution: implement debouncing or accumulate deltas over short time window (e.g., 16ms) before applying zoom. Mindstrike may benefit from ReactFlow's internal smoothing.", "deleted": false, "createdAt": "2025-11-05T22:27:05.341Z" }, { "id": 2, "text": "Implementation approach: Replace panzoom.zoomToPoint() call with manual viewport calculation matching mindstrike's MindMap.tsx lines 1004-1012. Get panzoom's current pan/zoom state, calculate new state with zoom-to-point formula, then apply with panzoom.zoom() and panzoom.pan() separately.", "deleted": false, "createdAt": "2025-11-05T22:27:07.063Z" } ], "nextNoteId": 3, "userStory": { "role": "developer viewing mermaid diagrams in fullscreen mode", "action": "zoom in and out from my cursor position smoothly with both mouse and trackpad", "benefit": "I can examine diagram details precisely where I'm looking without the diagram jumping around" }, "estimate": 3, "questions": [], "nextQuestionId": 0, "updated": "2025-11-05T22:36:06.022Z" }, "REMIND-010": { "id": "REMIND-010", "title": "Foundation discovery removal commands documentation", "type": "story", "status": "done", "createdAt": "2025-11-06T05:16:35.454Z", "updatedAt": "2025-11-06T05:29:31.830Z", "description": "Document remove-persona and remove-capability in help setup section and improve discover-foundation placeholder guidance", "children": [], "userStory": { "role": "developer using fspec", "action": "understand how to remove placeholder items during foundation discovery", "benefit": "I can easily clean up unwanted personas/capabilities without manual JSON editing" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-06T05:16:51.596Z" }, { "state": "testing", "timestamp": "2025-11-06T05:23:07.455Z" }, { "state": "implementing", "timestamp": "2025-11-06T05:25:11.317Z" }, { "state": "validating", "timestamp": "2025-11-06T05:25:53.827Z" }, { "state": "done", "timestamp": "2025-11-06T05:29:31.830Z" } ], "rules": [ { "id": 0, "text": "The 'fspec help setup' section must include remove-persona command documentation", "deleted": false, "createdAt": "2025-11-06T05:16:58.581Z" }, { "id": 1, "text": "discover-foundation placeholder warnings must explain how to remove unwanted items", "deleted": false, "createdAt": "2025-11-06T05:17:04.591Z" }, { "id": 2, "text": "Both remove-persona and remove-capability must be documented in help setup section", "deleted": false, "createdAt": "2025-11-06T05:20:09.760Z" }, { "id": 3, "text": "discover-foundation error message must include instructions for both filling AND removing placeholder fields", "deleted": false, "createdAt": "2025-11-06T05:21:17.089Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Developer runs 'fspec help setup' and sees remove-persona command listed alongside add-persona", "deleted": false, "createdAt": "2025-11-06T05:17:10.139Z" }, { "id": 1, "text": "discover-foundation detects placeholder personas and outputs system-reminder explaining to use 'fspec remove-persona <name>' to remove them", "deleted": false, "createdAt": "2025-11-06T05:17:16.611Z" }, { "id": 2, "text": "Developer runs 'fspec help setup' and sees remove-capability command with usage, options, and examples", "deleted": false, "createdAt": "2025-11-06T05:20:15.217Z" }, { "id": 3, "text": "Help text for remove-persona and remove-capability follows same format as add-persona/add-capability with usage, description, and examples", "deleted": false, "createdAt": "2025-11-06T05:20:37.309Z" }, { "id": 4, "text": "When discover-foundation detects placeholder personas like '[QUESTION: Who uses this?]', the error message should explain: 'To remove unwanted placeholders: fspec remove-persona \"[QUESTION: Who uses this?]\"'", "deleted": false, "createdAt": "2025-11-06T05:21:03.264Z" } ], "nextExampleId": 5, "questions": [ { "id": 0, "text": "@human: Should remove-capability also be included in the help setup section, or just remove-persona?", "deleted": false, "createdAt": "2025-11-06T05:17:22.687Z", "selected": true, "answer": "Yes, both remove-capability and remove-persona should be included in the help setup section" }, { "id": 1, "text": "@human: Where exactly in the discover-foundation flow should the removal guidance appear - when placeholders are detected, when showing field-by-field prompts, or both?", "deleted": false, "createdAt": "2025-11-06T05:17:28.465Z", "selected": true, "answer": "When discover-foundation detects placeholder personas/capabilities, show removal guidance in the error/warning message" }, { "id": 2, "text": "@human: Should the help text follow the same format as other commands in the setup section (showing usage, options, examples)?", "deleted": false, "createdAt": "2025-11-06T05:17:35.106Z", "selected": true, "answer": "Yes, follow the same format as other commands in the setup section (usage, options, examples)" } ], "nextQuestionId": 3, "estimate": 2, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-06T05:29:31.830Z" }, "REMIND-011": { "id": "REMIND-011", "title": "Auto-replace placeholder personas and capabilities when adding first item", "type": "story", "status": "done", "createdAt": "2025-11-06T05:30:23.517Z", "updatedAt": "2025-11-06T05:47:35.081Z", "description": "When running add-persona or add-capability, automatically remove placeholder entries if this is the first real persona/capability being added", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-06T05:37:07.361Z" }, { "state": "testing", "timestamp": "2025-11-06T05:40:10.470Z" }, { "state": "implementing", "timestamp": "2025-11-06T05:42:28.240Z" }, { "state": "validating", "timestamp": "2025-11-06T05:47:04.408Z" }, { "state": "done", "timestamp": "2025-11-06T05:47:35.081Z" } ], "userStory": { "role": "developer using discover-foundation workflow", "action": "add my first real persona or capability", "benefit": "placeholder items are automatically cleaned up without manual editing" }, "rules": [ { "id": 0, "text": "add-persona must detect and remove placeholder personas when adding the first real persona", "deleted": false, "createdAt": "2025-11-06T05:37:28.995Z" }, { "id": 1, "text": "add-capability must detect and remove placeholder capabilities when adding the first real capability", "deleted": false, "createdAt": "2025-11-06T05:37:34.007Z" }, { "id": 2, "text": "Placeholder detection: name or description contains [QUESTION:] or [DETECTED:] patterns", "deleted": false, "createdAt": "2025-11-06T05:37:41.075Z" }, { "id": 3, "text": "Only remove placeholders when adding the FIRST real item (not subsequent items)", "deleted": false, "createdAt": "2025-11-06T05:37:45.993Z" }, { "id": 4, "text": "Must work with both foundation.json and foundation.json.draft files", "deleted": false, "createdAt": "2025-11-06T05:37:50.968Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Foundation has placeholder persona '[QUESTION: Who uses this?]', user runs 'fspec add-persona \"Developer\" \"Writes code\"', placeholder persona is removed, Developer persona is added", "deleted": false, "createdAt": "2025-11-06T05:37:57.611Z" }, { "id": 1, "text": "Foundation has placeholder capability '[QUESTION: What can users DO?]', user runs 'fspec add-capability \"Spec Validation\" \"Validates Gherkin\"', placeholder capability is removed, Spec Validation capability is added", "deleted": false, "createdAt": "2025-11-06T05:38:03.006Z" }, { "id": 2, "text": "Foundation already has real persona 'Developer', user adds 'QA Engineer', NO placeholders are removed (not the first item)", "deleted": false, "createdAt": "2025-11-06T05:38:09.379Z" }, { "id": 3, "text": "Foundation has 3 placeholder personas, user adds first real persona, ALL 3 placeholder personas are removed", "deleted": false, "createdAt": "2025-11-06T05:38:14.371Z" }, { "id": 4, "text": "Foundation has 1 real persona 'Developer' and 1 placeholder persona '[QUESTION: ...]', user adds 'QA Engineer', NO placeholders removed (already has real persona)", "deleted": false, "createdAt": "2025-11-06T05:38:20.857Z" } ], "nextExampleId": 5, "questions": [ { "id": 0, "text": "@human: Should the command output show a message when placeholders are removed?", "deleted": false, "createdAt": "2025-11-06T05:38:28.270Z", "selected": true, "answer": "Yes - show informative message like 'Removed N placeholder persona(s)' so user understands what happened" } ], "nextQuestionId": 1, "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-06T05:47:35.081Z" }, "AGENT-019": { "id": "AGENT-019", "title": "Optimize AI agent information ingestion with state-aware documentation", "type": "story", "status": "backlog", "createdAt": "2025-11-07T00:18:30.412Z", "updatedAt": "2025-11-07T01:05:37.391Z", "description": "Implement state-aware bootstrap, progressive disclosure guides, and inline tips to help ALL AI agents efficiently consume fspec workflow information. Uses Codex's 10KB/256-line limits as baseline constraint to ensure universal compatibility.", "children": [], "attachments": [ "spec/attachments/AGENT-019/agent-information-ingestion-optimization-v2.md", "spec/attachments/AGENT-019/domain-knowledge-graph-epic.md" ] }, "GRAPH-001": { "id": "GRAPH-001", "title": "Graph Core Infrastructure", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:02:29.624Z", "updatedAt": "2025-11-07T01:02:29.624Z", "description": "Natural boundary: Basic graph operations working. Install ngraph.graph, create graph builder, define node types (Command, State, Event, Guide, Tag, Help), define edge types (suggests, requires, triggers, documents, contains, uses), build JSON serialization, write unit tests. MUST use 'fspec' command for testing, NOT npx/npm/node. TDD required: RED-GREEN-REFACTOR.", "epic": "domain-knowledge-graph", "children": [] }, "GRAPH-002": { "id": "GRAPH-002", "title": "Command Graph Population", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:02:31.222Z", "updatedAt": "2025-11-07T01:07:32.909Z", "description": "Natural boundary: All existing fspec commands mapped to graph. Every command exists as graph node with metadata, state transitions modeled as edges, command relationships defined, prerequisites added, help text linked. DO NOT use 'node dist/index.js' - use 'fspec' command. Parse help text programmatically. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "GRAPH-001" ] }, "GRAPH-003": { "id": "GRAPH-003", "title": "Graph Query Foundation", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:02:32.727Z", "updatedAt": "2025-11-07T01:10:30.315Z", "description": "Natural boundary: Basic graph queries working. Graph traversal utilities, pathfinding algorithms (ngraph.path), query by node/edge type, unit tests pass. Dependencies: GRAPH-001, GRAPH-002. Blocks: NAV-001, NAV-002. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "GRAPH-002", "GRAPH-001" ] }, "NAV-001": { "id": "NAV-001", "title": "Suggest Command", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:02:46.473Z", "updatedAt": "2025-11-07T01:07:36.242Z", "description": "Natural boundary: 'fspec suggest' returns contextual suggestions. Queries graph for current context, returns 1-3 next-step suggestions with examples, output ≤300 bytes, help text included. Dependencies: GRAPH-003. Blocks: NAV-003. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "GRAPH-003" ] }, "NAV-002": { "id": "NAV-002", "title": "Path Command", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:02:47.862Z", "updatedAt": "2025-11-07T01:07:38.053Z", "description": "Natural boundary: 'fspec path <goal>' shows command sequence. Uses ngraph.path for pathfinding, supports goals (done/implementing/testing), shows step-by-step sequence, output ≤800 bytes, help text included. Dependencies: GRAPH-003. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "GRAPH-003" ] }, "NAV-003": { "id": "NAV-003", "title": "Inline Contextual Tips", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:02:49.524Z", "updatedAt": "2025-11-07T01:07:39.920Z", "description": "Natural boundary: Key commands output graph-powered suggestions. Tips appear after success, graph-powered (not hardcoded), added to create-story/update-work-unit-status/set-user-story/generate-scenarios, overhead ≤200-300 bytes. Dependencies: NAV-001. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "NAV-001" ] }, "DOC-007": { "id": "DOC-007", "title": "Guide System Core", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:09.848Z", "updatedAt": "2025-11-07T01:03:09.848Z", "description": "Natural boundary: 'fspec guide <topic>' command working. Reads guide files from spec/guides/, output checked (≤5KB per guide), help text included, list available guides, feature file and tests. Dependencies: None. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [] }, "DOC-008": { "id": "DOC-008", "title": "Core Workflow Guides", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:11.420Z", "updatedAt": "2025-11-07T01:11:29.413Z", "description": "Natural boundary: All essential guides written. Guide files (≤5KB each): acdd.md, example-mapping.md, coverage.md, hooks.md, kanban.md, getting-started.md. All guides linked in graph, accessible via 'fspec guide <topic>', output size validated. Dependencies: DOC-001, GRAPH-002. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "GRAPH-002", "DOC-007" ] }, "DOC-009": { "id": "DOC-009", "title": "Enhanced Help System", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:13.132Z", "updatedAt": "2025-11-07T01:10:44.544Z", "description": "Natural boundary: Graph-powered help with semantic search. 'fspec help' shows graph-powered list, 'fspec help <command>' shows graph-enhanced details, NEW: 'fspec help specs' (workflow guide), 'fspec help commands' (grouped by phase), 'fspec help workflows' (all workflows). Dependencies: GRAPH-002, DOC-001. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOC-007", "GRAPH-002" ] }, "DOC-010": { "id": "DOC-010", "title": "AGENTS.md Restructure", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:14.590Z", "updatedAt": "2025-11-07T01:10:03.319Z", "description": "Natural boundary: Minimal navigation hub complete (≤4KB). AGENTS.md rewritten as navigation hub, file ≤4KB, contains quick start/core concepts/graph query examples, delegates to guides, tested with Codex (10KB limit - NO TRUNCATION) and Claude Code. Dependencies: DOC-001, DOC-002. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOC-008", "DOC-007" ] }, "DOC-011": { "id": "DOC-011", "title": "Context-Aware Bootstrap", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:16.361Z", "updatedAt": "2025-11-07T01:09:53.761Z", "description": "Natural boundary: Bootstrap supports optional context flags. Default ≤8KB (general overview), --work-unit=<id> ≤7KB (work unit context), --phase=<phase> ≤6KB (phase guide), all modes tested with Codex. Dependencies: DOC-004, NAV-001. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "NAV-001", "DOC-010" ] }, "DOMAIN-001": { "id": "DOMAIN-001", "title": "Event Storming Workflow State", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:35.664Z", "updatedAt": "2025-11-07T01:03:35.664Z", "description": "Natural boundary: New workflow state working. 'event_storming' state added, transitions defined (backlog→event_storming, event_storming→specifying), state validation updated, help text updated. Dependencies: None. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [] }, "DOMAIN-002": { "id": "DOMAIN-002", "title": "Event Storm Data Model", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:37.300Z", "updatedAt": "2025-11-07T01:07:47.921Z", "description": "Natural boundary: Event Storm artifacts stored in graph. Event node types added (DomainEvent, Command, Aggregate, Policy, ExternalSystem, Hotspot, BoundedContext), metadata schema defined, work unit/foundation data structures, serialization working. Dependencies: GRAPH-001. Blocks: DOMAIN-003, DOMAIN-004, DOMAIN-005, DOMAIN-006. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "GRAPH-001" ] }, "DOMAIN-003": { "id": "DOMAIN-003", "title": "Event Storm Commands Part 1", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:39.498Z", "updatedAt": "2025-11-07T01:07:49.626Z", "description": "Natural boundary: Basic artifact capture working. Commands: add-domain-event, add-command (--triggers flag), add-aggregate (--context flag). Artifacts added to graph, stored in work-units.json, help text included. Dependencies: DOMAIN-002. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOMAIN-002" ] }, "DOMAIN-004": { "id": "DOMAIN-004", "title": "Event Storm Commands Part 2", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:41.019Z", "updatedAt": "2025-11-07T01:07:51.146Z", "description": "Natural boundary: Advanced artifact capture working. Commands: add-policy, add-hotspot, add-external-system, add-bounded-context-to-foundation, list-event-storm. Artifacts added to graph, stored in work-units.json/foundation.json, help text included. Dependencies: DOMAIN-002. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOMAIN-002" ] }, "DOMAIN-005": { "id": "DOMAIN-005", "title": "Event Storm Transformation", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:42.613Z", "updatedAt": "2025-11-07T01:11:26.245Z", "description": "Natural boundary: Event Storm → Example Mapping transformation working. Command: transform-event-storm. Transforms domain events→examples, policies→rules, hotspots→questions, advances work unit to specifying (--auto-advance). Dependencies: DOMAIN-003, DOMAIN-004. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOMAIN-004", "DOMAIN-003" ] }, "TAG-001": { "id": "TAG-001", "title": "Tag Relationship Data Model", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:57.935Z", "updatedAt": "2025-11-07T01:03:57.935Z", "description": "Natural boundary: Enhanced tags.json with relationships. tags.json schema updated, relationship types defined (hierarchical/semantic/domain), JSON Schema validation, migration script, unit tests pass. Dependencies: None. Blocks: TAG-002, TAG-003, TAG-004. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [] }, "TAG-002": { "id": "TAG-002", "title": "Tag Relationship Commands", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:03:59.359Z", "updatedAt": "2025-11-07T01:07:56.291Z", "description": "Natural boundary: CRUD operations for tag relationships. Commands: add-tag-relationship (--parent/--requires/--domain-event flags), show-tag-relationships, remove-tag-relationship. Stored in tags.json, circular hierarchy prevention, help text. Dependencies: TAG-001. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "TAG-001" ] }, "TAG-003": { "id": "TAG-003", "title": "Tag Discovery from Events", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:01.042Z", "updatedAt": "2025-11-07T01:08:38.344Z", "description": "Natural boundary: Automatic tag suggestion from Event Storm. Commands: suggest-tags-from-events, sync-tags-with-event-storm. Algorithm: cluster events by aggregate/context→component tags, group by similarity→feature tags, identify external systems→technical tags. Dependencies: TAG-002, DOMAIN-005. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOMAIN-005" ] }, "TAG-004": { "id": "TAG-004", "title": "Tag Validation", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:02.575Z", "updatedAt": "2025-11-07T01:11:27.965Z", "description": "Natural boundary: Comprehensive tag validation. Command: validate-tag-relationships. Checks: no circular hierarchies, valid semantic relationships, feature tags have domain mappings, component tags have bounded context mappings, orphaned tags. Dependencies: TAG-001, TAG-002. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "TAG-002", "TAG-001" ] }, "VIZ-001": { "id": "VIZ-001", "title": "Graph Visualization Core", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:18.022Z", "updatedAt": "2025-11-07T01:08:01.270Z", "description": "Natural boundary: Graph export to multiple formats. Commands: 'fspec graph show', 'fspec graph export --format=<format> --output=<file>'. Formats: mermaid, dot, json. Mermaid/DOT/JSON generators. Dependencies: GRAPH-003. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "GRAPH-003" ] }, "VIZ-002": { "id": "VIZ-002", "title": "Graph Filtering", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:19.705Z", "updatedAt": "2025-11-07T01:08:03.101Z", "description": "Natural boundary: Filter graph by type, context, epic. Filtering options: --type=<node-type>, --context=<bounded-context>, --epic=<epic-name>, --depth=<n>. Command: 'fspec graph show --type=Command --context=Authentication'. Dependencies: VIZ-001. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "VIZ-001" ] }, "VIZ-003": { "id": "VIZ-003", "title": "Tag Graph Visualization", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:21.231Z", "updatedAt": "2025-11-07T01:11:02.884Z", "description": "Natural boundary: Specialized tag graph export. Command: 'fspec export-tag-graph'. Graph types: hierarchy, semantic, domain, complete. Command: 'fspec export-tag-graph --type=<type> --format=mermaid --output=<file>'. Dependencies: TAG-002, VIZ-001. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "VIZ-001", "TAG-002" ] }, "VIZ-004": { "id": "VIZ-004", "title": "Event Storm Diagrams", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:22.808Z", "updatedAt": "2025-11-07T01:11:04.533Z", "description": "Natural boundary: Generate Event Storm visualizations. Generate timeline (events in sequence), bounded context map, command-event flow. Command: 'fspec export-event-storm-diagram <work-unit-id> --type=<type> --output=<file>'. Auto-attach diagrams to work units. Dependencies: DOMAIN-005, VIZ-001. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "VIZ-001", "DOMAIN-005" ] }, "INT-001": { "id": "INT-001", "title": "Auto-Tagging During Scenario Generation", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:39.521Z", "updatedAt": "2025-11-07T01:10:21.409Z", "description": "Natural boundary: Feature files auto-tagged from Event Storm. 'fspec generate-scenarios' queries Event Storm, auto-applies tags from domain mappings (bounded context/aggregates/events), coverage file includes domain event links. Dependencies: TAG-003, DOMAIN-005. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOMAIN-005", "TAG-003" ] }, "INT-002": { "id": "INT-002", "title": "System Reminder Integration", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:41.127Z", "updatedAt": "2025-11-07T01:04:41.127Z", "description": "Natural boundary: All reminders integrated into workflow. Estimation reminder on transition without estimate, status duration reminder on show-work-unit, estimation blocked for stories without feature files, estimation blocked for prefill placeholders, temporal validation on state transitions. Dependencies: None. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [] }, "INT-003": { "id": "INT-003", "title": "Research Tool Integration", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:42.966Z", "updatedAt": "2025-11-07T01:08:09.331Z", "description": "Natural boundary: Event Storming integrated with fspec research. 'fspec research' queries Event Storm artifacts, research prompts reference domain events/aggregates/bounded contexts, graph queries integrated. Dependencies: DOMAIN-005. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOMAIN-005" ] }, "INT-004": { "id": "INT-004", "title": "Validation Hooks", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:44.377Z", "updatedAt": "2025-11-07T01:08:11.365Z", "description": "Natural boundary: Tag-Event Storm alignment validation. Lifecycle hook: pre-validating state checks tag alignment, runs 'validate-tag-relationships' automatically, fails if orphaned tags/missing domain mappings, emits system-reminder with fix instructions. Dependencies: TAG-004. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "TAG-004" ] }, "DOC-012": { "id": "DOC-012", "title": "Event Storming Guides", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:04:59.978Z", "updatedAt": "2025-11-07T01:08:12.906Z", "description": "Natural boundary: Event Storming guides written. Guides: spec/guides/event-storming.md, spec/guides/tag-ontology.md. Guides ≤5KB each, accessible via 'fspec guide event-storming' and 'fspec guide tag-ontology', linked in graph. Dependencies: DOC-001. Use 'fspec' command only. TDD required.", "epic": "domain-knowledge-graph", "children": [], "dependsOn": [ "DOC-007" ] }, "DOC-013": { "id": "DOC-013", "title": "Comprehensive Help Documentation", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:05:01.617Z", "updatedAt": "2025-11-07T01:05:01.617Z", "description": "Natural boundary: All commands have help text. Every new command has comprehensive --help output, help text follows fspec conventions (AI-optimized sections), examples use 'fspec' command (NOT npx/npm/node), all help text added to graph nodes. Dependencies: All command work units. Use 'fspec' command only.", "epic": "domain-knowledge-graph", "children": [] }, "DOC-014": { "id": "DOC-014", "title": "Example Sessions", "type": "story", "status": "backlog", "createdAt": "2025-11-07T01:05:03.079Z", "updatedAt": "2025-11-07T01:05:03.079Z", "description": "Natural boundary: Example workflows documented. Examples: Greenfield project with Big Picture Event Storming, Adding feature with Process Modeling Event Storming, Refactoring with tag-domain alignment. All examples use ONLY 'fspec' command. Dependencies: All previous work units.", "epic": "domain-knowledge-graph", "children": [] }, "BUG-071": { "id": "BUG-071", "title": "Worker module not bundled - MODULE_NOT_FOUND for diff-worker.js", "type": "bug", "status": "done", "createdAt": "2025-11-07T07:11:57.014Z", "updatedAt": "2025-11-07T07:25:03.366Z", "description": "Critical bundling issue: Worker file is being called from static location instead of being bundled with the application.\n\nError: Cannot find module '/Users/rquast/projects/ollama/dist/git/diff-worker.js'\n at Function._resolveFilename (node:internal/modules/cjs/loader:1383:15)\n at MessagePort.<anonymous> (node:internal/main/worker_thread:226:26)\n\nRoot cause: Build configuration is not bundling worker files, causing hard-coded paths to fail.\n\nRequirements:\n- Worker file MUST be bundled with the application\n- Worker path resolution must use bundled location, not static paths\n- Fix must work in both development and production environments", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-07T07:13:27.404Z" }, { "state": "testing", "timestamp": "2025-11-07T07:15:39.573Z" }, { "state": "implementing", "timestamp": "2025-11-07T07:24:33.814Z" }, { "state": "validating", "timestamp": "2025-11-07T07:24:36.263Z" }, { "state": "done", "timestamp": "2025-11-07T07:25:03.366Z" } ], "rules": [ { "id": 0, "text": "Worker path must resolve relative to the fspec module location, not process.cwd()", "deleted": false, "createdAt": "2025-11-07T07:13:39.243Z" }, { "id": 1, "text": "Worker file must be accessible when fspec is installed as a dependency in another project", "deleted": false, "createdAt": "2025-11-07T07:13:39.844Z" }, { "id": 2, "text": "Fix must work in both development (running from source) and production (installed as dependency)", "deleted": false, "createdAt": "2025-11-07T07:13:41.311Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "When fspec is used in /Users/rquast/projects/ollama, process.cwd() returns /Users/rquast/projects/ollama, but worker is at /Users/rquast/projects/ollama/node_modules/@sengac/fspec/dist/git/diff-worker.js", "deleted": false, "createdAt": "2025-11-07T07:13:42.856Z" }, { "id": 1, "text": "Current code in FileDiffViewer.tsx:60 uses join(process.cwd(), 'dist', 'git', 'diff-worker.js') which fails when cwd is not fspec directory", "deleted": false, "createdAt": "2025-11-07T07:13:44.723Z" }, { "id": 2, "text": "CheckpointViewer.tsx:175 has the same issue with hardcoded process.cwd() path resolution", "deleted": false, "createdAt": "2025-11-07T07:13:46.271Z" } ], "nextExampleId": 3, "architectureNotes": [ { "id": 0, "text": "Solution: Use import.meta.url and fileURLToPath to resolve worker path relative to module location. This works in both development and production environments.", "deleted": false, "createdAt": "2025-11-07T07:13:57.848Z" }, { "id": 1, "text": "Affected files: src/tui/components/FileDiffViewer.tsx:60 and src/tui/components/CheckpointViewer.tsx:175", "deleted": false, "createdAt": "2025-11-07T07:13:59.515Z" }, { "id": 2, "text": "Worker is already bundled separately via esbuild in package.json build script. No changes needed to build process.", "deleted": false, "createdAt": "2025-11-07T07:14:01.059Z" } ], "nextNoteId": 3, "userStory": { "role": "developer using fspec as a dependency", "action": "spawn worker threads for git diff operations", "benefit": "the worker module is found and loaded correctly regardless of project location" }, "estimate": 2, "questions": [], "nextQuestionId": 0, "updated": "2025-11-07T07:25:03.366Z" }, "BUG-072": { "id": "BUG-072", "title": "TUI hangs when foundation.json is missing", "type": "bug", "status": "done", "createdAt": "2025-11-07T23:33:33.203Z", "updatedAt": "2025-11-07T23:44:49.150Z", "description": "When running 'fspec' (no arguments) in a project without spec/foundation.json, the TUI pauses/hangs instead of showing an empty board or a helpful error message.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-07T23:33:46.248Z" }, { "state": "testing", "timestamp": "2025-11-07T23:35:17.984Z" }, { "state": "implementing", "timestamp": "2025-11-07T23:37:50.630Z" }, { "state": "validating", "timestamp": "2025-11-07T23:39:13.268Z" }, { "state": "done", "timestamp": "2025-11-07T23:44:49.150Z" } ], "userStory": { "role": "developer using fspec in a new project", "action": "run the TUI without a foundation.json file", "benefit": "I see either an empty board or a helpful error message instead of the app hanging" }, "rules": [ { "id": 0, "text": "TUI must not hang or pause when foundation.json is missing", "deleted": false, "createdAt": "2025-11-07T23:34:04.701Z" }, { "id": 1, "text": "TUI should display an empty board when no work units exist", "deleted": false, "createdAt": "2025-11-07T23:34:06.784Z" }, { "id": 2, "text": "TUI must be responsive and allow user to exit with ESC key", "deleted": false, "createdAt": "2025-11-07T23:34:08.272Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "User runs 'fspec' in ~/projects/cagetools (no spec dir), TUI loads showing empty board", "deleted": false, "createdAt": "2025-11-07T23:34:16.234Z" }, { "id": 1, "text": "User runs 'fspec' in project with spec dir but no foundation.json, TUI loads showing empty board", "deleted": false, "createdAt": "2025-11-07T23:34:17.940Z" }, { "id": 2, "text": "User presses ESC key in TUI, app exits gracefully", "deleted": false, "createdAt": "2025-11-07T23:34:19.336Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-07T23:44:49.150Z" }, "TUI-029": { "id": "TUI-029", "title": "View FOUNDATION.md in TUI with attachment viewer", "type": "story", "status": "done", "createdAt": "2025-11-07T23:54:31.267Z", "updatedAt": "2025-11-08T00:22:25.003Z", "description": "Enable viewing spec/FOUNDATION.md file using the existing attachment viewer infrastructure with a new 'D' keybinding in the main TUI board view", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-07T23:54:43.663Z" }, { "state": "testing", "timestamp": "2025-11-08T00:03:34.728Z" }, { "state": "implementing", "timestamp": "2025-11-08T00:05:22.086Z" }, { "state": "specifying", "timestamp": "2025-11-08T00:07:17.892Z" }, { "state": "testing", "timestamp": "2025-11-08T00:09:24.826Z" }, { "state": "implementing", "timestamp": "2025-11-08T00:11:35.022Z" }, { "state": "validating", "timestamp": "2025-11-08T00:22:08.599Z" }, { "state": "done", "timestamp": "2025-11-08T00:22:25.004Z" } ], "userStory": { "role": "developer using fspec TUI", "action": "view the spec/FOUNDATION.md file directly from the main board", "benefit": "I can quickly review project foundation documentation without leaving the TUI" }, "rules": [ { "id": 0, "text": "Must reuse existing attachment viewer code by making it shared/reusable (refactor for code reuse)", "deleted": false, "createdAt": "2025-11-07T23:55:07.136Z" }, { "id": 1, "text": "FOUNDATION.md is NOT an attachment and does NOT belong to any work unit", "deleted": false, "createdAt": "2025-11-07T23:55:09.267Z" }, { "id": 2, "text": "New keybinding 'D' (uppercase D) must open spec/FOUNDATION.md in viewer", "deleted": false, "createdAt": "2025-11-07T23:55:10.725Z" }, { "id": 3, "text": "UI must display '◆ D View FOUNDATION.md' in the keybinding help line", "deleted": false, "createdAt": "2025-11-07T23:55:12.183Z" }, { "id": 4, "text": "UI element must appear to the RIGHT of 'F View Changed Files' with diamond separator", "deleted": false, "createdAt": "2025-11-07T23:55:13.941Z" }, { "id": 5, "text": "Must use diamond separator '◆' before 'D View FOUNDATION.md' text", "deleted": false, "createdAt": "2025-11-07T23:55:15.651Z" }, { "id": 6, "text": "File path is spec/FOUNDATION.md relative to project root (cwd)", "deleted": false, "createdAt": "2025-11-07T23:55:17.306Z" }, { "id": 7, "text": "Viewer must support all Markdown features (headings, lists, links, code blocks, etc.)", "deleted": false, "createdAt": "2025-11-07T23:55:19.004Z" }, { "id": 8, "text": "If FOUNDATION.md does not exist, show helpful error message instead of crashing", "deleted": false, "createdAt": "2025-11-07T23:55:22.225Z" }, { "id": 9, "text": "When D key is pressed, open spec/FOUNDATION.md in browser via HTTP server (like attachments)", "deleted": false, "createdAt": "2025-11-08T00:07:55.429Z" }, { "id": 10, "text": "Use openInBrowser() with HTTP URL http://localhost:{port}/view/spec/FOUNDATION.md", "deleted": false, "createdAt": "2025-11-08T00:07:57.452Z" }, { "id": 11, "text": "Reuse attachment server infrastructure (same HTTP server serves both attachments and FOUNDATION.md)", "deleted": false, "createdAt": "2025-11-08T00:07:59.542Z" } ], "nextRuleId": 12, "examples": [ { "id": 0, "text": "User runs 'fspec' (TUI), presses 'D' key, opens spec/FOUNDATION.md in viewer with Markdown rendering", "deleted": false, "createdAt": "2025-11-07T23:55:36.099Z" }, { "id": 1, "text": "User sees keybinding help line showing '◆ F View Changed Files ◆ D View FOUNDATION.md' in main TUI", "deleted": false, "createdAt": "2025-11-07T23:55:37.454Z" }, { "id": 2, "text": "User opens FOUNDATION.md viewer, sees rendered Markdown with headings/lists/code blocks, presses ESC, returns to board", "deleted": false, "createdAt": "2025-11-07T23:55:38.931Z" }, { "id": 3, "text": "User presses 'D' in project without spec/FOUNDATION.md, sees error 'FOUNDATION.md not found at spec/FOUNDATION.md'", "deleted": false, "createdAt": "2025-11-07T23:55:40.514Z" }, { "id": 4, "text": "Attachment viewer code is refactored into shared component, both attachment viewing and FOUNDATION.md viewing use same code", "deleted": false, "createdAt": "2025-11-07T23:55:41.896Z" }, { "id": 5, "text": "Diamond separator '◆' appears between 'F View Changed Files' and 'D View FOUNDATION.md' in help line", "deleted": false, "createdAt": "2025-11-07T23:55:43.769Z" } ], "nextExampleId": 6, "architectureNotes": [ { "id": 0, "text": "Refactor attachment server viewer code into shared component that can render any Markdown file (not just attachments)", "deleted": false, "createdAt": "2025-11-07T23:55:56.016Z" }, { "id": 1, "text": "Bind 'D' key in BoardView useInput handler to set viewMode to 'foundation-viewer'", "deleted": false, "createdAt": "2025-11-07T23:55:59.088Z" }, { "id": 2, "text": "Update UnifiedBoardLayout help line to include '◆ D View FOUNDATION.md' after 'F View Changed Files'", "deleted": false, "createdAt": "2025-11-07T23:56:00.875Z" }, { "id": 3, "text": "Foundation viewer should use attachment server to serve spec/FOUNDATION.md via HTTP (reuse existing server infrastructure)", "deleted": false, "createdAt": "2025-11-07T23:56:02.249Z" }, { "id": 4, "text": "D key handler directly calls openInBrowser() with HTTP URL (no view mode change)", "deleted": false, "createdAt": "2025-11-08T00:08:03.681Z" } ], "nextNoteId": 5, "estimate": 5, "questions": [], "nextQuestionId": 0, "updated": "2025-11-08T00:22:25.003Z" }, "RES-008": { "id": "RES-008", "title": "Integrate research guidance into AI agent assistance and ULTRATHINK compilation", "type": "story", "status": "done", "createdAt": "2025-11-08T05:44:18.552Z", "updatedAt": "2025-11-08T06:17:23.155Z", "description": "Update system-reminders, bootstrap content, and spec/CLAUDE.md to guide agents on using fspec research during specifying phase. Add ULTRATHINK-powered research compilation that creates markdown files with mermaid diagrams and auto-attaches to work units.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T05:47:18.921Z" }, { "state": "testing", "timestamp": "2025-11-08T05:51:26.594Z" }, { "state": "implementing", "timestamp": "2025-11-08T05:56:02.278Z" }, { "state": "validating", "timestamp": "2025-11-08T06:10:16.993Z" }, { "state": "done", "timestamp": "2025-11-08T06:17:23.155Z" } ], "userStory": { "role": "AI agent using fspec during discovery", "action": "receive guidance on using research tools and compile findings", "benefit": "I can answer questions with high-quality research that includes diagrams and gets attached to work units" }, "rules": [ { "id": 0, "text": "System-reminders during SPECIFYING phase must mention available research tools (fspec research)", "deleted": false, "createdAt": "2025-11-08T05:47:43.242Z" }, { "id": 1, "text": "Bootstrap content (fspec bootstrap) must include RESEARCH section documenting when and how to use research tools", "deleted": false, "createdAt": "2025-11-08T05:47:45.139Z" }, { "id": 2, "text": "spec/CLAUDE.md must document research workflow with concrete examples", "deleted": false, "createdAt": "2025-11-08T05:47:47.152Z" }, { "id": 3, "text": "Research compilation must use agent detection (agentRegistry.ts) to determine ULTRATHINK support", "deleted": false, "createdAt": "2025-11-08T05:47:48.678Z" }, { "id": 4, "text": "Compiled research must be markdown format with front matter metadata (work unit ID, timestamp, tool used)", "deleted": false, "createdAt": "2025-11-08T05:47:50.316Z" }, { "id": 5, "text": "Compiled research must generate mermaid diagrams for visual concepts (flowcharts, architecture, relationships)", "deleted": false, "createdAt": "2025-11-08T05:47:52.090Z" }, { "id": 6, "text": "Compiled research must auto-attach to work unit using add-attachment command", "deleted": false, "createdAt": "2025-11-08T05:47:53.738Z" } ], "nextRuleId": 7, "examples": [ { "id": 0, "text": "Agent moves AUTH-001 to specifying → system-reminder shows: 'Use fspec research --tool=ast or --tool=stakeholder to answer questions'", "deleted": false, "createdAt": "2025-11-08T05:48:06.387Z" }, { "id": 1, "text": "Agent runs 'fspec bootstrap' → output includes RESEARCH section with tool examples and workflow", "deleted": false, "createdAt": "2025-11-08T05:48:08.187Z" }, { "id": 2, "text": "spec/CLAUDE.md contains: 'During specifying, use fspec research --tool=ast --query=\"pattern\" to analyze code'", "deleted": false, "createdAt": "2025-11-08T05:48:09.866Z" }, { "id": 3, "text": "Agent runs 'fspec compile-research AUTH-001' → creates markdown with ULTRATHINK analysis (Claude) or deep analysis (other agents)", "deleted": false, "createdAt": "2025-11-08T05:48:11.964Z" }, { "id": 4, "text": "Compiled research includes: mermaid flowchart showing authentication flow, markdown summary, auto-attached to spec/attachments/AUTH-001/", "deleted": false, "createdAt": "2025-11-08T05:48:13.655Z" } ], "nextExampleId": 5, "estimate": 13, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-08T06:17:23.155Z" }, "BROWSE-001": { "id": "BROWSE-001", "title": "Remote Browser Control via EventSource", "type": "story", "status": "specifying", "createdAt": "2025-11-08T06:48:42.824Z", "updatedAt": "2025-11-08T06:56:45.261Z", "description": "Allow openBrowser function to connect to remote browser window using EventSource for tab/window control", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T06:48:48.365Z" } ], "userStory": { "role": "fspec developer", "action": "configure browser opening to use remote EventSource-controlled browser", "benefit": "I can control browser behavior from a central location without spawning new processes" }, "questions": [ { "id": 0, "text": "@human: Where will the EventSource server be running? (separate process, browser extension, web page?)", "deleted": false, "createdAt": "2025-11-08T06:49:17.350Z", "selected": false }, { "id": 1, "text": "@human: What config structure in fspec-config.json? (simple URL string or complex object with auth/retry?)", "deleted": false, "createdAt": "2025-11-08T06:49:18.812Z", "selected": false }, { "id": 2, "text": "@human: When to fallback to 'open' library? (config missing, connection fails, or both?)", "deleted": false, "createdAt": "2025-11-08T06:49:20.814Z", "selected": true, "answer": "Both: fallback when config missing AND when connection fails" }, { "id": 3, "text": "@human: What event payload should be sent? (just URL, or include tab/window preferences?)", "deleted": false, "createdAt": "2025-11-08T06:49:22.272Z", "selected": false } ], "nextQuestionId": 4, "attachments": [ "spec/attachments/BROWSE-001/eventsource-research.md" ], "rules": [ { "id": 0, "text": "Configuration in fspec-config.json must include EventSource URL and fallback behavior", "deleted": false, "createdAt": "2025-11-08T06:56:13.909Z" }, { "id": 1, "text": "Must fall back to 'open' library when EventSource config is missing or connection fails", "deleted": false, "createdAt": "2025-11-08T06:56:15.565Z" }, { "id": 2, "text": "Event payload must include URL and optional tab/window preference", "deleted": false, "createdAt": "2025-11-08T06:56:17.049Z" }, { "id": 3, "text": "EventSource connection must handle disconnects gracefully and retry", "deleted": false, "createdAt": "2025-11-08T06:56:18.692Z" }, { "id": 4, "text": "Both: fallback when config missing AND when connection fails", "deleted": false, "createdAt": "2025-11-08T06:56:45.261Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "openBrowser called with no EventSource config → uses 'open' library (current behavior)", "deleted": false, "createdAt": "2025-11-08T06:56:27.252Z" }, { "id": 1, "text": "openBrowser called with EventSource config present → sends event to remote browser listener", "deleted": false, "createdAt": "2025-11-08T06:56:28.988Z" }, { "id": 2, "text": "EventSource connection fails → falls back to 'open' library", "deleted": false, "createdAt": "2025-11-08T06:56:30.531Z" }, { "id": 3, "text": "Config specifies EventSource URL http://localhost:3000/browser-control → openBrowser sends POST to that endpoint", "deleted": false, "createdAt": "2025-11-08T06:56:32.345Z" } ], "nextExampleId": 4 }, "RES-009": { "id": "RES-009", "title": "Research Tool Discovery and Configuration UX", "type": "story", "status": "done", "createdAt": "2025-11-08T06:58:20.872Z", "updatedAt": "2025-11-10T08:20:25.900Z", "description": "Improve discoverability, configuration, and integration of fspec research tools to make them a natural part of Example Mapping workflow", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T06:58:27.598Z" }, { "state": "testing", "timestamp": "2025-11-10T05:47:44.958Z" }, { "state": "implementing", "timestamp": "2025-11-10T05:49:07.794Z" }, { "state": "validating", "timestamp": "2025-11-10T05:54:16.723Z" }, { "state": "done", "timestamp": "2025-11-10T05:55:35.420Z" }, { "state": "specifying", "timestamp": "2025-11-10T06:14:09.363Z" }, { "state": "blocked", "timestamp": "2025-11-10T06:34:31.350Z", "reason": "Waiting for RES-015 (TypeScript plugin system) - tool execution requires TypeScript architecture, RES-009 UX improvements complete" }, { "state": "specifying", "timestamp": "2025-11-10T08:17:48.189Z" }, { "state": "testing", "timestamp": "2025-11-10T08:18:41.657Z" }, { "state": "implementing", "timestamp": "2025-11-10T08:19:48.588Z" }, { "state": "validating", "timestamp": "2025-11-10T08:20:24.212Z" }, { "state": "done", "timestamp": "2025-11-10T08:20:25.900Z" } ], "userStory": { "role": "AI agent using fspec for Example Mapping", "action": "discover and use research tools easily without reading source code", "benefit": "I can answer technical questions efficiently and integrate findings into work units" }, "rules": [ { "id": 0, "text": "Tool listing must show tool status (configured vs unconfigured) at a glance", "deleted": false, "createdAt": "2025-11-08T06:58:51.869Z" }, { "id": 1, "text": "Tool listing must include brief description of what each tool does and when to use it", "deleted": false, "createdAt": "2025-11-08T06:58:53.423Z" }, { "id": 2, "text": "System-reminder when entering specifying state must prominently suggest research tools with status", "deleted": false, "createdAt": "2025-11-08T06:58:54.900Z" }, { "id": 3, "text": "Tool-specific help must be accessible via --help flag (not generic research help)", "deleted": false, "createdAt": "2025-11-08T06:58:56.384Z" }, { "id": 4, "text": "Configuration wizard must guide setup for unconfigured tools with validation", "deleted": false, "createdAt": "2025-11-08T06:58:58.032Z" }, { "id": 5, "text": "Research tool configs must support environment variables for API keys (avoid plain text)", "deleted": false, "createdAt": "2025-11-08T06:58:59.879Z" }, { "id": 6, "text": "Config validation command must check all tools and report which are ready vs need setup", "deleted": false, "createdAt": "2025-11-08T06:59:01.650Z" }, { "id": 7, "text": "Research output with --work-unit flag must prompt to save as attachment automatically", "deleted": false, "createdAt": "2025-11-08T06:59:03.361Z" }, { "id": 8, "text": "Attachment prompt must offer to extract rules/examples from research findings", "deleted": false, "createdAt": "2025-11-08T06:59:05.002Z" }, { "id": 9, "text": "AST tool must work in production mode (not just FSPEC_TEST_MODE=1)", "deleted": false, "createdAt": "2025-11-08T06:59:06.543Z" }, { "id": 10, "text": "No environment variables for API keys - use config file only", "deleted": false, "createdAt": "2025-11-10T01:42:30.182Z" }, { "id": 11, "text": "AI auto-parse research findings but ask user for clarification when uncertain (Example Mapping approach)", "deleted": false, "createdAt": "2025-11-10T01:47:01.927Z" }, { "id": 12, "text": "Three configuration methods: 1) CLI flags (--api-key=...), 2) Interactive wizard (detect TTY), 3) TUI config view (in main fspec TUI)", "deleted": false, "createdAt": "2025-11-10T01:49:24.999Z" }, { "id": 13, "text": "Yes, but use feedback loop pattern like 'fspec reverse' - emit system-reminder with tool suggestions, let AI analyze and choose, no hardcoded semantic analysis", "deleted": false, "createdAt": "2025-11-10T05:42:43.581Z" }, { "id": 14, "text": "AST tool help/interface exists but production implementation blocked - needs actual AST parsing logic implemented and tested (currently only works with FSPEC_TEST_MODE=1)", "deleted": false, "createdAt": "2025-11-10T05:43:48.851Z" }, { "id": 15, "text": "Research command must forward ALL unknown arguments to the research tool script (use Commander.js .allowUnknownOption())", "deleted": false, "createdAt": "2025-11-10T06:15:10.863Z" }, { "id": 16, "text": "YES! Research tools MUST be platform-agnostic TypeScript modules (not bash scripts). Use tsx/ts-node to execute .ts files in spec/research-scripts/, or bundle them with fspec. Tools must work on Windows, macOS, Linux without modification.", "deleted": false, "createdAt": "2025-11-10T06:19:29.506Z" }, { "id": 17, "text": "Research tools are dynamically loaded TypeScript modules - fspec uses dynamic import() to load and execute tools from spec/research-tools/*.ts", "deleted": false, "createdAt": "2025-11-10T06:19:51.877Z" }, { "id": 18, "text": "DEPENDENCY: Tool execution blocked on RES-015 (TypeScript plugin system). RES-009 scope limited to UX improvements only (listing, status, descriptions).", "deleted": false, "createdAt": "2025-11-10T06:34:23.637Z" } ], "nextRuleId": 19, "examples": [ { "id": 0, "text": "BEFORE: Run 'fspec research' → get list of tool names only (ast, confluence, jira, perplexity, stakeholder)", "deleted": false, "createdAt": "2025-11-08T06:59:27.480Z" }, { "id": 1, "text": "AFTER: Run 'fspec research' → see status (✓ configured ✗ not configured), descriptions, and usage hints", "deleted": false, "createdAt": "2025-11-08T06:59:29.358Z" }, { "id": 2, "text": "BEFORE: Run 'fspec research --tool=perplexity --help' → get GENERIC research help (not tool-specific)", "deleted": false, "createdAt": "2025-11-08T06:59:31.281Z" }, { "id": 3, "text": "AFTER: Run 'fspec research --tool=perplexity --help' → get perplexity script's --help output (query, model, format options)", "deleted": false, "createdAt": "2025-11-08T06:59:32.884Z" }, { "id": 4, "text": "BEFORE: Try perplexity tool → get error about missing API key, manually create ~/.fspec/fspec-config.json", "deleted": false, "createdAt": "2025-11-08T06:59:34.487Z" }, { "id": 5, "text": "AFTER: Run 'fspec research --configure perplexity' → wizard prompts for API key, validates, saves config", "deleted": false, "createdAt": "2025-11-08T06:59:36.851Z" }, { "id": 6, "text": "BEFORE: Research output to stdout → manually save to file → manually attach with 'fspec add-attachment'", "deleted": false, "createdAt": "2025-11-08T06:59:38.472Z" }, { "id": 7, "text": "AFTER: Research with --work-unit flag → prompts 'Save to attachments? (y/n)' → auto-attaches → offers to extract rules", "deleted": false, "createdAt": "2025-11-08T06:59:40.183Z" }, { "id": 8, "text": "BEFORE: AST tool requires FSPEC_TEST_MODE=1 → unusable in production Example Mapping workflow", "deleted": false, "createdAt": "2025-11-08T06:59:41.754Z" }, { "id": 9, "text": "AFTER: AST tool works in production without test mode flag", "deleted": false, "createdAt": "2025-11-08T06:59:43.457Z" }, { "id": 10, "text": "CURRENT: Perplexity script has outdated model 'llama-3.1-sonar-small-128k-online' → must guess 'sonar'", "deleted": false, "createdAt": "2025-11-08T06:59:45.272Z" }, { "id": 11, "text": "FIXED: Perplexity default model is up-to-date and works without guessing", "deleted": false, "createdAt": "2025-11-08T06:59:46.903Z" }, { "id": 12, "text": "Run 'fspec research --tool=ast --query \"find all async functions\"' → executes ast script with --query flag", "deleted": false, "createdAt": "2025-11-10T06:14:58.878Z" }, { "id": 13, "text": "Run 'fspec research --tool=ast --file src/index.ts' → executes ast script with --file flag", "deleted": false, "createdAt": "2025-11-10T06:15:04.309Z" }, { "id": 14, "text": "ARCHITECTURE: spec/research-tools/ast.ts exports { execute(args) => Promise<string> } interface, fspec dynamically imports and calls execute()", "deleted": false, "createdAt": "2025-11-10T06:19:57.917Z" } ], "nextExampleId": 15, "questions": [ { "id": 0, "text": "@human: Should research tool configs stay in ~/.fspec/fspec-config.json or move to project spec/fspec-config.json?", "deleted": false, "createdAt": "2025-11-08T07:00:02.351Z", "selected": true, "answer": "~/.fspec/fspec-config.json (user-level config)" }, { "id": 1, "text": "@human: Which environment variables should be supported? (e.g., PERPLEXITY_API_KEY, JIRA_TOKEN, CONFLUENCE_TOKEN, etc.)", "deleted": false, "createdAt": "2025-11-08T07:00:04.026Z", "selected": true, "answer": "No environment variables for API keys - use config file only" }, { "id": 2, "text": "@human: For rule/example extraction from research: AI auto-parse or AI suggest + human approve?", "deleted": false, "createdAt": "2025-11-08T07:00:06.154Z", "selected": true, "answer": "AI auto-parse research findings but ask user for clarification when uncertain (Example Mapping approach)" }, { "id": 3, "text": "@human: Config wizard: Interactive prompts (y/n questions) or command-line flags (--api-key=...)", "deleted": false, "createdAt": "2025-11-08T07:00:07.681Z", "selected": true, "answer": "Three configuration methods: 1) CLI flags (--api-key=...), 2) Interactive wizard (detect TTY), 3) TUI config view (in main fspec TUI)" }, { "id": 4, "text": "@human: Should system proactively suggest which research tool to use based on question type?", "deleted": false, "createdAt": "2025-11-08T07:00:09.156Z", "selected": true, "answer": "Yes, but use feedback loop pattern like 'fspec reverse' - emit system-reminder with tool suggestions, let AI analyze and choose, no hardcoded semantic analysis" }, { "id": 5, "text": "@human: AST production mode - are there technical blockers or just not implemented yet?", "deleted": false, "createdAt": "2025-11-08T07:00:10.776Z", "selected": true, "answer": "AST tool help/interface exists but production implementation blocked - needs actual AST parsing logic implemented and tested (currently only works with FSPEC_TEST_MODE=1)" }, { "id": 6, "text": "@human: Should research tools be integrated TypeScript commands within fspec (like 'fspec research ast --query') instead of separate bash scripts?", "deleted": false, "createdAt": "2025-11-10T06:16:27.253Z", "selected": true, "answer": "YES! Research tools MUST be platform-agnostic TypeScript modules (not bash scripts). Use tsx/ts-node to execute .ts files in spec/research-scripts/, or bundle them with fspec. Tools must work on Windows, macOS, Linux without modification." } ], "nextQuestionId": 7, "assumptions": [ "~/.fspec/fspec-config.json (user-level config)" ], "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-10T08:20:25.900Z", "blockedBy": [ "RES-015" ] }, "RES-010": { "id": "RES-010", "title": "Tool Discovery and Status Display", "type": "story", "status": "done", "createdAt": "2025-11-08T07:15:35.103Z", "updatedAt": "2025-11-09T00:10:36.326Z", "description": "Improve research tool listing to show configuration status, descriptions, and usage guidance at a glance", "epic": "research-tool-experience", "children": [], "dependsOn": [ "RES-012" ], "relatesTo": [ "RES-011" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T22:59:01.966Z" }, { "state": "testing", "timestamp": "2025-11-08T23:12:54.950Z" }, { "state": "implementing", "timestamp": "2025-11-08T23:15:07.185Z" }, { "state": "validating", "timestamp": "2025-11-09T00:10:00.406Z" }, { "state": "done", "timestamp": "2025-11-09T00:10:36.327Z" } ], "userStory": { "role": "developer using research tools", "action": "see configuration status and usage guidance for all available tools", "benefit": "I can quickly understand which tools are ready to use and how to configure them" }, "rules": [ { "id": 0, "text": "Tool listing command must show all registered research tools with their names and descriptions", "deleted": false, "createdAt": "2025-11-08T22:59:24.796Z" }, { "id": 1, "text": "Each tool must display configuration status: CONFIGURED (ready), NOT CONFIGURED (missing required config), or PARTIALLY CONFIGURED (some optional config missing)", "deleted": false, "createdAt": "2025-11-08T22:59:31.099Z" }, { "id": 2, "text": "Configuration status must use the config resolution system from RES-012 to check all config sources (ENV, User, Project, Defaults)", "deleted": false, "createdAt": "2025-11-08T22:59:37.406Z" }, { "id": 3, "text": "Tool listing must show which configuration source is being used for configured tools (ENV, USER, PROJECT, DEFAULT)", "deleted": false, "createdAt": "2025-11-08T22:59:42.559Z" }, { "id": 4, "text": "For unconfigured tools, output must show usage guidance with configuration command examples", "deleted": false, "createdAt": "2025-11-08T22:59:48.240Z" }, { "id": 5, "text": "Tool listing output must be AI-agent friendly (structured, clear status indicators, machine-parseable)", "deleted": false, "createdAt": "2025-11-08T22:59:53.488Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "User runs 'fspec research' and sees Perplexity tool with status CONFIGURED (source: ENV) because PERPLEXITY_API_KEY is set", "deleted": false, "createdAt": "2025-11-08T23:00:04.898Z" }, { "id": 1, "text": "User runs 'fspec research' and sees Jira tool with status NOT CONFIGURED along with command example: export JIRA_URL=... JIRA_TOKEN=...", "deleted": false, "createdAt": "2025-11-08T23:00:10.312Z" }, { "id": 2, "text": "User runs 'fspec research' and sees Confluence tool with status CONFIGURED (source: USER) showing config from ~/.fspec/fspec-config.json", "deleted": false, "createdAt": "2025-11-08T23:00:15.775Z" }, { "id": 3, "text": "User runs 'fspec research' and sees all tools listed with descriptions, status indicators (✓ or ✗), and config sources", "deleted": false, "createdAt": "2025-11-08T23:00:21.393Z" }, { "id": 4, "text": "User runs 'fspec research --tool=perplexity --help' and sees tool-specific help with configuration requirements and usage examples", "deleted": false, "createdAt": "2025-11-08T23:00:27.312Z" } ], "nextExampleId": 5, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-09T00:10:36.326Z" }, "RES-011": { "id": "RES-011", "title": "Tool-Specific Help System", "type": "story", "status": "done", "createdAt": "2025-11-08T07:15:45.799Z", "updatedAt": "2025-11-08T07:59:52.602Z", "description": "Forward --help flag to actual research tool scripts for tool-specific documentation instead of generic help", "epic": "research-tool-experience", "children": [], "relatesTo": [ "RES-010" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T07:36:40.575Z" }, { "state": "testing", "timestamp": "2025-11-08T07:40:26.824Z" }, { "state": "implementing", "timestamp": "2025-11-08T07:42:04.889Z" }, { "state": "validating", "timestamp": "2025-11-08T07:54:46.320Z" }, { "state": "done", "timestamp": "2025-11-08T07:59:52.602Z" } ], "userStory": { "role": "AI agent or developer using fspec research tools", "action": "get tool-specific help documentation when running --help flag", "benefit": "I can learn tool options without reading source code or generic help" }, "rules": [ { "id": 0, "text": "When --help flag is used with --tool specified, forward --help to the tool script", "deleted": false, "createdAt": "2025-11-08T07:36:59.974Z" }, { "id": 1, "text": "When --help flag is used without --tool, show generic research help", "deleted": false, "createdAt": "2025-11-08T07:37:01.450Z" }, { "id": 2, "text": "When tool does not exist, show error with available tools list", "deleted": false, "createdAt": "2025-11-08T07:37:03.260Z" }, { "id": 3, "text": "All research tool scripts must implement --help flag with standardized format", "deleted": false, "createdAt": "2025-11-08T07:37:04.754Z" }, { "id": 4, "text": "Tool help must include: usage, options, examples, configuration, exit codes", "deleted": false, "createdAt": "2025-11-08T07:37:06.259Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Run 'fspec research --help' → shows generic research help with list of available tools", "deleted": false, "createdAt": "2025-11-08T07:37:15.415Z" }, { "id": 1, "text": "Run 'fspec research --tool=perplexity --help' → shows Perplexity-specific help (query, model, format options)", "deleted": false, "createdAt": "2025-11-08T07:37:17.878Z" }, { "id": 2, "text": "Run 'fspec research --tool=nonexistent --help' → error: tool not found, shows available tools", "deleted": false, "createdAt": "2025-11-08T07:37:19.493Z" }, { "id": 3, "text": "Tool script without --help implementation → warning message with fallback to file location", "deleted": false, "createdAt": "2025-11-08T07:37:21.182Z" } ], "nextExampleId": 4, "estimate": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-08T07:59:52.602Z" }, "RES-012": { "id": "RES-012", "title": "Configuration Management with TUI Integration", "type": "story", "status": "done", "createdAt": "2025-11-08T07:15:47.493Z", "updatedAt": "2025-11-08T11:24:06.945Z", "description": "Build comprehensive config system with wizard, validation, env var support, and dedicated TUI view for managing research tool settings", "epic": "research-tool-experience", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-08T09:08:59.450Z" }, { "state": "testing", "timestamp": "2025-11-08T11:12:56.102Z" }, { "state": "implementing", "timestamp": "2025-11-08T11:14:58.560Z" }, { "state": "validating", "timestamp": "2025-11-08T11:18:25.627Z" }, { "state": "done", "timestamp": "2025-11-08T11:24:06.946Z" } ], "userStory": { "role": "developer using research tools", "action": "configure and validate research tool settings without manual file editing", "benefit": "I can quickly set up tools with confidence and see configuration status at a glance" }, "rules": [ { "id": 0, "text": "Configuration sources are checked in priority order: ENV vars → User config (~/.fspec/fspec-config.json) → Project config (spec/fspec-config.json) → Defaults", "deleted": false, "createdAt": "2025-11-08T10:59:54.392Z" }, { "id": 1, "text": "Environment variables take precedence over all config files (e.g., PERPLEXITY_API_KEY overrides config file settings)", "deleted": false, "createdAt": "2025-11-08T11:00:00.232Z" }, { "id": 2, "text": "User-level config (~/.fspec/fspec-config.json) stores personal API keys and is never version controlled", "deleted": false, "createdAt": "2025-11-08T11:00:05.929Z" }, { "id": 3, "text": "Project-level config (spec/fspec-config.json) stores team defaults and URLs but no secrets (can be version controlled)", "deleted": false, "createdAt": "2025-11-08T11:00:11.695Z" }, { "id": 4, "text": "Config validation must check for required fields before tool execution", "deleted": false, "createdAt": "2025-11-08T11:00:17.097Z" }, { "id": 5, "text": ".env file support must load environment variables from project root .env file if it exists", "deleted": false, "createdAt": "2025-11-08T11:00:22.396Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "Perplexity API key set via PERPLEXITY_API_KEY env var overrides user config file setting", "deleted": false, "createdAt": "2025-11-08T11:00:28.437Z" }, { "id": 1, "text": "Jira URL in project config (spec/fspec-config.json) is used when JIRA_URL env var is not set and user config doesn't exist", "deleted": false, "createdAt": "2025-11-08T11:00:34.902Z" }, { "id": 2, "text": ".env file in project root loads PERPLEXITY_API_KEY=pplx-abc123 which then takes precedence over config files", "deleted": false, "createdAt": "2025-11-08T11:00:40.639Z" }, { "id": 3, "text": "Validation detects missing CONFLUENCE_TOKEN before tool execution and shows clear error message", "deleted": false, "createdAt": "2025-11-08T11:00:46.342Z" }, { "id": 4, "text": "Default Perplexity model 'sonar' is used when no PERPLEXITY_MODEL env var or config file setting exists", "deleted": false, "createdAt": "2025-11-08T11:00:52.164Z" } ], "nextExampleId": 5, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-08T11:24:06.945Z" }, "RES-013": { "id": "RES-013", "title": "Smart Research Integration and Auto-Attachment", "type": "story", "status": "done", "createdAt": "2025-11-08T07:15:49.704Z", "updatedAt": "2025-11-09T00:46:14.964Z", "description": "Automatically prompt to save research results as attachments and extract rules/examples with AI assistance", "epic": "research-tool-experience", "children": [], "dependsOn": [ "RES-010", "RES-012" ], "relatesTo": [ "RES-014" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-09T00:24:59.088Z" }, { "state": "testing", "timestamp": "2025-11-09T00:36:32.795Z" }, { "state": "implementing", "timestamp": "2025-11-09T00:40:00.690Z" }, { "state": "validating", "timestamp": "2025-11-09T00:42:03.869Z" }, { "state": "done", "timestamp": "2025-11-09T00:46:14.965Z" } ], "userStory": { "role": "developer using research tools during Example Mapping", "action": "automatically save research results as attachments and extract rules/examples with AI assistance", "benefit": "I can quickly capture research findings and convert them into actionable specification artifacts" }, "rules": [ { "id": 0, "text": "After running a research tool, system must prompt user to save results as attachment to current work unit", "deleted": false, "createdAt": "2025-11-09T00:25:25.011Z" }, { "id": 1, "text": "AI assistant must analyze research output and suggest extractable business rules, examples, and questions", "deleted": false, "createdAt": "2025-11-09T00:25:35.051Z" }, { "id": 2, "text": "User must be able to accept/reject/edit AI-suggested rules and examples before adding to Example Map", "deleted": false, "createdAt": "2025-11-09T00:25:35.715Z" }, { "id": 3, "text": "Saved attachments must be stored in spec/attachments/<work-unit-id>/ directory", "deleted": false, "createdAt": "2025-11-09T00:25:36.337Z" }, { "id": 4, "text": "Research output must be saved as both raw format and AI-extracted structured format", "deleted": false, "createdAt": "2025-11-09T00:25:36.974Z" }, { "id": 5, "text": "System must support --auto-attach flag to skip prompt and auto-save research results", "deleted": false, "createdAt": "2025-11-09T00:25:37.606Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=perplexity --query=\"OAuth best practices\" --work-unit=AUTH-001' and after receiving results, system prompts: 'Save research results as attachment? (y/n)'", "deleted": false, "createdAt": "2025-11-09T00:25:55.266Z" }, { "id": 1, "text": "User saves research results, AI analyzes output and suggests: 'Found 3 rules, 5 examples. Add to AUTH-001? (y/n/edit)'", "deleted": false, "createdAt": "2025-11-09T00:25:55.886Z" }, { "id": 2, "text": "User accepts AI suggestions, system adds rules/examples to AUTH-001 Example Map and saves raw output to spec/attachments/AUTH-001/perplexity-oauth-research.md", "deleted": false, "createdAt": "2025-11-09T00:25:56.529Z" }, { "id": 3, "text": "User runs 'fspec research --tool=ast --query=\"authentication patterns\" --work-unit=AUTH-001 --auto-attach' and results are automatically saved without prompts", "deleted": false, "createdAt": "2025-11-09T00:25:57.141Z" }, { "id": 4, "text": "AI extracts rule 'JWT tokens must expire within 24 hours' from research output and adds it to Example Map after user confirmation", "deleted": false, "createdAt": "2025-11-09T00:25:57.757Z" } ], "nextExampleId": 5, "estimate": 8, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-09T00:46:14.964Z" }, "RES-014": { "id": "RES-014", "title": "Language-Agnostic AST Tool for AI Analysis", "type": "story", "status": "done", "createdAt": "2025-11-08T07:15:51.252Z", "updatedAt": "2025-11-10T01:04:40.318Z", "description": "Implement production-ready AST tool using tree-sitter for language-agnostic codebase analysis and pattern detection", "epic": "research-tool-experience", "children": [], "dependsOn": [ "RES-012" ], "relatesTo": [ "RES-013" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-09T06:00:33.341Z" }, { "state": "testing", "timestamp": "2025-11-09T06:04:35.595Z" }, { "state": "implementing", "timestamp": "2025-11-09T22:41:34.133Z" }, { "state": "validating", "timestamp": "2025-11-09T22:45:34.434Z" }, { "state": "done", "timestamp": "2025-11-10T01:04:40.318Z" } ], "userStory": { "role": "developer using research tools", "action": "analyze code patterns across multiple programming languages", "benefit": "I can understand codebase structure without language-specific tools" }, "rules": [ { "id": 0, "text": "AST tool must use tree-sitter for language-agnostic parsing", "deleted": false, "createdAt": "2025-11-09T06:00:58.838Z" }, { "id": 1, "text": "Tool must support JavaScript, TypeScript, Python, Go, Rust, and Java", "deleted": false, "createdAt": "2025-11-09T06:01:00.656Z" }, { "id": 2, "text": "AST queries must support finding function definitions, class definitions, imports, and exports", "deleted": false, "createdAt": "2025-11-09T06:01:02.533Z" }, { "id": 3, "text": "Results must include file path, line number, and code snippet for each match", "deleted": false, "createdAt": "2025-11-09T06:01:04.251Z" }, { "id": 4, "text": "Tool must integrate with research command system (RES-010) using --tool=ast flag", "deleted": false, "createdAt": "2025-11-09T06:01:05.960Z" }, { "id": 5, "text": "AST results must be formatted for AI agent consumption with structured JSON output", "deleted": false, "createdAt": "2025-11-09T06:01:07.496Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=ast --query=\"function definitions\"' and sees list of all functions in codebase with file paths and line numbers", "deleted": false, "createdAt": "2025-11-09T06:01:21.638Z" }, { "id": 1, "text": "User queries 'class AuthService' and AST tool finds AuthService class definition in src/auth/service.ts:42-150", "deleted": false, "createdAt": "2025-11-09T06:01:23.495Z" }, { "id": 2, "text": "User searches for 'import statements' across TypeScript files and gets JSON output with import paths, line numbers, and imported symbols", "deleted": false, "createdAt": "2025-11-09T06:01:25.430Z" }, { "id": 3, "text": "AST tool parses Python file and finds all class definitions with their methods using tree-sitter Python grammar", "deleted": false, "createdAt": "2025-11-09T06:01:27.229Z" }, { "id": 4, "text": "User queries 'export default' pattern and AST finds all default exports across JavaScript and TypeScript files", "deleted": false, "createdAt": "2025-11-09T06:01:29.016Z" } ], "nextExampleId": 5, "estimate": 8, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-10T01:04:40.318Z" }, "RES-015": { "id": "RES-015", "title": "Convert Research Tools to TypeScript Plugin System", "type": "story", "status": "done", "createdAt": "2025-11-10T06:21:08.581Z", "updatedAt": "2025-11-10T06:59:09.637Z", "description": "Replace bash scripts with platform-agnostic TypeScript modules. Implement hybrid architecture: core tools bundled with fspec, optional custom tools loaded dynamically from spec/research-tools/", "epic": "research-tools", "children": [], "userStory": { "role": "developer using fspec on any platform (Windows/macOS/Linux)", "action": "use research tools without bash dependency", "benefit": "research tools work cross-platform and integrate seamlessly with fspec's TypeScript ecosystem" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-10T06:21:34.853Z" }, { "state": "testing", "timestamp": "2025-11-10T06:37:57.584Z" }, { "state": "implementing", "timestamp": "2025-11-10T06:39:22.610Z" }, { "state": "validating", "timestamp": "2025-11-10T06:56:15.247Z" }, { "state": "done", "timestamp": "2025-11-10T06:59:09.637Z" } ], "rules": [ { "id": 0, "text": "ARCHITECTURE: Hybrid plugin system - core tools (ast, perplexity, jira, confluence, stakeholder) bundled with fspec, custom tools loaded dynamically from spec/research-tools/", "deleted": false, "createdAt": "2025-11-10T06:21:42.140Z" }, { "id": 1, "text": "INTERFACE: Standard TypeScript interface - export interface ResearchTool { name, description, execute(args), help() }", "deleted": false, "createdAt": "2025-11-10T06:21:49.139Z" }, { "id": 2, "text": "DISCOVERY: Tool registry merges bundled tools (import) + dynamic tools (dynamic import from spec/research-tools/*.ts)", "deleted": false, "createdAt": "2025-11-10T06:21:56.595Z" }, { "id": 3, "text": "ARGS: Use Commander.js .allowUnknownOption() to forward ALL args to tool.execute() - tools parse their own arguments", "deleted": false, "createdAt": "2025-11-10T06:22:04.671Z" }, { "id": 4, "text": "MIGRATION: Convert existing bash scripts to TypeScript - ast.ts, perplexity.ts, jira.ts, confluence.ts, stakeholder.ts in src/research-tools/", "deleted": false, "createdAt": "2025-11-10T06:22:12.777Z" }, { "id": 5, "text": "TESTING: Tools are testable TypeScript modules - unit tests verify execute() logic, integration tests verify fspec loads and runs tools correctly", "deleted": false, "createdAt": "2025-11-10T06:22:20.756Z" }, { "id": 6, "text": "CONFIG: Each tool handles its own config resolution via resolveConfig(toolName) from config-resolution.ts - tools check required fields and throw clear errors", "deleted": false, "createdAt": "2025-11-10T06:22:28.518Z" }, { "id": 7, "text": "Custom tools must be .js files. Provide 'fspec build-tool <name>' command that uses esbuild (already a dependency) to transpile spec/research-tools/<name>.ts → spec/research-tools/<name>.js. Users write TypeScript, run build command, fspec loads .js.", "deleted": false, "createdAt": "2025-11-10T06:29:05.644Z" }, { "id": 8, "text": "Wrap tool errors in <system-reminder> tags for AI visibility. When tool.execute() throws, catch and wrap stderr/error message in system-reminder block so AI agents can see and self-correct. Example: <system-reminder>RESEARCH TOOL ERROR\\n\\nTool: ast\\nError: {message}\\n</system-reminder>", "deleted": false, "createdAt": "2025-11-10T06:31:56.161Z" } ], "nextRuleId": 9, "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=ast --query \"find async functions\"' → fspec loads bundled ast.ts → calls ast.execute({ query: 'find async functions' }) → returns JSON output", "deleted": false, "createdAt": "2025-11-10T06:22:37.972Z" }, { "id": 1, "text": "User creates spec/research-tools/custom.ts with ResearchTool interface → runs 'fspec research --tool=custom --arg=value' → fspec dynamically imports custom.ts → executes tool", "deleted": false, "createdAt": "2025-11-10T06:22:46.762Z" }, { "id": 2, "text": "User runs 'fspec research --tool=perplexity --help' → fspec loads perplexity.ts → calls perplexity.help() → displays tool-specific help with options", "deleted": false, "createdAt": "2025-11-10T06:22:55.163Z" } ], "nextExampleId": 3, "questions": [ { "id": 0, "text": "@human: Should custom tools in spec/research-tools/ be transpiled on-the-fly (tsx/ts-node) or pre-compiled by user?", "deleted": false, "createdAt": "2025-11-10T06:23:02.532Z", "selected": true, "answer": "Custom tools must be .js files. Provide 'fspec build-tool <name>' command that uses esbuild (already a dependency) to transpile spec/research-tools/<name>.ts → spec/research-tools/<name>.js. Users write TypeScript, run build command, fspec loads .js." }, { "id": 1, "text": "@human: Should tool registry cache loaded tools or reload on every invocation?", "deleted": false, "createdAt": "2025-11-10T06:23:10.349Z", "selected": true, "answer": "No explicit caching - rely on Node.js module cache. Each CLI invocation is a new process, so caching between invocations is irrelevant. Within a single invocation, Node.js automatically caches dynamic imports. Keep it simple." }, { "id": 2, "text": "@human: When tool.execute() throws error, should fspec wrap it in system-reminder for AI visibility or pass through raw?", "deleted": false, "createdAt": "2025-11-10T06:23:18.800Z", "selected": true, "answer": "Wrap tool errors in <system-reminder> tags for AI visibility. When tool.execute() throws, catch and wrap stderr/error message in system-reminder block so AI agents can see and self-correct. Example: <system-reminder>RESEARCH TOOL ERROR\\n\\nTool: ast\\nError: {message}\\n</system-reminder>" } ], "nextQuestionId": 3, "assumptions": [ "No explicit caching - rely on Node.js module cache. Each CLI invocation is a new process, so caching between invocations is irrelevant. Within a single invocation, Node.js automatically caches dynamic imports. Keep it simple." ], "blocks": [ "RES-009" ], "estimate": 8, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-10T06:59:09.637Z" }, "HOOK-012": { "id": "HOOK-012", "title": "Virtual hooks don't execute during status transitions", "type": "bug", "status": "done", "createdAt": "2025-11-10T07:36:39.959Z", "updatedAt": "2025-11-10T08:11:01.835Z", "description": "Virtual hooks are stored in work-units.json but never actually execute. The update-work-unit-status command doesn't call executeVirtualHooks at all. Need to integrate execa library to execute hooks before/after status transitions.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-10T07:38:47.921Z" }, { "state": "testing", "timestamp": "2025-11-10T07:42:35.178Z" }, { "state": "implementing", "timestamp": "2025-11-10T07:43:41.936Z" }, { "state": "validating", "timestamp": "2025-11-10T07:52:30.025Z" }, { "state": "done", "timestamp": "2025-11-10T08:11:01.835Z" } ], "rules": [ { "id": 0, "text": "Virtual hooks MUST execute during status transitions using execa library", "deleted": false, "createdAt": "2025-11-10T07:39:00.772Z" }, { "id": 1, "text": "update-work-unit-status command MUST call executeVirtualHooks before status change", "deleted": false, "createdAt": "2025-11-10T07:39:02.735Z" }, { "id": 2, "text": "Blocking hook failures MUST prevent status transitions and wrap errors in <system-reminder> tags", "deleted": false, "createdAt": "2025-11-10T07:39:04.685Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Work unit has blocking virtual hook 'exit 1' at pre-validating. When moving to validating, hook executes and fails with exit code 1. Transition is blocked and stderr contains <system-reminder>BLOCKING HOOK FAILURE</system-reminder>.", "deleted": false, "createdAt": "2025-11-10T07:39:06.432Z" }, { "id": 1, "text": "Work unit has passing hook 'echo success' at pre-validating. When moving to validating, hook executes successfully with exit code 0. Transition proceeds and status becomes validating.", "deleted": false, "createdAt": "2025-11-10T07:39:08.040Z" } ], "nextExampleId": 2, "userStory": { "role": "AI agent using fspec workflow", "action": "have virtual hooks execute during status transitions", "benefit": "I can enforce quality gates and blocking checks for specific work units" }, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-10T08:11:01.835Z" }, "RES-016": { "id": "RES-016", "title": "AST tool returns stub instead of actual parsing", "type": "bug", "status": "done", "createdAt": "2025-11-10T08:22:44.023Z", "updatedAt": "2025-11-10T08:26:28.305Z", "description": "AST research tool shows 'stub-implementation' message instead of performing actual AST analysis using tree-sitter. Need to investigate if implementation exists but isn't connected, or if it was never completed.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-10T08:23:11.190Z" }, { "state": "testing", "timestamp": "2025-11-10T08:23:58.812Z" }, { "state": "implementing", "timestamp": "2025-11-10T08:24:38.260Z" }, { "state": "validating", "timestamp": "2025-11-10T08:26:26.601Z" }, { "state": "done", "timestamp": "2025-11-10T08:26:28.306Z" } ], "rules": [ { "id": 0, "text": "AST parser implementation EXISTS in src/utils/ast-parser.ts with full tree-sitter support (JavaScript, TypeScript, Python, Go)", "deleted": false, "createdAt": "2025-11-10T08:23:22.125Z" }, { "id": 1, "text": "src/research-tools/ast.ts returns stub instead of calling parseFile() from ast-parser.ts", "deleted": false, "createdAt": "2025-11-10T08:23:22.779Z" }, { "id": 2, "text": "Fix: Import parseFile from ../utils/ast-parser and call it instead of returning stub JSON", "deleted": false, "createdAt": "2025-11-10T08:23:23.413Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "BEFORE: fspec research --tool=ast --query 'find async functions' → Returns stub JSON", "deleted": false, "createdAt": "2025-11-10T08:23:24.047Z" }, { "id": 1, "text": "AFTER: fspec research --tool=ast --query 'find async functions' → Returns actual AST matches using tree-sitter", "deleted": false, "createdAt": "2025-11-10T08:23:24.685Z" } ], "nextExampleId": 2, "userStory": { "role": "AI agent using fspec", "action": "use AST research tool to analyze code", "benefit": "I can find patterns and analyze code structure during Example Mapping" }, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-10T08:26:28.305Z" }, "BUG-074": { "id": "BUG-074", "title": "Fix 'fspec research --tool=ast --help' command - should display tool-specific help instead of failing", "type": "bug", "status": "done", "createdAt": "2025-11-10T12:38:37.177Z", "updatedAt": "2025-11-11T22:43:25.918Z", "description": "When running 'fspec research --tool=ast --help', the command fails with 'Error: Research tool 'ast' not found'. However, running 'fspec research --tool=ast --query \"find X\"' works correctly. The --help flag should work for individual research tools to show tool-specific usage and options.", "children": [], "attachments": [ "spec/attachments/BUG-074/help-system-architecture-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-11T21:58:27.174Z" }, { "state": "testing", "timestamp": "2025-11-11T22:10:07.053Z" }, { "state": "implementing", "timestamp": "2025-11-11T22:13:07.666Z" }, { "state": "validating", "timestamp": "2025-11-11T22:36:56.605Z" }, { "state": "done", "timestamp": "2025-11-11T22:43:25.918Z" } ], "userStory": { "role": "AI agent or developer using fspec research tools", "action": "get help for a specific research tool using --help flag", "benefit": "I can understand tool usage without trial-and-error or reading source code" }, "rules": [ { "id": 0, "text": "Help display must work for both bundled tools (src/research-tools/) and custom tools (spec/research-tools/)", "deleted": false, "createdAt": "2025-11-11T22:04:03.358Z" }, { "id": 1, "text": "Help output must follow standardized format with AI-optimized sections (WHEN TO USE, PREREQUISITES, COMMON ERRORS)", "deleted": false, "createdAt": "2025-11-11T22:04:05.440Z" }, { "id": 2, "text": "All research tools must use structured ResearchToolHelpConfig instead of hand-crafted strings", "deleted": false, "createdAt": "2025-11-11T22:04:07.150Z" }, { "id": 3, "text": "Help formatting logic must be centralized in help-formatter.ts to avoid duplication", "deleted": false, "createdAt": "2025-11-11T22:04:10.449Z" }, { "id": 4, "text": "The help flag must be checked BEFORE tool validation to show help even if tool has loading issues", "deleted": false, "createdAt": "2025-11-11T22:04:17.793Z" }, { "id": 5, "text": "Help formatter must support custom sections beyond standard ones for advanced documentation", "deleted": false, "createdAt": "2025-11-11T22:07:14.931Z" }, { "id": 6, "text": "TypeScript compiler provides validation for ResearchToolHelpConfig - no runtime JSON Schema validation needed", "deleted": false, "createdAt": "2025-11-11T22:07:16.546Z" }, { "id": 7, "text": "CONFIGURATION section is optional and shown only when tool provides it in config", "deleted": false, "createdAt": "2025-11-11T22:07:18.093Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=ast --help' and sees structured help with USAGE, OPTIONS, EXAMPLES, WHEN TO USE sections", "deleted": false, "createdAt": "2025-11-11T22:04:29.414Z" }, { "id": 1, "text": "User runs 'fspec research --tool=jira --help' and sees help with CONFIGURATION section showing required credentials", "deleted": false, "createdAt": "2025-11-11T22:04:30.915Z" }, { "id": 2, "text": "User runs 'fspec research --tool=custom --help' where custom is in spec/research-tools/ and sees same formatted help as bundled tools", "deleted": false, "createdAt": "2025-11-11T22:04:32.751Z" }, { "id": 3, "text": "User runs 'fspec research --tool=nonexistent --help' and sees error with list of available tools", "deleted": false, "createdAt": "2025-11-11T22:04:34.379Z" }, { "id": 4, "text": "Developer refactors ast.ts help from string-based help() method to structured getHelpConfig() returning ResearchToolHelpConfig", "deleted": false, "createdAt": "2025-11-11T22:04:36.105Z" } ], "nextExampleId": 5, "questions": [ { "id": 0, "text": "@human: Should the help formatter support custom sections beyond the standard ones (USAGE, OPTIONS, EXAMPLES, etc.)?", "deleted": false, "createdAt": "2025-11-11T22:04:46.576Z", "selected": true, "answer": "Yes, support custom sections for tools that need ADVANCED USAGE or TROUBLESHOOTING sections" }, { "id": 1, "text": "@human: Should we validate ResearchToolHelpConfig with JSON Schema to enforce required fields?", "deleted": false, "createdAt": "2025-11-11T22:04:48.419Z", "selected": true, "answer": "No, rely on TypeScript only for compile-time validation - simpler approach" }, { "id": 2, "text": "@human: Should the CONFIGURATION section be optional or required for tools that need config files?", "deleted": false, "createdAt": "2025-11-11T22:04:50.612Z", "selected": true, "answer": "Optional - CONFIGURATION section shown only when tool provides it in getHelpConfig()" } ], "nextQuestionId": 3, "estimate": 8, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-11T22:43:25.918Z" }, "COV-054": { "id": "COV-054", "title": "Coverage enforcement gap: 21.3% of features bypass validation", "type": "bug", "status": "done", "createdAt": "2025-11-11T01:21:20.107Z", "updatedAt": "2025-11-11T23:58:10.691Z", "description": "Coverage validation only runs if linkedFeatures is populated, but @TAGs don't auto-populate this array. Developers forget to run 'fspec link-feature', resulting in 62/291 (21.3%) empty coverage files for done work units.", "children": [], "attachments": [ "spec/attachments/COV-054/coverage-enforcement-gap-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-11T23:46:19.413Z" }, { "state": "testing", "timestamp": "2025-11-11T23:49:25.381Z" }, { "state": "implementing", "timestamp": "2025-11-11T23:54:09.124Z" }, { "state": "validating", "timestamp": "2025-11-11T23:54:42.919Z" }, { "state": "done", "timestamp": "2025-11-11T23:58:10.691Z" } ], "userStory": { "role": "developer using fspec", "action": "have coverage validation automatically detect features tagged with work unit IDs", "benefit": "I don't need to manually run link-feature commands and coverage validation never gets skipped" }, "rules": [ { "id": 0, "text": "Coverage validation must auto-discover feature files tagged with @WORK-UNIT-ID when linkedFeatures array is empty", "deleted": false, "createdAt": "2025-11-11T23:46:45.117Z" }, { "id": 1, "text": "Auto-discovery must scan all feature files in spec/features directory", "deleted": false, "createdAt": "2025-11-11T23:46:53.729Z" }, { "id": 2, "text": "Auto-discovery must use extractWorkUnitTags() utility from src/utils/work-unit-tags.ts", "deleted": false, "createdAt": "2025-11-11T23:46:54.287Z" }, { "id": 3, "text": "If both linkedFeatures array AND @TAG exist, linkedFeatures takes precedence (explicit override)", "deleted": false, "createdAt": "2025-11-11T23:46:54.855Z" }, { "id": 4, "text": "Coverage validation must run for ALL scenarios in auto-discovered features", "deleted": false, "createdAt": "2025-11-11T23:46:55.418Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Work unit AUTH-001 has linkedFeatures: null but feature file has @AUTH-001 tag → Auto-discovery finds user-authentication.feature → Coverage validation runs", "deleted": false, "createdAt": "2025-11-11T23:47:01.795Z" }, { "id": 1, "text": "Work unit with both linkedFeatures: ['custom-name'] AND @TAG in feature file → Use linkedFeatures (explicit wins over auto-discovery)", "deleted": false, "createdAt": "2025-11-11T23:47:10.952Z" }, { "id": 2, "text": "Work unit TASK-001 (type=task) has no @TAG and no linkedFeatures → Allow progression with warning (tasks exempt)", "deleted": false, "createdAt": "2025-11-11T23:47:11.518Z" }, { "id": 3, "text": "Work unit BUG-042 has @BUG-042 tag in feature file but 0% coverage → Block progression with coverage error", "deleted": false, "createdAt": "2025-11-11T23:47:12.079Z" } ], "nextExampleId": 4, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-11T23:58:10.691Z" }, "RES-017": { "id": "RES-017", "title": "Refactor AST tool to use deterministic tree-sitter queries instead of semantic natural language parsing", "type": "story", "status": "done", "createdAt": "2025-11-12T00:32:11.601Z", "updatedAt": "2025-11-12T01:48:00.274Z", "description": "Replace semantic natural language query parsing (e.g., 'find all functions') with deterministic tree-sitter query operations (e.g., --operation=list-functions). Expose all tree-sitter capabilities through explicit command-line flags and predefined query files.", "epic": "research-tools", "children": [], "attachments": [ "spec/attachments/RES-017/ast-tool-refactoring-research.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T00:50:15.437Z" }, { "state": "testing", "timestamp": "2025-11-12T01:31:07.035Z" }, { "state": "specifying", "timestamp": "2025-11-12T01:31:47.613Z" }, { "state": "testing", "timestamp": "2025-11-12T01:32:39.665Z" }, { "state": "implementing", "timestamp": "2025-11-12T01:34:46.770Z" }, { "state": "validating", "timestamp": "2025-11-12T01:44:10.301Z" }, { "state": "done", "timestamp": "2025-11-12T01:48:00.275Z" } ], "rules": [ { "id": 0, "text": "AST tool MUST NOT use semantic natural language parsing (e.g., queryLower.includes('find all'))", "deleted": false, "createdAt": "2025-11-12T00:50:27.863Z" }, { "id": 1, "text": "All AST operations MUST use deterministic tree-sitter query language (S-expressions)", "deleted": false, "createdAt": "2025-11-12T00:50:32.520Z" }, { "id": 2, "text": "CLI MUST use --operation flag instead of --query for predefined operations", "deleted": false, "createdAt": "2025-11-12T00:51:54.776Z" }, { "id": 3, "text": "Query library MUST be organized by language (javascript/, typescript/, python/, go/, rust/)", "deleted": false, "createdAt": "2025-11-12T00:52:00.236Z" }, { "id": 4, "text": "Each operation MUST map to a predefined tree-sitter S-expression query stored in .scm files", "deleted": false, "createdAt": "2025-11-12T00:52:05.798Z" }, { "id": 5, "text": "Power users MUST be able to provide custom queries via --query-file flag pointing to .scm files", "deleted": false, "createdAt": "2025-11-12T00:52:11.776Z" }, { "id": 6, "text": "File flag MUST be required for all AST operations (no implicit glob search)", "deleted": false, "createdAt": "2025-11-12T00:52:27.298Z" }, { "id": 7, "text": "Operations MUST support parametric predicates (e.g., min-params, pattern, name filters)", "deleted": false, "createdAt": "2025-11-12T00:52:32.585Z" }, { "id": 8, "text": "Structural operations MUST include: list-functions, list-classes, list-imports, list-exports, find-class, find-function", "deleted": false, "createdAt": "2025-11-12T00:52:38.642Z" } ], "nextRuleId": 9, "examples": [ { "id": 0, "text": "User runs: fspec research --tool=ast --operation=list-functions --file=src/auth.ts, receives JSON with all function declarations, expressions, and arrow functions", "deleted": false, "createdAt": "2025-11-12T00:52:45.875Z" }, { "id": 1, "text": "User runs: fspec research --tool=ast --operation=find-class --name=AuthController --file=src/auth.ts, receives class definition with line numbers", "deleted": false, "createdAt": "2025-11-12T00:52:51.660Z" }, { "id": 2, "text": "User runs: fspec research --tool=ast --operation=find-functions --min-params=5 --file=src/api.ts, receives functions with parameter count >= 5", "deleted": false, "createdAt": "2025-11-12T00:52:57.688Z" }, { "id": 3, "text": "Power user runs: fspec research --tool=ast --query-file=queries/custom-pattern.scm --file=src/utils.ts, executes custom tree-sitter query from .scm file", "deleted": false, "createdAt": "2025-11-12T00:53:04.885Z" }, { "id": 4, "text": "User runs: fspec research --tool=ast --operation=find-identifiers --pattern=\"^[A-Z][A-Z_]+\" --file=src/constants.ts, receives all CONSTANT_CASE identifiers", "deleted": false, "createdAt": "2025-11-12T00:53:10.952Z" }, { "id": 5, "text": "User runs: fspec research --tool=ast --operation=find-async-functions --file=src/api.ts, receives all async function declarations", "deleted": false, "createdAt": "2025-11-12T00:53:23.195Z" }, { "id": 6, "text": "User runs: fspec research --tool=ast --operation=find-exports --export-type=default --file=src/index.ts, receives default export statement", "deleted": false, "createdAt": "2025-11-12T00:53:27.967Z" } ], "nextExampleId": 7, "userStory": { "role": "developer using fspec for code analysis", "action": "use deterministic tree-sitter query operations instead of ambiguous natural language queries", "benefit": "I get predictable, composable AST analysis without language-dependent semantic parsing" }, "estimate": 8, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T01:48:00.274Z" }, "RES-018": { "id": "RES-018", "title": "Unconfigured research tool visibility and discovery", "type": "story", "status": "done", "createdAt": "2025-11-12T03:26:03.534Z", "updatedAt": "2025-11-12T05:45:29.649Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T03:27:20.923Z" }, { "state": "testing", "timestamp": "2025-11-12T05:35:31.705Z" }, { "state": "testing", "timestamp": "2025-11-12T05:39:29.887Z" }, { "state": "implementing", "timestamp": "2025-11-12T05:41:40.435Z" }, { "state": "validating", "timestamp": "2025-11-12T05:42:43.549Z" }, { "state": "done", "timestamp": "2025-11-12T05:45:29.650Z" } ], "userStory": { "role": "developer or AI agent using fspec research tools", "action": "discover available research tools even when not configured", "benefit": "I know what tools exist and can configure them when needed" }, "questions": [ { "id": 0, "text": "@human: Should 'fspec research' list only configured tools, all tools with visual distinction, or have a flag to show all?", "deleted": false, "createdAt": "2025-11-12T03:28:51.606Z", "selected": true, "answer": "Option B with enhancement: Show all tools with visual distinction in system-reminders for AI awareness. User-facing output shows configured tools by default, with --all flag to show unconfigured tools. This balances AI discoverability with clean user experience." }, { "id": 1, "text": "@human: When using an unconfigured tool, should it fail with setup instructions, offer alternative tool, have interactive setup, or different behavior for AI vs humans?", "deleted": false, "createdAt": "2025-11-12T04:44:44.644Z", "selected": true, "answer": "Option A: Fail fast with setup instructions. Show clear error message with step-by-step setup guide and suggest alternative configured tools. This is clear, non-interactive (good for AI agents), and educational." }, { "id": 2, "text": "@human: In system-reminders, should all tools be shown equally, or should configured tools be emphasized with unconfigured tools mentioned separately?", "deleted": false, "createdAt": "2025-11-12T04:45:51.588Z", "selected": true, "answer": "Option A: Always show all tools equally in system-reminders with accurate configuration information. Show config file paths (spec/fspec-config.json or ~/.fspec/fspec-config.json) and JSON structure, NOT environment variable examples." }, { "id": 3, "text": "@human: For checking if tools are configured, should we do full validation, quick key existence check, or hybrid approach?", "deleted": false, "createdAt": "2025-11-12T05:19:38.990Z", "selected": true, "answer": "Option A: Try to validate the full configuration. Use the existing loadConfig() and validation logic from each tool to accurately determine if it's configured. Accept the slight performance cost for accuracy." }, { "id": 4, "text": "@human: For setup guidance, show minimal hint, full JSON example inline, or reference setup command?", "deleted": false, "createdAt": "2025-11-12T05:25:57.993Z", "selected": true, "answer": "Option B: Show full JSON example inline. This is clear and immediately actionable - users can copy-paste the JSON structure directly into their config file. System-reminders can be more concise since AI agents can run --help commands." } ], "nextQuestionId": 5, "rules": [ { "id": 0, "text": "Option B with enhancement: Show all tools with visual distinction in system-reminders for AI awareness. User-facing output shows configured tools by default, with --all flag to show unconfigured tools. This balances AI discoverability with clean user experience.", "deleted": false, "createdAt": "2025-11-12T04:44:30.869Z" }, { "id": 1, "text": "Option A: Fail fast with setup instructions. Show clear error message with step-by-step setup guide and suggest alternative configured tools. This is clear, non-interactive (good for AI agents), and educational.", "deleted": false, "createdAt": "2025-11-12T04:45:38.381Z" }, { "id": 2, "text": "Option A: Always show all tools equally in system-reminders with accurate configuration information. Show config file paths (spec/fspec-config.json or ~/.fspec/fspec-config.json) and JSON structure, NOT environment variable examples.", "deleted": false, "createdAt": "2025-11-12T05:18:47.924Z" }, { "id": 3, "text": "Configuration uses JSON files at spec/fspec-config.json (project) or ~/.fspec/fspec-config.json (user), with structure: {\"research\": {\"toolName\": {config}}}", "deleted": false, "createdAt": "2025-11-12T05:18:58.021Z" }, { "id": 4, "text": "AST tool requires no configuration. Perplexity requires apiKey. JIRA requires jiraUrl, username, apiToken. Confluence requires confluenceUrl, username, apiToken. Stakeholder requires at least one platform webhook/token.", "deleted": false, "createdAt": "2025-11-12T05:19:00.026Z" }, { "id": 5, "text": "Tools validate configuration on execution and throw helpful errors with setup instructions pointing to config file locations", "deleted": false, "createdAt": "2025-11-12T05:19:01.728Z" }, { "id": 6, "text": "Option A: Try to validate the full configuration. Use the existing loadConfig() and validation logic from each tool to accurately determine if it's configured. Accept the slight performance cost for accuracy.", "deleted": false, "createdAt": "2025-11-12T05:25:45.036Z" }, { "id": 7, "text": "Option B: Show full JSON example inline. This is clear and immediately actionable - users can copy-paste the JSON structure directly into their config file. System-reminders can be more concise since AI agents can run --help commands.", "deleted": false, "createdAt": "2025-11-12T05:27:28.412Z" }, { "id": 8, "text": "User-facing 'fspec research' output shows only configured tools by default. Use --all flag to show unconfigured tools with setup instructions.", "deleted": false, "createdAt": "2025-11-12T05:27:39.767Z" }, { "id": 9, "text": "System-reminders (AI-only) always show all tools with status to enable AI agents to suggest and guide setup for better tools.", "deleted": false, "createdAt": "2025-11-12T05:27:42.327Z" } ], "nextRuleId": 10, "examples": [ { "id": 0, "text": "User runs 'fspec research' with no tools configured. Output shows only AST (no config needed) as available. Shows message about other tools with --all flag.", "deleted": false, "createdAt": "2025-11-12T05:19:19.654Z" }, { "id": 1, "text": "User runs 'fspec research --all'. Output shows all 5 tools: AST (✓ ready), Perplexity (✗ not configured - needs config.research.perplexity.apiKey in spec/fspec-config.json), etc.", "deleted": false, "createdAt": "2025-11-12T05:19:21.493Z" }, { "id": 2, "text": "AI agent sees system-reminder listing all 5 tools with configuration status and JSON config structure examples for each unconfigured tool.", "deleted": false, "createdAt": "2025-11-12T05:19:23.025Z" }, { "id": 3, "text": "User runs 'fspec research --tool=perplexity --query=\"test\"' without config. Error message shows: missing apiKey, how to add to spec/fspec-config.json with JSON example, suggests using AST instead.", "deleted": false, "createdAt": "2025-11-12T05:19:24.960Z" }, { "id": 4, "text": "User has only AST configured. Runs 'fspec research'. Sees: 'Available: ast (ready)' and footer message: 'Run fspec research --all to see 4 additional tools that require configuration.'", "deleted": false, "createdAt": "2025-11-12T05:27:44.099Z" } ], "nextExampleId": 5, "attachments": [ "spec/attachments/RES-018/RES-018-unconfigured-tool-visibility-research.md" ], "estimate": 3, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-12T05:45:29.649Z" }, "REMIND-013": { "id": "REMIND-013", "title": "Enhanced research tool guidance in system reminders", "type": "story", "status": "done", "createdAt": "2025-11-12T06:12:23.191Z", "updatedAt": "2025-11-12T06:35:12.931Z", "description": "Improve system reminders to guide AI agents about available research tools, when to use AST for code tasks, and promote AI-powered search tools like Perplexity with natural language queries.", "children": [], "attachments": [ "spec/attachments/REMIND-013/REMIND-012-research-tool-guidance-refactoring.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T06:12:48.977Z" }, { "state": "testing", "timestamp": "2025-11-12T06:22:43.602Z" }, { "state": "implementing", "timestamp": "2025-11-12T06:28:47.645Z" }, { "state": "validating", "timestamp": "2025-11-12T06:31:58.977Z" }, { "state": "done", "timestamp": "2025-11-12T06:35:12.931Z" } ], "userStory": { "role": "AI agent using fspec", "action": "receive context-aware research tool guidance in system reminders", "benefit": "I use the right research tool at the right time with proper natural language queries" }, "rules": [ { "id": 0, "text": "System reminders must show all 5 bundled research tools (ast, perplexity, jira, confluence, stakeholder) with their configuration status", "deleted": false, "createdAt": "2025-11-12T06:13:14.524Z" }, { "id": 1, "text": "Configuration status must be determined using RES-018's getToolConfigurationStatus() function, not environment variables", "deleted": false, "createdAt": "2025-11-12T06:13:20.797Z" }, { "id": 2, "text": "When work unit title contains code-related keywords (refactor, implement, create, add, update), emphasize AST tool in reminder", "deleted": false, "createdAt": "2025-11-12T06:13:27.245Z" }, { "id": 3, "text": "When work unit title contains research keywords (research, explore, investigate), emphasize Perplexity tool with natural language guidance", "deleted": false, "createdAt": "2025-11-12T06:13:32.948Z" }, { "id": 4, "text": "Reminders must be emitted at TWO points: work unit creation AND when entering specifying state", "deleted": false, "createdAt": "2025-11-12T06:13:38.985Z" }, { "id": 5, "text": "For unconfigured tools, reminder must show JSON config example from RES-018's getConfigExample()", "deleted": false, "createdAt": "2025-11-12T06:13:45.164Z" }, { "id": 6, "text": "Yes, reminders should be tailored by type. Stories: emphasize new functionality/refactoring scenarios. Bugs: emphasize different strategies like asking Perplexity for solutions and using AST to check linkage/structure. Tasks: emphasize code analysis and infrastructure work.", "deleted": false, "createdAt": "2025-11-12T06:16:31.007Z" }, { "id": 7, "text": "Make getStatusChangeReminder() fully async (Option B). Only one call site to update, already have async specifyingStateReminder(), and it's future-proof for adding tool guidance to other states if needed. Clean architecture with await handling both Promise and string returns.", "deleted": false, "createdAt": "2025-11-12T06:19:10.799Z" }, { "id": 8, "text": "Tool emphasis should show in BOTH creation and specifying reminders. Creation (backlog): AI needs immediate guidance for initial discovery/research. Specifying: AI needs tool guidance for Example Mapping to answer questions and gather rules/examples. Both states benefit from context-aware AST/Perplexity emphasis based on work unit type and title.", "deleted": false, "createdAt": "2025-11-12T06:20:35.035Z" } ], "nextRuleId": 9, "examples": [ { "id": 0, "text": "AI creates task 'Refactor authentication module', reminder shows 'CODE-RELATED task' and emphasizes AST tool with example commands", "deleted": false, "createdAt": "2025-11-12T06:13:52.628Z" }, { "id": 1, "text": "AI creates story 'Research OAuth2 implementation patterns', reminder shows 'RESEARCH-HEAVY story' and emphasizes Perplexity with 'USE NATURAL LANGUAGE' guidance", "deleted": false, "createdAt": "2025-11-12T06:13:59.080Z" }, { "id": 2, "text": "AI moves work unit to specifying state, reminder lists all 5 tools with ✓ for configured and ✗ for unconfigured, showing JSON config examples for unconfigured tools", "deleted": false, "createdAt": "2025-11-12T06:14:04.666Z" }, { "id": 3, "text": "Perplexity is not configured, reminder shows '✗ perplexity (not configured)' with JSON example showing {\"research\": {\"perplexity\": {\"apiKey\": \"...\"}}}", "deleted": false, "createdAt": "2025-11-12T06:14:10.650Z" }, { "id": 4, "text": "AST tool is always shown as '✓ ast (configured)' with reason 'No configuration required'", "deleted": false, "createdAt": "2025-11-12T06:14:16.699Z" } ], "nextExampleId": 5, "questions": [ { "id": 0, "text": "@human: Should reminders be different for bugs vs stories vs tasks, or only based on title keywords?", "deleted": false, "createdAt": "2025-11-12T06:14:22.747Z", "selected": true, "answer": "Yes, reminders should be tailored by type. Stories: emphasize new functionality/refactoring scenarios. Bugs: emphasize different strategies like asking Perplexity for solutions and using AST to check linkage/structure. Tasks: emphasize code analysis and infrastructure work." }, { "id": 1, "text": "@human: The research document says reminder functions must be async. Should we add async support to ALL state reminders or just specifying and creation?", "deleted": false, "createdAt": "2025-11-12T06:14:29.041Z", "selected": true, "answer": "Make getStatusChangeReminder() fully async (Option B). Only one call site to update, already have async specifyingStateReminder(), and it's future-proof for adding tool guidance to other states if needed. Clean architecture with await handling both Promise and string returns." }, { "id": 2, "text": "@human: Should tool emphasis (AST vs Perplexity) only show in creation reminders, only in specifying reminders, or both?", "deleted": false, "createdAt": "2025-11-12T06:14:34.567Z", "selected": true, "answer": "Tool emphasis should show in BOTH creation and specifying reminders. Creation (backlog): AI needs immediate guidance for initial discovery/research. Specifying: AI needs tool guidance for Example Mapping to answer questions and gather rules/examples. Both states benefit from context-aware AST/Perplexity emphasis based on work unit type and title." } ], "nextQuestionId": 3, "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-12T06:35:12.931Z" }, "REVIEW-001": { "id": "REVIEW-001", "title": "Enhance fspec review with DRY and SOLID principles checking using AST analysis", "type": "story", "status": "done", "createdAt": "2025-11-12T07:18:27.910Z", "updatedAt": "2025-11-12T09:36:07.753Z", "description": "Refactor the fspec review command to integrate AST-based code quality analysis for detecting DRY (Don't Repeat Yourself) violations and SOLID principle violations. Use the existing fspec research AST tool to analyze implementation files and provide actionable feedback on code duplication, class design, and dependency management.", "children": [], "attachments": [ "spec/attachments/REVIEW-001/research-fspec-review-ast-integration-v2.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T07:26:15.379Z" }, { "state": "testing", "timestamp": "2025-11-12T07:37:23.289Z" }, { "state": "implementing", "timestamp": "2025-11-12T07:41:56.272Z" }, { "state": "validating", "timestamp": "2025-11-12T08:01:30.548Z" }, { "state": "done", "timestamp": "2025-11-12T09:36:07.754Z" } ], "userStory": { "role": "AI agent using fspec review command", "action": "receive AST-based structural data about implementation files", "benefit": "I can analyze code for DRY/SOLID principles using the data and tools provided" }, "rules": [ { "id": 0, "text": "fspec MUST NOT perform semantic code analysis or make quality judgments", "deleted": false, "createdAt": "2025-11-12T07:27:10.680Z" }, { "id": 1, "text": "fspec review must gather structural data using fspec research --tool=ast commands", "deleted": false, "createdAt": "2025-11-12T07:30:19.680Z" }, { "id": 2, "text": "System-reminders must present structural data in neutral, factual format without judgments", "deleted": false, "createdAt": "2025-11-12T07:30:26.629Z" }, { "id": 3, "text": "System-reminders must suggest AST commands AI can run for deeper investigation", "deleted": false, "createdAt": "2025-11-12T07:30:32.617Z" }, { "id": 4, "text": "System-reminders must include guidance questions to prompt AI thinking about DRY/SOLID principles", "deleted": false, "createdAt": "2025-11-12T07:30:38.933Z" }, { "id": 5, "text": "fspec review must gather function counts, class counts, import counts, and export counts per file", "deleted": false, "createdAt": "2025-11-12T07:30:45.512Z" }, { "id": 6, "text": "fspec review must identify functions/classes with identical names across multiple files", "deleted": false, "createdAt": "2025-11-12T07:30:53.365Z" }, { "id": 7, "text": "AST data gathering must add less than 2 seconds overhead to fspec review command", "deleted": false, "createdAt": "2025-11-12T07:31:01.180Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "AI runs fspec review AUTH-001, receives system-reminder with function counts for each implementation file", "deleted": false, "createdAt": "2025-11-12T07:31:15.392Z" }, { "id": 1, "text": "System-reminder shows formatOutput() function appears in review.ts:156 and validate.ts:234", "deleted": false, "createdAt": "2025-11-12T07:31:22.653Z" }, { "id": 2, "text": "System-reminder suggests running: fspec research --tool=ast --operation=list-functions --file=src/commands/review.ts", "deleted": false, "createdAt": "2025-11-12T07:31:31.215Z" }, { "id": 3, "text": "System-reminder asks: Are there functions with similar names that might have duplicate logic?", "deleted": false, "createdAt": "2025-11-12T07:31:38.080Z" }, { "id": 4, "text": "System-reminder reports ReviewCommand class has 15 public methods detected", "deleted": false, "createdAt": "2025-11-12T07:31:45.090Z" }, { "id": 5, "text": "System-reminder says 'Patterns detected (NOT violations, just observations)' when listing similar function names", "deleted": false, "createdAt": "2025-11-12T07:31:52.794Z" }, { "id": 6, "text": "AI reads system-reminder data, runs suggested AST commands, uses Read tool, and decides if refactoring is needed", "deleted": false, "createdAt": "2025-11-12T07:32:00.814Z" } ], "nextExampleId": 7, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T09:36:07.753Z" }, "TUI-030": { "id": "TUI-030", "title": "Handle binary files and large files in diff display", "type": "story", "status": "done", "createdAt": "2025-11-12T09:36:40.241Z", "updatedAt": "2025-11-12T10:07:26.926Z", "description": "Improve checkpoint viewer diff display to handle binary files (show message instead of diff) and truncate files over 20,000 lines. Binary files should show '[Binary file - no diff available]' and large files should show first 20,000 lines with a message '[File truncated - showing first 20,000 of N lines]'.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T09:37:53.480Z" }, { "state": "testing", "timestamp": "2025-11-12T09:58:09.753Z" }, { "state": "implementing", "timestamp": "2025-11-12T09:59:12.337Z" }, { "state": "validating", "timestamp": "2025-11-12T10:03:33.488Z" }, { "state": "done", "timestamp": "2025-11-12T10:07:26.926Z" } ], "userStory": { "role": "developer using checkpoint viewer", "action": "view diffs for all file types without performance issues or display errors", "benefit": "I can quickly understand changes in checkpoints regardless of file type or size" }, "rules": [ { "id": 0, "text": "Binary files must not show diff content, only a message indicating it's binary", "deleted": false, "createdAt": "2025-11-12T09:38:10.966Z" }, { "id": 1, "text": "Files with more than 20,000 lines must be truncated at 20,000 lines", "deleted": false, "createdAt": "2025-11-12T09:38:11.512Z" }, { "id": 2, "text": "Truncated files must show a message with total line count", "deleted": false, "createdAt": "2025-11-12T09:38:12.058Z" }, { "id": 3, "text": "Binary file detection must check file content, not just extension", "deleted": false, "createdAt": "2025-11-12T09:38:12.605Z" }, { "id": 4, "text": "Normal text files under 20,000 lines must show complete diff", "deleted": false, "createdAt": "2025-11-12T09:38:13.158Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User views checkpoint with image file (PNG), sees '[Binary file - no diff available]' instead of garbled text", "deleted": false, "createdAt": "2025-11-12T09:38:22.440Z" }, { "id": 1, "text": "User views checkpoint with PDF file, sees binary file message", "deleted": false, "createdAt": "2025-11-12T09:38:22.986Z" }, { "id": 2, "text": "User views checkpoint with 50,000-line log file, sees first 20,000 lines plus '[File truncated - showing first 20,000 of 50,000 lines]'", "deleted": false, "createdAt": "2025-11-12T09:38:23.546Z" }, { "id": 3, "text": "User views checkpoint with normal 500-line source file, sees complete diff", "deleted": false, "createdAt": "2025-11-12T09:38:24.097Z" }, { "id": 4, "text": "User views checkpoint with executable binary, sees binary file message", "deleted": false, "createdAt": "2025-11-12T09:38:24.642Z" } ], "nextExampleId": 5, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T10:07:26.926Z" }, "BUG-075": { "id": "BUG-075", "title": "AST research tool fails with '--file is required' error even when --file flag is provided", "type": "bug", "status": "done", "createdAt": "2025-11-12T09:41:58.355Z", "updatedAt": "2025-11-12T09:50:55.948Z", "children": [], "attachments": [ "spec/attachments/BUG-075/bug-075-ast-tool-investigation.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T09:42:52.055Z" }, { "state": "testing", "timestamp": "2025-11-12T09:47:17.580Z" }, { "state": "implementing", "timestamp": "2025-11-12T09:48:28.449Z" }, { "state": "validating", "timestamp": "2025-11-12T09:50:30.541Z" }, { "state": "done", "timestamp": "2025-11-12T09:50:55.948Z" } ], "rules": [ { "id": 0, "text": "The research command must correctly forward all arguments after --tool to the tool's execute() function", "deleted": false, "createdAt": "2025-11-12T09:43:02.554Z" }, { "id": 1, "text": "The tool's execute() function must correctly parse --file argument from the forwarded args array", "deleted": false, "createdAt": "2025-11-12T09:43:03.104Z" }, { "id": 2, "text": "AST tool must handle both --flag=value and --flag value argument formats", "deleted": false, "createdAt": "2025-11-12T09:45:13.710Z" }, { "id": 3, "text": "When --file is not found in args array, check if any element starts with '--file='", "deleted": false, "createdAt": "2025-11-12T09:45:14.274Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=src/git/diff.ts', AST tool should receive ['--operation=list-functions', '--file=src/git/diff.ts'] as args", "deleted": false, "createdAt": "2025-11-12T09:43:03.646Z" }, { "id": 1, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=src/git/diff.ts' (equals format), tool should parse --file=src/git/diff.ts correctly", "deleted": false, "createdAt": "2025-11-12T09:45:12.615Z" }, { "id": 2, "text": "User runs 'fspec research --tool=ast --operation list-functions --file src/git/diff.ts' (space format), tool should parse arguments correctly", "deleted": false, "createdAt": "2025-11-12T09:45:13.163Z" } ], "nextExampleId": 3, "userStory": { "role": "developer using fspec research tool", "action": "use either --flag=value or --flag value syntax for all arguments", "benefit": "the tool works reliably regardless of which argument format I choose" }, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T09:50:55.948Z" }, "BUG-076": { "id": "BUG-076", "title": "JIRA research tool outputs [object Object] in markdown format for description field", "type": "bug", "status": "done", "createdAt": "2025-11-12T11:08:36.058Z", "updatedAt": "2025-11-12T11:18:48.863Z", "children": [], "attachments": [ "spec/attachments/BUG-076/bug-076-jira-markdown-description.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T11:10:19.567Z" }, { "state": "testing", "timestamp": "2025-11-12T11:13:29.022Z" }, { "state": "implementing", "timestamp": "2025-11-12T11:15:17.839Z" }, { "state": "validating", "timestamp": "2025-11-12T11:16:07.648Z" }, { "state": "done", "timestamp": "2025-11-12T11:18:48.863Z" } ], "rules": [ { "id": 0, "text": "JIRA API returns description field as Atlassian Document Format (ADF) object, not plain string", "deleted": false, "createdAt": "2025-11-12T11:10:52.264Z" }, { "id": 1, "text": "ADF object has nested content structure with type/version/content fields", "deleted": false, "createdAt": "2025-11-12T11:10:59.567Z" }, { "id": 2, "text": "Markdown formatter must recursively parse ADF content array to extract text nodes", "deleted": false, "createdAt": "2025-11-12T11:11:05.044Z" }, { "id": 3, "text": "JSON format works correctly because it preserves ADF object structure", "deleted": false, "createdAt": "2025-11-12T11:11:11.030Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=jira --issue CCS-6' and sees description text instead of [object Object]", "deleted": false, "createdAt": "2025-11-12T11:11:18.033Z" }, { "id": 1, "text": "Issue CCS-6 description 'The frontend interface should be user-friendly...' displays correctly in markdown format", "deleted": false, "createdAt": "2025-11-12T11:11:24.826Z" }, { "id": 2, "text": "Empty or missing description field shows 'No description provided' instead of [object Object]", "deleted": false, "createdAt": "2025-11-12T11:11:31.966Z" } ], "nextExampleId": 3, "userStory": { "role": "developer using fspec research tool", "action": "view JIRA issue descriptions in markdown format", "benefit": "I can read issue details without switching to JSON format" }, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T11:18:48.863Z" }, "RES-019": { "id": "RES-019", "title": "Add multi-language support to AST research tool (Kotlin, Dart, Python, Go, Rust, Swift, C#, C, C++)", "type": "story", "status": "done", "createdAt": "2025-11-12T11:23:07.338Z", "updatedAt": "2025-11-12T12:12:46.688Z", "description": "Extend AST research tool to support Kotlin and Dart languages by integrating tree-sitter-kotlin and tree-sitter-dart parsers", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T11:23:16.315Z" }, { "state": "testing", "timestamp": "2025-11-12T11:26:08.154Z" }, { "state": "implementing", "timestamp": "2025-11-12T11:28:13.779Z" }, { "state": "specifying", "timestamp": "2025-11-12T11:58:28.909Z" }, { "state": "testing", "timestamp": "2025-11-12T12:01:18.623Z" }, { "state": "implementing", "timestamp": "2025-11-12T12:11:13.048Z" }, { "state": "validating", "timestamp": "2025-11-12T12:11:44.502Z" }, { "state": "done", "timestamp": "2025-11-12T12:12:46.688Z" } ], "userStory": { "role": "developer using AST research tool", "action": "analyze Kotlin and Dart codebases", "benefit": "I can use fspec research commands with projects written in these languages" }, "rules": [ { "id": 0, "text": "AST tool must support tree-sitter-kotlin for Kotlin language parsing", "deleted": false, "createdAt": "2025-11-12T11:23:31.831Z" }, { "id": 1, "text": "AST tool must support tree-sitter-dart for Dart language parsing", "deleted": false, "createdAt": "2025-11-12T11:23:32.371Z" }, { "id": 2, "text": "Language detection must identify .kt and .kts files as Kotlin", "deleted": false, "createdAt": "2025-11-12T11:23:32.912Z" }, { "id": 3, "text": "Language detection must identify .dart files as Dart", "deleted": false, "createdAt": "2025-11-12T11:23:33.455Z" }, { "id": 4, "text": "AST tool must support tree-sitter parsers for Python, Go, Rust, Swift, C#, C, and C++", "deleted": false, "createdAt": "2025-11-12T11:58:56.774Z" }, { "id": 5, "text": "Language detection must identify file extensions: .py (Python), .go (Go), .rs (Rust), .swift (Swift), .cs (C#), .c/.h (C), .cpp/.hpp/.cc/.cxx (C++)", "deleted": false, "createdAt": "2025-11-12T11:59:03.870Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=MyClass.kt' and gets list of Kotlin functions", "deleted": false, "createdAt": "2025-11-12T11:23:41.665Z" }, { "id": 1, "text": "User runs 'fspec research --tool=ast --operation=list-classes --file=MyWidget.dart' and gets list of Dart classes", "deleted": false, "createdAt": "2025-11-12T11:23:42.210Z" }, { "id": 2, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=app.dart' and gets Flutter/Dart functions", "deleted": false, "createdAt": "2025-11-12T11:23:42.751Z" }, { "id": 3, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=main.py' and gets list of Python functions", "deleted": false, "createdAt": "2025-11-12T11:59:11.526Z" }, { "id": 4, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=main.go' and gets list of Go functions", "deleted": false, "createdAt": "2025-11-12T11:59:19.393Z" }, { "id": 5, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=main.rs' and gets list of Rust functions", "deleted": false, "createdAt": "2025-11-12T11:59:29.228Z" }, { "id": 6, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=App.swift' and gets list of Swift functions", "deleted": false, "createdAt": "2025-11-12T11:59:35.521Z" }, { "id": 7, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=Program.cs' and gets list of C# methods", "deleted": false, "createdAt": "2025-11-12T11:59:42.618Z" }, { "id": 8, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=main.c' and gets list of C functions", "deleted": false, "createdAt": "2025-11-12T11:59:49.974Z" }, { "id": 9, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=main.cpp' and gets list of C++ functions", "deleted": false, "createdAt": "2025-11-12T11:59:58.105Z" } ], "nextExampleId": 10, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T12:12:46.688Z" }, "RES-020": { "id": "RES-020", "title": "Add Java, PHP, Ruby, Bash support to AST research tool", "type": "story", "status": "done", "createdAt": "2025-11-12T12:24:29.732Z", "updatedAt": "2025-11-12T19:50:12.247Z", "description": "Complete AST research tool language support by adding Java, PHP, Ruby, and Bash languages with full configuration, testing, and documentation", "epic": "research-tools", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T12:24:36.379Z" }, { "state": "testing", "timestamp": "2025-11-12T19:34:21.460Z" }, { "state": "implementing", "timestamp": "2025-11-12T19:39:34.114Z" }, { "state": "validating", "timestamp": "2025-11-12T19:46:07.337Z" }, { "state": "done", "timestamp": "2025-11-12T19:50:12.247Z" } ], "userStory": { "role": "developer using AST research tool", "action": "analyze codebases in Java, PHP, Ruby, and Bash", "benefit": "I can use fspec research tool with all major programming languages in my projects" }, "rules": [ { "id": 0, "text": "AST tool must support tree-sitter-java for Java language parsing (.java files)", "deleted": false, "createdAt": "2025-11-12T12:24:55.902Z" }, { "id": 1, "text": "AST tool must support tree-sitter-php for PHP language parsing (.php files)", "deleted": false, "createdAt": "2025-11-12T12:25:06.104Z" }, { "id": 2, "text": "AST tool must support tree-sitter-ruby for Ruby language parsing (.rb files)", "deleted": false, "createdAt": "2025-11-12T12:25:06.669Z" }, { "id": 3, "text": "AST tool must support tree-sitter-bash for Bash script parsing (.sh, .bash files)", "deleted": false, "createdAt": "2025-11-12T12:25:07.237Z" }, { "id": 4, "text": "All parsers must be properly imported and initialized in src/research-tools/ast.ts", "deleted": false, "createdAt": "2025-11-12T12:25:07.794Z" }, { "id": 5, "text": "Language detection must identify file extensions for all 4 new languages", "deleted": false, "createdAt": "2025-11-12T12:25:08.352Z" }, { "id": 6, "text": "Query executor must handle language-specific AST node types for each language", "deleted": false, "createdAt": "2025-11-12T12:25:08.909Z" }, { "id": 7, "text": "Help documentation in src/help.ts must list all research tools and their capabilities", "deleted": false, "createdAt": "2025-11-12T12:25:09.462Z" }, { "id": 8, "text": "AST tool help must document all 15 supported languages", "deleted": false, "createdAt": "2025-11-12T12:25:10.022Z" } ], "nextRuleId": 9, "examples": [ { "id": 0, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=Example.java' and gets list of Java methods", "deleted": false, "createdAt": "2025-11-12T12:25:22.072Z" }, { "id": 1, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=example.php' and gets list of PHP functions", "deleted": false, "createdAt": "2025-11-12T12:25:22.627Z" }, { "id": 2, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=example.rb' and gets list of Ruby methods", "deleted": false, "createdAt": "2025-11-12T12:25:23.185Z" }, { "id": 3, "text": "User runs 'fspec research --tool=ast --operation=list-functions --file=script.sh' and gets list of Bash functions", "deleted": false, "createdAt": "2025-11-12T12:25:23.743Z" }, { "id": 4, "text": "User runs 'fspec research --tool=ast --help' and sees all 15 supported languages documented", "deleted": false, "createdAt": "2025-11-12T12:25:24.299Z" }, { "id": 5, "text": "User runs 'fspec research' and sees AST tool listed with correct language support count", "deleted": false, "createdAt": "2025-11-12T12:25:24.855Z" }, { "id": 6, "text": "Developer checks src/help.ts and finds complete research tools documentation", "deleted": false, "createdAt": "2025-11-12T12:25:25.416Z" } ], "nextExampleId": 7, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T19:50:12.247Z" }, "DEP-003": { "id": "DEP-003", "title": "Eliminate tree-sitter legacy-peer-deps requirement", "type": "story", "status": "done", "createdAt": "2025-11-12T20:19:18.626Z", "updatedAt": "2025-11-12T20:38:42.771Z", "description": "Research and implement solution to remove --legacy-peer-deps flag from npm install by fixing tree-sitter package peer dependency conflicts through npm overrides", "children": [], "attachments": [ "spec/attachments/DEP-003/tree-sitter-legacy-peer-deps-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T20:20:53.324Z" }, { "state": "testing", "timestamp": "2025-11-12T20:26:43.091Z" }, { "state": "implementing", "timestamp": "2025-11-12T20:28:41.015Z" }, { "state": "validating", "timestamp": "2025-11-12T20:33:47.670Z" }, { "state": "done", "timestamp": "2025-11-12T20:38:42.772Z" } ], "userStory": { "role": "developer installing fspec", "action": "install npm dependencies without legacy-peer-deps flag", "benefit": "I follow npm best practices and avoid peer dependency conflicts" }, "rules": [ { "id": 0, "text": "npm install must succeed without --legacy-peer-deps flag", "deleted": false, "createdAt": "2025-11-12T20:21:21.698Z" }, { "id": 1, "text": "All tree-sitter language parsers must be compatible with tree-sitter@0.25.0", "deleted": false, "createdAt": "2025-11-12T20:21:27.947Z" }, { "id": 2, "text": "Solution must use npm native features (no external patching tools)", "deleted": false, "createdAt": "2025-11-12T20:21:34.056Z" }, { "id": 3, "text": "No manual forking or republishing of tree-sitter packages allowed", "deleted": false, "createdAt": "2025-11-12T20:21:40.638Z" }, { "id": 4, "text": "Runtime compatibility must be verified with actual parser tests before deployment", "deleted": false, "createdAt": "2025-11-12T20:21:47.399Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Developer runs 'npm install' in fresh clone, installation succeeds without errors or warnings", "deleted": false, "createdAt": "2025-11-12T20:21:59.998Z" }, { "id": 1, "text": "Developer runs 'npm install' after deleting node_modules and package-lock.json, all tree-sitter packages resolve to tree-sitter@0.25.0", "deleted": false, "createdAt": "2025-11-12T20:22:06.832Z" }, { "id": 2, "text": "AST parser uses tree-sitter-c to parse C code, parsing succeeds with tree-sitter@0.25.0", "deleted": false, "createdAt": "2025-11-12T20:22:13.517Z" }, { "id": 3, "text": "AST parser uses tree-sitter-typescript to parse TypeScript code, parsing succeeds with tree-sitter@0.25.0", "deleted": false, "createdAt": "2025-11-12T20:22:18.594Z" }, { "id": 4, "text": "Developer runs 'npm list tree-sitter' and sees only version 0.25.0 (no duplicate versions)", "deleted": false, "createdAt": "2025-11-12T20:22:28.437Z" } ], "nextExampleId": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T20:38:42.771Z" }, "VAL-001": { "id": "VAL-001", "title": "Mermaid validation using parse() instead of render() misses semantic errors", "type": "bug", "status": "done", "createdAt": "2025-11-12T22:09:52.108Z", "updatedAt": "2025-11-12T22:26:05.358Z", "description": "The add-attachment command validates mermaid diagrams using mermaid.parse() which only checks syntax/grammar but not rendering semantics. This allows invalid diagrams (e.g., quoted subgraph titles) to pass validation but fail in browser rendering.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T22:09:58.883Z" }, { "state": "testing", "timestamp": "2025-11-12T22:16:53.208Z" }, { "state": "implementing", "timestamp": "2025-11-12T22:18:57.824Z" }, { "state": "validating", "timestamp": "2025-11-12T22:22:34.665Z" }, { "state": "done", "timestamp": "2025-11-12T22:23:23.077Z" } ], "attachments": [ "spec/attachments/VAL-001/MERMAID_VALIDATION_BUG_INVESTIGATION.md", "spec/attachments/VAL-001/test-valid-subgraph.md" ], "rules": [ { "id": 0, "text": "Mermaid validation must catch ALL errors that would occur during browser rendering", "deleted": false, "createdAt": "2025-11-12T22:13:56.653Z" }, { "id": 1, "text": "Validation must reject semantically invalid diagrams (e.g., quoted subgraph titles)", "deleted": false, "createdAt": "2025-11-12T22:14:04.086Z" }, { "id": 2, "text": "Validation must occur at attachment time (one-time operation)", "deleted": false, "createdAt": "2025-11-12T22:14:09.901Z" }, { "id": 3, "text": "Error messages must clearly indicate what is wrong and how to fix it", "deleted": false, "createdAt": "2025-11-12T22:14:15.794Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "User attaches markdown with quoted subgraph title 'subgraph \"Server Side\"' - validation REJECTS with clear error", "deleted": false, "createdAt": "2025-11-12T22:14:23.583Z" }, { "id": 1, "text": "User attaches markdown with proper subgraph syntax 'subgraph ServerSide[Server Side]' - validation PASSES", "deleted": false, "createdAt": "2025-11-12T22:14:29.787Z" }, { "id": 2, "text": "User attaches markdown with invalid subgraph identifier 'subgraph INVALID\\!\\!\\!' - validation REJECTS", "deleted": false, "createdAt": "2025-11-12T22:14:35.364Z" }, { "id": 3, "text": "User attaches markdown with broken syntax (missing closing bracket) - validation REJECTS (already working)", "deleted": false, "createdAt": "2025-11-12T22:14:41.310Z" }, { "id": 4, "text": "User attaches markdown with multiple diagrams, one invalid - validation REJECTS with clear indication which diagram failed", "deleted": false, "createdAt": "2025-11-12T22:14:47.076Z" } ], "nextExampleId": 5, "userStory": { "role": "developer using fspec to document architecture", "action": "validate mermaid diagrams for both syntax and semantic errors", "benefit": "I catch rendering errors before viewing in browser" }, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T22:23:23.077Z" }, "VAL-003": { "id": "VAL-003", "title": "Refactor mermaid validation for code quality improvements", "type": "task", "status": "done", "createdAt": "2025-11-12T22:36:40.375Z", "updatedAt": "2025-11-12T22:50:29.810Z", "description": "Apply code review recommendations: 1) Fix global cleanup inconsistency in error path, 2) Validate all subgraphs not just first, 3) Add proper TypeScript global declarations", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-12T22:37:03.150Z" }, { "state": "implementing", "timestamp": "2025-11-12T22:37:11.073Z" }, { "state": "validating", "timestamp": "2025-11-12T22:49:45.412Z" }, { "state": "done", "timestamp": "2025-11-12T22:50:29.811Z" } ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-12T22:50:29.810Z" }, "VAL-004": { "id": "VAL-004", "title": "Multiple consecutive system-reminder blocks in update-work-unit-status", "type": "bug", "status": "done", "createdAt": "2025-11-12T22:47:24.951Z", "updatedAt": "2025-11-15T12:00:45.826Z", "description": "The update-work-unit-status command creates multiple consecutive <system-reminder> blocks instead of a single unified block when multiple reminders are applicable", "children": [], "attachments": [ "spec/attachments/VAL-004/VAL-004-system-reminder-duplication-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-15T11:55:04.495Z" }, { "state": "testing", "timestamp": "2025-11-15T11:57:33.447Z" }, { "state": "implementing", "timestamp": "2025-11-15T12:00:26.333Z" }, { "state": "validating", "timestamp": "2025-11-15T12:00:31.657Z" }, { "state": "done", "timestamp": "2025-11-15T12:00:45.826Z" } ], "userStory": { "role": "developer using fspec CLI", "action": "see single unified system-reminder blocks", "benefit": "I don't get confused by multiple consecutive reminder blocks" }, "rules": [ { "id": 0, "text": "All system-reminder content must be in a single unified block", "deleted": false, "createdAt": "2025-11-15T11:56:14.645Z" }, { "id": 1, "text": "Multiple reminders should be combined by unwrapping individual blocks and re-wrapping once", "deleted": false, "createdAt": "2025-11-15T11:56:19.366Z" } ], "nextRuleId": 2, "examples": [ { "id": 0, "text": "Work unit transitions to done status with multiple applicable reminders - output should have single system-reminder block containing all reminder content", "deleted": false, "createdAt": "2025-11-15T11:56:24.411Z" }, { "id": 1, "text": "Status change reminder, virtual hooks reminder, and cleanup reminder all triggered - should combine into one block, not three separate blocks", "deleted": false, "createdAt": "2025-11-15T11:56:30.010Z" } ], "nextExampleId": 2, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-15T12:00:45.826Z" }, "PERF-001": { "id": "PERF-001", "title": "Lazy Load Tree-Sitter Language Parsers", "type": "story", "status": "done", "createdAt": "2025-11-15T05:08:40.769Z", "updatedAt": "2025-11-15T05:20:29.478Z", "description": "Refactor AST utilities to lazy-load tree-sitter language parsers on-demand instead of eagerly importing all 15 parsers at startup, improving CLI load time by 85-93% for single-language analysis", "children": [], "userStory": { "role": "developer using fspec AST research tools", "action": "have fast CLI startup time when analyzing code", "benefit": "I can quickly analyze single files without loading all 15 language parsers unnecessarily" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-15T05:09:07.155Z" }, { "state": "testing", "timestamp": "2025-11-15T05:12:51.847Z" }, { "state": "implementing", "timestamp": "2025-11-15T05:14:06.421Z" }, { "state": "validating", "timestamp": "2025-11-15T05:16:10.839Z" }, { "state": "done", "timestamp": "2025-11-15T05:20:29.478Z" } ], "rules": [ { "id": 0, "text": "Language parsers must be loaded on-demand using dynamic imports, not eagerly at module load time", "deleted": false, "createdAt": "2025-11-15T05:09:14.926Z" }, { "id": 1, "text": "Only the parser needed for the target file's language should be loaded", "deleted": false, "createdAt": "2025-11-15T05:09:15.593Z" }, { "id": 2, "text": "Loaded parsers should be cached to avoid re-importing the same language parser multiple times", "deleted": false, "createdAt": "2025-11-15T05:09:16.256Z" }, { "id": 3, "text": "Refactoring must not change the external API of ast-parser.ts or research-tools/ast.ts", "deleted": false, "createdAt": "2025-11-15T05:09:16.927Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Developer analyzes a TypeScript file using 'fspec research --tool=ast --file=src/auth.ts' and only the TypeScript parser is loaded (not all 15 parsers)", "deleted": false, "createdAt": "2025-11-15T05:09:25.619Z" }, { "id": 1, "text": "Developer analyzes multiple TypeScript files and the TypeScript parser is loaded once and cached for subsequent analyses", "deleted": false, "createdAt": "2025-11-15T05:09:26.984Z" }, { "id": 2, "text": "CLI startup time improves by 85-93% when analyzing a single TypeScript file (from ~750-3000ms to ~50-200ms)", "deleted": false, "createdAt": "2025-11-15T05:09:28.273Z" }, { "id": 3, "text": "All existing tests pass after refactoring without modification", "deleted": false, "createdAt": "2025-11-15T05:09:29.991Z" } ], "nextExampleId": 4, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-15T05:20:29.478Z" }, "RES-021": { "id": "RES-021", "title": "Enhance AST Research Tool with Missing Tree-Sitter Capabilities", "type": "story", "status": "done", "createdAt": "2025-11-15T06:03:25.947Z", "updatedAt": "2025-11-15T06:24:10.916Z", "description": "Leverage advanced tree-sitter features (Query API, TreeCursor, field-based access, closest() navigation, etc.) to make fspec's AST research tool more powerful, performant, and maintainable. Analysis shows 7 major capability categories currently unused.", "children": [], "attachments": [ "spec/attachments/RES-021/tree-sitter-missing-capabilities.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-15T06:10:08.313Z" }, { "state": "testing", "timestamp": "2025-11-15T06:15:19.843Z" }, { "state": "implementing", "timestamp": "2025-11-15T06:16:48.699Z" }, { "state": "validating", "timestamp": "2025-11-15T06:20:09.854Z" }, { "state": "done", "timestamp": "2025-11-15T06:24:10.916Z" } ], "userStory": { "role": "developer using fspec AST research tools", "action": "leverage advanced tree-sitter capabilities for powerful code analysis", "benefit": "I can perform complex pattern matching, improve performance, and analyze code more effectively" }, "rules": [ { "id": 0, "text": "Phase 1 implementation must include Query System (S-expression pattern matching), Field-Based Access, and closest() method", "deleted": false, "createdAt": "2025-11-15T06:10:32.003Z" }, { "id": 1, "text": "Query operations must support inline queries via --query parameter and external .scm files via --query-file parameter", "deleted": false, "createdAt": "2025-11-15T06:10:33.637Z" }, { "id": 2, "text": "Field-based access (childForFieldName) must be used internally instead of type-based child searches for reliability", "deleted": false, "createdAt": "2025-11-15T06:10:35.203Z" }, { "id": 3, "text": "New operations must be backward compatible - existing operations (list-functions, find-class, etc.) continue to work", "deleted": false, "createdAt": "2025-11-15T06:10:36.805Z" }, { "id": 4, "text": "Query predicates must support at minimum: #eq?, #match?, #any-of? for filtering captures", "deleted": false, "createdAt": "2025-11-15T06:10:38.342Z" }, { "id": 5, "text": "Defer TreeCursor to Phase 2 (v0.10.0) - Phase 1 focuses on Query System, Field Access, and closest() for high-impact features first", "deleted": false, "createdAt": "2025-11-15T06:12:43.925Z" }, { "id": 6, "text": "Transform to QueryMatch interface for consistency with existing operations - include captures metadata in extended format", "deleted": false, "createdAt": "2025-11-15T06:12:46.280Z" }, { "id": 7, "text": "Separate work unit - fspec review enhancement is RES-022, Phase 1 provides the tools (query operations) that review can use later", "deleted": false, "createdAt": "2025-11-15T06:12:48.281Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "Developer uses --operation=query --query='(function_declaration name: (identifier) @name)' to find all function names declaratively instead of manual traversal", "deleted": false, "createdAt": "2025-11-15T06:10:50.646Z" }, { "id": 1, "text": "Developer uses --operation=find-context --row=42 --column=10 --context-type=function to find the containing function at a specific position (uses closest() internally)", "deleted": false, "createdAt": "2025-11-15T06:10:52.419Z" }, { "id": 2, "text": "Developer creates queries/anti-patterns.scm with pattern for empty catch blocks and runs --query-file=queries/anti-patterns.scm to detect code smells", "deleted": false, "createdAt": "2025-11-15T06:10:53.941Z" }, { "id": 3, "text": "Existing operation 'fspec research --tool=ast --operation=list-functions' continues to work exactly as before (backward compatibility verified)", "deleted": false, "createdAt": "2025-11-15T06:10:55.549Z" }, { "id": 4, "text": "Query with predicate: '(function_declaration name: (identifier) @name (#match? @name \"^handle\"))' finds only functions starting with 'handle'", "deleted": false, "createdAt": "2025-11-15T06:10:57.229Z" } ], "nextExampleId": 5, "questions": [ { "id": 0, "text": "@human: Should Phase 1 include TreeCursor performance optimization or defer to Phase 2?", "deleted": false, "createdAt": "2025-11-15T06:11:05.981Z", "selected": true, "answer": "Defer TreeCursor to Phase 2 (v0.10.0) - Phase 1 focuses on Query System, Field Access, and closest() for high-impact features first" }, { "id": 1, "text": "@human: Should query operations return raw tree-sitter captures or transform them into the existing QueryMatch interface format?", "deleted": false, "createdAt": "2025-11-15T06:11:07.670Z", "selected": true, "answer": "Transform to QueryMatch interface for consistency with existing operations - include captures metadata in extended format" }, { "id": 2, "text": "@human: Should fspec review command be enhanced with anti-pattern detection in Phase 1, or is that a separate work unit?", "deleted": false, "createdAt": "2025-11-15T06:11:09.452Z", "selected": true, "answer": "Separate work unit - fspec review enhancement is RES-022, Phase 1 provides the tools (query operations) that review can use later" } ], "nextQuestionId": 3, "estimate": 5, "architectureNotes": [], "nextNoteId": 0, "updated": "2025-11-15T06:24:10.916Z" }, "REMIND-014": { "id": "REMIND-014", "title": "Enhance fspec review with architecture alignment and AST verification", "type": "story", "status": "done", "createdAt": "2025-11-15T08:39:22.326Z", "updatedAt": "2025-11-15T09:20:43.523Z", "children": [], "userStory": { "role": "AI agent working on a feature", "action": "run architectural review before moving to testing phase", "benefit": "I ensure alignment with existing codebase architecture, follow DRY/SOLID principles, and verify complete code understanding via AST analysis" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-15T08:41:12.358Z" }, { "state": "testing", "timestamp": "2025-11-15T08:59:52.385Z" }, { "state": "implementing", "timestamp": "2025-11-15T09:01:56.602Z" }, { "state": "validating", "timestamp": "2025-11-15T09:06:00.953Z" }, { "state": "done", "timestamp": "2025-11-15T09:20:43.524Z" } ], "rules": [ { "id": 0, "text": "Architectural review must be automatic and mandatory before transitioning from specifying to testing", "deleted": false, "createdAt": "2025-11-15T08:41:16.140Z" }, { "id": 1, "text": "AST analysis must verify: all referenced files were analyzed, all mentioned functions/classes exist, all dependencies/imports are documented, and refactoring candidates were researched via AST", "deleted": false, "createdAt": "2025-11-15T08:43:51.370Z" }, { "id": 2, "text": "Architecture alignment must verify: proposed approach matches existing code patterns, decisions align with FOUNDATION.md/CLAUDE.md/AGENTS.md principles, architectural notes reference actual discovered code structures, and explicit justification required when diverging from established patterns", "deleted": false, "createdAt": "2025-11-15T08:45:51.283Z" }, { "id": 3, "text": "DRY/SOLID validation must verify: AI performed AST research during specifying phase (check attachments), architectural notes reference actual discovered code (not assumptions), AI is not proposing to reinvent existing utilities/functions, and proposed solutions follow SOLID principles based on architectural notes", "deleted": false, "createdAt": "2025-11-15T08:48:08.973Z" }, { "id": 4, "text": "Review enforcement must be hard block implemented inside update-work-unit-status command (not as hook), automatically run review when transitioning specifying to testing, throw error and prevent state change if critical issues or ACDD compliance failed, output full review report with specific issues and guidance", "deleted": false, "createdAt": "2025-11-15T08:49:14.667Z" }, { "id": 5, "text": "CRITICAL: fspec MUST NOT perform semantic code analysis - NO code quality judgments, NO similarity detection, NO anti-pattern detection in fspec itself. fspec ONLY provides structural data via AST (counts, names, locations). The AI agent makes ALL analysis decisions based on data provided.", "deleted": false, "createdAt": "2025-11-15T08:49:53.259Z" }, { "id": 6, "text": "Review has two-level blocking: Level 1 (Objective ACDD) - fspec hard blocks for no Example Mapping, no architectural notes, no AST research attachments, no feature file, invalid Gherkin. Level 2 (Subjective Analysis) - review passes but emits system-reminder with AST data, architectural notes, guidance questions for AI to analyze and decide whether to continue or revert to specifying", "deleted": false, "createdAt": "2025-11-15T08:51:51.557Z" } ], "nextRuleId": 7, "examples": [ { "id": 0, "text": "AI moves work unit from specifying to testing, review auto-runs and finds no AST research attachments, command fails with error: 'Cannot transition to testing - no AST research performed during discovery', AI must go back and run fspec research --tool=ast", "deleted": false, "createdAt": "2025-11-15T08:51:58.767Z" }, { "id": 1, "text": "AI moves work unit from specifying to testing, objective checks pass, review outputs system-reminder showing AST data (15 functions found across 3 files, validateFeature appears in 2 locations), AI analyzes data and realizes it was about to reinvent validateFeature, AI reverts to specifying using fspec update-work-unit-status WORK-001 specifying", "deleted": false, "createdAt": "2025-11-15T08:52:06.785Z" }, { "id": 2, "text": "AI creates architectural note 'Refactoring: Extract validation logic to shared utility because current code has 3 copies of same validation pattern across files', attaches AST research showing the 3 locations, review passes and allows transition to testing with all data validated", "deleted": false, "createdAt": "2025-11-15T08:52:12.930Z" } ], "nextExampleId": 3, "estimate": 8, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-15T09:20:43.523Z" }, "INIT-016": { "id": "INIT-016", "title": "Graceful Initialization Without Spec Directory", "type": "story", "status": "done", "createdAt": "2025-11-15T11:41:45.094Z", "updatedAt": "2025-11-15T11:48:20.057Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-15T11:41:52.135Z" }, { "state": "testing", "timestamp": "2025-11-15T21:44:00.000Z" }, { "state": "implementing", "timestamp": "2025-11-15T21:45:00.000Z" }, { "state": "validating", "timestamp": "2025-11-15T11:44:57.562Z" }, { "state": "done", "timestamp": "2025-11-15T11:48:20.057Z" } ], "estimate": 5, "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-15T11:48:20.057Z" }, "EXMAP-005": { "id": "EXMAP-005", "title": "Event Storm data model for work units", "type": "story", "status": "done", "createdAt": "2025-11-15T12:16:15.377Z", "updatedAt": "2025-11-15T23:57:49.896Z", "description": "Add eventStorm section to WorkUnit type in work-units.json for storing Process/Design Event Storming artifacts per story", "parent": "EXMAP-004", "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-15T12:19:48.294Z" }, { "state": "testing", "timestamp": "2025-11-15T23:54:39.372Z" }, { "state": "implementing", "timestamp": "2025-11-15T23:54:59.293Z" }, { "state": "validating", "timestamp": "2025-11-15T23:55:04.874Z" }, { "state": "done", "timestamp": "2025-11-15T23:57:49.896Z" } ], "userStory": { "role": "AI agent performing Event Storming during specifying phase", "action": "store Event Storm artifacts in work-units.json", "benefit": "I have persistent structured data for tag discovery and Example Mapping transformation" }, "rules": [ { "id": 0, "text": "Event Storm data model uses stable IDs with soft-delete pattern (id, text, deleted, createdAt, deletedAt) consistent with existing rules/examples/questions pattern", "deleted": false, "createdAt": "2025-11-15T12:20:15.096Z" }, { "id": 1, "text": "WorkUnit.eventStorm section stores: level (process_modeling or software_design), sessionDate, items array (events, commands, aggregates, policies, hotspots, external systems, bounded contexts), nextItemId counter", "deleted": false, "createdAt": "2025-11-15T12:20:21.557Z" }, { "id": 2, "text": "Event Storm items have type field: 'event', 'command', 'aggregate', 'policy', 'hotspot', 'external_system', 'bounded_context'", "deleted": false, "createdAt": "2025-11-15T12:20:26.714Z" }, { "id": 3, "text": "Items support relationships via relatedTo array containing IDs of related items (e.g., command triggersEvent, policy when/then)", "deleted": false, "createdAt": "2025-11-15T12:20:32.311Z" }, { "id": 4, "text": "Suggested tags generated from Event Storm stored in suggestedTags object with componentTags, featureGroupTags, technicalTags arrays and reasoning field", "deleted": false, "createdAt": "2025-11-15T12:20:38.138Z" }, { "id": 5, "text": "Data model must be versioned and support JSON Schema validation", "deleted": false, "createdAt": "2025-11-15T12:20:43.246Z" }, { "id": 6, "text": "Yes, add timestamp field for timeline visualization. Makes Event Storm temporal and enables Mermaid timeline diagrams.", "deleted": false, "createdAt": "2025-11-15T12:21:32.004Z" }, { "id": 7, "text": "Yes, add color field matching Event Storming convention (orange/blue/yellow/pink/purple/green/red) for visualization and adherence to Event Storming standard.", "deleted": false, "createdAt": "2025-11-15T12:21:38.099Z" }, { "id": 8, "text": "Use discriminated union with type field for type safety. Each item type has specific required fields (e.g., commands have triggersEvent, policies have when/then).", "deleted": false, "createdAt": "2025-11-15T12:21:44.395Z" } ], "nextRuleId": 9, "examples": [ { "id": 0, "text": "WorkUnit AUTH-001 has eventStorm section with level='process_modeling', 5 domain events (UserRegistered, EmailVerified, UserAuthenticated, SessionCreated, PasswordResetRequested), each with id, text, type='event', deleted=false", "deleted": false, "createdAt": "2025-11-15T12:20:49.670Z" }, { "id": 1, "text": "Event with id=0 'UserAuthenticated' has relatedTo=[1] linking to command id=1 'AuthenticateUser' which has triggersEvent=0", "deleted": false, "createdAt": "2025-11-15T12:20:54.782Z" }, { "id": 2, "text": "suggestedTags object contains componentTags=['@auth', '@session-management'], featureGroupTags=['@authentication', '@user-management'], technicalTags=['@oauth2-integration'], reasoning='Derived from Authentication bounded context, User aggregate, and OAuth2Provider external system'", "deleted": false, "createdAt": "2025-11-15T12:21:00.895Z" }, { "id": 3, "text": "Soft-delete: item id=3 marked deleted=true with deletedAt timestamp, still in items array, ID not reused, can be restored via restore commands", "deleted": false, "createdAt": "2025-11-15T12:21:06.852Z" } ], "nextExampleId": 4, "questions": [ { "id": 0, "text": "@human: Should timestamp field be added to Event Storm items for timeline visualization (like in the attachment's example with timestamp: 5000, 15000)?", "deleted": false, "createdAt": "2025-11-15T12:21:14.074Z", "selected": true, "answer": "Yes, add timestamp field for timeline visualization. Makes Event Storm temporal and enables Mermaid timeline diagrams." }, { "id": 1, "text": "@human: Should the data model include color field (orange, blue, yellow, etc.) to match physical Event Storming sticky note colors for better visualization?", "deleted": false, "createdAt": "2025-11-15T12:21:19.850Z", "selected": true, "answer": "Yes, add color field matching Event Storming convention (orange/blue/yellow/pink/purple/green/red) for visualization and adherence to Event Storming standard." }, { "id": 2, "text": "@human: For TypeScript types, should we create EventStormItem interface with discriminated union based on type field, or simpler base interface with optional fields?", "deleted": false, "createdAt": "2025-11-15T12:21:25.869Z", "selected": true, "answer": "Use discriminated union with type field for type safety. Each item type has specific required fields (e.g., commands have triggersEvent, policies have when/then)." } ], "nextQuestionId": 3, "estimate": 3, "architectureNotes": [ { "id": 0, "text": "Uses TypeScript discriminated unions for Event Storm item types, following ItemWithId pattern for stable IDs and soft-delete. Data stored in work-units.json eventStorm section.", "deleted": false, "createdAt": "2025-11-15T23:42:34.817Z" } ], "nextNoteId": 1, "attachments": [ "spec/attachments/EXMAP-005/ast-research-types.md" ], "updated": "2025-11-15T23:57:49.896Z" }, "EXMAP-006": { "id": "EXMAP-006", "title": "Event Storm artifact commands (events, commands, aggregates)", "type": "story", "status": "done", "createdAt": "2025-11-15T12:16:21.432Z", "updatedAt": "2025-11-16T00:47:21.999Z", "description": "Implement fspec commands: add-domain-event, add-command, add-aggregate for capturing Event Storm sticky notes", "parent": "EXMAP-004", "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-15T23:10:09.499Z" }, { "state": "testing", "timestamp": "2025-11-15T23:20:10.586Z" }, { "state": "implementing", "timestamp": "2025-11-16T00:26:30.263Z" }, { "state": "validating", "timestamp": "2025-11-16T00:26:36.178Z" }, { "state": "implementing", "timestamp": "2025-11-16T00:31:06.895Z" }, { "state": "validating", "timestamp": "2025-11-16T00:43:20.775Z" }, { "state": "done", "timestamp": "2025-11-16T00:47:22.000Z" } ], "userStory": { "role": "AI agent performing Event Storming during specifying phase", "action": "add domain events, commands, and aggregates using fspec CLI", "benefit": "I capture Event Storm sticky notes in structured format for tag discovery and traceability" }, "rules": [ { "id": 0, "text": "Commands: add-domain-event, add-command, add-aggregate take work-unit-id and text as required arguments", "deleted": false, "createdAt": "2025-11-15T23:10:30.054Z" }, { "id": 1, "text": "Each command creates item with auto-incremented ID, type field, color (orange/blue/yellow), deleted=false, createdAt timestamp", "deleted": false, "createdAt": "2025-11-15T23:10:35.955Z" }, { "id": 2, "text": "Commands initialize eventStorm section if not present with level='process_modeling', items=[], nextItemId=0", "deleted": false, "createdAt": "2025-11-15T23:10:41.479Z" }, { "id": 3, "text": "add-command supports --actor flag for who executes command, add-aggregate supports --responsibilities flag (comma-separated list)", "deleted": false, "createdAt": "2025-11-15T23:10:47.369Z" }, { "id": 4, "text": "All commands support --timestamp flag for timeline visualization (milliseconds), --bounded-context for domain association", "deleted": false, "createdAt": "2025-11-15T23:10:53.696Z" }, { "id": 5, "text": "Commands must validate work unit exists and is not in done/blocked state before adding Event Storm items", "deleted": false, "createdAt": "2025-11-15T23:10:59.386Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "Run 'fspec add-domain-event AUTH-001 \"UserRegistered\"' creates event with id=0, type='event', color='orange', text='UserRegistered'", "deleted": false, "createdAt": "2025-11-15T23:11:06.386Z" }, { "id": 1, "text": "Run 'fspec add-command AUTH-001 \"AuthenticateUser\" --actor \"User\"' creates command with id=1, type='command', color='blue', actor='User'", "deleted": false, "createdAt": "2025-11-15T23:11:11.844Z" }, { "id": 2, "text": "Run 'fspec add-aggregate AUTH-001 \"User\" --responsibilities \"Authentication,Profile management\"' creates aggregate with id=2, type='aggregate', color='yellow', responsibilities=['Authentication','Profile management']", "deleted": false, "createdAt": "2025-11-15T23:11:17.650Z" }, { "id": 3, "text": "First command on work unit initializes eventStorm section, subsequent commands append to items array and increment nextItemId", "deleted": false, "createdAt": "2025-11-15T23:11:24.541Z" } ], "nextExampleId": 4, "estimate": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-16T00:47:21.999Z" }, "EXMAP-007": { "id": "EXMAP-007", "title": "Event Storm artifact commands (policies, hotspots, external systems)", "type": "story", "status": "done", "createdAt": "2025-11-15T12:16:27.272Z", "updatedAt": "2025-11-16T02:30:56.524Z", "description": "Implement fspec commands: add-policy, add-hotspot, add-external-system, add-bounded-context for complete Event Storm capture", "parent": "EXMAP-004", "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-16T01:49:39.968Z" }, { "state": "testing", "timestamp": "2025-11-16T02:15:30.239Z" }, { "state": "implementing", "timestamp": "2025-11-16T02:18:10.511Z" }, { "state": "validating", "timestamp": "2025-11-16T02:25:58.388Z" }, { "state": "done", "timestamp": "2025-11-16T02:30:56.524Z" } ], "userStory": { "role": "AI agent or developer conducting Event Storming", "action": "capture policies, hotspots, external systems, and bounded contexts", "benefit": "I can document complete Event Storm sessions with all artifact types" }, "rules": [ { "id": 0, "text": "Commands add-policy, add-hotspot, add-external-system, add-bounded-context take work-unit-id and text as required arguments", "deleted": false, "createdAt": "2025-11-16T01:50:32.179Z" }, { "id": 1, "text": "Each command creates item with auto-incremented ID, type field, appropriate color code, deleted=false, createdAt timestamp", "deleted": false, "createdAt": "2025-11-16T01:50:33.871Z" }, { "id": 2, "text": "Commands initialize eventStorm section if not present with level='process_modeling', items=[], nextItemId=0", "deleted": false, "createdAt": "2025-11-16T01:50:35.362Z" }, { "id": 3, "text": "All commands support --timestamp flag for timeline visualization (milliseconds) and --bounded-context flag for domain association", "deleted": false, "createdAt": "2025-11-16T01:50:37.433Z" }, { "id": 4, "text": "Commands must validate work unit exists and is not in done/blocked state before adding Event Storm items", "deleted": false, "createdAt": "2025-11-16T01:50:38.848Z" }, { "id": 5, "text": "Color codes: Policies='purple', Hotspots='red', External Systems='pink', Bounded Contexts (default to 'purple' if not specified in Event Storming standard)", "deleted": false, "createdAt": "2025-11-16T01:50:45.604Z" }, { "id": 6, "text": "Yes, support --when and --then flags to capture policy rule (event triggering it and resulting command)", "deleted": false, "createdAt": "2025-11-16T02:04:21.969Z" }, { "id": 7, "text": "Yes, support --concern flag to capture description of risk/uncertainty/problem", "deleted": false, "createdAt": "2025-11-16T02:04:23.289Z" }, { "id": 8, "text": "Yes, support --type flag with values: REST_API, MESSAGE_QUEUE, DATABASE, THIRD_PARTY_SERVICE, FILE_SYSTEM", "deleted": false, "createdAt": "2025-11-16T02:04:24.727Z" }, { "id": 9, "text": "Yes, support --description flag to capture scope (what the bounded context covers)", "deleted": false, "createdAt": "2025-11-16T02:04:26.436Z" }, { "id": 10, "text": "Use null/undefined for color since bounded contexts are conceptual boundaries, not sticky note artifacts", "deleted": false, "createdAt": "2025-11-16T02:04:27.972Z" } ], "nextRuleId": 11, "questions": [ { "id": 0, "text": "@human: Should add-policy command support --when and --then flags to capture the policy rule (when X happens, then Y should occur)?", "deleted": false, "createdAt": "2025-11-16T01:50:59.507Z", "selected": true, "answer": "Yes, support --when and --then flags to capture policy rule (event triggering it and resulting command)" }, { "id": 1, "text": "@human: Should add-hotspot command support a --concern or --question flag to capture what needs clarification or what the risk/issue is?", "deleted": false, "createdAt": "2025-11-16T01:51:00.854Z", "selected": true, "answer": "Yes, support --concern flag to capture description of risk/uncertainty/problem" }, { "id": 2, "text": "@human: Should add-external-system command support --type or --protocol flags to describe the external system integration (e.g., REST API, Message Queue, Database)?", "deleted": false, "createdAt": "2025-11-16T01:51:02.292Z", "selected": true, "answer": "Yes, support --type flag with values: REST_API, MESSAGE_QUEUE, DATABASE, THIRD_PARTY_SERVICE, FILE_SYSTEM" }, { "id": 3, "text": "@human: Should add-bounded-context command support --description and/or --responsibilities flags similar to add-aggregate?", "deleted": false, "createdAt": "2025-11-16T01:51:03.795Z", "selected": true, "answer": "Yes, support --description flag to capture scope (what the bounded context covers)" }, { "id": 4, "text": "@human: What color should bounded contexts use? The Event Storming standard doesn't specify a color for bounded contexts - should we use a specific color or allow --color flag?", "deleted": false, "createdAt": "2025-11-16T01:51:05.512Z", "selected": true, "answer": "Use null/undefined for color since bounded contexts are conceptual boundaries, not sticky note artifacts" } ], "nextQuestionId": 5, "attachments": [ "spec/attachments/EXMAP-007/perplexity-event-storming-artifacts-2025-11-16.md", "spec/attachments/EXMAP-007/ast-research-event-storm-commands-2025-11-16.md" ], "examples": [ { "id": 0, "text": "Run 'fspec add-policy AUTH-001 \"Send welcome email\" --when \"UserRegistered\" --then \"SendWelcomeEmail\"' creates policy with id=0, type='policy', color='purple', when='UserRegistered', then='SendWelcomeEmail'", "deleted": false, "createdAt": "2025-11-16T02:04:41.898Z" }, { "id": 1, "text": "Run 'fspec add-hotspot AUTH-001 \"Password reset token expiration\" --concern \"Unclear timeout duration\"' creates hotspot with id=1, type='hotspot', color='red', concern='Unclear timeout duration'", "deleted": false, "createdAt": "2025-11-16T02:04:43.614Z" }, { "id": 2, "text": "Run 'fspec add-bounded-context AUTH-001 \"User Management\" --description \"Handles user registration, authentication, and profile management\"' creates bounded context with id=3, type='bounded_context', color=null, description='Handles user registration...'", "deleted": false, "createdAt": "2025-11-16T02:04:47.922Z" }, { "id": 3, "text": "Commands initialize eventStorm section if not present, then append to items array and increment nextItemId counter", "deleted": false, "createdAt": "2025-11-16T02:04:49.416Z" }, { "id": 4, "text": "All commands support optional --timestamp and --bounded-context flags for timeline visualization and domain association", "deleted": false, "createdAt": "2025-11-16T02:04:50.992Z" }, { "id": 5, "text": "Run fspec add-external-system AUTH-001 \"OAuth2Provider\" --type REST_API creates external system with id=2, type=external_system, color=pink, integrationType=REST_API", "deleted": false, "createdAt": "2025-11-16T02:04:56.501Z" } ], "nextExampleId": 6, "estimate": 5, "architectureNotes": [ { "id": 0, "text": "Implementation: Extends EXMAP-006 pattern with 4 new commands (add-policy, add-hotspot, add-external-system, add-bounded-context). Uses same data model (stable IDs, soft-delete, TypeScript discriminated unions). Each command has specific flags based on Event Storming research.", "deleted": false, "createdAt": "2025-11-16T02:11:29.836Z" } ], "nextNoteId": 1, "updated": "2025-11-16T02:30:56.524Z" }, "EXMAP-010": { "id": "EXMAP-010", "title": "Big Picture Event Storm in foundation.json", "type": "story", "status": "done", "createdAt": "2025-11-15T12:16:45.145Z", "updatedAt": "2025-11-16T05:21:01.369Z", "description": "Add eventStorm section to foundation.json for storing foundation-level Big Picture Event Storming (bounded contexts, major aggregates, pivotal events)", "parent": "EXMAP-004", "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-16T05:01:22.260Z" }, { "state": "testing", "timestamp": "2025-11-16T05:10:16.275Z" }, { "state": "implementing", "timestamp": "2025-11-16T05:13:35.850Z" }, { "state": "validating", "timestamp": "2025-11-16T05:19:43.205Z" }, { "state": "done", "timestamp": "2025-11-16T05:21:01.370Z" } ], "attachments": [ "spec/attachments/EXMAP-010/exmap-010-ultrathinking-research.md", "spec/attachments/EXMAP-010/ast-research-foundation-types.md" ], "userStory": { "role": "AI agent performing Big Picture Event Storming", "action": "capture foundation-level bounded contexts, pivotal events, and major aggregates in foundation.json", "benefit": "I can understand the strategic domain structure before diving into tactical work units" }, "rules": [ { "id": 0, "text": "Foundation Event Storm must use level='big_picture' (not 'process_modeling' or 'software_design')", "deleted": false, "createdAt": "2025-11-16T05:08:03.684Z" }, { "id": 1, "text": "All Event Storm items must use same EventStormItem union type as work unit-level for consistency", "deleted": false, "createdAt": "2025-11-16T05:08:04.218Z" }, { "id": 2, "text": "Foundation Event Storm is OPTIONAL in foundation.json (not required for all projects)", "deleted": false, "createdAt": "2025-11-16T05:08:04.767Z" }, { "id": 3, "text": "Commands must NOT include semantic logic (tag suggestion, classification, inference) - zero-semantics principle", "deleted": false, "createdAt": "2025-11-16T05:08:05.334Z" }, { "id": 4, "text": "Deleted items (deleted=true) must be filtered out when showing Event Storm data", "deleted": false, "createdAt": "2025-11-16T05:08:05.873Z" }, { "id": 5, "text": "nextItemId must auto-increment for each new item to ensure stable IDs", "deleted": false, "createdAt": "2025-11-16T05:08:06.420Z" }, { "id": 6, "text": "Foundation Event Storm commands must use fileManager.transaction() for atomic updates", "deleted": false, "createdAt": "2025-11-16T05:08:06.972Z" } ], "nextRuleId": 7, "examples": [ { "id": 0, "text": "Add bounded context 'User Management' to foundation Event Storm → creates item with type='bounded_context', text='User Management', level='big_picture', deleted=false", "deleted": false, "createdAt": "2025-11-16T05:08:23.036Z" }, { "id": 1, "text": "Show foundation Event Storm filtered by type='bounded_context' → returns only bounded context items, excludes deleted items", "deleted": false, "createdAt": "2025-11-16T05:08:23.572Z" }, { "id": 2, "text": "Foundation.json has no eventStorm section → add-foundation-bounded-context initializes eventStorm with level='big_picture', items=[], nextItemId=1", "deleted": false, "createdAt": "2025-11-16T05:08:24.105Z" }, { "id": 3, "text": "Foundation Event Storm has 3 items, 1 deleted → show-foundation-event-storm returns 2 active items only", "deleted": false, "createdAt": "2025-11-16T05:08:24.652Z" } ], "nextExampleId": 4, "architectureNotes": [ { "id": 0, "text": "Implementation: Extend GenericFoundation type with optional eventStorm: FoundationEventStorm field. Use EventStormBase interface shared with work unit EventStorm. Commands: add-foundation-bounded-context, show-foundation-event-storm. Use fileManager.transaction() for atomic updates. Update generic-foundation.schema.json. NO semantic code - structural data only.", "deleted": false, "createdAt": "2025-11-16T05:08:33.427Z" } ], "nextNoteId": 1, "questions": [], "nextQuestionId": 0, "updated": "2025-11-16T05:21:01.369Z" }, "BUG-077": { "id": "BUG-077", "title": "Coverage validation missing for implementing→validating transition", "type": "bug", "status": "done", "createdAt": "2025-11-16T00:29:34.882Z", "updatedAt": "2025-11-16T00:47:36.407Z", "description": "System validates coverage only when moving to done, but should validate implementation coverage exists when moving from implementing to validating. Currently allows validating non-existent implementation.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-16T00:29:40.824Z" }, { "state": "testing", "timestamp": "2025-11-16T00:36:05.966Z" }, { "state": "implementing", "timestamp": "2025-11-16T00:37:44.510Z" }, { "state": "validating", "timestamp": "2025-11-16T00:47:30.027Z" }, { "state": "done", "timestamp": "2025-11-16T00:47:36.407Z" } ], "rules": [ { "id": 0, "text": "Step validation must check that validateSteps() actually validates @step comments exist in test file, not just that coverage file exists", "deleted": false, "createdAt": "2025-11-16T00:29:51.363Z" }, { "id": 1, "text": "validateTestStepDocstrings() currently passes if coverage file exists with test mappings, but doesn't verify @step comments", "deleted": false, "createdAt": "2025-11-16T00:29:52.905Z" }, { "id": 2, "text": "Coverage validation (checkCoverageCompleteness) should run when moving from implementing to validating, not just done", "deleted": false, "createdAt": "2025-11-16T00:32:11.675Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "EXMAP-006 moved from testing to implementing to validating without any @step comments in test file, validation should have blocked this", "deleted": false, "createdAt": "2025-11-16T00:29:54.386Z" }, { "id": 1, "text": "EXMAP-006 moved from implementing to validating without any implementation files linked in coverage, should have been blocked", "deleted": false, "createdAt": "2025-11-16T00:32:13.153Z" } ], "nextExampleId": 2, "userStory": { "role": "AI agent following ACDD workflow", "action": "move work unit from implementing to validating", "benefit": "system validates implementation exists before allowing validation phase" }, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-16T00:47:36.407Z" }, "EXMAP-011": { "id": "EXMAP-011", "title": "Show Event Storm data as JSON", "type": "story", "status": "done", "createdAt": "2025-11-16T04:37:30.470Z", "updatedAt": "2025-11-16T04:51:46.917Z", "description": "Expose Event Storm artifacts from work unit as queryable JSON structure for AI agent analysis", "epic": "example-driven-discovery", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-16T04:37:39.377Z" }, { "state": "testing", "timestamp": "2025-11-16T04:43:49.675Z" }, { "state": "implementing", "timestamp": "2025-11-16T04:45:33.391Z" }, { "state": "validating", "timestamp": "2025-11-16T04:51:16.108Z" }, { "state": "done", "timestamp": "2025-11-16T04:51:46.918Z" } ], "userStory": { "role": "AI agent analyzing Event Storm sessions", "action": "query Event Storm artifacts as structured JSON data", "benefit": "I can use my language understanding to interpret domain semantics and suggest appropriate tags" }, "rules": [ { "id": 0, "text": "Command must output Event Storm data as valid JSON to stdout", "deleted": false, "createdAt": "2025-11-16T04:37:54.412Z" }, { "id": 1, "text": "Must include all Event Storm item types: bounded_context, aggregate, event, command, policy, hotspot, external_system", "deleted": false, "createdAt": "2025-11-16T04:37:56.159Z" }, { "id": 2, "text": "Must filter out deleted items (deleted: true)", "deleted": false, "createdAt": "2025-11-16T04:37:57.873Z" }, { "id": 3, "text": "Output structure must match EventStorm type from types/index.ts", "deleted": false, "createdAt": "2025-11-16T04:37:59.523Z" }, { "id": 4, "text": "Must fail gracefully if work unit has no Event Storm data", "deleted": false, "createdAt": "2025-11-16T04:38:01.337Z" }, { "id": 5, "text": "No semantic interpretation - just return raw structural data", "deleted": false, "createdAt": "2025-11-16T04:38:03.062Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "Work unit AUTH-001 with 3 events (UserLoggedIn, UserRegistered, PasswordChanged) outputs JSON array with 3 event objects", "deleted": false, "createdAt": "2025-11-16T04:38:16.911Z" }, { "id": 1, "text": "Work unit with bounded context 'User Management' outputs JSON with bounded_context object", "deleted": false, "createdAt": "2025-11-16T04:38:18.817Z" }, { "id": 2, "text": "Work unit with no Event Storm data returns error message", "deleted": false, "createdAt": "2025-11-16T04:38:20.696Z" }, { "id": 3, "text": "Work unit with deleted items (deleted: true) excludes them from output", "deleted": false, "createdAt": "2025-11-16T04:38:22.403Z" } ], "nextExampleId": 4, "architectureNotes": [ { "id": 0, "text": "Implementation: Read work-units.json, extract eventStorm.items array, filter deleted=false, output as JSON. Use existing WorkUnitsData and EventStorm types. Command: fspec show-event-storm <work-unit-id> [--format=json|pretty]", "deleted": false, "createdAt": "2025-11-16T04:38:24.035Z" } ], "nextNoteId": 1, "attachments": [ "spec/attachments/EXMAP-011/ast-research-event-storm-types.md" ], "questions": [], "nextQuestionId": 0, "updated": "2025-11-16T04:51:46.917Z" }, "EXMAP-012": { "id": "EXMAP-012", "title": "Complete Big Picture Event Storm Schema Integration", "type": "story", "status": "done", "createdAt": "2025-11-16T06:15:15.532Z", "updatedAt": "2025-11-16T06:45:04.138Z", "children": [], "attachments": [ "spec/attachments/EXMAP-012/exmap-010-integration-analysis.md", "spec/attachments/EXMAP-012/generic-foundation-schema-research.json", "spec/attachments/EXMAP-012/json-ast-support-fix.md", "spec/attachments/EXMAP-012/ast-research-schema-properties.json" ], "userStory": { "role": "developer maintaining fspec foundation system", "action": "have Event Storm data validated by JSON Schema during foundation discovery and regeneration", "benefit": "invalid Event Storm structures are caught early and foundation integrity is maintained" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-16T06:17:29.338Z" }, { "state": "testing", "timestamp": "2025-11-16T06:30:05.093Z" }, { "state": "implementing", "timestamp": "2025-11-16T06:38:12.537Z" }, { "state": "validating", "timestamp": "2025-11-16T06:44:47.121Z" }, { "state": "done", "timestamp": "2025-11-16T06:45:04.138Z" } ], "rules": [ { "id": 0, "text": "eventStorm property must be defined in generic-foundation.schema.json as optional field", "deleted": false, "createdAt": "2025-11-16T06:17:40.528Z" }, { "id": 1, "text": "eventStorm.level must be constrained to 'big_picture' constant in schema", "deleted": false, "createdAt": "2025-11-16T06:17:41.154Z" }, { "id": 2, "text": "eventStormItem discriminated union must validate all 7 item types (event, command, aggregate, policy, hotspot, external_system, bounded_context)", "deleted": false, "createdAt": "2025-11-16T06:17:41.777Z" }, { "id": 3, "text": "Schema validation must enforce type-specific fields (e.g., actor for commands, responsibilities for aggregates)", "deleted": false, "createdAt": "2025-11-16T06:17:42.404Z" }, { "id": 4, "text": "discover-foundation --finalize must validate eventStorm structure if present in draft", "deleted": false, "createdAt": "2025-11-16T06:17:43.038Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Foundation with Event Storm containing bounded context validates successfully when level='big_picture'", "deleted": false, "createdAt": "2025-11-16T06:17:51.996Z" }, { "id": 1, "text": "Schema validation fails when eventStorm.level='process_modeling' (invalid for foundation)", "deleted": false, "createdAt": "2025-11-16T06:17:53.494Z" }, { "id": 2, "text": "EventStormCommand item with actor field passes validation", "deleted": false, "createdAt": "2025-11-16T06:17:55.037Z" }, { "id": 3, "text": "EventStormBoundedContext item with null color passes validation (conceptual boundary, not sticky note)", "deleted": false, "createdAt": "2025-11-16T06:17:56.475Z" }, { "id": 4, "text": "discover-foundation --finalize rejects draft with invalid Event Storm item type", "deleted": false, "createdAt": "2025-11-16T06:17:57.990Z" } ], "nextExampleId": 5, "estimate": 3, "architectureNotes": [ { "id": 0, "text": "Update src/schemas/generic-foundation.schema.json to add eventStorm property with level='big_picture' constraint. Define eventStormItem discriminated union using oneOf pattern matching TypeScript EventStormItem union (7 types). Reuse validation pattern from existing schema definitions. Integration via validateGenericFoundationObject() and discover-foundation --finalize flow.", "deleted": false, "createdAt": "2025-11-16T06:19:41.877Z" } ], "nextNoteId": 1, "questions": [], "nextQuestionId": 0, "updated": "2025-11-16T06:45:04.138Z" }, "EXMAP-014": { "id": "EXMAP-014", "title": "Generate Example Mapping from Event Storm", "type": "story", "status": "done", "createdAt": "2025-11-16T22:42:15.008Z", "updatedAt": "2025-11-16T22:54:21.476Z", "description": "Implement generate-example-mapping-from-event-storm command that derives rules from policies, examples from events, and questions from hotspots", "epic": "example-driven-discovery", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-16T22:42:28.757Z" }, { "state": "testing", "timestamp": "2025-11-16T22:44:02.010Z" }, { "state": "implementing", "timestamp": "2025-11-16T22:46:39.984Z" }, { "state": "validating", "timestamp": "2025-11-16T22:46:45.557Z" }, { "state": "done", "timestamp": "2025-11-16T22:54:21.476Z" } ], "userStory": { "role": "AI agent performing Event Storming", "action": "automatically generate Example Mapping from Event Storm artifacts", "benefit": "I reduce manual work and ensure Event Storm knowledge flows to acceptance criteria" }, "rules": [ { "id": 0, "text": "Command must derive business rules from Event Storm policies by combining when/then fields into rule text", "deleted": false, "createdAt": "2025-11-16T22:42:37.011Z" }, { "id": 1, "text": "Command must derive scenario examples from domain events by converting PascalCase event names to natural language", "deleted": false, "createdAt": "2025-11-16T22:42:37.561Z" }, { "id": 2, "text": "Command must derive questions for humans from hotspot concerns", "deleted": false, "createdAt": "2025-11-16T22:42:38.121Z" }, { "id": 3, "text": "Command must skip deleted Event Storm items (deleted: true)", "deleted": false, "createdAt": "2025-11-16T22:42:38.678Z" }, { "id": 4, "text": "Generated rules, examples, and questions must include timestamps and proper ID sequencing", "deleted": false, "createdAt": "2025-11-16T22:42:39.223Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Policy 'when UserRegistered then SendWelcomeEmail' generates rule 'System must send welcome email after user registration'", "deleted": false, "createdAt": "2025-11-16T22:42:45.983Z" }, { "id": 1, "text": "Event 'UserAuthenticated' generates example 'User user authenticated and is logged in'", "deleted": false, "createdAt": "2025-11-16T22:42:46.580Z" }, { "id": 2, "text": "Hotspot with concern 'Unclear password reset timeout' generates question '@human: What should unclear password reset timeout be?'", "deleted": false, "createdAt": "2025-11-16T22:42:47.139Z" } ], "nextExampleId": 3, "architectureNotes": [ { "id": 0, "text": "Implements Gap 1 from EXMAP-013 analysis. Uses fileManager.transaction for atomic updates to work-units.json. Processes Event Storm items to derive Example Mapping (policies→rules, events→examples, hotspots→questions). Follows pattern from existing Event Storm commands (add-domain-event, add-command, etc.)", "deleted": false, "createdAt": "2025-11-16T22:43:47.096Z" } ], "nextNoteId": 1, "attachments": [ "spec/attachments/EXMAP-014/ast-research-event-storm-commands.json" ], "questions": [], "nextQuestionId": 0, "updated": "2025-11-16T22:54:21.476Z" }, "EXMAP-015": { "id": "EXMAP-015", "title": "Wire up comprehensive help for all Event Storm commands", "type": "story", "status": "done", "createdAt": "2025-11-16T23:18:24.211Z", "updatedAt": "2025-11-16T23:36:09.091Z", "description": "Add dedicated help files (*-help.ts) for all 7 Event Storm commands and integrate them into src/help.ts under the discovery group. Event Storm commands currently lack AI-optimized help documentation.", "epic": "example-driven-discovery", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-16T23:18:33.021Z" }, { "state": "testing", "timestamp": "2025-11-16T23:24:29.186Z" }, { "state": "implementing", "timestamp": "2025-11-16T23:26:00.559Z" }, { "state": "validating", "timestamp": "2025-11-16T23:31:40.591Z" }, { "state": "done", "timestamp": "2025-11-16T23:36:09.092Z" } ], "userStory": { "role": "AI agent using fspec", "action": "access comprehensive help for Event Storm commands", "benefit": "I can understand how to use Event Storm features without reading source code" }, "rules": [ { "id": 0, "text": "All 7 Event Storm commands must have dedicated *-help.ts files following existing help file patterns", "deleted": false, "createdAt": "2025-11-16T23:18:44.688Z" }, { "id": 1, "text": "Help files must include AI-optimized sections: WHEN TO USE, PREREQUISITES, TYPICAL WORKFLOW, COMMON ERRORS, COMMON PATTERNS", "deleted": false, "createdAt": "2025-11-16T23:18:49.418Z" }, { "id": 2, "text": "Event Storm commands must be added to src/help.ts under the discovery group section", "deleted": false, "createdAt": "2025-11-16T23:18:54.386Z" }, { "id": 3, "text": "Help content must cover all 7 Event Storm commands: add-command, add-domain-event, add-hotspot, add-policy, generate-example-mapping-from-event-storm, show-event-storm, show-foundation-event-storm", "deleted": false, "createdAt": "2025-11-16T23:18:59.974Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Running 'fspec add-domain-event --help' shows comprehensive usage with examples and AI-optimized sections", "deleted": false, "createdAt": "2025-11-16T23:19:04.795Z" }, { "id": 1, "text": "Running 'fspec help discovery' displays Event Storm commands section with add-domain-event, add-command, add-policy, add-hotspot, show-event-storm, show-foundation-event-storm, generate-example-mapping-from-event-storm", "deleted": false, "createdAt": "2025-11-16T23:19:09.649Z" }, { "id": 2, "text": "File src/commands/generate-example-mapping-from-event-storm-help.ts exists and exports getGenerateExampleMappingFromEventStormHelp function", "deleted": false, "createdAt": "2025-11-16T23:19:14.201Z" } ], "nextExampleId": 3, "estimate": 8, "architectureNotes": [ { "id": 0, "text": "Help files follow the pattern in src/commands/generate-scenarios-help.ts. Each exports a function returning formatted help text with sections for description, usage, AI-optimized guidance, and examples. Integration requires adding commands to displayDiscoveryHelp() in src/help.ts under an EVENT STORM section after existing Example Mapping commands.", "deleted": false, "createdAt": "2025-11-16T23:21:36.740Z" } ], "nextNoteId": 1, "attachments": [ "spec/attachments/EXMAP-015/ast-research-help-file-pattern.json" ], "questions": [], "nextQuestionId": 0, "updated": "2025-11-16T23:36:09.091Z" }, "HELP-006": { "id": "HELP-006", "title": "Fix help formatter option name rendering and commonErrors property mismatch", "type": "bug", "status": "done", "createdAt": "2025-11-16T23:39:01.898Z", "updatedAt": "2025-11-16T23:47:35.613Z", "description": "During EXMAP-015 review, discovered two issues: (1) Option names render as 'undefined' in help output instead of showing flag names like '--timestamp <ms>', and (2) help files use 'solution' property but interface expects 'fix' property in commonErrors array.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-16T23:39:07.955Z" }, { "state": "testing", "timestamp": "2025-11-16T23:41:52.366Z" }, { "state": "implementing", "timestamp": "2025-11-16T23:43:23.642Z" }, { "state": "validating", "timestamp": "2025-11-16T23:46:07.251Z" }, { "state": "done", "timestamp": "2025-11-16T23:47:35.613Z" } ], "userStory": { "role": "developer viewing help for Event Storm commands", "action": "see properly formatted option names in help output", "benefit": "I can understand what flags are available without seeing 'undefined'" }, "rules": [ { "id": 0, "text": "Option names in help output must show the actual flag name (e.g., '--timestamp <ms>'), not 'undefined'", "deleted": false, "createdAt": "2025-11-16T23:39:24.087Z" }, { "id": 1, "text": "CommandHelpConfig commonErrors array should use 'fix' property consistently (not 'solution')", "deleted": false, "createdAt": "2025-11-16T23:39:24.629Z" }, { "id": 2, "text": "Help formatter must parse option.name field correctly to extract flag names", "deleted": false, "createdAt": "2025-11-16T23:39:25.171Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Running 'fspec add-domain-event --help' shows OPTIONS section with '--timestamp <ms>' and '--bounded-context <context>' (not 'undefined')", "deleted": false, "createdAt": "2025-11-16T23:39:32.516Z" }, { "id": 1, "text": "All Event Storm help files use 'fix' property in commonErrors, not 'solution'", "deleted": false, "createdAt": "2025-11-16T23:39:33.071Z" }, { "id": 2, "text": "Help formatter extracts flag name from option.name using regex or string parsing", "deleted": false, "createdAt": "2025-11-16T23:39:33.624Z" } ], "nextExampleId": 3, "attachments": [ "spec/attachments/HELP-006/ast-research-help-formatter-options.json" ], "architectureNotes": [ { "id": 0, "text": "Fix requires two changes: (1) Update all 7 Event Storm help files to use 'flag' property instead of 'name' in options array, matching CommandOption interface. (2) Update commonErrors to use 'fix' property instead of 'solution'. Interface is in src/utils/help-formatter.ts. No formatter changes needed - help files are using wrong property names.", "deleted": false, "createdAt": "2025-11-16T23:40:44.237Z" } ], "nextNoteId": 1, "estimate": 2, "questions": [], "nextQuestionId": 0, "updated": "2025-11-16T23:47:35.613Z" }, "EXMAP-016": { "id": "EXMAP-016", "title": "Complete Event Storm interactive workflow with Example Mapping integration", "type": "story", "status": "done", "createdAt": "2025-11-17T00:37:42.612Z", "updatedAt": "2025-11-17T01:27:57.294Z", "description": "Implement guided Event Storm sessions with automatic detection, system-reminders, and seamless Example Mapping integration", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T00:37:52.614Z" }, { "state": "testing", "timestamp": "2025-11-17T00:57:46.537Z" }, { "state": "implementing", "timestamp": "2025-11-17T01:05:01.092Z" }, { "state": "validating", "timestamp": "2025-11-17T01:23:00.178Z" }, { "state": "done", "timestamp": "2025-11-17T01:27:57.294Z" } ], "userStory": { "role": "AI agent working with fspec", "action": "perform Event Storm discovery interactively with automatic detection and guidance", "benefit": "I understand domain complexity before Example Mapping and write better specifications" }, "rules": [ { "id": 0, "text": "Event Storm must have an interactive guided workflow like discover-foundation and Example Mapping (step-by-step with system-reminders)", "deleted": false, "createdAt": "2025-11-17T00:38:15.910Z" }, { "id": 1, "text": "System must automatically detect WHEN Event Storm is needed based on work unit complexity (like Example Mapping is triggered for specifying state)", "deleted": false, "createdAt": "2025-11-17T00:38:17.737Z" }, { "id": 2, "text": "Event Storm artifacts (policies, events, hotspots) must automatically pipe into Example Mapping using generate-example-mapping-from-event-storm command", "deleted": false, "createdAt": "2025-11-17T00:38:19.936Z" }, { "id": 3, "text": "Event Storm guidance must be agent-aware (detect Claude Code vs Cursor) like discover-foundation uses getAgentConfig", "deleted": false, "createdAt": "2025-11-17T00:38:23.112Z" }, { "id": 4, "text": "CRITICAL: NO semantic code understanding allowed - fspec uses only AST/syntax analysis, file operations, and explicit human input", "deleted": false, "createdAt": "2025-11-17T00:39:31.402Z" }, { "id": 5, "text": "Event Storm is a HUMAN-DRIVEN collaborative workshop - AI facilitates but does NOT infer domain knowledge from code semantics", "deleted": false, "createdAt": "2025-11-17T00:39:32.836Z" }, { "id": 6, "text": "ABSOLUTELY NO semantic code - fspec relies on AI responses and tool calling with guidance and AST/research tools to help AI figure things out", "deleted": false, "createdAt": "2025-11-17T00:41:24.726Z" }, { "id": 7, "text": "ABSOLUTELY NO heuristics - Leave it up to AI to interactively figure out if Event Storm is needed. Ask AI if it's appropriate for what needs to be written/done. Do this interactively using guidance, same way other interactive commands work (fspec review, fspec reverse)", "deleted": false, "createdAt": "2025-11-17T00:42:47.753Z" }, { "id": 8, "text": "Yes, manual opt-in command 'fspec discover-event-storm <work-unit-id>' - BUT the critical part is CRYSTAL CLEAR GUIDANCE that makes AI understand WHEN to run it and WHY. Guidance must prevent AI from skipping this valuable discovery step when appropriate. Use ULTRATHINK prompts in guidance to make AI pause and consider if Event Storm would help before jumping to Example Mapping.", "deleted": false, "createdAt": "2025-11-17T00:46:45.452Z" }, { "id": 9, "text": "System-reminder when moving to specifying state that prompts AI to ASSESS domain complexity with self-assessment questions (Do you understand core domain events? Are commands/policies clear? Significant domain complexity?). Makes AI CONSCIOUSLY CHOOSE between: (1) Run Event Storm FIRST then transform to Example Mapping, or (2) Skip Event Storm go directly to Example Mapping. Uses ULTRATHINK-style prompts to prevent skipping. Shows flow: Event Storm → generate-example-mapping-from-event-storm → Example Mapping → Scenarios. CRITICAL: Include concrete EXAMPLES in guidance showing when Event Storm helped vs when it was unnecessary.", "deleted": false, "createdAt": "2025-11-17T00:49:05.867Z" }, { "id": 10, "text": "Different pattern from discover-foundation - use free-form pattern like Example Mapping. Command 'fspec discover-event-storm <work-unit-id>' emits comprehensive guidance showing conversation pattern with examples. AI uses existing commands (add-domain-event, add-command, add-policy, add-hotspot) freely in whatever order conversation goes. Explains flow: Events → Commands → Policies → Hotspots. Shows when to stop (like Example Mapping stop criteria). When complete, AI runs generate-example-mapping-from-event-storm to transform artifacts. NO draft/finalize - just guidance + existing tools.", "deleted": false, "createdAt": "2025-11-17T00:50:29.082Z" }, { "id": 11, "text": "Create new section file src/utils/slashCommandSections/eventStorm.ts (similar to exampleMapping.ts) with comprehensive Event Storm guidance including examples", "deleted": false, "createdAt": "2025-11-17T00:56:17.997Z" }, { "id": 12, "text": "Import eventStorm section in slashCommandTemplate.ts and add to getCompleteWorkflowDocumentation() array (appears in bootstrap output)", "deleted": false, "createdAt": "2025-11-17T00:56:22.903Z" } ], "nextRuleId": 13, "examples": [ { "id": 0, "text": "AI creates story with 13+ points → System emits reminder suggesting Event Storm → AI runs guided Event Storm session → Captures domain events, commands, policies → Transforms to Example Mapping → Generates scenarios", "deleted": false, "createdAt": "2025-11-17T00:38:37.996Z" }, { "id": 1, "text": "AI creates simple 2-point bug → System skips Event Storm suggestion → Goes directly to Example Mapping workflow", "deleted": false, "createdAt": "2025-11-17T00:38:39.529Z" }, { "id": 2, "text": "AI performs Event Storm → Adds domain event UserRegistered → System chains with prompt: 'Add related command or continue to next event?' → AI adds RegisterUser command → System chains to policies → Session completes → Artifacts visible in show-work-unit", "deleted": false, "createdAt": "2025-11-17T00:38:41.120Z" }, { "id": 3, "text": "AI uses bootstrap guidance → Sees Event Storm explanation → Understands ES → Example Mapping → Scenarios pipeline → Applies to complex feature", "deleted": false, "createdAt": "2025-11-17T00:38:46.211Z" }, { "id": 4, "text": "AI creates eventStorm.ts section file → Imports in slashCommandTemplate.ts → Section appears in bootstrap output → AI reads bootstrap → Sees Event Storm guidance with examples → Understands when to use Event Storm", "deleted": false, "createdAt": "2025-11-17T00:56:34.317Z" } ], "nextExampleId": 5, "questions": [ { "id": 0, "text": "@human: Should Event Storm guidance use semantic code understanding or stay with AST/syntax-only analysis like all other fspec tools?", "deleted": false, "createdAt": "2025-11-17T00:39:17.696Z", "selected": true, "answer": "ABSOLUTELY NO semantic code - fspec relies on AI responses and tool calling with guidance and AST/research tools to help AI figure things out" }, { "id": 1, "text": "@human: For automatic Event Storm detection, should we use simple heuristics (estimate > threshold, work unit type) or NO automatic detection at all?", "deleted": false, "createdAt": "2025-11-17T00:39:19.204Z", "selected": true, "answer": "ABSOLUTELY NO heuristics - Leave it up to AI to interactively figure out if Event Storm is needed. Ask AI if it's appropriate for what needs to be written/done. Do this interactively using guidance, same way other interactive commands work (fspec review, fspec reverse)" }, { "id": 2, "text": "@human: Should Event Storm be a manual opt-in workflow (fspec discover-event-storm) with guidance only, similar to how discover-foundation works?", "deleted": false, "createdAt": "2025-11-17T00:39:20.791Z", "selected": true, "answer": "Yes, manual opt-in command 'fspec discover-event-storm <work-unit-id>' - BUT the critical part is CRYSTAL CLEAR GUIDANCE that makes AI understand WHEN to run it and WHY. Guidance must prevent AI from skipping this valuable discovery step when appropriate. Use ULTRATHINK prompts in guidance to make AI pause and consider if Event Storm would help before jumping to Example Mapping." }, { "id": 3, "text": "@human: What triggers should suggest Event Storm? (1) Large estimates (13+ points)? (2) Specific work unit types? (3) Human request only? (4) Never auto-suggest?", "deleted": false, "createdAt": "2025-11-17T00:39:22.267Z", "selected": true, "answer": "System-reminder when moving to specifying state that prompts AI to ASSESS domain complexity with self-assessment questions (Do you understand core domain events? Are commands/policies clear? Significant domain complexity?). Makes AI CONSCIOUSLY CHOOSE between: (1) Run Event Storm FIRST then transform to Example Mapping, or (2) Skip Event Storm go directly to Example Mapping. Uses ULTRATHINK-style prompts to prevent skipping. Shows flow: Event Storm → generate-example-mapping-from-event-storm → Example Mapping → Scenarios. CRITICAL: Include concrete EXAMPLES in guidance showing when Event Storm helped vs when it was unnecessary." }, { "id": 4, "text": "@human: Should Event Storm workflow be similar to discover-foundation (draft → field-by-field prompting → finalize) or different pattern?", "deleted": false, "createdAt": "2025-11-17T00:39:23.837Z", "selected": true, "answer": "Different pattern from discover-foundation - use free-form pattern like Example Mapping. Command 'fspec discover-event-storm <work-unit-id>' emits comprehensive guidance showing conversation pattern with examples. AI uses existing commands (add-domain-event, add-command, add-policy, add-hotspot) freely in whatever order conversation goes. Explains flow: Events → Commands → Policies → Hotspots. Shows when to stop (like Example Mapping stop criteria). When complete, AI runs generate-example-mapping-from-event-storm to transform artifacts. NO draft/finalize - just guidance + existing tools." } ], "nextQuestionId": 5, "estimate": 13, "architectureNotes": [ { "id": 0, "text": "Create src/utils/slashCommandSections/eventStorm.ts modeled after exampleMapping.ts - exports getEventStormSection() returning markdown string with ULTRATHINK prompts, self-assessment questions, conversation examples, and command references", "deleted": false, "createdAt": "2025-11-17T00:57:16.697Z" }, { "id": 1, "text": "Modify src/utils/slashCommandTemplate.ts - import getEventStormSection, add to getCompleteWorkflowDocumentation() array between bootstrapFoundation and exampleMapping for logical flow", "deleted": false, "createdAt": "2025-11-17T00:57:18.783Z" }, { "id": 2, "text": "Create src/commands/discover-event-storm.ts - command emits system-reminder with guidance, takes work-unit-id, validates work unit exists and is in specifying status, outputs guidance from eventStorm section", "deleted": false, "createdAt": "2025-11-17T00:57:20.391Z" }, { "id": 3, "text": "Modify src/commands/update-work-unit-status.ts - when transitioning to specifying status, emit system-reminder with Event Storm assessment questions (self-assessment pattern), present conscious choice between Event Storm or Example Mapping, include examples from guidance", "deleted": false, "createdAt": "2025-11-17T00:57:22.033Z" }, { "id": 4, "text": "Use getAgentConfig() in system-reminder to detect Claude Code vs Cursor and provide agent-aware prompts (ULTRATHINK for Claude Code, simpler prompts for others)", "deleted": false, "createdAt": "2025-11-17T00:57:23.682Z" } ], "nextNoteId": 5, "attachments": [ "spec/attachments/EXMAP-016/ast-research-example-mapping-pattern.json" ], "updated": "2025-11-17T01:27:57.294Z" }, "FOUND-013": { "id": "FOUND-013", "title": "Auto-create Big Picture Event Storming work unit after foundation finalization", "type": "story", "status": "done", "createdAt": "2025-11-17T02:26:30.387Z", "updatedAt": "2025-11-17T03:00:05.991Z", "description": "When discover-foundation --finalize completes successfully, automatically create a new work unit in backlog status that prompts AI to conduct Big Picture Event Storming. The work unit should have clear description explaining it should use existing foundation Event Storm commands (add-foundation-bounded-context, add-aggregate-to-foundation, add-domain-event-to-foundation, show-foundation-event-storm) to populate the foundation.json eventStorm field.", "children": [], "attachments": [ "spec/attachments/FOUND-013/implementation-plan.md", "spec/attachments/FOUND-013/ast-research-discover-foundation.md" ], "dependsOn": [ "FOUND-014" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T02:49:31.375Z" }, { "state": "testing", "timestamp": "2025-11-17T02:51:48.235Z" }, { "state": "implementing", "timestamp": "2025-11-17T02:54:47.264Z" }, { "state": "validating", "timestamp": "2025-11-17T02:57:08.108Z" }, { "state": "done", "timestamp": "2025-11-17T03:00:05.992Z" } ], "userStory": { "role": "AI agent using fspec", "action": "be prompted to conduct Big Picture Event Storming after foundation discovery", "benefit": "I capture domain architecture in foundation.json eventStorm field" }, "rules": [ { "id": 0, "text": "Work unit is created ONLY when --finalize flag is used", "deleted": false, "createdAt": "2025-11-17T02:49:53.753Z" }, { "id": 1, "text": "Work unit is created ONLY when validation passes", "deleted": false, "createdAt": "2025-11-17T02:49:55.413Z" }, { "id": 2, "text": "Work unit ID uses FOUND prefix with next available number", "deleted": false, "createdAt": "2025-11-17T02:49:57.023Z" }, { "id": 3, "text": "Work unit description includes Event Storming commands and CLAUDE.md reference", "deleted": false, "createdAt": "2025-11-17T02:49:58.586Z" }, { "id": 4, "text": "Console output confirms work unit creation with ID and command to view details", "deleted": false, "createdAt": "2025-11-17T02:50:00.130Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User runs 'fspec discover-foundation --finalize', validation passes, work unit FOUND-XXX is created in backlog with Big Picture Event Storming guidance", "deleted": false, "createdAt": "2025-11-17T02:50:10.371Z" }, { "id": 1, "text": "User runs 'fspec discover-foundation' without --finalize flag, NO work unit is created", "deleted": false, "createdAt": "2025-11-17T02:50:12.020Z" }, { "id": 2, "text": "User runs 'fspec discover-foundation --finalize' but validation fails, NO work unit is created", "deleted": false, "createdAt": "2025-11-17T02:50:13.792Z" }, { "id": 3, "text": "AI agent reads created work unit description and sees list of foundation Event Storm commands (add-foundation-bounded-context, add-aggregate-to-foundation, etc.)", "deleted": false, "createdAt": "2025-11-17T02:50:15.375Z" } ], "nextExampleId": 4, "architectureNotes": [ { "id": 0, "text": "Modifies src/commands/discover-foundation.ts to auto-create work unit after successful finalization. Uses existing getNextWorkUnitId() utility for FOUND prefix ID generation. Work unit includes description with foundation Event Storm commands and CLAUDE.md reference. Implementation adds logic after foundation.json write (line ~300-350). No new commands needed - reuses existing Event Storming infrastructure (SOLID/DRY principles).", "deleted": false, "createdAt": "2025-11-17T02:50:49.146Z" } ], "nextNoteId": 1, "questions": [], "nextQuestionId": 0, "updated": "2025-11-17T03:00:05.991Z" }, "FOUND-014": { "id": "FOUND-014", "title": "Update CLAUDE.md with Big Picture Event Storming workflow documentation", "type": "story", "status": "done", "createdAt": "2025-11-17T02:26:37.003Z", "updatedAt": "2025-11-17T02:48:20.193Z", "description": "Add section to spec/CLAUDE.md explaining that after foundation discovery, AI should conduct Big Picture Event Storming to capture bounded contexts, aggregates, and domain events. Include workflow steps, commands to use, and explain this populates foundation.json eventStorm field which is used for tag ontology generation and domain architecture visualization.", "children": [], "attachments": [ "spec/attachments/FOUND-014/implementation-plan.md", "spec/attachments/FOUND-014/ast-research-event-storm-section.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T02:31:44.445Z" }, { "state": "testing", "timestamp": "2025-11-17T02:36:49.072Z" }, { "state": "implementing", "timestamp": "2025-11-17T02:38:19.351Z" }, { "state": "validating", "timestamp": "2025-11-17T02:42:14.731Z" }, { "state": "done", "timestamp": "2025-11-17T02:48:20.193Z" } ], "userStory": { "role": "AI agent using fspec", "action": "understand when and how to conduct Big Picture Event Storming after foundation discovery", "benefit": "I can properly capture bounded contexts and domain architecture in foundation.json eventStorm field" }, "rules": [ { "id": 0, "text": "New section must be added to CLAUDE.md after Step 1.5 (Bootstrap Foundation) and before Step 1.6 (Event Storm - Work Unit Level)", "deleted": false, "createdAt": "2025-11-17T02:32:08.540Z" }, { "id": 1, "text": "Section must explain difference between Big Picture (foundation-level) and Process Modeling (work unit-level) Event Storming", "deleted": false, "createdAt": "2025-11-17T02:32:13.877Z" }, { "id": 2, "text": "All foundation Event Storm commands must be documented with examples (add-foundation-bounded-context, add-aggregate-to-foundation, add-domain-event-to-foundation, add-command-to-foundation, show-foundation-event-storm)", "deleted": false, "createdAt": "2025-11-17T02:32:20.611Z" }, { "id": 3, "text": "Section must include table comparing foundation vs work unit Event Storming (scope, storage, commands, timing, output)", "deleted": false, "createdAt": "2025-11-17T02:32:26.670Z" }, { "id": 4, "text": "Section must explain integration with EXMAP-004 tag ontology generation (derive-tags-from-foundation command)", "deleted": false, "createdAt": "2025-11-17T02:32:32.528Z" }, { "id": 5, "text": "Existing Step 1.5 (Event Storm) must be renumbered to Step 1.6 to make room for new Step 1.5a (Big Picture Event Storm)", "deleted": false, "createdAt": "2025-11-17T02:32:37.692Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "AI agent completes discover-foundation --finalize, sees work unit FOUND-XXX in backlog, reads CLAUDE.md Step 1.5a, understands to conduct Big Picture Event Storm using foundation commands", "deleted": false, "createdAt": "2025-11-17T02:32:44.469Z" }, { "id": 1, "text": "Developer reads CLAUDE.md and sees clear table showing foundation Event Storm uses add-foundation-bounded-context while work unit Event Storm uses add-bounded-context with work unit ID", "deleted": false, "createdAt": "2025-11-17T02:32:51.265Z" }, { "id": 2, "text": "AI agent reads section explaining Big Picture Event Storm session flow, asks human for bounded contexts, uses add-foundation-bounded-context command, then populates aggregates and events per context", "deleted": false, "createdAt": "2025-11-17T02:32:57.004Z" }, { "id": 3, "text": "AI agent completes Big Picture Event Storm, reads CLAUDE.md integration section, runs derive-tags-from-foundation command to generate component tags from bounded contexts (EXMAP-004)", "deleted": false, "createdAt": "2025-11-17T02:33:02.686Z" } ], "nextExampleId": 4, "estimate": 2, "architectureNotes": [ { "id": 0, "text": "This feature requires editing spec/CLAUDE.md only - no code changes. Will insert new Step 1.5a section after existing Step 1.5 (Bootstrap Foundation). Existing Step 1.5 (Event Storm) will be renumbered to Step 1.6. Section will include: (1) explanation of Big Picture vs work unit Event Storming, (2) comparison table with 6 dimensions, (3) workflow steps with examples, (4) foundation Event Storm commands documentation, (5) EXMAP-004 integration guidance. Manual testing will verify markdown format, section placement, and command accuracy against implementation.", "deleted": false, "createdAt": "2025-11-17T02:34:50.566Z" } ], "nextNoteId": 1, "questions": [], "nextQuestionId": 0, "updated": "2025-11-17T02:48:20.193Z" }, "FOUND-015": { "id": "FOUND-015", "title": "Update bootstrap output with Big Picture Event Storming guidance", "type": "story", "status": "done", "createdAt": "2025-11-17T02:26:42.990Z", "updatedAt": "2025-11-17T03:14:45.546Z", "description": "Enhance fspec bootstrap command output to include guidance about Big Picture Event Storming workflow after foundation discovery. Add system-reminder explaining when and why to conduct foundation-level Event Storming, which commands to use, and how it integrates with tag ontology and domain architecture.", "children": [], "attachments": [ "spec/attachments/FOUND-015/implementation-plan.md", "spec/attachments/FOUND-015/ast-research-bootstrap-structure.json" ], "dependsOn": [ "FOUND-014", "FOUND-013" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T03:02:34.314Z" }, { "state": "testing", "timestamp": "2025-11-17T03:06:22.620Z" }, { "state": "implementing", "timestamp": "2025-11-17T03:08:08.441Z" }, { "state": "validating", "timestamp": "2025-11-17T03:09:35.754Z" }, { "state": "done", "timestamp": "2025-11-17T03:14:45.546Z" } ], "userStory": { "role": "AI agent using fspec", "action": "be reminded to conduct Big Picture Event Storming when foundation exists but eventStorm field is empty", "benefit": "I don't skip critical domain architecture discovery step" }, "rules": [ { "id": 0, "text": "System-reminder emitted ONLY when foundation.json exists", "deleted": false, "createdAt": "2025-11-17T03:02:57.538Z" }, { "id": 1, "text": "System-reminder emitted ONLY when eventStorm field is empty or missing", "deleted": false, "createdAt": "2025-11-17T03:02:58.100Z" }, { "id": 2, "text": "System-reminder references work unit ID if FOUND-XXX Event Storm work unit exists and not done", "deleted": false, "createdAt": "2025-11-17T03:02:58.639Z" }, { "id": 3, "text": "System-reminder appears AFTER CLAUDE.md content, BEFORE final message", "deleted": false, "createdAt": "2025-11-17T03:02:59.195Z" }, { "id": 4, "text": "System-reminder provides commands, CLAUDE.md reference, and explains why Event Storm matters", "deleted": false, "createdAt": "2025-11-17T03:02:59.742Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "AI runs 'fspec bootstrap', foundation.json exists with empty eventStorm, FOUND-XXX work unit exists in backlog, system-reminder emitted with work unit ID and next steps", "deleted": false, "createdAt": "2025-11-17T03:03:07.963Z" }, { "id": 1, "text": "AI runs 'fspec bootstrap', foundation.json exists with empty eventStorm, NO work unit exists, system-reminder emitted suggesting to create work unit or run commands directly", "deleted": false, "createdAt": "2025-11-17T03:03:08.508Z" }, { "id": 2, "text": "AI runs 'fspec bootstrap', foundation.json exists with populated eventStorm field, NO system-reminder emitted", "deleted": false, "createdAt": "2025-11-17T03:03:09.049Z" }, { "id": 3, "text": "AI runs 'fspec bootstrap', NO foundation.json exists, NO system-reminder emitted", "deleted": false, "createdAt": "2025-11-17T03:03:09.599Z" } ], "nextExampleId": 4, "architectureNotes": [ { "id": 0, "text": "Modifies src/commands/bootstrap.ts to emit system-reminder when Event Storm needed. Detection logic: Check foundation.json exists, eventStorm empty, find FOUND-XXX work units. System-reminder emitted AFTER CLAUDE.md content, BEFORE final fspec mode message. Uses existing wrapInSystemReminder utility for consistent formatting. Reuses existing file reading utilities (readFile, existsSync, JSON.parse).", "deleted": false, "createdAt": "2025-11-17T03:06:02.413Z" } ], "nextNoteId": 1, "questions": [], "nextQuestionId": 0, "updated": "2025-11-17T03:14:45.546Z" }, "FOUND-016": { "id": "FOUND-016", "title": "Conduct Big Picture Event Storming for Foundation", "description": "Complete the foundation by capturing domain architecture through Big Picture Event Storming.\n\nUse these commands to populate foundation.json eventStorm field:\n- fspec add-foundation-bounded-context <name>\n- fspec add-aggregate-to-foundation <context> <aggregate>\n- fspec add-domain-event-to-foundation <context> <event>\n- fspec show-foundation-event-storm\n\nWhy this matters:\n- Establishes bounded contexts for domain-driven design\n- Enables tag ontology generation from domain model\n- Provides foundation for architectural documentation\n- Supports EXMAP-004 tag discovery workflow\n\nSee spec/CLAUDE.md \"Big Picture Event Storming\" section for detailed guidance.", "type": "task", "status": "done", "createdAt": "2025-11-17T04:06:55.787Z", "updatedAt": "2025-11-17T04:11:20.433Z", "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T04:10:32.260Z" }, { "state": "implementing", "timestamp": "2025-11-17T04:11:06.449Z" }, { "state": "validating", "timestamp": "2025-11-17T04:11:14.623Z" }, { "state": "done", "timestamp": "2025-11-17T04:11:20.433Z" } ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T04:11:20.433Z" }, "FOUND-017": { "id": "FOUND-017", "title": "Generate Event Storm section in FOUNDATION.md with validated Mermaid diagram", "type": "story", "status": "done", "createdAt": "2025-11-17T04:14:28.263Z", "updatedAt": "2025-11-17T04:55:26.241Z", "description": "Update foundation-md.ts generator to include Event Storm bounded contexts as both text list and Mermaid bounded context map. Validate Mermaid syntax before adding to FOUNDATION.md. Auto-regenerate FOUNDATION.md when Event Storm commands are run (add-foundation-bounded-context, etc.).", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T04:14:34.699Z" }, { "state": "testing", "timestamp": "2025-11-17T04:17:48.782Z" }, { "state": "specifying", "timestamp": "2025-11-17T04:20:48.475Z" }, { "state": "testing", "timestamp": "2025-11-17T04:22:50.917Z" }, { "state": "implementing", "timestamp": "2025-11-17T04:29:48.019Z" }, { "state": "validating", "timestamp": "2025-11-17T04:44:51.268Z" }, { "state": "done", "timestamp": "2025-11-17T04:55:26.242Z" } ], "userStory": { "role": "AI agent using fspec for any project", "action": "see Event Storm bounded contexts visualized in FOUNDATION.md with a Mermaid diagram", "benefit": "I understand the strategic domain architecture at a glance" }, "rules": [ { "id": 0, "text": "Mermaid diagram syntax must be validated using mermaid.parse() before adding to FOUNDATION.md", "deleted": false, "createdAt": "2025-11-17T04:14:51.666Z" }, { "id": 1, "text": "FOUNDATION.md must auto-regenerate when Event Storm commands are run (add-foundation-bounded-context, etc.)", "deleted": false, "createdAt": "2025-11-17T04:14:52.214Z" }, { "id": 2, "text": "Event Storm section should include both text list AND Mermaid bounded context map", "deleted": false, "createdAt": "2025-11-17T04:14:52.777Z" }, { "id": 3, "text": "Event Storm section only appears if foundation.json has eventStorm field with items", "deleted": false, "createdAt": "2025-11-17T04:14:53.353Z" }, { "id": 4, "text": "Mermaid diagram should show bounded contexts as nodes in a graph", "deleted": false, "createdAt": "2025-11-17T04:14:53.910Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User runs 'fspec add-foundation-bounded-context Work Management', FOUNDATION.md auto-regenerates with Domain Architecture section showing bounded context in text list and Mermaid diagram", "deleted": false, "createdAt": "2025-11-17T04:15:02.832Z" }, { "id": 1, "text": "foundation.json has 7 bounded contexts, FOUNDATION.md includes Mermaid graph with 7 nodes", "deleted": false, "createdAt": "2025-11-17T04:15:03.381Z" }, { "id": 2, "text": "Invalid Mermaid syntax detected during generation, error thrown with line number and helpful message", "deleted": false, "createdAt": "2025-11-17T04:15:03.926Z" } ], "nextExampleId": 3, "architectureNotes": [ { "id": 0, "text": "Use existing validateMermaidSyntax() utility from src/utils/mermaid-validation.ts to validate generated Mermaid diagram. Call validateMermaidSyntax() before writing to FOUNDATION.md. Reuse existing pattern from add-diagram command. Auto-regenerate FOUNDATION.md by calling generateFoundationMd() at end of add-foundation-bounded-context command.", "deleted": false, "createdAt": "2025-11-17T04:15:23.535Z" } ], "nextNoteId": 1, "attachments": [ "spec/attachments/FOUND-017/ast-research-foundation-md-generator.json", "spec/attachments/FOUND-017/ast-research-add-foundation-bounded-context.json" ], "questions": [], "nextQuestionId": 0, "updated": "2025-11-17T04:55:26.241Z" }, "FOUND-019": { "id": "FOUND-019", "title": "discover-foundation regenerates draft when used to check next field", "type": "bug", "status": "done", "createdAt": "2025-11-17T05:22:42.690Z", "updatedAt": "2025-11-17T05:33:53.244Z", "description": "The discover-foundation command regenerates the entire draft from scratch when run without flags, losing all previously filled fields. AI agents may mistakenly run 'fspec discover-foundation' thinking it will show the next field to fill, but it actually destroys their progress. The guidance in system-reminders should clarify: (1) Run 'fspec discover-foundation' ONCE to create initial draft, (2) Use 'fspec update-foundation' and 'fspec add-persona/add-capability' commands to fill fields (the commands auto-chain to next field), (3) Run 'fspec discover-foundation --finalize' ONCE to validate and create foundation.json. There's no separate command to 'check what field is next' - the update commands handle that automatically via system-reminders.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T05:22:48.338Z" }, { "state": "testing", "timestamp": "2025-11-17T05:24:07.298Z" }, { "state": "implementing", "timestamp": "2025-11-17T05:25:23.811Z" }, { "state": "validating", "timestamp": "2025-11-17T05:27:51.621Z" }, { "state": "done", "timestamp": "2025-11-17T05:33:53.244Z" } ], "userStory": { "role": "AI agent filling foundation draft", "action": "understand which command to use next", "benefit": "I don't accidentally regenerate the draft and lose my progress" }, "rules": [ { "id": 0, "text": "discover-foundation without flags ALWAYS regenerates draft from scratch", "deleted": false, "createdAt": "2025-11-17T05:23:07.996Z" }, { "id": 1, "text": "update-foundation commands automatically emit system-reminder for next field", "deleted": false, "createdAt": "2025-11-17T05:23:09.528Z" }, { "id": 2, "text": "System-reminders must clarify the workflow: discover once → update many → finalize once", "deleted": false, "createdAt": "2025-11-17T05:23:11.160Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "AI runs 'fspec discover-foundation' after filling 3 fields → draft regenerated, all progress lost", "deleted": false, "createdAt": "2025-11-17T05:23:12.971Z" }, { "id": 1, "text": "AI runs 'fspec update-foundation projectName fspec' → system-reminder says 'Field 2/8: project.vision' with correct command", "deleted": false, "createdAt": "2025-11-17T05:23:14.779Z" }, { "id": 2, "text": "System-reminder after update-foundation should say 'Continue with: fspec update-foundation...' NOT 'Run: fspec discover-foundation'", "deleted": false, "createdAt": "2025-11-17T05:23:16.274Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T05:33:53.244Z" }, "FOUND-021": { "id": "FOUND-021", "title": "discover-foundation overwrites draft without warning", "type": "bug", "status": "done", "createdAt": "2025-11-17T05:52:33.189Z", "updatedAt": "2025-11-17T06:01:48.706Z", "description": "Running 'fspec discover-foundation' when foundation.json.draft already exists silently regenerates the draft and loses all progress. This happened during foundation discovery when the command was accidentally run again without --finalize flag. Need to add a safety check that prevents overwriting existing draft unless --force flag is provided.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T05:53:16.027Z" }, { "state": "testing", "timestamp": "2025-11-17T05:54:55.792Z" }, { "state": "implementing", "timestamp": "2025-11-17T05:56:22.511Z" }, { "state": "validating", "timestamp": "2025-11-17T06:00:00.828Z" }, { "state": "done", "timestamp": "2025-11-17T06:01:48.706Z" } ], "userStory": { "role": "AI agent or developer using fspec", "action": "run discover-foundation command safely without losing draft progress", "benefit": "I can recover from accidentally running the command twice without losing all my work" }, "rules": [ { "id": 0, "text": "discover-foundation without --finalize flag MUST check if foundation.json.draft exists before creating a new draft", "deleted": false, "createdAt": "2025-11-17T05:53:45.495Z" }, { "id": 1, "text": "If draft exists, command MUST emit error message with --force flag suggestion", "deleted": false, "createdAt": "2025-11-17T05:53:53.817Z" }, { "id": 2, "text": "The --force flag MUST allow overwriting existing draft (explicit opt-in)", "deleted": false, "createdAt": "2025-11-17T05:53:54.360Z" }, { "id": 3, "text": "If foundation.json already exists, command MUST also warn and require --force flag", "deleted": false, "createdAt": "2025-11-17T05:53:54.907Z" }, { "id": 4, "text": "Error message MUST be wrapped in system-reminder tags for AI visibility", "deleted": false, "createdAt": "2025-11-17T05:53:55.458Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "User runs 'fspec discover-foundation' when draft exists → Error: Draft already exists, use --force to overwrite", "deleted": false, "createdAt": "2025-11-17T05:54:03.101Z" }, { "id": 1, "text": "User runs 'fspec discover-foundation --force' when draft exists → Draft is overwritten, warning shown", "deleted": false, "createdAt": "2025-11-17T05:54:03.653Z" }, { "id": 2, "text": "User runs 'fspec discover-foundation' when foundation.json exists → Error: Foundation already exists, use --force to regenerate draft", "deleted": false, "createdAt": "2025-11-17T05:54:04.205Z" }, { "id": 3, "text": "User runs 'fspec discover-foundation' when neither draft nor foundation.json exist → Draft created successfully", "deleted": false, "createdAt": "2025-11-17T05:54:04.750Z" }, { "id": 4, "text": "User runs 'fspec discover-foundation --finalize' when draft exists → Normal finalization flow (no change to existing behavior)", "deleted": false, "createdAt": "2025-11-17T05:54:05.297Z" } ], "nextExampleId": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T06:01:48.706Z" }, "FOUND-022": { "id": "FOUND-022", "title": "Conduct Big Picture Event Storming for Foundation", "description": "Complete the foundation by capturing domain architecture through Big Picture Event Storming.\n\nUse these commands to populate foundation.json eventStorm field:\n- fspec add-foundation-bounded-context <name>\n- fspec add-aggregate-to-foundation <context> <aggregate>\n- fspec add-domain-event-to-foundation <context> <event>\n- fspec show-foundation-event-storm\n\nWhy this matters:\n- Establishes bounded contexts for domain-driven design\n- Enables tag ontology generation from domain model\n- Provides foundation for architectural documentation\n- Supports EXMAP-004 tag discovery workflow\n\nSee spec/CLAUDE.md \"Big Picture Event Storming\" section for detailed guidance.", "type": "task", "status": "done", "createdAt": "2025-11-17T06:47:08.326Z", "updatedAt": "2025-11-17T11:51:40.314Z", "stateHistory": [ { "state": "backlog", "timestamp": "2025-11-17T08:21:54.659Z" }, { "state": "specifying", "timestamp": "2025-11-17T08:23:00.545Z" }, { "state": "blocked", "timestamp": "2025-11-17T10:49:58.234Z", "reason": "Missing foundation Event Storm commands: add-aggregate-to-foundation, add-domain-event-to-foundation, add-command-to-foundation. Created FOUND-033 to implement these commands." }, { "state": "specifying", "timestamp": "2025-11-17T11:16:35.511Z" }, { "state": "implementing", "timestamp": "2025-11-17T11:51:19.665Z" }, { "state": "validating", "timestamp": "2025-11-17T11:51:27.575Z" }, { "state": "done", "timestamp": "2025-11-17T11:51:40.314Z" } ], "attachments": [ "spec/attachments/FOUND-022/continuation-notes.md" ], "blockedBy": [ "FOUND-033" ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T11:51:40.314Z" }, "DOCS-003": { "id": "DOCS-003", "title": "Fix step numbering in bootstrap documentation", "type": "task", "status": "done", "createdAt": "2025-11-17T06:56:28.014Z", "updatedAt": "2025-11-17T07:27:31.666Z", "description": "The bootstrap command outputs confusing step numbers (1, 1.5, 1.5a, 1.6, 2, 2.5, 3, 3 duplicate, 5 no 4, 7 no 6, 6.5, 2 duplicate). Need to renumber to clear sequential steps: 1, 2, 3, 4, etc. Affects: bootstrap command help output, spec/CLAUDE.md, spec/AGENTS.md (if exists), and any source templates that generate these docs.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T06:57:07.359Z" }, { "state": "implementing", "timestamp": "2025-11-17T06:57:13.679Z" }, { "state": "validating", "timestamp": "2025-11-17T07:01:15.044Z" }, { "state": "done", "timestamp": "2025-11-17T07:27:31.667Z" } ], "rules": [], "examples": [], "questions": [], "architectureNotes": [], "nextRuleId": 0, "nextExampleId": 0, "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T07:27:31.666Z" }, "BUG-078": { "id": "BUG-078", "title": "discover-foundation --finalize creates work unit without adding to states array", "type": "bug", "status": "done", "createdAt": "2025-11-17T07:37:59.496Z", "updatedAt": "2025-11-17T08:15:23.272Z", "description": "The discover-foundation.ts --finalize code directly creates FOUND-022 work unit by manually constructing the object (lines 399-423) instead of calling createWorkUnit() from work-unit.ts. This violates DRY/SOLID principles and causes the work unit to be missing from states.backlog array, making it invisible in the TUI.\n\nRoot cause: Code duplication - discover-foundation.ts reimplements work unit creation logic instead of reusing the existing createWorkUnit() function.\n\nImpact: FOUND-022 exists in workUnits object but not in states.backlog, so TUI filtering (fspecStore.ts lines 109-130) skips it.\n\nFix: Refactor discover-foundation.ts to import and call createWorkUnit() instead of manually creating the work unit object.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T07:38:39.351Z" }, { "state": "testing", "timestamp": "2025-11-17T07:45:38.080Z" }, { "state": "implementing", "timestamp": "2025-11-17T07:47:05.726Z" }, { "state": "validating", "timestamp": "2025-11-17T08:08:44.541Z" }, { "state": "done", "timestamp": "2025-11-17T08:15:23.273Z" } ], "rules": [ { "id": 0, "text": "Work unit creation logic must be centralized - all commands must call createWorkUnit() from work-unit.ts", "deleted": false, "createdAt": "2025-11-17T07:38:52.613Z" }, { "id": 1, "text": "All work unit creation commands (create-story, create-bug, create-task, discover-foundation) must call createWorkUnit() instead of duplicating logic", "deleted": false, "createdAt": "2025-11-17T07:40:10.932Z" }, { "id": 2, "text": "states.backlog array must be updated atomically with workUnits object to prevent TUI display bugs", "deleted": false, "createdAt": "2025-11-17T07:40:18.161Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "discover-foundation.ts:401 manually creates work unit object and FORGETS to add to states.backlog array - causing FOUND-022 to be invisible in TUI", "deleted": false, "createdAt": "2025-11-17T07:39:50.046Z" }, { "id": 1, "text": "create-story.ts:110, create-bug.ts:110, create-task.ts:110 all DUPLICATE the logic from work-unit.ts:212 - violating DRY principle", "deleted": false, "createdAt": "2025-11-17T07:39:58.194Z" }, { "id": 2, "text": "work-unit.ts:212 has the CORRECT logic that adds to states.backlog array - this should be the ONLY place this logic exists (Single Responsibility Principle)", "deleted": false, "createdAt": "2025-11-17T07:40:04.760Z" } ], "nextExampleId": 3, "userStory": { "role": "developer using fspec", "action": "create work units through any command", "benefit": "all work units appear in the TUI Kanban board without missing entries" }, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T08:15:23.272Z" }, "BUG-079": { "id": "BUG-079", "title": "Prefill detection incorrectly flags code syntax as placeholders", "type": "bug", "status": "done", "createdAt": "2025-11-17T07:45:29.630Z", "updatedAt": "2025-11-17T08:39:53.790Z", "description": "The prefill detection regex matches ANY text inside square brackets, causing false positives when Gherkin steps describe code syntax like 'workUnitsData.workUnits[id]'.\n\nRoot cause: Overly broad regex pattern matches [anything] instead of specific placeholder patterns we generate.\n\nImpact: \n- Valid feature files blocked from workflow progression\n- Forces workarounds (rewording steps to avoid brackets)\n- Breaks when describing array access, generics, or other bracket syntax\n\nFix: Only detect actual placeholder patterns we generate:\n- [role], [action], [benefit] (user story placeholders)\n- [precondition], [expected outcome] (step placeholders) \n- TODO: markers (architecture note placeholders)\n- @component, @critical (tag placeholders)\n\nDo NOT match arbitrary bracket syntax that happens to be in step descriptions.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T08:28:28.244Z" }, { "state": "testing", "timestamp": "2025-11-17T08:30:56.441Z" }, { "state": "implementing", "timestamp": "2025-11-17T08:32:35.637Z" }, { "state": "validating", "timestamp": "2025-11-17T08:34:58.670Z" }, { "state": "done", "timestamp": "2025-11-17T08:39:53.791Z" } ], "userStory": { "role": "AI agent writing Gherkin specifications", "action": "describe code syntax in steps without triggering false positive prefill detection", "benefit": "I can write clear, accurate specifications without workarounds" }, "rules": [ { "id": 0, "text": "Prefill detection MUST only match actual placeholder text patterns we generate: [role], [action], [benefit], [precondition], [expected outcome], TODO:", "deleted": false, "createdAt": "2025-11-17T08:28:44.210Z" }, { "id": 1, "text": "Prefill detection MUST NOT match arbitrary bracket syntax like array access [id], TypeScript generics Array<T>, or code examples", "deleted": false, "createdAt": "2025-11-17T08:28:50.764Z" } ], "nextRuleId": 2, "examples": [ { "id": 0, "text": "Step 'Then only work-unit.ts should contain workUnitsData.workUnits[id] = object logic' incorrectly flagged as containing placeholder", "deleted": false, "createdAt": "2025-11-17T08:28:59.075Z" }, { "id": 1, "text": "Step 'Given I have [role] placeholder' should be flagged as containing placeholder", "deleted": false, "createdAt": "2025-11-17T08:29:05.633Z" }, { "id": 2, "text": "Step 'When I access array[index] in code' should NOT be flagged as placeholder", "deleted": false, "createdAt": "2025-11-17T08:29:12.168Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T08:39:53.790Z" }, "FOUND-033": { "id": "FOUND-033", "title": "Implement Foundation Event Storm Commands for Aggregates, Events, and Commands", "type": "story", "status": "done", "createdAt": "2025-11-17T10:47:55.217Z", "updatedAt": "2025-11-17T11:11:44.168Z", "children": [], "attachments": [ "spec/attachments/FOUND-033/foundation-event-storm-analysis.md", "spec/attachments/FOUND-033/ast-research-foundation-command-pattern.md" ], "blocks": [ "FOUND-022" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T10:51:42.671Z" }, { "state": "testing", "timestamp": "2025-11-17T10:57:30.866Z" }, { "state": "implementing", "timestamp": "2025-11-17T11:05:12.457Z" }, { "state": "validating", "timestamp": "2025-11-17T11:08:56.631Z" }, { "state": "done", "timestamp": "2025-11-17T11:11:44.168Z" } ], "userStory": { "role": "developer conducting Big Picture Event Storming", "action": "add aggregates, domain events, and commands to foundation bounded contexts", "benefit": "I can complete the domain architecture model and generate comprehensive FOUNDATION.md documentation" }, "rules": [ { "id": 0, "text": "Each aggregate must be linked to a specific bounded context", "deleted": false, "createdAt": "2025-11-17T10:52:01.907Z" }, { "id": 1, "text": "Domain events must be linked to a specific bounded context", "deleted": false, "createdAt": "2025-11-17T10:52:03.512Z" }, { "id": 2, "text": "Commands must be linked to a specific bounded context", "deleted": false, "createdAt": "2025-11-17T10:52:05.158Z" }, { "id": 3, "text": "Bounded context must exist before adding aggregates, events, or commands to it", "deleted": false, "createdAt": "2025-11-17T10:52:06.705Z" }, { "id": 4, "text": "Foundation Event Storm uses same data structure as work unit Event Storm (foundation.json eventStorm field)", "deleted": false, "createdAt": "2025-11-17T10:52:08.692Z" }, { "id": 5, "text": "Commands must follow pattern: add-<type>-to-foundation <context> <name>", "deleted": false, "createdAt": "2025-11-17T10:52:10.828Z" }, { "id": 6, "text": "Yes, support optional --description flag to match work unit Event Storm pattern", "deleted": false, "createdAt": "2025-11-17T10:52:51.665Z" }, { "id": 7, "text": "Yes, generate-foundation-md should include Event Storm section showing bounded contexts with their aggregates, events, and commands", "deleted": false, "createdAt": "2025-11-17T10:52:53.204Z" } ], "nextRuleId": 8, "examples": [ { "id": 0, "text": "Developer runs 'fspec add-aggregate-to-foundation \"Work Management\" \"WorkUnit\"' and it creates item with type='aggregate' linked to Work Management context", "deleted": false, "createdAt": "2025-11-17T10:52:23.375Z" }, { "id": 1, "text": "Developer runs 'fspec add-domain-event-to-foundation \"Work Management\" \"WorkUnitCreated\"' and it creates item with type='domain_event' linked to Work Management context", "deleted": false, "createdAt": "2025-11-17T10:52:24.937Z" }, { "id": 2, "text": "Developer runs 'fspec add-command-to-foundation \"Work Management\" \"CreateWorkUnit\"' and it creates item with type='command' linked to Work Management context", "deleted": false, "createdAt": "2025-11-17T10:52:26.548Z" }, { "id": 3, "text": "Developer tries to add aggregate to non-existent context 'Foo' and gets error: Bounded context 'Foo' not found", "deleted": false, "createdAt": "2025-11-17T10:52:28.585Z" }, { "id": 4, "text": "Developer runs 'fspec show-foundation-event-storm --context=\"Work Management\"' and sees only items for that context (bounded context, aggregates, events, commands)", "deleted": false, "createdAt": "2025-11-17T10:52:30.511Z" }, { "id": 5, "text": "Developer runs 'fspec show-foundation-event-storm --type=aggregate' and sees only aggregate items across all contexts", "deleted": false, "createdAt": "2025-11-17T10:52:32.359Z" } ], "nextExampleId": 6, "questions": [ { "id": 0, "text": "@human: Should we support optional --description flag for aggregates, events, and commands?", "deleted": false, "createdAt": "2025-11-17T10:52:40.668Z", "selected": true, "answer": "Yes, support optional --description flag to match work unit Event Storm pattern" }, { "id": 1, "text": "@human: Should generate-foundation-md include Event Storm visualization (aggregates, events, commands) in the output?", "deleted": false, "createdAt": "2025-11-17T10:52:43.044Z", "selected": true, "answer": "Yes, generate-foundation-md should include Event Storm section showing bounded contexts with their aggregates, events, and commands" } ], "nextQuestionId": 2, "estimate": 5, "architectureNotes": [ { "id": 0, "text": "Implementation requires three new command files in src/commands/: add-aggregate-to-foundation.ts, add-domain-event-to-foundation.ts, add-command-to-foundation.ts. Each follows same pattern as add-foundation-bounded-context.ts", "deleted": false, "createdAt": "2025-11-17T10:56:10.580Z" }, { "id": 1, "text": "Data model: foundation.json eventStorm.items array contains objects with: id, type ('bounded_context'|'aggregate'|'domain_event'|'command'), text, boundedContextId (links to parent context), color, deleted, createdAt", "deleted": false, "createdAt": "2025-11-17T10:56:13.441Z" }, { "id": 2, "text": "Use existing foundation.json read/write utilities from src/utils/foundation.ts. Follow atomic write pattern with .tmp file for safety. Validate bounded context exists before adding child items.", "deleted": false, "createdAt": "2025-11-17T10:56:15.168Z" }, { "id": 3, "text": "Update show-foundation-event-storm.ts to add --context and --type filtering options. Filter items array based on boundedContextId or type field.", "deleted": false, "createdAt": "2025-11-17T10:56:17.342Z" }, { "id": 4, "text": "Update generate-foundation-md.ts to render Event Storm section: loop through bounded contexts, show aggregates/events/commands for each. Group by bounded context in markdown output.", "deleted": false, "createdAt": "2025-11-17T10:56:19.013Z" } ], "nextNoteId": 5, "updated": "2025-11-17T11:11:44.168Z" }, "FOUND-042": { "id": "FOUND-042", "title": "Enhance FOUNDATION.md Event Storm visualization", "type": "story", "status": "done", "createdAt": "2025-11-17T11:53:57.786Z", "updatedAt": "2025-11-17T12:07:02.097Z", "description": "generate-foundation-md should render complete Event Storm with aggregates, domain events, and commands for each bounded context", "children": [], "attachments": [ "spec/attachments/FOUND-042/found-042-analysis.md", "spec/attachments/FOUND-042/ast-research-foundation-md-functions.json" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T11:55:49.956Z" }, { "state": "testing", "timestamp": "2025-11-17T12:00:19.051Z" }, { "state": "implementing", "timestamp": "2025-11-17T12:02:12.114Z" }, { "state": "validating", "timestamp": "2025-11-17T12:03:58.688Z" }, { "state": "done", "timestamp": "2025-11-17T12:07:02.097Z" } ], "userStory": { "role": "developer viewing foundation architecture", "action": "see complete Event Storm visualization in FOUNDATION.md", "benefit": "I understand the domain model with aggregates, events, and commands for each bounded context" }, "rules": [ { "id": 0, "text": "Each bounded context must have a dedicated section in FOUNDATION.md", "deleted": false, "createdAt": "2025-11-17T11:57:29.870Z" }, { "id": 1, "text": "Aggregates must be listed under each bounded context with their descriptions", "deleted": false, "createdAt": "2025-11-17T11:57:31.837Z" }, { "id": 2, "text": "Domain events must be listed under each bounded context with their descriptions", "deleted": false, "createdAt": "2025-11-17T11:57:33.436Z" }, { "id": 3, "text": "Commands must be listed under each bounded context with their descriptions", "deleted": false, "createdAt": "2025-11-17T11:57:35.100Z" }, { "id": 4, "text": "Items must only appear under their parent bounded context (filter by boundedContextId)", "deleted": false, "createdAt": "2025-11-17T11:57:36.616Z" }, { "id": 5, "text": "Deleted items must be excluded from the visualization", "deleted": false, "createdAt": "2025-11-17T11:57:38.217Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "Work Management context shows 4 aggregates: WorkUnit, Epic, Dependency, Prefix with descriptions", "deleted": false, "createdAt": "2025-11-17T11:57:51.668Z" }, { "id": 1, "text": "Work Management context shows 4 events: WorkUnitCreated, WorkUnitStatusChanged, WorkUnitBlocked, DependencyAdded with descriptions", "deleted": false, "createdAt": "2025-11-17T11:57:53.231Z" }, { "id": 2, "text": "Work Management context shows 4 commands: CreateWorkUnit, UpdateWorkUnitStatus, BlockWorkUnit, AddDependency with descriptions", "deleted": false, "createdAt": "2025-11-17T11:57:54.622Z" }, { "id": 3, "text": "All 6 bounded contexts have their own sections after the Bounded Context Map diagram", "deleted": false, "createdAt": "2025-11-17T11:57:55.979Z" }, { "id": 4, "text": "Deleted items (deleted: true) do not appear in the output", "deleted": false, "createdAt": "2025-11-17T11:57:58.470Z" } ], "nextExampleId": 5, "architectureNotes": [ { "id": 0, "text": "Implementation will modify src/generators/foundation-md.ts lines 180-223 to add new sections after the Bounded Context Map. For each bounded context, filter items by boundedContextId and type (aggregate/event/command), then generate markdown sections with heading level 2 for context name and bold subsections for Aggregates/Domain Events/Commands. Each item will be rendered as a bullet list with item.text and item.description. Existing Mermaid diagram generation remains unchanged.", "deleted": false, "createdAt": "2025-11-17T12:00:00.180Z" } ], "nextNoteId": 1, "questions": [], "nextQuestionId": 0, "updated": "2025-11-17T12:07:02.097Z" }, "TEST-009": { "id": "TEST-009", "title": "Mermaid validation test uses invalid test data", "type": "bug", "status": "done", "createdAt": "2025-11-17T13:01:05.811Z", "updatedAt": "2025-11-17T22:24:28.198Z", "description": "Test in generate-event-storm-section-in-foundation-md.test.ts expects generateFoundationMd to throw for 'Invalid{Context}' but that's valid Mermaid. Needs actually-invalid syntax or redesign.", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T22:07:55.534Z" }, { "state": "testing", "timestamp": "2025-11-17T22:11:58.809Z" }, { "state": "implementing", "timestamp": "2025-11-17T22:15:16.788Z" }, { "state": "validating", "timestamp": "2025-11-17T22:19:52.728Z" }, { "state": "done", "timestamp": "2025-11-17T22:24:28.198Z" } ], "userStory": { "role": "developer writing tests for Mermaid validation", "action": "validate that Event Storm diagrams with invalid Mermaid syntax are rejected", "benefit": "FOUNDATION.md is never generated with broken diagrams" }, "attachments": [ "spec/attachments/TEST-009/TEST-009-root-cause.md" ], "rules": [ { "id": 0, "text": "generateFoundationMd must validate Event Storm Mermaid diagrams before writing FOUNDATION.md", "deleted": false, "createdAt": "2025-11-17T22:08:25.024Z" }, { "id": 1, "text": "Invalid Mermaid syntax in Event Storm bounded context names must trigger validation error", "deleted": false, "createdAt": "2025-11-17T22:08:31.218Z" } ], "nextRuleId": 2, "examples": [ { "id": 0, "text": "Bounded context with unclosed bracket 'Context[Unclosed' causes validation error", "deleted": false, "createdAt": "2025-11-17T22:08:38.843Z" }, { "id": 1, "text": "generateFoundationMd throws error with helpful message pointing to invalid syntax", "deleted": false, "createdAt": "2025-11-17T22:08:45.918Z" }, { "id": 2, "text": "FOUNDATION.md is not written when Event Storm diagram validation fails", "deleted": false, "createdAt": "2025-11-17T22:08:52.581Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T22:24:28.198Z" }, "BUG-081": { "id": "BUG-081", "title": "show-foundation command has multiple quality issues", "type": "bug", "status": "done", "createdAt": "2025-11-17T23:07:18.725Z", "updatedAt": "2025-11-17T23:28:44.517Z", "description": "Parameters are ignored (--list-sections, --section), unintended file creation, documentation mismatches between display names and property names. Reported in GitHub issue #6.", "children": [], "attachments": [ "spec/attachments/BUG-081/issue-6-show-foundation-quality-issues.md", "spec/attachments/BUG-081/bug-081-investigation-findings.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T23:16:38.604Z" }, { "state": "testing", "timestamp": "2025-11-17T23:18:48.708Z" }, { "state": "implementing", "timestamp": "2025-11-17T23:20:06.420Z" }, { "state": "validating", "timestamp": "2025-11-17T23:22:03.181Z" }, { "state": "done", "timestamp": "2025-11-17T23:28:44.517Z" } ], "userStory": { "role": "developer using show-foundation command", "action": "view foundation data with correct parameter handling", "benefit": "I can access foundation content using documented syntax without confusion" }, "rules": [ { "id": 0, "text": "The --section parameter must correctly filter to show only the specified field", "deleted": false, "createdAt": "2025-11-17T23:17:04.415Z" }, { "id": 1, "text": "Positional argument syntax 'fspec show-foundation <field>' must work as documented in help text", "deleted": false, "createdAt": "2025-11-17T23:17:06.072Z" }, { "id": 2, "text": "Both --section flag and positional argument must accept field names from FIELD_MAP or JSON paths", "deleted": false, "createdAt": "2025-11-17T23:17:07.587Z" }, { "id": 3, "text": "When no field specified, show entire foundation in formatted text", "deleted": false, "createdAt": "2025-11-17T23:17:09.028Z" }, { "id": 4, "text": "Auto-creation of foundation.json with template data is expected behavior when file is missing", "deleted": false, "createdAt": "2025-11-17T23:17:10.526Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "Run 'fspec show-foundation --section projectOverview' and see only the project overview content, not the entire foundation", "deleted": false, "createdAt": "2025-11-17T23:17:20.723Z" }, { "id": 1, "text": "Run 'fspec show-foundation projectOverview' (positional) and get the same result as using --section flag", "deleted": false, "createdAt": "2025-11-17T23:17:22.419Z" }, { "id": 2, "text": "Run 'fspec show-foundation solutionSpace.overview' using JSON path and retrieve the nested field", "deleted": false, "createdAt": "2025-11-17T23:17:23.963Z" }, { "id": 3, "text": "Run 'fspec show-foundation' with no arguments and see the entire foundation formatted as text with sections", "deleted": false, "createdAt": "2025-11-17T23:17:25.777Z" }, { "id": 4, "text": "Run 'fspec show-foundation --section nonExistentField' and receive error message 'Field not found'", "deleted": false, "createdAt": "2025-11-17T23:17:27.369Z" } ], "nextExampleId": 5, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T23:28:44.517Z" }, "BUG-082": { "id": "BUG-082", "title": "add-diagram fails with 'screen is not defined' error for valid C4 diagrams", "type": "bug", "status": "done", "createdAt": "2025-11-17T23:07:36.502Z", "updatedAt": "2025-11-17T23:48:12.519Z", "description": "C4Context diagrams fail Mermaid validation with error 'screen is not defined'. Valid C4 syntax is rejected. Reported in GitHub issue #5.", "children": [], "attachments": [ "spec/attachments/BUG-082/issue-5-add-diagram-screen-not-defined.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-17T23:33:50.119Z" }, { "state": "testing", "timestamp": "2025-11-17T23:38:06.769Z" }, { "state": "implementing", "timestamp": "2025-11-17T23:39:23.717Z" }, { "state": "validating", "timestamp": "2025-11-17T23:44:35.723Z" }, { "state": "done", "timestamp": "2025-11-17T23:48:12.519Z" } ], "userStory": { "role": "developer adding C4 diagrams to foundation", "action": "add valid C4Context diagrams without errors", "benefit": "I can document system architecture using C4 notation" }, "rules": [ { "id": 0, "text": "C4Context diagram syntax must be recognized as valid Mermaid", "deleted": false, "createdAt": "2025-11-17T23:34:45.906Z" }, { "id": 1, "text": "Mermaid validation must support C4 diagram types (C4Context, C4Container, C4Component, C4Dynamic, C4Deployment)", "deleted": false, "createdAt": "2025-11-17T23:34:46.453Z" }, { "id": 2, "text": "C4 diagrams with valid syntax must not throw 'screen is not defined' error", "deleted": false, "createdAt": "2025-11-17T23:34:47.009Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Add C4Context diagram with Person, System, and Relationships - should succeed without errors", "deleted": false, "createdAt": "2025-11-17T23:34:54.450Z" }, { "id": 1, "text": "Add C4Context diagram similar to reported issue example - validates successfully", "deleted": false, "createdAt": "2025-11-17T23:34:55.006Z" }, { "id": 2, "text": "Add simple C4Context with one Person and one System - validates and adds to foundation.json", "deleted": false, "createdAt": "2025-11-17T23:34:55.559Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-17T23:48:12.519Z" }, "BUG-083": { "id": "BUG-083", "title": "AST research tool fails with relative file paths", "type": "bug", "status": "done", "createdAt": "2025-11-18T00:14:37.981Z", "updatedAt": "2025-11-18T00:45:07.608Z", "children": [], "attachments": [ "spec/attachments/BUG-083/bug-report-ast-research-tool.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T00:40:48.391Z" }, { "state": "testing", "timestamp": "2025-11-18T00:42:29.154Z" }, { "state": "implementing", "timestamp": "2025-11-18T00:44:04.679Z" }, { "state": "validating", "timestamp": "2025-11-18T00:45:01.306Z" }, { "state": "done", "timestamp": "2025-11-18T00:45:07.608Z" } ], "userStory": { "role": "developer using fspec research tools", "action": "use relative file paths with AST research tool", "benefit": "I can analyze code without specifying full absolute paths" }, "rules": [ { "id": 0, "text": "AST research tool must resolve relative file paths from current working directory", "deleted": false, "createdAt": "2025-11-18T00:40:59.305Z" }, { "id": 1, "text": "Absolute paths must continue to work as before", "deleted": false, "createdAt": "2025-11-18T00:41:04.723Z" } ], "nextRuleId": 2, "examples": [ { "id": 0, "text": "Run 'fspec research --tool=ast --operation=list-functions --file=src/index.ts' and it successfully analyzes the file", "deleted": false, "createdAt": "2025-11-18T00:41:10.343Z" }, { "id": 1, "text": "Run 'fspec research --tool=ast --operation=list-functions --file=/Users/rquast/projects/fspec/src/index.ts' and it successfully analyzes the file", "deleted": false, "createdAt": "2025-11-18T00:41:16.511Z" } ], "nextExampleId": 2, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T00:45:07.608Z" }, "CLEAN-004": { "id": "CLEAN-004", "title": "Remove compile-research command and all references", "type": "task", "status": "done", "createdAt": "2025-11-18T00:25:10.921Z", "updatedAt": "2025-11-18T00:36:06.824Z", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T00:25:15.860Z" }, { "state": "implementing", "timestamp": "2025-11-18T00:27:48.327Z" }, { "state": "validating", "timestamp": "2025-11-18T00:36:00.319Z" }, { "state": "done", "timestamp": "2025-11-18T00:36:06.824Z" } ], "userStory": { "role": "developer maintaining fspec", "action": "remove the compile-research command and all its references", "benefit": "eliminate hardcoded semantic diagram generation logic" }, "rules": [ { "id": 0, "text": "All references to compile-research must be removed from codebase", "deleted": false, "createdAt": "2025-11-18T00:25:30.988Z" }, { "id": 1, "text": "Command must be unregistered from CLI (src/index.ts)", "deleted": false, "createdAt": "2025-11-18T00:25:35.533Z" }, { "id": 2, "text": "Help file and documentation must be removed from src/help.ts", "deleted": false, "createdAt": "2025-11-18T00:25:40.121Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Remove src/commands/compile-research.ts command implementation file", "deleted": false, "createdAt": "2025-11-18T00:25:45.989Z" }, { "id": 1, "text": "Remove src/commands/compile-research-help.ts help file", "deleted": false, "createdAt": "2025-11-18T00:25:52.458Z" }, { "id": 2, "text": "Remove registerCompileResearchCommand import and call from src/index.ts", "deleted": false, "createdAt": "2025-11-18T00:25:57.724Z" }, { "id": 3, "text": "Remove compile-research documentation from src/help.ts RESEARCH TOOLS section", "deleted": false, "createdAt": "2025-11-18T00:26:04.230Z" }, { "id": 4, "text": "Search for any test files referencing compile-research and remove or update them", "deleted": false, "createdAt": "2025-11-18T00:26:09.280Z" } ], "nextExampleId": 5, "attachments": [ "spec/attachments/CLEAN-004/compile-research-removal-plan.md" ], "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T00:36:06.824Z" }, "COV-055": { "id": "COV-055", "title": "Coverage File Synchronization", "type": "story", "status": "done", "createdAt": "2025-11-18T01:07:49.494Z", "updatedAt": "2025-11-18T01:40:58.748Z", "description": "Fix coverage files not syncing when scenarios are deleted from feature files, causing false-positive uncovered scenario errors", "children": [], "userStory": { "role": "developer using fspec", "action": "have coverage files automatically sync when scenarios are deleted", "benefit": "I don't get false-positive uncovered scenario errors" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T01:08:10.983Z" }, { "state": "testing", "timestamp": "2025-11-18T01:20:10.360Z" }, { "state": "implementing", "timestamp": "2025-11-18T01:21:56.286Z" }, { "state": "validating", "timestamp": "2025-11-18T01:33:15.798Z" }, { "state": "done", "timestamp": "2025-11-18T01:40:58.748Z" } ], "rules": [ { "id": 0, "text": "When a scenario is deleted from a feature file, the corresponding entry must be removed from the .feature.coverage file", "deleted": false, "createdAt": "2025-11-18T01:08:16.093Z" }, { "id": 1, "text": "The updateCoverageFile() function must detect and remove scenarios that exist in coverage file but not in feature file", "deleted": false, "createdAt": "2025-11-18T01:08:21.291Z" }, { "id": 2, "text": "Coverage validation must check that all scenarios in coverage file still exist in the feature file before reporting uncovered scenarios", "deleted": false, "createdAt": "2025-11-18T01:08:26.481Z" }, { "id": 3, "text": "Coverage statistics (totalScenarios, coveredScenarios) must be recalculated after removing deleted scenarios", "deleted": false, "createdAt": "2025-11-18T01:08:31.672Z" }, { "id": 4, "text": "Use explicit rename command (update-scenario) to preserve mappings. When user runs update-scenario, rename coverage entry and preserve test mappings. Manual delete + create loses mappings (expected behavior).", "deleted": false, "createdAt": "2025-11-18T01:15:28.909Z" }, { "id": 5, "text": "Use conditional notifications: (1) Explicit user commands (delete-scenario) always notify about coverage updates, (2) Automatic cleanup (generate-coverage, updateCoverageFile) only notify if stale scenarios found, (3) Validation errors always notify. Use ✓ for successful actions, ℹ for informational cleanup, ✗ for errors.", "deleted": false, "createdAt": "2025-11-18T01:16:37.116Z" } ], "nextRuleId": 6, "examples": [ { "id": 0, "text": "Developer deletes 'Scenario B' from test.feature using delete-scenario command. The .feature.coverage file automatically removes the 'Scenario B' entry and recalculates stats.", "deleted": false, "createdAt": "2025-11-18T01:08:38.559Z" }, { "id": 1, "text": "Developer deletes multiple scenarios tagged @deprecated using delete-scenarios-by-tag. All deleted scenarios are removed from coverage files across multiple feature files.", "deleted": false, "createdAt": "2025-11-18T01:08:43.454Z" }, { "id": 2, "text": "Developer runs update-work-unit-status to 'validating'. Coverage checker detects that coverage file has 'Scenario C' but feature file doesn't. System suggests running generate-coverage to sync.", "deleted": false, "createdAt": "2025-11-18T01:08:50.408Z" }, { "id": 3, "text": "Developer runs generate-coverage on a feature that has scenarios A and B in feature file but coverage file has A, B, C (stale). Coverage file is updated to only have A and B.", "deleted": false, "createdAt": "2025-11-18T01:08:55.475Z" }, { "id": 4, "text": "Developer has coverage file with uncovered 'Scenario X' but deletes the scenario from feature file. Running update-work-unit-status no longer reports 'Scenario X uncovered' error.", "deleted": false, "createdAt": "2025-11-18T01:09:00.576Z" }, { "id": 5, "text": "Developer runs update-scenario to rename 'User logs in' to 'User authenticates'. The coverage file entry is renamed and all test mappings are preserved.", "deleted": false, "createdAt": "2025-11-18T01:16:43.638Z" } ], "nextExampleId": 6, "questions": [ { "id": 0, "text": "@human: Should we preserve test/implementation mappings from deleted scenarios in a separate archive file for historical tracking?", "deleted": false, "createdAt": "2025-11-18T01:09:07.148Z", "selected": true, "answer": "No, do not preserve mappings from deleted scenarios. Clean removal without archiving." }, { "id": 1, "text": "@human: What should happen if a scenario is renamed (appears as both deleted and new)? Should we attempt to preserve mappings based on step similarity?", "deleted": false, "createdAt": "2025-11-18T01:09:12.709Z", "selected": true, "answer": "Use explicit rename command (update-scenario) to preserve mappings. When user runs update-scenario, rename coverage entry and preserve test mappings. Manual delete + create loses mappings (expected behavior)." }, { "id": 2, "text": "@human: Should the fix emit warnings/notifications when stale scenarios are removed from coverage files, or silently clean up?", "deleted": false, "createdAt": "2025-11-18T01:09:18.277Z", "selected": true, "answer": "Use conditional notifications: (1) Explicit user commands (delete-scenario) always notify about coverage updates, (2) Automatic cleanup (generate-coverage, updateCoverageFile) only notify if stale scenarios found, (3) Validation errors always notify. Use ✓ for successful actions, ℹ for informational cleanup, ✗ for errors." } ], "nextQuestionId": 3, "assumptions": [ "No, do not preserve mappings from deleted scenarios. Clean removal without archiving." ], "estimate": 5, "architectureNotes": [ { "id": 0, "text": "Fix delete-scenario.ts: After deleting scenario from feature file (line 162), load coverage file, remove scenario entry, recalculate stats, write updated coverage using fileManager.transaction()", "deleted": false, "createdAt": "2025-11-18T01:19:12.452Z" }, { "id": 1, "text": "Fix updateCoverageFile() in coverage-file.ts: Add logic to detect deleted scenarios (exist in coverage but not in feature file), filter them out, rebuild scenarios array with only current scenarios", "deleted": false, "createdAt": "2025-11-18T01:19:18.040Z" }, { "id": 2, "text": "Fix checkCoverageCompleteness() in update-work-unit-status.ts: Before checking for uncovered scenarios, validate coverage file scenarios against feature file scenarios using getScenariosFromFeatureFile(), emit error if stale scenarios detected", "deleted": false, "createdAt": "2025-11-18T01:19:23.744Z" }, { "id": 3, "text": "Fix update-scenario.ts: When scenario renamed, also rename the scenario entry in coverage file (find by old name, update name field, preserve testMappings array)", "deleted": false, "createdAt": "2025-11-18T01:19:29.555Z" } ], "nextNoteId": 4, "attachments": [ "spec/attachments/COV-055/ast-research-coverage-sync-bug.md" ], "updated": "2025-11-18T01:40:58.748Z" }, "DOC-016": { "id": "DOC-016", "title": "Documentation Clarity Improvements", "type": "story", "status": "done", "createdAt": "2025-11-18T02:11:02.446Z", "updatedAt": "2025-11-18T02:54:15.647Z", "description": "Address confusing or unclear sections in fspec bootstrap documentation based on AI feedback", "children": [], "attachments": [ "spec/attachments/DOC-016/ai-feedback-on-documentation.md", "spec/attachments/DOC-016/ast-research-slash-command-sections.md" ], "userStory": { "role": "AI agent using fspec", "action": "understand all bootstrap documentation without confusion", "benefit": "I can confidently use fspec commands and workflows in the correct context" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T02:20:49.466Z" }, { "state": "testing", "timestamp": "2025-11-18T02:39:51.267Z" }, { "state": "implementing", "timestamp": "2025-11-18T02:43:05.216Z" }, { "state": "validating", "timestamp": "2025-11-18T02:54:00.130Z" }, { "state": "done", "timestamp": "2025-11-18T02:54:15.647Z" } ], "questions": [ { "id": 0, "text": "@human: How should we address the Event Storm naming confusion? Should we rename 'Big Picture Event Storming' and 'Event Storm - Domain Discovery' to make them more distinct (e.g., 'Strategic Event Storm' vs 'Tactical Event Storm'), or would adding a comparison table early in the docs be better?", "deleted": false, "createdAt": "2025-11-18T02:21:10.978Z", "selected": true, "answer": "Rename to 'Foundation Event Storm' and 'Feature Event Storm' for self-documenting clarity. Add comparison table showing when/scope/storage/commands/output/purpose differences. Foundation aligns with foundation.json, Feature clearly indicates per-story recurring use." }, { "id": 1, "text": "@human: For deciding when to use Feature Event Storm vs skip to Example Mapping - the current criteria are somewhat subjective ('complex domain', 'many entities'). Should we provide a clearer default heuristic, like 'When in doubt for stories >5 points, do Feature Event Storm' or 'Always do Feature Event Storm for new domains, skip for familiar ones'?", "deleted": false, "createdAt": "2025-11-18T02:24:35.153Z", "selected": true, "answer": "Make Feature Event Storm decision interactive and research-first: 1) Research codebase using 'fspec research --tool=ast --files \"path/to/files\"' FIRST to understand domain, 2) Self-assess based on research findings, 3) If uncertain after research, ASK USER (share findings, let them decide), 4) Proceed with chosen approach. Decision is SUBJECTIVE and COLLABORATIVE - emphasize no guessing, always ask if unsure. Research builds familiarity before judgment." }, { "id": 2, "text": "@human: For @step comment matching (used by link-coverage validation), should we document the exact matching rules for edge cases like: multi-line Gherkin steps, steps with data tables, steps with docstrings, case sensitivity, and whitespace handling? Or are these edge cases rare enough that we can wait for them to come up organically?", "deleted": false, "createdAt": "2025-11-18T02:31:50.442Z", "selected": true, "answer": "After researching the code, these 'edge cases' don't actually exist\\! Feature parser extracts ONLY step.text (not data tables/docstrings). Matching uses hybrid fuzzy similarity with adaptive thresholds (0.70-0.85 based on length), whitespace normalized. Documentation should clarify: @step comments match ONLY the step line text (e.g., 'Given I have items:' NOT the table below). Add simple example showing data table step matching (table content ignored). No need for complex edge case documentation - the implementation is simpler than it appears." } ], "nextQuestionId": 3, "rules": [ { "id": 0, "text": "Rename to 'Foundation Event Storm' and 'Feature Event Storm' for self-documenting clarity. Add comparison table showing when/scope/storage/commands/output/purpose differences. Foundation aligns with foundation.json, Feature clearly indicates per-story recurring use.", "deleted": false, "createdAt": "2025-11-18T02:24:27.886Z" }, { "id": 1, "text": "Make Feature Event Storm decision interactive and research-first: 1) Research codebase using 'fspec research --tool=ast --files \"path/to/files\"' FIRST to understand domain, 2) Self-assess based on research findings, 3) If uncertain after research, ASK USER (share findings, let them decide), 4) Proceed with chosen approach. Decision is SUBJECTIVE and COLLABORATIVE - emphasize no guessing, always ask if unsure. Research builds familiarity before judgment.", "deleted": false, "createdAt": "2025-11-18T02:28:17.429Z" }, { "id": 2, "text": "Add 'Coverage File Lifecycle' section that explicitly separates AUTOMATIC vs MANUAL operations with clear visual labels (✨ AUTOMATIC / 🔧 MANUAL). AUTOMATIC: creation (create-feature, generate-coverage), synchronization (delete-scenario, update-scenario auto-updates coverage), validation (update-work-unit-status blocks if stale). MANUAL: linking tests (link-coverage --test-file), linking implementation (link-coverage --impl-file), manual re-sync if needed. This prevents confusion between auto-sync and manual linking.", "deleted": false, "createdAt": "2025-11-18T02:31:42.997Z" }, { "id": 3, "text": "After researching the code, these 'edge cases' don't actually exist\\! Feature parser extracts ONLY step.text (not data tables/docstrings). Matching uses hybrid fuzzy similarity with adaptive thresholds (0.70-0.85 based on length), whitespace normalized. Documentation should clarify: @step comments match ONLY the step line text (e.g., 'Given I have items:' NOT the table below). Add simple example showing data table step matching (table content ignored). No need for complex edge case documentation - the implementation is simpler than it appears.", "deleted": false, "createdAt": "2025-11-18T02:34:11.920Z" }, { "id": 4, "text": "Document foundation discovery iteration/recovery capabilities explicitly: 1) Iteration fully supported - update-foundation can re-update any field anytime with no restrictions, 2) Review draft with 'cat spec/foundation.json.draft' (no dedicated command yet), 3) Validation failure recovery - draft persists on --finalize failure, fix errors and re-run, draft only deleted on success, 4) Manual edit protection - direct file edits detected and reverted (CLI-only enforcement). Add clear 'Foundation Discovery Iteration' section explaining these capabilities.", "deleted": false, "createdAt": "2025-11-18T02:36:27.476Z" } ], "nextRuleId": 5, "examples": [ { "id": 0, "text": "In bootstrap docs, Step 3 is 'Big Picture Event Storming (Foundation Level)' and Step 4 is 'Event Storm - Domain Discovery BEFORE Example Mapping'. AI reads both and has to carefully distinguish them. After renaming to 'Foundation Event Storm' and 'Feature Event Storm' with comparison table, the distinction is immediately clear from names alone.", "deleted": false, "createdAt": "2025-11-18T02:36:41.505Z" }, { "id": 1, "text": "AI is about to do Feature Event Storm but hasn't seen the codebase yet. Instead of guessing, AI first runs 'fspec research --tool=ast --files src/auth/*.ts' to understand authentication domain. Then shares findings: 'I found 3 domain events: UserRegistered, LoginAttempted, SessionExpired. Should we do Feature Event Storm to map the full authentication flow?' Human decides based on actual code analysis.", "deleted": false, "createdAt": "2025-11-18T02:36:49.416Z" }, { "id": 2, "text": "AI reads 'coverage files are automatically synchronized' and thinks linking is also automatic. Wastes time waiting for coverage to auto-populate. With ✨ AUTOMATIC vs 🔧 MANUAL labels, AI immediately sees: ✨ AUTOMATIC: create-feature creates .coverage files, delete-scenario syncs coverage. 🔧 MANUAL: link-coverage --test-file required to link tests. AI runs the right commands without confusion.", "deleted": false, "createdAt": "2025-11-18T02:36:58.682Z" }, { "id": 3, "text": "Feature file has 'Given I have the following items:' with a data table below. AI thinks @step comment must include the entire table text. Wastes time trying to format multi-line comment. With clarification that parser extracts ONLY step.text, AI correctly writes: // @step Given I have the following items: (table content ignored by matcher).", "deleted": false, "createdAt": "2025-11-18T02:37:05.930Z" }, { "id": 4, "text": "AI fills field 3 of foundation discovery, then realizes field 1 (project name) was wrong. Without iteration docs, AI might think 'too late, can't go back'. With explicit iteration documentation, AI confidently runs 'fspec update-foundation projectName \"correct-name\"' to fix the mistake, then continues from field 4.", "deleted": false, "createdAt": "2025-11-18T02:37:13.161Z" } ], "nextExampleId": 5, "estimate": 3, "architectureNotes": [ { "id": 0, "text": "Implementation approach: Update bootstrap documentation sections in src/utils/slashCommandSections/ and src/utils/projectManagementSections/ files to incorporate clarity improvements. Rename 'Big Picture Event Storming' to 'Foundation Event Storm' and 'Event Storm - Domain Discovery' to 'Feature Event Storm'. Add comparison tables and visual labels (✨/🔧) for automatic vs manual operations. Update field-by-field guidance in discover-foundation to emphasize iteration support.", "deleted": false, "createdAt": "2025-11-18T02:39:25.062Z" } ], "nextNoteId": 1, "updated": "2025-11-18T02:54:15.647Z" }, "BUG-084": { "id": "BUG-084", "title": "discover-foundation --finalize does not auto-create Foundation Event Storm work unit", "type": "bug", "status": "done", "createdAt": "2025-11-18T03:42:55.104Z", "updatedAt": "2025-11-18T04:52:47.112Z", "description": "After successful foundation discovery finalization, the system should automatically create a work unit for Foundation Event Storm, but it doesn't", "children": [], "attachments": [ "spec/attachments/BUG-084/bug-report.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T04:39:32.960Z" }, { "state": "testing", "timestamp": "2025-11-18T04:43:22.559Z" }, { "state": "implementing", "timestamp": "2025-11-18T04:45:24.235Z" }, { "state": "validating", "timestamp": "2025-11-18T04:52:27.494Z" }, { "state": "done", "timestamp": "2025-11-18T04:52:47.113Z" } ], "userStory": { "role": "developer using fspec for foundation discovery", "action": "have Foundation Event Storm work unit auto-created after finalization", "benefit": "I can immediately proceed with Event Storm workflow without manual setup" }, "rules": [ { "id": 0, "text": "When discover-foundation --finalize succeeds, it MUST auto-create a FOUND-XXX work unit for Foundation Event Storm", "deleted": false, "createdAt": "2025-11-18T04:40:31.531Z" }, { "id": 1, "text": "The FOUND prefix MUST be auto-registered if it doesn't exist", "deleted": false, "createdAt": "2025-11-18T04:40:33.184Z" }, { "id": 2, "text": "Tests MUST use isolated temporary directories and NEVER write to the actual spec/work-units.json file", "deleted": false, "createdAt": "2025-11-18T04:40:34.789Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "First finalize creates FOUND-001 work unit with title 'Foundation Event Storm' in isolated test directory", "deleted": false, "createdAt": "2025-11-18T04:40:43.277Z" }, { "id": 1, "text": "FOUND prefix is auto-registered with description 'Foundation Event Storm tasks' if it doesn't exist", "deleted": false, "createdAt": "2025-11-18T04:40:45.281Z" }, { "id": 2, "text": "Running finalize twice does NOT create duplicate work units (idempotency check in isolated test)", "deleted": false, "createdAt": "2025-11-18T04:40:46.797Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T04:52:47.112Z" }, "BUG-085": { "id": "BUG-085", "title": "Bounded Context Map UI duplicates each bounded context name in visualization", "type": "bug", "status": "done", "createdAt": "2025-11-18T04:12:35.558Z", "updatedAt": "2025-11-18T04:28:51.709Z", "description": "The bounded context map visualization renders each bounded context name twice, even though the foundation.json data contains only single entries", "children": [], "attachments": [ "spec/attachments/BUG-085/bug-report.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T04:21:11.847Z" }, { "state": "testing", "timestamp": "2025-11-18T04:23:04.702Z" }, { "state": "implementing", "timestamp": "2025-11-18T04:24:33.554Z" }, { "state": "validating", "timestamp": "2025-11-18T04:25:20.896Z" }, { "state": "done", "timestamp": "2025-11-18T04:28:51.709Z" } ], "userStory": { "role": "developer using fspec", "action": "view bounded context map visualization", "benefit": "I see each context name displayed exactly once without duplication" }, "rules": [ { "id": 0, "text": "Each bounded context must appear exactly once in the Mermaid diagram node label", "deleted": false, "createdAt": "2025-11-18T04:21:24.388Z" }, { "id": 1, "text": "Mermaid node labels should display context name on first line and brief description on second line using <br/> tag", "deleted": false, "createdAt": "2025-11-18T04:21:30.842Z" }, { "id": 2, "text": "For bounded contexts without hardcoded descriptions, display only the context name without duplication", "deleted": false, "createdAt": "2025-11-18T04:21:36.362Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Bounded context 'Work Management' generates node label 'Work Management<br/>Stories, Epics, Dependencies' (two lines: name + description)", "deleted": false, "createdAt": "2025-11-18T04:21:42.403Z" }, { "id": 1, "text": "Bounded context 'Conversation Management' currently generates 'Conversation Management<br/>Conversation Management' (BUG: duplicated), should generate 'Conversation Management' (single line only)", "deleted": false, "createdAt": "2025-11-18T04:21:48.170Z" }, { "id": 2, "text": "After fix, 'Mind Mapping' context generates node label 'Mind Mapping' (single line, no <br/> tag)", "deleted": false, "createdAt": "2025-11-18T04:21:55.712Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T04:28:51.709Z" }, "BUG-086": { "id": "BUG-086", "title": "Event Storm commands exit with code 1 on success", "type": "bug", "status": "done", "createdAt": "2025-11-18T05:24:38.537Z", "updatedAt": "2025-11-18T06:59:30.693Z", "description": "Commands like add-domain-event exit with code 1 even when successfully completing operations, breaking command chaining and CI/CD pipelines", "children": [], "attachments": [ "spec/attachments/BUG-086/fspec-exit-code-bug-findings.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T06:45:03.334Z" }, { "state": "testing", "timestamp": "2025-11-18T06:47:14.898Z" }, { "state": "implementing", "timestamp": "2025-11-18T06:49:37.356Z" }, { "state": "validating", "timestamp": "2025-11-18T06:54:43.784Z" }, { "state": "done", "timestamp": "2025-11-18T06:59:30.693Z" } ], "userStory": { "role": "AI agent or developer chaining fspec Event Storm commands", "action": "receive correct exit codes from Event Storm commands", "benefit": "command chaining with && works correctly and CI/CD pipelines don't fail" }, "rules": [ { "id": 0, "text": "Event Storm commands must return exit code 0 on success", "deleted": false, "createdAt": "2025-11-18T06:45:24.161Z" }, { "id": 1, "text": "Event Storm commands must return exit code 1 only on actual errors", "deleted": false, "createdAt": "2025-11-18T06:45:29.434Z" }, { "id": 2, "text": "Command chaining with && must work correctly when all commands succeed", "deleted": false, "createdAt": "2025-11-18T06:45:34.108Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Running 'fspec add-domain-event UI-001 TestEvent' successfully adds event and returns exit code 0", "deleted": false, "createdAt": "2025-11-18T06:45:39.814Z" }, { "id": 1, "text": "Running 'fspec add-command UI-001 TestCommand' successfully adds command and returns exit code 0", "deleted": false, "createdAt": "2025-11-18T06:45:45.023Z" }, { "id": 2, "text": "Running 'fspec add-policy UI-001 \"Send email\" --when UserRegistered --then SendEmail' successfully adds policy and returns exit code 0", "deleted": false, "createdAt": "2025-11-18T06:45:50.380Z" }, { "id": 3, "text": "Running 'fspec add-hotspot UI-001 \"Email timeout\" --concern \"Unclear timeout duration\"' successfully adds hotspot and returns exit code 0", "deleted": false, "createdAt": "2025-11-18T06:45:55.023Z" }, { "id": 4, "text": "Chaining commands: 'fspec add-domain-event UI-001 Event1 && fspec add-domain-event UI-001 Event2' should execute both commands when both succeed", "deleted": false, "createdAt": "2025-11-18T06:46:00.112Z" }, { "id": 5, "text": "Running 'fspec add-domain-event NONEXISTENT-001 Event' with invalid work unit should return exit code 1", "deleted": false, "createdAt": "2025-11-18T06:46:05.388Z" } ], "nextExampleId": 6, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T06:59:30.693Z" }, "BUG-087": { "id": "BUG-087", "title": "Event Storm commands allow duplicate entries without validation", "type": "bug", "status": "done", "createdAt": "2025-11-18T05:36:11.191Z", "updatedAt": "2025-11-18T10:27:45.247Z", "description": "Commands like add-domain-event create duplicate entries when the same text is added multiple times, causing data integrity issues and confusion", "children": [], "attachments": [ "spec/attachments/BUG-087/fspec-bug-duplicate-events.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T10:15:41.030Z" }, { "state": "testing", "timestamp": "2025-11-18T10:19:19.812Z" }, { "state": "implementing", "timestamp": "2025-11-18T10:20:46.161Z" }, { "state": "validating", "timestamp": "2025-11-18T10:26:48.803Z" }, { "state": "done", "timestamp": "2025-11-18T10:27:45.247Z" } ], "userStory": { "role": "developer using Event Storm commands", "action": "prevent duplicate entries when adding the same text", "benefit": "Event Storm data stays clean and scenarios generate correctly" }, "rules": [ { "id": 0, "text": "Prevent duplicate Event Storm entries by default (case-insensitive check)", "deleted": false, "createdAt": "2025-11-18T10:16:04.413Z" }, { "id": 1, "text": "Throw error with message: Event 'X' already exists (ID: N)", "deleted": false, "createdAt": "2025-11-18T10:16:11.362Z" }, { "id": 2, "text": "Only check non-deleted entries for duplicates", "deleted": false, "createdAt": "2025-11-18T10:16:19.138Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "add-domain-event UI-001 'EventA' succeeds, add-domain-event UI-001 'EventA' throws error", "deleted": false, "createdAt": "2025-11-18T10:16:26.671Z" }, { "id": 1, "text": "add-domain-event UI-001 'EventA' succeeds, add-domain-event UI-001 'eventa' (lowercase) throws error (case-insensitive)", "deleted": false, "createdAt": "2025-11-18T10:16:33.514Z" }, { "id": 2, "text": "add-domain-event UI-001 'EventA', delete event 0, add-domain-event UI-001 'EventA' succeeds (deleted entries ignored)", "deleted": false, "createdAt": "2025-11-18T10:16:41.207Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T10:27:45.247Z" }, "BUG-088": { "id": "BUG-088", "title": "Malformed question text when transforming Event Storm hotspots to Example Mapping", "type": "bug", "status": "done", "createdAt": "2025-11-18T05:37:18.457Z", "updatedAt": "2025-11-18T10:40:11.504Z", "description": "Questions generated from hotspots have broken grammar with redundant text like 'What should when should... be?' instead of using the concern text directly", "children": [], "attachments": [ "spec/attachments/BUG-088/fspec-bug-malformed-questions.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T10:30:57.924Z" }, { "state": "testing", "timestamp": "2025-11-18T10:32:39.165Z" }, { "state": "implementing", "timestamp": "2025-11-18T10:34:28.995Z" }, { "state": "validating", "timestamp": "2025-11-18T10:39:45.804Z" }, { "state": "done", "timestamp": "2025-11-18T10:40:11.504Z" } ], "userStory": { "role": "developer transforming Event Storm to Example Mapping", "action": "generate clear, grammatically correct questions from hotspot concerns", "benefit": "questions are readable and usable without manual editing" }, "rules": [ { "id": 0, "text": "When hotspot concern is already a question, use concern text as-is with '@human:' prefix", "deleted": false, "createdAt": "2025-11-18T10:31:21.646Z" }, { "id": 1, "text": "Preserve original capitalization of concern text (don't lowercase)", "deleted": false, "createdAt": "2025-11-18T10:31:22.251Z" }, { "id": 2, "text": "Ensure question ends with '?' if concern lacks one", "deleted": false, "createdAt": "2025-11-18T10:31:22.828Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Concern 'When should playlists be saved?' → '@human: When should playlists be saved?'", "deleted": false, "createdAt": "2025-11-18T10:31:31.918Z" }, { "id": 1, "text": "Concern 'How long should metadata be cached' → '@human: How long should metadata be cached?'", "deleted": false, "createdAt": "2025-11-18T10:31:32.473Z" }, { "id": 2, "text": "Concern 'Should drag-and-drop support multi-select? How to handle edge cases?' → '@human: Should drag-and-drop support multi-select? How to handle edge cases?'", "deleted": false, "createdAt": "2025-11-18T10:31:33.038Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T10:40:11.504Z" }, "BUG-089": { "id": "BUG-089", "title": "Generic and unhelpful examples auto-generated from Event Storm domain events", "type": "bug", "status": "done", "createdAt": "2025-11-18T05:38:39.348Z", "updatedAt": "2025-11-18T11:37:01.037Z", "description": "Examples generated from domain events follow template 'User [event] and is logged in' with no concrete data, context, or variation, defeating the purpose of Example Mapping", "children": [], "attachments": [ "spec/attachments/BUG-089/fspec-bug-generic-examples.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T10:47:27.332Z" }, { "state": "testing", "timestamp": "2025-11-18T10:49:28.768Z" }, { "state": "implementing", "timestamp": "2025-11-18T10:51:15.691Z" }, { "state": "validating", "timestamp": "2025-11-18T11:36:28.569Z" }, { "state": "done", "timestamp": "2025-11-18T11:37:01.037Z" } ], "userStory": { "role": "developer transforming Event Storm to Example Mapping", "action": "avoid auto-generated generic examples from domain events", "benefit": "Example Mapping provides value through concrete, specific examples" }, "rules": [ { "id": 0, "text": "System must NOT auto-generate examples from domain events during Event Storm to Example Mapping transformation", "deleted": false, "createdAt": "2025-11-18T10:47:54.076Z" }, { "id": 1, "text": "Example Mapping examples list must remain empty after transformation, allowing humans to add concrete examples", "deleted": false, "createdAt": "2025-11-18T10:48:00.093Z" }, { "id": 2, "text": "Transformation should preserve rules and questions from policies and hotspots, but skip event-to-example conversion", "deleted": false, "createdAt": "2025-11-18T10:48:06.550Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Event Storm with domain event 'TrackPlayed' generates generic example 'User track played and is logged in' (unhelpful)", "deleted": false, "createdAt": "2025-11-18T10:48:12.992Z" }, { "id": 1, "text": "After transformation, examples list should be empty (0 examples added) even when domain events exist", "deleted": false, "createdAt": "2025-11-18T10:48:18.261Z" }, { "id": 2, "text": "Policies still generate rules and hotspots still generate questions (only event-to-example conversion is removed)", "deleted": false, "createdAt": "2025-11-18T10:48:24.031Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T11:37:01.037Z" }, "BUG-090": { "id": "BUG-090", "title": "Answered questions display as 'true' instead of actual answer text", "type": "bug", "status": "done", "createdAt": "2025-11-18T05:39:59.451Z", "updatedAt": "2025-11-18T11:57:35.269Z", "description": "When answering Example Mapping questions, the answer text is lost and replaced with boolean 'true' in feature files and work unit output, losing critical decision context", "children": [], "attachments": [ "spec/attachments/BUG-090/fspec-bug-answers-as-true.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T11:42:30.930Z" }, { "state": "testing", "timestamp": "2025-11-18T11:44:38.292Z" }, { "state": "implementing", "timestamp": "2025-11-18T11:50:27.525Z" }, { "state": "validating", "timestamp": "2025-11-18T11:52:30.507Z" }, { "state": "done", "timestamp": "2025-11-18T11:57:35.269Z" } ], "userStory": { "role": "developer answering Example Mapping questions", "action": "preserve answer text instead of boolean true", "benefit": "decision context is retained for documentation and knowledge sharing" }, "rules": [ { "id": 0, "text": "System must store answer text in question.answer field, not just answered: true boolean", "deleted": false, "createdAt": "2025-11-18T11:43:06.234Z" }, { "id": 1, "text": "Feature file comments must display actual answer text, not boolean value", "deleted": false, "createdAt": "2025-11-18T11:43:06.788Z" }, { "id": 2, "text": "Work unit output must show complete answer text when displaying answered questions", "deleted": false, "createdAt": "2025-11-18T11:43:07.357Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Answer question with 'Cache for 24 hours', feature file shows 'A: Cache for 24 hours' not 'A: true'", "deleted": false, "createdAt": "2025-11-18T11:43:16.419Z" }, { "id": 1, "text": "Answer multiline question, all text preserved in work unit JSON and feature file comments", "deleted": false, "createdAt": "2025-11-18T11:43:16.971Z" }, { "id": 2, "text": "Question answered before BUG-090 fix shows 'A: true', after fix shows actual answer text", "deleted": false, "createdAt": "2025-11-18T11:43:17.519Z" } ], "nextExampleId": 3, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T11:57:35.269Z" }, "VAL-005": { "id": "VAL-005", "title": "Multiple test files mapped to single feature file causes validation errors", "type": "bug", "status": "done", "createdAt": "2025-11-18T08:50:01.873Z", "updatedAt": "2025-11-18T10:04:39.505Z", "description": "When multiple test files are linked to a single feature file via coverage mappings, the step validation logic validates EVERY test file against ALL scenarios in the feature, rather than only validating each test file against its linked scenarios. This causes false validation failures. Design intent: 1 feature file should map to 1 test file (1:1 mapping). AI agents should be reminded to split large feature files into multiple smaller feature files, each with its own test file.", "children": [], "attachments": [ "spec/attachments/VAL-005/validation-bug-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-18T09:43:39.472Z" }, { "state": "testing", "timestamp": "2025-11-18T09:46:26.451Z" }, { "state": "implementing", "timestamp": "2025-11-18T09:49:32.474Z" }, { "state": "specifying", "timestamp": "2025-11-18T09:53:35.195Z" }, { "state": "testing", "timestamp": "2025-11-18T09:56:32.681Z" }, { "state": "implementing", "timestamp": "2025-11-18T09:58:04.862Z" }, { "state": "validating", "timestamp": "2025-11-18T09:59:40.803Z" }, { "state": "done", "timestamp": "2025-11-18T10:04:39.506Z" } ], "userStory": { "role": "AI agent moving work unit through workflow", "action": "enforce 1 feature file = 1 test file", "benefit": "I maintain clean 1:1 mapping and don't allow multiple test files per feature" }, "rules": [ { "id": 0, "text": "When multiple test files are linked to one feature, emit system-reminder suggesting to split the feature file", "deleted": false, "createdAt": "2025-11-18T09:44:39.799Z" }, { "id": 1, "text": "Design intent is 1 feature file = 1 test file for simplicity and maintainability", "deleted": false, "createdAt": "2025-11-18T09:44:45.037Z" }, { "id": 2, "text": "ENFORCE: 1 feature file = 1 test file ONLY", "deleted": false, "createdAt": "2025-11-18T09:54:28.778Z" }, { "id": 3, "text": "If workUnitTestFiles.size > 1, throw error and BLOCK transition", "deleted": false, "createdAt": "2025-11-18T09:54:34.436Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Coverage file shows 5 test files linked to one feature. System emits reminder: 'MULTIPLE TEST FILES DETECTED... RECOMMENDED: Split this feature file into multiple smaller features.'", "deleted": false, "createdAt": "2025-11-18T09:45:01.140Z" }, { "id": 1, "text": "Current bug: PerplexityResearch.test.ts is validated against 'Navigate between layouts' scenario even though coverage links that scenario to useKeyboardNavigation.test.ts. After fix: PerplexityResearch.test.ts only validated against scenarios it's actually linked to", "deleted": false, "createdAt": "2025-11-18T09:45:07.697Z" }, { "id": 2, "text": "Coverage has 1 test file linked to feature -> validation proceeds normally", "deleted": false, "createdAt": "2025-11-18T09:54:40.939Z" }, { "id": 3, "text": "Coverage has 2 test files linked to feature -> throw error: 'Multiple test files detected. Split feature file.'", "deleted": false, "createdAt": "2025-11-18T09:54:48.725Z" } ], "nextExampleId": 4, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-18T10:04:39.505Z" }, "DOC-017": { "id": "DOC-017", "title": "Spec-Driven Development vs fspec Comparison", "type": "task", "status": "backlog", "createdAt": "2025-11-20T01:18:55.524Z", "updatedAt": "2025-11-20T01:30:00.879Z", "description": "Research and document the fundamental differences between traditional spec-driven development frameworks and fspec's just-in-time command system with deterministic feedback", "children": [], "attachments": [ "spec/attachments/DOC-017/ai-spec-frameworks-comparison.md", "spec/attachments/DOC-017/fspec-encapsulation-explained.md", "spec/attachments/DOC-017/diagram-reference.md" ] }, "AGENT-020": { "id": "AGENT-020", "title": "Test Antigravity Support", "type": "story", "status": "done", "createdAt": "2025-11-23T03:45:52.102Z", "updatedAt": "2025-11-23T03:51:59.246Z", "epic": "agent-testing", "children": [], "userStory": { "role": "Antigravity User", "action": "initialize and use fspec with the Antigravity agent", "benefit": "I can leverage fspec's project management capabilities within my Antigravity workflow" }, "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-23T03:46:26.974Z" }, { "state": "testing", "timestamp": "2025-11-23T03:47:39.485Z" }, { "state": "implementing", "timestamp": "2025-11-23T03:49:52.306Z" }, { "state": "validating", "timestamp": "2025-11-23T03:50:32.481Z" }, { "state": "done", "timestamp": "2025-11-23T03:51:59.246Z" } ], "rules": [ { "id": 0, "text": "fspec init should detect or support manual selection of Antigravity agent", "deleted": false, "createdAt": "2025-11-23T03:46:27.851Z" }, { "id": 1, "text": "Standard fspec commands should function correctly in the Antigravity environment", "deleted": false, "createdAt": "2025-11-23T03:46:28.698Z" } ], "nextRuleId": 2, "examples": [ { "id": 0, "text": "User runs 'fspec init --agent=antigravity' and sees success message", "deleted": false, "createdAt": "2025-11-23T03:46:34.845Z" }, { "id": 1, "text": "User runs 'fspec status' and sees correct output in Antigravity terminal", "deleted": false, "createdAt": "2025-11-23T03:46:35.707Z" } ], "nextExampleId": 2, "architectureNotes": [ { "id": 0, "text": "Implement Antigravity agent support by extending the AgentRegistry and ensuring CLI compatibility.", "deleted": false, "createdAt": "2025-11-23T03:47:13.834Z" } ], "nextNoteId": 1, "attachments": [ "spec/attachments/AGENT-020/ast-research-agent-registry.json" ], "questions": [], "nextQuestionId": 0, "updated": "2025-11-23T03:51:59.246Z" }, "BUG-091": { "id": "BUG-091", "title": "link-coverage crashes when coverage file stats are missing", "type": "bug", "status": "done", "createdAt": "2025-11-23T03:50:54.682Z", "updatedAt": "2025-11-23T04:05:53.719Z", "epic": "coverage-tracking", "children": [], "attachments": [ "spec/attachments/BUG-091/bug-report.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-23T04:03:00.894Z" }, { "state": "testing", "timestamp": "2025-11-23T04:03:38.272Z" }, { "state": "implementing", "timestamp": "2025-11-23T04:04:47.954Z" }, { "state": "validating", "timestamp": "2025-11-23T04:05:32.222Z" }, { "state": "done", "timestamp": "2025-11-23T04:05:53.719Z" } ], "rules": [ { "id": 0, "text": "link-coverage must handle missing 'stats' object in coverage files gracefully", "deleted": false, "createdAt": "2025-11-23T04:03:01.703Z" }, { "id": 1, "text": "link-coverage must automatically initialize 'stats' if missing before updating", "deleted": false, "createdAt": "2025-11-23T04:03:02.461Z" } ], "nextRuleId": 2, "examples": [ { "id": 0, "text": "User runs link-coverage on a manually created coverage file without stats object", "deleted": false, "createdAt": "2025-11-23T04:03:03.217Z" } ], "nextExampleId": 1, "userStory": { "role": "Developer", "action": "link coverage to a feature file", "benefit": "I don't encounter crashes even if the coverage file is incomplete" }, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-23T04:05:53.719Z" }, "REFAC-005": { "id": "REFAC-005", "title": "Refactor link-coverage command to reduce file size and complexity", "type": "story", "status": "done", "createdAt": "2025-11-23T05:03:22.570Z", "updatedAt": "2025-11-23T05:44:14.720Z", "epic": "coverage-tracking", "children": [], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-23T05:03:33.115Z" }, { "state": "testing", "timestamp": "2025-11-23T05:04:23.846Z" }, { "state": "implementing", "timestamp": "2025-11-23T05:41:33.169Z" }, { "state": "validating", "timestamp": "2025-11-23T05:43:59.577Z" }, { "state": "done", "timestamp": "2025-11-23T05:44:14.720Z" } ], "userStory": { "role": "Developer", "action": "refactor the link-coverage command", "benefit": "the code is maintainable and complies with project standards" }, "rules": [ { "id": 0, "text": "link-coverage.ts must be split into smaller, focused modules", "deleted": false, "createdAt": "2025-11-23T05:03:35.832Z" }, { "id": 1, "text": "File size must be reduced below 300 lines", "deleted": false, "createdAt": "2025-11-23T05:03:36.550Z" }, { "id": 2, "text": "Functionality must remain identical to the original implementation", "deleted": false, "createdAt": "2025-11-23T05:03:37.332Z" } ], "nextRuleId": 3, "examples": [ { "id": 0, "text": "Developer runs link-coverage after refactoring and it works exactly as before", "deleted": false, "createdAt": "2025-11-23T05:03:38.145Z" }, { "id": 1, "text": "Developer checks file sizes and confirms link-coverage.ts is < 300 lines", "deleted": false, "createdAt": "2025-11-23T05:03:38.938Z" } ], "nextExampleId": 2, "architectureNotes": [ { "id": 0, "text": "Split link-coverage.ts into core logic, validation, and stats update modules", "deleted": false, "createdAt": "2025-11-23T05:04:12.655Z" } ], "nextNoteId": 1, "attachments": [ "spec/attachments/REFAC-005/ast-research-link-coverage.json" ], "questions": [], "nextQuestionId": 0, "updated": "2025-11-23T05:44:14.720Z" }, "BUG-092": { "id": "BUG-092", "title": "Duplicate question IDs from generate-example-mapping-from-event-storm", "type": "bug", "status": "done", "createdAt": "2025-11-24T10:03:51.019Z", "updatedAt": "2025-11-24T10:20:32.349Z", "description": "generate-example-mapping-from-event-storm creates duplicate question IDs by using questions.length instead of nextQuestionId", "children": [], "attachments": [ "spec/attachments/BUG-092/bug-analysis.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-24T10:09:47.383Z" }, { "state": "testing", "timestamp": "2025-11-24T10:12:13.018Z" }, { "state": "implementing", "timestamp": "2025-11-24T10:14:46.041Z" }, { "state": "validating", "timestamp": "2025-11-24T10:17:08.272Z" }, { "state": "done", "timestamp": "2025-11-24T10:20:32.349Z" } ], "userStory": { "role": "developer using fspec", "action": "have unique question IDs after generating example mapping from event storm", "benefit": "data integrity is maintained and no duplicate IDs corrupt the work unit" }, "rules": [ { "id": 0, "text": "Question IDs must be assigned using workUnit.nextQuestionId counter, not array length", "deleted": false, "createdAt": "2025-11-24T10:10:14.029Z" }, { "id": 1, "text": "nextQuestionId counter must be incremented after each question is added", "deleted": false, "createdAt": "2025-11-24T10:10:19.760Z" }, { "id": 2, "text": "nextQuestionId must be initialized to 0 if undefined for backward compatibility", "deleted": false, "createdAt": "2025-11-24T10:10:24.975Z" }, { "id": 3, "text": "Same pattern must apply to rules and examples for consistency", "deleted": false, "createdAt": "2025-11-24T10:10:31.043Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "When hotspots are transformed to questions, nextQuestionId starts at 0 if undefined", "deleted": false, "createdAt": "2025-11-24T10:10:43.296Z" }, { "id": 1, "text": "When 3 hotspots are converted, questions get IDs 0, 1, 2 and nextQuestionId becomes 3", "deleted": false, "createdAt": "2025-11-24T10:10:49.058Z" }, { "id": 2, "text": "Running generate-example-mapping-from-event-storm twice does not create duplicate IDs", "deleted": false, "createdAt": "2025-11-24T10:10:54.976Z" }, { "id": 3, "text": "After event storm mapping, manual add-question command gets next sequential ID without collision", "deleted": false, "createdAt": "2025-11-24T10:11:00.883Z" } ], "nextExampleId": 4, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-24T10:20:32.349Z" }, "BUG-093": { "id": "BUG-093", "title": "VAL-005 1:1 validation checks across entire work unit instead of per-feature", "type": "bug", "status": "done", "createdAt": "2025-11-26T05:40:01.619Z", "updatedAt": "2025-11-26T06:27:26.189Z", "children": [], "attachments": [ "spec/attachments/BUG-093/bug-report.md" ], "stateHistory": [ { "state": "specifying", "timestamp": "2025-11-26T05:42:10.754Z" }, { "state": "testing", "timestamp": "2025-11-26T05:44:58.615Z" }, { "state": "implementing", "timestamp": "2025-11-26T05:47:21.419Z" }, { "state": "validating", "timestamp": "2025-11-26T06:23:05.882Z" }, { "state": "done", "timestamp": "2025-11-26T06:27:26.190Z" } ], "userStory": { "role": "developer using fspec", "action": "have VAL-005 validate 1:1 feature-to-test mapping per individual feature file", "benefit": "work units with multiple features can pass validation when each feature has exactly one test file" }, "rules": [ { "id": 0, "text": "VAL-005 must check 1:1 mapping per individual feature file, not across all features", "deleted": false, "createdAt": "2025-11-26T05:42:27.605Z" }, { "id": 1, "text": "Each feature file must have exactly one test file linked to it", "deleted": false, "createdAt": "2025-11-26T05:42:29.165Z" }, { "id": 2, "text": "A feature file with zero test files should fail validation", "deleted": false, "createdAt": "2025-11-26T05:42:30.769Z" }, { "id": 3, "text": "A feature file with more than one test file should fail validation", "deleted": false, "createdAt": "2025-11-26T05:42:32.528Z" } ], "nextRuleId": 4, "examples": [ { "id": 0, "text": "Work unit with 1 feature + 1 test file = PASS", "deleted": false, "createdAt": "2025-11-26T05:42:41.768Z" }, { "id": 1, "text": "Work unit with 1 feature + 2 test files = FAIL (multiple test files for single feature)", "deleted": false, "createdAt": "2025-11-26T05:42:43.299Z" }, { "id": 2, "text": "Work unit with 3 features + 3 test files (1 each) = PASS (currently fails - THIS IS THE BUG)", "deleted": false, "createdAt": "2025-11-26T05:42:45.053Z" }, { "id": 3, "text": "Work unit with 3 features where one has 2 test files = FAIL", "deleted": false, "createdAt": "2025-11-26T05:42:46.551Z" }, { "id": 4, "text": "Work unit with 3 features where one has 0 test files = FAIL", "deleted": false, "createdAt": "2025-11-26T05:42:48.050Z" } ], "nextExampleId": 5, "estimate": 2, "questions": [], "architectureNotes": [], "nextQuestionId": 0, "nextNoteId": 0, "updated": "2025-11-26T06:27:26.189Z" } }, "states": { "backlog": [ "AGENT-002", "AGENT-003", "AGENT-004", "AGENT-005", "AGENT-006", "AGENT-007", "AGENT-008", "AGENT-009", "AGENT-010", "AGENT-011", "AGENT-012", "AGENT-013", "AGENT-014", "AGENT-015", "AGENT-016", "AGENT-017", "FEAT-018", "CLEAN-002", "FEAT-020", "AGENT-019", "GRAPH-001", "GRAPH-002", "GRAPH-003", "NAV-001", "NAV-002", "NAV-003", "DOC-007", "DOC-008", "DOC-009", "DOC-010", "DOC-011", "DOMAIN-001", "DOMAIN-002", "DOMAIN-003", "DOMAIN-004", "DOMAIN-005", "TAG-001", "TAG-002", "TAG-003", "TAG-004", "VIZ-001", "VIZ-002", "VIZ-003", "VIZ-004", "INT-001", "INT-002", "INT-003", "INT-004", "DOC-012", "DOC-013", "DOC-014", "DOC-017" ], "specifying": [ "LANG-001", "EXMAP-004", "BOARD-020", "AGENT-001", "BROWSE-001" ], "testing": [], "implementing": [], "validating": [], "done": [ "BUG-093", "BUG-092", "REFAC-005", "BUG-091", "AGENT-020", "BUG-090", "BUG-089", "BUG-088", "BUG-087", "VAL-005", "BUG-086", "BUG-084", "BUG-085", "DOC-016", "COV-055", "BUG-083", "CLEAN-004", "BUG-082", "BUG-081", "TEST-009", "FOUND-042", "FOUND-022", "FOUND-033", "BUG-079", "BUG-078", "DOCS-003", "FOUND-021", "FOUND-019", "FOUND-017", "FOUND-016", "FOUND-015", "FOUND-013", "FOUND-014", "EXMAP-016", "HELP-006", "EXMAP-015", "EXMAP-014", "EXMAP-012", "EXMAP-010", "EXMAP-011", "EXMAP-007", "BUG-077", "EXMAP-006", "EXMAP-005", "VAL-004", "INIT-016", "REMIND-014", "RES-021", "PERF-001", "VAL-003", "VAL-001", "DEP-003", "RES-020", "RES-019", "BUG-076", "TUI-030", "BUG-075", "REVIEW-001", "REMIND-013", "RES-018", "RES-017", "COV-054", "BUG-074", "RES-016", "RES-009", "HOOK-012", "RES-015", "RES-014", "RES-013", "RES-010", "RES-012", "RES-011", "RES-008", "TECH-001", "RES-006", "RES-007", "RES-001", "RES-005", "RES-004", "RES-003", "TUI-029", "BUG-072", "BUG-071", "BUG-070", "REMIND-011", "REMIND-010", "VIEW-002", "TUI-028", "BUG-069", "TUI-027", "GIT-012", "TUI-026", "TUI-025", "TUI-024", "TUI-023", "GIT-011", "VIEW-001", "TUI-022", "TUI-021", "REFAC-004", "TUI-020", "TUI-019", "TUI-013", "TUI-012", "GIT-009", "GIT-010", "TUI-011", "TUI-018", "BUG-068", "REFAC-003", "BUG-066", "BUG-053", "TUI-017", "BUG-065", "BUG-064", "TUI-016", "BUG-063", "TUI-015", "TUI-014", "BUG-062", "BUG-059", "BUG-060", "BUG-061", "BUG-058", "CLI-014", "BUG-055", "COV-053", "DISC-002", "BUG-057", "HELP-005", "BUG-056", "CLEAN-003", "INIT-015", "CLI-013", "BUG-054", "IDX-002", "IDX-001", "MIG-001", "TUI-010", "TUI-009", "TUI-008", "TUI-007", "TUI-006", "TUI-005", "TUI-004", "TUI-002", "TUI-001", "BUG-050", "GIT-008", "GIT-007", "GIT-006", "GIT-004", "BUG-049", "AGENT-018", "BUG-048", "ITF-008", "ITF-007", "ITF-006", "BOARD-019", "BOARD-018", "INIT-014", "INIT-013", "BOARD-017", "BUG-047", "LOG-002", "LOG-001", "LOCK-002", "LOCK-001", "BOARD-014", "BOARD-016", "BOARD-015", "BOARD-013", "BOARD-012", "BUG-046", "BOARD-011", "BOARD-010", "BUG-045", "BOARD-009", "BOARD-008", "BOARD-007", "BOARD-006", "BOARD-005", "ITF-005", "ITF-004", "ITF-003", "ITF-002", "ITF-001", "HELP-004", "INIT-012", "CONFIG-003", "INIT-011", "CONFIG-002", "REV-005", "REV-004", "BUG-044", "REV-003", "FEAT-019", "REMIND-009", "REV-002", "TEST-006", "CLI-012", "QRY-002", "CLI-011", "BUG-043", "GIT-005", "REFAC-002", "BUG-042", "BUG-041", "CONFIG-001", "CLI-010", "CLI-009", "CLI-008", "BOARD-004", "RES-002", "BUG-040", "BUG-038", "BUG-037", "DEP-002", "BUG-035", "BOARD-003", "BUG-034", "BUG-033", "DOC-005", "INIT-010", "INIT-009", "BUG-032", "FEAT-017", "BUG-031", "BUG-030", "BUG-029", "BUG-028", "CLI-007", "BUG-027", "TECH-002", "INIT-008", "BUG-026", "BUG-025", "INIT-006", "INIT-005", "BUG-024", "INIT-004", "CLEAN-001", "BOARD-002", "GIT-003", "GIT-002", "GIT-001", "HELP-003", "BUG-023", "SPEC-003", "SPEC-002", "BUG-022", "BUG-021", "DOCS-002", "UX-001", "REV-001", "BUG-020", "FEAT-016", "DOCS-001", "BUG-019", "FEAT-015", "FEAT-014", "BUG-018", "BUG-017", "BUG-016", "BUG-015", "DISC-001", "FOUND-010", "FOUND-009", "HELP-002", "HELP-001", "COV-052", "REFAC-001", "TEST-005", "BUG-014", "FOUND-007", "BUG-013", "BUG-012", "FOUND-006", "FOUND-005", "FOUND-004", "FOUND-003", "FOUND-002", "FOUND-001", "TEST-004", "HOOK-010", "FEAT-013", "FEAT-012", "BUG-011", "HOOK-009", "HOOK-008", "HOOK-007", "HOOK-006", "HOOK-005", "HOOK-004", "HOOK-003", "HOOK-002", "HOOK-001", "EXMAP-003", "EXMAP-002", "BUG-010", "DOC-004", "FEAT-011", "FEAT-006", "BUG-008", "BUG-007", "COV-051", "COV-050", "COV-049", "COV-048", "COV-047", "COV-046", "COV-045", "COV-044", "COV-043", "COV-042", "COV-041", "COV-040", "COV-039", "COV-038", "COV-037", "COV-036", "COV-035", "COV-034", "COV-033", "COV-032", "COV-031", "COV-030", "COV-029", "COV-028", "COV-027", "COV-026", "COV-025", "COV-024", "COV-023", "COV-022", "COV-021", "COV-020", "COV-019", "COV-018", "COV-017", "COV-016", "COV-015", "COV-014", "COV-013", "COV-012", "COV-011", "COV-010", "DOC-003", "COV-008", "COV-007", "BUG-006", "BUG-005", "COV-006", "COV-005", "COV-004", "COV-003", "COV-002", "COV-001", "REMIND-008", "REMIND-007", "REMIND-006", "REMIND-005", "REMIND-004", "REMIND-003", "REMIND-002", "BUG-004", "CLI-006", "CLI-005", "BUG-003", "RSPEC-001", "DOC-002", "INIT-003", "BUG-002", "BUG-001", "CLI-004", "SAFE-002", "TEST-003", "CLI-003", "TEST-002", "REMIND-001", "DOC-001", "CLI-002", "SAFE-001", "BOARD-001", "INIT-002", "FEAT-005", "FEAT-004", "FEAT-003", "FEAT-002", "FEAT-001", "SPEC-001", "QRY-001", "EST-001", "DEP-001", "CLI-001", "INIT-001", "EXMAP-001" ], "blocked": [ "QUERY-001" ] }, "migrationHistory": [ { "version": "0.7.0", "applied": "2025-10-31T10:37:21.791Z", "backupPath": "spec/work-units.json.backup-0.7.0-1761907041785" }, { "version": "0.7.0", "applied": "2025-10-31T10:55:37.023Z", "backupPath": "spec/work-units.json.backup-0.7.0-1761908137018" } ], "version": "0.7.0", "prefixCounters": { "CLI": 14, "HELP": 6, "BUG": 93, "DISC": 2, "COV": 55, "TUI": 30, "REFAC": 5, "VIEW": 2, "DOC": 17, "GIT": 12, "FEAT": 20, "REMIND": 14, "CODEX": 1, "AGENT": 20, "GRAPH": 3, "NAV": 3, "DOMAIN": 5, "TAG": 4, "VIZ": 4, "INT": 4, "VID": 2, "RES": 21, "BROWSE": 1, "TEST": 10, "HOOK": 12, "REVIEW": 1, "DEP": 3, "VAL": 5, "PERF": 1, "INIT": 16, "EXMAP": 16, "FOUND": 43, "DOCS": 3, "CLEAN": 4 } }