Release 0.11.0 repo workflow contract

.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-13T00:55:54Z
+  version: 0.11.0
+  generated_at: 2026-05-19T18:52:32Z
 
 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
@@ -70,14 +72,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
 
@@ -140,6 +144,22 @@ 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
+    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
@@ -163,4 +183,3 @@ manifests:
       - path reference: src/configs/context-config.yaml
       - path reference: src/configs/detection-signals.yaml
       - path reference: tests/suite.sh
-

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
 ```

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"

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"

changes.md

@@ -1,6 +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
 

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

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.

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