ontoref/reflection/modules/validate.nu

#!/usr/bin/env nu
# reflection/modules/validate.nu — ADR constraint validation + justfile convention checker.
#
# Interprets the typed constraint_check_type ADT exported by adrs/adr-schema.ncl.
# Each constraint.check record has a `tag` discriminant; this module dispatches
# execution per variant and returns a structured result.
#
# Commands:
#   validate check-constraint <c> — run a single constraint record
#   validate check-adr <id>       — run all constraints for one ADR
#   validate check-all            — run all constraints across all accepted ADRs
#   validate justfile             — validate project justfile against convention schema
#   validate modes [--check]      — ADR-018 level hierarchy + strategy compliance
#   mode resolve <id>             — show which hierarchy level handles a mode
#
# Error handling: do { ... } | complete — never panics, always returns a result.

use env.nu *
use store.nu [daemon-export-safe]

# ── Internal helpers ────────────────────────────────────────────────────────

def adr-root []: nothing -> string {
  $env.ONTOREF_PROJECT_ROOT? | default $env.ONTOREF_ROOT
}

def adr-files []: nothing -> list<string> {
  glob ([(adr-root), "adrs", "adr-*.ncl"] | path join)
}

# Resolve a check path (may be file or directory) relative to project root.
def resolve-path [rel: string]: nothing -> string {
  [(adr-root), $rel] | path join
}

# Run a 'Grep check: ripgrep pattern across paths; empty/non-empty assertion.
def run-grep [check: record]: nothing -> record {
  let paths = ($check.paths | each { |p| resolve-path $p })
  let valid_paths = ($paths | where { |p| $p | path exists })

  if ($valid_paths | is-empty) {
    return {
      passed: false,
      detail: $"No paths exist: ($check.paths | str join ', ')"
    }
  }

  let result = do {
    ^rg --no-heading --count-matches $check.pattern ...$valid_paths
  } | complete

  let has_matches = ($result.exit_code == 0)

  if $check.must_be_empty {
    {
      passed: (not $has_matches),
      detail: (if $has_matches { $"Pattern found, violation: ($result.stdout | str trim)" } else { "Pattern absent — ok" })
    }
  } else {
    {
      passed: $has_matches,
      detail: (if $has_matches { "Pattern present — ok" } else { "Pattern absent — required match missing" })
    }
  }
}

# Run a 'Cargo check: parse Cargo.toml, verify forbidden_deps absent from [dependencies].
# Resolves Cargo.toml in two steps:
#   1. workspace layout: <adr-root>/crates/<check.crate>/Cargo.toml (preferred for multi-crate repos)
#   2. single-crate fallback: <adr-root>/Cargo.toml when its [package].name matches check.crate,
#                             OR unconditionally when check.crate equals the basename of adr-root
# This lets the same constraint shape apply to workspace projects (stratumiops, provisioning)
# and single-crate projects (lian-build, ontoref-* satellites).
def run-cargo [check: record]: nothing -> record {
  let workspace_path = ([(adr-root), "crates", $check.crate, "Cargo.toml"] | path join)
  let root_path     = ([(adr-root), "Cargo.toml"] | path join)
  let cargo_path = if ($workspace_path | path exists) {
    $workspace_path
  } else if ($root_path | path exists) {
    let root_cargo = (open $root_path)
    let pkg_name = ($root_cargo.package?.name? | default "")
    let project_basename = ((adr-root) | path basename)
    if $pkg_name == $check.crate or $project_basename == $check.crate {
      $root_path
    } else {
      return { passed: false, detail: $"Cargo.toml at ($root_path) declares package.name='($pkg_name)', not '($check.crate)' — workspace path ($workspace_path) also missing" }
    }
  } else {
    return { passed: false, detail: $"Cargo.toml not found at ($workspace_path) or ($root_path)" }
  }

  let cargo = (open $cargo_path)
  let all_dep_sections = [
    ($cargo.dependencies? | default {}),
    ($cargo."dev-dependencies"? | default {}),
    ($cargo."build-dependencies"? | default {}),
  ]
  let all_dep_keys = ($all_dep_sections | each { |d| $d | columns } | flatten)

  let found = ($check.forbidden_deps | where { |dep| $dep in $all_dep_keys })
  {
    passed: ($found | is-empty),
    detail: (if ($found | is-empty) { $"No forbidden deps found in ($cargo_path)" } else { $"Forbidden deps present: ($found | str join ', ')" })
  }
}

# Run a 'NuCmd check: execute cmd via nu -c, assert exit code.
# The cmd executes with cwd = (adr-root) so relative paths in the constraint
# (e.g. 'manifest.ncl', 'src/main.rs', 'catalog/domains') resolve against the
# project being validated, regardless of where validate was invoked from.
# The cd is composed into the cmd string rather than mutating parent shell
# state — keeps run-nucmd reentrant and side-effect-free.
def run-nucmd [check: record]: nothing -> record {
  let cmd_with_cwd = $"cd '(adr-root)'; ($check.cmd)"
  let result = do { nu -c $cmd_with_cwd } | complete
  let expected = ($check.expect_exit? | default 0)
  {
    passed: ($result.exit_code == $expected),
    detail: (if ($result.exit_code == $expected) {
      $"Command exited as expected from cwd (adr-root)"
    } else {
      $"Exit ($result.exit_code) ≠ expected ($expected): ($result.stderr | str trim)"
    })
  }
}

