ultra-builder-pro-cli 0.21.1 → 0.23.0

package/docs/AGENT-CONTEXT.md

@@ -25,50 +25,55 @@ not put it in a plugin until that allowlist classifies it.
 ## 2. Three-layer architecture
 
 ```text
-native command or skill -> MCP workflow-state operation -> .ultra/.runtime/state.db
+native command or skill -> 7-tool MCP safety kernel -> .ultra/.runtime/state.db
+                                      | \
+                                      |  -> .ultra/tasks/tasks.json (Git checkpoint)
+                                      |  -> .ultra/.runtime/projections/ (local views)
                                       ^
-                                      |
-              selected CLI init / doctor / diagnostics / orchestration
+                         CLI diagnostics / orchestration
 ```
 
 | Layer | Artifact | Contract |
 |---|---|---|
 | Skill/command | `skills/*/SKILL.md`, `commands/*.md` | Model-facing workflow and host-native entry point |
-| MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/.runtime/state.db` |
+| MCP | `mcp-server/server.cjs` | Persistence, semantic checkpoints, team sync, leases, archive transactions, and mechanical recovery |
 | CLI | `ultra-tools`, `ubp-orchestrator` | Selected initialization, backup-first recovery, automation, and diagnostics; not a change-state mirror |
 
 `.ultra/` is project-local cross-session workflow memory for normalized intent,
 progress, tasks, bounded context, specifications, evidence, provenance, and recovery.
-`.ultra/.runtime/state.db` is the only lifecycle, index, transition, freshness, and
-coordination authority for baselines, changes, decisions, tasks, workflow runs/steps,
-sessions, events, incidents, projection jobs/cursors, telemetry, review evidence, and
-circuit-breaker state. Registered digest-bound specifications and reports carry
-semantic or evidence bodies. `tasks.json`, generated task-context files, runtime
-checkpoints, and collaboration scratch are not independent authority. See
+`.ultra/.runtime/state.db` is checkout-local lifecycle, index, transition, freshness,
+and coordination authority for baselines, changes, decisions, tasks, workflow
+runs/steps, sessions, events, incidents, projection jobs/cursors, telemetry, review
+evidence, and circuit-breaker state. Registered digest-bound specifications and
+reports carry semantic or evidence bodies. `.ultra/tasks/tasks.json` is the
+MCP-published portable baseline/Change/task checkpoint; it is not live lease or session
+authority. Generated task views, runtime checkpoints, and collaboration scratch are
+not independent authority. See
 [`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
 
-## 3. Live MCP and declared contracts
+## 3. Public MCP kernel and compatibility layer
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 57 tools across
-nine families:
+Every host discovers the same seven model-facing tools:
 
-| Family | Live tools |
+| Public tool | Contract |
 |---|---|
-| `baseline.*` | start, record, get, converge |
-| `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
-| `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
-| `change.*` | create, update, delta, documentation_reconcile, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
-| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, complete, checkpoint |
-| `workflow.*` | start, get, list, step, revise, supersede, complete |
-| `artifact.*` | record, get |
-| `system.*` | doctor |
-| `plan.*` | export, get |
-
-Review, repository impact discovery, skill loading, and decision presentation remain
-host-native capabilities rather than fake MCP contracts. MCP stores only normalized
-decision authority, pending-question recovery state, lifecycle completion, and optional
-checkpoints; it never generates questions or retains prompts and transcripts. The
-generated Codex capability map documents host replacements.
+| `ultra.context` | side-effect-free current authority and evidence spine |
+| `ultra.record` | idempotent batch recording of typed draft facts and events |
+| `ultra.checkpoint` | one semantic stage commit; rejection keeps the draft mutable |
+| `ultra.sync` | Git team-checkpoint inspect/import/publish |
+| `ultra.session` | transactional execution lease |
+| `ultra.archive` | recoverable convergence and archive boundary |
+| `ultra.doctor` | mechanical diagnosis and backup-first repair |
+
+The public schemas stay below a 12KB discovery budget. The sixty 0.22 fine-grained
+task/session/baseline/change/decision/workflow/artifact/system/plan tools remain
+callable but undiscoverable for one compatibility release. They are implementation
+operations, not a second public API, and Skills must not call them directly.
+
+Semantic rejections return `accepted: false`, `mutable: true`, and diagnostics. Hard
+MCP errors are reserved for corruption, unsafe paths, real concurrency conflicts,
+permissions, or irreversible effects. Review, repository discovery, model reasoning,
+and owner interaction remain host-native.
 
 The complete write, transition, invalidation, and recovery contract lives in
 [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md).
