specky-sdd 3.11.0 → 3.12.0

package/.apm/hooks/scripts/specky-branch-validator.sh

@@ -1,131 +1,44 @@
-#!/bin/bash
-# specky-branch-validator.sh — Validate git branch matches expected pattern for current tool.
-#
-# Type: Mixed (see below) | Trigger: PreToolUse | All phases
-#   • Advisory (exit 0, warn) for sdd_* pipeline tools (always).
-#   • For native edit tools (Write|Edit|MultiEdit) on a wrong branch during
-#     an active pipeline:
-#       - default (SPECKY_GUARD unset OR "off"/"advisory") → warn, exit 0
-#       - SPECKY_GUARD=strict                              → exit 2 (BLOCK)
-#
-# Rationale (rc.13): rc.10-rc.12 defaulted Write|Edit|MultiEdit to BLOCKING,
-# which burned pilots who run `specky init` and then edit anything from
-# develop/main. Enforcement is now explicit opt-in.
+#!/usr/bin/env bash
+# specky-branch-validator.sh — Validate persisted release branch policy.
+# Type: advisory by default; strict for native edits when SPECKY_GUARD=strict.
 
 set -euo pipefail
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "$SCRIPT_DIR/specky-contract-context.bash"
 
 TOOL="${SDD_TOOL_NAME:-unknown}"
 CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr -d '\n' || true)
 [ -z "$CURRENT_BRANCH" ] && CURRENT_BRANCH="unknown"
 
-# Mode selection (rc.13): strict = block, anything else = advisory.
-SPECKY_GUARD_MODE="${SPECKY_GUARD:-advisory}"
-if [ "$SPECKY_GUARD_MODE" = "off" ]; then
-  SPECKY_GUARD_MODE="advisory"
+specky_load_contract_context || exit $?
+if [ "${SPECKY_CONTEXT_ACTIVE:-0}" != "1" ]; then
+  echo "ℹ️  Branch Validator — no explicit feature context; no branch inferred."
+  exit 0
 fi