# Run an 'ApiCall check: GET endpoint, navigate json_path, compare to expected.
def run-apicall [check: record]: nothing -> record {
  let result = do { ^curl -sf $check.endpoint } | complete
  if $result.exit_code != 0 {
    return { passed: false, detail: $"curl failed (exit ($result.exit_code)): ($result.stderr | str trim)" }
  }
  let value = do { $result.stdout | from json | get $check.json_path } | complete
  if $value.exit_code != 0 {
    return { passed: false, detail: $"json_path '($check.json_path)' not found in response" }
  }
  let actual = $value.stdout | str trim
  let expected = ($check.expected | into string)
  {
    passed: ($actual == $expected),
    detail: (if ($actual == $expected) { "Value matches" } else { $"Expected '($expected)', got '($actual)'" })
  }
}

# Run a 'FileExists check: assert presence or absence of a path.
def run-fileexists [check: record]: nothing -> record {
  let p = (resolve-path $check.path)
  let exists = ($p | path exists)
  let want = ($check.present? | default true)
  {
    passed: ($exists == $want),
    detail: (if ($exists == $want) {
      (if $want { $"File exists: ($p)" } else { $"File absent: ($p)" })
    } else {
      (if $want { $"File missing: ($p)" } else { $"File unexpectedly present: ($p)" })
    })
  }
}

# Dispatch a single constraint.check record to the appropriate runner.
def dispatch-check [check: record]: nothing -> record {
  match $check.tag {
    "Grep"       => (run-grep $check),
    "Cargo"      => (run-cargo $check),
    "NuCmd"      => (run-nucmd $check),
    "ApiCall"    => (run-apicall $check),
    "FileExists" => (run-fileexists $check),
    _            => { passed: false, detail: $"Unknown check tag: ($check.tag)" }
  }
}

# ── Public commands ──────────────────────────────────────────────────────────

# Run a single constraint record.
# Returns { constraint_id, severity, passed, detail }.
export def "validate check-constraint" [
  constraint: record,  # Constraint record from an ADR export
]: nothing -> record {
  if ($constraint.check? | is-empty) {
    return {
      constraint_id: ($constraint.id? | default "unknown"),
      severity: ($constraint.severity? | default "Hard"),
      passed: false,
      detail: "No typed 'check' field — constraint uses deprecated check_hint only"
    }
  }

  let result = dispatch-check $constraint.check
  {
    constraint_id: $constraint.id,
    severity:      $constraint.severity,
    passed:        $result.passed,
    detail:        $result.detail,
  }
}

# Run all constraints for a single ADR by id ("001", "adr-001", or "adr-001-slug").
# Returns a list of { constraint_id, severity, passed, detail }.
export def "validate check-adr" [
  id: string,    # ADR id: "001", "adr-001", or full stem
  --fmt: string = "table",  # Output: table | json | yaml
]: nothing -> any {
  let canonical = if ($id | str starts-with "adr-") { $id } else { $"adr-($id)" }
  let files = (glob ([(adr-root), "adrs", $"($canonical)-*.ncl"] | path join))
  if ($files | is-empty) {
    error make { msg: $"ADR '($id)' not found in adrs/" }
  }

  let adr = (daemon-export-safe ($files | first))
  if $adr == null {
    error make { msg: $"ADR '($id)' failed to export" }
  }

  let results = ($adr.constraints | each { |c|
    if ($c.check? | is-empty) {
      {
        constraint_id: $c.id,
        severity:      $c.severity,
        passed:        false,
        detail:        "check field missing — uses deprecated check_hint"
      }
    } else {
      validate check-constraint $c
    }
  })

  match $fmt {
    "json"  => { $results | to json },
    "yaml"  => { $results | to yaml },
    _       => { $results | table --expand },
  }
}

# Run all Hard constraints across all accepted ADRs.
# Returns { adr_id, constraint_id, severity, passed, detail } records.
# Exit code is non-zero if any Hard constraint fails.
export def "validate check-all" [
  --fmt: string = "table",   # Output: table | json | yaml
  --hard-only,               # Include only Hard constraints (default: all)
]: nothing -> any {
  let all_results = (adr-files | each { |ncl|
    let adr = (daemon-export-safe $ncl)
    if $adr == null { return [] }
    if $adr.status != "Accepted" { return [] }

    $adr.constraints | each { |c|
      if $hard_only and $c.severity != "Hard" { return null }
      let res = if ($c.check? | is-empty) {
        { passed: false, detail: "check field missing — uses deprecated check_hint" }
      } else {
        dispatch-check $c.check
      }
      {
        adr_id:        $adr.id,
        constraint_id: $c.id,
        severity:      $c.severity,
        passed:        $res.passed,
        detail:        $res.detail,
      }
    } | compact
  } | flatten)

  let failures = ($all_results | where passed == false)
  let total    = ($all_results | length)
  let n_fail   = ($failures | length)

  let output = match $fmt {
    "json"  => { $all_results | to json },
    "yaml"  => { $all_results | to yaml },
    _       => { $all_results | table --expand },
  }

  print $output

  if ($failures | is-not-empty) {
    error make {
      msg: $"($n_fail) of ($total) constraints failed",
    }
  }
}

