fix: use canonical nested Anchors bundle directories

README.md

@@ -27,7 +27,7 @@ async def main():
     # Load Anchors as the complete-host base and a Foundation provider partial.
     anchors = await load_bundle(
         "git+https://github.com/microsoft/amplifier-foundation@main"
-        "#subdirectory=bundles/anchors.md"
+        "#subdirectory=bundles/anchors/bundle.md"
     )
     provider = await load_bundle(
         "git+https://github.com/microsoft/amplifier-foundation@main"
@@ -120,8 +120,8 @@ This repo also contains reference bundle content for common configurations:
 |------|---------|
 | `behaviors/` | Reusable capability behaviors — the primary authoring and sharing surface |
 | `bundle.md` | Legacy selected Foundation root, retained for compatible complete compositions |
-| `bundles/anchors.md` | Recommended supporting root for a new complete host; assets stay in `bundles/anchors/` |
-| `bundles/anchors-amp-dev.md` | Anchors plus the portable `behaviors/amp-dev.yaml` capability |
+| `bundles/anchors/bundle.md` | Recommended supporting root for a new complete host, alongside its agents and context |
+| `bundles/anchors-amp-dev/bundle.md` | Anchors plus the portable `behaviors/amp-dev.yaml` capability |
 | `providers/` | Provider configurations (anthropic, openai, azure-openai, gemini, ollama) |
 | `agents/` | Reusable agent definitions |
 | `context/` | Shared context files |
@@ -132,8 +132,8 @@ This repo also contains reference bundle content for common configurations:
 `behaviors/amp-dev.yaml` adds the lean `amp-dev:amplifier-dev-expert`, short
 ecosystem instructions, and the Amplifier Tester behavior without selecting an
 orchestrator or context manager. Existing hosts can compose that capability
-without adopting Anchors. The old `bundles/anchors/bundle.md` and
-`bundles/anchors-amp-dev/bundle.md` paths remain compatibility wrappers; the former
+without adopting Anchors. The nested manifests are the only Anchors entry points;
+there are no flat manifests or compatibility wrappers. The former
 `anchors-amp-dev:amplifier-dev-expert` agent alias is not retained.
 
 ## Examples

bundles/anchors-amp-dev/README.md

@@ -1,6 +1,6 @@
 # Anchors + Amplifier-Ecosystem Knowledge
 
-The [`anchors`](../anchors.md) bundle plus one portable capability: knowledge of
+The [`anchors`](../anchors/bundle.md) bundle plus one portable capability: knowledge of
 the Amplifier ecosystem itself — repo dependency order, cross-repo validation in
 a Digital Twin Universe, and bundle/agent authoring.
 
@@ -10,19 +10,20 @@ it is being used to build.
 
 ## Install
 
-### Migration from the nested entry point
+### Resource identifiers
 
-The old root URI remains supported, but its added resource identifiers changed:
+The nested root is canonical. Its added resource identifiers use the portable
+capability's namespace:
 
 | Former identifier | Replacement |
 |---|---|
 | `anchors-amp-dev:amplifier-dev-expert` | `amp-dev:amplifier-dev-expert` |
 | `anchors-amp-dev:context/amplifier-ecosystem.md` | `amp-dev:context/amplifier-dev/amplifier-ecosystem.md` |
 
 Update explicit delegate calls and context references. The old agent alias and
-context path are not compatibility exports. The wrappers and expert use the
-enclosing `foundation:` resource namespace; it must resolve to this candidate
-version or later, not a stale separately cached Foundation tree.
+context path are not compatibility exports. The expert uses the enclosing
+`foundation:` resource namespace for documentation, not its runtime. There are
+no flat manifests or compatibility wrappers.
 
 ### Select the complete root
 
@@ -33,22 +34,27 @@ amplifier bundle use anchors-amp-dev
 ```
 
 Or add it explicitly by URI (single-quote to prevent shell expansion of the `#`
-fragment; the `.md` suffix is required):
+fragment):
 
 ```bash
-amplifier bundle add 'git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors-amp-dev.md' --name anchors-amp-dev
+amplifier bundle add 'git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors-amp-dev' --name anchors-amp-dev
 amplifier bundle use anchors-amp-dev
 ```
 
 ## What it is, mechanically
 
