agentic-sdd-framework 1.4.0 → 1.5.0

package/.agents/AGENTS.template.md

@@ -4,56 +4,64 @@ This document establishes the non-negotiable operating rules for AI coding agent
 
 ---
 
+<!-- sdd:rule id="discovery-first" tier="moderate" -->
 ## 1. Discovery First (No Premature Assumptions)
 * **Rule:** Before recommending architectures, selecting frameworks, or generating code on a new initiative, the agent must execute the 4-Pillar Discovery Interview (Scale/Concurrency, Hardware/Deployment, Workload/Compute, Modularity).
 * **Why this rule exists:**
-  > [Document the incident or rationale here. For example: An agent previously recommended a heavy full-stack framework for a lightweight streaming utility, introducing unnecessary runtime bloat.]
+  > A stack or architecture chosen before the actual scale, deployment target, and workload are known tends to be either over-built or wrong for the job; a few minutes of discovery costs less than unwinding that choice later.
 
 ---
 
+<!-- sdd:rule id="evidence-driven-debugging" tier="moderate" -->
 ## 2. Evidence-Driven Debugging & Diagnostics
 * **Rule:** Never guess root causes or apply speculative patches. Inspect log files, inspect command output, and run diagnostics before altering code.
 * **Why this rule exists:**
-  > [Document the incident or rationale here. For example: Speculative patches often introduce regression cascades that obscure the original defect.]
+  > A fix aimed at a guessed cause, instead of the one diagnostics actually show, risks patching a symptom while the real defect -- and a regression alongside it -- stays hidden.
 
 ---
 
+<!-- sdd:rule id="mandatory-verification" tier="critical" -->
 ## 3. Mandatory Verification Before Certification
-* **Rule:** A task or phase is not complete until its explicit verification command exits with code 0. Reading code visually is never a substitute for running the code.
+* **Rule:** A task or phase is not complete until its explicit verification command exits with code 0. Reading code visually is never a substitute for running the code. When the change touches anything a user perceives directly -- rendered markup, CSS, a screen transition, an interactive flow -- a green test suite is not sufficient evidence: verify by actually driving the interface the way a user would, since a unit test does not render CSS or exercise the DOM's `hidden`/cascade behavior. Any claim of having stopped, cleaned up, or removed a process or resource must name the exact identifier (PID, handle, container id) the agent itself created; never certify a resource as handled without confirming it is the one you spawned.
 * **Why this rule exists:**
-  > [Document the incident or rationale here. For example: Clean syntax does not guarantee functional runtime behavior or integration success.]
+  > Clean-looking code is not proof of working code. A visual review cannot catch a broken runtime path, a failing integration, or a regression an agent introduced while editing; running the actual command is the only evidence this framework accepts, which is why `sdd-verify` exists. A full test suite has passed while a CSS rule silently defeated the `hidden` attribute and left two screens stacked on top of each other, invisible to any test that never renders a page -- the tests were evidence of the backend logic, not of what a user would actually see. The same gap extends to claims about system actions: an agent reported having stopped "its own" test process while actually terminating a different, pre-existing one, misidentifying the PID in its own success report. Certifying either kind of claim requires evidence tied to the specific thing claimed, not prose that merely sounds like evidence.
 
 ---
 
+<!-- sdd:rule id="closed-network-testing" tier="moderate" -->
 ## 4. Closed-Network Testing Isolation
 * **Rule:** Automated test suites must never contact external internet hosts. All external integrations must be mocked or gated on environment variables. Loopback testing is permitted for local servers.
 * **Why this rule exists:**
-  > [Document the incident or rationale here. For example: Test suites that hit third-party APIs can cause hard bounces, rate limits, and unexpected billing exposure.]
+  > A test suite that reaches a real third-party API is one flaky network call away from a false failure, and one bad run away from a rate limit or a bill nobody asked for.
 
 ---
 
+<!-- sdd:rule id="zero-trust-secrets" tier="critical" -->
 ## 5. Zero-Trust Secrets Management
 * **Rule:** Agents must never request API keys or credentials in chat prompts. Secrets must be read directly from the Tier 3 Vault (`~/secrets/<app>/.vault`) or environment variables. Never commit secrets to Git. Tier model: `docs/guides/AGENT_CREDENTIALS.md`.
 * **Why this rule exists:**
-  > [Document the incident or rationale here. For example: Chat logs and git histories are permanently recorded; leaking credentials requires immediate key revocation.]
+  > A credential typed into a chat prompt or pasted into a diff is permanently recorded in logs and git history. Treat every prompt and every commit as effectively public, and never put a secret where either can capture it.
 
 ---
 
+<!-- sdd:rule id="scope-bounding" tier="critical" -->
 ## 6. Scope Bounding & Atomic Progression
 * **Rule:** Execute one task at a time in strict sequence. Do not refactor unrelated files or perform out-of-scope cleanups without explicit Auditor authorization.
 * **Why this rule exists:**
-  > [Document the incident or rationale here. For example: Unbounded edits make regression tracing difficult and invalidate concurrent session handoffs.]
+  > An agent that touches files outside the current task makes the change hard to attribute, review, and revert, and breaks the handoff when a different session or agent picks up the work next.
 
 ---
 
+<!-- sdd:rule id="factual-copy" tier="moderate" -->
 ## 7. Factual Technical Copy (No AI Slop)
 * **Rule:** All documentation, user-facing copy, and commit messages must be factual, concise, and dense, following the `no-ai-slop` skill. The quality gate enforces its banned patterns.
 * **Why this rule exists:**
-  > [Document the incident or rationale here. For example: Promotional puffery and marketing contrasts obscure technical reality and degrade documentation clarity.]
+  > Generic, promotional phrasing in docs and commit messages buries the one technical fact a future reader actually needs.
 
 ---
 
+<!-- sdd:rule id="author-attribution" tier="moderate" -->
 ## 8. Author Attribution & Integrity
-* **Rule:** Never attach `Co-Authored-By:` trailers crediting AI assistants to Git commits. The repository owner is the sole author.
+* **Rule:** Never attach `Co-Authored-By:` trailers crediting AI assistants to Git commits. The repository owner is the sole author. Before the first commit in a repository you have not committed to before, run `git config user.email` (and `user.name`) and confirm the result is the identity this project actually wants -- do not assume whatever the global default resolves to is correct, since it may be a different project's or a personal identity.
 * **Why this rule exists:**