# Show a summary of constraint validation state across all accepted ADRs.
# Intended for ontoref status / describe guides.
export def "validate summary" []: nothing -> record {
  let all_results = (adr-files | each { |ncl|
    let adr = (daemon-export-safe $ncl)
    if $adr == null { return [] }
    if $adr.status != "Accepted" { return [] }

    $adr.constraints | each { |c|
      let res = if ($c.check? | is-empty) {
        { passed: false }
      } else {
        dispatch-check $c.check
      }
      { severity: $c.severity, passed: $res.passed }
    } | compact
  } | flatten)

  let hard = ($all_results | where severity == "Hard")
  let soft = ($all_results | where severity == "Soft")
  {
    hard_total:   ($hard | length),
    hard_passing: ($hard | where passed == true | length),
    soft_total:   ($soft | length),
    soft_passing: ($soft | where passed == true | length),
  }
}

# ── Justfile convention validator ────────────────────────────────────────────

# Detect module system from root justfile content.
def detect-just-module-system [justfile_path: string]: nothing -> string {
  if not ($justfile_path | path exists) { return "Flat" }
  let content = (open --raw $justfile_path)
  let has_import = ($content | lines | any { |l| $l =~ '^import ' })
  let has_mod    = ($content | lines | any { |l| $l =~ '^mod ' })
  if $has_import and $has_mod { "Hybrid" } else if $has_import { "Import" } else if $has_mod { "Mod" } else { "Flat" }
}

# Extract recipe names from a just file (lines starting with identifier at col 0, followed by whitespace or ':').
def extract-just-recipes [file_path: string]: nothing -> list<string> {
  if not ($file_path | path exists) { return [] }
  open --raw $file_path
  | lines
  | where { |l| not ($l | str starts-with "#") and not ($l | str starts-with " ") and not ($l | str starts-with "\t") and not ($l | str starts-with "[") and ($l =~ '^[a-z_@][a-z0-9_@-]*[\s:]') }
  | each { |l| $l | str replace -r '[\s:].*' '' | str replace -r '^@' '' }
  | where { |n| ($n | str length) > 0 }
  | uniq
}

# Extract variable names from a just file (lines with ':=' at col 0).
def extract-just-variables [file_path: string]: nothing -> list<string> {
  if not ($file_path | path exists) { return [] }
  open --raw $file_path
  | lines
  | where { |l| $l =~ ':=' and not ($l | str starts-with "#") and not ($l | str starts-with " ") and not ($l | str starts-with "\t") }
  | each { |l| $l | split row ':=' | first | str trim }
  | where { |n| ($n | str length) > 0 }
  | uniq
}

