ultra-builder-pro-cli 0.26.0 → 0.26.2

package/hooks/README.md

@@ -5,18 +5,25 @@ directory and exits silently when the workflow is not active.
 
 | Hook | Lifecycle | Purpose |
 |---|---|---|
-| `session_context.py` | Session start | Inject the one-line north star and current acceptance criteria |
-| `mid_workflow_recall.py` | Before source reads or edits | Restate current acceptance only |
+| `session_context.py` | Session start | Inject the accepted North Star or Project Brief fallback, plus acceptance from the unique active Change's current task |
+| `mid_workflow_recall.py` | Before source reads or edits | Restate acceptance only for a task matching the unique active `change_id` |
 | `compact_context.py` | Before/after compaction | Save and restore a disposable snapshot derived from files and Git |
 | `post_edit_guard.py` | After edits | Record mechanical evidence observations without deciding completion |
-| `block_dangerous_commands.py` | Before shell execution | Block a narrow named external effect until the exact command is owner-authorized |
+| `block_dangerous_commands.py` | Before shell execution | Advise on additive protected-branch publication; block history rewrites and a narrow destructive set until the exact command is owner-authorized |
 
 `_common.py` is a shared library, not a lifecycle registration. Compact snapshots and
 progress observations live under ignored `.ultra/.runtime/` or `.ultra/progress/`; the
 canonical semantic facts remain the owner-readable files and Git.
+Legacy task rows with no `change_id` remain readable from an active-path `change_ref`
+during migration; a present canonical `change_id` always wins, and archived or
+abandoned paths are never revived as current work. Task
+selection prefers the single `in_progress` row, then the first `pending` row whose
+same-Change dependencies are complete; ambiguous concurrent work stays silent.
 
 Claude Code runs the hooks directly. Codex, Kimi Code, and Grok Build use the small
 wire adapters under `hooks/adapters/`. OpenCode calls the same scripts from its native
 JavaScript plugin. A hook failure is advisory except for the explicitly classified
-external effects in `block_dangerous_commands.py`, whose denial includes a reachable
-SHA-256-scoped authorization path.
+destructive effects in `block_dangerous_commands.py`, whose denial includes a reachable
+SHA-256-scoped authorization path. Additive protected-branch publication stays advisory
+because portable hooks cannot consume every host's trusted owner-approval receipt;
+history rewrites and branch deletion remain guarded.

package/hooks/_common.py

@@ -47,12 +47,61 @@ def read_tasks(root: Path) -> list[dict[str, Any]]:
     return [item for item in tasks if isinstance(item, dict)] if isinstance(tasks, list) else []
 
 
+def active_change_id(root: Path) -> str | None:
+    active = root / ".ultra" / "changes" / "active"
+    try:
+        change_ids = sorted(
+            entry.name
+            for entry in active.iterdir()
+            if entry.is_dir() and (entry / "intent.md").is_file()
+        )
+    except OSError:
+        return None
+    if len(change_ids) != 1:
+        return None
+    change_id = change_ids[0]
+    return change_id if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", change_id) else None
+
+
+def legacy_task_change_id(task: dict[str, Any]) -> str | None:
+    value = task.get("change_ref")
+    if not isinstance(value, str):
+        return None
+    match = re.fullmatch(
+        r"(?:\.ultra/)?changes/active/([A-Za-z0-9][A-Za-z0-9._-]*)/intent\.md",
+        value,
+    )
+    return match.group(1) if match else None
+
+
 def current_task(root: Path) -> dict[str, Any] | None:
-    tasks = read_tasks(root)
-    for status in ("in_progress", "pending"):
-        for task in tasks:
-            if task.get("status") == status:
-                return task
+    change_id = active_change_id(root)
+    if change_id is None:
+        return None
+    tasks = [
+        task for task in read_tasks(root)
+        if task.get("change_id") == change_id
+        or ("change_id" not in task and legacy_task_change_id(task) == change_id)
+    ]
+    in_progress = [task for task in tasks if task.get("status") == "in_progress"]
+    if len(in_progress) == 1:
+        return in_progress[0]
+    if len(in_progress) > 1:
+        return None
+    by_id = {task.get("id"): task for task in tasks if isinstance(task.get("id"), str)}
+    for task in tasks:
+        if task.get("status") != "pending":
+            continue
+        dependencies = task.get("dependencies", [])
+        if not isinstance(dependencies, list):
+            continue
+        if all(
+            isinstance(dependency, str)
+            and dependency in by_id
+            and by_id[dependency].get("status") == "completed"
+            for dependency in dependencies
+        ):
+            return task
     return None
 
 

package/hooks/block_dangerous_commands.py

@@ -7,11 +7,88 @@ import hashlib
 import json
 import os
 import re
+import shlex
 import subprocess
 
 from _common import emit_context, project_root, read_payload
 
 
+APPROVAL_VAR = "UBP_DANGEROUS_COMMAND_APPROVED"
+APPROVAL_PREFIX = re.compile(rf"^\s*{APPROVAL_VAR}=\S*\s+")
+
+HEREDOC = re.compile(
+    r"<<-?\s*(['\"]?)(?P<tag>[A-Za-z_]\w*)\1(?P<rest>[^\n]*)\n(?P<body>.*?)^\s*(?P=tag)\s*$",
+    re.DOTALL | re.MULTILINE,
+)
+# Commands whose heredoc is a payload rather than a script. Deliberately short: an
+# unlisted sink keeps its body in scope, so the cost of an omission is a false positive,
+# never a missed effect.
+DATA_SINK = re.compile(r"\bgit\s+(?:commit|tag|notes)\b", re.IGNORECASE)
+SEARCH_COMMANDS = {"egrep", "fgrep", "grep", "rg"}
+SHELL_CONTROL = {";", ";;", "&", "&&", "|", "||", "(", ")", "\n"}
+
+
+def strip_data_heredocs(command: str) -> str:
+    """Drop heredoc bodies that are data for a known sink.
+
+    Describing an effect inside a commit message is not performing it, and a message
+    that mentions one used to be blocked as though it did.
+
+    Bodies are kept whenever they might be executed: an interpreter reading a heredoc
+    runs it, so stripping there would make quoting style a way around this gate. The
+    body survives unless the delimiter is quoted, the segment introducing it is a
+    listed data sink, and nothing on the heredoc's own line pipes it somewhere else.
+    An unquoted delimiter performs parameter, command and arithmetic expansion before
+    the sink receives the data, so its body remains executable shell input.
+    """
+    def resolve(match: re.Match) -> str:
+        segment = re.split(r"\|\||&&|[;&|\n]", command[:match.start()])[-1]
+        if (
+            not match.group(1)
+            or "|" in match.group("rest")
+            or not DATA_SINK.search(segment)
+        ):
+            return match.group(0)
+        tag = match.group("tag")
+        return f"<<{tag}\n{tag}"
+
+    return HEREDOC.sub(resolve, command)
+
+
+def effect_of(command: str) -> str:
+    """The command reduced to what it actually does.
+
+    Strips an inline approval assignment, then any heredoc body that is data for a
+    known sink. What remains is the effect: the part worth classifying and hashing.
+
+    The digest must identify the *effect*, not the spelling of the retry. Without this,
+    prepending the variable changes the command text, which changes the digest, which
+    means the quoted digest is never the one that matches -- the repair path is a loop.
+
+    The assigned value is discarded on purpose. Only the process environment authorizes,
+    because the command string is composed by the model and honouring an inline value
+    would let it approve itself.
+    """
+    return strip_data_heredocs(APPROVAL_PREFIX.sub("", command, count=1))
+
+
+def is_inert_search(command: str) -> bool:
+    """Return true when a search query is data, not executable shell input."""
+    if any(marker in command for marker in ("$(", "<(", ">(", "`")):
+        return False
+    try:
+        lexer = shlex.shlex(command, posix=True, punctuation_chars=";&|()\n")
+        lexer.whitespace = " \t\r"
+        lexer.whitespace_split = True
+        lexer.commenters = ""
+        tokens = list(lexer)
+    except ValueError:
+        return False
+    if not tokens or any(token in SHELL_CONTROL for token in tokens):
+        return False
+    return os.path.basename(tokens[0]) in SEARCH_COMMANDS
+
+
 def protected_push(command: str, root) -> bool:
     if not re.search(r"\bgit\s+push\b", command, re.IGNORECASE):
         return False
