ultra-builder-pro-cli 0.23.0 → 0.24.0

package/docs/ARTIFACT-AUTHORITY.md

@@ -16,16 +16,16 @@ Semantic and evidence artifacts under `.ultra/` are trackable so reviewed intent
 verification can travel with the repository. `.ultra/.runtime/` is always ignored:
 the SQLite authority, leases, worktrees, local telemetry, and recovery snapshots remain
 checkout-local. `.ultra/tasks/tasks.json` is the narrow MCP-owned Git handoff for
-portable baseline, Change, and durable task records; it is not a copy of live runtime
-state.
+portable baseline, Change, Decision, accepted Stage Checkpoint, and durable Task
+records; it is not a copy of live runtime state.
 
 ## Artifact classes
 
 | Class | Examples | Authority |
 |---|---|---|
-| Checkout-local lifecycle and index | `.ultra/.runtime/state.db` | Operational authority for identifiers, normalized accepted intent, status, legal transitions, references, digests, freshness, provenance, locks, leases, transactions, recovery, and coordination in one checkout |
-| Git team checkpoint | `.ultra/tasks/tasks.json` | MCP-published, digest-chained handoff of portable baseline, Change, task-contract, dependency, and durable status records; never live session or lease authority |
-| Digest-bound semantic artifacts | specifications, research reports, Change intent/delta/plan, context manifests | Authoritative semantic bodies only while registered by the owning DB row or workflow step and matching its recorded digest |
+| Checkout-local persistence and safety | `.ultra/.runtime/state.db` | Operational authority for identifiers, normalized accepted intent, accepted Stage Checkpoints, references, digests, freshness, provenance, locks, leases, transactions, recovery, and coordination in one checkout; never semantic route selection |
+| Git team checkpoint | `.ultra/tasks/tasks.json` | MCP-published, digest-chained handoff of portable baseline, Change, Decision summary/reference, accepted Stage Checkpoint, Task contract, dependency, and durable outcome records; never live Session or lease authority |
+| Digest-bound semantic artifacts | specifications, research reports, Change intent/delta/plan, Context Envelopes, Decision Records | Authoritative semantic bodies only while registered by the owning record or Stage Checkpoint and matching its recorded digest |
 | Digest-bound evidence artifacts | test, review, delivery, and verification reports | Authoritative evidence bodies only while registered, immutable where required, and matching the recorded digest and scope |
 | Generated projections | `.ultra/.runtime/projections/tasks.json`, generated task contexts, activity exports | Checkout-local read-only views derived from DB authority; manual edits are overwritten and never become authority |
 | Advisory recovery | `.ultra/.runtime/checkpoint.json` | Compact recovery hint derived from DB authority; stale or missing content never overrides the DB |
@@ -43,8 +43,8 @@ these surfaces independently owns all three roles.
 | Actor | Responsible for | Must not do |
 |---|---|---|
 | Owner | Goals, acceptance, non-goals, material choices, risk acceptance, and authorization for irreversible or external effects | Supply facts the checkout or runtime can establish directly |
-| Host model | Inspect evidence, recommend a route, ask only for unresolved owner choices, normalize the answer, call the owning write, update semantic artifacts, read back the result, and present the next recommendation | Fabricate evidence, infer owner authorization, or bypass legal transitions |
-| Ultra MCP | Persist normalized inputs, validate structure and current digests, record lifecycle and provenance, enforce legal transitions, project local views, publish/import the Git checkpoint, and expose recovery | Choose product direction, prove a UI click, force a semantic route, or replace model judgment |
+| Host model | Inspect evidence, recommend a route, ask only for unresolved owner choices, normalize the answer, call the owning write, update semantic artifacts, read back the result, and present the next recommendation | Fabricate evidence, infer owner authorization, or bypass mechanical safety |
+| Ultra MCP | Persist normalized inputs, validate structure and current digests, record facts and provenance, commit Stage Checkpoints, project local views, publish/import the Git checkpoint, and expose recovery | Choose product direction, prove a UI click, pre-authorize reasoning steps, force a semantic route, or replace model judgment |
 | Host adapter | Render the shared interaction contract through the host-native question and tool surfaces | Become a second workflow authority |
 | Hook | Observe lifecycle, inject compact DB-derived recovery context, and protect MCP-owned checkpoint and generated projection paths | Select a semantic route or block ordinary development |
 
@@ -79,12 +79,12 @@ Working material becomes durable only when all applicable conditions hold:
 2. consequential claims are verified against the checkout, runtime, test result, or
    primary source;
 3. the model writes through the owning MCP operation or immutable artifact path;
