ultra-builder-pro-cli 0.24.0 → 0.24.1

package/.ultra-template/tasks/tasks.json

@@ -1,13 +1,15 @@
 {
   "kind": "ultra-team-task-ledger",
-  "schema_version": "1.0",
+  "schema_version": "2.0",
   "generation": 0,
   "parent_digest": null,
   "ancestors": [],
-  "state_digest": "5bf27fb3627b711c97abf72f0aad150ba693d35bcebdd57c2d80e325f495de6d",
+  "state_digest": "88098433d797125bb0f87068a01205cf378494169ca93ee2a9dcf15c1c83dd63",
   "published_at": null,
   "reason": "scaffold",
   "baseline": null,
   "changes": [],
+  "decisions": [],
+  "checkpoints": [],
   "tasks": []
 }

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.1] — 2026-07-31
+
+### Changed
+
+- Kept semantic completeness, route selection, baseline sufficiency, and delivery
+  acceptance in Skills and the host model. The MCP kernel now records those conclusions
+  as advisory diagnostics while retaining hard failures only for structural authority,
+  current bytes, digests, scope ownership, concurrency, permissions, and recovery.
+- Made local delivery follow the evidence required by the actual Change route. Explicit
+  omissions and their rationale are preserved without imposing a fixed
+  Plan/Dev/Test/Review sequence on every archive.
+- Made completed Tasks explicitly reopenable without erasing their prior completion
+  commit or accepted history.
+
+### Fixed
+
+- Fixed nonexistent or mismatched Task/Change checkpoint scopes creating ghost
+  checkpoint authority; invalid scopes now fail before any Context or checkpoint write.
+- Fixed shallow or contradictory evidence declarations being accepted without checking
+  current managed artifact authority and stable file bytes.
+- Fixed baseline semantic gaps, missing optional research, and `not_run` verification
+  being misrepresented as mechanical authority failures.
+- Fixed installed Change revision paths depending on source-only semantic supervisor
+  modules excluded from the npm package.
+- Fixed Hooks, Skills, templates, and packaged documentation disagreeing about advisory
+  diagnostics, adaptive delivery, and the persistence/safety-kernel boundary.
+
 ## [0.24.0] — 2026-07-30
 
 ### Added

package/README.md

@@ -48,8 +48,10 @@ Ultra Builder Pro addresses those gaps with four ideas:
    recovery state across host sessions. Tracked semantic artifacts plus the
    MCP-published `.ultra/tasks/tasks.json` checkpoint carry reviewed project intent
    across Git checkouts without committing SQLite, leases, or telemetry.
-4. **Convergent delivery.** Research, plans, implementation, tests, review, and
-   specification updates must agree before a change is archived.
+4. **Adaptive delivery.** The host model evaluates the evidence produced by the
+   actual Change route, explicitly records any omitted capability and its rationale,
+   and asks the owner to accept the local handoff. MCP validates current managed
+   authority and archive integrity rather than requiring a fixed stage sequence.
 
 For example, if the user asks an agent to add organization SSO to an existing
 application, Ultra helps the agent inspect the real authentication path, capture
@@ -103,14 +105,14 @@ The responsibility split is deliberate:
 |---|---|
 | **User** | Product intent, semantic route selection, material scope and trade-offs, risk acceptance, destructive actions, publishing and deployment authorization |
 | **Host model** | Fact-finding, synthesis, research-coverage and route recommendations, reversible implementation decisions |
-| **Ultra MCP** | Structure validation, durable checkpoints, evidence references, digests, team sync, leases, archive transactions, and mechanical recovery; never semantic route selection |
+| **Ultra MCP** | Structure/current-byte validation, caller-declared checkpoints, evidence references, digests, team sync, leases, archive transactions, and mechanical recovery; never semantic completeness or route selection |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
 | **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of MCP-owned checkpoint and generated projection paths |
 
