ace-swarm 2.0.6 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+This changelog is based on local tagged release history and repository diffs.
+
+## [2.1.0] - 2026-03-13
+
+### Changed
+
+- Rewrote the package README into a tighter operator-facing format with ASCII system maps and compact internal tables.
+- Added a recent-release summary to the README so the last three versions remain visible without turning the README into a full changelog.
+
+### Added
+
+- Added `CHANGELOG.md` to track tagged package release notes directly in the package.
+
+### Packaging
+
+- Bumped package version from `2.0.7` to `2.1.0`.
+
+## [2.0.7] - 2026-03-13
+
+### Added
+
+- Added runtime profile, runtime command, runtime executor, and runtime tool spec surfaces.
+- Added tracker adapters and tracker snapshot synchronization.
+- Added workspace-manager and Vericify bridge surfaces.
+- Added problem triage, skill auditor, skill catalog, and public-surface audit modules.
+- Added VS Code Copilot hook scaffolding and new packaged runtime/state schema assets.
+
+### Validation
+
+- Added broad new test coverage for runtime execution, tracker adapters, workspace management, problem triage, skill auditing, public surface checks, Vericify bridge behavior, and Copilot hook dispatch.
+
+## [2.0.6] - 2026-03-10
+
+### Fixed
+
+- Hardened bootstrap workspace path handling in `src/helpers.ts`.
+- Updated `assets/scripts/bootstrap-workspace.sh` to align with the fixed workspace bootstrap path flow.
+
+### Validation
+
+- Added integration coverage for workspace bootstrap behavior.
+
+## [2.0.5] - 2026-03-10
+
+### Added
+
+- Added packaged `ARTIFACT_MANIFEST.json`.
+- Expanded artifact-manifest and provenance-related schema coverage.
+
+### Changed
+
+- Tightened framework/file tool handling around artifact manifests and provenance enforcement.
+
+### Validation
+
+- Added integration and schema tests for the artifact-manifest path.

package/README.md

@@ -1,307 +1,283 @@
 # ACE Swarm MCP Server
 
-ACE Swarm packages the ACE framework (agents, skills, schemas, prompts, tasks, handoffs, and state scaffolding) as an MCP server and turnkey CLI.
+ACE Swarm is an MCP server and terminal-first CLI for durable agent orchestration.
 
-Swarm agents (`orchestrator`, `vos`, `ui`, `coders`) and composable agents (`skeptic`, `ops`, `research`, `spec`, `builder`, `qa`, `docs`) are treated as one unified agent system, with composable agents available as subagents for every swarm workflow.
+It turns agent workflows into a local control plane with explicit state, handoffs, locks, diffs, runtime profiles, and operator tooling.
 
-Suggestions and collaborations: `voybio.fundr@gmail.com`.
+## System Map
 
-## Install
-
-```bash
-npm install -g ace-swarm
+```text
+ACE Swarm
+|
++-- bootstrap
+|   +-- `ace init` / `ace turnkey`
+|   +-- workspace scaffolding
+|   `-- MCP client config bundle
+|
++-- control plane
+|   +-- agents
+|   |   +-- swarm: orchestrator, vos, ui, coders
+|   |   `-- composable: skeptic, ops, research, spec, builder, qa, docs, ...
+|   +-- contracts
+|   |   +-- prompts
+|   |   +-- schemas
+|   |   `-- handoff templates
+|   +-- runtime state
+|   |   +-- run ledger
+|   |   +-- todo state
+|   |   +-- handoff registry
+|   |   +-- status events
+|   |   +-- job queue
+|   |   +-- lock table
+|   |   `-- scheduler lease
+|   `-- dispatch
+|       +-- immediate scheduling
+|       +-- priority bands
+|       +-- persistent resource locks
+|       `-- recovery semantics
+|
++-- change intelligence
+|   +-- workspace delta scan
+|   +-- semantic snapshots
+|   +-- semantic diff / drift report
+|   +-- rewrite targets
+|   `-- safe edit rollback
+|
+`-- operator surface
+    +-- MCP server on stdio
+    `-- TUI: chat, tabs, telemetry, provider-aware runtime
 ```
 