-
-# ── Branch enforcement for native edit tools when pipeline is active ──
-if [[ "$TOOL" == "Write" || "$TOOL" == "Edit" || "$TOOL" == "MultiEdit" ]]; then
-  LATEST=$(ls -td .specs/*/ 2>/dev/null | head -1 || true)
-  if [ -z "$LATEST" ]; then exit 0; fi
-  STATE="$LATEST/.sdd-state.json"
-  if [ ! -f "$STATE" ]; then exit 0; fi
-
-  PHASE="?"
-  if command -v jq >/dev/null 2>&1; then
-    PHASE=$(jq -r '.current_phase // "?"' "$STATE" 2>/dev/null || echo "?")
-  fi
-
-  FEATURE=$(basename "$LATEST")
-
-  emit_violation() {
-    local expected="$1"
-    if [ "$SPECKY_GUARD_MODE" = "strict" ]; then
-      echo "" >&2
-      echo "🚫 [specky-branch-validator] BLOCKED — $TOOL on '$CURRENT_BRANCH' (phase $PHASE expects $expected) [SPECKY_GUARD=strict]" >&2
-      echo "   Feature:  $FEATURE" >&2
-      echo "   Fix:      git checkout $expected   (or: git checkout -b spec/$FEATURE)" >&2
-      echo "   Disable:  unset SPECKY_GUARD" >&2
-      exit 2
-    fi
-    echo "⚠️  [specky-branch-validator] $TOOL on '$CURRENT_BRANCH' during phase $PHASE (expected $expected). Enforce with: export SPECKY_GUARD=strict" >&2
-  }
-
-  case "$PHASE" in
-    init|discover|specify|clarify|design|tasks|analyze|implement)
-      if [[ "$CURRENT_BRANCH" != spec/* ]]; then
-        emit_violation "spec/$FEATURE"
-      fi
-      ;;
-    verify)
-      if [[ "$CURRENT_BRANCH" != "develop" ]]; then
-        emit_violation "develop"
-      fi
-      ;;
-    release)
-      if [[ "$CURRENT_BRANCH" != "stage" ]]; then
-        emit_violation "stage"
-      fi
-      ;;
-  esac
+if [ "${SPECKY_RELEASE_ENABLED:-0}" != "1" ]; then
+  echo "ℹ️  Branch Validator — release capability disabled by $SPECKY_CONTRACT_ID."
   exit 0
 fi
 
-echo "🔀 Branch Validator — $CURRENT_BRANCH — before $TOOL"
+EXPECTED_FEATURE_BRANCH="${SPECKY_BRANCH_PREFIX}${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}"
+EXPECTED="$EXPECTED_FEATURE_BRANCH"
+if [ "$TOOL" = "sdd_create_branch" ]; then
+  EXPECTED="$SPECKY_BASE_BRANCH"
+fi
 
-warn() {
-  echo "⚠️  $1"
-  echo "   Expected: $2"
-}
+if [ "$CURRENT_BRANCH" = "$EXPECTED" ]; then
+  echo "✅ Branch Validator — $CURRENT_BRANCH matches persisted release policy."
+  exit 0
+fi
 
-case "$TOOL" in
-  sdd_init|sdd_create_branch)
-    # Init should happen on develop (about to create spec branch)
-    if [[ "$CURRENT_BRANCH" != "develop" ]] && [[ "$CURRENT_BRANCH" != spec/* ]]; then
-      warn "sdd_init typically runs on 'develop' before creating a spec branch" "develop"
-    fi
-    ;;
-  sdd_write_spec|sdd_turnkey_spec|sdd_figma_to_spec|sdd_write_design|sdd_write_tasks|sdd_implement|sdd_generate_tests|sdd_generate_pbt|sdd_generate_iac|sdd_generate_dockerfile)
-    # Spec work must be on spec/* branch
-    if [[ "$CURRENT_BRANCH" != spec/* ]]; then
-      warn "Spec work should be on a spec/NNN-* branch, not '$CURRENT_BRANCH'" "spec/NNN-feature-name"
-      echo "   Flow: spec/NNN-* → develop → stage → main"
-    fi
-    ;;
-  sdd_discover|sdd_research|sdd_import_document|sdd_import_transcript|sdd_clarify|sdd_validate_ears)
-    # Research/clarify on spec branch
-    if [[ "$CURRENT_BRANCH" != spec/* ]]; then
-      warn "Research and clarification should be on a spec/NNN-* branch" "spec/NNN-feature-name"
-    fi
-    ;;
-  sdd_verify_tests|sdd_verify_tasks|sdd_check_sync)
-    # Verification on spec branch
-    if [[ "$CURRENT_BRANCH" != spec/* ]]; then
-      warn "Verification should be on a spec/NNN-* branch" "spec/NNN-feature-name"
-    fi
-    ;;
-  sdd_run_analysis|sdd_cross_analyze|sdd_compliance_check)
-    # Review on develop (after merge from spec)
-    if [[ "$CURRENT_BRANCH" != "develop" ]] && [[ "$CURRENT_BRANCH" != spec/* ]]; then
-      warn "Review tools typically run on 'develop' after merge from spec" "develop"
-    fi
-    ;;
-  sdd_create_pr)
-    # PR: branch determines target
-    if [[ "$CURRENT_BRANCH" == spec/* ]]; then
-      echo "  ℹ️  spec branch → PR will target develop"
-    elif [[ "$CURRENT_BRANCH" == "develop" ]]; then
-      echo "  ℹ️  develop → PR will target stage"
-    elif [[ "$CURRENT_BRANCH" == "stage" ]]; then
-      echo "  ℹ️  stage → PR will target main"
-    elif [[ "$CURRENT_BRANCH" == "main" ]]; then
-      warn "Cannot create PR from main — nothing to merge" "spec/*, develop, or stage"
-    fi
-    ;;
-  *)
-    echo "  ✅ No branch requirement for $TOOL"
-    ;;
-esac
+MESSAGE="branch '$CURRENT_BRANCH' does not match persisted release policy '$EXPECTED' for $TOOL"
+if [[ "$TOOL" == "Write" || "$TOOL" == "Edit" || "$TOOL" == "MultiEdit" ]] && [ "${SPECKY_GUARD:-advisory}" = "strict" ]; then
+  echo "🚫 [specky-branch-validator] BLOCKED — $MESSAGE" >&2
+  exit 2
+fi
 
-# Always exit 0 — advisory only
+echo "⚠️  [specky-branch-validator] $MESSAGE" >&2
+echo "   Contract: $SPECKY_CONTRACT_ID" >&2
+echo "   Base: $SPECKY_BASE_BRANCH | Prefix: $SPECKY_BRANCH_PREFIX" >&2
+echo "   Enforce native edits with: export SPECKY_GUARD=strict" >&2
 exit 0

package/.apm/hooks/scripts/specky-cognitive-debt-alert.sh

@@ -5,14 +5,17 @@
 # Paper: arXiv:2603.22106 — cognitive surrender measurement
 
 set -euo pipefail
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+. "$SCRIPT_DIR/specky-contract-context.bash"
+specky_load_contract_context || exit $?
+[ "${SPECKY_CONTEXT_ACTIVE:-0}" = "1" ] || exit 0
 
-STATE=$(find . -name ".sdd-state.json" -maxdepth 2 2>/dev/null | head -1)
-[ -z "$STATE" ] || [ ! -f "$STATE" ] && exit 0
+STATE="$SPECKY_STATE_FILE"
 
 # Check if gate history exists in state
 if command -v jq &>/dev/null && [ -f "$STATE" ]; then
   GATES=$(jq -r '.gate_history // [] | length' "$STATE" 2>/dev/null || echo "0")
-  LGTM_NO_MOD=$(jq -r '[.gate_history // [] | .[] | select(.modified == false)] | length' "$STATE" 2>/dev/null || echo "0")
+  LGTM_NO_MOD=$(jq -r '[.gate_history // [] | .[] | select(.was_modified == false)] | length' "$STATE" 2>/dev/null || echo "0")
   
   if [ "$GATES" -gt 0 ]; then
     RATE=$((LGTM_NO_MOD * 100 / GATES))

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

@@ -0,0 +1,24 @@
+# Shared explicit feature-contract context for Specky hooks.
+
+specky_load_contract_context() {
+  local context_dir context_exports
+  context_dir=$(cd "$(dirname "$0")" && pwd)
+  context_exports=$(node "$context_dir/specky-contract-context.mjs" shell) || return $?
+  eval "$context_exports"
+}
+
+specky_has_capability() {
+  local capability=",${SPECKY_CAPABILITIES:-},"
+  case "$capability" in
+    *",$1,"*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+specky_require_feature_context() {
+  specky_load_contract_context || return $?
+  if [ "${SPECKY_CONTEXT_ACTIVE:-0}" != "1" ]; then
+    echo "[specky] Explicit feature context required: ${SPECKY_CONTEXT_REASON:-missing context}." >&2
+    return 2
+  fi
+}

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

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+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);
+}
+
+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 "";
+  }
+}
+
+function parseInput(raw) {
+  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),
+  );
+}
+
+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();
+    }
+  }
+  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("/");
+}
+
+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;
+    }, {});
+}
+
+function fingerprintContract(contract) {
+  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"));
+}
+
+function shellQuote(value) {
+  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 ?? "",
+  };
+}
+
+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 command = process.argv[2] ?? "shell";
+const context = resolveContext();
+if (command === "json") {
+  console.log(JSON.stringify(context));
+} else if (command === "shell") {
+  printShell(context);
+} else {
+  fail(`unknown command ${command}`);
+}

package/.apm/hooks/scripts/specky-drift-monitor.sh

@@ -5,14 +5,17 @@
 # Paper: arXiv:2602.20478, arXiv:2603.22106
 
 set -euo pipefail
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+. "$SCRIPT_DIR/specky-contract-context.bash"
+specky_load_contract_context || exit $?
+[ "${SPECKY_CONTEXT_ACTIVE:-0}" = "1" ] || exit 0
 
-LATEST=$(ls -td .specs/*/ 2>/dev/null | head -1 || true)
-[ -z "$LATEST" ] && exit 0
+LATEST="$SPECKY_FEATURE_DIR"
 CONST="$LATEST/CONSTITUTION.md"
 SPEC="$LATEST/SPECIFICATION.md"
 [ -f "$CONST" ] && [ -f "$SPEC" ] || exit 0
 