@@ -24,9 +101,26 @@ def protected_push(command: str, root) -> bool:
     return result.stdout.strip() in {"main", "master", "production", "prod"}
 
 
+def destructive_protected_push(command: str, root) -> bool:
+    """Detect history rewrites or deletion, not ordinary additive publication."""
+    if not protected_push(command, root):
+        return False
+    match = re.search(r"\bgit\s+push\b", command, re.IGNORECASE)
+    if match is None:
+        return False
+    segment = re.split(r"\|\||&&|[;&|\n]", command[match.end():], maxsplit=1)[0]
+    force_or_delete = re.search(
+        r"(?:^|\s)(?:-f|--force(?:-with-lease(?:=\S+)?|-if-includes)?|--delete)(?=\s|$)",
+        segment,
+        re.IGNORECASE,
+    )
+    forced_refspec = re.search(r"(?:^|\s)(?:\+\S+|:\S+)(?=\s|$)", segment)
+    return force_or_delete is not None or forced_refspec is not None
+
+
 def classify(command: str, root) -> str | None:
-    if protected_push(command, root):
-        return "protected branch push"
+    if destructive_protected_push(command, root):
+        return "protected branch history rewrite or deletion"
     if re.search(r"\b(?:drop\s+(?:table|database|schema)|truncate\s+(?:table\s+)?)\b", command, re.IGNORECASE):
         return "destructive database operation"
     if re.search(r"\b(?:cast\s+send|solana\s+transfer|bitcoin-cli\s+send|near\s+send|aptos\s+move\s+run)\b", command, re.IGNORECASE):
@@ -42,7 +136,14 @@ def classify(command: str, root) -> str | None:
     return None
 
 
