Refine dev.kit repo context and agent flow

.rabbit/context.yaml

@@ -1,74 +1,177 @@
 # Generated by dev.kit repo — do not edit manually.
 # Run `dev.kit repo` to refresh.
 kind: repoContext
-version: udx.io/dev.kit/v1
-generated: 2026-04-17
+version: udx.dev/dev.kit/v1
+generated: 2026-05-04
 
 repo:
   name: dev.kit
-  archetype: library-cli
-  profile: node
+  archetype: package-cli
+
+# 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: Prefer README, focused docs, workflows, manifests, and explicit operational files.
+# Note: Exclude broad implementation directories unless they are the contract themselves.
 
 refs:
   - ./README.md
-  - ./docs/installation.md
-  - ./docs/context.md
-  - ./docs/agents.md
-  - ./docs/integration.md
-  - ./docs
-  - ./.rabbit
+  - ./changes.md
+  - ./deploy.yml
   - ./.github/workflows
   - ./Makefile
-  - ./package.json
-  - ./deploy.yml
-  - ./lib
-  - ./src
-  - ./tests
+  - ./docs
+
+# Commands — Canonical repo entrypoints detected from strong repo signals.
+# Note: Prefer declared make targets and package scripts before regex matches in docs.
+# Note: Emit only commands that can be traced to a concrete source.
+# Note: Record the source path so the command can be reviewed and corrected.
 
 commands:
-  verify: make test
-  build: make build
-  run: make run
+  verify:
+    run: make test
+    source: Makefile
+
+# 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.
+# Note: Include message and evidence so the status can be reviewed.
+# Note: Prefer traceable refs and missing signals over vague advice.
 
-# Gaps — factors that are missing or partial
 gaps:
-  - config (partial)
+  - 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.
+    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.
+# 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.
 
-# External dependencies — cross-repo and upstream references
-# Trace these to find infrastructure, deployment, and build logic outside this repo.
-# Same-org deps are resolved with metadata. External deps listed for agent reference.
 dependencies:
   - repo: udx/reusable-workflows
-    type: reusable workflow
+    kind: reusable workflow
     resolved: true
     archetype: workflow-repo
-    profile: unknown
+    description: Reusable GitHub Actions workflow templates for CI/CD
     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
+    declared_as: udx.io/worker-v1/deploy
+    archetype: runtime-image
+    description: UDX Worker Docker image
+    used_by:
+      - deploy.yml
 
-# Config manifests — traceable workflow and tooling dependencies
-# Read these to understand what controls repo behavior before reading shell code.
-manifests:
-  - src/configs/archetype-rules.yaml — archetype definitions and matching rules
-  - src/configs/archetype-signals.yaml — file/dir signals for framework and platform detection
-  - src/configs/audit-rules.yaml — factor gap messages and improvement guidance
-  - src/configs/context-config.yaml — repo root markers and priority paths
-  - src/configs/detection-patterns.yaml — regex patterns for build/verify/run command detection
-  - src/configs/detection-signals.yaml — file/dir/glob patterns for factor analysis
-  - src/configs/development-practices.yaml — engineering principles inlined into repo context
-  - src/configs/development-workflows.yaml — git workflow steps, PR process, and operational notes
-  - src/configs/github-issues.yaml — issue templates, labels, and agent issue workflow
-  - src/configs/github-prs.yaml — PR templates, bot reviewers, and post-merge checklist
-  - src/configs/knowledge-base.yaml — org hierarchy and preferred knowledge sources
-  - src/configs/learning-workflows.yaml — agent session discovery and lesson extraction rules
-  - src/configs/repo-scaffold.yaml — baseline dirs/files per archetype and factor
-  - .github/workflows/context7-ops.yml
-  - .github/workflows/npm-release-ops.yml
-  - 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.
+# Note: Prefer structured kind and description metadata from the manifest itself.
+# Note: Include eval and workflow manifests, not only deploy manifests.
 
-# Lessons from agent sessions
-lessons:
-  - .rabbit/dev.kit/lessons-dev.kit-2026-04-15.md
-  - .rabbit/dev.kit/lessons-dev.kit-2026-04-14.md
+manifests:
+  - path: src/configs/archetypes.yaml
+    kind: repoArchetypes
+    description: Repo archetype definitions and matching rules
+    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/audit-rules.yaml
+    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
+    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/detection-patterns.yaml
+    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:
+      - version: udx.dev/dev.kit/v1
+      - path reference: lib/modules/repo_signals.sh
+  - path: src/configs/detection-signals.yaml
+    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
+    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: 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
+      - src/configs/context-config.yaml
+    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: 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