Merge pull request #23 from udx/fix/release-0.10.0

Author: fqjony

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.gitignore

@@ -9,6 +9,7 @@
 .codex/
 .copilot/
 .devin/
+copilot-session-*.md
 tests/fixtures/tmp-bin/
 
 # Generated context (regenerated by test suite at runtime)

.rabbit/context.yaml

@@ -2,23 +2,34 @@
 # Run `dev.kit repo` to refresh.
 kind: repoContext
 version: udx.dev/dev.kit/v1
-generated: 2026-05-04
+generator:
+  tool: dev.kit
+  repo: https://github.com/udx/dev.kit
+  version: 0.10.0
+  generated_at: 2026-05-13T00:55:54Z
 
 repo:
   name: dev.kit
-  archetype: package-cli
+  archetype: manifest-repo
 
 # Refs — Direct-read files and paths that define the repo contract.
-# Note: Include only files or directories an agent should read before code exploration.
+# Note: Include only files or directories a repo consumer should read before code exploration.
 # Note: Prefer README, focused docs, workflows, manifests, and explicit operational files.
 # Note: Exclude broad implementation directories unless they are the contract themselves.
 
 refs:
   - ./README.md
   - ./changes.md
+  - ./Makefile
+  - ./docs/references/command-surfaces.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
   - ./deploy.yml
   - ./.github/workflows
-  - ./Makefile
   - ./docs
 
 # Commands — Canonical repo entrypoints detected from strong repo signals.
@@ -30,6 +41,12 @@ 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
 
 # Gaps — Factors that are missing or only partially supported by current repo signals.
 # Note: Base the result on explicit factor rules, not free-form judgment.
@@ -39,55 +56,47 @@ commands:
 gaps:
   - factor: config
     status: partial
-    message: Config signals exist, but no explicit env contract file was detected. Add .env.example, .env.sample, or .env.template when runtime configuration is required.
+    message: Found config-bearing repo assets in deploy.yml, but no canonical checked-in config contract is declared yet.
+    repair_target: deploy.yml or .env.example
+    reference: docs/references/config-contract-surfaces.md
     evidence:
       - runtime config: deploy.yml
 
-# Dependencies — External repos, actions, images, or versioned manifests this repo relies on.
-# Note: Capture behavior defined outside the current checkout.
+# 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.
+# Note: Avoid promoting standard package inventory or ordinary GitHub action refs into top-level context.
 # Note: Normalize same-org versioned refs into repo slugs when possible.
-# Note: Keep where-used tracing so the dependency can be followed back to its source.
 
 dependencies:
   - repo: udx/reusable-workflows
     kind: reusable workflow
-    resolved: true
-    archetype: workflow-repo
-    description: Reusable GitHub Actions workflow templates for CI/CD
+    resolved: false
     used_by:
       - .github/workflows/context7-ops.yml
       - .github/workflows/npm-release-ops.yml
-  - repo: udx/dev.kit
-    kind: manifest contract (v1)
-    resolved: true
-    declared_as: udx.dev/dev.kit/v1
-    archetype: package-cli
-    used_by:
-      - src/configs/archetypes.yaml
-      - src/configs/audit-rules.yaml
-      - src/configs/context-config.yaml
-      - src/configs/detection-patterns.yaml
-      - src/configs/detection-signals.yaml
   - repo: udx/worker
     kind: manifest contract (deploy)
-    resolved: true
+    resolved: false
     declared_as: udx.io/worker-v1/deploy
-    archetype: runtime-image
-    description: UDX Worker Docker image
     used_by:
       - deploy.yml
 
-# Manifests — YAML files that define detection rules, workflows, evaluation, deploy, or runtime behavior.
-# Note: Include manifests that materially shape repo behavior or agent understanding.
+# Manifests — YAML files that define repo-specific workflow, deploy, or contract behavior.
+# Note: Include custom config/manifests that materially shape repo behavior or contract understanding.
+# Note: Do not include workflow YAML only because it lives under .github/workflows.
+# Note: Promote workflow files only when they declare reusable workflow refs or other repo-specific execution contracts.
 # Note: Prefer structured kind and description metadata from the manifest itself.
-# Note: Include eval and workflow manifests, not only deploy manifests.
+# Note: Include hidden or nested contract dirs when they contain repo-owned manifests with meaningful metadata.
 
 manifests:
+  - path: .github/workflows/context7-ops.yml
+    kind: githubWorkflow
+  - path: .github/workflows/npm-release-ops.yml
+    kind: githubWorkflow
   - path: src/configs/archetypes.yaml
     kind: repoArchetypes
-    description: Repo archetype definitions and matching rules
+    description: Minimal repo-level archetype definitions
     declared_as: udx.dev/dev.kit/v1
-    source_repo: udx/dev.kit
     used_by:
       - lib/modules/config_catalog.sh
     evidence:
@@ -97,17 +106,15 @@ manifests:
     kind: auditRules
     description: Gap messages and guidance for missing or partial repo factors
     declared_as: udx.dev/dev.kit/v1
-    source_repo: udx/dev.kit
     used_by:
       - lib/modules/config_catalog.sh
     evidence:
       - version: udx.dev/dev.kit/v1
       - path reference: lib/modules/config_catalog.sh
   - path: src/configs/context-config.yaml
     kind: contextConfig
-    description: Repo root markers, direct-read refs, and documentation priority order
+    description: Minimal repo root markers, direct-read refs, and documentation priority order
     declared_as: udx.dev/dev.kit/v1
-    source_repo: udx/dev.kit
     used_by:
       - lib/modules/config_catalog.sh
     evidence:
@@ -117,7 +124,6 @@ manifests:
     kind: detectionPatterns
     description: Regex patterns for command, workflow, and env detection
     declared_as: udx.dev/dev.kit/v1
-    source_repo: udx/dev.kit
     used_by:
       - lib/modules/repo_signals.sh
     evidence:
@@ -127,51 +133,34 @@ manifests:
     kind: detectionSignals
     description: File, directory, and glob signals for factor and dependency detection
     declared_as: udx.dev/dev.kit/v1
-    source_repo: udx/dev.kit
     used_by:
-      - tests/suite.sh
       - lib/modules/repo_signals.sh
+      - tests/suite.sh
     evidence:
       - version: udx.dev/dev.kit/v1
-      - path reference: tests/suite.sh
       - path reference: lib/modules/repo_signals.sh
-  - path: .github/workflows/context7-ops.yml
-    kind: githubWorkflow
-  - path: .github/workflows/npm-release-ops.yml
-    kind: githubWorkflow
-    used_by:
-      - .claude/settings.local.json
-    evidence:
-      - path reference: .claude/settings.local.json
+      - path reference: tests/suite.sh
   - path: deploy.yml
     kind: workerDeployConfig
     declared_as: udx.io/worker-v1/deploy
     source_repo: udx/worker
     used_by:
       - Makefile
-      - tests/suite.sh
-      - tests/fixtures/docker-repo/.dev-kit/manifest.json
-      - tests/fixtures/docker-repo/.rabbit/context.yaml
-      - .claude/settings.local.json
-      - lib/modules/repo_scaffold.sh
-      - src/configs/detection-signals.yaml
+      - docs/references/command-surfaces.md
+      - docs/references/config-contract-surfaces.md
+      - docs/repo-contract-boundary.md
+      - lib/modules/repo_factors.sh
       - src/configs/context-config.yaml
+      - src/configs/detection-signals.yaml
+      - tests/suite.sh
     evidence:
       - version: udx.io/worker-v1/deploy
       - path reference: Makefile
-      - path reference: tests/suite.sh
-      - path reference: tests/fixtures/docker-repo/.dev-kit/manifest.json
-      - path reference: tests/fixtures/docker-repo/.rabbit/context.yaml
-      - path reference: .claude/settings.local.json
-      - path reference: lib/modules/repo_scaffold.sh
-      - path reference: src/configs/detection-signals.yaml
+      - path reference: docs/references/command-surfaces.md
+      - path reference: docs/references/config-contract-surfaces.md
+      - path reference: docs/repo-contract-boundary.md
+      - path reference: lib/modules/repo_factors.sh
       - path reference: src/configs/context-config.yaml
-  - path: evals/promptfooconfig.yaml
-    description: "dev.kit context impact — with vs without AGENTS.md"
-    used_by:
-      - Makefile
-      - src/configs/detection-signals.yaml
-    evidence:
-      - path reference: Makefile
       - path reference: src/configs/detection-signals.yaml
+      - path reference: tests/suite.sh
 

AGENTS.md

@@ -1,38 +1,33 @@
 # AGENTS.md
 
