workstate-bootstrap 0.6.0__tar.gz → 0.7.0__tar.gz

{workstate_bootstrap-0.6.0 → workstate_bootstrap-0.7.0}/CHANGELOG.md

@@ -2,11 +2,43 @@
 
 ## Unreleased
 
+## [0.7.0] — 2026-06-01
+
+### Added
+
+- **Package-source overlay delivery (WS-PKG-DELIVERY-01).** `install` /
+  `update` can resolve the harness overlay from an installed
+  `workstate-system` distribution (`source_kind="package"`) instead of a git
+  clone, writing a `package`-kind `BootstrapManifest`. `update` / `repair`
+  reject a package-source manifest with a clear error rather than
+  dereferencing a `remote_url` that package manifests do not carry.
+
+### Changed
+
+- **MCP launch decoupled from resolution (implementation note Theme A,
+  WS-MCP-LAUNCH-01).** Generated serve commands now use `uv run --no-sync`
+  and the server venvs are pre-built at install time
+  (`_presync_local_mcp_envs`), eliminating the cold-start re-sync race that
+  overran the harness's 30s MCP connection timeout and registered zero tools.
+  The `--no-sync` invariant is enforced at the shared render seam
+  (`_canonicalize_managed_servers`), so `install` / `update` / `repair` /
+  `mcp-sync` all rewrite an older launcher; the earlier preserve-path
+  `_normalize_local_mcp_server_specs` patch is retired.
+
+### Removed
+
+- **Runtime-path migration shim retired (implementation note Slice D cutover complete).**
+  The legacy-runtime-tree migration helpers (`migrate_runtime_paths()`,
+  `plan_runtime_path_migration()`) and the `legacy_runtime_path` `doctor` check
+  are removed. `.workstate/` / `docs/workstate/` are the sole runtime paths with
+  no backward compatibility — a consumer still carrying the pre-rebrand runtime
+  tree must reinstall cleanly.
+
 ## [0.6.0] — 2026-05-30
 
 ### Changed
 
-- **MCP server identity cutover (Plan 0013 Slice B).** Default managed servers
+- **MCP server identity cutover (implementation note Slice B).** Default managed servers
   register under the canonical `workstate-handoff-mcp` /
   `workstate-orchestrator-mcp` names. `LEGACY_MCP_SERVER_RENAMES` +
   `_legacy_prune_for()` dedup and forward-rewrite a stale `agent-*-mcp`
@@ -20,8 +52,8 @@
 
 ### Added
 
-- **Runtime path migration `.agentic/` → `.workstate/` and
-  `docs/agentic/` → `docs/workstate/` (Plan 0013 Slice D).**
+- **Runtime path migration `.workstate/` → `.workstate/` and
+  `docs/workstate/` → `docs/workstate/` (implementation note Slice D).**
   `migrate_runtime_paths()` / `plan_runtime_path_migration()` run on
   `install`/`update`: idempotent, archive-backed (a both-present collision
   moves the legacy tree aside rather than overwriting), dry-run-capable, and
@@ -41,11 +73,11 @@
 
 ### Fixed
 
-- **AHMCP-57 — stale shared-surface symlinks now repointed on rerun.**
+- **WORKSTATE-REF-57 — stale shared-surface symlinks now repointed on rerun.**
   When a consumer was installed pre-v0.2.0 (legacy root layout
   `<clone>/<surface>`) and the layout subsequently moved into
   `<clone>/packages/workstate-system/<surface>`, the target-side
-  `scripts/hooks -> ../.agentic/remote/scripts/hooks` symlink survived
+  `scripts/hooks -> ../.workstate/remote/scripts/hooks` symlink survived
   every subsequent `workstate-bootstrap install` because the pre-fix
   `points_into_clone` check still passed lexically for the broken
   resolved path. `_materialize_surfaces` now classifies each existing
@@ -61,7 +93,7 @@
 
 ### Changed
 
