recipes: migrate the 6 remaining legacy recipes to schema v2; agent-ref lint; validate-bundle-repo enhance_diagrams=false guard

recipes/bundle-behavioral-model.yaml

@@ -16,11 +16,44 @@
 #     }
 #   )
 #
+# CHANGELOG:
+# v1.1.0 - Portability: declare a schema_version 2 dependency manifest
+#          (contract recipe-dependency-manifest.v1). The three `agent:`
+#          steps below (foundation:explorer, foundation:file-ops)
+#          previously resolved out of the CALLING session's agent map;
+#          a caller without those agents failed at run time with
+#          "Agent '<name>' not found in configuration". They now resolve
+#          from this recipe's own declared closure.
+#        - Self-referential on purpose: foundation's own recipe declares
+#          foundation as a dependency. Core 11 forbids inferring a source
+#          from the `foundation:` namespace prefix -- an undeclared
+#          dependency is never guessed, so it must be written down.
+#        - No behavior change under the legacy engine, which ignores both
+#          new top-level keys. Recipe logic, steps and prompts untouched.
+# v1.0.0 - Initial release.
+#
 # =============================================================================
 
+# --- Dependency manifest (contract: recipe-dependency-manifest.v1) ----------
+# schema_version 2 makes this recipe portable: every `agent:` reference below
+# resolves ONLY from the declared closure here, never from the calling
+# session's agent map. A caller that lacks these agents can still run it.
+# Pinned to the released tag `v2.1.2`. Foundation fetches a ref with
+# `git clone --branch`, which accepts a branch or a tag but NOT a commit SHA,
+# so a tag is the most immutable pin a `source:` can currently express.
+schema_version: 2
+
+dependencies:
+  - source: "git+https://github.com/microsoft/amplifier-foundation@v2.1.2"
+    kind: bundle
+    required_agents:
+      - "foundation:explorer"
+      - "foundation:file-ops"
+# ---------------------------------------------------------------------------
+
 name: "bundle-behavioral-model"
 description: "Analyze a bundle's full composition and produce a behavioral model document"
-version: "1.0.0"
+version: "1.1.0"
 tags: ["bundle", "analysis", "documentation", "behavioral-model"]
 
 recursion:

recipes/change-spec-to-behavioral-model.yaml

@@ -26,11 +26,44 @@
 #     }
 #   )
 #
+# CHANGELOG:
+# v1.1.0 - Portability: declare a schema_version 2 dependency manifest
+#          (contract recipe-dependency-manifest.v1). The three `agent:`
+#          steps below (foundation:explorer, foundation:file-ops)
+#          previously resolved out of the CALLING session's agent map;
+#          a caller without those agents failed at run time with
+#          "Agent '<name>' not found in configuration". They now resolve
+#          from this recipe's own declared closure.
+#        - Self-referential on purpose: foundation's own recipe declares
+#          foundation as a dependency. Core 11 forbids inferring a source
+#          from the `foundation:` namespace prefix -- an undeclared
+#          dependency is never guessed, so it must be written down.
+#        - No behavior change under the legacy engine, which ignores both
+#          new top-level keys. Recipe logic, steps and prompts untouched.
+# v1.0.0 - Initial release.
+#
 # =============================================================================
 
+# --- Dependency manifest (contract: recipe-dependency-manifest.v1) ----------
+# schema_version 2 makes this recipe portable: every `agent:` reference below
+# resolves ONLY from the declared closure here, never from the calling
+# session's agent map. A caller that lacks these agents can still run it.
+# Pinned to the released tag `v2.1.2`. Foundation fetches a ref with
+# `git clone --branch`, which accepts a branch or a tag but NOT a commit SHA,
+# so a tag is the most immutable pin a `source:` can currently express.
+schema_version: 2
+
+dependencies:
+  - source: "git+https://github.com/microsoft/amplifier-foundation@v2.1.2"
+    kind: bundle
+    required_agents:
+      - "foundation:explorer"
+      - "foundation:file-ops"
+# ---------------------------------------------------------------------------
+
 name: "change-spec-to-behavioral-model"
 description: "Generate a behavioral model showing how proposed changes affect an existing bundle"
-version: "1.0.0"
+version: "1.1.0"
 tags: ["change-spec", "behavioral-model", "impact-analysis", "bundle-improvement"]
 
 context:

recipes/generate-bundle-docs.yaml

