ultra-builder-pro-cli 0.26.2 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/.ultra-template/contexts/TEMPLATE.md +70 -29
  2. package/.ultra-template/north-star.md +35 -18
  3. package/.ultra-template/tasks.json +1 -0
  4. package/.ultra-template/test-report.json +17 -1
  5. package/CHANGELOG.md +235 -1
  6. package/README.md +210 -50
  7. package/README.zh-CN.md +440 -0
  8. package/adapters/_shared/host-profile.cjs +3 -95
  9. package/adapters/_shared/plugin-core.cjs +61 -5
  10. package/adapters/_shared/runtime-assets.cjs +66 -5
  11. package/adapters/zcode.js +375 -0
  12. package/bin/delegate-worker.cjs +2 -325
  13. package/bin/delegate.cjs +3 -461
  14. package/bin/install.js +11 -6
  15. package/docs/ARCHITECTURE.md +133 -31
  16. package/docs/ARTIFACT-AUTHORITY.md +185 -24
  17. package/docs/DECISIONS.md +153 -18
  18. package/docs/PHILOSOPHY.md +58 -7
  19. package/docs/PLUGIN-ISOLATION-CONTRACT.md +34 -12
  20. package/docs/RUNTIME-COMPAT-MATRIX.md +195 -23
  21. package/docs/SKILL-AUTHORING.md +19 -6
  22. package/docs/WORKFLOW-LIFECYCLE.md +196 -44
  23. package/docs/evals/adversarial-review-2026-08-14.md +84 -0
  24. package/docs/evals/ultra-5-0-journey-results.md +62 -0
  25. package/docs/evals/ultra-5-0-live-acp-conformance.md +93 -0
  26. package/docs/evals/ultra-5-0-route-journeys.md +145 -0
  27. package/docs/evals/zcode-automation-2026-08-14.md +103 -0
  28. package/hooks/README.md +27 -4
  29. package/hooks/_common.py +1678 -61
  30. package/hooks/adapters/zcode.py +227 -0
  31. package/hooks/compact_context.py +176 -17
  32. package/hooks/mid_workflow_recall.py +27 -5
  33. package/hooks/post_edit_guard.py +133 -23
  34. package/hooks/session_context.py +707 -22
  35. package/package.json +7 -3
  36. package/skills/ultra-change/SKILL.md +69 -12
  37. package/skills/ultra-change/references/change-contract.md +93 -27
  38. package/skills/ultra-change/references/execution-grant.md +109 -0
  39. package/skills/ultra-change/references/primary-transfer.md +273 -0
  40. package/skills/ultra-change/scripts/validate_primary_transfer.cjs +1928 -0
  41. package/skills/ultra-delegate/SKILL.md +103 -8
  42. package/skills/ultra-delegate/patches/zcode-acp-0.1.0-zcode-0.16.5.patch +184 -0
  43. package/skills/ultra-delegate/references/delegation-contract.md +80 -1
  44. package/skills/ultra-delegate/scripts/acp-conformance.cjs +287 -0
  45. package/skills/ultra-delegate/scripts/acp-driver.cjs +762 -0
  46. package/skills/ultra-delegate/scripts/agent-execution-driver.cjs +320 -0
  47. package/skills/ultra-delegate/scripts/cli-driver.cjs +61 -0
  48. package/skills/ultra-delegate/scripts/delegate-worker.cjs +328 -0
  49. package/skills/ultra-delegate/scripts/delegate.cjs +690 -0
  50. package/skills/ultra-delegate/scripts/host-profile.cjs +267 -0
  51. package/skills/ultra-deliver/SKILL.md +98 -11
  52. package/skills/ultra-dev/SKILL.md +188 -42
  53. package/skills/ultra-grilling/SKILL.md +10 -7
  54. package/skills/ultra-grilling/references/reframing.md +7 -3
  55. package/skills/ultra-init/SKILL.md +56 -7
  56. package/skills/ultra-init/scripts/init_project.cjs +968 -21
  57. package/skills/ultra-plan/SKILL.md +91 -47
  58. package/skills/ultra-plan/references/task-evidence-v2.md +300 -0
  59. package/skills/ultra-plan/scripts/validate_task_evidence.cjs +859 -0
  60. package/skills/ultra-research/SKILL.md +70 -14
  61. package/skills/ultra-research/references/04-product-strategy.md +11 -2
  62. package/skills/ultra-research/references/21-features-scope.md +8 -0
  63. package/skills/ultra-research/references/22-success-metrics.md +4 -3
  64. package/skills/ultra-research/references/99-synthesis.md +19 -2
  65. package/skills/ultra-research/references/north-star-v2.md +168 -0
  66. package/skills/ultra-research/references/wayfinding.md +8 -0
  67. package/skills/ultra-research/scripts/validate_north_star.cjs +1174 -0
  68. package/skills/ultra-review/SKILL.md +201 -27
  69. package/skills/ultra-review/references/adversarial-evaluation.md +31 -0
  70. package/skills/ultra-review/references/spec.md +5 -0
  71. package/skills/ultra-review/references/unified-schema.md +146 -11
  72. package/skills/ultra-review/references/worker-packet.md +151 -8
  73. package/skills/ultra-review/scripts/review_wait.py +2653 -63
  74. package/skills/ultra-status/SKILL.md +129 -15
  75. package/skills/ultra-status/references/route-contract.md +100 -0
  76. package/skills/ultra-tdd/SKILL.md +11 -4
  77. package/skills/ultra-tdd/references/test-execution.md +6 -1
  78. package/skills/ultra-test/SKILL.md +161 -18
  79. package/skills/ultra-test/scripts/validate_review_transport.cjs +549 -0
  80. package/skills/ultra-test/scripts/worktree_digest.cjs +518 -30
  81. /package/{adapters/_shared → skills/ultra-delegate/scripts}/delegate-profiles/kimi-read-only.md +0 -0
  82. /package/{adapters/_shared → skills/ultra-delegate/scripts}/delegate-profiles/kimi-write.md +0 -0
