specky-sdd 3.11.1 → 3.12.0

package/.apm/hooks/scripts/specky-contract-context.mjs

@@ -1,219 +1,235 @@
 #!/usr/bin/env node
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 
 function fail(message) {
-    console.error(`[specky-contract-context] ${message}`);
-    process.exit(2);
+  console.error(`[specky-contract-context] ${message}`);
+  process.exit(2);
 }
 
 function readHookInput() {
-    const fromEnvironment = process.env.SDD_HOOK_INPUT;
-    if (fromEnvironment?.trim()) return fromEnvironment;
-    if (process.stdin.isTTY) return "";
-    try {
-        return readFileSync(0, "utf8");
-    } catch {
-        return "";
-    }
+  const fromEnvironment = process.env.SDD_HOOK_INPUT;
+  if (fromEnvironment?.trim()) return fromEnvironment;
+  if (process.stdin.isTTY) return "";
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
 }
 
 function parseInput(raw) {
-    if (!raw.trim()) return {};
-    try {
-        return JSON.parse(raw);
-    } catch {
-        return {};
-    }
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
 }
 
 function objects(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
-    const record = value;
-    return [
-        record,
-        record.tool_input,
-        record.toolInput,
-        record.arguments,
-        record.input,
-        record.params,
-        record.params?.arguments,
-        record.request?.params?.arguments,
-    ].filter((candidate) => typeof candidate === "object" && candidate !== null && !Array.isArray(candidate));
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
+  const record = value;
+  return [
+    record,
+    record.tool_input,
+    record.toolInput,
+    record.arguments,
+    record.input,
+    record.params,
+    record.params?.arguments,
+    record.request?.params?.arguments,
+  ].filter(
+    (candidate) => typeof candidate === "object" && candidate !== null && !Array.isArray(candidate),
+  );
 }
 
 function findString(input, keys) {
-    for (const candidate of objects(input)) {
-        for (const key of keys) {
-            const value = candidate[key];
-            if (typeof value === "string" && value.trim()) return value.trim();
-        }
+  for (const candidate of objects(input)) {
+    for (const key of keys) {
+      const value = candidate[key];
+      if (typeof value === "string" && value.trim()) return value.trim();
     }
-    return undefined;
+  }
+  return undefined;
 }
 
 function safeRelativePath(value, label) {
-    if (!value || value.startsWith("/") || value.startsWith("\\") || /^[A-Za-z]:/.test(value)) {
-        fail(`${label} must be a workspace-relative path.`);
-    }
-    const segments = value.split(/[\\/]/);
-    if (segments.includes("..") || value.includes("\0")) fail(`${label} contains unsafe traversal.`);
-    return segments.filter((segment) => segment && segment !== ".").join("/");
+  if (!value || value.startsWith("/") || value.startsWith("\\") || /^[A-Za-z]:/.test(value)) {
+    fail(`${label} must be a workspace-relative path.`);
+  }
+  const segments = value.split(/[\\/]/);
+  if (segments.includes("..") || value.includes("\0")) fail(`${label} contains unsafe traversal.`);
+  return segments.filter((segment) => segment && segment !== ".").join("/");
 }
 
 function canonicalize(value) {
-    if (Array.isArray(value)) return value.map(canonicalize);
-    if (typeof value !== "object" || value === null) return value;
-    return Object.keys(value)
-        .sort((left, right) => left.localeCompare(right))
-        .reduce((result, key) => {
-            result[key] = canonicalize(value[key]);
-            return result;
-        }, {});
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.keys(value)
+    .sort((left, right) => left.localeCompare(right))
+    .reduce((result, key) => {
+      result[key] = canonicalize(value[key]);
+      return result;
+    }, {});
 }
 
 function fingerprintContract(contract) {
-    const { fingerprint: _fingerprint, ...snapshot } = contract;
-    return createHash("sha256").update(JSON.stringify(canonicalize(snapshot))).digest("hex");
+  const { fingerprint: _fingerprint, ...snapshot } = contract;
+  return createHash("sha256")
+    .update(JSON.stringify(canonicalize(snapshot)))
+    .digest("hex");
 }
 
 function safeEqualHex(left, right) {
-    if (!/^[a-f0-9]{64}$/.test(left) || !/^[a-f0-9]{64}$/.test(right)) return false;
-    return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+  if (!/^[a-f0-9]{64}$/.test(left) || !/^[a-f0-9]{64}$/.test(right)) return false;
+  return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
 }
 
 function shellQuote(value) {
-    return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
 }
 
 function resolveContext() {
-    const workspace = resolve(process.env.SPECKY_HOOK_WORKSPACE ?? process.cwd());
-    const input = parseInput(readHookInput());
-    const requestedSpecDir = process.env.SDD_SPEC_DIR ?? findString(input, ["spec_dir", "specDir"]);
-    const requestedFeatureNumber = process.env.SDD_FEATURE_NUMBER
-        ?? findString(input, ["feature_number", "featureNumber"]);
-
-    if (!requestedSpecDir || !requestedFeatureNumber) {
-        return { active: false, reason: "missing explicit SDD_SPEC_DIR/SDD_FEATURE_NUMBER context" };
-    }
-    const specDir = safeRelativePath(requestedSpecDir, "spec_dir");
-    if (!/^\d{3}$/.test(requestedFeatureNumber)) fail("feature_number must be exactly three digits.");
-
-    const specRoot = resolve(workspace, specDir);
-    if (!existsSync(specRoot)) fail(`spec root does not exist: ${specDir}`);
-    const matches = readdirSync(specRoot, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory() && entry.name.startsWith(`${requestedFeatureNumber}-`));
-    if (matches.length !== 1) {
-        fail(`feature ${requestedFeatureNumber} must resolve to exactly one directory in ${specDir}; found ${matches.length}.`);
-    }
-
-    const featureName = matches[0].name.slice(4);
-    const featureDirectory = `${specDir}/${matches[0].name}`;
-    const statePath = resolve(workspace, featureDirectory, ".sdd-state.json");
-    const signaturePath = `${statePath}.sig`;
-    if (!existsSync(statePath) || !existsSync(signaturePath)) {
-        fail(`feature ${requestedFeatureNumber} requires signed v5 state at ${featureDirectory}/.sdd-state.json.`);
-    }
-
-    const raw = readFileSync(statePath, "utf8");
-    let state;
-    try {
-        state = JSON.parse(raw);
-    } catch {
-        fail(`state is not valid JSON: ${relative(workspace, statePath)}`);
-    }
-    if (state.version !== "5.0.0") fail(`state version ${String(state.version)} requires migration.`);
-
-    const key = process.env.SDD_STATE_KEY
-        ?? createHash("sha256").update(`specky-state-v1:${workspace}`).digest("hex");
-    const expectedSignature = createHmac("sha256", key).update(raw).digest("hex");
-    const storedSignature = readFileSync(signaturePath, "utf8").trim();
-    if (!safeEqualHex(storedSignature, expectedSignature)) fail("feature state signature verification failed.");
-
-    if (
-        state.feature?.number !== requestedFeatureNumber ||
-        state.feature?.name !== featureName ||
-        state.feature?.directory !== featureDirectory
-    ) {
-        fail(`feature state identity does not match ${featureDirectory}.`);
-    }
-    if (!state.contract || fingerprintContract(state.contract) !== state.contract.fingerprint) {
-        fail("feature contract fingerprint verification failed.");
-    }
-    if (!Array.isArray(state.contract.phases) || !state.contract.phases.includes(state.current_phase)) {
-        fail(`current phase ${String(state.current_phase)} is not enabled by the feature contract.`);
-    }
-
-    const capabilities = Array.isArray(state.contract.capabilities) ? state.contract.capabilities : [];
-    const capabilityConfig = state.contract.capability_config ?? {};
-    const configuredCapabilities = Object.keys(capabilityConfig).sort();
-    const declaredCapabilities = [...new Set(capabilities)].sort();
-    if (JSON.stringify(configuredCapabilities) !== JSON.stringify(declaredCapabilities)) {
-        fail("capabilities and capability_config keys do not match.");
-    }
-
-    return {
-        active: true,
-        workspace,
-        specDir,
-        featureNumber: requestedFeatureNumber,
-        featureName,
-        featureDirectory,
-        statePath: relative(workspace, statePath).split(sep).join("/"),
-        phase: state.current_phase,
-        contract: state.contract,
-        gateDecision: state.gate_decision?.decision ?? "",
-    };
+  const workspace = resolve(process.env.SPECKY_HOOK_WORKSPACE ?? process.cwd());
+  const input = parseInput(readHookInput());
+  const requestedSpecDir = process.env.SDD_SPEC_DIR ?? findString(input, ["spec_dir", "specDir"]);
+  const requestedFeatureNumber =
+    process.env.SDD_FEATURE_NUMBER ?? findString(input, ["feature_number", "featureNumber"]);
+
+  if (!requestedSpecDir || !requestedFeatureNumber) {
+    return { active: false, reason: "missing explicit SDD_SPEC_DIR/SDD_FEATURE_NUMBER context" };
+  }
+  const specDir = safeRelativePath(requestedSpecDir, "spec_dir");
+  if (!/^\d{3}$/.test(requestedFeatureNumber)) fail("feature_number must be exactly three digits.");
+
+  const specRoot = resolve(workspace, specDir);
+  if (!existsSync(specRoot)) fail(`spec root does not exist: ${specDir}`);
+  const matches = readdirSync(specRoot, { withFileTypes: true }).filter(
+    (entry) => entry.isDirectory() && entry.name.startsWith(`${requestedFeatureNumber}-`),
+  );
+  if (matches.length !== 1) {
+    fail(
+      `feature ${requestedFeatureNumber} must resolve to exactly one directory in ${specDir}; found ${matches.length}.`,
+    );
+  }
+
+  const featureName = matches[0].name.slice(4);
+  const featureDirectory = `${specDir}/${matches[0].name}`;
+  const statePath = resolve(workspace, featureDirectory, ".sdd-state.json");
+  const signaturePath = `${statePath}.sig`;
+  if (!existsSync(statePath) || !existsSync(signaturePath)) {
+    fail(
+      `feature ${requestedFeatureNumber} requires signed v5 state at ${featureDirectory}/.sdd-state.json.`,
+    );
+  }
+
+  const raw = readFileSync(statePath, "utf8");
+  let state;
+  try {
+    state = JSON.parse(raw);
+  } catch {
+    fail(`state is not valid JSON: ${relative(workspace, statePath)}`);
+  }
+  if (state.version !== "5.0.0") fail(`state version ${String(state.version)} requires migration.`);
+
+  const key =
+    process.env.SDD_STATE_KEY ??
+    createHash("sha256").update(`specky-state-v1:${workspace}`).digest("hex");
+  const expectedSignature = createHmac("sha256", key).update(raw).digest("hex");
+  const storedSignature = readFileSync(signaturePath, "utf8").trim();
+  if (!safeEqualHex(storedSignature, expectedSignature))
+    fail("feature state signature verification failed.");
+
+  if (
+    state.feature?.number !== requestedFeatureNumber ||
+    state.feature?.name !== featureName ||
+    state.feature?.directory !== featureDirectory
+  ) {
+    fail(`feature state identity does not match ${featureDirectory}.`);
+  }
+  if (!state.contract || fingerprintContract(state.contract) !== state.contract.fingerprint) {
+    fail("feature contract fingerprint verification failed.");
+  }
+  if (
+    !Array.isArray(state.contract.phases) ||
+    !state.contract.phases.includes(state.current_phase)
+  ) {
+    fail(`current phase ${String(state.current_phase)} is not enabled by the feature contract.`);
+  }
+
+  const capabilities = Array.isArray(state.contract.capabilities)
+    ? state.contract.capabilities
+    : [];
+  const capabilityConfig = state.contract.capability_config ?? {};
+  const configuredCapabilities = Object.keys(capabilityConfig).sort();
+  const declaredCapabilities = [...new Set(capabilities)].sort();
+  if (JSON.stringify(configuredCapabilities) !== JSON.stringify(declaredCapabilities)) {
+    fail("capabilities and capability_config keys do not match.");
+  }
+
+  return {
+    active: true,
+    workspace,
+    specDir,
+    featureNumber: requestedFeatureNumber,
+    featureName,
+    featureDirectory,
+    statePath: relative(workspace, statePath).split(sep).join("/"),
+    phase: state.current_phase,
+    contract: state.contract,
+    gateDecision: state.gate_decision?.decision ?? "",
+  };
 }
 
 function printShell(context) {
-    const contract = context.contract ?? {};
-    const capabilities = Array.isArray(contract.capabilities) ? contract.capabilities : [];
-    const release = contract.capability_config?.release;
-    const tdd = contract.capability_config?.tdd;
-    const compliance = contract.capability_config?.compliance;
-    const development = contract.capability_config?.["dev-environment"];
-    const iac = contract.capability_config?.iac;
-    const values = {
-        SPECKY_CONTEXT_ACTIVE: context.active ? "1" : "0",
-        SPECKY_CONTEXT_REASON: context.reason ?? "",
-        SPECKY_SPEC_DIR: context.specDir ?? "",
-        SPECKY_FEATURE_NUMBER: context.featureNumber ?? "",
-        SPECKY_FEATURE_NAME: context.featureName ?? "",
-        SPECKY_FEATURE_DIR: context.featureDirectory ?? "",
-        SPECKY_STATE_FILE: context.statePath ?? "",
-        SPECKY_PHASE: context.phase ?? "",
-        SPECKY_CONTRACT_ID: contract.id ?? "",
-        SPECKY_CONTRACT_FINGERPRINT: contract.fingerprint ?? "",
-        SPECKY_LIFECYCLE: contract.lifecycle ?? "",
-        SPECKY_WORKLOAD: contract.workload ?? "",
-        SPECKY_EXECUTION_MODE: contract.execution_mode ?? "",
-        SPECKY_CAPABILITIES: capabilities.join(","),
-        SPECKY_GATE_DECISION: context.gateDecision ?? "",
-        SPECKY_RELEASE_ENABLED: release ? "1" : "0",
-        SPECKY_BRANCH_PREFIX: release?.branch_prefix ?? "",
-        SPECKY_BASE_BRANCH: release?.base_branch ?? "",
-        SPECKY_CHECKPOINTS_REQUIRED: release?.checkpoints ? "1" : "0",
-        SPECKY_TDD_ENABLED: tdd ? "1" : "0",
-        SPECKY_TDD_THRESHOLD: tdd ? String(tdd.coverage_threshold) : "",
-        SPECKY_COMPLIANCE_ENABLED: compliance ? "1" : "0",
-        SPECKY_COMPLIANCE_FRAMEWORKS: compliance?.frameworks?.join(",") ?? "",
-        SPECKY_DEV_ENV_ENABLED: development ? "1" : "0",
-        SPECKY_DEV_LANGUAGE: development?.language ?? "",
-        SPECKY_IAC_ENABLED: iac ? "1" : "0",
-        SPECKY_IAC_PROVIDER: iac?.provider ?? "",
-        SPECKY_IAC_CLOUD: iac?.cloud ?? "",
-    };
-    for (const [key, value] of Object.entries(values)) console.log(`${key}=${shellQuote(value)}`);
+  const contract = context.contract ?? {};
+  const capabilities = Array.isArray(contract.capabilities) ? contract.capabilities : [];
+  const release = contract.capability_config?.release;
+  const tdd = contract.capability_config?.tdd;
+  const compliance = contract.capability_config?.compliance;
+  const development = contract.capability_config?.["dev-environment"];
+  const iac = contract.capability_config?.iac;
+  const values = {
+    SPECKY_CONTEXT_ACTIVE: context.active ? "1" : "0",
+    SPECKY_CONTEXT_REASON: context.reason ?? "",
+    SPECKY_SPEC_DIR: context.specDir ?? "",
+    SPECKY_FEATURE_NUMBER: context.featureNumber ?? "",
+    SPECKY_FEATURE_NAME: context.featureName ?? "",
+    SPECKY_FEATURE_DIR: context.featureDirectory ?? "",
+    SPECKY_STATE_FILE: context.statePath ?? "",
+    SPECKY_PHASE: context.phase ?? "",
+    SPECKY_CONTRACT_ID: contract.id ?? "",
+    SPECKY_CONTRACT_FINGERPRINT: contract.fingerprint ?? "",
+    SPECKY_LIFECYCLE: contract.lifecycle ?? "",
+    SPECKY_WORKLOAD: contract.workload ?? "",
+    SPECKY_EXECUTION_MODE: contract.execution_mode ?? "",
+    SPECKY_CAPABILITIES: capabilities.join(","),
+    SPECKY_GATE_DECISION: context.gateDecision ?? "",
+    SPECKY_RELEASE_ENABLED: release ? "1" : "0",
+    SPECKY_BRANCH_PREFIX: release?.branch_prefix ?? "",
+    SPECKY_BASE_BRANCH: release?.base_branch ?? "",
+    SPECKY_CHECKPOINTS_REQUIRED: release?.checkpoints ? "1" : "0",
+    SPECKY_TDD_ENABLED: tdd ? "1" : "0",
+    SPECKY_TDD_THRESHOLD: tdd ? String(tdd.coverage_threshold) : "",
+    SPECKY_COMPLIANCE_ENABLED: compliance ? "1" : "0",
+    SPECKY_COMPLIANCE_FRAMEWORKS: compliance?.frameworks?.join(",") ?? "",
+    SPECKY_DEV_ENV_ENABLED: development ? "1" : "0",
+    SPECKY_DEV_LANGUAGE: development?.language ?? "",
+    SPECKY_IAC_ENABLED: iac ? "1" : "0",
+    SPECKY_IAC_PROVIDER: iac?.provider ?? "",
+    SPECKY_IAC_CLOUD: iac?.cloud ?? "",
+  };
+  for (const [key, value] of Object.entries(values)) console.log(`${key}=${shellQuote(value)}`);
 }
 
 const command = process.argv[2] ?? "shell";
 const context = resolveContext();
 if (command === "json") {
-    console.log(JSON.stringify(context));
+  console.log(JSON.stringify(context));
 } else if (command === "shell") {
-    printShell(context);
+  printShell(context);
 } else {
-    fail(`unknown command ${command}`);
+  fail(`unknown command ${command}`);
 }

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.12.0] - 2026-07-20
+
+### Added
+
+- Backward-compatible `mode: "explicit" | "auto"` inputs for `sdd_generate_diagram` and `sdd_generate_all_diagrams`; explicit remains the default.
+- Evidence-grounded automatic Mermaid generation for C4 context, sequence, ER, and deployment diagrams from `SPECIFICATION.md` and `DESIGN.md`.
+- Source evidence tracking for derived actors, requirements, exchanges, use cases, components, entities, and deployment nodes.
+- Biome lint and format integration with `biome.json` and npm scripts (`lint`, `lint:fix`, `format`).
+- Unit tests for previously uncovered modules: `slug`, `routing-helper`, `audit-tools`, `transcript-tools`, `cli-commands`, `vscode-settings-writer`, and `agent-skills`.
+- `.specs/001-biome-lint-integration/` spec package for dogfooding the SDD pipeline on Specky itself.
+
+### Changed
+
+- Terraform resource discovery now uses canonical `module:service` keys derived from the relevant `DESIGN.md` sections, with clause-scoped handling for exclusions such as `without`, `avoid`, and `not use`.
+- Diagram-set auto mode synthesizes and validates the complete contracted set in memory before atomically writing `DIAGRAMS.md`.
+- Coverage thresholds ratcheted to 89% statements, 77% branches, 95% functions, and 90% lines.
+- Test suite expanded from 663 to 1019 tests across 99 files.
+
+### Fixed
+
+- Unsupported Terraform resource types now fail preflight with an actionable error instead of emitting placeholder comments.
+- `specky compile` now validates and reads instruction primitives through a single file descriptor, eliminating the CodeQL-reported filesystem race.
+- Feature directory identifiers use stable forward-slash separators in user-facing MCP errors on Windows.
+- Integration test and hook timeouts allow subprocess-heavy tests to complete under full-suite CPU contention.
+- Biome warnings for unused imports, unused variables, optional chains, and static-only classes.
+- `useOptionalChain` violations in `settings-merger`, `audit-logger`, `http-auth`, and `token-table`.
+- `noUnusedVariables` violations in `pipeline.ts`, `cross-analyzer.ts`, and `vscode-settings-writer.ts`.
+- `noUnusedFunctionParameters` violations in `metrics.ts` and `turnkey.ts`.
+- `noStaticOnlyClass` suppressions documented for `DependencyGraph` and `MethodologyGuide`.
+
 ## [3.11.1] - 2026-07-16
 
 ### Added

