ultra-builder-pro-cli 0.26.1 → 3.0.2

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 (75) hide show
  1. package/.ultra-template/contexts/TEMPLATE.md +64 -29
  2. package/.ultra-template/north-star.md +36 -30
  3. package/.ultra-template/project-brief.md +28 -0
  4. package/.ultra-template/specs/product.md +4 -0
  5. package/.ultra-template/specs/research-distillate.md +8 -0
  6. package/.ultra-template/tasks.json +1 -0
  7. package/.ultra-template/test-report.json +18 -1
  8. package/CHANGELOG.md +227 -1
  9. package/README.md +161 -59
  10. package/adapters/_shared/host-profile.cjs +68 -12
  11. package/adapters/_shared/plugin-core.cjs +4 -5
  12. package/adapters/_shared/runtime-assets.cjs +11 -2
  13. package/adapters/zcode.js +375 -0
  14. package/bin/delegate-worker.cjs +20 -0
  15. package/bin/delegate.cjs +94 -25
  16. package/bin/install.js +11 -6
  17. package/docs/ARCHITECTURE.md +109 -25
  18. package/docs/ARTIFACT-AUTHORITY.md +204 -30
  19. package/docs/DECISIONS.md +141 -10
  20. package/docs/PHILOSOPHY.md +61 -8
  21. package/docs/PLUGIN-ISOLATION-CONTRACT.md +6 -0
  22. package/docs/RUNTIME-COMPAT-MATRIX.md +106 -13
  23. package/docs/SKILL-AUTHORING.md +14 -9
  24. package/docs/WORKFLOW-LIFECYCLE.md +211 -53
  25. package/docs/evals/adversarial-review-2026-08-14.md +84 -0
  26. package/docs/evals/zcode-automation-2026-08-14.md +103 -0
  27. package/hooks/README.md +31 -3
  28. package/hooks/_common.py +1699 -33
  29. package/hooks/adapters/zcode.py +227 -0
  30. package/hooks/compact_context.py +176 -17
  31. package/hooks/mid_workflow_recall.py +27 -5
  32. package/hooks/post_edit_guard.py +133 -23
  33. package/hooks/session_context.py +722 -11
  34. package/package.json +6 -3
  35. package/skills/ultra-change/SKILL.md +84 -64
  36. package/skills/ultra-change/references/change-contract.md +130 -32
  37. package/skills/ultra-change/references/execution-grant.md +109 -0
  38. package/skills/ultra-change/references/primary-transfer.md +273 -0
  39. package/skills/ultra-change/scripts/validate_primary_transfer.cjs +1928 -0
  40. package/skills/ultra-delegate/SKILL.md +38 -5
  41. package/skills/ultra-delegate/references/delegation-contract.md +21 -1
  42. package/skills/ultra-deliver/SKILL.md +123 -44
  43. package/skills/ultra-deliver/references/baseline-reconciliation.md +5 -3
  44. package/skills/ultra-dev/SKILL.md +173 -43
  45. package/skills/ultra-grilling/SKILL.md +19 -16
  46. package/skills/ultra-grilling/references/reframing.md +7 -3
  47. package/skills/ultra-init/SKILL.md +99 -87
  48. package/skills/ultra-init/references/brownfield-adoption.md +23 -40
  49. package/skills/ultra-init/scripts/init_project.cjs +968 -21
  50. package/skills/ultra-plan/SKILL.md +83 -46
  51. package/skills/ultra-plan/references/task-evidence-v2.md +300 -0
  52. package/skills/ultra-plan/scripts/validate_task_evidence.cjs +859 -0
  53. package/skills/ultra-research/SKILL.md +119 -68
  54. package/skills/ultra-research/references/{03-competitive-landscape.md → 03-alternatives.md} +6 -6
  55. package/skills/ultra-research/references/04-product-strategy.md +11 -2
  56. package/skills/ultra-research/references/21-features-scope.md +8 -0
  57. package/skills/ultra-research/references/22-success-metrics.md +9 -4
  58. package/skills/ultra-research/references/99-synthesis.md +25 -1
  59. package/skills/ultra-research/references/north-star-v2.md +168 -0
  60. package/skills/ultra-research/references/wayfinding.md +50 -0
  61. package/skills/ultra-research/scripts/validate_north_star.cjs +1174 -0
  62. package/skills/ultra-review/SKILL.md +201 -24
  63. package/skills/ultra-review/references/adversarial-evaluation.md +31 -0
  64. package/skills/ultra-review/references/spec.md +5 -0
  65. package/skills/ultra-review/references/unified-schema.md +146 -11
  66. package/skills/ultra-review/references/worker-packet.md +151 -8
  67. package/skills/ultra-review/scripts/review_wait.py +2653 -63
  68. package/skills/ultra-status/SKILL.md +146 -32
  69. package/skills/ultra-tdd/SKILL.md +14 -4
  70. package/skills/ultra-tdd/references/test-execution.md +6 -1
  71. package/skills/ultra-test/SKILL.md +157 -15
  72. package/skills/ultra-test/scripts/validate_review_transport.cjs +549 -0
  73. package/skills/ultra-test/scripts/worktree_digest.cjs +551 -29
  74. package/skills/ultra-think/SKILL.md +5 -10
  75. package/skills/ultra-think/references/interaction-boundary.md +2 -1
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "ultra-builder-pro-cli",
3
- "version": "0.26.1",
4
- "description": "File-first Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build.",
3
+ "version": "3.0.2",
4
+ "description": "File-first Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, Grok Build, and ZCode.",
5
5
  "bin": {
6
6
  "ultra-builder-pro-cli": "bin/install.js",
7
7
  "ubp": "bin/install.js"
@@ -38,6 +38,7 @@
38
38
  "docs/DECISIONS.md",
39
39
  "docs/PLUGIN-ISOLATION-CONTRACT.md",
40
40
  "docs/RUNTIME-COMPAT-MATRIX.md",
41
+ "docs/evals/*.md",
41
42
  "!**/*.pyc",
42
43
  "!**/*.pyo",
43
44
  "!**/*.test.cjs",
@@ -50,6 +51,7 @@
50
51
  "codex",
51
52
  "kimi-code",
52
53
  "grok-build",
54
+ "zcode",
53
55
  "agent",
54
56
  "cli",
55
57
  "multi-runtime",
@@ -81,9 +83,10 @@
81
83
  "install:claude": "node bin/install.js --claude --local",
82
84
  "install:kimi": "node bin/install.js --kimi --global",
83
85
  "install:grok": "node bin/install.js --grok --global",
86
+ "install:zcode": "node bin/install.js --zcode --global",
84
87
  "install:all": "node bin/install.js --all --global"
85
88
  },