package/docs/DECISIONS.md CHANGED
@@ -1,8 +1,66 @@
1
- # Ultra Builder Pro v0.26 decisions
1
+ # Ultra Builder Pro decisions
2
2
 
3
3
  This file records durable product-level decisions that explain the current source tree.
4
4
  Project decisions created by Ultra belong in each project's `.ultra/decisions/`.
5
5
 
6
+ ## Ultra Core Protocol (3.0, accepted 2026-08-17; r3 revision same day)
7
+
8
+ The owner accepted `docs/ULTRA-BUILDER-PRO-3.0.zh-CN.md` and projected it as North
9
+ Star revision `north-star-v2-r2`
10
+ (`.ultra/decisions/2026-08-17-ultra-3-0-north-star-r2.md`), then converged the
11
+ constitution with the owner-directed r3 design
12
+ (`docs/ULTRA-BUILDER-PRO-3.0-NORTH-STAR-R3.zh-CN.md`) as revision
13
+ `north-star-v2-r3`
14
+ (`.ultra/decisions/2026-08-17-ultra-3-0-north-star-r3.md`). Ultra Builder Pro is
15
+ the file-first, provider-neutral Ultra Core Protocol: cognitive alignment through
16
+ checkpoints, per-fact canonical authority, explicit dual-mode authorization, typed
17
+ evidence with recovery, exclusive verified Agent handover, and review convergence
18
+ bounded by an owner-visible budget. The constitution itself stays count-free —
19
+ agent counts and topology detail, Host and Skill counts, provider names, and
20
+ exact review-round numbers live in the versioned product contract and exact
21
+ work-package grants. Authorization has two
22
+ modes — `session-local` by default, `durable work-package` when the owner issues an
23
+ exact grant (see `.ultra/decisions/2026-08-17-ultra-builder-pro-3.0-mode-b.md`); no
24
+ file, status, Hook, or Resume note ever implies activation. Optional Graph/Loop
25
+ coordination layers own observations only and none is integrated.
26
+
27
+ ## Ultra 5.0 workflow projection (accepted 2026-08-25)
28
+
29
+ The owner accepted the 5.0 scope and interaction boundary in
30
+ `.ultra/decisions/2026-08-25-ultra-5-0-scope.md`; the versioned contract is
31
+ `docs/ULTRA-BUILDER-PRO-5.0.zh-CN.md`. One shared Route Contract projects the existing
32
+ owner-checkpoint semantics into every public Skill without adding route state. Research
33
+ has explicit baseline and grant-continuable Change-scoped modes; Change makes
34
+ intake/evidence/reconcile/accepted visible and permits only same-Change non-material
35
+ reconciliation under a valid grant; Plan returns product evidence gaps through Change.
36
+ Host invocation bits remain coarse discovery metadata and every Skill rechecks mode,
37
+ grant, effects, and material checkpoints. Team Pack, remote shared assets, a semantic
38
+ state machine, daemon, and resident ACP service remain outside 5.0.
39
+
40
+ ## Primary transfer between Agents (r3, accepted 2026-08-17)
41
+
42
+ A work package's canonical writer moves to another Agent only through an
43
+ owner-granted primary transfer: the sender writes current reality into the task
44
+ context and Resume Note, derives an OFFER binding canonical refs/hashes, HEAD,
45
+ and the worktree digest, and stops writing after the receiver's ready ACK; the
46
+ receiver stable-reads, verifies every digest, becomes the sole canonical writer,
47
+ and freezes a terminal RESULT. Receipts under `.ultra/.runtime/handoffs/` are
48
+ derived and rebuildable, never authority; mismatches block instead of
49
+ auto-repairing; delegated workers stay mutually exclusive with this path and
50
+ never write canonical `.ultra`
51
+ (`.ultra/decisions/2026-08-17-ultra-3-0-r3-primary-handoff.md`,
52
+ `skills/ultra-change/references/primary-transfer.md`).
53
+
54
+ ## ZCode headless transport stays experimental (r3, accepted 2026-08-17)
55
+
56
+ The ZCode app-bundled CLI is a verified-local surface — it exists, launches, and
57
+ passed local drills — but the provider publishes no headless CLI, SDK, or
58
+ protocol stability contract. Its transport maturity is recorded `experimental`
59
+ in the shared host profile and compatibility matrix; promotion to `supported`
60
+ requires both official documentation and a full recovery drill. Interactive
61
+ Desktop use and the documented plugin surface are unaffected, and no adapter may
62
+ pass an app-internal binary off as an official stable interface.
63
+
6
64
  ## File-first authority