-echo "🧭 Drift Monitor: $(basename "$LATEST")"
+echo "🧭 Drift Monitor: ${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME} ($SPECKY_CONTRACT_ID)"
 
 # Simple drift: compare key terms in constitution vs spec (POSIX ERE for portability)
 CONST_TERMS=$(grep -oE '[A-Z][a-z]+([[:space:]][A-Z][a-z]+)+' "$CONST" 2>/dev/null | sort -u | wc -l)

package/.apm/hooks/scripts/specky-ears-validator.sh

@@ -10,9 +10,12 @@
 # plain `set -eu` instead of bash-only `set -o pipefail`.
 
 set -eu
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+. "$SCRIPT_DIR/specky-contract-context.bash"
+specky_load_contract_context || exit $?
+[ "${SPECKY_CONTEXT_ACTIVE:-0}" = "1" ] || exit 0
 
-LATEST=$(ls -td .specs/*/ 2>/dev/null | head -1 || true)
-[ -z "$LATEST" ] && exit 0
+LATEST="$SPECKY_FEATURE_DIR"
 SPEC="$LATEST/SPECIFICATION.md"
 
 if [ ! -f "$SPEC" ] || [ ! -r "$SPEC" ]; then

package/.apm/hooks/scripts/specky-lgtm-gate.sh

@@ -4,13 +4,15 @@
 # Summarizes artifact and prompts for LGTM before phase advancement
 
 set -euo pipefail
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+. "$SCRIPT_DIR/specky-contract-context.bash"
+specky_load_contract_context || exit $?
+[ "${SPECKY_CONTEXT_ACTIVE:-0}" = "1" ] || exit 0
 
 TOOL="${SDD_TOOL_NAME:-unknown}"
-LATEST=$(ls -td .specs/*/ 2>/dev/null | head -1 || true)
+LATEST="$SPECKY_FEATURE_DIR"
 
