agentbundle 0.29.0__tar.gz → 0.29.2__tar.gz

{agentbundle-0.29.0 → agentbundle-0.29.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.29.0
+Version: 0.29.2
 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: Apache-2.0 OR MIT
@@ -289,6 +289,15 @@ agentbundle catalogue self-host --check --root .
 
 Exits non-zero if any projected file is out of date. Safe to run in CI as a required check; use `--write` locally to regenerate.
 
+By default projects for `claude-code` and `codex`. Downstream repos that use a single adapter (e.g. `kiro-ide`) can declare it in `catalogue.toml` — only that adapter is then projected, and its output files participate in the drift check:
+
+```toml
+[distribution.agentbundle]
+preferred-adapter = "kiro-ide"
+```
+
+When `preferred-adapter` names an adapter not in the upstream `SELF_HOST_ADAPTERS` list, the self-host engine switches to single-adapter mode: only the named adapter is projected; Claude Code-specific artifacts (`.claude/`, `.codex/`, `.claude-plugin/`, `CLAUDE.md`) are neither written nor drift-checked.
+
 **Run Tier-A activation evals** to measure whether each covered skill fires on the prompts it should:
 
 ```bash
@@ -349,15 +358,23 @@ each Claude Code session. It exposes six tools over MCP stdio:
 python3 -m agentbundle.workspace_mcp
 ```
 
+> **Trusted checkout only.** This form runs whichever `agentbundle` is on
+> `sys.path`. If the repo uses an editable install (`pip install -e .`), it
+> runs the local checkout's code. Use only on repos you trust. An isolated
+> spawn mode (`python3 -I -m agentbundle.workspace_mcp`) is planned for
+> Stage 2 and will require a stable non-editable install.
+
 **Inject the session instruction** so the agent knows to use the tools:
 
 ```python
 from agentbundle.workspace_mcp import DEFAULT_SESSION_INSTRUCTION
 ```
 
-Pass `WORKSPACE_MCP_SPEC_PATH` (path to the spec directory) and
-`WORKSPACE_MCP_DISPATCHED_ITEM` (`ini_slug/type:slug`) as environment variables
-when spawning to unlock the git write tools and FSM event tracking.
+Pass exactly one environment variable when spawning to set the session mode:
+`WORKSPACE_MCP_SPEC_PATH` (path to the spec directory) for FSM/work-loop items,
+or `WORKSPACE_MCP_DISPATCHED_ITEM` (`ini_slug/type:slug`) for non-FSM shaping
+items. Setting neither gives discovery-only mode (git writes disabled). Setting
+both is unsupported — only one selects the mode.
 
 ## Credentials
 

{agentbundle-0.29.0 → agentbundle-0.29.2}/README-pypi.md

@@ -267,6 +267,15 @@ agentbundle catalogue self-host --check --root .
 
 Exits non-zero if any projected file is out of date. Safe to run in CI as a required check; use `--write` locally to regenerate.
 
+By default projects for `claude-code` and `codex`. Downstream repos that use a single adapter (e.g. `kiro-ide`) can declare it in `catalogue.toml` — only that adapter is then projected, and its output files participate in the drift check:
+
+```toml
+[distribution.agentbundle]
+preferred-adapter = "kiro-ide"
+```
+
+When `preferred-adapter` names an adapter not in the upstream `SELF_HOST_ADAPTERS` list, the self-host engine switches to single-adapter mode: only the named adapter is projected; Claude Code-specific artifacts (`.claude/`, `.codex/`, `.claude-plugin/`, `CLAUDE.md`) are neither written nor drift-checked.
+
 **Run Tier-A activation evals** to measure whether each covered skill fires on the prompts it should:
 
 ```bash
@@ -327,15 +336,23 @@ each Claude Code session. It exposes six tools over MCP stdio:
 python3 -m agentbundle.workspace_mcp
 ```
 
+> **Trusted checkout only.** This form runs whichever `agentbundle` is on
+> `sys.path`. If the repo uses an editable install (`pip install -e .`), it
+> runs the local checkout's code. Use only on repos you trust. An isolated
+> spawn mode (`python3 -I -m agentbundle.workspace_mcp`) is planned for
+> Stage 2 and will require a stable non-editable install.
+
 **Inject the session instruction** so the agent knows to use the tools:
 
 ```python
 from agentbundle.workspace_mcp import DEFAULT_SESSION_INSTRUCTION
 ```
 
-Pass `WORKSPACE_MCP_SPEC_PATH` (path to the spec directory) and
-`WORKSPACE_MCP_DISPATCHED_ITEM` (`ini_slug/type:slug`) as environment variables
-when spawning to unlock the git write tools and FSM event tracking.
+Pass exactly one environment variable when spawning to set the session mode:
+`WORKSPACE_MCP_SPEC_PATH` (path to the spec directory) for FSM/work-loop items,
+or `WORKSPACE_MCP_DISPATCHED_ITEM` (`ini_slug/type:slug`) for non-FSM shaping
+items. Setting neither gives discovery-only mode (git writes disabled). Setting
+both is unsupported — only one selects the mode.
 
 ## Credentials
 

{agentbundle-0.29.0 → agentbundle-0.29.2}/agentbundle/build/adapter_root_bins.py

@@ -34,9 +34,9 @@ shell-config edits.
 
 from __future__ import annotations
 
+import contextlib
 import os
 import shutil
-import stat
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -309,19 +309,18 @@ def apply_projection(working_tree: Path, packs_dir: Path) -> None:
     expected_targets = {p.target for p in projections}
     for proj in projections:
         proj.target.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copy2(proj.source, proj.target)
+        shutil.copyfile(proj.source, proj.target)
         if os.name == "posix":
-            os.chmod(proj.target, EXECUTABLE_MODE)
+            with contextlib.suppress(OSError):
+                proj.target.chmod(EXECUTABLE_MODE)
     # Orphan removal: any *.py file under <working_tree>/.agentbundle/bin/
     # not claimed by an expected target.
     target_dir = working_tree / TARGET_SUBDIR
     if target_dir.is_dir():
         for existing in sorted(target_dir.glob("*.py")):
             if existing not in expected_targets:
-                try:
+                with contextlib.suppress(FileNotFoundError):  # pragma: no cover — race-only
                     existing.unlink()
-                except FileNotFoundError:  # pragma: no cover — race-only
-                    pass
 
 
 def check_drift(working_tree: Path, packs_dir: Path) -> list[str]:
@@ -336,7 +335,7 @@ def check_drift(working_tree: Path, packs_dir: Path) -> list[str]:
     """
     drifts: list[str] = []
     try:
-        sources = collect_sources(packs_dir)
+        collect_sources(packs_dir)
     except ValueError as exc:
         drifts.append(f"[adapter-root-bins] {exc}; run: make build-self")
         return drifts

{agentbundle-0.29.0 → agentbundle-0.29.2}/agentbundle/build/self_host.py

@@ -23,10 +23,12 @@ consumer.
 
 Self-host scope (see docs/specs/self-hosting/spec.md § Phased rollout):
 the `SELF_HOST_ADAPTERS` allow-list runs `claude-code` and `codex`.
-Kiro and Copilot stay distribution-only so self-host does not project
-`.kiro/` or `.github/instructions/`. Both `SELF_HOST_ADAPTERS` and
-`SELF_HOST_PACKS` are sourced from `recipes/self-host.toml` (see the
-`_DEFAULT_*` block below); the values named here are the current defaults.
+Both `SELF_HOST_ADAPTERS` and `SELF_HOST_PACKS` are sourced from
+`recipes/self-host.toml` (see the `_DEFAULT_*` block below); the values
+named here are the current defaults.  When `catalogue.toml` declares a
+`preferred-adapter` outside `SELF_HOST_ADAPTERS` (e.g. ``"kiro-ide"``),
+`run_self_host` restricts projection to that adapter only — see
+`_effective_adapters`.
 """
 
 from __future__ import annotations
@@ -76,6 +78,7 @@ TARGET_PATHS = (
     Path(".claude"),
     Path(".codex"),
     Path(".agents"),
+    Path(".kiro"),
     Path("tools") / "hooks",
     Path(".github") / "instructions",
     Path("AGENTS.md"),
@@ -84,12 +87,12 @@ TARGET_PATHS = (
 # Built-in fallbacks for the self-host pack / adapter allow-lists. The
 # authoritative values live in `recipes/self-host.toml` (read at import below);
 # these are used only when that recipe is missing a key or can't be read, so
-# module import stays total. Kiro and Copilot remain in the contract for
-# distribution builds but are excluded from the self-host runner. This repo is
-# the catalogue's home, not an adopter, so `make build-self` only projects the
-# in-house packs; `_aggregate_marketplace` intentionally ignores the pack
-# filter — the catalogue advertises every pack. See the recipe for the full
-# rationale behind the pack selection.
+# module import stays total. This repo is the catalogue's home, not an adopter,
+# so `make build-self` only projects the in-house packs;
+# `_aggregate_marketplace` intentionally ignores the pack filter — the
+# catalogue advertises every pack. See the recipe for the full rationale.
+# Adapters outside this list (e.g. `kiro-ide`) are handled via the
+# `preferred_adapter` override path in `_effective_adapters`.
 _DEFAULT_SELF_HOST_ADAPTERS: tuple[str, ...] = ("claude-code", "codex")
 _DEFAULT_SELF_HOST_PACKS: tuple[str, ...] = (
     "core",
@@ -269,29 +272,52 @@ def _clone_target_subtree(working_tree: Path, destination: Path) -> None:
         target = destination / relative
         target.parent.mkdir(parents=True, exist_ok=True)
         if source.is_dir():
-            shutil.copytree(source, target)
+            shutil.copytree(source, target, copy_function=shutil.copy)
         else:
-            shutil.copy2(source, target)
+            shutil.copy(source, target)
+
+
+def _effective_adapters(preferred_adapter: str | None) -> tuple[str, ...]:
+    """Return the adapter set to project.
+
+    When `preferred_adapter` names an adapter that is NOT already in
+    `SELF_HOST_ADAPTERS` (e.g. ``"kiro-ide"`` on a downstream repo),
+    restrict the set to that single adapter so only its output lands in
+    the shadow / working tree.  Otherwise — including when
+    `preferred_adapter` is ``None`` or is already covered by
+    `SELF_HOST_ADAPTERS` — use the full allow-list unchanged, preserving
+    existing behaviour for repos like this one that project both
+    ``claude-code`` and ``codex``.
+    """
+    if preferred_adapter and preferred_adapter not in SELF_HOST_ADAPTERS:
+        return (preferred_adapter,)
+    return SELF_HOST_ADAPTERS
 
 
 def _project_all_adapters(
     output_root: Path,
     packs_dir: Path,
     contract: dict,
+    preferred_adapter: str | None = None,
 ) -> None:
     """Run direct self-host adapter projections against the
     `SELF_HOST_PACKS`-filtered pack list. Pack uniqueness validation
     still runs across every discovered pack so naming collisions in
     user-scope-default packs aren't masked by the filter.
+
+    When `preferred_adapter` names an adapter outside `SELF_HOST_ADAPTERS`
+    (e.g. ``"kiro-ide"``), only that adapter is projected; see
+    `_effective_adapters` for the full selection logic.
     """
     packs = discover_packs(packs_dir)
     for pack in packs:
         validate_pack_uniqueness(pack)
     pack_paths = _filter_self_host_packs([pack.path for pack in packs])
+    effective = _effective_adapters(preferred_adapter)
     for adapter_name in ADAPTERS:
         if adapter_name not in contract["adapter"]:
             continue
-        if adapter_name not in SELF_HOST_ADAPTERS:
+        if adapter_name not in effective:
             continue
         adapter_module = registry[adapter_name.replace("-", "_")]
         adapter_module.project_packs(pack_paths, contract, output_root)
@@ -392,7 +418,6 @@ EXCLUDED_PATTERNS: tuple[str, ...] = (
     ".github/**",
     "AGENTS.local.md",
     "AGENTS.md",  # root-level; nested AGENTS.md not excluded
-    ".kiro/**",
     "packages/agentbundle/**",
     "packs/**",
     "tools/**",
@@ -567,7 +592,11 @@ def _project_seeds(packs_dir: Path, output_root: Path) -> dict[Path, Path]:
             continue
         target = output_root / relative
         target.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copy2(src, target, follow_symlinks=False)
+        # Use shutil.copy (content + mode, no timestamps) so the shadow seed
+        # file has the same permission bits as the source regardless of umask.
+        # copyfile (content-only) would leave umask-derived mode on new files,
+        # causing false mode drift when the diff gate compares shadow vs disk.
+        shutil.copy(src, target)
     return seen
 
 
@@ -693,6 +722,7 @@ def _recreate_claude_symlink(output_root: Path, *, force_copy: bool = False) ->
 def _build_projected_to_source_map(
     packs_dir: Path,
     contract: dict,
+    preferred_adapter: str | None = None,
 ) -> dict[Path, Path]:
     """Build `{projected_relative_path → source_path}` for Phase-1
     self-host output. Used by `diff_against_working_tree` to name the
@@ -701,12 +731,13 @@ def _build_projected_to_source_map(
     if "primitive" not in contract or "adapter" not in contract:
         return mapping
     allow = set(SELF_HOST_PACKS)
+    effective = _effective_adapters(preferred_adapter)
     for pack_path in sorted(packs_dir.iterdir()):
         if not pack_path.is_dir() or not (pack_path / "pack.toml").exists():
             continue
         if pack_path.name not in allow:
             continue
-        for adapter_name in SELF_HOST_ADAPTERS:
+        for adapter_name in effective:
             if adapter_name not in contract["adapter"]:
                 continue
             for rule in contract["adapter"][adapter_name].get("projection", []):
@@ -1060,6 +1091,7 @@ def run_self_host(
     force: bool,
     contract: dict | None = None,
     no_symlink: bool = False,
+    preferred_adapter: str | None = None,
 ) -> int:
     """Execute `make build-self` (or `make build-self DRY_RUN=1`).
 
@@ -1068,6 +1100,10 @@ def run_self_host(
     projection → marketplace aggregation → CLAUDE.md symlink → marker
     resolution. Under `dry_run`, all writes happen in a shadow temp
     dir and the result is diffed against the working tree.
+
+    When `preferred_adapter` names an adapter not in `SELF_HOST_ADAPTERS`
+    (e.g. ``"kiro-ide"``), only that adapter is projected and compared.
+    Pass ``None`` (default) to use the full `SELF_HOST_ADAPTERS` list.
     """
     if contract is None:
         contract = load_contract(CONTRACT_PATH)
@@ -1107,11 +1143,18 @@ def run_self_host(
     owner = discovery_flat.get("owner", "eugenelim")
     marketplace_name = discovery_flat.get("project-name", "agent-ready-repo")
 
+    # Gate Claude Code-specific artifacts (CLAUDE.md, .claude-plugin/) on
+    # whether the effective adapter set includes claude-code.  When
+    # preferred-adapter is kiro-ide or kiro-cli (or any other adapter not in
+    # SELF_HOST_ADAPTERS), those artifacts are neither written nor expected in
+    # the drift check.
+    _project_claude_artifacts = "claude-code" in _effective_adapters(preferred_adapter)
+
     if dry_run:
         with tempfile.TemporaryDirectory(prefix="agentbundle-shadow-") as shadow_str:
             shadow = Path(shadow_str)
             _clone_target_subtree(working_tree, shadow)
-            _project_all_adapters(shadow, packs_dir, contract)
+            _project_all_adapters(shadow, packs_dir, contract, preferred_adapter)
             # Compose AGENTS.md BEFORE seed projection: on a fresh tree the
             # composed output (body + footer) must win over the body-only
             # seed at `packs/core/seeds/AGENTS.md`; on an existing tree
@@ -1123,15 +1166,16 @@ def run_self_host(
             except ValueError as exc:
                 print(f"self-host: {exc}", file=sys.stderr)
                 return 4
-            _aggregate_marketplace(packs_dir, shadow, owner=owner, name=marketplace_name)
-            _recreate_claude_symlink(shadow, force_copy=no_symlink)
-            extra_marker_paths = list(seed_map.keys()) + [
-                Path(".claude-plugin") / "marketplace.json",
-            ]
+            if _project_claude_artifacts:
+                _aggregate_marketplace(packs_dir, shadow, owner=owner, name=marketplace_name)
+                _recreate_claude_symlink(shadow, force_copy=no_symlink)
+            extra_marker_paths = list(seed_map.keys())
+            if _project_claude_artifacts:
+                extra_marker_paths.append(Path(".claude-plugin") / "marketplace.json")
             if agents_path is not None:
                 extra_marker_paths.append(Path("AGENTS.md"))
             resolve_markers(shadow, discovery_flat, extra_paths=extra_marker_paths)
-            source_map = _build_projected_to_source_map(packs_dir, contract)
+            source_map = _build_projected_to_source_map(packs_dir, contract, preferred_adapter)
             projected_paths = {
                 rendered.relative_to(shadow)
                 for rendered in shadow.rglob("*")
@@ -1169,7 +1213,7 @@ def run_self_host(
     # and the catalogue-visible pack copy (`.apm/user-libs/credbroker/`). No-op
     # outside the monorepo (package source absent — see user_libs docstring).
     _user_libs_apply(working_tree, packs_dir)
-    _project_all_adapters(working_tree, packs_dir, contract)
+    _project_all_adapters(working_tree, packs_dir, contract, preferred_adapter)
     # Compose AGENTS.md BEFORE seed projection — see dry-run branch for
     # rationale (the body-only seed at packs/core/seeds/AGENTS.md must
     # not race the body+footer composition on fresh trees).
@@ -1179,11 +1223,12 @@ def run_self_host(
     except ValueError as exc:
         print(f"self-host: {exc}", file=sys.stderr)
         return 4
-    _aggregate_marketplace(packs_dir, working_tree, owner=owner, name=marketplace_name)
-    _recreate_claude_symlink(working_tree, force_copy=no_symlink)
-    extra_marker_paths = list(seed_map.keys()) + [
-        Path(".claude-plugin") / "marketplace.json",
-    ]
+    if _project_claude_artifacts:
+        _aggregate_marketplace(packs_dir, working_tree, owner=owner, name=marketplace_name)
+        _recreate_claude_symlink(working_tree, force_copy=no_symlink)
+    extra_marker_paths = list(seed_map.keys())
+    if _project_claude_artifacts:
+        extra_marker_paths.append(Path(".claude-plugin") / "marketplace.json")
     if agents_path is not None:
         extra_marker_paths.append(Path("AGENTS.md"))
     resolve_markers(working_tree, discovery_flat, extra_paths=extra_marker_paths)

{agentbundle-0.29.0 → agentbundle-0.29.2}/agentbundle/catalogue_tooling/self_host.py

@@ -40,6 +40,14 @@ def _make_result(ok: bool, operation: str, config: object | None) -> SelfHostRes
     )
 
 
+def _preferred_adapter(config: object | None) -> str | None:
+    """Extract preferred_adapter from a loaded CatalogueConfig, or None."""
+    try:
+        return config.distribution.agentbundle.preferred_adapter or None  # type: ignore[union-attr]
+    except AttributeError:
+        return None
+
+
 def check_self_host(root: Path) -> SelfHostResult:
     """Dry-run self-host check (read-only). Returns SelfHostResult with ok=True on clean."""
     from agentbundle.build.self_host import run_self_host
@@ -52,6 +60,7 @@ def check_self_host(root: Path) -> SelfHostResult:
         packs_dir=packs_dir,
         dry_run=True,
         force=False,
+        preferred_adapter=_preferred_adapter(config),
     )
     return _make_result(ok=(rc == 0), operation="check", config=config)
 
@@ -68,5 +77,6 @@ def write_self_host(root: Path, force: bool = False) -> SelfHostResult:
         packs_dir=packs_dir,
         dry_run=False,
         force=force,
+        preferred_adapter=_preferred_adapter(config),
     )
     return _make_result(ok=(rc == 0), operation="write", config=config)

{agentbundle-0.29.0 → agentbundle-0.29.2}/agentbundle/version.py

@@ -14,7 +14,7 @@ import tomllib
 from importlib.resources import files
 from pathlib import Path
 
-CLI_VERSION = "0.29.0"
+CLI_VERSION = "0.29.2"
 
 _HERE = Path(__file__).resolve().parent
 

{agentbundle-0.29.0 → agentbundle-0.29.2}/agentbundle/workspace_mcp.py

@@ -966,9 +966,20 @@ class _GitTools:
     def __init__(self, repo_root: Path) -> None:
         self._repo_root = repo_root
         spec_path = os.environ.get("WORKSPACE_MCP_SPEC_PATH")
+        # Capture raw env presence BEFORE validation: FSM mode is determined by
+        # whether the operator SUPPLIED WORKSPACE_MCP_SPEC_PATH, not whether it
+        # passes path validation.  An empty string or invalid path still activates
+        # the FSM guard (fail-closed); git writes are blocked even if anchoring fails.
+        # Use `in os.environ` (not bool()) to treat "" as supplied.
+        _spec_path_supplied = "WORKSPACE_MCP_SPEC_PATH" in os.environ
         dispatched = os.environ.get("WORKSPACE_MCP_DISPATCHED_ITEM")
+        # Capture raw dispatched presence for the both-vars warning: if the
+        # DISPATCHED_ITEM value is malformed, validation below sets dispatched=None,
+        # but the warning should still fire to signal the unsupported configuration.
+        _dispatched_supplied = "WORKSPACE_MCP_DISPATCHED_ITEM" in os.environ
         # Validate spec_path: must resolve inside repo_root. An out-of-repo or malformed
-        # path is treated as absent — fail closed (discovery mode; git writes blocked).
+        # path is treated as absent for event-bridge anchoring only — FSM mode
+        # is already locked by _spec_path_supplied above.
         if spec_path:
             try:
                 if not Path(spec_path).resolve().is_relative_to(repo_root.resolve()):
@@ -991,7 +1002,21 @@ class _GitTools:
                 dispatched,
             )
             dispatched = None
-        self._discovery_mode = not spec_path and not dispatched
+        # Discovery mode: only when NEITHER env var was supplied.  Use the raw
+        # presence flag (_spec_path_supplied) so that SPEC_PATH="" stays out of
+        # discovery mode (it is FSM mode, fail-closed).
+        self._discovery_mode = not _spec_path_supplied and not dispatched
+        # FSM mode: WORKSPACE_MCP_SPEC_PATH was supplied → FSM mode, regardless of
+        # whether it passed validation (fail-closed: invalid path still blocks git
+        # writes).  When BOTH env vars are supplied (unsupported per the one-variable
+        # contract), SPEC_PATH wins and a startup warning is logged.
+        if _spec_path_supplied and _dispatched_supplied:
+            _log.warning(
+                "Both WORKSPACE_MCP_SPEC_PATH and WORKSPACE_MCP_DISPATCHED_ITEM are set "
+                "(unsupported); WORKSPACE_MCP_SPEC_PATH takes precedence — "
+                "FSM mode active, git writes blocked"
+            )
+        self._fsm_mode = _spec_path_supplied
         # Expected branch from dispatched item (ini_slug/type:slug → ini_slug/type/slug)
         self._expected_branch: str | None = self._derive_expected_branch(dispatched)
         self._session_branch: str | None = self._read_head_branch()
@@ -1006,10 +1031,10 @@ class _GitTools:
             # Case 1: resumed dispatched session
             (self._expected_branch is not None
              and self._session_branch == self._expected_branch)
-            # Case 2: FSM-only mode (SPEC_PATH set, no DISPATCHED_ITEM)
-            or (spec_path is not None
-                and dispatched is None
-                and self._session_branch is not None)
+            # Case 2: FSM mode (SPEC_PATH supplied); lock to startup HEAD so the
+            # session cannot redirect git_push to an arbitrary caller-chosen ref.
+            # _fsm_mode blocks mutating tools anyway; this lock is belt-and-suspenders.
+            or (_spec_path_supplied and self._session_branch is not None)
         )
         # Serialize all mutating git operations: prevents index.lock collisions
         # and TOCTOU races on _session_branch between concurrent tool calls.
@@ -1256,6 +1281,15 @@ class _GitTools:
         return {"output": r.stdout, "returncode": r.returncode}
 
     def git_branch(self, arguments: dict) -> dict:
+        # FSM guard precedes discovery-mode guard (fail-closed: SPEC_PATH="" is FSM,
+        # not discovery mode, so _fsm_mode fires before _discovery_mode can).
+        if self._fsm_mode:
+            return {
+                "error": (
+                    "git_branch is not available in work-loop (FSM) mode — "
+                    "work-loop manages its own git lifecycle"
+                )
+            }
         if self._discovery_mode:
             return {"error": "git_branch is not available in discovery mode"}
         name = arguments.get("name", "")
@@ -1301,6 +1335,13 @@ class _GitTools:
         return {"branch": name}
 
     def git_commit(self, arguments: dict) -> dict:
+        if self._fsm_mode:
+            return {
+                "error": (
+                    "git_commit is not available in work-loop (FSM) mode — "
+                    "work-loop manages its own git lifecycle"
+                )
+            }
         if self._discovery_mode:
             return {"error": "git_commit is not available in discovery mode"}
         message = arguments.get("message", "workspace-mcp: commit artifacts")
@@ -1411,6 +1452,13 @@ class _GitTools:
         return {"committed": matched, "message": message}
 
     def git_push(self, arguments: dict) -> dict:
+        if self._fsm_mode:
+            return {
+                "error": (
+                    "git_push is not available in work-loop (FSM) mode — "
+                    "work-loop manages its own git lifecycle"
+                )
+            }
         if self._discovery_mode:
             return {"error": "git_push is not available in discovery mode"}
         branch = arguments.get("branch", "")
@@ -1553,15 +1601,31 @@ class _StdioLoop:
                     "Returns the current workspace queue and active-run state. "
                     "Call this at session start before doing any work. "
                     "Response fields: "
-                    "ready[] — items that can be dispatched immediately, each with "
+                    "ready[] — items that may be dispatchable, each with "
                     "ini_slug, type, slug, and dispatch_skill; "
-                    "blocked[] — items whose dependencies are not yet met; "
+                    "dispatchable items omit the 'available' field (treat absent as eligible); "
+                    "items where available=false require an optional pack (see required_pack); "
+                    "items with a non-empty unmet_needs list have unresolved dependencies; "
+                    "only dispatch items where 'available' is absent (not false) and "
+                    "'unmet_needs' is absent or empty; "
+                    "blocked[] — items whose dependency needs are not yet met; "
                     "active[] — items currently in progress; "
-                    "shaping[] — non-implementation items (research, design, shape, strategy); "
-                    "current_state — current work-loop phase name (null when idle); "
-                    "gate_pending — true when human input is required before work can continue; "
+                    "shaping[] — informational only in Stage 1; non-FSM items (research, design, "
+                    "shape, strategy) whose skill flows are not yet shipped (Stage 3); "
+                    "do not dispatch shaping items in Stage 1 — selecting one opens a bound "
+                    "session with no usable skill flow; same available/required_pack/unmet_needs "
+                    "fields as ready[] for readiness visibility; "
+                    "current_state — current work-loop phase name (null when idle OR when this "
+                    "session is not bound to a valid spec — see below); "
+                    "gate_pending — true when human input is required before work can continue "
+                    "(always false when not spec-bound); "
                     "gate — name of the pending gate (e.g. SPEC-HUMAN-GATE, REVIEW-HUMAN-GATE); "
-                    "gate_question — the specific question the work-loop is asking."
+                    "gate_question — the specific question the work-loop is asking. "
+                    "IMPORTANT: current_state, gate_pending, gate, and gate_question are "
+                    "authoritative only in a session where WORKSPACE_MCP_SPEC_PATH is set to "
+                    "a valid spec directory; in discovery sessions (no SPEC_PATH) or sessions "
+                    "with an invalid SPEC_PATH these fields are always null/false even if a "
+                    "work-loop is active in another session."
                 ),
                 "inputSchema": {"type": "object", "properties": {}},
             },
@@ -1602,6 +1666,7 @@ class _StdioLoop:
             {
                 "name": "git_status",
                 "description": (
+                    "Use this instead of running 'git status' directly. "
                     "Returns uncommitted file changes in the repo "
                     "(equivalent to git status --short). "
                     "Returns {output: string, returncode: int}."
@@ -1611,11 +1676,15 @@ class _StdioLoop:
             {
                 "name": "git_branch",
                 "description": (
-                    "Create and check out a new feature branch. "
+                    "Use this instead of running 'git checkout -b' directly — "
+                    "raw git branch commands bypass the scoping guard that locks "
+                    "the session to exactly one branch for the dispatched item. "
+                    "Creates and checks out a new feature branch. "
                     "The branch name must follow the ini_slug/type/slug format "
-                    "(e.g. my-initiative/work/fix-bug) and must match the dispatched item. "
+                    "(e.g. my-initiative/shape/new-feature) and must match the dispatched item. "
                     "May only be called once per session; subsequent calls are rejected. "
-                    "Not available when no item has been dispatched."
+                    "Not available in FSM/work-loop sessions (WORKSPACE_MCP_SPEC_PATH set) "
+                    "or when no item has been dispatched."
                 ),
                 "inputSchema": {
                     "type": "object",
@@ -1624,7 +1693,7 @@ class _StdioLoop:
                             "type": "string",
                             "description": (
                                 "Branch name in ini_slug/type/slug format "
-                                "(e.g. my-initiative/work/fix-bug)."
+                                "(e.g. my-initiative/shape/new-feature)."
                             ),
                         }
                     },
@@ -1634,9 +1703,13 @@ class _StdioLoop:
             {
                 "name": "git_commit",
                 "description": (
-                    "Stage and commit files that belong to the dispatched work item. "
-                    "Only files under the item's configured output paths are staged; "
-                    "files outside those paths are excluded. "
+                    "Use this instead of running 'git add' and 'git commit' directly — "
+                    "raw git commit bypasses the output-path filter and may silently "
+                    "include files outside the dispatched item's scope. "
+                    "Stages and commits only files under the item's configured output "
+                    "paths; unstaged files outside those paths are excluded automatically. "
+                    "If any files outside the output paths are already pre-staged (via "
+                    "git add), the commit is refused — unstage them first. "
                     "Not available when no item has been dispatched, or for work-loop "
                     "items (work-loop manages its own git lifecycle)."
                 ),
@@ -1656,9 +1729,16 @@ class _StdioLoop:
             {
                 "name": "git_push",
                 "description": (
-                    "Push the session branch to origin. "
-                    "Requires git_branch() to have been called first in this session. "
-                    "Not available when no item has been dispatched."
+                    "Use this instead of running 'git push' directly — "
+                    "raw git push bypasses the branch check that prevents pushing "
+                    "to a branch other than the one established for this session. "
+                    "Pushes the session branch to origin. "
+                    "The session branch must be established before pushing: "
+                    "call git_branch() in a new session, or in a resumed "
+                    "dispatched session the branch may already be locked from "
+                    "the prior run (no git_branch() call required in that case). "
+                    "Not available in FSM/work-loop sessions (WORKSPACE_MCP_SPEC_PATH set) "
+                    "or when no item has been dispatched."
                 ),
                 "inputSchema": {
                     "type": "object",
@@ -1666,8 +1746,9 @@ class _StdioLoop:
                         "branch": {
                             "type": "string",
                             "description": (
-                                "Branch name to push. Must match the branch "
-                                "established by git_branch() in this session."
+                                "Branch name to push. Must match the session-bound "
+                                "branch established by git_branch() or inherited "
+                                "from session startup."
                             ),
                         }
                     },