ultra-builder-pro-cli 0.25.1 → 0.26.0

package/skills/ultra-init/SKILL.md

@@ -1,54 +1,111 @@
 ---
 name: ultra-init
-description: Create or recover Ultra project authority for a new repository, an existing codebase, or an older Ultra installation. Use when `.ultra` is absent, initialization is incomplete, or doctor reports a migration fault.
+description: Establish a project's Ultra authority as files — the owner's one-line goal, hard constraints, the three specification skeletons, an empty task ledger, and Git. Use when a repository has no `.ultra` directory yet, or has a partial one left by an interrupted setup, whether the codebase is new or already carries years of history.
 ---
 
-# Initialize project authority
+# Build the skeleton the rest of the workflow writes into
 
-Initialization creates the repository-local Ultra authority. It does not perform
-research, accept a product baseline, choose a Change, or start another public
-capability.
+Initialization creates the repository-local authority and nothing else.
+It does not perform research, accept a product baseline, choose a Change, or
+start another capability — recommend the next one and stop; do not invoke it.
 
-## Inspect and align
+The dividing line against research is **authorization versus claim**. What the
+owner authorizes comes out of their head and evidence cannot overturn it. What
+research collects is a claim about the outside world, which evidence can confirm
+or refute. A technology choice is a claim, so it is not initialization's business
+— and a new project has no configuration files to read anyway.
 
-1. Inspect the repository root, Git state, meaningful source, existing `.ultra`,
-   monorepo boundaries, and the current request.
-2. When authority already exists, call `ultra.doctor { repair: false }` and preserve
-   healthy state. Never replace or delete it merely to obtain a clean init.
-3. Classify the repository from evidence:
-   - `greenfield`: no meaningful delivered behavior exists;
-   - `brownfield`: source, runtime, API, data, deployment, or tests describe an
-     existing maintained system;
-   - `migrated`: older Ultra authority was preserved but is not yet a trusted baseline.
-4. Ask the owner only when scope, healthy-authority replacement, destructive recovery,
-   or another material choice cannot be derived. Reuse explicit intent.
+## Before you start
 
-Read `../ultra-think/references/interaction-boundary.md` before asking a material
-question.
+1. Read `.ultra/tasks.json` if it exists, along with the `context_file` of any
+   task it names — a partial `.ultra/` means an earlier attempt stopped midway.
+2. Read `CONTEXT.md` at the repository root for vocabulary already settled, and
+   `.ultra/decisions/` for any entries preserved by a partial setup.
+3. Establish the route's facts from the filesystem, not by asking.
 
-## Initialize once
+## Definition of done
 
