ultra-builder-pro-cli 5.0.0 → 6.0.0

package/skills/ultra-change/SKILL.md

@@ -1,165 +0,0 @@
----
-name: ultra-change
-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 connects research, plan, implementation, verification, review, and delivery.
-Reconcile first so new intent does not bury an existing specification/code conflict.
-
-## Route modes
-
-| Mode | Entry | Observable exit | Next |
-|---|---|---|---|
-| `intake` | Explicit owner request with no active Change | One stable draft `change_id` captures outcome, acceptance, non-goals, seams, trace, and Research Disposition | Stay in `ultra-change` for acceptance or move to `evidence-needed` |
-| `evidence-needed` | The draft names one load-bearing question and required exit evidence | The bounded Research Disposition is owner-visible and records its return to this Change | Recommend `ultra-research/change-scoped` |
-| `reconcile` | Explicit invocation or a valid Execution Grant for the same active Change | Research or implementation evidence is dispositioned in the same intent and any material delta is accepted | Recommend or continue to `ultra-plan/decompose` when the intent is accepted |
-| `accepted` | Explicit owner acceptance of the Change outcome and boundary | Accepted intent, current trace, satisfied Research Disposition, and resolved material decisions are read back | Recommend `ultra-plan/decompose` |
-
-Follow `../ultra-status/references/route-contract.md`. A draft may be revised in place;
-an already accepted owner decision is revised by a superseding decision record so its
-history remains recoverable. Show a Route Card before each public transition. Under a
-valid grant only the non-material `reconcile` mode may continue implicitly.
-
-## Before you start
-
-1. If model-selected, require `reconcile` mode for the same active Change and verify a
-   live grant under `references/execution-grant.md`. Any intake, evidence-needed boundary,
-   acceptance, abandonment, reduction, or primary transfer stops and recommends current
-   explicit owner invocation; a coarse Host invocation bit cannot authorize it.
-2. Read `references/change-contract.md` and apply its **Active Change authority
-   resolution** before reading any active `intent.md`, relying on a current `change_id`,
-   or creating or writing a Change. Continue only from its positively observed stable
-   zero-or-one result; return its typed repair for any other result. With one active
-   Change, read `.ultra/tasks.json`, then only its unfinished `context_file` values.
-   Update the same `change_id`; never open a second active Change.
-3. Read `.ultra/project-brief.md`, `CONTEXT.md`, relevant `.ultra/decisions/`, and
-   `.ultra/north-star.md` for raw provenance, accepted language, and direction.
-4. 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 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 | Outside the Ultra lifecycle — use ordinary repository TDD and verification |
-
-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
-
-- Active `intent.md` states outcome, typed acceptance with named required evidence,
-  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 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. 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:
-
-| Bucket | Meaning |
-|---|---|
-| Specification says it, code does not implement it | Promised and missing |
-| Code implements it, no specification says so | Built and unpromised |
-| Both speak and they conflict | Contradictory |
-
-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 headings. Until planning or
-delivery, the active directory contains only this contract; add no parallel record.
-
-Use `../ultra-grilling/SKILL.md` to settle the boundary and
-`../ultra-domain-modeling/SKILL.md` for new domain terms.
-
-Use `../ultra-think/SKILL.md` only for one consequential evidenced trade-off. If the
-whole path is unclear, recommend Research instead of manufacturing tasks.
-
-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.
-Record one `## North Star Trace` with resolving `FP-<n>`/`NS-<n>`/`HC-<n>` ids, causal
-evidence, the accepted revision, the current Git blob digest, and any contradiction
-requiring owner disposition. Reference IDs only; do not mirror North Star prose.
-
-When Research accepts a revision whose id or digest differs from an active Change trace,
-that active Change has a stale observation, not a semantic failure. Preserve its intent,
-tasks, review, Test, and delivery evidence; reconcile old IDs to the accepted revision,
-surface contradictions for owner disposition, and invalidate any plan-bound execution
-approval through its own contract. Never silently rewrite the North Star or infer that a
-replacement grants execution.
-
-Every active Change still goes through `ultra-plan`; once durable intent exists, the
-smallest evidence-backed task graph for its real seams binds development, review,
-audit, and delivery to the stable `change_id`. The profile never fixes task or context
-count.
-
-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 without a covering grant; with a valid
-grant covering same-Change reconciliation and Plan, show the transition Route Card and
-allow Plan to re-verify its own entry contract.
-
-## 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 primary writer changes Agent
-
-When the owner moves the canonical implementation authority of an active
-work package to another Agent, follow `references/primary-transfer.md` exactly:
-the sender writes current reality into the task context and its Resume Note,
-derives the OFFER from canonical files and Git, and stops writing after the
-receiver's ready ACK; the receiver stable-reads, verifies every digest, and
-becomes the sole canonical writer. A delegated worker slice is never a
-substitute — `ultra-delegate` owns the mutually exclusive bounded-worker path.
-Validate receipts with
-`scripts/validate_primary_transfer.cjs`; the report is structural observation,
-never an acceptance.
-
-## When the owner decides
-
-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.
-
-If the owner rejects the presented options or says none is adequate, preserve that
-answer as current intake and keep the intent draft or move it to `evidence-needed`.
-Gather the missing discriminating evidence or present materially different options; do
-not select the nearest rejected option, manufacture acceptance, or route to Plan.
-
-## References
-
-- `../ultra-grilling/SKILL.md` — the loop for settling the boundary.
-- `references/change-contract.md` — canonical Active Change authority resolution, exact
-  `intent.md` structure, and profile fields.
-- `references/execution-grant.md` — read when the owner requests bounded workflow continuation under a session-local or durable grant.
-- `references/primary-transfer.md` — read when the owner moves the work package's canonical writer to another Agent (OFFER → ACK → RESULT).
-- `../ultra-status/references/route-contract.md` — owner-visible route, checkpoint, and recovery output.
-- `../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

@@ -1,199 +0,0 @@
-# Change Contract and profile
-
-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.
-
-## Active Change authority resolution
-
-Every Skill that selects a current `change_id`, reads active intent, or creates a new
-Change must first use native host filesystem checks to apply this instruction contract.
-It is not a parser, registry, or persisted state.
-A positively observed absent `.ultra` is the existing uninitialized condition:
-`ultra-status` may recommend `ultra-init`, while writers write nothing. This known
-absence is distinct from an unavailable observation. Otherwise:
-
-1. Require `.ultra`, `.ultra/changes`, and `.ultra/changes/active` to be a stable chain
-   of ordinary non-symlink directories with the same no-follow identities before and
-   after selection.
-2. Stable-list every active-root entry without following symlinks. Only `.gitkeep`,
-   when it is an ordinary regular non-symlink file, may be ignored. A `.gitkeep` of any
-   other type is malformed, is never a Change directory, and returns a typed diagnostic
-   with repair before any candidate intent is read. Every other non-directory or symlink
-   entry returns a typed diagnostic with a reachable repair before any intent read.
-3. A positively observed stable empty root, with or without that sole marker, means no
-   active Change. Active authority exists only when exactly one ordinary non-symlink
-   Change directory remains. More than one returns a typed conflict and repair; select
-   none of them.
-4. Require the selected directory's own `intent.md` to be a stable regular non-symlink
-   file opened with no-follow behavior. Capture one bounded snapshot, then recheck the
-   directory chain, active-root entries, selected directory, and intent identity before
-   consuming its contents.
-5. On any unavailable observation or changed identity, stop with a typed diagnostic and
-   reachable retry or repair. Do not read any intent, route from it, write any workflow
-   artifact, or create a new Change. Only a positively observed stable zero-directory
-   result permits `ultra-change` to create one.
-
-## Exact `intent.md` structure
-
-```markdown
-# Change <id>: <title>
-
-> **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>
-
-## Acceptance
-| ID | Criterion | Verification type | Required evidence |
-|---|---|---|---|
-
-## Non-goals
-- <explicit boundary>
-
-## Public Seams
-- <entry point or output>
-
-## Reconciliation
-### Promised and Missing
-### 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>
-
-## North Star Trace
-- First principles: <FP-<n> ids and the causal premise>
-- Serves: <NS-<n> ids and the causal contribution>
-- Touches: <HC-<n> ids, or none>
-- Evidence: <repository-relative paths and claims>
-- North Star revision: <accepted Revision field from `.ultra/north-star.md`>
-- North Star digest: <output of `git hash-object .ultra/north-star.md`>
-- Contradictions or refinements: <none, or the owner disposition still required>
-
-## Execution Grant
-
-- Grant: `session-local` (default) | `durable work-package` <grant-id>
-- Allowed workflows: <subset of research, plan, dev, test, deliver-reconcile>
-- Agent topology: <single-Agent default, or the owner-selected providers, counts, and write scopes>
-- Allowed local effects: <exact authorized local writes, tests, and bounded verification>
-- Budgets and expiry: <time, cost, tool, provider, delegation, review-round ceilings and expiry>
-- Mandatory reviews: <plan, task, and aggregate Change requirements>
-- Stop conditions: <named semantic, evidence, recovery, and budget stops>
-- Invalidation: <conditions that end the grant and return control to the owner>
-- Never granted: <new Change, baseline checkpoint, finalization/archive, external effects, cross-family provider calls>
-- 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>
-
-## 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>
-
-## Unresolved Decisions
-- <stable id, summary, blocking state, owner>
-```
-
-Use `[NEEDS CLARIFICATION]` for missing semantic content. Do not silently omit a
-heading, and do not add another file that restates the same contract.
-
-## Contract fields
-
-- `outcome`: one externally observable result.
-- `acceptance`: stable ids, one criterion each, one verification type, and exact
-  required evidence. The supported types are `command`, `inspection`,
-  `owner-judgment`, and `external-observation`. When one outcome needs more than one
-  authority, split it into independent criteria with unique IDs and keep one
-  verification type per criterion. A row must not carry multiple verification types.
-- `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.
-- `unresolved_decisions`: stable ids, summary, blocking state, and owner when known.
-
-Resolve every blocking decision before planning. Keep non-blocking uncertainty visible
-in the task and verification contracts.
-
-`North Star Trace` is the Change-level semantic trace. `First principles`, `Serves`, and
-`Touches` ids must resolve in `.ultra/north-star.md`; `Evidence` explains the causal
-claim rather than merely naming the file. Revision and digest are freshness observations.
-A mismatch returns the intent to reconciliation and never mechanically declares
-alignment or contradiction. Preserve historical evidence while reconciliation maps old
-IDs, records contradictions, and obtains any material owner disposition.
-
-Every Change records an `Execution Grant`; `session-local` is the default and a
-durable grant requires an exact owner record. The exact mode behavior,
-activation, and durable-verification rules live in `execution-grant.md`. The
-grant bounds native model continuation; it is not persisted route authority.
-
-## Why verification has to name its authority
-
-Acceptance is only auditable when the observation and its authority are explicit:
-
-- `command` records the exact command, working directory, exit status, and retained raw
-  output reference;
-- `inspection` cites the exact file, revision or digest, and the observed fact;
-- `owner-judgment` cites the durable owner disposition without replacing it with a
-  machine proxy; only the owner can supply its semantic result;
-- `external-observation` records the provider or environment, run identity, observation
-  time, and retained raw result.
-
-Development, Review, Test, and Deliver may verify that the required evidence exists,
-is fresh, and is bound to the criterion. They must not turn a command exit code, regex,
-digest, or schema result into a semantic verdict for an inspection, owner judgment, or
-external observation. Missing or stale evidence returns a typed gap to the responsible
-model or owner; it never silently deletes the criterion or manufactures acceptance.
-A validator owns exact structure, identity, and provenance only; validator success is
-never a semantic pass.
-
-## Profile
-
-- `quick`: a bounded low-risk change with no material risk flags and no research dependency.
-- `standard`: a bounded change with ordinary integration risk.
-- `major`: a broad or consequential change with material contract, migration,
-  authorization, security, multi-module, external-integration, or release impact.
-- `incident`: urgent diagnosis and recovery with a reproducible symptom. Baseline
-  break-glass still requires a recorded approver and recovery contract.
-
-Record a profile rationale and every applicable risk flag. Select the smallest profile
-whose guarantees cover the real blast radius; never use profile labels to prescribe a
-task count, file count, review effort, or estimate.
-
-## 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
-
-Before moving an owner-abandoned Change, append this exact structure to `intent.md`:
-
-```markdown
-## Abandonment
-- Date:
-- Owner decision:
-- Reason:
-- Reusable evidence:
-- Recovery or successor:
-```

