agentbundle 0.38.6__tar.gz → 0.41.1__tar.gz

{agentbundle-0.38.6/agentbundle.egg-info → agentbundle-0.41.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.38.6
+Version: 0.41.1
 Summary: npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent.
 Author-email: eugenelim <eugenelim@users.noreply.github.com>
 License-Expression: Apache-2.0 OR MIT
@@ -34,6 +34,97 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
+## What's new in 0.41.1
+
+The same release as 0.41.0, which never reached PyPI: its release run failed a
+pre-release gate on a faulty performance measurement, so the version exists in
+the internal repository but was never published here. No shipped code differs
+between the two.
+
+## What's new in 0.41.0
+
+`install` and `validate` now accept a skill folder, a `skills/` collection, or a
+single pack taken straight from a repository — no catalogue required. A direct
+source is admitted against explicit shape and size bounds, pinned to the commit
+its bytes came from, and summarised for consent before anything is written.
+
+## What's new in 0.40.3
+
+Catalogue validation now checks bounded reviewer declarations and keeps their
+least-privilege posture in supported adapter projections.
+
+## What's new in 0.40.2
+
+Catalogue seed lint now accepts the core pack's bounded rule router,
+cognitive-load topic, and scoped docs guidance. Undeclared seed paths still
+fail closed.
+
+## What's new in 0.40.1
+
+Workspace MCP lifecycle metadata now dispatches briefs to the canonical
+`author-delivery-brief` owner. Existing workspace kinds, queues, paths, and
+lifecycle semantics are unchanged.
+
+## What's new in 0.40.0
+
+Catalogue builds now produce offline-validatable Agent Plugins 1.0.0 packages
+under `dist/agent-plugins/<pack>/` for every skills-only pack. The new route
+preserves canonical skill bytes and executable bits, emits a privacy-minimal
+root `plugin.json`, and reports every pack excluded by non-portable primitives.
+The paired plugin and MCP schemas are bundled from an immutable upstream commit;
+MCP behavior remains a separate follow-on.
+
+Extension namespaces are closed and allocation-gated. Kiro and Copilot are
+reserved, while active namespaces must name a versioned schema before their
+manifest data or files can enter a portable artifact.
+
+## What's new in 0.39.4
+
+Codex-projected agents that declare `Read`, `Grep`, or `Glob` without `Bash`
+can read and search local files again. AgentBundle now retains Codex's default
+shell tool for those read intents while confining the agent to a read-only
+sandbox; write and web capabilities still require their corresponding source
+declarations.
+
+Kiro IDE and CLI agents may also declare `resources: []` to suppress the
+default skill-resource injection without emitting an empty consumer field. The
+portable way to say the same thing is Claude Code's own `skills: []`, which now
+suppresses that injection too — a non-empty `skills` list is a build error until
+`skill://` URI templating exists.
+
+**Breaking for Kiro agent sources:** the Kiro projectors now bound the field set
+they emit rather than passing unmapped source frontmatter through verbatim.
+Claude Code fields Kiro cannot read (`permissionMode`, `memory`, `maxTurns`, …)
+and IDE-only keys that make the CLI loader drop an agent (`hooks`) are dropped,
+each with a `kiro: dropping … agent field` line on stderr. If you relied on the
+previous pass-through, check your build log after upgrading.
+## What's new in 0.39.3
+
+The bundled workspace-status engine now recognizes reviewed legacy work-intake
+migrations, validates durable operation digests, and refuses linked or aliased
+workspace input before projecting exact legacy bytes.
+
+## What's new in 0.39.2
+
+Level A packs can now provide an optional manual next step after installation.
+When present, `agentbundle install` prints it after `Verify:`, so packs can guide
+adopters even when a runtime hook does not execute. Existing packs without the
+field keep their current output, and Level B packs still require it.
+
+## What's new in 0.39.1
+
+Catalogue seed lint now rejects generic directory-tree placeholders unless the
+architecture overview also explains each area's responsibility and change
+guidance. This keeps generated starter repositories useful without assuming a
+particular application layout.
+
+## What's new in 0.39.0
+
+Catalogue builders can now inspect a first-class, schema-validated distribution
+route contract for the existing APM and Claude-plugin package formats. Recipes
+name their route explicitly and fail before writing on inconsistent route data;
+the emitted package trees and direct-install behavior are unchanged.
+
 ## What's new in 0.38.6
 
 Catalogue authors can now read the profile schema from initialized catalogues
@@ -144,10 +235,11 @@ agentbundle catalogue index . --output catalogue-index.json
 
 ## Contract discovery
 
-The bundled public contract inventory includes `catalogue-index.schema.json` as
-the closed contract for generated neutral indexes. It also includes the strict
-`knowledge-captured-observation.schema.json` contract used by the core pack's
-project-knowledge capture handoff.
+The bundled public contract inventory includes `distribution-routes.toml` and
+its closed schema for package-route semantics, plus
+`catalogue-index.schema.json` for generated neutral indexes. It also includes
+the strict `knowledge-captured-observation.schema.json` contract used by the
+core pack's project-knowledge capture handoff.
 
 You can inspect the exact public contracts bundled with the installed
 AgentBundle version without network access:

{agentbundle-0.38.6 → agentbundle-0.41.1}/README-pypi.md

@@ -14,6 +14,97 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
+## What's new in 0.41.1
+
+The same release as 0.41.0, which never reached PyPI: its release run failed a
+pre-release gate on a faulty performance measurement, so the version exists in
+the internal repository but was never published here. No shipped code differs
+between the two.
+
+## What's new in 0.41.0
+
+`install` and `validate` now accept a skill folder, a `skills/` collection, or a
+single pack taken straight from a repository — no catalogue required. A direct
+source is admitted against explicit shape and size bounds, pinned to the commit
+its bytes came from, and summarised for consent before anything is written.
+
+## What's new in 0.40.3
+
+Catalogue validation now checks bounded reviewer declarations and keeps their
+least-privilege posture in supported adapter projections.
+
+## What's new in 0.40.2
+
+Catalogue seed lint now accepts the core pack's bounded rule router,
+cognitive-load topic, and scoped docs guidance. Undeclared seed paths still
+fail closed.
+
+## What's new in 0.40.1
+
+Workspace MCP lifecycle metadata now dispatches briefs to the canonical
+`author-delivery-brief` owner. Existing workspace kinds, queues, paths, and
+lifecycle semantics are unchanged.
+
+## What's new in 0.40.0
+
+Catalogue builds now produce offline-validatable Agent Plugins 1.0.0 packages
+under `dist/agent-plugins/<pack>/` for every skills-only pack. The new route
+preserves canonical skill bytes and executable bits, emits a privacy-minimal
+root `plugin.json`, and reports every pack excluded by non-portable primitives.
+The paired plugin and MCP schemas are bundled from an immutable upstream commit;
+MCP behavior remains a separate follow-on.
+
+Extension namespaces are closed and allocation-gated. Kiro and Copilot are
+reserved, while active namespaces must name a versioned schema before their
+manifest data or files can enter a portable artifact.
+
+## What's new in 0.39.4
+
+Codex-projected agents that declare `Read`, `Grep`, or `Glob` without `Bash`
+can read and search local files again. AgentBundle now retains Codex's default
+shell tool for those read intents while confining the agent to a read-only
+sandbox; write and web capabilities still require their corresponding source
+declarations.
+
+Kiro IDE and CLI agents may also declare `resources: []` to suppress the
+default skill-resource injection without emitting an empty consumer field. The
+portable way to say the same thing is Claude Code's own `skills: []`, which now
+suppresses that injection too — a non-empty `skills` list is a build error until
+`skill://` URI templating exists.
+
+**Breaking for Kiro agent sources:** the Kiro projectors now bound the field set
+they emit rather than passing unmapped source frontmatter through verbatim.
+Claude Code fields Kiro cannot read (`permissionMode`, `memory`, `maxTurns`, …)
+and IDE-only keys that make the CLI loader drop an agent (`hooks`) are dropped,
+each with a `kiro: dropping … agent field` line on stderr. If you relied on the
+previous pass-through, check your build log after upgrading.
+## What's new in 0.39.3
+
+The bundled workspace-status engine now recognizes reviewed legacy work-intake
+migrations, validates durable operation digests, and refuses linked or aliased
+workspace input before projecting exact legacy bytes.
+
+## What's new in 0.39.2
+
+Level A packs can now provide an optional manual next step after installation.
+When present, `agentbundle install` prints it after `Verify:`, so packs can guide
+adopters even when a runtime hook does not execute. Existing packs without the
+field keep their current output, and Level B packs still require it.
+
+## What's new in 0.39.1
+
+Catalogue seed lint now rejects generic directory-tree placeholders unless the
+architecture overview also explains each area's responsibility and change
+guidance. This keeps generated starter repositories useful without assuming a
+particular application layout.
+
+## What's new in 0.39.0
+
+Catalogue builders can now inspect a first-class, schema-validated distribution
+route contract for the existing APM and Claude-plugin package formats. Recipes
+name their route explicitly and fail before writing on inconsistent route data;
+the emitted package trees and direct-install behavior are unchanged.
+
 ## What's new in 0.38.6
 
 Catalogue authors can now read the profile schema from initialized catalogues
@@ -124,10 +215,11 @@ agentbundle catalogue index . --output catalogue-index.json
 
 ## Contract discovery
 
-The bundled public contract inventory includes `catalogue-index.schema.json` as
-the closed contract for generated neutral indexes. It also includes the strict
-`knowledge-captured-observation.schema.json` contract used by the core pack's
-project-knowledge capture handoff.
+The bundled public contract inventory includes `distribution-routes.toml` and
+its closed schema for package-route semantics, plus
+`catalogue-index.schema.json` for generated neutral indexes. It also includes
+the strict `knowledge-captured-observation.schema.json` contract used by the
+core pack's project-knowledge capture handoff.
 
 You can inspect the exact public contracts bundled with the installed
 AgentBundle version without network access:

{agentbundle-0.38.6 → agentbundle-0.41.1}/README.md

@@ -43,7 +43,7 @@ The install auto-detects your agent (`--adapter` overrides). Multi-IDE? Install
 agentbundle list-packs
 agentbundle list-profiles
 
-# See what a single pack contains — skills and agents, derived live from its tree
+# See what a single pack contains — inventory and catalogue metadata, derived live
 agentbundle show core
 agentbundle show core --format json          # stable object for scripts/agents
 
@@ -72,7 +72,18 @@ agentbundle uninstall --pack core --yes
 
 **`list-installed`** reads your state files (not the catalogue) and reports every installed `(pack, adapter)` at each scope with its version and a four-value status — `up-to-date`, `upgrade-available`, `ahead` (installed version is newer than catalogue), or `unknown`; it degrades to `unknown` (never an error) when the catalogue can't be resolved, and `--no-check` skips the check entirely. `--format json` emits a stable JSON contract (`schema_version: 1`) to stdout — useful for CI automation of upgrade decisions. `--updates-only` hides `up-to-date` rows.
 
-**`show <pack>`** answers "what skills and agents does this pack contain?" by walking the pack's source tree live on each call — so the answer can't drift, and nothing is persisted. `--format json` emits a stable object (`name`, `version`, `description`, `skills`, `agents`, `source`) for scripts and agents. When the catalogue can't be resolved, an *installed* pack still reports its inventory from your state files (marked `source: installed-state`); a not-installed pack errors.
+**`show <pack>`** answers "what does this pack contain?" by walking the pack's
+source tree live on each call, so the answer cannot drift and nothing is
+persisted. `--format json` retains the ordinary `name`, `version`,
+`description`, `skills`, `agents`, `integrations`, and `source` fields and adds
+`pack_metadata`, per-Skill `skill_metadata`, and declared OKF `knowledge` for a
+live catalogue. Those three rich metadata fields are **pre-release**: they are
+source-backed only for live catalogue reads and are not a cross-pack OKF index.
+It is one-pack-at-a-time and read-only: it does not compile
+knowledge, run pack code, or fetch remote OKF content. When the catalogue cannot
+be resolved, an *installed* pack still reports its inventory from state files
+(marked `source: installed-state`), while `pack_metadata`, `skill_metadata`, and
+`knowledge` are exactly `null`; a not-installed pack errors.
 
 A **profile** is a catalogue-curated, single-scope set of packs you install in one command — it declares its own scope, so `--scope` doesn't apply. **Upgrade takes no version** — the target is whatever the catalogue you point at declares; to pin a past version, point the catalogue at that git ref. Install a pack that's **already there** and `agentbundle` offers to `upgrade` it instead (`--yes` runs it straight away).
 

{agentbundle-0.38.6 → agentbundle-0.41.1}/agentbundle/_data/adapter.schema.json

@@ -1,4 +1,5 @@
 {
+  "x-spec": "docs/specs/distribution-route-contract",
   "type": "object",
   "required": ["contract", "primitive", "adapter"],
   "properties": {
@@ -54,25 +55,6 @@
                   ]
                 },
                 "target-path": {"type": "string"},
-                "plugin-target-path": {"type": "string"},
-                "plugin-mode": {
-                  "type": "string",
-                  "enum": [
-                    "direct-directory",
-                    "direct-file",
-                    "merge-json",
-                    "user-merge-json",
-                    "merge-into-agent-json",
-                    "instruction-file",
-                    "managed-block-inline",
-                    "degraded-info-log",
-                    "dropped",
-                    "codex-agent-toml",
-                    "copilot-agent-md",
-                    "copilot-hooks-json",
-                    "gemini-command-toml"
-                  ]
-                },
                 "on-conflict": {
                   "type": "string",
                   "enum": [
@@ -251,13 +233,6 @@
                 }
               }
             }
