specky-sdd 3.10.2 → 3.11.1

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"

package/.apm/hooks/scripts/specky-pipeline-guard.sh

@@ -22,6 +22,8 @@
 # ALL work MUST flow through @specky-orchestrator.
 
 set -euo pipefail
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "$SCRIPT_DIR/specky-contract-context.bash"
 
 # ── rc.14: Copilot compatibility guard ───────────────────
 # VS Code Copilot reads .claude/settings.json hooks and treats SessionStart/
@@ -51,40 +53,31 @@ if [ "$SPECKY_GUARD_MODE" = "off" ]; then
   SPECKY_GUARD_MODE="advisory"
 fi
 
-# ── Check if pipeline is active ──────────────────────────
-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
-
-FEATURE=$(basename "$LATEST")
-
-# Try to read current phase (optional — requires jq)
-PHASE="?"
-if command -v jq >/dev/null 2>&1; then
-  PHASE=$(jq -r '.current_phase // "?"' "$STATE" 2>/dev/null || echo "?")
+# Buffer stdin once; both the context resolver and prompt parser consume this JSON.
+if [ -z "${SDD_HOOK_INPUT:-}" ] && [ ! -t 0 ]; then
+  SDD_HOOK_INPUT=$(cat 2>/dev/null || true)
+  export SDD_HOOK_INPUT
 fi
 
 # ── Extract user prompt ──────────────────────────────────
-# Claude Code sends the prompt as JSON on stdin: {"prompt": "..."}
-# Copilot uses $CLAUDE_USER_PROMPT. Fall back to empty.
-PROMPT=""
-if [ -n "${CLAUDE_USER_PROMPT:-}" ]; then
-  PROMPT="$CLAUDE_USER_PROMPT"
-elif [ ! -t 0 ]; then
-  # Read from stdin non-blocking
+PROMPT="${CLAUDE_USER_PROMPT:-}"
+if [ -z "$PROMPT" ] && [ -n "${SDD_HOOK_INPUT:-}" ]; then
   if command -v jq >/dev/null 2>&1; then
-    PROMPT=$(jq -r '.prompt // .user_prompt // ""' 2>/dev/null || cat || true)
+    PROMPT=$(printf '%s' "$SDD_HOOK_INPUT" | jq -r '.prompt // .user_prompt // ""' 2>/dev/null || true)
   else
-    PROMPT=$(cat 2>/dev/null || true)
+    PROMPT="$SDD_HOOK_INPUT"
   fi
 fi
 
+# ── Resolve explicit pipeline context ───────────────────
+specky_load_contract_context || exit $?
+if [ "${SPECKY_CONTEXT_ACTIVE:-0}" != "1" ]; then
+  exit 0
+fi
+FEATURE="${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}"
+PHASE="$SPECKY_PHASE"
+STATE="$SPECKY_STATE_FILE"
+
 # Lowercase for matching
 PROMPT_LC=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]' 2>/dev/null || true)
 

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

@@ -1,62 +1,54 @@
-#!/bin/bash
-# specky-release-gate.sh — Verify VERIFICATION.md + 90% pass rate before PR
-# Target: Claude Code (.claude/hooks/)
-# Type: BLOCKING (exit 2) | Trigger: before sdd_create_pr | Phase: 9
-# Paper: arXiv:2601.03878 — human-in-loop gate
+#!/usr/bin/env bash
+# specky-release-gate.sh — Verify persisted release and TDD policy before PR payload generation.
+# Type: BLOCKING (exit 2) | Trigger: before release operations.
 
 set -euo pipefail
-FAILS=0
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "$SCRIPT_DIR/specky-contract-context.bash"
+specky_require_feature_context || exit $?
 
-echo "🚦 Release Gate Check"
+FAILS=0
+echo "🚦 Release Gate — ${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}"
 
