agentic-sdd-framework 1.4.0

package/scripts/sdd-init.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/sdd-init.js
+ *
+ * Day-0 Bootstrapping Wizard for the Agentic SDD Framework.
+ * Pure Node.js standard library implementation (zero npm dependencies).
+ *
+ * Usage:
+ *   node scripts/sdd-init.js                      Guided mode (interactive)
+ *   node scripts/sdd-init.js --express [flags]    Non-interactive mode
+ *   npx github:tBeltty/agentic-sdd-framework      Install into the current directory
+ *
+ * Flags (`--flag=value` or `--flag value`; unknown flags are an error):
+ *   --target=<dir>        Project to provision (default: current directory)
+ *   --name=<name>         Project name (default: target directory name)
+ *   --runtime=<runtime>   e.g. node-24-lts, go-1.23, python-3.12
+ *   --mode=lite|rigor     Specification depth (default: lite)
+ *   --ast=<adapter>       ast-grep | graphify | ripgrep | lsp (default: ast-grep)
+ *   --concurrency=, --hardware=, --workload=   Discovery answers
+ *   --i18n, --pwa         Enable the matching capability flags
+ *   --force               Refresh copied skills and templates in install mode
+ *   --help                Print this help
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execFileSync, spawnSync } = require('child_process');
+const { FRAMEWORK_ROOT, provision } = require('./lib/provision');
+const { loadConfig, getIn } = require('./lib/config');
+
+const VALUE_FLAGS = ['target', 'name', 'runtime', 'mode', 'ast', 'concurrency', 'hardware', 'workload'];
+const BOOLEAN_FLAGS = ['express', 'i18n', 'pwa', 'force', 'help'];
+const USAGE = `Usage: sdd-init [--express] [--target=<dir>] [--name=<name>] [--runtime=<id>]
+                [--mode=lite|rigor] [--ast=ast-grep|graphify|ripgrep|lsp]
+                [--concurrency=<text>] [--hardware=<text>] [--workload=<text>]
+                [--i18n] [--pwa] [--force] [--help]`;
+
+function parseArgs(argv) {
+    const values = new Map();
+    const flags = new Set();
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const match = arg.match(/^--([a-z0-9-]+)(?:=(.*))?$/);
+        if (!match) throw new Error(`Unexpected argument "${arg}".`);
+        const [, name, inline] = match;
+        if (VALUE_FLAGS.includes(name)) {
+            const value = inline !== undefined ? inline : argv[++i];
+            if (value === undefined || (inline === undefined && value.startsWith('--'))) {
+                throw new Error(`--${name} needs a value.`);
+            }
+            values.set(name, value);
+        } else if (BOOLEAN_FLAGS.includes(name) && inline === undefined) {
+            flags.add(name);
+        } else {
+            throw new Error(`Unknown flag "${arg}".`);
+        }
+    }
+    return { values, flags };
+}
+
+let parsed;
+try {
+    parsed = parseArgs(process.argv.slice(2));
+} catch (error) {
+    console.error(`❌ ${error.message}\n${USAGE}`);
+    process.exit(2);
+}
+if (parsed.flags.has('help')) {
+    console.log(USAGE);
+    process.exit(0);
+}
+
+function getArgValue(name, defaultValue) {
+    return parsed.values.has(name) ? parsed.values.get(name) : defaultValue;
+}
+
+const target = path.resolve(getArgValue('target', process.cwd()));
+const force = parsed.flags.has('force');
+const wantsExpress = parsed.flags.has('express') || ['mode', 'ast', 'name', 'runtime'].some(f => parsed.values.has(f));
+
+// A previous run's sdd.config.json seeds the wizard's defaults, so re-running sdd-init
+// (e.g. to pick up a new template version) doesn't reset answers the project already made.
+// The framework's own repository is exempt: its config describes the framework, not a template.
+function loadExistingDefaults() {
+    let config;
+    try {
+        config = loadConfig(target);
+    } catch {
+        return {};
+    }
+    if (getIn(config, 'project.type', 'application') === 'framework') return {};
+    return {
+        projectName: getIn(config, 'project.name'),
+        runtime: getIn(config, 'project.runtime'),
+        specMode: getIn(config, 'specification.mode'),
+        astAdapter: getIn(config, 'capabilities.astNavigation.adapter'),
+        concurrency: getIn(config, 'discovery.concurrency'),
+        hardware: getIn(config, 'discovery.hardware'),
+        workload: getIn(config, 'discovery.workload'),
+        i18n: getIn(config, 'capabilities.i18n.enabled'),
+        pwa: getIn(config, 'capabilities.pwa.enabled')
+    };
+}
+
+const EXISTING = loadExistingDefaults();
+
+const DEFAULTS = {
+    runtime: EXISTING.runtime || 'node-24-lts',
+    concurrency: EXISTING.concurrency || '1-10 internal',
+    hardware: EXISTING.hardware || '$5 VPS',
+    workload: EXISTING.workload || 'I/O-heavy API'
+};
+
+function printHeader() {
+    console.log('\n===============================================================');
+    console.log('  🧙 Agentic SDD Framework: Day-0 Wizard');
+    console.log('  Spec-Driven Development with Autonomous AI Agents');
+    console.log('===============================================================\n');
+}
+
+async function runGuidedMode() {
+    printHeader();
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (query, defaultVal) => new Promise(resolve => {
+        rl.question(defaultVal ? `${query} [${defaultVal}]: ` : `${query}: `, answer => {
+            resolve(answer.trim() || defaultVal);
+        });
+    });
+    const askYesNo = async (query, defaultYes) =>
+        (await ask(`${query} (${defaultYes ? 'Y/n' : 'y/N'})`, defaultYes ? 'y' : 'n')).toLowerCase().startsWith('y');
+
+    const exists = fs.existsSync(target);
+    const installMode = !exists || fs.realpathSync(target) !== fs.realpathSync(FRAMEWORK_ROOT);
+    const question = exists ? `Install SDD governance into ${target}?` : `${target} does not exist. Create it and install SDD governance?`;
+    if (installMode && !(await askYesNo(question, true))) {
+        rl.close();
+        console.log('Aborted. Pass --target=<dir> to choose another project.');
+        return;
+    }
+    fs.mkdirSync(target, { recursive: true });
+
+    console.log('--- Step 1: System Prerequisites Check ---');
+    try {
+        execFileSync(process.execPath, [path.join(__dirname, 'check-system-prerequisites.js')], { stdio: 'inherit', cwd: target });
+    } catch {
+        console.log('\n⚠️  Prerequisites warning detected. Continuing with configuration...\n');
+    }
+
+    console.log('\n--- Step 2: Project Definition ---');
+    const projectName = await ask('Project Name', EXISTING.projectName || path.basename(target));
+    const runtime = await ask('Primary Runtime / Stack (e.g. node-24-lts, go-1.23, python-3.12)', DEFAULTS.runtime);
+
+    console.log('\n--- Step 3: 4-Pillar Discovery Interview (recorded in ADR-0001) ---');
+    const concurrency = await ask('1. Expected peak concurrency (e.g. 1-10 internal, 100-1,000, 50k+ public)', DEFAULTS.concurrency);
+    const hardware = await ask('2. Target deployment environment (e.g. local machine, $5 VPS, serverless, cloud)', DEFAULTS.hardware);
+    const workload = await ask('3. Primary compute workload (e.g. I/O-heavy API, static SPA, live transcoding)', DEFAULTS.workload);
+    const i18n = await askYesNo('4a. Multi-language support (i18n) required?', EXISTING.i18n === true);
+    const pwa = await askYesNo('4b. Offline / Progressive Web App support required?', EXISTING.pwa === true);
+
+    console.log('\n--- Step 4: Specification Depth ---');
+    console.log('  [1] 🟢 Lite Mode (Default): Single file docs/SPEC.md (Specify + Plan + Tasks + Gate).');
+    console.log('      Recommended for solo developers and rapid MVP building.');
+    console.log('  [2] 🔴 Rigor Mode: Plan of Record + Execution Guide + Compliance Log (+ Remediation annexes).');
+    console.log('      Recommended for multi-agent teams and mission-critical systems.');
+    const specMode = (await ask('Select Mode (1 or 2)', EXISTING.specMode === 'rigor' ? '2' : '1')) === '2' ? 'rigor' : 'lite';
+
+    console.log('\n--- Step 5: AST Navigation Adapter ---');
+    console.log('  [1] ast-grep (Fast native Tree-sitter structural search, zero Python)');
+    console.log('  [2] graphify (Relational knowledge graph, maximum token reduction)');
+    console.log('  [3] ripgrep (Universal fast regex baseline)');
+    console.log('  [4] lsp (Language Server Protocol / SCIP compiler type indexing)');
+    const astAdapters = { '1': 'ast-grep', '2': 'graphify', '3': 'ripgrep', '4': 'lsp' };
+    const astDefault = Object.keys(astAdapters).find(key => astAdapters[key] === EXISTING.astAdapter) || '1';
+    const astAdapter = astAdapters[await ask('Select AST Adapter (1-4)', astDefault)] || 'ast-grep';
+
+    rl.close();
+    bootstrap({ projectName, runtime, specMode, astAdapter, concurrency, hardware, workload, i18n, pwa });
+}
+
+function runExpressMode() {
+    printHeader();
+    console.log(`⚡ Express Mode: provisioning ${target}\n`);
+    bootstrap({
+        projectName: getArgValue('name', EXISTING.projectName || path.basename(target)),
+        runtime: getArgValue('runtime', DEFAULTS.runtime),
+        specMode: getArgValue('mode', EXISTING.specMode || 'lite').toLowerCase(),
+        astAdapter: getArgValue('ast', EXISTING.astAdapter || 'ast-grep').toLowerCase(),
+        concurrency: getArgValue('concurrency', DEFAULTS.concurrency),
+        hardware: getArgValue('hardware', DEFAULTS.hardware),
+        workload: getArgValue('workload', DEFAULTS.workload),
+        i18n: parsed.flags.has('i18n') ? true : EXISTING.i18n === true,
+        pwa: parsed.flags.has('pwa') ? true : EXISTING.pwa === true
+    });
+}
+
+function bootstrap(answers) {
+    console.log('\n===============================================================');
+    console.log('  📦 Provisioning SDD Governance Structure...');
+    console.log('===============================================================\n');
+
+    let result;
+    try {
+        result = provision(answers, { target, force });
+    } catch (error) {
+        console.error(`\n❌ ${error.message}\n`);
+        process.exit(1);
+    }
+
+    console.log('\n🎉 Bootstrapping complete!\n');
+    console.log('Next steps:');
+    if (result.skippedEntrypoints.length === 0) {
+        console.log('  1. Commit the generated files. AGENTS.md, CLAUDE.md and .claude/skills/ load the');
+        console.log('     rules automatically in Claude Code, Codex, Cursor and other AGENTS.md-aware agents.');
+    } else {
+        console.log(`  1. Commit the generated files. ${result.skippedEntrypoints.join(' and ')} already existed and`);
+        console.log('     were left untouched, so agents will not load the rules until you add to them:');
+        console.log('     "Before any task, read .agents/AGENTS.md and .agents/CONTEXT.md."');
+    }
+    console.log('  2. Record the incident or rationale behind each rule in .agents/AGENTS.md.');
+    const { specification = {} } = result.config;
+    if (answers.specMode === 'lite') {
+        console.log(`  3. Define your tasks in ${specification.specFile || 'docs/SPEC.md'} and implement with verifiable gates.`);
+    } else {
+        console.log(`  3. Write ${specification.roadmapDir || 'docs/roadmap'}/plan-of-record.md and coordinate with the Auditor-Executor protocol.`);
+        if (spawnSync('auditkit', ['--version']).error) {
+            console.log('     Rigor mode is checked by auditkit, which is not installed. Install it with:');
+            console.log('     pipx install git+https://github.com/tBeltty/auditor-executor-protocol');
+        }
+    }
+    console.log(`  4. Quality gate: ${result.gateCommand}${result.hookInstalled ? ' (runs on every git push)' : ''}\n`);
+}
+
+if (wantsExpress) {
+    runExpressMode();
+} else if (!process.stdin.isTTY) {
+    console.log('ℹ️  No interactive terminal detected; using Express Mode defaults.');
+    runExpressMode();
+} else {
+    runGuidedMode().catch(error => {
+        console.error(`\n❌ ${error.message}\n`);
+        process.exit(1);
+    });
+}

