project-iris 0.3.0 → 0.3.1

package/flows/aidlc/skills/construction/bolt-start.md

@@ -159,9 +159,22 @@ Based on bolt state:
 - **completed** → Inform user bolt is done
 - **blocked** → Show blocker, ask how to resolve
 
-### 6. Update Bolt File on Start (CRITICAL - DO FIRST)
+### 6. Update Bolt File on Start (CRITICAL - HARD GATE)
 
-**⚠️ BEFORE any stage work begins, update the bolt file IMMEDIATELY.**
+**⛔ HARD GATE - MUST EXECUTE BEFORE ANY STAGE WORK**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  BOLT FILE UPDATE - NON-NEGOTIABLE                          │
+│                                                              │
+│  You CANNOT proceed to stage work until you have:           │
+│  1. Used the Edit tool to update bolt.md                    │
+│  2. Verified the edit was applied                           │
+│  3. Shown the user confirmation of the update               │
+│                                                              │
+│  This is a BLOCKING GATE - no exceptions.                   │
+└─────────────────────────────────────────────────────────────┘
+```
 
 When transitioning from `planned` to `in-progress`:
 
@@ -173,11 +186,23 @@ current_stage: {first-stage}  # was: null (e.g., "domain-design")
 ---
 ```
 
-**This is NON-NEGOTIABLE.** The bolt file must reflect that work has begun before any stage activities start. This ensures:
+**Verification Output (REQUIRED):**
+
+After editing, output this confirmation to the user:
+
+```text
+✅ Bolt file updated: {bolt-id}/bolt.md
+   - status: planned → in-progress
+   - started: {timestamp}
+   - current_stage: {stage-name}
+```
+
+**Why This Gate Exists:**
 
 1. Progress is tracked even if execution is interrupted
 2. Other tools/agents see accurate status
 3. Resumption works correctly
+4. **Prevents "Lost in the Middle" bug where updates are skipped**
 
 **Also update construction log** (see "Update Construction Log" section below).
 
@@ -216,26 +241,53 @@ For the current stage, follow the bolt type definition:
    - Use templates if specified by bolt type
    - Place in correct paths per schema
 
-### 7b. Story-by-Story Execution (Code Generation Stages)
+### 7b. Story-by-Story Execution (Code Generation Stages) - HARD GATE
 
-**⛔ CRITICAL**: When executing stages that involve code generation (e.g., Stage 4 in DDD bolts), process stories SEQUENTIALLY:
+**⛔ HARD GATE - SEQUENTIAL STORY EXECUTION REQUIRED**
 
 ```text
 ┌─────────────────────────────────────────────────────────────┐
-│  STORY-BY-STORY EXECUTION                                    │
+│  STORY-BY-STORY EXECUTION - NON-NEGOTIABLE                  │
 │                                                              │
-│  For EACH story in bolt's stories array:                     │
-│  1. Announce: "⏳ Story {n}/{total}: {story-id}"             │
-│  2. Read story file for acceptance criteria                  │
-│  3. Implement code for that story                            │
-│  4. Update stories_progress in bolt file                     │
-│  5. Announce: "✅ Story {story-id}: Implemented"             │
+│  ⛔ FORBIDDEN: Implementing multiple stories at once         │
+│  ⛔ FORBIDDEN: Skipping story file reads                     │
+│  ⛔ FORBIDDEN: Not updating stories_progress in bolt file    │
 │                                                              │
-│  DO NOT batch implement - track each story individually!     │
+│  You MUST process stories ONE AT A TIME in sequence.         │
+│  Each story requires its own announce → read → implement →   │
+│  update cycle. Batch implementation = broken traceability.   │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-**Story Progress Display (show after each story)**:
+**For EACH story in bolt's stories array, execute this exact sequence:**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY EXECUTION LOOP (repeat for each story)               │
+│                                                              │
+│  STEP A: Announce start                                      │
+│  Output: "⏳ Story {n}/{total}: {story-id} - {title}"       │
+│                                                              │
+│  STEP B: Read story file (MANDATORY)                         │
+│  Action: Read {intent}/units/{unit}/stories/{story-id}.md   │
+│  Purpose: Extract acceptance criteria for implementation     │
+│                                                              │
+│  STEP C: Implement code for THIS story only                  │
+│  Action: Create/modify code to satisfy acceptance criteria   │
+│  Add traceability: // Story: {story-id}                      │
+│                                                              │
+│  STEP D: Update bolt file stories_progress (MANDATORY)       │
+│  Action: Edit bolt.md to mark story as completed             │
+│                                                              │
+│  STEP E: Announce completion                                 │
+│  Output: "✅ Story {story-id}: Implemented → `{files}`"     │
+│                                                              │
+│  STEP F: Show updated progress list                          │
+│  Then proceed to next story (back to STEP A)                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story Progress Display (show after EACH story completion):**
 
 ```markdown
 ### Story Progress ({completed}/{total})
