sdg-agents 1.4.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdg-agents",
-  "version": "1.4.0",
+  "version": "1.10.0",
   "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

@@ -12,20 +12,19 @@ Write one sentence per completed PLAN task. If no PLAN existed (e.g. `[S]` tasks
 
 ## Step 2 — CHANGELOG
 
-- Append an entry under `## [Unreleased]` in `CHANGELOG.md`:
-
-1. **Identify Version**: Check `package.json` (or equivalent) for the current version.
-2. **Calculate Next**: Determine the next version (patch/minor) based on the cycle type (`feat` → minor/patch, `fix` → patch).
-3. **Update Header**:
-   - If the project uses auto-bump or a release is intended: Create/Update the header to `## [NEXT_VERSION] - YYYY-MM-DD`.
-   - Otherwise: Append under `## [Unreleased]`.
-4. **Append Entry**:
-   - `feat:` cycle → `### Added`
-   - `fix:` cycle → `### Fixed`
-   - `docs:` cycle → skip this step
-   - `land:` cycle → skip this step
-
-If `## [Unreleased]` (or the appropriate version header) does not exist, create it above the most recent entry.
+Prepare your technical narrative in the `CHANGELOG.md`.
+
+1. **Identify Strategy**:
+   - **Automated**: If `auto-bump.mjs` exists, you **MUST** first manually populate the `## [Unreleased]` section with your technical narrative. The automated pipeline will promote this content to the new version header during the commit. **DO NOT commit with an empty [Unreleased] section.**
+   - **Manual**: If no automation is present, you must promote the header manually (e.g., `## [1.2.0] - 2026-04-11`) or run the designated `bump` script.
+
+2. **Append Entry**:
+   - `feat:` cycle → Add under `### Added`
+   - `fix:` cycle → Add under `### Fixed`
+   - `docs:` cycle → Optional (for major architectural docs)
+   - `land:` cycle → Skip
+
+3. **Verify Header**: Ensure `## [Unreleased]` exists at the top. If missing, create it above the most recent version entry.
 
 ## Step 3 — BACKLOG: tasks.md
 

package/src/assets/instructions/core/writing-soul.md

@@ -1,82 +1,45 @@
-# Writing Soul — Professional Authority Standards
+# The Writing Soul
 
-> [!IMPORTANT]
-> **GOVERNANCE MANDATE**
-> This specification applies to all **non-code writing tasks**, including READMEs, Guides, UI Content, CHANGELOGs, and Commit Messages.
-> The goal is to eliminate "AI Slop" and restore **Developer intentionality**, density, and soul to every project artifact.
+Good technical writing starts with the realization that there is a person on both sides of the screen. We believe that software documentation is a shared conversation, and maintaining a sense of mind behind the words is essential for effective communication. Sterile or voiceless text often feels like a missed opportunity to connect and share real engineering wisdom. These standards apply to all non-code writing tasks, including READMEs, guides, UI content, and commit messages.
 
-## 1. Personality and Soul
+## Cultivating Personality
 
-Good technical writing has a **mind** behind it. Sterile, voiceless writing is as obvious as low-density slop.
+Effective writing reflects the natural rhythms of how we think and solve problems. You can bring a sense of purpose to your text by offering a clear perspective on the facts you present. Mixing brief observations with longer, more detailed explanations helps keep the reader engaged.
 
-- **Have opinions**: Don't just report facts — react to them.
-- **Vary your rhythm**: Mix short, punchy sentences with longer, flowing ones.
-- **Acknowledge complexity**: Real professionals have mixed feelings and uncertainty.
-- **Let some mess in**: Perfectly algorithmic structure feels fake. Tangents and asides add pulse.
+Authenticity also comes from acknowledging that engineering is complex. Professionals often navigate uncertainty or hold nuanced views on a topic, and reflecting those feelings makes your writing more reliable. Allowing space for a well-placed aside or a brief tangent can create the pulse that makes a technical guide feel alive and uniquely human.
 
----
-
-## 2. Content Patterns to Eliminate
-
-### I. Significance Inflation
+## Seeking Authenticity
 
-**Banned phrases**: "testament/reminder to", "pivotal moment", "is a testament/reminder", "evolving landscape", "underscores its significance".
-**Fix**: Remove the "puffery". Just state the facts and their direct consequences.
+Maintaining a professional and grounded tone involves recognizing patterns that sometimes cloud the clarity of our message. We can improve our writing by focusing on direct observations rather than relying on stylistic crutches.
 
-### II. Superficial -ing Endings
+### Natural Expression
 
-**Patterns**: "...highlighting X", "...ensuring Y", "...reflecting Z".
-**Fix**: Break into clear, active clauses. Avoid tacking on "fake depth" via present participle phrases.
+True authority often speaks for itself. We can avoid significance inflation by stating facts and their direct consequences, allowing the quality of the work to be the primary focus. Using phrases like "testament to" or "pivotal moment" often adds unnecessary weight where a simple description of the impact would be more effective.
 
-### III. Promotional & Sycophantic Tone
+### Active Clarity
 
-**Banned adjectives**: "vibrant", "rich", "groundbreaking", "breathtaking", "seamless".
-**Banned artifacts**: "Great question!", "I hope this helps!", "Certainly!".
-**Fix**: Maintain a professional, peer-to-level tone. No sales pitch, no servility.
+Direct communication is usually the most helpful for the reader. We can sharpen our message by breaking complex ideas into clear, active clauses. While present participle phrases ending in "-ing" are common, they sometimes obscure the relationship between actions. Choosing active verbs helps ensure the reader understands the exact flow of information or logic.
 
-### IV. Generic Positive Conclusions
-
-**Patterns**: "The future looks bright", "Exciting times lie ahead".
-**Fix**: End with a concrete next step or a specific fact about future plans.
-
----
+### Professional Peerage
 
-## 3. Language & Style Hardening
+We value a tone that respects the expertise of the reader. A calm and peer-to-level approach builds trust more effectively than using promotional adjectives like "vibrant" or "groundbreaking." This same principle applies to our interactions, where a professional and direct response carries more weight than conversational fillers or overly decorative enthusiasm.
 
-### I. Copula Avoidance
+## Language and Style Practices
 
-**Stop**: "serves as", "stands as", "represents [a]".
-**Use**: "is", "are", "has". Simple is more direct.
+The way we structure our language influences how easily a reader can follow our logic. We prefer simple and direct verbs to keep the focus on the content. Words like "is," "are," and "has" are often more effective than complex alternatives that can slow down the reading experience.
 
-### II. Em Dash & Boldface Overuse
+### Visual Serenity
 
-**Rule**: Em dashes (—) are banned. No exceptions. AI uses them constantly to fake rhetorical punch.
-**Fix**: Rewrite with a comma, a period, or a new sentence. If it needs a pause, earn it with structure.
-Bold is for true technical emphasis only: a term, a command, a key constraint. Not decoration.
-
-### III. Title Case & Emojis
-
-**Rule**: No Title Case for everything. Emojis are reserved for **pattern signaling only** — marking BAD/GOOD examples, callouts, or explicit visual cues in documentation.
-**Banned**: Decorative emojis in section headers, link anchors, or inline prose (e.g. `## 🚀 Quick Start`, `✨ Try the app`).
-**Allowed**: Signal emojis that carry semantic meaning in structured examples:
-
-- `BAD`: `❌ if (data == null)` / `GOOD`: `✅ if (!data)`
-- `[!WARNING]`, `[!TIP]`, `[!NOTE]` callouts (GitHub-native, not emoji)
-  **Fix**: Use Sentence case for headings. Strip all decorative emoji. If a header needs visual weight, use formatting — not icons.
-
----
+Structure and rhythm should guide the reader through the text naturally. We find that avoiding em dashes encourages a more thoughtful sentence structure, as it requires earning each pause through careful composition. Similarly, we use bold formatting exclusively for technical emphasis, such as specific terms, commands, or key constraints.
 
-## 4. The Authority Loop
+Our approach to formatting also prioritizes clarity. Headings follow sentence case to maintain a serene and professional appearance. We use emojis only when they carry semantic meaning for pattern signaling, such as marking successful or unsuccessful examples in a technical guide. This keeps the visual environment focused on the information being shared.
 
-Before finalizing any content, perform a self-audit:
+## The Refinement Process
 
-1. **Identify Patterns**: Scan for the AI-isms listed above.
-2. **Rewrite**: Replace slop with direct, active voice.
-3. **Add Soul**: Inject a specific observation or a varied rhythm.
-4. **Final Check**: Ask: _"What makes this so obviously AI-generated?"_ Fix the remaining tells.
+Before sharing your work, a brief moment of reflection can help ensure the content reflects your intention. You might find it helpful to look for familiar patterns that feel more like general summaries than specific observations. Replacing these with active, direct language often makes the writing feel more genuine. Adding a unique insight or varying the length of your sentences can provide the final touch that makes the text feel truly yours.
 
 ---
 
-## Reference & Credits
+## Reference and Credits
 
-This specification is based on the **Wikipedia:Signs of AI writing** project, maintained by **WikiProject AI Cleanup**. It serves as the foundational standard for eliminating statistical slop and restoring **Developer intentionality** to generated text.
+This standard is inspired by the collective efforts of the project to eliminate statistical slop and restore intentionality to generated text. It serves as a foundation for building clear, purposeful, and human-centered documentation across the entire ecosystem.

package/src/assets/instructions/templates/bump.mjs

@@ -63,7 +63,6 @@ function updateChangelog(newVersion) {
   const today = new Date().toISOString().split('T')[0];
 
   // Pattern to find the [Unreleased] section
-  // It handles both formats: ## [Unreleased] and ## [Unreleased] - YYYY-MM-DD
   const unreleasedRegex = /##\s*\[Unreleased\](\s*-\s*\d{4}-\d{2}-\d{2})?/i;
 
   if (!unreleasedRegex.test(content)) {

package/src/engine/bin/auto-bump.mjs

@@ -12,6 +12,7 @@ const { runIfDirect } = FsUtils;
 // bin/ → engine/ → src/ → root
 const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../');
 const PACKAGE_PATHS = [path.join(ROOT_DIR, 'package.json')];
+const CHANGELOG_PATH = path.join(ROOT_DIR, 'CHANGELOG.md');
 
 // --- Orchestrator ---
 
@@ -27,7 +28,13 @@ async function run() {
   const rootPkg = readPackageJson(resolveRootPackagePath());
   const nextVersion = bumpVersion(rootPkg.version, bumpType);
 
+  // 1. Promote Changelog
+  updateChangelog(nextVersion);
+
+  // 2. Sync Package.json files
   syncAllPackages(nextVersion);
+
+  // 3. Commit the bump
   stageAndCommit(nextVersion);
 
   console.log(`  auto-bump: ${rootPkg.version} → ${nextVersion} (${bumpType})`);
@@ -57,9 +64,37 @@ function bumpVersion(current, bumpType) {
       return `${major}.${minor + 1}.0`;
     case 'patch':
       return `${major}.${minor}.${patch + 1}`;
+    default:
+      return current;
   }
 }
 
+function updateChangelog(newVersion) {
+  if (!fs.existsSync(CHANGELOG_PATH)) return;
+
+  const content = fs.readFileSync(CHANGELOG_PATH, 'utf8');
+  const today = new Date().toISOString().split('T')[0];
+
+  // Pattern to find the [Unreleased] section
+  const unreleasedRegex = /##\s*\[Unreleased\](\s*-\s*\d{4}-\d{2}-\d{2})?/i;
+
+  if (!unreleasedRegex.test(content)) return;
+
+  const newHeader = `## [${newVersion}] - ${today}`;
+
+  // 1. Promote Unreleased to New Version
+  let updatedContent = content.replace(unreleasedRegex, newHeader);
+
+  // 2. Inject new [Unreleased] block at the top if it was promoted
+  const insertIndex = updatedContent.indexOf(newHeader);
+  const nextBlock = `## [Unreleased]\n\n### Added\n\n### Fixed\n\n`;
+
+  updatedContent =
+    updatedContent.slice(0, insertIndex) + nextBlock + updatedContent.slice(insertIndex);
+
+  fs.writeFileSync(CHANGELOG_PATH, updatedContent);
+}
+
 // --- Sync & Commit ---
 
 function syncAllPackages(nextVersion) {
@@ -71,7 +106,8 @@ function syncAllPackages(nextVersion) {
 
 function stageAndCommit(nextVersion) {
   const paths = resolvePackagePaths();
-  const files = paths.filter((p) => fs.existsSync(p)).join(' ');
+  const files = [...paths, CHANGELOG_PATH].filter((p) => fs.existsSync(p)).join(' ');
+
   execSync(`git add ${files}`, { stdio: 'inherit' });
   execSync(`git commit -m "chore: bump version to ${nextVersion}"`, { stdio: 'inherit' });
 }

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * Narrative Guard — Blocks feat: and fix: commits if CHANGELOG.md [Unreleased] is empty.
+ * Ensures the auto-bump pipeline always has content to promote.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { execSync } from 'node:child_process';
+
+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);
+  }
+
+  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();
+
+  // 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
+    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) {
+    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
+    .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);
+  }
+
+  console.log('  ✅ Narrative Guard: CHANGELOG.md validated.');
+  process.exit(0);
+}
+
+run().catch((err) => {
+  console.error('  ❌ Narrative Guard Exception:', err.message);
+  process.exit(1);
+});
+// test

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

