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