@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/scripts/validate-app-dependencies.sh

@@ -0,0 +1,664 @@
+#!/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"; }
+# R1: an empty population is "measured nothing", not a pass — the [N/A] tag
+# must start the line (no leading colour escape) so callers can detect it.
+log_na() { echo -e "[N/A] $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
+
+# ──────────────────────────────────────────────────────────────────────────────
+# R1: with zero declared dependencies the run measures nothing, so the
+# prerequisite checks report as [INFO] rather than [PASS] — a [PASS] line would
+# make the empty run read as a pass. Counted up front, quietly; the real count
+# (with parse-failure reporting) happens in main.
+PRE_DEP_COUNT=0
+log_prereq() {
+    if [[ "$PRE_DEP_COUNT" -gt 0 ]]; then log_pass "$1"; else log_info "$1"; fi
+}
+
+check_prerequisites() {
+    log_section "Prerequisites"
+
+    if command -v yq &>/dev/null; then
+        local _src
+        for _src in "${DEP_SOURCES[@]+"${DEP_SOURCES[@]}"}"; do
+            PRE_DEP_COUNT=$((PRE_DEP_COUNT + $(quiet_dep_count "$_src")))
+        done
+    fi
+
+    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_prereq "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_prereq "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_prereq "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_prereq "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."
+        log_na "App dependencies: 0 platform_dependencies entries found — nothing to check"
+        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 "$@"