-# Branch validation (advisory — warning only)
-CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
-if [[ "$CURRENT_BRANCH" == "main" ]]; then
-  echo "⚠️  WARNING: You are on 'main'. Spec work should be on spec/NNN-* branches."
-  echo "   Expected flow: spec/NNN-* → develop → stage → main"
-elif [[ "$CURRENT_BRANCH" == "develop" ]] || [[ "$CURRENT_BRANCH" == "stage" ]]; then
-  echo "ℹ️  Branch: $CURRENT_BRANCH (integration/release branch)"
-elif [[ "$CURRENT_BRANCH" == spec/* ]]; then
-  echo "ℹ️  Branch: $CURRENT_BRANCH (spec branch → PR targets develop)"
-else
-  echo "⚠️  WARNING: Branch '$CURRENT_BRANCH' does not follow naming convention."
-  echo "   Expected: spec/NNN-feature-name, develop, stage, or main"
+if [ "${SPECKY_RELEASE_ENABLED:-0}" != "1" ]; then
+  echo "🚫 Release capability is not enabled by $SPECKY_CONTRACT_ID"
+  FAILS=$((FAILS+1))
 fi
-echo ""
-
-# Find active feature
-LATEST=$(ls -td .specs/*/ 2>/dev/null | head -1 || true)
-[ -z "$LATEST" ] && { echo "❌ No .specs/ directory found"; exit 2; }
-
-# VERIFICATION.md must exist
-if [ ! -f "$LATEST/VERIFICATION.md" ]; then
-  echo "🚫 Missing VERIFICATION.md in $LATEST — run /sdd:test first"
+if [ "${SPECKY_GATE_DECISION:-}" != "APPROVE" ]; then
+  echo "🚫 Analysis gate is '${SPECKY_GATE_DECISION:-none}', expected APPROVE"
   FAILS=$((FAILS+1))
 fi
-
-# CHECKLIST.md must exist
-if [ ! -f "$LATEST/CHECKLIST.md" ]; then
-  echo "🚫 Missing CHECKLIST.md in $LATEST — run /sdd:implement first"
+if [ ! -f "$SPECKY_FEATURE_DIR/ANALYSIS.md" ]; then
+  echo "🚫 Missing ANALYSIS.md"
+  FAILS=$((FAILS+1))
+fi
+if [ ! -f "$SPECKY_FEATURE_DIR/VERIFICATION.md" ]; then
+  echo "🚫 Missing VERIFICATION.md"
   FAILS=$((FAILS+1))
 fi
 
-# Pass rate >= 90%
-if [ -f "$LATEST/VERIFICATION.md" ]; then
-  RATE=$(grep -oE 'pass_rate:[[:space:]]*"?([0-9]+(\.[0-9]+)?)"?' "$LATEST/VERIFICATION.md" | grep -oE '[0-9.]+' | head -1 || echo "0")
-  if [ -n "$RATE" ]; then
-    PASS=$(echo "$RATE >= 90" | bc -l 2>/dev/null || echo "0")
-    if [ "$PASS" -eq 0 ]; then
-      echo "🚫 Test pass rate ${RATE}% < 90% — fix failing tests"
-      FAILS=$((FAILS+1))
-    fi
+if [ "${SPECKY_TDD_ENABLED:-0}" = "1" ] && [ -f "$SPECKY_FEATURE_DIR/VERIFICATION.md" ]; then
+  RATE=$(grep -m1 -oE '\*\*Pass Rate\*\*:[[:space:]]*[0-9]+([.][0-9]+)?%' "$SPECKY_FEATURE_DIR/VERIFICATION.md" | grep -oE '[0-9]+([.][0-9]+)?' || true)
+  if [ -z "$RATE" ]; then
+    echo "🚫 VERIFICATION.md does not contain a parseable Pass Rate"
+    FAILS=$((FAILS+1))
+  elif ! node -e 'process.exit(Number(process.argv[1]) >= Number(process.argv[2]) ? 0 : 1)' "$RATE" "$SPECKY_TDD_THRESHOLD"; then
+    echo "🚫 Verification pass rate ${RATE}% is below contracted threshold ${SPECKY_TDD_THRESHOLD}%"
+    FAILS=$((FAILS+1))
+  else
+    echo "  ✅ Verification pass rate ${RATE}% meets ${SPECKY_TDD_THRESHOLD}%"
   fi
 fi
 
+EXPECTED_BRANCH="${SPECKY_BRANCH_PREFIX}${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}"
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+if [ -n "$CURRENT_BRANCH" ] && [ "$CURRENT_BRANCH" != "$EXPECTED_BRANCH" ]; then
+  echo "⚠️  Current branch '$CURRENT_BRANCH' differs from persisted release head '$EXPECTED_BRANCH'"
+fi
+
 if [ "$FAILS" -gt 0 ]; then
-  echo ""
-  echo "❌ Release gate FAILED ($FAILS issues). Cannot create PR."
-  exit 2  # BLOCKING
+  echo "❌ Release gate failed with $FAILS issue(s)."
+  exit 2
 fi
 
-echo "✅ Release gate passed."
-exit 0
+echo "✅ Release gate passed for base '$SPECKY_BASE_BRANCH'."

package/.apm/hooks/scripts/specky-security-scan.sh

@@ -1,55 +1,72 @@
-#!/bin/bash
-# specky-security-scan.sh — OWASP + secrets scan
-# Target: Claude Code (.claude/hooks/)
-# Type: BLOCKING (exit 2) | Trigger: Stop | Phase: 9
-# Paper: arXiv:2503.23278 — security enforcement
-#
-# Claude Code settings.json:
-#   "hooks": { "Stop": ["bash .claude/hooks/specky-security-scan.sh"] }
+#!/usr/bin/env bash
+# specky-security-scan.sh — Contract-aware release security checks.
+# Type: BLOCKING (exit 2) | Trigger: before release operations.
 
 set -euo pipefail
-FAILS=0
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "$SCRIPT_DIR/specky-contract-context.bash"
+specky_require_feature_context || exit $?
+
+if [ "${SPECKY_RELEASE_ENABLED:-0}" != "1" ]; then
+  echo "🚫 Security scan requires the release capability." >&2
+  exit 2
+fi
 
-echo "🔒 Security Scan"
+FAILS=0
+echo "🔒 Security Scan — ${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME} ($SPECKY_CONTRACT_ID)"
 
-# Hardcoded secrets
 PATTERNS='AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{48}|sk-ant-[a-zA-Z0-9-]{90}|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|xox[bpors]-[a-zA-Z0-9-]+|sk_live_[a-zA-Z0-9]{24}'
-FOUND=$(grep -rnE "$PATTERNS" src/ tests/ test/ --include="*.ts" --include="*.js" --include="*.py" --include="*.json" --include="*.yml" --include="*.env" 2>/dev/null || true)
+FOUND=$(git grep -nE "$PATTERNS" -- ':!*.lock' ':!.specs/**' 2>/dev/null || true)
 if [ -n "$FOUND" ]; then
-  echo "🚫 HARDCODED SECRETS FOUND:"
+  echo "🚫 Hardcoded credential patterns found in tracked files:"
   echo "$FOUND" | head -10
   FAILS=$((FAILS+1))
 fi
 
-# .env in tracked files
-if git ls-files --error-unmatch .env .env.local .env.production 2>/dev/null; then
-  echo "🚫 .env file tracked in git — add to .gitignore"
+TRACKED_ENV=$(git ls-files '.env' '.env.*' 2>/dev/null || true)
+if [ -n "$TRACKED_ENV" ]; then
+  echo "🚫 Environment secret files are tracked:"
+  echo "$TRACKED_ENV"
   FAILS=$((FAILS+1))
 fi
 
-# npm audit (if package.json exists)
-if [ -f "package.json" ] && command -v npm &>/dev/null; then
-  AUDIT=$(npm audit --json 2>/dev/null | grep -o '"critical":[0-9]*' | head -1 || true)
-  CRITICAL=$(echo "$AUDIT" | grep -oE '[0-9]+' || echo "0")
-  if [ "$CRITICAL" -gt 0 ]; then
-    echo "🚫 npm audit: $CRITICAL critical vulnerabilities"
-    FAILS=$((FAILS+1))
-  fi
-fi
+case "${SPECKY_DEV_LANGUAGE:-}" in
+  TypeScript|JavaScript)
+    if [ -f package-lock.json ] && command -v npm >/dev/null 2>&1; then
+      AUDIT=$(npm audit --json 2>/dev/null || true)
+      CRITICAL=$(printf '%s' "$AUDIT" | node -e 'let x="";process.stdin.on("data",d=>x+=d).on("end",()=>{try{const j=JSON.parse(x);console.log(j.metadata?.vulnerabilities?.critical??0)}catch{console.log(0)}})')
+      if [ "$CRITICAL" -gt 0 ]; then
+        echo "🚫 npm audit reports $CRITICAL critical vulnerabilities"
+        FAILS=$((FAILS+1))
+      fi
+    fi
+    ;;
+  Python)
+    if [ -f requirements.txt ] && command -v pip-audit >/dev/null 2>&1; then
+      if ! pip-audit -r requirements.txt --strict; then
+        echo "🚫 pip-audit reports vulnerabilities"
+        FAILS=$((FAILS+1))
+      fi
+    fi
+    ;;
+  Go)
+    if [ -f go.mod ] && command -v govulncheck >/dev/null 2>&1; then
+      if ! govulncheck ./...; then
+        echo "🚫 govulncheck reports reachable vulnerabilities"
+        FAILS=$((FAILS+1))
+      fi
+    fi
+    ;;
+esac
 