@@ -1,3 +1,47 @@
+# generate-bundle-docs.yaml
+# Bundle Documentation Generator Recipe v3.1.0
+# Generates bundle.dot + bundle.png for a whole bundle repository.
+#
+# CHANGELOG:
+# v3.1.0 - Portability: declare a schema_version 2 dependency manifest
+#          (contract recipe-dependency-manifest.v1). The
+#          `agent: "foundation:zen-architect"` step below previously
+#          resolved out of the CALLING session's agent map; a caller
+#          without that agent failed at run time with
+#          "Agent 'foundation:zen-architect' not found in configuration".
+#          It now resolves from this recipe's own declared closure.
+#        - Self-referential on purpose: foundation's own recipe declares
+#          foundation as a dependency. Core 11 forbids inferring a source
+#          from the `foundation:` namespace prefix -- an undeclared
+#          dependency is never guessed, so it must be written down.
+#        - No behavior change under the legacy engine, which ignores both
+#          new top-level keys. Recipe logic, steps and prompts untouched.
+#        - FIX (same defect class as validate-bundle-repo v3.12.0): the
+#          producer `enhance-bundle-dot` is conditional on
+#          `{{enhance_diagrams}} != 'false'` but the consumer
+#          `write-bundle-dot` reads {{enhanced_bundle_dot}}
+#          unconditionally. New `set-default-enhanced-bundle-dot` step
+#          emits an empty default ahead of the conditional producer, so
+#          `enhance_diagrams: "false"` falls back to the structural DOT
+#          instead of raising `Undefined variable`.
+# v3.0.0 - Single bundle.dot + bundle.png per repository via bundle_repo_dot().
+
+# --- Dependency manifest (contract: recipe-dependency-manifest.v1) ----------
+# schema_version 2 makes this recipe portable: every `agent:` reference below
+# resolves ONLY from the declared closure here, never from the calling
+# session's agent map. A caller that lacks these agents can still run it.
+# Pinned to the released tag `v2.1.2`. Foundation fetches a ref with
+# `git clone --branch`, which accepts a branch or a tag but NOT a commit SHA,
+# so a tag is the most immutable pin a `source:` can currently express.
+schema_version: 2
+
+dependencies:
+  - source: "git+https://github.com/microsoft/amplifier-foundation@v2.1.2"
+    kind: bundle
+    required_agents:
+      - "foundation:zen-architect"
+# ---------------------------------------------------------------------------
+
 name: generate-bundle-docs
 description: |
   Generates bundle.dot + bundle.png for the whole repository via bundle_repo_dot().
@@ -12,7 +56,7 @@ description: |
 
   Both embed source_hash for freshness tracking.
   LLM label enhancement is on by default (set enhance_diagrams: "false" to skip).
-version: "3.0.0"
+version: "3.1.0"
 author: "Amplifier Foundation"
 tags: ["bundles", "documentation", "visualization", "dot"]
 
@@ -85,6 +129,21 @@ steps:
   # STEP 2: LLM-enhance bundle DOT labels (skip with enhance_diagrams: "false")
   # Only runs when a bundle DOT needs to be written.
   # ============================================================================
+  # Default for the CONDITIONAL producer below. `enhance-bundle-dot` only runs
+  # when enhance_diagrams != 'false', but `write-bundle-dot` reads
+  # {{enhanced_bundle_dot}} unconditionally. Steps execute in declaration order,
+  # so this default lands first and the conditional producer overwrites it when
+  # it runs. The consumer treats an empty value as "no enhanced DOT" and falls
+  # back to the structural DOT -- the intended behaviour when enhancement is off.
+  - id: "set-default-enhanced-bundle-dot"
+    type: "bash"
+    command: |
+      echo ""
+    output: "enhanced_bundle_dot"
+    timeout: 10
+    on_error: "continue"
+    depends_on: ["generate-bundle-dot"]
+
   - id: "enhance-bundle-dot"
     agent: "foundation:zen-architect"
     mode: "ARCHITECT"
@@ -132,7 +191,7 @@ steps:
   # ============================================================================
   - id: "write-bundle-dot"
     type: "bash"
-    depends_on: ["enhance-bundle-dot"]
+    depends_on: ["set-default-enhanced-bundle-dot", "enhance-bundle-dot"]
     on_error: "continue"
     command: |
       "${AMPLIFIER_PYTHON:-python3}" << 'PYEOF'

recipes/objectives-to-behavioral-model.yaml

@@ -20,11 +20,44 @@
 #     }
 #   )
 #
+# CHANGELOG:
+# v1.1.0 - Portability: declare a schema_version 2 dependency manifest
+#          (contract recipe-dependency-manifest.v1). The two `agent:`
+#          steps below (foundation:explorer, foundation:file-ops)
+#          previously resolved out of the CALLING session's agent map;
+#          a caller without those agents failed at run time with
+#          "Agent '<name>' not found in configuration". They now resolve
+#          from this recipe's own declared closure.
+#        - Self-referential on purpose: foundation's own recipe declares
+#          foundation as a dependency. Core 11 forbids inferring a source
+#          from the `foundation:` namespace prefix -- an undeclared
+#          dependency is never guessed, so it must be written down.
+#        - No behavior change under the legacy engine, which ignores both
+#          new top-level keys. Recipe logic, steps and prompts untouched.
+# v1.0.0 - Initial release.
+#
 # =============================================================================
 