@@ -248,7 +300,7 @@ For the current stage, follow the bolt type definition:
 6. [ ] **{SSS}-{story-slug}**: Pending
 ```
 
-**Update bolt file after each story:**
+**Update bolt file after EACH story (not at the end):**
 
 ```yaml
 stories_progress:
@@ -264,10 +316,51 @@ stories_progress:
     status: pending
 ```
 
-This ensures:
-- Clear visibility into which story is being worked on
-- Ability to resume if interrupted
-- Validation that all stories are addressed
+**Why This Pattern Exists:**
+
+1. **Traceability**: Each piece of code maps to a specific story
+2. **Resumability**: If interrupted, we know exactly where to continue
+3. **Verification**: We can validate that ALL stories were addressed
+4. **Visibility**: User sees clear progress through the work
+5. **Quality**: Reading acceptance criteria prevents missed requirements
+
+### 7c. Final Regression Check (After All Stories Implemented)
+
+**⛔ REQUIRED: After implementing all stories, verify no regressions**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  REGRESSION CHECK - BEFORE STAGE CHECKPOINT                  │
+│                                                              │
+│  After ALL stories are implemented, you MUST verify:         │
+│  1. Re-read acceptance criteria from FIRST story             │
+│  2. Verify the implementation still satisfies those ACs      │
+│  3. Repeat for each story in order                           │
+│  4. Report any regressions found                             │
+│                                                              │
+│  Later stories may have broken earlier implementations.      │
+│  Catch this BEFORE moving to Testing stage.                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Regression Check Output:**
+
+```text
+### Regression Check ({stories_count} stories)
+
+1. ✅ **{story-1}**: All ACs still valid
+2. ✅ **{story-2}**: All ACs still valid
+3. ⚠️ **{story-3}**: AC2 regression - {description} → FIX REQUIRED
+4. ✅ **{story-4}**: All ACs still valid
+
+{If regressions found: Fix before proceeding to checkpoint}
+```
+
+**Why This Check Exists:**
+
+- Story N implementation may modify shared code
+- Changes could invalidate Story 1-N-1 acceptance criteria
+- Catching regressions early prevents cascade failures in Testing stage
 
 ### 8. Handle Checkpoints (As Defined by Bolt Type)
 
@@ -310,14 +403,29 @@ If the bolt type specifies automatic validation criteria, follow those rules.
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### 9. Update Bolt File on Stage Completion
+### 9. Update Bolt File on Stage Completion (HARD GATE)
+
+**⛔ HARD GATE - MUST EXECUTE AFTER EACH STAGE**
 
 **Trigger**: After EACH stage completion (not just final stage).
 
-After each stage completion:
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STAGE COMPLETION UPDATE - NON-NEGOTIABLE                   │
+│                                                              │
+│  Before presenting checkpoint to user, you MUST:            │
+│  1. Use Edit tool to update bolt.md with stage completion   │
+│  2. Show verification output to user                        │
+│  3. Only THEN present the checkpoint prompt                 │
+│                                                              │
+│  Stages not recorded in bolt.md = stages not done.          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Required Updates:**
 
 - Add stage to `stages_completed` with timestamp
-- Update `current_stage` to next stage
+- Update `current_stage` to next stage (or null if final)
 
 **⚠️ TIMESTAMP FORMAT**: See `memory-bank.yaml` → `conventions.timestamps`
 
@@ -332,9 +440,18 @@ stages_completed:
 ---
 ```
 
+**Verification Output (REQUIRED):**
+
+```text
+✅ Stage recorded: {stage-name}
+   - stages_completed: [{list of completed stages}]
+   - current_stage: {next-stage-name}
+   - artifact: {artifact-filename}
+```
+
 **If this is the FINAL stage**, proceed to **Step 10** (bolt completion).
 
-**If this is NOT the final stage**, update bolt file and proceed to next stage. Stop here.
+**If this is NOT the final stage**, update bolt file, show verification, then present checkpoint.
 
 ---
 

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt.md

@@ -386,8 +386,9 @@ Implement CQRS pattern with separate read models for task queries.
 
 **After ALL stories are implemented:**
 
-6 - **Setup project structure**: Verify scaffolding exists
-7 - **Run code quality validation**: Execute linting, type checking, build
+6 - **Run regression check**: Re-verify ALL story acceptance criteria still valid
+7 - **Setup project structure**: Verify scaffolding exists
+8 - **Run code quality validation**: Execute linting, type checking, build
 
 **Artifact**: Source code in unit directory
 **Location**: `src/{unit}/` or as defined in project structure
@@ -433,6 +434,7 @@ src/{unit}/
 **Completion Criteria**:
 
 - [ ] **All stories implemented in order** (see Story Progress below)
+- [ ] **Regression check passed** - all previous story ACs still valid
 - [ ] All domain models implemented
 - [ ] All use cases implemented
 - [ ] All API endpoints implemented