@@ -87,23 +92,20 @@ review, and deliver route back to the same thread instead of deciding for the ow
 One partial unique index permits only one open item per thread. `decision.resolve`,
 `decision.delegate`, and `decision.defer` preserve the source of authority;
 `decision.supersede` preserves history when evidence or intent changes.
-After normalization, the host applies accepted intent through the owning MCP operation
-or digest-bound artifact, reads it back, and records typed `applied_refs` when another
-authority changed. Row-backed references require the exact field and canonical value;
-specification and artifact references require the exact file digest. Active proposals
-are never recalled as accepted intent. `decision.complete` then closes settled state without manufacturing
-an approval receipt. Prepare and confirm checkpointing remain optional and bind only a
-material accepted cluster to current artifact digests when interruption recovery needs
-that boundary. Status and breadcrumb return the current unresolved question, accepted
-intent relevant to the active authority, and allowed or mechanically required
-transitions, so recovery does not require replaying conversation history.
+After normalization, the host records accepted intent in one `ultra.record` batch,
+reads it back through `ultra.context`, and attempts an owning `ultra.checkpoint` only
+when durable authority is ready. Active proposals are never recalled as accepted
+intent. Status returns the current unresolved question, accepted intent, evidence,
+warnings, and hard blockers so recovery does not require replaying conversation
+history. The host model, not SQLite, recommends the next capability.
 
 ## 5. Context Spine contract
 
 Context Manifest v3 is an immutable DB-backed role handoff, not a static codebase summary.
-`change.context` compiles required references, digests, readiness, context budget,
-public seam, exact verification command, Change/task authority digests, and valid
-transitions for `plan`, `implement`, `check`, or `review`. Compilation never updates
+`ultra.checkpoint` compiles or reuses a content-addressed Context Manifest containing
+required references, digests, readiness, context budget, public seam, exact verification
+command, and Change/task authority digests for `plan`, `implement`, `check`, or
+`review`. Compilation never updates
 Change or provider authority; provider metadata changes through `change.update`.
 Snapshots are selected exactly by `change_id`, nullable `task_id`, `role`, and `gate`,
 so a review packet cannot satisfy implementation or planning evidence.
@@ -121,9 +123,9 @@ not block work or require raising a threshold. Prefer direct reads, bounded
 excerpts, or a smaller slice when they preserve correctness, and retain all
 necessary context when they do not.
 
-`change.breadcrumb` is the only compact router. Hooks may inject its change/task,
-role, gate, readiness, blockers, bounded normalized accepted intent,
-`allowed_transitions`, and `required_transition`. They must not inject raw prompts,
+The compact breadcrumb is a hook-only compatibility reader. Hooks may inject its
+change/task, role, gate, readiness, blockers, and bounded normalized accepted intent.
+They must not inject raw prompts,
 interaction transcripts, external-memory payloads, or graph payloads. Missing references,
 required digest drift, HEAD drift, or a missing execution seam blocks readiness. Context
 size and baseline drift are advisory for a change that is already active. New ordinary
@@ -172,15 +174,16 @@ the shared read-only `context_spine.py` breadcrumb helper:
   and types, never transcript paths or messages.
 
 `workflow_context.py`, `active_task_context.py`, `workflow_resume.py`, and the
-OpenCode plugin invoke the same bundled JavaScript `change.breadcrumb` reader
+OpenCode plugin invoke the same bundled JavaScript hook-only breadcrumb reader
 through the thin `context_spine.py` bridge. No hook reimplements the state query.
 `health_check.py` and
 `workflow_context.py` may inspect any initialized project;