-          },
-          "install-routes": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "enum": ["cli", "claude-plugins", "apm"]
-            }
           }
         }
       }

{agentbundle-0.38.6 → agentbundle-0.41.1}/agentbundle/_data/adapter.toml

@@ -180,38 +180,29 @@ source-path = ".apm/user-libs/"
 # entries remain authoritative; the new tables are declarative metadata.
 # ---------------------------------------------------------------------------
 
-# Install routes declared for this adapter ("claude-plugins" at v0.4;
-# "apm" added at v0.5).
-# Kiro, Copilot, and Codex do not declare install-routes; the field defaults to ["cli"]
-# on read for adapters that omit it.
 [adapter."claude-code"]
-install-routes = ["cli", "claude-plugins", "apm"]
 
 [[adapter."claude-code".projection]]
 primitive = "skill"
 mode = "direct-directory"
 target-path = ".claude/skills/"
-plugin-target-path = "skills/"
 on-conflict = "prompt-then-preserve"
 
 [[adapter."claude-code".projection]]
 primitive = "agent"
 mode = "direct-file"
 target-path = ".claude/agents/"
-plugin-target-path = "agents/"
 on-conflict = "prompt-then-preserve"
 
 [[adapter."claude-code".projection]]
 primitive = "hook-body"
 mode = "direct-file"
 target-path = "tools/hooks/"