@@ -13,13 +13,12 @@ import crypto from 'node:crypto';
 import { FsUtils } from '../lib/fs-utils.mjs';
 import { ResultUtils } from '../lib/result-utils.mjs';
 
-const { getDirname, runIfDirect } = FsUtils;
+const { runIfDirect } = FsUtils;
 const { success, fail } = ResultUtils;
 
-const __dirname = getDirname(import.meta.url);
-const MONOREPO_ROOT = path.join(__dirname, '..', '..', '..', '..', '..');
-const ASSETS_DIR = path.join(MONOREPO_ROOT, 'packages', 'cli', 'src', 'assets', 'instructions');
-const AI_DIR = path.join(MONOREPO_ROOT, 'packages', 'cli', '.ai', 'instructions');
+const PROJECT_ROOT = process.cwd();
+const ASSETS_DIR = path.join(PROJECT_ROOT, 'src', 'assets', 'instructions');
+const AI_DIR = path.join(PROJECT_ROOT, '.ai', 'instructions');
 
 // why: flavor/ in .ai/ is populated by renaming flavors/{id}/ — no direct mirror exists in src/assets/flavor/
 const MIRRORED_DIRS = ['core', 'idioms', 'templates', 'competencies'];

package/src/engine/bin/index.mjs

@@ -39,6 +39,11 @@ async function run() {
   // Resolve target directory early for the entire cycle
   args.targetDir = path.resolve(args.targetDir || process.cwd());
 
+  // Maintainer Protocol: ensuring core instructions are synced to .ai/ for the agent
+  if (!args.subcommand && !args.help && !args.version) {
+    await ensureMaintainerSync(args.targetDir);
+  }
+
   if (args.subcommand) {
     await executeSubcommand(args);
   } else {
@@ -210,6 +215,35 @@ async function runSettingsMenu(targetDir) {
 
 // --- System ---
 
+async function ensureMaintainerSync(targetDir) {
+  const { isMaintainerMode } = PromptUtils;
+  if (!isMaintainerMode()) return;
+
+  const { SyncChecker } = await import('./check-sync.mjs');
+  const syncResult = SyncChecker.run();
+
+  if (syncResult.isFailure) {
+    console.log('\n  🛠️  MAINTAINER MODE: Drift detected in core instructions.');
+    console.log('  🔄 Automatic sync in progress...\n');
+
+    const { ManifestUtils } = await import('../lib/manifest-utils.mjs');
+    const { SDG } = await import('./build-bundle.mjs');
+    const manifest = ManifestUtils.loadManifest(targetDir);
+
+    if (manifest) {
+      try {
+        await SDG.run(targetDir, { selections: manifest.selections });
+        console.log('\n  ✅ Core instructions synchronized. Agent rules are up-to-date.\n');
+        console.log('─'.repeat(50) + '\n');
+      } catch (error) {
+        console.log(`\n  ⚠️  Automatic sync failed: ${error.message}\n`);
+      }
+    } else {
+      console.log('  ⚠️  Cannot auto-sync: No manifest found. Run "init" once.\n');
+    }
+  }
+}
+
 function handleExitError(error) {
   if (error.message?.includes('force closed') || error.name === 'ExitPromptError') {
     console.log('\n\n  👋 Goodbye! See you soon engineer.');

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

@@ -573,10 +573,10 @@ function writeAutomationScripts(targetDir, selections) {
     const nvmShim = dedent`
       # NVM Shim (Essential for projects Staff in Linux/NVM)
       export NVM_DIR="$HOME/.nvm"
-      [ -s "$NVM_DIR/nvm.sh" ] && \\. "$NVM_DIR/nvm.sh"
+      [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
     `;
 
-    const bumpCmd = 'npm run bump fix';
+    const bumpCmd = '# Pre-push check (non-mutating)\nnpm test';
 
     if (fs.existsSync(prePushPath)) {
       const content = fs.readFileSync(prePushPath, 'utf8');
@@ -587,7 +587,6 @@ function writeAutomationScripts(targetDir, selections) {
     } else {
       const prePushContent = dedent`
         #!/usr/bin/env sh
-        . "$(dirname -- "$0")/_/husky.sh"
 
         ${nvmShim}