workstate-bootstrap 0.7.2__tar.gz → 0.7.3__tar.gz

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## [0.7.3] — 2026-06-03
+
+### Changed
+
+- TODO: summarize this release.
+
+
 ## [0.7.2] — 2026-06-02
 
 > Ships the linked-worktree overlay self-heal (implementation note) **and** its deferred

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstate-bootstrap
-Version: 0.7.2
+Version: 0.7.3
 Summary: Bootstrap CLI that hoists the shared workstate-system surface into consumer repos.
 Project-URL: Homepage, https://github.com/darce/workstate
 Project-URL: Source, https://github.com/darce/workstate/tree/main/packages/workstate-bootstrap
@@ -12,7 +12,7 @@ Requires-Python: >=3.11
 Requires-Dist: pyyaml>=6
 Requires-Dist: tomlkit>=0.13
 Requires-Dist: workstate-protocol<0.2.0,>=0.1.7
-Requires-Dist: workstate-system<0.2.0,>=0.1.2
+Requires-Dist: workstate-system<0.2.0,>=0.1.3
 Provides-Extra: dev
 Requires-Dist: mcp-workstate-handoff; (python_version >= '3.12') and extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
@@ -120,9 +120,11 @@ overlay starts absent — the plugin is enabled (tracked
 `.claude/settings.json`) but unresolvable. Self-heal works as follows:
 
 - **`make task-start`** (the supported flow) adopts the overlay into the
-  new worktree automatically, so it works out of the box. Set
-  `WORKSTATE_ADOPT_CMD=""` to disable that auto-adopt (e.g. inside the
-  workstate monorepo, where worktrees resolve via the editable `.venv`).
+  new worktree automatically, so it works out of the box. In source
+  checkouts, the lifecycle uses the freshly provisioned worktree `.venv`
+  `workstate-bootstrap` command when available, then falls back to `uvx`.
+  Set `WORKSTATE_ADOPT_CMD=""` to disable auto-adopt, or set it to a custom
+  command to override that default.
 - **Raw `git worktree add` / auto-worktrees** are healed on demand:
 
   ```bash

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/README.md

@@ -100,9 +100,11 @@ overlay starts absent — the plugin is enabled (tracked
 `.claude/settings.json`) but unresolvable. Self-heal works as follows:
 
 - **`make task-start`** (the supported flow) adopts the overlay into the
-  new worktree automatically, so it works out of the box. Set
-  `WORKSTATE_ADOPT_CMD=""` to disable that auto-adopt (e.g. inside the
-  workstate monorepo, where worktrees resolve via the editable `.venv`).
+  new worktree automatically, so it works out of the box. In source
+  checkouts, the lifecycle uses the freshly provisioned worktree `.venv`
+  `workstate-bootstrap` command when available, then falls back to `uvx`.
+  Set `WORKSTATE_ADOPT_CMD=""` to disable auto-adopt, or set it to a custom
+  command to override that default.
 - **Raw `git worktree add` / auto-worktrees** are healed on demand:
 
   ```bash

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workstate-bootstrap"
-version = "0.7.2"
+version = "0.7.3"
 description = "Bootstrap CLI that hoists the shared workstate-system surface into consumer repos."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,7 +14,7 @@ dependencies = [
 	"tomlkit>=0.13",
 	"pyyaml>=6",
 	"workstate-protocol>=0.1.7,<0.2.0",
-	"workstate-system>=0.1.2,<0.2.0",
+	"workstate-system>=0.1.3,<0.2.0",
 ]
 
 [project.scripts]

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/src/workstate_bootstrap/adopt.py