-plugin-target-path = "hooks/"
 on-conflict = "prompt-then-preserve"
 
 [[adapter."claude-code".projection]]
 primitive = "hook-wiring"
 mode = "merge-json"
-plugin-mode = "dropped"
 target-path = ".claude/settings.local.json"
 managed-key = "hooks"
 on-conflict = "merge-managed-key-only"
@@ -220,7 +211,6 @@ on-conflict = "merge-managed-key-only"
 primitive = "command"
 mode = "direct-file"
 target-path = ".claude/commands/"
-plugin-target-path = "commands/"
 on-conflict = "prompt-then-preserve"
 
 # hook-body — scope-conditional target.
@@ -361,7 +351,12 @@ frontmatter-mapping = "kiro-ide-agent-frontmatter-v0.9"
 # #4993). Inject the same fixed skill-resources glob as kiro-cli; the IDE
 # agent `resources` field is documented and `skill://`-aware, so it does not
 # trip the silent-drop bug (that's for non-schema keys like `hooks`). Emitted
-# into the `.md` YAML frontmatter, quoted. Author override wins.
+# into the `.md` YAML frontmatter, quoted. Author override wins; an explicit
+# empty `resources` list suppresses injection and is omitted from output, and so
+# does Claude Code's `skills: []` — the portable form of the same intent, since
+# `resources` is Kiro-native and not valid Claude Code agent frontmatter. A
+# non-empty `skills` list is a build error: turning a bare skill name into a
+# `skill://` URI needs templating this mapping grammar cannot express.
 inject-resources = ["skill://.kiro/skills/**/SKILL.md", "skill://~/.kiro/skills/**/SKILL.md"]
 on-conflict = "prompt-then-preserve"
 