-4. the DB records the owning baseline, change, workflow, task, or artifact reference;
+4. the DB records the owning baseline, Change, Stage Checkpoint, Task, Decision, or artifact reference;
 5. content-bearing files match the recorded SHA-256 digest and scope;
 6. the model reads back the resulting state before reporting completion.
 
 The durable evidence trail may include normalized decisions, delegation source,
-durable effects, typed applied references, workflow-step evidence, artifact hashes,
+durable effects, typed applied references, Stage Checkpoint evidence, artifact hashes,
 verification commands and results, provenance, events, and recovery state. It must not
 include chain-of-thought, UI-click proof, raw prompts, or conversation transcripts.
 
@@ -95,7 +95,7 @@ directory is not promotion.
 ## Change overlay authority
 
 An active Change is an isolated overlay below
-`.ultra/changes/active/<change-id>/`. Its intent, adaptive research, `findings.md`,
+`.ultra/changes/active/<change-id>/`. Its intent, normalized decisions, adaptive research,
 typed delta payloads, plan, contexts, documentation payloads, progress projection,
 test reports, review artifacts, and delivery evidence remain below that root. Change
 research never edits baseline specifications.
@@ -120,11 +120,12 @@ as delivered.
 
 ## Context and plan authority
 
-The Context compiler used by `ultra.checkpoint` reads accepted Change, task, baseline,
-checkout, and provider-reference authority and writes one immutable manifest plus its
-DB snapshot row. It never updates provider references or semantic Change fields. Each snapshot is
-identified exactly by `change_id`, nullable `task_id`, `role`, and `gate`; consumers
-must not substitute a newer snapshot from a different tuple.
+The canonical Context Envelope generator reads accepted Change, Task, baseline,
+Decision, checkout, evidence, execution, and provider-reference authority and writes
+one immutable manifest plus its DB snapshot row when persistence is requested. It
+never updates provider references or semantic Change fields. Each snapshot is
+identified by its exact scope, stage, content digest, and selected execution seam;
+consumers must not substitute a snapshot from another scope.
 
 Context refs preserve `expected_digest`, `anchor`, `scope`, and `freshness_policy`.
 Digest-bound refs are revalidated at the consuming gate, existence-bound implementation
@@ -151,7 +152,7 @@ never current write or dispatch authority.
 ## Registry contract
 
 `ultra.record` is the public writer for a semantic or evidence file that is not
-already registered by its owning workflow operation. Every managed registry row has:
+already registered by its owning typed record or Stage Checkpoint. Every managed registry row has:
 
 - a typed `owner_type` and `owner_id`;
 - an artifact `kind`, project-relative `path`, lifecycle `status`, and SHA-256
@@ -164,7 +165,7 @@ already registered by its owning workflow operation. Every managed registry row
 The write replaces all edges for the artifact in one immediate SQLite transaction.
 It never accumulates stale edges with `INSERT OR IGNORE`. If an existing digest
 changes, the same transaction emits `spec_changed`, marks only reachable artifact
-and task consumers stale through typed artifact/task/workflow/change intermediates,
+and Task consumers stale through typed artifact, Task, checkpoint, and Change intermediates,
 and records the exact invalidated endpoints. Self-edges and dependency cycles are
 rejected without changing prior authority. A caller can provide
 `expected_before_digest`; a mismatch fails without changing the row or its edges.
@@ -176,13 +177,13 @@ all owners and kinds. Runtime, scratch, the MCP-owned team checkpoint, and gener
 task contexts cannot be promoted through this API.
 
 Owning internal writers use the same transaction contract. Change intent, delta and
-documentation packets, contexts, adaptive research, findings, incident diagnosis,
+documentation packets, Context Envelopes, adaptive research, incident diagnosis,
 plan, test, review, delivery, archive reconciliation, and specification learning
 cannot update a managed digest or provenance through a parallel SQL path.
 
 Rows migrated from pre-20 schemas remain readable and preserve their original IDs,
 paths, hashes, timestamps, and legacy change/task ownership. They are marked
-`managed = 0` until an owning workflow or `artifact.record` supplies complete
+`managed = 0` until an owning current record or `artifact.record` supplies complete
 provenance and dependency edges. This compatibility state preserves data without
 pretending that an old row satisfies the current registry contract.
 
@@ -219,8 +220,10 @@ or retired.
 contains:
 
 - one portable baseline record, when present;
