project-iris 0.2.3 → 0.3.1

package/flows/aidlc/commands/construction-agent.md

@@ -35,7 +35,7 @@ You are now the **Construction Agent** for iris AI-DLC.
 - **List Bolts**: `.iris/aidlc/skills/construction/bolt-list.md` → View all bolts
 - **Bolt Status**: `.iris/aidlc/skills/construction/bolt-status.md` → Detailed bolt status
 - **Start/Continue Bolt**: `.iris/aidlc/skills/construction/bolt-start.md` → Execute bolt stages
-- **Plan Bolts**: `.iris/aidlc/skills/construction/bolt-plan.md` → Redirects to Inception
+- **Replan Bolts**: `.iris/aidlc/skills/construction/bolt-replan.md` → Modify bolt plan during construction
 - **Menu**: `.iris/aidlc/skills/construction/navigator.md` → Show skills
 
 ---

package/flows/aidlc/commands/operations-agent.md

@@ -36,6 +36,7 @@ You are now the **Operations Agent** for iris AI-DLC.
 - **Deploy**: `.iris/aidlc/skills/operations/deploy.md` → Deploy to environment
 - **Verify**: `.iris/aidlc/skills/operations/verify.md` → Validate deployment
 - **Monitor**: `.iris/aidlc/skills/operations/monitor.md` → Setup observability
+- **Rollback**: `.iris/aidlc/skills/operations/rollback.md` → Rollback deployment
 - **Menu**: `.iris/aidlc/skills/operations/navigator.md` → Show skills
 
 ---

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

@@ -21,6 +21,9 @@
 - ✅ Checkpoint prompts clear and actionable
 - ✅ Code references stories (comments: `// Story: S-XXX`)
 - ✅ Tests reference acceptance criteria they verify
+- ✅ **Stories processed sequentially in code generation stages**
+- ✅ **Story progress list shown during execution**
+- ✅ **stories_progress updated in bolt file after each story**
 
 ## Failure Modes
 
@@ -30,6 +33,9 @@
 - ❌ Not reading bolt type definition first
 - ❌ Code without story traceability comments
 - ❌ Tests without acceptance criteria references
+- ❌ **Implementing all stories at once without tracking progress**
+- ❌ **Not showing story progress during code generation**
+- ❌ **Stories implemented out of order without justification**
 
 ---
 
@@ -153,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`:
 
@@ -167,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).
 
@@ -194,19 +225,143 @@ For the current stage, follow the bolt type definition:
    {From bolt type definition}
 
    ### Stories in Scope
-   {From bolt instance}
+   {From bolt instance - show with status}
+   - [ ] 001-story-one (pending)
+   - [ ] 002-story-two (pending)
    ```
 
 2. **Perform Activities**:
    - Follow bolt type's activity instructions exactly
    - Create artifacts as specified
    - Respect constraints (e.g., "no code in this stage")
+   - **For code generation stages**: Follow story-by-story execution (see 7b)
 
 3. **Generate Outputs**:
    - Create specified output artifacts
    - Use templates if specified by bolt type
    - Place in correct paths per schema
 
+### 7b. Story-by-Story Execution (Code Generation Stages) - HARD GATE
+
+**⛔ HARD GATE - SEQUENTIAL STORY EXECUTION REQUIRED**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY-BY-STORY EXECUTION - NON-NEGOTIABLE                  │
+│                                                              │
+│  ⛔ FORBIDDEN: Implementing multiple stories at once         │
+│  ⛔ FORBIDDEN: Skipping story file reads                     │
+│  ⛔ FORBIDDEN: Not updating stories_progress in bolt file    │
+│                                                              │
+│  You MUST process stories ONE AT A TIME in sequence.         │
+│  Each story requires its own announce → read → implement →   │
+│  update cycle. Batch implementation = broken traceability.   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**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})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ⏳ **{SSS}-{story-slug}**: In Progress
+4. [ ] **{SSS}-{story-slug}**: Pending
+5. [ ] **{SSS}-{story-slug}**: Pending
+6. [ ] **{SSS}-{story-slug}**: Pending
+```
+
+**Update bolt file after EACH story (not at the end):**
+
+```yaml
+stories_progress:
+  - id: 001-database-init
+    status: completed
+    implemented_at: {timestamp}
+  - id: 002-schema-tables
+    status: completed
+    implemented_at: {timestamp}
+  - id: 003-crud-operations
+    status: in-progress
+  - id: 004-query-helpers
+    status: pending
+```
+
+**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)
 
 The bolt type definition specifies:
@@ -248,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`
 
@@ -270,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.
 
 ---
 
@@ -400,6 +579,13 @@ If construction log doesn't exist, create it using template:
 **Type**: {bolt-type}
 **Progress**: Stage {n} of {total}
 
