project-iris 0.6.8 → 0.6.10

package/flows/aidlc/memory-bank.yaml

@@ -73,7 +73,7 @@ naming:
         type: "array of URLs"
         format: "https://www.figma.com/design/{file-id}/{file-name}?node-id={node-id}&t={token}"
         note: "Construction Agent uses Figma MCP to fetch design specs. Prototype connections extracted if available."
-        collected_by: "Inception Agent during story creation (Step 4a in story-create skill)"
+        collected_by: "Inception Agent during story creation (Step 2 in story-create skill)"
       interaction_flows:
         description: "Manual interaction flow definition (fallback when Figma has no prototype)"
         type: "array of screen interaction definitions"
@@ -84,7 +84,7 @@ naming:
                 action: navigate | overlay | close | submit
                 target: {destination-screen}
         note: "Only needed if Figma file has designs but no prototype connections. Construction Agent uses this to wire navigation."
-        collected_by: "Inception Agent during story creation (Step 4a-2 in story-create skill)"
+        collected_by: "Inception Agent during story creation (Step 2 in story-create skill, via figma-story-refs)"
         priority: "Figma prototype > interaction_flows > infer from labels > ask user"
 
   bolts:

package/flows/aidlc/skills/inception/refs/figma-story-refs.md

@@ -4,7 +4,7 @@ This sub-skill handles collecting Figma frame URLs and interaction flows during
 
 ---
 
-## 4a. Collect Figma References (UI Stories Only)
+## Collect Figma References (UI Stories Only)
 
 **For stories that involve UI screens, ask the user for Figma frame URLs.**
 
@@ -68,7 +68,7 @@ I detected {n} stories with UI components. Would you like to:
 3 - Skip Figma references for all (use ui-patterns.md)
 ```
 
-## 4a-2. Collect Interaction Flows (If No Prototype in Figma)
+## Collect Interaction Flows (If No Prototype in Figma)
 
 **After collecting Figma URLs, ask about prototype connections:**
 

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

@@ -19,6 +19,7 @@
 - ✅ Unit-brief.md updated with story summary
 - ✅ **All assigned FRs have corresponding stories (validation passed)**
 - ✅ **FR-to-story mapping shown in output**
+- ✅ **Figma URLs collected (or explicitly skipped) for all UI stories BEFORE generation**
 
 ## Failure Modes
 
@@ -28,6 +29,7 @@
 - ❌ Stories without INVEST criteria validation
 - ❌ **Assigned FRs without corresponding stories**
 - ❌ **Proceeding without FR-to-story validation**
+- ❌ **Skipping Figma URL collection for UI stories (HARD GATE — see Step 2)**
 
 ---
 
@@ -99,7 +101,46 @@ Review the unit-brief.md to understand:
 
 **IMPORTANT**: Stories are created from the unit's **Assigned Requirements** section, NOT directly from intent requirements.md. The FR-to-unit mapping happened during unit decomposition.
 
-### 2. Generate Stories
+### 2. Collect Figma Design URLs (⛔ HARD GATE — Before Story Generation)
+
+**This step MUST run before generating any story files. It CANNOT be deferred or skipped for UI work.**
+
+**Detection**: Check if this unit involves UI by looking at:
+
+- `unit_type: frontend` in unit-brief frontmatter
+- Project type is `mobile-app`, `web-app`, `desktop-app`, or similar UI-producing type
+- Any FR assigned to the unit mentions screens, pages, forms, components, navigation, layouts, modals, buttons, or widgets
+
+**If ANY UI signal is detected, this is a HARD GATE — you MUST ask the user before proceeding.**
+
+> **Read `.iris/aidlc/skills/inception/refs/figma-story-refs.md` and follow the Batch Collection flow.**
+
+**Batch-first approach (REQUIRED for multi-story units):**
+
+```text
+⛔ FIGMA DESIGN REFERENCE GATE
+
+This unit ({unit-name}) involves UI development.
+I detected {n} stories that will need UI implementation.
+
+Before I generate story files, I need Figma design references.
+
+Do you have Figma designs for this unit's stories?
+
+1 - Yes, I'll provide a Figma file/page URL (I'll map frames to stories)
+2 - Yes, I'll provide individual frame URLs per story
+3 - No Figma designs exist — use ui-patterns.md guidelines
+```
+
+**⛔ DO NOT proceed to Step 3 (Generate Stories) until the user has responded.**
+
+- If user selects 1: Collect the file/page URL, then ask which frames map to which stories after listing the planned stories.
+- If user selects 2: Collect URLs per story as each story is generated.
+- If user selects 3: Proceed without Figma URLs — all stories get `figma_frames: []`.
+
+**Store collected URLs** so they are written into each story's frontmatter during Step 7 (Document Stories).
+
+### 3. Generate Stories
 
 For each feature in the unit:
 
@@ -129,7 +170,7 @@ So that {benefit}
 - {other stories this depends on}
 ```
 
