ultra-builder-pro-cli 5.0.1 → 6.0.0

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -1,107 +1,19 @@
 # Plugin isolation contract
 
-Ultra Builder Pro owns a narrow install surface. Installation and discovery create no
-project authority. A public workflow becomes active only through an explicit owner
-entry or one mode covered by a currently valid Execution Grant; Hooks separately use
-the presence of `.ultra/` as their idle guard.
+UBP v6 installs one `ultra` Skill, its engine copy and a SessionStart observer for
+Claude Code or Codex. Installation does not authorize project work or external effects.
 
-## Owned surfaces
+The plugin never creates or rewrites the user's global `AGENTS.md` or `CLAUDE.md`.
+Repository guidance belongs to the repository. The host owns permissions and hook trust.
 
-Per host, Ultra may install:
+Installers replace and remove only managed plugin trees. They preserve unrelated host
+configuration and restore the previous managed installation if publication fails.
+`--config-dir` confines both plugin files and host registration sidecars to that directory;
+with `--all`, each host gets a separate child directory. Doctor is read-only.
 
-- exactly fourteen managed Skills;
-- the launcher, worker, Host profile, and launch-only profile assets below the managed
-  `ultra-delegate/scripts/` Skill directory;
-- exactly five hook scripts plus `_common.py` and any required wire adapter;
-- one native plugin manifest or entrypoint;
-- provenance and managed-ownership markers;
-- the host's native registry entry where required.
+SessionStart reads its input and project status, prints a reminder when `.ultra/spec.md`
+exists and `UBP_DRIVE` is not set, and always exits successfully. It writes no files and grants no authority.
 
-For one release cycle the package also owns thin `ubp delegate` launcher/worker
-compatibility imports. They execute the Skill-local implementation and contain no
-forked behavior.
-
-## Surfaces Ultra does not own
-
-Ultra must not create or rewrite:
-
-- global user instruction files such as `~/.codex/AGENTS.md` or
-  `~/.claude/CLAUDE.md`;
-- general memory, code-graph, browser, deployment, framework, or productivity assets;
-- user-defined commands, agents, plugins, hooks, or registry entries;
-- repository files outside `.ultra/` and `CONTEXT.md` unless the selected engineering
-  task itself authorizes them;
-- an Ultra database, server registration, semantic runtime, or daemon.
-
-## Installation lifecycle
-
-Install builds a complete staging tree, including the Skill-local delegation runtime,
-marks it managed, writes provenance, then atomically publishes it. An existing unmanaged
-target is never overwritten. Reinstall replaces only the managed tree. Doctor is
-read-only and reports runner reachability separately. Uninstall removes only assets
-whose ownership can be proven.
-
-Host-owned sidecars must resolve from the same isolation root as `--config-dir`. For
-Codex this includes both `plugins/ultra-builder-pro` and
-`.agents/plugins/marketplace.json`; sandbox installation must not touch the real home
-directory. Codex native registration runs with both `HOME` and `CODEX_HOME` set to that
-root. If registration fails, install restores the previous managed tree and marketplace,
-or removes every fresh partial artifact.
-
-When one invocation selects multiple hosts, the supplied path is a parent isolation
-root and each adapter receives `<path>/<runtime>`. Sharing one concrete config directory
-would collide host-native `skills/` and `plugins/` layouts.
-
-OpenCode installation may remove a specifically recognizable Ultra registration from
-an older release. It must preserve unrelated configuration and files.
-
-Before first install, each adapter records only the exact config files and directory
-shells that do not yet exist. Uninstall may prune those recorded paths only when they
-are still empty (or a zero-byte host-created file); it preserves every pre-existing,
-non-empty, modified, symlinked, or unowned path. Codex marketplace and Kimi registry
-files additionally remember whether Ultra created the registry itself, so an empty
-registry that existed before installation is retained.
-
-ZCode publishes one managed local marketplace whose nested plugin is activated through
-the host's documented `plugins.dirs` configuration. Install preserves unrelated ZCode
-configuration, and uninstall removes only Ultra's exact directory entry and restores
-the pre-install `plugins.enabled` value when that value has not since been changed by
-the owner.
-
-## Activation
-
-Public Skill modes are `explicit-entry`, `grant-continuable`, or read-only `router`.
-Explicit-entry modes activate only through the Host's owner-facing Skill surface.
-Grant-continuable modes may be model-selected only after the loaded Skill verifies the
-same active Change, valid grant, allowed effects, and material checkpoints. A router may
-diagnose read-only state only on explicit owner invocation and creates no continuation
-authority. Model-discipline Skills
-may be selected only as methods inside the current covered workflow.
-
-Host invocation metadata is a coarse discovery aid. It cannot express every per-mode
-boundary, so the in-Skill check remains mandatory and Hosts without an equivalent bit
-rely on discriminating descriptions plus that same check. A public Skill may transition
-to another only when a valid grant covers the exact next mode and effects, after showing
-the Route Card; otherwise it stops and recommends the explicit route. Installation does
-not create a grant, launch a workflow, or start background work. Hooks activate only
-through Host lifecycle registrations and retain their independent idle guard.
-
-## Idle behavior
-
-Every hook resolves the current project and checks for `.ultra/` before reading,
-writing, injecting context, or denying an effect. Without `.ultra/`, it emits no stdout,
-exits zero, and leaves the project untouched.
-
-The only hook denial is a named destructive shell effect in an active Ultra project.
-The denial identifies the protected effect and supplies an exact-command SHA-256
-authorization path. Additive protected-branch publication is an advisory observation
-because a portable hook cannot consume every host's trusted owner-approval receipt;
-history rewrites and branch deletion remain guarded. All other hook failures are
-fail-open diagnostics.
-
-## Project data boundary
-
-Canonical project data is owner-readable and Git-compatible. Derived hook, review, and
-delegation artifacts live only under ignored `.ultra/.runtime/`, `.ultra/progress/`, or
-`.ultra/reviews/`. Disabling or uninstalling Ultra leaves canonical project data intact
-and resumable by ordinary file reading.
+Project truth is `.ultra/spec.md`, `checks.json`, `plan.json`, `rulings.md`, the ledgers,
+records and Git. The engine computes progress; a hook's printed observation is not a new
+source of truth. `.ultra/.runtime/` is disposable execution data.

