microsoft · colombod · May 21, 2026 · May 21, 2026 · May 21, 2026 · May 21, 2026
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@ __pycache__/
 .ruff_cache/
 .venv/
 .investigation/
+APPROVAL_CHECKPOINT.md
diff --git a/README.md b/README.md
@@ -21,6 +21,8 @@ Two agents are included for querying session data:
 
 A **`/context-intelligence` mode** is also included for building new context intelligence-aware tooling. Activate it to enter a design workspace where you can investigate session data, explore the graph model, and produce reusable Amplifier components (skills, agents, context files, recipes, CLIs) for your project.
 
+A **`/bundle-usage` mode** is also included for analysing what a session or workspace actually used versus what its installed bundles declared. It surfaces tree-shake opportunities, under-utilised bundles, and configuration gaps — useful for auditing bundle payloads and guiding optimisation.
+
 ---
 
 ## Understanding workspace
@@ -305,11 +307,14 @@ See [`context/graph-model-reference.md`](context/graph-model-reference.md) for t
 | `graph-analyst` | Always | `graph_query`, `blob_read`, `tool-filesystem`, `tool-bash`, `tool-skills` | Primary entry point — graph-powered analysis via Cypher across all three data layers, blob resolution, automatic fallback |
 | `session-navigator` | Always (via delegation) | `tool-filesystem`, `tool-search`, `tool-bash`, `tool-skills` | Local fallback — safe JSONL navigation via bash/jq/grep; invoked by graph-analyst when the server is unreachable |
 | `context-intelligence-design-facilitator` | `/context-intelligence` mode only | `tool-skills` | Design guide — domain elicitation and component design facilitation for building new context intelligence-aware tooling |
+| `bundle-usage-analyst` | `/bundle-usage` mode only | `bundle_usage`, `tool-filesystem`, `tool-bash` | Bundle usage specialist — calls `bundle_usage`, inspects gap output, optionally reads bundle content for engagement-gap reasoning, writes a `.bundle-usage-report-<timestamp>.md` |
 
 **Delegation chain:** External callers always invoke `graph-analyst`. If the server is unreachable or the workspace contains 0 sessions, it delegates to `session-navigator`, which navigates local JSONL files using safe extraction patterns. `session-navigator` is never invoked directly.
 
 The `context-intelligence-design-facilitator` is a conversational design guide available only when the `/context-intelligence` mode is active. It asks questions to understand the user's domain, maps that domain to context intelligence data layers, and helps design the right Amplifier component shape (skill, agent, recipe, CLI, etc.) for the investigation findings. It delegates investigation to `graph-analyst` and component authoring mechanics to ecosystem experts (`foundation:foundation-expert`, `recipes:recipe-author`).
 
+The `bundle-usage-analyst` is available only when the `/bundle-usage` mode is active. It calls the `bundle_usage` tool to run a three-layer analysis (JSONL signals, local cache inventory, set-arithmetic gap), then writes a structured markdown report.
+
 See [`context/safe-extraction-patterns.md`](context/safe-extraction-patterns.md) for JSONL navigation patterns.
 
 ---