package/skills/ultra-change/references/execution-grant.md

@@ -1,109 +0,0 @@
-# Change-scoped execution grants (session-local or durable)
-
-Use this reference only after the owner has accepted one active Change and wants
-an Agent to continue through a bounded local execution segment. The host's
-native model-tool loop is the executor; repository authority and ordinary
-workflow contracts remain unchanged.
-
-Ultra Builder Pro 3.0 has exactly two grant modes. Choosing a duration is not
-choosing a second product:
-
-- **Mode A — `session-local`** (the default): the owner's authorization lives
-  only in the current conversation. A fresh Agent may read the files for
-  context, but must obtain a new activation from the owner before continuing.
-  When the conversation activation is lost — a fresh session, another host, or
-  compaction — the work stops.
-- **Mode B — `durable work-package`**: the owner explicitly issues an exact
-  grant so one named work package can continue across sessions, hosts, and
-  compaction. A fresh Agent or host may continue that package only after
-  stably verifying the recorded grant.
-
-Neither mode grants finalization or archive: writing `delivery.md`, deciding
-version or package posture, and moving a Change to archive always require a
-current explicit owner invocation, in every mode.
-
-## What a grant is not
-
-- A grant is not inferred from task status, progress records, prose, Hook
-  output, Resume notes, or a stored quote. Stored grant text is inactive data
-  until a consuming Agent verifies it.
-- A grant never includes external or irreversible effects by default: commit,
-  push, tag, publication, deployment, real installation, credentials, and
-  incremental provider spend each require their own current owner
-  authorization, even under a durable grant.
-- A grant is not a daemon, scheduler, or auto-wake: it answers "may this
-  continued work proceed", not "who runs next".
-- An Agent cannot create, widen, or extend its own grant. A topology or scope
-  change returns to the owner.
-
-## Session-local activation
-
-All of these must be true:
-
-- the active `intent.md` is accepted and its North Star Trace is current;
-- the same session contains an explicit owner utterance naming the grant and
-  approving the current task ledger;
-- the next workflow is listed under `Allowed workflows` and remains inside every
-  budget;
-- the model can still point to that utterance in current conversation context.
-
-After a fresh session, a different host, or compaction that no longer contains
-the activation, stop and ask the owner to re-activate after `ultra-status`
-reconstructs the files.
-
-## Durable grant verification
-
-Before relying on a recorded `durable work-package` grant, a fresh Agent must
-stably verify, from the repository alone:
-
-1. the grant record's exact bytes and its cited accepted-design digest (for
-   example the SHA-256 recorded in the owner decision);
-2. the repository identity and base HEAD the grant names;
-3. the current work-package status (the implementation WIP or Change intent);
-4. the grant's subject, scope, Agent topology, allowed local effects,
-   budgets/expiry, review budget, invalidation, and revocation clauses;
-5. that no invalidation condition has fired.
-
-Any mismatch, ambiguity, or unknown stops the work and returns to the owner.
-Handoff passes the grant identity (path and digest); it never copies a new
-authorization prose into a second file.
-
-## Continuing the native loop
-
-After one workflow reaches its own observable completion, reread the intent,
-ledger, current evidence, review results, and budgets. If no stop condition
-applies, select the next covered workflow through the host's native Skill
-surface. Run one ready task at a time; never parallelize canonical writes. When
-the owner has not selected a multi-Agent topology, the current Agent continues
-alone: no automatic spawning, delegation, or control-plane enablement.
-
-A grant-covered Deliver run may reconcile, review, and report, and then stops
-before finalization: its inputs, writes, and effects end at the report. Only a
-current explicit owner invocation of `ultra-deliver` may write `delivery.md`,
-decide version or package posture, or archive the Change.
-
-Do not add a route ledger or progress authority. Task status, existing
-evidence, review artifacts, the Test report, and Git remain the observations
-the model interprets.
-
-## Budgets, stops, and termination
-
-Each budget is a hard ceiling and a resource observation, never evidence of
-semantic completion. Stop immediately for a REDUCTION, a North Star
-contradiction or stale trace, an unmet owner checkpoint, `Stalled` or
-`Unreachable` development, a disputed or unresolved P0/P1 finding,
-residual-risk acceptance, task-graph drift, lost activation (session-local) or
-failed grant verification (durable), or budget exhaustion. Report completed
-evidence and the cheapest safe next action.
-
-A grant never authorizes a new Change, a baseline acceptance, scope or risk
-acceptance, finalization or archival, external or irreversible effects, or
-cross-family provider calls beyond its recorded topology. Review terminates
-under the accepted convergence contract, and its precedence is one rule: an
-exact current owner grant overrides the versioned product default of
-one initial review plus at most two
-P0/P1 delta reviews per coherent work package.
-P2/P3 findings are reported and never auto-repaired, no budget extends itself,
-and the same root cause surviving three failed fixes stops point-patching and
-reports an architecture problem. Existing host permission and destructive-effect
-guards remain in force.