specky-sdd 3.10.2 → 3.11.1

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

@@ -4,20 +4,20 @@
 # Ensures required artifacts exist before a phase tool runs
 
 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
 
-if [ -z "$LATEST" ]; then
-  if [ "$TOOL" != "sdd_init" ]; then
-    echo "❌ No .specs/ directory found. Run @specky-sdd-init first."
-    exit 2
-  fi
+if [ "$TOOL" = "sdd_init" ]; then
+  echo "✅ Artifact Validator — sdd_init has no existing feature prerequisites"
   exit 0
 fi
+specky_require_feature_context || exit $?
+LATEST="$SPECKY_FEATURE_DIR"
 
-FEATURE=$(basename "$LATEST")
+FEATURE="${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}"
 echo "📄 Artifact Validator — $FEATURE — before $TOOL"
 
 check_exists() {
@@ -44,7 +44,7 @@ case "$TOOL" in
   sdd_init)
     echo "  ✅ No prerequisites for sdd_init"
     ;;
-  sdd_discover|sdd_research|sdd_import_document|sdd_import_transcript|sdd_batch_import)
+  sdd_discover|sdd_research|sdd_import_transcript)
     check_exists "CONSTITUTION.md" "CONSTITUTION.md" "Run @specky-sdd-init or /specky-greenfield"
     ;;
   sdd_clarify|sdd_validate_ears)
@@ -53,7 +53,7 @@ case "$TOOL" in
   sdd_write_spec|sdd_turnkey_spec|sdd_figma_to_spec)
     check_exists "CONSTITUTION.md" "CONSTITUTION.md" "Run @specky-sdd-init"
     ;;
-  sdd_write_design|sdd_generate_all_diagrams)
+  sdd_write_design|sdd_generate_all_diagrams|sdd_generate_diagram|sdd_figma_diagram)
     check_exists "SPECIFICATION.md" "SPECIFICATION.md" "Run @specky-spec-engineer or /specky-specify"
     check_content "SPECIFICATION.md" "REQ-[A-Z]+-[0-9]+" "EARS requirements with REQ-IDs"
     ;;
@@ -70,13 +70,17 @@ case "$TOOL" in
     check_exists "TASKS.md" "TASKS.md" "Run /specky-tasks"
     ;;
   sdd_run_analysis|sdd_cross_analyze)
-    check_exists "VERIFICATION.md" "VERIFICATION.md" "Run @specky-test-verifier or /specky-verify"
     check_exists "SPECIFICATION.md" "SPECIFICATION.md" "Run /specky-specify"
     check_exists "DESIGN.md" "DESIGN.md" "Run /specky-design"
     check_exists "TASKS.md" "TASKS.md" "Run /specky-tasks"
     ;;
   sdd_compliance_check)
+    if ! specky_has_capability "compliance"; then
+      echo "🚫 Compliance capability is not enabled by $SPECKY_CONTRACT_ID"
+      FAILS=$((FAILS+1))
+    fi
     check_exists "SPECIFICATION.md" "SPECIFICATION.md" "Run /specky-specify"
+    check_exists "DESIGN.md" "DESIGN.md" "Run /specky-design"
     ;;
   sdd_create_pr|sdd_export_work_items)
     check_exists "ANALYSIS.md" "ANALYSIS.md" "Run @specky-quality-reviewer"

package/.apm/hooks/scripts/specky-auto-checkpoint.sh

@@ -5,16 +5,21 @@
 # Paper: arXiv:2602.20478 — artifact preservation
 
 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
+[ "${SPECKY_CHECKPOINTS_REQUIRED:-0}" = "1" ] || exit 0
 
-# Check if a spec artifact was recently modified (last 60 seconds)
-RECENT=$(find .specs -name "*.md" -newer /tmp/.sdd-last-checkpoint 2>/dev/null | head -5 || true)
-[ -d .specs ] || exit 0
+MARKER="/tmp/.sdd-last-checkpoint-${SPECKY_CONTRACT_FINGERPRINT}"
+[ -f "$MARKER" ] || touch -t 197001010000 "$MARKER"
+RECENT=$(find "$SPECKY_FEATURE_DIR" -name "*.md" -newer "$MARKER" 2>/dev/null | head -5 || true)
 
 if [ -n "$RECENT" ]; then
   echo "💾 Spec artifacts modified:"
   echo "$RECENT"
   echo "   Consider running sdd_checkpoint to save a snapshot."
-  touch /tmp/.sdd-last-checkpoint
+  touch "$MARKER"
 fi
 
 exit 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,219 @@
+#!/usr/bin/env node
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } 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