-### 3. Apply INVEST Criteria
+### 4. Apply INVEST Criteria
 
 Validate each story against:
 
@@ -140,7 +181,7 @@ Validate each story against:
 - [ ] **S**mall: Fits in a single bolt stage? (Required)
 - [ ] **T**estable: Acceptance criteria are binary? (Required)
 
-### 4. Group by Priority
+### 5. Group by Priority
 
 Organize stories for bolt planning:
 
@@ -148,14 +189,7 @@ Organize stories for bolt planning:
 - **Should**: Important but not blocking (Error handling, validation)
 - **Could**: Nice to have (Advanced features, optimizations)
 
-### 4a. Collect Figma References (UI Stories Only)
-
-**For UI stories, collect Figma frame URLs and interaction flows.**
-
-> **Read `.iris/aidlc/skills/inception/refs/figma-story-refs.md` and follow its instructions.**
-> Covers: UI signal detection, Figma URL collection (individual and batch), interaction flow definition, and frontmatter updates.
-
-### 4b. Validate FR-to-Story Coverage (CRITICAL - HARD GATE)
+### 6. Validate FR-to-Story Coverage (CRITICAL - HARD GATE)
 
 **⛔ HARD GATE**: Before creating story files, validate that ALL assigned FRs have stories.
 
@@ -203,7 +237,7 @@ Organize stories for bolt planning:
 - Every FR MUST have at least one story
 - This validation catches FRs that were "lost" during decomposition
 
-### 5. Document Stories
+### 7. Document Stories
 
 1. **Read Path**: Check `schema.stories` from `.iris/aidlc/memory-bank.yaml`
    *(Default: `memory-bank/intents/{intent-name}/units/{unit-name}/stories/`)*
@@ -245,7 +279,7 @@ Organize stories for bolt planning:
 4. **Link to Unit**:
    Update unit's story index if one exists
 
-### 6. Update Unit Brief with Story Summary
+### 8. Update Unit Brief with Story Summary
 
 **CRITICAL**: After creating stories, update the unit-brief.md with a story summary.
 
@@ -269,7 +303,7 @@ Add/update this section in the unit's `unit-brief.md`:
 
 This ensures each unit-brief shows its story count at a glance.
 
-### 7. Update Global Story Index
+### 9. Update Global Story Index
 
 **CRITICAL**: After creating EACH story, IMMEDIATELY update the index.
 

package/lib/installer.js