-- every Change summary, including a Change that has not yet produced tasks;
-- durable task contracts, dependencies, acceptance mappings, and statuses;
+- every Change summary, including a Change that has not yet produced Tasks;
+- normalized Decision summaries, artifact references, digests, and supersession;
+- accepted Stage Checkpoint summaries and evidence references;
+- durable Task contracts, dependencies, acceptance mappings, and outcomes;
 - per-record revisions, parent digests, the checkpoint state digest, and bounded
   checkpoint ancestry.
 
@@ -268,6 +271,7 @@ carrying the generated marker may be pruned, and the removal emits
 `projection_pruned`.
 
 Model findings, decisions, or evidence discovered during development must be written
-below the owning Change root and registered through the workflow or `artifact.record`.
+below the owning Change root and registered through its typed record, checkpoint, or
+`artifact.record`.
 The next context projection references that authority. Editing the task-context body
 or an accepted baseline specification directly is neither persistence nor promotion.

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -30,26 +30,29 @@ ownership or preserve unrelated edits. The owner may review and remove them sepa
 
 ## Activation
 
-Public Ultra workflows run only after an explicit user command or skill invocation.
-Completion of one workflow may return allowed transitions and a recommendation, but it
-must not start another public workflow.
+Public Ultra workflows run only after an explicit user command or Skill invocation.
+Completion of one workflow may return current Context diagnostics and a host-model
+recommendation, but it must not start another public workflow. SQLite does not choose
+or authorize that recommendation.
 
 Host adapters prevent implicit model activation with the strongest native mechanism:
 
-- Claude Code and Kimi Code mark public workflow skills as model-disabled;
+- Claude Code and Kimi Code mark public workflow Skills as model-disabled;
 - Codex marks workflow metadata as implicit-invocation-disabled;
 - OpenCode exposes public workflows through commands backed by private plugin assets,
   not through the model-discoverable skill catalog.
+- Grok Build uses explicit plugin Skills/commands and makes Skill-entry
+  `ultra.context` authoritative when a Hook output channel is not consumed.
 
 Internal review-rule skills remain available only to their bounded workers.
 
 ## Idle behavior
 
-Outside a repository containing `.ultra/.runtime/state.db`, all Ultra hooks are silent. Inside
-an initialized repository they remain silent unless a DB-authoritative workflow is
-active, blocked, or ready. The sole idle-time enforcement is protection against direct
-writes to the MCP-owned team checkpoint or generated Ultra projections; the DB remains
-checkout-local operational authority.
+Outside a repository containing `.ultra/.runtime/state.db`, all Ultra Hooks are silent.
+Inside an initialized repository, a Hook may inject one bounded Context Envelope when
+the host consumes that channel. The sole idle-time enforcement is protection against
+direct writes to the MCP-owned team checkpoint or generated Ultra projections; the DB
+remains checkout-local operational authority. Semantic incompleteness is advisory.
 
 Installation tests preserve byte-for-byte snapshots of all supported user handbook
 paths. Runtime tests cover explicit activation, idle silence, active recovery, and

package/docs/ROADMAP.md