package/scripts/sdd-verify.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/sdd-verify.js
+ *
+ * Runs verification commands for the Lite specification and records the results.
+ *
+ *   node scripts/sdd-verify.js [--record]
+ *       Runs the "Verification Gate" command. Passes when it exits 0, every non-empty
+ *       expected line appears in its output (a /.../ line is a regular expression), and it
+ *       did not modify tracked files. --record writes
+ *       "Last Verified: <date> PASS|FAIL (commit <sha>, exit <code>, state <fingerprint>, check <hash>)"
+ *       into the spec; the gate compares that fingerprint with the committed content.
+ *
+ *   node scripts/sdd-verify.js --task <ID> -- <command ...>
+ *       Runs <command>, writes its transcript as the task's Evidence with the exit code and
+ *       a hash of the transcript, and checks the task's box.
+ *
+ * Commands come from the specification or the command line and run in a shell
+ * (specification.verifyShell, default /bin/sh or cmd.exe) with a time limit
+ * (specification.verifyTimeoutSeconds, default 900). The quality gate never runs them.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { git, repoRoot, WORKTREE } = require('./lib/git');
+const { loadConfig, getIn } = require('./lib/config');
+const { parseSpec, formatLastVerified, withLastVerified, withTaskEvidence } = require('./lib/spec');
+const { stateOf, currentCommit } = require('./lib/state');
+const { DEFAULT_TIMEOUT_SECONDS, runCommand, joinCommand } = require('./lib/runner');
+
+const MAX_EVIDENCE_LINES = 200;
+const USAGE = 'Usage: sdd-verify [--record] | sdd-verify --task <ID> -- <command ...>';
+
+function matchExpected(expected, output) {
+    const missing = [];
+    for (const raw of expected.split('\n')) {
+        const line = raw.trim();
+        if (!line) continue;
+        const regex = line.length > 2 && line.startsWith('/') && line.endsWith('/');
+        const found = regex ? new RegExp(line.slice(1, -1), 'm').test(output) : output.includes(line);
+        if (!found) missing.push(line);
+    }
+    return missing;
+}
+
+function loadLiteSpec(root) {
+    const config = loadConfig(root, WORKTREE);
+    if (getIn(config, 'specification.mode', 'lite') === 'rigor') {
+        throw new Error('sdd-verify covers Lite mode. In Rigor mode, gates are run per task (see the execution guide) and checked with auditkit lint.');
+    }
+    const specFile = getIn(config, 'specification.specFile', 'docs/SPEC.md');
+    const specPath = path.join(root, specFile);
+    if (!fs.existsSync(specPath)) throw new Error(`${specFile} not found.`);
+    const runOptions = {
+        cwd: root,
+        timeoutSeconds: getIn(config, 'specification.verifyTimeoutSeconds', DEFAULT_TIMEOUT_SECONDS),
+        shell: getIn(config, 'specification.verifyShell', undefined)
+    };
+    return { specFile, specPath, text: fs.readFileSync(specPath, 'utf8'), runOptions };
+}
+
+function today(date) {
+    return date || new Date().toISOString().slice(0, 10);
+}
+
+// Untracked files take part in the verification but not in the recorded state fingerprint,
+// so a recorded PASS could depend on files that are never committed.
+function untrackedFiles(root) {
+    return git(['ls-files', '--others', '--exclude-standard', '-z'], root).split('\0').filter(Boolean);
+}
+
+async function verify({ root = repoRoot(), record = false, log = console.log, date } = {}) {
+    const { specFile, specPath, text, runOptions } = loadLiteSpec(root);
+    const { gate, hiddenProblems } = parseSpec(text);
+    if (hiddenProblems.length > 0) throw new Error(`${specFile}: ${hiddenProblems.join(' ')}`);
+    if (!gate) throw new Error(`${specFile} has no "Verification Gate" section.`);
+    if (!gate.command) throw new Error(`${specFile}: the verification command is still a placeholder.`);
+    if (!gate.expected) throw new Error(`${specFile}: the expected output is still a placeholder.`);
+    const untracked = untrackedFiles(root);
+    if (record && untracked.length > 0) {
+        throw new Error(`Untracked files would take part in the verification but not in the recorded state: ${untracked.slice(0, 5).join(', ')}${untracked.length > 5 ? ', ...' : ''}. Commit, ignore, or remove them, then record again.`);
+    }
+    if (untracked.length > 0) log(`⚠️  ${untracked.length} untracked file(s) take part in this run; --record refuses to run until they are committed, ignored, or removed.`);
+
+    const before = stateOf(root, WORKTREE, specFile);
+    log(`$ ${gate.command}\n`);
+    const { exit, output } = await runCommand(gate.command, runOptions);
+    log(output.trimEnd());
+    const after = stateOf(root, WORKTREE, specFile);
+
+    const missing = matchExpected(gate.expected, output);
+    const modified = before !== after;
+    const pass = exit === '0' && missing.length === 0 && !modified;
+
+    log('');
+    if (exit !== '0') log(`❌ Command exited with ${exit}.`);
+    for (const line of missing) log(`❌ Expected output not found: ${line}`);
+    if (modified) log('❌ The command modified tracked files; verify a clean state, then run it again.');
+    if (pass) log('✅ Verification gate passed.');
+
+    if (record) {
+        const fields = { date: today(date), result: pass ? 'PASS' : 'FAIL', commit: currentCommit(root), exit, state: before };
+        const value = formatLastVerified(fields, gate.command, gate.expected);
+        fs.writeFileSync(specPath, withLastVerified(text, value));
+        log(`📝 Recorded in ${specFile}: Last Verified ${value}`);
+    }
+    return { pass, exitCode: exit, missing, modified };
+}
+
+async function recordTask({ root = repoRoot(), taskId, command, log = console.log, date } = {}) {
+    const { specFile, specPath, text, runOptions } = loadLiteSpec(root);
+    const spec = parseSpec(text);
+    if (spec.hiddenProblems.length > 0) throw new Error(`${specFile}: ${spec.hiddenProblems.join(' ')}`);
+    if (!spec.tasks.some(t => t.id === taskId)) {
+        throw new Error(`Task ${taskId} not found in ${specFile}.`);
+    }
+    log(`$ ${command}\n`);
+    const { exit, output } = await runCommand(command, runOptions);
+    log(output.trimEnd());
+
+    let lines = output.replace(/\r\n?/g, '\n').replace(/\s+$/, '').split('\n');
+    if (lines.length > MAX_EVIDENCE_LINES) {
+        const omitted = lines.length - MAX_EVIDENCE_LINES;
+        lines = [...lines.slice(0, MAX_EVIDENCE_LINES / 2), `[... ${omitted} lines omitted ...]`, ...lines.slice(-MAX_EVIDENCE_LINES / 2)];
+    }
+    const transcript = [`$ ${command}`, ...lines].join('\n');
+    fs.writeFileSync(specPath, withTaskEvidence(text, taskId, { date: today(date), exit, transcript }));
+    log(`\n${exit === '0' ? '✅' : '❌'} ${taskId}: exit ${exit}, evidence recorded in ${specFile}.`);
+    return { exitCode: exit };
+}
+
+function parseArgs(argv) {
+    const separator = argv.indexOf('--');
+    const flags = separator === -1 ? argv : argv.slice(0, separator);
+    const command = separator === -1 ? [] : argv.slice(separator + 1);
+    const options = { record: false, taskId: null, command: null };
+    for (let i = 0; i < flags.length; i++) {
+        const flag = flags[i];
+        if (flag === '--record') options.record = true;
+        else if (flag === '--task') options.taskId = flags[++i];
+        else if (flag.startsWith('--task=')) options.taskId = flag.slice('--task='.length);
+        else if (flag === '--help' || flag === '-h') throw new Error(USAGE);
+        else throw new Error(`Unknown argument "${flag}". ${USAGE}`);
+    }
+    if (options.taskId !== null) {
+        if (!options.taskId) throw new Error(`--task needs a task ID. ${USAGE}`);
+        if (command.length === 0) throw new Error(`--task needs a command after "--". ${USAGE}`);
+        if (options.record) throw new Error(`--record and --task are separate modes. ${USAGE}`);
+        options.command = joinCommand(command);
+    } else if (command.length > 0) {
+        throw new Error(`A command after "--" is only used with --task. ${USAGE}`);
+    }
+    return options;
+}
+
+async function main(argv) {
+    try {
+        const options = parseArgs(argv);
+        if (options.taskId) {
+            const { exitCode } = await recordTask({ taskId: options.taskId, command: options.command });
+            return exitCode === '0' ? 0 : 1;
+        }
+        const { pass } = await verify({ record: options.record });
+        return pass ? 0 : 1;
+    } catch (error) {
+        console.error(`❌ ${error.message}`);
+        return 2;
+    }
+}
+
+if (require.main === module) {
+    main(process.argv.slice(2)).then(code => process.exit(code));
+}
+
+module.exports = { matchExpected, parseArgs, verify, recordTask };