@@ -298,33 +298,32 @@ async function installFlow(flowKey, toolKeys) {
   console.log(theme.dim(`  Installing flow resources to ${targetFlowDir}/...`));
 
   // Clean existing flow directory to prevent duplicate files on reinstall
-  if (await fs.pathExists(targetFlowDir)) {
-    await fs.remove(targetFlowDir);
-  }
-  await fs.ensureDir(targetFlowDir);
+  // Use emptyDir instead of remove+ensureDir to avoid macOS filesystem race conditions
+  // that can create "folder 2" duplicates when Finder or iCloud observes the directory
+  await fs.emptyDir(targetFlowDir);
 
   // Copy agents
-  await fs.copy(path.join(flowPath, 'agents'), path.join(targetFlowDir, 'agents'));
+  await fs.copy(path.join(flowPath, 'agents'), path.join(targetFlowDir, 'agents'), { overwrite: true });
 
   // Copy internal agent capabilities (legacy check)
   if (await fs.pathExists(path.join(flowPath, 'agent-capabilities'))) {
-    await fs.copy(path.join(flowPath, 'agent-capabilities'), path.join(targetFlowDir, 'agent-capabilities'));
+    await fs.copy(path.join(flowPath, 'agent-capabilities'), path.join(targetFlowDir, 'agent-capabilities'), { overwrite: true });
   }
 
   // Copy bolt-types if they exist (legacy check)
   if (await fs.pathExists(path.join(flowPath, 'bolt-types'))) {
-    await fs.copy(path.join(flowPath, 'bolt-types'), path.join(targetFlowDir, 'bolt-types'));
+    await fs.copy(path.join(flowPath, 'bolt-types'), path.join(targetFlowDir, 'bolt-types'), { overwrite: true });
   }
 
   // Copy skills, templates, shared (now at flow root level, not nested in .iris)
   if (await fs.pathExists(path.join(flowPath, 'skills'))) {
-    await fs.copy(path.join(flowPath, 'skills'), path.join(targetFlowDir, 'skills'));
+    await fs.copy(path.join(flowPath, 'skills'), path.join(targetFlowDir, 'skills'), { overwrite: true });
   }
   if (await fs.pathExists(path.join(flowPath, 'templates'))) {
-    await fs.copy(path.join(flowPath, 'templates'), path.join(targetFlowDir, 'templates'));
+    await fs.copy(path.join(flowPath, 'templates'), path.join(targetFlowDir, 'templates'), { overwrite: true });
   }
   if (await fs.pathExists(path.join(flowPath, 'shared'))) {
-    await fs.copy(path.join(flowPath, 'shared'), path.join(targetFlowDir, 'shared'));
+    await fs.copy(path.join(flowPath, 'shared'), path.join(targetFlowDir, 'shared'), { overwrite: true });
   }
 
   // Copy config files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-iris",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "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/artifact-validator.js

@@ -32,8 +32,10 @@ const colors = {
     bright: '\x1b[1m'
 };
 
-// Memory bank paths
-const MEMORY_BANK_DIR = 'memory-bank';
+// Memory bank paths (resolved from project root)
+const { findProjectRoot } = require('./lib/frontmatter-utils');
+const PROJECT_ROOT = findProjectRoot();
+const MEMORY_BANK_DIR = path.join(PROJECT_ROOT, 'memory-bank');
 const INTENTS_DIR = path.join(MEMORY_BANK_DIR, 'intents');
 const BOLTS_DIR = path.join(MEMORY_BANK_DIR, 'bolts');
 
@@ -80,7 +82,7 @@ const patterns = {
 };
 
 class ArtifactValidator {
-    constructor(memoryBankPath = 'memory-bank') {
+    constructor(memoryBankPath = MEMORY_BANK_DIR) {
         this.memoryBankPath = memoryBankPath;
         this.results = [];
         this.fixCount = 0;

package/scripts/bolt-complete.js

@@ -132,11 +132,13 @@ const {
     colors,
     extractFrontmatter,
     updateFrontmatter,
-    getTimestamp
+    getTimestamp,
+    findProjectRoot
 } = require('./lib/frontmatter-utils');
 
-// Memory bank paths (relative to project root)
-const MEMORY_BANK_DIR = 'memory-bank';
+// Memory bank paths (resolved from project root)
+const PROJECT_ROOT = findProjectRoot();
+const MEMORY_BANK_DIR = path.join(PROJECT_ROOT, 'memory-bank');
 const BOLTS_DIR = path.join(MEMORY_BANK_DIR, 'bolts');
 const INTENTS_DIR = path.join(MEMORY_BANK_DIR, 'intents');
 

package/scripts/lib/frontmatter-utils.js

@@ -6,6 +6,8 @@
  */
 
 const yaml = require('js-yaml');
+const path = require('path');
+const fs = require('fs');
 
 // Theme colors for CLI output
 const colors = {
@@ -67,9 +69,28 @@ function getTimestamp() {
     return date.toISOString().replace(/\.\d+Z$/, 'Z');
 }
 
+/**
+ * Find the project root by walking up from cwd looking for memory-bank/ directory.
+ * Falls back to cwd if not found (preserving original behavior).
+ * @returns {string} Absolute path to the project root
+ */
+function findProjectRoot() {
+    let dir = process.cwd();
+    const root = path.parse(dir).root;
+    while (dir !== root) {
+        if (fs.existsSync(path.join(dir, 'memory-bank'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    // Fallback: return cwd (original behavior)
+    return process.cwd();
+}
+
 module.exports = {
     colors,
     extractFrontmatter,
     updateFrontmatter,
-    getTimestamp
+    getTimestamp,
+    findProjectRoot
 };

package/scripts/status-integrity.js

@@ -18,11 +18,13 @@ const path = require('path');
 const {
     colors,
     extractFrontmatter,
-    updateFrontmatter
+    updateFrontmatter,
+    findProjectRoot
 } = require('./lib/frontmatter-utils');
 
-// Memory bank paths (relative to project root)
-const MEMORY_BANK_DIR = 'memory-bank';
+// Memory bank paths (resolved from project root)
+const PROJECT_ROOT = findProjectRoot();
+const MEMORY_BANK_DIR = path.join(PROJECT_ROOT, 'memory-bank');
 const BOLTS_DIR = path.join(MEMORY_BANK_DIR, 'bolts');
 const INTENTS_DIR = path.join(MEMORY_BANK_DIR, 'intents');
 const MAINTENANCE_LOG = path.join(MEMORY_BANK_DIR, 'maintenance-log.md');