@@ -48,6 +48,7 @@ from workstate_bootstrap.install import (
     _install_lifecycle_profile,
     _is_repointable_bootstrap_symlink,
     _materialize_surfaces,
+    _overlay_surfaces_self_managed,
     _prepare_generated_surfaces,
     _raw_symlink_target_path,
     _resolve_in_clone,
@@ -186,10 +187,16 @@ def _compute_drift(target: Path, primary: Path, clone: Path) -> list[str]:
         drift.append("Makefile")
 
     # Managed overlay-ignore block (keeps git status clean). apply writes it, so
-    # --check must verify it too, else a missing block silently regresses.
+    # --check must verify it too, else a missing block silently regresses. But a
+    # self-hosting source repo manages the surfaces itself (tracked or already
+    # ignored): apply skips the block there, so --check must too — otherwise the
+    # block is reported as perpetual, unsatisfiable drift.
     gitignore = target / ".gitignore"
     gitignore_text = gitignore.read_text() if gitignore.exists() else ""
-    if GITIGNORE_SENTINEL_BEGIN not in gitignore_text:
+    if (
+        GITIGNORE_SENTINEL_BEGIN not in gitignore_text
+        and not _overlay_surfaces_self_managed(target)
+    ):
         drift.append(".gitignore")
 
     # core.hooksPath (resolved against this worktree's config).

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/src/workstate_bootstrap/install.py

@@ -148,6 +148,13 @@ def _finalize_install_manifest(
 # fake_remote_with_surfaces fixture used elsewhere in the test suite).
 WORKSTATE_SYSTEM_SUBDIR = "packages/workstate-system"
 
+# implementation note S3: the shipped overlay payload moved under
+# packages/workstate-system/workstate_system/payload/. Probe this co-located
+# payload root FIRST when resolving a surface in the clone, keeping the pre-S3
+# subdir and the clone root as fallbacks for already-installed / hoisted
+# consumers (and the fake_remote_with_surfaces test fixture).
+WORKSTATE_SYSTEM_PAYLOAD_SUBDIR = "packages/workstate-system/workstate_system/payload"
+
 # Shared overlay surfaces materialized as symlinks into ``.workstate/remote``.
 # Per-agent surfaces (.claude/skills, .claude/commands, .github/prompts,
 # .codex/skills) are no longer canonical in the overlay clone; they are
@@ -297,7 +304,7 @@ DEFAULT_MCP_SERVERS: dict[str, dict[str, Any]] = {
         "type": "stdio",
         "command": "uvx",
         "args": [
-            "mcp-workstate-handoff@0.12.0",
+            "mcp-workstate-handoff@0.12.1",
             "--workspace-root",
             ".",
             "serve-stdio",
@@ -307,7 +314,7 @@ DEFAULT_MCP_SERVERS: dict[str, dict[str, Any]] = {
         "type": "stdio",
         "command": "uvx",
         "args": [
-            "mcp-workstate-orchestrator@0.5.1",
+            "mcp-workstate-orchestrator@0.5.2",
             "--workspace-root",
             ".",
             "serve-stdio",
@@ -495,6 +502,13 @@ def _presync_local_mcp_envs(
         if project in seen or not (project / "pyproject.toml").is_file():
             continue
         seen.add(project)
+        # Base sync only — no optional extras. The orchestrator's `bridge` extra
+        # (workstate-codex-bridge for the `codex-subagent` backend) is host-specific
+        # and unpublished, so presync deliberately leaves it out to keep install
+        # cheap and bridge-free. When a server then launches from this venv, the
+        # bridge is absent and `list_available_backends(probe=true)` reports the
+        # backend as `declared_not_installed` rather than falsely available. Install
+        # the bridge on demand with `uv sync --extra bridge` against that project.
         subprocess.run(
             ["uv", "sync", "--project", str(project)],
             check=True,
@@ -737,18 +751,22 @@ def _resolve_ref_to_sha(clone: Path, remote_ref: str) -> str:
 def _resolve_in_clone(clone: Path, relpath: str) -> Path:
     """Resolve a surface/asset path against the clone.
 
-    Probes ``<clone>/packages/workstate-system/<relpath>`` first (the
-    workstate layout) and falls back to ``<clone>/<relpath>``
-    for legacy hoisted overlays. Returns the nested path when neither exists
-    so callers can use ``.exists()`` as the discriminator.
+    Probes ``<clone>/packages/workstate-system/workstate_system/payload/<relpath>``
+    first (the implementation note S3 co-located payload layout), then the pre-S3
+    ``<clone>/packages/workstate-system/<relpath>``, then ``<clone>/<relpath>``
+    for legacy hoisted overlays. Returns the co-located payload path when none
+    exists so callers can use ``.exists()`` as the discriminator.
     """
+    payload = clone / WORKSTATE_SYSTEM_PAYLOAD_SUBDIR / relpath
+    if payload.exists():
+        return payload
     nested = clone / WORKSTATE_SYSTEM_SUBDIR / relpath
     if nested.exists():
         return nested
     root = clone / relpath
     if root.exists():
         return root
-    return nested
+    return payload
 
 
 def _materialize_one_symlink(
@@ -1683,6 +1701,103 @@ def _consumer_gitignore_entries() -> list[str]:
     return entries
 
 
+def _git_path_is_tracked(target: Path, rel: str) -> bool:
+    """True when ``rel`` (relative to ``target``) has tracked content in git.
+
+    ``git ls-files --error-unmatch`` exits non-zero when the pathspec matches no
+    tracked file; for a tracked directory it matches the tracked children and
+    exits 0. Any git failure (non-zero exit, git absent, not a repo) is reported
+    as "not tracked" so the conservative default keeps the managed block.
+    """
+    try:
+        subprocess.run(
+            ["git", "-C", str(target), "ls-files", "--error-unmatch", "--", rel],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except (
+        subprocess.CalledProcessError,
+        subprocess.TimeoutExpired,
+        FileNotFoundError,
+        OSError,
+    ):
+        return False
+    return True
+
+
+def _git_path_is_ignored(target: Path, rel: str) -> bool:
+    """True when git already ignores ``rel`` (relative to ``target``).
+
+    ``git check-ignore -q`` exits 0 when the path is ignored, 1 when not, and 128
+    on error. Only exit 0 counts as ignored; anything else (including git absent /
+    not a repo) is "not ignored" so the conservative default keeps the block.
+
+    Probes a child path as a fallback: a hand-authored ``.gitignore`` commonly uses
+    a directory-only pattern (``.task-state/``, ``/.github/prompts/``) which
+    ``check-ignore`` will NOT match against the bare path when that directory does
+    not yet exist on disk (the very M1 trailing-slash subtlety the managed block
+    avoids). An ignored directory ignores its contents, so a child probe matches a
+    ``dir/`` pattern regardless of whether the directory has been materialized.
+    """
+    for probe in (rel, f"{rel}/.workstate-overlay-probe"):
+        try:
+            proc = subprocess.run(
+                ["git", "-C", str(target), "check-ignore", "-q", "--", probe],
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            return False
+        if proc.returncode == 0:
+            return True
+        if proc.returncode != 1:  # 128 / fatal — be conservative, keep the block
+            return False
+    return False
+
+
+def _leaking_overlay_entries(target: Path) -> list[str]:
+    """Managed overlay entries that would surface in ``git status`` as untracked —
+    i.e. neither tracked nor already ignored by the consumer's own config.
+
+    These are the ONLY entries the managed overlay-ignore block needs, and the
+    only ones it is *safe* to ignore. An entry that is already tracked is the
+    repo's own source — emitting a root-anchored ``/scripts/hooks`` ignore for it
+    would silently make that tracked source un-trackable (the footgun). An entry
+    already ignored is redundant. Filtering per-entry (rather than all-or-nothing)
+    keeps a MIXED self-host safe: a transiently-leaking new surface still gets an
+    ignore line while a sibling tracked-source surface never does.
+
+    Order is preserved from :func:`_consumer_gitignore_entries` for a stable block.
+    The caller checks for our own sentinel block first, so this never sees a
+    previously-written managed block masking the consumer's own config.
+    """
+    leaking: list[str] = []
+    for entry in _consumer_gitignore_entries():
+        rel = entry.lstrip("/")
+        if not (_git_path_is_tracked(target, rel) or _git_path_is_ignored(target, rel)):
+            leaking.append(entry)
+    return leaking
+
+
+def _overlay_surfaces_self_managed(target: Path) -> bool:
+    """True when ``target`` already tracks or ignores every managed overlay
+    surface on its own — the self-hosting source repo case (no entry leaks).
+
+    The managed overlay-ignore block exists for ONE reason: keep the adopted
+    overlay symlinks out of ``git status``. The workstate monorepo self-hosts the
+    overlay — it ships a hand-authored ``.gitignore`` that already ignores the
+    very same root surfaces (and a tracked-source layout may even version-control
+    them). When nothing leaks, the block is wholly unnecessary, so adopt/install
+    skip it (and ``adopt --check`` must not report it as drift). A normal external
+    consumer — freshly materialized symlinks, untracked and not yet ignored — has
+    leaking surfaces and still gets a block.
+    """
+    return not _leaking_overlay_entries(target)
+
+
 def _ensure_consumer_gitignore_block(target: Path) -> dict[str, str]:
     """Idempotently maintain a sentinel-delimited overlay-ignore block in
     ``<target>/.gitignore``.
@@ -1692,23 +1807,31 @@ def _ensure_consumer_gitignore_block(target: Path) -> dict[str, str]:
     uninstall can excise it cleanly, and never clobbers a user-authored
     ``.gitignore`` (the block is appended, preserving prior content). Keeps an
     installed/adopted overlay out of ``git status``. Returns the action taken
-    (``created`` / ``appended`` / ``already_present``).
+    (``created`` / ``appended`` / ``already_present`` / ``skipped_self_managed``).
+
+    Only the *leaking* managed entries are emitted (see
+    :func:`_leaking_overlay_entries`): a tracked surface is never ignored (closing
+    the self-hosting-source footgun even in a MIXED layout), and an already-ignored
+    surface is not duplicated. When nothing leaks the whole block is skipped.
     """
+    leaking = _leaking_overlay_entries(target)
     gitignore = target / ".gitignore"
+    existing = gitignore.read_text() if gitignore.exists() else None
+    if existing is not None and GITIGNORE_SENTINEL_BEGIN in existing:
+        return {"path": ".gitignore", "action": "already_present"}
+    if not leaking:
+        return {"path": ".gitignore", "action": "skipped_self_managed"}
     block = (
         GITIGNORE_SENTINEL_BEGIN
         + "\n"
-        + "\n".join(_consumer_gitignore_entries())
+        + "\n".join(leaking)
         + "\n"
         + GITIGNORE_SENTINEL_END
         + "\n"
     )
-    if not gitignore.exists():
+    if existing is None:
         gitignore.write_text(block)
         return {"path": ".gitignore", "action": "created"}
-    existing = gitignore.read_text()
-    if GITIGNORE_SENTINEL_BEGIN in existing:
-        return {"path": ".gitignore", "action": "already_present"}
     sep = "" if existing.endswith("\n") else "\n"
     gitignore.write_text(existing + sep + block)
     return {"path": ".gitignore", "action": "appended"}

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/tests/test_adopt_worktree.py

@@ -501,6 +501,57 @@ def test_check_reports_drift_when_gitignore_block_removed(
     assert ".gitignore" in receipt["drift"]
 
 
+def test_adopt_self_hosting_worktree_does_not_touch_tracked_gitignore(
+    tmp_path: Path,
+) -> None:
+    """Self-hosting source repo (the workstate monorepo): a feature worktree
+    inherits a TRACKED ``.gitignore`` that already ignores the overlay surfaces.
+    Adopt must NOT append the managed block — doing so dirties every feature
+    worktree's tracked ``.gitignore`` (and its root-anchored patterns would ignore
+    the repo's own tracked source). ``--check`` must agree it is clean, not report
+    perpetual, unsatisfiable ``.gitignore`` drift.
+    """
+    primary, _clone = _make_installed_primary(tmp_path / "primary")
+    # The self-hosting primary tracks a hand-authored .gitignore covering the
+    # runtime dirs + the overlay surfaces (a mix of root-anchored and
+    # directory-only patterns, as the live monorepo ships).
+    (primary / ".gitignore").write_text(
+        ".workstate/\n"
+        ".task-state/\n"
+        "/scripts/hooks\n"
+        "/.github/hooks\n"
+        "/docs/workstate/contracts\n"
+        "/docs/workstate/rules\n"
+        "/Makefile.d\n"
+        "/scripts/workstate\n"
+        "/.github/prompts/\n"
+    )
+    _git("add", ".gitignore", cwd=primary)
+    _git("commit", "-m", "hand-authored overlay ignores", cwd=primary)
+
+    wt = _add_worktree(primary, tmp_path / "wt")
+    tracked_before = (wt / ".gitignore").read_text()
+
+    receipt = adopt_worktree(target=wt, primary=primary)
+
+    assert receipt["adopted"] is True
+    assert receipt["gitignore"]["action"] == "skipped_self_managed"
+    # The tracked .gitignore is byte-for-byte untouched — no managed block, no
+    # spurious working-tree modification.
+    assert (wt / ".gitignore").read_text() == tracked_before
+    assert "WORKSTATE_BOOTSTRAP OVERLAY IGNORE" not in tracked_before
+    gitignore_status = [
+        line
+        for line in _git("status", "--porcelain", cwd=wt).splitlines()
+        if ".gitignore" in line
+    ]
+    assert gitignore_status == [], gitignore_status
+
+    # --check must not report .gitignore as drift (apply skipped it on purpose).
+    check = adopt_worktree(target=wt, primary=primary, check=True)
+    assert ".gitignore" not in check["drift"], check["drift"]
+
+
 # ---------------------------------------------------------------------------
 # implementation note S1: apply and --check share ONE surface enumeration
 #

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/tests/test_bootstrap_install_rehearsal.py

@@ -236,8 +236,8 @@ def test_install_with_default_servers_requires_uvx_in_args() -> None:
         assert entry["command"] == "uvx", (name, entry)
         assert "--workspace-root" in entry["args"], (name, entry)
         assert entry["args"][-1] == "serve-stdio", (name, entry)
-    assert DEFAULT_MCP_SERVERS["workstate-handoff-mcp"]["args"][0] == "mcp-workstate-handoff@0.12.0"
-    assert DEFAULT_MCP_SERVERS["workstate-orchestrator-mcp"]["args"][0] == "mcp-workstate-orchestrator@0.5.1"
+    assert DEFAULT_MCP_SERVERS["workstate-handoff-mcp"]["args"][0] == "mcp-workstate-handoff@0.12.1"
+    assert DEFAULT_MCP_SERVERS["workstate-orchestrator-mcp"]["args"][0] == "mcp-workstate-orchestrator@0.5.2"
 
 
 def test_rehearsal_hoists_plan_targets_makefile_and_shell_wrapper(

workstate_bootstrap-0.7.3/tests/test_clone_payload_resolution.py

@@ -0,0 +1,59 @@
+"""implementation note S3: the clone resolver must find surfaces at the co-located
+``workstate_system/payload/`` layout that a fresh monorepo clone now has.
+
+This is the runbook's "highest-risk gap": the monorepo's own make/hooks read the
+package SOURCE directly, so an in-repo regression in the CLONE resolver
+(``_resolve_in_clone``) is invisible to every other test — a downstream consumer
+cloning the monorepo would silently materialize an EMPTY overlay. These tests
+pin the payload-first probe + the legacy fallback directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from workstate_bootstrap.install import (
+    SHARED_SURFACES,
+    WORKSTATE_SYSTEM_PAYLOAD_SUBDIR,
+    WORKSTATE_SYSTEM_SUBDIR,
+    _resolve_in_clone,
+)
+
+
+def _seed(base: Path, surface: str) -> Path:
+    target = base / surface
+    target.mkdir(parents=True, exist_ok=True)
+    (target / "marker.txt").write_text("x", encoding="utf-8")
+    return target
+
+
+def test_resolve_in_clone_finds_every_shared_surface_at_payload_layout(tmp_path: Path) -> None:
+    """A clone at the post-S3 layout resolves every SHARED_SURFACE non-empty."""
+    clone = tmp_path / "clone"
+    payload = clone / WORKSTATE_SYSTEM_PAYLOAD_SUBDIR
+    for surface in SHARED_SURFACES:
+        _seed(payload, surface)
+
+    for surface in SHARED_SURFACES:
+        resolved = _resolve_in_clone(clone, surface)
+        assert resolved == payload / surface, surface
+        assert resolved.exists() and any(resolved.iterdir()), (
+            f"surface {surface} resolved empty from a payload-layout clone"
+        )
+
+
+def test_resolve_in_clone_keeps_legacy_subdir_fallback(tmp_path: Path) -> None:
+    """Already-installed/hoisted consumers at the pre-S3 layout still resolve."""
+    clone = tmp_path / "clone"
+    _seed(clone / WORKSTATE_SYSTEM_SUBDIR, "scripts/hooks")
+    resolved = _resolve_in_clone(clone, "scripts/hooks")
+    assert resolved == clone / WORKSTATE_SYSTEM_SUBDIR / "scripts" / "hooks"
+    assert resolved.exists()
+
+
+def test_resolve_in_clone_payload_wins_over_legacy(tmp_path: Path) -> None:
+    """When both layouts exist, the co-located payload is canonical."""
+    clone = tmp_path / "clone"
+    _seed(clone / WORKSTATE_SYSTEM_PAYLOAD_SUBDIR, "skills")
+    _seed(clone / WORKSTATE_SYSTEM_SUBDIR, "skills")
+    assert _resolve_in_clone(clone, "skills") == clone / WORKSTATE_SYSTEM_PAYLOAD_SUBDIR / "skills"

workstate_bootstrap-0.7.3/tests/test_gitignore_block.py

@@ -0,0 +1,259 @@
+"""TDD gate for implementation note Slice S4: managed consumer ``.gitignore`` block.
+
+An installed/adopted overlay materializes the runtime dir (``.workstate``) and a
+set of surface SYMLINKS (``Makefile.d``, ``scripts/hooks`` …). Without ignore
+rules these show as untracked, so ``git status`` is never clean. A managed,
+sentinel-delimited block (mirroring the Makefile-include pattern) keeps it clean
+without clobbering a user-authored ``.gitignore``.
+
+M1: the patterns must be ROOT-ANCHORED and NON-trailing-slash — a trailing-slash
+pattern matches only directories, but git treats a symlink as a non-directory,
+so ``Makefile.d/`` would miss an adopted ``Makefile.d`` symlink.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from workstate_bootstrap.install import (
+    GITIGNORE_SENTINEL_BEGIN,
+    _consumer_gitignore_entries,
+    _ensure_consumer_gitignore_block,
+)
+
+
+def _git(*args: str, cwd: Path) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        check=True,
+        capture_output=True,
+        text=True,
+        cwd=str(cwd),
+        timeout=30,
+    )
+    return result.stdout.strip()
+
+
+def _init_repo(root: Path) -> None:
+    root.mkdir(parents=True, exist_ok=True)
+    _git("init", "--initial-branch=main", cwd=root)
+    _git("config", "user.email", "t@e.com", cwd=root)
+    _git("config", "user.name", "T", cwd=root)
+
+
+def _is_ignored(repo: Path, rel: str) -> bool:
+    return (
+        subprocess.run(
+            ["git", "-C", str(repo), "check-ignore", "-q", "--", rel], timeout=30
+        ).returncode
+        == 0
+    )
+
+
+def test_block_created_when_no_gitignore(tmp_path: Path) -> None:
+    target = tmp_path / "consumer"
+    target.mkdir()
+    result = _ensure_consumer_gitignore_block(target)
+    assert result == {"path": ".gitignore", "action": "created"}
+    text = (target / ".gitignore").read_text()
+    assert GITIGNORE_SENTINEL_BEGIN in text
+    assert "/.workstate" in text
+    assert "/Makefile.d" in text
+
+
+def test_block_appended_preserves_user_content(tmp_path: Path) -> None:
+    target = tmp_path / "consumer"
+    target.mkdir()
+    (target / ".gitignore").write_text("# user\n*.log\nbuild/\n")
+    result = _ensure_consumer_gitignore_block(target)
+    assert result == {"path": ".gitignore", "action": "appended"}
+    text = (target / ".gitignore").read_text()
+    assert "*.log" in text and "build/" in text  # user content preserved
+    assert GITIGNORE_SENTINEL_BEGIN in text
+
+
+def test_block_is_idempotent(tmp_path: Path) -> None:
+    target = tmp_path / "consumer"
+    target.mkdir()
+    _ensure_consumer_gitignore_block(target)
+    result = _ensure_consumer_gitignore_block(target)
+    assert result == {"path": ".gitignore", "action": "already_present"}
+    # No duplicate block.
+    assert (target / ".gitignore").read_text().count(GITIGNORE_SENTINEL_BEGIN) == 1
+
+
+def test_block_ignores_symlink_surfaces_git_status_clean(tmp_path: Path) -> None:
+    """M1 regression: the block must ignore adopted SYMLINK surfaces + .workstate
+    so `git status` shows nothing but the .gitignore itself."""
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    external = tmp_path / "external"
+    external.mkdir()
+
+    # Materialize the overlay shape: a real .workstate dir with a child symlink,
+    # plus whole-dir surface symlinks (as adoption produces).
+    (repo / ".workstate").mkdir()
+    (repo / ".workstate" / "remote").symlink_to(external)
+    (repo / "Makefile.d").symlink_to(external)
+    (repo / "scripts").mkdir()
+    (repo / "scripts" / "hooks").symlink_to(external)
+    (repo / ".github").mkdir()
+    (repo / ".github" / "hooks").symlink_to(external)
+
+    _ensure_consumer_gitignore_block(repo)
+
+    status_lines = [
+        line
+        for line in _git("status", "--porcelain", cwd=repo).splitlines()
+        if line.strip()
+    ]
+    # Only the .gitignore itself may be untracked; no overlay path leaks.
+    assert all(".gitignore" in line for line in status_lines), status_lines
+    for leaked in (".workstate", "Makefile.d", "scripts/hooks", ".github/hooks"):
+        assert all(leaked not in line for line in status_lines), (leaked, status_lines)
+
+
+# ---------------------------------------------------------------------------
+# Self-hosting source repo guard: the workstate monorepo IS the overlay source,
+# so its surfaces are tracked (or already ignored by a hand-authored .gitignore).
+# Appending the managed block there dirties every feature worktree's TRACKED
+# .gitignore — and would ignore the repo's own tracked source. The block must be
+# skipped when the consumer already manages every managed surface itself.
+# ---------------------------------------------------------------------------
+
+
+# Managed entries that name overlay *surfaces* (not the runtime .workstate /
+# .task-state dirs). These are the paths a self-hosting repo tracks as real
+# source and that the root-anchored block would dangerously ignore.
+_TRACKED_SURFACE_DIRS = (
+    "scripts/hooks",
+    "Makefile.d",
+    "scripts/workstate",
+    "docs/workstate/contracts",
+    "docs/workstate/rules",
+    ".github/hooks",
+    ".github/prompts",
+)
+
+
+def test_block_skipped_when_surfaces_are_tracked_source(tmp_path: Path) -> None:
+    """Footgun guard: when the overlay surfaces are TRACKED source dirs (the
+    self-hosting monorepo), the managed block must NOT be written — its
+    root-anchored ``/scripts/hooks`` … patterns would start ignoring the repo's
+    own version-controlled source."""
+    repo = tmp_path / "monorepo"
+    _init_repo(repo)
+    # Track real source at every managed surface path.
+    for rel in _TRACKED_SURFACE_DIRS:
+        d = repo / rel
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "source.py").write_text("# real tracked overlay source\n")
+    # The repo still ignores its runtime dirs itself (as the live monorepo does).
+    (repo / ".gitignore").write_text(".workstate/\n.task-state/\n")
+    _git("add", "-A", cwd=repo)
+    _git("commit", "-m", "tracked overlay source", cwd=repo)
+
+    result = _ensure_consumer_gitignore_block(repo)
+
+    assert result == {"path": ".gitignore", "action": "skipped_self_managed"}
+    assert GITIGNORE_SENTINEL_BEGIN not in (repo / ".gitignore").read_text()
+    # The footgun must not occur: tracked source must never become ignored.
+    for rel in _TRACKED_SURFACE_DIRS:
+        assert not _is_ignored(repo, rel), f"tracked source {rel} must not be ignored"
+    # Sanity: every tracked surface still appears in git's tracked set.
+    tracked = _git("ls-files", cwd=repo).splitlines()
+    assert any(line.startswith("scripts/hooks/") for line in tracked)
+
+
+def test_block_skipped_when_surfaces_already_ignored(tmp_path: Path) -> None:
+    """The self-hosting monorepo ships a hand-authored ``.gitignore`` that already
+    ignores the overlay surfaces (some with directory-only ``dir/`` patterns). The
+    managed block must not be appended as a redundant duplicate that dirties every
+    feature worktree's tracked ``.gitignore``."""
+    repo = tmp_path / "monorepo"
+    _init_repo(repo)
+    # Mirror the live monorepo: a mix of root-anchored and directory-only
+    # (trailing-slash) patterns covering every managed entry.
+    hand_authored = (
+        ".workstate/\n"
+        ".task-state/\n"
+        "/scripts/hooks\n"
+        "/.github/hooks\n"
+        "/docs/workstate/contracts\n"
+        "/docs/workstate/rules\n"
+        "/Makefile.d\n"
+        "/scripts/workstate\n"
+        "/.github/prompts/\n"
+    )
+    (repo / ".gitignore").write_text(hand_authored)
+    _git("add", ".gitignore", cwd=repo)
+    _git("commit", "-m", "hand-authored overlay ignores", cwd=repo)
+    before = (repo / ".gitignore").read_text()
+
+    result = _ensure_consumer_gitignore_block(repo)
+
+    assert result == {"path": ".gitignore", "action": "skipped_self_managed"}
+    assert (repo / ".gitignore").read_text() == before  # untouched, no duplicate
+    assert GITIGNORE_SENTINEL_BEGIN not in before
+    # Idempotent: a second pass is still a clean skip, never an append.
+    assert _ensure_consumer_gitignore_block(repo)["action"] == "skipped_self_managed"
+
+
+def test_block_written_when_any_surface_leaks(tmp_path: Path) -> None:
+    """A real external consumer (surfaces freshly materialized, untracked, not yet
+    ignored) still gets the block — the self-managed guard only fires when every
+    managed surface is already tracked or ignored."""
+    repo = tmp_path / "consumer"
+    _init_repo(repo)
+    # Ignore the runtime dirs but leave the surfaces leaking (as before install).
+    (repo / ".gitignore").write_text(".workstate/\n.task-state/\n")
+    _git("add", ".gitignore", cwd=repo)
+    _git("commit", "-m", "runtime ignores only", cwd=repo)
+
+    result = _ensure_consumer_gitignore_block(repo)
+
+    assert result["action"] == "appended"
+    assert GITIGNORE_SENTINEL_BEGIN in (repo / ".gitignore").read_text()
+
+
+def test_mixed_self_host_never_ignores_tracked_surface(tmp_path: Path) -> None:
+    """MIXED self-host footgun gate: one surface is TRACKED source, another is a
+    still-leaking materialized symlink. The block must be written for the leaking
+    surface but must NEVER ignore the tracked surface — emitting a root-anchored
+    ``/scripts/hooks`` ignore over tracked source silently makes it un-trackable.
+    Per-entry filtering (not all-or-nothing) is what closes this."""
+    repo = tmp_path / "monorepo"
+    _init_repo(repo)
+    # Tracked source at one surface; runtime dirs ignored by hand-authored config.
+    (repo / "scripts" / "hooks").mkdir(parents=True)
+    (repo / "scripts" / "hooks" / "src.py").write_text("# tracked overlay source\n")
+    (repo / ".gitignore").write_text(".workstate/\n.task-state/\n")
+    _git("add", "-A", cwd=repo)
+    _git("commit", "-m", "tracked scripts/hooks + runtime ignores", cwd=repo)
+    # A genuinely-leaking surface: a materialized symlink, untracked + unignored.
+    external = tmp_path / "external"
+    external.mkdir()
+    (repo / "Makefile.d").symlink_to(external)
+
+    result = _ensure_consumer_gitignore_block(repo)
+
+    # A block IS written (the leaking surface needs ignoring)...
+    assert result["action"] == "appended"
+    text = (repo / ".gitignore").read_text()
+    assert GITIGNORE_SENTINEL_BEGIN in text
+    # ...but the tracked surface must NOT appear in it / must stay trackable.
+    assert "/scripts/hooks" not in text
+    assert not _is_ignored(repo, "scripts/hooks")
+    # ...while the leaking surface is now ignored.
+    assert "/Makefile.d" in text
+    assert _is_ignored(repo, "Makefile.d")
+
+
+def test_entries_helper_covers_surface_dirs() -> None:
+    """Pin: the surfaces the self-managed guard inspects are exactly the managed
+    entries, so a future surface addition is not silently excluded from the guard.
+    """
+    entries = {e.lstrip("/") for e in _consumer_gitignore_entries()}
+    for rel in _TRACKED_SURFACE_DIRS:
+        assert rel in entries, rel

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/tests/test_install.py

@@ -517,6 +517,23 @@ def fake_remote_with_generator(tmp_path: Path) -> tuple[str, str]:
     if system_root is None:
         pytest.skip("packages/workstate-system not available in this environment")
 
+    # implementation note S3: shipped overlay surfaces now live under the package's
+    # ``workstate_system/payload/`` tree. Reads of the REAL package source
+    # resolve payload-first, then fall back to the legacy top-level path for
+    # surfaces that stayed (e.g. ``Makefile.d/evals.mk``, ``scripts/workstate/
+    # evals``). The fake remote still mirrors the OLD consumer layout so the
+    # bootstrap resolver's legacy fallback probe keeps resolving.
+    payload_root = system_root / "workstate_system" / "payload"
+
+    def _real_surface_dirs(rel: str) -> list[Path]:
+        """Real source dirs for ``rel``, payload-first then legacy top-level.
+        Partial-move surfaces (Makefile.d, scripts/workstate) exist in both."""
+        return [d for d in (payload_root / rel, system_root / rel) if d.is_dir()]
+
+    def _merge_copytree(sources: list[Path], target_dir: Path) -> None:
+        for source_dir in sources:
+            shutil.copytree(source_dir, target_dir, dirs_exist_ok=True)
+
     src = tmp_path / "gen-src"
     src.mkdir()
     _git("init", "--initial-branch=main", cwd=src)
@@ -524,13 +541,13 @@ def fake_remote_with_generator(tmp_path: Path) -> tuple[str, str]:
     _git("config", "user.name", "Test", cwd=src)
     system_subdir = src / "packages" / "workstate-system"
     for surface in SHARED_SURFACES_EXPECTED:
-        source_dir = system_root / surface
+        source_dirs = _real_surface_dirs(surface)
         target_dir = system_subdir / surface
-        if source_dir.is_dir() and any(source_dir.iterdir()):
+        if source_dirs and any(any(d.iterdir()) for d in source_dirs):
             # Mirror the real surface so rehearsal tests see actual hoisted
             # content (e.g. implementation note implementation note needs Makefile.d/plans.mk's
             # launcher token to land verbatim).
-            shutil.copytree(source_dir, target_dir)
+            _merge_copytree(source_dirs, target_dir)
         else:
             target_dir.mkdir(parents=True)
             (target_dir / "MARKER.md").write_text(f"shared {surface}\n")
@@ -556,17 +573,19 @@ def fake_remote_with_generator(tmp_path: Path) -> tuple[str, str]:
             continue
         helper_path.write_text("#!/usr/bin/env python3\nimport sys; sys.exit(0)\n")
         helper_path.chmod(0o755)
-    # Generator + manifest + neutral skill source, all under packages/workstate-system/.
+    # Generator + manifest + neutral skill source. These surfaces MOVED to
+    # the payload tree (implementation note S3); read them from payload_root but mirror
+    # them into the fake remote at the OLD consumer layout.
     (system_subdir / "scripts").mkdir(parents=True, exist_ok=True)
     shutil.copy2(
-        system_root / "scripts" / "generate_agent_workflows.py",
+        payload_root / "scripts" / "generate_agent_workflows.py",
         system_subdir / "scripts" / "generate_agent_workflows.py",
     )
     shutil.copytree(
-        system_root / "config" / "agent-workflows",
+        payload_root / "config" / "agent-workflows",
         system_subdir / "config" / "agent-workflows",
     )
-    shutil.copytree(system_root / "skills", system_subdir / "skills")
+    shutil.copytree(payload_root / "skills", system_subdir / "skills")
 
     _git("add", "-A", cwd=src)
     _git("commit", "-m", "seed surfaces + generator", cwd=src)
@@ -680,7 +699,13 @@ def test_install_discovers_plugin_override_root_and_composes_effective_tree(
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    system_root = Path(__file__).resolve().parents[2] / "workstate-system"
+    # implementation note S3: skills/ moved into the package payload tree.
+    system_root = (
+        Path(__file__).resolve().parents[2]
+        / "workstate-system"
+        / "workstate_system"
+        / "payload"
+    )
     structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
     body = (system_root / "skills" / "branch-review" / "body.md").read_text()
@@ -767,7 +792,13 @@ def test_install_writes_tracked_override_lock_for_plugin_overrides(
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    system_root = Path(__file__).resolve().parents[2] / "workstate-system"
+    # implementation note S3: skills/ moved into the package payload tree.
+    system_root = (
+        Path(__file__).resolve().parents[2]
+        / "workstate-system"
+        / "workstate_system"
+        / "payload"
+    )
     structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
     body = (system_root / "skills" / "branch-review" / "body.md").read_text()
@@ -826,7 +857,13 @@ def test_install_accepts_explicit_plugin_override_root(
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    system_root = Path(__file__).resolve().parents[2] / "workstate-system"
+    # implementation note S3: skills/ moved into the package payload tree.
+    system_root = (
+        Path(__file__).resolve().parents[2]
+        / "workstate-system"
+        / "workstate_system"
+        / "payload"
+    )
     structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
     body = (system_root / "skills" / "branch-review" / "body.md").read_text()
@@ -894,7 +931,13 @@ def test_install_console_script_accepts_plugin_overrides_flag(
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    system_root = Path(__file__).resolve().parents[2] / "workstate-system"
+    # implementation note S3: skills/ moved into the package payload tree.
+    system_root = (
+        Path(__file__).resolve().parents[2]
+        / "workstate-system"
+        / "workstate_system"
+        / "payload"
+    )
     structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
     body = (system_root / "skills" / "branch-review" / "body.md").read_text()
@@ -969,7 +1012,13 @@ def test_install_points_plugin_pins_at_effective_tree_when_overrides_exist(
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    system_root = Path(__file__).resolve().parents[2] / "workstate-system"
+    # implementation note S3: skills/ moved into the package payload tree.
+    system_root = (
+        Path(__file__).resolve().parents[2]
+        / "workstate-system"
+        / "workstate_system"
+        / "payload"
+    )
     structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
     body = (system_root / "skills" / "branch-review" / "body.md").read_text()
@@ -1042,7 +1091,13 @@ def test_install_preserves_explicit_plugin_disable_when_overrides_exist(
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    system_root = Path(__file__).resolve().parents[2] / "workstate-system"
+    # implementation note S3: skills/ moved into the package payload tree.
+    system_root = (
+        Path(__file__).resolve().parents[2]
+        / "workstate-system"
+        / "workstate_system"
+        / "payload"
+    )
     structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
     body = (system_root / "skills" / "branch-review" / "body.md").read_text()
@@ -1116,7 +1171,13 @@ def test_install_reverts_effective_tree_pins_to_base_tree_when_overrides_disappe
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    system_root = Path(__file__).resolve().parents[2] / "workstate-system"
+    # implementation note S3: skills/ moved into the package payload tree.
+    system_root = (
+        Path(__file__).resolve().parents[2]
+        / "workstate-system"
+        / "workstate_system"
+        / "payload"
+    )
     structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
     body = (system_root / "skills" / "branch-review" / "body.md").read_text()
@@ -1181,7 +1242,13 @@ def test_install_reset_overrides_removes_clean_override_root(
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    system_root = Path(__file__).resolve().parents[2] / "workstate-system"
+    # implementation note S3: skills/ moved into the package payload tree.
+    system_root = (
+        Path(__file__).resolve().parents[2]
+        / "workstate-system"
+        / "workstate_system"
+        / "payload"
+    )
     structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
     body = (system_root / "skills" / "branch-review" / "body.md").read_text()
@@ -2148,8 +2215,8 @@ def test_install_with_default_sentinel_uses_built_in_server_map(
         assert entry["type"] == "stdio"
         assert "--workspace-root" in entry["args"]
         assert entry["args"][-1] == "serve-stdio"
-    assert mcp_doc["mcpServers"]["workstate-handoff-mcp"]["args"][0] == "mcp-workstate-handoff@0.12.0"
-    assert mcp_doc["mcpServers"]["workstate-orchestrator-mcp"]["args"][0] == "mcp-workstate-orchestrator@0.5.1"
+    assert mcp_doc["mcpServers"]["workstate-handoff-mcp"]["args"][0] == "mcp-workstate-handoff@0.12.1"
+    assert mcp_doc["mcpServers"]["workstate-orchestrator-mcp"]["args"][0] == "mcp-workstate-orchestrator@0.5.2"
     for entry in vscode_doc["servers"].values():
         assert entry["type"] == "stdio"
         assert "--workspace-root" in entry["args"]
@@ -2355,7 +2422,7 @@ def test_run_init_state_retries_with_cloned_handoff_project_when_uvx_fails(
     )
 
     assert [cmd[0] for cmd, _ in calls] == ["uvx", "uv"]
-    assert calls[0][0][1] == "mcp-workstate-handoff@0.12.0"
+    assert calls[0][0][1] == "mcp-workstate-handoff@0.12.1"
     assert calls[1][0][:5] == [
         "uv",
         "run",
@@ -2659,7 +2726,7 @@ def test_run_init_state_surfaces_uvx_error_when_no_cloned_handoff_project_exists
 
     assert calls == [[
         "uvx",
-        "mcp-workstate-handoff@0.12.0",
+        "mcp-workstate-handoff@0.12.1",
         "--workspace-root",
         ".",
         "--state-dir",

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/tests/test_package_source.py

@@ -51,7 +51,7 @@ def _build_and_unpack_package(tmp: Path) -> Path:
     unpacked = tmp / "site"
     with zipfile.ZipFile(wheel) as zf:
         zf.extractall(unpacked)
-    root = unpacked / "workstate_system"
+    root = unpacked / "workstate_system" / "payload"
     assert (root / "scripts" / "hooks").is_dir(), (
         "unpacked payload missing scripts/hooks"
     )
@@ -156,7 +156,7 @@ def test_cli_install_from_package_resolves_installed_payload(
     from workstate_bootstrap.cli import main as cli_main
 
     package_root = _build_and_unpack_package(tmp_path)
-    monkeypatch.syspath_prepend(str(package_root.parent))
+    monkeypatch.syspath_prepend(str(package_root.parents[1]))
 
     target = tmp_path / "consumer"
     target.mkdir()

{workstate_bootstrap-0.7.2 → workstate_bootstrap-0.7.3}/tests/test_subcommands.py

@@ -383,9 +383,12 @@ def test_overlay_manifest_contract_documents_canonical_and_legacy() -> None:
     """WS-HARNESS-FAILSAFE-01 implementation note: the overlay-manifest contract doc must
     name the canonical `.workstate-bootstrap.json` ledger as well as the legacy
     `.workstate-overlay.json` read-compat manifest."""
+    # implementation note S3: docs/workstate/contracts moved into the package payload tree.
     contract = (
         Path(__file__).resolve().parents[2]
         / "workstate-system"
+        / "workstate_system"
+        / "payload"
         / "docs"
         / "workstate"
         / "contracts"
@@ -436,9 +439,12 @@ def _seed_branch_review_override_at(override_root: Path, system_root: Path) -> N
         "---\nname: branch-review\ndescription: local override\n---\n\nBootstrap-composed override body.\n"
     )
 
-    structured = yaml.safe_load((system_root / "skills" / "branch-review" / "skill.yaml").read_text())
+    # implementation note S3: skills/ moved into the package payload tree. Read the real
+    # upstream skill source from payload; the override layout above stays.
+    payload_root = system_root / "workstate_system" / "payload"
+    structured = yaml.safe_load((payload_root / "skills" / "branch-review" / "skill.yaml").read_text())
     structured.pop("generator", None)
-    body = (system_root / "skills" / "branch-review" / "body.md").read_text()
+    body = (payload_root / "skills" / "branch-review" / "body.md").read_text()
     fm_text = yaml.safe_dump(structured, sort_keys=False, default_flow_style=False).rstrip()
     base_skill = f"---\n{fm_text}\n---\n\n{body if body.endswith(chr(10)) else body + chr(10)}"
     upstream_digest = hashlib.sha256(base_skill.encode("utf-8")).hexdigest()
@@ -764,6 +770,20 @@ def _build_generator_two_ref_remote(
     if system_root is None:
         pytest.skip("packages/workstate-system not available in this environment")
 
+    # implementation note S3: shipped overlay surfaces now live under the package's
+    # ``workstate_system/payload/`` tree. Reads of the REAL package source
+    # resolve payload-first, then fall back to the legacy top-level path for
+    # surfaces that stayed (e.g. ``Makefile.d/evals.mk``, ``scripts/workstate/
+    # evals``). The fake remote still mirrors the OLD consumer layout.
+    payload_root = system_root / "workstate_system" / "payload"
+
+    def _real_surface_dirs(rel: str) -> list[Path]:
+        return [d for d in (payload_root / rel, system_root / rel) if d.is_dir()]
+
+    def _merge_copytree(sources: list[Path], target_dir: Path) -> None:
+        for source_dir in sources:
+            shutil.copytree(source_dir, target_dir, dirs_exist_ok=True)
+
     src = tmp_path / "gen-two-refs-src"
     src.mkdir()
     _git("init", "--initial-branch=main", cwd=src)
@@ -772,10 +792,10 @@ def _build_generator_two_ref_remote(
 
     system_subdir = src / "packages" / "workstate-system"
     for surface in SHARED_SURFACES_EXPECTED:
-        source_dir = system_root / surface
+        source_dirs = _real_surface_dirs(surface)
         target_dir = system_subdir / surface
-        if source_dir.is_dir() and any(source_dir.iterdir()):
-            shutil.copytree(source_dir, target_dir)
+        if source_dirs and any(any(d.iterdir()) for d in source_dirs):
+            _merge_copytree(source_dirs, target_dir)
         else:
             target_dir.mkdir(parents=True)
             (target_dir / "MARKER.md").write_text(f"shared {surface}\n")
@@ -797,14 +817,14 @@ def _build_generator_two_ref_remote(
 
     (system_subdir / "scripts").mkdir(parents=True, exist_ok=True)
     shutil.copy2(
-        system_root / "scripts" / "generate_agent_workflows.py",
+        payload_root / "scripts" / "generate_agent_workflows.py",
         system_subdir / "scripts" / "generate_agent_workflows.py",
     )
     shutil.copytree(
-        system_root / "config" / "agent-workflows",
+        payload_root / "config" / "agent-workflows",
         system_subdir / "config" / "agent-workflows",
     )
-    shutil.copytree(system_root / "skills", system_subdir / "skills")
+    shutil.copytree(payload_root / "skills", system_subdir / "skills")
 
     _git("add", "-A", cwd=src)
     _git("commit", "-m", "v1", cwd=src)
@@ -1191,9 +1211,10 @@ def test_doctor_reports_hidden_override_collision_for_undeclared_skill(
     _init_git_repo(target)
     _seed_branch_review_override(target, system_root)
 
+    # implementation note S3: skills/ moved into the package payload tree.
     colliding_skill = next(
         path.name
-        for path in (system_root / "skills").iterdir()
+        for path in (system_root / "workstate_system" / "payload" / "skills").iterdir()
         if path.is_dir() and path.name != "branch-review"
     )
     undeclared_skill = (

workstate_bootstrap-0.7.2/tests/test_gitignore_block.py

@@ -1,104 +0,0 @@
-"""TDD gate for implementation note Slice S4: managed consumer ``.gitignore`` block.
-
-An installed/adopted overlay materializes the runtime dir (``.workstate``) and a
-set of surface SYMLINKS (``Makefile.d``, ``scripts/hooks`` …). Without ignore
-rules these show as untracked, so ``git status`` is never clean. A managed,
-sentinel-delimited block (mirroring the Makefile-include pattern) keeps it clean
-without clobbering a user-authored ``.gitignore``.
-
-M1: the patterns must be ROOT-ANCHORED and NON-trailing-slash — a trailing-slash
-pattern matches only directories, but git treats a symlink as a non-directory,
-so ``Makefile.d/`` would miss an adopted ``Makefile.d`` symlink.
-"""
-
-from __future__ import annotations
-
-import subprocess
-from pathlib import Path
-
-from workstate_bootstrap.install import (
-    GITIGNORE_SENTINEL_BEGIN,
-    _ensure_consumer_gitignore_block,
-)
-
-
-def _git(*args: str, cwd: Path) -> str:
-    result = subprocess.run(
-        ["git", *args],
-        check=True,
-        capture_output=True,
-        text=True,
-        cwd=str(cwd),
-        timeout=30,
-    )
-    return result.stdout.strip()
-
-
-def _init_repo(root: Path) -> None:
-    root.mkdir(parents=True, exist_ok=True)
-    _git("init", "--initial-branch=main", cwd=root)
-    _git("config", "user.email", "t@e.com", cwd=root)
-    _git("config", "user.name", "T", cwd=root)
-
-
-def test_block_created_when_no_gitignore(tmp_path: Path) -> None:
-    target = tmp_path / "consumer"
-    target.mkdir()
-    result = _ensure_consumer_gitignore_block(target)
-    assert result == {"path": ".gitignore", "action": "created"}
-    text = (target / ".gitignore").read_text()
-    assert GITIGNORE_SENTINEL_BEGIN in text
-    assert "/.workstate" in text
-    assert "/Makefile.d" in text
-
-
-def test_block_appended_preserves_user_content(tmp_path: Path) -> None:
-    target = tmp_path / "consumer"
-    target.mkdir()
-    (target / ".gitignore").write_text("# user\n*.log\nbuild/\n")
-    result = _ensure_consumer_gitignore_block(target)
-    assert result == {"path": ".gitignore", "action": "appended"}
-    text = (target / ".gitignore").read_text()
-    assert "*.log" in text and "build/" in text  # user content preserved
-    assert GITIGNORE_SENTINEL_BEGIN in text
-
-
-def test_block_is_idempotent(tmp_path: Path) -> None:
-    target = tmp_path / "consumer"
-    target.mkdir()
-    _ensure_consumer_gitignore_block(target)
-    result = _ensure_consumer_gitignore_block(target)
-    assert result == {"path": ".gitignore", "action": "already_present"}
-    # No duplicate block.
-    assert (target / ".gitignore").read_text().count(GITIGNORE_SENTINEL_BEGIN) == 1
-
-
-def test_block_ignores_symlink_surfaces_git_status_clean(tmp_path: Path) -> None:
-    """M1 regression: the block must ignore adopted SYMLINK surfaces + .workstate
-    so `git status` shows nothing but the .gitignore itself."""
-    repo = tmp_path / "repo"
-    _init_repo(repo)
-    external = tmp_path / "external"
-    external.mkdir()
-
-    # Materialize the overlay shape: a real .workstate dir with a child symlink,
-    # plus whole-dir surface symlinks (as adoption produces).
-    (repo / ".workstate").mkdir()
-    (repo / ".workstate" / "remote").symlink_to(external)
-    (repo / "Makefile.d").symlink_to(external)
-    (repo / "scripts").mkdir()
-    (repo / "scripts" / "hooks").symlink_to(external)
-    (repo / ".github").mkdir()
-    (repo / ".github" / "hooks").symlink_to(external)
-
-    _ensure_consumer_gitignore_block(repo)
-
-    status_lines = [
-        line
-        for line in _git("status", "--porcelain", cwd=repo).splitlines()
-        if line.strip()
-    ]
-    # Only the .gitignore itself may be untracked; no overlay path leaks.
-    assert all(".gitignore" in line for line in status_lines), status_lines
-    for leaked in (".workstate", "Makefile.d", "scripts/hooks", ".github/hooks"):
-        assert all(leaked not in line for line in status_lines), (leaked, status_lines)