-[ -z "$LATEST" ] && exit 0
-
-FEATURE=$(basename "$LATEST")
+FEATURE="${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}"
 
 print_summary() {
   local file="$1" label="$2"
@@ -29,25 +31,25 @@ case "$TOOL" in
   sdd_write_spec|sdd_turnkey_spec|sdd_figma_to_spec)
     print_summary "SPECIFICATION.md" "SPECIFICATION.md"
     echo ""
-    echo "⏸  LGTM GATE — Phase 3 (Specify)"
+    echo "⏸  LGTM REVIEW — Specify ($SPECKY_CONTRACT_ID)"
     echo "   Review SPECIFICATION.md above. Are the requirements correct?"
-    echo "   Reply 'LGTM' to proceed to Phase 4 (Design)."
+    echo "   If workspace policy requires LGTM, pass lgtm:true to sdd_advance_phase."
     echo "   Reply with feedback to revise."
     ;;
   sdd_write_design)
     print_summary "DESIGN.md" "DESIGN.md"
     echo ""
-    echo "⏸  LGTM GATE — Phase 4 (Design)"
+    echo "⏸  LGTM REVIEW — Design ($SPECKY_CONTRACT_ID)"
     echo "   Review DESIGN.md above. Is the architecture sound?"
-    echo "   Reply 'LGTM' to proceed to Phase 5 (Tasks)."
+    echo "   If workspace policy requires LGTM, pass lgtm:true to sdd_advance_phase."
     echo "   Reply with feedback to revise."
     ;;
   sdd_write_tasks)
     print_summary "TASKS.md" "TASKS.md"
     echo ""
-    echo "⏸  LGTM GATE — Phase 5 (Tasks)"
+    echo "⏸  LGTM REVIEW — Tasks ($SPECKY_CONTRACT_ID)"
     echo "   Review TASKS.md above. Is the task breakdown complete?"
-    echo "   Reply 'LGTM' to proceed to Phase 6 (Implement)."
+    echo "   If workspace policy requires LGTM, pass lgtm:true to sdd_advance_phase."
     echo "   Reply with feedback to revise."
     ;;
   *)

package/.apm/hooks/scripts/specky-metrics-dashboard.sh

@@ -5,9 +5,12 @@
 # Paper: arXiv:2507.09089 — AI productivity paradox
 
 set -euo pipefail
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+. "$SCRIPT_DIR/specky-contract-context.bash"
+specky_load_contract_context || exit $?
+[ "${SPECKY_CONTEXT_ACTIVE:-0}" = "1" ] || exit 0
 
