ultra-builder-pro-cli 0.23.0 → 0.24.1
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/docs/research/README.md +4 -4
- package/.ultra-template/tasks/tasks.json +4 -2
- package/CHANGELOG.md +72 -0
- package/README.md +55 -39
- package/adapters/_shared/codex-assets.cjs +121 -65
- package/adapters/_shared/interaction-contract.cjs +7 -1
- package/adapters/_shared/provenance.cjs +7 -2
- package/adapters/_shared/runtime-assets.cjs +3 -2
- package/adapters/_shared/runtime-native.cjs +132 -0
- package/adapters/claude.js +60 -30
- package/adapters/codex.js +178 -81
- package/adapters/grok.js +372 -0
- package/adapters/kimi.js +7 -3
- package/adapters/opencode.js +210 -32
- package/agents/code-reviewer.md +4 -2
- package/agents/debugger.md +4 -1
- package/agents/review-code.md +7 -3
- package/agents/review-comments.md +7 -4
- package/agents/review-coordinator.md +11 -7
- package/agents/review-design.md +8 -4
- package/agents/review-errors.md +8 -4
- package/agents/review-spec.md +8 -5
- package/agents/review-tests.md +7 -4
- package/agents/tdd-runner.md +5 -2
- package/bin/install.js +9 -4
- package/bin/orchestrator.js +4 -13
- package/docs/AGENT-CONTEXT.md +143 -229
- package/docs/ARCHITECTURE.md +205 -494
- package/docs/ARTIFACT-AUTHORITY.md +35 -28
- package/docs/LEGACY-CLI-CROSSWALK.md +1 -1
- package/docs/PLUGIN-ISOLATION-CONTRACT.md +12 -9
- package/docs/ROADMAP.md +85 -110
- package/docs/RUNTIME-COMPAT-MATRIX.md +139 -175
- package/docs/SKILL-AUTHORING.md +3 -3
- package/docs/STATE-DB-ACCESS-POLICY.md +13 -8
- package/docs/WORKFLOW-LIFECYCLE.md +189 -448
- package/hooks/README.md +11 -8
- package/hooks/active_task_context.py +16 -16
- package/hooks/adapters/grok.py +134 -0
- package/hooks/{context_spine.py → context_envelope.py} +26 -22
- package/hooks/health_check.py +29 -34
- package/hooks/pre_stop_check.py +22 -12
- package/hooks/subagent_tracker.py +1 -1
- package/hooks/workflow_checkpoint.py +14 -13
- package/hooks/workflow_context.py +11 -12
- package/hooks/workflow_resume.py +14 -13
- package/mcp-server/{breadcrumb.cjs → hook-context.cjs} +7 -9
- package/mcp-server/lib/baseline-workflow.cjs +108 -82
- package/mcp-server/lib/canonical-json.cjs +19 -0
- package/mcp-server/lib/change-authority.cjs +26 -0
- package/mcp-server/lib/change-workflow.cjs +630 -45
- package/mcp-server/lib/context-envelope.cjs +508 -0
- package/mcp-server/lib/decision-records.cjs +337 -0
- package/mcp-server/lib/doctor.cjs +91 -33
- package/mcp-server/lib/init-project.cjs +78 -39
- package/mcp-server/lib/managed-file-write.cjs +116 -0
- package/mcp-server/lib/plan-checkpoint.cjs +177 -0
- package/mcp-server/lib/project-context.cjs +178 -0
- package/mcp-server/lib/stage-checkpoints.cjs +309 -0
- package/mcp-server/lib/state-db.cjs +155 -24
- package/mcp-server/lib/state-ops.cjs +21 -3
- package/mcp-server/lib/task-ledger.cjs +522 -13
- package/mcp-server/lib/ultra-facade.cjs +757 -442
- package/mcp-server/lib/worker-packet.cjs +358 -0
- package/mcp-server/server.cjs +200 -1103
- package/orchestrator/daemon.cjs +27 -9
- package/orchestrator/parallel-orchestrator.cjs +111 -76
- package/orchestrator/session-runner.cjs +135 -34
- package/package.json +10 -3
- package/skills/ultra-change/SKILL.md +10 -8
- package/skills/ultra-deliver/SKILL.md +17 -19
- package/skills/ultra-dev/SKILL.md +20 -11
- package/skills/ultra-doctor/SKILL.md +4 -4
- package/skills/ultra-init/SKILL.md +6 -5
- package/skills/ultra-init/references/brownfield-adoption.md +20 -14
- package/skills/ultra-plan/SKILL.md +13 -9
- package/skills/ultra-research/SKILL.md +18 -9
- package/skills/ultra-review/SKILL.md +14 -9
- package/skills/ultra-review/references/unified-schema.md +2 -0
- package/skills/ultra-review/scripts/review_wait.py +8 -0
- package/skills/ultra-status/SKILL.md +2 -2
- package/skills/ultra-test/SKILL.md +10 -6
- package/skills/ultra-think/SKILL.md +8 -7
- package/skills/ultra-think/references/interaction-boundary.md +56 -0
- package/spec/cli-protocol.md +80 -199
- package/spec/mcp-tools.yaml +43 -2806
- package/spec/schemas/state-db.sql +107 -4
- package/spec/schemas/{task-ledger.v1.schema.json → task-ledger.v2.schema.json} +70 -6
- package/ultra-tools/commands/status.cjs +369 -243
- package/mcp-server/lib/context-spine.cjs +0 -1208
- package/mcp-server/lib/decision-dialogue.cjs +0 -1128
- package/mcp-server/lib/project-breadcrumb.cjs +0 -173
- package/mcp-server/lib/spec-learning.cjs +0 -284
- package/mcp-server/lib/workflow-state.cjs +0 -3129
- package/skills/ultra-think/references/decision-dialogue.md +0 -155
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ultra-builder-pro-cli",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI,
|
|
3
|
+
"version": "0.24.1",
|
|
4
|
+
"description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build, with a project-local MCP persistence and safety kernel.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"ultra-builder-pro-cli": "bin/install.js",
|
|
7
7
|
"ubp": "bin/install.js",
|
|
@@ -61,13 +61,19 @@
|
|
|
61
61
|
"!**/*.pyo",
|
|
62
62
|
"!**/*.test.cjs",
|
|
63
63
|
"!**/tests/**",
|
|
64
|
-
"!mcp-server/test-support/**"
|
|
64
|
+
"!mcp-server/test-support/**",
|
|
65
|
+
"!mcp-server/lib/workflow-state.cjs",
|
|
66
|
+
"!mcp-server/lib/decision-dialogue.cjs",
|
|
67
|
+
"!mcp-server/lib/context-spine.cjs",
|
|
68
|
+
"!mcp-server/lib/project-breadcrumb.cjs",
|
|
69
|
+
"!mcp-server/lib/spec-learning.cjs"
|
|
65
70
|
],
|
|
66
71
|
"keywords": [
|
|
67
72
|
"claude-code",
|
|
68
73
|
"opencode",
|
|
69
74
|
"codex",
|
|
70
75
|
"kimi-code",
|
|
76
|
+
"grok-build",
|
|
71
77
|
"agent",
|
|
72
78
|
"cli",
|
|
73
79
|
"multi-runtime",
|
|
@@ -101,6 +107,7 @@
|
|
|
101
107
|
"prepublishOnly": "npm run verify:release",
|
|
102
108
|
"install:claude": "node bin/install.js --claude --local",
|
|
103
109
|
"install:kimi": "node bin/install.js --kimi --local",
|
|
110
|
+
"install:grok": "node bin/install.js --grok --local",
|
|
104
111
|
"install:all": "node bin/install.js --all --local"
|
|
105
112
|
},
|
|
106
113
|
"dependencies": {
|
|
@@ -22,24 +22,26 @@ checkpoint accepts the downstream authority.
|
|
|
22
22
|
a choice changes accepted product intent, compatibility, security, material cost,
|
|
23
23
|
external effects, or recovery.
|
|
24
24
|
|
|
25
|
-
Read `../ultra-think/references/
|
|
25
|
+
Read `../ultra-think/references/interaction-boundary.md` before asking. MCP may report
|
|
26
26
|
contradictory risk fields, but the model and owner choose the semantic correction.
|
|
27
27
|
|
|
28
28
|
## Record the contract
|
|
29
29
|
|
|
30
|
-
Use one `ultra.record` batch
|
|
31
|
-
`
|
|
32
|
-
a stable idempotency key. Read the
|
|
30
|
+
Use one `ultra.record` batch with `change_contract / open` or
|
|
31
|
+
`change_contract / revise`, relevant `decision / accept`, and `artifact / bind` for
|
|
32
|
+
an already-known typed delta. Every entry carries a stable idempotency key. Read the
|
|
33
|
+
result through `ultra.context`.
|
|
33
34
|
|
|
34
35
|
Keep every Change-owned semantic artifact below
|
|
35
36
|
`.ultra/changes/active/<change-id>/`. Standard and major Changes require a typed delta
|
|
36
37
|
before planning. A true no-semantic-change case records an explicit reason instead of
|
|
37
38
|
manufacturing a mutation.
|
|
38
39
|
|
|
39
|
-
Changing accepted intent
|
|
40
|
-
stale.
|
|
41
|
-
|
|
42
|
-
|
|
40
|
+
Changing accepted intent creates a new accepted checkpoint revision and makes only
|
|
41
|
+
genuinely dependent evidence stale. Readiness is derived, not a stored absorbing
|
|
42
|
+
state. Semantic diagnostics remain advisory; structural, digest, path, or concurrency
|
|
43
|
+
conflicts require repair and retry of the same draft.
|
|
44
|
+
Use `change_contract / cancel` only when the owner intentionally abandons the Change.
|
|
43
45
|
|
|
44
46
|
Publish the durable Change contract with `ultra.sync { action: publish }` when it is a
|
|
45
47
|
useful team handoff. Recommend bounded `ultra-research` for a real evidence gap or
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ultra-deliver
|
|
3
|
-
description:
|
|
3
|
+
description: Reconcile and archive an explicitly accepted Ultra Change with recoverable local evidence. Use when the caller is ready to make a local delivery handoff with current managed evidence and an explicit rationale for any omitted capability.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Converge and archive local authority
|
|
@@ -12,8 +12,10 @@ publication, deployment, or another external effect.
|
|
|
12
12
|
|
|
13
13
|
1. Call `ultra.context { stage: deliver, scope: { change_id }, detail: full }`.
|
|
14
14
|
2. Import a newer team checkpoint with `ultra.sync`; stop on a real conflict.
|
|
15
|
-
3.
|
|
16
|
-
|
|
15
|
+
3. Inspect current task outcomes, tests, both review axes, accepted decisions, typed
|
|
16
|
+
delta, documentation reconciliation, and checkout evidence. Decide whether the
|
|
17
|
+
actual Change is sufficiently complete; explicitly record any omitted stage and its
|
|
18
|
+
evidence-based rationale instead of inventing a fixed recipe.
|
|
17
19
|
4. Resolve every specification-learning candidate. Keep updates inside the Change
|
|
18
20
|
overlay until archive.
|
|
19
21
|
5. Write and register documentation reconciliation and an
|
|
@@ -21,26 +23,22 @@ publication, deployment, or another external effect.
|
|
|
21
23
|
worktree/context digests, local checks, rollback guidance, and timestamp; it contains
|
|
22
24
|
no release decision.
|
|
23
25
|
|
|
24
|
-
Use one `ultra.record` batch for
|
|
25
|
-
|
|
26
|
+
Use one typed `ultra.record` batch for `artifact / bind`, any normalized
|
|
27
|
+
`decision / accept`, and bounded `event / append` facts.
|
|
26
28
|
|
|
27
29
|
## Archive once
|
|
28
30
|
|
|
29
31
|
Call `ultra.archive` once with the Change id, stable idempotency key, archive summary,
|
|
30
|
-
reconciliation fields, delivery evidence steps, and report output.
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
A semantic rejection returns mutable blockers. Repair the same packet and retry. A
|
|
42
|
-
hard corruption, path, concurrency, or recovery error remains fail-closed and routes to
|
|
43
|
-
`ultra-doctor`.
|
|
32
|
+
reconciliation fields, delivery evidence steps, explicit omissions, and report output.
|
|
33
|
+
The model's report is the semantic handoff. MCP validates its current registered
|
|
34
|
+
authority, paths, digests, reconciliation structure, and idempotency; applies the
|
|
35
|
+
overlay and archive through the recoverable filesystem/DB transaction; rebinds
|
|
36
|
+
registered artifacts into a self-contained archive; and publishes the updated team
|
|
37
|
+
checkpoint. It does not require a hard-coded Plan/Dev/Test/Review/Deliver sequence.
|
|
38
|
+
|
|
39
|
+
Semantic warnings remain in the archive history but do not reject an explicit local
|
|
40
|
+
handoff. Corruption, unsafe paths, digest/CAS conflicts, permissions, or recovery
|
|
41
|
+
failure remain fail-closed and route to `ultra-doctor`.
|
|
44
42
|
|
|
45
43
|
Verify the archived packet, baseline, checkpoint, and rollback state. Handle any
|
|
46
44
|
separately authorized Git or release effect only after local delivery and report it as
|
|
@@ -5,17 +5,21 @@ description: Implement one authoritative Ultra task through a fresh-context, tes
|
|
|
5
5
|
|
|
6
6
|
# Implement one task
|
|
7
7
|
|
|
8
|
-
The model owns code reasoning and edits. Ultra owns the durable task contract,
|
|
9
|
-
Context
|
|
8
|
+
The model owns code reasoning and edits. Ultra owns the durable task contract,
|
|
9
|
+
canonical Context Envelope, execution lease, immutable Worker Packet, evidence
|
|
10
|
+
references, and checkpoint.
|
|
10
11
|
|
|
11
12
|
## Bind execution
|
|
12
13
|
|
|
13
14
|
1. Call `ultra.context { stage: dev, scope: { change_id, task_id }, detail: full }`.
|
|
14
15
|
2. Import a newer team checkpoint with `ultra.sync`; stop on a real same-record or
|
|
15
16
|
active-session conflict.
|
|
16
|
-
3. Reuse a valid lease or call `ultra.session { action:
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
3. Reuse a valid lease or call `ultra.session { action: acquire }`. Acquire atomically
|
|
18
|
+
performs admission, compiles or reuses the implementation Context Envelope, mints
|
|
19
|
+
the lease/worktree, and returns the immutable Worker Packet. A separate
|
|
20
|
+
`action: admission` is an optional read-only preview, not a prerequisite.
|
|
21
|
+
4. Verify the returned packet digest, purpose, acceptance, dependencies, public seam,
|
|
22
|
+
exact output path/schema, verification command,
|
|
19
23
|
non-goals, recovery, and required context refs. Update the task contract before
|
|
20
24
|
implementation when accepted intent changed.
|
|
21
25
|
|
|
@@ -26,10 +30,13 @@ before changing logic. Implement the smallest complete vertical slice. Ask the o
|
|
|
26
30
|
only when new evidence changes product intent, compatibility, security, material cost,
|
|
27
31
|
external effects, or recovery.
|
|
28
32
|
|
|
29
|
-
Use `ultra.record`
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
+
Use typed `ultra.record` entries for `task_outcome / start|block|complete`,
|
|
34
|
+
`event / append`, `artifact / bind`, `decision / accept`, and corrected
|
|
35
|
+
`task_contract / revise`. Every worker output must repeat the exact `packet_digest`;
|
|
36
|
+
the parent registers it only after packet, output path, schema, and digest validation.
|
|
37
|
+
Live ownership, `in_progress`, session ids, leases, worktrees, telemetry, and
|
|
38
|
+
completion hashes remain local runtime state; durable task outcome and evidence may
|
|
39
|
+
enter the team checkpoint.
|
|
33
40
|
|
|
34
41
|
Run focused and adjacent risk-justified checks, then a task-scoped independent review.
|
|
35
42
|
Fix blocking findings and refresh affected evidence.
|
|
@@ -37,8 +44,10 @@ Fix blocking findings and refresh affected evidence.
|
|
|
37
44
|
## Commit one semantic checkpoint
|
|
38
45
|
|
|
39
46
|
Call `ultra.checkpoint` once with `stage: dev`, the exact Change/Task scope, evidence,
|
|
40
|
-
and stable idempotency key. It
|
|
41
|
-
|
|
47
|
+
and stable idempotency key. It binds the exact Context Envelope and Worker Packet and
|
|
48
|
+
reports outcome diagnostics. The model decides whether the implemented slice satisfies
|
|
49
|
+
the Task; semantic warnings remain visible. A rejection means the declared authority,
|
|
50
|
+
path, digest, or concurrency boundary was unsafe and leaves the draft mutable.
|
|
42
51
|
|
|
43
52
|
After acceptance, mark the task durably completed, publish with `ultra.sync`, and
|
|
44
53
|
create at most one authorized local task commit containing code and semantic
|
|
@@ -19,8 +19,8 @@ Call `ultra.doctor { repair: false }` and inspect:
|
|
|
19
19
|
- projection jobs, sessions, leases, worktrees, and recovery journals;
|
|
20
20
|
- installed plugin assets, MCP startup, and hook paths.
|
|
21
21
|
|
|
22
|
-
An expected workflow pause, editable draft,
|
|
23
|
-
|
|
22
|
+
An expected workflow pause, editable draft, semantic warning, or awaiting owner
|
|
23
|
+
decision is not corruption.
|
|
24
24
|
|
|
25
25
|
## Repair
|
|
26
26
|
|
|
@@ -30,8 +30,8 @@ journals, reconcile orphan sessions, and repair installed mechanical assets.
|
|
|
30
30
|
|
|
31
31
|
It may not manufacture semantic evidence, import or publish a team checkpoint, replace
|
|
32
32
|
a healthy baseline, resolve decisions, edit application code, or force a draft to
|
|
33
|
-
accepted. Use `ultra.sync` for reviewed checkpoint import/publish
|
|
34
|
-
|
|
33
|
+
accepted. Use `ultra.sync` for reviewed checkpoint import/publish. Doctor never changes
|
|
34
|
+
semantic checkpoint acceptance or Change intent.
|
|
35
35
|
|
|
36
36
|
Preserve corrupt DB/WAL/SHM and dirty worktrees. Never patch plugin cache files by
|
|
37
37
|
hand; reinstall through `ubp` and verify the installed manifest and hook targets.
|
|
@@ -23,17 +23,18 @@ capability.
|
|
|
23
23
|
4. Ask the owner only when scope, healthy-authority replacement, destructive recovery,
|
|
24
24
|
or another material choice cannot be derived. Reuse explicit intent.
|
|
25
25
|
|
|
26
|
-
Read `../ultra-think/references/
|
|
26
|
+
Read `../ultra-think/references/interaction-boundary.md` before asking a material
|
|
27
27
|
question.
|
|
28
28
|
|
|
29
29
|
## Initialize once
|
|
30
30
|
|
|
31
|
-
Call `ultra.record` with one entry:
|
|
31
|
+
Call `ultra.record` with one typed entry:
|
|
32
32
|
|
|
33
33
|
```text
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
34
|
+
kind: baseline
|
|
35
|
+
action: initialize
|
|
36
|
+
data: { target_dir, project_name, mode=auto, git_mode=auto, optional scope }
|
|
37
|
+
idempotency_key: <stable init attempt id>
|
|
37
38
|
```
|
|
38
39
|
|
|
39
40
|
This stateless bootstrap is the only `ultra.record` operation allowed before
|
|
@@ -52,21 +52,25 @@ baseline is ready.
|
|
|
52
52
|
Record every adoption gap with a stable id, evidence references, owner, blocking flag,
|
|
53
53
|
and one category:
|
|
54
54
|
|
|
55
|
-
- `baseline_blocker`:
|
|
55
|
+
- `baseline_blocker`: the model should recommend against adoption until resolved or
|
|
56
|
+
the owner explicitly accepts the recorded risk;
|
|
56
57
|
- `documentation_drift`: maintained prose conflicts with observed behavior;
|
|
57
58
|
- `known_defect`: reproducible incorrect behavior;
|
|
58
59
|
- `technical_debt`: accepted maintainability or quality cost;
|
|
59
60
|
- `unknown`: evidence is insufficient;
|
|
60
61
|
- `future_change`: desired behavior outside the current baseline.
|
|
61
62
|
|
|
62
|
-
Use `open` for unresolved gaps, `accepted` for owner-accepted
|
|
63
|
+
Use `open` for unresolved gaps, `accepted` for owner-accepted debt,
|
|
63
64
|
`resolved` when evidence closes the gap, and `deferred` for explicitly postponed
|
|
64
|
-
|
|
65
|
-
|
|
65
|
+
work. Keep every open `baseline_blocker` visible as a semantic warning. It does not
|
|
66
|
+
become a SQLite hard gate: the model explains the risk, recommends resolution, and may
|
|
67
|
+
record owner-authorized adoption without erasing the gap. Do not convert the ledger
|
|
68
|
+
into hundreds of application tasks.
|
|
66
69
|
|
|
67
70
|
## Record authority
|
|
68
71
|
|
|
69
|
-
|
|
72
|
+
Use `ultra.record` with `kind: baseline`, `action: observe`, and full replacement
|
|
73
|
+
arrays for:
|
|
70
74
|
|
|
71
75
|
- scope and repository revision;
|
|
72
76
|
- repository classification;
|
|
@@ -82,12 +86,14 @@ Use the server-returned revision, branch, worktree digest, and specification dig
|
|
|
82
86
|
## Obtain approval and converge
|
|
83
87
|
|
|
84
88
|
Present scope, observed behavior, drift, known-red verification, unknowns, gaps, dirty
|
|
85
|
-
worktree state, and material decisions to the owner.
|
|
86
|
-
|
|
87
|
-
items the owner
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
89
|
+
worktree state, and material decisions to the owner. Use `ultra.record` with
|
|
90
|
+
`kind: baseline`, `action: accept` only after explicit approval. Set
|
|
91
|
+
`accept_known_red` and `accept_dirty_worktree` only for the exact items the owner
|
|
92
|
+
accepted.
|
|
93
|
+
|
|
94
|
+
Resolve hard authority blockers, then present semantic warnings for evidence or an
|
|
95
|
+
owner decision. Adoption is complete when `ultra.context` reports a current accepted
|
|
96
|
+
baseline, every material open gap is visible with its owner/risk and any acceptance is
|
|
97
|
+
explicit in the approval note, and project doctor has no mechanical authority failure.
|
|
98
|
+
Route all selected work through `ultra-change`, including work described by a legacy
|
|
99
|
+
plan. Import its accepted intent into a current Change Contract before planning.
|
|
@@ -28,13 +28,14 @@ Large sources stay lazy. Use digest freshness for accepted inputs that must rema
|
|
|
28
28
|
byte-current, existence for expected implementation targets, and advisory only when
|
|
29
29
|
drift must be visible without blocking.
|
|
30
30
|
|
|
31
|
-
Read `../ultra-think/references/
|
|
31
|
+
Read `../ultra-think/references/interaction-boundary.md` before asking a material
|
|
32
32
|
question.
|
|
33
33
|
|
|
34
34
|
## Record and checkpoint
|
|
35
35
|
|
|
36
|
-
Use one `ultra.record` batch
|
|
37
|
-
|
|
36
|
+
Use one `ultra.record` batch with `task_contract / define` for new tasks and
|
|
37
|
+
`task_contract / revise` for corrected contracts. Read back the draft with
|
|
38
|
+
`ultra.context`.
|
|
38
39
|
Never read or write `.ultra/tasks/tasks.json`; use `ultra.sync` for the Git team
|
|
39
40
|
checkpoint, and never edit the local runtime projection directly.
|
|
40
41
|
|
|
@@ -47,13 +48,16 @@ payload: planning posture, optional approval already obtained, context budget/re
|
|
|
47
48
|
idempotency_key: stable semantic Plan checkpoint id
|
|
48
49
|
```
|
|
49
50
|
|
|
50
|
-
The
|
|
51
|
-
|
|
52
|
-
|
|
51
|
+
The model decides whether decomposition, acceptance coverage, and context are
|
|
52
|
+
sufficient and records any deliberate omission. The checkpoint compiles or reuses the
|
|
53
|
+
content-addressed Context Envelope, reports advisory coverage diagnostics, exports
|
|
54
|
+
`plan.json` and `plan.md` inside the same recoverable publication, accepts one Plan
|
|
55
|
+
revision, and publishes the team checkpoint. Do not export separately.
|
|
53
56
|
|
|
54
|
-
If rejected, the same Plan draft stays mutable. Fix
|
|
55
|
-
|
|
56
|
-
run to escape a
|
|
57
|
+
If rejected, the same Plan draft stays mutable. Fix only the reported structural,
|
|
58
|
+
digest, path, or concurrency conflict and retry. To replace an accepted Plan, submit a
|
|
59
|
+
new checkpoint revision; never edit SQLite or open a parallel run to escape a
|
|
60
|
+
diagnostic.
|
|
57
61
|
|
|
58
62
|
Return topology, executable slices, public seams, exact checks, checkpoint result, and
|
|
59
63
|
the model's recommended execution order. Do not invoke `ultra-dev` automatically.
|
|
@@ -21,7 +21,7 @@ not a questionnaire or a step-by-step supervisor.
|
|
|
21
21
|
5. Use the host-native question surface only for a material unresolved route. Reuse an
|
|
22
22
|
explicit owner choice without asking again.
|
|
23
23
|
|
|
24
|
-
Read `../ultra-think/references/
|
|
24
|
+
Read `../ultra-think/references/interaction-boundary.md` before asking. Load only the
|
|
25
25
|
reference files for research areas that actually apply.
|
|
26
26
|
|
|
27
27
|
## Investigate
|
|
@@ -34,10 +34,16 @@ For each selected area:
|
|
|
34
34
|
- never store transcripts, hidden reasoning, raw provider payloads, or copied prompts;
|
|
35
35
|
- record evidence, specification updates, decisions, deferrals, and consequences.
|
|
36
36
|
|
|
37
|
-
Use one `ultra.record` batch for durable facts
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
37
|
+
Use one `ultra.record` batch for typed durable facts:
|
|
38
|
+
|
|
39
|
+
- `artifact / bind` for a managed research or specification artifact;
|
|
40
|
+
- `decision / accept` for normalized owner intent;
|
|
41
|
+
- `baseline / observe` or `baseline / accept` for baseline authority;
|
|
42
|
+
- `change_contract / revise` for Change-bound findings.
|
|
43
|
+
|
|
44
|
+
Every entry needs a stable idempotency key. Structural or authority conflicts require
|
|
45
|
+
repair; semantic warnings remain visible but do not decide whether the research is
|
|
46
|
+
sufficient.
|
|
41
47
|
|
|
42
48
|
## Commit one research checkpoint
|
|
43
49
|
|
|
@@ -46,13 +52,16 @@ and their report outputs in `payload.steps`; include only work actually performe
|
|
|
46
52
|
verified, reused, deferred with owner authority, or proved not applicable. Synthesis
|
|
47
53
|
must always be present.
|
|
48
54
|
|
|
49
|
-
For baseline research,
|
|
50
|
-
|
|
55
|
+
For baseline research, update and accept the baseline through typed `ultra.record`
|
|
56
|
+
entries, then publish the team checkpoint with `ultra.sync { action: publish }`.
|
|
51
57
|
For Change-bound research, keep all findings and delta artifacts below the Change
|
|
52
58
|
root and never edit accepted baseline specs directly.
|
|
53
59
|
|
|
54
|
-
|
|
55
|
-
|
|
60
|
+
The model decides whether the selected coverage and synthesis are sufficient, and
|
|
61
|
+
states omissions or deferred areas in the payload. MCP validates declared evidence
|
|
62
|
+
bytes and records that conclusion; its semantic diagnostics are advisory. If it
|
|
63
|
+
returns `accepted: false`, repair the reported structural, digest, path, or concurrency
|
|
64
|
+
conflict and retry the same draft.
|
|
56
65
|
|
|
57
66
|
Return coverage, decisive evidence, remaining gaps, durable artifact paths, and a
|
|
58
67
|
model recommendation for the next explicit capability, such as `ultra-change` after a
|
|
@@ -21,21 +21,26 @@ Keep two independent verdict axes:
|
|
|
21
21
|
5. Always run `review-spec`. Select the smallest engineering worker set that covers
|
|
22
22
|
actual risk; record selected and excluded roles with rationale.
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
24
|
+
Use the current host's native bounded-worker mechanism. Workers are read-only and
|
|
25
|
+
receive one immutable Worker Packet containing the exact Context Envelope, HEAD/diff,
|
|
26
|
+
decisions, acceptance, output path/schema, and `packet_digest`. Validate their artifacts with `scripts/review_wait.py` and
|
|
27
|
+
`references/unified-schema.md`; reject any output that does not echo the exact packet
|
|
28
|
+
digest. Preserve every finding unchanged in `SUMMARY.json`; group duplicates only in
|
|
29
|
+
the human summary.
|
|
28
30
|
|
|
29
|
-
Register specialist and summary artifacts through one `ultra.record` batch
|
|
31
|
+
Register specialist and summary artifacts through one `ultra.record` batch using
|
|
32
|
+
`artifact / bind`.
|
|
30
33
|
|
|
31
34
|
## Checkpoint
|
|
32
35
|
|
|
33
36
|
Call `ultra.checkpoint` once with `stage: review`, exact scope, evidence, and outputs
|
|
34
|
-
tagged `spec_review`, `engineering_review`, or summary. The
|
|
35
|
-
|
|
37
|
+
tagged `spec_review`, `engineering_review`, or summary. The model and bounded review
|
|
38
|
+
agents own both evidence-derived axes. The checkpoint compiles or reuses review
|
|
39
|
+
context, verifies declared artifact bytes and digests, and records the supplied axes
|
|
40
|
+
without overriding findings.
|
|
36
41
|
|
|
37
|
-
A rejected checkpoint leaves the draft mutable. Fix
|
|
38
|
-
do not open a replacement run or suppress a finding.
|
|
42
|
+
A rejected checkpoint leaves the draft mutable. Fix the structural, digest, path, or
|
|
43
|
+
concurrency fault and retry; do not open a replacement run or suppress a finding.
|
|
39
44
|
|
|
40
45
|
Return both axes, findings, reviewed scope, worker rationale, digests, and the model's
|
|
41
46
|
recommended next explicit capability. Do not invoke it automatically.
|
|
@@ -10,6 +10,7 @@ return only a one-line acknowledgement to the parent.
|
|
|
10
10
|
"$schema": "ultra-review-findings-v2",
|
|
11
11
|
"agent": "review-code",
|
|
12
12
|
"axis": "engineering_standards",
|
|
13
|
+
"packet_digest": "<sha256-of-exact-worker-packet>",
|
|
13
14
|
"session": "<session-id>",
|
|
14
15
|
"timestamp": "<ISO-8601>",
|
|
15
16
|
"scope": {
|
|
@@ -74,6 +75,7 @@ preference as a defect. Preserve the source specialist's severity during coordin
|
|
|
74
75
|
"head": "<full-git-head>",
|
|
75
76
|
"worktree_digest": "<sha256-of-current-worktree>",
|
|
76
77
|
"context_digest": "<sha256-of-recorded-review-context>",
|
|
78
|
+
"packet_digest": "<sha256-of-coordinator-worker-packet>",
|
|
77
79
|
"status": "complete",
|
|
78
80
|
"verdict": "REQUEST_CHANGES",
|
|
79
81
|
"axes": {
|
|
@@ -66,6 +66,10 @@ def nonempty_string(value) -> bool:
|
|
|
66
66
|
return isinstance(value, str) and bool(value.strip())
|
|
67
67
|
|
|
68
68
|
|
|
69
|
+
def digest_string(value) -> bool:
|
|
70
|
+
return isinstance(value, str) and re.fullmatch(r"[0-9a-f]{64}", value) is not None
|
|
71
|
+
|
|
72
|
+
|
|
69
73
|
def validate_finding(finding, artifact_axis: str, seen_ids):
|
|
70
74
|
if not isinstance(finding, dict):
|
|
71
75
|
return "finding must be an object"
|
|
@@ -97,6 +101,8 @@ def validate_specialist(data):
|
|
|
97
101
|
return f"$schema must be {FINDINGS_SCHEMA}"
|
|
98
102
|
if not nonempty_string(data.get("agent")):
|
|
99
103
|
return "agent must be a non-empty string"
|
|
104
|
+
if not digest_string(data.get("packet_digest")):
|
|
105
|
+
return "packet_digest must be a lowercase SHA-256 digest"
|
|
100
106
|
axis = data.get("axis")
|
|
101
107
|
if axis not in AXES:
|
|
102
108
|
return "axis must be spec_fidelity or engineering_standards"
|
|
@@ -197,6 +203,8 @@ def validate_summary(data):
|
|
|
197
203
|
for field in ["session", "change_id", "head", "context_digest"]:
|
|
198
204
|
if not nonempty_string(data.get(field)):
|
|
199
205
|
return f"{field} must be a non-empty string"
|
|
206
|
+
if not digest_string(data.get("packet_digest")):
|
|
207
|
+
return "packet_digest must be a lowercase SHA-256 digest"
|
|
200
208
|
if data.get("worktree_digest") is not None and not nonempty_string(data.get("worktree_digest")):
|
|
201
209
|
return "worktree_digest must be null or a non-empty string"
|
|
202
210
|
task_ids = data.get("task_ids")
|
|
@@ -20,14 +20,14 @@ Report:
|
|
|
20
20
|
```text
|
|
21
21
|
Ultra: <healthy|degraded> · <branch>@<head|unborn|non-git>
|
|
22
22
|
Baseline: <mode>/<status> · gaps=<open>/<blocking>
|
|
23
|
-
|
|
23
|
+
Stage checkpoints: drafts=<count> · accepted=<current|stale|none>
|
|
24
24
|
Change: <id/status|none> · delta/docs=<state>
|
|
25
25
|
Task: <id/status|none> · Sessions: <active>
|
|
26
26
|
Evidence: plan=<state> · test=<state> · review=<axes> · delivery=<state>
|
|
27
27
|
Team checkpoint: <current|drifted|revalidation_required|missing|invalid>
|
|
28
28
|
Blockers: <hard mechanical blockers or none>
|
|
29
29
|
Warnings: <advisory semantic diagnostics or none>
|
|
30
|
-
|
|
30
|
+
Model recommendation: <capability and concise rationale>
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
Treat warnings and failed draft checks as information, not mechanical orders. Only
|
|
@@ -20,19 +20,23 @@ generated projections are not evidence.
|
|
|
20
20
|
5. Run repository-native commands and real boundaries. A bug or incident needs one
|
|
21
21
|
deterministic red-to-green regression signal.
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
When delegated, use the immutable Worker Packet supplied by the parent and echo its
|
|
24
|
+
`packet_digest` in the report. Write an `ultra-test-report-v1` report below the owning
|
|
25
|
+
Change. Bind exact acceptance
|
|
24
26
|
ids, task ids, HEAD, worktree/context digests, commands, seams, failures, recovery,
|
|
25
27
|
profile, timestamp, blockers, and evidence-derived verdict. Register it with
|
|
26
|
-
`ultra.record` using `artifact
|
|
28
|
+
`ultra.record` using `artifact / bind`.
|
|
27
29
|
|
|
28
30
|
## Checkpoint
|
|
29
31
|
|
|
30
32
|
Call `ultra.checkpoint` once with `stage: test`, exact scope, evidence, and an output
|
|
31
|
-
for the report (`kind: test-report`). The
|
|
32
|
-
|
|
33
|
+
for the report (`kind: test-report`). The model owns the evidence-derived verdict and
|
|
34
|
+
material exclusions. The checkpoint compiles or reuses checking context, verifies the
|
|
35
|
+
declared report authority and digest, and records that verdict without re-judging it.
|
|
33
36
|
|
|
34
|
-
If rejected, keep the same draft
|
|
35
|
-
assertion, hide a skip, or turn a warning into
|
|
37
|
+
If rejected, keep the same draft and repair the structural, digest, path, or
|
|
38
|
+
concurrency fault. Never weaken an assertion, hide a skip, or turn a warning into
|
|
39
|
+
proof.
|
|
36
40
|
|
|
37
41
|
Return the profile, exact results, verified seams, blockers, report digest, and the
|
|
38
42
|
model's recommended next explicit capability. Do not invoke it automatically.
|
|
@@ -18,20 +18,21 @@ project-bound decision that must survive interruption or control later work.
|
|
|
18
18
|
implementation judgment, and unresolved owner choice.
|
|
19
19
|
5. Stress-test the leading answer with its strongest failure path and recovery.
|
|
20
20
|
|
|
21
|
-
Read `references/
|
|
21
|
+
Read `references/interaction-boundary.md`. Reuse a clear decision already present in the
|
|
22
22
|
request. Decide reversible delegated implementation details yourself. When owner
|
|
23
23
|
authority is necessary, ask one dependent decision through the host-native question
|
|
24
24
|
surface with a recommendation, decisive evidence, and the effect of the answer.
|
|
25
25
|
|
|
26
26
|
## Persist only the normalized result
|
|
27
27
|
|
|
28
|
-
Use one `ultra.record` batch
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
artifact references, never transcripts or internal reasoning.
|
|
28
|
+
Use one `ultra.record` batch with `decision / accept` and, when required,
|
|
29
|
+
`artifact / bind` for the owning semantic document. A revised answer carries
|
|
30
|
+
`supersedes_id`; accepted records remain immutable history. Store normalized decisions
|
|
31
|
+
and artifact references, never transcripts or internal reasoning.
|
|
32
32
|
|
|
33
|
-
A
|
|
34
|
-
|
|
33
|
+
A structural or authority rejection remains a mutable diagnostic. Correct the record;
|
|
34
|
+
do not invent a new decision merely to satisfy a state machine. Semantic disagreement
|
|
35
|
+
belongs in the recommendation and visible decision record, not a kernel error.
|
|
35
36
|
|
|
36
37
|
Return the conclusion, decisive evidence, uncertainty, affected authority, and the
|
|
37
38
|
model's recommended next explicit capability. Thinking never performs unrelated
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Owner interaction boundary
|
|
2
|
+
|
|
3
|
+
Use this reference only when a material choice remains after inspecting current
|
|
4
|
+
authority and observable facts. Ultra does not require a ceremonial question before
|
|
5
|
+
every write.
|
|
6
|
+
|
|
7
|
+
## Responsibility split
|
|
8
|
+
|
|
9
|
+
- The owner controls product intent, acceptance, non-goals, material tradeoffs, risk
|
|
10
|
+
acceptance, irreversible actions, external effects, and real-money commitments.
|
|
11
|
+
- The host model investigates facts, recommends a direction, makes reversible
|
|
12
|
+
implementation judgments, and explains uncertainty.
|
|
13
|
+
- Use the host-native question surface declared by the installed interaction contract;
|
|
14
|
+
prefer its structured form when the host exposes one.
|
|
15
|
+
- `ultra.record` persists only the normalized result and its provenance.
|
|
16
|
+
- MCP validates structure, identity, digests, CAS, leases, paths, and recovery. It does
|
|
17
|
+
not decide whether a product answer is good.
|
|
18
|
+
|
|
19
|
+
## Interaction sequence
|
|
20
|
+
|
|
21
|
+
1. Read `ultra.context` for the relevant scope.
|
|
22
|
+
2. Inspect source, runtime, tests, accepted artifacts, and primary documentation.
|
|
23
|
+
3. Reuse an explicit choice already present in the current request or an accepted
|
|
24
|
+
Decision Record.
|
|
25
|
+
4. Decide a reversible delegated detail without asking.
|
|
26
|
+
5. When owner authority is still required, ask one unresolved owner choice at a time
|
|
27
|
+
with:
|
|
28
|
+
- the recommendation;
|
|
29
|
+
- the discriminating evidence;
|
|
30
|
+
- the meaningful cost or failure mode;
|
|
31
|
+
- what changes when the answer changes.
|
|
32
|
+
6. Normalize the answer into a deterministic Decision Record and persist it with
|
|
33
|
+
`ultra.record` using `kind: decision`, `action: accept`.
|
|
34
|
+
7. Read `ultra.context` back and verify that the accepted decision is visible before
|
|
35
|
+
relying on it.
|
|
36
|
+
|
|
37
|
+
## Decision Record
|
|
38
|
+
|
|
39
|
+
Persist only:
|
|
40
|
+
|
|
41
|
+
- normalized question;
|
|
42
|
+
- recommendation and selected answer;
|
|
43
|
+
- effects and non-goals;
|
|
44
|
+
- owner, source, and bounded provenance;
|
|
45
|
+
- applied artifact references;
|
|
46
|
+
- supersession link when revising an earlier answer.
|
|
47
|
+
|
|
48
|
+
Never persist raw transcripts, hidden reasoning, full prompts, UI receipts, or copied
|
|
49
|
+
memory-provider payloads.
|
|
50
|
+
|
|
51
|
+
## Revisions and interruptions
|
|
52
|
+
|
|
53
|
+
Accepted decisions are immutable history. A changed answer creates a new Decision
|
|
54
|
+
Record that supersedes the prior record. A cancelled question writes nothing. If a
|
|
55
|
+
decision cannot be obtained, preserve the unresolved issue as a diagnostic or bounded
|
|
56
|
+
event; do not invent an answer or block unrelated work.
|