-You can run the same CLI as either:
+## Quick Start
 
-```bash
-ace mcp
-# or
-ace-swarm mcp
+```text
++----+-----------------------------------------------+-----------------------------------------------+
+| #  | Command                                       | Result                                        |
++----+-----------------------------------------------+-----------------------------------------------+
+| 1  | npx -y ace-swarm turnkey --project "My Proj"  | Seeds workspace state, agents, skills, tasks  |
+| 2  | ace mcp                                       | Starts the MCP server over stdio              |
+| 3  | initiate ACE                                  | Kicks off the ACE workflow in your MCP host   |
++----+-----------------------------------------------+-----------------------------------------------+
 ```
 
-For one-off execution:
+## Recent Releases
 
-```bash
-npx -y ace-swarm mcp
+```text
++---------+------------+------------------------------------------------------+
+| Version | Date       | Highlights                                           |
++---------+------------+------------------------------------------------------+
+| 2.1.0   | 2026-03-13 | README redesign, ASCII docs, packaged changelog      |
+| 2.0.7   | 2026-03-13 | runtime executor/profile/tools, trackers, workspace  |
+| 2.0.6   | 2026-03-10 | bootstrap/workspace helper hardening                 |
++---------+------------+------------------------------------------------------+
 ```
 
-## Turnkey Setup (Recommended)
+See [CHANGELOG.md](./CHANGELOG.md) for the recent tagged release history that can be verified from the local repository.
 
-Bootstrap everything into the current workspace, including `.agents`, `agent-state`, scripts, and multi-client MCP config bundle:
+## Core Surfaces
 