+# --- Dependency manifest (contract: recipe-dependency-manifest.v1) ----------
+# schema_version 2 makes this recipe portable: every `agent:` reference below
+# resolves ONLY from the declared closure here, never from the calling
+# session's agent map. A caller that lacks these agents can still run it.
+# Pinned to the released tag `v2.1.2`. Foundation fetches a ref with
+# `git clone --branch`, which accepts a branch or a tag but NOT a commit SHA,
+# so a tag is the most immutable pin a `source:` can currently express.
+schema_version: 2
+
+dependencies:
+  - source: "git+https://github.com/microsoft/amplifier-foundation@v2.1.2"
+    kind: bundle
+    required_agents:
+      - "foundation:explorer"
+      - "foundation:file-ops"
+# ---------------------------------------------------------------------------
+
 name: "objectives-to-behavioral-model"
 description: "Design mechanisms and generate a behavioral model from objectives"
-version: "1.0.0"
+version: "1.1.0"
 tags: ["objectives", "behavioral-model", "design"]
 
 context:

recipes/spec-to-behavioral-model.yaml

@@ -17,11 +17,44 @@
 #     }
 #   )
 #
+# CHANGELOG:
+# v1.1.0 - Portability: declare a schema_version 2 dependency manifest
+#          (contract recipe-dependency-manifest.v1). The two `agent:`
+#          steps below (foundation:explorer, foundation:file-ops)
+#          previously resolved out of the CALLING session's agent map;
+#          a caller without those agents failed at run time with
+#          "Agent '<name>' not found in configuration". They now resolve
+#          from this recipe's own declared closure.
+#        - Self-referential on purpose: foundation's own recipe declares
+#          foundation as a dependency. Core 11 forbids inferring a source
+#          from the `foundation:` namespace prefix -- an undeclared
+#          dependency is never guessed, so it must be written down.
+#        - No behavior change under the legacy engine, which ignores both
+#          new top-level keys. Recipe logic, steps and prompts untouched.
+# v1.0.0 - Initial release.
+#
 # =============================================================================
 
+# --- Dependency manifest (contract: recipe-dependency-manifest.v1) ----------
+# schema_version 2 makes this recipe portable: every `agent:` reference below
+# resolves ONLY from the declared closure here, never from the calling
+# session's agent map. A caller that lacks these agents can still run it.
+# Pinned to the released tag `v2.1.2`. Foundation fetches a ref with
+# `git clone --branch`, which accepts a branch or a tag but NOT a commit SHA,
+# so a tag is the most immutable pin a `source:` can currently express.
+schema_version: 2
+
+dependencies:
+  - source: "git+https://github.com/microsoft/amplifier-foundation@v2.1.2"
+    kind: bundle
+    required_agents:
+      - "foundation:explorer"
+      - "foundation:file-ops"
+# ---------------------------------------------------------------------------
+
 name: "spec-to-behavioral-model"
 description: "Generate a behavioral model from a mechanism spec document"
-version: "1.0.0"
+version: "1.1.0"
 tags: ["mechanism-spec", "behavioral-model", "analysis"]
 
 context:

recipes/validate-bundle-repo.yaml

@@ -1,9 +1,36 @@
 # validate-bundle-repo.yaml
-# Repository-Wide Bundle Validator Recipe v3.11.0
+# Repository-Wide Bundle Validator Recipe v3.12.0
 # Validates an entire bundle repository against structural requirements, conventions,
 # and Amplifier bundle philosophy (context sink pattern, thin behaviors, tool placement)
 #
 # CHANGELOG:
+# v3.12.0 - Portability: declare a schema_version 2 dependency manifest
+#          (contract recipe-dependency-manifest.v1). The five
+#          `agent: "foundation:zen-architect"` steps below previously
+#          resolved out of the CALLING session's agent map; a caller
+#          without that agent failed at run time with
+#          "Agent 'foundation:zen-architect' not found in configuration".
+#          They now resolve from this recipe's own declared closure.
+#          This is the same fix PR #345 gave the three sibling validators
+#          (validate-agents, validate-bundle, validate-single-bundle);
+#          this recipe -- the one with the MOST references to the agent --
+#          was not included in that migration.
+#        - Self-referential on purpose: foundation's own recipe declares
+#          foundation as a dependency. Core 11 forbids inferring a source
+#          from the `foundation:` namespace prefix -- an undeclared
+#          dependency is never guessed, so it must be written down.
+#        - No behavior change under the legacy engine, which ignores both
+#          new top-level keys. Recipe logic, steps and prompts untouched.
+#        - FIX: with `enhance_diagrams: "false"` the recipe crashed with
+#          `Undefined variable: {{bundle_overview_enhanced_dot}}`. The
+#          producer `bundle-overview-regen-enhance` is conditional on
+#          `{{enhance_diagrams}} != 'false'`, but the consumer
+#          `bundle-overview-regen-write` reads that variable
+#          unconditionally. New `set-default-bundle-overview-enhanced-dot`
+#          step emits an empty default ahead of the conditional producer
+#          (same pattern as validate-agents' initialize-optional-outputs /
+#          set-default-* steps), so the consumer falls back to the
+#          structural DOT instead of failing.
 # v3.11.0 - NEW PHASE 0.6: module-dep-resolvability-check
 #        - Deterministic, no network, no LLM. `amplifier update` refreshes every
 #          bundle module with `uv pip install -e <cache-module-dir> --python