@@ -1,96 +1,56 @@
-# ultra-builder-pro-cli — Roadmap
-
-> **Current roadmap**. [`DECISIONS.md`](./DECISIONS.md) defines the current
-> authority and package boundaries. Executable contracts live in `spec/`,
-> `AGENT-CONTEXT.md`, and `RUNTIME-COMPAT-MATRIX.md`; source and contract tests
-> win when roadmap text drifts.
-
-**Goal**: distribute the Ultra Builder Pro engineering loop as native Claude
-Code, OpenCode, Codex, and Kimi Code plugins, and run it with isolated sessions
-sharing one authoritative workflow store.
-
-**First-class runtimes**: Claude Code · OpenCode · Codex · Kimi Code.
-
-**Distribution channels (v1.0)**: npm · Homebrew · pip.
-
-**Release line**: the `package.json` version; every release is gated by
-`npm run verify:release`.
-
----
-
-## Milestones
-
-| Release | Week | Contents                                                                  |
-|---------|-----:|---------------------------------------------------------------------------|
-| **v0.1**| 8    | Rule layer + execution-lite (session isolation + admission + event subscribe + active-session visibility) — solves the core "independent conversations don't pollute each other" pain |
-| **v0.2**| 11   | Auto-recovery + monitoring + full conformance |
-| **v0.3**| 16   | PRD → execution-plan artifact → parallel dispatch / merge — coding factory |
-| **v1.0**| 17–18| Three-channel publish (npm + Homebrew + pip)                              |
-
-## Phase status
-
-| Phase | Title                                          | Status        |
-|-------|------------------------------------------------|---------------|
-| 0     | Skeleton                                       | ✅ done (`da69a7a`) |
-| 1     | Three-layer interface contracts (`spec/`)      | ✅ done (D38) |
-| 2     | Authoritative state — SQLite + WAL             | ✅ done (D39, `e286e41`) |
-| 3     | Command thin-shells (skill + MCP + CLI)        | ✅ done (D40, `b3d1797`) |
-| 4     | Cross-runtime distribution + 4.6a smoke flow   | ✅ done (D41, `5aa1fd0`) |
-| 4.5   | Execution-lite (session + admission + events)  | ✅ done (D42, `0d3e5ed`) — **v0.1 ready** |
-| 5     | Recovery + staleness + auto-routing            | ✅ done (D43) → v0.2 |
-| 6     | Monitoring + telemetry                          | ✅ done (D44) → v0.2 |
-| 4.6b  | Full conformance suite                         | ✅ done (D45) — 20 conformance + 21 resolveTarget tests |
-| 7     | tagged tasks; non-core generation and retention surfaces removed from the plugin | ✅ superseded by the package-boundary cleanup |
-| 8A    | Plan automation (parse / topo / expand + artifact + human gate) | ✅ done (D47, `a932cb8`) → v0.3 |
-| 8B    | Execution automation (dispatch / parallel worktree / merge) | ✅ done (D48, `8224159`) — **v0.3 ready** |
-| 8C    | Continuous change packets + context compiler + convergence + doctor | ✅ done (D52) |
-| 10    | Context Manifest v3 + breadcrumb + fresh-context budget + spec learning + two-axis review | ✅ done |
-| 11    | Greenfield/brownfield baseline adoption + advisory context budgets + convergence gate | ✅ done |
-| 12    | Repository evidence snapshots + gap ledger + migration re-adoption + incident governance | ✅ done |
-| 13    | Durable init-to-delivery workflows + task execution contracts + immutable stage evidence | ✅ done |
-| 16    | Resumable one-question owner-agent decisions + artifact checkpoints + workflow gates | ✅ done |
-| 19    | Non-ceremonial decision completion + four-host semantic-selection contract | ✅ done |
-| 20    | Typed artifact registry + normalized dependency graph + orphan diagnostics | ✅ done |
-| 9     | Release pipeline                               | npm tag publishing live; Homebrew / pip not implemented |
-
-## What is in the repo today
-
-```
-spec/                       ← Phase 1 single source of truth
-├── mcp-tools.yaml          (7 public kernel tools + 60 hidden compatibility operations)
-├── cli-protocol.md         (CLI ↔ MCP mapping table)
-├── schemas/                (state-db.sql + 4 JSON schemas)
-├── fixtures/{valid,invalid}/  (+ v4.4-project for migration)
-└── scripts/test-all.cjs    (npm run test:spec — 7 validation stages)
-
-mcp-server/                 ← Phase 2 authoritative state layer
-├── server.cjs              (stdio MCP server with a 7-tool public façade)
-├── lib/
-│   ├── state-db.cjs        (SQLite + WAL + pragmas)
-│   ├── state-ops.cjs       (full write API, status state machine)
-│   ├── baseline-workflow.cjs (project adoption + approval + reconciliation)
-│   ├── decision-dialogue.cjs (one-question authority + completion/checkpoint gates)
-│   ├── workflow-state.cjs  (ordered stage runs, evidence, output digests, and gates)
-│   └── projector.cjs       (state.db → tasks.json + context md)
-└── tests/                  (npm run test:state)
-
-ultra-tools/                ← CLI fallback, migration, and diagnostics
-├── cli.cjs
-└── commands/
-    ├── db.cjs              (init/checkpoint/vacuum/integrity/backup)
-    ├── migrate.cjs         (v4.4 projection → v4.5 authority; v4.5 projection → current schema; dry/rollback)
-    └── legacy-memory.cjs   (explicit inspect/archive/confirmed prune)
-
-bin/install.js              ← multi-runtime installer
-adapters/                   ← native host plugin builders
+# Ultra Builder Pro roadmap
+
+The current product is a five-host adaptive delivery harness with a seven-tool
+persistence and safety kernel. `docs/DECISIONS.md` defines durable decisions;
+schemas, source, and contract tests define executable behavior.
+
+## Current release boundary
+
+- First-class hosts: Claude Code, OpenCode, Codex, Kimi Code, and Grok Build.
+- Distribution: npm package plus host-native generated plugins.
+- Public semantic workflows: 11 explicit Skills.
+- Public MCP surface: exactly 7 tools.
+- Local authority: `.ultra/.runtime/state.db`.
+- Team handoff: `.ultra/tasks/tasks.json` and tracked semantic/evidence artifacts.
+- General memory, code graph, browser, deployment, and framework guidance: external.
+
+## Current repository
+
+```text
+spec/
+├── mcp-tools.yaml
+├── cli-protocol.md
+├── schemas/
+└── fixtures/
+
+mcp-server/
+├── server.cjs
+├── hook-context.cjs
+└── lib/
+    ├── ultra-facade.cjs
+    ├── context-envelope.cjs
+    ├── decision-records.cjs
+    ├── stage-checkpoints.cjs
+    ├── worker-packet.cjs
+    ├── task-ledger.cjs
+    ├── state-db.cjs
+    ├── state-ops.cjs
+    ├── artifact-registry.cjs
+    ├── baseline-workflow.cjs
+    ├── change-workflow.cjs
+    ├── doctor.cjs
+    └── projector.cjs
+
+adapters/
 ├── claude.js
 ├── opencode.js
 ├── codex.js
