ultra-builder-pro-cli 3.0.2 → 5.0.1

package/skills/ultra-status/references/route-contract.md

@@ -0,0 +1,100 @@
+# Route Contract
+
+This reference defines the owner-visible navigation surface shared by every public
+Ultra Skill. A Route Card is a derived observation from canonical project files, Git,
+and the current run. It is not workflow authority, a stage marker, or permission to
+continue.
+
+## Route Card
+
+Show a compact `UBP Route Card` at entry, at a material checkpoint, when pausing or
+blocked, at the observable exit, and before moving to another public Skill. Keep an
+unchanged field short, but never omit an unresolved decision or unfinished obligation.
+
+| Field | Meaning |
+|---|---|
+| `Route` | The current public Skill, or `idle` when no workflow is active |
+| `Mode` | One mode declared by that Skill |
+| `Why` | The current problem or evidence gap |
+| `Outcome` | The owner-visible result this route is trying to produce |
+| `Accepted boundary` | Accepted scope, exclusions, and authority that cover this run |
+| `Position` | Artifact-derived navigation such as selected reports or remaining tasks |
+| `Exit condition` | Observable evidence or owner decision that ends this mode |
+| `Delta` | Material facts changed since the prior card |
+| `Reality` | Live path, verification state, fakes, limitations, and unknowns |
+| `Decision needed` | One material owner decision, or `none` |
+| `Next` | The smallest covered continuation or one recommended public route |
+| `Not done` | Obligations left at a pause or exit |
+
+`Position` may report exact mechanical observations such as selected lenses with
+reports, dependency-ready tasks, or an ACP session waiting for permission. Never turn a
+count, validator result, finding total, or transport event into semantic progress or a
+numeric completion score.
+
+## Material checkpoints
+
+Stop and obtain the Owner's current decision before any of these changes or effects:
+
+1. a new or reduced North Star, specification, or Change commitment;
+2. a material delta to an active Change outcome, acceptance, non-goal, or public seam;
+3. evidence that materially changes the feasible direction or product boundary;
+4. wider Execution Grant scope, effects, budget, expiry, or Agent/provider topology;
+5. transfer of the canonical writer;
+6. unresolved P0/P1, risk acceptance, or the same root cause surviving three failed fixes;
+7. finalization, archive, commit, push, tag, publication, deployment, real installation,
+   credentials, provider spend, or another external or irreversible effect.
+
+Naming, internal design, ordinary technical choices, task decomposition, covered local
+edits and tests, and non-material evidence reconciliation remain model-owned inside the
+accepted boundary. Do not ask for confirmation when `Decision needed` is `none`.
+
+## Continuation
+
+Public modes belong to one of three invocation classes; model-only disciplines form a
+fourth class:
+
+| Invocation class | Owner entry | Model continuation |
+|---|---:|---:|
+| `explicit-entry` | yes | no |
+| `grant-continuable` | yes | only under a valid Execution Grant covering that mode |
+| `router` | yes | no; the Owner invokes read-only diagnosis explicitly |
+| `model-discipline` | no | only as an internal method of a covered workflow |
+
+Host metadata is only a coarse discovery bit. Before continuing, the Skill itself must
+verify its selected mode, the same active `change_id`, the valid Execution Grant,
+allowed local effects, stop conditions, and any material checkpoint. A coarse Host bit
+never permits an explicit-entry mode. Without a covering grant, stop with a Route Card
+and recommend the exact explicit route; never invoke another public Skill merely because
+its files appear ready.
+
+Within an accepted Change and valid grant, show the Route Card before each public Skill
+transition and continue without a confirmation question only when the next mode and all
+effects are covered. A material checkpoint still pauses. `Next` is either `continue:
+<route>/<mode>` when covered or `recommend: <route>/<mode>` when owner invocation is
+required.
+
+Execution events such as tool calls, plans, usage, permission requests, worker output,
+ACP updates, and process termination are transport observations. They may populate
+`Position`, `Delta`, or `Reality`; they never decide acceptance, task completion, or the
+next semantic route.
+
+## Recovery and degraded diagnosis
+
+On a fresh session or Host, reconstruct the card from the accepted North Star, Project
+Brief, active Change authority, task ledger and matching contexts, decisions, evidence,
+Git, and current installation/runtime observations. Read the closing `## Resume Note`
+for only the current work package. Do not rerun completed Research or create a route
+ledger to remember where the conversation stopped.
+
+If authority is absent, ambiguous, stale, malformed, or temporarily unreadable, stop
+semantic writes but keep read-only diagnosis reachable. Report the exact fact that
+prevents a normal route and the cheapest safe repair, retry, cancel, abandon, or fresh
+session path. Never describe a blocked route as an endless in-progress workflow.
+
+Owner revisions remain recoverable: edit a draft in place, supersede an accepted
+decision with a new owner record, and preserve Git/history. Status may summarize that
+history on request, but no event log becomes a second source of truth.
+
+When context pressure threatens reliable continuation, finish the nearest safe write,
+refresh the canonical context's Resume Note, show a final card, and recommend a fresh
+session. Context size is an observation, not a hard semantic gate.

package/skills/ultra-test/SKILL.md

@@ -9,6 +9,18 @@ This is the one end-of-change sensor allowed by PHILOSOPHY C4: an export cannot
 called orphaned while a later task may still wire it. It is a terminal sensor, never a gate;
 the owner decides what to fix or accept.
 
+## Route modes
+
+| Mode | Entry | Observable exit | Next |
+|---|---|---|---|
+| `audit` | Explicit invocation or a valid Execution Grant after every matching task has current completion evidence | One current whole-Change report and aggregate review preserve all six audit areas, findings, omissions, identities, and dispositions | Recommend `ultra-deliver/reconcile` when current, or the owner-selected responsible route |
+| `reaudit` | Explicit invocation or a valid Execution Grant after an owner-dispositioned repair invalidates the prior report | A fresh report binds the repaired Change snapshot without hiding earlier findings | Recommend `ultra-deliver/reconcile` when current, or another bounded owner disposition |
+
+Follow `../ultra-status/references/route-contract.md`. Show a Route Card at audit entry,
+before asking for finding disposition, and at the report exit. Audit counts and review
+events populate `Position` or `Reality`; they never choose repair, convergence, or risk
+acceptance. Test does not call its own repair route.
+
 ## Before you start
 
 1. If model-selected, verify the live execution grant in `../ultra-change/references/execution-grant.md` — a current session-local activation or a stably verified durable work-package grant; without either, stop.
@@ -209,7 +221,9 @@ disposition as separate fields. No validator result is itself semantic acceptanc
 
 Present the findings by consequence and recommend the highest-leverage response. The
 owner may fix all, fix selected findings, accept recorded risk, or reduce scope through
-the normal REDUCTION decision. Recommend the next capability; do not invoke it.
+the normal REDUCTION decision. Recommend the next capability. Continue only when the
+owner disposition or existing grant covers its exact mode and effects, and show the
+transition Route Card first; Test itself never manufactures that coverage.
 
 ## When the owner decides
 
@@ -225,5 +239,6 @@ an observation, not permission to auto-fix, weaken a test or silently change sco
 - `../ultra-review/SKILL.md` — read for aggregate Change review after the six-area audit.
 - `../ultra-plan/references/task-evidence-v2.md` — canonical current task evidence and task-review contract.
 - `../ultra-change/references/execution-grant.md` — read only for grant-activated continuation.
+- `../ultra-status/references/route-contract.md` — owner-visible route, checkpoint, and recovery output.
 - `../ultra-think/references/autonomy-boundary.md` — read when a proposed response
   would make an existing specification commitment stop holding.