@@ -437,8 +432,21 @@ frontmatter-mapping = "kiro-cli-agent-frontmatter-v1.0"
 # `--agent` run sees zero skills unless the agent declares them. Inject this
 # fixed skill-resources glob (both install scopes) into every projected agent.
 # Skipped when the agent source already declares its own `resources` (author
-# override wins). kiro-ide carries the same field on its own agent projection
+# override wins); an explicit empty list suppresses injection and is omitted, as
+# does the portable Claude Code `skills: []` opt-out (see the kiro-ide entry).
+# kiro-ide carries the same field on its own agent projection
 # entry (emitted into `.md` frontmatter rather than JSON).
+#
+# Both Kiro agent projectors rewrite the *source frontmatter* and pass unmapped
+# keys through, unlike codex/copilot/cursor/gemini which iterate this mapping and
+# so drop anything unmapped. That is what admits a Kiro-native `resources` or
+# `prompt`, but it also means an unmapped key would reach the consumer verbatim.
+# `_CLI_AGENT_FIELDS` / `_IDE_AGENT_FIELDS` in `adapters/kiro.py` bound the
+# emitted shape and log every drop, so Claude Code fields Kiro cannot read
+# (`permissionMode`, `memory`, `maxTurns`) and IDE-only fields that make the CLI
+# loader silently drop an agent (`hooks`) stay out of the output. `skills` is
+# not among them: it is consumed as the portable no-skill opt-out before that
+# bound applies, so it is never emitted and never logged as a drop.
 inject-resources = ["skill://.kiro/skills/**/SKILL.md", "skill://~/.kiro/skills/**/SKILL.md"]
 on-conflict = "prompt-then-preserve"
 