86
89
  "dependencies": {
87
- "js-yaml": "^4.1.0"
90
+ "js-yaml": "^4.3.1"
88
91
  }
89
92
  }
@@ -1,59 +1,60 @@
1
1
  ---
2
2
  name: ultra-change
3
- description: Open one bounded unit of work by first reconciling what the specifications promise against what the code actually does, then writing the intent that closes the gap. Use when nothing is in flight and something new is being asked for — a feature, a fix, a redesign, or an incident response.
3
+ description: Open or reconcile one bounded unit of work by comparing specification promises with actual code, then writing the intent that closes the gap. Use when no Change is active and a feature, fix, redesign, or incident response is requested, or when an active Change's draft, researched evidence, or accepted boundary must be reconciled.
4
4
  ---
5
5
 
6
6
  # Reconcile first, then write down what this Change commits to
7
7
 
8
- A Change is the durable unit connecting research, plan, implementation,
9
- verification, review and delivery. Reconciliation comes first because writing new
10
- intent on top of specifications that already disagree with the code buries the
11
- disagreement instead of resolving it.
8
+ A Change connects research, plan, implementation, verification, review, and delivery.
9
+ Reconcile first so new intent does not bury an existing specification/code conflict.
12
10
 
13
11
  ## Before you start
14
12
 
15
- 1. Read `.ultra/tasks.json`, and the `context_file` of any task not yet finished.
16
- 2. Read `CONTEXT.md` for vocabulary and `.ultra/decisions/` for entries in scope.
17
- 3. Read `.ultra/north-star.md` — a Change that does not serve it is worth
18
- questioning out loud before it is written down.
19
- 4. Grep `.ultra/changes/archive/` for Changes that already touched this area. Read
20
- `delivery.md` when present; otherwise read `archive-summary.md`, `verification.md` and
21
- remaining owner-readable Markdown. A missing `delivery.md` does not mean no history;
22
- a module that keeps reappearing is an architecture signal.
13
+ 1. Read `references/change-contract.md` and apply its **Active Change authority
14
+ resolution** before reading any active `intent.md`, relying on a current `change_id`,
15
+ or creating or writing a Change. Continue only from its positively observed stable
16
+ zero-or-one result; return its typed repair for any other result. With one active
17
+ Change, read `.ultra/tasks.json`, then only its unfinished `context_file` values.
18
+ Update the same `change_id`; never open a second active Change.
19
+ 2. Read `.ultra/project-brief.md`, `CONTEXT.md`, relevant `.ultra/decisions/`, and
20
+ `.ultra/north-star.md` for raw provenance, accepted language, and direction.
21
+ 3. Grep archive and abandoned Changes that touched this area. Prefer archived
22
+ `delivery.md`; otherwise read `archive-summary.md`, `verification.md`, `intent.md`,
23
+ and remaining Markdown. Read abandoned Changes as history of rejected boundaries and
24
+ reusable evidence, never current intent. A missing `delivery.md` does not mean no history;
25
+ repeated modules are an architecture signal.
23
26
 