7
65
 
8
66
  Owner-readable repository files and Git are the complete semantic authority. Ultra
@@ -13,14 +71,58 @@ ownership of route and meaning.
13
71
 
14
72
  ## Three Skill roles
15
73
 
16
- The product exposes eight owner-invoked workflows, five model-invoked disciplines, and
17
- one router. Public workflows require explicit owner selection. A public workflow may
18
- recommend but never launch another public workflow. A model discipline needs at least
19
- two canonical callers or it is inlined.
74
+ The product exposes eight owner-invocable public workflows, five model-invoked
75
+ disciplines, and one router. Public modes are `explicit-entry` or
76
+ `grant-continuable`. Scoped Research, same-Change reconciliation, Plan, Dev, Test, and
77
+ Deliver reconciliation may be selected under an activated Change-scoped execution
78
+ grant — session-local activation in the current conversation, or a stably verified
79
+ durable work-package grant. All other public modes stay explicit-entry; Status stays
80
+ owner-invoked and read-only. A model discipline needs at least two canonical callers or it is inlined.
20
81
 
21
82
  This keeps reusable reasoning in one place without turning it into another user-facing
22
83
  route or custom-agent registry.
23
84
 
85
+ ## Bounded same-session continuation
86
+
87
+ The stored grant text is descriptive authority, not an executable grant. Session-local
88
+ activation is a current owner utterance approving the exact grant and current task
89
+ ledger; a durable work-package grant is executable only after a fresh Agent stably
90
+ verifies its recorded subject, scope, topology, effects, budgets, expiry, revocation,
91
+ and invalidation. A fresh session without a durable grant, host change, lost
92
+ activation context, semantic stop, or budget ceiling pauses
93
+ the loop. Plan, task, and aggregate reviews remain mandatory. Delivery continuation is
94
+ reconcile-only; finalization, archive, authenticated providers, install, commit, push,
95
+ publish, and deploy remain separately authorized.
96
+
97
+ The native host model-tool loop performs the work. Existing files and Git carry
98
+ recovery; no route position, daemon, or extra semantic store is introduced.
99
+
100
+ ## Review topology is owner-selected
101
+
102
+ The owner chooses reviewer and provider count for each stage. The default is one reviewer:
103
+ the current Agent. An initial task review selects `review-spec` plus the
104
+ lenses justified by risk and touched seams; a delta review reruns only affected
105
+ lenses; an aggregate Change review may default to the full roster only when cross-task
106
+ wiring justifies it — never as a mandatory count or a quality proxy. Specification
107
+ fidelity owns both accepted-behavior mapping and the challenge to a Change's claimed
108
+ North Star contribution, with actual execution mode and coverage recorded. When
109
+ another model family is available, a blind premise challenger is an additional probe
110
+ rather than a voting lens.
111
+
112
+ The seeded 2026-08-14 evaluation found no consequential defect class uniquely caught
113
+ by a permanent premise lens: the strengthened specification lens, the six-concern Kimi
114
+ probe, and the ZCode specification probe each found all five hidden classes. Grok's
115
+ malformed terminal output was rejected and was not counted as semantic evidence. See
116
+ `docs/evals/adversarial-review-2026-08-14.md`.
117
+
118
+ ## ZCode activation uses documented plugin directories
119
+
120
+ ZCode receives a managed local marketplace for importability and a documented
121
+ `plugins.dirs` entry for immediate native discovery. Ultra owns only the entry it adds,
122
+ so reinstall is idempotent and uninstall preserves unrelated user configuration. It
123
+ does not write ZCode's private plugin cache or copy desktop provider credentials into
124
+ headless CLI configuration.
125
+
24
126
  ## Intake, baseline, and delta