-LATEST=$(ls -td .specs/*/ 2>/dev/null | head -1 || true)
-[ -z "$LATEST" ] && exit 0
+LATEST="$SPECKY_FEATURE_DIR"
 
 # Check if analysis is done but metrics not generated
 if [ -f "$LATEST/ANALYSIS.md" ] && [ ! -f "$LATEST/specky-metrics-dashboard.html" ]; then

package/.apm/hooks/scripts/specky-phase-gate.sh

@@ -4,14 +4,16 @@
 # Ensures phase artifacts exist and meet minimum quality after creation
 
 set -euo pipefail
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "$SCRIPT_DIR/specky-contract-context.bash"
 
 TOOL="${SDD_TOOL_NAME:-unknown}"
-LATEST=$(ls -td .specs/*/ 2>/dev/null | head -1 || true)
 FAILS=0
 
-[ -z "$LATEST" ] && exit 0
+specky_require_feature_context || exit $?
+LATEST="$SPECKY_FEATURE_DIR"
 
-FEATURE=$(basename "$LATEST")
+FEATURE="${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}"
 echo "🚦 Phase Gate — $FEATURE — after $TOOL"
 
 check_created() {
@@ -43,28 +45,35 @@ case "$TOOL" in
   sdd_init)
     check_created "CONSTITUTION.md" "CONSTITUTION.md"
     check_created ".sdd-state.json" ".sdd-state.json"
+    check_created ".sdd-state.json.sig" ".sdd-state.json.sig"
     ;;
   sdd_write_spec|sdd_turnkey_spec|sdd_figma_to_spec)
     check_created "SPECIFICATION.md" "SPECIFICATION.md"
-    check_has_content "SPECIFICATION.md" "REQ-[A-Z]+-[0-9]+" "REQ-IDs" 3
-    check_has_content "SPECIFICATION.md" "(shall|When .* shall|While .* shall|Where .* shall|If .* then)" "EARS patterns" 3
+    check_has_content "SPECIFICATION.md" "REQ-[A-Z]+-[0-9]+" "REQ-IDs" 1
+    check_has_content "SPECIFICATION.md" "(shall|When .* shall|While .* shall|Where .* shall|If .* then)" "EARS patterns" 1
     ;;
   sdd_write_design)
     check_created "DESIGN.md" "DESIGN.md"
-    check_has_content "DESIGN.md" "##" "Sections" 3
+    check_has_content "DESIGN.md" "## 13\. Workload-Specific Design Contract" "Workload design contract" 1
+    check_has_content "DESIGN.md" "REQ-[A-Z]+-[0-9]+" "REQ-ID traceability" 1
+    ;;
+  sdd_generate_all_diagrams)
+    check_created "DIAGRAMS.md" "DIAGRAMS.md"
+    REQUIRED_DIAGRAMS=$(node -e 'const s=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")); console.log(s.contract.required_diagrams.length)' "$SPECKY_STATE_FILE")
+    check_has_content "DIAGRAMS.md" '^```mermaid' "Contracted Mermaid diagrams" "$REQUIRED_DIAGRAMS"
     ;;
   sdd_write_tasks)
     check_created "TASKS.md" "TASKS.md"
     check_has_content "TASKS.md" "REQ-[A-Z]+-[0-9]+" "REQ-ID traceability" 1
-    check_has_content "TASKS.md" "T-?[0-9]{3}" "Task IDs" 3
+    check_has_content "TASKS.md" "T-[0-9]{3}" "Task IDs" 1
     ;;
   sdd_verify_tests|sdd_verify_tasks)
     check_created "VERIFICATION.md" "VERIFICATION.md"
-    check_has_content "VERIFICATION.md" "pass_rate" "Pass rate metric" 1
+    check_has_content "VERIFICATION.md" "Pass Rate|pass_rate" "Pass rate metric" 1
     ;;
   sdd_run_analysis)
     check_created "ANALYSIS.md" "ANALYSIS.md"
-    check_has_content "ANALYSIS.md" "gate_decision" "Gate decision" 1
+    check_has_content "ANALYSIS.md" "APPROVE|CHANGES_NEEDED|BLOCK" "Gate decision" 1
     ;;
   sdd_cross_analyze)
     check_created "CROSS_ANALYSIS.md" "CROSS_ANALYSIS.md"