specsmd 0.0.0-dev.1 → 0.0.0-dev.11

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

@@ -182,6 +182,23 @@ 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).
@@ -210,11 +227,22 @@ stages_completed:
 
 ---
 
-### 10. Mark Bolt Complete (CRITICAL - MANDATORY ON FINAL STAGE)
+### 10. Mark Bolt Complete (HARD GATE - MANDATORY ON FINAL STAGE)
 
 **Trigger**: ONLY when this is the FINAL stage.
 
-**⚠️ DO NOT SKIP THIS STEP. When the final stage completes, you MUST run the command below.**
+```text
+⛔ 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.
+```
+
+**Run this command:**
 
 ```bash
 node .specsmd/scripts/bolt-complete.js {bolt-id}

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

@@ -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/templates/construction/bolt-template.md

@@ -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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.1",
+  "version": "0.0.0-dev.11",
   "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

@@ -510,6 +510,29 @@ async function updateIntentStatus(bolt) {
     return { updated: false };
 }
 
+/**
+ * Validate bolt status before allowing completion
+ *
+ * Pre-flight checks to ensure:
+ * - Bolt is in "in-progress" status (can't complete already-complete or not-started bolts)
+ * - Bolt has not already been completed
+ */
+function validateBoltStatus(bolt) {
+    const status = bolt.frontmatter.status || 'unknown';
+
+    // Cannot complete a bolt that's already complete
+    if (status === 'complete') {
+        return { valid: false, reason: 'Bolt is already complete' };
+    }
+
+    // Bolt should be in-progress before completing
+    if (status !== 'in-progress') {
+        return { valid: false, reason: `Bolt status is "${status}", expected "in-progress"` };
+    }
+
+    return { valid: true };
+}
+
 /**
  * Main: Mark bolt as complete with all dependent updates
  */
@@ -522,6 +545,14 @@ async function boltMarkComplete(boltId, lastStage) {
         // Step 1: Read bolt file
         const bolt = await readBolt(boltId);
 
+        // Step 1.5: Validate bolt status before proceeding
+        const validation = validateBoltStatus(bolt);
+        if (!validation.valid) {
+            console.error(`\n${colors.red}Error:${colors.reset} ${validation.reason}`);
+            console.error(`${colors.dim}Use bolt-status command to check current state.${colors.reset}`);
+            return 1;
+        }
+
         console.log(`${colors.dim}Bolt: ${bolt.id}${colors.reset}`);
         console.log(`${colors.dim}Intent: ${bolt.frontmatter.intent}${colors.reset}`);
         console.log(`${colors.dim}Unit: ${bolt.frontmatter.unit}${colors.reset}`);
@@ -537,11 +568,11 @@ async function boltMarkComplete(boltId, lastStage) {
         console.log(`\n${colors.dim}Stories: ${colors.green}${storyResults.updated} updated${colors.reset}, ${colors.dim}${storyResults.skipped} skipped${colors.reset}${storyResults.errors > 0 ? `, ${colors.red}${storyResults.errors} errors${colors.reset}` : ''}\n`);
 
         // Step 4: Update unit status
-        const unitResult = await updateUnitStatus(bolt);
+        await updateUnitStatus(bolt);
         console.log();
 
         // Step 5: Update intent status
-        const intentResult = await updateIntentStatus(bolt);
+        await updateIntentStatus(bolt);
         console.log();
 
         // Final summary