# Validate the project justfile tree against reflection/schemas/justfile-convention.ncl.
# Reports missing required modules, recipes, and variables.
export def "validate justfile" [
  --root (-r): string = "",   # Project root (default: ONTOREF_PROJECT_ROOT or ONTOREF_ROOT)
  --fmt (-f): string = "",    # json | text (default: actor-aware)
  --actor (-a): string = "",
]: nothing -> nothing {
  let project_root = if ($root | is-not-empty) { $root } else {
    $env.ONTOREF_PROJECT_ROOT? | default $env.ONTOREF_ROOT
  }
  let actor = if ($actor | is-not-empty) { $actor } else { $env.ONTOREF_ACTOR? | default "developer" }
  let fmt   = if ($fmt | is-not-empty) { $fmt } else if $actor == "agent" { "json" } else { "text" }

  let schema_file = ([$env.ONTOREF_ROOT, "reflection", "schemas", "justfile-convention.ncl"] | path join)
  if not ($schema_file | path exists) {
    error make { msg: $"Convention schema not found: ($schema_file)" }
  }

  let exported = (daemon-export-safe $schema_file --import-path $env.ONTOREF_ROOT)
  if $exported == null {
    error make { msg: "Failed to export justfile-convention.ncl" }
  }
  let conv = $exported.Convention

  # Locate root justfile
  let root_just = ([$project_root, "justfile"] | path join)
  let detected_system = (detect-just-module-system $root_just)

  # Collect all just files in the convention directory
  let just_dir  = ([$project_root, $conv.directory] | path join)
  let all_files = (
    [[$root_just]] ++
    (if ($just_dir | path exists) {
      glob $"($just_dir)/*($conv.extension)"
    } else { [] })
  ) | flatten | where { |f| $f | path exists }

  # Extract recipes and variables across all files
  let all_recipes  = ($all_files | each { |f| extract-just-recipes $f }  | flatten | uniq)
  let all_variables = ($all_files | each { |f| extract-just-variables $f } | flatten | uniq)

  # Check canonical modules: for each module, does {dir}/{name}{ext} exist?
  let module_results = ($conv.canonical_modules | each { |m|
    let mfile = ([$project_root, $conv.directory, $"($m.name)($conv.extension)"] | path join)
    let present = ($mfile | path exists)
    {
      name:        $m.name,
      required:    $m.required,
      present:     $present,
      description: $m.description,
    }
  })

  let missing_required_modules = ($module_results | where required == true and present == false | get name)
  let missing_optional_modules = ($module_results | where required == false and present == false | get name)

  # Check required recipes
  let missing_recipes = ($conv.required_recipes | where { |r| not ($r in $all_recipes) })

  # Check required variables
  let missing_variables = ($conv.required_variables | where { |v| not ($v in $all_variables) })

  let ok = ($missing_required_modules | is-empty) and ($missing_recipes | is-empty) and ($missing_variables | is-empty)

  let result = {
    ok:                       $ok,
    module_system_detected:   $detected_system,
    module_system_expected:   ($conv.system | into string),
    modules_present:          ($module_results | where present == true | get name),
    missing_required_modules: $missing_required_modules,
    missing_optional_modules: $missing_optional_modules,
    recipes_found:            ($all_recipes | length),
    missing_required_recipes: $missing_recipes,
    variables_found:          ($all_variables | length),
    missing_required_variables: $missing_variables,
  }

  if $fmt == "json" {
    print ($result | to json)
    return
  }

  # Text output
  let status_line = if $ok { "✓ justfile validates against convention" } else { "✗ justfile convention violations found" }
  print $status_line
  print $"  module system: detected=($detected_system) expected=($conv.system)"
  print $"  modules present: ($result.modules_present | str join ', ')"

  if ($missing_required_modules | is-not-empty) {
    print $"  MISSING required modules: ($missing_required_modules | str join ', ')"
  }
  if ($missing_optional_modules | is-not-empty) {
    print $"  optional modules absent: ($missing_optional_modules | str join ', ')"
  }
  if ($missing_recipes | is-not-empty) {
    print $"  MISSING required recipes: ($missing_recipes | str join ', ')"
  }
  if ($missing_variables | is-not-empty) {
    print $"  MISSING required variables: ($missing_variables | str join ', ')"
  }
  if $ok {
    print $"  recipes found: ($result.recipes_found)  variables found: ($result.variables_found)"
  }
}

# ── Mode hierarchy validation (ADR-018) ──────────────────────────────────────

# Extract level info from the project manifest. Returns Base if absent.
def load-level-info []: nothing -> record {
  let root = (adr-root)
  let manifest_file = ([$root, ".ontology", "manifest.ncl"] | path join)
  if not ($manifest_file | path exists) {
    return { index: "Base", name: ([$root] | path basename), parent: null }
  }
  let manifest = (daemon-export-safe $manifest_file)
  if $manifest == null {
    return { index: "Base", name: ([$root] | path basename), parent: null }
  }
  let level = ($manifest.level? | default null)
  if $level == null {
    return { index: "Base", name: ($manifest.project? | default ([$root] | path basename)), parent: null }
  }
  {
    index:       ($level.index | into string),
    name:        ($level.name? | default "unknown"),
    parent:      ($level.parent? | default null),
    parent_path: ($level.parent_path? | default null),
  }
}

# Read mode id and strategy from a single NCL file via source grep.
# Using rg instead of nickel export because local normalizers may strip strategy/extends
# from the exported record — these are source-level annotations, not runtime fields.
def read-mode-strategy [file: string]: nothing -> record {
  let stem = ($file | path basename | str replace ".ncl" "")

  # id: prefer grepped value, fall back to stem (they match in practice)
  let id_hit = (do { ^rg -m1 --no-heading -o 'id\s*=\s*"[^"]*"' $file } | complete)
  let id = if $id_hit.exit_code == 0 {
    $id_hit.stdout | str trim
    | str replace -r '^id\s*=\s*"' '' | str replace -r '".*$' '' | str trim
    | if ($in | str length) > 0 { $in } else { $stem }
  } else { $stem }

  # strategy = 'Override  (Nickel enum tag syntax — single quote prefix)
  let strat_hit = (do { ^rg -m1 --no-heading -o "'(Override|Delegate|Merge|Compose)" $file } | complete)
  let strategy = if $strat_hit.exit_code == 0 {
    $strat_hit.stdout | str trim | str replace "'" "" | str trim
  } else { null }

  # extends = ["step-a", "step-b"]  — extract content between [ and ]
  let ext_hit = (do { ^rg -m1 --no-heading -o 'extends\s*=\s*\[[^\]]*\]' $file } | complete)
  let extends = if $ext_hit.exit_code == 0 {
    $ext_hit.stdout | str trim
    | str replace -r '^extends\s*=\s*\[' '' | str replace -r '\].*$' ''
    | split row ","
    | each { |s| $s | str replace -ra '"' '' | str trim }
    | where { |s| ($s | str length) > 0 }
  } else { [] }

  {
    id:       $id,
    file:     $file,
    strategy: $strategy,
    extends:  $extends,
    parse_ok: ($file | path exists),
  }
}