@@ -789,7 +797,13 @@ allowed-prefixes.user = [".agents/skills/", ".gemini/", ".agentbundle/"]
 # ---------------------------------------------------------------------------
 
 # Kiro agent frontmatter v0.9: renames Claude Code agent fields to Kiro's schema.
-# Adapters consume this table generically; no field dictionary hardcoded in Python.
+# Adapters consume the RENAME/NORMALIZE/VALUES rules below generically — no
+# per-field rename dictionary is hardcoded in Python. The emitted field *set* is
+# a separate concern and is bounded in `adapters/kiro.py` (`_IDE_AGENT_FIELDS` /
+# `_CLI_AGENT_FIELDS`), because these projectors iterate source frontmatter and
+# would otherwise pass unmapped keys through verbatim. A rename target added
+# here must also be a member of that set or the rule is a silent no-op;
+# `test_adapter_kiro_cli.py` / `test_adapter_kiro_ide.py` assert that coupling.
 [frontmatter-mapping."kiro-ide-agent-frontmatter-v0.9"]
 
 [frontmatter-mapping."kiro-ide-agent-frontmatter-v0.9".description]
@@ -845,6 +859,9 @@ values = { opus = "claude-opus-4.6", sonnet = "claude-sonnet-4.5", haiku = "clau
 # `codex-agent-toml` projection reduces duplicate intents to documented
 # config keys (`sandbox_mode`, `[features].shell_tool`, `web_search`,
 # `[tools].web_search`) and never emits a generic `tools = [...]` array.
+# Codex has no named Read/Grep/Glob tool allowlist, so any mapped `read`
+# intent retains the default shell tool inside `sandbox_mode = "read-only"`;
+# mapped `write` remains the only route to a writable sandbox.
 # The markdown body lands in TOML `developer_instructions` via a
 # mode-level convention in the `codex-agent-toml` projection mode, NOT
 # via a rename rule (frontmatter mapping is keyed on frontmatter fields;

agentbundle-0.41.1/agentbundle/_data/agent-plugin-extension-namespaces.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agent-plugin-extension-namespaces.schema.json",
+  "x-spec": "docs/specs/portable-agent-plugin-projection",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contract", "namespace"],
+  "properties": {
+    "contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version"],
+      "properties": {
+        "version": {"type": "string", "enum": ["1.0"]}
+      }
+    },
+    "namespace": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["owner", "state"],
+        "properties": {
+          "owner": {"type": "string", "minLength": 1},
+          "state": {"type": "string", "enum": ["reserved", "active"]},
+          "schema": {
+            "type": "string",
+            "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[a-zA-Z0-9._/-]+/v?[0-9]+(?:\\.[0-9]+)*/[a-zA-Z0-9._-]+\\.schema\\.json$"
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {"state": {"const": "active"}},
+              "required": ["state"]
+            },
+            "then": {"required": ["schema"]}
+          },
+          {
+            "if": {
+              "properties": {"state": {"const": "reserved"}},
+              "required": ["state"]
+            },
+            "then": {"not": {"required": ["schema"]}}
+          }
+        ]
+      }
+    }
+  }
+}