+### Story Progress ({completed}/{total})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ⏳ **{SSS}-{story-slug}**: In Progress
+4. [ ] **{SSS}-{story-slug}**: Pending
+
 ### Activities Performed
 1. ✅ {activity 1}
 2. ✅ {activity 2}
@@ -408,10 +594,6 @@ If construction log doesn't exist, create it using template:
 ### Artifacts Created
 - `{path/to/artifact}` - {description}
 
-### Stories Addressed
-- ✅ **{SSS}-{story-slug}**: {criteria} - Complete
-- ⏳ **{SSS}-{story-slug}**: {criteria} - In Progress
-
 ---
 
 ### Checkpoint (if defined by bolt type)

package/flows/aidlc/skills/inception/story-create.md

@@ -17,6 +17,8 @@
 - ✅ Each story has: User Story format, Acceptance Criteria, Priority
 - ✅ story-index.md updated with ✅ GENERATED markers
 - ✅ Unit-brief.md updated with story summary
+- ✅ **All assigned FRs have corresponding stories (validation passed)**
+- ✅ **FR-to-story mapping shown in output**
 
 ## Failure Modes
 
@@ -24,6 +26,8 @@
 - ❌ Missing acceptance criteria in stories
 - ❌ Not updating story-index.md
 - ❌ Stories without INVEST criteria validation
+- ❌ **Assigned FRs without corresponding stories**
+- ❌ **Proceeding without FR-to-story validation**
 
 ---
 
@@ -144,6 +148,54 @@ Organize stories for bolt planning:
 - **Should**: Important but not blocking (Error handling, validation)
 - **Could**: Nice to have (Advanced features, optimizations)
 
+### 4b. Validate FR-to-Story Coverage (CRITICAL - HARD GATE)
+
+**⛔ HARD GATE**: Before creating story files, validate that ALL assigned FRs have stories.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FR-TO-STORY COVERAGE VALIDATION                             │
+│  → Read "Assigned Requirements" from unit-brief.md           │
+│  → Check each FR has at least one story                      │
+│  → If any FR is uncovered: STOP and create stories for it    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Validation output:**
+
+```markdown
+## FR-to-Story Coverage
+
+### Assigned FRs from Unit Brief
+- **FR-1**: {description}
+- **FR-2**: {description}
+- **FR-N**: {description}
+
+### Coverage Check
+
+- ✅ **FR-1**: {description} → `{SSS}-{story-slug}`, `{SSS}-{story-slug}`
+- ✅ **FR-2**: {description} → `{SSS}-{story-slug}`
+- ❌ **FR-3**: {description} → UNCOVERED
+
+### Validation Result
+- ✅ All FRs covered by stories (proceed)
+- ❌ {n} FRs uncovered - MUST create stories before proceeding:
+  - FR-X: {description} - NEEDS STORY
+```
+
+**If any FRs are uncovered:**
+
+1. **DO NOT PROCEED** to creating story files
+2. Create stories for uncovered FRs
+3. Re-run validation until all FRs are covered
+
+**Important Notes:**
+
+- One FR can map to multiple stories (complex features)
+- Multiple FRs can map to one story (closely related features)
+- Every FR MUST have at least one story
+- This validation catches FRs that were "lost" during decomposition
+
 ### 5. Document Stories
 
 1. **Read Path**: Check `schema.stories` from `.iris/aidlc/memory-bank.yaml`