# Collect mode files with source metadata: { file, local }
# local=true means the file belongs to this project (not the ontoref root).
# strategy-declared checks only apply to local files.
def collect-mode-files-tagged []: nothing -> list<record> {
  let root = (adr-root)
  let ontoref_root = ($env.ONTOREF_ROOT? | default $root)
  let is_self = ($root == $ontoref_root)

  let root_modes = if ($ontoref_root | path exists) {
    glob $"($ontoref_root)/reflection/modes/*.ncl"
    | each { |f| { file: $f, local: $is_self } }
  } else { [] }

  let project_modes = if (not $is_self) and ([$root, "reflection", "modes"] | path join | path exists) {
    glob $"($root)/reflection/modes/*.ncl"
    | each { |f| { file: $f, local: true } }
  } else { [] }

  # project-local files shadow root files with same basename
  let local_basenames = ($project_modes | each { |r| $r.file | path basename } | uniq)
  let filtered_root = ($root_modes | where { |r| not (($r.file | path basename) in $local_basenames) })
  ($filtered_root | append $project_modes)
}

# Collect all mode files (plain list, for backwards compat with mode resolve).
def collect-mode-files []: nothing -> list<string> {
  collect-mode-files-tagged | get file
}

# Format a single mode result row for text output.
def fmt-mode-row [m: record, level_index: string]: nothing -> string {
  let status = if not $m.parse_ok {
    $"(ansi red)PARSE_ERROR(ansi reset)"
  } else if ($m.strategy | is-empty) {
    if $level_index == "Base" {
      $"(ansi dark_gray)implicit-base(ansi reset)"
    } else {
      $"(ansi yellow)MISSING(ansi reset)"
    }
  } else {
    match $m.strategy {
      "Override" => $"(ansi green)Override(ansi reset)",
      "Delegate" => $"(ansi cyan)Delegate(ansi reset)",
      "Merge"    => $"(ansi blue)Merge(ansi reset)",
      "Compose"  => $"(ansi magenta)Compose(ansi reset)",
      _          => $"(ansi yellow)($m.strategy)(ansi reset)",
    }
  }
  let extends_str = if ($m.extends | is-not-empty) { $" extends=[($m.extends | str join ', ')]" } else { "" }
  $"  ($m.id | fill -w 45) ($status)($extends_str)"
}

# Run the level-declared check: manifest must declare level if not Base.
def check-level-declared [level: record, modes: list<record>]: nothing -> list<record> {
  let ok = $level.index != "Base" or ($level.name | is-not-empty)
  [{
    check:   "level-declared",
    severity: "Soft",
    passed:  ($level.index != "Base"),
    detail:  (if $level.index == "Base" {
      "No level declared — project is implicitly Base (ontoref root). Add level = { index = 'Domain, ... } for consumer projects."
    } else {
      $"Level ($level.index) declared: name=($level.name) parent=($level.parent? | default 'none')"
    }),
  }]
}

# Run the strategy-declared check: at Domain/Instance, local mode files must declare strategy.
# Root (inherited) modes are excluded — if no local file exists, delegation is implicit and correct.
def check-strategy-declared [level: record, modes: list<record>]: nothing -> list<record> {
  if $level.index == "Base" {
    return [{
      check:    "strategy-declared",
      severity: "Soft",
      passed:   true,
      detail:   "Base level — strategy declarations not required",
    }]
  }
  let local_modes = ($modes | where local == true)
  if ($local_modes | is-empty) {
    return [{
      check:    "strategy-declared",
      severity: "Soft",
      passed:   true,
      detail:   "No local mode files — all modes delegate to parent implicitly",
    }]
  }
  $local_modes | each { |m|
    let missing = $m.parse_ok and ($m.strategy | is-empty)
    {
      check:    "strategy-declared",
      severity: "Soft",
      passed:   (not $missing),
      detail:   (if $missing {
        $"($m.id): strategy field absent — implicit Delegate \(Soft warning per ADR-018\)"
      } else if not $m.parse_ok {
        $"($m.id): NCL parse error — cannot verify strategy"
      } else {
        $"($m.id): strategy=($m.strategy)"
      }),
    }
  }
}