-_Auto-generated by `dev.kit agent`. Source: `.rabbit/context.yaml`._
+_Normalized repo-owned guidance for agents. Keep it aligned with `docs/references/agent-dev-workflow.md` and `.rabbit/context.yaml`._
 
 ## Repo: dev.kit
 
-- archetype: package-cli
 - context: ./.rabbit/context.yaml
+- workflow_ref: ./docs/references/agent-dev-workflow.md
 
-## Operating contract
+## Start here
 
-1. Before each session, make sure `dev.kit` itself is up to date, then run `dev.kit`. Refresh focused layers with `dev.kit repo` or `dev.kit agent` after repo changes.
-2. Read `.rabbit/context.yaml` first. It is the machine contract for refs, commands, dependencies, manifests, and gaps.
-3. Read only the refs, manifests, dependency context, and explicitly referenced paths from `context.yaml`. Avoid broad filesystem scans.
-4. Prefer manifests and repo-declared commands over implementation guesses. Do not edit generated `.rabbit/context.yaml` directly.
-5. Fetch dynamic GitHub state with `gh` only when the current task needs issues, PRs, reviews, workflow runs, or alerts.
+1. Make sure `dev.kit` itself is current, then run `dev.kit`.
+2. Read `.rabbit/context.yaml` first when it exists.
+3. Read the highest-priority refs and manifests that `context.yaml` points to.
+4. Run `dev.kit repo` after repo changes or when context is missing or stale.
 
-### Dependency context
+## Operating rules
 
-When a dependency entry points to another repo, treat that repo as its own context boundary. Prefer the dependency repo’s `.rabbit/context.yaml`; if it is missing in a local checkout, run `dev.kit repo` from that dependency repo before reading its implementation files.
-
-For manifest backend traces, read the manifest first, then the traced backend path or docs listed under that manifest entry. Use live GitHub lookups only when local dependency context is unavailable or stale.
-
-### Gap repair loop
-
-For each gap, read its evidence in `context.yaml`, identify the repo-owned source asset that should declare the missing contract, patch that source asset, then rerun `dev.kit repo`. Repeat until the gap is resolved or clearly document why the repo intentionally cannot cover it.
-
-Do not patch generated context to hide a gap. Fix docs, example env files, manifests, workflows, package scripts, Dockerfiles, or other primary repo assets so the next context refresh can detect the improvement.
-
-  - config (partial): Config signals exist, but no explicit env contract file was detected. Add .env.example, .env.sample, or .env.template when runtime configuration is required.
+- treat `.rabbit/context.yaml` as generated repo evidence, not hand-authored guidance
+- prefer repo-declared commands and manifests over guessed behavior
+- keep durable workflow guidance in repo-owned docs, especially `docs/references/agent-dev-workflow.md`
+- when a gap appears, repair the owning repo asset and rerun `dev.kit repo`
+- use live GitHub data only when the task needs issues, PRs, reviews, workflow runs, or alerts
 
 ## Workflow
 
-Use these repo-derived steps as the default operating path. Adapt them to the current agent role instead of forcing a single development lifecycle onto every task.
+- read: `README.md`, `changes.md`, `deploy.yml`, `.github/workflows/`, `docs/`
+- verify: `make test`
 
-  - Read the highest-priority repo refs first: ./README.md, ./changes.md, ./deploy.yml, ./.github/workflows, ./Makefile, ./docs
-  - Run the canonical verification command: make test
+## Notes
 
+- `AGENTS.md` is optional and repo-owned in this repo
+- the reference doc is the fuller source of examples, Q&A, and best practices

Makefile

@@ -1,6 +1,6 @@
 WORKER_IMAGE := usabilitydynamics/udx-worker:latest
 
-.PHONY: test test-real test-docker test-docker-pull test-shell eval eval-view
+.PHONY: test test-real test-docker test-docker-pull test-shell
 
 # Run tests locally
 test:
@@ -21,12 +21,4 @@ test-shell:
 
 # Pull the worker image explicitly
 test-docker-pull:
-	docker pull $(WORKER_IMAGE)
-
-# Run promptfoo eval — measures agent accuracy with vs without dev.kit context
-eval:
-	promptfoo eval -c evals/promptfooconfig.yaml
-
-# View eval results in browser
-eval-view:
-	promptfoo view
+	docker pull $(WORKER_IMAGE)