-  > [Document the incident or rationale here. For example: Project contributors retain 100% ownership and commit graph clarity without AI tooling noise.]
+  > The project owner is the sole author of record; a Co-Authored-By trailer credits work no tool did unsupervised, and pollutes the commit graph for everyone after. A commit's author is never wrong by accident -- it is either the identity someone actually configured for this project, or nobody checked.

package/.agents/ENTRYPOINT.template.md

@@ -15,9 +15,26 @@ Load a skill from `.agents/skills/<name>/SKILL.md` only when its trigger applies
 | :--- | :--- |
 | `strategic-cto` | Choosing a stack or architecture, or answering "can this be improved?" |
 | `auditor-executor-protocol` | Work spans several phases or sessions, or another agent implements the plan |
+| `fix-and-verify` | Fixing a reported bug, including a vague one with no repro steps, in a single session |
 | `no-ai-slop` | Writing documentation, user-facing copy, or commit messages |
 | `ast-navigator` | Exploring code. Active adapter: `{{AST_ADAPTER}}` (`.agents/skills/ast-navigator/adapters/{{AST_ADAPTER}}.md`) |
 
+## Adding a Rule
+
+`.agents/AGENTS.md` is the only place a project rule lives. If the user asks to add one
+("always do X", "never do Y", "remember this constraint"), do not write it to memory, to
+CLAUDE.md, or to a temporary or unrelated doc -- none of those are read by every agent, or
+checked by the gate. Run:
+
+```
+{{ADD_RULE_COMMAND}} --title "<short title>" --rule "<the operating rule>" --why "<why this rule exists>"
+```
+
+It appends a correctly numbered, tagged rule block; it refuses empty fields and bracket
+placeholders. If the rule replaces one of the 8 defaults with an equivalent of your own,
+add `--fulfills=<id>` (see the tag above the rule you are replacing in `.agents/AGENTS.md`)
+so the constitution check still recognizes it as fulfilling that slot.
+
 ## Project Facts
 
 * Runtime: {{RUNTIME}}

package/.agents/skills/fix-and-verify/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: fix-and-verify
+description: "Investigate and resolve a bug report, including a vague one ('this doesn't work', 'it looks wrong', a one-line client complaint with no repro steps), with reproduction before diagnosis and independent, evidence-backed verification before claiming done. Use for any single-session bug fix, whether or not the project has adopted the full spec lifecycle -- a quick 'fix this' ask inherits the same evidence standard as a tracked task. Triggers: 'this doesn't work', 'fix this bug', 'it looks wrong', 'the client/user says', a complaint with no repro steps, being asked to fix something another agent already touched and reported as done. NOT for multi-phase or multi-session work handed to a different implementing agent -- see auditor-executor-protocol for that."
+---
+
+# Fix and Verify
+
+A vague bug report is not an invitation to guess. This exists because the two most
+expensive failures in a bug-fix task both look identical to a rushed, confident report:
+a fix that patches the wrong thing, and a fix that's real but never actually checked.
+
+## 1. Reproduce before you diagnose
+
+Never fix a symptom you haven't seen yourself. A one-line complaint ("se ve mal", "this
+doesn't work") describes what the user perceived, not the mechanism -- go observe the
+actual failure (run the app, read the log, load the actual page) before touching a
+single file. If a previous engineer or agent already touched this and reported it fixed,
+do not trust that report either: reproduce the *original* complaint yourself first, on
+the current state of the code, before deciding whether their fix actually closed it.
+
+## 2. Read the full source of anything load-bearing
+
+Grep finds a string; it does not tell you whether a class is used elsewhere, whether a
+rule is overridden further down the file, or whether a fix for one element also covers a
+sibling that has the same shape. Read the actual file for anything the fix depends on.
+
+## 3. Tests passing is not evidence for a class of bug tests can't see
+
+A backend/unit test suite exercises logic, not rendering. If the complaint is about
+anything a user perceives visually or interactively -- a layout, a form, a screen
+transition, an overlapping element -- a green suite tells you nothing about whether the
+complaint is resolved, because no unit test renders CSS or exercises the DOM's `hidden`
+attribute against the cascade. Confirm the fix the same way the complaint was raised:
+drive the actual interface, the same flow the user described.
+
+## 4. Minimal, scoped fix
+
+Fix the reported failure. Do not refactor adjacent code, rename things, or "while I'm
+here" clean up unrelated issues -- note them separately if they're worth flagging, but
+scope creep on a bug-fix task is itself a defect (see Rule 6, Scope Bounding, in
+`AGENTS.md`).
+
+## 5. Verify by re-running the exact repro, not a nearby one
+
+Re-run the precise steps that surfaced the complaint after the fix, in a fresh session/
+page load, not a variation that happens to look clean. Fixing one visible symptom (e.g.
+two forms toggling correctly) is not the same as fixing the complaint (e.g. the screen
+staying stacked after login) if the two share a root cause but not a code path. Before
+reporting done, ask: does this exact repro, run again, now show the correct result? If
+you can't answer that from something you just ran, you don't have a verified fix yet.
+
+## 6. Never claim credit for cleaning up a resource you didn't create
+
+If you started a server, process, or container to test the fix, stop only that one, and
+report the specific identifier (PID, port, handle) you yourself created it with. A
+process that predates your task, or one you didn't verify the origin of, is out of scope
+to touch and out of scope to claim you stopped -- "confirmed nothing is listening" is not
+the same claim as "confirmed *the process I started* is gone," and conflating the two in
+a report has caused a pre-existing, unrelated process to be killed without authorization
+while the report described it as the agent's own test server.
+
+## 7. Report what you found, not how confident you feel
+
+State: what was still broken, the root cause, exactly what changed, and the repro output
+that confirms it's fixed now. "Should be fixed" or "this looks correct now" is not a
+substitute for pasting the result of re-running the repro.

package/.agents/skills/no-ai-slop/SKILL.md

@@ -40,6 +40,7 @@ Do not use decorative buzzwords that inflate importance without adding technical
 1. **Active Voice & Factual Density:** Explain what the code does, what parameters it receives, and what command validates it.
 2. **State Measurable Facts:** Replace "ultra-fast performance" with measured latency or memory consumption (for example: "< 30MB RAM, < 50ms startup").
 3. **No Unverifiable Claims:** If a metric has not been empirically benchmarked, do not state it as fact.