# Run the delegate-chain check: Delegate modes must have a declared parent in the manifest.
# If parent_path is set, verifies the parent project actually has the mode file (Hard failure if absent).
# If parent_path is absent but parent is declared, emits a Soft warning (unverifiable remotely).
def check-delegate-chain [level: record, modes: list<record>]: nothing -> list<record> {
  let delegates = ($modes | where { |m| $m.strategy == "Delegate" })
  if ($delegates | is-empty) {
    return [{
      check:    "delegate-chain",
      severity: "Soft",
      passed:   true,
      detail:   "No Delegate modes — chain is trivially valid",
    }]
  }
  if ($level.parent | is-empty) {
    return ($delegates | each { |m|
      {
        check:    "delegate-chain",
        severity: "Hard",
        passed:   false,
        detail:   $"($m.id): strategy=Delegate but manifest.level.parent is not declared — orphaned delegation",
      }
    })
  }
  let parent_path = ($level.parent_path? | default null)
  if ($parent_path | is-empty) {
    # parent declared but no path — unverifiable, Soft warning
    return ($delegates | each { |m|
      {
        check:    "delegate-chain",
        severity: "Soft",
        passed:   true,
        detail:   $"($m.id): delegates to parent=($level.parent) — add parent_path to manifest.level to enable cross-project verification",
      }
    })
  }
  # parent_path declared — verify each Delegate mode exists in parent's reflection/modes/
  $delegates | each { |m|
    let parent_mode_file = ([$parent_path, "reflection", "modes", $"($m.id).ncl"] | path join)
    let found = ($parent_mode_file | path exists)
    {
      check:    "delegate-chain",
      severity: "Hard",
      passed:   $found,
      detail:   (if $found {
        $"($m.id): verified in parent at ($parent_path)/reflection/modes/($m.id).ncl"
      } else {
        $"($m.id): strategy=Delegate but ($parent_path)/reflection/modes/($m.id).ncl not found — orphaned delegation"
      }),
    }
  }
}

# Run the compose-extends check: Compose modes must have a non-empty extends field.
def check-compose-extends [level: record, modes: list<record>]: nothing -> list<record> {
  let composers = ($modes | where { |m| $m.strategy == "Compose" })
  if ($composers | is-empty) {
    return [{
      check:    "compose-extends",
      severity: "Soft",
      passed:   true,
      detail:   "No Compose modes",
    }]
  }
  $composers | each { |m|
    let ok = ($m.extends | is-not-empty)
    {
      check:    "compose-extends",
      severity: "Hard",
      passed:   $ok,
      detail:   (if $ok {
        $"($m.id): extends=[($m.extends | str join ', ')]"
      } else {
        $"($m.id): strategy=Compose but extends=[] — must name parent step ids to inherit"
      }),
    }
  }
}

# ── Self-test (exercises all 4 check variants with synthetic fixtures) ────────

# Write a minimal NCL mode fragment to a file — no contracts, just the fields rg needs.
def write-test-mode [dir: string, id: string, content: string]: nothing -> string {
  let file = ([$dir, $"($id).ncl"] | path join)
  $content | save --force $file
  $file
}