-The MCP does not replace the model's judgment or pre-authorize a semantic route. It
-reports draft diagnostics and commits accepted checkpoints. A hook does not decide
-product strategy. A prompt does not become durable authority merely because it
-appeared in a conversation.
+The MCP does not replace the model's judgment, judge completion, or pre-authorize a
+semantic route. It reports diagnostics and safely commits the model's explicit
+checkpoint/archive handoff. A hook does not decide product strategy. A prompt does not
+become durable authority merely because it appeared in a conversation.
 
 ### The seven-tool MCP kernel
 
@@ -120,10 +122,10 @@ The public model-facing surface is intentionally small:
 |---|---|
 | `ultra.context` | Read the complete current spine without side effects |
 | `ultra.record` | Batch typed draft facts and events with idempotency |
-| `ultra.checkpoint` | Attempt one semantic stage checkpoint; rejection leaves the draft editable |
+| `ultra.checkpoint` | Commit one caller-declared stage checkpoint after structural, byte, digest, and publication validation |
 | `ultra.sync` | Inspect, import, or publish the Git team checkpoint |
 | `ultra.session` | Own the transactional execution lease |
-| `ultra.archive` | Converge and archive through the recoverable filesystem/DB boundary |
+| `ultra.archive` | Persist one explicit local delivery handoff through the recoverable filesystem/DB boundary |
 | `ultra.doctor` | Inspect or repair mechanical health, backup first |
 
 Retired fine-grained operation names are neither discoverable nor callable. Workflow
@@ -283,7 +285,7 @@ resolves observable facts itself and asks for material product decisions as
 needed. Once the evidence and specifications are accurate, the user approves
 the baseline.
 
-The common path after baseline approval is:
+One common full-depth path after baseline approval is:
 
 ```text
 ultra-change
@@ -295,11 +297,14 @@ ultra-change
   -> ultra-deliver
 ```
 
-Each public workflow is explicitly invoked rather than auto-chained. Thinking and
-research coverage are adaptive, and verification depth is risk-selected, but every
-Change reaches a current plan, DB-backed task contract, and role-scoped context before
-development. “Direct Build” skips Research only; it does not bypass Plan, Task, or
-Context authority.
+Each public workflow is explicitly invoked rather than auto-chained. The example is a
+recommended route for a normal implementation Change, not an archive state machine.
+Thinking and research coverage are adaptive, verification depth is risk-selected, and
+the host may omit or repeat a capability when the actual Change makes that appropriate,
+provided the delivery handoff names the omission and its rationale. Any implementation
+task still requires a current plan, DB-backed task contract, and role-scoped context.
+“Direct Build” skips Research only; it does not bypass Plan, Task, or Context authority
+when development is performed.
 
 ### 2. Adopt an existing project
 
@@ -365,9 +370,12 @@ must be reconciled against the current Change authority.
 
 ### 4. Deliver and continue
 
-`ultra-deliver` verifies that implementation, acceptance evidence, testing,
-review findings, specification learning, and baseline reconciliation agree. It
-then archives the local Ultra change authority.
+`ultra-deliver` asks the host model to assess the current managed evidence for the
+route the Change actually took. The handoff explicitly records any omitted capability
+and its evidence-based rationale; the owner decides whether that semantic packet is
+sufficient. MCP then validates paths, digests, reconciliation structure, idempotency,
+and recoverability before archiving the local Ultra change authority. It does not
+require every Change to pass through a fixed Research/Plan/Dev/Test/Review sequence.
 
 Delivery does **not** grant permission to commit, push, publish, tag, deploy, or
 perform another external effect. Those actions remain separate and require the
@@ -430,11 +438,16 @@ flowchart TD
     PLAN --> DEV["ultra-dev<br/>one dependency-ready vertical task"]
     DEV --> TASKS{"More executable tasks?"}
     TASKS -->|"Yes"| DEV
-    TASKS -->|"No"| TEST["ultra-test<br/>risk-selected formal verification"]
+    TASKS -->|"No"| ASSESS{"What evidence does this Change still need?"}
+    ROUTE -->|"Accepted handoff already has sufficient evidence"| DELIVER["ultra-deliver"]
+    ASSESS -->|"Risk-selected verification"| TEST["ultra-test<br/>risk-selected formal verification"]
+    ASSESS -->|"Independent review"| REVIEW["ultra-review<br/>specification fidelity and engineering quality"]
+    ASSESS -->|"Caller accepts current evidence and explicit omissions"| DELIVER
     TEST -->|"Failed or incomplete"| DEV
