agentic-sdd-framework 1.4.0

package/docs/guides/GITHUB_CLI_SETUP.md

@@ -0,0 +1,74 @@
+# 🐙 GitHub CLI Setup & Zero-Trust Provisioning Guide
+
+This guide establishes the standard Day-0 provisioning procedure for repositories built with the **Agentic SDD Framework**.
+
+---
+
+## 1. Why GitHub CLI (`gh`) over the Web UI?
+
+Using the command-line interface (`gh`) instead of clicking through github.com provides three fundamental engineering advantages:
+
+1. **Deterministic & Scriptable:** Ensures every repository is provisioned with identical security flags (private by default, clean `.gitignore`, standard branch).
+2. **Eliminates URL Credential Leaks:** Cloning through `gh` uses authenticated keychain tokens or SSH agent keys, preventing hardcoded credentials in `.git/config` remote URLs.
+3. **Automated Branch Governance:** Enables setting up branch protection rules and CI/CD secret environments directly from terminal scripts.
+
+---
+
+## 2. Authentication & Least-Privilege Scopes
+
+Before running provisioning commands, verify your local authentication state:
+
+```bash
+gh auth status
+```
+
+### 🔒 Security Risk: Over-Privileged Personal Access Tokens (PAT)
+When running `gh auth login`:
+* **Recommended Protocol:** Choose `SSH` or `HTTPS` with web-browser verification.
+* **Minimum Scopes Required:** `'repo'`, `'read:org'`, `'workflow'`.
+* **FORBIDDEN:** Never grant `'admin:org'` or full account administration scopes to everyday CLI development machines.
+
+---
+
+## 3. Provisioning a New SDD Repository
+
+To create and clone a clean, private repository from scratch:
+
+```bash
+# 1. Create remote private repo and clone to local disk
+gh repo create <project-name> --private --description "Spec-Driven Development Project" --clone
+
+# 2. Navigate into the project
+cd <project-name>
+```
+
+---
+
+## 4. Branch Protection Rules (The First Defense)
+
+Autonomous AI agents must **never** be permitted to execute blind force-pushes (`git push --force`) to your production branch.
+
+### Setting up Branch Protection via CLI:
+Protect the `main` (or `master`) branch by requiring pull requests and status checks:
+
+```bash
+# Verify the default branch name
+git branch -M main
+
+# Enforce branch protection (requires GitHub Pro/Team for private repos or public repo)
+gh api \
+  --method PUT \
+  "repos/:owner/:repo/branches/main/protection" \
+  -f required_status_checks='{"strict":true,"contexts":["quality-gate"]}' \
+  -f enforce_admins=true \
+  -f required_pull_request_reviews=null \
+  -f restrictions=null
+```
+
+---
+
+## 5. Security Checklist Before First Commit
+
+- [ ] Repository is set to **Private** (unless explicitly intended as open-source).
+- [ ] `.gitignore` contains rules for `.env`, `.vault`, `scratch/`, and private keys.
+- [ ] No personal access tokens or credentials are typed into terminal arguments that persist in shell history (`~/.zsh_history` or `~/.bash_history`).

package/docs/incidents/0000-00-00-incident-template.md

@@ -0,0 +1,35 @@
+# Incident Post-Mortem: [YYYY-MM-DD] [Incident Title]
+
+**Date:** [YYYY-MM-DD]  
+**Author / Investigator:** [Name]  
+**Severity:** P1 (Critical) | P2 (Major) | P3 (Minor)  
+**Status:** Resolved  
+
+---
+
+## 1. Summary and Impact
+Briefly describe what failed, which services were affected, and how the issue was detected (e.g. automated alert, customer report, test suite).
+
+---
+
+## 2. Timeline
+* **[Time UTC]:** Initial symptom observed.
+* **[Time UTC]:** Investigation started; root cause identified.
+* **[Time UTC]:** Remediation deployed.
+* **[Time UTC]:** Verification completed; service restored.
+
+---
+
+## 3. Root Cause Analysis
+Explain the underlying mechanical, configuration, or architectural failure without speculation. State what code path or environment variable triggered the failure.
+
+---
+
+## 4. Remediation and Verification
+* **Fix Applied:** [Link to commit or description of change]
+* **Verification Command:** [Terminal command used to reproduce and verify the fix]
+
+---
+
+## 5. Inviolable Rule Created
+Document the permanent rule added to `.agents/AGENTS.md` to ensure AI agents and engineers cannot repeat this error.

package/docs/roadmap/templates/compliance-log.md

