agentbundle 0.29.3__tar.gz → 0.29.4__tar.gz

{agentbundle-0.29.3 → agentbundle-0.29.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.29.3
+Version: 0.29.4
 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
@@ -234,16 +234,29 @@ my-pack/
   .claude-plugin/
     plugin.json              # Claude Code plugin manifest (hand-authored)
   README.md                  # the pack's portable doc — projected with the pack
-  .apm/                      # primitives — projected by the build pipeline
+  .apm/                      # runtime — projected by the build pipeline
     skills/<name>/
       SKILL.md               # the skill body; one folder per skill
+      scripts/               # helper code the skill invokes
       references/            # progressive-disclosure docs, loaded on demand
       assets/                # templates the skill copies into the repo
+      evals/                 # activation + output-quality evals, skill-local
     agents/<name>.md         # subagents
     hooks/<name>.py          # lifecycle hooks
+  tests/                     # implementation tests — NEVER projected
+    skills/<name>/
+    hooks/
+    pack/
   seeds/                     # files scaffolded into the adopter repo
 ```
 
+Three boundaries: the **pack** owns and executes its tests, **`.apm/`** is the
+runtime export boundary, and a **skill** owns its eval fixtures. Only `.apm/`
+and `seeds/` are projected into an installed environment — `tests/` is visible
+in a catalogue archive, so an extracted pack can verify itself, but `install`
+never places it. Keep tests out of `.apm/` even though the installer would
+ignore them there; the separation is structural, not incidental.
+
 `pack.toml` is the **single source of truth** for a pack's metadata. Declare
 `license`, `[[pack.maintainers]]`, `[pack.links]`, `categories`, and
 `keywords` once; the build projects the cleanly-mappable subset — plus the

{agentbundle-0.29.3 → agentbundle-0.29.4}/README-pypi.md

@@ -212,16 +212,29 @@ my-pack/
   .claude-plugin/
     plugin.json              # Claude Code plugin manifest (hand-authored)
   README.md                  # the pack's portable doc — projected with the pack
-  .apm/                      # primitives — projected by the build pipeline
+  .apm/                      # runtime — projected by the build pipeline
     skills/<name>/
       SKILL.md               # the skill body; one folder per skill
+      scripts/               # helper code the skill invokes
       references/            # progressive-disclosure docs, loaded on demand
       assets/                # templates the skill copies into the repo
+      evals/                 # activation + output-quality evals, skill-local
     agents/<name>.md         # subagents
     hooks/<name>.py          # lifecycle hooks
+  tests/                     # implementation tests — NEVER projected
+    skills/<name>/
+    hooks/
+    pack/
   seeds/                     # files scaffolded into the adopter repo
 ```
 
+Three boundaries: the **pack** owns and executes its tests, **`.apm/`** is the
+runtime export boundary, and a **skill** owns its eval fixtures. Only `.apm/`
+and `seeds/` are projected into an installed environment — `tests/` is visible
+in a catalogue archive, so an extracted pack can verify itself, but `install`
+never places it. Keep tests out of `.apm/` even though the installer would
+ignore them there; the separation is structural, not incidental.
+
 `pack.toml` is the **single source of truth** for a pack's metadata. Declare
 `license`, `[[pack.maintainers]]`, `[pack.links]`, `categories`, and
 `keywords` once; the build projects the cleanly-mappable subset — plus the

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

@@ -49,6 +49,32 @@ user journey it serves — not a skill inventory. See the `_example` pack for a
 
 ## 4. Pack layout
 
+Three boundaries, each owned by a different thing:
+
+- The **pack** is the ownership and test-execution boundary.
+- `.apm/` is the **runtime export** boundary.
+- A **skill** is the evaluation-fixture boundary.
+
+```
+packs/<pack>/
+├── pack.toml
+├── README.md
+├── .apm/                          # runtime — projected into installed environments
+│   └── skills/<skill>/
+│       ├── SKILL.md
+│       ├── scripts/
+│       ├── references/
+│       ├── assets/
+│       └── evals/                 # skill-local, projected with the skill
+├── tests/                         # implementation verification — never projected
+│   └── skills/<skill>/
+└── seeds/                         # governance files projected to the repo root
+```
+
+Deterministic implementation tests live under `packs/<pack>/tests/`. Runtime
+skill evals live under `.apm/skills/<skill>/evals/`. `[pack.evals].skills`
+selects which skill-local activation evals the pack evaluator runs.
+
 Primitive sources live under `.apm/` and are projected per adapter by `catalogue self-host`.
 
 | Source directory | Primitive type |
@@ -58,6 +84,111 @@ Primitive sources live under `.apm/` and are projected per adapter by `catalogue
 | `.apm/hooks/` | Hook bodies |
 | `.apm/hook-wiring/` | Hook wiring |
 | `.apm/commands/` | Commands |
+| `.apm/shared-libs/` | Shared libraries |
+| `.apm/skills/<skill>/evals/` | Activation and output-quality evals (projected with the skill) |
+
+### Tests live with the pack, outside the payload they validate
+
+Keep tests beside the pack they validate, but out of the runtime payload.
+`.apm/` holds only files meant to participate in installation, projection, or
+execution — so a test never belongs there, **even where the installer happens
+to ignore its path**. Runtime separation is expressed by directory structure,
+not by relying on an implicit exclusion that a future adapter may not honour.
+
+```
+packs/<pack>/tests/
+├── skills/
+│   └── <skill>/          # unit/, integration/, fixtures/ as the skill warrants
+├── hooks/
+├── pack/                 # manifest, metadata, projection
+└── fixtures/
+```
+
+Tests should execute or import the real implementation under `.apm/`. Never
+duplicate production code into the test tree.
+
+### Tests versus evaluations
+
+Two different questions, two homes.
+
+| | `tests/` | `evals/` |
+|---|---|---|
+| Verifies | Deterministic software behaviour | Agent-level behaviour |
+| Covers | Function output, parsing, exit status, CLI behaviour, error handling, projected install contents | Whether a skill activates, whether a near-miss avoids activation, whether output satisfies a rubric |
+| Run by | pytest, Vitest, Go test, shell tooling | The eval runner |
+| Lives at | `packs/<pack>/tests/` | `.apm/skills/<skill>/evals/` |
+
+Evaluations do not replace unit or integration tests for scripts.
+
+Evals are skill-local by design, not by accident. A fixture only means anything
+next to the skill it exercises, so it belongs to the skill and is projected with
+it — the adapters copy `.apm/skills/<skill>/` wholesale. That is why the `tests/`
+rule is scoped to the `.apm/` boundary rather than "anything that isn't runtime":
+`evals/` is runtime-adjacent content, a test suite is not. The linter enforces
+this — it looks for `eval_queries.json` and `evals.json` under
+`<skill>/evals/`, and requires one for every skill named in `[pack.evals].skills`.
+
+A **diagnostic** may live under `.apm/` when it is an intentional runtime
+feature users or agents invoke — `scripts/doctor.py`,
+`scripts/check_environment.py`. Those are runtime commands, not test suites.
+
+### Catalogue archives may carry tests; installers must not install them
+
+A catalogue or source archive walks `packs/**`, so it carries a pack's
+`pack.toml`, `README.md`, `.apm/**`, `seeds/**`, `tests/**`, `docs/**`,
+`.claude-plugin/`, and pack-root markdown. Shipping tests in a source-oriented
+archive supports downstream verification, auditing, security review, and
+testing an extracted release.
+
+Catalogue inclusion does not imply runtime installation. Installers and
+projection adapters treat `.apm/` and `seeds/` as the projected surfaces, so
+nothing outside those two — `tests/` included — reaches an installed
+environment.
+
+### Test dependencies are not runtime dependencies
+
+A skill's runtime dependency declaration lists only what the installed skill
+needs at run time. `pytest`, `hypothesis`, `vitest`, `eslint`,
+`mypy`, `ruff` and friends belong in development configuration.
+
+Fixtures under a pack's test tree ship in the archive, so they must carry no
+credentials or private data, prefer synthetic data, stay modest in size, and
+name their licence when sourced externally. Fuzzing corpora, generated output,
+coverage reports, and caches are neither committed nor packaged.
+
+### Repository-root tests
+
+A test concerning one pack stays inside that pack. Behaviour no single pack
+owns — the catalogue system, packaging, shared projection machinery, profiles,
+cross-pack interaction — belongs to the repository, not to a pack.
+
+Where that lives is the repository's call. This catalogue keeps it in the
+engine's own suite (`packages/agentbundle/tests/`) rather than 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.
+
+### Normative summary
+
+- A pack **MUST** be the ownership boundary for its tests.
+- Pack-specific tests **MUST** live under `packs/<pack>/tests/`.
+- 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
+  distinct from implementation tests.
+- Test dependencies **MUST NOT** be declared as runtime dependencies.
+- Tests **MAY** be included in catalogue or source archives.
+- Tests **MUST NOT** be projected into installed agent environments. Evals
+  **are** projected, as a skill subdirectory — they are runtime-adjacent.
+- Tests that no single pack owns **SHOULD** be kept out of pack test trees,
+  wherever the repository chooses to put them.
+- CI **SHOULD** exercise both the source implementation and the projected
+  runtime artifact.
+
+Release validation should therefore project the pack into a temporary agent
+environment, smoke-test it there, and confirm the projection contains no
+`tests/`, `__pycache__/`, `.pytest_cache/`, coverage output, or
+`test-results/`.
 
 ---
 

{agentbundle-0.29.3 → agentbundle-0.29.4}/agentbundle/_data/catalogue-scaffold/manifest.json

@@ -1,13 +1,13 @@
 {
   "files": {
-    "guides/_shared/reference/catalogue-authoring-standards.md": "4fe9ce077af089ab52840d1b3de600c09ca23eace114c1e28c4685a3b7289520",
+    "guides/_shared/reference/catalogue-authoring-standards.md": "0d278062872d62d059e322bae9e5af9f573d79bc93ff24ca18fb750705da5cc6",
     "guides/_shared/reference/catalogue-ci-contract.md": "fae793ab47989b6dd3c731afcb0b4cda21c7d08bbe7fa40fca6d3abb3d158141",
-    "packs/AGENTS.md": "4d9e94478d3c941d4a08c8827ed9d30edaa07207854eac020b9fc3014f5b3237",
-    "packs/README.md": "68a141500fed78988dbfe7400ea9b8fa0b7d97186d420a93dfe40763272b69ee",
+    "packs/AGENTS.md": "7b534acfdaab757079ca678d9290c2257267d7f4e0b4b3c3401d9da22cb4be0b",
+    "packs/README.md": "d2de5f9556f4c8e521103474bde74636e02cc805f9bf5312a3a61a1f3eb45d8f",
     "packs/_example/.apm/skills/example-skill/SKILL.md": "33be8cbf4b2c014a5a63e788b7d0b350ad8061c6c4b2579369a3e984135bf9f1",
+    "packs/_example/.apm/skills/example-skill/evals/eval_queries.json": "f41ecda0834a22f3b4823c81ab02e58b0e4beba610e3b40c185579abff9cfeee",
     "packs/_example/.claude-plugin/plugin.json": "d38c8456640d5e2f9296361f7e3e675e368ddd3eb22a6245267560f460155f41",
     "packs/_example/README.md": "ef130c9c1f97a75a07cc59fc55fc5b3bf71846dd2f06c3cddf5a1154023b6ef6",
-    "packs/_example/evals/eval_queries.json": "f41ecda0834a22f3b4823c81ab02e58b0e4beba610e3b40c185579abff9cfeee",
     "packs/_example/pack.toml": "94e2c7fd25d4d115858728c7ecb8f739adfd0f594b29596c106daba0791a4b94",
     "profiles/AGENTS.md": "8950438d9e0f57c13613104c88c90b598b53196c91bfdced6d63e4e01b5e9254",
     "profiles/README.md": "a0b0268edc57fc575f7fea08f3363ba7da9f6e67dc4a0a6f8bd38c9668c97922",

{agentbundle-0.29.3 → agentbundle-0.29.4}/agentbundle/_data/catalogue-scaffold/packs/AGENTS.md

@@ -5,12 +5,16 @@ Read `packs/AGENTS.local.md` when present — it carries host-specific overrides
 
 ## Pack layout
 
+The pack is the ownership and test-execution boundary; `.apm/` is the runtime export boundary; a skill is the
+evaluation-fixture boundary. Tests go in `packs/<pack>/tests/`, never under `.apm/`. Evals stay skill-local at
+`.apm/skills/<skill>/evals/` and project with the skill.
+
 | Path | Purpose |
 |------|---------|
 | `pack.toml` | Pack metadata — version, description, adapter-contract, categories |
 | `.claude-plugin/plugin.json` | Claude plugin manifest source (must match `pack.toml` version, stay schema-valid) |
 | `seeds/` | Adopter scaffold templates (brownfield install) |
-| `docs/` | Concept anchor and pack guides — never projected or installed |
+| `tests/` · `docs/` | Never projected — implementation tests (`skills/<skill>/`, `hooks/`, `pack/`) · concept anchor and pack guides |
 | `.apm/skills/` | Skill sources → projected per adapter |
 | `.apm/agents/` | Agent sources → projected per adapter |
 | `.apm/hooks/` | Hook-body sources → projected per adapter |
@@ -40,10 +44,7 @@ installed, and are not included in packaged archives. See `packs/README.md`.
 | `[pack.evals]` | — | `skills` (array of covered skill names) |
 | `[pack.recipes.*]` | `description` | `steps`, `adapter` |
 | `[pack.dependencies]` | — | `required`, `recommended`, `conflicts` (arrays) |
-| `[pack.seeds]` | — | Seed path configuration |
-| `[pack.layout]` | — | Per-scope layout overrides |
-| `[pack.first-value]` | — | First-value install metadata |
-| `[pack.adaptation]` | — | Adaptation inference rules |
+| `[pack.seeds]` · `[pack.layout]` · `[pack.first-value]` · `[pack.adaptation]` | — | Seed paths · per-scope layout overrides · first-value install metadata · adaptation inference rules |
 
 `[pack.install]` is required when `adapter-contract.version` ≥ 0.2.
 

{agentbundle-0.29.3 → agentbundle-0.29.4}/agentbundle/_data/catalogue-scaffold/packs/README.md

@@ -20,7 +20,7 @@ Copy `packs/_example` to `packs/<your-pack>`, then:
 1. Update `pack.toml` — set `[pack].name`, `version`, `description`, and `[pack.install]` fields.
 2. Update `.claude-plugin/plugin.json` — set `name`, `version`, and `description` to match.
 3. Rename `.apm/skills/example-skill` to your skill name and rewrite `SKILL.md`.
-4. Update `evals/eval_queries.json` with activation fixtures for your skill.
+4. Update `.apm/skills/<skill>/evals/eval_queries.json` with activation fixtures for your skill.
 5. Rewrite `README.md` with your pack's outcome, audience, and install instructions.
 6. Run `agentbundle catalogue verify --root .` from the catalogue root.
 
@@ -50,7 +50,7 @@ full primitive directory list and adapter-contract map.
 
 `seeds/` holds adopter scaffold templates delivered on brownfield install.
 
-`evals/eval_queries.json` holds Tier-A activation eval fixtures — should-trigger and near-miss
+`.apm/skills/<skill>/evals/eval_queries.json` holds Tier-A activation eval fixtures — should-trigger and near-miss
 queries for each user-triggered skill. List every covered skill in `[pack.evals].skills`.
 
 ## Versioning expectations

{agentbundle-0.29.3 → agentbundle-0.29.4}/agentbundle/catalogue_tooling/self_host_windows.py

@@ -81,8 +81,8 @@ def run_windows_compat(root: Path) -> int:
         ),
         (
             "hook parity-net suite (windows-hooks-phase3)",
-            [py, "-m", "pytest", "tests/hooks/"],
-            pkg,
+            [py, "-m", "pytest", str(root / "packs" / "core" / "tests" / "hooks")],
+            root,
         ),
         # Atlassian SSO suites (asyncio + SSL-context wiring is platform-sensitive)
         (

{agentbundle-0.29.3 → agentbundle-0.29.4}/agentbundle/version.py

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

{agentbundle-0.29.3 → agentbundle-0.29.4}/agentbundle.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.29.3
+Version: 0.29.4
 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
@@ -234,16 +234,29 @@ my-pack/
   .claude-plugin/
     plugin.json              # Claude Code plugin manifest (hand-authored)
   README.md                  # the pack's portable doc — projected with the pack
-  .apm/                      # primitives — projected by the build pipeline
+  .apm/                      # runtime — projected by the build pipeline
     skills/<name>/
       SKILL.md               # the skill body; one folder per skill
+      scripts/               # helper code the skill invokes
       references/            # progressive-disclosure docs, loaded on demand
       assets/                # templates the skill copies into the repo
+      evals/                 # activation + output-quality evals, skill-local
     agents/<name>.md         # subagents
     hooks/<name>.py          # lifecycle hooks
+  tests/                     # implementation tests — NEVER projected
+    skills/<name>/
+    hooks/
+    pack/
   seeds/                     # files scaffolded into the adopter repo
 ```
 
+Three boundaries: the **pack** owns and executes its tests, **`.apm/`** is the
+runtime export boundary, and a **skill** owns its eval fixtures. Only `.apm/`
+and `seeds/` are projected into an installed environment — `tests/` is visible
+in a catalogue archive, so an extracted pack can verify itself, but `install`
+never places it. Keep tests out of `.apm/` even though the installer would
+ignore them there; the separation is structural, not incidental.
+
 `pack.toml` is the **single source of truth** for a pack's metadata. Declare
 `license`, `[[pack.maintainers]]`, `[pack.links]`, `categories`, and
 `keywords` once; the build projects the cleanly-mappable subset — plus the

{agentbundle-0.29.3 → agentbundle-0.29.4}/agentbundle.egg-info/SOURCES.txt

@@ -46,7 +46,6 @@ agentbundle/_data/catalogue-scaffold/packs/AGENTS.md
 agentbundle/_data/catalogue-scaffold/packs/README.md
 agentbundle/_data/catalogue-scaffold/packs/_example/README.md
 agentbundle/_data/catalogue-scaffold/packs/_example/pack.toml
-agentbundle/_data/catalogue-scaffold/packs/_example/evals/eval_queries.json
 agentbundle/_data/catalogue-scaffold/profiles/AGENTS.md
 agentbundle/_data/catalogue-scaffold/profiles/README.md
 agentbundle/_data/catalogue-scaffold/profiles/_example/README.md
@@ -188,11 +187,9 @@ agentbundle/commands/upgrade.py
 agentbundle/commands/validate.py
 tests/test_adapter_permissions_projection.py
 tests/test_linear_primitive.py
-tests/test_loop_engine_events_jsonl.py
 tests/test_workspace_mcp_elicit.py
 tests/test_workspace_mcp_event_bridge.py
 tests/test_workspace_mcp_git.py
 tests/test_workspace_mcp_lifecycle.py
 tests/test_workspace_mcp_stdin.py
-tests/test_workspace_mcp_tools.py
-tests/test_workspace_status_engine_autonomous.py
+tests/test_workspace_mcp_tools.py

{agentbundle-0.29.3 → agentbundle-0.29.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentbundle"
-version = "0.29.3"
+version = "0.29.4"
 description = "npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent."
 requires-python = ">=3.11"
 dependencies = []

agentbundle-0.29.3/agentbundle/_data/catalogue-scaffold/packs/_example/evals/eval_queries.json

@@ -1,42 +0,0 @@
-[
-  {
-    "query": "run example",
-    "skill": "example-skill",
-    "should_trigger": true
-  },
-  {
-    "query": "show example skill output",
-    "skill": "example-skill",
-    "should_trigger": true
-  },
-  {
-    "query": "what does example-skill do",
-    "skill": "example-skill",
-    "should_trigger": true
-  },
-  {
-    "query": "demonstrate the example",
-    "skill": "example-skill",
-    "should_trigger": true
-  },
-  {
-    "query": "run the example skill now",
-    "skill": "example-skill",
-    "should_trigger": true
-  },
-  {
-    "query": "give me a demo",
-    "skill": "example-skill",
-    "should_trigger": false
-  },
-  {
-    "query": "show me a test run of architect-design",
-    "skill": "example-skill",
-    "should_trigger": false
-  },
-  {
-    "query": "how do I install a pack",
-    "skill": "example-skill",
-    "should_trigger": false
-  }
-]

agentbundle-0.29.3/tests/test_loop_engine_events_jsonl.py

@@ -1,168 +0,0 @@
-"""Tests for loop-engine events.jsonl outbox protocol."""
-from __future__ import annotations
-
-import json
-import subprocess
-import sys
-from pathlib import Path
-
-import pytest
-
-_SCRIPTS = (
-    Path(__file__).resolve().parents[3]
-    / "packs" / "core" / ".apm" / "skills" / "work-loop" / "scripts"
-)
-_LOOP_ENGINE = _SCRIPTS / "loop-engine.py"
-_LOOP_COHORT = _SCRIPTS / "loop-cohort.py"
-
-
-def _run(script: Path, *args: str, cwd: Path) -> subprocess.CompletedProcess:
-    return subprocess.run(
-        [sys.executable, str(script), *args],
-        capture_output=True, text=True, encoding="utf-8",
-        cwd=str(cwd),
-    )
-
-
-def _init_git_repo(tmp_path: Path) -> Path:
-    """Initialize a minimal git repo at tmp_path; return repo root."""
-    subprocess.run(["git", "init", str(tmp_path)], check=True, capture_output=True)
-    for cmd in (
-        ["git", "config", "user.email", "test@example.com"],
-        ["git", "config", "user.name", "Test"],
-    ):
-        subprocess.run(cmd, check=True, capture_output=True, cwd=str(tmp_path))
-    return tmp_path
-
-
-def _make_spec_dir(repo: Path, name: str = "test-spec") -> Path:
-    spec_dir = repo / "docs" / "specs" / name
-    spec_dir.mkdir(parents=True, exist_ok=True)
-    (spec_dir / "spec.md").write_text("- **Status:** Approved\n")
-    (spec_dir / "plan.md").write_text("- **Status:** Approved\n")
-    return spec_dir
-
-
-def _engine_init(repo: Path, spec_dir: Path) -> str:
-    """Run loop-engine init + loop-cohort init; return run_id."""
-    r = _run(_LOOP_ENGINE, "init", str(spec_dir), "--mode", "code", "--json", cwd=repo)
-    assert r.returncode == 0, r.stderr
-    run_id = json.loads(r.stdout.strip())["run_id"]
-    r = _run(_LOOP_COHORT, "init", str(spec_dir), "--run-id", run_id, cwd=repo)
-    assert r.returncode == 0, r.stderr
-    return run_id
-
-
-class TestOutboxInit:
-    """cmd_init creates .loop-run/ + empty events.jsonl + gitignore entry."""
-
-    def test_events_jsonl_created_empty(self, tmp_path: pytest.TempDir) -> None:
-        repo = _init_git_repo(tmp_path)
-        spec_dir = _make_spec_dir(repo)
-        _engine_init(repo, spec_dir)
-        jsonl = repo / ".loop-run" / "events.jsonl"
-        assert jsonl.exists(), "events.jsonl must be created by cmd_init"
-        assert jsonl.read_text() == "", "events.jsonl must start empty (no header line)"
-
-    def test_gitignore_entry_added(self, tmp_path: pytest.TempDir) -> None:
-        repo = _init_git_repo(tmp_path)
-        spec_dir = _make_spec_dir(repo)
-        _engine_init(repo, spec_dir)
-        lines = (repo / ".gitignore").read_text().splitlines()
-        assert ".loop-run/" in lines
-
-    def test_gitignore_not_duplicated_on_second_init(self, tmp_path: pytest.TempDir) -> None:
-        repo = _init_git_repo(tmp_path)
-        (repo / ".gitignore").write_text(".loop-run/\n")
-        spec_dir = _make_spec_dir(repo)
-        _engine_init(repo, spec_dir)
-        lines = (repo / ".gitignore").read_text().splitlines()
-        assert lines.count(".loop-run/") == 1
-
-
-class TestOutboxTransition:
-    """Outbox write protocol: pending → state → jsonl → delete pending."""
-
-    def test_transition_appends_event_line(self, tmp_path: pytest.TempDir) -> None:
-        repo = _init_git_repo(tmp_path)
-        spec_dir = _make_spec_dir(repo)
-        _engine_init(repo, spec_dir)
-        r = _run(_LOOP_ENGINE, "transition", str(spec_dir), "spec-ready", cwd=repo)
-        assert r.returncode == 0, r.stderr
-        jsonl = repo / ".loop-run" / "events.jsonl"
-        lines = [ln for ln in jsonl.read_text().splitlines() if ln.strip()]
-        assert len(lines) == 1
-        event = json.loads(lines[0])
-        assert event["from"] == "SPEC-PLAN-DRAFTING"
-        assert event["event"] == "spec-ready"
-        assert event["to"] == "SPEC-PLAN-REVIEW"
-        assert event["seq"] == 1
-        for key in ("run_id", "spec", "at"):
-            assert key in event, f"missing required key: {key!r}"
-
-    def test_event_schema_field_names(self, tmp_path: pytest.TempDir) -> None:
-        """Event fields must be seq/run_id/spec/from/event/to/at (design.md:317)."""
-        repo = _init_git_repo(tmp_path)
-        spec_dir = _make_spec_dir(repo)
-        _engine_init(repo, spec_dir)
-        _run(_LOOP_ENGINE, "transition", str(spec_dir), "spec-ready", cwd=repo)
-        jsonl = repo / ".loop-run" / "events.jsonl"
-        event = json.loads(jsonl.read_text().strip())
-        required_keys = {"seq", "run_id", "spec", "from", "event", "to", "at"}
-        forbidden_aliases = {"to_state", "from_state", "timestamp"}
-        assert set(event.keys()) >= required_keys
-        assert not (set(event.keys()) & forbidden_aliases), (
-            f"event uses forbidden alias(es): {set(event.keys()) & forbidden_aliases}"
-        )
-
-    def test_no_pending_file_after_successful_transition(self, tmp_path: pytest.TempDir) -> None:
-        repo = _init_git_repo(tmp_path)
-        spec_dir = _make_spec_dir(repo)
-        _engine_init(repo, spec_dir)
-        _run(_LOOP_ENGINE, "transition", str(spec_dir), "spec-ready", cwd=repo)
-        assert not (repo / ".loop-run" / "events.pending").exists()
-
-    def test_multiple_transitions_append_in_order(self, tmp_path: pytest.TempDir) -> None:
-        repo = _init_git_repo(tmp_path)
-        spec_dir = _make_spec_dir(repo)
-        _engine_init(repo, spec_dir)
-        _run(_LOOP_ENGINE, "transition", str(spec_dir), "spec-ready", cwd=repo)
-        _run(_LOOP_ENGINE, "transition", str(spec_dir), "reviewers-clean", cwd=repo)
-        jsonl = repo / ".loop-run" / "events.jsonl"
-        lines = [json.loads(ln) for ln in jsonl.read_text().splitlines() if ln.strip()]
-        assert len(lines) == 2
-        assert lines[0]["seq"] == 1
-        assert lines[1]["seq"] == 2
-        assert lines[1]["from"] == "SPEC-PLAN-REVIEW"
-
-
-class TestOutboxReset:
-    """cmd_reset removes .loop-run/."""
-
-    def test_loop_run_removed_on_reset(self, tmp_path: pytest.TempDir) -> None:
-        repo = _init_git_repo(tmp_path)
-        spec_dir = _make_spec_dir(repo)
-        _engine_init(repo, spec_dir)
-        assert (repo / ".loop-run").exists()
-        r = _run(_LOOP_ENGINE, "reset", str(spec_dir), cwd=repo)
-        assert r.returncode == 0, r.stderr
-        assert not (repo / ".loop-run").exists()
-
-
-class TestOutboxRecovery:
-    """Outbox recovery: replay/discard stale events.pending."""
-
-    def test_outbox_recovery_replay_when_to_matches_state(self) -> None:
-        pytest.skip("STUB: replay the pending event when its `to` matches state")
-
-    def test_outbox_recovery_discard_when_to_mismatches_state(self) -> None:
-        pytest.skip("STUB: discard the pending event when its `to` mismatches state")
-
-    def test_cmd_transition_recovers_stale_pending_before_new_transition(self) -> None:
-        pytest.skip("STUB: crash-then-next-transition — pending from prior crash must be replayed/discarded at top of next cmd_transition, not lost")
-
-    def test_cmd_transition_recovers_foreign_spec_pending_before_writing_own(self) -> None:
-        pytest.skip("STUB: cross-spec — crash on spec-A then transition on spec-B must recover spec-A's pending against spec-A's engine-state.json before writing spec-B's new pending event — skipping leaves spec-A's event silently lost to the step-2 overwrite")
-
-    def test_io_failure_does_not_abort_transition(self) -> None:
-        pytest.skip("STUB (graceful-degradation): monkeypatch events.jsonl append to raise PermissionError; assert engine-state.json write still succeeds and a warning is emitted")