-    TEST -->|"Passing"| REVIEW["ultra-review<br/>specification fidelity and engineering quality"]
+    TEST -->|"Review is warranted"| REVIEW
+    TEST -->|"Caller accepts current evidence and explicit omissions"| DELIVER
     REVIEW -->|"Changes required"| DEV
-    REVIEW -->|"Approved"| DELIVER["ultra-deliver"]
+    REVIEW -->|"Approved"| DELIVER
     DELIVER --> ARCHIVE["Reconcile specifications<br/>apply the Change overlay and archive evidence"]
     ARCHIVE --> NEXT{"Continue"}
     NEXT -->|"Next outcome"| CHANGE
@@ -586,10 +599,10 @@ host's existing model session.
   any real conflict. Never edit `.ultra/tasks/tasks.json` by hand.
 - **A generated view disagrees with MCP:** trust `.ultra/.runtime/state.db`; never edit
   `.ultra/.runtime/projections/` by hand.
-- **A draft checkpoint is rejected:** use `ultra-status` to read the exact warnings
-  and blockers, fix the same mutable draft, and retry. If the attempt is no longer
-  relevant, leave it as history and open a new draft revision; no hidden workflow
-  state must be cancelled first.
+- **A draft checkpoint reports warnings:** the model keeps them visible and decides
+  whether to investigate, revise, defer with rationale, or accept. If a checkpoint is
+  rejected for a structural, digest, path, publication, or concurrency conflict, fix
+  the same mutable draft and retry; no hidden workflow state must be cancelled first.
 - **Kimi reports a native-module ABI error:** ensure an external Node.js 22+
   executable is available on `PATH`; the generated Kimi MCP launcher uses
   `env node`.

package/docs/AGENT-CONTEXT.md

@@ -95,15 +95,17 @@ If the host mode forbids interaction, leave the decision unresolved.
 
 ## Stage Checkpoints
 
-Skills describe adaptive evidence expectations; SQLite does not authorize a fixed
-step sequence. A stage has a mutable draft and immutable accepted revisions:
+Skills describe adaptive evidence expectations and decide semantic sufficiency;
+SQLite does not authorize a fixed step sequence or reinterpret the supplied verdict.
+A stage has a mutable draft and immutable accepted revisions:
 
 ```text
 draft N -> accepted N -> superseded by accepted N+1
 ```
 
-Warnings and semantic gaps do not lock a draft. An accepted revision can be replaced
-by a later accepted revision without rewriting history.
+Warnings and semantic gaps do not reject explicit acceptance. Structural, digest,
+path, publication, and concurrency conflicts leave the draft mutable. An accepted
+revision can be replaced by a later accepted revision without rewriting history.
 
 ## Worker handoff
 

package/docs/ARCHITECTURE.md

@@ -59,10 +59,10 @@ Every host discovers exactly seven tools:
 |---|---|
 | `ultra.context` | Side-effect-free, bounded Context Envelope read |
 | `ultra.record` | Typed, idempotent recording of facts, decisions, artifacts, tasks, outcomes, and observations |
-| `ultra.checkpoint` | Reversible draft validation and immutable accepted Stage Checkpoint |
+| `ultra.checkpoint` | Caller-declared Stage Checkpoint with structural, scope, byte, digest, and publication validation |
 | `ultra.sync` | Inspect, migrate, import, or publish the Git team checkpoint |
 | `ultra.session` | Lease/worktree acquisition plus immutable Worker Packet handoff |
-| `ultra.archive` | Crash-safe delivery convergence and immutable archive |
+| `ultra.archive` | Crash-safe caller-declared local handoff and immutable archive |
 | `ultra.doctor` | Mechanical diagnosis and backup-first repair |
 
 Retired fine-grained tool names are not registered and return `UNKNOWN_TOOL`. The