@@ -459,6 +461,13 @@ src/{unit}/
 5. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
 6. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
 
+### Regression Check ({n}/{n} stories verified)
+
+1. ✅ **{SSS}-{story-slug}**: All ACs still valid
+2. ✅ **{SSS}-{story-slug}**: All ACs still valid
+3. ✅ **{SSS}-{story-slug}**: All ACs still valid
+...
+
 ### Code Generated
 - {n} domain entities
 - {n} use cases
@@ -469,6 +478,7 @@ src/{unit}/
 - ✅ Types: Passed
 - ✅ Build: Passed
 - ✅ Traceability: All files linked to stories
+- ✅ Regression: No story ACs broken
 
 ### Acceptance Criteria Preview
 Each story's ACs will be validated in Stage 5 (Testing).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-iris",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {

package/scripts/bolt-complete.js

@@ -58,6 +58,8 @@
  *   │ 3. If not complete:                                              │
  *   │      status: {current} → complete                                 │
  *   │      implemented: false → true                                    │
+ *   │ 4. Check off acceptance criteria checkboxes:                     │
+ *   │      - [ ] → - [x] (within ## Acceptance Criteria section)       │
  *   │                                                                  │
  *   │ Story search strategy:                                           │
  *   │ - Direct path: {intent}/units/{unit}/stories/{story}.md          │
@@ -106,7 +108,7 @@
  *   │           └── {unit}/
  *   │               ├── unit-brief.md  ← Updated: status (if all bolts complete)
  *   │               └── stories/
- *   │                   ├── 001-{story}.md  ← Updated: status, implemented
+ *   │                   ├── 001-{story}.md  ← Updated: status, implemented, ACs checked
  *   │                   └── ...
  *
  * ┌──────────────────────────────────────────────────────────────────────────┐
@@ -177,6 +179,50 @@ function updateFrontmatter(content, newFrontmatter) {
     return `---\n${newYaml}\n---${content.slice(match[0].length)}`;
 }
 
+/**
+ * Check off all acceptance criteria checkboxes in markdown content
+ * Converts "- [ ]" to "- [x]" in the Acceptance Criteria section
+ */
+function checkAcceptanceCriteria(content) {
+    // Find the Acceptance Criteria section and check all boxes
+    // Pattern matches: - [ ] at start of line (with optional leading whitespace)
+    // Only within Acceptance Criteria section
+
+    const lines = content.split('\n');
+    let inAcceptanceCriteria = false;
+    let modified = false;
+
+    const updatedLines = lines.map(line => {
+        // Check if we're entering Acceptance Criteria section
+        if (line.match(/^##\s*Acceptance Criteria/i)) {
+            inAcceptanceCriteria = true;
+            return line;
+        }
+
+        // Check if we're leaving (another h2 section)
+        if (inAcceptanceCriteria && line.match(/^##\s+[^#]/)) {
+            inAcceptanceCriteria = false;
+            return line;
+        }
+
+        // If in Acceptance Criteria section, check off unchecked boxes
+        if (inAcceptanceCriteria) {
+            const checkedLine = line.replace(/^(\s*-\s*)\[ \]/, '$1[x]');
+            if (checkedLine !== line) {
+                modified = true;
+            }
+            return checkedLine;
+        }
+
+        return line;
+    });
+
+    return {
+        content: updatedLines.join('\n'),
+        modified
+    };
+}
+
 /**
  * Format timestamp as ISO 8601
  * Format: YYYY-MM-DDTHH:MM:SSZ (no milliseconds, per memory-bank.yaml convention)
@@ -357,13 +403,19 @@ async function updateStories(bolt) {
             implemented: true
         };
 
-        const newContent = updateFrontmatter(content, newFrontmatter);
+        let newContent = updateFrontmatter(content, newFrontmatter);
         if (newContent) {
+            // Also check off acceptance criteria checkboxes
+            const acResult = checkAcceptanceCriteria(newContent);
+            newContent = acResult.content;
+            const acChecked = acResult.modified;
+
             await fs.writeFile(storyPath, newContent, 'utf8');
             const oldStatus = frontmatter.status || 'draft';
-            console.log(`  ${colors.green}✓${colors.reset} ${storyId} - ${colors.dim}${oldStatus} → complete${colors.reset}`);
+            const acNote = acChecked ? ` ${colors.dim}(ACs checked)${colors.reset}` : '';
+            console.log(`  ${colors.green}✓${colors.reset} ${storyId} - ${colors.dim}${oldStatus} → complete${colors.reset}${acNote}`);
             results.updated++;
-            results.details.push({ storyId, status: 'updated', from: oldStatus, to: 'complete' });
+            results.details.push({ storyId, status: 'updated', from: oldStatus, to: 'complete', acChecked });
         } else {
             console.log(`  ${colors.red}✗${colors.reset} ${storyId} - ${colors.dim}Failed to update${colors.reset}`);
             results.errors++;