-```bash
-npx -y ace-swarm turnkey --project "My Project"
+```text
++------------------+------------------------------------------+--------------------------------------------------+
+| Surface          | Internals                                | Public entrypoints                               |
++------------------+------------------------------------------+--------------------------------------------------+
+| Bootstrap        | workspace state, tasks, configs          | `ace init`, `ace turnkey`, `ace mcp-config`      |
+| Agent runtime    | swarm + composable roles                 | MCP server, TUI `/agent`, packaged agent assets  |
+| Durable state    | ledgers, TODOs, handoffs, status events  | runtime stores under `agent-state/*`             |
+| Dispatch         | queue, lock table, lease, recovery       | `enqueue_job`, `dispatch_jobs`, `complete_job`   |
+| Change analysis  | delta scan, semantic diff, rewrite hints | `scan_workspace_delta`, `semantic_diff`, etc.    |
+| Operator UI      | tabs, chat, telemetry, model switching   | `ace tui`                                        |
++------------------+------------------------------------------+--------------------------------------------------+
 ```
 
-Equivalent command:
+## Workspace Internals
 
-```bash
-npx -y ace-swarm init --project "My Project"
+```text
++----------------------------------+--------------------------------------------------+
+| Path                             | What lives there                                  |
++----------------------------------+--------------------------------------------------+
+| `agent-state/run-ledger.json`    | major updates, regressions, runtime history       |
+| `agent-state/todo-state.json`    | TODO nodes, dependencies, transition truth        |
+| `agent-state/handoff-registry.json` | handoff lifecycle state                        |
+| `agent-state/STATUS_EVENTS.ndjson`  | append-only lifecycle/status event log         |
+| `agent-state/job-queue.json`     | queued work with dependency and priority metadata |
+| `agent-state/job-locks.json`     | active resource lock table                        |
+| `agent-state/scheduler-lease.json` | active dispatcher owner and lease state         |
+| `agent-state/index.json`         | workspace delta index                             |
+| `.tmp/cache/semantic/*`          | semantic snapshots and diff cache                 |
+| `.ace/llm-profile.json`          | local runtime profile when configured             |
++----------------------------------+--------------------------------------------------+
 ```
 
-This writes:
+## Change And Safety Internals
 
-- `agent-state/*`
-- `.agents/ACE/*` and `.agents/skills/*`
-- `tasks/*`
-- `scripts/ace/*`
-- `.vscode/mcp.json`
-- `.mcp-config/{codex.config.toml,vscode.mcp.json,claude_desktop_config.json,cursor.mcp.json,antigravity.mcp.json}`
-
-### Turnkey with Ollama (Local Models)
-
-Bootstrap ACE + local model profile in one command:
-
-```bash
-npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b
+```text
++-------------------------+----------------------------------------------+
+| Capability              | Current surface                              |
++-------------------------+----------------------------------------------+
+| Coarse workspace diff   | `scan_workspace_delta`                       |
+| Semantic snapshot       | `snapshot_state`                             |
+| Semantic diff           | `semantic_diff`                              |
+| Drift gate              | `drift_report`                               |
+| Rewrite targeting       | `rewrite_targets`                            |
+| Exact diff summary      | `diff_files`, `git_diff`                     |
+| Safe write + rollback   | `safe_edit_file`                             |
++-------------------------+----------------------------------------------+
 ```
 
-Then enable and verify local runtime:
+## CLI
 
-```bash
-ollama serve
-ollama pull llama3.1:8b
-ace doctor --llm ollama --model llama3.1:8b
+```text
++---------------------------------------------+----------------------------------------------+
+| Command                                     | Purpose                                      |
++---------------------------------------------+----------------------------------------------+
+| `ace mcp` / `ace serve`                     | start MCP server over stdio                  |
+| `ace tui [options]`                         | launch terminal operator console             |
+| `ace init [options]`                        | bootstrap ACE files into current workspace   |
+| `ace turnkey [options]`                     | bootstrap + client config bundle             |
+| `ace doctor [options]`                      | validate local LLM + MCP readiness           |
+| `ace mcp-config [--client <name>|--all]`    | print one or all MCP client snippets         |
+| `ace paths`                                 | show resolved package and workspace paths    |
++---------------------------------------------+----------------------------------------------+
 ```
 
-If you need to explicitly (re)write MCP config for your editor:
+### Key Options
 
-```bash
-ace mcp-config --client vscode > .vscode/mcp.json
-# or choose codex|claude|cursor|antigravity
+```text
++-------------------------------+---------------------------------------------+
+| Command group                 | Options                                     |
++-------------------------------+---------------------------------------------+
+| `init` / `turnkey`            | `--project`, `--force`, `--no-mcp-config`   |
+|                               | `--no-client-config-bundle`                 |
+|                               | `--llm`, `--model`, `--ollama-url`          |
+| `tui`                         | `--provider`, `--model`, `--ollama-url`     |
+| `doctor`                      | `--llm`, `--model`, `--ollama-url`          |
++-------------------------------+---------------------------------------------+
 ```
 
-Artifacts written for local-model flow:
-
-- `.ace/llm-profile.json`
-- `.ace/doctor-checks.md`
-
-Rollout status:
-
-- `P0`: `init/turnkey` supports `--llm ollama --model --ollama-url`.
-- `P1`: `ace doctor` validates MCP config, Ollama endpoint, and model presence.
-- `P2`: MCP `bootstrap_state` supports `llm_provider`, `ollama_model`, `ollama_base_url`.
-
-## Client Compatibility
+## TUI
 
-ACE Swarm ships config templates for:
-
-- Codex
-- VS Code
-- Claude Desktop
-- Cursor
-- Antigravity
-
-### Get config snippets from CLI
+```text
++----------------------+----------------------------------------------+
+| Command              | Description                                  |
++----------------------+----------------------------------------------+
+| `/provider [name]`   | show or switch active provider               |
+| `/providers`         | list discovered providers                    |
+| `/models`            | list available models                        |
+| `/model <name>`      | switch active model                          |
+| `/pull <name>`       | download an Ollama model                     |
+| `/ollama`            | show Ollama connection status                |
+| `/agent <role>`      | launch a subagent tab                        |
+| `/agents`            | list agent roles and status                  |
+| `/status`            | show orchestrator status                     |
+| `/chat`              | open a chat tab                              |
+| `/logs`              | open logs tab                                |
+| `/help`              | list commands                                |
+| `/quit`              | exit the TUI                                 |
++----------------------+----------------------------------------------+
+```
 
-```bash
-ace mcp-config --client codex
-ace mcp-config --client vscode
-ace mcp-config --all
+```text
++----------------------+----------------------------------------------+
+| Shortcut             | Action                                       |
++----------------------+----------------------------------------------+
+| `Alt+1-9`            | switch tabs                                  |
+| `Tab` / `Shift+Tab`  | cycle tabs                                   |
+| `Ctrl+N`             | new chat                                     |
+| `Ctrl+R`             | refresh                                      |
+| `Ctrl+D`             | quit                                         |
++----------------------+----------------------------------------------+
 ```
 
-### Expected config targets
+Provider notes:
 
-- `codex`: `$CODEX_HOME/config.toml` (or `~/.codex/config.toml`)
-- `vscode`: `.vscode/mcp.json` (workspace)
-- `claude`: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux)
-- `cursor`: `~/.cursor/mcp.json`
-- `antigravity`: import/use `.mcp-config/antigravity.mcp.json` from the client MCP settings UI
+- Ollama works directly through `ace tui`.
+- OpenAI-compatible providers use `OPENAI_API_KEY` and optional `OPENAI_BASE_URL`, or provider-scoped equivalents such as `CODEX_API_KEY` and `CODEX_BASE_URL`.
+- VS Code Copilot model hints may appear in discovery, but the standalone TUI does not directly execute through the VS Code chat runtime without an extension-side bridge.
 
-## CLI Commands
+## Bootstrap Outputs
 
-```bash
-ace mcp                                 # start MCP server on stdio
-ace serve                               # alias for mcp
-ace tui [options]                       # launch interactive terminal dashboard
-ace init [options]                      # bootstrap ACE files into current workspace
-ace turnkey [options]                   # same as init (turnkey alias)
-ace doctor [options]                    # local LLM + MCP readiness checks
-ace mcp-config [--client <name>|--all]  # print one/all MCP client snippets
-ace paths                               # show resolved package/workspace paths
+```text
++----------------------------------+----------------------------------------------+
+| Path                             | Output                                       |
++----------------------------------+----------------------------------------------+
+| `agent-state/*`                  | state, ledgers, schemas, reports             |
+| `.agents/ACE/*`                  | packaged agent instructions                  |
+| `.agents/skills/*`               | packaged skills                              |
+| `tasks/*`                        | task packs, examples, handoff templates      |
+| `scripts/ace/*`                  | helper scripts                               |
+| `.vscode/mcp.json`               | VS Code MCP config                           |
+| `.mcp-config/*`                  | Codex / VS Code / Claude / Cursor / Antigravity |
+| `.github/hooks/*.json`           | optional workspace hook policies             |
++----------------------------------+----------------------------------------------+
 ```
 
-### Interactive TUI
-
-Launch a full-screen terminal dashboard with provider-aware model chat, agent tabs, telemetry, and task tracking:
+Local-model bootstrap:
 
 ```bash
-ace tui
-ace tui --model llama3.1:8b --ollama-url http://127.0.0.1:11434
+npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b
+ollama serve
+ollama pull llama3.1:8b
+ace doctor --llm ollama --model llama3.1:8b
 ```
 
-The TUI starts regardless of whether Ollama is running. Use `/ollama` inside the TUI to check status, or `/pull <model>` to download Ollama models. The TUI also refreshes the Ollama catalog in the background so `/model` completion can surface local models even when another provider is selected.
-
-For non-ollama providers, configure an OpenAI-compatible endpoint before chatting:
-
-- `OPENAI_API_KEY` (required) and optional `OPENAI_BASE_URL`
-- or provider-specific vars `${PROVIDER}_API_KEY` and `${PROVIDER}_BASE_URL` (example: `CODEX_API_KEY`, `CODEX_BASE_URL`)
-
-VS Code Copilot model hints such as `copilot/gpt-5-mini` are discovery-only in the standalone terminal TUI. They reflect models visible in VS Code chat, but the TUI cannot send directly through the VS Code chatbox from a terminal process without an extension-side bridge.
+## Client Config Targets
 
-Key commands inside TUI:
-
-| Command | Description |
-|---------|-------------|
-| `/provider [name]` | Show or switch active provider |
-| `/providers` | List discovered providers |
-| `/models` | List available models for active provider |
-| `/model <name>` | Switch active model (`Tab` searches discovered models, including Ollama) |
-| `/pull <name>` | Download an Ollama model |
-| `/ollama` | Check Ollama connection status and hints |
-| `/agent <role>` | Start a subagent in a new tab |
-| `/agents` | List all agent roles and status |
-| `/status` | Show orchestrator status |
-| `/chat` | Open new chat tab |
-| `/logs` | Open logs tab |
-| `/help` | List all commands |
-| `/quit` | Exit TUI |
-
-Keyboard shortcuts: `Alt+1-9` switch tabs, `Tab/Shift+Tab` cycle tabs, `Ctrl+N` new chat, `Ctrl+R` refresh, `Ctrl+D` quit.
-
-Options for `init` / `turnkey`:
-
-```bash
---project <name>                # Project name for global-state/MASTER_PLAN.md
---force                         # Overwrite scaffolded files
---no-mcp-config                 # Skip .vscode/mcp.json
---no-client-config-bundle       # Skip .mcp-config client bundle
---llm <provider>                # ollama
---model <name>                  # local model name (default: llama3.1:8b)
---ollama-url <url>              # Ollama base URL (default: http://127.0.0.1:11434)
+```text
++---------------+--------------------------------------------------------------+
+| Client        | Target                                                       |
++---------------+--------------------------------------------------------------+
+| Codex         | `$CODEX_HOME/config.toml` or `~/.codex/config.toml`         |
+| VS Code       | `.vscode/mcp.json`                                          |
+| Claude        | macOS: `~/Library/Application Support/Claude/...`           |
+|               | Linux: `~/.config/Claude/claude_desktop_config.json`        |
+| Cursor        | `~/.cursor/mcp.json`                                        |
+| Antigravity   | import `.mcp-config/antigravity.mcp.json` in client UI      |
++---------------+--------------------------------------------------------------+
 ```
 
-Options for `doctor`:
+## Included Assets
 
-```bash
---llm <provider>                # ollama (or auto from .ace/llm-profile.json)
---model <name>                  # override model to check
---ollama-url <url>              # override Ollama URL to check
+```text
++----------------------+-----------------------------------------------------------+
+| Asset class          | Included                                                  |
++----------------------+-----------------------------------------------------------+
+| Swarm agents         | 4: orchestrator, vos, ui, coders                         |
+| Composable agents    | 13: astgrep, skeptic, ops, research, spec, builder, ... |
+| Skills               | 11 packaged skills including orchestrator, codemunch,   |
+|                      | codesnipe, state-auditor, schema-forge, release-sentry  |
+| Tasks / templates    | `todo.md`, `lessons.md`, `role_tasks.md`,               |
+|                      | `cli_work_split.md`, `SWARM_HANDOFF.template.json`      |
++----------------------+-----------------------------------------------------------+
 ```
 
-## Initiate ACE Swarm
-
-After bootstrap, start your MCP host and issue:
+## Open Ideas
 
 ```text
-initiate ACE
++---------------------------------------------------------------+
+| Not shipped guarantees                                        |
++---------------------------------------------------------------+
+| high-certainty shadow workspace promotion mode                |
+| explicit promotion manifests for exact patch + AST evidence   |
+| richer operator views for rejected promotions and drift spikes|
++---------------------------------------------------------------+
 ```
 
-## Schema Validation (Runtime)
-
-Schema validation is wired into MCP tool execution paths:
-
-- `create_handoff`: validates handoff payload before write
-- `validate_handoff`: supports `schema_mode: auto|swarm|agent-state`
-- `write_workspace_file`: blocks invalid writes for:
-  - `agent-state/HANDOFF.json`
-  - `agent-state/HANDOFF_HISTORY/*.json`
-  - `agent-state/STATUS_EVENTS.ndjson`
-  - `ARTIFACT_MANIFEST.json`
-  - `SWARM_HANDOFF.*.json`
-
-Validation code is in `src/schemas.ts`.
-
-## Kanban Snapshot (Runtime)
-
-ACE Swarm now maintains a lightweight Kanban board in workspace state:
-
-- `agent-state/kanban.json`
-- `agent-state/kanban.html`
-
-You can regenerate manually with MCP tool `generate_kanban_ui`, and the server auto-refreshes Kanban after major artifact writes (`update_todo`, `create_handoff`, `bootstrap_state`, and `write_workspace_file` on ACE state/task/code paths).
-
-Resources:
-
-- `ace://kanban` (JSON)
-- `ace://kanban/html` (HTML)
-
-## Scheduler Queue (Runtime)
-
-ACE Swarm now supports a lease-owned dispatcher for handoff/job execution:
-
-- `agent-state/job-queue.json`
-- `agent-state/job-locks.json`
-- `agent-state/scheduler-lease.json`
-
-Dispatch model:
-
-- Priority-aware (`P0 > P1 > P2 > P3`) with FIFO ordering inside each band.
-- Immediate dispatch of runnable jobs; no interval gating.
-- Collision-free resource locks held until explicit completion/failure.
-- Lease heartbeat/recovery handles crash detection instead of slice overruns.
-
-Handoff integration:
-
-- `create_handoff` and `ack_handoff` automatically sync lifecycle updates into scheduler jobs.
-- Existing open/accepted handoffs are backfilled into scheduler state on startup.
-
-## New Runtime State Stores
-
-ACE Swarm now persists additional orchestration stores:
-
-- `agent-state/run-ledger.json` (major updates + regressions)
-- `agent-state/todo-state.json` (explicit TODO statuses, dependencies, transition gates)
-- `agent-state/index.json` (workspace delta scan index)
-- `agent-state/handoff-registry.json` (handoff lifecycle: `open|accepted|blocked|completed`)
-- `agent-state/job-queue.json` (scheduler jobs with dependency/priority metadata)
-- `agent-state/job-locks.json` (active resource lock table)
-- `agent-state/scheduler-lease.json` (active scheduler owner/heartbeat)
-
-New/extended tools:
-
-- `update_todo` now supports either full board replacement (`new_content`) or gated node transitions (`node_id`, `status`)
-- `scan_workspace_delta` writes indexed changed/unchanged/deleted diffs
-- `ack_handoff` updates handoff lifecycle status
-- `get_run_ledger`, `get_todo_state`, `get_handoff_status` expose persisted store state
-- Scheduler: `enqueue_job`, `list_jobs`, `ack_job`, `dispatch_jobs`, `dispatch_job_now`, `complete_job`, `get_lock_table`, `get_scheduler_lease`
-
-New resources:
-
-- `ace://run-ledger`
-- `ace://index`
-- `ace://handoffs/status`
-- `ace://scheduler/queue`
-- `ace://scheduler/locks`
-- `ace://scheduler/lease`
-- `ace://kernel/directive_kernel`
-- `ace://kernel/agent_registry`
-
-New tool:
-
-- `get_kernel_artifact` (`directive_kernel` | `agent_registry`)
-
-## ACE Assets Included
-
-### Agents (17)
-
-- **Swarm (4):** Orchestrator, VOS, UI, Coders
-- **Composable (13):** agent-astgrep, agent-skeptic, agent-ops, agent-research, agent-spec, agent-builder, agent-qa, agent-docs, agent-memory, agent-security, agent-observability, agent-eval, agent-release
-
-### Skills
-
-- Existing: `ace-orchestrator`, `codemunch`, `codesnipe`
-- New: `state-auditor`, `schema-forge`, `handoff-lint`, `memory-curator`, `risk-quant`, `eval-harness`, `incident-commander`, `release-sentry`
-
-### Tasks and Handoff Artifacts
-
-- `todo.md`, `lessons.md`, `role_tasks.md`, `cli_work_split.md`
-- `SWARM_HANDOFF.template.json` and examples
-
 ## Development
 
 ```bash
 cd ace-mcp-server
 npm install
 npm run build
+npm test
 npm run start
 ```
 
-## Documentation References
+## References
+
+- [OpenAI Codex MCP config](https://platform.openai.com/docs/codex/mcp)
+- [VS Code MCP](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
+- [Cursor MCP](https://docs.cursor.com/context/model-context-protocol)
+- [Claude Desktop MCP quickstart](https://modelcontextprotocol.io/quickstart/user)
+- [Antigravity MCP setup](https://docs.antigravity.dev/how-to/configuring-an-mcp-server)
 
-- OpenAI Codex MCP config: [platform.openai.com/docs/codex/mcp](https://platform.openai.com/docs/codex/mcp)
-- VS Code MCP: [code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
-- Cursor MCP: [docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol)
-- Claude Desktop MCP quickstart: [modelcontextprotocol.io/quickstart/user](https://modelcontextprotocol.io/quickstart/user)
-- Antigravity MCP server setup: [docs.antigravity.dev/how-to/configuring-an-mcp-server](https://docs.antigravity.dev/how-to/configuring-an-mcp-server)
+Collaborations, ideas, or concerns: `voybio.fundr@gmail.com`

package/assets/.agents/skills/landing-review-watcher/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: landing-review-watcher
+description:
+  Watch review, CI, and landing loops for a change and use when the user needs a durable merge-readiness procedure rather than a one-off PR check.
+---
+
+# Landing Review Watcher
+
+## Purpose
+
+Make code-review and landing work observable, repeatable, and operator-safe.
+This skill does not own the release decision itself; it owns the watch loop that turns "waiting on review/CI/merge" into a deterministic procedure with artifacts.
+
+## Canonical Use Cases
+
+1. A change is open for review and someone needs a stable loop for comments, CI state, and merge blockers.
+2. A release candidate is waiting to land and the team wants a written handoff-safe landing procedure.
+3. A long-running review thread needs explicit acknowledgement, blocker tracking, and final landing evidence.
+
+## Inputs
+
+- active branch / change identifier
+- review comments or requested changes
+- CI status / failing checks
+- merge policy constraints
+- rollout or release artifact pointers when applicable
+
+## Workflow
+
+1. Define the watch target:
+   branch, PR, merge queue item, or review thread.
+2. Capture the current state:
+   reviewers, open comments, requested changes, CI state, merge policy, and known blockers.
+3. Classify the loop:
+   `reviewing`, `changes_requested`, `waiting_on_ci`, `ready_to_land`, or `blocked`.
+4. Write or update `agent-state/LANDING_REVIEW_WATCH.md` with:
+   owner, blockers, next checks, evidence refs, and explicit exit criteria.
+5. On every cycle, acknowledge new review input explicitly:
+   accepted, rebutted, deferred, or blocked with reason.
+6. If CI fails, route the failure to the responsible owner and record the remediation checkpoint.
+7. If merge is safe, hand off to [$release-sentry](/Users/voy/Desktop/dev-ace/.agents/skills/release-sentry/SKILL.md) for the actual approve/hold decision.
+8. After landing, record the final result, landing timestamp, and rollback pointer if one exists.
+
+## Outputs
+
+- `agent-state/LANDING_REVIEW_WATCH.md`
+- updated evidence pointer in `agent-state/EVIDENCE_LOG.md`
+- optional release routing note to `release-sentry`
+
+## Validation
+
+- Verify every open reviewer/blocker has an owner or explicit waiting reason.
+- Verify CI state is current and tied to a specific run/check reference.
+- Verify landing state is one of:
+  `reviewing`, `changes_requested`, `waiting_on_ci`, `ready_to_land`, `blocked`, `landed`.
+- Verify the watch artifact names the next action instead of only summarizing history.
+
+## Compatibility
+
+- `SKILL.md` is the portable source of truth for this workflow.
+- The skill remains useful without provider-specific PR adapters; branch names, plain-text review notes, and CI summaries are enough.
+- Client overlays may add launch shortcuts, but must not redefine the watch-state model.
+
+## Failure Policy
+
+- Do not claim a change is ready to land if requested changes or failing CI remain unresolved.
+- Do not collapse review feedback into a vague summary; every new blocker or accepted fix must be acknowledged explicitly.
+- If the change cannot be tied to a concrete watch target, stop and create the target definition first.