25
127
 
26
128
  Init preserves raw owner intake in the Project Brief; Research establishes the accepted North Star, domain language, and specification baseline; Change reconciles only the sections touched by one requested delta.
@@ -47,14 +149,41 @@ Directory position and explicit fields record mechanically checkable facts. The
47
149
  model reads those facts and chooses the next route. There is no persisted “current
48
150
  workflow stage” whose value can override the actual files.
49
151
 
50
- Task status is written to both the ledger and context, then read back. Tasks retain a
51
- stable `change_id` in an append-only ledger; current readers select only rows matching
52
- the one active Change. Archive or abandonment is a `git mv`. Test-report freshness
53
- compares Change id, current task ids, intent digest, `git_commit`, and product-worktree
54
- digest with the current checkout. Deliver reconciles first and finalizes only while
55
- that complete snapshot remains current. A separate request cannot create a second
56
- active Change; it waits, exits the current Change, or is explicitly reconciled into the
57
- same id.
152
+ The `UBP Route Card` is the owner-visible projection of those facts: it adds Route,
153
+ Mode, Position, and Exit condition around the eight accepted checkpoint semantics. It
154
+ is derived at public boundaries, has no canonical path, and provides neither completion
155
+ nor continuation authority.
156
+
157
+ Task status lives only in the `ultra-task-ledger-v2` row and is read back there. New task
158
+ contexts do not duplicate it; legacy context Status and Complexity fields remain
159
+ migration diagnostics and the ledger wins. Tasks retain a stable `change_id` in the
160
+ append-only ledger; current readers select only rows matching the one active Change.
161
+ Archive or abandonment is a `git mv`. Test-report freshness is governed normatively by the complete v2 rule in [Artifact Authority](ARTIFACT-AUTHORITY.md#evidence-promotion).
162
+ That authority binds the current Change snapshot, ordered v2 task-evidence identities,
163
+ and strict aggregate-review packet, admission, subject, and summary bindings. This
164
+ decision intentionally does not maintain a second field mirror. Deliver reconciles
165
+ first and finalizes only while that complete snapshot remains current. A separate
166
+ request cannot create a second active Change; it waits, exits the current Change, or is
167
+ explicitly reconciled into the same id.
168
+
169
+ ## Typed task evidence and completion ordering
170
+
171
+ Current work uses `ultra-task-evidence-v2`. Command, inspection, owner-judgment, and
172
+ external-observation evidence retain distinct authorities; the owner alone can supply
173
+ an owner-judgment result. Structural validators report exact fields, identities,
174
+ digests, provenance, and freshness, never semantic acceptance. A task remains
175
+ `in_progress` through its task review. Blocking findings and their dispositions are
176
+ recorded and affected evidence is refreshed before the primary model writes
177
+ `completed` to the ledger. Historical v1 evidence remains readable but cannot satisfy a
178
+ current Change's Test or Deliver input without migration.
179
+
180
+ ## Counts are observations, not semantic gates
181
+
182
+ Task, file, line, context, question, finding, repair-round, and complexity counts do not
183
+ decide plan quality, review convergence, staleness, or completion. The model interprets
184
+ concrete coupling, evidence, risk, and recovery facts. Explicit physical ceilings such
185
+ as time, bytes, cost, provider spend, or bounded process resources still stop resource
186
+ consumption and return a typed recovery path; exhaustion never dispositions a finding.
58
187
 
59
188
  ## Three independent integration defences
60
189
 
@@ -75,11 +204,17 @@ their repair is authorization scoped to the exact command digest.
75
204
 
76
205
  ## Delegation is a process boundary
77
206
 
78
- `ubp delegate run` starts a supported CLI with an immutable instruction, explicit
79
- permission JSON, and named worktree. Files are the cross-host state. The parent reads a
80
- stable terminal result instead of worker chatter. Delegation adds no semantic store and
81
- no authority. The instruction selects task execution, scoped Research evidence, or
82
- aggregate Change review/verification; only task execution requires a task row.
207
+ The installed `ultra-delegate/scripts/delegate.cjs` starts a supported CLI with an
208
+ immutable instruction, explicit permission JSON, and named worktree. Its exact
209
+ digest-bound sources are embedded in
210
+ the worker prompt because some native sandboxes correctly deny reads outside the
211
+ worktree. Files remain the cross-host state; the embedded copy is transport, not another
212
+ authority. The parent reads a stable terminal result instead of worker chatter. The
213
+ package `ubp delegate` surface is a one-release compatibility import of that same
214
+ launcher, not a second implementation or a runtime installation requirement.
215
+ Delegation adds no semantic store and no authority. The instruction selects task
216
+ execution, scoped Research evidence, or aggregate Change review/verification; only task
217
+ execution requires a task row.
83
218
 
84
219
  ## Installation isolation
85
220
 
@@ -45,10 +45,36 @@ one or more.
45
45
 
46
46
  The agent never stops seeing the current steering contract. Before Research accepts a
47
47
  baseline, the session Hook injects the raw Project Brief fallback. After Research, it
48
- injects the accepted North Star: Project Direction, any settled North Star Outcome, and
49
- Hard Constraints. Current task acceptance is appended in both cases. The cost of
48
+ requires the exact field ``- Status: `accepted``` and injects the accepted North Star v2 `## Problem Reality`,
49
+ `## First-Principle Propositions`, `## North Star Outcomes`, and `## Hard Constraints`.
50
+ The complete selected sections have a 32 KiB SessionStart ceiling. Above it, the Hook
51
+ uses a reference-only fallback containing the canonical path, immutable accepted snapshot
52
+ path, revision, status, exact validated SHA-256 and byte length, and a direct-read
53
+ instruction that rejects different bytes as authority; semantic truncation is forbidden.
54
+ Brownfield fallback still reads the actual v0.26 `## Project Direction`, `## North Star
55
+ Outcome`, and `## Hard Constraints` shape, or the older `## One-line` shape, without
56
+ misreporting either as v2. Current task acceptance is appended in every case. The cost of
50
57
  repetition is always less than the cost of drift.
51
58
 
59
+ The publication choice is exact: inject a mechanically bound accepted North Star, otherwise use the Project Brief fallback or a recognized legacy shape.
60
+ When selected accepted sections exceed 32 KiB, use the reference-only path instead of
61
+ semantic truncation. A v2 file whose decision, digest, or immutable snapshot binding is
62
+ invalid is never labelled accepted session authority.
63
+ The Hook does not maintain a second accepted-publication grammar. It safely locates the
64
+ installed sibling Research validator and invokes that one JavaScript report through a
65
+ bounded argv-only subprocess. Missing Node.js, a missing validator, timeout, malformed or
66
+ oversized output, invalid UTF-8, and repository path escape all produce a typed repair
67
+ fallback rather than accepted authority. The report checks the complete mechanical
68
+ structure; it does not decide whether the accepted semantics are true or valuable.
69
+ North Star and Project Brief ingress share one bounded 8 MiB regular-file snapshot:
70
+ repository root, parent components, and file identity are recorded, symlink components
71
+ are rejected, and the canonical root-to-file chain is freshly reopened after the read.
72
+ Every accepted, reference-only, legacy, or Project Brief publication consumes only those
73
+ captured bytes. An unavailable Project Brief produces a typed repair note and is never
74
+ reread through an unbounded path API. This detects ordinary cooperative-workspace drift;
75
+ it is not a claim that a process can prevent malicious operating-system-level replacement.
76
+ The v0.26 legacy branch recognizes headings `## Project Direction`, `## North Star Outcome`, `## Hard Constraints` exactly.
77
+
52
78
  > **Test**: pick a random in-progress task, ask the agent "what's the acceptance criteria?" — if
53
79
  > it cannot answer in one sentence, this commandment is broken.
54
80
 
@@ -90,6 +116,30 @@ The agent always knows "how far from done." Each edit updates `.ultra/progress/<
90
116
  with evidence completeness across six dimensions. Final-gate audits are forbidden — if a gap
91
117
  matters at the end, it matters mid-flight.
92
118
 
119
+ Canonical task evidence uses `ultra-task-evidence-v2`: command, inspection,
120
+ owner-judgment, and external-observation retain distinct authorities, while the six
121
+ dimensions remain independent observations. The owner alone supplies an
122
+ owner-judgment result. Validators may check structure, identity, provenance, freshness,
123
+ and exact references; they never decide semantic acceptance. `.ultra/tasks.json` is the
124
+ sole task-status authority. A task remains `in_progress` through task review and becomes
125
+ `completed` only after blocking findings are resolved or authoritatively dispositioned
126
+ and affected evidence is refreshed. First-review admission uses the ledger, task
127
+ context, immutable packet, and actual pre-review evidence; the one final v2 record is
128
+ published only after its final review summary validates. Its `subject` is an independently
129
+ captured completion-snapshot freshness observation made after that validation and
130
+ immediately before evidence publication. Its `task_review` separately binds the retained strict summary; the summary does not prove the subject worktree digest. Aggregate Test
131
+ recomputes each command or external receipt's bounded stable bytes against
132
+ `raw_evidence_sha256`, then recomputes the exact record `evidence_digest`. The
133
+ product-worktree digest excludes `.ultra/evidence/**`; these separate raw and record
134
+ bindings make publication non-self-referential without making it invisible.
135
+ Aggregate Test
136
+ separately binds the current whole Change and rechecks current Acceptance, criterion and
137
+ verification type, review summary, owner record, and cited-artifact evidence. If later work
138
+ invalidates a completed task, Dev records affected criteria and reason in Change Log
139
+ and Resume Note before the explicit ledger `completed` to `in_progress` transition;
140
+ there is no silent demotion. Legacy context Status/Complexity and v1 evidence remain
141
+ honest migration diagnostics, not alternative truth.
142
+
93
143
  > **Scoped exception**: whole-system wiring audit (`ultra-test`) is necessarily terminal, because
94
144
  > "this export has no non-test importer" cannot be evaluated while later tasks are still pending.
95
145
  > It is a terminal **sensor**, never a gate: it reports and hands the trade-off to the owner.
@@ -187,15 +237,16 @@ Skill instruction. Do not touch it casually.
187
237
 
188
238
  | Consumer | Reads | Source of truth | Failure mode if drifted |
189
239
  |---|---|---|---|
190
- | `session_context` | North Star headings `## Project Direction`, `## North Star Outcome`, `## Hard Constraints`; Project Brief `## One-line`, or legacy North Star `## One-line` | `.ultra-template/north-star.md`, `.ultra-template/project-brief.md`, and the Hook's legacy-read branch | SessionStart shows no accepted North Star or Project Brief fallback; C1 dies |
191
- | `session_context` | unique active `change_id` → one matching `in_progress` task, else first dependency-ready `pending` task → its context | active Change directory plus `tasks.json[].change_id`, dependencies, status, and `context_file` | abandoned or blocked acceptance is injected, or current acceptance never surfaces |
240
+ | `session_context` | the canonical JavaScript North Star validation report; bound accepted v2 sections or the 32 KiB immutable-snapshot reference with exact validated SHA-256 and byte length, without semantic truncation; Project Brief `## One-line`; actual v0.26 `## Project Direction` / `## North Star Outcome` / `## Hard Constraints`; or older North Star `## One-line` | `skills/ultra-research/scripts/validate_north_star.cjs`, `.ultra-template/north-star.md`, `.ultra-template/project-brief.md`, accepted `.ultra/north-star.md`, its owner decision and immutable snapshot, and the validator's two legacy-read shapes | Python and JavaScript publication grammars diverge, SessionStart labels unbound or different bytes accepted, truncates steering semantics, or shows no honest Project Brief/legacy fallback; C1 dies |
241
+ | `session_context` | unique active `change_id` → one matching ledger `in_progress` task, else first dependency-ready ledger `pending` task → its context; legacy context Status/Complexity are diagnostics only | active Change directory plus `tasks.json[].change_id`, dependencies, sole status, and `context_file` | abandoned or blocked acceptance is injected, a legacy context overrides the ledger, or current acceptance never surfaces |
192
242
  | `mid_workflow_recall` | heading `## Acceptance Criteria` | `.ultra-template/contexts/TEMPLATE.md` | hook injects nothing; C1 dies silently |
193
243
  | `ultra-tdd` | path `references/templates/*` | `skills/ultra-tdd/references/templates/` | guidance points at a missing runnable alternative; C2 dies |
194
- | `post_edit_guard` | writes `.ultra/progress/<task-id>.json` for the active Change's current task | active Change directory plus `tasks.json[].change_id` and `id`, created on demand | historical work receives current observations; C4 weakens |
195
- | `ultra-dev` and `post_edit_guard` | 6 keys: `tests_written`, `tests_passed`, `persistence_real`, `feature_flags_audit`, `vertical_slice`, `spec_trace` | the six-dimension table in `skills/ultra-dev/SKILL.md` | sensor and workflow report different evidence |
244
+ | `post_edit_guard` | writes `.ultra/progress/<task-id>.json` for the active Change's current ledger task | active Change directory plus `tasks.json[].change_id`, `id`, and sole `status`, created on demand | historical work receives current observations or a Hook invents completion; C4 weakens |
245
+ | `ultra-dev` and `post_edit_guard` | 6 keys: `tests_written`, `tests_passed`, `persistence_real`, `feature_flags_audit`, `vertical_slice`, `spec_trace` | the six-dimension table in `skills/ultra-dev/SKILL.md` and typed evidence contract in `skills/ultra-plan/references/task-evidence-v2.md` | sensor and workflow report different evidence or a progress observation becomes semantic acceptance |
246
+ | plan/dev/review/test/deliver | ledger status; actual pre-review inputs; one final `ultra-task-evidence-v2` carrying an independent completion-snapshot freshness observation and separate task-review provenance; aggregate Test identity | `.ultra/tasks.json`, task context, immutable Review artifacts, and `skills/ultra-plan/references/task-evidence-v2.md` | first review requires its own final output, context becomes a second status authority, review provenance is claimed to prove the independent subject, task subject is rebound to a later aggregate worktree, or invalid evidence is silently demoted |
196
247
  | planning and status | marker `[NEEDS CLARIFICATION]` | `.ultra-template/specs/*.md` | unresolved product truth is hidden |
197
248
  | `ultra-plan` / `ultra-dev` / hooks | `trace_to` form `.ultra/specs/file.md#anchor` | `tasks.json[].trace_to` + GFM heading slugify | traces appear resolved when their heading is absent |
198
- | `ultra-deliver` / `ultra-status` | fields `change_id`, `task_ids`, `intent_digest`, `git_commit`, and `worktree.diff_digest` | `.ultra/test-report.json` plus `worktree_digest.cjs` | stale Change, intent, task set, or product results pass as current |
249
+ | `ultra-deliver` / `ultra-status` | root Change identity, ordered v2 task-evidence/review identities, and strict aggregate Review packet/admission/subject/summary bindings | `.ultra/test-report.json`, retained task evidence and Review artifacts, `worktree_digest.cjs`, and existing structural validators | stale Change, intent, task set, task evidence, Review transport, or product results pass as current |
199
250
  | `compact_context` | `.ultra/.runtime/compact-snapshot.md` | derived from canonical files and Git | compact recovery loses acceleration, not authority |
200
251
  | every hook | existence of `.ultra/` | the project directory | Ultra taxes projects that never opted in (see `docs/PLUGIN-ISOLATION-CONTRACT.md`) |
201
252
  | `ultra-init` | the project data skeleton | `.ultra-template/` and the exact file list in its Skill | later Skills read missing authority paths; C1 dies |
@@ -1,19 +1,25 @@
1
1
  # Plugin isolation contract
2
2
 
3
- Ultra Builder Pro owns a narrow install surface and becomes active only in a project
4
- that contains `.ultra/` or when the owner explicitly invokes an Ultra Skill.
3
+ Ultra Builder Pro owns a narrow install surface. Installation and discovery create no
4
+ project authority. A public workflow becomes active only through an explicit owner
5
+ entry or one mode covered by a currently valid Execution Grant; Hooks separately use
6
+ the presence of `.ultra/` as their idle guard.
5
7
 
6
8
  ## Owned surfaces
7
9
 
8
10
  Per host, Ultra may install:
9
11
 
10
12
  - exactly fourteen managed Skills;
13
+ - the launcher, worker, Host profile, and launch-only profile assets below the managed
14
+ `ultra-delegate/scripts/` Skill directory;
11
15
  - exactly five hook scripts plus `_common.py` and any required wire adapter;
12
16
  - one native plugin manifest or entrypoint;
13
17
  - provenance and managed-ownership markers;
14
18
  - the host's native registry entry where required.
15
19
 
16
- The package also owns `ubp delegate run`, its worker, and rule-side Skill references.
20
+ For one release cycle the package also owns thin `ubp delegate` launcher/worker
21
+ compatibility imports. They execute the Skill-local implementation and contain no
22
+ forked behavior.
17
23
 
18
24
  ## Surfaces Ultra does not own
19
25
 
@@ -29,9 +35,10 @@ Ultra must not create or rewrite:
29
35
 
30
36
  ## Installation lifecycle
31
37
 
32
- Install builds a complete staging tree, marks it managed, writes provenance, then
33
- atomically publishes it. An existing unmanaged target is never overwritten. Reinstall
34
- replaces only the managed tree. Doctor is read-only. Uninstall removes only assets
38
+ Install builds a complete staging tree, including the Skill-local delegation runtime,
39
+ marks it managed, writes provenance, then atomically publishes it. An existing unmanaged
40
+ target is never overwritten. Reinstall replaces only the managed tree. Doctor is
41
+ read-only and reports runner reachability separately. Uninstall removes only assets
35
42
  whose ownership can be proven.
36
43
 
37
44
  Host-owned sidecars must resolve from the same isolation root as `--config-dir`. For
@@ -55,14 +62,29 @@ non-empty, modified, symlinked, or unowned path. Codex marketplace and Kimi regi
55
62
  files additionally remember whether Ultra created the registry itself, so an empty
56
63
  registry that existed before installation is retained.
57
64
 
58
- ## Activation
65
+ ZCode publishes one managed local marketplace whose nested plugin is activated through
66
+ the host's documented `plugins.dirs` configuration. Install preserves unrelated ZCode
67
+ configuration, and uninstall removes only Ultra's exact directory entry and restores
68
+ the pre-install `plugins.enabled` value when that value has not since been changed by
69
+ the owner.
59
70
 
60
- Owner-invoked Skills activate only through the host's explicit Skill surface.
61
- Model-invoked Skills may be selected by the host model only as methods inside the
62
- current authorized task. Hooks activate only through host lifecycle registrations.
71
+ ## Activation
63
72
 
64
- One public Skill may recommend another but never launches it. Installation does not
65
- create project authority or start background work.
73
+ Public Skill modes are `explicit-entry`, `grant-continuable`, or read-only `router`.
74
+ Explicit-entry modes activate only through the Host's owner-facing Skill surface.
75
+ Grant-continuable modes may be model-selected only after the loaded Skill verifies the
76
+ same active Change, valid grant, allowed effects, and material checkpoints. A router may
77
+ diagnose read-only state only on explicit owner invocation and creates no continuation
78
+ authority. Model-discipline Skills
79
+ may be selected only as methods inside the current covered workflow.
80
+
81
+ Host invocation metadata is a coarse discovery aid. It cannot express every per-mode
82
+ boundary, so the in-Skill check remains mandatory and Hosts without an equivalent bit
83
+ rely on discriminating descriptions plus that same check. A public Skill may transition
84
+ to another only when a valid grant covers the exact next mode and effects, after showing
85
+ the Route Card; otherwise it stops and recommends the explicit route. Installation does
86
+ not create a grant, launch a workflow, or start background work. Hooks activate only
87
+ through Host lifecycle registrations and retain their independent idle guard.
66
88
 
67
89
  ## Idle behavior
68
90