-The canonical `bundles/anchors-amp-dev.md` declares no runtime of its own. Its
-includes and instruction body are:
+The canonical `bundles/anchors-amp-dev/bundle.md` declares no runtime of its own.
+The directory URI selects that manifest; an explicit
+`#subdirectory=bundles/anchors-amp-dev/bundle.md` also works. Its own namespace
+stays at the manifest directory, without a `namespace_root` override or variant
+assets. Self-namespaced relative includes select the base and capability from the
+same repository, including direct local file/directory loads without separately
+registering Foundation. Its includes and instruction body are:
 
 ```yaml
 includes:
-  - bundle: foundation:bundles/anchors.md
-  - bundle: foundation:behaviors/amp-dev.yaml
+  - bundle: anchors-amp-dev:../anchors/bundle.md
+  - bundle: anchors-amp-dev:../../behaviors/amp-dev.yaml
 ```
 
 ```
@@ -99,11 +105,11 @@ includes produce a byte-identical mount plan.
 ```
 amplifier-foundation/
 ├── bundles/
-│   ├── anchors.md                  # complete Anchors host
-│   ├── anchors-amp-dev.md          # Anchors + amp-dev behavior
+│   ├── anchors/
+│   │   └── bundle.md               # complete Anchors host, alongside its assets
 │   └── anchors-amp-dev/
 │       ├── README.md               # this file
-│       └── bundle.md               # compatibility wrapper
+│       └── bundle.md               # Anchors + amp-dev behavior
 ├── behaviors/amp-dev.yaml          # complete portable amp-dev capability
 ├── agents/amplifier-dev-expert.md   # lean ecosystem authority
 └── context/amplifier-dev/
@@ -113,15 +119,17 @@ amplifier-foundation/
 
 ## Status
 
-Version 0.3.0. The flat root composes Anchors plus the shared capability. The old
-`bundles/anchors-amp-dev/bundle.md` URI remains a compatibility wrapper, not a
-second implementation. Local targeted qualification passes 232 checks. Separate
-`amplifier-tester` acceptance through official `amplifier-app-cli` passed 17
-bounded checks covering both flat roots and both compatibility entry points:
+Version 0.3.0. The nested root composes canonical nested Anchors plus the shared
+capability, without a second implementation or flat entry point.
+
+**Historical qualification (before the nested-only layout):** Local targeted
+qualification passed 232 checks. Separate `amplifier-tester` acceptance through
+official `amplifier-app-cli` passed 17 bounded checks covering the then-flat roots
+and compatibility entry points:
 real model responses, file and Bash tools, named-agent spawning, skills loading,
 candidate resource provenance, and retained streaming/simple runtimes.
 
-The portable capability also passed real root and expert-spawn checks in an
-isolated non-Anchors host. These observations do not establish a clean
-repository-wide recipe verdict; full validation failures and coverage limits
-remain separate evidence.
+The portable capability also historically passed real root and expert-spawn
+checks in an isolated non-Anchors host. These observations do not qualify the
+nested-only layout or establish a clean repository-wide recipe verdict; full
+validation failures and coverage limits remain separate evidence.

bundles/anchors-amp-dev/bundle.md

@@ -3,10 +3,11 @@ bundle:
   name: anchors-amp-dev
   display_name: Anchors · Amplifier development
   version: 0.3.0
-  description: Compatibility entry point for the flat Anchors Amplifier-development host.
+  description: Anchors with portable Amplifier ecosystem development and isolated validation.
 
 includes:
-  - bundle: foundation:bundles/anchors-amp-dev.md
+  - bundle: anchors-amp-dev:../anchors/bundle.md
+  - bundle: anchors-amp-dev:../../behaviors/amp-dev.yaml
 ---
 
 @anchors:context/system.md

