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.
Files changed (95) hide show
  1. package/.ultra-template/docs/research/README.md +4 -4
  2. package/.ultra-template/tasks/tasks.json +4 -2
  3. package/CHANGELOG.md +72 -0
  4. package/README.md +55 -39
  5. package/adapters/_shared/codex-assets.cjs +121 -65
  6. package/adapters/_shared/interaction-contract.cjs +7 -1
  7. package/adapters/_shared/provenance.cjs +7 -2
  8. package/adapters/_shared/runtime-assets.cjs +3 -2
  9. package/adapters/_shared/runtime-native.cjs +132 -0
  10. package/adapters/claude.js +60 -30
  11. package/adapters/codex.js +178 -81
  12. package/adapters/grok.js +372 -0
  13. package/adapters/kimi.js +7 -3
  14. package/adapters/opencode.js +210 -32
  15. package/agents/code-reviewer.md +4 -2
  16. package/agents/debugger.md +4 -1
  17. package/agents/review-code.md +7 -3
  18. package/agents/review-comments.md +7 -4
  19. package/agents/review-coordinator.md +11 -7
  20. package/agents/review-design.md +8 -4
  21. package/agents/review-errors.md +8 -4
  22. package/agents/review-spec.md +8 -5
  23. package/agents/review-tests.md +7 -4
  24. package/agents/tdd-runner.md +5 -2
  25. package/bin/install.js +9 -4
  26. package/bin/orchestrator.js +4 -13
  27. package/docs/AGENT-CONTEXT.md +143 -229
  28. package/docs/ARCHITECTURE.md +205 -494
  29. package/docs/ARTIFACT-AUTHORITY.md +35 -28
  30. package/docs/LEGACY-CLI-CROSSWALK.md +1 -1
  31. package/docs/PLUGIN-ISOLATION-CONTRACT.md +12 -9
  32. package/docs/ROADMAP.md +85 -110
  33. package/docs/RUNTIME-COMPAT-MATRIX.md +139 -175
  34. package/docs/SKILL-AUTHORING.md +3 -3
  35. package/docs/STATE-DB-ACCESS-POLICY.md +13 -8
  36. package/docs/WORKFLOW-LIFECYCLE.md +189 -448
  37. package/hooks/README.md +11 -8
  38. package/hooks/active_task_context.py +16 -16
  39. package/hooks/adapters/grok.py +134 -0
  40. package/hooks/{context_spine.py → context_envelope.py} +26 -22
  41. package/hooks/health_check.py +29 -34
  42. package/hooks/pre_stop_check.py +22 -12
  43. package/hooks/subagent_tracker.py +1 -1
  44. package/hooks/workflow_checkpoint.py +14 -13
  45. package/hooks/workflow_context.py +11 -12
  46. package/hooks/workflow_resume.py +14 -13
  47. package/mcp-server/{breadcrumb.cjs → hook-context.cjs} +7 -9
  48. package/mcp-server/lib/baseline-workflow.cjs +108 -82
  49. package/mcp-server/lib/canonical-json.cjs +19 -0
  50. package/mcp-server/lib/change-authority.cjs +26 -0
  51. package/mcp-server/lib/change-workflow.cjs +630 -45
  52. package/mcp-server/lib/context-envelope.cjs +508 -0
  53. package/mcp-server/lib/decision-records.cjs +337 -0
  54. package/mcp-server/lib/doctor.cjs +91 -33
  55. package/mcp-server/lib/init-project.cjs +78 -39
  56. package/mcp-server/lib/managed-file-write.cjs +116 -0
  57. package/mcp-server/lib/plan-checkpoint.cjs +177 -0
  58. package/mcp-server/lib/project-context.cjs +178 -0
  59. package/mcp-server/lib/stage-checkpoints.cjs +309 -0
  60. package/mcp-server/lib/state-db.cjs +155 -24
  61. package/mcp-server/lib/state-ops.cjs +21 -3
  62. package/mcp-server/lib/task-ledger.cjs +522 -13
  63. package/mcp-server/lib/ultra-facade.cjs +757 -442
  64. package/mcp-server/lib/worker-packet.cjs +358 -0
  65. package/mcp-server/server.cjs +200 -1103
  66. package/orchestrator/daemon.cjs +27 -9
  67. package/orchestrator/parallel-orchestrator.cjs +111 -76
  68. package/orchestrator/session-runner.cjs +135 -34
  69. package/package.json +10 -3
  70. package/skills/ultra-change/SKILL.md +10 -8
  71. package/skills/ultra-deliver/SKILL.md +17 -19
  72. package/skills/ultra-dev/SKILL.md +20 -11
  73. package/skills/ultra-doctor/SKILL.md +4 -4
  74. package/skills/ultra-init/SKILL.md +6 -5
  75. package/skills/ultra-init/references/brownfield-adoption.md +20 -14
  76. package/skills/ultra-plan/SKILL.md +13 -9
  77. package/skills/ultra-research/SKILL.md +18 -9
  78. package/skills/ultra-review/SKILL.md +14 -9
  79. package/skills/ultra-review/references/unified-schema.md +2 -0
  80. package/skills/ultra-review/scripts/review_wait.py +8 -0
  81. package/skills/ultra-status/SKILL.md +2 -2
  82. package/skills/ultra-test/SKILL.md +10 -6
  83. package/skills/ultra-think/SKILL.md +8 -7
  84. package/skills/ultra-think/references/interaction-boundary.md +56 -0
  85. package/spec/cli-protocol.md +80 -199
  86. package/spec/mcp-tools.yaml +43 -2806
  87. package/spec/schemas/state-db.sql +107 -4
  88. package/spec/schemas/{task-ledger.v1.schema.json → task-ledger.v2.schema.json} +70 -6
  89. package/ultra-tools/commands/status.cjs +369 -243
  90. package/mcp-server/lib/context-spine.cjs +0 -1208
  91. package/mcp-server/lib/decision-dialogue.cjs +0 -1128
  92. package/mcp-server/lib/project-breadcrumb.cjs +0 -173
  93. package/mcp-server/lib/spec-learning.cjs +0 -284
  94. package/mcp-server/lib/workflow-state.cjs +0 -3129
  95. 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.23.0",