-Call `ultra.record` with one typed entry:
+- `.ultra/north-star.md` carries the owner's one-line goal in their own words.
+- Every file listed under **What gets written** exists; you read each one back
+  after writing and stopped at the first one missing.
+- `.git` exists. Any initial commit is a separately authorized delivery effect.
+- Nothing is invented: what is unknown says `[NEEDS CLARIFICATION]`.
+
+## Which route
+
+Check the filesystem in this order and take the first match:
+
+| Check | Route | What changes |
+|---|---|---|
+| `docs/` holds two or more non-README `.md` files, or `docs/adr/` or `doc/` exists | Documented brownfield | Write everything; cite maintained documents as evidence and preserve their repository paths in `trace_to` when they remain authoritative |
+| A language configuration file exists and the row above did not match | Brownfield | Write everything; record what a code scan shows in `architecture.md` and `discovery.md`, marked as observed and unverified |
+| Neither | Greenfield | Write everything |
+
+For either brownfield route, read `references/brownfield-adoption.md`. Existing docs
+are evidence or an explicitly retained authority; they never justify omitting the
+canonical specification skeleton that downstream workflows require.
+
+## Draw out the intent
+
+Follow `../ultra-grilling/SKILL.md`. It is a loop, not a questionnaire, because
+the owner cannot state what they want up front. Start from what they already said
+when invoking you, restate it for confirmation, and ask only about what is
+genuinely missing. Five things come out of it:
+
+| What you draw out | Where it lands |
+|---|---|
+| What you want to build, in one sentence, their words | `north-star.md`, `## One-line` |
+| What counts as success | `specs/product.md`, behavioral requirements and acceptance |
+| What must never happen | `north-star.md`, `## Hard Constraints` |
+| Who uses it, and how they cope today | `discovery.md`, marked as the owner's statement |
+| **What you already know you are unsure about** | `discovery.md` — research's priority queue |
+
+When the first domain terms appear, follow `../ultra-domain-modeling/SKILL.md`
+and create `CONTEXT.md` at the repository root.
+
+## What gets written
+
+Resolve this loaded Skill's directory, then run
+`node <ultra-init-skill-dir>/scripts/init_project.cjs --project <repository-root>`. The script copies
+only missing files from `assets/project-template`, preserves every existing authority
+file byte-for-byte, and reads the resulting skeleton back. Then fill its semantic
+placeholders from verified facts and owner decisions.
 
 ```text
-kind: baseline
-action: initialize
-data: { target_dir, project_name, mode=auto, git_mode=auto, optional scope }
-idempotency_key: <stable init attempt id>
+.ultra/north-star.md                                ## One-line, ## Hard Constraints
+.ultra/specs/{product,architecture,discovery}.md    ## Observed, ## Decisions, ## Unknowns
+.ultra/tasks.json                                   {"tasks": []}
+.ultra/test-report.json                             not-yet-run report with git_commit
+.ultra/contexts/  .ultra/decisions/  .ultra/evidence/
+CONTEXT.md                                          repository root, once a term is settled
 ```
 
-This stateless bootstrap is the only `ultra.record` operation allowed before
-`state.db` exists. It must create or migrate `.ultra/.runtime/state.db`, preserve
-existing artifacts and Git history, install only missing scaffold assets on resume,
-validate or safely upgrade a legacy task ledger, and read back the result.
+The copied `.ultra/.gitignore` excludes `.runtime/`, `progress/`, and `reviews/`
+without editing the owner's root ignore file. Those paths are exact — hooks and later
+skills read them by name. Every section left unfilled carries
+`[NEEDS CLARIFICATION]`, and which of those you resolve now has a checkable rule:
+**what can be read out of repository files, you fill; what needs investigation,
+research fills.**
+
+Git is not a preference. Reconciliation reads `git log` and `git diff`, staleness
+detection compares against `HEAD`, archiving is a `git mv`, and rollback is Git.
+If `.git` is absent, run `git init`. Report the uncommitted initialized files and ask
+for commit authority only if the owner wants that separate effect now.
+
+## When the owner decides
+
+Only the five things above, and only through the grilling loop. Replacing
+authority that already exists and looks healthy is the owner's call, never a
+convenience on the way to a clean start — preserve it and report what you found.
 
-An unborn Git repository may require a local initial commit, but init never creates a
-remote, tag, push, publish, or deployment. Corrupt DB/WAL/SHM and backups remain
-preserved until an explicit recovery choice is made.
+Where the host cannot ask at all, leave the one-line goal empty and say plainly
+that it is empty, that goal injection will therefore be empty, and that the next
+skill asks again. Do not infer it from the directory name.
 
-## Return control
+## References
 
-Report classification, scope, schema and backup result, Git state, imported team
-checkpoint state, and any mechanical blocker. Recommend the next useful capability
-from current evidence, usually `ultra-research`, `ultra-change`, `ultra-status`, or
-`ultra-doctor`; do not invoke it automatically.
+- `../ultra-grilling/SKILL.md` — the loop; read it before the first question.
+- `../ultra-domain-modeling/SKILL.md` — read when the first term needs writing.
+- `references/brownfield-adoption.md` — read for either existing-code route.
+- `../ultra-think/references/autonomy-boundary.md` — read before touching
+  authority that already exists.

package/skills/ultra-init/references/brownfield-adoption.md

@@ -1,99 +1,49 @@
 # Brownfield adoption
 