agentbundle-0.41.1/agentbundle/_data/agent-plugin-extension-namespaces.toml

@@ -0,0 +1,12 @@
+# Agent Plugins extension namespace allocation contract.
+
+[contract]
+version = "1.0"
+
+[namespace."com.github.copilot"]
+owner = "copilot-profile"
+state = "reserved"
+
+[namespace."dev.kiro"]
+owner = "kiro-profile"
+state = "reserved"

{agentbundle-0.38.6 → agentbundle-0.41.1}/agentbundle/_data/catalogue-scaffold/guides/_shared/reference/catalogue-authoring-standards.md

@@ -266,10 +266,10 @@ tooling. Neither is a root `tests/` tree; a catalogue that wants the separate
 tree can add one. Don't create a top-level directory for a single test — the
 ownership rule is what matters, not the path.
 
-### One test process per skill
+### One test process per skill, unless a compatibility class says otherwise
 
-Run each skill's suite in its own process. This is a correctness requirement,
-not a performance preference.
+Each skill's suite runs in its own process by default. This is a correctness
+default, not a performance preference, and a new suite gets it without asking.
 
 Skills are independent, so two of them may reasonably ship a `render.py`, and
 their suites may both be called `test_render.py`. Collect them into one pytest
@@ -278,19 +278,57 @@ run and two things break: pytest refuses the duplicate test basenames outright
 would serve every suite that expects its own.
 
 ```
-pytest packs/<pack>/tests/skills/<skill>/     # one invocation per skill
+pytest packs/<pack>/tests/skills/<skill>/     # the default: one per skill
 ```
 