# Run validate modes self-test: creates ephemeral temp fixtures, exercises every check
# variant on known positive and negative inputs, reports pass/fail for each assertion.
# Returns non-zero if any assertion fails.
export def "validate modes --self-test" [
  --fmt (-f): string = "text",
]: nothing -> any {
  # Build temp dirs for a synthetic Instance project and its parent Domain
  let tmp       = ([ ($env.TMPDIR? | default "/tmp"), "ontoref-validate-selftest" ] | path join)
  let tmp_parent = ([ ($env.TMPDIR? | default "/tmp"), "ontoref-validate-selftest-parent" ] | path join)
  let modes_dir        = ([$tmp, "reflection", "modes"] | path join)
  let parent_modes_dir = ([$tmp_parent, "reflection", "modes"] | path join)

  do { rm -rf $tmp $tmp_parent } | ignore
  mkdir $modes_dir
  mkdir $parent_modes_dir

  # ── Fixture: parent project has one mode (delegate-present) ─────────────────
  write-test-mode $parent_modes_dir "delegate-present" '{ id = "delegate-present", strategy = '"'"'Override, steps = [] }' | ignore

  # ── Fixtures: local Instance modes ──────────────────────────────────────────
  # override-mode: should pass strategy-declared
  write-test-mode $modes_dir "override-mode" '{ id = "override-mode", strategy = '"'"'Override, steps = [] }' | ignore
  # no-strategy: should warn strategy-declared (Soft)
  write-test-mode $modes_dir "no-strategy" '{ id = "no-strategy", steps = [] }' | ignore
  # delegate-present: delegates to parent, parent HAS the mode → should pass Hard
  write-test-mode $modes_dir "delegate-present" '{ id = "delegate-present", strategy = '"'"'Delegate, steps = [] }' | ignore
  # delegate-missing: delegates to parent, parent DOES NOT have it → should fail Hard
  write-test-mode $modes_dir "delegate-missing" '{ id = "delegate-missing", strategy = '"'"'Delegate, steps = [] }' | ignore
  # compose-ok: Compose with non-empty extends → should pass Hard
  write-test-mode $modes_dir "compose-ok" '{ id = "compose-ok", strategy = '"'"'Compose, extends = ["build-base", "test-base"], steps = [] }' | ignore
  # compose-bad: Compose with empty extends → should fail Hard
  write-test-mode $modes_dir "compose-bad" '{ id = "compose-bad", strategy = '"'"'Compose, extends = [], steps = [] }' | ignore

  # ── Synthetic level records (bypass manifest loading) ───────────────────────
  let level_base = {
    index: "Base", name: "selftest-base", parent: null, parent_path: null
  }
  let level_instance_no_parent_path = {
    index: "Instance", name: "selftest-instance", parent: "selftest-domain", parent_path: null
  }
  let level_instance_with_parent_path = {
    index: "Instance", name: "selftest-instance", parent: "selftest-domain", parent_path: $tmp_parent
  }

  # ── Read synthetic mode records via rg ──────────────────────────────────────
  let all_modes = (
    glob $"($modes_dir)/*.ncl"
    | each { |f| (read-mode-strategy $f) | merge { local: true } }
    | sort-by id
  )

  # Helper: run a check, assert expected outcome, return result record
  let assertions = [
    # level-declared: Base → Soft warning (no level declared)
    {
      label:    "level-declared/Base → Soft warning",
      expected: false,
      result:   (check-level-declared $level_base [] | first),
    },
    # level-declared: Instance → passes
    {
      label:    "level-declared/Instance → pass",
      expected: true,
      result:   (check-level-declared $level_instance_no_parent_path [] | first),
    },
    # strategy-declared: override-mode → pass; no-strategy → Soft warn
    {
      label:    "strategy-declared/override-mode → pass",
      expected: true,
      result:   (check-strategy-declared $level_instance_no_parent_path $all_modes | where { |r| "override-mode" in $r.detail } | get 0? | default { passed: false }),
    },
    {
      label:    "strategy-declared/no-strategy → Soft warn",
      expected: false,
      result:   (check-strategy-declared $level_instance_no_parent_path $all_modes | where { |r| "no-strategy" in $r.detail } | get 0? | default { passed: true }),
    },
    # delegate-chain: no parent_path → Soft pass (unverifiable)
    {
      label:    "delegate-chain/no-parent_path → Soft pass",
      expected: true,
      result:   (check-delegate-chain $level_instance_no_parent_path $all_modes | where { |r| "delegate-present" in $r.detail } | get 0? | default { passed: false }),
    },
    # delegate-chain: parent_path set, mode present → Hard pass
    {
      label:    "delegate-chain/parent_path+present → Hard pass",
      expected: true,
      result:   (check-delegate-chain $level_instance_with_parent_path $all_modes | where { |r| "delegate-present" in $r.detail } | get 0? | default { passed: false }),
    },
    # delegate-chain: parent_path set, mode absent → Hard fail
    {
      label:    "delegate-chain/parent_path+missing → Hard fail",
      expected: false,
      result:   (check-delegate-chain $level_instance_with_parent_path $all_modes | where { |r| "delegate-missing" in $r.detail } | get 0? | default { passed: true }),
    },
    # compose-extends: compose-ok → Hard pass
    {
      label:    "compose-extends/extends-present → Hard pass",
      expected: true,
      result:   (check-compose-extends $level_instance_no_parent_path $all_modes | where { |r| "compose-ok" in $r.detail } | get 0? | default { passed: false }),
    },
    # compose-extends: compose-bad → Hard fail
    {
      label:    "compose-extends/extends-empty → Hard fail",
      expected: false,
      result:   (check-compose-extends $level_instance_no_parent_path $all_modes | where { |r| "compose-bad" in $r.detail } | get 0? | default { passed: true }),
    },
  ]

  let results = ($assertions | each { |a|
    let actual   = $a.result.passed
    let ok       = ($actual == $a.expected)
    {
      label:    $a.label,
      expected: (if $a.expected { "pass" } else { "fail" }),
      actual:   (if $actual { "pass" } else { "fail" }),
      ok:       $ok,
    }
  })

  # Cleanup
  do { rm -rf $tmp $tmp_parent } | ignore

  let failures = ($results | where ok == false)

  if $fmt == "json" {
    print ($results | to json)
  } else {
    print $"validate modes --self-test: ($results | length) assertions, ($failures | length) failures"
    print ""
    for r in $results {
      let icon = if $r.ok { $"(ansi green)✓(ansi reset)" } else { $"(ansi red)✗(ansi reset)" }
      let detail = if $r.ok { "" } else { $"  expected=($r.expected) got=($r.actual)" }
      print $"($icon) ($r.label)($detail)"
    }
  }

  if ($failures | is-not-empty) {
    error make { msg: $"($failures | length) self-test assertion\(s\) failed" }
  }
}

