ultra-builder-pro-cli 0.25.1 → 0.26.0

package/docs/STATE-DB-ACCESS-POLICY.md

@@ -1,161 +0,0 @@
-# `.ultra/.runtime/state.db` access policy
-
-> Multi-process access contract. Current authority is defined by
-> [`DECISIONS.md`](./DECISIONS.md) and the live database schema.
-
-`.ultra/.runtime/state.db` is the checkout-local persistence and safety authority for
-baselines, Changes, normalized Decision Records, Stage Checkpoints, Context Envelopes,
-Worker Packets, Tasks, events, Sessions, incidents, projections, telemetry, and spec
-references. Registered digest-bound files carry semantic and evidence
-bodies; the DB owns their references and current digests. The tracked
-`.ultra/tasks/tasks.json` is an MCP-published handoff checkpoint, not a parallel live
-writer. Every process that touches the DB must follow the rules below; deviations are
-bugs.
-
-## 1. Three-role write matrix
-
-| Role | tasks | baselines | change/workflow/artifact state | decisions | events | sessions | telemetry | specs_refs | migration_history |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| **MCP server** (single writer for mutables) | RW | RW | RW | RW | RW | RW | RW | RW | RW |
-| **CLI** (`ultra-tools …`) | R | RW (init only) | R | R | RW (append-only) | R | R | R | RW (migration only) |
-| **Orchestrator daemon** | R | R | R | R | RW | RW | RW | RW | R |
-
-- **R** = read-only;
-- **RW** = read + write;
-- A `(append-only)` qualifier means the role may execute `INSERT INTO`
-  but never `UPDATE` / `DELETE`.
-
-The CLI may indirectly mutate ordinary workflow tables by spawning the MCP server over
-stdio and calling the public `ultra.*` kernel — but the actual
-SQLite write is performed by the MCP server's writer connection. The documented
-exceptions are initial schema/baseline creation, migration, and explicitly
-authorized backup-first doctor recovery. The CLI never provides a parallel raw
-write API for normal task, change, session, or baseline lifecycle updates.
-
-The append-only carve-out for `events` exists because `events.id INTEGER
-PRIMARY KEY AUTOINCREMENT` makes concurrent inserts collision-free under
-WAL + `busy_timeout`. This lets hooks and short-lived CLI invocations
-record audit observations without paying the cost of a full MCP round trip.
-It does not grant lifecycle authority: external writers use the published observation
-allowlist, while lifecycle event
-names are emitted only inside the mutation that owns the corresponding state change.
-Consumers must verify mutable rows rather than infer success from an event name.
-Rejected semantic calls are recorded as `ultra_kernel_attempt` observations and shown
-by `ultra.context`; they do not create the rejected row or authorize a transition.
-
-## 2. Connection discipline
-
-Every process **must**:
-
-1. Open the database with WAL + `busy_timeout=5000` + `foreign_keys=ON`.
-   Use `mcp-server/lib/state-db.cjs` `openStateDb` so the pragmas are
-   applied uniformly.
-2. Wrap every mutable state operation with `state-ops.cjs` `tx(db, fn)`. The
-   helper calls better-sqlite3's immediate transaction variant, so the writer
-   lock is acquired before user code runs and the whole operation rolls back on
-   failure.
-3. Retry the complete transaction up to **10 attempts** on `SQLITE_BUSY`, using
-   decorrelated jitter from a 50 ms base with a 2 s cap. Never retry only a
-   suffix of a failed transaction or preserve partial state.
-4. Close the connection in a `finally` block. WAL files (`-wal`,
-   `-shm`) are reclaimed on the last writer's close.
-
-Reads never need explicit transactions; better-sqlite3 reads observe a
-consistent snapshot under WAL.
-
-## 3. WAL requirement
-
-WAL is part of the authority contract, not an optional performance setting.
-`openStateDb` asks SQLite to enable WAL and checks the actual returned mode. If
-the storage layer returns anything else, startup fails with
-`STATE_DB_WAL_UNAVAILABLE`. Ultra does not silently downgrade to a different
-concurrency model. Move `.ultra/.runtime/state.db` to storage that supports SQLite WAL or
-resolve the mount/runtime constraint before retrying.
-
-## 4. Where each table is owned
-
-| Table              | Writer of record                                      |
-|--------------------|--------------------------------------------------------|
-| `baselines`        | MCP server through `ultra.record`, `ultra.checkpoint`, and `ultra.archive`; initialization and legacy migration may create only the first draft or compatibility row |
-| `tasks`            | MCP server through `ultra.record`, `ultra.checkpoint`, and `ultra.sync` |
-| `changes`          | MCP server through `ultra.record`, `ultra.checkpoint`, and `ultra.archive` |
-| `decision_records` | MCP server through `ultra.record`; normalized accepted intent and applied references are stored, never UI receipts, prompts, or transcripts |
-| `stage_checkpoints` | MCP server through `ultra.checkpoint`; mutable drafts and immutable accepted/superseded revisions, never fixed reasoning steps |
-| `context_envelopes`, `worker_packets` | MCP server through `ultra.context`, `ultra.checkpoint`, and `ultra.session`; exact digest-bound handoff authority |
-| `decision_threads`, `decision_items`, `workflow_runs`, `workflow_steps` | read-only legacy history retained for migration and audit; no current public writer, invalidation mutation, or authorization role |
-| `artifacts`, `artifact_edges` | MCP server through `ultra.record` and checkpoint-owned registration |
-| `context_snapshots`, `spec_learning_candidates`, `trace_links` | MCP server through `ultra.record` and `ultra.checkpoint` |
-| `incidents`, `projection_jobs`, `event_consumers`, `circuit_breaker` | MCP server; backup-first doctor recovery may perform only documented mechanical transitions |
-| `events`           | MCP server for lifecycle events; approved processes and `ultra.record` for allowlisted append-only observations |
-| `sessions`         | MCP server through `ultra.session`; orchestrator may write status transitions |
-| `telemetry`        | MCP server (collected from tool-call wrappers); orchestrator may dump bulk samples |
-| `specs_refs`       | MCP server (rebuilt on `spec_changed` event); orchestrator may rebuild |
-| `migration_history`| schema initializer and `ultra-tools migrate` or doctor repair |
-| `schema_version`   | schema initializer, `ultra-tools db init`, migration, and doctor repair |
-
-## 5. Git team checkpoint
-
-Only `ultra.sync { action: publish }` may derive `.ultra/tasks/tasks.json` from SQLite,
-and only `ultra.sync { action: import }` may merge it into SQLite. Server startup performs one import after
-opening project authority; later pulls in a long-running process require an explicit
-import. The same checkpoint is idempotent and must not append an event again.
-
-The checkpoint carries portable baseline, Change, and durable task records with
-per-record revisions and digests. It excludes local `in_progress` ownership, sessions,
-leases, worktrees, telemetry, and completion commit hashes. Import validates document
-ancestry plus record-level common bases. It fast-forwards clean records and fails
-before commit on same-record concurrency, parent/owner gaps, non-descendant history, or
-an active-task collision. A Git-ready baseline is downgraded to checkout-local
-revalidation rather than trusted as execution authority.
-
-Legacy v4.4/v4.5 task projections are backed up and replaced only when every available
-durable field matches current SQLite. Doctor reports checkpoint condition but never
-performs semantic import, publication, or conflict selection.
-
-## 6. Forbidden patterns
-
-- **No file copies for state.** Don't `cp .ultra/.runtime/state.db
-  somewhere/state.db` and edit; use `ultra-tools db backup`.
-- **No direct checkpoint edits.** Don't merge or repair
-  `.ultra/tasks/tasks.json` by hand; use the typed import/publish conflict path.
-- **No committed live projections.** `.ultra/.runtime/projections/**` remains ignored
-  checkout-local output.
-- **No long-held writer connections** outside the MCP server. Pop a
-  short transaction, finish, close.
-- **No `PRAGMA journal_mode` toggling at runtime** by any process other
-  than the orchestrator's boot-time WAL detector.
-- **No raw SQL in command md files.** Commands call MCP tools or
-  `ultra-tools …` subcommands; the SQL lives in `mcp-server/lib`.
-- **No legacy authority mode switch.** Public Change callers use the single Kernel
-  facade. New workflow-owned artifacts and workflow/dialogue writes are rejected.
-- **No semantic meaning in projection metadata.** `_ultra.projection_commit` means
-  only that the generated-view job was durably enqueued and processed; acceptance is
-  read from the typed tool result and current authority.
-- **No `vacuum` / `wal_checkpoint(TRUNCATE)` from inside a transaction.**
-  Maintenance subcommands open their own connection.
-
-## 7. Maintenance windows
-
-`ultra-tools db checkpoint` and `ultra-tools db vacuum` are safe to run
-while the MCP server is up (they take their own connection and obey the
-busy timeout). `db backup` uses better-sqlite3's online `.backup` API
-and produces a consistent snapshot without blocking writers.
-
-## 8. Verification
-
-The contract on this page is enforced by:
-
-- `mcp-server/tests/concurrency.test.cjs` — three writer threads
-  appending to `events` simultaneously; asserts no `SQLITE_BUSY` escapes
-  the retry loop and the resulting `events.id` sequence has no gaps and
-  no duplicates.
-- `mcp-server/tests/state-ops.test.cjs` — immediate transactions, rollback,
-  status transitions, task contracts, and event coupling.
-- `mcp-server/lib/stage-checkpoints.test.cjs` — mutable drafts, immutable accepted
-  revisions, supersession, and report-first diagnostics.
-- `mcp-server/lib/context-envelope.test.cjs` and
-  `mcp-server/lib/worker-packet.test.cjs` — content-addressed Context and immutable
-  delegated handoff.
-- `mcp-server/lib/task-ledger.test.cjs` — portable-field filtering, digest ancestry,
-  idempotent import, baseline/Change/task fast-forward and conflict behavior, legacy
-  backup, and active-session protection.

package/hooks/active_task_context.py

@@ -1,152 +0,0 @@
-#!/usr/bin/env python3
-"""Protect managed task files and restate the live Ultra Context Envelope."""
-
-import json
-import sys
-from pathlib import Path
-
-from context_envelope import (
-    ContextEnvelopeError,
-    find_root,
-    read_context_envelope,
-    render_context_envelope,
-)
-
-TEAM_TASK_LEDGER = Path(".ultra/tasks/tasks.json")
-LIVE_TASK_PROJECTION = Path(".ultra/.runtime/projections/tasks.json")
-PROTECTED_TASK_FILES = (TEAM_TASK_LEDGER, LIVE_TASK_PROJECTION)
-
-
-def tool_paths(data: dict, start: Path):
-    """Yield absolute tool targets without assuming they belong to ``start``."""
-    tool_input = data.get("tool_input")
-    if not isinstance(tool_input, dict):
-        return
-    for key in ("file_path", "filePath", "filepath", "path"):
-        value = tool_input.get(key)
-        if not isinstance(value, str) or not value.strip():
-            continue
-        candidate = Path(value)
-        yield candidate.resolve() if candidate.is_absolute() else (start / candidate).resolve()
-
-
-def protected_root_for_target(target: Path) -> Path | None:
-    """Return the project root for an exact MCP-managed task file."""
-    parts = target.parts
-    for relative in PROTECTED_TASK_FILES:
-        suffix = relative.parts
-        if len(parts) >= len(suffix) and parts[-len(suffix):] == suffix:
-            return Path(*parts[:-len(suffix)])
-    return None
-
-
-def targets_managed_task_file(data: dict, root: Path) -> bool:
-    for resolved in tool_paths(data, root):
-        if any(resolved == (root / relative).resolve() for relative in PROTECTED_TASK_FILES):
-            return True
-    return False
-
-
-def managed_file_denial(reason: str) -> dict:
-    return {"hookSpecificOutput": {
-        "hookEventName": "PreToolUse",
-        "permissionDecision": "deny",
-        "permissionDecisionReason": reason,
-    }}
-
-
-def conflicted_managed_root(data: dict, start: Path) -> Path | None:
-    for candidate in (start, *start.parents):
-        if not (candidate / ".ultra").exists():
-            continue
-        if targets_managed_task_file(data, candidate):
-            return candidate
-    return None
-
-
-def managed_roots(data: dict, start: Path):
-    """Yield initialized project roots derived from every resolved tool target."""
-    for target in tool_paths(data, start):
-        root = protected_root_for_target(target)
-        if root is not None and (root / ".ultra").exists():
-            yield root
-
-
-def main() -> None:
-    try:
-        data = json.loads(sys.stdin.read() or "{}")
-        data = data if isinstance(data, dict) else {}
-    except json.JSONDecodeError as exc:
-        print(f"[active_task_context] invalid hook input: {exc}", file=sys.stderr)
-        data = {}
-    start = Path(data.get("cwd") or Path.cwd()).resolve()
-    # An absolute tool target carries its own project boundary. Resolve and
-    # protect that authority before consulting cwd, because hooks may run from
-    # a host-owned temporary directory or another repository.
-    for target_root in managed_roots(data, start):
-        try:
-            target_authority = find_root(target_root)
-        except ContextEnvelopeError as exc:
-            print(json.dumps(managed_file_denial(
-                "Refusing a direct write to an MCP-managed Ultra task file while the "
-                f"runtime authority is conflicted: {exc}. Resolve the "
-                "state.db conflict with ultra-doctor before retrying the owning "
-                "MCP operation."
-            )))
-            return
-        if target_authority is None:
-            continue
-        print(json.dumps(managed_file_denial(
-            "Refusing a direct write to an MCP-managed Ultra task file. "
-            ".ultra/tasks/tasks.json is the MCP-published team checkpoint and "
-            ".ultra/.runtime/projections/tasks.json is the checkout-local DB view. "
-            "Use ultra.record for task contracts/outcomes and ultra.sync for the team checkpoint."
-        )))
-        return
-
-    try:
-        root = find_root(start)
-    except ContextEnvelopeError as exc:
-        print(
-            f"[active_task_context] cannot resolve Ultra root: {exc}",
-            file=sys.stderr,
-        )
-        # Ordinary context injection remains fail-open. A direct write to a
-        # known managed task file is different: an authority conflict means the
-        # hook cannot prove which DB owns the publish or projection operation.
-        if conflicted_managed_root(data, start) is not None:
-            print(json.dumps(managed_file_denial(
-                "Refusing a direct write to an MCP-managed Ultra task file while the "
-                f"runtime authority is conflicted: {exc}. Resolve the "
-                "state.db conflict with ultra-doctor before retrying the owning "
-                "public Ultra operation."
-            )))
-            return
-        root = None
-    if root is None:
-        print(json.dumps({}))
-        return
-    if targets_managed_task_file(data, root):
-        print(json.dumps(managed_file_denial(
-                "Refusing a direct write to an MCP-managed Ultra task file. "
-                ".ultra/tasks/tasks.json is the MCP-published team checkpoint and "
-                ".ultra/.runtime/projections/tasks.json is the checkout-local DB view. "
-                "Use ultra.record for task contracts/outcomes and ultra.sync for the team checkpoint."
-        )))
-        return
-    try:
-        envelope = read_context_envelope(root)
-    except ContextEnvelopeError as exc:
-        print(f"[active_task_context] cannot inspect Context Envelope: {exc}", file=sys.stderr)
-        envelope = None
-    if envelope:
-        print(json.dumps({"hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "additionalContext": render_context_envelope(root, envelope),
-        }}))
-        return
-    print(json.dumps({}))
-
-
-if __name__ == "__main__":
-    main()

package/hooks/context_envelope.py

@@ -1,100 +0,0 @@
-#!/usr/bin/env python3
-"""Thin read-only bridge to the bundled Ultra Context Envelope reader."""
-
-import json
-import os
-import shutil
-import subprocess
-import sys
-from pathlib import Path
-
-from runtime_paths import RuntimePathError, find_project_root
-
-
-class ContextEnvelopeError(RuntimeError):
-    """The canonical Context Envelope helper could not be executed or decoded."""
-
-
-class ContextEnvelope(dict):
-    """Dictionary envelope carrying its canonical bounded injection text."""
-
-    def __init__(self, value: dict, rendered: str):
-        super().__init__(value)
-        self.rendered = rendered
-
-
-def find_root(start: Path):
-    try:
-        return find_project_root(start)
-    except RuntimePathError as exc:
-        raise ContextEnvelopeError(str(exc)) from exc
-
-
-def find_root_for_hook(start: Path, hook_name: str):
-    """Fail open at a hook boundary while preserving path-conflict evidence."""
-    try:
-        return find_root(start)
-    except ContextEnvelopeError as exc:
-        print(f"[{hook_name}] cannot resolve Ultra root: {exc}", file=sys.stderr)
-        return None
-
-
-def _helper_path() -> Path:
-    hook_root = Path(__file__).resolve().parent
-    installed = hook_root.parent / "runtime" / "hook-context.cjs"
-    if installed.is_file():
-        return installed
-    source = hook_root.parent / "mcp-server" / "hook-context.cjs"
-    if source.is_file():
-        return source
-    raise ContextEnvelopeError("bundled Context Envelope helper is missing")
-
-
-def _node_binary() -> str:
-    configured = os.environ.get("UBP_NODE")
-    if configured:
-        return configured
-    discovered = shutil.which("node")
-    if discovered:
-        return discovered
-    raise ContextEnvelopeError("node executable is unavailable")
-
-
-def read_context_envelope(root: Path):
-    try:
-        result = subprocess.run(
-            [_node_binary(), str(_helper_path()), str(root.resolve())],
-            text=True,
-            capture_output=True,
-            check=False,
-            timeout=5,
-        )
-    except (OSError, subprocess.TimeoutExpired) as exc:
-        raise ContextEnvelopeError(str(exc)) from exc
-    if result.returncode != 0:
-        detail = result.stderr.strip() or f"exit {result.returncode}"
-        raise ContextEnvelopeError(detail)
-    try:
-        payload = json.loads(result.stdout)
-    except json.JSONDecodeError as exc:
-        raise ContextEnvelopeError(f"invalid Context Envelope response: {exc}") from exc
-    if not isinstance(payload, dict):
-        raise ContextEnvelopeError("Context Envelope response must be an object")
-    value = payload.get("context")
-    if value is None:
-        return None
-    rendered = payload.get("text")
-    if not isinstance(value, dict) or not isinstance(rendered, str) or not rendered:
-        raise ContextEnvelopeError(
-            "Context Envelope response is missing canonical state or text"
-        )
-    return ContextEnvelope(value, rendered)
-
-
-def render_context_envelope(_root: Path, context: dict) -> str:
-    rendered = getattr(context, "rendered", None)
-    if not isinstance(rendered, str) or not rendered:
-        raise ContextEnvelopeError(
-            "Context Envelope was not produced by the canonical reader"
-        )
-    return rendered

package/hooks/health_check.py

@@ -1,196 +0,0 @@
-#!/usr/bin/env python3
-"""Fast, read-only Ultra runtime health inspection at session start."""
-
-import json
-import sqlite3
-import sys
-from pathlib import Path
-
-from context_envelope import (
-    ContextEnvelopeError,
-    find_root_for_hook,
-    read_context_envelope,
-)
-from runtime_paths import state_db_path
-
-
-REQUIRED_TABLES = {
-    "baselines",
-    "tasks", "events", "sessions", "schema_version", "migration_history",
-    "telemetry", "specs_refs", "circuit_breaker", "changes", "artifacts",
-    "artifact_edges", "context_snapshots", "spec_learning_candidates", "trace_links",
-    "incidents", "projection_jobs", "event_consumers", "stage_checkpoints",
-    "decision_records", "context_envelopes", "worker_packets",
-}
-
-
-def hook_input() -> dict:
-    try:
-        value = json.loads(sys.stdin.read() or "{}")
-        return value if isinstance(value, dict) else {}
-    except json.JSONDecodeError as exc:
-        print(f"[health_check] invalid hook input: {exc}", file=sys.stderr)
-        return {}
-
-
-def inspect(root: Path) -> dict:
-    db_path = state_db_path(root)
-    report = {"status": "healthy", "project": str(root), "checks": {}}
-    issues = []
-    if not db_path.is_file():
-        report["checks"]["state_db"] = {"status": "fail", "reason": "missing"}
-        report["status"] = "degraded"
-        return report
-
-    try:
-        context = read_context_envelope(root)
-    except ContextEnvelopeError as exc:
-        report["checks"]["authority"] = {"status": "fail", "reason": str(exc)}
-        report["status"] = "degraded"
-        return report
-
-    try:
-        uri = f"file:{db_path}?mode=ro"
-        with sqlite3.connect(uri, uri=True, timeout=1) as conn:
-            conn.row_factory = sqlite3.Row
-            quick = conn.execute("PRAGMA quick_check").fetchone()[0]
-            tables = {
-                row[0] for row in conn.execute(
-                    "SELECT name FROM sqlite_master WHERE type='table'"
-                )
-            }
-            missing = sorted(REQUIRED_TABLES - tables)
-            report["checks"]["state_db"] = {
-                "status": "pass" if quick == "ok" and not missing else "fail",
-                "integrity": quick,
-                "missing_tables": missing,
-            }
-            if quick != "ok" or missing:
-                issues.append("state_db")
-            if missing:
-                report["status"] = "degraded"
-                return report
-
-            envelope = context.get("envelope", {}) if context else {}
-            diagnostics = envelope.get("diagnostics", {})
-            baseline_blockers = [
-                str(item.get("code"))
-                for item in [
-                    *diagnostics.get("needs_attention", []),
-                    *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_blockers and baseline_is_ready
-                else "warning" if baseline_blockers or baseline_warnings
-                else "pass"
-            )
-            report["checks"]["baseline"] = {
-                "baseline": baseline,
-                "blockers": baseline_blockers,
-                "warnings": baseline_warnings,
-                "readiness": "blocked" if baseline_blockers else "ready",
-                "status": baseline_status,
-            }
-            if baseline_status == "fail":
-                issues.append("baseline")
-
-            incidents = [
-                {"id": row[0], "code": row[1], "severity": row[2], "retryable": bool(row[3])}
-                for row in conn.execute(
-                    """SELECT id, code, severity, retryable FROM incidents
-                       WHERE status = 'open' ORDER BY last_seen_at DESC LIMIT 20"""
-                )
-            ]
-            report["checks"]["incidents"] = {
-                "status": "pass" if not incidents else "fail",
-                "open": incidents,
-            }
-            if incidents:
-                issues.append("incidents")
-
-            pending = conn.execute(
-                "SELECT COUNT(*) FROM projection_jobs WHERE status = 'pending'"
-            ).fetchone()[0]
-            running = conn.execute(
-                "SELECT COUNT(*) FROM projection_jobs WHERE status = 'running'"
-            ).fetchone()[0]
-            failed = conn.execute(
-                "SELECT COUNT(*) FROM projection_jobs WHERE status = 'failed'"
-            ).fetchone()[0]
-            event_cursor = conn.execute(
-                "SELECT COALESCE(MAX(id), 0) FROM events"
-            ).fetchone()[0]
-            projected_cursor = conn.execute(
-                """SELECT COALESCE(MAX(event_cursor), 0) FROM projection_jobs
-                   WHERE status = 'completed'"""
-            ).fetchone()[0]
-            projection_ok = (
-                pending == 0 and running == 0 and failed == 0
-                and event_cursor <= projected_cursor
-            )
-            report["checks"]["projections"] = {
-                "status": "pass" if projection_ok else "fail",
-                "pending": pending,
-                "running": running,
-                "failed": failed,
-                "event_cursor": event_cursor,
-                "projected_cursor": projected_cursor,
-            }
-            if not projection_ok:
-                issues.append("projections")
-
-            orphan = conn.execute(
-                "SELECT COUNT(*) FROM sessions WHERE status = 'orphan'"
-            ).fetchone()[0]
-            report["checks"]["sessions"] = {
-                "status": "pass" if orphan == 0 else "fail", "orphan": orphan,
-            }
-            if orphan:
-                issues.append("sessions")
-
-            missing_artifacts = []
-            for change_id, artifact_root in conn.execute(
-                """SELECT id, artifact_root FROM changes
-                   WHERE status IN ('active', 'blocked', 'ready')"""
-            ):
-                if artifact_root and not (root / artifact_root).exists():
-                    missing_artifacts.append(change_id)
-            report["checks"]["change_artifacts"] = {
-                "status": "pass" if not missing_artifacts else "fail",
-                "missing": missing_artifacts,
-            }
-            if missing_artifacts:
-                issues.append("change_artifacts")
-    except sqlite3.Error as exc:
-        report["checks"]["state_db"] = {"status": "fail", "reason": str(exc)}
-        issues.append("state_db")
-
-    if issues:
-        report["status"] = "degraded"
-    return report
-
-
-def main() -> None:
-    data = hook_input()
-    start = Path(data.get("cwd") or Path.cwd()).resolve()
-    root = find_root_for_hook(start, "health_check")
-    if root is None:
-        print(json.dumps({}))
-        return
-    report = inspect(root)
-    if report["status"] != "healthy":
-        print("[Ultra health] " + json.dumps(report, ensure_ascii=False, sort_keys=True), file=sys.stderr)
-    print(json.dumps({}))
-
-
-if __name__ == "__main__":
-    main()

package/hooks/pre_stop_check.py

@@ -1,66 +0,0 @@
-#!/usr/bin/env python3
-"""Report unfinished DB-authoritative Ultra work without trapping session stop."""
-
-import json
-import sys
-from pathlib import Path
-
-from context_envelope import (
-    ContextEnvelopeError,
-    find_root_for_hook,
-    read_context_envelope,
-)
-
-
-def allow_stop() -> None:
-    print(json.dumps({}))
-
-
-def main() -> None:
-    try:
-        hook_data = json.loads(sys.stdin.read() or "{}")
-        hook_data = hook_data if isinstance(hook_data, dict) else {}
-    except json.JSONDecodeError as exc:
-        print(f"[pre_stop_check] invalid hook input: {exc}", file=sys.stderr)
-        allow_stop()
-        return
-
-    if hook_data.get("stop_hook_active", False):
-        allow_stop()
-        return
-    root = find_root_for_hook(
-        Path(hook_data.get("cwd") or Path.cwd()).resolve(),
-        "pre_stop_check",
-    )
-    if root is None:
-        allow_stop()
-        return
-    try:
-        context = read_context_envelope(root)
-    except ContextEnvelopeError as exc:
-        print(f"[pre_stop_check] cannot inspect Context Envelope: {exc}", file=sys.stderr)
-        allow_stop()
-        return
-    envelope = context.get("envelope", {}) if context else {}
-    change = envelope.get("change") or {}
-    task = envelope.get("task") or {}
-    if change.get("id") and change.get("status") not in ("archived", "cancelled"):
-        attention = envelope.get("diagnostics", {}).get("needs_attention", [])
-        warnings = envelope.get("diagnostics", {}).get("warnings", [])
-        codes = ", ".join(
-            str(item.get("code")) for item in [*attention, *warnings] if item.get("code")
-        ) or "none"
-        print(
-            "[Ultra stop advisory] Active Ultra change remains open: "
-            f"change={change['id']}, "
-            f"task={task.get('id') or 'none'}, "
-            f"stage={envelope.get('execution', {}).get('stage') or 'project'}, "
-            f"diagnostics={codes}. "
-            "Stop is allowed; read ultra.context before resuming or explicitly archive later.",
-            file=sys.stderr,
-        )
-    allow_stop()
-
-
-if __name__ == "__main__":
-    main()