-└── kimi.js
-skills/                     ← allowlisted Ultra workflows, internal rules, and collab companions
-hooks/                      ← allowlisted workflow hooks; OpenCode uses native JavaScript hooks
+├── kimi.js
+└── grok.js
+
+hooks/
 ├── active_task_context.py
-├── context_spine.py
+├── context_envelope.py
 ├── health_check.py
 ├── pre_stop_check.py
 ├── runtime_paths.py
@@ -98,29 +58,44 @@ hooks/                      ← allowlisted workflow hooks; OpenCode uses native
 ├── workflow_checkpoint.py
 ├── workflow_context.py
 └── workflow_resume.py
-docs/
-├── DECISIONS.md                 current authority and package boundaries
-├── ARCHITECTURE.md              Phase 1 single-page entry point
-├── WORKFLOW-LIFECYCLE.md        baseline classification + DB transition contract
-├── AGENT-CONTEXT.md             Phase 3 canonical runtime context contract
-├── PLUGIN-ISOLATION-CONTRACT.md install, activation, idle, and ownership contract
-├── RUNTIME-COMPAT-MATRIX.md     Phase 4 runtime capability matrix
-├── STATE-DB-ACCESS-POLICY.md    Phase 2 multi-process write contract
-├── COMMIT-HASH-BACKFILL.md      Checkout-local completion commit evidence
-└── ROADMAP.md                   this file
-```
-
-## How to verify
 
+skills/                 # 11 public, 4 internal, explicit collab companions
+agents/                 # bounded Worker Packet consumers
+ultra-tools/            # CLI diagnostics, migration, and recovery
+orchestrator/           # optional approved Worker Packet dispatch
 ```
-npm install
-npm run test:all
-python3 -m pytest hooks/tests -q
-npm audit
+
+Retired semantic-supervisor modules remain only in source migration/regression history
+and are excluded from the npm package. They do not authorize current Stage
+Checkpoints, Sessions, Skills, or archive.
+
+## Completed product invariants
+
+- MCP does not select semantic routes or pre-authorize reasoning steps.
+- Draft Stage Checkpoints are mutable; accepted revisions are immutable and
+  supersedable.
+- Context, accepted decisions, and evidence are visible across sessions and Git
+  checkout sync.
+- Every delegated worker receives an immutable Worker Packet.
+- All five host installers stage, preflight, and atomically swap complete native
+  runtimes.
+- v4.4/v4.5 and v0.22/v0.23 authority migrates backup-first.
+- Hooks are observation/injection/protection only.
+- `.runtime` stays local while reviewed intent and evidence remain team-trackable.
+
+## Verification
+
+```bash
+npm run verify:release
+npm pack --dry-run --json
+node bin/install.js --all --global --doctor --json
 ```
 
-## Out of scope for v1.0 (deferred)
+The release gate also installs the tarball into a clean consumer and exercises public
+write/read/backup/reopen through every generated host launcher.
+
+## Deferred product directions
 
-Additional runtimes, a web dashboard or TUI, a team-collaboration server, and
-an independent plugin marketplace remain deferred until a current product
-decision brings them into scope.
+A web dashboard or TUI, a collaboration server, Homebrew/pip distribution, and an
+independent marketplace remain uncommitted product directions. They must enter through
+a new explicit decision and Change rather than this roadmap silently promising them.