@sdd-method/verify-cli 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdd-method/verify-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Verify an SDD repository without changing it — validate, list, and read-only catalogue and pack checks. Ships only the code those verbs reach; it cannot write to the repository it is pointed at. Authoring and maintenance are in @sdd-method/sdd-cli.",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,6 +25,7 @@
   },
   "files": [
     "dist",
+    "scripts",
     "README.md",
     "LICENSE",
     "NOTICE"

package/scripts/validate-app-dependencies.sh

@@ -0,0 +1,644 @@
+#!/bin/bash
+#
+# validate-app-dependencies.sh - Validate app platform dependency declarations
+#
+# Usage:
+#   ./validate-app-dependencies.sh --app-root <path> [--platform-root <path>]
+#
+# --platform-root is OPTIONAL. Without it the checks that need no platform surface
+# still run, and the ones that do are reported as NOT RUN with their denominator —
+# a partial run, never a met gate. See the block above the flag parsing.
+#
+# Checks (for each entry in app-platform-dependencies.yaml), split by whether they
+# need a platform surface at all — LOCAL checks run wherever the app repo is:
+#   1.  (local)    required_stability is a valid value (provisional | locked | unknown)
+#   2a. (local)    service_id is declared and non-empty
+#   2b. (platform) service_id resolves against the platform source of truth:
+#                  catalogues/services.csv (exact id match) when the catalogue exists,
+#                  else docs/platform/service-architecture.md (word-anchored match)
+#   3a. (local)    a `locked` dependency declares a contract_path at all
+#   3b. (platform) that contract_path resolves to a file under the platform root
+#
+# Outputs a dependency status table.
+# Used as the Stage 6 lock-in gate in the App Exploration Workflow.
+#
+# THE STABILITY VOCABULARY, AND WHY IT IS WHAT IT IS
+#   `required_stability` states the CONSUMING app's expectation of contract
+#   stability. Three values express that:
+#
+#     provisional  the contract may still change; the app tolerates it
+#     locked       the contract is fixed; a contract_path must exist (check 3)
+#     unknown      the expectation is not determined
+#
+#   `unknown` is accepted because the canonical schema's
+#   product_platform_dependencies table and the distributed reverse template
+#   both offer it, and this gate was the only surface rejecting it — an adopter
+#   filling in the method's own template produced a file the method's own gate
+#   hard-failed. Reverse-derived declarations legitimately cannot always
+#   determine the expectation, and naming that is better than encoding it as
+#   silence (M-ADR 0196). It does not require a contract_path.
+#
+#   `external` and `legacy` are NOT stability values and are reported as
+#   warnings, not failures. They answer different questions — where the target
+#   lives, and what lifecycle its implementation is in — on a field that asks
+#   how stable the consumer needs the contract to be. A third-party API can be
+#   more stable than an internal one, so the two axes are orthogonal. They are
+#   warned rather than failed because they encode real information for which no
+#   replacement field exists yet: an `external` target is a declaration that the
+#   dependency does not resolve against platform services at all, which is the
+#   method's external-system concept (M-ADR 0189), not a stability claim. Failing
+#   them before that route exists would force an adopter to discard the
+#   information to get green. They become failures when the locus field ships.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_fail() { echo -e "${RED}[FAIL]${NC} $1"; }
+log_pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+log_section() {
+    echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
+    echo -e "${BLUE}  $1${NC}"
+    echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}\n"
+}
+
+APP_ROOT=""
+PLATFORM_ROOT=""
+
+usage() {
+    cat <<USAGE
+Usage: $(basename "$0") --app-root <path> [--platform-root <path>]
+
+Options:
+  --app-root       Path to the app repository root (must contain app-platform-dependencies.yaml)
+  --platform-root  OPTIONAL. Path to the platform repository root (service_id checks use
+                   catalogues/services.csv when present, else docs/platform/service-architecture.md).
+                   Omitted: the stability vocabulary and the local halves of the
+                   service_id/contract_path checks run; the resolutions are reported
+                   as not run. The gate is not met by a partial run.
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --app-root)
+            APP_ROOT="${2:-}"
+            shift 2
+            ;;
+        --platform-root)
+            PLATFORM_ROOT="${2:-}"
+            shift 2
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            log_fail "Unknown argument: $1"
+            usage
+            exit 1
+            ;;
+    esac
+done
+
+if [[ -z "$APP_ROOT" ]]; then
+    log_fail "--app-root is required"
+    usage
+    exit 1
+fi
+
+if [[ ! -d "$APP_ROOT" ]]; then
+    log_fail "App root not found: $APP_ROOT"
+    exit 1
+fi
+
+# --platform-root is OPTIONAL, and this is the whole of why:
+#
+#   Only checks 2 and 3 need a platform surface. Check 1 is local to the app repo.
+#   While the flag was mandatory, an app repo standing alone could run NONE of the
+#   three — the validator was skipped wholesale by the dispatcher, so it had never
+#   executed in any of the 70 dependency files across two estates, and the suite
+#   reported "All validators passed" over the skip.
+#
+#   Without a platform root the checks that CAN run, run, and the checks that
+#   cannot are named as not-run with their denominator. Absent evidence is
+#   reported as absent, never as a pass (M-ADR 0200 §4.3) — the same treatment
+#   validate-gate-readiness.sh gives an empty registry.
+PLATFORM_AVAILABLE=1
+if [[ -z "$PLATFORM_ROOT" ]]; then
+    PLATFORM_AVAILABLE=0
+elif [[ ! -d "$PLATFORM_ROOT" ]]; then
+    # An explicitly-given root that does not exist is an error, not a downgrade:
+    # the caller asserted a platform surface that is not there.
+    log_fail "Platform root not found: $PLATFORM_ROOT"
+    exit 1
+fi
+
+APP_DEPS_FILE="$APP_ROOT/app-platform-dependencies.yaml"
+
+# TWO AUTHORING SOURCES, NOT ONE.
+#   The catalogue builder does multi-source ingestion under the ADR 0157 parity
+#   principle: `app-platform-dependencies.yaml` AND every
+#   `reverse-evidence/**/feature-grounding-evidence.yaml`'s platform_dependencies
+#   block, merged by primary key with forward winning. They are equal-status
+#   authoring surfaces.
+#
+#   This gate read only the forward file, so an entire equal-status source went
+#   ungated. Measured in one reverse estate: 15 evidence files declaring 65
+#   further dependencies, 38 of them `locked` — precisely the lock-in population
+#   a Stage 6 lock-in gate exists to check — none of which this gate could see.
+#
+#   A source that the catalogue reads and the gate does not is a coverage gap by
+#   construction, so the gate now reads both.
+DEP_SOURCES=()
+if [[ -f "$APP_DEPS_FILE" ]]; then
+    DEP_SOURCES+=("$APP_DEPS_FILE")
+fi
+if [[ -d "$APP_ROOT/reverse-evidence" ]]; then
+    while IFS= read -r evidence_file; do
+        [[ -n "$evidence_file" ]] || continue
+        DEP_SOURCES+=("$evidence_file")
+    done < <(find "$APP_ROOT/reverse-evidence" -name "feature-grounding-evidence.yaml" -type f | sort)
+fi
+PLATFORM_SERVICE_ARCH="$PLATFORM_ROOT/docs/platform/service-architecture.md"
+PLATFORM_SERVICES_CSV="$PLATFORM_ROOT/catalogues/services.csv"
+
+# One value per line: this array is the enforcement point, and the correspondence
+# registry reads it line-wise to compare against what the distributed templates
+# offer (instances app-dependency-stability-vocabulary-forward and -reverse).
+VALID_STABILITY_VALUES=(
+    "provisional"  # contract may still change; the app tolerates it
+    "locked"       # contract is fixed; check 3 requires a resolvable contract_path
+    "unknown"      # expectation not determined; no contract_path required
+)
+
+# M-ADR 0204: where the dependency's TARGET lives. One value per line — the
+# correspondence registry reads this array line-wise against what the
+# distributed templates offer, exactly as it does VALID_STABILITY_VALUES.
+# Single-quoted deliberately: the correspondence extractor for the STABILITY
+# array captures `^    "value"` lines, and two enums sharing one line shape
+# would pollute each other's claimed sets — measured, not hypothetical.
+VALID_TARGET_LOCUS_VALUES=(
+    'platform'  # the default when absent; the row is fully platform-validated
+    'external'  # third-party target; platform resolution + realiser join skipped, named
+    'legacy'    # off-platform predecessor system; same skips, different lifecycle
+)
+
+# The pre-0204 improvisation. These were WARNED while no locus field existed;
+# M-ADR 0204 §4.4 flips them to FAILURES now that it does — the message names
+# the home for what they meant.
+DEPRECATED_STABILITY_VALUES=("external" "legacy")
+
+# The M-ADR 0192 async set. A shared-stream subscription has NO single realiser
+# service, so it binds to the stream contract plus the publishing capability
+# instead — the canonical schema makes product_platform_dependencies.
+# target_service_id conditionally nullable for exactly these contract types, and
+# states that a synchronous contract_type still requires it.
+#
+# This gate did not know that. Check 2a hard-failed "service_id is empty or
+# missing" on every async entry, which is the shape both distributed templates
+# instruct an author to write (they say to OMIT service_id). Found the moment the
+# check first ran: 3 of the reverse estate's 48 dependency files, all three async.
+ASYNC_CONTRACT_TYPES=("event" "event-stream" "stream")
+
+FAILURES=0
+WARNINGS=0
+TOTAL_DEPS=0
+PASSED_DEPS=0
+
+# What could not be checked for want of a platform surface. Counted, not ignored:
+# the summary states these as a denominator so a run without a platform root can
+# never read as a clean bill of health on the resolution checks.
+UNPARSEABLE_SOURCES=0
+SOURCE_DEP_COUNT=0
+UNRESOLVED_SERVICE_IDS=0
+UNRESOLVED_CONTRACT_PATHS=0
+
+# ──────────────────────────────────────────────────────────────────────────────
+check_prerequisites() {
+    log_section "Prerequisites"
+
+    if [[ ${#DEP_SOURCES[@]} -eq 0 ]]; then
+        log_fail "no dependency source found: neither $APP_DEPS_FILE nor any reverse-evidence/**/feature-grounding-evidence.yaml"
+        exit 1
+    fi
+    for src in "${DEP_SOURCES[@]}"; do
+        log_pass "dependency source: ${src#"$APP_ROOT"/}"
+    done
+
+    if ! command -v yq &>/dev/null; then
+        log_fail "yq is required but not installed. Install with: brew install yq"
+        exit 1
+    fi
+    log_pass "yq available"
+
+    if [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
+        PLATFORM_SERVICES_CSV=""
+        PLATFORM_SERVICE_ARCH=""
+        log_info "No --platform-root given: check 1 (stability vocabulary) runs; checks 2 and 3 do not."
+        return 0
+    fi
+
+    if [[ -f "$PLATFORM_SERVICES_CSV" ]]; then
+        log_pass "Platform services catalogue found (canonical service_id source)"
+    else
+        PLATFORM_SERVICES_CSV=""
+    fi
+
+    if [[ ! -f "$PLATFORM_SERVICE_ARCH" ]]; then
+        log_warn "Platform service-architecture.md not found: $PLATFORM_SERVICE_ARCH"
+        PLATFORM_SERVICE_ARCH=""
+    else
+        log_pass "Platform service-architecture.md found"
+    fi
+
+    if [[ -z "$PLATFORM_SERVICES_CSV" && -z "$PLATFORM_SERVICE_ARCH" ]]; then
+        log_warn "Neither services catalogue nor service-architecture.md found — service_id validation will be skipped"
+    fi
+}
+
+# Is this value shaped like a path, as opposed to a sentinel or a prose note?
+# Mirrors isPathShaped() in the CLI's contract-path-resolution.ts, which applies
+# the same test at aggregation tier — one rule, asserted at both tiers.
+is_path_shaped() {
+    local v="$1"
+    [[ -n "$v" && "$v" != "null" ]] || return 1
+    [[ "${v,,}" != n/a* ]] || return 1
+    [[ "${v:0:1}" != "[" ]] || return 1
+    [[ "$v" == */* ]] || return 1
+    # Prose gives itself away with whitespace before the first separator.
+    local first="${v%%/*}"
+    [[ "$first" != *[[:space:]]* ]] || return 1
+    return 0
+}
+
+# Word-anchored match: the id must not be a substring of a longer slug token.
+service_id_in_doc() {
+    local service_id="$1"
+    grep -qE "(^|[^a-zA-Z0-9-])${service_id}([^a-zA-Z0-9-]|$)" "$PLATFORM_SERVICE_ARCH" 2>/dev/null
+}
+
+service_id_in_catalogue() {
+    local service_id="$1"
+    awk -F',' -v id="$service_id" 'NR>1 && $1==id {found=1} END {exit !found}' "$PLATFORM_SERVICES_CSV" 2>/dev/null
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# How many platform_dependencies entries does this source declare? Zero for a
+# source that has no such block, and zero — with a reported finding — for one that
+# cannot be parsed. An unparseable evidence file is NOT silently treated as empty:
+# measured in one estate, a single unquoted colon made a 206-line authored file
+# invisible, taking its dependency declarations with it.
+# Sets SOURCE_DEP_COUNT, and increments UNPARSEABLE_SOURCES on a broken source.
+#
+# Deliberately NOT a function that echoes its answer: a command substitution runs
+# in a subshell, so the counter increment would be discarded and the log line
+# would be captured as part of the count. Both happened; both are silent in bash.
+read_source_dep_count() {
+    local source_file="$1"
+    if ! SOURCE_DEP_COUNT="$(yq e ".platform_dependencies | length" "$source_file" 2>/dev/null)"; then
+        log_fail "${source_file#"$APP_ROOT"/}: cannot be parsed as YAML — every dependency it declares is invisible to this gate and to the catalogue"
+        UNPARSEABLE_SOURCES=$((UNPARSEABLE_SOURCES + 1))
+        SOURCE_DEP_COUNT=0
+        return
+    fi
+    [[ "$SOURCE_DEP_COUNT" =~ ^[0-9]+$ ]] || SOURCE_DEP_COUNT=0
+}
+
+# Quiet variant for the display pass — the failure was already reported when the
+# sources were counted; reporting it twice would double-count nothing useful.
+quiet_dep_count() {
+    local source_file="$1" count
+    count="$(yq e ".platform_dependencies | length" "$source_file" 2>/dev/null || echo 0)"
+    [[ "$count" =~ ^[0-9]+$ ]] || count=0
+    echo "$count"
+}
+
+validate_dependency() {
+    local source_file="$1"
+    local index="$2"
+    local dep_errors=0
+
+    local capability_id service_id contract_type required_stability contract_path
+
+    capability_id="$(yq e ".platform_dependencies[$index].capability_id // \"\"" "$source_file")"
+    service_id="$(yq e ".platform_dependencies[$index].service_id // \"\"" "$source_file")"
+    contract_type="$(yq e ".platform_dependencies[$index].contract_type // \"\"" "$source_file")"
+    required_stability="$(yq e ".platform_dependencies[$index].required_stability // \"\"" "$source_file")"
+    contract_path="$(yq e ".platform_dependencies[$index].contract_path // \"\"" "$source_file")"
+
+    local dep_label="${service_id:-dep[$index]}"
+    if [[ -n "$capability_id" && "$capability_id" != "null" ]]; then
+        dep_label="$capability_id / $service_id"
+    fi
+
+    # M-ADR 0204: target locus. Absent = platform. Invalid FAILS — this field is
+    # new, has no legacy corpus, and a tolerated typo would silently exempt the
+    # row from every platform check.
+    local target_locus
+    target_locus="$(yq e ".platform_dependencies[$index].target_locus // \"\"" "$source_file")"
+    [[ "$target_locus" == "null" ]] && target_locus=""
+    if [[ -z "$target_locus" ]]; then
+        target_locus="platform"
+    elif [[ " ${VALID_TARGET_LOCUS_VALUES[*]} " != *" $target_locus "* ]]; then
+        log_fail "$dep_label: invalid target_locus '$target_locus' (allowed: ${VALID_TARGET_LOCUS_VALUES[*]})"
+        ((dep_errors++))
+        target_locus="platform"
+    fi
+
+    # Check 1: required_stability is a valid value. Needs NO platform surface —
+    # it is the only check that can run in an app repo standing alone.
+    local stability_valid=0
+    for v in "${VALID_STABILITY_VALUES[@]}"; do
+        if [[ "$required_stability" == "$v" ]]; then
+            stability_valid=1
+            break
+        fi
+    done
+
+    if [[ "$stability_valid" -eq 0 && ( -z "$required_stability" || "$required_stability" == "null" ) ]]; then
+        # ABSENT is not INVALID. The canonical schema declares
+        # required_stability nullable on both tables that carry it, so an entry
+        # without one is schema-legal and the gate must not contradict its own
+        # schema — that is exactly the defect the `unknown` alignment fixed.
+        # Reported all the same: M-ADR 0196 prefers a named gap to a silent one,
+        # and `unknown` now exists to name this one explicitly.
+        log_warn "$dep_label: required_stability is absent — schema-legal (nullable), but state it explicitly as 'unknown' so the gap is named rather than inferred"
+        ((WARNINGS++))
+    elif [[ "$stability_valid" -eq 0 ]]; then
+        local stability_deprecated=0
+        for v in "${DEPRECATED_STABILITY_VALUES[@]}"; do
+            if [[ "$required_stability" == "$v" ]]; then
+                stability_deprecated=1
+                break
+            fi
+        done
+
+        if [[ "$stability_deprecated" -eq 1 ]]; then
+            log_fail "$dep_label: required_stability '$required_stability' is not a stability value (M-ADR 0204 §4.4). Declare target_locus: '$required_stability' on the entry and give required_stability a real value (${VALID_STABILITY_VALUES[*]}) — a third-party contract can be locked."
+            ((dep_errors++))
+        else
+            log_fail "$dep_label: invalid required_stability '$required_stability' (allowed: ${VALID_STABILITY_VALUES[*]})"
+            ((dep_errors++))
+        fi
+    fi
+
+    # M-ADR 0204: an off-platform row skips platform resolution and the realiser
+    # join — NAMED, never silent. It must still bind to something (an
+    # external-system id in service_id, or a contract_path), and a capability_id
+    # on it is reported per §4.3.
+    if [[ "$target_locus" != "platform" ]]; then
+        if [[ -n "$capability_id" && "$capability_id" != "null" ]]; then
+            log_warn "$dep_label: capability_id on a target_locus=$target_locus row — an off-platform target has no platform capability (M-ADR 0204 §4.3); move the intent to notes"
+            ((WARNINGS++))
+        fi
+        if [[ ( -z "$service_id" || "$service_id" == "null" ) && ( -z "$contract_path" || "$contract_path" == "null" ) ]]; then
+            log_fail "$dep_label: target_locus=$target_locus entry names neither an external-system id (service_id) nor a contract_path — it binds to nothing"
+            ((dep_errors++))
+        else
+            log_info "$dep_label: target_locus=$target_locus — platform service/contract resolution NOT APPLICABLE (skipped, M-ADR 0204 §4.1); corroboration against external systems happens at aggregation"
+        fi
+        if [[ "$dep_errors" -eq 0 ]]; then
+            log_pass "$dep_label: locus=$target_locus stability=$required_stability type=$contract_type"
+            ((PASSED_DEPS++))
+            return 0
+        fi
+        FAILURES=$((FAILURES + dep_errors))
+        return 1
+    fi
+
+    # Check 2: service_id is declared (2a, local) and resolves against the platform
+    # source of truth (2b, needs the platform). The services catalogue (when present)
+    # is canonical — the same source the aggregator FK-validates dependency edges
+    # against. The prose service-architecture.md is the fallback for pre-catalogue
+    # platforms.
+    #
+    # 2a and 2b are separated because only 2b needs a platform surface: whether a
+    # service_id was declared at all is answerable in the app repo alone, and it is
+    # the more basic defect of the two.
+    local is_async=0
+    if [[ " ${ASYNC_CONTRACT_TYPES[*]} " == *" $contract_type "* ]]; then
+        is_async=1
+    fi
+
+    if [[ -z "$service_id" || "$service_id" == "null" ]]; then
+        if [[ "$is_async" -eq 1 ]]; then
+            # No realiser service by design (M-ADR 0192). It must still name what it
+            # DOES bind to, or nothing identifies the dependency at all — the
+            # aggregator drops such a row, so an unchecked hole here is a silent drop.
+            if [[ -z "$contract_path" || "$contract_path" == "null" ]]; then
+                log_fail "$dep_label: async dependency (contract_type '$contract_type') has neither service_id nor contract_path — it binds to nothing and cannot be recorded"
+                ((dep_errors++))
+            fi
+        else
+            log_fail "$dep_label: service_id is empty or missing"
+            ((dep_errors++))
+        fi
+    elif [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
+        ((UNRESOLVED_SERVICE_IDS++))
+    elif [[ -n "$PLATFORM_SERVICES_CSV" ]]; then
+        if ! service_id_in_catalogue "$service_id"; then
+            log_fail "$dep_label: service_id '$service_id' not found in platform services catalogue (catalogues/services.csv)"
+            ((dep_errors++))
+        elif [[ -n "$PLATFORM_SERVICE_ARCH" ]] && ! service_id_in_doc "$service_id"; then
+            log_warn "$dep_label: service_id '$service_id' is in the services catalogue but not mentioned in service-architecture.md (doc drift)"
+            ((WARNINGS++))
+        fi
+    elif [[ -n "$PLATFORM_SERVICE_ARCH" ]]; then
+        if ! service_id_in_doc "$service_id"; then
+            log_fail "$dep_label: service_id '$service_id' not found in platform service-architecture.md"
+            ((dep_errors++))
+        fi
+    fi
+
+    # Check 3c (local): a DECLARED contract_path must actually be a path. The field
+    # was long typed "<platform-relative-path-or-unknown>", which invited sentinels
+    # (`n/a`) and prose ("Kafka (<vendor> bus): topic-a") into a field every consumer
+    # resolves as a path. Reported where it is authored; the aggregator reports the
+    # same class as `convention` when it tries to resolve them. Warned, not failed:
+    # the corpus predates the rule and the explanation belongs in `notes` (0200 §4.6).
+    if [[ -n "$contract_path" && "$contract_path" != "null" ]] && ! is_path_shaped "$contract_path"; then
+        log_warn "$dep_label: contract_path \"$contract_path\" is not a path — nothing can resolve it; omit the field and put the explanation in notes"
+        ((WARNINGS++))
+    fi
+
+    # Check 3: a locked dependency declares a contract_path (3a, local) and that path
+    # resolves to a file (3b, needs the platform). Same split, same reason: "locked
+    # with no path at all" is an app-repo defect that needs nothing external to catch.
+    if [[ "$required_stability" == "locked" ]]; then
+        if [[ -z "$contract_path" || "$contract_path" == "null" ]]; then
+            log_fail "$dep_label: required_stability is 'locked' but contract_path is empty"
+            ((dep_errors++))
+        elif [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
+            ((UNRESOLVED_CONTRACT_PATHS++))
+        else
+            local full_contract_path="$PLATFORM_ROOT/$contract_path"
+            if [[ ! -f "$full_contract_path" ]]; then
+                log_fail "$dep_label: locked contract_path '$contract_path' does not exist in platform repo"
+                ((dep_errors++))
+            fi
+        fi
+    elif [[ "$required_stability" == "provisional" || "$required_stability" == "unknown" ]]; then
+        # Neither requires a contract_path. If one is declared it is still worth
+        # reporting when it does not resolve — silently accepting a path that
+        # points at nothing is how a locked dependency later inherits a dead path.
+        if [[ -n "$contract_path" && "$contract_path" != "null" && "$PLATFORM_AVAILABLE" -eq 1 ]]; then
+            local full_contract_path="$PLATFORM_ROOT/$contract_path"
+            if [[ ! -f "$full_contract_path" ]]; then
+                log_warn "$dep_label: contract_path '$contract_path' declared but not yet present ($required_stability — acceptable)"
+                ((WARNINGS++))
+            fi
+        fi
+    fi
+
+    if [[ "$dep_errors" -eq 0 ]]; then
+        log_pass "$dep_label: stability=$required_stability type=$contract_type"
+        ((PASSED_DEPS++))
+        return 0
+    fi
+
+    FAILURES=$((FAILURES + dep_errors))
+    return 1
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+print_status_table() {
+    log_section "Dependency Status Table"
+
+    local app_id
+    app_id="$(yq e ".app_id // \"unknown\"" "$APP_DEPS_FILE" 2>/dev/null || echo unknown)"
+    log_info "App: $app_id"
+
+    printf "\n  %-30s %-15s %-12s %s\n" "Service ID" "Stability" "Contract" "Status"
+    printf "  %-30s %-15s %-12s %s\n" "──────────────────────────────" "───────────────" "────────────" "──────────"
+
+    local source_file count
+    for source_file in "${DEP_SOURCES[@]}"; do
+    count="$(quiet_dep_count "$source_file")"
+    [[ "$count" -gt 0 ]] || continue
+    if [[ ${#DEP_SOURCES[@]} -gt 1 ]]; then
+        printf "  %s\n" "── ${source_file#"$APP_ROOT"/}"
+    fi
+
+    for ((i = 0; i < count; i++)); do
+        local service_id required_stability contract_type contract_path dep_status
+        service_id="$(yq e ".platform_dependencies[$i].service_id // \"(missing)\"" "$source_file")"
+        required_stability="$(yq e ".platform_dependencies[$i].required_stability // \"(missing)\"" "$source_file")"
+        contract_type="$(yq e ".platform_dependencies[$i].contract_type // \"(missing)\"" "$source_file")"
+        contract_path="$(yq e ".platform_dependencies[$i].contract_path // \"\"" "$source_file")"
+
+        # Determine display status
+        if [[ "$required_stability" == "locked" ]]; then
+            if [[ -z "$contract_path" || "$contract_path" == "null" ]]; then
+                dep_status="${RED}LOCKED UNMET${NC}"
+            elif [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
+                # A declared path that was never resolved is not "OK" and not "UNMET".
+                # Reporting either would be a claim the run cannot support.
+                dep_status="${YELLOW}LOCKED UNRESOLVED${NC}"
+            elif [[ -f "$PLATFORM_ROOT/$contract_path" ]]; then
+                dep_status="${GREEN}LOCKED OK${NC}"
+            else
+                dep_status="${RED}LOCKED UNMET${NC}"
+            fi
+        elif [[ "$required_stability" == "provisional" ]]; then
+            dep_status="${YELLOW}PROVISIONAL${NC}"
+        elif [[ "$required_stability" == "unknown" ]]; then
+            dep_status="${YELLOW}UNKNOWN${NC}"
+        elif [[ " ${DEPRECATED_STABILITY_VALUES[*]} " == *" $required_stability "* ]]; then
+            dep_status="${YELLOW}NOT A STABILITY VALUE${NC}"
+        else
+            dep_status="${RED}INVALID${NC}"
+        fi
+
+        printf "  %-30s %-15s %-12s " "$service_id" "$required_stability" "$contract_type"
+        echo -e "$dep_status"
+    done
+    done
+    echo ""
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+main() {
+    log_section "App Dependency Validation"
+    log_info "App root:      $APP_ROOT"
+    log_info "Platform root: $PLATFORM_ROOT"
+
+    check_prerequisites
+
+    log_section "Validating Dependencies"
+
+    local source_file dep_count
+    TOTAL_DEPS=0
+    for source_file in "${DEP_SOURCES[@]}"; do
+        read_source_dep_count "$source_file"
+        dep_count="$SOURCE_DEP_COUNT"
+        [[ "$dep_count" -gt 0 ]] || continue
+        if [[ ${#DEP_SOURCES[@]} -gt 1 ]]; then
+            log_info "${source_file#"$APP_ROOT"/}: $dep_count dependency(ies)"
+        fi
+        TOTAL_DEPS=$((TOTAL_DEPS + dep_count))
+        for ((i = 0; i < dep_count; i++)); do
+            validate_dependency "$source_file" "$i" || true
+        done
+    done
+
+    if [[ "$TOTAL_DEPS" -eq 0 ]]; then
+        if [[ "$UNPARSEABLE_SOURCES" -gt 0 ]]; then
+            # Zero dependencies BECAUSE the source could not be read is not the
+            # same result as zero dependencies declared, and must not exit alike.
+            log_fail "$UNPARSEABLE_SOURCES dependency source(s) could not be parsed — 0 dependencies checked, which is an absence of evidence, not a pass."
+            exit 1
+        fi
+        log_warn "No platform_dependencies entries found in ${#DEP_SOURCES[@]} source(s)"
+        log_info "If this app has no platform deps, this is acceptable."
+        exit 0
+    fi
+
+    print_status_table
+
+    log_section "Summary"
+    log_info "Total dependencies: $TOTAL_DEPS"
+    log_info "Passed:  $PASSED_DEPS"
+    log_info "Warnings: $WARNINGS"
+    log_info "Failures: $FAILURES"
+
+    if [[ "$UNPARSEABLE_SOURCES" -gt 0 ]]; then
+        log_fail "$UNPARSEABLE_SOURCES dependency source(s) could not be parsed. Whatever they declare was checked by nothing, so no verdict here covers them."
+        exit 1
+    fi
+
+    if [[ "$FAILURES" -gt 0 ]]; then
+        log_fail "$FAILURES dependency check(s) failed. Stage 6 lock-in gate NOT met."
+        exit 1
+    fi
+
+    # Without a platform surface the gate cannot claim to have been met, however
+    # clean the checks it DID run. Naming the un-run checks and their denominator
+    # is the whole point: "no failures" and "the gate is met" are different claims,
+    # and conflating them is how this validator came to report green for months
+    # while never executing (M-ADR 0200 §4.3).
+    if [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
+        log_warn "Ran check 1 (stability vocabulary) and the local halves of checks 2-3 over $TOTAL_DEPS dependency(ies): $FAILURES failure(s), $WARNINGS warning(s)."
+        log_warn "NOT RUN, for want of --platform-root: $UNRESOLVED_SERVICE_IDS service_id resolution(s) and $UNRESOLVED_CONTRACT_PATHS locked contract_path resolution(s)."
+        log_info "This is a partial run, not a met gate — pass --platform-root to complete it."
+        exit 0
+    fi
+
+    if [[ "$WARNINGS" -gt 0 ]]; then
+        log_warn "All required checks passed with $WARNINGS warning(s)."
+    else
+        log_pass "All dependency checks passed. Stage 6 lock-in gate met."
+    fi
+    exit 0
+}
+
+main "$@"

package/scripts/validate-app-docs.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+#
+# validate-app-docs.sh - Validate app repo documentation structure
+#
+# Usage: ./validate-app-docs.sh [--app-root <path>]
+#
+# Checks:
+#   1. service-architecture.md is present
+#   2. feature-tree.md is present (may be at docs/ or repo root)
+#   3. app-platform-dependencies.yaml is present
+#   4. Feature spec files under features/*/ have required sections:
+#      - ## Overview
+#      - ## Acceptance Criteria
+#      - ## Platform Contract Dependencies
+#
+# Does NOT check:
+#   - Glossary alignment (no domain glossary in app repos)
+#   - Cascade completeness (no domain model or capability tier)
+#   - DDD artifacts (no bounded contexts or aggregates)
+#   - Traceability manifests (no capability traceability in app repos)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_fail() { echo -e "${RED}[FAIL]${NC} $1"; }
+log_pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+log_section() {
+    echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
+    echo -e "${BLUE}  $1${NC}"
+    echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}\n"
+}
+
+APP_ROOT="$ROOT_DIR"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --app-root)
+            APP_ROOT="${2:-}"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: $(basename "$0") [--app-root <path>]"
+            exit 0
+            ;;
+        *)
+            log_fail "Unknown argument: $1"
+            exit 1
+            ;;
+    esac
+done
+
+if [[ ! -d "$APP_ROOT" ]]; then
+    log_fail "App root not found: $APP_ROOT"
+    exit 1
+fi
+
+FAILURES=0
+
+# ──────────────────────────────────────────────────────────────────────────────
+check_required_files() {
+    log_section "Group 1: Required App Repo Files"
+
+    local checks_passed=0
+    local checks_failed=0
+
+    # 1a. service-architecture.md
+    local service_arch=""
+    if [[ -f "$APP_ROOT/docs/service-architecture.md" ]]; then
+        service_arch="$APP_ROOT/docs/service-architecture.md"
+    elif [[ -f "$APP_ROOT/service-architecture.md" ]]; then
+        service_arch="$APP_ROOT/service-architecture.md"
+    fi
+
+    if [[ -z "$service_arch" ]]; then
+        log_fail "service-architecture.md not found (checked docs/service-architecture.md and service-architecture.md)"
+        checks_failed=$((checks_failed + 1))
+    else
+        log_pass "service-architecture.md found: ${service_arch#$APP_ROOT/}"
+        checks_passed=$((checks_passed + 1))
+    fi
+
+    # 1b. feature-tree.md
+    local feature_tree=""
+    if [[ -f "$APP_ROOT/docs/platform/feature-tree.md" ]]; then
+        feature_tree="$APP_ROOT/docs/platform/feature-tree.md"
+    elif [[ -f "$APP_ROOT/docs/feature-tree.md" ]]; then
+        feature_tree="$APP_ROOT/docs/feature-tree.md"
+    elif [[ -f "$APP_ROOT/feature-tree.md" ]]; then
+        feature_tree="$APP_ROOT/feature-tree.md"
+    fi
+
+    if [[ -z "$feature_tree" ]]; then
+        log_warn "feature-tree.md not found (checked docs/platform/, docs/, and repo root) — create when features are classified"
+        # warn only; not a hard fail at exploration stage
+    else
+        log_pass "feature-tree.md found: ${feature_tree#$APP_ROOT/}"
+        checks_passed=$((checks_passed + 1))
+    fi
+
+    # 1c. app-platform-dependencies.yaml
+    if [[ -f "$APP_ROOT/app-platform-dependencies.yaml" ]]; then
+        log_pass "app-platform-dependencies.yaml found"
+        checks_passed=$((checks_passed + 1))
+    else
+        log_fail "app-platform-dependencies.yaml not found in repo root"
+        checks_failed=$((checks_failed + 1))
+    fi
+
+    if [[ "$checks_failed" -gt 0 ]]; then
+        FAILURES=$((FAILURES + checks_failed))
+    fi
+
+    log_info "Group 1: $checks_passed passed, $checks_failed failed"
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+check_feature_specs() {
+    log_section "Group 2: Feature Spec Section Validation"
+
+    local required_sections=("## Overview" "## Acceptance Criteria" "## Platform Contract Dependencies")
+    local specs_found=0
+    local specs_failed=0
+    local specs_passed=0
+
+    # Discover feature specs under features/*/
+    local feature_spec
+    while IFS= read -r feature_spec; do
+        specs_found=$((specs_found + 1))
+        local rel="${feature_spec#$APP_ROOT/}"
+        local file_failures=0
+
+        for section in "${required_sections[@]}"; do
+            if ! grep -q "^${section}" "$feature_spec" 2>/dev/null; then
+                log_fail "$rel: missing required section '$section'"
+                file_failures=$((file_failures + 1))
+            fi
+        done
+
+        if [[ "$file_failures" -eq 0 ]]; then
+            log_pass "$rel: all required sections present"
+            specs_passed=$((specs_passed + 1))
+        else
+            specs_failed=$((specs_failed + 1))
+            FAILURES=$((FAILURES + file_failures))
+        fi
+    done < <(find "$APP_ROOT/features" -type f -name "*.md" 2>/dev/null | sort)
+
+    if [[ "$specs_found" -eq 0 ]]; then
+        log_info "No feature specs found under features/ — skipping section validation"
+        return 0
+    fi
+
+    log_info "Group 2: $specs_passed/$specs_found feature specs passed, $specs_failed failed"
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+main() {
+    log_section "App Documentation Validation"
+    log_info "App root: $APP_ROOT"
+
+    check_required_files
+    check_feature_specs
+
+    log_section "Summary"
+
+    if [[ "$FAILURES" -eq 0 ]]; then
+        log_pass "All app documentation checks passed."
+        exit 0
+    else
+        log_fail "$FAILURES check(s) failed."
+        exit 1
+    fi
+}
+
+main "$@"

package/scripts/validate-integration-docs.sh

@@ -0,0 +1,505 @@
+#!/bin/bash
+#
+# validate-integration-docs.sh - Validate integration repo documentation structure
+#
+# Usage: ./validate-integration-docs.sh [--repo-root <path>]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+REPO_ROOT="$ROOT_DIR"
+EXPECTED_REPO_KIND="integration-product"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_fail() { echo -e "${RED}[FAIL]${NC} $1"; }
+log_pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+log_section() {
+    echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
+    echo -e "${BLUE}  $1${NC}"
+    echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}\n"
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo-root)
+            REPO_ROOT="${2:-}"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: $(basename "$0") [--repo-root <path>]"
+            exit 0
+            ;;
+        *)
+            log_fail "Unknown argument: $1"
+            exit 1
+            ;;
+    esac
+done
+
+if [[ ! -d "$REPO_ROOT" ]]; then
+    log_fail "Repo root not found: $REPO_ROOT"
+    exit 1
+fi
+
+command -v yq >/dev/null 2>&1 || {
+    log_fail "yq is required. Install it before running $(basename "$0")."
+    exit 1
+}
+
+FAILURES=0
+
+check_repo_kind() {
+    log_section "Group 1: Repo Kind"
+
+    local marker="$REPO_ROOT/.sdd-repo-kind"
+    if [[ ! -f "$marker" ]]; then
+        log_fail ".sdd-repo-kind not found"
+        FAILURES=$((FAILURES + 1))
+        return
+    fi
+
+    local value
+    value="$(tr -d '[:space:]' < "$marker")"
+    if [[ "$value" != "$EXPECTED_REPO_KIND" ]]; then
+        log_fail "Expected repo kind '$EXPECTED_REPO_KIND', found '$value'"
+        FAILURES=$((FAILURES + 1))
+    else
+        log_pass "Repo kind marker present: $value"
+    fi
+}
+
+check_required_files() {
+    log_section "Group 2: Required Files"
+
+    local files=(
+        "integration-manifest.yaml"
+        "docs/service-architecture.md"
+        "docs/method/methods/templates/feature-grounding-integration-template.md"
+        "docs/method/methods/workflows/integration-delivery-workflow-guide.md"
+        "docs/method/methods/templates/integration-service-architecture-template.md"
+    )
+    local rel
+
+    for rel in "${files[@]}"; do
+        if [[ -f "$REPO_ROOT/$rel" ]]; then
+            log_pass "$rel found"
+        else
+            log_fail "$rel missing"
+            FAILURES=$((FAILURES + 1))
+        fi
+    done
+}
+
+check_manifest() {
+    log_section "Group 3: Manifest Structure"
+
+    local manifest="$REPO_ROOT/integration-manifest.yaml"
+    if [[ ! -f "$manifest" ]]; then
+        log_fail "integration-manifest.yaml missing; cannot validate structure"
+        FAILURES=$((FAILURES + 1))
+        return
+    fi
+
+    local required_scalars=("integrationId" "providerName" "version" "profileType" "sdkVersion" "publishedBy" "bindingModel")
+    local field value
+    for field in "${required_scalars[@]}"; do
+        value="$(yq e ".${field} // \"\"" "$manifest")"
+        if [[ -z "$value" || "$value" == "null" || "$value" == "TBD" ]]; then
+            log_fail "integration-manifest.yaml: '$field' missing or placeholder"
+            FAILURES=$((FAILURES + 1))
+        else
+            log_pass "integration-manifest.yaml: '$field' set"
+        fi
+    done
+
+    local inbound outbound asset_count profile
+    inbound="$(yq e '.capabilityFlags.inbound' "$manifest")"
+    outbound="$(yq e '.capabilityFlags.outbound' "$manifest")"
+    profile="$(yq e '.profileType // ""' "$manifest")"
+    asset_count="$(yq e '.supportedAssetTypes | length' "$manifest" 2>/dev/null || echo 0)"
+
+    if [[ "$inbound" != "true" && "$inbound" != "false" ]]; then
+        log_fail "integration-manifest.yaml: capabilityFlags.inbound must be true or false"
+        FAILURES=$((FAILURES + 1))
+    else
+        log_pass "integration-manifest.yaml: capabilityFlags.inbound set"
+    fi
+
+    if [[ "$outbound" != "true" && "$outbound" != "false" ]]; then
+        log_fail "integration-manifest.yaml: capabilityFlags.outbound must be true or false"
+        FAILURES=$((FAILURES + 1))
+    else
+        log_pass "integration-manifest.yaml: capabilityFlags.outbound set"
+    fi
+
+    if [[ "$asset_count" -lt 1 ]]; then
+        log_fail "integration-manifest.yaml: supportedAssetTypes must contain at least one value"
+        FAILURES=$((FAILURES + 1))
+    else
+        log_pass "integration-manifest.yaml: supportedAssetTypes populated"
+    fi
+
+    case "$profile" in
+        workflow|financial-services|data-hub|data-feed)
+            if [[ "$outbound" != "false" ]]; then
+                log_fail "integration-manifest.yaml: profileType '$profile' should default outbound capability to false"
+                FAILURES=$((FAILURES + 1))
+            else
+                log_pass "integration-manifest.yaml: inbound-only profile directionality is coherent"
+            fi
+            ;;
+        *)
+            ;;
+    esac
+
+    # Interaction patterns (ADR 0171) — optional fields, validated only when present.
+    # Existing manifests predate the field; absence is not a failure. Directionality
+    # mismatch (pattern present but the matching capability flag is false) is a warning.
+    local ingestion invocation
+    ingestion="$(yq e '.ingestionPattern // ""' "$manifest")"
+    invocation="$(yq e '.invocationPattern // ""' "$manifest")"
+
+    if [[ -n "$ingestion" && "$ingestion" != "null" ]]; then
+        case "$ingestion" in
+            event-stream-consume|webhook|socket-listen|poll)
+                log_pass "integration-manifest.yaml: ingestionPattern '$ingestion' valid"
+                # if/fi for the same reason as the invocationPattern warn below:
+                # safe only because more code follows, which is not a property
+                # worth relying on.
+                if [[ "$inbound" != "true" ]]; then
+                    log_warn "integration-manifest.yaml: ingestionPattern set but capabilityFlags.inbound is not true"
+                fi
+                ;;
+            *)
+                log_fail "integration-manifest.yaml: ingestionPattern '$ingestion' not in {event-stream-consume, webhook, socket-listen, poll} — if this provider is none of the four, pick the pattern matching the MECHANICS and move the distinguishing semantics to patternQualifier (free-text); minting a pattern value is a method change"
+                FAILURES=$((FAILURES + 1))
+                ;;
+        esac
+    fi
+
+    if [[ -n "$invocation" && "$invocation" != "null" ]]; then
+        case "$invocation" in
+            request-response|async-request|publish)
+                log_pass "integration-manifest.yaml: invocationPattern '$invocation' valid"
+                # Explicit if/fi, NOT `[[ ... ]] && log_warn`. As the last
+                # statement in this function, a false test made the function
+                # return 1, and under `set -e` that aborted the whole run before
+                # Group 4 — so the check fired on the CORRECT case (a manifest
+                # that declares invocationPattern and properly sets
+                # outbound: true), and the better-formed the manifest, the more
+                # certainly its grounding evidence went unchecked.
+                if [[ "$outbound" != "true" ]]; then
+                    log_warn "integration-manifest.yaml: invocationPattern set but capabilityFlags.outbound is not true"
+                fi
+                ;;
+            *)
+                log_fail "integration-manifest.yaml: invocationPattern '$invocation' not in {request-response, async-request, publish}"
+                FAILURES=$((FAILURES + 1))
+                ;;
+        esac
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Unedited-scaffold-residue lint (WARN-only).
+#
+# WHAT THIS MEASURES, and what it deliberately does not: residue measures
+# **authoring completeness** — how much of the scaffold is still untouched. It is
+# NOT a signal for whether an SDD models a real provider. Those are independent
+# properties, measured to be so: on one estate 5 SDDs are demonstrations and 11
+# carry residue, because six REAL integrations are simply not authored yet. A
+# residue list is therefore an authoring WORK QUEUE, never a census of
+# demonstrations. Do not re-couple it to the `exemplar` trait.
+#
+# THE TEMPLATE IS THE ORACLE. Residue is defined as template text that survived
+# into the authored document, so the shipped template is read at runtime and the
+# comparison is exact. This matters for two reasons:
+#   1. It is self-maintaining. An earlier attempt at this check hardcoded a list
+#      of placeholder strings; the list silently went stale, so tokens from other
+#      templates read as real content.
+#   2. It separates residue from a brace that is legitimately authored. A JSON
+#      example containing `{` is not residue; the exact string `{provider field}`
+#      is, because the template is where it comes from.
+#
+# WHAT IS LEGITIMATELY RETAINED — state this half or the rule flags correct
+# authoring. Template text kept as STRUCTURE is right and must never be reported:
+#   - section headings (`^#`) — a cohort of SDDs sharing one standard deliberately
+#     keeps the method's section shape while filling it with real content, and that
+#     is exactly correct authoring;
+#   - table header and separator rows (`^|`);
+#   - short shared lines — a bare path, a field label — dropped by a length floor.
+# Residue is template text left IN THE SLOTS, never template text AS STRUCTURE.
+#
+# THREE SHAPES OF RESIDUE, and only two are detectable:
+#   1. Unfilled placeholder tokens      — detected (exact token match).
+#   2. Leftover instruction prose       — detected (exact line match).
+#   3. Unmodified example table rows    — NOT ATTEMPTED, on evidence rather than
+#      difficulty: every placeholder-free table row in the shipped templates is a
+#      table HEADER row, which an authored document is supposed to retain. Rows
+#      that do carry placeholders are already caught by shape 1. So verbatim-row
+#      matching would flag precisely the lines that should survive and add no
+#      signal that shape 1 misses.
+# ---------------------------------------------------------------------------
+
+# Templates that may reach an integration SDD (forward via integration-baseline,
+# reverse via reverse-extension-baseline). Whichever are present are used.
+GROUNDING_TEMPLATES=(
+    "docs/method/methods/templates/feature-grounding-integration-template.md"
+    "docs/method/methods/reverse/templates/integration-product/docs/design/integration/feature-grounding.md"
+)
+
+# Cap on reported items per class — an untouched scaffold would otherwise bury
+# the rest of the run. The count is always reported in full, per no-silent-caps.
+RESIDUE_REPORT_CAP=5
+
+check_grounding_residue() {
+    local grounding="$1"
+    local rel="docs/design/integration/feature-grounding.md"
+
+    local -a templates=()
+    local t
+    for t in "${GROUNDING_TEMPLATES[@]}"; do
+        [[ -f "$REPO_ROOT/$t" ]] && templates+=("$REPO_ROOT/$t")
+    done
+
+    # Never pass silently for want of an oracle: "no residue found" and "could
+    # not look" must not be the same output.
+    if [[ ${#templates[@]} -eq 0 ]]; then
+        log_warn "$rel: cannot check scaffold residue — no grounding template present in this repo (expected one of: ${GROUNDING_TEMPLATES[*]})"
+        return
+    fi
+
+    # --- Shape 1: unfilled placeholder tokens -------------------------------
+    # `|| true` on every match pipeline below: grep exits 1 on no-match, and
+    # under `set -euo pipefail` that aborts the run at the assignment. "Found
+    # nothing" is the expected result for a well-authored document, so it must not
+    # be fatal — this is the same trap that was silently killing Group 4.
+    local tokens
+    tokens="$(grep -ohE '\{[^}]{1,80}\}' "${templates[@]}" 2>/dev/null | sort -u || true)"
+
+    local -a hits=()
+    local token
+    while IFS= read -r token; do
+        [[ -z "$token" ]] && continue
+        local lines
+        lines="$(grep -Fn -- "$token" "$grounding" 2>/dev/null | cut -d: -f1 | paste -sd, - || true)"
+        [[ -n "$lines" ]] && hits+=("line ${lines}: ${token}")
+    done <<< "$tokens"
+
+    if [[ ${#hits[@]} -gt 0 ]]; then
+        log_warn "$rel: ${#hits[@]} unfilled placeholder token(s) from the shipped template — authoring incomplete (not a demonstration marker)"
+        local i
+        for ((i = 0; i < ${#hits[@]} && i < RESIDUE_REPORT_CAP; i++)); do
+            echo "    - ${hits[$i]}"
+        done
+        if [[ ${#hits[@]} -gt $RESIDUE_REPORT_CAP ]]; then
+            echo "    - … and $(( ${#hits[@]} - RESIDUE_REPORT_CAP )) more"
+        fi
+    fi
+
+    # --- Shape 2: leftover template instruction prose -----------------------
+    # Prose only: headings and table rows are structure an authored document
+    # legitimately keeps. The length floor drops short shared lines (a bare path
+    # or a field label) that carry no instruction and would false-positive.
+    local -a prose_hits=()
+    local line
+    while IFS= read -r line; do
+        [[ ${#line} -lt 60 ]] && continue
+        if grep -Fxq -- "$line" "$grounding" 2>/dev/null; then
+            prose_hits+=("$line")
+        fi
+    done < <(grep -hvE '^#|^\||^$|^[[:space:]]*$' "${templates[@]}" 2>/dev/null | sort -u || true)
+
+    if [[ ${#prose_hits[@]} -gt 0 ]]; then
+        log_warn "$rel: ${#prose_hits[@]} line(s) of template instruction prose retained verbatim"
+        local j
+        for ((j = 0; j < ${#prose_hits[@]} && j < RESIDUE_REPORT_CAP; j++)); do
+            local shown="${prose_hits[$j]}"
+            [[ ${#shown} -gt 90 ]] && shown="${shown:0:90}…"
+            echo "    - ${shown}"
+        done
+        if [[ ${#prose_hits[@]} -gt $RESIDUE_REPORT_CAP ]]; then
+            echo "    - … and $(( ${#prose_hits[@]} - RESIDUE_REPORT_CAP )) more"
+        fi
+    fi
+
+    if [[ ${#hits[@]} -eq 0 && ${#prose_hits[@]} -eq 0 ]]; then
+        log_pass "$rel: no unedited scaffold residue detected"
+    fi
+}
+
+check_grounding_doc() {
+    log_section "Group 4: Grounding Evidence"
+
+    local grounding="$REPO_ROOT/docs/design/integration/feature-grounding.md"
+    if [[ ! -f "$grounding" ]]; then
+        log_warn "docs/design/integration/feature-grounding.md not found — create before lock-in"
+        return
+    fi
+
+    local manifest="$REPO_ROOT/integration-manifest.yaml"
+    local outbound
+    outbound="$(yq e '.capabilityFlags.outbound' "$manifest" 2>/dev/null || echo "")"
+
+    local sections=("## Overview" "## Platform Contract Boundary" "## Provider-to-Canonical Field Mapping" "## Identity Resolution and Routing" "## Security and Secrets")
+    local section
+    local missing=0
+    for section in "${sections[@]}"; do
+        if ! grep -q "^${section}" "$grounding"; then
+            log_fail "docs/design/integration/feature-grounding.md missing section '$section'"
+            FAILURES=$((FAILURES + 1))
+            missing=1
+        fi
+    done
+
+    if [[ "$missing" -eq 0 ]]; then
+        log_pass "docs/design/integration/feature-grounding.md contains required sections"
+    fi
+
+    if [[ "$outbound" == "true" ]]; then
+        if grep -q "^## Command Mapping" "$grounding"; then
+            log_pass "docs/design/integration/feature-grounding.md includes command mapping for bidirectional integration"
+        else
+            log_fail "docs/design/integration/feature-grounding.md missing section '## Command Mapping' for bidirectional integration"
+            FAILURES=$((FAILURES + 1))
+        fi
+    fi
+
+    # Substance, not just presence. The checks above establish that the required
+    # sections EXIST; this one asks whether they were filled in. WARN-only and
+    # never incrementing FAILURES: an estate must not turn red for being honest
+    # about its authoring state, and an exploration-stage integration is a
+    # legitimate thing to have.
+    check_grounding_residue "$grounding"
+}
+
+main() {
+    log_section "Integration Documentation Validation"
+    log_info "Repo root: $REPO_ROOT"
+
+    check_repo_kind
+    check_required_files
+    check_manifest
+    check_grounding_doc
+    check_components_declaration
+
+    log_section "Summary"
+
+    if [[ "$FAILURES" -eq 0 ]]; then
+        log_pass "All integration documentation checks passed."
+        exit 0
+    fi
+
+    log_fail "$FAILURES check(s) failed."
+    exit 1
+}
+
+# Components declaration (M-ADR 0212-era coordination: the agreed four-state design).
+#
+# Asks only for the INVENTORY, never for per-component patterns: `id` is the sole
+# required field of a components[] entry, so an inventory-only block is complete and
+# conformant. Measured authoring cost was under a minute per SDD for the inventory and
+# up to twenty-five for the patterns, and a warn cannot make the second cheaper — a
+# warn nobody can afford to clear becomes a warn everybody filters.
+#
+# Counts components from each repo's OWN `profile` in reverse-metadata.yaml, never from
+# catalogue row counts: catalogue rows include support repos, so row counting over-counts
+# every SDD that mirrors a shared library.
+#
+# Zero is three different facts and they are reported separately. Collapsing them is what
+# would bury the only one that is a defect.
+check_components_declaration() {
+    local manifest="$REPO_ROOT/integration-manifest.yaml"
+    [[ -f "$manifest" ]] || return 0
+
+    local repos_dir="$REPO_ROOT/repos"
+    local components=0 support=0 unreadable=0
+
+    if [[ -d "$repos_dir" ]]; then
+        local d meta profile
+        for d in "$repos_dir"/*/; do
+            meta="$d/reverse-metadata.yaml"
+            [[ -f "$meta" ]] || continue
+            # A file that EXISTS and yields no profile is not the same fact as one that
+            # is absent, and the fallback treats them identically. Say so — this is the
+            # defect that hid a mis-typed repo through an otherwise correct rebuild.
+            if ! profile="$(yq e '.profile // ""' "$meta" 2>/dev/null)" || [[ -z "$profile" || "$profile" == "null" ]]; then
+                unreadable=$((unreadable + 1))
+                log_warn "repos/$(basename "$d")/reverse-metadata.yaml: no readable \`profile\` — this repo is not counted, so the component total below may be low"
+                continue
+            fi
+            case "$profile" in
+                integration-product) components=$((components + 1)) ;;
+                support-repo) support=$((support + 1)) ;;
+            esac
+        done
+    fi
+
+    local catalogue="$REPO_ROOT/catalogues/repositories.csv"
+    local catalogued=-1
+    if [[ -f "$catalogue" ]]; then
+        catalogued="$(awk -F, 'NR>1 && $5=="integration-product"' "$catalogue" 2>/dev/null | wc -l)"
+    fi
+
+    # Fall back to the catalogue only when there is no per-repo evidence at all.
+    if [[ "$components" -eq 0 && "$support" -eq 0 && "$unreadable" -eq 0 && "$catalogued" -gt 0 ]]; then
+        components="$catalogued"
+    fi
+
+    local declared="no"
+    yq e 'has("components")' "$manifest" 2>/dev/null | grep -q true && declared="yes"
+
+    # (c) The two sources disagree in the one direction that is a defect: components
+    # exist on disk and the catalogue holds none. Reported whatever the count bucket,
+    # and deliberately louder than the declaration warn — it is the only state here
+    # that means something is broken rather than merely undeclared.
+    if [[ "$components" -gt 0 && "$catalogued" -eq 0 ]]; then
+        log_warn "catalogues/repositories.csv holds NO integration-product rows while repos/ holds $components — the catalogue was never built for this SDD. Declaring components will not fix it; rebuild the catalogue."
+    fi
+
+    if [[ "$components" -gt 1 ]]; then
+        if [[ "$declared" == "yes" ]]; then
+            local entries
+            entries="$(yq e '.components | length' "$manifest" 2>/dev/null || echo 0)"
+            [[ "$entries" =~ ^[0-9]+$ ]] || entries=0
+            # Asymmetric on purpose. Declaring MORE than repos/ holds is legitimate —
+            # components that are generated or held elsewhere are real and uncloned
+            # (the same case as the support-repo-only SDDs below). Declaring FEWER means
+            # mirrored components the inventory does not mention, which is a declaration
+            # that was true when written and quietly is not now.
+            if [[ "$entries" -lt "$components" ]]; then
+                log_warn "integration-manifest.yaml: \`components:\` declares $entries entr(ies) but repos/ holds $components component repos — the inventory omits $((components - entries)). A declared inventory that stops being true is worse than an absent one."
+            else
+                log_pass "integration-manifest.yaml: components declared ($entries entr(ies), $components component repos in repos/)"
+            fi
+        else
+            log_warn "integration-manifest.yaml: $components component repos in repos/, no \`components:\` block — the inventory is undeclared. Only \`id\` is required per entry; patterns are optional."
+        fi
+        return 0
+    fi
+
+    if [[ "$components" -eq 1 ]]; then
+        log_pass "integration-manifest.yaml: single-component integration — the manifest's own patterns are the whole truth"
+        return 0
+    fi
+
+    # (a) Entries exist, none of them a component: the components live elsewhere.
+    if [[ "$support" -gt 0 ]]; then
+        log_info "0 component repos; $support support repo(s) — components are not cloned into this SDD (generated, or held elsewhere). Nothing owed."
+        return 0
+    fi
+
+    # (b) Nothing mirrored at all: a spec-first SDD being silent about components is
+    # a spec-first SDD behaving correctly.
+    log_info "0 component repos and nothing mirrored — no inventory to declare yet."
+}
+
+main "$@"