@@ -296,6 +323,22 @@
 # All size measurements use tokens estimated as: len(content) // 4
 # This provides consistent sizing regardless of line length variations.
 
+# --- Dependency manifest (contract: recipe-dependency-manifest.v1) ----------
+# schema_version 2 makes this recipe portable: every `agent:` reference below
+# resolves ONLY from the declared closure here, never from the calling
+# session's agent map. A caller that lacks these agents can still run it.
+# Pinned to the released tag `v2.1.2`. Foundation fetches a ref with
+# `git clone --branch`, which accepts a branch or a tag but NOT a commit SHA,
+# so a tag is the most immutable pin a `source:` can currently express.
+schema_version: 2
+
+dependencies:
+  - source: "git+https://github.com/microsoft/amplifier-foundation@v2.1.2"
+    kind: bundle
+    required_agents:
+      - "foundation:zen-architect"
+# ---------------------------------------------------------------------------
+
 name: validate-bundle-repo
 description: |
   Validates an entire Amplifier bundle repository including:
@@ -356,7 +399,7 @@ description: |
   - All measurements use TOKENS (len/4), never line counts
 
   For single bundle validation, use validate-bundle.yaml instead.
-version: "3.11.0"
+version: "3.12.0"
 author: "Amplifier Foundation Team"
 tags: ["bundle", "validation", "quality", "conventions", "repository", "packaging", "hygiene", "context-sink"]
 
@@ -4833,6 +4876,24 @@ steps:
     parse_json: true
     timeout: 30
 
+  # Default for the CONDITIONAL producer below. `bundle-overview-regen-enhance`
+  # only runs when enhance_diagrams != 'false', but `bundle-overview-regen-write`
+  # reads {{bundle_overview_enhanced_dot}} unconditionally -- with
+  # enhance_diagrams: "false" that raised `Undefined variable:
+  # {{bundle_overview_enhanced_dot}}`. Steps execute in declaration order, so
+  # this default lands first and the conditional producer overwrites it when it
+  # runs (same pattern as validate-agents' set-default-* steps). The consumer
+  # treats an empty value as "no enhanced DOT" and falls back to the structural
+  # DOT, which is exactly the intended behaviour when enhancement is off.
+  - id: "set-default-bundle-overview-enhanced-dot"
+    type: "bash"
+    command: |
+      echo ""
+    output: "bundle_overview_enhanced_dot"
+    timeout: 10
+    on_error: "continue"
+    depends_on: ["bundle-overview-regen-structural"]
+
   - id: "bundle-overview-regen-enhance"
     agent: "foundation:zen-architect"
     mode: "ARCHITECT"
@@ -4882,7 +4943,7 @@ steps:
 
   - id: "bundle-overview-regen-write"
     type: "bash"
-    depends_on: ["bundle-overview-regen-enhance"]
+    depends_on: ["set-default-bundle-overview-enhanced-dot", "bundle-overview-regen-enhance"]
     on_error: "continue"
     command: |
       "${AMPLIFIER_PYTHON:-python3}" << 'EOF'

tests/test_module_dep_resolvability_check.py

@@ -157,9 +157,15 @@ def test_synthesize_report_references_output(self, steps_by_id):
 
 
 class TestVersionAndChangelog:
-    def test_version_is_3_11_0(self, recipe_data):
+    def test_version_is_current(self, recipe_data):
+        """Pinned to the recipe's current release.
+
+        Bumped 3.11.0 -> 3.12.0 by the schema-v2 migration (dependency
+        manifest + enhance_diagrams guard). The v3.11.0 changelog entry
+        below is unaffected -- changelog entries accumulate.
+        """
         data, _ = recipe_data
-        assert data["version"] == "3.11.0"
+        assert data["version"] == "3.12.0"
 
     def test_changelog_has_v3_11_0_entry(self, recipe_data):
         _, content = recipe_data