feat(bundle): context-intelligence opt-in dispatch filtering — workspace pattern filter and dispatch gate

[colombod]

Summary

This PR implements a config schema restructure and introduces workspace filtering to the Context Intelligence server dispatch system:

• Config restructure (breaking): Flat config keys (context_intelligence_server_url, context_intelligence_api_key) move into a nested server: block with url and api_key subkeys
• Workspace filtering (new): Deny-all-by-default include and exclude pattern lists under server:, using fnmatch glob syntax (e.g. -home-user-*, *-secrets)
• Union semantics across layers: All three configuration sources (hook config, coordinator config, env vars) union their patterns — nothing is overridden, all patterns accumulate
• Upload CLI filtering: New context-intelligence-upload command gains repeatable --include/--exclude flags and corresponding env var support
• Improved diagnostics: forwarding_blocked_reason property on ConfigResolver returns specific denial messages instead of generic ones

---

What Changed in Detail

Config Restructure (Breaking)

Before (on main):

hooks:
  - module: hook-context-intelligence
    config:
      context_intelligence_server_url: "${AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_URL:}"
      context_intelligence_api_key: "${AMPLIFIER_CONTEXT_INTELLIGENCE_API_KEY:}"
      workspace: "${AMPLIFIER_CONTEXT_INTELLIGENCE_WORKSPACE:}"
      log_level: ...

After (this PR):

hooks:
  - module: hook-context-intelligence
    config:
      server:
        url: "${AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_URL:}"
        api_key: "${AMPLIFIER_CONTEXT_INTELLIGENCE_API_KEY:}"
        # include: []   # uncomment to enable forwarding (deny-all by default)
        # exclude: []   # uncomment to exclude patterns
      workspace: "${AMPLIFIER_CONTEXT_INTELLIGENCE_WORKSPACE:}"
      log_level: ...

Workspace Filtering (New)

Deny-all-by-default: Nothing dispatches to the server unless include patterns are configured. This is an intentional breaking change to support workspace opt-in security.

Pattern matching: Patterns use fnmatch glob syntax (e.g. -home-user-*, work-*, *-secrets). Workspace names are slugified working directory paths (e.g. /home/alice/work/my-api becomes -home-alice-work-my-api).

Union semantics: All include and exclude patterns are unioned across configuration sources:

• Hook config server.include / server.exclude
• Coordinator config (if any)
• Environment variables: AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_INCLUDE / _EXCLUDE (comma-separated)

Resolution order (first match blocks):

Step	Condition	Result
1	include patterns absent across all layers	Blocked (deny-all default)
2	workspace matches no include pattern	Blocked (not opted in)
3	workspace matches any exclude pattern	Blocked (deny trims include)
4	otherwise	Dispatches

Upload CLI Filtering (New)

context-intelligence-upload gains new repeatable --include/--exclude flags:

context-intelligence-upload --include work-* --include personal-* --exclude work-scratch-*

Environment variable support: AMPLIFIER_CONTEXT_INTELLIGENCE_SERVER_INCLUDE and _EXCLUDE (comma-separated). Same deny-all default — no --include = nothing uploaded, with a clear warning to stderr.

Improved Diagnostics

New forwarding_blocked_reason property on ConfigResolver returns a specific denial message:

• "no include patterns configured (deny-all default)" — no include patterns found in any layer
• "workspace 'X' does not match any server.include pattern" — workspace not in include list
• "workspace 'X' is excluded by server.exclude pattern 'Y'" — excluded by deny list

---

Breaking Changes

Existing settings.yaml files must migrate from the old flat schema to the new nested schema:

Before (current main)

overrides:
  hook-context-intelligence:
    config:
      context_intelligence_server_url: "http://localhost:8000"
      context_intelligence_api_key: "my-key"

After (this PR)

overrides:
  hook-context-intelligence:
    config:
      server:
        url: "http://localhost:8000"
        api_key: "my-key"
        include: ["work-*", "personal-*"]   # opt-in workspaces
        exclude: ["work-scratch-*"]         # deny-trim the include list