package/README.md

@@ -60,7 +60,7 @@
 | **Enterprise** | [Compliance Frameworks](#compliance-frameworks) | HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001 |
 | | [Enterprise Ready](#enterprise-ready) | Security, audit trail, quality gates |
 | **Platform** | [The SDD Platform](#the-spec-driven-development-platform) | Built on Spec-Kit, everything included |
-| | [Roadmap](#roadmap) | v3.11.1 current, future capabilities planned |
+| | [Roadmap](#roadmap) | v3.12.0 current, future capabilities planned |
 
 ## What is Specky?
 
@@ -106,7 +106,7 @@ specky install --target=opencode     # OpenCode
 specky install --target=agent-skills # Skills-only shared .agents/skills bundle
 ```
 
-> **Important:** Prefer `--target=...`. The legacy `--ide` flag still works for `copilot`, `claude`, `both`, and `auto`, but it is deprecated in favor of APM-style targets. If Copilot is installed in a workspace, Specky strips Claude hooks from `.claude/settings.json` to prevent Copilot cross-read blocks. See [docs/INSTALL.md](docs/INSTALL.md) for details.
+> **Important:** Prefer `--target=...`. The legacy `--ide` flag still works for `copilot`, `claude`, `both`, and `auto`, but it is deprecated in favor of APM-style targets. Copilot + Claude in the same workspace is supported (`--target=both` or `all`); Specky strips Claude hooks from `.claude/settings.json` so Copilot cannot cross-read them. Prefer a **single** target if you need Claude lifecycle hooks. See [docs/INSTALL.md](docs/INSTALL.md) for details.
 
 Or per-project (for teams — pins version in `package.json`, run via `npx`):
 
@@ -215,8 +215,8 @@ Specky adds a **deterministic engine** between your intent and your code:
 | EARS validation (programmatic, not AI guessing) | 6 patterns enforced at schema level |
 | Enforced pipeline (not suggestions) | Contract-specific phases, central analysis gate, optional configured LGTM blocking |
 | Pre/post hooks on every phase | specky-artifact-validator, specky-branch-validator, specky-phase-gate, specky-lgtm-gate |
-| Workload-specific diagrams | Exact required manifest, explicit Mermaid/FigJam payloads, source evidence references |
-| Infrastructure as Code | Terraform from persisted cloud/resources; DESIGN.md evidence required |
+| Workload-specific diagrams | Explicit evidence validation or deterministic auto-generation from specification/design content |
+| Infrastructure as Code | DESIGN.md-driven Terraform with exact resource templates and fail-fast preflight |
 | Work item export | GitHub Issues, Azure Boards, Jira via MCP-to-MCP routing |
 | 5 compliance frameworks | HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001 with explicit control-ID evidence |
 | Cross-artifact traceability | Requirement to design to task to test to code |
@@ -566,7 +566,7 @@ The AI calls:
 
 - `sdd_run_analysis` → completeness audit, orphaned criteria detection
 - `sdd_compliance_check` → evaluates the persisted SOC2 pack using evidence keyed by control ID
-- `sdd_generate_all_diagrams` → validates exactly the workload-required Mermaid payloads against source evidence
+- `sdd_generate_all_diagrams` → validates explicit Mermaid payloads or uses `mode: "auto"` to derive the complete supported set from source evidence before an atomic write
 
 ### Step 6: Generate infrastructure and tests
 
@@ -576,7 +576,7 @@ The AI calls:
 
 The AI calls:
 
-- `sdd_generate_iac` → Terraform for the exact cloud/resources stored in the feature contract
+- `sdd_generate_iac` → Terraform for the exact cloud/resources grounded in the relevant `DESIGN.md` sections; excluded or unsupported resources fail before files are written
 - `sdd_generate_dockerfile` → Dockerfile/compose from the persisted development stack
 - `sdd_generate_tests` → executable tests from fingerprinted requirement bindings
 
@@ -839,16 +839,18 @@ All artifacts are saved in [`.specs/NNN-feature/`](#where-specifications-live).
 
 | Tool | Description |
 |------|-------------|
-| `sdd_generate_diagram` | Single Mermaid diagram validated against the workload contract's required set |
-| `sdd_generate_all_diagrams` | The exact diagram set the feature contract requires, written atomically |
+| `sdd_generate_diagram` | Explicit Mermaid validation by default, or evidence-grounded auto-generation for supported types |
+| `sdd_generate_all_diagrams` | Explicit validation or atomic auto-generation of the complete supported contracted set |
 | `sdd_generate_user_stories` | User stories with flow diagrams (web-application workload) |
 | `sdd_figma_diagram` | FigJam-ready diagram via Figma MCP |
 
+`mode: "explicit"` remains the compatibility default and requires caller-supplied Mermaid plus evidence references. `mode: "auto"` derives C4 context, sequence, ER, and deployment diagrams from `SPECIFICATION.md` and `DESIGN.md`; unsupported contracted types fail before any file is written.
+
 ### Infrastructure as Code (3)
 
 | Tool | Description |
 |------|-------------|
-| `sdd_generate_iac` | Terraform/Bicep from architecture design |
+| `sdd_generate_iac` | Terraform from canonical `module:service` resources grounded in relevant `DESIGN.md` sections; unsupported templates fail preflight |
 | `sdd_validate_iac` | Validation via Terraform MCP + Azure MCP |
 | `sdd_generate_dockerfile` | Dockerfile + docker-compose from tech stack |
 
@@ -1248,6 +1250,10 @@ npm test
 # Run tests with coverage report
 npm run test:coverage
 
+# Lint and format with Biome
+npm run lint
+npm run format
+
 # Development mode (auto-reload on file changes)
 npm run dev
 
@@ -1255,9 +1261,9 @@ npm run dev
 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js 2>/dev/null
 
 # Run the published image from GHCR (multi-arch: linux/amd64 + linux/arm64)
-docker pull ghcr.io/paulasilvatech/specky:latest        # or pin a release: :3.11.1
+docker pull ghcr.io/paulasilvatech/specky:latest        # or pin a release: :3.12.0
 docker run --rm -p 3200:3200 ghcr.io/paulasilvatech/specky:latest
-curl http://localhost:3200/health                       # -> {"status":"ok","version":"3.11.1"}
+curl http://localhost:3200/health                       # -> {"status":"ok","version":"3.12.0"}
 
 # Or build and run locally from source
 docker build -t specky-sdd:dev .
@@ -1272,7 +1278,7 @@ deployments (enterprise profile, token auth, TLS proxy, private packages) see
 
 ## Roadmap
 
-### v3.11.1 (current)
+### v3.12.0 (current)
 
 | Capability | Status |
 |------------|--------|
@@ -1281,7 +1287,8 @@ deployments (enterprise profile, token auth, TLS proxy, private packages) see
 | Target-specific install: `--target=copilot`, `claude`, `cursor`, `opencode`, or `agent-skills` | Stable |
 | Copilot-safe hook manifests (no lifecycle event cross-read) | Stable |
 | Phase validation on every tool with gate enforcement | Stable |
-| Workload-contracted diagram sets (C4, sequence, ER, DFD, deployment, network) | Stable |
+| Evidence-grounded diagram generation with explicit and auto modes | Stable |
+| DESIGN.md-driven Terraform with unsupported-resource preflight | Stable |
 | 12-section system design template (C4 model, security, infrastructure) | Stable |
 | Enriched interactive responses on all tools (progress, handoff, education) | Stable |
 | Parallel documentation generation (5 types via Promise.all) | Stable |

package/apm.lock.yaml

@@ -2,7 +2,7 @@
 schemaVersion: 1
 package:
   name: specky-sdd
-  version: 3.11.1
+  version: 3.12.0
 primitives:
   .apm/agents/specky-design-architect.agent.md: sha256:54c69e392e21cbc1097fce8dd9d53d457d2a80d442390c6072c7d8dc5429c47f
   .apm/agents/specky-implementer.agent.md: sha256:4bad0b5238d185e25011cc01de90a146d2e719ad2621c814989c5e2986f13772

package/apm.yml

@@ -1,5 +1,5 @@
 name: specky-sdd
-version: 3.11.1
+version: 3.12.0
 description: "Agentic Spec-Driven Development — 10-phase pipeline with 58 MCP tools, 13 agents, 22 prompts, 14 skills, 16 hooks, EARS notation, model routing, and enterprise security"
 author: Paula Silva
 license: MIT
@@ -32,7 +32,7 @@ mcp:
       registry: false
       transport: stdio
       command: npx
-      args: ["-y", "specky-sdd@3.11.1", "serve"]
+      args: ["-y", "specky-sdd@3.12.0", "serve"]
       tools: ["sdd_*"]
 
 dependencies:
@@ -41,7 +41,7 @@ dependencies:
       registry: false
       transport: stdio
       command: npx
-      args: ["-y", "specky-sdd@3.11.1"]
+      args: ["-y", "specky-sdd@3.12.0"]
       tools: ["*"]
 
 scripts:

package/config.yml

@@ -1,5 +1,5 @@
 kind: "specky-package-catalog"
-version: "3.11.1"
+version: "3.12.0"
 runtime_config:
   path: ".specky/config.yml"
   required: true

package/dist/cli/commands/apm.d.ts

@@ -1,2 +1,13 @@
+/**
+ * commands/apm.ts — `specky apm <subcommand>` governance surface.
+ *
+ * Subcommands:
+ *   validate     Validate apm.yml against on-disk primitives + package.json.
+ *   lock         Write apm.lock.yaml with a sha256 for every primitive.
+ *   verify-lock  Recompute hashes and diff against apm.lock.yaml.
+ *   policy       Enforce apm-policy.yml (MCP allowlist, hooks, tool isolation).
+ *   audit        Run the primitive frontmatter audit.
+ *   sbom         Emit a CycloneDX SBOM of the packaged primitives.
+ */
 export declare function apmCommand(argv: string[]): number;
 //# sourceMappingURL=apm.d.ts.map

package/dist/cli/commands/apm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apm.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/apm.ts"],"names":[],"mappings":"AAgHA,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAwCjD"}
+{"version":3,"file":"apm.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/apm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAoGH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAwCjD"}