-`active_task_context.py` always protects the task projection but limits ordinary
+`active_task_context.py` protects both the MCP-owned Git checkpoint and local task
+projection but limits ordinary
 edit guidance to an active workflow. Compact/stop/subagent hooks remain
 active-workflow scoped. OpenCode natively injects baseline/change context and
-protects the projection; full health inspection is available through
-`system.doctor` rather than a session-start health hook.
+protects both managed task paths; full health inspection is available through
+`ultra.doctor` rather than a session-start health hook.
 Advisory baseline or context-budget warnings are presentation only and never
 reject an edit, stop, or tool call.
 Generic command blocking, post-edit governance, and unrelated user hooks are not
@@ -213,14 +216,18 @@ sessions never call it, and it cannot collect, recall, or reflect memory.
 .ultra/
 ├── .runtime/
 │   ├── state.db             # authoritative SQLite lifecycle/index store
-│   └── checkpoint.json      # advisory breadcrumb recovery projection
+│   ├── checkpoint.json      # advisory breadcrumb recovery projection
+│   └── projections/         # generated checkout-local task views
 ├── changes/
 │   ├── active/<id>/         # all Change semantics and evidence
 │   │   ├── intent.md, findings.md, progress.md
 │   │   ├── research/, delta/, documentation/, plan.json, plan.md
 │   │   └── contexts/, test/, review/, delivery/
 │   └── archive/             # converged packets after baseline reconciliation
-├── tasks/                   # projections and task contexts
+├── tasks/
+│   └── tasks.json           # MCP-published Git team checkpoint
+├── templates/
+│   └── task-context.md      # authored task-context template
 ├── specs/                   # research/product/architecture artifacts
 └── reports/templates/      # blank report schemas; never evidence
 ```

package/docs/ARCHITECTURE.md

@@ -9,8 +9,9 @@
 `ultra-builder-pro-cli` is a multi-runtime plugin suite that **distributes** the
 Ultra Builder Pro engineering loop (skills + commands + workflow hooks) as
 native Claude Code, OpenCode, Codex, and Kimi Code plugins, and
-**runs** that loop with isolated sessions sharing one authoritative state
-store (`.ultra/.runtime/state.db`).
+**runs** that loop with isolated sessions sharing checkout-local operational
+authority (`.ultra/.runtime/state.db`) plus one MCP-published Git team checkpoint
+(`.ultra/tasks/tasks.json`).
 
 It is not an agent or a general conversational-memory provider. It is the workflow
 substrate the supported hosts share, including project-local cross-session workflow
@@ -42,24 +43,26 @@ memory under `.ultra/`.
                   │   .ultra/.runtime/state.db   │
                   │  (SQLite + WAL)     │  ← lifecycle + index authority
                   └──────────┬──────────┘
-                             │ projector (Phase 2.6)
-                             ▼
-              .ultra/tasks/tasks.json     (read-only view)
-              .ultra/tasks/contexts/*.md  (fully generated read-only view)
-              .ultra/activity-log.json    (optional dump)
+                             │
+                   ┌─────────┴──────────┐
+                   │                    │
+                   ▼                    ▼
+     .ultra/.runtime/projections/   .ultra/tasks/tasks.json
+       (local generated views)      (Git team checkpoint:
+                                    baseline + Changes + tasks)
 ```
 
 | Layer        | Role                                         | Form                                                  |
 |--------------|----------------------------------------------|-------------------------------------------------------|
 | **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all supported runtimes |
