agentic-sdd-framework 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Install a specific release
+with `npx github:tBeltty/agentic-sdd-framework#v<version>`.
+
+## [Unreleased]
+
+## [1.4.0] - 2026-09-25
+
+Records written by 1.3.0 use the old format: run `sdd-verify --record` (and `sdd-verify --task`
+for recorded evidence) again before pushing a `Completed` spec.
+
+### Changed
+- `Last Verified` now ends with `check <hash>`, a hash over the date, result, commit, exit code,
+  state, verification command, and expected output. Editing FAIL to PASS, or changing the command
+  or expected output after recording, reopens the spec. Recorded task evidence hashes the date and
+  exit code together with the transcript.
+- `sdd-verify --record` refuses to run while untracked files exist; they took part in the run but
+  not in the recorded state.
+- `sdd-init` reuses the answers stored in an existing `sdd.config.json` as defaults; only explicit
+  flags override them. The spec and Rigor documents are created at the configured
+  `specification.specFile` and `specification.roadmapDir`.
+- Rigor mode requires `auditkit` 0.3.9 or newer, which tightens negative-control validation. CI
+  pins the protocol repository to v0.3.9.
+- Check scripts reject unknown flags (a typo checked the working tree instead) and accept
+  `--ref <commit>` as well as `--ref=<commit>`.
+- Config paths must be canonical (`docs/SPEC.md`, not `./docs/SPEC.md`), and `specFile` and
+  `roadmapDir` must not end with `/`; other forms broke the spec check.
+- CI uses `actions/checkout@v7` and `actions/setup-node@v7`, which run on Node.js 24.
+
+### Fixed
+- Fixed how some tracked files (unusual names, very large content) were read for the secret scan.
+- Fixed secrets not being scanned in some commits.
+- Fixed a false positive on committed specs with CRLF line endings.
+- Fixed a misleading failure in shallow clones.
+- Fixed the spec parser disagreeing with GitHub on some Markdown, which could hide a task,
+  change the Status, or run a different verification command.
+- Fixed a rare case where the spec parser could read a list item differently than GitHub does.
+- Fixed a crash when the spec contains a table.
+- Fixed a checked task that could be misread and skip validation.
+- Fixed a hidden task not being detected in some cases.
+- Fixed unclosed code fences being accepted when the spec requires them closed.
+- Fixed `sdd-verify --task` misplacing evidence in some cases.
+- Fixed `sdd-verify --task` silently deleting other task data in some cases.
+- Fixed `sdd-verify --task` not checking for existing spec problems before writing evidence.
+- Fixed where `sdd-verify --task` wrote evidence under numbered tasks.
+- Fixed several false positives and false negatives in the secret scanner.
+- Fixed which paths the secret scanner skips.
+- Fixed a prose-check false positive where symlinks are unavailable.
+- Fixed `scripts/dev/sync-vendored.js` accepting a mistyped flag.
+- Fixed `sdd-verify` not killing background processes on timeout.
+- Fixed the framework exemption in the specification check applying too broadly.
+- Fixed the config validator accepting invalid keys.
+- Fixed the prose linter's handling of a custom `roadmapDir`.
+- Fixed `sdd-init`'s next steps and guided mode in some configurations.
+- Fixed test cleanup and Windows hook tests.
+
+## [1.3.0] - 2026-09-25
+
+### Fixed
+- Fixed the pre-push hook checking the working tree instead of the pushed commits.
+- Fixed Git failures being swallowed instead of failing the check.
+- Fixed `sdd.config.json` not being validated.
+- Fixed several bypasses in the specification check.
+- Fixed the secret scanner missing several kinds of credentials and secret files.
+- Fixed `maxEmDashes` and the fence-closing rule.
+- Fixed the pre-push hook installer writing into a shared hooks directory.
+- Fixed `sdd-init` ignoring some flags and forms.
+- `.claude/skills/` copies (used where symlinks are unavailable) were never refreshed; `--force`
+  refreshes them.
+- `--staged` was inconsistent: the Rigor check and the version check read the working tree.
+- Rigor mode accepted any `auditkit` version; it now requires 0.3.0 or newer.
+
+### Added
+- `sdd-verify --task <ID> -- <command>` records a command's transcript as task evidence with its
+  exit code and a hash; the gate rejects edited or failing recorded evidence, counts hand-written
+  evidence, and rejects it when `specification.requireRecordedEvidence` is true.
+- `sdd-verify --record` writes a state fingerprint and fails when the command modifies tracked files.
+- `specification.verifyTimeoutSeconds` (default 900) and `specification.verifyShell`.
+- `quality-gate.js --ref=<commit>` and `--push [remote]`. In push mode, a ref whose commit is
+  already on the remote (such as a tag on a published commit) publishes nothing new and is skipped.
+- `security.allowFiles` for tracked files with sensitive names.
+- `.sdd/VERSION` in installed projects; the wizard reports tooling upgrades.
+- CI runs on Linux, macOS, and Windows; `.gitattributes` keeps line endings consistent.
+
+### Changed
+- The README describes what the framework does and what each check enforces, including its limits.
+- `package.json` no longer declares a `main` entry (requiring the package ran the wizard).
+
+## [1.2.0] - 2026-09-25
+
+### Added
+- The quality gate checks the specification: Lite specs need evidence for checked tasks and a
+  recorded PASS to be completed; Rigor documents are checked with `auditkit lint`.
+- `sdd-verify` runs the spec's verification command and records the result.
+- Rigor documents use the auditkit format, vendored from auditor-executor-protocol, with a CI check
+  that the vendored files match the canonical repository.
+
+## [1.1.0] - 2026-09-25
+
+### Added
+- Root `AGENTS.md`, `CLAUDE.md`, and `.claude/skills/` so agents load the rules without a prompt.
+- Install into an existing project with `npx github:tBeltty/agentic-sdd-framework`.
+- File size limit check; `node:test` suites; single-process quality gate.
+
+### Changed
+- Node.js 22 LTS or newer is required.
+
+## [1.0.0] - 2026-09-02
+
+### Added
+- Initial release: constitution and context templates, Lite and Rigor specification templates,
+  strategic-cto, no-ai-slop, ast-navigator, and auditor-executor-protocol skills, bootstrapping
+  wizard, and quality gate scripts.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tBeltty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# Agentic SDD Framework
+
+> Spec-Driven Development governance for AI coding agents: agent rules that load automatically, specifications with recorded evidence, and a quality gate that checks both before every push.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Quality Gate](https://github.com/tBeltty/agentic-sdd-framework/actions/workflows/quality-gate.yml/badge.svg?branch=main)](https://github.com/tBeltty/agentic-sdd-framework/actions)
+
+---
+
+## 🎯 What It Does
+
+AI coding agents (Claude Code, Antigravity, Cursor, Codex) write code quickly, and without constraints they also guess the stack, drift out of scope, and report work as done without running it. This framework adds three things to a repository:
+
+1. **Agent rules that load without a prompt.** `AGENTS.md`, `CLAUDE.md`, and `.claude/skills/` point every supported agent at a constitution, an operational context file, and four on-demand skills.
+2. **A specification with evidence.** Tasks are checked off with recorded command output, and a spec is completed only with a recorded verification run tied to the exact content it verified.
+3. **A quality gate.** A pre-push hook checks the commits being pushed for secrets, prose rules, file size limits, and specification evidence.
+
+```mermaid
+graph LR
+    subgraph VibeCoding [Without a specification]
+        V1[Vague Prompt] --> V2[Agent Guesses Stack]
+        V2 --> V3[Unverified Multi-File Edits]
+        V3 --> V4[Regression Cascade]
+    end
+
+    subgraph AgenticSDD [With Agentic SDD]
+        S1[Constitution and Discovery] --> S2[Specification]
+        S2 --> S3[Atomic Tasks with Evidence]
+        S3 --> S4[Recorded Verification Gate]
+    end
+```
+
+---
+
+## 🧭 Progressive Rigor: Two Specification Modes
+
+Projects begin simply and scale as architectural complexity grows. The mode is set in `sdd.config.json`:
+
+```mermaid
+graph TD
+    A[New Project or Feature] --> B{Choose Specification Depth}
+    B -->|Solo Dev / Lightweight MVP| C[Lite Mode - Default]
+    C --> C1[Single File: docs/SPEC.md]
+    C1 --> C2[Recorded Verification Gate]
+    B -->|Multi-Agent / Enterprise System| D[Rigor Mode]
+    D --> D1[Plan, Execution Guide, Compliance Log, Annexes]
+    D1 --> D2[Negative Control Gates]
+```
+
+### 1. 🟢 Lite Mode (Default, Solo Developers)
+* **Single Entry Point:** `docs/SPEC.md` holds context, architecture, atomic tasks, and the verification gate.
+* **Recorded Evidence:** `sdd-verify --task <ID> -- <command>` runs a command and records its output as the task's evidence. `sdd-verify --record` runs the spec's verification command and records the result.
+* **Best For:** Solo developers, utilities, early-stage MVPs.
+
+### 2. 🔴 Rigor Mode (Opt-In, Multi-Agent Teams)
+* **The Auditor-Executor document set** in `docs/roadmap/`, in the format of [auditor-executor-protocol](https://github.com/tBeltty/auditor-executor-protocol):
+  * `plan-of-record.md`: the "what" and "why" (phases and trade-offs).
+  * `execution-guide.md`: the "how" (numbered tasks `P<phase>-T<n>` and gates `P<phase>-G<n>`).
+  * `compliance-log.md`: the ledger of pasted command output and verdicts.
+  * `annexes/`: self-contained remediation orders issued after a verdict that is not a clean `APPROVED`.
+* **Mechanical Checks:** the quality gate runs `auditkit lint` (0.3.9 or newer), which rejects missing or orphaned task entries, gates without a negative control, and `DONE` reports without pasted verify output.
+* **Best For:** Multi-agent handoffs, asynchronous work, and regulated domains.
+
+---
+
+## ⚡ Quickstart
+
+**Requirements:** Git and Node.js 22 LTS or newer (24 LTS recommended), for projects in any language. Rigor mode also needs Python 3.9+ for `auditkit`:
+
+```bash
+pipx install git+https://github.com/tBeltty/auditor-executor-protocol
+```
+
+### 1. Install into a Project (Recommended)
+Run the wizard from the root of a new or existing Git repository. Pin a release tag so a later change to `main` never reaches you unannounced (see [CHANGELOG.md](CHANGELOG.md)):
+
+```bash
+cd my-project
+npx github:tBeltty/agentic-sdd-framework#v1.4.0
+```
+
+Express mode skips the interview and takes every answer from flags:
+
+```bash
+npx github:tBeltty/agentic-sdd-framework#v1.4.0 --express --mode=lite --ast=ast-grep --runtime=go-1.23
+```
+
+### 2. Start from a Clone
+Use the framework repository itself as the starting point of a new project:
+
+```bash
+git clone --branch v1.4.0 https://github.com/tBeltty/agentic-sdd-framework.git my-project
+cd my-project
+node scripts/sdd-init.js
+```
+
+### Wizard Flags
+
+Flags take `--flag=value` or `--flag value`. Unknown flags are an error.
+
+| Flag | Values | Default |
+| :--- | :--- | :--- |
+| `--express` | Non-interactive run | Guided mode on a terminal |
+| `--target=<dir>` | Project to provision | Current directory |
+| `--name=<name>` | Project name | Target directory name |
+| `--runtime=<id>` | `node-24-lts`, `go-1.23`, `python-3.12`, ... | `node-24-lts` |
+| `--mode=<mode>` | `lite`, `rigor` | `lite` |
+| `--ast=<adapter>` | `ast-grep`, `graphify`, `ripgrep`, `lsp` | `ast-grep` |
+| `--concurrency=`, `--hardware=`, `--workload=` | Discovery answers recorded in ADR-0001 | Small internal service |
+| `--i18n`, `--pwa` | Enable the capability flags | Disabled |
+| `--force` | Refresh copied skills, templates, and `.claude/skills/` copies | Keep existing copies |
+| `--help` | Print usage | |
+
+Rerunning the wizard is safe. Existing documents are kept, `sdd.config.json` is merged and validated (keys starting with `x-` are free-form), and `AGENTS.md` / `CLAUDE.md` are only rewritten while they carry the `sdd:managed` marker. If they already exist without it, the wizard says so and prints the line to add.
+
+### What the Wizard Generates
+
+| Path | Purpose |
+| :--- | :--- |
+| `AGENTS.md` | Entry point read automatically by Codex, Cursor, and other AGENTS.md-aware agents |
+| `CLAUDE.md` | Imports the entry point, constitution, and context into Claude Code |
+| `.claude/skills/` | Symlinks to `.agents/skills/` (copies where symlinks are unavailable) so Claude Code loads each skill on demand |
+| `.agents/AGENTS.md` | Constitution: 8 non-negotiable rules, each with a "Why this rule exists" field |
+| `.agents/CONTEXT.md` | Project facts, incident registry, technical debt, and non-goals |
+| `docs/SPEC.md` (Lite) or `docs/roadmap/` (Rigor) | Active specification documents, checked by the quality gate |
+| `docs/decisions/ADR-0001-stack-and-architecture.md` | Stack decision record seeded with the discovery answers |
+| `sdd.config.json` | Configuration, validated against [`scripts/lib/sdd.config.schema.json`](scripts/lib/sdd.config.schema.json) |
+| `.sdd/scripts/`, `.sdd/VERSION` | Quality gate tooling and its version (install mode only) |
+| Git `pre-push` hook | Runs the quality gate on the pushed commits; an existing hook is kept as `pre-push.local` and runs first |
+
+When `core.hooksPath` is set (Husky, lefthook, or a shared hooks directory), the wizard installs nothing there and prints the command to add to that hook manager instead.
+
+---
+
+## 🚦 Quality Gate
+
+`node scripts/quality-gate.js` (`node .sdd/scripts/quality-gate.js` in installed projects) runs every check in one process and exits 1 if any fails. Each run reads files from one source:
+
+| Invocation | Checks |
+| :--- | :--- |
+| *(no flag)* | Tracked files in the working tree |
+| `--staged` | The index: what the next commit contains |
+| `--ref=<commit>` or `--ref <commit>` | The content of that commit |
+| `--push [remote]` | Pre-push mode (used by the hook): every check on the tip commit of each pushed ref, plus a secret scan of every new commit in the push (merge commits included), so a secret added and later removed is still caught. Refs whose commit is already on the remote are skipped |
+
+Unknown flags are errors, so a typo never falls back to checking the working tree. A check that cannot read the repository (not a Git repository, Git error, unreadable file) fails; it never reports "0 files, all clean". An invalid `sdd.config.json` (unknown key, wrong type, unknown value) fails every check with the exact problem.
+
+| Check | Script | Configuration (`sdd.config.json`) |
+| :--- | :--- | :--- |
+| Secret leak scanner | `verify-no-secrets.js` | `security.allowFiles`; the `sdd-allow-secret` line pragma (suppressions are counted in the report) |
+| No-AI-Slop copy linter | `check-copy-slop.js` | `capabilities.noAiSlop.enabled`, `.exclude`, `.maxEmDashes` |
+| File size limit | `check-file-size.js` | `architecture.maxLocPerFile` (0 disables), `architecture.maxLocExclude` |
+| Specification check | `check-spec.js` | `specification.mode`, `.specFile`, `.roadmapDir`, `.requireRecordedEvidence` |
+| Version sync | `check-versions.js` | Applies only when `project.type` is `framework` |
+
+The secret scanner reports provider keys (Anthropic, OpenAI, Stripe, GitHub, Slack, Resend, AWS, Google), private key blocks (including PGP), credentials embedded in URLs, high-entropy values assigned to secret-named keys (`password`, `client_secret`, `access_token`, `SECRET_KEY`, `signing_key`, ...; unquoted values count in env, config, rc, shell, and Docker files), and tracked secret files (`.env`, `id_rsa`, `*.key`, `*.p12`, ...). It skips only its own file at the paths the framework installs it (`scripts/` and `.sdd/scripts/`) and `node_modules/` directories; lockfiles are scanned, since a private-registry URL can embed a token. It is a regex scanner, not a replacement for a dedicated tool such as gitleaks.
+
+### What the Specification Check Enforces
+
+| Mode | Rule |
+| :--- | :--- |
+| Lite, any status | Exactly one Status line: `Draft`, `In Progress`, or `Completed`; the `Verification Gate` section exists; every checked task (any checkbox list item, blockquotes included) has evidence; the spec stays within the supported Markdown subset (below) |
+| Lite, recorded evidence | Evidence written by `sdd-verify --task` must be unedited (the hash covers the date, exit code, and transcript) and exit 0 |
+| Lite, hand-written evidence | Accepted and counted in the report; rejected when `specification.requireRecordedEvidence` is `true` |
+| Lite, `In Progress` | The verification command and expected output are filled in, not template placeholders |
+| Lite, `Completed` | Every task is checked, and `Last Verified` is an unedited PASS written by `sdd-verify --record` for the current verification command and expected output, whose state fingerprint matches the content the spec was completed with |
+| Rigor | `auditkit lint docs/roadmap` exits 0 |
+
+The gate reads the spec the way it renders: it parses it with a CommonMark parser (markdown-it, vendored in `scripts/lib/vendor/`, MIT) and takes tasks, the Status, the evidence, and the verification command from the parsed structure, so a line counts only if it renders as what it claims to be. On top of that, a small subset keeps GitHub's renderer and the parser in agreement: no raw HTML outside code (HTML comments included), no link reference definitions or footnotes (inline links only), no HTML entities or invisible and non-ASCII whitespace characters, spaces instead of tabs for indentation, and the Status and gate fields written exactly as in the template (a line that reads as a field name followed by a colon, or emphasized, in any other spelling is an error). Code is taken verbatim. Anything else fails with the line number and what to change; the template and everything `sdd-verify` writes stay inside the subset. `scripts/dev/fuzz-spec-markup.js` compares the gate's reading with cmark-gfm, GitHub's renderer, on random specs.
+
+`sdd-verify --record` runs the spec's verification command, checks that every expected line appears in the output (`/.../` lines are regular expressions), fails if the command modified tracked files, and writes `Last Verified: <date> PASS|FAIL (commit <sha>, exit <code>, state <fingerprint>, check <hash>)`. The fingerprint covers every tracked file except the spec. The check hash covers the other fields plus the verification command and expected output, so editing the result, or changing the command after recording, reopens the spec. `--record` refuses to run while there are untracked files, because they would take part in the run without being part of the recorded state; commit, ignore, or remove them first. The gate recomputes it for the commit that completed the spec (or the uncommitted state), so files changed after the verification invalidate the PASS. Later commits that do not touch the spec do not reopen it: catching regressions after a spec is closed is the job of CI and tests.
+
+Commands run in `specification.verifyShell` (default `/bin/sh` on macOS and Linux, `cmd.exe` on Windows) with a limit of `specification.verifyTimeoutSeconds` (default 900). The gate never runs a command from the spec itself; it only checks recorded results. On timeout the whole process tree is killed, including background processes the command started.
+
+The check finds the commit that completed the spec in the Git history, so CI needs the full history: in GitHub Actions, use `actions/checkout` with `fetch-depth: 0`. In a shallow clone the check fails and says so.
+
+The hashes are integrity checks, not signatures: they catch hand edits and stale records, but anyone who can run `sdd-verify` can also write a matching record. For an authoritative result, have CI run `sdd-verify` again. Recorded evidence also cannot prove a verification command is meaningful; that remains the reviewer's call.
+
+`check-system-prerequisites.js` (Git identity, `gh` authentication, SSH keys) runs once inside the wizard and is available as `npm run check:prereqs`. It is not part of the gate because it depends on the local machine, not on the code.
+
+---
+
+## 🧠 Repository Layout
+
+```text
+agentic-sdd-framework/
+├── .agents/
+│   ├── AGENTS.template.md         # Constitution template (8 rules)
+│   ├── CONTEXT.template.md        # Operational memory template
+│   ├── ENTRYPOINT.template.md     # Root AGENTS.md template
+│   └── skills/
+│       ├── strategic-cto/         # 4-Pillar Discovery, Anti-Bloat, ROI Verdict
+│       ├── auditor-executor-protocol/ # Execution protocol (tBeltty/auditor-executor-protocol)
+│       ├── no-ai-slop/            # Factual copy rules (petergyang/no-ai-slop)
+│       └── ast-navigator/         # Pluggable adapters (graphify, ast-grep, ripgrep, lsp)
+│
+├── docs/
+│   ├── SPEC_TEMPLATE.md           # Lite Mode template
+│   ├── decisions/ADR_TEMPLATE.md  # Architecture Decision Record template
+│   ├── roadmap/templates/         # Rigor Mode templates (vendored from auditkit)
+│   ├── incidents/                 # Post-mortem template
+│   ├── guides/                    # Credential tiers, GitHub CLI setup
+│   └── guidelines/                # AST navigation adapter comparison
+│
+├── scripts/
+│   ├── sdd-init.js                # Bootstrapping wizard (guided and express)
+│   ├── quality-gate.js            # Runs every check (working tree, index, commit, or push)
+│   ├── verify-no-secrets.js       # Credential scanner
+│   ├── check-copy-slop.js         # No-AI-Slop linter
+│   ├── check-file-size.js         # maxLocPerFile enforcement
+│   ├── check-spec.js              # Specification evidence check
+│   ├── sdd-verify.js              # Runs and records verification commands and task evidence
+│   ├── check-versions.js          # Framework version sync
+│   ├── check-system-prerequisites.js # Day-0 Git, gh CLI, and SSH checks
+│   ├── install-git-hooks.js       # pre-push hook installer
+│   ├── lib/                       # Git sources, config schema, spec parser, provisioning
+│   └── dev/sync-vendored.js       # Syncs and checks files vendored from auditor-executor-protocol
+│
+├── test/                          # node:test suites (npm test)
+├── CHANGELOG.md                   # Release notes
+└── sdd.config.json                # Configuration of this repository
+```
+
+---
+
+## 📜 Open-Source Attributions
+
+The **Agentic SDD Framework** integrates, adapts, or provides adapters for the following open-source projects:
+
+| Component | Author / Organization | Upstream Repository | License | Role |
+| :--- | :--- | :--- | :--- | :--- |
+| **Auditor-Executor Protocol** | **tBeltty** | [tBeltty/auditor-executor-protocol](https://github.com/tBeltty/auditor-executor-protocol) | MIT | Multi-agent coordination, Rigor Mode documents, and negative control gates. |
+| **Spec-Kit Concepts** | **GitHub** | [github/spec-kit](https://github.com/github/spec-kit) | MIT | Progressive specification hierarchy, unified single-spec model, and interactive constitution. |
+| **No-AI-Slop** | **Peter Yang** | [petergyang/no-ai-slop](https://github.com/petergyang/no-ai-slop) | MIT | Writing rules behind the copy linter. |
+| **Graphify** | **Graphify Labs** | [Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify) | Apache 2.0 | Relational knowledge graph adapter for code navigation. |
+| **ast-grep** | **Herrington Darkholme** | [ast-grep/ast-grep](https://github.com/ast-grep/ast-grep) | MIT | Tree-sitter structural search adapter. |
+| **ripgrep** | **Andrew Gallant** | [BurntSushi/ripgrep](https://github.com/BurntSushi/ripgrep) | MIT / Unlicense | Regex text search adapter. |
+| **SCIP / LSP** | **SCIP Code** (originally Sourcegraph) | [scip-code/scip](https://github.com/scip-code/scip) | Apache 2.0 | Language Server Protocol code intelligence adapter. |
+
+---
+
+## 🛡️ License
+
+This repository is licensed under the [MIT License](LICENSE). The vendored `no-ai-slop` skill keeps its upstream MIT license ([`.agents/skills/no-ai-slop/LICENSE`](.agents/skills/no-ai-slop/LICENSE)).

package/docs/SPEC_TEMPLATE.md

@@ -0,0 +1,78 @@
+# Feature Specification: [Feature Name]
+
+**Specification Mode:** Lite (Single-Document Execution)  
+**Status:** Draft | In Progress | Completed  
+**Author:** [Author Name]  
+**Target Completion:** [Date]  
+
+> The quality gate enforces this document. Status must be `Draft`, `In Progress`, or `Completed`. A checked task needs evidence: record it with `sdd-verify --task <ID> -- <command>`, or paste the command and its output. `In Progress` and `Completed` need a real verification command and expected output. `Completed` needs every task checked and a PASS recorded by `sdd-verify --record` for the exact content being completed; change a file afterwards and the PASS no longer counts. Keep to plain Markdown (spaces for indentation, closed fences, no raw HTML or comments, inline links only): the gate rejects markup it cannot read exactly as it renders.
+
+---
+
+## 1. Context and Problem Statement
+
+State the exact problem or user requirement. Document the operational root cause or feature motivation without filler or marketing language.
+
+* **Current Behavior:** Describe what happens today.
+* **Desired Behavior:** Describe what should happen after implementation.
+* **Non-Goals:** Explicitly list what this change will not address.
+
+---
+
+## 2. Technical Architecture and Constraints
+
+List every component, file, and interface impacted by this specification.
+
+* **Components Affected:**
+  * Component A: [Brief description of changes]
+  * Component B: [Brief description of changes]
+* **Data Models & Contracts:** Detail input/output schemas, schema migrations, or API payloads.
+* **Dependencies:** Name any external libraries needed. If none, state "None".
+* **Architectural Boundaries:** State constraints (for example: Domain must not import Infrastructure).
+
+---
+
+## 3. Implementation Tasks
+
+List atomic, sequential tasks. Each task must name target files and concrete actions. Check a task only after pasting the command you ran and its literal output under **Evidence**.
+
+* [ ] **T1:** [Action description]
+  * **Files:** `path/to/fileA.ext`
+  * **Details:** Specific functions, types, or configuration keys to add or modify.
+  * **Evidence:** [command run and its literal output]
+* [ ] **T2:** [Action description]
+  * **Files:** `path/to/fileB.ext`
+  * **Details:** Integration and orchestration logic.
+  * **Evidence:** [command run and its literal output]
+* [ ] **T3:** [Action description]
+  * **Files:** `path/to/tests/feature.test.ext`
+  * **Details:** Unit and integration test coverage.
+  * **Evidence:** [command run and its literal output]
+
+---
+
+## 4. Verification Gate
+
+The specification is not complete until this command exits with code 0 and returns expected output. `sdd-verify --record` runs it in `/bin/sh` (macOS, Linux) or `cmd.exe` (Windows) unless `specification.verifyShell` says otherwise, and checks that every non-empty line of the expected output appears in the actual output (a line wrapped in `/slashes/` is a regular expression).
+
+* **Verification Command:**
+  ```bash
+  [command to run tests or validation scripts]
+  ```
+* **Expected Output:**
+  ```text
+  [exact pattern or output line confirming success]
+  ```
+* **Manual Verification (If applicable):** Specific manual steps to observe expected behavior.
+* **Last Verified:** [recorded by sdd-verify --record]
+
+`sdd-verify --record` writes `Last Verified` with a hash over the result, the command, and the expected output. Do not edit it by hand: changing any of them reopens the spec until you record again.
+
+---
+
+## 5. Decision Rationale
+
+Record trade-offs and alternatives rejected during implementation.
+
+* **Decision 1:** [Why option A was selected over option B].
+* **Origin:** [Incident, performance measurement, or architectural requirement driving the decision].

package/docs/decisions/ADR_TEMPLATE.md

@@ -0,0 +1,49 @@
+# ADR-[NNNN]: [Decision Title]
+
+**Status:** Accepted | Proposed | Superseded  
+**Date:** [YYYY-MM-DD]  
+**Deciders:** [Author / Team]  
+
+---
+
+## 1. Context and Problem Statement
+
+Document the application requirements and the results of the **4-Pillar Discovery Interview**:
+
+1. **Scale and Concurrency:** Target users (e.g. 1–10 internal users vs 50,000 public users). Concurrency peaks expected in Year 1.
+2. **Hardware and Deployment:** Target runtime environment (e.g. $5 VPS, local machine, cloud containers). Memory and CPU bounds.
+3. **Data and Workload:** Primary operations (I/O-heavy, CPU-intensive, static storage vs live compute). Data persistence volume.
+4. **Modularity and Localization:** Requirement for multi-language translation (i18n), PWA offline caching, role-based access.
+
+---
+
+## 2. Decision and Selected Stack
+
+State the selected technologies across each layer of the application:
+
+* **Backend Runtime & Framework:** [e.g. Go with standard net/http, Node.js 24 LTS with Hono, Python 3.12 with FastAPI]
+* **Frontend Architecture:** [e.g. Static Single Page Application (Vite + React), Server-Rendered HTML, CLI tool]
+* **Persistence Engine:** [e.g. SQLite with WAL mode, PostgreSQL 16, Flat JSON files]
+* **Code Navigation Adapter:** [e.g. Graphify, ast-grep, ripgrep]
+
+---
+
+## 3. Anti-Bloat Burden of Proof
+
+Explain why simpler architectural tiers were accepted or discarded:
+
+* **Tier 1 Evaluation (Ultra-Lightweight):** [Why Tier 1 was selected, or why it lacked required capability].
+* **Tier 2 Evaluation (Balanced):** [Why Tier 2 was selected, or why it was bypassed].
+* **Tier 3 Evaluation (Heavy Batteries):** If choosing a heavy full-stack framework (such as Next.js SSR or Django), document the mandatory technical reason that simpler stacks could not satisfy.
+
+---
+
+## 4. Consequences and Trade-Offs
+
+### Positive Consequences:
+* Minimal memory footprint and predictable resource consumption.
+* Fast continuous integration build times.
+* Clear isolation of domain logic and infrastructure.
+
+### Negative Consequences and Mitigations:
+* [Document trade-offs accepted, such as manual routing or lack of monolithic magic].

package/docs/guidelines/AST_NAVIGATION.md

@@ -0,0 +1,51 @@
+# 🧭 Codebase Navigation: AST First and Token Efficiency
+
+This guide establishes the codebase exploration protocol for developers and autonomous AI agents using the **Agentic SDD Framework**.
+
+---
+
+## 1. The Core Problem: Context Bloat and Token Exhaustion
+
+Traditional agent exploration relies on running broad `grep` commands or dumping whole source files into model context. This approach causes three compounding failures:
+
+1. **Context Saturation:** Reading five 800-line files consumes 20,000+ tokens before any code is written.
+2. **Loss of Precision:** Agents struggle with needle-in-a-haystack symbol tracing when flooded with irrelevant function bodies.
+3. **Financial Cost:** Monorepo exploration costs scale linearly with repository lines of code.
+
+---
+
+## 2. The Solution: AST-First Hierarchy
+
+Always follow the three-tier exploration hierarchy:
+
+```text
+Step 1: AST / Graph Query (Locate symbol, caller, or interface definition)
+                   │
+                   ▼ (If not found or graph stale)
+Step 2: Scoped Grep (Search bounded by file extension or directory glob)
+                   │
+                   ▼ (After locating exact line bounds)
+Step 3: Slice Inspection (Read only target lines, e.g. lines 40 to 80)
+```
+
+---
+
+## 3. Objective Comparison of Navigation Adapters
+
+| Adapter | Upstream Creator | Mechanism | Best For | Trade-offs |
+| :--- | :--- | :--- | :--- | :--- |
+| **`graphify`** | Graphify Labs | Relational graph + visual extraction | Monorepos, cross-layer dependency tracing | Requires Python 3.10+; index requires updates after edits. |
+| **`ast-grep`** | Herrington Darkholme | Tree-sitter structural syntax matching | Syntax-aware structural grep, code migrations | Requires language parser support; no whole-repo graph visualization. |
+| **`ripgrep`** | Andrew Gallant | Line-oriented SIMD regex engine | Fast text search, markdown/config inspection | Does not understand semantic code structure or imports. |
+| **`lsp / scip`** | SCIP Code (originally Sourcegraph) | Language Server Protocol type indexing | Enterprise TypeScript, Go, Java, Rust | Heavier initial indexing pipeline; language-specific setups. |
+
+---
+
+## 4. How to Select Your Active Adapter
+
+In `sdd.config.json`, set the adapter under `capabilities.astNavigation.adapter`:
+
+* Choose **`graphify`** if you work in a medium-to-large multi-service monorepo and have Python available.
+* Choose **`ast-grep`** if you want zero Python dependencies and fast structural syntax matching.
+* Choose **`ripgrep`** if you are building a small project and prefer standard text utilities.
+* Choose **`lsp`** if your primary language relies heavily on complex compiler type hierarchies.

package/docs/guides/AGENT_CREDENTIALS.md

@@ -0,0 +1,75 @@
+# 🔐 Zero-Trust Secret Architecture & Credential Registry
+
+This document establishes the **Three-Tier Secret Isolation Model** for repositories managed with the **Agentic SDD Framework**.
+
+---
+
+## 🏛️ The Three-Tier Secret Isolation Model
+
+AI agents are powerful code executors, but they must be treated under a **Zero-Trust Model**. Secrets are categorized into three isolated tiers to ensure credentials can never be leaked through code, git history, or agent context logs.
+
+```text
+┌────────────────────────────────────────────────────────┐
+│ Tier 1: Production Host Secrets                        │
+│ - Stored ONLY on production hosts (VPS/Cloud)          │
+│ - Read directly by the running application process     │
+│ - Never checked into Git, never in developer workspaces │
+└────────────────────────────────────────────────────────┘
+                           ▲
+┌────────────────────────────────────────────────────────┐
+│ Tier 2: CI/CD Execution Secrets                        │
+│ - Stored in GitHub Actions Secrets                     │
+│ - Injected ephemeral into runner memory                │
+│ - Masked automatically from build & test logs          │
+└────────────────────────────────────────────────────────┘
+                           ▲
+┌────────────────────────────────────────────────────────┐
+│ Tier 3: Agent Diagnostic Vault (OUTSIDE REPOSITORY)    │
+│ - Location: ~/secrets/<project-name>/.vault            │
+│ - Filesystem permissions: chmod 600 (User-only read)   │
+│ - Agent reads from disk; NEVER asks user to paste keys │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚨 Inviolable Rules for AI Coding Agents
+
+1. **NEVER Ask the User to Paste a Secret in Chat:**
+   Asking the user to paste an API key or password into a conversation stores that credential in model training logs and session history.
+2. **NEVER Write Secrets to Tracked Files:**
+   Credentials must never be hardcoded into source code, test files, configs, or markdown artifacts.
+3. **NEVER Log Credentials to Console or Files:**
+   Avoid `console.log(process.env)` or printing authorization headers during debugging.
+4. **Always Read from the Tier 3 Vault:**
+   When an agent requires read-only diagnostic access (e.g. Sentry API, GitHub API, Cloudflare API), it must read directly from `~/secrets/<project-name>/.vault` using local filesystem read tools.
+
+---
+
+## 🛠️ Setting Up the Tier 3 Local Vault
+
+Run this setup once on your local developer machine:
+
+```bash
+# 1. Create secure secrets directory outside of any git repository
+mkdir -p ~/secrets/<project-name>
+
+# 2. Create the vault file
+touch ~/secrets/<project-name>/.vault
+
+# 3. Restrict permissions to owner-only read/write
+chmod 600 ~/secrets/<project-name>/.vault
+```
+
+### Format of `.vault`:
+```bash
+# Key-value pairs read by diagnostic tools
+GITHUB_TOKEN=gho_xxxxxxxxxxxxxxxxxxxx
+SENTRY_AUTH_TOKEN=sntrys_xxxxxxxxxxxxxxxxxxxx
+```
+
+---
+
+## 🛡️ Pre-Commit Verification Scanner
+
+Before committing code, the repository enforces `scripts/verify-no-secrets.js`. Any commit containing a staged secret or private key will be blocked immediately.