@@ -358,17 +363,105 @@ See [`context/dual-path-library-template.md`](context/dual-path-library-template
 
 ---
 
+## Bundle Usage Analysis Mode
+
+Activate with `/bundle-usage` (or `/mode bundle-usage`).
+
+The bundle usage mode analyses what a session or workspace actually used versus what each installed bundle declared. It reports gaps and generates actionable improvement suggestions for bundle optimisation.
+
+**Zero footprint when inactive** — the mode is registered with `advertised: false`, so neither the `bundle_usage` tool nor the `bundle-usage-analyst` agent appear in default sessions. They are only mounted when the mode is explicitly activated.
+
+### What it analyses
+
+The analysis runs three deterministic layers, in order:
+
+| Layer | What it does | Data source |
+|-------|-------------|-------------|
+| **Signals** | Counts actual invocations per bundle by component type (agents, skills, modes, recipes, tools) | Local JSONL event files (`events.jsonl`) |
+| **Inventory** | Enumerates what each installed bundle *declares* (agents, modes, skills, recipes) | Local bundle cache at `~/.amplifier/cache/` |
+| **Gap** | Computes set differences; classifies improvement opportunities | Set arithmetic — no LLM |
+
+### Improvement classifications
+
+| Type | Meaning | Trigger |
+|------|---------|---------|
+| `tree-shake` 🌳 | Bundle is declared but never invoked | 0 invocations across all component types |
+| `mode-refactor` ⚙️ | Bundle is under-utilised | Used < 20 % of declared components |
+| `config-gap` 🚩 | Bundle was invoked but is absent from local cache | Present in signals, missing from inventory |
+| `mode-never-activated` 🔒 | A contributed mode was never activated | Mode name absent from `mode:activated` / `mode:changed` events |
+
+### Requirements
+
+The **Signals** layer reads **local JSONL event files only** — no CI graph server required.
+
+| Signal type | Event kind | Coverage |
+|-------------|-----------|---------|
+| Agents | `delegate:agent_spawned` | Full — bundle prefix from event or inventory reverse-lookup |
+| Skills | `skill:loaded` | Full — bundle extracted from cache path or inventory reverse-lookup |
+| Recipes | `tool:pre` (recipes, execute) | Full — bundle extracted from `@bundle:path` prefix |
+| Tools | `tool:pre` (all other tools) | Full — attributed via inventory `agent_level` tool declarations |
+| Modes | `mode:activated`, `mode:changed` | Full — attributed via inventory `modes` reverse-lookup |
+| Context | `mentions:resolved` | Full — attributed via bundle key (new format) or cache path (legacy) |
+
+Events are read from `~/.amplifier/projects/{workspace}/sessions/*/context-intelligence/events.jsonl`.
+
+### Usage
+
+```
+# Session scope — analyse one session
+/bundle-usage
+> Analyse session <session-id>
+
+# Workspace scope — aggregate across all sessions in the workspace
+/bundle-usage
+> Analyse the whole workspace
+```
+
+The `bundle-usage-analyst` handles both scopes. It delegates to `bundle_usage(session_id=...)` for session scope and `bundle_usage(workspace=...)` for workspace scope, then writes a structured report.
+
+### Tool policies in the mode
+
+| Tool | Policy |
+|------|--------|
+| `bundle_usage`, `read_file`, `glob`, `grep`, `bash`, `delegate`, `todo` | Safe — always allowed |
+| `write_file` | Safe — analyst writes the report file |
+| `edit_file` | Warn — first call blocked with a reminder; retry proceeds |
+
+### Report format
+
+The analyst writes `.bundle-usage-report-<timestamp>.md` with:
+
+```
+# Bundle Usage Report
+Scope: session=<id>  OR  workspace=<name>
+
+## Summary Table
+| Bundle | Declared | Used | Util % | Improvement |
+
+## Improvement Actions
+🌳 TREE-SHAKE     — declared but zero invocations
+⚙️ MODE-REFACTOR  — used < 20 % of declared components
+🚩 CONFIG-GAP     — invoked but absent from cache
+
+## Engagement Gap (if requested)
+## Raw Output (JSON)
+```
+
+---
+
 ## Repository structure
 
 ```
 amplifier-bundle-context-intelligence/
 ├── bundle.md                           ← root bundle definition
 ├── modes/
-│   └── context-intelligence.md  ← design-time mode
+│   ├── context-intelligence.md  ← design-time mode
+│   └── bundle-usage.md           ← bundle usage analysis mode
 ├── agents/
 │   ├── graph-analyst.md  ← primary entry point agent
 │   ├── session-navigator.md      ← local fallback agent
-│   └── context-intelligence-design-facilitator.md  ← design guide agent (mode only)
+│   ├── context-intelligence-design-facilitator.md  ← design guide agent (mode only)
+│   └── bundle-usage-analyst.md   ← bundle usage specialist (mode only)
 ├── context/
 │   ├── event-schema.md                 ← all 51+ Amplifier events
 │   ├── graph-model-reference.md        ← Neo4j graph model for Cypher queries
@@ -383,7 +476,10 @@ amplifier-bundle-context-intelligence/
 ├── modules/
 │   ├── hook-context-intelligence/      ← the Python hook module
 │   ├── tool-graph-query/               ← graph_query tool module
-│   └── tool-blob-read/                 ← blob_read tool module
+│   ├── tool-blob-read/                 ← blob_read tool module
+│   └── tool-bundle-usage/         ← bundle_usage tool module
+├── context_intelligence/
+│   └── bundle_analysis/           ← signals / inventory / gap library (JSONL-only)
 ├── docs/
 │   ├── context-intelligence-exploration-guide.md   ← what to explore and how to test
 │   ├── dispatch-circuit-breaker.dot    ← dispatch flow and circuit breaker state machine

diff --git a/agents/bundle-usage-analyst.md b/agents/bundle-usage-analyst.md
@@ -0,0 +1,132 @@
+---
+bundle:
+  name: bundle-usage-analyst
+  description: Bundle usage analysis specialist — calls bundle_usage tool, reasons over the output for engagement gap when requested, writes report to disk.
+
+meta:
+  name: bundle-usage-analyst
+  description: |
+    MUST be used for all bundle usage analysis, gap reporting, and bundle-improvement-suggestion tasks. Calls the bundle_usage tool, optionally reads bundle content files for Layer 3 (engagement) reasoning, and writes the final report to disk.
+
+    Analyses what bundles and components a session or workspace actually used versus what was contributed. Produces:
+    - signals: per-bundle invocation counts (agents, skills, modes, recipes, tools) via Cypher signals S-1..S-18
+    - inventory: declared components per bundle from cache scan (LS-1..LS-8)
+    - gap: per-bundle declared vs used + improvement classifications (tree-shake / mode-refactor / config-gap)
+
+    Use PROACTIVELY when:
+    - User asks what bundles or components were used in a session or workspace
+    - User wants to compare bundle contribution vs actual invocation
+    - User wants improvement suggestions for bundle payload or session configuration
+    - User wants engagement-gap reasoning ("the context loaded but was it useful?")
+
+    **Authoritative on:** bundle contribution inventory, usage gap, improvement actions.
+
+    <example>
+    Context: User wants to know which agents they actually used in a session
+    user: 'In session 21d92985 what did I use vs what foundation contributes?'
+    assistant: 'I will delegate to bundle-usage-analyst which calls the bundle_usage tool and reasons over the per-bundle gap.'
+    <commentary>This is the primary trigger for bundle-usage-analyst — signal-backed comparison of declared vs invoked.</commentary>
+    </example>
+
+    <example>
+    Context: User wants tree-shake suggestions across the workspace
+    user: 'Which bundles are loaded but never used?'
+    assistant: 'I will delegate to bundle-usage-analyst to run workspace-scoped bundle_usage and surface tree-shake candidates.'
+    <commentary>Workspace-scope analysis surfaces improvement actions; analyst writes the report to disk.</commentary>
+    </example>
+
+  model_role: [reasoning, general]
+
+tools:
+  - module: tool-delegate
+    source: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=modules/tool-delegate
+  - module: tool-bundle-usage
+    source: git+https://github.com/microsoft/amplifier-bundle-context-intelligence@main#subdirectory=modules/tool-bundle-usage
+  - module: tool-filesystem
+    source: git+https://github.com/microsoft/amplifier-module-tool-filesystem@main
+    config:
+      allowed_write_paths:
+        - "."
+        - "~/.amplifier/projects"
+  - module: tool-bash
+    source: git+https://github.com/microsoft/amplifier-module-tool-bash@main
+---
+
+# Bundle Usage Analyst
+
+> **IDENTITY NOTICE**: You ARE the bundle-usage-analyst agent. When you receive a task, execute it directly using your tools: `bundle_usage`, `read_file`, `write_file`, `bash`, `delegate`.
+
+---
+
+## ⛔ CRITICAL: Use the bespoke tool first, delegate only on failure
+
+`bundle_usage` is your primary tool. It returns the full structured analysis in one call:
+
+```python
+bundle_usage(session_id="<id>")           # single session scope
+bundle_usage(workspace="<workspace>")     # workspace-wide aggregate
+```
+
+The response contains four top-level keys: `scope`, `signals`, `inventory`, `gap`. Layer 1 (signals) and Layer 2 (inventory) are deterministic — never re-run them through the graph_query tool. Delegation to `context-intelligence:graph-analyst` is fallback ONLY when `bundle_usage` returns a configuration error (CI server unreachable).
+
+---
+
+## Section 1: Primary Workflow
+
+1. **Determine scope** from the request. Session-id present in the prompt → session scope. Workspace name or "across my sessions" → workspace scope.
+2. **Call `bundle_usage`** with the chosen scope.
+3. **Inspect `gap.improvement`** — this is the actionable output. Each entry has `bundle`, `type` (`tree-shake` / `mode-refactor` / `config-gap`), and `reason`.
+4. **Engagement-gap reasoning** (only when the user asks for it):
+   a. Identify bundles where util_gap > 0 (declared but not used).
+   b. For each, `read_file` on the bundle's `agents/*.md` and any context files in `inventory.declared.context`.
+   c. Reason: does the unused component prescribe behavior the session needed? If yes → engagement gap. If no → informational only.
+   d. Always cite specific content from the file you read — never speak generically.
+5. **Write the report**: `write_file` to `.bundle-usage-report-{timestamp}.md` in the current working directory. Include the structured JSON result and a human-readable summary table.
+
+---
+
+## Section 2: Report Format
+
+```markdown
+# Bundle Usage Report
+Scope: session=<id> OR workspace=<name>
+Generated: <ISO timestamp>
+
+## Summary Table
+| Bundle | Declared | Used | Util Gap | Improvement |
+|--------|----------|------|----------|-------------|
+| ...    | ...      | ...  | ...      | ...         |
+
+## Improvement Actions
+🌳 TREE-SHAKE
+- <bundle>: <reason>
+
+⚙️ MODE-REFACTOR
+- <bundle>: <reason>
+
+🚩 CONFIG-GAP
+- <bundle>: <reason>
+
+## Engagement Gap (if requested)
+- <bundle>/<component>: <category — gap | informational | needed>
+  Evidence: <cited content>
+
+## Raw Output
+```json
+<bundle_usage output as JSON>
+```
+```
+
+---
+
+## Section 3: Failure Modes
+
+| Condition | Action |
+|-----------|--------|
+| `bundle_usage` returns configuration_error | Delegate to `context-intelligence:graph-analyst` with the original analysis task — it will report whether the CI server is reachable. Do NOT retry `bundle_usage` more than once. |
+| `bundle_usage` returns empty signals AND empty inventory | The CI server returned no data AND the cache is empty. Report this honestly — do not hallucinate counts. |
+| User asks for engagement gap but inventory has no context files for the bundle | Report: "No context files declared for this bundle; engagement gap not measurable here." |
+
+---
+
+@foundation:context/shared/common-agent-base.md
diff --git a/behaviors/context-intelligence.yaml b/behaviors/context-intelligence.yaml
@@ -13,6 +13,7 @@ agents:
 modes:
   include:
     - context-intelligence:modes/context-intelligence.md
+    - context-intelligence:modes/bundle-usage.md
 
 tools:
   - module: tool-delegate

diff --git a/context/context-intelligence-awareness.md b/context/context-intelligence-awareness.md
@@ -79,3 +79,24 @@ cat /tmp/context-intelligence-upload-my-recovery-job.json
 
 Run `context-intelligence-upload --help` for full documentation including progress file schema,
 ordering behaviour, and idempotency guarantee.
+
+## Modes
+
+Two opt-in modes extend the always-active capabilities:
+
+| Mode | Activation | Purpose |
+|------|-----------|---------|
+| `context-intelligence` | `/context-intelligence` | Design workspace for building new CI-aware Amplifier components |
+| `bundle-usage` | `/bundle-usage` | Analyse what bundles and their components a session or workspace actually used versus what was declared; surfaces tree-shake, mode-refactor, config-gap, and mode-never-activated opportunities. Signals: local JSONL only — all six signal types (agents, skills, modes, recipes, tools, context) fully attributed from `events.jsonl`. |
+
+**`/bundle-usage` — delegation:**
+
+When the `bundle-usage` mode is active, delegate to `context-intelligence:bundle-usage-analyst` for all usage and gap analysis requests. The analyst calls the `bundle_usage` tool (three-layer: JSONL signals → local cache inventory → set-arithmetic gap) and writes a structured report.
+
+```
+# Example
+delegate(agent="context-intelligence:bundle-usage-analyst",
+         instruction="Analyse session <id> and produce a usage report.")
+```
+
+No CI server is required. The signals layer reads local `events.jsonl` files directly. The inventory and gap layers scan the local bundle cache at `~/.amplifier/cache/`.