-An invocation that spans two skill test directories is safe only while their
-basenames happen not to collide — which is a property of today's contents, not
-of the layout. Keep the invocations separate and the question never arises.
+A single process may cover several suites only when they form an explicitly
+declared **compatibility class**. A class:
+
+- lives entirely inside one pack — the pack stays the execution boundary;
+- names its exact member paths, never an ancestor directory, so a suite added
+  later cannot join it silently;
+- declares how duplicate test basenames are resolved and which pytest flags the
+  grouping requires;
+- is re-derived from source by a fail-closed gate on every run, so it stops
+  being valid the moment a member stops being safe.
+
+A grouping justified only by "nothing collides today" is not a class. That is a
+property of the current contents, not of the layout.
+
+**How to prove a class before declaring it.** Collect each member alone, then
+collect the group, and compare the node-ID sets:
+
+```
+pytest <member> --collect-only -q          # once per member; union the output
+pytest <member-1> <member-2> … --collect-only -q
+```
+
+The union must equal the grouped set exactly, and the raw line count must equal
+the unique count on both sides — otherwise something is collected twice. Repeat
+the grouped command with the members in reverse order; a difference means an
+import in one member is deciding what another member sees. Any suite that needs
+a flag to collect cleanly must carry that flag in the runner, and the class
+should record why.
+
+That is the test-module half. The subject half is separate, and no collection
+comparison can see it: two suites can bind the same module object and still
+produce identical node IDs.
+
+Retaining isolation is a valid result. A suite that needs a clean interpreter,
+carries a collection floor, or reaches a subject through `sys.path` should stay
+in its own process, and saying so is engineering rather than a failure to
+optimise.
+
+Record the decision behind each class where your repository keeps decisions,
+and keep the class declaration itself next to the gate that enforces it.
 
 ### Write suites that do not depend on isolation
 
-Process isolation is the guarantee above. It is not a licence to write suites
+Process isolation is the default above. It is not a licence to write suites
 that only work because they run alone — a suite that depends on being the sole
 occupant of an interpreter is fragile even when isolated, because collection
-order inside its own directory can still decide a binding.
+order inside its own directory can still decide a binding. It is also what
+keeps a suite eligible to join a compatibility class later.
 
 Two collisions matter, and they are not the same:
 
@@ -304,6 +342,17 @@ Two collisions matter, and they are not the same:
   collision is in the interpreter's module namespace rather than in pytest's
   collection.
 
