agentic-sdd-framework 1.4.0

package/scripts/check-spec.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/check-spec.js
+ *
+ * Verifies that the active specification backs its claims with evidence.
+ *
+ * Lite mode (docs/SPEC.md):
+ *   - "**Status:**" is Draft, In Progress, or Completed (the untouched template counts as
+ *     Draft; anything else is an error).
+ *   - The "Verification Gate" section exists.
+ *   - Every checked task has evidence. Evidence recorded by `sdd-verify --task` must be
+ *     intact (its hash matches) and exit 0. Hand-written evidence is reported as manual,
+ *     and rejected when specification.requireRecordedEvidence is true.
+ *   - In Progress / Completed: the verification command and expected output are real.
+ *   - Completed: every task is checked, and "Last Verified" is a PASS recorded by
+ *     `sdd-verify --record` whose state fingerprint matches the state the spec was
+ *     completed in (see lib/state.js).
+ *
+ * Rigor mode (docs/roadmap/): delegates to `auditkit lint` (>= MIN_AUDITKIT), run on the
+ * documents read from the same source as every other check.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { readFile, readFiles, listTrackedFiles, describeSource, WORKTREE } = require('./lib/git');
+const { loadConfig, getIn } = require('./lib/config');
+const { runCheckCli } = require('./lib/cli');
+const { parseSpec } = require('./lib/spec');
+const { stateOf, referenceSourceFor } = require('./lib/state');
+
+const AUDITKIT_INSTALL = 'pipx install git+https://github.com/tBeltty/auditor-executor-protocol';
+const MIN_AUDITKIT = [0, 3, 9];
+
+function lintLiteSpec(text, { requireRecordedEvidence = false, expectedState = null, shallow = false } = {}) {
+    const spec = parseSpec(text);
+    const problems = [];
+    const notes = [];
+    // An unknown status is reported as a problem and otherwise held to the draft rules.
+    const status = spec.status || 'draft';
+    const shownStatus = spec.statusProblem && spec.statusProblem.startsWith('Unknown') ? 'unknown' : status;
+
+    problems.push(...spec.hiddenProblems);
+    if (spec.statusProblem) problems.push(spec.statusProblem);
+    if (!spec.gate) problems.push('No "Verification Gate" section. Every specification needs one.');
+
+    let manual = 0;
+    for (const task of spec.tasks.filter(t => t.checked)) {
+        const { text: evidence, recorded } = task.evidence;
+        if (!evidence) {
+            const how = task.id.startsWith('line ')
+                ? 'Give the task an ID (for example `**T4:**`) and record evidence with sdd-verify --task T4 -- <command>'
+                : `Record it with sdd-verify --task ${task.id} -- <command>`;
+            problems.push(`${task.id} is checked but has no evidence. ${how}, or paste the command and its output under **Evidence:**.`);
+        } else if (recorded) {
+            if (!recorded.intact) problems.push(`${task.id}: recorded evidence was edited after sdd-verify wrote it (hash mismatch).`);
+            else if (recorded.exit !== '0') problems.push(`${task.id}: recorded evidence shows exit ${recorded.exit}, not 0.`);
+        } else {
+            manual++;
+            if (requireRecordedEvidence) problems.push(`${task.id}: evidence is hand-written; specification.requireRecordedEvidence needs sdd-verify --task ${task.id} -- <command>.`);
+        }
+    }
+    if (manual > 0 && !requireRecordedEvidence) notes.push(`${manual} checked task(s) have hand-written evidence (not recorded by sdd-verify).`);
+
+    if (spec.gate && (status === 'in progress' || status === 'completed')) {
+        if (!spec.gate.command) problems.push(`Status is "${status}" but the verification command is still a placeholder.`);
+        if (!spec.gate.expected) problems.push(`Status is "${status}" but the expected output is still a placeholder.`);
+    }
+    if (status === 'completed') {
+        for (const task of spec.tasks.filter(t => !t.checked)) {
+            problems.push(`Status is "completed" but ${task.id} is not checked.`);
+        }
+        const last = spec.gate && spec.gate.lastVerifiedParsed;
+        if (!last) {
+            problems.push('Status is "completed" but "Last Verified" is missing or was not written by sdd-verify --record.');
+        } else if (!last.intact) {
+            problems.push('"Last Verified" was edited after sdd-verify wrote it, or the verification command or expected output changed since. Run sdd-verify --record.');
+        } else if (last.result !== 'PASS' || last.exit !== '0') {
+            problems.push(`Status is "completed" but the last verification is ${last.result} (exit ${last.exit}). Fix it and run sdd-verify --record.`);
+        } else if (expectedState && last.state !== expectedState) {
+            problems.push(shallow
+                ? `The recorded verification (state ${last.state}) does not match the oldest commit in this shallow clone (state ${expectedState}), and the commit that completed the spec may be older. Fetch the full history (git fetch --unshallow; in GitHub Actions, actions/checkout with fetch-depth: 0).`
+                : `The recorded verification (state ${last.state}) does not match the content the spec was completed with (state ${expectedState}). Files changed after sdd-verify ran; run it again.`);
+        }
+    }
+    return { status: shownStatus, spec, problems, notes };
+}
+
+function parseVersion(text) {
+    const match = String(text).match(/(\d+)\.(\d+)\.(\d+)/);
+    return match ? match.slice(1).map(Number) : null;
+}
+
+function versionAtLeast(actual, minimum) {
+    for (let i = 0; i < 3; i++) {
+        if (actual[i] !== minimum[i]) return actual[i] > minimum[i];
+    }
+    return true;
+}
+
+function runAuditkit(root, roadmapDir, source) {
+    const bin = process.env.SDD_AUDITKIT || 'auditkit';
+    const version = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+    if (version.error) {
+        return { ok: false, report: `❌ Rigor mode is checked by auditkit, which is not installed.\nInstall it with: ${AUDITKIT_INSTALL}` };
+    }
+    const actual = parseVersion(version.stdout);
+    if (!actual || !versionAtLeast(actual, MIN_AUDITKIT)) {
+        return {
+            ok: false,
+            report: `❌ auditkit ${actual ? actual.join('.') : '(unknown version)'} is older than ${MIN_AUDITKIT.join('.')}, which this gate requires.\nUpgrade with: pipx install --force git+https://github.com/tBeltty/auditor-executor-protocol`
+        };
+    }
+
+    // auditkit reads files from disk; for the index or a commit, lint a temporary copy.
+    let dir = path.join(root, roadmapDir);
+    let tmp = null;
+    if (source.kind !== 'worktree') {
+        tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sdd-roadmap-'));
+        const prefix = `${roadmapDir.replace(/\/+$/, '')}/`;
+        const files = listTrackedFiles(root, source).filter(f => f.startsWith(prefix));
+        for (const [file, buffer] of readFiles(root, files, source)) {
+            if (!buffer) continue;
+            const target = path.join(tmp, file.slice(prefix.length));
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, buffer);
+        }
+        dir = tmp;
+    }
+    try {
+        const result = spawnSync(bin, ['lint', dir], { cwd: root, encoding: 'utf8' });
+        const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+        return {
+            ok: result.status === 0,
+            report: `${result.status === 0 ? '✅' : '❌'} auditkit lint ${roadmapDir} (${describeSource(source)})\n${output}`
+        };
+    } finally {
+        if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+// The framework's own repository has no project specification. The exemption requires both
+// project.type "framework" and the framework's package name, so it cannot be used as a
+// switch to turn the specification check off in a project.
+function isFrameworkRepository(root, source, config) {
+    if (getIn(config, 'project.type', 'application') !== 'framework') return false;
+    const pkg = readFile(root, 'package.json', source);
+    try {
+        return Boolean(pkg) && JSON.parse(pkg.toString('utf8')).name === 'agentic-sdd-framework';
+    } catch {
+        return false;
+    }
+}
+
+function run({ root, source = WORKTREE } = {}) {
+    const config = loadConfig(root, source);
+    if (isFrameworkRepository(root, source, config)) {
+        return { ok: true, report: '⏭️  Not applicable (the framework repository has no project specification).' };
+    }
+
+    if (getIn(config, 'specification.mode', 'lite') === 'rigor') {
+        const roadmapDir = getIn(config, 'specification.roadmapDir', 'docs/roadmap');
+        if (!readFile(root, `${roadmapDir}/execution-guide.md`, source)) {
+            return { ok: false, report: `❌ Rigor mode: ${roadmapDir}/execution-guide.md not found. Run sdd-init --mode=rigor.` };
+        }
+        return runAuditkit(root, roadmapDir, source);
+    }
+
+    const specFile = getIn(config, 'specification.specFile', 'docs/SPEC.md');
+    const buffer = readFile(root, specFile, source);
+    if (!buffer) {
+        return { ok: false, report: `❌ Lite mode: ${specFile} not found. Run sdd-init or create it from docs/SPEC_TEMPLATE.md.` };
+    }
+    const text = buffer.toString('utf8');
+    const completed = parseSpec(text).status === 'completed';
+    const reference = completed ? referenceSourceFor(root, source, specFile) : null;
+    const expectedState = reference ? stateOf(root, reference, specFile) : null;
+    const { status, spec, problems, notes } = lintLiteSpec(text, {
+        requireRecordedEvidence: getIn(config, 'specification.requireRecordedEvidence', false),
+        expectedState,
+        shallow: Boolean(reference && reference.shallow)
+    });
+    const done = spec.tasks.filter(t => t.checked).length;
+    const summary = `${specFile}: status "${status}", ${done}/${spec.tasks.length} task(s) checked`;
+    const noteLines = notes.map(n => `  ℹ️  ${n}`);
+    if (problems.length === 0) {
+        return { ok: true, report: [`✅ ${summary}.`, ...noteLines].join('\n') };
+    }
+    return {
+        ok: false,
+        report: [`❌ ${summary}, ${problems.length} problem(s):\n`, ...problems.map(p => `  - ${p}`), ...noteLines].join('\n')
+    };
+}
+
+if (require.main === module) {
+    runCheckCli('📋 Agentic SDD Framework: Specification Check', run);
+}
+
+module.exports = { MIN_AUDITKIT, lintLiteSpec, parseVersion, versionAtLeast, run };

package/scripts/check-system-prerequisites.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/check-system-prerequisites.js
+ * 
+ * Day-0 System Diagnostics Validator
+ * Verifies that the local environment meets the minimum prerequisites for
+ * Spec-Driven Development (SDD) with AI agents.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Oldest Node.js release line still maintained upstream.
+const MIN_NODE_MAJOR = 22;
+
+function runCommand(command) {
+    try {
+        return { success: true, output: execSync(command, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim() };
+    } catch (error) {
+        return { success: false, error: error.message, stderr: error.stderr ? error.stderr.toString().trim() : '' };
+    }
+}
+
+// Collects the diagnostics. env and homedir are injectable for tests.
+function collectChecks({ env = process.env, homedir = os.homedir(), nodeVersion = process.version } = {}) {
+    const checks = [];
+
+    // 1. Check Node.js Version
+    const majorVersion = parseInt(nodeVersion.replace(/^v/, '').split('.')[0], 10);
+    if (majorVersion >= MIN_NODE_MAJOR) {
+        checks.push({ name: 'Node.js Runtime', status: 'PASS', detail: `Version ${nodeVersion} (>= ${MIN_NODE_MAJOR} required)` });
+    } else {
+        checks.push({ name: 'Node.js Runtime', status: 'FAIL', detail: `Version ${nodeVersion} detected. Node.js ${MIN_NODE_MAJOR} LTS or newer is required.` });
+    }
+
+    // 2. Check Git Installation
+    const gitCheck = runCommand('git --version');
+    if (gitCheck.success) {
+        checks.push({ name: 'Git Binary', status: 'PASS', detail: gitCheck.output });
+    } else {
+        checks.push({ name: 'Git Binary', status: 'FAIL', detail: 'Git is not installed or not in PATH.' });
+    }
+
+    // 3. Check Git Identity (user.name and user.email)
+    const isCI = env.CI === 'true' || env.GITHUB_ACTIONS === 'true';
+    const gitNameCheck = runCommand('git config --get user.name');
+    const gitEmailCheck = runCommand('git config --get user.email');
+    if (gitNameCheck.success && gitEmailCheck.success && gitNameCheck.output && gitEmailCheck.output) {
+        checks.push({ name: 'Git Identity', status: 'PASS', detail: `${gitNameCheck.output} <${gitEmailCheck.output}>` });
+    } else if (isCI) {
+        checks.push({ name: 'Git Identity', status: 'PASS', detail: 'CI Runner environment (committer identity not required for builds)' });
+    } else {
+        checks.push({
+            name: 'Git Identity',
+            status: 'FAIL',
+            detail: 'git config user.name or user.email is missing. Run: git config --global user.name "Your Name" && git config --global user.email "your@email.com"'
+        });
+    }
+
+    // 4. Check GitHub CLI (gh)
+    const ghVersionCheck = runCommand('gh --version');
+    if (ghVersionCheck.success) {
+        const firstLine = ghVersionCheck.output.split('\n')[0];
+        const ghAuthCheck = runCommand('gh auth status');
+        if (ghAuthCheck.success) {
+            checks.push({ name: 'GitHub CLI (gh)', status: 'PASS', detail: `${firstLine} (Authenticated)` });
+        } else {
+            checks.push({
+                name: 'GitHub CLI (gh)',
+                status: 'WARN',
+                detail: `${firstLine} installed, but not authenticated. Run: gh auth login`
+            });
+        }
+    } else {
+        checks.push({
+            name: 'GitHub CLI (gh)',
+            status: 'WARN',
+            detail: 'gh CLI is not installed. Recommended for automated repository provisioning. See: https://cli.github.com'
+        });
+    }
+
+    // 5. Check SSH Keys for secure Git operations
+    const sshDir = path.join(homedir, '.ssh');
+    const commonKeys = ['id_ed25519', 'id_rsa', 'id_ecdsa'];
+    const foundKeys = commonKeys.filter(k => fs.existsSync(path.join(sshDir, k)));
+    if (foundKeys.length > 0) {
+        checks.push({ name: 'SSH Keys', status: 'PASS', detail: `Detected: ${foundKeys.join(', ')} in ~/.ssh/` });
+    } else {
+        checks.push({
+            name: 'SSH Keys',
+            status: 'WARN',
+            detail: 'No standard SSH private keys found in ~/.ssh/. HTTPS credentials or token auth will be required.'
+        });
+    }
+    return checks;
+}
+
+function main() {
+    const checks = collectChecks();
+    console.log('\n======================================================');
+    console.log('  🔍 Agentic SDD Framework: Day-0 Environment Check');
+    console.log('======================================================\n');
+
+    let hasFailure = false;
+    checks.forEach(check => {
+        let icon = '✅';
+        if (check.status === 'FAIL') {
+            icon = '❌';
+            hasFailure = true;
+        } else if (check.status === 'WARN') {
+            icon = '⚠️ ';
+        }
+        console.log(`${icon} [${check.status}] ${check.name}`);
+        console.log(`   ${check.detail}\n`);
+    });
+
+    if (hasFailure) {
+        console.log('❌ Environment diagnostic FAILED. Please resolve the critical issues above.\n');
+        process.exit(1);
+    } else {
+        console.log('✅ Environment diagnostic PASSED. System is ready for SDD bootstrapping.\n');
+        process.exit(0);
+    }
+}
+
+if (require.main === module) {
+    main();
+}
+
+module.exports = { MIN_NODE_MAJOR, collectChecks };

package/scripts/check-versions.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/check-versions.js
+ *
+ * Version Sync Checker for the framework repository itself.
+ * When sdd.config.json declares project.type "framework", package.json and
+ * sdd.config.json must carry the same version. In projects bootstrapped by sdd-init,
+ * sdd.config.json "version" records the framework version that generated it and is
+ * unrelated to the project's own version, so the check does not apply.
+ */
+
+const { readFile, WORKTREE } = require('./lib/git');
+const { parseConfig, getIn } = require('./lib/config');
+const { runCheckCli } = require('./lib/cli');
+
+function run({ root, source = WORKTREE } = {}) {
+    const configBuffer = readFile(root, 'sdd.config.json', source);
+    if (!configBuffer) {
+        return { ok: false, report: '❌ sdd.config.json not found. Run sdd-init first.' };
+    }
+    const config = parseConfig(configBuffer.toString('utf8'));
+    const type = getIn(config, 'project.type', 'application');
+    if (type !== 'framework') {
+        return { ok: true, report: `⏭️  Not applicable (project.type is "${type}"; only the framework repository syncs versions).` };
+    }
+
+    const packageBuffer = readFile(root, 'package.json', source);
+    if (!packageBuffer) {
+        return { ok: false, report: '❌ package.json not found.' };
+    }
+    const pkgVersion = JSON.parse(packageBuffer.toString('utf8')).version;
+    const configVersion = config.version;
+    const summary = `  - package.json:    ${pkgVersion}\n  - sdd.config.json: ${configVersion}\n\n`;
+
+    if (pkgVersion !== configVersion) {
+        return {
+            ok: false,
+            report: summary + `❌ Version mismatch: package.json (${pkgVersion}) !== sdd.config.json (${configVersion}).\n` +
+                'Action: Synchronize version strings before committing.'
+        };
+    }
+    return { ok: true, report: summary + '✅ Version manifests are in sync.' };
+}
+
+if (require.main === module) {
+    runCheckCli('🏷️  Agentic SDD Framework: Version Sync Check', run);
+}
+
+module.exports = { run };

package/scripts/dev/fuzz-spec-markup.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/dev/fuzz-spec-markup.js
+ *
+ * Differential fuzz for the Lite spec parser against cmark-gfm, the renderer GitHub uses.
+ * It generates random specs from risky Markdown (fences on list markers, tabs, comments,
+ * raw HTML, lazy lines, definitions, entities, look-alike and invisible characters, Status
+ * variants), and for every spec the parser accepts (no problems) compares its reading with
+ * the cmark-gfm rendering. A bypass is a rendered unchecked task the parser does not see, a
+ * rendered Status different from the parsed one, or a gate command different from the
+ * rendered one.
+ *
+ *   python3 -m venv /tmp/fuzz-venv && /tmp/fuzz-venv/bin/pip install cmarkgfm
+ *   FUZZ_PYTHON=/tmp/fuzz-venv/bin/python node scripts/dev/fuzz-spec-markup.js [cases]
+ *
+ * Exits 1 on any bypass.
+ */
+
+const { spawnSync } = require('child_process');
+
+const PYTHON = process.env.FUZZ_PYTHON || 'python3';
+const RENDER = `
+import json, sys
+import cmarkgfm
+from cmarkgfm.cmark import Options
+opts = Options.CMARK_OPT_UNSAFE | Options.CMARK_OPT_FOOTNOTES
+print(json.dumps([cmarkgfm.github_flavored_markdown_to_html(t, options=opts) for t in json.load(sys.stdin)]))
+`;
+// Renders a batch of documents with cmark-gfm in one Python process.
+function renderAll(texts) {
+    const result = spawnSync(PYTHON, ['-c', RENDER], { input: JSON.stringify(texts), encoding: 'utf8', maxBuffer: 1 << 30 });
+    if (result.status !== 0) {
+        console.error(`cmark-gfm is needed (a dev-only tool, not a framework dependency):\n  python3 -m pip install cmarkgfm\n${result.stderr}`);
+        process.exit(2);
+    }
+    return JSON.parse(result.stdout);
+}
+const { parseSpec } = require('../lib/spec');
+const { skeleton } = require('../lib/spec-markup');
+const rnd = n => Math.floor(Math.random() * n);
+const BODY = [
+    '**Status:** Draft', '**Status:** Completed', '* [ ] **T2:** open', '* [x] **T3:** done', '  * [ ] **T4:** nested',
+    '1. [ ] **T5:** num', '  * **Evidence:** ok', '```', '  ```', '~~~', '  ~~~', '    ~~~', '', '', 'plain text', 'lazy line',
+    '  indented two', '> quoted', '<!-- x -->', '<!--', '-->', '  <!--', 'a `b` c', '* ~~~', '1. ~~~', '* ```', '> ~~~',
+    '* > ~~~', '  * ~~~', '- ~~~', '+ ```', '> * ~~~', '* [ ] ~~~', '  echo A', '  echo B', 'echo C', '    ```', '````',
+    '* [x] **T6:** x\n  ~~~', '\t~~~', '* \t~~~', '1) ~~~',
+    '[n](https://e.com "t', 'end")', '[n](https://e.com "t")', '**Sta&#116;us:** Completed', '**Sta\u200Btus:** Completed',
+    '**\u0405tatus:** Completed', '\u00A0', '  \u00A0', '> x', '>   * [ ] **T7:** q', '  > * [ ] **T8:** q', '[d]: https://e.com',
+    '"title"', '[ci]: https://e.com "**Verification Command:**"', '**Status**: Completed', '**Status:**Completed', '&nbsp;',
+    '<!-->', '<!--->', '\t<!--', '\t-->', 'notes <!--x@y_z>', '<https://e.com>', '<a@b.co>', '[ref', ']: https://e.com',
+    '[^n]: note', '[^n]', '1. **Status:** Draft', '1. **Verification Command:**', '   ```bash', '   echo D', '   ```',
+    '**Status** Completed', '__Status:__ Draft', 'Status codes follow RFC 9110', '    rm -rf build', '__Verification Command:__',
+    '```\f', '~~~\v', '  ```\f', '* [a]: /u "', '1. [a]: /u "', '"', 'Tracking: <https://e.com/x`y> <!-- `', '      npm test',
+    '* [^n]: note', '> [^n]: note',
+    // Wide markers ("1.   ", "10.  ") widen the gap between 4 spaces and the item's own
+    // content column, where cmark-gfm and markdown-it can read a ">"/"#"/fence line
+    // differently (lazy continuation vs. indented code): R45, R46.
+    '1.   [x] **T9:** wide marker', '10.  [ ] **T9:** wide marker', '    > shallow quote', '    # shallow heading',
+    '    ```', '    ~~~', '     * [ ] **T9:** deep nested',
+];
+const SAFE = ['**Status:** Draft', '* [ ] **T2:** open', '* [x] **T3:** done', '  * [ ] **T4:** nested', '', 'plain text',
+    '  ```bash', '  echo A', '  ```', '  ~~~', '  echo B', '<!-- x -->', 'a `b` c', '  indented two'];
+const pick = () => (Math.random() < 0.8 ? SAFE[rnd(SAFE.length)] : BODY[rnd(BODY.length)]);
+function renderedView(html) {
+    const noCode = html.replace(/<pre>[\s\S]*?<\/pre>/g, '').replace(/<code>[\s\S]*?<\/code>/g, '');
+    const tasks = [...noCode.matchAll(/<input type="checkbox"( checked="")? disabled="" \/>/g)].map(m => Boolean(m[1]));
+    // Every rendered block that reads as a Status line: "Status" followed by a colon, or
+    // emphasized, at the start of the block, however it is spelled.
+    const decode = t => t.replace(/<[^>]+>/g, '').replace(/&amp;/g, '&').replace(/&quot;/g, '"').replace(/&lt;/g, '<').replace(/&gt;/g, '>');
+    const statuses = [];
+    for (const block of noCode.split(/<\/?(?:p|li|h[1-6]|blockquote|ul|ol|td|th)[^>]*>|<br\s*\/?>|\n/)) {
+        const clean = block.replace(/^\s*<input[^>]*>\s*/, '');
+        const text = skeleton(decode(clean));
+        const emphasized = clean.trim().match(/^<(strong|em|del)>([\s\S]*?)<\/\1>/);
+        if (text.startsWith('status:') || (emphasized && skeleton(decode(emphasized[2])).startsWith('status'))) {
+            statuses.push(text.slice(text.indexOf(':') + 1) || text.slice('status'.length));
+        }
+    }
+    let command = null;
+    const label = html.match(/<li>\s*(?:<p>)?<strong>Verification Command:<\/strong>/);
+    if (label) {
+        const m = html.slice(label.index).match(/<pre[^>]*><code[^>]*>([\s\S]*?)<\/code><\/pre>/);
+        if (m) command = m[1].replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&amp;/g, '&').trim();
+    }
+    return { tasks, statuses, command };
+}
+
+const N = Number(process.argv[2] || 100000);
+const BATCH = 5000;
+let accepted = 0;
+let bad = 0;
+for (let done = 0; done < N; done += BATCH) {
+    const cases = [];
+    for (let k = 0; k < Math.min(BATCH, N - done); k++) {
+        const body = Array.from({ length: 3 + rnd(10) }, pick);
+        const gate = ['## 4. Verification Gate', '', '* **Verification Command:**', ...Array.from({ length: 2 + rnd(8) }, pick),
+            '* **Expected Output:**', '  ```text', '  ok', '  ```'];
+        const text = ['# Spec', '', ...body, '', ...gate].join('\n') + '\n';
+        const spec = parseSpec(text);
+        if (spec.hiddenProblems.length === 0 && !spec.statusProblem) cases.push({ text, spec });
+    }
+    const html = renderAll(cases.map(c => c.text));
+    cases.forEach(({ text, spec }, k) => {
+        accepted++;
+        const r = renderedView(html[k]);
+        const pUnchecked = spec.tasks.filter(t => !t.checked).length;
+        const rUnchecked = r.tasks.filter(c => !c).length;
+        const rStatus = r.statuses.length === 1 ? r.statuses[0] : null;
+        const pStatus = spec.status ? skeleton(spec.status) : null;
+        const pCommand = spec.gate && spec.gate.command ? spec.gate.command.trim() : null;
+        const problems = [];
+        if (rUnchecked > pUnchecked) problems.push('hidden unchecked task');
+        if (r.statuses.length > 1 || (rStatus !== null && rStatus !== pStatus)) problems.push(`status p=${pStatus} r=${r.statuses.join('|')}`);
+        if (pCommand !== null && pCommand !== r.command) problems.push(`command p=${JSON.stringify(pCommand)} r=${JSON.stringify(r.command)}`);
+        if (problems.length) {
+            bad++;
+            if (bad <= 4) console.log('--- BYPASS', problems.join('; '), '\n' + JSON.stringify(text));
+        }
+    });
+}
+console.log(`cases ${N}, accepted ${accepted}, bypasses ${bad}`);
+process.exitCode = bad === 0 ? 0 : 1;

package/scripts/dev/set-npm-publish-token.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+# scripts/dev/set-npm-publish-token.sh
+#
+# One-time setup: stores an npm publish token as the GitHub Actions secret
+# NPM_TOKEN on this repository, so the release workflow can publish to npm
+# without anyone's npm password or token ever appearing in chat, a commit,
+# or this terminal's scrollback.
+#
+# The token is read with hidden input and piped straight to `gh secret set`
+# via stdin; it is never written to disk and never echoed back.
+#
+# Prerequisite: create the token yourself at
+#   https://www.npmjs.com/settings/<your-username>/tokens
+# Choose "Automation" (Classic Token), or a Granular Access Token scoped to
+# read/write on this package — CI has no interactive 2FA prompt, so a token
+# type that skips it is required.
+
+set -eu
+
+REPO="tBeltty/agentic-sdd-framework"
+
+command -v gh >/dev/null 2>&1 || { echo "GitHub CLI (gh) is required. Install it, then run this again." >&2; exit 1; }
+gh auth status >/dev/null 2>&1 || { echo "Run 'gh auth login' first, then run this again." >&2; exit 1; }
+
+echo "This will set the NPM_TOKEN secret on: $REPO"
+printf "npm token (input hidden): "
+stty -echo
+IFS= read -r NPM_TOKEN
+stty echo
+echo
+
+if [ -z "$NPM_TOKEN" ]; then
+    echo "No token entered; nothing was set." >&2
+    exit 1
+fi
+
+printf '%s' "$NPM_TOKEN" | gh secret set NPM_TOKEN --repo "$REPO" --body-file -
+unset NPM_TOKEN
+
+echo "Done: NPM_TOKEN is set on $REPO. The value was not saved anywhere and was not shown."

package/scripts/dev/sync-vendored.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/dev/sync-vendored.js
+ *
+ * Keeps the files vendored from tBeltty/auditor-executor-protocol identical to their
+ * canonical copies: the protocol skill (SKILL.md and references/) and the Rigor
+ * templates used by `auditkit init`. Framework-maintenance only; not installed into
+ * projects.
+ *
+ * Usage:
+ *   node scripts/dev/sync-vendored.js <canonical-checkout>           copy canonical -> framework
+ *   node scripts/dev/sync-vendored.js <canonical-checkout> --check   exit 1 on any difference
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const FRAMEWORK_ROOT = path.resolve(__dirname, '..', '..');
+
+// Checkouts may use CRLF (Windows with core.autocrlf); compare and write LF content.
+const readNormalized = file => fs.readFileSync(file, 'utf8').replace(/\r\n?/g, '\n');
+const SKILL_DIR = '.agents/skills/auditor-executor-protocol';
+const TEMPLATE_DIR = 'docs/roadmap/templates';
+
+function mappings(canonical) {
+    const pairs = [[path.join(canonical, 'SKILL.md'), path.join(SKILL_DIR, 'SKILL.md')]];
+    for (const name of fs.readdirSync(path.join(canonical, 'references')).filter(f => f.endsWith('.md')).sort()) {
+        pairs.push([path.join(canonical, 'references', name), path.join(SKILL_DIR, 'references', name)]);
+    }
+    for (const name of ['plan-of-record.md', 'execution-guide.md', 'compliance-log.md']) {
+        pairs.push([path.join(canonical, 'src/auditkit/templates', name), path.join(TEMPLATE_DIR, name)]);
+    }
+    return pairs;
+}
+
+// Vendored files that no longer exist upstream.
+function orphans(canonical) {
+    const upstream = new Set(fs.readdirSync(path.join(canonical, 'references')));
+    const local = path.join(FRAMEWORK_ROOT, SKILL_DIR, 'references');
+    return fs.existsSync(local)
+        ? fs.readdirSync(local).filter(f => !upstream.has(f)).map(f => path.join(SKILL_DIR, 'references', f))
+        : [];
+}
+
+function main() {
+    const usage = 'Usage: node scripts/dev/sync-vendored.js <canonical-checkout> [--check]';
+    const args = process.argv.slice(2);
+    const flags = args.filter(a => a.startsWith('-'));
+    const positional = args.filter(a => !a.startsWith('-'));
+    // A mistyped flag must not turn a check into a write.
+    const unknown = flags.filter(f => f !== '--check');
+    if (unknown.length > 0 || positional.length !== 1) {
+        console.error(unknown.length > 0 ? `Unknown argument "${unknown[0]}". ${usage}` : usage);
+        process.exit(2);
+    }
+    const canonical = path.resolve(positional[0]);
+    if (!fs.existsSync(path.join(canonical, 'SKILL.md'))) {
+        console.error(`${canonical} is not a checkout of the protocol repository (no SKILL.md). ${usage}`);
+        process.exit(2);
+    }
+    const check = flags.includes('--check');
+    const drift = [];
+
+    for (const [src, rel] of mappings(canonical)) {
+        const dest = path.join(FRAMEWORK_ROOT, rel);
+        const upstream = readNormalized(src);
+        const same = fs.existsSync(dest) && readNormalized(dest) === upstream;
+        if (same) continue;
+        drift.push(rel.split(path.sep).join('/'));
+        if (!check) {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.writeFileSync(dest, upstream);
+        }
+    }
+    for (const rel of orphans(canonical)) {
+        drift.push(`${rel.split(path.sep).join('/')} (removed upstream)`);
+        if (!check) fs.rmSync(path.join(FRAMEWORK_ROOT, rel));
+    }
+
+    if (drift.length === 0) {
+        console.log('✅ Vendored protocol files match the canonical repository.');
+        return;
+    }
+    const verb = check ? 'differ from' : 'updated from';
+    console.log(`${check ? '❌' : '🔄'} ${drift.length} vendored file(s) ${verb} the canonical repository:`);
+    for (const rel of drift) console.log(`  - ${rel}`);
+    if (check) {
+        console.log('\nRun: node scripts/dev/sync-vendored.js <canonical-checkout>');
+        process.exit(1);
+    }
+}
+
+main();