@@ -0,0 +1,37 @@
+# {{PROJECT_NAME}} — Compliance Log
+
+> **Evidence of record.** One report and one verdict per task/gate ID. Pre-generate an
+> empty row per ID from the execution guide so nothing gets skipped silently.
+>
+> Maintained by the Auditor after every verdict. Compact repeated open conditions
+> periodically instead of only appending — see the protocol's note on log maintenance.
+
+---
+
+## Status board
+
+| ID | Delivery | Verdict | Notes |
+|---|---|---|---|
+| P0-T1 | | `PENDING` | |
+| P0-G1 | | `PENDING` | |
+
+---
+
+## Open conditions
+
+None yet.
+
+---
+
+## Reports
+
+### P0-T1 — PENDING
+**Changed:**
+**Verify output:**
+**Observations:**
+**Decisions made without stopping:**
+
+### P0-G1 — PENDING
+**Verify output:**
+**Observations:**
+

package/docs/roadmap/templates/execution-guide.md

@@ -0,0 +1,75 @@
+# {{PROJECT_NAME}} — Execution Guide
+
+> **You are the Executor.** The Auditor wrote this file and will re-run every gate
+> independently. Read `plan-of-record.md` once for context, then work only from here.
+> Report every task in `compliance-log.md`.
+
+---
+
+## Rules of engagement
+
+1. **One task at a time, in order.** No batching. Do not start a phase whose
+   predecessor is not marked `APPROVED` in the compliance log.
+2. **Never invent a value the codebase declares.** Read it. Needing to ask for one
+   means a file was skipped.
+3. **Never guess a cause. Observe it.** Read the log, run the query, print the value.
+4. **Verification is running the thing, not reading the code.** "I reviewed it and it
+   looks correct" is reported as `FAILED`.
+5. **Scope is the task text.** Unrelated problems go in *Observations*. Do not fix
+   them.
+6. **Stop and ask** when this document contradicts the code, when a task needs a
+   decision this document does not make, or when a previously passing check starts
+   failing for reasons unrelated to your change. If you resolve an ambiguity without
+   stopping, log the decision. A decision in the plan of record is settled; a factual
+   claim never is — if this document states something the code contradicts, the
+   evidence outranks the order.
+7. **When the system cannot do what a task asks, that is the deliverable.** Report it
+   and stop. A task that ends in a well-argued finding is a success.
+8. Project-specific rules that apply to every task — list them here, cited from their
+   source rather than restated:
+   -
+   -
+
+## Reporting format
+
+For each task, append to `compliance-log.md`:
+
+```
+### <TASK-ID> — DONE | BLOCKED | FAILED
+**Changed:** <paths>
+**Verify output:**
+<pasted, literal, unedited command output>
+**Observations:** <or "none">
+**Decisions made without stopping:** <or "none">
+```
+
+A `DONE` with no pasted output is recorded as `FAILED`.
+
+---
+
+# Phase 0 — <name>
+
+### P0-T1 — <imperative, one line>
+
+**Goal:**
+**Files:**
+**Steps:**
+1.
+
+**Expected failure to avoid:**
+
+**Verify:**
+```bash
+```
+
+**Report:** `P0-T1`
+
+---
+
+### P0-G1 — Gate: <claim under test>
+
+**Proven by:** <the check that proves the claim>
+
+**Negative control:** <how you remove the protection, which check fails, and that it passes again once restored>
+
+**Report:** `P0-G1`

package/docs/roadmap/templates/plan-of-record.md

@@ -0,0 +1,49 @@
+# {{PROJECT_NAME}} — Plan of Record
+
+> **Status:** draft. This document holds the *what* and the *why*. Nobody implements
+> from this file. The executable instructions live in `execution-guide.md`; evidence
+> goes in `compliance-log.md`.
+
+**Target version / milestone:**
+
+---
+
+## 1. Why this exists
+
+What problem is this solving, and why now. If several requests trace back to one
+underlying gap, name the gap here rather than listing the requests as unrelated.
+
+## 2. What the audit of the current system found
+
+| Finding | Evidence |
+|---|---|
+| | |
+
+State each finding with the command or artifact that established it, not from memory.
+
+## 3. The decisions (settled — reopening one is a stop, not a choice)
+
+### D1 — <decision name>
+
+What was decided, what alternative was rejected and why, what failure this prevents.
+
+## 4. What this deliberately does not do
+
+Scope boundaries the Auditor is holding, so an Executor (or a future Auditor) doesn't
+drift into rebuilding something that was cut on purpose.
+
+## 5. Phases
+
+| Phase | Delivers | Risk |
+|---|---|---|
+| | | |
+
+## 6. Request traceability
+
+| Origin request | Where it lands |
+|---|---|
+| | |
+
+## 7. Standards this work is held to
+
+Cite the project's own conventions rather than restating them here.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "agentic-sdd-framework",
+  "version": "1.4.0",
+  "description": "Spec-Driven Development governance for AI coding agents: auto-loaded agent rules, specifications with recorded evidence, and a pre-push quality gate",
+  "bin": {
+    "sdd-init": "scripts/sdd-init.js"
+  },
+  "files": [
+    "scripts/",
+    ".agents/",
+    "docs/",
+    "sdd.config.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "init": "node scripts/sdd-init.js",
+    "verify": "node scripts/sdd-verify.js",
+    "check:prereqs": "node scripts/check-system-prerequisites.js",
+    "check:secrets": "node scripts/verify-no-secrets.js",
+    "check:slop": "node scripts/check-copy-slop.js",
+    "check:size": "node scripts/check-file-size.js",
+    "check:spec": "node scripts/check-spec.js",
+    "check:versions": "node scripts/check-versions.js",
+    "install-hooks": "node scripts/install-git-hooks.js",
+    "quality-gate": "node scripts/quality-gate.js"
+  },
+  "keywords": [
+    "sdd",
+    "spec-driven-development",
+    "ai-agents",
+    "claude-code",
+    "antigravity",
+    "cursor",
+    "governance",
+    "auditor-executor"
+  ],
+  "author": "tBeltty",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tBeltty/agentic-sdd-framework.git"
+  }
+}

