specsmd 0.1.2 → 0.1.3

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

@@ -182,13 +182,31 @@ Ready to proceed?
 
 If the bolt type specifies automatic validation criteria, follow those rules.
 
+### 8b. Final Stage Checkpoint (CRITICAL RE-READ)
+
+**⚠️ If this is the FINAL stage of the bolt**, before presenting completion:
+
+1. **STOP** and re-read **Step 10** from this skill
+2. This step is often skipped due to context distance - re-reading prevents this
+3. Do NOT report bolt as complete until you have executed Step 10
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FINAL STAGE DETECTED                                       │
+│  → Re-read Step 10 NOW                                     │
+│  → You MUST run: node .specsmd/scripts/bolt-complete.js    │
+│  → Do NOT manually edit story files                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
 ### 9. Update Bolt File on Stage Completion
 
+**Trigger**: After EACH stage completion (not just final stage).
+
 After each stage completion:
 
 - Add stage to `stages_completed` with timestamp
 - Update `current_stage` to next stage
-- If final stage, set `status: completed` and `completed` timestamp
 
 **⚠️ TIMESTAMP FORMAT**: See `memory-bank.yaml` → `conventions.timestamps`
 
@@ -197,112 +215,97 @@ After each stage completion:
 status: in-progress
 current_stage: {next-stage-from-bolt-type}
 stages_completed:
-  - {stage-name}: {timestamp}
+  - name: {stage-name}
+    completed: {timestamp}
+    artifact: {artifact-filename}
 ---
 ```
 
-**On bolt completion**, also update:
-
-```yaml
-completed: {timestamp}
-```
-
-#### Update Story Status (On Bolt Completion)
-
-When marking a bolt as `status: complete`, update all stories in the bolt's `stories` array:
+**If this is the FINAL stage**, proceed to **Step 10** (bolt completion).
 
-1. **Read bolt's stories**: Get story IDs from bolt frontmatter `stories: [001-story-name, 002-story-name, ...]`
-2. **Locate story files**: `{intent}/units/{unit}/stories/{story-id}.md`
-3. **Update each story frontmatter**:
+**If this is NOT the final stage**, update bolt file and proceed to next stage. Stop here.
 
-   ```yaml
-   # Change from
-   status: draft
-   implemented: false
+---
 
-   # To
-   status: complete
-   implemented: true
-   ```
+### 10. Mark Bolt Complete (HARD GATE - MANDATORY ON FINAL STAGE)
 
-**Example**:
+**Trigger**: ONLY when this is the FINAL stage.
 
 ```text
-Bolt stories: [001-create-role, 002-manage-permissions, 003-view-roles]
-
-Updated:
-✅ stories/001-create-role.md → status: complete, implemented: true
-✅ stories/002-manage-permissions.md → status: complete, implemented: true
-✅ stories/003-view-roles.md → status: complete, implemented: true
+⛔ HARD GATE - SCRIPT EXECUTION REQUIRED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+You CANNOT report bolt completion without:
+1. Running the bolt-complete.js script
+2. Showing the script output to the user
+
+If you skip this, the memory-bank becomes inconsistent.
+Do NOT manually edit story files - the script handles everything.
 ```
 
-This ensures the memory-bank reflects actual implementation status and the VS Code extension shows correct completion indicators.
+**Run this command:**
 
-#### Update Unit & Intent Status (Status Cascade)
+```bash
+node .specsmd/scripts/bolt-complete.js {bolt-id}
+```
 
-Status changes cascade upward: Bolt → Story → Unit → Intent.
+**What this command does (deterministically):**
 
-**On Bolt Start** (when changing from `planned` to `in-progress`):
+1. Updates bolt file to `status: complete`
+2. Updates ALL stories in bolt's `stories` array to `status: complete, implemented: true`
+3. Updates unit status if all bolts for unit are complete
+4. Updates intent status if all units for intent are complete
 
-1. **Update Unit Status**:
-   - Read unit-brief: `{intent}/units/{unit}/unit-brief.md`
-   - If unit status is `stories-defined` or `stories-updated` → change to `in-progress`
+**Example output:**
 
-2. **Update Intent Status**:
-   - Read requirements: `{intent}/requirements.md`
-   - If intent status is `units-defined` → change to `construction`
+```text
+════════════════════════════════════════
+Bolt Completion: 016-analytics-tracker
+════════════════════════════════════════
 
