sdg-agents 1.10.0 → 1.10.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdg-agents",
-  "version": "1.10.0",
+  "version": "1.10.4",
   "description": "Structured working protocol and engineering rules for AI agents. Works with Claude Code, Antigravity, Codex, and others.",
   "type": "module",
   "main": "./src/engine/bin/index.mjs",

package/src/assets/instructions/commands/sdg-end.md

@@ -61,13 +61,17 @@ If a lint script exists (`lint`, `lint:fix`, `lint:all`, or a config file is det
 - If non-auto-fixable violations remain, surface them explicitly.
 - Block commit if errors remain.
 
-## Step 8 — COMMIT
+## Step 8 — COMMIT & RELEASE
 
 Propose the commit message and **WAIT** for explicit Developer approval before committing.
 
+- **Option A (Manual)**: If you just want to save progress without a version bump, commit with `feat:` or `fix:`. Remember you **MUST** have content in `[Unreleased]`.
+- **Option B (End Cycle)**: If the cycle is complete, run `npm run bump <fix|feat|major>` to consolidate the narrative and bump the version.
+
 ## Step 9 — PUSH
 
 **ASK** for explicit permission before pushing to remote.
+The `pre-push` hook will **BLOCK** the push if any `[Unreleased]` narrative remains (preventing unversioned leaks to main).
 
 ---
 

package/src/engine/bin/check-narrative.mjs

@@ -14,71 +14,82 @@ const PROJECT_ROOT = process.cwd();
 const CHANGELOG_PATH = path.join(PROJECT_ROOT, 'CHANGELOG.md');
 
 async function run() {
-  const commitMsgFile = process.argv[2];
-  if (!commitMsgFile) {
-    console.error('  ❌ Error: No commit message file provided.');
-    process.exit(1);
-  }
+  const isPrePush = process.argv.includes('--pre-push');
+  const commitMsgFile = isPrePush ? null : process.argv[2];
 
-  if (!fs.existsSync(commitMsgFile)) {
-    console.error(`  ❌ Error: Commit message file not found at ${commitMsgFile}`);
-    process.exit(1);
-  }
+  if (!isPrePush) {
+    if (!commitMsgFile) {
+      console.error('  ❌ Error: No commit message file provided.');
+      process.exit(1);
+    }
+    if (!fs.existsSync(commitMsgFile)) {
+      console.error(`  ❌ Error: Commit message file not found at ${commitMsgFile}`);
+      process.exit(1);
+    }
 
-  const commitMsg = fs.readFileSync(commitMsgFile, 'utf8').trim();
-  const firstLine = commitMsg.split('\n')[0].trim();
+    const commitMsg = fs.readFileSync(commitMsgFile, 'utf8').trim();
+    const firstLine = commitMsg.split('\n')[0].trim();
 
-  // ONLY target feat: and fix: (SDG Cycle Triggers) as per maintainer instruction
-  const isSdgTrigger = /^feat:/.test(firstLine) || /^fix:/.test(firstLine);
-  if (!isSdgTrigger) {
-    process.exit(0);
+    // ONLY target feat: and fix: (SDG Cycle Triggers) as per maintainer instruction
+    const isSdgTrigger = /^feat:/.test(firstLine) || /^fix:/.test(firstLine);
+    if (!isSdgTrigger) {
+      process.exit(0);
+    }
   }
 
   let changelog = '';
   try {
-    // Read STAGED version of CHANGELOG.md to prevent issues with lint-staged or stashing
+    // Read STAGED version of CHANGELOG.md (if possible)
     changelog = execSync('git show :CHANGELOG.md', {
       stdio: ['pipe', 'pipe', 'ignore'],
     }).toString();
   } catch {
-    // Fallback to disk if not in index (shouldn't happen in a commit hook for a tracked file)
     if (fs.existsSync(CHANGELOG_PATH)) {
       changelog = fs.readFileSync(CHANGELOG_PATH, 'utf8');
     }
   }
 
   if (!changelog) {
-    console.warn('  ⚠️  Warning: CHANGELOG.md not found or empty. Skipping narrative check.');
     process.exit(0);
   }
 
-  // Extract content between [Unreleased] and the next version header (## [...) or end of file
-  // We use (?=\n##\s) to match the next level-2 header specifically, avoiding matches on ### sub-headers.
   const unreleasedMatch = changelog.match(
     /##\s*\[Unreleased\].*?\n([\s\S]*?)(?=\n##\s|(?:\n){0,1}$)/i
   );
 
   if (!unreleasedMatch) {
+    if (isPrePush) process.exit(0);
     console.error('\n  ❌ NARRATIVE VIOLATION: "## [Unreleased]" section missing in CHANGELOG.md.');
-    console.error('  SDG cycles (feat/fix) MUST have a technical narrative before committing.\n');
     process.exit(1);
   }
 
   const narrative = unreleasedMatch[1]
     .replace(/###\s*(Added|Fixed|Changed|Removed|Security|Deprecated)/gi, '')
-    .replace(/<!--[\s\S]*?-->/g, '') // Remove markdown comments
+    .replace(/<!--[\s\S]*?-->/g, '')
     .trim();
 
-  // If the narrative is just whitespace or empty after removing headers/comments
-  if (!narrative || narrative.length < 3) {
-    console.error('\n  ❌ NARRATIVE VIOLATION: The [Unreleased] section is empty.');
-    console.error('  You are committing a "feat:" or "fix:" which triggers a version bump.');
-    console.error('  Please document your changes in CHANGELOG.md under [Unreleased] first.\n');
-    process.exit(1);
-  }
+  const isNarrativeEmpty = !narrative || narrative.length < 3;
 
-  console.log('  ✅ Narrative Guard: CHANGELOG.md validated.');
-  process.exit(0);
+  if (isPrePush) {
+    if (!isNarrativeEmpty) {
+      console.error('\n  ❌ DELIVERY BLOCKED: Unreleased narrative detected.');
+      console.error('  You have documented changes in CHANGELOG.md that have not been versioned.');
+      console.error(
+        '  Action: Run "npm run bump <fix|feat>" to finalize the cycle before pushing.\n'
+      );
+      process.exit(1);
+    }
+    process.exit(0);
+  } else {
+    // commit-msg mode
+    if (isNarrativeEmpty) {
+      console.error('\n  ❌ NARRATIVE VIOLATION: The [Unreleased] section is empty.');
+      console.error('  SDG cycles (feat/fix) MUST have a technical narrative before committing.\n');
+      process.exit(1);
+    }
+    console.log('  ✅ Narrative Guard: CHANGELOG.md validated.');
+    process.exit(0);
+  }
 }
 
 run().catch((err) => {

package/src/engine/lib/fs-utils.mjs

@@ -88,6 +88,25 @@ function runIfDirect(importMetaUrl, fn) {
   }
 }
 
+function detectIndentation(content) {
+  const lines = content.split('\n');
+  for (const line of lines) {
+    const match = line.match(/^(\s+)/);
+    if (match) return match[1];
+  }
+  return '  ';
+}
+
+function writeJsonAtomic(filePath, data, originalContent = null) {
+  const indent = originalContent ? detectIndentation(originalContent) : '  ';
+  const newContent = JSON.stringify(data, null, indent) + '\n';
+
+  if (originalContent === newContent) return false;
+
+  fs.writeFileSync(filePath, newContent);
+  return true;
+}
+
 const FsUtils = {
   getDirectories,
   copyRecursiveSync,
@@ -96,6 +115,8 @@ const FsUtils = {
   evaluateVersionCondition,
   getDirname,
   runIfDirect,
+  detectIndentation,
+  writeJsonAtomic,
 };
 
 export { FsUtils };

package/src/engine/lib/instruction-assembler.mjs

@@ -14,7 +14,7 @@ import { FsUtils } from './fs-utils.mjs';
 
 const { displayName } = DisplayUtils;
 const { computeHashes } = ManifestUtils;
-const { getDirname } = FsUtils;
+const { getDirname, writeJsonAtomic } = FsUtils;
 
 const __dirname = getDirname(import.meta.url);
 const SOURCE_INSTRUCTIONS = path.join(__dirname, '..', '..', 'assets', 'instructions');
@@ -463,6 +463,9 @@ function writeAgentConfig(targetDir, content, requestedAgents = []) {
     const fullDir = path.join(targetDir, target.dir);
     if (!fs.existsSync(fullDir)) fs.mkdirSync(fullDir, { recursive: true });
 
+    const targetFile = path.join(fullDir, target.file);
+    const originalContent = fs.existsSync(targetFile) ? fs.readFileSync(targetFile, 'utf8') : null;
+
     let finalContent = content;
     if (agent === 'cursor') {
       finalContent = `---\ndescription: Project Governance and Architectural Rules\nglob: *\n---\n\n${content}`;
@@ -470,7 +473,9 @@ function writeAgentConfig(targetDir, content, requestedAgents = []) {
       finalContent = buildClaudeContent();
     }
 
-    fs.writeFileSync(path.join(fullDir, target.file), finalContent);
+    if (originalContent !== finalContent) {
+      fs.writeFileSync(targetFile, finalContent);
+    }
   }
 }
 
@@ -525,7 +530,13 @@ function writeManifest(targetDir, selections, pkgVersion) {
 
   const aiDir = path.join(targetDir, '.ai');
   if (!fs.existsSync(aiDir)) fs.mkdirSync(aiDir, { recursive: true });
-  fs.writeFileSync(path.join(aiDir, '.sdg-manifest.json'), JSON.stringify(manifest, null, 2));
+
+  const manifestPath = path.join(aiDir, '.sdg-manifest.json');
+  const originalContent = fs.existsSync(manifestPath)
+    ? fs.readFileSync(manifestPath, 'utf8')
+    : null;
+
+  writeJsonAtomic(manifestPath, manifest, originalContent);
 }
 
 /**
@@ -563,7 +574,7 @@ function writeAutomationScripts(targetDir, selections) {
   if (!pkg.scripts) pkg.scripts = {};
   if (!pkg.scripts.bump) {
     pkg.scripts.bump = 'node scripts/bump.mjs';
-    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    writeJsonAtomic(pkgPath, pkg, fs.readFileSync(pkgPath, 'utf8'));
   }
 
   // 4. Configure Husky if .husky exists
@@ -580,9 +591,10 @@ function writeAutomationScripts(targetDir, selections) {
 
     if (fs.existsSync(prePushPath)) {
       const content = fs.readFileSync(prePushPath, 'utf8');
-      if (!content.includes('npm run bump')) {
+      if (!content.includes('npm test')) {
         const separator = content.endsWith('\n') ? '' : '\n';
-        fs.appendFileSync(prePushPath, `${separator}\n${nvmShim}\n${bumpCmd}\n`);
+        const newPrePushContent = `${content}${separator}\n${nvmShim}\n${bumpCmd}\n`;
+        fs.writeFileSync(prePushPath, newPrePushContent);
       }
     } else {
       const prePushContent = dedent`