package/scripts/check-copy-slop.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/check-copy-slop.js
+ *
+ * Linter for AI-generated writing cliches, buzzwords, and banned patterns in prose
+ * (.md, .mdx, .txt). Code blocks, inline code and table rows are not checked.
+ * Inspired by https://github.com/petergyang/no-ai-slop (MIT License).
+ *
+ * Config (sdd.config.json -> capabilities.noAiSlop):
+ *   enabled      false skips the check (default true)
+ *   exclude      path prefixes to skip
+ *   maxEmDashes  em dashes allowed per file, counted individually (default 1)
+ */
+
+const { listFiles, readFiles, isBinary, WORKTREE } = require('./lib/git');
+const { loadConfig, getIn } = require('./lib/config');
+const { runCheckCli } = require('./lib/cli');
+const { normalizeEol, createFenceTracker } = require('./lib/markdown');
+const { BANNED_PATTERNS } = require('./lib/slop-patterns');
+
+const PROSE_EXTENSIONS = ['.md', '.mdx', '.txt'];
+
+// The skill that defines the banned patterns must quote them; vendored skills and the
+// Rigor templates are synced from their upstream repositories and linted there. Rigor
+// documents (specification.roadmapDir) are records in the protocol's format and hold
+// pasted command output.
+// sdd-init copies the skills into .claude/skills/ where symlinks are unavailable (Windows
+// without Developer Mode), so those copies are excluded too.
+const DEFAULT_EXCLUDE = [
+    '.agents/skills/no-ai-slop/',
+    '.agents/skills/auditor-executor-protocol/',
+    '.claude/skills/no-ai-slop/',
+    '.claude/skills/auditor-executor-protocol/',
+    'docs/roadmap/templates/'
+];
+
+function lintContent(content, { maxEmDashes = 1 } = {}) {
+    const violations = [];
+    const emDashLines = [];
+    let emDashes = 0;
+    const fence = createFenceTracker();
+
+    normalizeEol(content).split('\n').forEach((rawLine, index) => {
+        const trimmed = rawLine.trim();
+        if (fence.update(rawLine) || fence.inside) return;
+        if (trimmed.startsWith('|') || /^-{3,}$/.test(trimmed)) return;
+
+        const line = rawLine.replace(/`[^`]*`/g, '``');
+        const dashes = (line.match(/—/g) || []).length;
+        if (dashes > 0) {
+            emDashes += dashes;
+            emDashLines.push(index + 1);
+        }
+
+        for (const pattern of BANNED_PATTERNS) {
+            const match = line.match(pattern.regex);
+            if (match) {
+                violations.push({
+                    line: index + 1,
+                    pattern: pattern.name,
+                    matchedText: match[0].trim(),
+                    lineText: trimmed.slice(0, 100)
+                });
+                break;
+            }
+        }
+    });
+
+    if (emDashes > maxEmDashes) {
+        violations.push({
+            line: emDashLines[0],
+            pattern: `Em Dash Overuse (${emDashes} found, max ${maxEmDashes} per file)`,
+            matchedText: '—',
+            lineText: `lines ${emDashLines.join(', ')}`
+        });
+    }
+    return violations;
+}
+
+function run({ root, source = WORKTREE } = {}) {
+    const config = loadConfig(root, source);
+    if (getIn(config, 'capabilities.noAiSlop.enabled', true) === false) {
+        return { ok: true, report: '⏭️  No-AI-Slop linter disabled in sdd.config.json.' };
+    }
+    const roadmapDir = `${getIn(config, 'specification.roadmapDir', 'docs/roadmap').replace(/\/+$/, '')}/`;
+    const exclude = [...DEFAULT_EXCLUDE, roadmapDir, ...getIn(config, 'capabilities.noAiSlop.exclude', [])];
+    const maxEmDashes = getIn(config, 'capabilities.noAiSlop.maxEmDashes', 1);
+
+    const files = listFiles(root, source)
+        .filter(f => PROSE_EXTENSIONS.some(ext => f.endsWith(ext)))
+        .filter(f => !exclude.some(prefix => f.startsWith(prefix)));
+
+    const violations = [];
+    for (const [file, buffer] of readFiles(root, files, source)) {
+        if (!buffer || isBinary(buffer)) continue;
+        for (const v of lintContent(buffer.toString('utf8'), { maxEmDashes })) {
+            violations.push({ file, ...v });
+        }
+    }
+
+    if (violations.length === 0) {
+        return { ok: true, report: `✅ Scanned ${files.length} file(s). Zero AI slop patterns detected.` };
+    }
+    const lines = [`❌ Found ${violations.length} AI writing pattern violation(s):\n`];
+    for (const v of violations) {
+        lines.push(`  - File: ${v.file}:${v.line}`);
+        lines.push(`    Pattern: ${v.pattern}`);
+        lines.push(`    Matched: "${v.matchedText}"`);
+        lines.push(`    Context: ${v.lineText}\n`);
+    }
+    lines.push('Action: Rewrite directly without empty filler or binary contrasts.');
+    return { ok: false, report: lines.join('\n') };
+}
+
+if (require.main === module) {
+    runCheckCli('✍️  Agentic SDD Framework: No-AI-Slop Copy Linter', run);
+}
+
+module.exports = { lintContent, run };

package/scripts/check-file-size.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/check-file-size.js
+ *
+ * Enforces architecture.maxLocPerFile from sdd.config.json on tracked source files.
+ * Documentation, data and lockfiles are not counted.
+ *
+ * Config (sdd.config.json -> architecture):
+ *   maxLocPerFile   line limit per source file (default 400; 0 disables the check)
+ *   maxLocExclude   path prefixes to skip (for example generated code)
+ */
+
+const path = require('path');
+const { listFiles, readFiles, isBinary, WORKTREE } = require('./lib/git');
+const { loadConfig, getIn } = require('./lib/config');
+const { runCheckCli } = require('./lib/cli');
+
+const SOURCE_EXTENSIONS = new Set([
+    '.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx', '.vue', '.svelte',
+    '.py', '.go', '.rs', '.java', '.kt', '.kts', '.scala', '.rb', '.php', '.cs',
+    '.c', '.h', '.cc', '.cpp', '.hpp', '.m', '.swift', '.dart', '.ex', '.exs',
+    '.sh', '.bash', '.zsh', '.lua', '.sql'
+]);
+
+function countLines(text) {
+    if (text.length === 0) return 0;
+    const normalized = text.replace(/\r\n?/g, '\n');
+    return normalized.split('\n').length - (normalized.endsWith('\n') ? 1 : 0);
+}
+
+function run({ root, source = WORKTREE } = {}) {
+    const config = loadConfig(root, source);
+    const limit = getIn(config, 'architecture.maxLocPerFile', 400);
+    if (!limit) {
+        return { ok: true, report: '⏭️  File size limit disabled (architecture.maxLocPerFile is 0).' };
+    }
+    const exclude = getIn(config, 'architecture.maxLocExclude', []);
+
+    const files = listFiles(root, source)
+        .filter(f => SOURCE_EXTENSIONS.has(path.extname(f).toLowerCase()))
+        .filter(f => !exclude.some(prefix => f.startsWith(prefix)));
+
+    const oversized = [];
+    for (const [file, buffer] of readFiles(root, files, source)) {
+        if (!buffer || isBinary(buffer)) continue;
+        const lines = countLines(buffer.toString('utf8'));
+        if (lines > limit) oversized.push({ file, lines });
+    }
+
+    if (oversized.length === 0) {
+        return { ok: true, report: `✅ ${files.length} source file(s) within ${limit} lines.` };
+    }
+    const report = [`❌ ${oversized.length} source file(s) exceed architecture.maxLocPerFile (${limit}):\n`];
+    for (const { file, lines } of oversized.sort((a, b) => b.lines - a.lines)) {
+        report.push(`  - ${file}: ${lines} lines`);
+    }
+    report.push('\nAction: Split the file by responsibility, or add generated paths to architecture.maxLocExclude.');
+    return { ok: false, report: report.join('\n') };
+}
+
+if (require.main === module) {
+    runCheckCli('📏 Agentic SDD Framework: File Size Limit', run);
+}
+
+module.exports = { countLines, run };