-# pip audit (if requirements.txt exists)
-if [ -f "requirements.txt" ] && command -v pip-audit &>/dev/null; then
-  if ! pip-audit -r requirements.txt --strict 2>/dev/null; then
-    echo "🚫 pip-audit: vulnerabilities found"
-    FAILS=$((FAILS+1))
-  fi
+if [ "${SPECKY_COMPLIANCE_ENABLED:-0}" = "1" ] && [ ! -f "$SPECKY_FEATURE_DIR/COMPLIANCE.md" ]; then
+  echo "🚫 Configured compliance frameworks lack COMPLIANCE.md evidence: $SPECKY_COMPLIANCE_FRAMEWORKS"
+  FAILS=$((FAILS+1))
 fi
 
 if [ "$FAILS" -gt 0 ]; then
-  echo ""
-  echo "❌ Security scan FAILED ($FAILS issues). Fix before release."
-  exit 2  # BLOCKING
+  echo "❌ Security scan failed with $FAILS issue(s)."
+  exit 2
 fi
 
-echo "✅ Security scan passed."
-exit 0
+echo "✅ Contract-aware security scan passed."

package/.apm/hooks/scripts/specky-session-banner.sh

@@ -1,82 +1,30 @@
-#!/bin/bash
-# specky-session-banner.sh — Show Specky pipeline status at session start.
-# Target: Claude Code + GitHub Copilot
-# Type: Advisory (exit 0 always) | Trigger: SessionStart
-#
-# Prints a one-screen banner whenever the user opens a new session so they
-# immediately see which feature and phase are active. Helps avoid the SIFAP
-# incident where a user bypassed the pipeline because they didn't realize
-# one was running.
+#!/usr/bin/env bash
+# specky-session-banner.sh — Show explicit feature context or workspace-level status guidance.
+# Type: Advisory | Trigger: SessionStart.
 
 set -euo pipefail