@@ -119,8 +119,10 @@ draft N -> accepted N -> superseded by accepted N+1
 ```
 
 There is no fixed step authorization table. Skills decide which evidence is relevant
-to the actual work. Checkpoint validation verifies declared facts, files, digests, and
-scope; an incomplete draft remains mutable.
+and whether the actual work is semantically sufficient. Checkpoint validation verifies
+declared facts, files, digests, scope, idempotency, and safe publication. Semantic
+warnings remain recorded but do not prevent an explicit caller acceptance; a hard
+authority conflict leaves the draft mutable.
 
 ### Worker Packets
 

package/docs/ARTIFACT-AUTHORITY.md

@@ -44,7 +44,7 @@ these surfaces independently owns all three roles.
 |---|---|---|
 | 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 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 |
+| Ultra MCP | Persist normalized inputs, validate structure/current bytes/digests, record facts and provenance, commit caller-declared Stage Checkpoints, project local views, publish/import the Git checkpoint, and expose recovery | Judge semantic completeness, 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 |
 
@@ -112,11 +112,13 @@ document's before/after digest, delta and acceptance references, verification, a
 verified consumer or explicit no-consumer reason. Standard and major delivery require
 one current reconciliation even when its document set is empty.
 
-`change.archive` preflights the complete target set before writing, applies overlay
-bytes through a recoverable local transaction, refreshes baseline digests, moves the
-complete Change root to its archive location, and rebinds registry paths. A conflict,
-crash, or DB failure must roll back or resume the whole packet; no subset is reported
-as delivered.
+The Deliver Skill owns the evidence-based semantic handoff and records any deliberate
+stage omission. `change.archive` does not infer completeness or require a fixed
+Plan/Dev/Test/Review/Deliver sequence. It preflights the caller-declared target set
+before writing, validates reconciliation structure, applies overlay bytes through a
+recoverable local transaction, refreshes baseline digests, moves the complete Change
+root to its archive location, and rebinds registry paths. A conflict, crash, or DB
+failure must roll back or resume the whole packet; no subset is reported as delivered.
 
 ## Context and plan authority
 
@@ -141,7 +143,8 @@ A current plan is a Change-owned pair:
   task contracts.
 
 The Plan checkpoint selects both paths from the owning Change and accepts no arbitrary
-output path. It binds the JSON digest and the preceding `plan/planning` snapshot;
+output path. The model owns decomposition and semantic coverage. MCP binds the JSON
+digest and the preceding `plan/planning` snapshot;
 the artifact registry records both plan files with that context provenance. Publication
 preflights both path authorities and prior digests, rejects symlinked ancestors or
 targets, and journals the two file replacements so a registry or event failure restores

package/docs/LEGACY-CLI-CROSSWALK.md

@@ -29,7 +29,7 @@ contract and adds stronger authority, recovery, or portability.
 | Development uses isolated Git work, TDD, verification, review, commit, and integration | `ultra-dev`, `session.*`, and the session runner create real worktrees and retain task/review/commit evidence | Preserved and strengthened. Process exit cannot complete a task; uncommitted or unintegrated worktrees cannot be deleted. |
 | Test checks wiring, acceptance, regression, build, performance, security, and failures | `ultra-test` emits a change-bound immutable report covering each applicable dimension | Preserved and strengthened with HEAD, context, task-set, and report-digest validation. |
 | Review challenges specification fidelity and engineering quality | `ultra-review` is a first-class stage with independent specification and engineering axes | Strengthened. A coordinated summary cannot replace either complete axis. |
-| Delivery verifies clean readiness, documentation, build, and evidence | `ultra-deliver` requires current tasks, test, review, learning resolution, reconciliation, a local archive, and an immutable report | Preserved and strengthened. Publish, deploy, push, and other external effects remain separate explicitly authorized operations. |
+| Delivery verifies clean readiness, documentation, build, and evidence | `ultra-deliver` assesses the explicitly accepted evidence packet for the actual Change route, records deliberate omissions, reconciles current managed authority, and creates a recoverable local archive and immutable report | Preserved without a fixed stage gate and strengthened by path, digest, reconciliation, idempotency, and recovery validation. Publish, deploy, push, and other external effects remain separate explicitly authorized operations. |
 | Status restores the current workflow position | `ultra-status` reads DB authority, Git, sessions, artifacts, decisions, allowed transitions, and any hard recovery requirement | Strengthened. The host recommends the semantic route; projections and Prompt prose cannot override state. |
 | Thinking synchronizes owner and Agent intent | `ultra-think` plus `decision.*` persists one-question dialogue, non-ceremonial completion, and optional artifact checkpoints | Strengthened. Observable facts are resolved first; only load-bearing owner choices block. |
 

package/docs/WORKFLOW-LIFECYCLE.md

@@ -15,19 +15,24 @@ flowchart TD
     RESEARCH --> THINK["ultra-think when a material decision remains"]
     THINK --> RESEARCH
     RESEARCH --> CHANGE["ultra-change"]
-    CHANGE --> ROUTE{"Evidence sufficient?"}
-    ROUTE -->|"No"| CR["bounded ultra-research"]
-    CR --> PLAN["ultra-plan"]
-    ROUTE -->|"Yes"| PLAN
+    CHANGE --> ROUTE{"What does this Change actually need?"}
+    ROUTE -->|"Evidence gap"| CR["bounded ultra-research"]
+    CR --> ROUTE
+    ROUTE -->|"Implementation"| PLAN["ultra-plan"]
     PLAN --> DEV["ultra-dev for one owned Task"]
     DEV --> MORE{"More executable Tasks?"}
     MORE -->|"Yes"| DEV
-    MORE -->|"No"| TEST["ultra-test"]
+    MORE -->|"No"| ASSESS{"What evidence is still warranted?"}
+    ROUTE -->|"No implementation; current evidence is sufficient"| ASSESS
+    ASSESS -->|"Risk-selected verification"| TEST["ultra-test"]
+    ASSESS -->|"Independent review"| REVIEW["ultra-review"]
+    ASSESS -->|"Caller accepts current packet and explicit omissions"| DELIVER["ultra-deliver"]
     TEST -->|"implementation gap"| DEV
-    TEST -->|"evidence accepted"| REVIEW["ultra-review"]
+    TEST -->|"review warranted"| REVIEW
+    TEST -->|"caller accepts evidence"| DELIVER
     REVIEW -->|"implementation issue"| DEV
     REVIEW -->|"contract issue"| PLAN
-    REVIEW -->|"accepted"| DELIVER["ultra-deliver"]
+    REVIEW -->|"accepted"| DELIVER
     DELIVER --> CHANGE
     STATUS["ultra-status"] -.-> INIT
     STATUS -.-> CHANGE
@@ -35,10 +40,12 @@ flowchart TD
     DOCTOR -.-> CHANGE
 ```
 
