specsmd 0.0.0-dev → 0.0.0-dev.10

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",
+  "version": "0.0.0-dev.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": {
@@ -36,6 +36,7 @@
     "bin/",
     "flows/",
     "lib/",
+    "scripts/",
     "README.md"
   ],
   "dependencies": {