24
27
  ## Whether this skill applies at all
25
28
 
26
29
  | Situation | Where it goes |
27
30
  |---|---|
28
- | No pending or in-progress task, and something new is asked for | Here |
31
+ | No active Change, and a new bounded request exists | Here — create one stable id |
32
+ | One active Change needs its draft, Research evidence, or accepted boundary reconciled | Here — update the same `change_id` |
33
+ | A separate request arrives while one Change remains active | Do not create a second Change; finish or deliver the current one, abandon it with owner authority, or explicitly fold the request into its boundary |
29
34
  | A task is in progress and the specification turns out not to match reality | Not here — the dual-write path inside `ultra-dev` |
30
- | The change makes no sentence in the specifications false | Neither — just make the change |
35
+ | The change makes no sentence in the specifications false | Outside the Ultra lifecycle — use ordinary repository TDD and verification |
31
36
 
32
- That third row is the checkable answer to "how small is too small to deserve a
33
- Change file": if nothing the specifications say becomes untrue, there is nothing
34
- to reconcile and nothing to record.
37
+ If no specification sentence becomes untrue, there is nothing to reconcile. Use
38
+ `../ultra-tdd/SKILL.md` when helpful, but create no Change artifacts or Ultra
39
+ Test/Deliver claim for that micro change.
35
40
 
36
41
  ## Definition of done
37
42
 
38
- - `.ultra/changes/active/<id>/intent.md` states the observable outcome, the
39
- executable acceptance, the non-goals, and the public seams touched.
40
- - Each of the three reconciliation buckets is either empty or dispositioned, with
41
- the owner's answer recorded for every bucket that was not empty.
42
- - The draft stays editable until then; the owner's acceptance is what turns it
43
- into authority.
43
+ - Active `intent.md` states outcome, typed acceptance with named required evidence,
44
+ non-goals, public seams,
45
+ and Research Disposition.
46
+ - Every reconciliation bucket is empty or dispositioned with the owner's answer.
47
+ - The draft remains editable until owner acceptance makes it authority.
44
48
 
45
49
  ## Reconcile against a bounded scope
46
50
 
47
- A whole-repository diff is unusable, so derive the scope with four steps anyone
48
- can rerun:
51
+ A Change does not rebuild the project baseline; reconcile only the touched specification sections
52
+ and leave unrelated gaps visible with four rerunnable steps:
49
53
 
50
54
  1. Decide which specification sections this request touches.
51
- 2. For each section, collect the past tasks whose `trace_to` points at it, and
52
- from those the set of code files they changed.
53
- 3. `git log -- .ultra/specs/<file>` gives the commit where that specification
54
- last changed.
55
- 4. `git diff <that commit>..HEAD -- <those code files>` is the reconciliation
56
- scope.
55
+ 2. Collect past tasks whose `trace_to` points there and the code files they changed.
56
+ 3. Use `git log -- .ultra/specs/<file>` to find its last specification change.
57
+ 4. Inspect `git diff <that commit>..HEAD -- <those code files>`.
57
58
 
58
59
  Sort what you find into three buckets, each with your recommended disposition:
59
60
 
@@ -63,47 +64,63 @@ Sort what you find into three buckets, each with your recommended disposition:
63
64
  | Code implements it, no specification says so | Built and unpromised |
64
65
  | Both speak and they conflict | Contradictory |
65
66
 
66
- Take the buckets to the owner — confirmed rather than assumed, because a
67
- disposition can quietly withdraw a commitment. Sort by risk first and match the
68
- asking to it: anything that touches a `HC-<n>` hard constraint or removes
69
- something already promised goes one at a time with your recommendation; the
70
- remaining low-risk rows go as a single list with a recommended disposition each,
71
- for one confirmation. Twenty separate questions about rows that change nothing
72
- spends the owner's attention where it was not needed, and trains them to approve
73
- without reading.
67
+ Take non-empty buckets to the owner because disposition can withdraw a commitment.
68
+ Ask one recommended question per `HC-<n>` impact or removed promise; group remaining
69
+ low-risk rows into one recommended list for confirmation.
74
70
 
75
71
  ## Write the intent
76
72
 
