From fd5823ecfc662b9ca5938ff0fe1f898bdb64c82b Mon Sep 17 00:00:00 2001
From: Dmytro Smirnov <dmitry.smirnov@usabilitydynamics.com>
Date: Tue, 19 May 2026 21:06:19 +0300
Subject: [PATCH 1/7] Expose repo workflow contract

---
 .rabbit/context.yaml                          |   9 +-
 bin/dev-kit                                   | 104 ++++++++++++++-
 bin/scripts/install.sh                        |   1 +
 changes.md                                    |   3 +
 docs/context-coverage.md                      |   2 +
 docs/repo-contract-boundary.md                |  17 +++
 lib/commands/env.sh                           |  78 +++++++++++
 lib/commands/repo.sh                          |  16 +++
 lib/modules/repo_factors.sh                   | 126 +++++++++++++++++-
 lib/modules/repo_signals.sh                   |   3 +
 lib/modules/repo_workflows.sh                 | 120 ++++++++++++++++-
 src/templates/repo.json                       |   1 +
 .../infra_configs/staging/k8s-configmap.yaml  |   2 +
 tests/suite.sh                                |  14 +-
 14 files changed, 481 insertions(+), 15 deletions(-)
 create mode 100644 tests/fixtures/docker-repo/.rabbit/infra_configs/staging/k8s-configmap.yaml

diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml
index d5719ae..cc40d38 100644
--- a/.rabbit/context.yaml
+++ b/.rabbit/context.yaml
@@ -6,7 +6,7 @@ generator:
   tool: dev.kit
   repo: https://github.com/udx/dev.kit
   version: 0.10.0
-  generated_at: 2026-05-13T00:55:54Z
+  generated_at: 2026-05-19T17:49:21Z
 
 repo:
   name: dev.kit
@@ -70,14 +70,16 @@ gaps:
 dependencies:
   - repo: udx/reusable-workflows
     kind: reusable workflow
-    resolved: false
+    resolved: true
+    archetype: workflow-repo
     used_by:
       - .github/workflows/context7-ops.yml
       - .github/workflows/npm-release-ops.yml
   - repo: udx/worker
     kind: manifest contract (deploy)
-    resolved: false
+    resolved: true
     declared_as: udx.io/worker-v1/deploy
+    archetype: manifest-repo
     used_by:
       - deploy.yml
 
@@ -163,4 +165,3 @@ manifests:
       - path reference: src/configs/context-config.yaml
       - path reference: src/configs/detection-signals.yaml
       - path reference: tests/suite.sh
-
diff --git a/bin/dev-kit b/bin/dev-kit
index 004bfa4..b1711de 100755
--- a/bin/dev-kit
+++ b/bin/dev-kit
@@ -309,6 +309,94 @@ dev_kit_home_context_reason() {
   fi
 }
 