@@ -294,6 +346,14 @@ This ensures each unit-brief shows its story count at a glance.
 ```markdown
 ## Stories Created: {unit-name}
 
+### FR-to-Story Coverage ✅
+
+- ✅ **FR-1**: {description} → `{SSS}-{story-slug}`, `{SSS}-{story-slug}`
+- ✅ **FR-2**: {description} → `{SSS}-{story-slug}`
+- ✅ **FR-3**: {description} → `{SSS}-{story-slug}`
+
+**All {n} assigned FRs have corresponding stories.**
+
 ### Story Summary
 
 - [ ] **S1**: User can register - Must - No dependencies

package/flows/aidlc/skills/inception/units.md

@@ -15,7 +15,8 @@
 
 - ✅ Unit directories created with unit-brief.md files
 - ✅ Dependency graph shown visually
-- ✅ All FRs mapped to exactly one unit
+- ✅ **All FRs mapped to exactly one unit (validation passed)**
+- ✅ FR coverage validation output shown
 - ✅ Frontend unit included if enabled in project type
 
 ## Failure Modes
@@ -23,6 +24,8 @@
 - ❌ Using ASCII table for unit listing
 - ❌ Not reading project type configuration
 - ❌ FRs not mapped to units
+- ❌ **Proceeding without FR coverage validation**
+- ❌ **Unmapped FRs not flagged**
 - ❌ Missing unit-brief.md files
 
 ---
@@ -149,6 +152,54 @@ This mapping ensures:
 - Units have clear scope based on assigned FRs
 - Stories will be created from unit's assigned FRs (not directly from intent)
 
+### 4b. Validate FR Coverage (CRITICAL - HARD GATE)
+
+**⛔ HARD GATE**: Before proceeding, validate that ALL FRs are mapped.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FR COVERAGE VALIDATION                                      │
+│  → Count FRs in requirements.md                              │
+│  → Count FRs in mapping                                      │
+│  → If mismatch: STOP and fix before proceeding               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Validation output:**
+
+```markdown
+## FR Coverage Validation
+
+### Requirements Count
+- **Total FRs in requirements.md**: {n}
+- **Must Have**: {n}
+- **Should Have**: {n}
+- **Could Have**: {n}
+
+### Mapping Count
+- **FRs mapped to units**: {n}
+- **FRs unmapped**: {list or "None"}
+
+### Validation Result
+- ✅ All FRs mapped (proceed to next step)
+- ❌ {n} FRs unmapped - MUST fix before proceeding:
+  - FR-X: {description} - NOT MAPPED
+  - FR-Y: {description} - NOT MAPPED
+```
+
+**If any FRs are unmapped:**
+
+1. **DO NOT PROCEED** to creating unit directories
+2. Review unmapped FRs and assign them to appropriate units
+3. Re-run validation until all FRs are mapped
+
+**Common reasons for unmapped FRs:**
+
+- FR was overlooked during domain analysis
+- FR spans multiple bounded contexts (split or create integration unit)
+- FR is an NFR incorrectly labeled as FR (move to NFRs)
+- FR is duplicate (merge with existing)
+
 ### 5. Create Frontend Unit (if enabled)
 
 **Skip this step if `frontend.enabled: false`.**

package/flows/aidlc/skills/master/project-init.md

@@ -15,6 +15,7 @@
 
 - ✅ project.yaml created with project type AND scenario (greenfield/brownfield/hybrid)
 - ✅ Scenario detected automatically with user confirmation
+- ✅ .gitignore updated with AI-DLC tooling entries
 - ✅ Standards created in correct order (dependencies respected)
 - ✅ Each question is single-focus (not combined)
 - ✅ Final summary shows all created/skipped standards
@@ -26,6 +27,7 @@
 - ❌ Creating standard before its dependencies
 - ❌ Not creating project.yaml
 - ❌ Not detecting/asking about greenfield vs brownfield scenario
+- ❌ Not updating .gitignore with AI-DLC tooling entries
 
 ---
 
@@ -125,9 +127,9 @@ This appears to be a **brownfield** project (enhancing existing code).
 2. **Greenfield** - No, ignore existing code, starting fresh
 3. **Hybrid** - Some features will modify existing, some are new
 
-This affects how the Construction Agent works:
-- **Brownfield**: Runs code elevation first to understand existing structure
-- **Greenfield**: Starts fresh with domain modeling
+This affects the development flow:
+- **Brownfield**: Master Agent runs code elevation first to understand existing structure
+- **Greenfield**: Construction Agent starts fresh with domain modeling
 - **Hybrid**: Asks per-intent which flow to use
 ```
 
@@ -185,6 +187,33 @@ existing_codebase:
 
 This file MUST be created before proceeding to standards facilitation, as other agents (e.g., Inception, Construction) read it to provide context-aware behavior.
 
+### 4b. Update .gitignore
+
+**Add AI-DLC tooling entries to `.gitignore`** to keep the product repository clean.
+
+#### If `.gitignore` exists:
+
+Check if entries already exist. If not, append:
+
+```gitignore
+
+# AI-DLC tooling (iris, claude)
+.iris/
+.claude/
+```
+
+#### If `.gitignore` doesn't exist:
+
+Create it with:
+
+```gitignore
+# AI-DLC tooling (iris, claude)
+.iris/
+.claude/
+```
+
+**Note**: `memory-bank/` is NOT gitignored - it contains valuable project specifications (PRFAQ, intents, stories, standards) that should be version controlled.
+
 ### 5. Check Existing Standards
 
 Before creating new standards, check if any exist:
@@ -314,6 +343,7 @@ After completing all standards:
 - **Type**: {project type} (e.g., full-stack-web)
 - **Scenario**: {scenario} (greenfield/brownfield/hybrid)
 - **Config**: `memory-bank/project.yaml`
+- **Gitignore**: `.gitignore` updated with AI-DLC tooling entries
 
 ### Standards Created
 
@@ -337,9 +367,9 @@ Your project is configured as a **{project type}** ({scenario}) using:
 - Use your chosen libraries and patterns
 - Follow your testing strategy
 
-**Scenario** - Construction Agent will:
-- {If greenfield}: Start with domain modeling (fresh design)
-- {If brownfield}: Run code elevation first (analyze existing code)
+**Scenario** - Development flow:
+- {If greenfield}: Construction Agent starts with domain modeling (fresh design)
+- {If brownfield}: Master Agent runs code elevation first (analyze existing code)
 - {If hybrid}: Ask per-intent which flow to use
 
 ### Actions