-**On Bolt Completion** (after updating stories):
+Bolt: 016-analytics-tracker
+Intent: 007-installer-analytics
+Unit: analytics-tracker
+Stories: 12
 
-1. **Check Unit Completion**:
-   - Find all bolts for this unit: scan `memory-bank/bolts/*/bolt.md` and match `unit: {unit-name}` in frontmatter
-   - If ALL bolts have `status: complete` → update unit-brief to `status: complete`
+✓ Bolt status: in-progress → complete
 
-2. **Check Intent Completion**:
-   - Read unit-briefs for all units in intent: `{intent}/units/*/unit-brief.md`
-   - If ALL units have `status: complete` → update requirements to `status: complete`
+Updating stories:
+  ✓ 001-initialize-mixpanel - draft → complete
+  ✓ 002-generate-machine-hash - draft → complete
+  ...
 
-**Status Transitions**:
+Stories: 12 updated, 0 skipped, 0 errors
 
-```text
-Intent:  draft → requirements-defined → units-defined → construction → complete
-Unit:    draft → stories-defined → in-progress → complete
-Story:   draft → in-progress → complete
+✓ Unit status: in-progress → complete
+✓ Intent status: construction → complete
+
+════════════════════════════════════════
+✓ Bolt Complete: 016-analytics-tracker
+════════════════════════════════════════
 ```
 
-**Example** (001-artifact-parser completes):
+**Do NOT manually edit story files.** The command handles everything deterministically.
 
-```text
-1. Stories updated: 001, 002, 003, 004 → complete
-2. Check unit bolts:
-   - 001-artifact-parser: complete ✓
-   - 005-artifact-parser: planned ✗
-   → Unit stays in-progress (not all bolts complete)
-3. Intent stays construction (unit not complete)
-```
+**Verify the script completed successfully:**
 
-**Example** (last bolt for file-watcher completes):
+After running the command, verify the changes were applied correctly:
 