+dev_kit_home_repo_workflow_status() {
+  local repo_root="$1"
+  local context_status="$2"
+  local context_yaml_path="$3"
+  local gap_count=0
+
+  [ -n "$repo_root" ] || {
+    printf '%s' "unavailable"
+    return 0
+  }
+
+  case "$context_status" in
+    missing)
+      printf '%s' "needs_repo_context"
+      return 0
+      ;;
+    stale)
+      printf '%s' "stale_context"
+      return 0
+      ;;
+  esac
+
+  if [ -n "$context_yaml_path" ] && [ -f "$context_yaml_path" ]; then
+    gap_count="$(dev_kit_context_section_item_count "$context_yaml_path" "gaps" '^  - factor:')"
+  else
+    gap_count="$(dev_kit_repo_gap_count "$repo_root")"
+  fi
+
+  if [ "${gap_count:-0}" -gt 0 ]; then
+    printf '%s' "needs_repair"
+    return 0
+  fi
+
+  printf '%s' "ready"
+}
+
+dev_kit_home_workflow_status() {
+  local repo_detected="$1"
+  local env_status="$2"
+  local repo_status="$3"
+
+  if [ "$env_status" = "blocked" ]; then
+    printf '%s' "blocked"
+    return 0
+  fi
+
+  if [ "$repo_detected" != "true" ]; then
+    printf '%s' "workspace_only"
+    return 0
+  fi
+
+  case "$repo_status" in
+    needs_repo_context|stale_context)
+      printf '%s' "needs_repo_context"
+      ;;
+    needs_repair)
+      printf '%s' "needs_repair"
+      ;;
+    *)
+      printf '%s' "ready"
+      ;;
+  esac
+}
+
+dev_kit_home_workflow_json() {
+  local repo_detected="$1"
+  local repo_root="$2"
+  local context_status="$3"
+  local context_yaml_path="$4"
+  local env_status=""
+  local repo_status=""
+  local workflow_status=""
+  local jobs_json=""
+
+  env_status="$(dev_kit_env_workflow_status)"
+  repo_status="$(dev_kit_home_repo_workflow_status "$repo_root" "$context_status" "$context_yaml_path")"
+  workflow_status="$(dev_kit_home_workflow_status "$repo_detected" "$env_status" "$repo_status")"
+  jobs_json="$(dev_kit_env_workflow_job_json)"
+
+  if [ "$repo_detected" = "true" ]; then
+    jobs_json="${jobs_json}, $(dev_kit_repo_workflow_job_json "$repo_root" "$repo_status" "write" "$context_status")"
+  fi
+
+  printf '{ "id": "dev-kit", "label": "Normalize repo and environment", "status": "%s", "jobs": [%s] }' \
+    "$(dev_kit_json_escape "$workflow_status")" \
+    "$jobs_json"
+}
+
 dev_kit_run_home() {
   local format="${1:-text}"
   local state="installed"
@@ -319,6 +407,9 @@ dev_kit_run_home() {
   local context_yaml_path=""
   local context_status="none"
   local context_reason=""
+  local env_workflow_status=""
+  local repo_workflow_status=""
+  local workflow_status=""
 
   repo_root="$(dev_kit_repo_root "$repo_dir")"
   if [ -n "$repo_root" ]; then
@@ -344,11 +435,16 @@ dev_kit_run_home() {
     fi
   fi
 
+  env_workflow_status="$(dev_kit_env_workflow_status)"
+  repo_workflow_status="$(dev_kit_home_repo_workflow_status "$repo_root" "$context_status" "$context_yaml_path")"
+  workflow_status="$(dev_kit_home_workflow_status "$repo_detected" "$env_workflow_status" "$repo_workflow_status")"
+
   if [ "$format" = "json" ]; then
     printf '{\n'
     printf '  "name": "dev.kit",\n'
     printf '  "home": "%s",\n' "$(dev_kit_json_escape "$DEV_KIT_HOME")"
     printf '  "state": "%s",\n' "$(dev_kit_json_escape "$state")"
+    printf '  "workflow": %s,\n' "$(dev_kit_home_workflow_json "$repo_detected" "$repo_root" "$context_status" "$context_yaml_path")"
     printf '  "workspace": {\n'
     printf '    "path": "%s",\n' "$(dev_kit_json_escape "$repo_dir")"
     printf '    "repo_detected": %s,\n' "$repo_detected"
@@ -392,6 +488,13 @@ dev_kit_run_home() {
   # Text mode: print title immediately, then compute and print progressively
   dev_kit_output_title "dev.kit"
 
+  dev_kit_output_section "workflow"
+  dev_kit_output_row "status" "$workflow_status"
+  dev_kit_output_row "env" "$env_workflow_status"
+  if [ "$repo_detected" = "true" ]; then
+    dev_kit_output_row "repo" "$repo_workflow_status"
+  fi
+
   # ── Environment: list tools by category with what they enable ───────────────
   local _env_line _env_cat _env_val _prev_cat=""
   while IFS= read -r _env_line; do
@@ -422,7 +525,6 @@ EOF
     context_yaml_path="$(dev_kit_context_yaml_path "$repo_root")"
 
     dev_kit_output_summary "${summary_name} • ${summary_archetype}"
-
     dev_kit_output_section "context"
     dev_kit_output_row "path" "$context_yaml_path"
     dev_kit_output_row "status" "$context_status"
diff --git a/bin/scripts/install.sh b/bin/scripts/install.sh
index e96d05c..fbf2376 100755
--- a/bin/scripts/install.sh
+++ b/bin/scripts/install.sh
@@ -173,6 +173,7 @@ main() {
 
   find "$DEV_KIT_HOME/bin" -type f -exec chmod +x {} \;
   ln -sfn "$DEV_KIT_HOME/bin/dev-kit" "$target"
+  ln -sfn "$DEV_KIT_HOME/bin/dev-kit" "${DEV_KIT_BIN_DIR}/dev-kit"
 
   if command -v dev_kit_output_title >/dev/null 2>&1; then
     dev_kit_output_title "Installed dev.kit"
diff --git a/changes.md b/changes.md
index a495a50..f60500d 100644
--- a/changes.md
+++ b/changes.md
@@ -2,6 +2,9 @@
 
 ### unreleased
 
+- Expose repo-centric workflow status in `dev.kit`, `dev.kit env`, and `dev.kit repo` output so environment checks, context refresh, and gap repair appear as one repo-owned loop
+- Clarify the repo contract boundary between deterministic structured parsing and interpreted prose/session intent
+
 ### 0.10.0
 
 - Remove `dev.kit agent` so `.rabbit/context.yaml` is the single generated repo contract
diff --git a/docs/context-coverage.md b/docs/context-coverage.md
index 8261cee..442a167 100644
--- a/docs/context-coverage.md
+++ b/docs/context-coverage.md
@@ -14,6 +14,8 @@ It should answer three questions:
 
 For the boundary between generated contract data and durable repo docs, see [Repo Contract Boundary](repo-contract-boundary.md).
 
+Structured sources such as YAML, JSON, workflow refs, and manifest metadata should be parsed programmatically where possible. Prose sources such as Markdown docs, prompts, reviews, and session notes should be treated as interpreted intent unless they point to a concrete script, manifest, or command.
+
 Typical sections include:
 
 - generator metadata
diff --git a/docs/repo-contract-boundary.md b/docs/repo-contract-boundary.md
index 98c1c6d..70db651 100644
--- a/docs/repo-contract-boundary.md
+++ b/docs/repo-contract-boundary.md
@@ -20,6 +20,21 @@ Use **scripts and manifests** for programmatic execution:
 - deploy manifests such as `deploy.yml`
 - checked-in config examples when they are part of the runnable contract
 
+Use **structured refs** for deterministic parsing:
+
+- YAML and JSON manifests
+- package and tool config files
+- workflow references
+- version, kind, and description metadata
+- explicit command definitions
+
+Use **prose and session material** for interpreted intent:
+
+- Markdown docs and design notes
+- issue, PR, and review discussions
+- agent prompts and session summaries
+- manual decisions that are not encoded in scripts yet
+
 Use **`.rabbit/context.yaml`** for generated operational summary:
 
 - direct-read refs
@@ -38,6 +53,8 @@ If a repo needs a compact generated summary for tooling or safe repo-scoped exec
 
 If a repo needs something to be executed safely by tools, keep that in a script or manifest rather than only in prose docs.
 
+When both structured and prose sources exist, `dev.kit` should parse the structured source first and use prose to explain intent, repair guidance, or open decisions. That keeps automation deterministic while still preserving the human and agent context behind the repo design.
+
 ## Repair loop
 
 1. `dev.kit repo` detects a gap or weak contract
diff --git a/lib/commands/env.sh b/lib/commands/env.sh
index c4f4d68..3a0f839 100644
--- a/lib/commands/env.sh
+++ b/lib/commands/env.sh
@@ -2,6 +2,76 @@
 
 # @description: Inspect environment tools and dev.kit usage config
 
+dev_kit_env_workflow_status() {
+  local missing_tools=""
+  local disabled_tools=""
+  local disabled_credentials=""
+
+  missing_tools="$(dev_kit_env_missing_base_tools)"
+  disabled_tools="$(dev_kit_env_config_list "disabled_tools")"
+  disabled_credentials="$(dev_kit_env_config_list "disabled_credentials")"
+
+  if [ -n "$missing_tools" ]; then
+    printf '%s' "blocked"
+    return 0
+  fi
+
+  if [ -n "$disabled_tools" ] || [ -n "$disabled_credentials" ]; then
+    printf '%s' "customized"
+    return 0
+  fi
+
+  printf '%s' "ready"
+}
+
+dev_kit_env_workflow_step_summaries() {
+  local config_path=""
+
+  config_path="$(dev_kit_env_config_path)"
+  printf '%s\n' "Detect local tools and auth capabilities."
+  printf '%s\n' "Resolve repo-facing capabilities from the current machine."
+  if [ -f "$config_path" ]; then
+    printf '%s\n' "Review environment config overrides at ${config_path}."
+  else
+    printf '%s\n' "Create ${config_path} with dev.kit env --config when overrides are needed."
+  fi
+}
+
+dev_kit_env_workflow_job_json() {
+  local config_path=""
+  local disabled_tools=""
+  local disabled_credentials=""
+  local missing_tools=""
+  local workflow_status=""
+  local config_status="ready"
+
+  config_path="$(dev_kit_env_config_path)"
+  disabled_tools="$(dev_kit_env_config_list "disabled_tools")"
+  disabled_credentials="$(dev_kit_env_config_list "disabled_credentials")"
+  missing_tools="$(dev_kit_env_missing_base_tools)"
+  workflow_status="$(dev_kit_env_workflow_status)"
+
+  if [ -n "$disabled_tools" ] || [ -n "$disabled_credentials" ]; then
+    config_status="customized"
+  fi
+
+  printf '{ "id": "env", "label": "Resolve local environment", "command": "dev.kit env", "status": "%s", "steps": [' \
+    "$(dev_kit_json_escape "$workflow_status")"
+  printf '{ "id": "detect_tools", "type": "inspect", "label": "Detect local tools", "status": "%s", "missing_required": %s, "tools": %s }, ' \
+    "$(if [ -n "$missing_tools" ]; then printf 'blocked'; else printf 'ready'; fi)" \
+    "$(printf '%s' "$missing_tools" | tr ' ' '\n' | awk 'NF' | dev_kit_lines_to_json_array)" \
+    "$(dev_kit_env_tools_json)"
+  printf '{ "id": "resolve_capabilities", "type": "inspect", "label": "Resolve capabilities from the current machine", "status": "ready", "capabilities": %s }, ' \
+    "$(dev_kit_global_context_capabilities_json)"
+  printf '{ "id": "review_config", "type": "read", "label": "Review environment config overrides", "status": "%s", "path": "%s", "exists": %s, "disabled_tools": %s, "disabled_credentials": %s }' \
+    "$(dev_kit_json_escape "$config_status")" \
+    "$(dev_kit_json_escape "$config_path")" \
+    "$([ -f "$config_path" ] && printf 'true' || printf 'false')" \
+    "$(printf '%s' "$disabled_tools" | dev_kit_lines_to_json_array)" \
+    "$(printf '%s' "$disabled_credentials" | dev_kit_lines_to_json_array)"
+  printf '] }'
+}
+
 dev_kit_cmd_env() {
   local format="${1:-text}"
   local manage_config=0
@@ -35,6 +105,7 @@ dev_kit_cmd_env() {
     printf '{\n'
     printf '  "command": "env",\n'
     printf '  "home": "%s",\n' "$(dev_kit_json_escape "$DEV_KIT_HOME")"
+    printf '  "workflow": { "id": "dev-kit", "label": "Normalize repo and environment", "jobs": [%s] },\n' "$(dev_kit_env_workflow_job_json)"
     printf '  "tools": %s,\n' "$(dev_kit_env_tools_json)"
     printf '  "capabilities": %s,\n' "$(dev_kit_global_context_capabilities_json)"
     printf '  "config": {\n'
@@ -49,6 +120,13 @@ dev_kit_cmd_env() {
 
   dev_kit_output_title "dev.kit env"
 
+  dev_kit_output_section "workflow"
+  dev_kit_output_row "job" "env"
+  dev_kit_output_row "status" "$(dev_kit_env_workflow_status)"
+  dev_kit_output_list_from_lines <<EOF
+$(dev_kit_env_workflow_step_summaries)
+EOF
+
   local _env_line _env_cat _env_val _prev_cat=""
   while IFS= read -r _env_line; do
     [ -n "$_env_line" ] || continue
diff --git a/lib/commands/repo.sh b/lib/commands/repo.sh
index 411bdeb..837bedb 100644
--- a/lib/commands/repo.sh
+++ b/lib/commands/repo.sh
@@ -45,6 +45,8 @@ dev_kit_cmd_repo() {
   local actions_json=""
   local context_yaml_path=""
   local gap_lines=""
+  local workflow_status=""
+  local workflow_context_status=""
 
   local force_resolve=0
   local repo_soft_timeout="${DEV_KIT_REPO_SOFT_TIMEOUT:-15}"
@@ -76,12 +78,18 @@ dev_kit_cmd_repo() {
   local gap_count
   gap_count="$(printf '%s\n' "$gaps_json" | grep -c '"factor"' 2>/dev/null || true)"
   gap_count="${gap_count:-0}"
+  workflow_status="$(dev_kit_repo_workflow_status "$repo_dir" "$gap_count")"
   actions_json="$(dev_kit_repo_actions_json "$gap_count")"
 
   # JSON mode: compute everything up front then emit template
   if [ "$format" = "json" ]; then
     if [ "$mode" = "write" ]; then
       dev_kit_context_yaml_write "$repo_dir" "$force_resolve" >/dev/null
+      workflow_context_status="current"
+    elif [ -f "$context_yaml_path" ]; then
+      workflow_context_status="existing"
+    else
+      workflow_context_status="missing"
     fi
     dev_kit_template_render "repo.json" \
       "command=repo" \
@@ -93,6 +101,7 @@ dev_kit_cmd_repo() {
       "factors=$(dev_kit_repo_factor_summary_json "$repo_dir")" \
       "gaps=$gaps_json" \
       "actions=$actions_json" \
+      "workflow={ \"id\": \"dev-kit\", \"label\": \"Normalize repo and environment\", \"jobs\": [$(dev_kit_repo_workflow_job_json "$repo_dir" "$workflow_status" "$mode" "$workflow_context_status" "$gap_count")] }" \
       "context=$(dev_kit_json_escape "$context_yaml_path")" \
       "dependencies=$(dev_kit_deps_json "$repo_dir")" \
       "recommended_repos=$(dev_kit_repo_recommended_repos_json)"
@@ -109,6 +118,13 @@ dev_kit_cmd_repo() {
 
   dev_kit_output_summary "${repo_name} • ${archetype} • mode: ${mode}"
 
+  dev_kit_output_section "workflow"
+  dev_kit_output_row "job" "repo"
+  dev_kit_output_row "status" "$workflow_status"
+  dev_kit_output_list_from_lines <<EOF
+$(dev_kit_repo_workflow_step_summaries "$repo_dir")
+EOF
+
   # ── Priority refs — what to read first ─────────────────────────────────────
   local priority_refs first_ref second_ref
   priority_refs="$(dev_kit_repo_priority_refs "$repo_dir")"
diff --git a/lib/modules/repo_factors.sh b/lib/modules/repo_factors.sh
index bd84233..1f7523b 100644
--- a/lib/modules/repo_factors.sh
+++ b/lib/modules/repo_factors.sh
@@ -636,16 +636,138 @@ dev_kit_repo_factor_repair_target() {
   [ -n "$first_doc" ] && printf '%s' "$first_doc"
 }
 
+dev_kit_repo_prefers_internal_references() {
+  local repo_dir="$1"
+  local repo_name=""
+  local repo_slug=""
+  local real_repo_dir=""
+
+  repo_name="$(dev_kit_repo_name "$repo_dir" 2>/dev/null || true)"
+  repo_slug="$(dev_kit_repo_current_slug "$repo_dir" "$repo_name" 2>/dev/null || true)"
+  real_repo_dir="$(cd "$repo_dir" 2>/dev/null && pwd)"
+
+  [ "$real_repo_dir" = "$REPO_DIR" ] || { [ "$repo_slug" = "udx/dev.kit" ] && [ "$repo_name" = "dev.kit" ]; }
+}
+
+dev_kit_repo_reference_doc_default() {
+  local repo_dir="$1"
+  local first_doc=""
+
+  first_doc="$(dev_kit_repo_first_existing_signal "$repo_dir" "documentation_files" 2>/dev/null || true)"
+  if [ -n "$first_doc" ]; then
+    printf '%s' "$first_doc"
+    return 0
+  fi
+
+  if dev_kit_repo_has_dir "$repo_dir" "docs"; then
+    printf '%s' "docs/"
+    return 0
+  fi
+
+  printf '%s' "README.md"
+}
+
+dev_kit_repo_dependency_reference_local() {
+  local repo_dir="$1"
+  local first_manifest=""
+  local first_workflow=""
+
+  first_manifest="$(dev_kit_repo_contract_manifest_files "$repo_dir" | awk 'NF { print; exit }')"
+  if [ -n "$first_manifest" ]; then
+    printf '%s' "$first_manifest"
+    return 0
+  fi
+
+  first_workflow="$(dev_kit_repo_first_existing_signal "$repo_dir" "workflow_primary_files" 2>/dev/null || true)"
+  if [ -n "$first_workflow" ]; then
+    printf '%s' "$first_workflow"
+    return 0
+  fi
+
+  if dev_kit_has_file "$repo_dir" "deploy.yml"; then
+    printf '%s' "deploy.yml"
+    return 0
+  fi
+
+  dev_kit_repo_reference_doc_default "$repo_dir"
+}
+
+dev_kit_repo_config_reference_local() {
+  local repo_dir="$1"
+  local runtime_config=""
+  local config_doc=""
+
+  config_doc="$(dev_kit_repo_documented_env_var_sources "$repo_dir" | awk 'NF { print; exit }')"
+  if [ -n "$config_doc" ]; then
+    printf '%s' "$config_doc"
+    return 0
+  fi
+
+  runtime_config="$(dev_kit_repo_first_existing_signal "$repo_dir" "config_runtime_files" 2>/dev/null || true)"
+  if [ -n "$runtime_config" ]; then
+    printf '%s' "$runtime_config"
+    return 0
+  fi
+
+  if dev_kit_has_file "$repo_dir" ".env.example"; then
+    printf '%s' ".env.example"
+    return 0
+  fi
+
+  dev_kit_repo_reference_doc_default "$repo_dir"
+}
+
+dev_kit_repo_pipeline_reference_local() {
+  local repo_dir="$1"
+  local verify_source=""
+  local first_workflow=""
+
+  verify_source="$(dev_kit_repo_command_detection_result "$repo_dir" "verification" 2>/dev/null | cut -d'|' -f3)"
+  if [ -n "$verify_source" ]; then
+    printf '%s' "$verify_source"
+    return 0
+  fi
+
+  first_workflow="$(dev_kit_repo_first_existing_signal "$repo_dir" "workflow_primary_files" 2>/dev/null || true)"
+  if [ -n "$first_workflow" ]; then
+    printf '%s' "$first_workflow"
+    return 0
+  fi
+
+  if dev_kit_has_file "$repo_dir" "deploy.yml"; then
+    printf '%s' "deploy.yml"
+    return 0
+  fi
+
+  dev_kit_repo_reference_doc_default "$repo_dir"
+}
+
 dev_kit_repo_factor_reference() {
+  local repo_dir=""
   local factor="$1"
   local status="$2"
-  local maybe_status="$3"
 
-  if [ -n "${maybe_status:-}" ]; then
+  if [ "$#" -ge 3 ]; then
+    repo_dir="$1"
     factor="$2"
     status="$3"
   fi
 
+  if [ -n "$repo_dir" ] && ! dev_kit_repo_prefers_internal_references "$repo_dir"; then
+    case "${factor}:${status}" in
+      dependencies:partial|dependencies:missing)
+        dev_kit_repo_dependency_reference_local "$repo_dir"
+        ;;
+      config:partial|config:missing)
+        dev_kit_repo_config_reference_local "$repo_dir"
+        ;;
+      pipeline:partial|pipeline:missing)
+        dev_kit_repo_pipeline_reference_local "$repo_dir"
+        ;;
+    esac
+    return 0
+  fi
+
   case "${factor}:${status}" in
     dependencies:partial|dependencies:missing)
       printf '%s' "docs/references/dependency-contracts.md"
diff --git a/lib/modules/repo_signals.sh b/lib/modules/repo_signals.sh
index a99eeb8..a90fe02 100644
--- a/lib/modules/repo_signals.sh
+++ b/lib/modules/repo_signals.sh
@@ -539,6 +539,9 @@ dev_kit_repo_contract_manifest_refs() {
   while IFS= read -r manifest_rel; do
     [ -n "$manifest_rel" ] || continue
     case "$manifest_rel" in
+      .rabbit/*/*)
+        continue
+        ;;
       .rabbit/*.yml|.rabbit/*.yaml|*.yml|*.yaml)
         printf './%s\n' "$manifest_rel"
         ;;
diff --git a/lib/modules/repo_workflows.sh b/lib/modules/repo_workflows.sh
index 2fdb8af..55babe8 100644
--- a/lib/modules/repo_workflows.sh
+++ b/lib/modules/repo_workflows.sh
@@ -26,11 +26,39 @@ dev_kit_repo_entrypoint_source() {
   printf "%s" "$(printf '%s' "$result" | cut -d'|' -f3)"
 }
 
+dev_kit_repo_gap_count() {
+  local repo_dir="$1"
+
+  dev_kit_repo_factor_summary_json "$repo_dir" | jq -r '
+    to_entries
+    | map(select(.value.status == "missing" or .value.status == "partial"))
+    | length
+  ' 2>/dev/null || printf '0'
+}
+
+dev_kit_repo_workflow_status() {
+  local repo_dir="$1"
+  local gap_count="${2:-}"
+
+  if [ -z "$gap_count" ]; then
+    gap_count="$(dev_kit_repo_gap_count "$repo_dir")"
+  fi
+
+  if [ "${gap_count:-0}" -gt 0 ]; then
+    printf '%s' "needs_repair"
+    return 0
+  fi
+
+  printf '%s' "ready"
+}
+
 dev_kit_repo_workflow_steps() {
   local repo_dir="$1"
   local verify_cmd=""
   local build_cmd=""
   local run_cmd=""
+  local context_path=""
+  local gap_count=0
 
   printf "read_repo|Read the highest-priority repo refs first|%s\n" "$(dev_kit_repo_priority_refs "$repo_dir" | dev_kit_lines_to_csv)"
 
@@ -49,8 +77,49 @@ dev_kit_repo_workflow_steps() {
     printf "run|Use the canonical runtime command instead of ad hoc startup paths|%s\n" "$run_cmd"
   fi
 
+  context_path="$(dev_kit_context_yaml_path "$repo_dir")"
+  if [ -n "$context_path" ]; then
+    printf "read_context|Review the generated repo contract|%s\n" "${context_path#"${repo_dir}/"}"
+  fi
+
+  gap_count="$(dev_kit_repo_gap_count "$repo_dir")"
+  if [ "${gap_count:-0}" -gt 0 ]; then
+    printf "confirm_repair|Confirm whether to start the repair loop|repo-owned gaps\n"
+    printf "repair_loop|Repair the strongest gap and rerun dev.kit repo|repo-owned gaps\n"
+  fi
 }
 
+dev_kit_repo_workflow_step_summaries() {
+  local repo_dir="$1"
+  local line=""
+  local step_id=""
+  local command=""
+
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    step_id="${line%%|*}"
+    command="${line##*|}"
+    case "$step_id" in
+      read_repo)
+        printf '%s\n' "Read the highest-priority repo refs."
+        ;;
+      verify|build|run)
+        printf '%s\n' "$command"
+        ;;
+      read_context)
+        printf '%s\n' "Review .rabbit/context.yaml."
+        ;;
+      confirm_repair)
+        printf '%s\n' "Confirm whether to start the repo repair loop."
+        ;;
+      repair_loop)
+        printf '%s\n' "Repair the strongest gap and rerun dev.kit repo."
+        ;;
+    esac
+  done <<EOF
+$(dev_kit_repo_workflow_steps "$repo_dir")
+EOF
+}
 
 dev_kit_repo_workflow_json() {
   local repo_dir="$1"
@@ -71,25 +140,41 @@ dev_kit_repo_workflow_json() {
       printf ", "
     fi
     if [ "$step_id" = "read_repo" ]; then
-      # refs is a CSV of file paths — emit as JSON array with proper escaping
-      local refs_json ref_item
+      local refs_json ref_item ref_first
       refs_json="["
-      local ref_first=1
+      ref_first=1
       while IFS= read -r ref_item; do
         [ -n "$ref_item" ] || continue
-        if [ "$ref_first" -eq 0 ]; then refs_json="${refs_json}, "; fi
+        if [ "$ref_first" -eq 0 ]; then
+          refs_json="${refs_json}, "
+        fi
         refs_json="${refs_json}\"$(dev_kit_json_escape "$ref_item")\""
         ref_first=0
       done <<REFS
 $(printf '%s\n' "$command" | awk '{ n=split($0,a,", "); for(i=1;i<=n;i++) if(a[i]!="") print a[i] }')
 REFS
       refs_json="${refs_json}]"
-      printf '{ "id": "%s", "label": "%s", "refs": %s }' \
+      printf '{ "id": "%s", "type": "read", "label": "%s", "refs": %s }' \
         "$(dev_kit_json_escape "$step_id")" \
         "$(dev_kit_json_escape "$label")" \
         "$refs_json"
+    elif [ "$step_id" = "read_context" ]; then
+      printf '{ "id": "%s", "type": "read", "label": "%s", "path": "%s" }' \
+        "$(dev_kit_json_escape "$step_id")" \
+        "$(dev_kit_json_escape "$label")" \
+        "$(dev_kit_json_escape "$command")"
+    elif [ "$step_id" = "confirm_repair" ]; then
+      printf '{ "id": "%s", "type": "decision", "label": "%s", "subject": "%s" }' \
+        "$(dev_kit_json_escape "$step_id")" \
+        "$(dev_kit_json_escape "$label")" \
+        "$(dev_kit_json_escape "$command")"
+    elif [ "$step_id" = "repair_loop" ]; then
+      printf '{ "id": "%s", "type": "loop", "label": "%s", "subject": "%s" }' \
+        "$(dev_kit_json_escape "$step_id")" \
+        "$(dev_kit_json_escape "$label")" \
+        "$(dev_kit_json_escape "$command")"
     else
-      printf '{ "id": "%s", "label": "%s", "command": "%s" }' \
+      printf '{ "id": "%s", "type": "run", "label": "%s", "command": "%s" }' \
         "$(dev_kit_json_escape "$step_id")" \
         "$(dev_kit_json_escape "$label")" \
         "$(dev_kit_json_escape "$command")"
@@ -100,3 +185,26 @@ $(dev_kit_repo_workflow_steps "$repo_dir")
 EOF
   printf "]"
 }
+
+dev_kit_repo_workflow_job_json() {
+  local repo_dir="$1"
+  local status="${2:-}"
+  local mode="${3:-write}"
+  local context_status="${4:-current}"
+  local gap_count="${5:-}"
+
+  if [ -z "$gap_count" ]; then
+    gap_count="$(dev_kit_repo_gap_count "$repo_dir")"
+  fi
+  if [ -z "$status" ]; then
+    status="$(dev_kit_repo_workflow_status "$repo_dir" "$gap_count")"
+  fi
+
+  printf '{ "id": "repo", "label": "Build repo context", "command": "dev.kit repo", "mode": "%s", "status": "%s", "context": "%s", "context_status": "%s", "gap_count": %s, "steps": %s }' \
+    "$(dev_kit_json_escape "$mode")" \
+    "$(dev_kit_json_escape "$status")" \
+    "$(dev_kit_json_escape "$(dev_kit_context_yaml_path "$repo_dir")")" \
+    "$(dev_kit_json_escape "$context_status")" \
+    "${gap_count:-0}" \
+    "$(dev_kit_repo_workflow_json "$repo_dir")"
+}
diff --git a/src/templates/repo.json b/src/templates/repo.json
index dd1d117..576d829 100644
--- a/src/templates/repo.json
+++ b/src/templates/repo.json
@@ -9,6 +9,7 @@
   "factors": {{factors}},
   "gaps": {{gaps}},
   "actions": {{actions}},
+  "workflow": {{workflow}},
   "context": "{{context}}",
   "dependencies": {{dependencies}},
   "recommended_repos": {{recommended_repos}}
diff --git a/tests/fixtures/docker-repo/.rabbit/infra_configs/staging/k8s-configmap.yaml b/tests/fixtures/docker-repo/.rabbit/infra_configs/staging/k8s-configmap.yaml
new file mode 100644
index 0000000..f19994f
--- /dev/null
+++ b/tests/fixtures/docker-repo/.rabbit/infra_configs/staging/k8s-configmap.yaml
@@ -0,0 +1,2 @@
+kind: ConfigMap
+apiVersion: v1
diff --git a/tests/suite.sh b/tests/suite.sh
index 7e1c4fc..d4af9e4 100644
--- a/tests/suite.sh
+++ b/tests/suite.sh
@@ -165,9 +165,12 @@ if should_run "core"; then
   assert_contains "$home_json" "\"repo_detected\": true" "home: detects repo"
   assert_contains "$home_json" "\"synced\": {" "home: reports synced artifacts"
   assert_contains "$home_json" "\"context_status\": \"missing\"" "home: reports missing context"
+  assert_contains "$home_json" "\"workflow\": {" "home: reports workflow contract"
+  assert_contains "$home_json" "\"id\": \"env\"" "home: includes env job"
   assert_contains "$home_json" "\"helpers\": [" "home: reports helpers"
 
   home_text="$(cd "$HOME_ACTION_REPO" && dev.kit)"
+  assert_contains "$home_text" "[workflow]" "home text: renders workflow section"
   assert_contains "$home_text" "[required]" "home text: renders env tools"
   assert_contains "$home_text" "[context]" "home text: renders context section"
   assert_contains "$home_text" "Repo context is missing." "home text: guides missing context"
@@ -225,7 +228,7 @@ if should_run "core"; then
   assert_contains "$home_repeat_text" "[gaps]" "home text: summarizes gaps"
   assert_contains "$home_repeat_text" "[next]" "home text: summarizes next step"
   assert_contains "$home_repeat_text" "repair: README.md or .env.example" "home text: shows gap repair target"
-  assert_contains "$home_repeat_text" "reference: docs/references/config-contract-surfaces.md" "home text: shows gap reference"
+  assert_contains "$home_repeat_text" "reference: README.md" "home text: shows local gap reference"
   assert_contains "$home_repeat_text" "repair:            fix repo-owned gaps, then rerun dev.kit repo" "home text: prints repair loop next step"
 
   replace_in_file \
@@ -244,15 +247,19 @@ if should_run "core"; then
 
   env_json="$(cd "$HOME_ACTION_REPO" && dev.kit env --json)"
   assert_contains "$env_json" "\"command\": \"env\"" "env: reports command name"
+  assert_contains "$env_json" "\"workflow\": {" "env: reports workflow contract"
 
   repo_json="$(cd "$DOCUMENTED_SHELL_REPO" && dev.kit repo --json)"
   assert_contains "$repo_json" "\"archetype\":" "repo: reports archetype"
   assert_contains "$repo_json" "\"context\":" "repo: reports context path"
+  assert_contains "$repo_json" "\"context_status\": \"current\"" "repo: reports current workflow context after write"
   assert_contains "$repo_json" "\"repair_target\": \"README.md or .env.example\"" "repo: includes repair target"
-  assert_contains "$repo_json" "\"reference\": \"docs/references/config-contract-surfaces.md\"" "repo: includes reference doc"
+  assert_contains "$repo_json" "\"reference\": \"README.md\"" "repo: includes local reference doc"
   assert_contains "$repo_json" "\"id\": \"confirm-research-fix-loop\"" "repo: includes confirmation loop action"
+  assert_contains "$repo_json" "\"workflow\": {" "repo: reports workflow contract"
 
   repo_text="$(cd "$DOCUMENTED_SHELL_REPO" && dev.kit repo)"
+  assert_contains "$repo_text" "[workflow]" "repo text: renders workflow section"
   assert_contains "$repo_text" "[read first]" "repo text: renders read first section"
   assert_contains "$repo_text" "[factors]" "repo text: renders factors section"
   assert_contains "$repo_text" "[context]" "repo text: renders context section"
@@ -307,6 +314,9 @@ if should_run "core"; then
   assert_contains "$(cat "$docker_context_yaml")" "generator:" "docker repo: includes generator metadata"
   assert_contains "$(cat "$docker_context_yaml")" "path: deploy.yml" "docker repo: includes deploy manifest"
   assert_contains "$(cat "$docker_context_yaml")" "path: .rabbit/deploy.yml" "docker repo: includes hidden custom manifest"
+  assert_contains "$(cat "$docker_context_yaml")" "path: .rabbit/infra_configs/staging/k8s-configmap.yaml" "docker repo: inventories nested rabbit manifests"
+  docker_context_refs="$(awk '/^refs:/{flag=1;next} /^# Commands/{if(flag) exit} flag{print}' "$docker_context_yaml")"
+  assert_not_contains "$docker_context_refs" ".rabbit/infra_configs/staging/k8s-configmap.yaml" "docker repo: excludes nested rabbit manifests from read-first refs"
   assert_contains "$(cat "$docker_context_yaml")" "source_repo: udx/worker" "docker repo: traces manifest owner from version"
 
   mkdir -p "$IGNORED_ACTION_REPO/.next/cache"

From 7755c053c9d555fcfa52f2405a6d472a99b90ed6 Mon Sep 17 00:00:00 2001
From: Dmytro Smirnov <dmitry.smirnov@usabilitydynamics.com>
Date: Tue, 19 May 2026 21:20:17 +0300
Subject: [PATCH 2/7] Add read-only real repo validation

---
 README.md                        |   3 +-
 docs/real-repo-validation.md     |  47 ++++++++++
 lib/commands/repo.sh             |   6 +-
 lib/modules/config_catalog.sh    |   8 ++
 src/configs/repo-validation.yaml |  25 +++++
 tests/real-repos.sh              | 153 ++++++++++++++++++++++++-------
 6 files changed, 203 insertions(+), 39 deletions(-)
 create mode 100644 docs/real-repo-validation.md
 create mode 100644 src/configs/repo-validation.yaml

diff --git a/README.md b/README.md
index 57379bd..b1f2a60 100644
--- a/README.md
+++ b/README.md
@@ -181,6 +181,7 @@ All commands support `--json`.
 - [Environment Config](docs/environment-config.md)
 - [Context Coverage](docs/context-coverage.md)
 - [Integration](docs/integration.md)
+- [Real Repo Validation](docs/real-repo-validation.md)
 - [Smart Dependency Detection](docs/smart-dependency-detection.md)
 - [Reference Docs](docs/references/README.md)
 - [Reference: Command and Workflow Surfaces](docs/references/command-surfaces.md)
@@ -199,5 +200,5 @@ bash tests/worker-smoke.sh
 ```
 
 ```bash
-bash tests/real-repos.sh /path/to/repo1 /path/to/repo2
+bash tests/real-repos.sh --check /path/to/repo1 /path/to/repo2
 ```
diff --git a/docs/real-repo-validation.md b/docs/real-repo-validation.md
new file mode 100644
index 0000000..0cc57b6
--- /dev/null
+++ b/docs/real-repo-validation.md
@@ -0,0 +1,47 @@
+# Real Repo Validation
+
+dev.kit is validated at two levels:
+
+- fixtures verify deterministic contracts inside this repo
+- real repos verify whether dev.kit reads repo-owned evidence well enough to guide work
+
+Keep fixtures small. They should cover stable output shape, gap categories, manifest handling, and known regressions. They should not try to model every UDX repo.
+
+Use real repos as optimization probes before a release. Run them read-only by default so the probe reports what dev.kit sees without changing the target repo.
+
+## Local UDX Matrix
+
+Use the matrix declared in `src/configs/repo-validation.yaml` when the listed repos are available locally.
+
+Example:
+
+```bash
+bash tests/real-repos.sh --check ./reusable-workflows ./github-rabbit-action
+```
+
+The summary should be used to compare:
+
+- home context status
+- repo workflow status
+- repo context status
+- gap count
+- read-first ref count
+
+When one repo looks noisy or inconsistent, repair the strongest repo-owned gap or dev.kit normalization issue, rerun the matrix, and verify the output changed.
+
+## Public Repo Probes
+
+Public repos are useful for compatibility checks, but they should be optional and pinned when used for repeatable release evidence. Upstream repos change for reasons unrelated to dev.kit.
+
+Use public probes to test broad ecosystem recognition:
+
+- package manifests and scripts
+- docs-first repos
+- workflow-only repos
+- container repos
+
+Do not assert exact output for moving public repos in the default suite.
+
+## Write Mode
+
+`tests/real-repos.sh --write` generates `.rabbit/context.yaml` in the target repo. Use it only for temp clones or repos intentionally selected for context regeneration.
diff --git a/lib/commands/repo.sh b/lib/commands/repo.sh
index 837bedb..ab05dc2 100644
--- a/lib/commands/repo.sh
+++ b/lib/commands/repo.sh
@@ -3,11 +3,7 @@
 # @description: Analyze repo structure and factors
 
 dev_kit_repo_recommended_repos_text() {
-  cat <<'EOF'
-https://github.com/udx/worker
-https://github.com/udx/reusable-workflows
-https://github.com/udx/github-rabbit-action
-EOF
+  dev_kit_repo_validation_list "recommended_repos"
 }
 
 dev_kit_repo_recommended_repos_json() {
diff --git a/lib/modules/config_catalog.sh b/lib/modules/config_catalog.sh
index 5b6775e..36984bc 100644
--- a/lib/modules/config_catalog.sh
+++ b/lib/modules/config_catalog.sh
@@ -24,6 +24,14 @@ dev_kit_context_config_path() {
   dev_kit_config_path "src/configs/context-config.yaml"
 }
 
+dev_kit_repo_validation_config_path() {
+  dev_kit_config_path "src/configs/repo-validation.yaml"
+}
+
+dev_kit_repo_validation_list() {
+  dev_kit_yaml_config_list "$(dev_kit_repo_validation_config_path)" "$1"
+}
+
 dev_kit_context_list() {
   dev_kit_yaml_config_list "$(dev_kit_context_config_path)" "$1"
 }
diff --git a/src/configs/repo-validation.yaml b/src/configs/repo-validation.yaml
new file mode 100644
index 0000000..25a58e3
--- /dev/null
+++ b/src/configs/repo-validation.yaml
@@ -0,0 +1,25 @@
+kind: repoValidationConfig
+version: udx.dev/dev.kit/v1
+description: Public repo probes and validation defaults for dev.kit release checks
+
+config:
+  recommended_repos:
+    - https://github.com/udx/worker
+    - https://github.com/udx/reusable-workflows
+    - https://github.com/udx/github-rabbit-action
+  real_repo_probe_examples:
+    - udx/reusable-workflows
+    - udx/github-rabbit-action
+  real_repo_matrix:
+    site_enc_apps:
+      repo: udx/site-enc-apps
+      purpose: many .rabbit/infra_configs environment definitions; validates manifest coverage without flooding first-read refs
+    gh_workflows:
+      repo: udx/gh-workflows
+      purpose: workflow-heavy repo; validates pipeline and reusable workflow context
+    rabbit_automation_action:
+      repo: udx/rabbit-automation-action
+      purpose: action, container, docs, and workflow mix
+    dev_kit:
+      repo: udx/dev.kit
+      purpose: self-hosting sanity check
diff --git a/tests/real-repos.sh b/tests/real-repos.sh
index bf0ee64..5265a28 100644
--- a/tests/real-repos.sh
+++ b/tests/real-repos.sh
@@ -6,22 +6,37 @@ TEST_HOME="${DEV_KIT_TEST_HOME:-$(mktemp -d "${TMPDIR:-/tmp}/dev-kit-real-repos.
 DEV_KIT_BIN_DIR="$TEST_HOME/.local/bin"
 KEEP_HOME="${DEV_KIT_TEST_KEEP_HOME:-0}"
 REAL_REPOS_CSV="${DEV_KIT_TEST_REAL_REPOS:-}"
+MODE="check"
+REPORT_DIR="${DEV_KIT_TEST_REPORT_DIR:-$TEST_HOME/reports}"
+COMMAND_SOFT_TIMEOUT="${DEV_KIT_TEST_SOFT_TIMEOUT:-15}"
+COMMAND_HARD_TIMEOUT="${DEV_KIT_TEST_HARD_TIMEOUT:-180}"
+
+# shellcheck disable=SC1091
+. "$REPO_DIR/lib/modules/output.sh"
 
 usage() {
   cat <<'EOF'
-Usage: bash tests/real-repos.sh [/abs/path/to/repo ...]
+Usage: bash tests/real-repos.sh [--check|--write] [/abs/path/to/repo ...]
 
 Runs the current dev.kit working tree against real local repos using a temporary
 plain `dev.kit` shim, without changing the global install.
 
+Default mode is --check, which is read-only for target repos.
+
 Options via environment:
   DEV_KIT_TEST_REAL_REPOS   Colon-separated repo paths when no CLI args are given
   DEV_KIT_TEST_HOME         Temp home for the test run
+  DEV_KIT_TEST_REPORT_DIR   Directory for per-repo JSON reports
+  DEV_KIT_TEST_SOFT_TIMEOUT Seconds before a slow-command notice (default: 15)
+  DEV_KIT_TEST_HARD_TIMEOUT Seconds before stopping a command (default: 180)
   DEV_KIT_TEST_KEEP_HOME    Keep temp home after exit (default: 0)
 
 Examples:
-  bash tests/real-repos.sh ~/git/udx/reusable-workflows ~/git/udx/www.peakclt.com
-  DEV_KIT_TEST_REAL_REPOS="$HOME/git/udx/reusable-workflows:$HOME/git/udx/www.peakclt.com" bash tests/real-repos.sh
+  bash tests/real-repos.sh --check ./reusable-workflows ./github-rabbit-action
+  DEV_KIT_TEST_REAL_REPOS="./reusable-workflows:./github-rabbit-action" bash tests/real-repos.sh --check
+  bash tests/real-repos.sh --write /tmp/dev-kit-probe-clone
+
+Probe examples and release matrix candidates live in src/configs/repo-validation.yaml.
 EOF
 }
 
@@ -33,30 +48,34 @@ cleanup() {
 
 trap cleanup EXIT
 
-if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
-  usage
-  exit 0
-fi
-
 repo_paths=()
-if [ "$#" -gt 0 ]; then
-  while [ "$#" -gt 0 ]; do
-    repo_paths+=("$1")
-    shift
-  done
-elif [ -n "$REAL_REPOS_CSV" ]; then
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --check) MODE="check" ;;
+    --write) MODE="write" ;;
+    -h|--help) usage; exit 0 ;;
+    --*) printf 'Unknown option: %s\n' "$1" >&2; usage >&2; exit 1 ;;
+    *) repo_paths+=("$1") ;;
+  esac
+  shift
+done
+
+if [ "${#repo_paths[@]}" -eq 0 ] && [ -n "$REAL_REPOS_CSV" ]; then
   while IFS= read -r repo_path; do
     [ -n "$repo_path" ] || continue
     repo_paths+=("$repo_path")
   done <<EOF
 $(printf '%s' "$REAL_REPOS_CSV" | tr ':' '\n')
 EOF
-else
+fi
+
+if [ "${#repo_paths[@]}" -eq 0 ]; then
   usage >&2
   exit 1
 fi
 
 mkdir -p "$DEV_KIT_BIN_DIR"
+mkdir -p "$REPORT_DIR"
 ln -sfn "$REPO_DIR/bin/dev-kit" "$DEV_KIT_BIN_DIR/dev.kit"
 
 export HOME="$TEST_HOME"
@@ -64,28 +83,96 @@ export PATH="$DEV_KIT_BIN_DIR:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
 unset DEV_KIT_HOME
 unset DEV_KIT_BIN_DIR
 
+require_jq() {
+  if ! command -v jq >/dev/null 2>&1; then
+    printf 'jq is required for real repo report summaries\n' >&2
+    exit 1
+  fi
+}
+
+report_name_for_repo() {
+  basename "$1" | tr -c 'A-Za-z0-9._-' '-'
+}
+
+print_check_summary() {
+  local repo_path="$1"
+  local home_json="$2"
+  local repo_json="$3"
+  local refs_count=""
+  local gap_count=""
+  local workflow_status=""
+  local context_status=""
+  local home_context_status=""
+
+  home_context_status="$(jq -r '.synced.context_status // "none"' "$home_json")"
+  workflow_status="$(jq -r '.workflow.jobs[] | select(.id == "repo") | .status' "$repo_json")"
+  context_status="$(jq -r '.workflow.jobs[] | select(.id == "repo") | .context_status' "$repo_json")"
+  gap_count="$(jq -r '.workflow.jobs[] | select(.id == "repo") | .gap_count' "$repo_json")"
+  refs_count="$(jq -r '[.workflow.jobs[] | select(.id == "repo") | .steps[]? | select(.id == "read_repo") | .refs[]?] | length' "$repo_json")"
+
+  printf '%s\tmode=%s\thome_context=%s\trepo_status=%s\trepo_context=%s\tgaps=%s\tread_refs=%s\n' \
+    "$repo_path" "$MODE" "$home_context_status" "$workflow_status" "$context_status" "$gap_count" "$refs_count"
+}
+
+print_write_summary() {
+  local repo_path="$1"
+  local repo_json="$2"
+  local context_yaml="$repo_path/.rabbit/context.yaml"
+  local gap_count=""
+  local manifest_count=0
+  local dep_count=0
+
+  gap_count="$(jq -r '.workflow.jobs[] | select(.id == "repo") | .gap_count' "$repo_json")"
+  if [ -f "$context_yaml" ]; then
+    manifest_count="$(awk '/^manifests:/{flag=1;next} flag && /^[^[:space:]#]/{exit} flag && /^  - path:/{count += 1} END{print count + 0}' "$context_yaml")"
+    dep_count="$(awk '/^dependencies:/{flag=1;next} /^# Manifests/{if(flag) exit} flag && /^  - repo:/{count += 1} END{print count + 0}' "$context_yaml")"
+  fi
+
+  printf '%s\tmode=%s\tcontext=%s\tgaps=%s\tmanifests=%s\tdependencies=%s\n' \
+    "$repo_path" "$MODE" "$context_yaml" "$gap_count" "$manifest_count" "$dep_count"
+}
+
+run_report_command() {
+  local label="$1"
+  local output_file="$2"
+  shift 2
+
+  local tmp_file="${output_file}.tmp"
+  rm -f "$tmp_file"
+  DEV_KIT_SPINNER_DISABLE=1 dev_kit_run_guarded \
+    "$label" \
+    "$COMMAND_SOFT_TIMEOUT" \
+    "$COMMAND_HARD_TIMEOUT" \
+    "$label is taking longer than usual; still resolving repo evidence" \
+    "$@" >"$tmp_file"
+  mv "$tmp_file" "$output_file"
+}
+
+require_jq
+printf 'report_dir: %s\n' "$REPORT_DIR"
+printf 'mode: %s\n' "$MODE"
+
 for repo_path in "${repo_paths[@]}"; do
   repo_path="$(cd "$repo_path" 2>/dev/null && pwd || true)"
   [ -n "$repo_path" ] || { printf 'repo not found\n' >&2; exit 1; }
   [ -d "$repo_path/.git" ] || { printf 'not a git repo: %s\n' "$repo_path" >&2; exit 1; }
-  run_out="$(mktemp "$TEST_HOME/dev-kit-real.XXXXXX.out")"
+  repo_report_name="$(report_name_for_repo "$repo_path")"
+  home_json="$REPORT_DIR/${repo_report_name}.home.json"
+  repo_json="$REPORT_DIR/${repo_report_name}.repo.json"
 
   printf '\n===== %s =====\n' "$repo_path"
-  (
-    cd "$repo_path"
-    if ! dev.kit >"$run_out"; then
-      cat "$run_out" >&2
-      exit 1
-    fi
-    dev.kit repo >/dev/null
-    [ -f .rabbit/context.yaml ] || { printf 'missing .rabbit/context.yaml\n' >&2; exit 1; }
-
-    printf 'context: %s\n' "$repo_path/.rabbit/context.yaml"
-    printf '\nrepo:\n'
-    sed -n '1,20p' .rabbit/context.yaml
-    printf '\ngaps:\n'
-    awk '/^gaps:/{flag=1;next} /^# Dependencies/{if(flag) exit} flag{print}' .rabbit/context.yaml || true
-    printf '\ndependencies:\n'
-    awk '/^dependencies:/{flag=1;next} /^# Manifests/{if(flag) exit} flag{print}' .rabbit/context.yaml | sed -n '1,80p'
-  )
+  if [ "$MODE" = "check" ]; then
+    (
+      cd "$repo_path"
+      run_report_command "dev.kit home check: $repo_path" "$home_json" dev.kit --json
+      run_report_command "dev.kit repo check: $repo_path" "$repo_json" dev.kit repo --json --check
+    )
+    print_check_summary "$repo_path" "$home_json" "$repo_json"
+  else
+    (
+      cd "$repo_path"
+      run_report_command "dev.kit repo write: $repo_path" "$repo_json" dev.kit repo --json
+    )
+    print_write_summary "$repo_path" "$repo_json"
+  fi
 done

From 71fd2566234b1e5948b0ade36922f33c3e89ddd0 Mon Sep 17 00:00:00 2001
From: Dmytro Smirnov <dmitry.smirnov@usabilitydynamics.com>
Date: Tue, 19 May 2026 21:21:00 +0300
Subject: [PATCH 3/7] Prepare release 0.11.0

---
 changes.md   | 3 ++-
 package.json | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/changes.md b/changes.md
index f60500d..ac30e80 100644
--- a/changes.md
+++ b/changes.md
@@ -1,9 +1,10 @@
 # Changes
 
-### unreleased
+### 0.11.0
 
 - Expose repo-centric workflow status in `dev.kit`, `dev.kit env`, and `dev.kit repo` output so environment checks, context refresh, and gap repair appear as one repo-owned loop
 - Clarify the repo contract boundary between deterministic structured parsing and interpreted prose/session intent
+- Make real-repo validation read-only by default with guarded JSON reports, and move release probe values into repo-owned config
 
 ### 0.10.0
 
diff --git a/package.json b/package.json
index 53e88ac..b0f05b2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@udx/dev-kit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Context-driven engineering toolkit for AI agents and developers",
   "license": "MIT",
   "repository": {

From 3520ad5d54ed58f0ce9f5bd4e2d064cf29f99066 Mon Sep 17 00:00:00 2001
From: Dmytro Smirnov <dmitry.smirnov@usabilitydynamics.com>
Date: Tue, 19 May 2026 21:32:03 +0300
Subject: [PATCH 4/7] Move real repo probe defaults into config

---
 .rabbit/context.yaml             | 23 +++++++++++++++++++++--
 lib/modules/config_catalog.sh    |  4 ++++
 src/configs/repo-validation.yaml |  4 ++++
 tests/real-repos.sh              | 14 +++++++++++---
 4 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml
index cc40d38..30d6ffc 100644
--- a/.rabbit/context.yaml
+++ b/.rabbit/context.yaml
@@ -5,8 +5,8 @@ version: udx.dev/dev.kit/v1
 generator:
   tool: dev.kit
   repo: https://github.com/udx/dev.kit
-  version: 0.10.0
-  generated_at: 2026-05-19T17:49:21Z
+  version: 0.11.0
+  generated_at: 2026-05-19T18:25:00Z
 
 repo:
   name: dev.kit
@@ -22,12 +22,14 @@ refs:
   - ./changes.md
   - ./Makefile
   - ./docs/references/command-surfaces.md
+  - ./docs/real-repo-validation.md
   - ./docs/references/repo-design.md
   - ./src/configs/archetypes.yaml
   - ./src/configs/audit-rules.yaml
   - ./src/configs/context-config.yaml
   - ./src/configs/detection-patterns.yaml
   - ./src/configs/detection-signals.yaml
+  - ./src/configs/repo-validation.yaml
   - ./deploy.yml
   - ./.github/workflows
   - ./docs
@@ -142,6 +144,23 @@ manifests:
       - version: udx.dev/dev.kit/v1
       - path reference: lib/modules/repo_signals.sh
       - path reference: tests/suite.sh
+  - path: src/configs/repo-validation.yaml
+    kind: repoValidationConfig
+    description: Public repo probes and validation defaults for dev.kit release checks
+    declared_as: udx.dev/dev.kit/v1
+    source_repo: udx/worker
+    used_by:
+      - docs/real-repo-validation.md
+      - lib/modules/config_catalog.sh
+      - tests/real-repos.sh
+    evidence:
+      - version: udx.dev/dev.kit/v1
+      - github reference: udx/worker
+      - github reference: udx/reusable-workflows
+      - github reference: udx/github-rabbit-action
+      - path reference: docs/real-repo-validation.md
+      - path reference: lib/modules/config_catalog.sh
+      - path reference: tests/real-repos.sh
   - path: deploy.yml
     kind: workerDeployConfig
     declared_as: udx.io/worker-v1/deploy
diff --git a/lib/modules/config_catalog.sh b/lib/modules/config_catalog.sh
index 36984bc..534ee55 100644
--- a/lib/modules/config_catalog.sh
+++ b/lib/modules/config_catalog.sh
@@ -32,6 +32,10 @@ dev_kit_repo_validation_list() {
   dev_kit_yaml_config_list "$(dev_kit_repo_validation_config_path)" "$1"
 }
 
+dev_kit_repo_validation_scalar() {
+  dev_kit_yaml_mapping_scalar "$(dev_kit_repo_validation_config_path)" "$1" "$2"
+}
+
 dev_kit_context_list() {
   dev_kit_yaml_config_list "$(dev_kit_context_config_path)" "$1"
 }
diff --git a/src/configs/repo-validation.yaml b/src/configs/repo-validation.yaml
index 25a58e3..74baa6a 100644
--- a/src/configs/repo-validation.yaml
+++ b/src/configs/repo-validation.yaml
@@ -3,6 +3,10 @@ version: udx.dev/dev.kit/v1
 description: Public repo probes and validation defaults for dev.kit release checks
 
 config:
+  real_repo_probe:
+    default_mode: check
+    soft_timeout_seconds: 15
+    hard_timeout_seconds: 180
   recommended_repos:
     - https://github.com/udx/worker
     - https://github.com/udx/reusable-workflows
diff --git a/tests/real-repos.sh b/tests/real-repos.sh
index 5265a28..ab4a86a 100644
--- a/tests/real-repos.sh
+++ b/tests/real-repos.sh
@@ -6,14 +6,22 @@ TEST_HOME="${DEV_KIT_TEST_HOME:-$(mktemp -d "${TMPDIR:-/tmp}/dev-kit-real-repos.
 DEV_KIT_BIN_DIR="$TEST_HOME/.local/bin"
 KEEP_HOME="${DEV_KIT_TEST_KEEP_HOME:-0}"
 REAL_REPOS_CSV="${DEV_KIT_TEST_REAL_REPOS:-}"
-MODE="check"
 REPORT_DIR="${DEV_KIT_TEST_REPORT_DIR:-$TEST_HOME/reports}"
-COMMAND_SOFT_TIMEOUT="${DEV_KIT_TEST_SOFT_TIMEOUT:-15}"
-COMMAND_HARD_TIMEOUT="${DEV_KIT_TEST_HARD_TIMEOUT:-180}"
 
+# shellcheck disable=SC1091
+. "$REPO_DIR/lib/modules/utils.sh"
+# shellcheck disable=SC1091
+. "$REPO_DIR/lib/modules/config_catalog.sh"
 # shellcheck disable=SC1091
 . "$REPO_DIR/lib/modules/output.sh"
 
+MODE="${DEV_KIT_TEST_MODE:-$(dev_kit_repo_validation_scalar "real_repo_probe" "default_mode")}"
+MODE="${MODE:-check}"
+COMMAND_SOFT_TIMEOUT="${DEV_KIT_TEST_SOFT_TIMEOUT:-$(dev_kit_repo_validation_scalar "real_repo_probe" "soft_timeout_seconds")}"
+COMMAND_SOFT_TIMEOUT="${COMMAND_SOFT_TIMEOUT:-15}"
+COMMAND_HARD_TIMEOUT="${DEV_KIT_TEST_HARD_TIMEOUT:-$(dev_kit_repo_validation_scalar "real_repo_probe" "hard_timeout_seconds")}"
+COMMAND_HARD_TIMEOUT="${COMMAND_HARD_TIMEOUT:-180}"
+
 usage() {
   cat <<'EOF'
 Usage: bash tests/real-repos.sh [--check|--write] [/abs/path/to/repo ...]

From 2f8a2a59ed9519d2a21c500d44c981bfdfde0e79 Mon Sep 17 00:00:00 2001
From: Dmytro Smirnov <dmitry.smirnov@usabilitydynamics.com>
Date: Tue, 19 May 2026 21:53:07 +0300
Subject: [PATCH 5/7] Tighten public repo validation probes

---
 .rabbit/context.yaml             |  3 +-
 lib/modules/repo_scaffold.sh     |  9 +----
 src/configs/repo-validation.yaml | 18 +++++-----
 tests/suite.sh                   | 56 +++++++++++++++++++++++++++++---
 4 files changed, 62 insertions(+), 24 deletions(-)

diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml
index 30d6ffc..7c53354 100644
--- a/.rabbit/context.yaml
+++ b/.rabbit/context.yaml
@@ -6,7 +6,7 @@ generator:
   tool: dev.kit
   repo: https://github.com/udx/dev.kit
   version: 0.11.0
-  generated_at: 2026-05-19T18:25:00Z
+  generated_at: 2026-05-19T18:52:32Z
 
 repo:
   name: dev.kit
@@ -148,7 +148,6 @@ manifests:
     kind: repoValidationConfig
     description: Public repo probes and validation defaults for dev.kit release checks
     declared_as: udx.dev/dev.kit/v1
-    source_repo: udx/worker
     used_by:
       - docs/real-repo-validation.md
       - lib/modules/config_catalog.sh
diff --git a/lib/modules/repo_scaffold.sh b/lib/modules/repo_scaffold.sh
index 373215f..a04c404 100644
--- a/lib/modules/repo_scaffold.sh
+++ b/lib/modules/repo_scaffold.sh
@@ -310,16 +310,9 @@ EOF
 
 dev_kit_manifest_source_repo() {
   local manifest_path="$1"
-  local comment_repo=""
   local version_value=""
   local version_repo=""
 
-  comment_repo="$(dev_kit_manifest_comment_repo_refs "$manifest_path" | head -n 1)"
-  if [ -n "$comment_repo" ]; then
-    printf '%s\n' "$comment_repo"
-    return 0
-  fi
-
   version_value="$(dev_kit_manifest_version_value "$manifest_path")"
   if [ -n "$version_value" ]; then
     version_repo="$(dev_kit_dep_version_repo_slug "$version_value" 2>/dev/null || true)"
@@ -1069,7 +1062,7 @@ EOF
     if [ -n "$_manifests_yaml" ]; then
       dev_kit_context_section_comment_block "manifests"
       printf 'manifests:\n'
-      printf '%b\n' "$_manifests_yaml"
+      printf '%b' "$_manifests_yaml"
     fi
 
   } > "$context_path"
diff --git a/src/configs/repo-validation.yaml b/src/configs/repo-validation.yaml
index 74baa6a..b7dcc53 100644
--- a/src/configs/repo-validation.yaml
+++ b/src/configs/repo-validation.yaml
@@ -15,15 +15,15 @@ config:
     - udx/reusable-workflows
     - udx/github-rabbit-action
   real_repo_matrix:
-    site_enc_apps:
-      repo: udx/site-enc-apps
-      purpose: many .rabbit/infra_configs environment definitions; validates manifest coverage without flooding first-read refs
-    gh_workflows:
-      repo: udx/gh-workflows
-      purpose: workflow-heavy repo; validates pipeline and reusable workflow context
-    rabbit_automation_action:
-      repo: udx/rabbit-automation-action
-      purpose: action, container, docs, and workflow mix
+    worker:
+      repo: udx/worker
+      purpose: worker manifest and deployment contract sanity check
+    reusable_workflows:
+      repo: udx/reusable-workflows
+      purpose: reusable workflow contracts and docs-first workflow context
+    github_rabbit_action:
+      repo: udx/github-rabbit-action
+      purpose: action, docs, and workflow context mix
     dev_kit:
       repo: udx/dev.kit
       purpose: self-hosting sanity check
diff --git a/tests/suite.sh b/tests/suite.sh
index d4af9e4..8a15203 100644
--- a/tests/suite.sh
+++ b/tests/suite.sh
@@ -16,7 +16,7 @@ DOCKER_ACTION_REPO="$TEST_HOME/docker-action-repo"
 EMPTY_REPO="$TEST_HOME/empty-repo"
 IGNORED_ACTION_REPO="$TEST_HOME/ignored-action-repo"
 WORKFLOW_CONTRACT_REPO="$TEST_HOME/workflow-contract-repo"
-AVAILABLE_TEST_GROUPS="core"
+AVAILABLE_TEST_GROUPS="core repo-contract"
 TEST_ONLY="${DEV_KIT_TEST_ONLY:-}"
 
 cleanup() {
@@ -26,10 +26,11 @@ trap cleanup EXIT
 
 usage() {
   cat <<'EOF'
-Usage: bash tests/suite.sh [--only core] [--list]
+Usage: bash tests/suite.sh [--only core|repo-contract] [--list]
 
 Groups:
-  core        command flow, output, and context generation checks
+  core           command flow, output, and context generation checks
+  repo-contract  focused generated-context contract regressions
 EOF
 }
 
@@ -51,6 +52,11 @@ should_run() {
   return 1
 }
 
+should_run_explicit() {
+  [ -n "$TEST_ONLY" ] || return 1
+  should_run "$1"
+}
+
 replace_in_file() {
   local file_path="$1"
   local before="$2"
@@ -118,6 +124,37 @@ done <<EOF
 $(find "$REPO_DIR/lib/commands" -maxdepth 1 -type f -name '*.sh' | sort)
 EOF
 
+if should_run_explicit "repo-contract"; then
+  self_repo_json="$(cd "$REPO_DIR" && dev.kit repo --json)"
+  self_context_yaml="$(cat "$REPO_DIR/.rabbit/context.yaml")"
+  repo_validation_manifest="$(
+    awk '
+      /^  - path: src\/configs\/repo-validation.yaml$/ { flag = 1 }
+      flag && /^  - path:/ && $0 !~ /src\/configs\/repo-validation.yaml$/ { exit }
+      flag { print }
+    ' "$REPO_DIR/.rabbit/context.yaml"
+  )"
+
+  assert_not_contains "$self_repo_json" "\"repo\": \"udx/dev.kit\"" "repo contract: omits self dependency contracts"
+  assert_not_contains "$self_context_yaml" "source_repo: udx/dev.kit" "repo contract: omits self source repo provenance"
+  assert_not_contains "$repo_validation_manifest" "source_repo: udx/worker" "repo contract: does not treat probe repo values as manifest source repo"
+  assert_not_contains "$self_context_yaml" ".rabbit/dev.kit/" "repo contract: excludes generated rabbit evidence"
+
+  cp -R "$DOCKER_REPO" "$DOCKER_ACTION_REPO"
+  rm -f "$DOCKER_ACTION_REPO/.rabbit/context.yaml"
+
+  docker_repo_json="$(cd "$DOCKER_ACTION_REPO" && dev.kit repo --json)"
+  assert_contains "$docker_repo_json" "\"context\":" "repo contract: docker repo reports context path"
+
+  docker_context_yaml="${DOCKER_ACTION_REPO}/.rabbit/context.yaml"
+  assert_contains "$(cat "$docker_context_yaml")" "path: deploy.yml" "repo contract: includes deploy manifest"
+  assert_contains "$(cat "$docker_context_yaml")" "path: .rabbit/deploy.yml" "repo contract: includes hidden custom manifest"
+  assert_contains "$(cat "$docker_context_yaml")" "path: .rabbit/infra_configs/staging/k8s-configmap.yaml" "repo contract: inventories nested rabbit manifests"
+  docker_context_refs="$(awk '/^refs:/{flag=1;next} /^# Commands/{if(flag) exit} flag{print}' "$docker_context_yaml")"
+  assert_not_contains "$docker_context_refs" ".rabbit/infra_configs/staging/k8s-configmap.yaml" "repo contract: excludes nested rabbit manifests from read-first refs"
+  assert_contains "$(cat "$docker_context_yaml")" "source_repo: udx/worker" "repo contract: traces manifest owner from version"
+fi
+
 if should_run "core"; then
   guard_soft_output="$(
     DEV_KIT_SPINNER_DISABLE=1 \
@@ -284,9 +321,18 @@ if should_run "core"; then
   assert_contains "$repo_write_failure_output" "boom" "repo text: preserves underlying write error"
 
   self_repo_json="$(cd "$REPO_DIR" && dev.kit repo --json)"
+  self_context_yaml="$(cat "$REPO_DIR/.rabbit/context.yaml")"
+  repo_validation_manifest="$(
+    awk '
+      /^  - path: src\/configs\/repo-validation.yaml$/ { flag = 1 }
+      flag && /^  - path:/ && $0 !~ /src\/configs\/repo-validation.yaml$/ { exit }
+      flag { print }
+    ' "$REPO_DIR/.rabbit/context.yaml"
+  )"
   assert_not_contains "$self_repo_json" "\"repo\": \"udx/dev.kit\"" "repo: omits self dependency contracts"
-  assert_not_contains "$(cat "$REPO_DIR/.rabbit/context.yaml")" "source_repo: udx/dev.kit" "repo: omits self source repo provenance"
-  assert_not_contains "$(cat "$REPO_DIR/.rabbit/context.yaml")" ".rabbit/dev.kit/" "repo: excludes generated rabbit evidence"
+  assert_not_contains "$self_context_yaml" "source_repo: udx/dev.kit" "repo: omits self source repo provenance"
+  assert_not_contains "$repo_validation_manifest" "source_repo: udx/worker" "repo: does not treat probe repo values as manifest source repo"
+  assert_not_contains "$self_context_yaml" ".rabbit/dev.kit/" "repo: excludes generated rabbit evidence"
 
   cp -R "$SIMPLE_REPO" "$SIMPLE_ACTION_REPO"
   rm -rf "$SIMPLE_ACTION_REPO/.dev-kit"

From 136bd757079ac6c4db2c1c1586a387706bc00dc7 Mon Sep 17 00:00:00 2001
From: Dmytro Smirnov <dmitry.smirnov@usabilitydynamics.com>
Date: Tue, 19 May 2026 21:54:35 +0300
Subject: [PATCH 6/7] Handle Copilot review feedback

---
 lib/modules/repo_workflows.sh | 21 ++++++++++++++++-----
 tests/real-repos.sh           |  8 +++++++-
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/lib/modules/repo_workflows.sh b/lib/modules/repo_workflows.sh
index 55babe8..6c41ecb 100644
--- a/lib/modules/repo_workflows.sh
+++ b/lib/modules/repo_workflows.sh
@@ -28,12 +28,23 @@ dev_kit_repo_entrypoint_source() {
 
 dev_kit_repo_gap_count() {
   local repo_dir="$1"
+  local factor=""
+  local status=""
+  local gap_count=0
+
+  while IFS= read -r factor; do
+    [ -n "$factor" ] || continue
+    status="$(dev_kit_repo_factor_status "$repo_dir" "$factor")"
+    case "$status" in
+      missing|partial)
+        gap_count=$((gap_count + 1))
+        ;;
+    esac
+  done <<EOF
+$(dev_kit_repo_factor_ids)
+EOF
 
-  dev_kit_repo_factor_summary_json "$repo_dir" | jq -r '
-    to_entries
-    | map(select(.value.status == "missing" or .value.status == "partial"))
-    | length
-  ' 2>/dev/null || printf '0'
+  printf '%s' "$gap_count"
 }
 
 dev_kit_repo_workflow_status() {
diff --git a/tests/real-repos.sh b/tests/real-repos.sh
index ab4a86a..5ec51c8 100644
--- a/tests/real-repos.sh
+++ b/tests/real-repos.sh
@@ -99,7 +99,13 @@ require_jq() {
 }
 
 report_name_for_repo() {
-  basename "$1" | tr -c 'A-Za-z0-9._-' '-'
+  local repo_path="$1"
+  local safe_path=""
+  local path_hash=""
+
+  safe_path="$(printf '%s' "$repo_path" | tr -c 'A-Za-z0-9._-' '-')"
+  path_hash="$(printf '%s' "$repo_path" | cksum | awk '{ print $1 }')"
+  printf '%s-%s' "$safe_path" "$path_hash"
 }
 
 print_check_summary() {

From e1a3f46de0a57034f9f5931deb4fa058bb09dfef Mon Sep 17 00:00:00 2001
From: Dmytro Smirnov <dmitry.smirnov@usabilitydynamics.com>
Date: Tue, 19 May 2026 22:03:26 +0300
Subject: [PATCH 7/7] Address follow-up Copilot feedback

---
 lib/modules/repo_factors.sh | 2 +-
 tests/suite.sh              | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/modules/repo_factors.sh b/lib/modules/repo_factors.sh
index 1f7523b..47dac43 100644
--- a/lib/modules/repo_factors.sh
+++ b/lib/modules/repo_factors.sh
@@ -644,7 +644,7 @@ dev_kit_repo_prefers_internal_references() {
 
   repo_name="$(dev_kit_repo_name "$repo_dir" 2>/dev/null || true)"
   repo_slug="$(dev_kit_repo_current_slug "$repo_dir" "$repo_name" 2>/dev/null || true)"
-  real_repo_dir="$(cd "$repo_dir" 2>/dev/null && pwd)"
+  real_repo_dir="$(cd "$repo_dir" 2>/dev/null && pwd || true)"
 
   [ "$real_repo_dir" = "$REPO_DIR" ] || { [ "$repo_slug" = "udx/dev.kit" ] && [ "$repo_name" = "dev.kit" ]; }
 }
diff --git a/tests/suite.sh b/tests/suite.sh
index 8a15203..affd553 100644
--- a/tests/suite.sh
+++ b/tests/suite.sh
@@ -26,7 +26,7 @@ trap cleanup EXIT
 
 usage() {
   cat <<'EOF'
-Usage: bash tests/suite.sh [--only core|repo-contract] [--list]
+Usage: bash tests/suite.sh [--only core|repo-contract|core,repo-contract] [--list]
 
 Groups:
   core           command flow, output, and context generation checks