-The graph is guidance, not database authorization. A quick, well-understood Change may
-skip extra research, but it still needs an explicit Plan, Task contract, Context,
-verification, review, and delivery evidence. `ultra-status` is read-only.
-`ultra-doctor` repairs mechanical authority only.
+The graph is guidance, not database authorization. The host model selects the evidence
+needed by the actual Change route and records every deliberate omission in the delivery
+handoff. When implementation occurs, its Plan, Task contract, and Context remain
+mandatory execution authority; Research, Test, and Review are used according to the
+actual evidence and risk rather than as universal archive gates. `ultra-status` is
+read-only. `ultra-doctor` repairs mechanical authority only.
 
 ## Shared command contract
 
@@ -99,10 +106,12 @@ draft revision N
   -> accepted revision N+1 supersedes N
 ```
 
-A failed acceptance returns diagnostics and keeps the same draft mutable. Plan export
-is part of Plan checkpoint publication, so changing a Task contract before acceptance
-cannot invalidate an already-recorded “export step.” There is no locked intermediate
-run to cancel or manually repair.
+Semantic diagnostics remain recorded but do not reject the model's explicit
+checkpoint conclusion. A structural, digest, path, publication, or concurrency
+conflict keeps the same draft mutable. Plan export is part of Plan checkpoint
+publication, so changing a Task contract before acceptance cannot invalidate an
+already-recorded “export step.” There is no locked intermediate run to cancel or
+manually repair.
 
 Accepted checkpoints are immutable evidence. New facts create a replacement draft.
 Only archive history is terminal; subsequent product work opens a new Change.
@@ -118,9 +127,11 @@ active -> archived
 ```
 
 `blocked`, `ready`, and `needs_attention` are derived diagnostics, not absorbing Change