-Execute this procedure for a detected brownfield repository, a migrated compatibility
-baseline, or an existing adoption in `adopting` or `blocked` state.
+Use this procedure only when `ultra-init` detects an existing codebase without a
+healthy `.ultra/` authority surface. Initialization records the observable baseline;
+it does not redesign the application or accept claims the repository cannot support.
 
 ## Bind the repository boundary
 
-Record the repository root, selected scope, workspace roots, branch, HEAD, dirty files,
-generated and vendored exclusions, manifests, verification commands, and public seams.
-Use `.` for a whole-repository adoption. Use selected workspace roots only when the
-user's requested ownership is narrower than the monorepo.
+Record the repository root, selected workspace roots, branch, `HEAD`, dirty files,
+generated and vendored exclusions, manifests, verification commands, and public
+seams. Keep out-of-scope dirty files visible as context without treating them as part
+of the selected baseline.
 
-The authoritative worktree snapshot contains only selected-scope paths. Report dirty
-files outside that scope separately as repository context, but do not include them in
-the baseline digest. Require `accept_dirty_worktree: true` only after the owner confirms
-the exact in-scope `worktree_files` returned by the server.
+## Inspect the maintained system
 
-## Build the evidence model
+Trace product behavior through real entry points, runtime consumers, persistence,
+integrations, permissions, failure paths, tests, deployment, observability, and
+recovery. Classify every material statement as `Observed`, `Verified`, `Decided`, or
+`Unknown`. Record maintained-document conflicts as drift.
 
-Inspect the maintained system through its live boundaries:
+## Write the baseline once
 
-- product behavior, actors, entry points, and public acceptance;
-- runtime modules, consumers, data flow, persistence, and authority;
-- APIs, events, integrations, permissions, security, and failure paths;
-- build, test, lint, typecheck, deployment, migration, observability, and recovery;
-- maintained documents and every detected source-to-document conflict.
+- Update `.ultra/specs/product.md` with delivered behavior and acceptance.
+- Update `.ultra/specs/architecture.md` with boundaries, authority, consumers,
+  permissions, failures, and recovery.
+- Update `.ultra/specs/discovery.md` with scope evidence, known defects, drift, and
+  unresolved questions.
+- Initialize `.ultra/tasks.json` and `.ultra/test-report.json` from the packaged
+  templates without manufacturing passing results.
 
-Classify each material statement as `Observed`, `Verified`, `Decided`, or `Unknown`.
-Record document/source conflicts as drift. Keep provider payloads outside Ultra and
-record only bounded metadata references.
+Use the specifications as the canonical representation. Do not create a second
+baseline ledger, database projection, or generated semantic mirror.
 
-## Write baseline artifacts
-
-Update `.ultra/specs/product.md` with current delivered behavior and acceptance. Update
-`.ultra/specs/architecture.md` with real boundaries, owners, writers, consumers,
-consistency rules, permissions, failures, and recovery. Use `discovery.md` for scope
-evidence, decisions, and unresolved questions.
-
-Capture current facts without redesigning the application or manufacturing product
-narratives that are absent from evidence.
-
-## Run characterization verification
+## Characterize verification
 
 Run the repository's existing verification commands. Record each result as `pass`,
-`known_red`, or `not_run`. A known-red item needs evidence and a rationale; a missing
-command is not a passing result. Record a characterization gap for a critical public
-seam that has no stable verification signal; create its ordinary task only after the
-baseline is ready.
-
-## Maintain the gap ledger
-
-Record every adoption gap with a stable id, evidence references, owner, blocking flag,
-and one category:
-
-- `baseline_blocker`: the model should recommend against adoption until resolved or
-  the owner explicitly accepts the recorded risk;
-- `documentation_drift`: maintained prose conflicts with observed behavior;
-- `known_defect`: reproducible incorrect behavior;
-- `technical_debt`: accepted maintainability or quality cost;
-- `unknown`: evidence is insufficient;
-- `future_change`: desired behavior outside the current baseline.
-
-Use `open` for unresolved gaps, `accepted` for owner-accepted debt,
-`resolved` when evidence closes the gap, and `deferred` for explicitly postponed
-work. Keep every open `baseline_blocker` visible as a semantic warning. It does not
-become a SQLite hard gate: the model explains the risk, recommends resolution, and may
-record owner-authorized adoption without erasing the gap. Do not convert the ledger
-into hundreds of application tasks.
-
-## Record authority
-
-Use `ultra.record` with `kind: baseline`, `action: observe`, and full replacement
-arrays for:
-
-- scope and repository revision;
-- repository classification;
-- product and architecture specification paths;
-- bounded source, documentation, runtime, test, deployment, or external references;
-- verification results;
-- blocking and non-blocking unknowns;
-- the complete gap ledger;
-- external provider metadata references, when supplied.
-
-Use the server-returned revision, branch, worktree digest, and specification digests.
+`known_red`, or `not_run`; a missing command is not a pass. A critical public seam
+without a stable signal is an explicit gap, not an excuse to invent completion.
 