bundles/anchors/README.md

@@ -1,7 +1,8 @@
 # Anchors Bundle
 
-The CLI's current default runtime bundle and the recommended supporting root for a
-new complete host. It remains a lean experimental bundle that shapes the agent's
+The lean base host included by the CLI's default `anchors-amp-dev` bundle and the
+recommended supporting root for a new complete host. It remains a lean
+experimental bundle that shapes the agent's
 conduct with a short, explicit set of **behavioral principles** placed at the very
 top of the system prompt -- rather than encoding behavior across large rule
 documents.
@@ -14,12 +15,13 @@ still producing disciplined, delegation-aware behavior.
 ## Install
 
 ```bash
-amplifier bundle add 'git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors.md' --name anchors
+amplifier bundle add 'git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors' --name anchors
 amplifier bundle use anchors
 ```
 
-Single-quote the URI to prevent shell expansion of the `#` fragment. The `.md`
-suffix is required.
+Single-quote the URI to prevent shell expansion of the `#` fragment. The directory
+selects `bundle.md`; an explicit `#subdirectory=bundles/anchors/bundle.md` also
+names the same manifest.
 
 ## The idea
 
@@ -77,20 +79,18 @@ for them.
 Every module, tool, hook, and behavior is referenced by its full
 `git+https://...` source URL rather than a `foundation:` namespace. The bundle's
 own agents and context are referenced through its own `anchors:`
-namespace. The canonical manifest is `bundles/anchors.md`; its
-`namespace_root: anchors` is relative to the manifest's containing `bundles/`
-directory, so assets still resolve under `bundles/anchors/`. It does not require
-the Foundation runtime to be composed. Keep the manifest and its asset directory
-together when relocating it.
+namespace. The canonical manifest is `bundles/anchors/bundle.md`; its containing
+directory is the asset root, so no `namespace_root` override is needed. It does
+not require the Foundation runtime to be composed. Keep the manifest and its
+agents and context together when relocating it.
 
 ## Files
 
 ```
 bundles/
-├── anchors.md                 # canonical session / tools / hooks / agents
 └── anchors/
     ├── README.md              # this file
-    ├── bundle.md              # compatibility wrapper for anchors.md
+    ├── bundle.md              # canonical session / tools / hooks / agents
     ├── agents/
     │   ├── explorer.md        # multi-file recon
     │   ├── architect.md       # design / spec / review
@@ -115,17 +115,17 @@ boundary is not permission to ignore rules that apply after discovery.
 
 Promoted out of an `experiments/` prototype to a published bundle by 70a84d0
 (#259); `anchors-amp-dev` followed in 78d0abe (#273). The prototype trees were
-deleted once promotion made them stale copies -- read `bundles/anchors.md` and
-`bundles/anchors-amp-dev.md` for the live manifests, and those two commits (or
+deleted once promotion made them stale copies -- read `bundles/anchors/bundle.md`
+and `bundles/anchors-amp-dev/bundle.md` for the live manifests, and those two commits (or
 `git log --diff-filter=D -- experiments/behavioral-anchor`) for the originals.
 
-Version 0.3.0 -- the flat manifest retains the evaluated (#327) principle and
+Version 0.3.0 -- the nested manifest retains the historically evaluated (#327) principle and
 agent text, and is the source of the runtime that `anchors-amp-dev` includes.
 The principle set and tool/agent roster are a starting point and will be adjusted
 as observation shows what helps or hurts.
 
-`bundles/anchors/bundle.md` remains a compatibility entry point. The complete
-Anchors root chooses `loop-streaming` and `context-simple`; reusable behaviors do
-not choose either runtime, and applications may override those defaults.
-Validation of the flat-root migration is pending; the historical evaluations
-above do not qualify this new layout.
+The nested manifest is the only entry point, not a compatibility wrapper. The
+complete Anchors root chooses `loop-streaming` and `context-simple`; reusable
+behaviors do not choose either runtime, and applications may override those
+defaults. The historical evaluations above do not qualify this nested-only
+layout.