77
- Read `references/change-contract.md` and use its exact `intent.md` headings. The active
78
- Change directory contains only this accepted contract until planning or delivery adds
79
- its defined artifacts; do not invent a parallel semantic record.
73
+ Read `references/change-contract.md` and use its exact headings. Until planning or
74
+ delivery, the active directory contains only this contract; add no parallel record.
80
75
 
81
- Follow `../ultra-grilling/SKILL.md` to settle the boundary — one question at a
82
- time, each with your recommendation. New domain terms go through
83
- `../ultra-domain-modeling/SKILL.md`.
76
+ Use `../ultra-grilling/SKILL.md` to settle the boundary and
77
+ `../ultra-domain-modeling/SKILL.md` for new domain terms.
84
78
 
85
- When the work is too large *and* the path itself is unclear, follow
86
- `../ultra-think/SKILL.md` for a decision ticket instead of forcing a task
87
- breakdown. What comes out is a question whose answer is a decision, not an
88
- implementation slice.
79
+ Use `../ultra-think/SKILL.md` only for one consequential evidenced trade-off. If the
80
+ whole path is unclear, recommend Research instead of manufacturing tasks.
89
81
 
90
- When reconciliation proves the request is a directly executable one-slice correction,
91
- follow `../ultra-tdd/SKILL.md` at the confirmed public seam instead of manufacturing a
92
- task graph merely to satisfy ceremony.
82
+ Record `## Research Disposition` exactly. `none` needs enough evidence to plan;
83
+ `bounded` or `required` names one question, selected lenses, and exit evidence. After
84
+ Research, reconcile outputs here; an unverified path or bare claim is not evidence.
85
+ Record one `## North Star Trace` with resolving `FP-<n>`/`NS-<n>`/`HC-<n>` ids, causal
86
+ evidence, the accepted revision, the current Git blob digest, and any contradiction
87
+ requiring owner disposition. Reference IDs only; do not mirror North Star prose.
93
88
 
94
- Output is `.ultra/changes/active/<id>/intent.md`, the specification patches
95
- reconciliation justified, possibly a `.ultra/decisions/<id>.md`, and any
96
- vocabulary update. Recommend `ultra-research` for a real evidence gap or
97
- `ultra-plan` once the contract is evidenced enough; do not invoke either.
89
+ When Research accepts a revision whose id or digest differs from an active Change trace,
90
+ that active Change has a stale observation, not a semantic failure. Preserve its intent,
91
+ tasks, review, Test, and delivery evidence; reconcile old IDs to the accepted revision,
92
+ surface contradictions for owner disposition, and invalidate any plan-bound execution
93
+ approval through its own contract. Never silently rewrite the North Star or infer that a
94
+ replacement grants execution.
95
+
96
+ Every active Change still goes through `ultra-plan`; once durable intent exists, the
97
+ smallest evidence-backed task graph for its real seams binds development, review,
98
+ audit, and delivery to the stable `change_id`. The profile never fixes task or context
99
+ count.
100
+
101
+ Output active `intent.md` under a stable id, justified specification patches, qualifying
102
+ decision or vocabulary updates. For an evidence gap recommend `ultra-research`; when
103
+ evidenced recommend `ultra-plan`. Invoke neither.
98
104
 
99
105
  ## Abandoning a Change
100
106
 
101
- A Change that turns out to be the wrong thing to build exits by
102
- `git mv .ultra/changes/active/<id> .ultra/changes/abandoned/<id>`, plus one line in
103
- its `intent.md` saying why. Completed tasks keep their evidence; the work is
104
- unlinked from the frontier, not deleted. This is the owner's call and a cheap one —
105
- a Change kept alive to avoid admitting it was wrong poisons every later
106
- reconciliation, which then measures the code against promises nobody intends to keep.
107
+ Append the exact `## Abandonment` closure from `references/change-contract.md`, then
108
+ `git mv .ultra/changes/active/<id> .ultra/changes/abandoned/<id>`. Keep completed-task
109
+ evidence. Future Change and Status consume this history; it is neither current intent
110
+ nor an orphan. Abandonment is the owner's call.
111
+
112
+ ## When the primary writer changes Agent
113
+
114
+ When the owner moves the canonical implementation authority of an active
115
+ work package to another Agent, follow `references/primary-transfer.md` exactly:
116
+ the sender writes current reality into the task context and its Resume Note,
117
+ derives the OFFER from canonical files and Git, and stops writing after the
118
+ receiver's ready ACK; the receiver stable-reads, verifies every digest, and
119
+ becomes the sole canonical writer. A delegated worker slice is never a
120
+ substitute — `ultra-delegate` owns the mutually exclusive bounded-worker path.
121
+ Validate receipts with
122
+ `scripts/validate_primary_transfer.cjs`; the report is structural observation,
123
+ never an acceptance.
107
124
 
