From dae14dd5cced7d59fdff32307b5f3496239a1afd Mon Sep 17 00:00:00 2001 From: Dmytro Smirnov Date: Fri, 26 Jun 2026 13:43:45 +0300 Subject: [PATCH 1/3] Prepare dev.kit 0.14.0 user experience release --- .rabbit/context.yaml | 15 +++------------ changes.md | 7 +++++++ docs/real-repo-validation.md | 16 ++++++++++++++++ docs/references/command-surfaces.md | 6 ++++++ lib/modules/repo_signals.sh | 3 +++ package-lock.json | 4 ++-- package.json | 2 +- src/configs/repo-validation.yaml | 3 +++ tests/suite.sh | 27 +++++++++++++++++++++++++++ 9 files changed, 68 insertions(+), 15 deletions(-) diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml index f9791e3..34ed3f9 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.13.0 - generated_at: 2026-05-27T18:39:54Z + version: 0.14.0 + generated_at: 2026-06-26T10:41:30Z sources: homepage: https://udx.dev/kit repository: https://github.com/udx/dev.kit @@ -26,10 +26,7 @@ refs: - ./README.md - ./changes.md - ./Makefile - - ./docs/references/command-surfaces.md - ./docs/real-repo-validation.md - - ./docs/references/output-schemas.md - - ./docs/references/repo-design.md - ./src/configs/archetypes.yaml - ./src/configs/audit-rules.yaml - ./src/configs/context-config.yaml @@ -49,12 +46,6 @@ commands: verify: run: make test source: Makefile - build: - run: make build - source: docs/references/command-surfaces.md - run: - run: make run - source: docs/references/command-surfaces.md # Dependencies — Meaningful dependency-repo contracts such as reusable workflows, images, or versioned manifests this repo relies on. # Note: Capture execution-shaping behavior defined outside the current checkout. @@ -65,7 +56,7 @@ dependencies: - repo: udx/reusable-workflows kind: reusable workflow resolved: true - archetype: workflow-repo + archetype: manifest-repo used_by: - .github/workflows/context7-ops.yml - .github/workflows/npm-release-ops.yml diff --git a/changes.md b/changes.md index eae0b9f..ca5bc06 100644 --- a/changes.md +++ b/changes.md @@ -1,5 +1,12 @@ # Changes +### 0.14.0 + +- Ignore command examples from `docs/references/` when generating repo command contracts, preventing reference docs from creating misleading `build` or `run` commands. +- Add regression coverage for reference-only command examples so generated context stays tied to runnable repo-owned surfaces. +- Add release verification guidance that distinguishes GitHub release, npm registry, tarball, and npmjs.com UI evidence. +- Add `udx/rabbit-automation-action` to the real-repo validation matrix as a manifest-heavy config contract probe. + ### 0.13.0 - Allow repo-owned manifests to satisfy config contract coverage when they declare explicit config contract metadata or runtime config sections, avoiding forced `.env.example` files for repos with custom manifest contracts. diff --git a/docs/real-repo-validation.md b/docs/real-repo-validation.md index 0cc57b6..afbc44a 100644 --- a/docs/real-repo-validation.md +++ b/docs/real-repo-validation.md @@ -29,6 +29,10 @@ The summary should be used to compare: 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. +For config and manifest contract releases, include `udx/rabbit-automation-action` +when it is available locally. It is a useful probe because it relies on +repo-owned manifests instead of generic `.env.example` files. + ## 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. @@ -45,3 +49,15 @@ 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. + +## Release Verification + +Before reporting a release as published, verify each source precisely: + +- GitHub PR is merged into the release branch. +- GitHub release and tag exist for the intended version. +- Release workflow completed successfully. +- npm registry API reports the intended dist-tag and version. +- npm tarball URL returns a successful response. +- npmjs.com package page is treated as optional UI evidence because it can lag + behind registry metadata. diff --git a/docs/references/command-surfaces.md b/docs/references/command-surfaces.md index 85286c1..89c9ec2 100644 --- a/docs/references/command-surfaces.md +++ b/docs/references/command-surfaces.md @@ -30,6 +30,12 @@ Workflow and operational contracts are often packaged in: Docs should explain execution behavior, tradeoffs, and decision points. The runnable contract should stay in scripts and manifests. +Repo-specific docs such as `README.md`, `changes.md`, or focused operational +docs can still declare commands when a repo intentionally keeps its command +surface in prose. Reusable reference docs under `docs/references/` are examples +and interpretation guidance; they should not become generated command contracts +unless a runnable repo surface also declares the same command. + ## Build and deploy may be separate Some repos intentionally separate: diff --git a/lib/modules/repo_signals.sh b/lib/modules/repo_signals.sh index a90fe02..88c4aba 100644 --- a/lib/modules/repo_signals.sh +++ b/lib/modules/repo_signals.sh @@ -278,6 +278,9 @@ dev_kit_repo_command_doc_files() { case "$ref" in AGENTS.md|CLAUDE.md|.rabbit/*) continue ;; esac + case "$ref" in + docs/references/*) continue ;; + esac case "$ref" in *.md|*.markdown) printf '%s/%s\n' "$repo_dir" "$ref" ;; esac diff --git a/package-lock.json b/package-lock.json index 8e514b1..dd09825 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@udx/dev-kit", - "version": "0.13.0", + "version": "0.14.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@udx/dev-kit", - "version": "0.13.0", + "version": "0.14.0", "license": "MIT", "bin": { "dev-kit": "bin/dev-kit", diff --git a/package.json b/package.json index a53e511..fb38c8f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@udx/dev-kit", - "version": "0.13.0", + "version": "0.14.0", "description": "Context-driven engineering toolkit for AI agents and developers", "license": "MIT", "repository": { diff --git a/src/configs/repo-validation.yaml b/src/configs/repo-validation.yaml index b7dcc53..299c287 100644 --- a/src/configs/repo-validation.yaml +++ b/src/configs/repo-validation.yaml @@ -24,6 +24,9 @@ config: github_rabbit_action: repo: udx/github-rabbit-action purpose: action, docs, and workflow context mix + rabbit_automation_action: + repo: udx/rabbit-automation-action + purpose: manifest-heavy repo and config contract sanity check dev_kit: repo: udx/dev.kit purpose: self-hosting sanity check diff --git a/tests/suite.sh b/tests/suite.sh index 571bfc8..2bfa1b0 100644 --- a/tests/suite.sh +++ b/tests/suite.sh @@ -16,6 +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" +REFERENCE_DOC_COMMAND_REPO="$TEST_HOME/reference-doc-command-repo" AVAILABLE_TEST_GROUPS="core repo-contract" TEST_ONLY="${DEV_KIT_TEST_ONLY:-}" @@ -163,6 +164,8 @@ if should_run_explicit "repo-contract"; then 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" assert_not_contains "$self_context_yaml" ".rabbit/context.yaml.tmp." "repo contract: excludes context temp files from evidence" + assert_not_contains "$self_context_yaml" "run: make build" "repo contract: ignores reference-doc build command examples" + assert_not_contains "$self_context_yaml" "run: make run" "repo contract: ignores reference-doc run command examples" cp -R "$DOCKER_REPO" "$DOCKER_ACTION_REPO" rm -f "$DOCKER_ACTION_REPO/.rabbit/context.yaml" @@ -360,6 +363,8 @@ if should_run "core"; then 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" assert_not_contains "$self_context_yaml" ".rabbit/context.yaml.tmp." "repo: excludes context temp files from evidence" + assert_not_contains "$self_context_yaml" "run: make build" "repo: ignores reference-doc build command examples" + assert_not_contains "$self_context_yaml" "run: make run" "repo: ignores reference-doc run command examples" cp -R "$SIMPLE_REPO" "$SIMPLE_ACTION_REPO" rm -rf "$SIMPLE_ACTION_REPO/.dev-kit" @@ -456,6 +461,28 @@ EOF assert_not_contains "$(cat "$workflow_context_yaml")" "path: .github/workflows/ci.yml" "workflow repo: excludes marketplace-only workflow manifest" assert_contains "$(cat "$workflow_context_yaml")" "repo: udx/reusable-workflows" "workflow repo: traces reusable workflow dependency" + mkdir -p "$REFERENCE_DOC_COMMAND_REPO/docs/references" + git -C "$REFERENCE_DOC_COMMAND_REPO" init >/dev/null 2>&1 + cat > "$REFERENCE_DOC_COMMAND_REPO/README.md" <<'EOF' +# Reference Doc Command Repo + +This repo has no build or run command. +EOF + cat > "$REFERENCE_DOC_COMMAND_REPO/docs/references/command-surfaces.md" <<'EOF' +# Command Surfaces + +Examples only: + +- `make build` +- `make run` +EOF + + reference_doc_json="$(cd "$REFERENCE_DOC_COMMAND_REPO" && dev.kit repo --json)" + assert_contains "$reference_doc_json" "\"context\":" "reference docs repo: reports context path" + reference_doc_context_yaml="${REFERENCE_DOC_COMMAND_REPO}/.rabbit/context.yaml" + assert_not_contains "$(cat "$reference_doc_context_yaml")" "run: make build" "reference docs repo: ignores reference-only build example" + assert_not_contains "$(cat "$reference_doc_context_yaml")" "run: make run" "reference docs repo: ignores reference-only run example" + mkdir -p "$EMPTY_REPO" git -C "$EMPTY_REPO" init >/dev/null 2>&1 From 33a53bbd5318f7c413e9c23b4651864b6f0b627d Mon Sep 17 00:00:00 2001 From: Dmytro Smirnov Date: Sun, 5 Jul 2026 21:11:15 +0300 Subject: [PATCH 2/3] Clarify stale context version mismatch --- .rabbit/context.yaml | 2 +- bin/dev-kit | 2 +- changes.md | 1 + tests/suite.sh | 15 +++++++++++++++ 4 files changed, 18 insertions(+), 2 deletions(-) diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml index 34ed3f9..524fce9 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.14.0 - generated_at: 2026-06-26T10:41:30Z + generated_at: 2026-07-05T18:10:03Z sources: homepage: https://udx.dev/kit repository: https://github.com/udx/dev.kit diff --git a/bin/dev-kit b/bin/dev-kit index b1711de..770be99 100755 --- a/bin/dev-kit +++ b/bin/dev-kit @@ -283,7 +283,7 @@ dev_kit_home_context_reason() { fi if [ -n "$(dev_kit_tool_version)" ] && [ "$generator_version" != "$(dev_kit_tool_version)" ]; then - printf '%s' "context was generated by a different dev.kit version" + printf 'context was generated by dev.kit %s; current dev.kit is %s' "$generator_version" "$(dev_kit_tool_version)" return 0 fi diff --git a/changes.md b/changes.md index ca5bc06..7f137fc 100644 --- a/changes.md +++ b/changes.md @@ -6,6 +6,7 @@ - Add regression coverage for reference-only command examples so generated context stays tied to runnable repo-owned surfaces. - Add release verification guidance that distinguishes GitHub release, npm registry, tarball, and npmjs.com UI evidence. - Add `udx/rabbit-automation-action` to the real-repo validation matrix as a manifest-heavy config contract probe. +- Clarify stale-context output when generated context came from a different `dev.kit` version by showing both the generator and current versions. ### 0.13.0 diff --git a/tests/suite.sh b/tests/suite.sh index 2bfa1b0..98ab92e 100644 --- a/tests/suite.sh +++ b/tests/suite.sh @@ -128,6 +128,7 @@ ln -sf "$REPO_DIR/bin/dev-kit" "$DEV_KIT_BIN_DIR/dev.kit" export PATH="$DEV_KIT_BIN_DIR:$PATH" assert_contains "$(command -v dev.kit)" "$DEV_KIT_BIN_DIR/dev.kit" "suite: uses local dev.kit shim" assert_contains "$(dev.kit --version)" "$(awk -F'"' '/"version"/{print $4; exit}' "$REPO_DIR/package.json")" "suite: uses checkout dev.kit version" +DEV_KIT_VERSION="$(awk -F'"' '/"version"/{print $4; exit}' "$REPO_DIR/package.json")" # shellcheck disable=SC1090 . "$DEV_KIT_HOME/bin/env/dev-kit.sh" @@ -297,6 +298,20 @@ if should_run "core"; then 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 \ + "$HOME_ACTION_REPO/.rabbit/context.yaml" \ + " version: ${DEV_KIT_VERSION}" \ + " version: 0.0.0-test" + + stale_version_home_json="$(cd "$HOME_ACTION_REPO" && dev.kit --json)" + assert_contains "$stale_version_home_json" "\"context_status\": \"stale\"" "home: marks version-mismatched context as stale" + assert_contains "$stale_version_home_json" "\"context_reason\": \"context was generated by dev.kit 0.0.0-test; current dev.kit is ${DEV_KIT_VERSION}\"" "home: reports stale generator and current versions" + + replace_in_file \ + "$HOME_ACTION_REPO/.rabbit/context.yaml" \ + " version: 0.0.0-test" \ + " version: ${DEV_KIT_VERSION}" + replace_in_file \ "$HOME_ACTION_REPO/.rabbit/context.yaml" \ "No repo-owned configuration contract was found in docs, manifests, or checked-in example files." \ From 6c6ee2ce8c8ec67f8f3eed9a0f07269f8312dab5 Mon Sep 17 00:00:00 2001 From: Dmytro Smirnov Date: Sun, 5 Jul 2026 21:19:28 +0300 Subject: [PATCH 3/3] Remove private repo validation reference --- .rabbit/context.yaml | 2 +- changes.md | 2 +- docs/real-repo-validation.md | 6 +++--- src/configs/repo-validation.yaml | 3 --- 4 files changed, 5 insertions(+), 8 deletions(-) diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml index 524fce9..3f9f59e 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.14.0 - generated_at: 2026-07-05T18:10:03Z + generated_at: 2026-07-05T18:19:05Z sources: homepage: https://udx.dev/kit repository: https://github.com/udx/dev.kit diff --git a/changes.md b/changes.md index 7f137fc..679028d 100644 --- a/changes.md +++ b/changes.md @@ -5,7 +5,7 @@ - Ignore command examples from `docs/references/` when generating repo command contracts, preventing reference docs from creating misleading `build` or `run` commands. - Add regression coverage for reference-only command examples so generated context stays tied to runnable repo-owned surfaces. - Add release verification guidance that distinguishes GitHub release, npm registry, tarball, and npmjs.com UI evidence. -- Add `udx/rabbit-automation-action` to the real-repo validation matrix as a manifest-heavy config contract probe. +- Clarify manifest-heavy config contract validation guidance for optional local repo probes. - Clarify stale-context output when generated context came from a different `dev.kit` version by showing both the generator and current versions. ### 0.13.0 diff --git a/docs/real-repo-validation.md b/docs/real-repo-validation.md index afbc44a..e7ceb57 100644 --- a/docs/real-repo-validation.md +++ b/docs/real-repo-validation.md @@ -29,9 +29,9 @@ The summary should be used to compare: 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. -For config and manifest contract releases, include `udx/rabbit-automation-action` -when it is available locally. It is a useful probe because it relies on -repo-owned manifests instead of generic `.env.example` files. +For config and manifest contract releases, include at least one available +manifest-heavy local repo probe. It should rely on repo-owned manifests instead +of generic `.env.example` files. ## Public Repo Probes diff --git a/src/configs/repo-validation.yaml b/src/configs/repo-validation.yaml index 299c287..b7dcc53 100644 --- a/src/configs/repo-validation.yaml +++ b/src/configs/repo-validation.yaml @@ -24,9 +24,6 @@ config: github_rabbit_action: repo: udx/github-rabbit-action purpose: action, docs, and workflow context mix - rabbit_automation_action: - repo: udx/rabbit-automation-action - purpose: manifest-heavy repo and config contract sanity check dev_kit: repo: udx/dev.kit purpose: self-hosting sanity check