package/docs/examples/drive/claude-reviewer.sh

@@ -0,0 +1,53 @@
+#!/bin/sh
+# Headless Claude Code reviewer for `ubp drive --reviewer`, run once at the milestone gate.
+# The engine sets UBP_ROOT, UBP, UBP_DRIVE, UBP_MILESTONE and UBP_REVIEW (the review file to
+# write), and puts its own `ubp` first on PATH.
+# It runs with edits accepted and Bash allowed, without a sandbox: use it only on a
+# repository you are willing to let an agent change. Copy it and adjust before use.
+# Outward commands that cannot be undone are denied by Claude Code permission rules
+# (--disallowedTools below). Ceiling: they match command prefixes, so they stop `git push`
+# and compound forms (checked with claude -p on 2026-11-04) but not `git -C <dir> push`,
+# `git -c k=v push` or a push made inside a script; a mid-command rule like `git * push *`
+# would also deny every commit whose message says "push". The stronger guard is a work tree
+# with no push remote; add the deploy and release CLIs your project uses to the list.
+set -eu
+cd "$UBP_ROOT"
+PROMPT="# Mission: whole-branch review of milestone $UBP_MILESTONE
+
+Workspace: $UBP_ROOT (a Git repository). You wrote none of this milestone's code. If you
+need this project's engine, call it as \`eval \"\$UBP <args>\"\` (a plain \`ubp\` may be another
+install); \`ubp check\` and \`ubp gate\` write the ledger, so prefer running tests on a copy.
+
+Read: the milestone's requirements in .ultra/spec.md (the Direction and Interface sections
+too), the milestone's diff (from the commit that last changed .ultra/ledger/milestones.jsonl
+to HEAD), .ultra/ledger/plan-log.jsonl and .ultra/rulings.md since that commit, and the
+handoffs under .ultra/records/handoffs/. Then drive the product by hand through its real
+interface, and run the milestone's checks against deliberately broken copies of the code: make
+each copy in a temporary directory outside the repository, never in it. A check that passes on
+a broken copy is an acceptance gap. Run the checks once on an unmodified copy of HEAD too
+(\`git archive HEAD\`): a fix that lives only in a file Git ignores passes in the work tree.
+
+The Owner's rule is that a check that could be stronger never blocks. So a finding blocks only
+when the product, as HEAD builds it, breaks a requirement's \`Done when\` line or the
+Direction, or does something wrong that you can reproduce through its real interface. Wrong
+means it contradicts the text of the spec (a requirement, the Interface or the Direction),
+loses or corrupts data, crashes, or opens a security hole. An acceptance gap does not block
+once you have driven HEAD through its real interface on the input the broken copy got wrong
+and seen it behave correctly: quote what HEAD did, name the check that would close the gap
+under \"What must be said to the Owner\", and keep the verdict accept. If the latest earlier
+review of this milestone in .ultra/records/milestones/ (\`$UBP_MILESTONE-review-<n>.md\`) ends
+with \`Verdict: revise\`, also check each of its blocking findings and look for regressions.
+Quote an earlier verdict only inside a code fence.
+
+Write $UBP_REVIEW and nothing else in the repository (no commits, no other edits): a first
+line \`Reviewer: claude -p (${UBP_REVIEWER_MODEL:-opus}), fresh session\`, then the findings
+that block (each with its evidence, the \`Done when\` line, Direction or reproduction it rests
+on, and the layer it belongs to: L4 implementation, L2 design, L1 acceptance or requirements,
+L0 direction), then a section \"What must be said to the Owner\" with everything else, then
+exactly one line \`Verdict: accept\` (no finding blocks) or \`Verdict: revise\`. Stop every
+server you start by its PID."
+exec claude -p "$PROMPT" --model "${UBP_REVIEWER_MODEL:-opus}" --output-format json \
+  --setting-sources project --strict-mcp-config --disable-slash-commands \
+  --no-session-persistence --permission-mode acceptEdits \
+  --allowedTools "Bash,Read,Edit,Write,Glob,Grep" \
+  --disallowedTools "Bash(git push *)" "Bash(npm publish *)" "Bash(gh *)"

package/docs/examples/drive/claude-writer.sh

@@ -0,0 +1,43 @@
+#!/bin/sh
+# Headless Claude Code writer for `ubp drive --writer`. The engine sets UBP_ROOT, UBP_NODE,
+# UBP_BRIEF, UBP_ATTEMPT, UBP_DRIVE and UBP, and puts its own `ubp` first on PATH.
+# The writer sees the brief and the repository only, never the controller's conversation.
+# It runs with edits accepted and Bash allowed, without a sandbox: use it only on a
+# repository you are willing to let an agent change. Copy it and adjust before use.
+# Outward commands that cannot be undone are denied by Claude Code permission rules
+# (--disallowedTools below). Ceiling: they match command prefixes, so they stop `git push`
+# and compound forms (checked with claude -p on 2026-11-04) but not `git -C <dir> push`,
+# `git -c k=v push` or a push made inside a script; a mid-command rule like `git * push *`
+# would also deny every commit whose message says "push". The stronger guard is a work tree
+# with no push remote; add the deploy and release CLIs your project uses to the list.
+set -eu
+cd "$UBP_ROOT"
+PROMPT="# Mission: node $UBP_NODE (attempt $UBP_ATTEMPT)
+
+Workspace: $UBP_ROOT (a Git repository). You are the writer of one node. The brief below is
+everything you are given; the current code is in the repository.
+
+Call this project's engine as \`eval \"\$UBP <args>\"\` from the workspace (the current
+directory is the project root), for example \`eval \"\$UBP check C-1\"\`; a plain \`ubp\` may be
+another install. Below, \`ubp <args>\` means exactly that. Work test-first inside the node's
+scope. Run the \`ubp check\` line of the brief's rules for this node's checks until they are
+green; before \`ubp node done $UBP_NODE\`, also run \`ubp check\` (every stale check):
+invariants and checks that were green before must stay green. Red checks of other nodes or of later milestones are expected; leave them alone.
+
+Never edit .ultra/spec.md, .ultra/checks.json, .ultra/plan.json, .ultra/ledger/milestones.jsonl,
+.ultra/ledger/approvals.jsonl, .ultra/ledger/plan-log.jsonl or any check's test file, and never
+run \`ubp gate\`, \`ubp approve\` or \`ubp milestone close\`: if one of them looks wrong, stop and
+say so in .ultra/records/handoffs/$UBP_NODE.md. Write that handoff and commit it with the
+code; besides what the brief asks, say in it what you noticed and left unchanged and what
+behavior no check pins. Commit inside this repository only (local commits); leave the work tree clean; install
+nothing. Stop every server you start by its PID, never with a pattern-based kill, and keep
+data files in a temp directory outside the repository. Finish with \`ubp node done $UBP_NODE\`.
+
+---
+
+$(cat "$UBP_BRIEF")"
+exec claude -p "$PROMPT" --model "${UBP_WRITER_MODEL:-sonnet}" --output-format json \
+  --setting-sources project --strict-mcp-config --disable-slash-commands \
+  --no-session-persistence --permission-mode acceptEdits \
+  --allowedTools "Bash,Read,Edit,Write,Glob,Grep" \
+  --disallowedTools "Bash(git push *)" "Bash(npm publish *)" "Bash(gh *)"