108
125
  ## When the owner decides
109
126
 
@@ -114,6 +131,9 @@ specification sentence false needs no permission at all.
114
131
  ## References
115
132
 
116
133
  - `../ultra-grilling/SKILL.md` — the loop for settling the boundary.
117
- - `references/change-contract.md` — exact `intent.md` structure and profile fields.
134
+ - `references/change-contract.md` — canonical Active Change authority resolution, exact
135
+ `intent.md` structure, and profile fields.
136
+ - `references/execution-grant.md` — read when the owner requests bounded workflow continuation under a session-local or durable grant.
137
+ - `references/primary-transfer.md` — read when the owner moves the work package's canonical writer to another Agent (OFFER → ACK → RESULT).
118
138
  - `../ultra-think/references/autonomy-boundary.md` — read before removing a promise.
119
139
  - `../ultra-tdd/SKILL.md` — read for an evidenced one-slice correction.
@@ -3,6 +3,40 @@
3
3
  Create one contract before planning. Keep every field specific enough to verify and
4
4
  stable enough to survive a fresh session.
5
5
 
6
+ The directory id is globally unique across active, archive, and abandoned Changes and
7
+ matches `[A-Za-z0-9][A-Za-z0-9._-]*`. It is the stable `change_id`; moving the directory
8
+ never changes it.
9
+
10
+ ## Active Change authority resolution
11
+
12
+ Every Skill that selects a current `change_id`, reads active intent, or creates a new
13
+ Change must first use native host filesystem checks to apply this instruction contract.
14
+ It is not a parser, registry, or persisted state.
15
+ A positively observed absent `.ultra` is the existing uninitialized condition:
16
+ `ultra-status` may recommend `ultra-init`, while writers write nothing. This known
17
+ absence is distinct from an unavailable observation. Otherwise:
18
+
19
+ 1. Require `.ultra`, `.ultra/changes`, and `.ultra/changes/active` to be a stable chain
20
+ of ordinary non-symlink directories with the same no-follow identities before and
21
+ after selection.
22
+ 2. Stable-list every active-root entry without following symlinks. Only `.gitkeep`,
23
+ when it is an ordinary regular non-symlink file, may be ignored. A `.gitkeep` of any
24
+ other type is malformed, is never a Change directory, and returns a typed diagnostic
25
+ with repair before any candidate intent is read. Every other non-directory or symlink
26
+ entry returns a typed diagnostic with a reachable repair before any intent read.
27
+ 3. A positively observed stable empty root, with or without that sole marker, means no
28
+ active Change. Active authority exists only when exactly one ordinary non-symlink
29
+ Change directory remains. More than one returns a typed conflict and repair; select
30
+ none of them.
31
+ 4. Require the selected directory's own `intent.md` to be a stable regular non-symlink
32
+ file opened with no-follow behavior. Capture one bounded snapshot, then recheck the
33
+ directory chain, active-root entries, selected directory, and intent identity before
34
+ consuming its contents.
35
+ 5. On any unavailable observation or changed identity, stop with a typed diagnostic and
36
+ reachable retry or repair. Do not read any intent, route from it, write any workflow
37
+ artifact, or create a new Change. Only a positively observed stable zero-directory
38
+ result permits `ultra-change` to create one.
39
+
6
40
  ## Exact `intent.md` structure
7
41
 