package/scripts/verify-no-secrets.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/verify-no-secrets.js
+ *
+ * Credential leak scanner. Reads tracked files from the working tree, the index
+ * (--staged) or a commit (--ref=<sha>) and reports:
+ *   - provider keys and private key blocks (pattern match on content);
+ *   - credentials in URLs and high-entropy values assigned to secret-named keys;
+ *   - tracked files whose name marks them as secret (.env, id_rsa, *.key, *.p12, ...).
+ *
+ * A content match is ignored when the matched value is an obvious placeholder, or when
+ * the line carries the pragma "sdd-allow-secret"; suppressed lines are counted in the
+ * report. A sensitive file name is accepted only when listed in security.allowFiles.
+ */
+
+const path = require('path');
+const { listFiles, readFiles, isBinary, WORKTREE } = require('./lib/git');
+const { loadConfig, getIn } = require('./lib/config');
+const { runCheckCli } = require('./lib/cli');
+
+// Ordered from most to least specific; every match of every pattern on a line is checked,
+// so a placeholder earlier on the line cannot hide a real key later on it.
+const SECRET_PATTERNS = [
+    { name: 'Private Key Block', regex: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/g },
+    { name: 'Anthropic API Key', regex: /\bsk-ant-[0-9A-Za-z_-]{20,}/g },
+    { name: 'OpenAI API Key', regex: /\bsk-(?:proj|svcacct|admin)-[0-9A-Za-z_-]{20,}/g },
+    { name: 'OpenAI Legacy API Key', regex: /\bsk-[0-9A-Za-z]{32,}\b/g },
+    { name: 'Stripe Live Key', regex: /\b[rs]k_live_[0-9A-Za-z]{16,}/g },
+    { name: 'GitHub Token', regex: /\bgh[pousr]_[0-9A-Za-z]{36}\b/g },
+    { name: 'GitHub Fine-Grained Token', regex: /\bgithub_pat_[0-9A-Za-z_]{22,}/g },
+    { name: 'Slack Token', regex: /\bxox[abposr]-[0-9A-Za-z-]{10,}/g },
+    // Requires both a digit and a letter so identifiers like re_compiled_pattern_list pass.
+    { name: 'Resend API Key', regex: /\bre_(?=[A-Za-z_]*\d)(?=[0-9_]*[A-Za-z])[0-9A-Za-z_]{24,}/g },
+    { name: 'AWS Access Key ID', regex: /\b(?:AKIA|ABIA|ACCA|ASIA)[0-9A-Z]{16}\b/g },
+    { name: 'Google API Key', regex: /\bAIza[0-9A-Za-z_-]{35}/g },
+    {
+        name: 'Credentials in URL',
+        regex: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@'"]+:([^\s@/'"]{6,})@/gi,
+        group: 1,
+        accept: value => !isReference(value) && !/^\*+$/.test(value)
+    }
+];
+
+// Keys whose value is a secret: ends in secret, token, password, pwd, credential(s), or an
+// api, private, access, secret, signing, encryption or master key. `max_tokens`,
+// `tokenizer` or `cache_key` do not match.
+const SECRET_KEY_RE = /(?:^|[^A-Za-z0-9_])([A-Za-z0-9_.-]*?(?:secret|token|passw(?:or)?d|pwd|credentials?|(?:api|private|access|secret|signing|encryption|master)[_-]?key))["']?\s*(?::=|[:=])\s*(.*)$/i;
+const PASSWORD_KEY_RE = /passw(?:or)?d|pwd|secret|credential/i;
+// Files where an unquoted value is a literal (KEY=value), not a code expression: env and
+// config files, package manager rc files, shell and batch scripts, and Dockerfiles. PowerShell
+// is not included: its right-hand sides are expressions (Read-Host, Get-Credential, ...).
+const CONFIG_FILE_RE = /(^|\/)(\.env[^/]*|\.npmrc|\.pypirc|\.yarnrc(\.yml)?|Dockerfile[^/]*|Containerfile)$|\.(env|ini|cfg|conf|properties|toml|ya?ml|json|sh|bash|zsh|bat|cmd|tfvars|dockerfile)$/i;
+
+// Shannon entropy in bits per character.
+function entropy(value) {
+    const counts = {};
+    for (const ch of value) counts[ch] = (counts[ch] || 0) + 1;
+    return Object.values(counts).reduce((sum, n) => {
+        const p = n / value.length;
+        return sum - p * Math.log2(p);
+    }, 0);
+}
+
+// $VAR, ${VAR}, %VAR%, {{var}}, <value>, process.env.X, os.environ[...]
+function isReference(value) {
+    return /^\$|\$\{|^%\w+%$|\{\{|<[^>]*>|process\.env|os\.environ|getenv/.test(value);
+}
+
+// Checked against the matched value only; a placeholder elsewhere on the line does not
+// hide a real key.
+const SAFE_PLACEHOLDERS = [
+    'test_secret', 'test-secret', 'your_api_key', 'your-api-key', 'dummy', 'placeholder',
+    'mock_key', 'example', 'xxxxxxxx', 'changeme', 'redacted', 'fake', 'sample'
+];
+const isPlaceholder = value => SAFE_PLACEHOLDERS.some(p => value.toLowerCase().includes(p))
+    || /^(password|secret|token|none|null|undefined|true|false)$/i.test(value);
+
+// The literal assigned to a secret-named key, if any. In code, only quoted values are
+// literals (an unquoted value is an expression such as a call or a variable); in config
+// files, an unquoted value is a literal too.
+function secretAssignment(rawLine, { configFile }) {
+    // Dockerfile legacy form `ENV KEY value` is `ENV KEY=value`.
+    let line = configFile ? rawLine.replace(/^(\s*(?:ENV|ARG)\s+)([A-Za-z_][A-Za-z0-9_]*)\s+(?=\S)/i, '$1$2=') : rawLine;
+    // `set /p NAME=Prompt:` in a batch file reads input; the text is a prompt, not a value.
+    if (configFile && /^\s*set\s+\/p\b/i.test(line)) return null;
+    // `setx [/M] NAME value` (batch) is `NAME=value`.
+    if (configFile) line = line.replace(/^(\s*@?setx(?:\s+\/\w+)*\s+)"?([A-Za-z_][A-Za-z0-9_]*)"?\s+(?=\S)/i, '$1$2=');
+    const match = line.match(SECRET_KEY_RE);
+    if (!match) return null;
+    const [, key, rest] = match;
+    const quoted = rest.match(/^(["'`])((?:\\.|(?!\1).)*)\1/);
+    let value;
+    if (quoted) value = quoted[2];
+    // `#` starts a comment only after whitespace (dotenv, YAML), so it can be part of a value.
+    else if (configFile) value = (rest.match(/^\S+/) || [''])[0].replace(/[,;]$/, '');
+    else return null;
+    if (value.length < 8 || isPlaceholder(value) || isReference(value)) return null;
+    if (/\s/.test(value)) return null; // prose, not a credential
+    // Lockfile dependency specifiers (pnpm/yarn) put peer-dependency ranges in parens, e.g.
+    // "0.4.8(@solana/web3.js@1.95.3(...))"; no credential format uses parens.
+    if (/[()]/.test(value)) return null;
+    // Passwords can be low-entropy words; tokens and keys must look random.
+    if (!PASSWORD_KEY_RE.test(key) && (value.length < 16 || entropy(value) < 3.0)) return null;
+    return { key, value };
+}
+
+const ALLOW_PRAGMA = 'sdd-allow-secret';
+
+// Skipped: this scanner at the paths the framework installs it (its patterns would match
+// themselves) and dependency directories as whole path segments. Lockfiles are scanned:
+// a private-registry URL in them can embed a token.
+const SKIPPED_PATHS = ['scripts/verify-no-secrets.js', '.sdd/scripts/verify-no-secrets.js'];
+const isSkipped = file => SKIPPED_PATHS.includes(file) || /(^|\/)node_modules\//.test(file);
+
+const SENSITIVE_FILES = [
+    {
+        name: 'Environment file',
+        test: base => /^\.env(\..+)?$/.test(base) && !/^\.env\.(example|sample|template|dist|defaults)$/.test(base)
+    },
+    { name: 'SSH private key', test: base => /^id_(rsa|dsa|ecdsa|ed25519)$/.test(base) },
+    { name: 'Key or keystore file', test: base => /\.(key|p12|pfx|jks|keystore|ppk|kdbx)$/i.test(base) }
+];
+
+function maskMatch(str) {
+    if (str.length <= 8) return '****';
+    return str.slice(0, 4) + '...' + str.slice(-4);
+}
+
+function findInLine(line, options) {
+    for (const pattern of SECRET_PATTERNS) {
+        for (const match of line.matchAll(pattern.regex)) {
+            const value = pattern.group ? match[pattern.group] : match[0];
+            if (isPlaceholder(value)) continue;
+            if (pattern.accept && !pattern.accept(value)) continue;
+            return { patternName: pattern.name, value };
+        }
+    }
+    const assignment = secretAssignment(line, options);
+    return assignment ? { patternName: 'Secret Assignment', value: assignment.value } : null;
+}
+
+// `file` (a repository path) decides whether unquoted values count as literals.
+function scanContent(content, { file = '' } = {}) {
+    const options = { configFile: CONFIG_FILE_RE.test(file) };
+    const violations = [];
+    let suppressed = 0;
+    content.split(/\r?\n/).forEach((line, index) => {
+        const hit = findInLine(line, options);
+        if (!hit) return;
+        if (line.includes(ALLOW_PRAGMA)) {
+            suppressed++;
+            return;
+        }
+        violations.push({ line: index + 1, patternName: hit.patternName, snippet: maskMatch(hit.value) });
+    });
+    return { violations, suppressed };
+}
+
+// Text to scan from a file's bytes. UTF-16 files are decoded; other binary files are
+// reduced to their printable runs (like `strings`), so a NUL byte cannot hide a secret.
+function textOf(buffer) {
+    if (buffer[0] === 0xff && buffer[1] === 0xfe) return buffer.subarray(2).toString('utf16le');
+    if (buffer[0] === 0xfe && buffer[1] === 0xff) return Buffer.from(buffer.subarray(2)).swap16().toString('utf16le');
+    if (!isBinary(buffer)) return buffer.toString('utf8');
+    return (buffer.toString('latin1').match(/[\x20-\x7e]{8,}/g) || []).join('\n');
+}
+
+function sensitiveFileName(file) {
+    const rule = SENSITIVE_FILES.find(r => r.test(path.posix.basename(file)));
+    return rule ? rule.name : null;
+}
+
+// `files` restricts the scan (the pre-push hook passes the files each new commit changed).
+function run({ root, source = WORKTREE, files: only = null } = {}) {
+    const config = loadConfig(root, source);
+    const allowFiles = new Set(getIn(config, 'security.allowFiles', []));
+    const files = (only || listFiles(root, source)).filter(f =>
+        !isSkipped(f));
+
+    const violations = [];
+    let suppressed = 0;
+    for (const file of files) {
+        const fileRule = sensitiveFileName(file);
+        if (fileRule && !allowFiles.has(file)) {
+            violations.push({ file, line: 0, patternName: `Tracked ${fileRule}`, snippet: 'file should not be in git' });
+        }
+    }
+    for (const [file, buffer] of readFiles(root, files, source)) {
+        if (!buffer) continue;
+        const result = scanContent(textOf(buffer), { file });
+        suppressed += result.suppressed;
+        for (const v of result.violations) violations.push({ file, ...v });
+    }
+
+    const suppressedNote = suppressed > 0 ? ` ${suppressed} line(s) suppressed with "${ALLOW_PRAGMA}".` : '';
+    if (violations.length === 0) {
+        return { ok: true, report: `✅ Scanned ${files.length} files. Zero unmasked secrets found.${suppressedNote}` };
+    }
+    const lines = ['❌ CRITICAL ERROR: Potential secrets detected in codebase!\n'];
+    for (const v of violations) {
+        lines.push(`  - File: ${v.file}${v.line ? `:${v.line}` : ''}`);
+        lines.push(`    Pattern: ${v.patternName}`);
+        lines.push(`    Detected: ${v.snippet}\n`);
+    }
+    lines.push('Action Required: Move secrets to Tier 3 Vault (~/secrets/<app>/.vault) or environment variables, and remove secret files from git.');
+    lines.push(`False positive? Add the comment "${ALLOW_PRAGMA}" to that line, or list the file in security.allowFiles.`);
+    if (suppressedNote) lines.push(suppressedNote.trim());
+    return { ok: false, report: lines.join('\n') };
+}
+
+if (require.main === module) {
+    runCheckCli('🔒 Agentic SDD Framework: Secret Leak Scanner', run);
+}
+
+module.exports = { SECRET_PATTERNS, entropy, secretAssignment, scanContent, sensitiveFileName, textOf, run };

package/sdd.config.json

@@ -0,0 +1,33 @@
+{
+  "version": "1.4.0",
+  "project": {
+    "name": "agentic-sdd-framework",
+    "type": "framework",
+    "runtime": "node-24-lts"
+  },
+  "specification": {
+    "mode": "lite",
+    "allowedModes": [
+      "lite",
+      "rigor"
+    ]
+  },
+  "architecture": {
+    "style": "clean-architecture",
+    "maxLocPerFile": 400
+  },
+  "capabilities": {
+    "astNavigation": {
+      "adapter": "ast-grep"
+    },
+    "noAiSlop": {
+      "enabled": true
+    },
+    "i18n": {
+      "enabled": false
+    },
+    "pwa": {
+      "enabled": false
+    }
+  }
+}