-```text
-1. Stories updated: 001, 002 → complete
-2. Check unit bolts:
-   - 003-file-watcher: complete ✓
-   → Only bolt for unit, all complete!
-   → Update unit-brief: status: complete
-3. Check intent units:
-   - artifact-parser: in-progress ✗
-   - file-watcher: complete ✓
-   - sidebar-provider: in-progress ✗
-   → Intent stays construction (not all units complete)
-```
+- [ ] **Bolt file updated**:
+  - [ ] `status: complete`
+  - [ ] `current_stage: null`
+  - [ ] `completed: {timestamp}` set
+
+- [ ] **Stories updated** (sample 2-3 from the bolt's stories array):
+  - [ ] `status: complete`
+  - [ ] `implemented: true`
 
-### 10. Continue or Complete
+- [ ] **Unit status updated** (if all bolts for this unit are complete):
+  - [ ] Check `{intent}/units/{unit}/unit-brief.md` → `status: complete`
 
-Based on condition:
+- [ ] **Intent status updated** (if all units for this intent are complete):
+  - [ ] Check `{intent}/intent.md` → `status: complete`
 
-- **More stages remain** → Proceed to next stage
-- **Final stage complete** → Mark bolt complete, suggest next bolt
-- **User stops** → Save progress, can resume later
+**If any verification fails**, the script may have encountered an error. Check the console output for error messages.
 
 ---
 
@@ -396,6 +399,31 @@ If construction log doesn't exist, create it using template:
 
 ---
 
+## Bolt Completion Checklist
+
+**Use this checklist to verify all completion tasks are done:**
+
+```text
+□ Bolt file updated:
+  □ status: complete
+  □ completed: {timestamp}
+  □ current_stage: null
+
+□ Stories updated (Step 10):
+  □ Each story in bolt's stories array:
+    □ status: complete
+    □ implemented: true
+
+□ Status cascade checked (Step 11):
+  □ Unit status updated if all bolts complete
+  □ Intent status updated if all units complete
+
+□ Construction log updated:
+  □ "{bolt-id} completed" entry added
+```
+
+---
+
 ## Transition
 
 After bolt completion:

package/flows/aidlc/skills/inception/bolt-plan.md

@@ -63,7 +63,7 @@ Review all stories to understand:
 
    ```yaml
    ---
-   unit: expense-tracker-ui
+   unit: 001-expense-tracker-ui
    unit_type: frontend
    default_bolt_type: simple-construction-bolt
    ---
@@ -235,8 +235,8 @@ Establish execution order based on dependencies:
    ```markdown
    ---
    id: {BBB}-{unit-name}
-   unit: {unit-name}
-   intent: {intent-name}
+   unit: {UUU}-{unit-name}
+   intent: {NNN}-{intent-name}
    type: {bolt-type}  # From unit-brief.md or default (ddd-construction-bolt, simple-construction-bolt)
    status: planned
    stories: [story-1, story-2]
@@ -289,10 +289,23 @@ Establish execution order based on dependencies:
 
 Check the plan against:
 
+**Frontmatter Validation (CRITICAL - check each bolt.md)**:
+
+- [ ] `id` - Bolt identifier present
+- [ ] `unit` - Parent unit ID present
+- [ ] `intent` - Parent intent ID present
+- [ ] `type` - Bolt type specified (`ddd-construction-bolt` or `simple-construction-bolt`)
+- [ ] `status` - Set to `planned`
+- [ ] `stories` - **Array of story IDs included** (NOT just in body, MUST be in frontmatter)
+- [ ] `created` - Timestamp present
+- [ ] `requires_bolts` - Dependency array present (can be empty `[]`)
+- [ ] `enables_bolts` - Enables array present (can be empty `[]`)
+- [ ] `complexity` - Complexity block with all 4 fields
+
+**Content Validation**:
+
 - [ ] All stories are assigned to bolts
 - [ ] Dependencies are respected (bolt-to-bolt AND unit-to-unit)
-- [ ] All dependencies documented in frontmatter
-- [ ] Complexity assessment included for each bolt
 - [ ] Each bolt has clear outputs
 - [ ] No bolt is too large (max 5-6 stories)
 - [ ] No circular dependencies exist

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

@@ -126,7 +126,7 @@ Update these sections:
 
 ```markdown
 ---
-intent: {intent-name}
+intent: {NNN}-{intent-name}
 created: {original-date}
 completed: {today}
 status: complete

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

@@ -152,12 +152,14 @@ When `frontend.enabled: true` in the project type configuration, create a fronte
 
 ```yaml
 ---
-unit: {intent}-ui
+unit: {UUU}-{intent}-ui
 unit_type: frontend
 default_bolt_type: simple-construction-bolt
 ---
 ```
 
+**Note**: The `unit` field uses the full folder name including the numeric prefix (e.g., `001-auth-service`, `002-auth-service-ui`). This matches the folder structure and enables direct path construction in scripts.
+
 ---
 
 ### 6. Propose Unit Structure
@@ -193,10 +195,10 @@ Present proposed decomposition with their assigned requirements:
    Update `units.md` with all units for this intent
 
 3. **Create Unit Directories**:
-   For each unit: `{schema.units}/{unit-name}/`
+   For each unit: `{schema.units}/{UUU}-{unit-name}/`
 
 4. **Create Unit Brief** (CRITICAL):
-   For each unit, create `unit-brief.md` using `.specsmd/aidlc/templates/inception/unit-brief-template.md`
+   For each unit, create `{UUU}-{unit-name}/unit-brief.md` using `.specsmd/aidlc/templates/inception/unit-brief-template.md`
 
    This brief is the **input for Construction Agent**. Include:
    - Purpose and scope
@@ -209,14 +211,16 @@ Present proposed decomposition with their assigned requirements:
 
    ```yaml
    ---
-   unit: auth-service
-   intent: 001-user-authentication
+   unit: {UUU}-{unit-name}
+   intent: {NNN}-{intent-name}
    phase: inception
    status: draft
    ---
    ```
 
-   Note: Story naming uses the story title (e.g., `001-user-signup.md`). No prefix field needed.
+   **Note**: The `unit` field uses the full folder name including the numeric prefix. This matches the folder structure and enables direct path construction in scripts.
+
+   Story naming uses the story title (e.g., `001-user-signup.md`). No prefix field needed.
 
    **For frontend units**, also include:
 
@@ -239,25 +243,25 @@ For each unit, verify:
 ## Output
 
 ```markdown
-## Unit Decomposition: {intent-name}
+## Unit Decomposition: {NNN}-{intent-name}
 
 ### Units Created
 
-- [ ] **{unit-1}**: {purpose} - Dependencies: None - Stories: ~{n}
-- [ ] **{unit-2}**: {purpose} - Dependencies: `{unit-1}` - Stories: ~{n}
+- [ ] **{UUU}-{unit-1}**: {purpose} - Dependencies: None - Stories: ~{n}
+- [ ] **{UUU}-{unit-2}**: {purpose} - Dependencies: `{UUU}-{unit-1}` - Stories: ~{n}
 
 ### Dependency Graph
 
-    {unit-1} ──► {unit-2} ──► {unit-3}
+    {UUU}-{unit-1} ──► {UUU}-{unit-2} ──► {UUU}-{unit-3}
                     │
                     ▼
-                {unit-4}
+                {UUU}-{unit-4}
 
 ### Artifacts Created
 
 ✅ `{intent-path}/units.md`
-✅ `{intent-path}/units/{unit-1}/unit-brief.md`
-✅ `{intent-path}/units/{unit-2}/unit-brief.md`
+✅ `{intent-path}/units/{UUU}-{unit-1}/unit-brief.md`
+✅ `{intent-path}/units/{UUU}-{unit-2}/unit-brief.md`
 
 ```
 

package/flows/aidlc/skills/operations/monitor.md

@@ -141,7 +141,7 @@ Create/update `deployment/monitoring.md`:
 
 ```markdown
 ---
-unit: {unit-name}
+unit: {UUU}-{unit-name}
 configured: {timestamp}
 ---
 

package/flows/aidlc/templates/construction/bolt-template.md

@@ -27,8 +27,8 @@ memory-bank/bolts/{bolt-id}/
 ```yaml
 ---
 id: bolt-{unit}-{sequence}
-unit: {unit-name}
-intent: {intent-name}
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
 type: ddd-construction-bolt
 status: planned
 stories:
@@ -57,6 +57,27 @@ complexity:
 
 ---
 
+## Required Frontmatter Fields (VALIDATION CHECKLIST)
+
+Before creating a bolt, verify ALL required fields are present:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | **YES** | Bolt identifier (format: `{BBB}-{unit-name}`) |
+| `unit` | **YES** | Parent unit ID |
+| `intent` | **YES** | Parent intent ID |
+| `type` | **YES** | Bolt type (`ddd-construction-bolt` or `simple-construction-bolt`) |
+| `status` | **YES** | Current status (`planned`, `in-progress`, `completed`, `blocked`) |
+| `stories` | **YES** | Array of story IDs included in this bolt |
+| `created` | **YES** | Creation timestamp |
+| `requires_bolts` | **YES** | Array of bolt IDs this depends on (can be empty `[]`) |
+| `enables_bolts` | **YES** | Array of bolt IDs waiting on this (can be empty `[]`) |
+| `complexity` | **YES** | Complexity assessment block |
+
+**If any required field is missing, the bolt is INVALID.**
+
+---
+
 ## Content
 
 ```markdown
@@ -132,8 +153,8 @@ complexity:
 ```yaml
 ---
 id: bolt-auth-service-1
-unit: auth-service
-intent: user-authentication
+unit: 001-auth-service
+intent: 001-user-authentication
 type: ddd-construction-bolt
 status: in-progress
 stories:

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-01-domain-model-template.md

@@ -1,6 +1,6 @@
 ---
-unit: {unit-name}
-bolt: {bolt-id}
+unit: {UUU}-{unit-name}
+bolt: {BBB}-{unit-name}
 stage: model
 status: complete
 updated: {YYYY-MM-DDTHH:MM:SSZ}

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-02-technical-design-template.md

@@ -1,6 +1,6 @@
 ---
-unit: {unit-name}
-bolt: {bolt-id}
+unit: {UUU}-{unit-name}
+bolt: {BBB}-{unit-name}
 stage: design
 status: complete
 updated: {YYYY-MM-DDTHH:MM:SSZ}

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-03-test-report-template.md

@@ -1,6 +1,6 @@
 ---
-unit: {unit-name}
-bolt: {bolt-id}
+unit: {UUU}-{unit-name}
+bolt: {BBB}-{unit-name}
 stage: test
 status: complete
 updated: {YYYY-MM-DDTHH:MM:SSZ}

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

@@ -270,6 +270,11 @@ created: {YYYY-MM-DDTHH:MM:SSZ}
 - **Tests**: {passed}/{total} passed
 - **Coverage**: {percentage}%
 
+### Test Files
+
+- [x] `{path/to/test-file.test.ts}` - {what this test file covers}
+- [x] `{path/to/another.test.ts}` - {what this test file covers}
+
 ### Acceptance Criteria Validation
 
 - ✅/❌ **{Criterion}**: {Status}

package/flows/aidlc/templates/construction/construction-log-template.md

@@ -14,8 +14,8 @@ Use this template to track construction progress and replanning decisions for a
 
 ```markdown
 ---
-unit: {unit-name}
-intent: {intent-name}
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
 created: {YYYY-MM-DDTHH:MM:SSZ}
 last_updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---

package/flows/aidlc/templates/inception/inception-log-template.md

@@ -14,7 +14,7 @@ Use this template to track inception progress and decisions for an intent.
 
 ```markdown
 ---
-intent: {intent-name}
+intent: {NNN}-{intent-name}
 created: {YYYY-MM-DDTHH:MM:SSZ}
 completed: {YYYY-MM-DDTHH:MM:SSZ or null}
 status: {in-progress | complete}

package/flows/aidlc/templates/inception/requirements-template.md

@@ -8,7 +8,7 @@ Use this template when documenting requirements for an intent.
 
 ```yaml
 ---
-intent: {intent-name}
+intent: {NNN}-{intent-name}
 phase: inception
 status: draft|in-progress|complete
 created: {YYYY-MM-DDTHH:MM:SSZ}

package/flows/aidlc/templates/inception/stories-template.md

@@ -1,5 +1,5 @@
 ---
-intent: {intent-name}
+intent: {NNN}-{intent-name}
 phase: inception
 status: stories-created
 updated: {YYYY-MM-DDTHH:MM:SSZ}

package/flows/aidlc/templates/inception/story-template.md

@@ -8,9 +8,9 @@ Use this template when creating individual story files during story creation.
 
 ```yaml
 ---
-id: {intent-name}-story-{n}
-unit: {unit-name}
-intent: {intent-name}
+id: {SSS}-{title-slug}
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
 status: draft
 priority: must|should|could
 created: {YYYY-MM-DDTHH:MM:SSZ}
@@ -24,7 +24,7 @@ implemented: false
 ## Content
 
 ```markdown
-# Story: {intent-name}-story-{n}
+# Story: {SSS}-{title-slug}
 
 ## User Story
 
@@ -91,19 +91,19 @@ implemented: false
 
 ```yaml
 ---
-id: user-authentication-story-1
-unit: auth-service
-intent: user-authentication
+id: 001-user-signup
+unit: 001-auth-service
+intent: 001-user-authentication
 status: ready
 priority: must
 created: 2024-12-05T10:00:00Z
-assigned_bolt: bolt-auth-service-1
+assigned_bolt: 001-auth-service
 implemented: false
 ---
 ```
 
 ```markdown
-# Story: user-authentication-story-1
+# Story: 001-user-signup
 
 ## User Story
 
@@ -129,8 +129,8 @@ implemented: false
 - None (first story)
 
 ### Enables
-- story-2 (User login)
-- story-3 (Email verification)
+- 002-user-login (User login)
+- 003-email-verification (Email verification)
 
 ## Edge Cases
 

package/flows/aidlc/templates/inception/system-context-template.md

@@ -1,5 +1,5 @@
 ---
-intent: {intent-name}
+intent: {NNN}-{intent-name}
 phase: inception
 status: context-defined
 updated: {YYYY-MM-DDTHH:MM:SSZ}

package/flows/aidlc/templates/inception/unit-brief-template.md

@@ -8,8 +8,8 @@ Use this template when creating unit briefs during decomposition. This is the **
 
 ```yaml
 ---
-unit: {unit-name}
-intent: {intent-name}
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
 phase: inception
 status: draft|ready
 created: {YYYY-MM-DDTHH:MM:SSZ}
@@ -17,7 +17,7 @@ updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 ```
 
-Note: Story naming uses the story title (e.g., `001-user-signup.md`). No prefix field needed.
+**Note**: The `unit` field uses the full folder name including the 3-digit prefix (e.g., `001-auth-service`). This matches the folder structure and enables direct path construction in scripts. Story naming uses the story title (e.g., `001-user-signup.md`).
 
 ---
 

package/flows/aidlc/templates/inception/units-template.md

@@ -1,5 +1,5 @@
 ---
-intent: {intent-name}
+intent: {NNN}-{intent-name}
 phase: inception
 status: units-decomposed
 updated: {YYYY-MM-DDTHH:MM:SSZ}

package/lib/analytics/tracker.js

@@ -56,7 +56,12 @@ class AnalyticsTracker {
             const Mixpanel = require('mixpanel');
             this.mixpanel = Mixpanel.init(MIXPANEL_TOKEN, {
                 protocol: 'https',
-                host: 'api-eu.mixpanel.com'  // EU endpoint for GDPR compliance
+                host: 'api-eu.mixpanel.com',  // EU endpoint for GDPR compliance
+                // Note: geolocate: true enables IP-based geolocation for analytics.
+                // This data is used solely for aggregate usage insights (e.g., country-level
+                // adoption patterns). No personal identifiers are collected. Users can
+                // opt out via the --no-telemetry flag or SPECSMD_NO_TELEMETRY env var.
+                geolocate: true
             });
 
             // Generate IDs
@@ -117,7 +122,7 @@ class AnalyticsTracker {
         if (waitForDelivery) {
             return new Promise((resolve) => {
                 try {
-                    this.mixpanel.track(eventName, eventData, (err) => {
+                    this.mixpanel.track(eventName, eventData, () => {
                         // Resolve regardless of error - silent failure
                         resolve();
                     });

package/lib/installer.js

@@ -250,6 +250,20 @@ async function installFlow(flowKey, toolKeys) {
 
   CLIUtils.displayStatus('', 'Installed flow resources', 'success');
 
+  // Step 2.5: Install local scripts for deterministic operations
+  // These scripts are version-matched to the installed specsmd version
+  const scriptsDir = path.join(specsmdDir, 'scripts');
+  await fs.ensureDir(scriptsDir);
+
+  const sourceScriptsDir = path.join(__dirname, '..', 'scripts');
+  if (await fs.pathExists(sourceScriptsDir)) {
+    await fs.copy(sourceScriptsDir, scriptsDir);
+    CLIUtils.displayStatus('', 'Installed local scripts', 'success');
+  }
+
+  // Note: Scripts are invoked directly via relative path (e.g., node .specsmd/scripts/bolt-complete.js)
+  // No npm scripts added to package.json to avoid dependency on package.json for execution
+
   // NOTE: memory-bank/ is NOT created during installation
   // It will be created when user runs project-init
   // This allows us to detect if project is initialized by checking for memory-bank/standards/