-
-# ── rc.14: Copilot compatibility guard ───────────────────
-# VS Code Copilot reads .claude/settings.json hooks and treats SessionStart as
-# PreToolUse. This script is advisory-only but Copilot surfaces any output from
-# a hook as a block warning. Skip entirely when not in Claude Code context.
-if [ -z "${CLAUDE_PROJECT_DIR:-}" ]; then
-  exit 0
-fi
-
-SPECS_DIR=".specs"
-[ -d "$SPECS_DIR" ] || exit 0
-
-# Find most recently touched feature
-LATEST=$(ls -td "$SPECS_DIR"/*/ 2>/dev/null | head -1 || true)
-if [ -z "$LATEST" ]; then
-  exit 0
-fi
-
-STATE="$LATEST/.sdd-state.json"
-if [ ! -f "$STATE" ]; then
+[ -n "${CLAUDE_PROJECT_DIR:-}" ] || exit 0
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+. "$SCRIPT_DIR/specky-contract-context.bash"
+specky_load_contract_context || exit $?
+
+if [ "${SPECKY_CONTEXT_ACTIVE:-0}" != "1" ]; then
+  if [ -d .specs ]; then
+    echo "🧭 Specky workspace detected. No feature selected; run 'specky status' and resume with explicit spec_dir + feature_number."
+  fi
   exit 0
 fi
 
-FEATURE=$(basename "$LATEST")
-PHASE="?"
-if command -v jq >/dev/null 2>&1; then
-  PHASE=$(jq -r '.current_phase // "?"' "$STATE" 2>/dev/null || echo "?")
-fi
-
 BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr -d '\n' || true)
-[ -z "$BRANCH" ] && BRANCH="unknown"
+[ -n "$BRANCH" ] || BRANCH="unknown"
 
 echo ""
-echo "╭─────────────────────────────────────────────────────────────╮"
-echo "│ 🧭 Specky Pipeline Active                                    │"
-echo "├─────────────────────────────────────────────────────────────┤"
-printf "│ Feature:  %-50s│\n" "$FEATURE"
-printf "│ Phase:    %-50s│\n" "$PHASE"
-printf "│ Branch:   %-50s│\n" "$BRANCH"
-echo "├─────────────────────────────────────────────────────────────┤"
-echo "│ Resume:   @specky-orchestrator (Copilot)                     │"
-echo "│           /specky-orchestrate (Claude Code)                  │"
-echo "│ Status:   specky status  (or npx specky status)             │"
-echo "│ New work: @specky-onboarding                                 │"
-echo "╰─────────────────────────────────────────────────────────────╯"
-echo ""
-
-# Validate branch matches expected for phase (advisory warning only)
-case "$PHASE" in
-  init|discover|specify|clarify|design|tasks|analyze|implement)
-    if [[ ! "$BRANCH" =~ ^spec/ ]]; then
-      echo "⚠️  [specky-session-banner] Phase $PHASE expects branch spec/NNN-* — you are on '$BRANCH'"
-      echo "    Consider: git checkout -b spec/$FEATURE (or let @specky-orchestrator handle it)"
-      echo ""
-    fi
-    ;;
-  verify)
-    if [ "$BRANCH" != "develop" ]; then
-      echo "⚠️  [specky-session-banner] Phase 'verify' expects branch 'develop' — you are on '$BRANCH'"
-      echo ""
-    fi
-    ;;
-  release)
-    if [ "$BRANCH" != "stage" ]; then
-      echo "⚠️  [specky-session-banner] Phase 'release' expects branch 'stage' — you are on '$BRANCH'"
-      echo ""
-    fi
-    ;;
-esac
-
-exit 0
+echo "🧭 Specky Feature Context"
+echo "   Feature:  ${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}"
+echo "   Contract: $SPECKY_CONTRACT_ID"
+echo "   Phase:    $SPECKY_PHASE"
+echo "   Branch:   $BRANCH"
+echo "   Resume:   @specky-orchestrator or /specky-orchestrate"
+if [ "${SPECKY_RELEASE_ENABLED:-0}" = "1" ]; then
+  echo "   Release:  head=${SPECKY_BRANCH_PREFIX}${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME} base=$SPECKY_BASE_BRANCH"
+fi

package/.apm/hooks/scripts/specky-spec-quality.sh

@@ -5,9 +5,12 @@
 # Paper: arXiv:2601.03878 — EARS quality
 
 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"
 SPEC="$LATEST/SPECIFICATION.md"
 [ -f "$SPEC" ] || exit 0
 
@@ -15,8 +18,8 @@ echo "📋 Spec Quality Check: $SPEC"
 
 # Count requirements (POSIX ERE for macOS/Linux portability)
 REQ_COUNT=$(grep -cE 'REQ-[A-Z]+-[0-9]+' "$SPEC" 2>/dev/null || echo "0")
-if [ "$REQ_COUNT" -lt 5 ]; then
-  echo "⚠️  Only $REQ_COUNT requirements found (minimum 5)."
+if [ "$REQ_COUNT" -lt 1 ]; then
+  echo "⚠️  No requirements found. The contract requires source-backed requirements, not a fixed generic count."
 fi
 
 # Check REQ-ID format consistency

package/.apm/hooks/scripts/specky-spec-sync.sh

@@ -8,19 +8,20 @@
 #   "hooks": { "PostToolUse": ["bash .claude/hooks/specky-spec-sync.sh"] }
 
 set -euo pipefail
-SPECS_DIR=".specs"
-[ -d "$SPECS_DIR" ] || exit 0
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+. "$SCRIPT_DIR/specky-contract-context.bash"
+specky_load_contract_context || exit $?
+[ "${SPECKY_CONTEXT_ACTIVE:-0}" = "1" ] || exit 0
 
 DRIFT=0
-for dir in "$SPECS_DIR"/*/; do
-  [ -f "$dir/SPECIFICATION.md" ] || continue
-  REQS=$(grep -oE 'REQ-[A-Z]+-[0-9]+' "$dir/SPECIFICATION.md" 2>/dev/null | sort -u)
-  for req in $REQS; do
-    if ! grep -rq "$req" src/ tests/ test/ __tests__/ 2>/dev/null; then
-      echo "⚠️  DRIFT: $req ($(basename "$dir")) — not found in code or tests"
-      DRIFT=1
-    fi
-  done
+dir="$SPECKY_FEATURE_DIR"
+[ -f "$dir/SPECIFICATION.md" ] || exit 0
+REQS=$(grep -oE 'REQ-[A-Z]+-[0-9]+' "$dir/SPECIFICATION.md" 2>/dev/null | sort -u)
+for req in $REQS; do
+  if ! grep -rq "$req" src/ tests/ test/ __tests__/ 2>/dev/null; then
+    echo "⚠️  DRIFT: $req (${SPECKY_FEATURE_NUMBER}-${SPECKY_FEATURE_NAME}) — not found in code or tests"
+    DRIFT=1
+  fi
 done
 
 [ "$DRIFT" -eq 1 ] && echo "📋 Run sdd_check_sync for details. If intentional, run sdd_amend."

package/.apm/hooks/scripts/specky-task-tracer.sh

@@ -5,9 +5,12 @@
 # Paper: arXiv:2602.00180 — SDD traceability
 
 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"
 TASKS="$LATEST/TASKS.md"
 [ -f "$TASKS" ] || exit 0
 

package/.apm/hooks/specky-run.sh

@@ -6,6 +6,7 @@ SCRIPT="${1:?usage: specky-run.sh <script-name> [--blocking]}"
 BLOCKING="${2:-}"
 HOOK=".cursor/hooks/scripts/${SCRIPT}"
 INPUT=$(cat || true)
+[ -n "$INPUT" ] && export SDD_HOOK_INPUT="$INPUT"
 
 if command -v jq >/dev/null 2>&1 && [ -n "$INPUT" ]; then
   RAW=$(echo "$INPUT" | jq -r '
@@ -19,6 +20,8 @@ if command -v jq >/dev/null 2>&1 && [ -n "$INPUT" ]; then
 
   PROMPT=$(echo "$INPUT" | jq -r '.prompt // .user_prompt // .text // empty' 2>/dev/null || true)
   [ -n "$PROMPT" ] && export CLAUDE_USER_PROMPT="$PROMPT"
+  WORKSPACE=$(echo "$INPUT" | jq -r '.workspace // .workspace_path // .cwd // .project_dir // empty' 2>/dev/null || true)
+  [ -n "$WORKSPACE" ] && export SPECKY_HOOK_WORKSPACE="$WORKSPACE"
 fi
 
 set +e

package/.apm/instructions/claude-instructions.instructions.md

@@ -13,14 +13,14 @@ This project uses Spec-Driven Development (SDD) via the Specky pipeline.
 3. **Model routing matters.** Use a fast model class for lightweight scaffolding (Phase 0, 9), a balanced model class for iterative delivery (Phase 1, 5-7), and a reasoning-focused model class for complex analysis and design (Phase 2-4, 8). The user chooses any available model.
 4. **Never skip hooks.** Blocking hooks (specky-security-scan, specky-release-gate) must pass before release.
 5. **Artifacts live in `.specs/NNN-feature/`.** CONSTITUTION.md, RESEARCH.md, SPECIFICATION.md, DESIGN.md, TASKS.md, VERIFICATION.md, ANALYSIS.md.
-6. **One branch per spec.** Create `spec/NNN-feature-name` from `develop` for all pipeline work (Phases 0-7). All `.specs/` artifacts are created on this branch. Merge to `develop` after verification, then `stage` for QA and release gates, then `main` for production. Never commit spec work directly to develop, stage, or main.
+6. **Branch policy is explicit.** Use `capability_config.release.branch_prefix` and `base_branch` when release capability is enabled. Do not invent Gitflow branches or create a branch during Init.
 7. **Load companion SKILL.md first.** Every agent reads its companion skill file (`.claude/skills/{skill-name}/SKILL.md`) as the first workflow step. Phase agents have dedicated skills (specky-sdd-init, specky-spec-engineer, specky-sdd-clarify, specky-design-architect, specky-task-planner, specky-quality-reviewer); shared pipeline context lives in specky-sdd-pipeline.
-8. **Orchestrator is the single entry point.** When `.specs/` exists with an active pipeline (`.sdd-state.json` present), ALL work — code, branches, commits, PRs — MUST flow through `@specky-orchestrator`. Direct calls to phase agents, manual branch creation outside `spec/NNN-*`, or free-form edits bypass the quality gates and are pipeline violations. If unsure where to start, invoke `@specky-onboarding`. Starting in v3.5, `specky-pipeline-guard` hook enforces this automatically.
+8. **Orchestrator is the single entry point.** When a feature directory contains signed `.sdd-state.json`, work flows through `@specky-orchestrator` and the persisted contract. Calls that omit feature identity, capability policy, or phase gates are pipeline violations. If unsure where to start, invoke `@specky-onboarding`.
 
 ## Available Agents
 
 - @specky-onboarding — Interactive wizard and default entry point
-- @specky-orchestrator — Full pipeline coordinator (all 10 phases)
+- @specky-orchestrator — Contracted phase-graph coordinator
 - @specky-sdd-init — Initialize pipeline (Phase 0)
 - @specky-requirements-engineer — Produce FRD + NFRD
 - @specky-research-analyst — Technical research (Phase 1)

package/.apm/instructions/copilot-instructions.instructions.md

@@ -13,14 +13,14 @@ This project uses Spec-Driven Development (SDD) via the Specky pipeline.
 3. **Model routing matters.** Use a fast model class for lightweight scaffolding (Phase 0, 9), a balanced model class for iterative delivery (Phase 1, 5-7), and a reasoning-focused model class for complex analysis and design (Phase 2-4, 8). The user chooses any available model.
 4. **Never skip hooks.** Blocking hooks (specky-security-scan, specky-release-gate) must pass before release.
 5. **Artifacts live in `.specs/NNN-feature/`.** CONSTITUTION.md, RESEARCH.md, SPECIFICATION.md, DESIGN.md, TASKS.md, VERIFICATION.md, ANALYSIS.md.
-6. **One branch per spec.** Create `spec/NNN-feature-name` from `develop` for all pipeline work (Phases 0-7). All `.specs/` artifacts are created on this branch. Merge to `develop` after verification, then `stage` for QA and release gates, then `main` for production. Never commit spec work directly to develop, stage, or main.
+6. **Branch policy is explicit.** Use `capability_config.release.branch_prefix` and `base_branch` when release capability is enabled. Do not invent Gitflow branches or create a branch during Init.
 7. **Load companion SKILL.md first.** Every agent reads its companion skill file (`.github/skills/{skill-name}/SKILL.md`) as the first workflow step. Phase agents have dedicated skills (specky-sdd-init, specky-spec-engineer, specky-sdd-clarify, specky-design-architect, specky-task-planner, specky-quality-reviewer); shared pipeline context lives in specky-sdd-pipeline.
-8. **Orchestrator is the single entry point.** When `.specs/` exists with an active pipeline (`.sdd-state.json` present), ALL work — code, branches, commits, PRs — MUST flow through `@specky-orchestrator`. Direct calls to phase agents, manual branch creation outside `spec/NNN-*`, or free-form edits bypass the quality gates and are pipeline violations. If unsure where to start, invoke `@specky-onboarding`. Starting in v3.5, `specky-pipeline-guard` hook enforces this automatically.
+8. **Orchestrator is the single entry point.** When a feature directory contains signed `.sdd-state.json`, work flows through `@specky-orchestrator` and the persisted contract. Calls that omit feature identity, capability policy, or phase gates are pipeline violations. If unsure where to start, invoke `@specky-onboarding`.
 
 ## Available Agents
 
 - @specky-onboarding — Interactive wizard and default entry point
-- @specky-orchestrator — Full pipeline coordinator (all 10 phases)
+- @specky-orchestrator — Contracted phase-graph coordinator
 - @specky-sdd-init — Initialize pipeline (Phase 0)
 - @specky-requirements-engineer — Produce FRD + NFRD
 - @specky-research-analyst — Technical research (Phase 1)

package/.apm/instructions/cursor-instructions.instructions.md

@@ -13,14 +13,14 @@ This project uses Spec-Driven Development (SDD) via the Specky pipeline.
 3. **Model routing matters.** Use a fast model class for lightweight scaffolding (Phase 0, 9), a balanced model class for iterative delivery (Phase 1, 5-7), and a reasoning-focused model class for complex analysis and design (Phase 2-4, 8).
 4. **Never skip hooks.** Blocking hooks (specky-security-scan, specky-release-gate, specky-artifact-validator, specky-phase-gate) must pass before release.
 5. **Artifacts live in `.specs/NNN-feature/`.** CONSTITUTION.md, RESEARCH.md, SPECIFICATION.md, DESIGN.md, TASKS.md, VERIFICATION.md, ANALYSIS.md.
-6. **One branch per spec.** Create `spec/NNN-feature-name` from `develop` for all pipeline work (Phases 0-7). Merge to `develop` after verification, then `stage` for QA, then `main` for production.
+6. **Branch policy is explicit.** Use the persisted release branch prefix and base branch. Do not invent Gitflow branches or create a branch during Init.
 7. **Load companion SKILL.md first.** Every agent reads `.agents/skills/{skill-name}/SKILL.md` as the first workflow step. Phase agents have dedicated skills (specky-sdd-init, specky-spec-engineer, specky-sdd-clarify, specky-design-architect, specky-task-planner, specky-quality-reviewer); shared pipeline context lives in specky-sdd-pipeline.
-8. **Orchestrator is the single entry point.** When `.specs/` exists with an active pipeline (`.sdd-state.json` present), ALL work MUST flow through `@specky-orchestrator`. If unsure where to start, invoke `@specky-onboarding`.
+8. **Orchestrator is the single entry point.** When a feature directory contains signed `.sdd-state.json`, work follows its persisted contract through `@specky-orchestrator`. If unsure where to start, invoke `@specky-onboarding`.
 
 ## Available Agents
 
 - @specky-onboarding — Interactive wizard and default entry point
-- @specky-orchestrator — Full pipeline coordinator (all 10 phases)
+- @specky-orchestrator — Contracted phase-graph coordinator
 - @specky-sdd-init — Initialize pipeline (Phase 0)
 - @specky-requirements-engineer — Produce FRD + NFRD
 - @specky-research-analyst — Technical research (Phase 1)

package/.apm/instructions/opencode-instructions.instructions.md

@@ -18,9 +18,9 @@ OpenCode requires two steps after install:
 1. **EARS notation is mandatory.** Every requirement must follow one of the 6 EARS patterns.
 2. **REQ-ID traceability is non-negotiable.** Every test, task, and design decision traces to a REQ-ID.
 3. **Artifacts live in `.specs/NNN-feature/`.** CONSTITUTION.md, SPECIFICATION.md, DESIGN.md, TASKS.md, ANALYSIS.md, VERIFICATION.md.
-4. **One branch per spec.** Create `spec/NNN-feature-name` from `develop` for pipeline work (Phases 0-7).
+4. **Branch policy is explicit.** Use the persisted release branch prefix and base branch. Do not invent Gitflow branches or create a branch during Init.
 5. **Load companion SKILL.md first.** Read `.agents/skills/{skill-name}/SKILL.md` before phase work.
-6. **Orchestrator is the single entry point.** When `.specs/` has an active pipeline, route work through `@specky-orchestrator` or `/specky-orchestrate`.
+6. **Orchestrator is the single entry point.** When a feature directory has signed state, route work through `@specky-orchestrator` or `/specky-orchestrate` and follow its persisted contract.
 
 ## Available Agents