-def advisory(command: str) -> str | None:
+def advisory(command: str, root) -> str | None:
+    if protected_push(command, root):
+        return (
+            "Ultra observed a protected branch push. This portable hook cannot receive "
+            "the host's trusted owner-approval receipt, so it does not replace the host's "
+            "native authority flow. Proceed only after explicit owner authorization and "
+            "verify the remote result."
+        )
     if re.search(
         r"\b(?:alembic\s+upgrade|prisma\s+migrate|knex\s+migrate|sequelize\s+db:migrate|rails\s+db:migrate|manage\.py\s+migrate)\b",
         command,
@@ -65,19 +166,24 @@ def main() -> int:
     command = tool_input.get("command")
     if not isinstance(command, str) or not command.strip():
         return 0
-    threat = classify(command, root)
+    effect = effect_of(command)
+    if is_inert_search(effect):
+        return 0
+    threat = classify(effect, root)
     if threat is None:
-        note = advisory(command)
+        note = advisory(effect, root)
         if note:
             emit_context("PreToolUse", note)
         return 0
-    digest = hashlib.sha256(command.encode()).hexdigest()
-    if os.environ.get("UBP_DANGEROUS_COMMAND_APPROVED") == digest:
+    digest = hashlib.sha256(effect.encode()).hexdigest()
+    if os.environ.get(APPROVAL_VAR) == digest:
         return 0
     reason = (
-        f"Ultra blocked {threat}. Protected effect: the exact shell command. "
-        f"After explicit owner authorization, rerun with "
-        f"UBP_DANGEROUS_COMMAND_APPROVED={digest}."
+        f"Ultra blocked {threat}. Protected effect: the exact shell command, "
+        f"digest {digest}. Authorization comes from the owner's environment, never from "
+        f"the command text. Either run it yourself, or export "
+        f"{APPROVAL_VAR}={digest} in the environment that launches the agent and ask "
+        f"again. Prefixing the assignment onto this command does not authorize it."
     )
     print(json.dumps({
         "decision": "block",

package/hooks/session_context.py

@@ -1,22 +1,48 @@
 #!/usr/bin/env python3
-"""Inject the one-line goal and current task acceptance at session start."""
+"""Inject the accepted North Star or its pre-Research fallback plus task acceptance."""
 
 from _common import current_task, emit_context, markdown_section, project_root, read_payload, task_sections
 
 
+def settled_section(text: str) -> str:
+    """Return an explicitly populated section, not a packaged unresolved marker."""
+    if not text or "[NEEDS CLARIFICATION]" in text or "not yet defined" in text.lower():
+        return ""
+    return text.strip()
+
+
+def read_text(file) -> str:
+    try:
+        return file.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
 def main() -> int:
     payload = read_payload()
     root = project_root(payload)  # Idle guard: no `.ultra/` means silent exit.
     if root is None:
         return 0
-    try:
-        north_star = (root / ".ultra" / "north-star.md").read_text(encoding="utf-8")
-    except OSError:
-        north_star = ""
+    ultra = root / ".ultra"
+    north_star = read_text(ultra / "north-star.md")
+    project_brief = read_text(ultra / "project-brief.md")
     parts = []
-    one_line = markdown_section(north_star, "One-line")
-    if one_line:
-        parts.append(f"Ultra north star:\n{one_line}")
+    direction = settled_section(markdown_section(north_star, "Project Direction"))
+    if direction:
+        baseline = [f"Project Direction:\n{direction}"]
+        for heading in ("North Star Outcome", "Hard Constraints"):
+            section = settled_section(markdown_section(north_star, heading))
+            if section:
+                baseline.append(f"{heading}:\n{section}")
+        baseline_text = "\n\n".join(baseline)
+        parts.append(f"Ultra accepted north star:\n{baseline_text}")
+    else:
+        brief_line = settled_section(markdown_section(project_brief, "One-line"))
+        legacy_line = settled_section(markdown_section(north_star, "One-line"))
+        if brief_line:
+            parts.append(f"Ultra project brief (Research not yet accepted):\n{brief_line}")
+        elif legacy_line:
+            parts.append(f"Ultra legacy project intent:\n{legacy_line}")
     task = current_task(root)
     if task:
         acceptance = task_sections(root, task)["acceptance"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "File-first Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",

package/skills/ultra-change/SKILL.md

@@ -1,55 +1,56 @@
 ---
 name: ultra-change
-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.
+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.
 ---
 
 # Reconcile first, then write down what this Change commits to
 
-A Change is the durable unit connecting research, plan, implementation,
-verification, review and delivery. Reconciliation comes first because writing new
-intent on top of specifications that already disagree with the code buries the
-disagreement instead of resolving it.
+A Change connects research, plan, implementation, verification, review, and delivery.
+Reconcile first so new intent does not bury an existing specification/code conflict.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json`, and the `context_file` of any task not yet finished.
-2. Read `CONTEXT.md` for vocabulary and `.ultra/decisions/` for entries in scope.
-3. Read `.ultra/north-star.md` — a Change that does not serve it is worth
-   questioning out loud before it is written down.
+1. List `.ultra/changes/active/`; more than one `intent.md` is a conflict, not a choice.
+   One directory name is the stable `change_id`. Read `.ultra/tasks.json`, then only its
+   unfinished `context_file` values. Update the same `change_id`; never open a second active Change.
+2. Read `.ultra/project-brief.md`, `CONTEXT.md`, relevant `.ultra/decisions/`, and
+   `.ultra/north-star.md` for raw provenance, accepted language, and direction.
+3. Grep archive and abandoned Changes that touched this area. Prefer archived
+   `delivery.md`; otherwise read `archive-summary.md`, `verification.md`, `intent.md`,
+   and remaining Markdown. Read abandoned Changes as history of rejected boundaries and
+   reusable evidence, never current intent. A missing `delivery.md` does not mean no history;
+   repeated modules are an architecture signal.
 
 ## Whether this skill applies at all
 
 | Situation | Where it goes |
 |---|---|
-| No pending or in-progress task, and something new is asked for | Here |
+| No active Change, and a new bounded request exists | Here — create one stable id |
+| One active Change needs its draft, Research evidence, or accepted boundary reconciled | Here — update the same `change_id` |
+| 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 |
 | A task is in progress and the specification turns out not to match reality | Not here — the dual-write path inside `ultra-dev` |
-| The change makes no sentence in the specifications false | Neither — just make the change |
+| The change makes no sentence in the specifications false | Outside the Ultra lifecycle — use ordinary repository TDD and verification |
 
-That third row is the checkable answer to "how small is too small to deserve a
-Change file": if nothing the specifications say becomes untrue, there is nothing
-to reconcile and nothing to record.
+If no specification sentence becomes untrue, there is nothing to reconcile. Use
+`../ultra-tdd/SKILL.md` when helpful, but create no Change artifacts or Ultra
+Test/Deliver claim for that micro change.
 
 ## Definition of done
 
-- `.ultra/changes/active/<id>/intent.md` states the observable outcome, the
-  executable acceptance, the non-goals, and the public seams touched.
-- Each of the three reconciliation buckets is either empty or dispositioned, with
-  the owner's answer recorded for every bucket that was not empty.
-- The draft stays editable until then; the owner's acceptance is what turns it
-  into authority.
+- Active `intent.md` states outcome, executable acceptance, non-goals, public seams,
+  and Research Disposition.
+- Every reconciliation bucket is empty or dispositioned with the owner's answer.
+- The draft remains editable until owner acceptance makes it authority.
 
 ## Reconcile against a bounded scope
 
-A whole-repository diff is unusable, so derive the scope with four steps anyone
-can rerun:
+A Change does not rebuild the project baseline; reconcile only the touched specification sections
+and leave unrelated gaps visible with four rerunnable steps:
 
 1. Decide which specification sections this request touches.
-2. For each section, collect the past tasks whose `trace_to` points at it, and
-   from those the set of code files they changed.
-3. `git log -- .ultra/specs/<file>` gives the commit where that specification
-   last changed.
-4. `git diff <that commit>..HEAD -- <those code files>` is the reconciliation
-   scope.
+2. Collect past tasks whose `trace_to` points there and the code files they changed.
+3. Use `git log -- .ultra/specs/<file>` to find its last specification change.
+4. Inspect `git diff <that commit>..HEAD -- <those code files>`.
 
 Sort what you find into three buckets, each with your recommended disposition:
 
@@ -59,43 +60,49 @@ Sort what you find into three buckets, each with your recommended disposition:
 | Code implements it, no specification says so | Built and unpromised |
 | Both speak and they conflict | Contradictory |
 
-Take the buckets to the owner. This is confirmed rather than assumed, because a
-disposition can quietly be a REDUCTION.
+Take non-empty buckets to the owner because disposition can withdraw a commitment.
+Ask one recommended question per `HC-<n>` impact or removed promise; group remaining
+low-risk rows into one recommended list for confirmation.
 
 ## Write the intent
 
-Read `references/change-contract.md` and use its exact `intent.md` headings. The active
-Change directory contains only this accepted contract until planning or delivery adds
-its defined artifacts; do not invent a parallel semantic record.
+Read `references/change-contract.md` and use its exact headings. Until planning or
+delivery, the active directory contains only this contract; add no parallel record.
 
-Follow `../ultra-grilling/SKILL.md` to settle the boundary — one question at a
-time, each with your recommendation. New domain terms go through
-`../ultra-domain-modeling/SKILL.md`.
+Use `../ultra-grilling/SKILL.md` to settle the boundary and
+`../ultra-domain-modeling/SKILL.md` for new domain terms.
 
-When the work is too large *and* the path itself is unclear, follow
-`../ultra-think/SKILL.md` for a decision ticket instead of forcing a task
-breakdown. What comes out is a question whose answer is a decision, not an
-implementation slice.
+Use `../ultra-think/SKILL.md` only for one consequential evidenced trade-off. If the
+whole path is unclear, recommend Research instead of manufacturing tasks.
 
-When reconciliation proves the request is a directly executable one-slice correction,
-follow `../ultra-tdd/SKILL.md` at the confirmed public seam instead of manufacturing a
-task graph merely to satisfy ceremony.
+Record `## Research Disposition` exactly. `none` needs enough evidence to plan;
+`bounded` or `required` names one question, selected lenses, and exit evidence. After
+Research, reconcile outputs here; an unverified path or bare claim is not evidence.
 
-Output is `.ultra/changes/active/<id>/intent.md`, the specification patches
-reconciliation justified, possibly a `.ultra/decisions/<id>.md`, and any
-vocabulary update. Recommend `ultra-research` for a real evidence gap or
-`ultra-plan` once the contract is evidenced enough; do not invoke either.
+A quick active Change still goes through one-task `ultra-plan`; once durable intent
+exists, that minimal task is what binds development, evidence, audit, and delivery to
+the stable `change_id`.
+
+Output active `intent.md` under a stable id, justified specification patches, qualifying
+decision or vocabulary updates. For an evidence gap recommend `ultra-research`; when
+evidenced recommend `ultra-plan`. Invoke neither.
+
+## Abandoning a Change
+
+Append the exact `## Abandonment` closure from `references/change-contract.md`, then
+`git mv .ultra/changes/active/<id> .ultra/changes/abandoned/<id>`. Keep completed-task
+evidence. Future Change and Status consume this history; it is neither current intent
+nor an orphan. Abandonment is the owner's call.
 
 ## When the owner decides
 
-Every non-empty bucket, the Change boundary, and anything reconciliation turns up
-that shrinks a prior commitment. A change that makes no specification sentence
-false needs no permission at all.
+Every non-empty bucket, the Change boundary, abandonment, and anything
+reconciliation turns up that shrinks a prior commitment. A change that makes no
+specification sentence false needs no permission at all.
 
 ## References
 
 - `../ultra-grilling/SKILL.md` — the loop for settling the boundary.
 - `references/change-contract.md` — exact `intent.md` structure and profile fields.
-- `../ultra-think/references/autonomy-boundary.md` — read before dispositioning a
-  bucket in a way that removes something already promised.
+- `../ultra-think/references/autonomy-boundary.md` — read before removing a promise.
 - `../ultra-tdd/SKILL.md` — read for an evidenced one-slice correction.

package/skills/ultra-change/references/change-contract.md

@@ -3,6 +3,10 @@
 Create one contract before planning. Keep every field specific enough to verify and
 stable enough to survive a fresh session.
 
+The directory id is globally unique across active, archive, and abandoned Changes and
+matches `[A-Za-z0-9][A-Za-z0-9._-]*`. It is the stable `change_id`; moving the directory
+never changes it.
+
 ## Exact `intent.md` structure
 
 ```markdown
@@ -10,6 +14,8 @@ stable enough to survive a fresh session.
 
 > **Status**: draft | accepted
 > **Profile**: quick | standard | major | incident
+> **Profile rationale**: <why the smallest selected profile covers the blast radius>
+> **Risk flags**: <applicable flags, or none>
 
 ## Outcome
 <one externally observable result>
@@ -29,8 +35,20 @@ stable enough to survive a fresh session.
 ### Built and Unpromised
 ### Contradictory
 
+## Research Disposition
+- Disposition: none | bounded | required
+- Question: <the exact load-bearing unknown, or none>
+- Selected lenses: <reference ids, or none>
+- Existing evidence: <repository-relative paths and claims>
+- Required exit evidence: <what must exist or be resolved before planning>
+- Rationale: <why this is sufficient for this Change boundary>
+
 ## Planning Posture
 <EXPAND | SELECTIVE | HOLD | REDUCE, rationale, and owner confirmation>
+<!-- Scope for this Change only. Not the commitment classification: REDUCE here
+     means "plan less work now", while a REDUCTION in a Change Log means "a
+     promise the specification already made no longer holds". -->
+
 
 ## Recovery
 <reversal or recovery path and its verification>
@@ -45,8 +63,10 @@ heading, and do not add another file that restates the same contract.
 ## Contract fields
 
 - `outcome`: one externally observable result.
-- `acceptance`: stable ids with a criterion and exact verification for each accepted
-  behavior.
+- `acceptance`: stable ids, one criterion each, and a `Verification` that is an
+  **executable command** — something with an exit code, not a description of an
+  intention. `curl -sf localhost:3000/health` qualifies; "check that the endpoint
+  responds" does not.
 - `non_goals`: explicit boundaries that prevent accidental scope growth.
 - `public_seams`: entry points or outputs through which acceptance is observed.
 - `recovery`: a bounded reversal or recovery strategy and its verification.
@@ -55,6 +75,26 @@ heading, and do not add another file that restates the same contract.
 Resolve every blocking decision before planning. Keep non-blocking uncertainty visible
 in the task and verification contracts.
 
+## Why verification has to be executable
+
+A criterion whose verification cannot be run is not acceptance, it is a wish. Three
+consumers downstream depend on it being runnable:
+
+- task development can treat passing acceptance as an exit condition only when
+  something can actually decide "passing";
+- the review tests lens maps each acceptance claim to executable evidence, and can
+  only report an honest gap when there is something to map onto;
+- delivery cannot otherwise separate "shipped" from "believed shipped".
+
+Writing the command is also the cheapest way to find out that a criterion is vague.
+"The feature is wired up" resists a command until it becomes "this export has a
+non-test importer", which is a `grep`.
+
+Where a criterion is genuinely a judgement call — visual polish, wording, feel — it
+does not belong in Acceptance at all. Record it as a taste decision for the owner and
+keep Acceptance to what a machine can settle. Mixing the two is what makes an
+acceptance set undecidable.
+
 ## Profile
 
 - `quick`: one low-risk task, no material risk flags, and no research dependency.
@@ -67,9 +107,27 @@ in the task and verification contracts.
 Record a profile rationale and every applicable risk flag. Select the smallest profile
 whose guarantees cover the real blast radius; never use profile labels as estimates.
 
-## Research disposition
+## Research Disposition
+
+The `Disposition` value is exactly `none | bounded | required`. Use `none` with a
+rationale when accepted evidence is sufficient. Use `bounded` for one already-framed
+question whose smallest sufficient lenses are known; it skips Wayfinding. Use `required`
+when several load-bearing claims or the evidence path itself remain unclear, so Research
+may Wayfind before selecting lenses. Both name the exact question, selected or candidate
+Research lenses, existing evidence, and required exit evidence.
+The host model evaluates whether the named evidence exists and supports the claim; do
+not add a `research_complete` bit, score, or workflow state. Planning waits while the
+recorded exit evidence is unsatisfied.
+
+## Exact abandonment closure
 
-Use `none` with a rationale when accepted evidence is sufficient. Use `bounded` or
-`required` with a supported mode and the exact selected semantic steps when product,
-behavior, architecture, deployment, or risk facts remain load-bearing. The recorded
-selection is the planning gate.
+Before moving an owner-abandoned Change, append this exact structure to `intent.md`:
+
+```markdown
+## Abandonment
+- Date:
+- Owner decision:
+- Reason:
+- Reusable evidence:
+- Recovery or successor:
+```