8
42
  ```markdown
@@ -10,12 +44,14 @@ stable enough to survive a fresh session.
10
44
 
11
45
  > **Status**: draft | accepted
12
46
  > **Profile**: quick | standard | major | incident
47
+ > **Profile rationale**: <why the smallest selected profile covers the blast radius>
48
+ > **Risk flags**: <applicable flags, or none>
13
49
 
14
50
  ## Outcome
15
51
  <one externally observable result>
16
52
 
17
53
  ## Acceptance
18
- | ID | Criterion | Verification | Trace |
54
+ | ID | Criterion | Verification type | Required evidence |
19
55
  |---|---|---|---|
20
56
 
21
57
  ## Non-goals
@@ -29,6 +65,36 @@ stable enough to survive a fresh session.
29
65
  ### Built and Unpromised
30
66
  ### Contradictory
31
67
 
68
+ ## Research Disposition
69
+ - Disposition: none | bounded | required
70
+ - Question: <the exact load-bearing unknown, or none>
71
+ - Selected lenses: <reference ids, or none>
72
+ - Existing evidence: <repository-relative paths and claims>
73
+ - Required exit evidence: <what must exist or be resolved before planning>
74
+ - Rationale: <why this is sufficient for this Change boundary>
75
+
76
+ ## North Star Trace
77
+ - First principles: <FP-<n> ids and the causal premise>
78
+ - Serves: <NS-<n> ids and the causal contribution>
79
+ - Touches: <HC-<n> ids, or none>
80
+ - Evidence: <repository-relative paths and claims>
81
+ - North Star revision: <accepted Revision field from `.ultra/north-star.md`>
82
+ - North Star digest: <output of `git hash-object .ultra/north-star.md`>
83
+ - Contradictions or refinements: <none, or the owner disposition still required>
84
+
85
+ ## Execution Grant
86
+
87
+ - Grant: `session-local` (default) | `durable work-package` <grant-id>
88
+ - Allowed workflows: <subset of research, plan, dev, test, deliver-reconcile>
89
+ - Agent topology: <single-Agent default, or the owner-selected providers, counts, and write scopes>
90
+ - Allowed local effects: <exact authorized local writes, tests, and bounded verification>
91
+ - Budgets and expiry: <time, cost, tool, provider, delegation, review-round ceilings and expiry>
92
+ - Mandatory reviews: <plan, task, and aggregate Change requirements>
93
+ - Stop conditions: <named semantic, evidence, recovery, and budget stops>
94
+ - Invalidation: <conditions that end the grant and return control to the owner>
95
+ - Never granted: <new Change, baseline checkpoint, finalization/archive, external effects, cross-family provider calls>
96
+ - Activation: <session-local: a current-session owner utterance approving this grant and the current task ledger; durable: stable verification of the recorded grant — stored text alone is inactive>
97
+
32
98
  ## Planning Posture
33
99
  <EXPAND | SELECTIVE | HOLD | REDUCE, rationale, and owner confirmation>
34
100
  <!-- Scope for this Change only. Not the commitment classification: REDUCE here
@@ -49,10 +115,11 @@ heading, and do not add another file that restates the same contract.
49
115
  ## Contract fields
50
116
 
51
117
  - `outcome`: one externally observable result.
52
- - `acceptance`: stable ids, one criterion each, and a `Verification` that is an
53
- **executable command** — something with an exit code, not a description of an
54
- intention. `curl -sf localhost:3000/health` qualifies; "check that the endpoint
55
- responds" does not.
118
+ - `acceptance`: stable ids, one criterion each, one verification type, and exact
119
+ required evidence. The supported types are `command`, `inspection`,
120
+ `owner-judgment`, and `external-observation`. When one outcome needs more than one
121
+ authority, split it into independent criteria with unique IDs and keep one
122
+ verification type per criterion. A row must not carry multiple verification types.
56
123
  - `non_goals`: explicit boundaries that prevent accidental scope growth.
57
124
  - `public_seams`: entry points or outputs through which acceptance is observed.
58
125
  - `recovery`: a bounded reversal or recovery strategy and its verification.
@@ -61,41 +128,72 @@ heading, and do not add another file that restates the same contract.
61
128
  Resolve every blocking decision before planning. Keep non-blocking uncertainty visible
62
129
  in the task and verification contracts.
63
130
 
64
- ## Why verification has to be executable
65
-
66
- A criterion whose verification cannot be run is not acceptance, it is a wish. Three
67
- consumers downstream depend on it being runnable:
68
-
69
- - task development can treat passing acceptance as an exit condition only when
70
- something can actually decide "passing";
71
- - the review tests lens maps each acceptance claim to executable evidence, and can
72
- only report an honest gap when there is something to map onto;
73
- - delivery cannot otherwise separate "shipped" from "believed shipped".
74
-
75
- Writing the command is also the cheapest way to find out that a criterion is vague.
76
- "The feature is wired up" resists a command until it becomes "this export has a
77
- non-test importer", which is a `grep`.
78
-
79
- Where a criterion is genuinely a judgement call — visual polish, wording, feel — it
80
- does not belong in Acceptance at all. Record it as a taste decision for the owner and
81
- keep Acceptance to what a machine can settle. Mixing the two is what makes an
82
- acceptance set undecidable.
131
+ `North Star Trace` is the Change-level semantic trace. `First principles`, `Serves`, and
132
+ `Touches` ids must resolve in `.ultra/north-star.md`; `Evidence` explains the causal
133
+ claim rather than merely naming the file. Revision and digest are freshness observations.
134
+ A mismatch returns the intent to reconciliation and never mechanically declares
135
+ alignment or contradiction. Preserve historical evidence while reconciliation maps old
136
+ IDs, records contradictions, and obtains any material owner disposition.
137
+
138
+ Every Change records an `Execution Grant`; `session-local` is the default and a
139
+ durable grant requires an exact owner record. The exact mode behavior,
140
+ activation, and durable-verification rules live in `execution-grant.md`. The
141
+ grant bounds native model continuation; it is not persisted route authority.
142
+
143
+ ## Why verification has to name its authority
144
+
145
+ Acceptance is only auditable when the observation and its authority are explicit:
146
+
147
+ - `command` records the exact command, working directory, exit status, and retained raw
148
+ output reference;
149
+ - `inspection` cites the exact file, revision or digest, and the observed fact;
150
+ - `owner-judgment` cites the durable owner disposition without replacing it with a
151
+ machine proxy; only the owner can supply its semantic result;
152
+ - `external-observation` records the provider or environment, run identity, observation
153
+ time, and retained raw result.
154
+
155
+ Development, Review, Test, and Deliver may verify that the required evidence exists,
156
+ is fresh, and is bound to the criterion. They must not turn a command exit code, regex,
157
+ digest, or schema result into a semantic verdict for an inspection, owner judgment, or
158
+ external observation. Missing or stale evidence returns a typed gap to the responsible
159
+ model or owner; it never silently deletes the criterion or manufactures acceptance.
160
+ A validator owns exact structure, identity, and provenance only; validator success is
161
+ never a semantic pass.
83
162
 
84
163
  ## Profile
85
164
 
86
- - `quick`: one low-risk task, no material risk flags, and no research dependency.
87
- - `standard`: a bounded change with multiple tasks or ordinary integration risk.
165
+ - `quick`: a bounded low-risk change with no material risk flags and no research dependency.
166
+ - `standard`: a bounded change with ordinary integration risk.
88
167
  - `major`: a broad or consequential change with material contract, migration,
89
168
  authorization, security, multi-module, external-integration, or release impact.
90
169
  - `incident`: urgent diagnosis and recovery with a reproducible symptom. Baseline
91
170
  break-glass still requires a recorded approver and recovery contract.
92
171
 
93
172
  Record a profile rationale and every applicable risk flag. Select the smallest profile
94
- whose guarantees cover the real blast radius; never use profile labels as estimates.
173
+ whose guarantees cover the real blast radius; never use profile labels to prescribe a
174
+ task count, file count, review effort, or estimate.
95
175
 
96
- ## Research disposition
176
+ ## Research Disposition
97
177
 
98
- Use `none` with a rationale when accepted evidence is sufficient. Use `bounded` or
99
- `required` with a supported mode and the exact selected semantic steps when product,
100
- behavior, architecture, deployment, or risk facts remain load-bearing. The recorded
101
- selection is the planning gate.
178
+ The `Disposition` value is exactly `none | bounded | required`. Use `none` with a
179
+ rationale when accepted evidence is sufficient. Use `bounded` for one already-framed
180
+ question whose smallest sufficient lenses are known; it skips Wayfinding. Use `required`
181
+ when several load-bearing claims or the evidence path itself remain unclear, so Research
182
+ may Wayfind before selecting lenses. Both name the exact question, selected or candidate
183
+ Research lenses, existing evidence, and required exit evidence.
184
+ The host model evaluates whether the named evidence exists and supports the claim; do
185
+ not add a `research_complete` bit, score, or workflow state. Planning waits while the
186
+ recorded exit evidence is unsatisfied.
187
+
188
+ ## Exact abandonment closure
189
+
190
+ Before moving an owner-abandoned Change, append this exact structure to `intent.md`:
191
+
192
+ ```markdown
193
+ ## Abandonment
194
+ - Date:
195
+ - Owner decision:
196
+ - Reason:
197
+ - Reusable evidence:
198
+ - Recovery or successor:
199
+ ```
@@ -0,0 +1,109 @@
1
+ # Change-scoped execution grants (session-local or durable)
2
+
3
+ Use this reference only after the owner has accepted one active Change and wants
4
+ an Agent to continue through a bounded local execution segment. The host's
5
+ native model-tool loop is the executor; repository authority and ordinary
6
+ workflow contracts remain unchanged.
7
+
8
+ Ultra Builder Pro 3.0 has exactly two grant modes. Choosing a duration is not
9
+ choosing a second product:
10
+
11
+ - **Mode A — `session-local`** (the default): the owner's authorization lives
12
+ only in the current conversation. A fresh Agent may read the files for
13
+ context, but must obtain a new activation from the owner before continuing.
14
+ When the conversation activation is lost — a fresh session, another host, or
15
+ compaction — the work stops.
16
+ - **Mode B — `durable work-package`**: the owner explicitly issues an exact
17
+ grant so one named work package can continue across sessions, hosts, and
18
+ compaction. A fresh Agent or host may continue that package only after
19
+ stably verifying the recorded grant.
20
+
21
+ Neither mode grants finalization or archive: writing `delivery.md`, deciding
22
+ version or package posture, and moving a Change to archive always require a
23
+ current explicit owner invocation, in every mode.
24
+
25
+ ## What a grant is not
26
+
27
+ - A grant is not inferred from task status, progress records, prose, Hook
28
+ output, Resume notes, or a stored quote. Stored grant text is inactive data
29
+ until a consuming Agent verifies it.
30
+ - A grant never includes external or irreversible effects by default: commit,
31
+ push, tag, publication, deployment, real installation, credentials, and
32
+ incremental provider spend each require their own current owner
33
+ authorization, even under a durable grant.
34
+ - A grant is not a daemon, scheduler, or auto-wake: it answers "may this
35
+ continued work proceed", not "who runs next".
36
+ - An Agent cannot create, widen, or extend its own grant. A topology or scope
37
+ change returns to the owner.
38
+
39
+ ## Session-local activation
40
+
41
+ All of these must be true:
42
+
43
+ - the active `intent.md` is accepted and its North Star Trace is current;
44
+ - the same session contains an explicit owner utterance naming the grant and
45
+ approving the current task ledger;
46
+ - the next workflow is listed under `Allowed workflows` and remains inside every
47
+ budget;
48
+ - the model can still point to that utterance in current conversation context.
49
+
50
+ After a fresh session, a different host, or compaction that no longer contains
51
+ the activation, stop and ask the owner to re-activate after `ultra-status`
52
+ reconstructs the files.
53
+
54
+ ## Durable grant verification
55
+
56
+ Before relying on a recorded `durable work-package` grant, a fresh Agent must
57
+ stably verify, from the repository alone:
58
+
59
+ 1. the grant record's exact bytes and its cited accepted-design digest (for
60
+ example the SHA-256 recorded in the owner decision);
61
+ 2. the repository identity and base HEAD the grant names;
62
+ 3. the current work-package status (the implementation WIP or Change intent);
63
+ 4. the grant's subject, scope, Agent topology, allowed local effects,
64
+ budgets/expiry, review budget, invalidation, and revocation clauses;
65
+ 5. that no invalidation condition has fired.
66
+
67
+ Any mismatch, ambiguity, or unknown stops the work and returns to the owner.
68
+ Handoff passes the grant identity (path and digest); it never copies a new
69
+ authorization prose into a second file.
70
+
71
+ ## Continuing the native loop
72
+
73
+ After one workflow reaches its own observable completion, reread the intent,
74
+ ledger, current evidence, review results, and budgets. If no stop condition
75
+ applies, select the next covered workflow through the host's native Skill
76
+ surface. Run one ready task at a time; never parallelize canonical writes. When
77
+ the owner has not selected a multi-Agent topology, the current Agent continues
78
+ alone: no automatic spawning, delegation, or control-plane enablement.
79
+
80
+ A grant-covered Deliver run may reconcile, review, and report, and then stops
81
+ before finalization: its inputs, writes, and effects end at the report. Only a
82
+ current explicit owner invocation of `ultra-deliver` may write `delivery.md`,
83
+ decide version or package posture, or archive the Change.
84
+
85
+ Do not add a route ledger or progress authority. Task status, existing
86
+ evidence, review artifacts, the Test report, and Git remain the observations
87
+ the model interprets.
88
+
89
+ ## Budgets, stops, and termination
90
+
91
+ Each budget is a hard ceiling and a resource observation, never evidence of
92
+ semantic completion. Stop immediately for a REDUCTION, a North Star
93
+ contradiction or stale trace, an unmet owner checkpoint, `Stalled` or
94
+ `Unreachable` development, a disputed or unresolved P0/P1 finding,
95
+ residual-risk acceptance, task-graph drift, lost activation (session-local) or
96
+ failed grant verification (durable), or budget exhaustion. Report completed
97
+ evidence and the cheapest safe next action.
98
+
99
+ A grant never authorizes a new Change, a baseline acceptance, scope or risk
100
+ acceptance, finalization or archival, external or irreversible effects, or
101
+ cross-family provider calls beyond its recorded topology. Review terminates
102
+ under the accepted convergence contract, and its precedence is one rule: an
103
+ exact current owner grant overrides the versioned product default of
104
+ one initial review plus at most two
105
+ P0/P1 delta reviews per coherent work package.
106
+ P2/P3 findings are reported and never auto-repaired, no budget extends itself,
107
+ and the same root cause surviving three failed fixes stops point-patching and
108
+ reports an architecture problem. Existing host permission and destructive-effect
109
+ guards remain in force.