# Validate mode files against the ADR-018 level hierarchy and resolution strategy rules.
# Checks: level-declared | strategy-declared | delegate-chain | compose-extends | all
export def "validate modes" [
  --check (-c): string = "all",  # level-declared | strategy-declared | delegate-chain | compose-extends | all
  --fmt (-f): string = "table",  # table | json | yaml | text
]: nothing -> any {
  let level = (load-level-info)
  let tagged = (collect-mode-files-tagged)
  let modes = ($tagged | each { |t|
    let m = (read-mode-strategy $t.file)
    $m | merge { local: $t.local }
  } | sort-by id)

  let results = match $check {
    "level-declared"    => (check-level-declared    $level $modes),
    "strategy-declared" => (check-strategy-declared $level $modes),
    "delegate-chain"    => (check-delegate-chain    $level $modes),
    "compose-extends"   => (check-compose-extends   $level $modes),
    _                   => (
      (check-level-declared    $level $modes)
      | append (check-strategy-declared $level $modes)
      | append (check-delegate-chain    $level $modes)
      | append (check-compose-extends   $level $modes)
    ),
  }

  let failures = ($results | where passed == false)
  let hard_failures = ($failures | where severity == "Hard")

  match $fmt {
    "json" => { print ($results | to json) },
    "yaml" => { print ($results | to yaml) },
    _      => {
      let local_count = ($modes | where local == true | length)
      let inherited_count = ($modes | where local == false | length)
      print $"Level: (ansi cyan_bold)($level.index)(ansi reset)  name=($level.name)  parent=($level.parent? | default 'none')"
      print $"Modes: ($modes | length) \(($local_count) local, ($inherited_count) inherited\)  Checks: ($results | length)  Failures: ($failures | length)"
      print ""
      for r in $results {
        let icon = if $r.passed { $"(ansi green)✓(ansi reset)" } else if $r.severity == "Hard" { $"(ansi red)✗(ansi reset)" } else { $"(ansi yellow)⚠(ansi reset)" }
        print $"($icon) [($r.check)] ($r.detail)"
      }
    },
  }

  if ($hard_failures | is-not-empty) {
    error make { msg: $"($hard_failures | length) Hard constraint\(s\) failed in validate modes --check ($check)" }
  }
}

# Show which hierarchy level handles a mode invocation (ADR-018 resolution).
# Reports the mode's strategy at this level and what that means for execution.
export def "mode resolve" [
  id: string,        # Mode id (without .ncl extension)
  --fmt (-f): string = "text",  # text | json
]: nothing -> any {
  let level = (load-level-info)
  let mode_files = (collect-mode-files)
  let candidates = ($mode_files | where { |f| ($f | path basename | str replace ".ncl" "") == $id })

  if ($candidates | is-empty) {
    error make { msg: $"Mode '($id)' not found in reflection/modes/" }
  }

  let m = (read-mode-strategy ($candidates | first))

  let resolution = if not $m.parse_ok {
    { answered_by: "unknown", reason: "NCL parse error", action: "fix parse error" }
  } else if ($m.strategy | is-empty) {
    if $level.index == "Base" {
      { answered_by: $level.name, reason: "Base level — implicit Override", action: "executes here" }
    } else {
      { answered_by: "parent", reason: "strategy absent — treated as implicit Delegate (ADR-018 Soft warning)", action: $"traverse to ($level.parent? | default 'unknown')" }
    }
  } else {
    match $m.strategy {
      "Override" => { answered_by: $level.name, reason: "strategy=Override", action: "executes here — traversal stops" },
      "Delegate" => { answered_by: "parent",     reason: "strategy=Delegate", action: $"traverse to ($level.parent? | default 'unknown') — not implemented here" },
      "Merge"    => { answered_by: "all-levels", reason: "strategy=Merge", action: $"accumulate contributions from ($level.name) and parent chain; this level wins conflicts" },
      "Compose"  => { answered_by: $level.name,  reason: $"strategy=Compose extends=[($m.extends | str join ', ')]", action: $"executes here with step\(s\) ($m.extends | str join ', ') inherited from ($level.parent? | default 'parent')" },
      _          => { answered_by: "unknown",    reason: $"unrecognised strategy: ($m.strategy)", action: "check ADR-018" },
    }
  }

  let effective_strategy = if ($m.strategy? | is-empty) {
    if $level.index == "Base" { "implicit-Override" } else { "implicit-Delegate" }
  } else {
    $m.strategy
  }

  let out = {
    mode:        $m.id,
    level_index: $level.index,
    level_name:  $level.name,
    parent:      ($level.parent? | default null),
    strategy:    $effective_strategy,
    answered_by: $resolution.answered_by,
    action:      $resolution.action,
    reason:      $resolution.reason,
  }

  if $fmt == "json" {
    print ($out | to json)
    return
  }

  print $"Mode:     (ansi cyan_bold)($out.mode)(ansi reset)"
  print $"Level:    ($out.level_index) / ($out.level_name)"
  print $"Strategy: ($out.strategy)"
  print $"Resolves: (ansi green_bold)($out.answered_by)(ansi reset) — ($out.action)"
  if ($out.reason | is-not-empty) { print $"Reason:   (ansi dark_gray)($out.reason)(ansi reset)" }
}