+4. **Changelog Entries, One Line Each:** One bullet per change, present tense, user-facing ("Fixed X.", "Added Y."). No mechanism internals, no multi-sentence rationale, no nested sub-bullets explaining how it works -- that belongs in code comments, tests, or the PR description, not in CHANGELOG.md. See this file's own `## [1.3.0]` and `## [1.4.0]` entries for the target density.
 
 ---
 

package/CHANGELOG.md

@@ -6,7 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 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.5.0] - 2026-09-27
+
+### Added
+- Constitution check: a non-blocking gate step that warns when a critical constitution rule is missing or the constitution is empty.
+- `sdd-init --rules=all|critical|none` to choose which default constitution rules the wizard writes.
+- `sdd-add-rule` to add a constitution rule correctly after day-0, with `--fulfills=<id>` for a custom equivalent of a default rule.
+- The constitution's Author Attribution rule now also requires confirming `git config user.email`/`user.name` before a repository's first commit, instead of trusting whatever identity the global git default resolves to.
+- `fix-and-verify` skill: reproduce a bug report before diagnosing it, verify a UI-facing fix by driving the interface instead of trusting a green test suite, and never claim credit for stopping a process the agent didn't itself spawn.
+- The Mandatory Verification rule now also covers UI-render evidence and requires naming the exact identifier (PID, handle, container id) behind any claim of having stopped, cleaned up, or removed a process or resource.
+
+### Fixed
+- `sdd-init`'s default `sdd.config.json` no longer claims "clean-architecture" for every new project; it says the style is not yet decided until the discovery interview records one.
 
 ## [1.4.0] - 2026-09-25
 

package/README.md

@@ -1,92 +1,68 @@
 # 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.
