@sdd-method/sdd-cli 1.0.1 → 1.1.0

package/scripts/validate-app-dependencies.sh

@@ -3,17 +3,52 @@
 # validate-app-dependencies.sh - Validate app platform dependency declarations
 #
 # Usage:
-#   ./validate-app-dependencies.sh --app-root <path> --platform-root <path>
+#   ./validate-app-dependencies.sh --app-root <path> [--platform-root <path>]
 #
-# Checks (for each entry in app-platform-dependencies.yaml):
-#   1. required_stability is a valid value (provisional | locked)
-#   2. 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)
-#   3. contract_path exists (as a file) when required_stability is "locked"
+# --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
 
@@ -41,12 +76,15 @@ PLATFORM_ROOT=""
 
 usage() {
     cat <<USAGE
-Usage: $(basename "$0") --app-root <path> --platform-root <path>
+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  Path to the platform repository root (service_id checks use
-                   catalogues/services.csv when present, else docs/platform/service-architecture.md)
+  --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
 }
 
@@ -78,42 +116,124 @@ if [[ -z "$APP_ROOT" ]]; then
     exit 1
 fi
 
-if [[ -z "$PLATFORM_ROOT" ]]; then
-    log_fail "--platform-root is required"
-    usage
-    exit 1
-fi
-
 if [[ ! -d "$APP_ROOT" ]]; then
     log_fail "App root not found: $APP_ROOT"
     exit 1
 fi
 
-if [[ ! -d "$PLATFORM_ROOT" ]]; then
+# --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"
 
-VALID_STABILITY_VALUES=("provisional" "locked")
+# 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 [[ ! -f "$APP_DEPS_FILE" ]]; then
-        log_fail "app-platform-dependencies.yaml not found: $APP_DEPS_FILE"
+    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
-    log_pass "app-platform-dependencies.yaml found"
+    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"
@@ -121,6 +241,13 @@ check_prerequisites() {
     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
@@ -139,6 +266,21 @@ check_prerequisites() {
     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"
@@ -151,24 +293,70 @@ service_id_in_catalogue() {
 }
 
 # ──────────────────────────────────────────────────────────────────────────────
+# 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 index="$1"
+    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 // \"\"" "$APP_DEPS_FILE")"
-    service_id="$(yq e ".platform_dependencies[$index].service_id // \"\"" "$APP_DEPS_FILE")"
-    contract_type="$(yq e ".platform_dependencies[$index].contract_type // \"\"" "$APP_DEPS_FILE")"
-    required_stability="$(yq e ".platform_dependencies[$index].required_stability // \"\"" "$APP_DEPS_FILE")"
-    contract_path="$(yq e ".platform_dependencies[$index].contract_path // \"\"" "$APP_DEPS_FILE")"
+    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
 
-    # Check 1: required_stability is a valid value
+    # 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
@@ -177,18 +365,86 @@ validate_dependency() {
         fi
     done
 
-    if [[ "$stability_valid" -eq 0 ]]; then
-        log_fail "$dep_label: invalid required_stability '$required_stability' (allowed: ${VALID_STABILITY_VALUES[*]})"
-        ((dep_errors++))
+    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
 
-    # Check 2: service_id resolves against the platform source of truth.
-    # The services catalogue (when present) is canonical — it is the same source
-    # the aggregator FK-validates dependency edges against. The prose
-    # service-architecture.md is the fallback for pre-catalogue platforms.
     if [[ -z "$service_id" || "$service_id" == "null" ]]; then
-        log_fail "$dep_label: service_id is empty or missing"
-        ((dep_errors++))
+        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)"
@@ -204,11 +460,26 @@ validate_dependency() {
         fi
     fi
 
-    # Check 3: contract_path exists when required_stability is locked
+    # 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
@@ -216,11 +487,14 @@ validate_dependency() {
                 ((dep_errors++))
             fi
         fi
-    elif [[ "$required_stability" == "provisional" ]]; then
-        if [[ -n "$contract_path" && "$contract_path" != "null" ]]; then
+    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 (provisional — acceptable)"
+                log_warn "$dep_label: contract_path '$contract_path' declared but not yet present ($required_stability — acceptable)"
                 ((WARNINGS++))
             fi
         fi
@@ -241,31 +515,46 @@ print_status_table() {
     log_section "Dependency Status Table"
 
     local app_id
-    app_id="$(yq e ".app_id // \"unknown\"" "$APP_DEPS_FILE")"
+    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 count
-    count="$(yq e ".platform_dependencies | length" "$APP_DEPS_FILE")"
+    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)\"" "$APP_DEPS_FILE")"
-        required_stability="$(yq e ".platform_dependencies[$i].required_stability // \"(missing)\"" "$APP_DEPS_FILE")"
-        contract_type="$(yq e ".platform_dependencies[$i].contract_type // \"(missing)\"" "$APP_DEPS_FILE")"
-        contract_path="$(yq e ".platform_dependencies[$i].contract_path // \"\"" "$APP_DEPS_FILE")"
+        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 [[ -n "$contract_path" && "$contract_path" != "null" && -f "$PLATFORM_ROOT/$contract_path" ]]; 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
@@ -273,6 +562,7 @@ print_status_table() {
         printf "  %-30s %-15s %-12s " "$service_id" "$required_stability" "$contract_type"
         echo -e "$dep_status"
     done
+    done
     echo ""
 }
 
@@ -286,20 +576,33 @@ main() {
 
     log_section "Validating Dependencies"
 
-    local dep_count
-    dep_count="$(yq e ".platform_dependencies | length" "$APP_DEPS_FILE")"
-    TOTAL_DEPS="$dep_count"
+    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 [[ "$dep_count" -eq 0 ]]; then
-        log_warn "No platform_dependencies entries found in app-platform-dependencies.yaml"
+    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
 
-    for ((i = 0; i < dep_count; i++)); do
-        validate_dependency "$i" || true
-    done
-
     print_status_table
 
     log_section "Summary"
@@ -308,11 +611,28 @@ main() {
     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