---

Verification Status

All test suites passing:

• 357 tests in hook module (deny-all logic, pattern matching, dispatch gate)
• 186 tests in upload CLI module (include/exclude flags, env var handling, filter semantics)

DTU validation: All 3 filter scenarios confirmed live against the production CI server:

• Include patterns match → dispatches
• Include patterns don't match → blocked
• Exclude pattern trims include → blocked

Code quality: ruff check and ruff format pass across all 27 changed files; pyright type checking clean.

---

Migration Guide

See docs/designs/2026-05-28-context-intelligence-include-exclude.md for the complete migration guide.

Quick migration (1-2 min):

1. Locate your settings.yaml file (typically ~/.amplifier/settings.yaml)
2. Replace flat keys with nested server: block
3. Add include: patterns for workspaces you want to dispatch
4. Optional: add exclude: patterns to deny-trim your include list

---

Stats

• 27 files changed, 2138 insertions, 155 deletions
• 357 tests passing (hook module)
• 186 tests passing (upload CLI)

---

Generated with Amplifier

[bkrabach]

Reviewed for parent_id propagation impact. Core logic is sound; deny-all default is the correct security posture. Three concrete concerns before merge:

1. Silent-failure mode on config migration. Old flat keys (context_intelligence_server_url, context_intelligence_api_key) are gone. Any settings.yaml or bundle config that still uses the flat keys gets silent dispatch-disabled — no warning, no error. The handler logs at DEBUG when forwarding is blocked. Recommend upgrading to INFO on the first dispatch-block per session minimum, ideally a one-time WARNING the first time forwarding_enabled=False is observed in a session that previously had it True. Operators should see this without grepping debug logs.

2. Missing combined test for parent_id × forwarding_enabled. test_config_resolver.py covers parent_id parsing in isolation. test_logging_handler_server_dispatch.py covers dispatch with _FakeResolver(forwarding_enabled=True) hardcoded. There's no test exercising the combined path: parent_id in config + workspace in allow_workspaces + parent_id visible in the server dispatch payload. That's the path that matters for CR-1; adding one test would lock it down.

3. Environment audit before merge. Any DTU profile or settings.yaml using the old flat keys goes silent on the server side after merge. Worth a one-pass grep -r context_intelligence_server_url across known consumers (resolve-stack.yaml, bundle-resolve profiles, internal DTU profiles) and migrating them in the same PR or as immediate follow-ups.

JSONL parent_id write is unaffected by all of the above — that path is before the filter evaluates. Server-side delivery is the operational caveat.

Otherwise approved.

[colombod]

All three concerns addressed in commits 941533a and a530386:

1. Silent-failure WARNING — LoggingHandler now logs at WARNING (once per session, guarded by _warned_no_dispatch) when the server URL is configured but dispatch is blocked. Message includes the workspace name and migration hint for users on old flat config keys. Two new tests: one asserts the WARNING fires on the first blocked event, one asserts it does not repeat.

2. parent_id × forwarding_enabled combined test — Added TestParentIdForwardingCombined using a real ConfigResolver (not _FakeResolver) with nested context_intelligence_server config, parent_id: "test-parent-abc-123", and workspace: "work-myapi" in allow_workspaces. Asserts forwarding_enabled is True, resolver.parent_id resolves correctly, and the dispatch payload carries parent_id through the CR-1 path.

3. Environment audit — Full grep across all source files, tests, and DTU profiles. The only real stale reference was the example config in the upload CLI's help text (cli.py lines 180-181). Updated to show the nested context_intelligence_server: format with commented allow_workspaces stub. New test asserts the nested key is present in help output and the old flat keys are absent. All _FakeResolver / SimpleNamespace references in test files use the property names (unchanged), not config keys — those are correct as-is.

331/331 hook tests passing, 162/162 upload tool tests passing.