-states. An active Change may be revised. Archive requires complete current Task,
-Context, test, review, documentation, and delivery checkpoints, then performs a
-recoverable filesystem/DB transaction. Archived bytes remain immutable.
+states. An active Change may be revised. The Deliver Skill inspects the relevant Task,
+Context, test, review, documentation, and delivery evidence, decides semantic
+sufficiency, and records deliberate omissions. Archive validates the explicit handoff,
+current authority, reconciliation structure, and safe recoverable filesystem/DB
+transaction without enforcing a fixed stage sequence. Archived bytes remain immutable.
 
 Older `ready` or `blocked` rows are readable migration history. They do not authorize
 new work until migration/revalidation derives current checkpoint authority.
@@ -130,14 +141,18 @@ new work until migration/revalidation derives current checkpoint authority.
 Task durable outcomes remain portable:
 
 ```text
-pending -> completed
-   |
+pending -> in_progress -> completed
+   |          |              |
+   |          -> blocked     -> in_progress (explicit reopen)
    -> blocked
    -> cancelled
 ```
 
 `in_progress`, Worker ownership, leases, PIDs, heartbeats, worktrees, and completion
 commit backfill are checkout-local. They are not published to Git.
+Reopening a completed Task clears the local completion/session fields, preserves the
+prior completion commit in an append-only `task_reopened` event, and requires a new
+durable outcome before it can be completed again.
 
 `ultra.session acquire` atomically:
 
@@ -210,6 +225,6 @@ Only these classes fail the tool call:
 - permission failure;
 - archive/publish/deploy or another irreversible external-effect failure.
 
-Evidence gaps, incomplete exploration, stale optional context, missing reports, or a
-checkpoint that is not yet ready are structured diagnostics. The model remains free to
-investigate, revise, and retry.
+Evidence gaps, incomplete exploration, stale optional context, missing reports, or
+other semantic insufficiency are structured diagnostics. The model remains responsible
+for investigating, revising, accepting, or explicitly recording an omission.

package/hooks/health_check.py

@@ -73,26 +73,31 @@ def inspect(root: Path) -> dict:
 
             envelope = context.get("envelope", {}) if context else {}
             diagnostics = envelope.get("diagnostics", {})
-            baseline_codes = [
+            baseline_blockers = [
                 str(item.get("code"))
                 for item in [
                     *diagnostics.get("needs_attention", []),
-                    *diagnostics.get("warnings", []),
                     *diagnostics.get("hard_conflicts", []),
                 ]
                 if str(item.get("code", "")).startswith("BASELINE_")
             ]
+            baseline_warnings = [
+                str(item.get("code"))
+                for item in diagnostics.get("warnings", [])
+                if str(item.get("code", "")).startswith("BASELINE_")
+            ]
             baseline = envelope.get("baseline")
             baseline_is_ready = isinstance(baseline, dict) and baseline.get("status") == "ready"
             baseline_status = (
-                "fail" if baseline_codes and baseline_is_ready
-                else "warning" if baseline_codes
+                "fail" if baseline_blockers and baseline_is_ready
+                else "warning" if baseline_blockers or baseline_warnings
                 else "pass"
             )
             report["checks"]["baseline"] = {
                 "baseline": baseline,
-                "blockers": baseline_codes,
-                "readiness": "blocked" if baseline_codes else "ready",
+                "blockers": baseline_blockers,
+                "warnings": baseline_warnings,
+                "readiness": "blocked" if baseline_blockers else "ready",
                 "status": baseline_status,
             }
             if baseline_status == "fail":