-## Obtain approval and converge
+## Converge
 
-Present scope, observed behavior, drift, known-red verification, unknowns, gaps, dirty
-worktree state, and material decisions to the owner. Use `ultra.record` with
-`kind: baseline`, `action: accept` only after explicit approval. Set
-`accept_known_red` and `accept_dirty_worktree` only for the exact items the owner
-accepted.
+Read every written file back, show the owner the selected scope, observed behavior,
+drift, known-red verification, unknowns, and material decisions, and leave unresolved
+items marked `[NEEDS CLARIFICATION]`. Adoption is ready when the file set is complete,
+the recorded revision matches the inspected checkout, and every material gap remains
+visible with its evidence and owner decision where one exists.
 
-Resolve hard authority blockers, then present semantic warnings for evidence or an
-owner decision. Adoption is complete when `ultra.context` reports a current accepted
-baseline, every material open gap is visible with its owner/risk and any acceptance is
-explicit in the approval note, and project doctor has no mechanical authority failure.
-Route all selected work through `ultra-change`, including work described by a legacy
-plan. Import its accepted intent into a current Change Contract before planning.
+Recommend `ultra-change` for subsequent work and stop; public skills do not invoke one
+another.

package/skills/ultra-init/scripts/init_project.cjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function usage() {
+  return 'usage: init_project.cjs --project <repository-root>';
+}
+
+function parseArgs(argv) {
+  if (argv.length !== 2 || argv[0] !== '--project' || !argv[1]) {
+    throw new Error(usage());
+  }
+  return path.resolve(argv[1]);
+}
+
+function listFiles(root) {
+  const files = [];
+  (function walk(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) walk(file);
+      else if (entry.isFile()) files.push(path.relative(root, file));
+    }
+  }(root));
+  return files.sort();
+}
+
+function templateRoot() {
+  const installed = path.resolve(__dirname, '..', 'assets', 'project-template');
+  if (fs.existsSync(installed)) return installed;
+  const checkout = path.resolve(__dirname, '..', '..', '..', '.ultra-template');
+  if (fs.existsSync(checkout)) return checkout;
+  throw new Error('ultra-init project template is missing');
+}
+
+function ensurePlainDirectory(directory, label) {
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`${label} must be a real directory: ${directory}`);
+  }
+}
+
+function initialize(project) {
+  if (!fs.existsSync(project)) throw new Error(`project does not exist: ${project}`);
+  ensurePlainDirectory(project, 'project');
+  const source = templateRoot();
+  const ultra = path.join(project, '.ultra');
+  if (fs.existsSync(ultra)) ensurePlainDirectory(ultra, '.ultra');
+  else fs.mkdirSync(ultra);
+
+  const created = [];
+  const preserved = [];
+  for (const relative of listFiles(source)) {
+    const target = path.join(ultra, relative);
+    if (fs.existsSync(target)) {
+      preserved.push(relative);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(path.join(source, relative), target, fs.constants.COPYFILE_EXCL);
+    created.push(relative);
+  }
+  for (const relative of [...created, ...preserved]) {
+    if (!fs.existsSync(path.join(ultra, relative))) {
+      throw new Error(`initialization read-back failed: ${relative}`);
+    }
+  }
+  return {
+    $schema: 'ultra-init-result-v1',
+    project,
+    template: source,
+    created,
+    preserved,
+  };
+}
+
+try {
+  process.stdout.write(`${JSON.stringify(initialize(parseArgs(process.argv.slice(2))), null, 2)}\n`);
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/skills/ultra-plan/SKILL.md

@@ -1,72 +1,92 @@
 ---
 name: ultra-plan
-description: Turn an accepted Ultra Change Contract into dependency-valid, DB-backed vertical task contracts. Use when research obligations are resolved and implementation needs an executable plan.
+description: Turn an evidenced Change intent into a dependency-valid task ledger, confirmed test seams, and resumable task contexts. Use when implementation needs decomposition, a wide refactor needs an expand-contract route, or an interrupted plan must be reconstructed from repository files.
 ---
 
-# Build an executable plan
-
-The model owns decomposition and technical design. MCP commits the accepted task graph,
-digests, context, and team checkpoint in one semantic operation.
-
-## Bind and design
-
-1. Call `ultra.context { stage: plan, scope: { change_id }, detail: full }`.
-2. Inspect or import the team checkpoint with `ultra.sync`. Resolve real concurrent
-   record conflicts; do not merge authority by editing JSON.
-3. Require an accepted Change contract and its current typed delta. Direct Build skips
-   extra research, never Plan or task contracts.
-4. Read `references/semantic-preflight.md`; inspect real consumers, source, tests,
-   deployment, and recovery.
-5. Recommend `EXPAND`, `SELECTIVE`, `HOLD`, or `REDUCE` only when posture changes
-   accepted scope. Reuse an explicit posture and ask through the host-native UI only
-   for a material unresolved choice.
-6. Design a walking skeleton and vertical slices. Each task owns an observable outcome,
-   public seam, verification command, acceptance mapping, target seams, bounded
-   context refs, documentation impact, recovery, owner, and dependencies. Set the
-   published `type`, `priority`, optional bounded `complexity`/`estimated_days`,
-   `slice_kind`, and string-array `deps`/`files_modified` deliberately. Prefer the
-   shared vocabulary when it communicates the work, but use a bounded
-   repository-specific label when it is clearer; SQLite validates structure and does
-   not choose business taxonomy.
-
-Large sources stay lazy. Use digest freshness for accepted inputs that must remain
-byte-current, existence for expected implementation targets, and advisory only when
-drift must be visible without blocking.
-
-Read `../ultra-think/references/interaction-boundary.md` before asking a material
-question.
-
-## Record and checkpoint
-
-Use one `ultra.record` batch with `task_contract / define` for new tasks and
-`task_contract / revise` for corrected contracts, including a wrong `title` or `type`,
-before accepting the Plan checkpoint. Read back the draft with `ultra.context`.
-Never write status, session, freshness, runtime tag, generated Context, or
-completion-commit fields through a Task Contract; Task outcomes and the runtime own
-them.
-Never read or write `.ultra/tasks/tasks.json`; use `ultra.sync` for the Git team
-checkpoint, and never edit the local runtime projection directly.
-
-Call exactly one `ultra.checkpoint`:
-
-```text
-stage: plan
-scope: { change_id }
-payload: planning posture, optional approval already obtained, context budget/refs
-idempotency_key: stable semantic Plan checkpoint id
-```
-
-The model decides whether decomposition, acceptance coverage, and context are
-sufficient and records any deliberate omission. Missing semantic detail remains a
-visible warning and does not deny an otherwise safe Session lease. The checkpoint compiles or reuses the
-content-addressed Context Envelope, reports advisory coverage diagnostics, exports
-`plan.json` and `plan.md` inside the same recoverable publication, accepts one Plan
-revision, and publishes the team checkpoint. Do not export separately.
-
-If rejected, the same Plan draft stays mutable. Fix only the reported structural,
-digest, path, or concurrency conflict and retry. To replace an accepted Plan, submit a
-new checkpoint revision; never edit SQLite or open a parallel run to escape a
-diagnostic.
-
-Return topology, executable slices, public seams, exact checks, checkpoint result, and
-the model's recommended execution order. Do not invoke `ultra-dev` automatically.
+# Turn one Change into executable tracer bullets
+
+Planning owns decomposition and technical design. Files carry the result across
+sessions and hosts; no runtime state decides whether the plan is meaningful.
+
+## Before you start
+
+1. Read `.ultra/tasks.json`; if a task is unfinished, read its `context_file` and
+   closing `## Resume Note` before replacing or extending anything.
+2. Read `CONTEXT.md` for vocabulary and the relevant `.ultra/decisions/` entries.
+3. Read the active Change intent, its `trace_to` specification anchors, and the
+   source, tests, consumers and recovery paths those anchors describe.
+
+## Definition of done
+
+- `.ultra/tasks.json` and one `.ultra/contexts/task-<id>.md` per task agree on
+  identifiers, status, dependencies and trace anchors.
+- The owner confirmed the scope posture and the seam list.
+- Every feature task is a tracer bullet touching at least two layers, unless the
+  Change itself demonstrably touches only one layer.
+- Coverage, dependency, trace, scope and context-budget checks have concrete results.
+
+## Fix the planning posture
+
+Choose `EXPAND`, `SELECTIVE`, `HOLD` or `REDUCE`; default to `SELECTIVE`. Once
+chosen, keep that posture visible in the active Change intent rather than silently drifting.
+Write it to the active Change `intent.md` under `## Planning Posture`; there is no
+separate `plan.md` authority.
+Use `../ultra-grilling/SKILL.md` through the host-native question surface when the
+choice remains material, one question with a recommendation at a time.
+
+If the work cannot fit in one session *and* the path itself is still unclear, use
+`../ultra-think/SKILL.md` to resolve decision tickets before decomposing tasks.
+
+## Choose the plan shape
+
+Use tracer bullets for ordinary work: each slice delivers one observable path through
+the layers it changes. Use expand–contract only when one mechanical change has a
+repository-wide blast radius and no vertical slice can keep the checkout green:
+expand with old and new forms, migrate bounded batches, then contract the old form.
+
+Build the graph with these structural defences:
+
+- **Walking Skeleton**: Task 1 traverses every layer this Change touches through one
+  real request and real data. A genuinely one-layer Change does not invent one.
+- **Contract task**: create it before both implementations when targets cross two top-
+  level source directories or two processes/services.
+- **Integration Checkpoint**: insert one after every three or four feature tasks.
+- A feature task that touches only one of several affected layers is merged or split
+  into a tracer bullet; moving a whole layer into one task is horizontal slicing.
+
+Confirm the seam list before tests are written. Reuse an existing public seam and use
+the highest seam that observes the behavior; one seam is ideal when it covers the path.
+
+## Write the files
+
+Each task records `id`, `title`, `type`, `priority`, `complexity`, `status`,
+`dependencies`, `context_file`, `trace_to` and `change_ref`. Complexity is only a
+splitting and context signal: 1–2 is local, 3–5 is bounded, 6–7 crosses a boundary,
+and complexity > 7 must split.
+
+Each context records Acceptance, confirmed seams, layers touched, target files,
+Implementation, verification commands, Definition of Drift, Change Log, Completion
+and Resume Note. Read every file back; task count and context count must match.
+
+## Verify the plan
+
+1. Map every in-scope user story or acceptance anchor to at least one task.
+2. Walk dependencies and repair every cycle with the exact cycle chain visible.
+3. Resolve every `trace_to` path and heading against a real file.
+4. Surface complexity, more than eight target files, or more than twenty tasks as
+   scope warnings; they are observations, not semantic verdicts.
+5. Estimate context at roughly `complexity × 5%`; surface anything above 40%.
+
+Report the graph, frontier, seams, warnings and first task. Recommend the next explicit
+capability from the files; do not invoke it.
+
+## When the owner decides
+
+The owner chooses the posture, confirms seams, resolves reductions and accepts material
+omissions. Mechanical cycles and broken paths are repaired before handoff because they
+make the written graph impossible to execute.
+
+## References
+
+- `../ultra-grilling/SKILL.md` — read before a material posture or seam question.
+- `../ultra-think/SKILL.md` — read when fog of war requires decision tickets.