-| **MCP**      | authoritative workflow-state, decision, artifact, and Context Spine API | stdio MCP server exposing 57 live tools across task/session/baseline/change/decision/workflow/artifact/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | persistence and safety kernel for checkpoints, evidence, sync, leases, archive, and recovery | stdio MCP server exposing seven public `ultra.*` tools; sixty 0.22 fine-grained operations remain hidden for one compatibility release |
 | **CLI**      | explicit initialization, recovery, diagnostics, and orchestration | `ultra-tools` / `ubp-orchestrator`; only commands listed by `--help` are executable (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
 
-Why three: skills give us behavior portability across runtimes; MCP gives
-us a strongly-typed contract so we can refactor implementations without
-rewriting prompts; the CLI supplies bounded maintenance and recovery paths when
-the MCP cannot start. It is deliberately not a second change-state API:
-continuous change mutations remain MCP-only and fail closed (D12).
+Why three: skills preserve adaptable model behavior across runtimes; MCP gives durable
+checkpoint and safety primitives without supervising every reasoning step; the CLI
+supplies bounded maintenance and recovery when MCP cannot start. Semantic draft
+diagnostics are report-first. Corruption, unsafe paths, real concurrency, permissions,
+and irreversible effects remain fail-closed.
 
 The skill layer is **read-only by design** (D29) and is discovered directly by
 each host. Ultra exposes no `skill.*` MCP family: skills are documentation, not
@@ -69,11 +72,14 @@ RPC, and host-native loaders own resolution and invocation.
 
 Together, `.ultra/` retains project-local cross-session workflow memory:
 normalized intent, progress, tasks, bounded context, specifications, evidence,
-provenance, and recovery. `.ultra/.runtime/state.db` is the sole authority for lifecycle,
-indexing, transitions, freshness, and coordination. Registered digest-bound files
-carry semantic and evidence bodies. Generated projections and working scratch do
-not become authority merely because they live under `.ultra/`. The complete
-classification and promotion contract is
+provenance, and recovery. `.ultra/.runtime/state.db` is operational authority for
+lifecycle, indexing, transitions, freshness, and coordination in one checkout.
+Registered digest-bound files carry semantic and evidence bodies.
+`.ultra/tasks/tasks.json` is a portable, digest-chained Git handoff for baseline,
+Change, and durable task records; it never owns sessions, leases, or live
+`in_progress` state. Generated projections and working scratch do not become
+authority merely because they live under `.ultra/`. The complete classification and
+promotion contract is
 [`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
 
 All durable Ultra lifecycle and index state lives in one SQLite file with WAL enabled.
@@ -109,9 +115,11 @@ Two rules make this work:
 
 1. **No double source (D32).** lease/heartbeat live only in `sessions`,
    not in a `lease.json` file. Activity log lives only in `events`, not
-   in JSON files. `tasks.json` and the complete
-   `contexts/task-*.md` files are **projections** generated by the projector;
-   manual edits are overwritten on the next state.db change.
+   in JSON files. `.ultra/.runtime/projections/tasks.json` and its complete
+   `contexts/task-*.md` files are local projections generated by the projector;
+   manual edits are overwritten on the next state.db change. The tracked
+   `.ultra/tasks/tasks.json` is a different surface: only MCP publishes or imports
+   this versioned team checkpoint, and digest validation rejects manual edits.
 
 2. **Single writer for mutable tables, multi-writer for `events`.**
    `.ultra/.runtime/state.db` opens in WAL with `busy_timeout=5000`. The MCP
@@ -214,15 +222,11 @@ current question per thread. The host ends that turn and waits.
 
 The next response becomes a normalized owner decision, explicit reversible delegation,
 or consequence-bearing deferral. Prompts and transcripts are never persisted. The host
-applies accepted intent through the owning MCP operation or digest-bound artifact,
-reads it back, and records typed `applied_refs` when another authority changed. Routine
-settled state then closes through `decision.complete`, which is lifecycle completion
-rather than another approval. The breadcrumb recalls normalized accepted intent after
-the thread closes. Only a coherent cluster that needs an artifact-bound recovery
-boundary moves through prepare/confirm checkpointing. Matching workflow steps fail
-closed while a blocking question, blocking deferral, prepared checkpoint, or stale
-checkpoint artifact remains. Supersession preserves prior history and reopens alignment
-instead of silently editing an old decision. The shared procedure lives in
+batches the normalized result and owning mutation through `ultra.record`, reads it back
+through `ultra.context`, and attempts a semantic checkpoint only when durable authority
+is ready. Failed semantic checks leave the draft editable. Accepted revisions remain
+immutable; a changed decision opens a replacement draft while preserving history. The
+shared procedure lives in
 `skills/ultra-think/references/decision-dialogue.md`; status, breadcrumb, and doctor expose
 only the current recovery surface.
 
@@ -254,9 +258,10 @@ consumer trace. Standard and major convergence requires both current authorities
 only after all writes and baseline reconciliation succeed does it rebind the complete
 Change root into the archive.
 
-Workflow revisions preserve prior accepted runs. A candidate becomes current only
-through `workflow.supersede`; the artifact graph then invalidates the prior run's true
-transitive consumers without staling unrelated tasks.
+Draft revisions remain editable and recoverable. A failed checkpoint can be repaired
+and retried in place or intentionally abandoned. Accepted runs are immutable; a later
+candidate supersedes them only after its own accepted checkpoint, and the artifact graph
+invalidates only true transitive consumers.
 
 ### Context Spine
 
@@ -269,25 +274,24 @@ implementation, checking, review, convergence, and recovery. Each snapshot recor
   execution contract;
 - advisory attention budgets (12 files / about 12k tokens / 40% by default);
 - a DB-derived execution contract (`slice_kind`, public seam, exact verification command);
-- mechanically valid `allowed_transitions` and a `required_transition` only when a
-  hard invariant leaves one recovery route;
+- warnings and hard mechanical blockers without a semantic next-action command;
 - a digest of the accepted Change authority so semantic updates invalidate the
   snapshot.
 
-Prompt input may identify the intended role/gate, add bounded reference candidates,
+Checkpoint input may identify the intended role/gate, add bounded reference candidates,
 and lower advisory budgets. It cannot supply or override the task seam, verification
 command, task context references, evidence digest, gate verdict, workflow summary, or
 machine transitions. A host may attach a clearly non-authoritative recommendation.
 Critical dev/test/review/deliver workflow steps record the matching
 snapshot as an output; test, review, and delivery reports carry its digest forward.
 
-`change.breadcrumb` derives the compact current position from state.db. Session,
+The hook-only breadcrumb derives the compact current position from state.db. Session,
 edit, resume, and OpenCode lifecycle hooks invoke one bundled read-only reader
 and inject it only while state.db proves an active, blocked, or ready workflow,
 never the intent body,
 provider content, or a conversation summary. A changed Git HEAD, task contract, or
-Change semantic authority marks the snapshot stale and permits recompilation through
-`change.context`.
+Change semantic authority marks the snapshot stale and permits content-addressed
+recompilation through the next `ultra.checkpoint`.
 
 PRD decomposition and complex-task subdivision use the active host model. The
 MCP accepts the resulting structured tasks, validates schema, topology,
@@ -297,9 +301,9 @@ model API credential.
 
 Plugin installation does not activate a semantic workflow and never edits the
 user's `CLAUDE.md`, `AGENTS.md`, or equivalent durable instructions. Public
-workflows require explicit user invocation. A completed workflow returns
-mechanically allowed transitions and a host-owned recommendation, then stops;
-it never launches the next public workflow. OpenCode realizes this boundary
+workflows require explicit user invocation. The host reads `ultra.context`, recommends
+the next capability from evidence and owner intent, then stops; SQLite never launches
+or semantically selects the next public workflow. OpenCode realizes this boundary
 with explicit commands backed by private plugin workflow assets, while Claude,
 Codex, and Kimi use their native implicit-invocation controls.
 
@@ -324,14 +328,40 @@ evidence, and final convergence decision.
 
 Mutating MCP calls enqueue durable `projection_jobs`. Success is exposed in MCP
 response metadata; failure becomes a retryable structured incident instead of a
-swallowed warning. `system.doctor` is read-only by default. Explicit repair performs
-backup-first schema upgrade, archive-journal recovery, session and projection
-recovery, and regenerated projections. It cannot approve a baseline or replace a
-corrupt SQLite file silently. `system restore` accepts only a verified SQLite backup
-inside `.ultra/.runtime/backups`, quarantines the corrupt authority, and rolls back on failure.
+swallowed warning. These jobs regenerate only checkout-local views below
+`.ultra/.runtime/projections/`; they never rewrite the Git team checkpoint. Durable
+semantic checkpoints publish team state at baseline, Change, plan, and task handoff
+boundaries. `ultra.doctor` is read-only by default. Explicit repair
+performs backup-first schema upgrade, archive-journal recovery, session and local
+projection recovery, and regenerated local views. It cannot import or publish semantic
+team state, approve a baseline, or replace a corrupt SQLite file silently. `system
+restore` accepts only a verified SQLite backup inside `.ultra/.runtime/backups`,
+quarantines the corrupt authority, and rolls back on failure.
 When no valid backup exists, confirmed `system rebaseline` preserves both corrupt
 authority and the legacy task projection before creating a new brownfield adoption.
 
+### Git team checkpoint and checkout merge
+
+`ultra.sync { action: publish }` serializes the current portable baseline, all Change
+summaries, and durable task contracts to `.ultra/tasks/tasks.json`. Per-record digests and
+revisions make independent fast-forward possible; the document state digest, parent
+digest, and bounded ancestor list reject stale or unrelated histories. Local process
+ownership fields are deliberately absent.
+
+The MCP server imports the checkpoint once when it opens project authority. A
+long-running host explicitly calls `ultra.sync { action: import }` after receiving a newer Git
+version. Import is transactional: it validates every record first, preserves local-only
+fields, fast-forwards clean records, and rejects same-record concurrency or an active
+task collision. Re-reading an already imported checkpoint performs no write. A ready
+baseline is never trusted from Git alone; import creates a local revalidation gap and
+clears checkout-specific approval until current scope bytes, HEAD, and verification
+converge.
+
+Baseline freshness hashes scoped application content independently of Git staging and
+excludes `.ultra/`, then checks commit ancestry. This removes the metadata treadmill:
+committing a checkpoint or another Ultra artifact advances HEAD without staling the
+baseline, while changing scoped application bytes still does.
+
 ## 5. Sessions — the execution unit
 
 A **session** is the standard unit of execution across all four runtimes
@@ -417,7 +447,7 @@ repository commit.
 `ubp --all --global --doctor [--json]` is read-only: it recomputes hashes and
 validates those entry points, returning a non-zero degraded result for
 missing/corrupt provenance, content drift, or broken host wiring. A single host
-can be selected instead of `--all`. This is separate from `system.doctor`, which
+can be selected instead of `--all`. This is separate from `ultra.doctor`, which
 diagnoses project state, projection, incidents, sessions, and backup-first
 workflow recovery.
 
@@ -456,7 +486,8 @@ shippable; downstream slip never blocks an earlier release.
 | What does each MCP tool accept and return?         | [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml)     |
 | How do CLI subcommands map to MCP tools?           | [`spec/cli-protocol.md`](../spec/cli-protocol.md)   |
 | Exact SQLite schema?                               | [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) |
-| What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
+| What does the Git team checkpoint look like?       | [`spec/schemas/task-ledger.v1.schema.json`](../spec/schemas/task-ledger.v1.schema.json) |
+| What does the local task projection look like?     | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
 | Current authority and package decisions            | [`docs/DECISIONS.md`](./DECISIONS.md)               |
 | When does each workflow write, invalidate, and converge state? | [`docs/WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md) |
 
@@ -469,8 +500,8 @@ Every contract on this page is enforced by `npm run test:spec`:
 - `validate-state-db.cjs` — schema applies cleanly to a fresh in-memory
   SQLite, valid fixtures insert, invalid fixtures are rejected by
   CHECK / NOT NULL / FK constraints.
-- `validate-json-schemas.cjs` — projection schemas for `tasks.json` and
-  `contexts/task-*.md`.
+- `validate-json-schemas.cjs` — the team-checkpoint schema plus local projection
+  schemas for `tasks.json` and `contexts/task-*.md`.
 - `validate-skills.cjs` — every existing skill passes the manifest
   contract; failures are recorded in `spec/migration-notes.md`.
 - `check-cli-mapping.cjs` — every MCP tool has exactly one CLI