workstate-bootstrap 0.5.2__tar.gz

workstate_bootstrap-0.5.2/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+build/
+dist/

workstate_bootstrap-0.5.2/CHANGELOG.md

@@ -0,0 +1,240 @@
+# Changelog — workstate-bootstrap
+
+## Unreleased
+
+## [0.5.2] — 2026-05-20
+
+### Changed
+
+- **Bump the default managed handoff server pin** to
+  `mcp-workstate-handoff@0.11.5` so fresh `workstate-bootstrap install`
+  dogfood installs pick up the `ACTIVE TASK PLANS` task-plan-path fix by
+  default. `mcp-workstate-orchestrator` remains pinned at `0.4.7`.
+
+## [0.5.1] — 2026-05-11
+
+### Fixed
+
+- **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
+  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
+  symlink into three buckets — resolves-to-expected (shared,
+  idempotent), lexically inside our remote subtree but stale-or-broken
+  (repointed to the canonical target, audited to stdout as
+  `repointed: <surface>`), and foreign (preserved as local override).
+  The lexical containment check uses `os.readlink` +
+  `os.path.normpath` so broken targets are classified without raising
+  during `Path.resolve(strict=True)`.
+
+## [0.5.0] — 2026-05-10
+
+### Changed
+
+- **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
+  table) instead of bespoke per-harness writers. New harnesses (Codex,
+  VS Code, …) are onboarded by appending adapter rows.
+- **CLI default profile flips back to `all`** so a no-argument
+  `workstate-bootstrap install` materializes the full surface set out of
+  the box — per-agent generated surfaces (`.claude/skills`,
+  `.claude/commands`, `.github/prompts`, `.codex/skills`), shared
+  overlay symlinks (`scripts/hooks`, `Makefile.d`, `scripts/workstate`,
+  …), and the lifecycle hoist (`Makefile.d/lifecycle.mk` plus the
+  sentinel-bracketed `-include` block). `--profile minimal` and
+  `--profile lifecycle` remain opt-in for lean installs. The library
+  `install()` API has always defaulted to `"all"`; this realigns the
+  two layers.
+- **The install manifest (`.workstate-bootstrap.json`) now records the
+  active profile** under `manifest["profile"]` so downstream tools
+  (`sync`, `doctor`, rehearsals) can reason about what the consumer
+  installed without re-inferring it from the surface set.
+- **Stop-hook wiring is fully opt-in across every harness shipped by
+  the manifest.** The legacy `--harness-hook-scope` flag is replaced by
+  four boolean flags: `--install-claude-stop-hook` (shared, checked-in
+  `.claude/settings.json`), `--install-claude-stop-hook-local`
+  (user-owned, gitignored `.claude/settings.local.json`),
+  `--install-codex-stop-hook` (`.codex/hooks/stop.json`), and
+  `--install-vscode-stop-hook` (`.vscode/agentic-stop-hooks.json`).
+  All four default off — no file is touched unless the operator
+  explicitly opts in. The library `install()` API surfaces the same
+  switches as `install_claude_stop_hook` / `install_claude_stop_hook_local`
+  / `install_codex_stop_hook` / `install_vscode_stop_hook`.
+
+## [0.4.2] — 2026-05-10
+
+### Changed
+
+- **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
+  WORKSTATE-REF-54 (multi-active CURRENT_TASK projection, import/export
+  malformed-payload rejection, target_branch/worktree_path/plan_path
+  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** (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
+  matching `Makefile.d/lifecycle.mk` and
+  `scripts/workstate/lifecycle/` runner that those skills' `make
+  task-start` / `make slice-start` / `make context` /
+  `make review-ready` / `make handoff-close-check` /
+  `make format-all` references resolve through. Consumer repos
+  bootstrapped under `--profile all` now receive the runner and the
+  sentinel-bracketed `-include Makefile.d/*.mk` directive, so the
+  skill manifest and the make graph stay aligned.
+
+### Changed
+
+- **Default managed MCP servers are now version-pinned.** The built-in
+  `--mcp-servers default` map writes `uvx mcp-workstate-handoff@0.11.0` and
+  `uvx mcp-workstate-orchestrator@0.4.4` (rather than unpinned `uvx
+  mcp-workstate-handoff` / `uvx mcp-workstate-orchestrator`) so consumer repos
+  do not silently drift when PyPI advances independently of the overlay
+  tag they bootstrapped against. Operators wanting a different pin
+  continue to pass `--mcp-servers <path>`.
+- **Raise `workstate-protocol` lower bound to `>=0.1.4,<0.2.0`** to match
+  the floor pinned by `mcp-workstate-handoff` 0.11.0 and
+  `mcp-workstate-orchestrator` 0.4.4 — the two packages bootstrap launches
+  via `uvx` — so the bootstrap venv cannot resolve a protocol release
+  older than what those servers import at startup.
+
+## [0.4.0] — 2026-05-04
+
+### Added
+
+- **Install profile contract: `--profile {minimal,lifecycle,all}`**
+  (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** (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.
+
+### Changed
+
+- Bootstrap installs and rehearsals are validated against
+  `mcp-workstate-handoff>=0.8.0` (the version that ships the
+  `plan_resolve` / `plan_cli` surface targeted by the new make
+  recipes).
+
+## [0.3.1] — 2026-05-03
+
+- **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.
+- **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
+  test asserts that `core.hooksPath` resolves to the directory
+  carrying all six executable hook scripts AND that the Python helper
+  `scripts/hooks/check_branch_naming.py` (the delegate the
+  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
+  assertion catches a future regression where the upstream package
+  drops the helper.
+- **Manifest renamed: `.workstate-overlay.json` → `.workstate-bootstrap.json`
+  (schema_version bumped to 2).** Resolves a name collision with consumer
+  repos that also use `.workstate-overlay.json` for unrelated config. On first
+  run, an existing `.workstate-overlay.json` carrying the bootstrap shape
+  (top-level dict with a list `surfaces` key) is renamed in-place via
+  `git mv` (or filesystem rename when the target is not a git worktree).
+  Consumer-owned files at the legacy name are left untouched. The Python
+  alias `OVERLAY_MANIFEST_NAME` is preserved (now pointing at the canonical
+  filename) for downstream import compatibility.
+- **Managed MCP defaults now launch stdio servers.** The built-in
+  `--mcp-servers default` map writes `uvx mcp-workstate-handoff
+  --workspace-root . serve-stdio` and `uvx mcp-workstate-orchestrator
+  --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 (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
+  state-mutating MCP call. The shared `scripts/hooks/` surface is still
+  materialized; `regenerate-task-views.sh` remains there only as a
+  documented manual fallback for the auto-regen opt-out path
+  (`WORKSTATE_HANDOFF_DASHBOARD_AUTO_REGEN=0`). Operators upgrading from
+  0.3.0 do not need to touch any harness config — the next
+  `workstate-bootstrap update` removes the obsolete hook wiring.
+
+## 0.3.0 — 2026-04-28
+
+- **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/`
+  ready for the first MCP call. The init-state invocation is resolved
+  from the same `mcp_servers` map written into `.mcp.json` /
+  `.vscode/mcp.json` / `.codex/config.toml` (avoiding dogfood version
+  skew between PyPI and local-source schemas), and the bootstrap
+  manifest's `remote_url` is threaded through `--expected-remote-url`
+  so a stale adjacent overlay from a different remote is rejected.
+  Skipped under `--no-mcp-servers`.
+- **Required-surfaces refusal runs before the generator and
+  init-state.** A failing required-surface check now leaves no
+  `.task-state/`, no generated artifacts, and no manifest behind on
+  disk, so refused installs no longer half-write the target.
+- **`status` reports handoff state.** When the install registered MCP
+  servers, `status` invokes `init-state --check` and appends the
+  resolved `state_dir` / `db_path` / `exports_dir` / `schema_version` /
+  `initialized` to the summary. `--no-mcp-servers` installs suppress
+  the section.
+- **`doctor` flags missing `.task-state/handoff.db` as `state_drift`,**
+  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.** 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
+  enforcement on content writes (`record_event`, `close_slice`,
+  `set_handoff_state`, `record_review_finding`,
+  `record_verified_test`) is unchanged — bootstrap's docs reflect
+  this, but the behavior change lives in the handoff package.
+
+## 0.2.1 — 2026-04-26
+
+- Add `pyyaml>=6` to runtime dependencies. The agent-workflow generator
+  imports `yaml` to read `skill.yaml`; bootstrap invokes the generator
+  via its own `sys.executable`, so PyYAML must be present in bootstrap's
+  uvx-isolated venv. Without it, install fails with
+  `PyYAML is required to read skill.yaml` on a clean uvx run.
+
+## 0.2.0 — 2026-04-26
+
+- Resolve shared overlay surfaces and the agent-workflow generator under
+  `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 implementation note step 1.
+- Rehearsal fixture (`fake_remote_with_generator`) now mirrors the real
+  monorepo layout so this regression cannot return silently.
+
+### Note on previously published refs
+
+The monorepo `v0.1.0` tag pre-dates this fix. Consumers using
+`uvx --from "...@v0.1.0..." workstate-bootstrap install ...` will hit the
+required-surface error. Pin to `v0.1.1` or later.

workstate_bootstrap-0.5.2/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: workstate-bootstrap
+Version: 0.5.2
+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
+Project-URL: Documentation, https://github.com/darce/workstate/blob/main/docs/CONSUMER.md
+Project-URL: Issues, https://github.com/darce/workstate/issues
+Author: darce
+License: Proprietary
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: workstate-protocol<0.2.0,>=0.1.4
+Provides-Extra: dev
+Requires-Dist: mcp-workstate-handoff; (python_version >= '3.12') and extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# workstate-bootstrap
+
+Pip-installable CLI that hoists the shared workstate-system surface
+(typed protocol, two MCP servers, hooks, skills, generated agent
+workflows) into consumer repositories. Lives inside
+[`darce/workstate`](https://github.com/darce/workstate).
+
+Consumers run `workstate-bootstrap install --target <path>` once; it
+clones the monorepo, materializes the overlay, and registers both
+managed MCP servers (`mcp-workstate-handoff`, `mcp-workstate-orchestrator`)
+across `.mcp.json`, `.vscode/mcp.json`, and `.codex/config.toml`. No
+hand-edits required.
+
+## Install
+
+### From PyPI (recommended)
+
+```bash
+uvx --from workstate-bootstrap workstate-bootstrap install --target /path/to/your/repo
+# or, persistent:
+uv tool install workstate-bootstrap
+```
+
+### From the monorepo source tree (development)
+
+```bash
+cd packages/workstate-bootstrap
+python -m pip install -e ".[dev]"
+```
+
+### Direct from git (private-repo phase, before PyPI release)
+
+One-shot (no install — fetches each invocation):
+
+```bash
+uvx --from "git+https://github.com/darce/workstate@workstate-bootstrap-v0.2.1#subdirectory=packages/workstate-bootstrap" \
+    workstate-bootstrap install \
+    --target /path/to/your/repo
+```
+
+Persistent (recommended once you start running `status` / `doctor`
+regularly — installs `workstate-bootstrap` onto `$PATH`):
+
+```bash
+uv tool install "git+https://github.com/darce/workstate@workstate-bootstrap-v0.2.1#subdirectory=packages/workstate-bootstrap"
+# then:
+workstate-bootstrap status --target /path/to/your/repo
+workstate-bootstrap doctor --target /path/to/your/repo
+# upgrade later:
+uv tool upgrade workstate-bootstrap
+```
+
+> **Hardlink warning on first install?** If you see
+> `Failed to hardlink files; falling back to full copy`, your `uv`
+> cache and tool dir live on different filesystems. The install still
+> succeeds; silence the warning with `export UV_LINK_MODE=copy` in
+> your shell profile.
+
+## Subcommands
+
+```text
+workstate-bootstrap install --target <path> [--remote-ref <tag>] [--mcp-servers <default|path>] [--no-mcp-servers]
+workstate-bootstrap update  --target <path> --remote-ref <tag>
+workstate-bootstrap status  --target <path>
+workstate-bootstrap doctor  --target <path> [--mcp-servers <default|path>]
+workstate-bootstrap repair  --target <path> [--force-dirty] [--mcp-servers <default|path>]
+```
+
+- `install`: Clone the monorepo, materialize SHARED + GENERATED
+  surfaces, write the three MCP-config files, run `init-state` to
+  provision `<target>/.task-state/handoff.db` (skipped under
+  `--no-mcp-servers`), set `core.hooksPath`, and write the overlay
+  manifest.
+- `update`: Re-run install at a new `--remote-ref`; refresh GENERATED
+  surfaces and, optionally, configs.
+- `status`: Print a summary of the installed overlay manifest. When
+  the install registered MCP servers, also reports the resolved
+  `state_dir` / `db_path` / `exports_dir` / `schema_version` via
+  `init-state --check`.
+- `doctor`: Detect drift in SHARED, GENERATED, config, and
+  initialized-state surfaces. Flags missing `.task-state/handoff.db`
+  as `state_drift` only when the manifest recorded `.mcp.json`. Exit
+  `1` when drift exists.
+- `repair`: Restore drifted surfaces flagged by `doctor`.
+
+See [`docs/CONSUMER.md`](https://github.com/darce/workstate/blob/main/docs/CONSUMER.md)
+for the consumer-facing walkthrough (upgrade, drift handling, skill
+overrides, the `current_task_auto_regen` migration note).
+
+## Surfaces written by `install`
+
+The canonical source of truth for bootstrap-managed surfaces is the
+installer implementation in
+`src/workstate_bootstrap/install.py` (`SHARED_SURFACES` and
+`GENERATED_SURFACES`). Keep this table aligned with those constants.
+
+| Surface                              | Source     | Layer       |
+| ------------------------------------ | ---------- | ----------- |
+| `scripts/hooks/`                     | shared     | symlink     |
+| `.github/hooks/`                     | shared     | symlink     |
+| `docs/agentic/contracts/`            | shared     | symlink     |
+| `docs/agentic/rules/`                | shared     | symlink     |
+| `Makefile.d/` non-excluded children  | shared     | carved dir  |
+| `scripts/workstate/` non-excluded children | shared | carved dir  |
+| `.github/prompts/`                   | generated  | real dir    |
+| `.agentic/generated/plugins/workstate-system/base/` | generated | real dir |
+| `.agentic/generated/plugins/workstate-system/effective/` | generated | real dir |
+| `.mcp.json`                          | generated  | real file   |
+| `.vscode/mcp.json`                   | generated  | real file   |
+| `.codex/config.toml`                 | generated  | real file   |
+| `core.hooksPath` git config          | generated  | git config  |
+| `.task-state/handoff.db`             | runtime    | sqlite      |
+| `.task-state/exports/`               | runtime    | dir         |
+| `.agentic/remote/`                   | bootstrap  | git clone   |
+| `.workstate-bootstrap.json`              | bootstrap  | manifest    |
+
+`.task-state/` is provisioned by the handoff server's `init-state`
+subcommand at install time and is gitignored — each fresh checkout
+regenerates it through `workstate-bootstrap install`.
+
+## Defaults
+
+- `--profile` defaults to `all`, which materializes the full surface
+  set: generated Copilot prompts, Claude/Codex plugin trees, shared
+  overlay surfaces, and the lifecycle hoist
+  (`Makefile.d/lifecycle.mk` plus the sentinel-bracketed `-include`
+  block in the consumer `Makefile`). Pass `--profile minimal` for a
+  clone-only install with no surfaces, or `--profile lifecycle` for
+  just the lifecycle runner and Makefile fragment. The active profile
+  is recorded in `.workstate-bootstrap.json` under `"profile"`.
+- `--remote-url` defaults to `git@github.com:darce/workstate.git`.
+- `--remote-ref` defaults to `main` (override with a release tag like `v0.1.0`).
+- `--mcp-servers` defaults to the built-in managed map registering
+  `mcp-workstate-handoff` and `mcp-workstate-orchestrator` via `uvx` with
+  `--workspace-root . serve-stdio`, so Codex, VS Code, and Claude
+  clients start real MCP stdio servers from the generated config.
+  Pass a JSON file path to override; pass `--no-mcp-servers` to skip
+  the three config writers entirely.
+- Plugin overrides are auto-discovered at
+  `workstate-overrides/workstate-system/` when that root contains an
+  `overrides.yaml` manifest. Use `--plugin-overrides <path>` on
+  `install`, `update`, `doctor`, or `repair` for a non-default root;
+  bootstrap records that path so later update/doctor/repair runs reuse
+  it. Override-aware installs generate effective plugin trees under
+  `.agentic/generated/plugins/workstate-system/effective/{claude,codex}`
+  and point marketplace pins at those generated trees.
+- `install` and `update` preserve plugin override files by default.
+  `--reset-overrides` is the explicit destructive path; it removes only
+  the resolved override root, refuses dirty git worktrees unless
+  `--backup` is supplied, and archives backups under
+  `.agentic/override-backups/<timestamp>/` before removal.
+
+## Development
+
+Tests live under `tests/`. From the monorepo root:
+
+```bash
+cd packages/workstate-bootstrap
+PYTHONPATH=.:src:../workstate-protocol/src pytest tests -q
+```

workstate_bootstrap-0.5.2/README.md

@@ -0,0 +1,160 @@
+# workstate-bootstrap
+
+Pip-installable CLI that hoists the shared workstate-system surface
+(typed protocol, two MCP servers, hooks, skills, generated agent
+workflows) into consumer repositories. Lives inside
+[`darce/workstate`](https://github.com/darce/workstate).
+
+Consumers run `workstate-bootstrap install --target <path>` once; it
+clones the monorepo, materializes the overlay, and registers both
+managed MCP servers (`mcp-workstate-handoff`, `mcp-workstate-orchestrator`)
+across `.mcp.json`, `.vscode/mcp.json`, and `.codex/config.toml`. No
+hand-edits required.
+
+## Install
+
+### From PyPI (recommended)
+
+```bash
+uvx --from workstate-bootstrap workstate-bootstrap install --target /path/to/your/repo
+# or, persistent:
+uv tool install workstate-bootstrap
+```
+
+### From the monorepo source tree (development)
+
+```bash
+cd packages/workstate-bootstrap
+python -m pip install -e ".[dev]"
+```
+
+### Direct from git (private-repo phase, before PyPI release)
+
+One-shot (no install — fetches each invocation):
+
+```bash
+uvx --from "git+https://github.com/darce/workstate@workstate-bootstrap-v0.2.1#subdirectory=packages/workstate-bootstrap" \
+    workstate-bootstrap install \
+    --target /path/to/your/repo
+```
+
+Persistent (recommended once you start running `status` / `doctor`
+regularly — installs `workstate-bootstrap` onto `$PATH`):
+
+```bash
+uv tool install "git+https://github.com/darce/workstate@workstate-bootstrap-v0.2.1#subdirectory=packages/workstate-bootstrap"
+# then:
+workstate-bootstrap status --target /path/to/your/repo
+workstate-bootstrap doctor --target /path/to/your/repo
+# upgrade later:
+uv tool upgrade workstate-bootstrap
+```
+
+> **Hardlink warning on first install?** If you see
+> `Failed to hardlink files; falling back to full copy`, your `uv`
+> cache and tool dir live on different filesystems. The install still
+> succeeds; silence the warning with `export UV_LINK_MODE=copy` in
+> your shell profile.
+
+## Subcommands
+
+```text
+workstate-bootstrap install --target <path> [--remote-ref <tag>] [--mcp-servers <default|path>] [--no-mcp-servers]
+workstate-bootstrap update  --target <path> --remote-ref <tag>
+workstate-bootstrap status  --target <path>
+workstate-bootstrap doctor  --target <path> [--mcp-servers <default|path>]
+workstate-bootstrap repair  --target <path> [--force-dirty] [--mcp-servers <default|path>]
+```
+
+- `install`: Clone the monorepo, materialize SHARED + GENERATED
+  surfaces, write the three MCP-config files, run `init-state` to
+  provision `<target>/.task-state/handoff.db` (skipped under
+  `--no-mcp-servers`), set `core.hooksPath`, and write the overlay
+  manifest.
+- `update`: Re-run install at a new `--remote-ref`; refresh GENERATED
+  surfaces and, optionally, configs.
+- `status`: Print a summary of the installed overlay manifest. When
+  the install registered MCP servers, also reports the resolved
+  `state_dir` / `db_path` / `exports_dir` / `schema_version` via
+  `init-state --check`.
+- `doctor`: Detect drift in SHARED, GENERATED, config, and
+  initialized-state surfaces. Flags missing `.task-state/handoff.db`
+  as `state_drift` only when the manifest recorded `.mcp.json`. Exit
+  `1` when drift exists.
+- `repair`: Restore drifted surfaces flagged by `doctor`.
+
+See [`docs/CONSUMER.md`](https://github.com/darce/workstate/blob/main/docs/CONSUMER.md)
+for the consumer-facing walkthrough (upgrade, drift handling, skill
+overrides, the `current_task_auto_regen` migration note).
+
+## Surfaces written by `install`
+
+The canonical source of truth for bootstrap-managed surfaces is the
+installer implementation in
+`src/workstate_bootstrap/install.py` (`SHARED_SURFACES` and
+`GENERATED_SURFACES`). Keep this table aligned with those constants.
+
+| Surface                              | Source     | Layer       |
+| ------------------------------------ | ---------- | ----------- |
+| `scripts/hooks/`                     | shared     | symlink     |
+| `.github/hooks/`                     | shared     | symlink     |
+| `docs/agentic/contracts/`            | shared     | symlink     |
+| `docs/agentic/rules/`                | shared     | symlink     |
+| `Makefile.d/` non-excluded children  | shared     | carved dir  |
+| `scripts/workstate/` non-excluded children | shared | carved dir  |
+| `.github/prompts/`                   | generated  | real dir    |
+| `.agentic/generated/plugins/workstate-system/base/` | generated | real dir |
+| `.agentic/generated/plugins/workstate-system/effective/` | generated | real dir |
+| `.mcp.json`                          | generated  | real file   |
+| `.vscode/mcp.json`                   | generated  | real file   |
+| `.codex/config.toml`                 | generated  | real file   |
+| `core.hooksPath` git config          | generated  | git config  |
+| `.task-state/handoff.db`             | runtime    | sqlite      |
+| `.task-state/exports/`               | runtime    | dir         |
+| `.agentic/remote/`                   | bootstrap  | git clone   |
+| `.workstate-bootstrap.json`              | bootstrap  | manifest    |
+
+`.task-state/` is provisioned by the handoff server's `init-state`
+subcommand at install time and is gitignored — each fresh checkout
+regenerates it through `workstate-bootstrap install`.
+
+## Defaults
+
+- `--profile` defaults to `all`, which materializes the full surface
+  set: generated Copilot prompts, Claude/Codex plugin trees, shared
+  overlay surfaces, and the lifecycle hoist
+  (`Makefile.d/lifecycle.mk` plus the sentinel-bracketed `-include`
+  block in the consumer `Makefile`). Pass `--profile minimal` for a
+  clone-only install with no surfaces, or `--profile lifecycle` for
+  just the lifecycle runner and Makefile fragment. The active profile
+  is recorded in `.workstate-bootstrap.json` under `"profile"`.
+- `--remote-url` defaults to `git@github.com:darce/workstate.git`.
+- `--remote-ref` defaults to `main` (override with a release tag like `v0.1.0`).
+- `--mcp-servers` defaults to the built-in managed map registering
+  `mcp-workstate-handoff` and `mcp-workstate-orchestrator` via `uvx` with
+  `--workspace-root . serve-stdio`, so Codex, VS Code, and Claude
+  clients start real MCP stdio servers from the generated config.
+  Pass a JSON file path to override; pass `--no-mcp-servers` to skip
+  the three config writers entirely.
+- Plugin overrides are auto-discovered at
+  `workstate-overrides/workstate-system/` when that root contains an
+  `overrides.yaml` manifest. Use `--plugin-overrides <path>` on
+  `install`, `update`, `doctor`, or `repair` for a non-default root;
+  bootstrap records that path so later update/doctor/repair runs reuse
+  it. Override-aware installs generate effective plugin trees under
+  `.agentic/generated/plugins/workstate-system/effective/{claude,codex}`
+  and point marketplace pins at those generated trees.
+- `install` and `update` preserve plugin override files by default.
+  `--reset-overrides` is the explicit destructive path; it removes only
+  the resolved override root, refuses dirty git worktrees unless
+  `--backup` is supplied, and archives backups under
+  `.agentic/override-backups/<timestamp>/` before removal.
+
+## Development
+
+Tests live under `tests/`. From the monorepo root:
+
+```bash
+cd packages/workstate-bootstrap
+PYTHONPATH=.:src:../workstate-protocol/src pytest tests -q
+```

workstate_bootstrap-0.5.2/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "workstate-bootstrap"
+version = "0.5.2"
+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.4,<0.2.0"]
+
+[project.scripts]
+workstate-bootstrap = "workstate_bootstrap.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/darce/workstate"
+Source = "https://github.com/darce/workstate/tree/main/packages/workstate-bootstrap"
+Documentation = "https://github.com/darce/workstate/blob/main/docs/CONSUMER.md"
+Issues = "https://github.com/darce/workstate/issues"
+
+[project.optional-dependencies]
+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 }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/workstate_bootstrap"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

workstate_bootstrap-0.5.2/src/workstate_bootstrap/__init__.py

@@ -0,0 +1,6 @@
+"""workstate-bootstrap: hoist the shared workstate-system surface into consumer repos."""
+
+from workstate_bootstrap.install import install
+
+__all__ = ["install"]
+__version__ = "0.5.2"

workstate_bootstrap-0.5.2/src/workstate_bootstrap/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m workstate_bootstrap``."""
+
+from workstate_bootstrap.cli import main
+
+raise SystemExit(main())