+> **Deterministic governance for AI coding agents.** Stop Claude Code, Cursor, Antigravity, and Codex from hallucinating completed tasks and drifting out of scope.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/agentic-sdd-framework.svg)](https://www.npmjs.com/package/agentic-sdd-framework)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node: 22+](https://img.shields.io/badge/node-22%2B%20LTS-green.svg)](https://nodejs.org/)
 [![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
+## The Problem
 
-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:
+AI coding agents write code fast, but uncontrolled:
+- They check off `[x] Done` without actually running the code.
+- They silently guess the stack, add dependencies, and drift from what was asked.
+- They pass a manual review because reading terminal output line by line is tedious, so nobody does it every time.
 
-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.
+## The Solution
 
-```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
-```
+Agentic SDD adds a specification lifecycle to your repository that an agent cannot talk its way around:
+1. **Rules that load without a prompt.** `AGENTS.md` and `CLAUDE.md` point every supported agent at a constitution before it writes a line of code.
+2. **Evidence, not claims.** A task cannot be checked off by hand: `sdd-verify` runs the command and stamps the result with a hash tied to the exact file state it verified.
+3. **A gate that actually blocks.** A pre-push hook fails the push, before it reaches `origin`, if evidence is missing, faked, or stale.
 
 ---
 
-## 🧭 Progressive Rigor: Two Specification Modes
+## See It Work
 
-Projects begin simply and scale as architectural complexity grows. The mode is set in `sdd.config.json`:
+```text
+$ git push
+❌ T1 is checked but has no evidence.
+   Quality gate failed — push rejected.
 
-```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]
-```
+$ sdd-verify --task T1 -- npm test
+$ 42 passed
+✅ T1: exit 0, evidence recorded in docs/SPEC.md.
 
-### 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.
+$ git add -A && git commit -m "T1: parser" && git push
+✅ Quality gate passed.
+```
 
-### 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.
+Nobody edits the spec by hand to mark a task done: `sdd-verify` is the only thing allowed to write evidence, and it only writes what actually happened.
 
 ---
 
-## ⚡ 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`:
+## Quickstart
 
 ```bash
-pipx install git+https://github.com/tBeltty/auditor-executor-protocol
+cd your-project
+npx github:tBeltty/agentic-sdd-framework#v1.4.0
 ```
 
-### 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)):
+The interactive wizard asks a few questions (specification mode, coding agent skills, runtime) and sets up agent rules, a starter spec, and the pre-push hook. Non-interactive:
 
 ```bash
-cd my-project
-npx github:tBeltty/agentic-sdd-framework#v1.4.0
+npx github:tBeltty/agentic-sdd-framework#v1.4.0 --express --mode=lite --runtime=node-24-lts
 ```
 
-Express mode skips the interview and takes every answer from flags:
+**Requirements:** Git and Node.js 22 LTS or newer (24 LTS recommended), for a project in any language. That's it. [Rigor mode](#progressive-modes-lite-vs-rigor) needs one more tool; see below.
 
-```bash
-npx github:tBeltty/agentic-sdd-framework#v1.4.0 --express --mode=lite --ast=ast-grep --runtime=go-1.23
-```
+<details>
+<summary>Other ways to install</summary>
 
-### 2. Start from a Clone
-Use the framework repository itself as the starting point of a new project:
+**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
@@ -94,7 +70,37 @@ cd my-project
 node scripts/sdd-init.js
 ```
 
-### Wizard Flags
+**Pin a release tag.** `#v1.4.0` above pins the exact release, so a later change to `main` never reaches you unannounced. See [CHANGELOG.md](CHANGELOG.md) for what changed in each version.
+
+</details>
+
+---
+
+## How It Works: The 3 Pillars
+
+1. **Constitution (`AGENTS.md`, `CLAUDE.md`):** 8 non-negotiable rules, each with a "why this rule exists" field, loaded automatically by every supported agent. No prompt engineering required to keep an agent inside its lane.
+2. **Evidence-Based Spec (`sdd-verify`):** `docs/SPEC.md` holds atomic tasks; `sdd-verify --task <ID> -- <command>` runs a command and records its output as that task's evidence, and `sdd-verify --record` does the same for the spec's overall verification command. See [docs/architecture/spec-integrity.md](docs/architecture/spec-integrity.md) for exactly how that evidence is hashed and checked.
+3. **Quality Gate (pre-push hook):** before a push reaches `origin`, it's checked for secrets, low-effort AI prose, oversized files, and specification evidence, in one process with one exit code.
+
+---
+
+## Progressive Modes: Lite vs. Rigor
+
+Projects start simple and scale as complexity grows. The mode is set in `sdd.config.json`.
+
+| | 🟢 Lite (default) | 🔴 Rigor (opt-in) |
+| :--- | :--- | :--- |
+| **Use it for** | Solo developers, utilities, early-stage MVPs | Multi-agent handoffs, asynchronous work, regulated domains |
+| **Spec lives in** | One file: `docs/SPEC.md` | `docs/roadmap/`: a plan, an execution guide, a compliance log, and remediation annexes |
+| **Format** | Tasks with recorded evidence and a verification gate | The [auditor-executor-protocol](https://github.com/tBeltty/auditor-executor-protocol) document set, with negative-control gates |
+| **Extra requirement** | None | Python 3.9+ and `auditkit`: `pipx install git+https://github.com/tBeltty/auditor-executor-protocol` |
+
+---
+
+## Commands & CLI Reference
+
+<details>
+<summary><strong>Wizard flags</strong> (<code>sdd-init</code>)</summary>
 
 Flags take `--flag=value` or `--flag value`. Unknown flags are an error.
 
@@ -105,82 +111,71 @@ Flags take `--flag=value` or `--flag value`. Unknown flags are an error.
 | `--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` |
+| `--rules=<selection>` | `all`, `critical`, `none` (constitution rules to include; see the Constitution check row below) | `all` |
 | `--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.
+Rerunning the wizard is safe: existing documents are kept, `sdd.config.json` is merged and validated (`x-` prefixed keys are free-form), and `AGENTS.md` / `CLAUDE.md` are only rewritten while they carry the `sdd:managed` marker.
+
+</details>
 
-### What the Wizard Generates
+<details>
+<summary><strong>What the wizard generates</strong></summary>
 
 | 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 |
+| `.claude/skills/` | Symlinks to `.agents/skills/` (copies where symlinks are unavailable) |
+| `.agents/AGENTS.md` | Constitution: 8 non-negotiable rules |
 | `.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.
+When `core.hooksPath` is set (Husky, lefthook, or a shared hooks directory), the wizard installs nothing there and prints the command to add instead.
 
----
+</details>
 
-## 🚦 Quality Gate
+<details>
+<summary><strong>Quality gate</strong> (<code>quality-gate.js</code>)</summary>
 
-`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:
+Runs every check in one process, 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.
+| `--ref=<commit>` | The content of that commit |
+| `--push [remote]` | Pre-push mode: every check on each pushed ref's tip, plus a secret scan of every new commit in the push |
 
-### What the Specification Check Enforces
+Unknown flags are errors. A check that cannot read the repository fails loudly instead of reporting "0 files, clean".
 
-| Mode | Rule |
+| Check | Enforces |
 | :--- | :--- |
-| 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.
+| Secret leak scanner | Provider keys, private key blocks, credentials in URLs, secret-named assignments, tracked secret files |
+| No-AI-Slop copy linter | Rejects generic AI-written prose patterns |
+| File size limit | `architecture.maxLocPerFile` |
+| Specification check | Status, evidence, and verification gate rules (see below) |
+| Constitution check | Non-blocking: 3 severity levels based on which of the 8 default rules are fulfilled (see below) |
+| Version sync | `package.json` and `sdd.config.json` versions match (framework repo only) |
 
-`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.
+**Constitution check** never fails the gate. Neither the rule count nor the "why this rule exists" rationale is mandatory, and a project can deliberately ship with none of the 8 default rules, or with entirely custom ones. The wizard's 8 defaults split into 3 critical (verification, secrets, scope) and 5 moderate suggestions; `sdd-init --rules=all|critical|none` (or the guided prompt) picks which ship, and each already carries real rationale, not a placeholder. The gate reads three outcomes: all 3 critical + 5 moderate present is silent (✅), all 3 critical present with some moderate missing is a light note (💡, optional), and a missing critical rule or an empty constitution is a warning (⚠️); none of them block the push. A rule is "present" only through its `<!-- sdd:rule id="..." tier="..." -->` tag, never by matching heading text, so an expert can replace a default with their own equivalent (`sdd-add-rule --fulfills=<id>`) and the gate still recognizes it. Add a rule after day-0 with `sdd-add-rule --title <t> --rule <r> --why <w>`, the sanctioned way to record a rule, instead of an agent writing "always do X" into memory, `CLAUDE.md`, or an unrelated doc the gate never reads.
 
-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.
+**Specification check, Lite mode:** exactly one Status line (`Draft`, `In Progress`, `Completed`); every checked task has recorded, unedited evidence; `In Progress`/`Completed` need a real verification command and expected output; `Completed` needs every task checked and an unedited PASS from `sdd-verify --record` matching the current file state. **Rigor mode:** `auditkit lint docs/roadmap` exits 0.
 
-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.
+Full mechanism (hashing, CommonMark parsing subset, timeouts): [docs/architecture/spec-integrity.md](docs/architecture/spec-integrity.md).
 
-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.
+</details>
 
 ---
 
-## 🧠 Repository Layout
+<details>
+<summary><strong>Repository Layout</strong></summary>
 
 ```text
 agentic-sdd-framework/
@@ -196,6 +191,7 @@ agentic-sdd-framework/
 │
 ├── docs/
 │   ├── SPEC_TEMPLATE.md           # Lite Mode template
+│   ├── architecture/              # How the gate and spec integrity work internally
 │   ├── decisions/ADR_TEMPLATE.md  # Architecture Decision Record template
 │   ├── roadmap/templates/         # Rigor Mode templates (vendored from auditkit)
 │   ├── incidents/                 # Post-mortem template
@@ -214,31 +210,29 @@ agentic-sdd-framework/
 │   ├── 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
+│   └── dev/                       # Vendoring sync and the spec parser's differential fuzz
 │
 ├── 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. |
+</details>
 
 ---
 
-## 🛡️ License
+## Attributions & 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)).
+This repository is [MIT licensed](LICENSE). It integrates, adapts, or provides adapters for:
+
+| Component | Author | License |
+| :--- | :--- | :--- |
+| [Auditor-Executor Protocol](https://github.com/tBeltty/auditor-executor-protocol) | tBeltty | MIT |
+| [Spec-Kit Concepts](https://github.com/github/spec-kit) | GitHub | MIT |
+| [No-AI-Slop](https://github.com/petergyang/no-ai-slop) | Peter Yang | MIT |
+| [Graphify](https://github.com/Graphify-Labs/graphify) | Graphify Labs | Apache 2.0 |
+| [ast-grep](https://github.com/ast-grep/ast-grep) | Herrington Darkholme | MIT |
+| [ripgrep](https://github.com/BurntSushi/ripgrep) | Andrew Gallant | MIT / Unlicense |
+| [SCIP / LSP](https://github.com/scip-code/scip) | SCIP Code (originally Sourcegraph) | Apache 2.0 |
+
+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/architecture/spec-integrity.md

@@ -0,0 +1,84 @@
+# Specification Integrity: How the Gate Reads and Verifies the Spec
+
+This document covers the internals behind the "cryptographic proofs" and "zero-trust gate"
+claims in the [README](../../README.md): how `docs/SPEC.md` is parsed, how evidence is hashed,
+and what the gate does and does not guarantee. Read this if you are auditing the framework,
+contributing to it, or curious about the mechanism. Skip it if you just want to use it.
+
+## The spec is read the way it renders
+
+The gate does not scan `docs/SPEC.md` line by line. It parses it with a real CommonMark parser
+(markdown-it, vendored in [`scripts/lib/vendor/`](../../scripts/lib/vendor/), MIT, no npm
+dependency) and takes tasks, the Status, the evidence, and the verification command from the
+parsed token tree: a line counts only if it renders as what it claims to be.
+
+On top of that, a small Markdown subset keeps GitHub's renderer (cmark-gfm) and the parser in
+agreement, for the narrow set of cases where they could still differ:
+
+- no raw HTML outside code (HTML comments included);
+- no link reference definitions or footnotes (inline links only);
+- no HTML entities, invisible characters, or non-ASCII whitespace outside code;
+- spaces instead of tabs for indentation;
+- 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);
+- a line right after a list item, indented 4 or more spaces but fewer than that item's own
+  content column, and starting with `>`, `#`, or a fence, is rejected: cmark-gfm and
+  markdown-it can disagree on whether it continues the item or starts indented code.
+
+Code (fenced or indented) is taken verbatim and never checked against these rules. Anything
+outside the subset fails with the line number and what to change; the template and everything
+`sdd-verify` writes stay inside it.
+
+[`scripts/dev/fuzz-spec-markup.js`](../../scripts/dev/fuzz-spec-markup.js) compares the gate's
+reading against cmark-gfm on tens of thousands of randomly generated specs on every change to
+the parser, looking for a rendered unchecked task the gate does not see, a rendered Status
+different from the parsed one, or a gate command different from the rendered one. This subset
+and parser have been through ten rounds of adversarial review closing bypasses found this way.
+
+## Recorded evidence and the verification hash chain
+
+`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:
+
+```text
+Last Verified: <date> PASS|FAIL (commit <sha>, exit <code>, state <fingerprint>, check <hash>)
+```
+
+- **`state <fingerprint>`** is a hash over every tracked file except the spec itself, computed
+  at record time. The gate recomputes it for the commit that completed the spec (or the
+  uncommitted state); a file changed after recording invalidates the PASS.
+- **`check <hash>`** covers the other fields plus the verification command and expected output,
+  so hand-editing the result, or changing the command after recording, reopens the spec.
+- Task evidence recorded by `sdd-verify --task <ID> -- <command>` carries its own hash over the
+  date, exit code, and transcript, so an edited transcript is detected the same way.
+
+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, not the gate.
+
+**These 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; there is no key involved.
+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.
+
+**The framework does not guarantee bug-free code, and does not claim to.** It guarantees that
+a checked-off task has a command that actually ran, exited the code it says it did, against
+the file state it says it did. It does not guarantee that command was the right one to catch
+the bug that matters: a backend unit suite passing has, in practice, certified a UI as working
+while a CSS rule silently defeated the `hidden` attribute and stacked two screens on top of
+each other, invisible to any test that never renders a page. Writing a verification command
+that actually exercises the failure mode in play (a live render, not just an exit code, for
+anything a user perceives directly) is still the task author's judgment call -- the gate
+enforces that a command ran and its evidence is intact, not that the command was sufficient.
+
+## Execution environment
+
+Commands run in `specification.verifyShell` (default `/bin/sh` on macOS and Linux, `cmd.exe` on
+Windows) with a limit of `specification.verifyTimeoutSeconds` (default 900 seconds). The gate
+never runs a command from the spec on its own initiative; it only checks recorded results. On
+timeout, the whole process tree is killed, including background processes the command started,
+and output is decoded as a UTF-8 stream.
+
+The check finds the commit that completed the spec in 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 instead of guessing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdd-framework",
-  "version": "1.4.0",
+  "version": "1.5.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"
@@ -26,6 +26,8 @@
     "check:slop": "node scripts/check-copy-slop.js",
     "check:size": "node scripts/check-file-size.js",
     "check:spec": "node scripts/check-spec.js",
+    "check:constitution": "node scripts/check-constitution.js",
+    "add-rule": "node scripts/sdd-add-rule.js",
     "check:versions": "node scripts/check-versions.js",
     "install-hooks": "node scripts/install-git-hooks.js",
     "quality-gate": "node scripts/quality-gate.js"
@@ -44,6 +46,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tBeltty/agentic-sdd-framework.git"
+    "url": "git+https://github.com/tBeltty/agentic-sdd-framework.git"
   }
 }

package/scripts/check-constitution.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/check-constitution.js
+ *
+ * Non-blocking reminder about the project's constitution (.agents/AGENTS.md). It never
+ * fails the gate: neither the rule count nor the "why this rule exists" rationale is
+ * mandatory, and a project can deliberately ship with none of the 8 defaults, or with
+ * its own rules entirely. What this catches is the unattended case -- the wizard's
+ * placeholder rationale left standing in for a rule nobody actually wrote -- and nudges
+ * toward the 3 critical rules (verification, secrets, scope) before the first push.
+ *
+ * A rule counts as present only through its "<!-- sdd:rule id="..." tier="..." -->" tag,
+ * never by matching heading text. That is what lets an expert replace a default rule with
+ * their own equivalent (same id, entirely different title and wording, added with
+ * sdd-add-rule --fulfills=<id>) and still have the gate recognize it -- a declared,
+ * greppable fact instead of the gate guessing at semantic equivalence.
+ */
+
+const { readFile, WORKTREE } = require('./lib/git');
+const { runCheckCli } = require('./lib/cli');
+const { RULES, CRITICAL_IDS, MODERATE_IDS } = require('./lib/constitution-rules');
+
+const CONSTITUTION_PATH = '.agents/AGENTS.md';
+const PLACEHOLDER = /\[Document the incident or rationale here\./;
+const RULE_HEADING = /^##\s+\d+\./gm;
+const TAG = /<!--\s*sdd:rule\s+id="([\w-]+)"\s+tier="[\w-]+"\s*-->/g;
+const ESSENTIALS_HINT = 'secrets handling, mandatory verification, and scope bounding';
+
+// Rule blocks are separated by the template's "\n\n---\n\n"; a tag is only trusted if a
+// rule's own content (up to the next tag or end of file) has no unedited placeholder text.
+function fulfilledIds(text) {
+    const tags = [...text.matchAll(TAG)];
+    const fulfilled = new Set();
+    tags.forEach((tag, i) => {
+        const end = i + 1 < tags.length ? tags[i + 1].index : text.length;
+        const body = text.slice(tag.index, end);
+        if (!PLACEHOLDER.test(body)) fulfilled.add(tag[1]);
+    });
+    return fulfilled;
+}
+
+function labelsFor(ids) {
+    return ids.map(id => RULES[id].label).join(', ');
+}
+
+function run({ root, source = WORKTREE } = {}) {
+    const buffer = readFile(root, CONSTITUTION_PATH, source);
+    if (buffer === null) {
+        return {
+            ok: true,
+            report: `⚠️  No ${CONSTITUTION_PATH}. An agent has no constitution to load. Not required, ` +
+                `but worth deciding on purpose -- at least the essentials (${ESSENTIALS_HINT}) go a long way.`
+        };
+    }
+
+    const text = buffer.toString('utf8');
+    const totalHeadings = (text.match(RULE_HEADING) || []).length;
+    if (totalHeadings === 0) {
+        return {
+            ok: true,
+            report: `⚠️  ${CONSTITUTION_PATH} has no rules. That can be a deliberate choice, ` +
+                `but make sure it is the one you meant to make -- at least the essentials (${ESSENTIALS_HINT}) go a long way.`
+        };
+    }
+
+    const fulfilled = fulfilledIds(text);
+    const criticalFound = CRITICAL_IDS.filter(id => fulfilled.has(id));
+    const moderateFound = MODERATE_IDS.filter(id => fulfilled.has(id));
+    const missingCritical = CRITICAL_IDS.filter(id => !fulfilled.has(id));
+    const missingModerate = MODERATE_IDS.filter(id => !fulfilled.has(id));
+
+    if (missingCritical.length === 0 && missingModerate.length === 0) {
+        return { ok: true, report: `✅ ${CONSTITUTION_PATH}: ${totalHeadings} rule(s), all 3 critical and 5 moderate defaults fulfilled.` };
+    }
+
+    if (missingCritical.length === 0) {
+        return {
+            ok: true,
+            report: `💡 ${CONSTITUTION_PATH}: all 3 critical rules are set (${labelsFor(CRITICAL_IDS)}). ` +
+                `${missingModerate.length}/5 moderate suggestion(s) are not included -- optional: ${labelsFor(missingModerate)}.`
+        };
+    }
+
+    return {
+        ok: true,
+        report: `⚠️  ${CONSTITUTION_PATH} is missing ${missingCritical.length}/3 critical rule(s): ${labelsFor(missingCritical)}. ` +
+            `These back the framework's core promise (${ESSENTIALS_HINT}). Add them with the wizard, or write your own ` +
+            `equivalent with sdd-add-rule --fulfills=<id> -- see scripts/lib/constitution-rules.js for the ids.`
+    };
+}
+
+if (require.main === module) {
+    runCheckCli('📜 Agentic SDD Framework: Constitution Check', run);
+}
+
+module.exports = { run, fulfilledIds, PLACEHOLDER, CONSTITUTION_PATH };

package/scripts/lib/constitution-rules.js

@@ -0,0 +1,25 @@
+/**
+ * scripts/lib/constitution-rules.js
+ *
+ * Identity of the 8 default constitution rules the wizard offers, shared by the wizard
+ * (rule selection), the constitution check (what "critical" and "moderate" mean), and
+ * sdd-add-rule (validating --fulfills). The id is the stable handle: an expert can write
+ * their own rule text under the same id and the gate still recognizes it as fulfilling
+ * that slot, because it never matches on heading text, only on this tag.
+ */
+
+const RULES = {
+    'discovery-first': { tier: 'moderate', label: 'Discovery First' },
+    'evidence-driven-debugging': { tier: 'moderate', label: 'Evidence-Driven Debugging' },
+    'mandatory-verification': { tier: 'critical', label: 'Mandatory Verification' },
+    'closed-network-testing': { tier: 'moderate', label: 'Closed-Network Testing Isolation' },
+    'zero-trust-secrets': { tier: 'critical', label: 'Zero-Trust Secrets Management' },
+    'scope-bounding': { tier: 'critical', label: 'Scope Bounding & Atomic Progression' },
+    'factual-copy': { tier: 'moderate', label: 'Factual Technical Copy (No AI Slop)' },
+    'author-attribution': { tier: 'moderate', label: 'Author Attribution & Integrity' }
+};
+
+const CRITICAL_IDS = Object.keys(RULES).filter(id => RULES[id].tier === 'critical');
+const MODERATE_IDS = Object.keys(RULES).filter(id => RULES[id].tier === 'moderate');
+
+module.exports = { RULES, CRITICAL_IDS, MODERATE_IDS };

package/scripts/lib/provision.js

@@ -15,6 +15,7 @@ const fs = require('fs');
 const path = require('path');
 const { install: installHook } = require('../install-git-hooks');
 const { validateConfig, getIn } = require('./config');
+const { CRITICAL_IDS } = require('./constitution-rules');
 
 const FRAMEWORK_ROOT = path.resolve(__dirname, '..', '..');
 const MANAGED_MARKER = 'sdd:managed';
@@ -23,10 +24,12 @@ const MANAGED_MARKER = 'sdd:managed';
 const COPY_MARKER = '.sdd-managed-copy';
 const SPEC_MODES = ['lite', 'rigor'];
 const AST_ADAPTERS = ['ast-grep', 'graphify', 'ripgrep', 'lsp'];
+const RULE_SELECTIONS = ['all', 'critical', 'none'];
 const TOOL_DIR = '.sdd/scripts';
 const TOOL_FILES = [
     'quality-gate.js', 'verify-no-secrets.js', 'check-copy-slop.js', 'check-file-size.js', 'check-spec.js',
-    'check-versions.js', 'check-system-prerequisites.js', 'install-git-hooks.js', 'sdd-verify.js', 'lib'
+    'check-constitution.js', 'check-versions.js', 'check-system-prerequisites.js', 'install-git-hooks.js',
+    'sdd-verify.js', 'sdd-add-rule.js', 'lib'
 ];
 const TEMPLATES = [
     '.agents/AGENTS.template.md',
@@ -85,12 +88,38 @@ function normalizeAnswers(answers) {
     if (!AST_ADAPTERS.includes(answers.astAdapter)) {
         throw new Error(`Unknown AST adapter "${answers.astAdapter}". Valid: ${AST_ADAPTERS.join(', ')}.`);
     }
-    return { ...answers, specMode };
+    const rules = answers.rules || 'all';
+    if (!RULE_SELECTIONS.includes(rules)) {
+        throw new Error(`Unknown rules selection "${answers.rules}". Valid: ${RULE_SELECTIONS.join(', ')}.`);
+    }
+    return { ...answers, specMode, rules };
+}
+
+// Keeps or drops the wizard's 8 default rule blocks in .agents/AGENTS.md, tagged
+// "<!-- sdd:rule id="..." tier="..." -->" in the template, and renumbers what remains.
+// A block without a tag (hand-written, added later) is always kept -- this only ever
+// touches the day-0 defaults. Neither the rule count nor "why this rule exists" is
+// mandatory; "all" (default) and "none" are both valid choices, made once, on purpose.
+function filterConstitution(text, selection) {
+    if (selection === 'all') return text;
+    const keepIds = selection === 'critical' ? new Set(CRITICAL_IDS) : new Set();
+    const SEP = '\n\n---\n\n';
+    const [header, ...blocks] = text.split(SEP);
+    const kept = blocks.filter(block => {
+        const tag = block.match(/<!--\s*sdd:rule\s+id="([\w-]+)"/);
+        return !tag || keepIds.has(tag[1]);
+    });
+    let n = 0;
+    const renumbered = kept.map(block => block.replace(/^## \d+\./m, () => `## ${++n}.`));
+    return [header, ...renumbered].join(SEP);
 }
 
 function buildConfig(answers, existing) {
+    // No default architecture style: the strategic-cto skill's discovery interview decides
+    // this per project (see ADR-0001), and "clean-architecture" for every new project was a
+    // claim nobody actually made.
     const defaults = {
-        architecture: { style: 'clean-architecture', maxLocPerFile: 400 },
+        architecture: { style: 'Not yet decided (see docs/decisions/ADR-0001-stack-and-architecture.md)', maxLocPerFile: 400 },
         capabilities: { noAiSlop: { enabled: true } }
     };
     const generated = {
@@ -173,7 +202,8 @@ function renderEntrypoint(answers, gateCommand, config) {
         AST_ADAPTER: answers.astAdapter,
         RUNTIME: answers.runtime,
         SPEC_MODE: answers.specMode,
-        GATE_COMMAND: gateCommand
+        GATE_COMMAND: gateCommand,
+        ADD_RULE_COMMAND: `node ${toolDir}/sdd-add-rule.js`
     };
     const template = fs.readFileSync(path.join(FRAMEWORK_ROOT, '.agents/ENTRYPOINT.template.md'), 'utf8');
     return Object.entries(values).reduce((out, [key, value]) => replaceLiteral(out, `{{${key}}}`, value), template);
@@ -252,7 +282,7 @@ function provision(rawAnswers, { target = process.cwd(), force = false, log = co
     record(existingConfig ? 'updated' : 'created', 'sdd.config.json');
 
     // 3. Governance documents.
-    createFromTemplate('.agents/AGENTS.template.md', '.agents/AGENTS.md');
+    createFromTemplate('.agents/AGENTS.template.md', '.agents/AGENTS.md', t => filterConstitution(t, answers.rules));
     createFromTemplate('.agents/CONTEXT.template.md', '.agents/CONTEXT.md', t => fillContext(t, answers, config));
     // Documents go where the config says, so the gate checks the files sdd-init created.
     const specFile = getIn(config, 'specification.specFile', 'docs/SPEC.md');

package/scripts/quality-gate.js

@@ -29,6 +29,7 @@ const CHECKS = [
     { title: '✍️  No-AI-Slop Copy Linter', module: require('./check-copy-slop') },
     { title: '📏 File Size Limit', module: require('./check-file-size') },
     { title: '📋 Specification Check', module: require('./check-spec') },
+    { title: '📜 Constitution Check', module: require('./check-constitution') },
     { title: '🏷️  Version Sync Check', module: require('./check-versions') }
 ];
 

package/scripts/sdd-add-rule.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/sdd-add-rule.js
+ *
+ * The sanctioned way to add a rule to .agents/AGENTS.md after day-0. Appends a correctly
+ * numbered, tagged rule block instead of an agent freehanding "always do X" into chat
+ * memory, CLAUDE.md, or an unrelated doc -- none of which every agent reads, and none of
+ * which the constitution check ever looks at.
+ *
+ * Usage:
+ *   sdd-add-rule --title "<title>" --rule "<the operating rule>" --why "<why this rule exists>"
+ *                [--fulfills=<id>]
+ *
+ *   --fulfills replaces one of the 8 default rules with the caller's own equivalent: the
+ *   new block is tagged with that rule's id, so the constitution check recognizes it as
+ *   fulfilling that slot even though the heading and text are entirely custom. See
+ *   scripts/lib/constitution-rules.js for the known ids.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { repoRoot } = require('./lib/git');
+const { RULES } = require('./lib/constitution-rules');
+
+const CONSTITUTION_PATH = '.agents/AGENTS.md';
+const FLAGS = ['title', 'rule', 'why', 'fulfills'];
+const PLACEHOLDER = /\[.*\]/;
+const USAGE = 'Usage: sdd-add-rule --title "<title>" --rule "<rule>" --why "<why this rule exists>" [--fulfills=<id>]';
+
+function parseArgs(argv) {
+    const values = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const match = arg.match(/^--([a-z]+)(?:=(.*))?$/);
+        if (!match || !FLAGS.includes(match[1])) throw new Error(`Unknown argument "${arg}". ${USAGE}`);
+        const [, name, inline] = match;
+        const value = inline !== undefined ? inline : argv[++i];
+        if (value === undefined || (inline === undefined && value.startsWith('--'))) {
+            throw new Error(`--${name} needs a value. ${USAGE}`);
+        }
+        values[name] = value;
+    }
+    return values;
+}
+
+function slugify(title) {
+    return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'custom-rule';
+}
+
+function nextNumber(text) {
+    const numbers = [...text.matchAll(/^## (\d+)\./gm)].map(m => Number(m[1]));
+    return numbers.length ? Math.max(...numbers) + 1 : 1;
+}
+
+function run({ root, argv }) {
+    let values;
+    try {
+        values = parseArgs(argv);
+    } catch (error) {
+        return { ok: false, report: `❌ ${error.message}` };
+    }
+    const { title, rule, why, fulfills } = values;
+    const missing = ['title', 'rule', 'why'].filter(name => !values[name] || !values[name].trim());
+    if (missing.length > 0) {
+        return { ok: false, report: `❌ --${missing.join(', --')} required and cannot be empty. A rule with no stated rationale is exactly the placeholder problem this command exists to avoid.` };
+    }
+    if ([title, rule, why].some(v => PLACEHOLDER.test(v))) {
+        return { ok: false, report: '❌ --title, --rule, and --why must be real text, not a bracketed placeholder.' };
+    }
+    if (fulfills && !RULES[fulfills]) {
+        return { ok: false, report: `❌ Unknown --fulfills id "${fulfills}". Known ids: ${Object.keys(RULES).join(', ')}.` };
+    }
+
+    const file = path.join(root, CONSTITUTION_PATH);
+    if (!fs.existsSync(file)) {
+        return { ok: false, report: `❌ ${CONSTITUTION_PATH} does not exist. Run sdd-init first.` };
+    }
+    const text = fs.readFileSync(file, 'utf8');
+    const number = nextNumber(text);
+    const id = fulfills || slugify(title);
+    const tier = fulfills ? RULES[fulfills].tier : 'custom';
+    const block = [
+        '---', '',
+        `<!-- sdd:rule id="${id}" tier="${tier}" -->`,
+        `## ${number}. ${title}`,
+        `* **Rule:** ${rule}`,
+        '* **Why this rule exists:**',
+        `  > ${why}`,
+        ''
+    ].join('\n');
+    fs.writeFileSync(file, `${text.replace(/\n*$/, '')}\n\n${block}`);
+    const recognized = fulfills ? ` Recognized by the gate as fulfilling the "${fulfills}" ${tier} rule.` : '';
+    return { ok: true, report: `✅ Added rule ${number} ("${title}") to ${CONSTITUTION_PATH}.${recognized}` };
+}
+
+if (require.main === module) {
+    let result;
+    try {
+        result = run({ root: repoRoot(), argv: process.argv.slice(2) });
+    } catch (error) {
+        result = { ok: false, report: `❌ ${error.message}` };
+    }
+    (result.ok ? console.log : console.error)(result.report);
+    process.exit(result.ok ? 0 : 1);
+}
+
+module.exports = { run, slugify, nextNumber };

package/scripts/sdd-init.js

@@ -18,6 +18,7 @@
  *   --mode=lite|rigor     Specification depth (default: lite)
  *   --ast=<adapter>       ast-grep | graphify | ripgrep | lsp (default: ast-grep)
  *   --concurrency=, --hardware=, --workload=   Discovery answers
+ *   --rules=all|critical|none   Constitution rules to include (default: all)
  *   --i18n, --pwa         Enable the matching capability flags
  *   --force               Refresh copied skills and templates in install mode
  *   --help                Print this help
@@ -30,12 +31,12 @@ 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 VALUE_FLAGS = ['target', 'name', 'runtime', 'mode', 'ast', 'concurrency', 'hardware', 'workload', 'rules'];
 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]`;
+                [--rules=all|critical|none] [--i18n] [--pwa] [--force] [--help]`;
 
 function parseArgs(argv) {
     const values = new Map();
@@ -175,8 +176,15 @@ async function runGuidedMode() {
     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';
 
+    console.log('\n--- Step 6: Constitution Rules ---');
+    console.log('  [1] All 8 (default): 3 critical + 5 moderate suggestions.');
+    console.log('  [2] Critical only: verification, secrets, and scope -- the 3 the framework leans on most.');
+    console.log('  [3] None: start from a blank constitution.');
+    const ruleChoices = { '1': 'all', '2': 'critical', '3': 'none' };
+    const rules = ruleChoices[await ask('Select Rules (1-3)', '1')] || 'all';
+
     rl.close();
-    bootstrap({ projectName, runtime, specMode, astAdapter, concurrency, hardware, workload, i18n, pwa });
+    bootstrap({ projectName, runtime, specMode, astAdapter, rules, concurrency, hardware, workload, i18n, pwa });
 }
 
 function runExpressMode() {
@@ -187,6 +195,7 @@ function runExpressMode() {
         runtime: getArgValue('runtime', DEFAULTS.runtime),
         specMode: getArgValue('mode', EXISTING.specMode || 'lite').toLowerCase(),
         astAdapter: getArgValue('ast', EXISTING.astAdapter || 'ast-grep').toLowerCase(),
+        rules: getArgValue('rules', 'all').toLowerCase(),
         concurrency: getArgValue('concurrency', DEFAULTS.concurrency),
         hardware: getArgValue('hardware', DEFAULTS.hardware),
         workload: getArgValue('workload', DEFAULTS.workload),
@@ -218,7 +227,9 @@ function bootstrap(answers) {
         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 toolDir = result.gateCommand.replace(/^node /, '').replace(/\/quality-gate\.js$/, '');
+    console.log('  2. Optional: record the incident or rationale behind each rule in .agents/AGENTS.md.');
+    console.log(`     Add a new rule later with node ${toolDir}/sdd-add-rule.js, not memory or another doc.`);
     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.`);

package/sdd.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4.0",
+  "version": "1.5.0",
   "project": {
     "name": "agentic-sdd-framework",
     "type": "framework",

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

@@ -1,40 +0,0 @@
-#!/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."