+These are separate obligations, and solving one proves nothing about the other.
+`--import-mode=importlib` gives two same-named *test* modules distinct
+identities; it does **not** touch subject-module identity, and must never be
+offered as a fix for it. Where two suites already carry `__init__.py` and their
+shared parent does not, the test-module half is resolved by that packaging
+alone and no flag is needed.
+
+The subject rule is that one module name maps to exactly one path. Two suites
+loading the *same* file under one name is idempotent and safe; one name
+resolving to two different files is the silent failure above.
+
 Load a subject module under a name that includes its pack and skill:
 
 ```python
@@ -323,6 +372,15 @@ module that an agent can still invoke directly — while making the test's
 binding explicit rather than positional. Apply the same rule to shared test
 helpers, which collide across packs for exactly the same reason.
 
+Do not repackage a runtime payload to suit a test. Hyphenated skill directories
+and standalone scripts under `.apm/skills/<skill>/scripts/` are valid runtime
+shapes; the test adapts to them, not the other way round.
+
+Remember that a suite's import set is larger than its test files. A
+`conftest.py` is loaded even for a single-file invocation, so a `sys.path`
+mutation there applies to everything the process runs afterwards — which is
+where this hazard usually lives.
+
 ### Keep a suite's cost in assertions, not in processes
 
 A test that spawns a process pays for an interpreter start, imports, and
@@ -344,6 +402,18 @@ asserting — so it grows worse on a loaded machine, not better.
 
 - A pack **MUST** be the ownership boundary for its tests.
 - Pack-specific tests **MUST** live under `packs/<pack>/tests/`.
+- A pack test suite **MUST** run in its own pytest process unless it is named
+  in an explicitly declared compatibility class.
+- A compatibility class **MUST NOT** span packs, **MUST** name its exact member
+  paths rather than an ancestor directory, and **MUST** be re-derived from
+  source by a fail-closed gate rather than trusted as a standing permission.
+- A suite bearing a collection floor **MUST** remain the sole target of its own
+  invocation, because the floor counts a whole pytest session.
+- Test-module identity and subject-module identity **MUST** be proven
+  separately; `--import-mode=importlib` **MUST NOT** be used as evidence about
+  subject modules.
+- A runtime payload under `.apm/` **MUST NOT** be repackaged to make tests
+  cohabit.
 - Ordinary tests **MUST NOT** live under `.apm/`.
 - `.apm/` **MUST** contain only runtime or projectable content.
 - Agent evaluations **MUST** live under `.apm/skills/<skill>/evals/` and stay

{agentbundle-0.38.6 → agentbundle-0.41.1}/agentbundle/_data/catalogue-scaffold/manifest.json

@@ -1,14 +1,14 @@
 {
   "files": {
-    "guides/_shared/reference/catalogue-authoring-standards.md": "d054430740c6230ccf1e733350a7e970746a3df0af5daa52d8fc7368e2ff4df0",
+    "guides/_shared/reference/catalogue-authoring-standards.md": "4e8bf28a1c4a6861bcfb3028a971163e0250c7db67be2fc32b6ea23f5d1fd547",
     "guides/_shared/reference/catalogue-ci-contract.md": "fae793ab47989b6dd3c731afcb0b4cda21c7d08bbe7fa40fca6d3abb3d158141",
     "packs/AGENTS.md": "c20af03f72b4c25c032ba5c15299eadaa0b41442c92d1cf621dde042cf9ff8db",
     "packs/README.md": "d2de5f9556f4c8e521103474bde74636e02cc805f9bf5312a3a61a1f3eb45d8f",
-    "packs/_example/.apm/skills/example-skill/SKILL.md": "33be8cbf4b2c014a5a63e788b7d0b350ad8061c6c4b2579369a3e984135bf9f1",
+    "packs/_example/.apm/skills/example-skill/SKILL.md": "e7e23d478278d4edefbf5aade77d1eefedeecf470ac2be2e32e385fafebc53a0",
     "packs/_example/.apm/skills/example-skill/evals/eval_queries.json": "f41ecda0834a22f3b4823c81ab02e58b0e4beba610e3b40c185579abff9cfeee",
-    "packs/_example/.claude-plugin/plugin.json": "7f94084a56260eed225ec47ac82042fe9029c594557cca760a459885d03ccc26",
+    "packs/_example/.claude-plugin/plugin.json": "f67fc61dddf93068395140546683689240d1b5f9de77e4bd98e85de77789c26b",
     "packs/_example/README.md": "ef130c9c1f97a75a07cc59fc55fc5b3bf71846dd2f06c3cddf5a1154023b6ef6",
-    "packs/_example/pack.toml": "f19a0be9fca99a6a0e3ce2d5cd188bf98000f0a4f186954fb42a0c99c6859701",
+    "packs/_example/pack.toml": "3834ecbdcfc8184d31412526bc97ed9e9ed4c41c1e65b00e6c1cc19748e11888",
     "profiles/AGENTS.md": "34fba229a4e8bd1b6efc948d3e1d51d9d47f88826897c259909e0a1fd2672a5e",
     "profiles/README.md": "a0b0268edc57fc575f7fea08f3363ba7da9f6e67dc4a0a6f8bd38c9668c97922",
     "profiles/_example/README.md": "164494df049ddce3e57cb44ed604cb3d39be0a6ec2072e609ea3fa4bbfc74c72",