4
- "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, and Kimi Code, with project-local MCP authority and lifecycle recovery.",
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/decision-dialogue.md` before asking. MCP may report
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 for `change.create` or `change.update`, relevant
31
- `decision.*`, and `change.delta` when the delta is already known. Every entry carries
32
- a stable idempotency key. Read the result through `ultra.context`.
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 reopens the draft and makes only genuinely dependent evidence
40
- stale. `ready` is not an absorbing state. A semantic rejection returns diagnostics;
41
- repair and retry the same draft. Use `workflow.abandon` only to preserve and cancel an
42
- attempt intentionally.
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: Converge a verified Ultra Change, reconcile baseline specifications, and archive it with recoverable local evidence. Use when implementation, testing, and review are current.
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. Require current task outcomes, test report, both review axes, accepted decisions,
16
- typed delta, documentation reconciliation, and current checkout evidence.
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 the reconciliation, report artifact, learning
25
- resolutions, and other durable facts.
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. The operation
31
- internally:
32
-
33
- - compiles or reuses convergence context;
34
- - checks the deliver draft;
35
- - derives convergence from current dev, test, review, delta, docs, and checkout;
36
- - applies the overlay and archive through the recoverable filesystem/DB transaction;
37
- - rebinds registered artifacts into a self-contained archive;
38
- - completes the durable delivery checkpoint;
39
- - publishes the updated team checkpoint.
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, current
9
- Context Manifest, execution lease, evidence references, and checkpoint.
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: admission }`, then
17
- `ultra.session { action: acquire }`. Work only in the returned worktree.
18
- 4. Confirm purpose, acceptance, dependencies, public seam, verification command,
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` batches for task status, bounded events, artifacts, decisions, and
30
- documentation candidates. Live ownership, `in_progress`, session ids, leases,
31
- worktrees, telemetry, and completion hashes remain local runtime state; durable task
32
- outcome and evidence may enter the team checkpoint.
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 compiles or reuses the implementation Context Manifest
41
- and validates the durable outcome. A rejection leaves the draft mutable.
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, failed semantic checkpoint, or awaiting
23
- owner decision is a warning, not corruption.
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 and
34
- `workflow.abandon` through `ultra.record` for intentional draft cancellation.
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/decision-dialogue.md` before asking a material
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
- operation: task.init_project
35
- data: target_dir, project_name, mode=auto, git_mode=auto, optional scope
36
- idempotency_key: stable init attempt id
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`: prevents trustworthy adoption;
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 non-blocking debt,
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
- non-blocking work. Every open `baseline_blocker` remains blocking. Do not convert the
65
- ledger into hundreds of application tasks.
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
- Call `baseline.record` with full replacement arrays for:
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. Call `baseline.converge` only after
86
- explicit approval. Set `accept_known_red` and `accept_dirty_worktree` only for the exact
87
- items the owner accepted.
88
-
89
- Resolve returned blockers through evidence or an owner decision, record the replacement
90
- snapshot, and retry. Adoption is complete only when `baseline.get` is `ready` and
91
- current, the gap ledger has no open blocker, and project doctor has no authority
92
- failure. Route all selected work through `ultra-change`, including work described by a
93
- legacy plan. Import its accepted intent into a current Change Contract before planning.
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/decision-dialogue.md` before asking a material
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 for all `task.create` and necessary `task.update`
37
- operations. Read back the draft with `ultra.context`.
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 checkpoint compiles or reuses the content-addressed Context Manifest, validates
51
- task coverage and dependencies, exports `plan.json` and `plan.md` once, completes the
52
- durable Plan, and publishes the team checkpoint. Do not export again after validation.
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 task contracts or evidence and
55
- retry. To discard it, record `workflow.abandon`; never edit SQLite or open a parallel
56
- run to escape a blocker.
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/decision-dialogue.md` before asking. Load only the
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 such as `artifact.record`,
38
- `decision.*`, `baseline.*`, `change.update`, or `change.delta`. Every entry needs a
39
- stable idempotency key. A rejected entry is a mutable diagnostic: fix the draft and
40
- retry; use `workflow.abandon` only when intentionally discarding that attempt.
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, record and converge the accepted baseline through
50
- `ultra.record`, then publish the team checkpoint with `ultra.sync { action: publish }`.
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
- If the checkpoint returns `accepted: false`, keep the same draft mutable, repair the
55
- reported evidence, and retry. Do not manufacture evidence or open a replacement run.
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
- Workers are read-only and use the host-native bounded-worker mechanism. Validate their
25
- artifacts with `scripts/review_wait.py` and
26
- `references/unified-schema.md`. Preserve every finding unchanged in `SUMMARY.json`;
27
- group duplicates only in the human summary.
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 checkpoint compiles or
35
- reuses review context and derives both axes from registered artifacts.
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 stale scope or evidence and retry;
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
- Workflow drafts: <active|blocked|ready> · accepted checkpoints=<current|stale>
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
- Host recommendation: <capability and concise rationale>
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
- Write an `ultra-test-report-v1` report below the owning Change. Bind exact acceptance
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.record`.
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 checkpoint compiles or reuses checking
32
- context and derives the verdict from the registered report.
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, repair evidence, and retry. Never weaken an
35
- assertion, hide a skip, or turn a warning into proof.
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/decision-dialogue.md`. Reuse a clear decision already present in the
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 for `decision.thread_start`, `decision.open`, the
29
- appropriate resolve/delegate/defer/supersede operation, the owning artifact mutation,
30
- and `decision.complete` when they are all known. Store normalized decisions and
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 semantic rejection remains a mutable diagnostic. Correct the record or intentionally
34
- abandon the draft; do not invent a new decision merely to satisfy a state machine.
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.