-- **AHMCP-56 — cross-harness install manifest is now the single source of
+- **WORKSTATE-REF-56 — cross-harness install manifest is now the single source of
   truth for hook adapter wiring.** `config/agent-workflows/portable_commands.json`
   schema v2 introduces a top-level `hooks[]` array; install dispatches
   adapter rows through a manifest-driven walker (closed-set operation
@@ -99,17 +131,17 @@
 
 - **Bump default managed MCP server pins** to `mcp-workstate-handoff@0.11.1`
   and `mcp-workstate-orchestrator@0.4.5` so consumer repos pick up the
-  AHMCP-54 (multi-active CURRENT_TASK projection, import/export
+  WORKSTATE-REF-54 (multi-active CURRENT_TASK projection, import/export
   malformed-payload rejection, target_branch/worktree_path/plan_path
-  preservation) and AHMCP-55 (compaction env-var namespace
-  consolidation under `AGENT_HANDOFF_COMPACTION_*` with `AHMCP_*` kept
+  preservation) and WORKSTATE-REF-55 (compaction env-var namespace
+  consolidation under `AGENT_HANDOFF_COMPACTION_*` with `WORKSTATE_*` kept
   as a deprecated alias) fixes by default.
 
 ## [0.4.1] — 2026-05-09
 
 ### Fixed
 
-- **`--profile all` now performs the lifecycle hoist** (AHMCP-48). The
+- **`--profile all` now performs the lifecycle hoist** (WORKSTATE-REF-48). The
   legacy default profile shipped lifecycle-referencing skills
   (`branch-lifecycle`, `tdd`, `incremental-implementation`,
   `branch-review`, `handoff-lifecycle`) but did not install the
@@ -142,11 +174,11 @@
 ### Added
 
 - **Install profile contract: `--profile {minimal,lifecycle,all}`**
-  (Plan 0009 / AHMCP-40 Slice 1.5.a). The CLI now accepts an explicit
+  (implementation note / WORKSTATE-REF-40 implementation note.5.a). The CLI now accepts an explicit
   install profile flag and honors it across the manifest layers, so
   consumer repos can pick a smaller hoist surface than the default.
-- **Hoist `Makefile.d/plans.mk` + `git-plan-cat.sh` stub** (Plan 0007 /
-  AHMCP-38 Slice 0). Consumer repos installed via `workstate-bootstrap`
+- **Hoist `Makefile.d/plans.mk` + `git-plan-cat.sh` stub** (implementation note /
+  WORKSTATE-REF-38 implementation note). Consumer repos installed via `workstate-bootstrap`
   pick up `make plan-show / plan-edit / plans-list / plan-register`
   out of the box; the targets shell out to `uvx mcp-workstate-handoff`
   under the hood.
@@ -160,14 +192,14 @@
 
 ## [0.3.1] — 2026-05-03
 
-- **Plan 0006 BR-01 — raise `workstate-protocol` lower bound to
+- **implementation note BR-01 — raise `workstate-protocol` lower bound to
   `>=0.1.2,<0.2.0`.** Bootstrap's default install path invokes
   `uvx mcp-workstate-handoff`, which imports `workstate_protocol.branch_naming`
   at startup; the previous `>=0.1.0` floor let `uvx` resolve a protocol
   release missing the module, crashing init-state on a fresh install. A
   new packaging test (`tests/test_package_metadata.py`) pins the floor
   so the declaration cannot silently drift back below the contract.
-- **Plan 0006 Slice 5 — install rehearsal pins six-hook surface +
+- **implementation note implementation note — install rehearsal pins six-hook surface +
   helper materialization.** `SHARED_GIT_HOOK_NAMES` now includes
   `pre-commit` (in addition to `post-checkout`, `post-commit`,
   `post-merge`, `post-rewrite`, `pre-push`); the install rehearsal
@@ -177,7 +209,7 @@
   post-checkout / pre-commit / pre-push hooks `exec`) is materialized
   alongside them. Without the helper, every branch-naming gate
   silently no-ops. The shared surface itself is unchanged
-  (`scripts/hooks` is symlinked from `.agentic/remote`); the new
+  (`scripts/hooks` is symlinked from `.workstate/remote`); the new
   assertion catches a future regression where the upstream package
   drops the helper.
 - **Manifest renamed: `.workstate-overlay.json` → `.workstate-bootstrap.json`
@@ -195,7 +227,7 @@
   --workspace-root . serve-stdio` into `.mcp.json`,
   `.vscode/mcp.json`, and `.codex/config.toml`, so external clients
   start runnable MCP servers from a fresh install or update.
-- **`regenerate-task-views` harness hook contract dropped (Plan 0005).**
+- **`regenerate-task-views` harness hook contract dropped (implementation note).**
   Bootstrap no longer materializes any Claude / VS Code / Codex hook
   wiring that invokes `regenerate-task-views`; `DASHBOARD.txt` is now
   auto-regenerated server-side inside `mcp-workstate-handoff` on every
@@ -208,7 +240,7 @@
 
 ## 0.3.0 — 2026-04-28
 
-- **Install-time state provisioning (Plan 0003).** `install` now runs
+- **Install-time state provisioning (implementation note).** `install` now runs
   the handoff server's `init-state` after surface/config materialization
   but before `core.hooksPath` is set, so a fresh install ends with a
   schema-current `.task-state/handoff.db` and `.task-state/exports/`
@@ -232,7 +264,7 @@
   gated on `.mcp.json` being present in the manifest's `configs` array
   so config-only installs (`--no-mcp-servers`) do not produce
   false-positive drift.
-- **`switch_task` cold-start fix.** Plan 0003 Slice 1 (in
+- **`switch_task` cold-start fix.** implementation note implementation note (in
   `mcp-workstate-handoff` 0.5.0+) drops `BranchMismatchError` from
   `switch_task`; the cold-start cycle (register task → `switch_task`
   → first content write) now completes from any branch. Branch
@@ -255,7 +287,7 @@
   `packages/workstate-system/` (the workstate monorepo layout) with
   fallback to the clone root for legacy hoisted overlays. Fixes
   `BootstrapManifestValidationError: required surface 'scripts/hooks' was
-  not materialized` against monorepo refs at or after Plan 0002 step 1.
+  not materialized` against monorepo refs at or after implementation note step 1.
 - Rehearsal fixture (`fake_remote_with_generator`) now mirrors the real
   monorepo layout so this regression cannot return silently.
 

{workstate_bootstrap-0.6.0 → workstate_bootstrap-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstate-bootstrap
-Version: 0.6.0
+Version: 0.7.0
 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
@@ -11,7 +11,8 @@ License: Proprietary
 Requires-Python: >=3.11
 Requires-Dist: pyyaml>=6
 Requires-Dist: tomlkit>=0.13
-Requires-Dist: workstate-protocol<0.2.0,>=0.1.6
+Requires-Dist: workstate-protocol<0.2.0,>=0.1.7
+Requires-Dist: workstate-system<0.2.0,>=0.1.0
 Provides-Extra: dev
 Requires-Dist: mcp-workstate-handoff; (python_version >= '3.12') and extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'

{workstate_bootstrap-0.6.0 → workstate_bootstrap-0.7.0}/pyproject.toml

@@ -4,13 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workstate-bootstrap"
-version = "0.6.0"
+version = "0.7.0"
 description = "Bootstrap CLI that hoists the shared workstate-system surface into consumer repos."
 readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "Proprietary" }
 authors = [{ name = "darce" }]
-dependencies = ["tomlkit>=0.13", "pyyaml>=6", "workstate-protocol>=0.1.6,<0.2.0"]
+dependencies = [
+	"tomlkit>=0.13",
+	"pyyaml>=6",
+	"workstate-protocol>=0.1.7,<0.2.0",
+	"workstate-system>=0.1.0,<0.2.0",
+]
 
 [project.scripts]
 workstate-bootstrap = "workstate_bootstrap.cli:main"
@@ -27,6 +32,7 @@ dev = ["pytest>=8", "mcp-workstate-handoff; python_version >= '3.12'"]
 [tool.uv.sources]
 mcp-workstate-handoff = { path = "../mcp-workstate-handoff", editable = true }
 workstate-protocol = { path = "../workstate-protocol", editable = true }
+workstate-system = { path = "../workstate-system", editable = true }
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/workstate_bootstrap"]

{workstate_bootstrap-0.6.0 → workstate_bootstrap-0.7.0}/src/workstate_bootstrap/cli.py

@@ -13,6 +13,7 @@ from workstate_bootstrap.install import (
     PROFILE_ALL,
     PROFILE_LIFECYCLE,
     PROFILE_MINIMAL,
+    _build_local_default_mcp_servers,
     install,
 )
 from workstate_bootstrap.mcp_sync import (
@@ -23,11 +24,11 @@ from workstate_bootstrap.mcp_sync import (
 )
 from workstate_bootstrap.subcommands import doctor, repair, status, update
 
-# Plan 0009: CLI default flips to ``minimal``. The library
+# implementation note: CLI default flips to ``minimal``. The library
 # ``install()`` API keeps ``profile="all"`` for back-compat with
 # pre-Plan-0009 callers.
 INSTALL_PROFILE_CHOICES: tuple[str, ...] = (PROFILE_MINIMAL, PROFILE_LIFECYCLE, PROFILE_ALL)
-# AHMCP-56 Slice 3: flipped from PROFILE_MINIMAL back to PROFILE_ALL so
+# WORKSTATE-REF-56 implementation note: flipped from PROFILE_MINIMAL back to PROFILE_ALL so
 # a no-argument ``workstate-bootstrap install`` materializes the full
 # surface set out of the box. ``--profile minimal`` and
 # ``--profile lifecycle`` remain opt-in for lean installs.
@@ -45,7 +46,7 @@ def _resolve_mcp_servers(
     - ``no_servers=True``: explicit opt-out → ``None`` (no config files written).
     - ``raw is None``: behavior depends on ``default_when_unset``. ``install``
       passes ``True`` so an unset flag falls back to :data:`DEFAULT_MCP_SERVERS`
-      (Plan 0002 step 2a — single-command, no-hand-edits install). ``doctor`` /
+      (implementation note step 2a — single-command, no-hand-edits install). ``doctor`` /
       ``update`` / ``repair`` pass ``False`` so an unset flag means
       "don't check / refresh configs at all".
     - ``raw == "default"``: use :data:`DEFAULT_MCP_SERVERS`.
@@ -64,8 +65,29 @@ def _resolve_mcp_servers(
     return doc
 
 
+def _resolve_managed_servers(
+    target: Path, raw: str | None
+) -> Mapping[str, Mapping[str, Any]] | None:
+    """Resolve ``--mcp-servers``, making ``default`` profile-aware.
+
+    On a ``git_overlay`` install with local MCP packages, ``default`` resolves
+    the LOCAL ``uv run --no-sync --project ...`` launchers (via
+    :func:`_build_local_default_mcp_servers`) instead of the uvx package map, so
+    ``mcp-sync`` and ``repair`` converge on the same launchers as
+    ``install``/``update`` and never silently downgrade a local install. Falls
+    back to the uvx map when no local packages are present. implementation note A1.
+    """
+    servers = _resolve_mcp_servers(raw)
+    if raw == "default":
+        local = _build_local_default_mcp_servers(target)
+        if local is not None:
+            return local
+    return servers
+
+
 DEFAULT_REMOTE_URL = "git@github.com:darce/workstate.git"
 DEFAULT_REMOTE_REF = "main"
+INSTALL_SOURCE_CHOICES: tuple[str, ...] = ("git_overlay", "package")
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -80,7 +102,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
     p_install = sub.add_parser(
         "install",
-        help="Clone the shared workstate-system remote and write the overlay manifest.",
+        help="Materialize the shared workstate-system overlay and write the manifest.",
     )
     p_install.add_argument(
         "--target",
@@ -98,6 +120,16 @@ def _build_parser() -> argparse.ArgumentParser:
         default=DEFAULT_REMOTE_REF,
         help=f"Tag or branch to check out (default: {DEFAULT_REMOTE_REF}).",
     )
+    p_install.add_argument(
+        "--source",
+        choices=INSTALL_SOURCE_CHOICES,
+        default="git_overlay",
+        help=(
+            "Overlay source. 'git_overlay' keeps the existing clone-backed "
+            "default; 'package' resolves payload data from the installed "
+            "workstate-system distribution."
+        ),
+    )
     p_install.add_argument(
         "--mcp-servers",
         default=None,
@@ -160,7 +192,7 @@ def _build_parser() -> argparse.ArgumentParser:
         choices=INSTALL_PROFILE_CHOICES,
         default=INSTALL_PROFILE_DEFAULT,
         help=(
-            "Install profile. 'all' (default, AHMCP-56 Slice 3) materializes "
+            "Install profile. 'all' (default, WORKSTATE-REF-56 implementation note) materializes "
             "per-agent surfaces, runs the workflow generator, writes MCP "
             "config surfaces, and performs the lifecycle hoist. 'minimal' "
             "clones the remote, writes the manifest, and sets core.hooksPath "
@@ -439,6 +471,7 @@ def main(argv: list[str] | None = None) -> int:
             target=args.target,
             remote_url=args.remote_url,
             remote_ref=args.remote_ref,
+            source=args.source,
             mcp_servers=_resolve_mcp_servers(
                 args.mcp_servers,
                 no_servers=args.no_mcp_servers,
@@ -454,11 +487,18 @@ def main(argv: list[str] | None = None) -> int:
             install_codex_stop_hook=args.install_codex_stop_hook,
             install_vscode_stop_hook=args.install_vscode_stop_hook,
         )
-        print(
-            f"installed workstate-system overlay: "
-            f"{args.remote_url}@{manifest['remote_sha']} -> {args.target}",
-            file=sys.stdout,
-        )
+        if manifest.get("source_kind") == "package":
+            print(
+                f"installed workstate-system overlay: "
+                f"workstate-system=={manifest['package_version']} -> {args.target}",
+                file=sys.stdout,
+            )
+        else:
+            print(
+                f"installed workstate-system overlay: "
+                f"{args.remote_url}@{manifest['remote_sha']} -> {args.target}",
+                file=sys.stdout,
+            )
         if isinstance(manifest.get("override_backup_path"), str):
             print(f"override backup: {manifest['override_backup_path']}", file=sys.stdout)
         if isinstance(manifest.get("state_backup_path"), str):
@@ -503,7 +543,7 @@ def main(argv: list[str] | None = None) -> int:
                 backup_overrides=args.backup,
                 enforce_required_surfaces=not args.no_enforce_required_surfaces,
             )
-        except FileNotFoundError as exc:
+        except (FileNotFoundError, ValueError) as exc:
             print(str(exc), file=sys.stderr)
             return 1
         print(
@@ -520,7 +560,7 @@ def main(argv: list[str] | None = None) -> int:
             report = repair(
                 target=args.target,
                 force_dirty=args.force_dirty,
-                mcp_servers=_resolve_mcp_servers(args.mcp_servers),
+                mcp_servers=_resolve_managed_servers(args.target, args.mcp_servers),
                 plugin_overrides=args.plugin_overrides,
             )
         except FileNotFoundError as exc:
@@ -540,7 +580,7 @@ def main(argv: list[str] | None = None) -> int:
 
     if args.command == "mcp-sync":
         try:
-            servers = _resolve_mcp_servers(args.mcp_servers)
+            servers = _resolve_managed_servers(args.target, args.mcp_servers)
         except (FileNotFoundError, json.JSONDecodeError) as exc:
             print(f"mcp-sync: --mcp-servers: {exc}", file=sys.stderr)
             return 2