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.
- package/.ultra-template/contexts/TEMPLATE.md +70 -29
- package/.ultra-template/north-star.md +35 -18
- package/.ultra-template/tasks.json +1 -0
- package/.ultra-template/test-report.json +17 -1
- package/CHANGELOG.md +235 -1
- package/README.md +210 -50
- package/README.zh-CN.md +440 -0
- package/adapters/_shared/host-profile.cjs +3 -95
- package/adapters/_shared/plugin-core.cjs +61 -5
- package/adapters/_shared/runtime-assets.cjs +66 -5
- package/adapters/zcode.js +375 -0
- package/bin/delegate-worker.cjs +2 -325
- package/bin/delegate.cjs +3 -461
- package/bin/install.js +11 -6
- package/docs/ARCHITECTURE.md +133 -31
- package/docs/ARTIFACT-AUTHORITY.md +185 -24
- package/docs/DECISIONS.md +153 -18
- package/docs/PHILOSOPHY.md +58 -7
- package/docs/PLUGIN-ISOLATION-CONTRACT.md +34 -12
- package/docs/RUNTIME-COMPAT-MATRIX.md +195 -23
- package/docs/SKILL-AUTHORING.md +19 -6
- package/docs/WORKFLOW-LIFECYCLE.md +196 -44
- package/docs/evals/adversarial-review-2026-08-14.md +84 -0
- package/docs/evals/ultra-5-0-journey-results.md +62 -0
- package/docs/evals/ultra-5-0-live-acp-conformance.md +93 -0
- package/docs/evals/ultra-5-0-route-journeys.md +145 -0
- package/docs/evals/zcode-automation-2026-08-14.md +103 -0
- package/hooks/README.md +27 -4
- package/hooks/_common.py +1678 -61
- package/hooks/adapters/zcode.py +227 -0
- package/hooks/compact_context.py +176 -17
- package/hooks/mid_workflow_recall.py +27 -5
- package/hooks/post_edit_guard.py +133 -23
- package/hooks/session_context.py +707 -22
- package/package.json +7 -3
- package/skills/ultra-change/SKILL.md +69 -12
- package/skills/ultra-change/references/change-contract.md +93 -27
- package/skills/ultra-change/references/execution-grant.md +109 -0
- package/skills/ultra-change/references/primary-transfer.md +273 -0
- package/skills/ultra-change/scripts/validate_primary_transfer.cjs +1928 -0
- package/skills/ultra-delegate/SKILL.md +103 -8
- package/skills/ultra-delegate/patches/zcode-acp-0.1.0-zcode-0.16.5.patch +184 -0
- package/skills/ultra-delegate/references/delegation-contract.md +80 -1
- package/skills/ultra-delegate/scripts/acp-conformance.cjs +287 -0
- package/skills/ultra-delegate/scripts/acp-driver.cjs +762 -0
- package/skills/ultra-delegate/scripts/agent-execution-driver.cjs +320 -0
- package/skills/ultra-delegate/scripts/cli-driver.cjs +61 -0
- package/skills/ultra-delegate/scripts/delegate-worker.cjs +328 -0
- package/skills/ultra-delegate/scripts/delegate.cjs +690 -0
- package/skills/ultra-delegate/scripts/host-profile.cjs +267 -0
- package/skills/ultra-deliver/SKILL.md +98 -11
- package/skills/ultra-dev/SKILL.md +188 -42
- package/skills/ultra-grilling/SKILL.md +10 -7
- package/skills/ultra-grilling/references/reframing.md +7 -3
- package/skills/ultra-init/SKILL.md +56 -7
- package/skills/ultra-init/scripts/init_project.cjs +968 -21
- package/skills/ultra-plan/SKILL.md +91 -47
- package/skills/ultra-plan/references/task-evidence-v2.md +300 -0
- package/skills/ultra-plan/scripts/validate_task_evidence.cjs +859 -0
- package/skills/ultra-research/SKILL.md +70 -14
- package/skills/ultra-research/references/04-product-strategy.md +11 -2
- package/skills/ultra-research/references/21-features-scope.md +8 -0
- package/skills/ultra-research/references/22-success-metrics.md +4 -3
- package/skills/ultra-research/references/99-synthesis.md +19 -2
- package/skills/ultra-research/references/north-star-v2.md +168 -0
- package/skills/ultra-research/references/wayfinding.md +8 -0
- package/skills/ultra-research/scripts/validate_north_star.cjs +1174 -0
- package/skills/ultra-review/SKILL.md +201 -27
- package/skills/ultra-review/references/adversarial-evaluation.md +31 -0
- package/skills/ultra-review/references/spec.md +5 -0
- package/skills/ultra-review/references/unified-schema.md +146 -11
- package/skills/ultra-review/references/worker-packet.md +151 -8
- package/skills/ultra-review/scripts/review_wait.py +2653 -63
- package/skills/ultra-status/SKILL.md +129 -15
- package/skills/ultra-status/references/route-contract.md +100 -0
- package/skills/ultra-tdd/SKILL.md +11 -4
- package/skills/ultra-tdd/references/test-execution.md +6 -1
- package/skills/ultra-test/SKILL.md +161 -18
- package/skills/ultra-test/scripts/validate_review_transport.cjs +549 -0
- package/skills/ultra-test/scripts/worktree_digest.cjs +518 -30
- /package/{adapters/_shared → skills/ultra-delegate/scripts}/delegate-profiles/kimi-read-only.md +0 -0
- /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
|
|
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-
|
|
17
|
-
one router. Public
|
|
18
|
-
|
|
19
|
-
|
|
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
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
|
|
79
|
-
permission JSON, and named worktree.
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
|
package/docs/PHILOSOPHY.md
CHANGED
|
@@ -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
|
-
|
|
49
|
-
|
|
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
|
|
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 `
|
|
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` |
|
|
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
|
|
4
|
-
|
|
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
|
-
|
|
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,
|
|
33
|
-
atomically publishes it. An existing unmanaged
|
|
34
|
-
replaces only the managed tree. Doctor is
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
65
|
-
|
|
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
|
|