ultra-builder-pro-cli 0.26.1 → 3.0.2

package/skills/ultra-init/SKILL.md

@@ -1,119 +1,131 @@
 ---
 name: ultra-init
-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.
+description: Create or recover Ultra's repository-local skeleton and raw Project Brief without performing product research. Use when `.ultra` is absent or partial in a new or existing codebase and later workflows need stable file paths, preserved authority, and Git.
 ---
 
-# Build the skeleton the rest of the workflow writes into
+# Create the skeleton and capture only the initial project outline
 
-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.
-
-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.
+Initialization establishes places for later authority and records raw owner intake. It
+does not validate the problem, establish a North Star, build a product or architecture
+baseline, settle domain language, choose a Change, or start another public workflow.
 
 ## Before you start
 
-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.
+1. If `.ultra/changes/active/` exists, resolve at most one active `change_id`. Read
+   `.ultra/tasks.json` if it exists, plus the `context_file` and closing `## Resume Note`
+   of unfinished tasks matching that id. Historical unfinished rows do not turn a
+   partial skeleton into current work. A partial `.ultra/` is recovery work.
+2. Read `.ultra/project-brief.md`, `.ultra/north-star.md`, `CONTEXT.md`, and relevant
+   `.ultra/decisions/` when they exist. Preserve accepted authority byte-for-byte.
+3. Establish the repository root, Git state, and whether meaningful code or maintained
+   documentation exists from the filesystem. Do not ask the owner for those facts.
 
 ## Definition of done
 
-- `.ultra/north-star.md` carries the owner's one-line goal in their own words.
-- Every `## Hard Constraints` entry has a stable `HC-<n>` id and can veto a
-  concrete technical decision. "Should be usable" vetoes nothing and is not yet a
-  constraint; "first paint under two seconds" is. Same bar for the success
-  metric: a threshold, not an aspiration. See
-  `../ultra-grilling/references/reframing.md` for what counts as an answer.
-- 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
+- `.ultra/project-brief.md` contains raw owner intake: one line, a broad outline,
+  explicit inputs already supplied, and open questions handed to Research.
+- For a new skeleton, a structurally complete North Star v2 with status `unresearched`
+  and the three specification skeletons exist. Init does not populate `FP-*`, `NS-*`,
+  or `HC-*`; recovery preserves any populated authority, and Init does not create
+  `CONTEXT.md`.
+- Every packaged path was read back after copying, while every pre-existing file stayed
+  byte-identical.
+- `.git` exists. Commit, push, remote creation, and publication remain separate effects.
 
-Check the filesystem in this order and take the first match:
+## Classify only for preservation
 
-| 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 |
+Use `references/brownfield-adoption.md` when source, runtime configuration, tests, or
+maintained product documentation already exist. Classification changes what must be
+preserved and what Research should inspect; it never authorizes Init to write observed
+product behavior into a specification.
 
-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 brief, then stop
 
-## Draw out the intent
+Follow `../ultra-grilling/SKILL.md` with only these required fields:
 
-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 |
+| Raw intake | Project Brief section |
 |---|---|
-| 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`, one `HC-<n>` per line |
-| 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 |
+| What the owner wants to build, in one sentence and their words | `## One-line` |
+| What it is, broadly for whom or what, intended result, broad boundary | `## Initial Outline` |
+| Constraints, materials, and decisions the owner already volunteered | `## Explicit Inputs` |
+| Questions already visible but requiring evidence or deeper decisions | `## Open Questions for Research` |
 
-When the first domain terms appear, follow `../ultra-domain-modeling/SKILL.md`
-and create `CONTEXT.md` at the repository root.
+Ask only enough to distinguish materially different outlines. If an answer would define
+a problem, actor evidence, desired outcome, success measure, product strategy, accepted
+constraint, domain term, requirement, or architecture, record it as an input or open
+question and stop drilling. Research owns that maturation and must not re-ask an answer
+unless evidence conflicts with it.
 
-## What gets written
+## Write and recover the skeleton
 
 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.
+`node <ultra-init-skill-dir>/scripts/init_project.cjs --project <repository-root>`.
+The script stages and reads back only missing files from `assets/project-template`,
+validates the staged North Star from its raw bytes, and then publishes a complete new
+`.ultra/` by atomic rename. Partial recovery publishes each staged file atomically
+without clobbering a concurrent or existing path. A validation or publication failure
+removes a published path only while its current stable identity and digest still match
+this invocation's recorded publication. A workspace edit is preserved and returns the
+typed retryable `initialization_snapshot_changed` diagnostic. Init binds every preserved
+file to one nonblocking, no-follow descriptor/path identity and SHA-256 digest, then
+rechecks all of them before staging, before publication, and before success. It likewise
+captures every staged digest before publication and compares it with a stable target
+snapshot before success. Each file publication takes fresh no-symlink parent-chain and
+resolved-root identity snapshots before and after the effect; detectable directory drift
+stops publication. A failed snapshot `lstat`, `open`, `fstat`, or `read` with no observed
+identity, type, size, or digest change instead returns the typed retryable
+`initialization_snapshot_io_error`; its sanitized `operation`, symbolic `errno`, and
+actionable permission, descriptor-limit, or storage recovery remain in the
+`ultra-init-error-v1` result. The North Star compatibility diagnostic remains
+`preserved_north_star_changed`. A malformed packaged placeholder stops before publication
+with an `ultra-init-error-v1` payload whose `code` is `north_star_template_invalid` and
+whose `diagnostics` preserve the canonical validator entries, including
+`invalid_unresearched_placeholder` for an exact-byte mismatch.
+
+This recovery contract assumes a cooperative local workspace. It detects observable
+path-identity or byte drift and preserves the current bytes for retry; it does not claim
+that Node filesystem calls can defeat a malicious operating-system-level replacement.
+Init also binds the root identity of its staging directory. Cleanup recursively removes
+that path only after a fresh no-symlink root rewalk proves the same device and inode. If
+the path was replaced, Init leaves it untouched and returns the retryable typed
+`initialization_cleanup_conflict` diagnostic with the owned identity and manual recovery
+instruction. If a typed initialization failure is already pending, that primary
+diagnostic remains the top-level `ultra-init-error-v1` result and the cleanup diagnostic
+is retained under `cleanup_conflict`, including its identity-bound manual recovery.
+On success every existing file stayed byte-identical and every new file matches its
+packaged digest.
 
 ```text
-.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,decisions,evidence,research}/ and changes/{active,archive,abandoned}/
-CONTEXT.md                                          repository root, once a term is settled
+.ultra/project-brief.md                            raw intake and initial outline
+.ultra/north-star.md                               unresearched Research-owned placeholder
+.ultra/specs/{product,architecture,discovery}.md  empty specification skeletons
+.ultra/specs/research-distillate.md                empty Research synthesis skeleton
+.ultra/{tasks.json,test-report.json}               empty or not-yet-run ledgers
+.ultra/{contexts,decisions,evidence,research}/
+.ultra/changes/{active,archive,abandoned}/
 ```
 
-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.**
+The script reports `created_unresearched` for a new placeholder. For a preserved file it
+reports exactly `preserved_unresearched`, `preserved_accepted`, `preserved_legacy`, or
+`preserved_unknown`; unknown or malformed content is never described as authority. For
+a legacy `north-star.md` containing the actual v0.26 headings or the older `## One-line`
+form, keep that file byte-identical.
+When the new Project Brief is still unresolved, copy the legacy one-line verbatim into
+it and list legacy hard constraints under Explicit Inputs without assigning new IDs.
+Research later proposes the accepted North Star; it never rewrites history silently.
 
-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.
+Git supplies revision identity, history, comparison, archive moves, and rollback. Run
+`git init` only when `.git` is absent, then report the uncommitted scaffold.
 
 ## 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.
-
-Where the host cannot ask at all, leave the one-line goal empty and say plainly
-that it is empty. Do not infer it from the directory name. An empty one-line goal
-is a **blocking** state, not a note: goal injection, boundary read-back and a
-Change's touched-constraints field all read from it, so planning and development
-must not start until it is filled. Say that too, and recommend rerunning this
-skill on a host that can ask.
+The owner confirms the one-line outline and any replacement of healthy authority. Where
+the host cannot ask, leave unresolved fields explicit and recommend resuming Init on a
+host that can; do not infer intent from the directory name. Recommend Research after a
+usable brief exists, but do not invoke it.
 
 ## References
 
-- `../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.
+- `../ultra-grilling/SKILL.md` — read before the first missing brief field.
+- `references/brownfield-adoption.md` — read when maintained behavior already exists.
+- `../ultra-think/references/autonomy-boundary.md` — read before replacing authority.

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

@@ -1,49 +1,32 @@
-# Brownfield adoption
+# Brownfield initialization
 
-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.
+Use this procedure only when `ultra-init` finds maintained behavior but no healthy,
+complete Ultra skeleton. Init preserves the checkout and prepares an evidence route; it
+does not establish the brownfield baseline.
 
 ## Bind the repository boundary
 
-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.
+Identify the repository root, selected workspace roots, branch, `HEAD`, dirty files,
+generated or vendored exclusions, manifests, maintained documents, verification
+commands, and visible public entry points. Resolve these from files and Git instead of
+asking the owner.
 
-## Inspect the maintained system
+## Preserve before interpreting
 
-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.
+- Never replace existing `.ultra` files, `CONTEXT.md`, decisions, or maintained project
+  documents merely to obtain the current template shape.
+- Treat source, tests, runtime configuration, and documentation as evidence candidates,
+  not conclusions Init may promote.
+- Keep out-of-scope dirty files visible in the report without adding them to the
+  Project Brief or specification skeletons.
+- Record an exact legacy one-line as raw intake only when the Project Brief is empty.
 
-## Write the baseline once
+## Prepare the Research handoff
 
-- 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.
+List the concrete paths and live seams that can answer each open baseline question.
+`ultra-research` establishes the observed and accepted baseline from those sources. Init
+does not run verification, classify delivered behavior, reconcile documentation drift,
+or write product, discovery, or architecture conclusions.
 
-Use the specifications as the canonical representation. Do not create a second
-baseline ledger, database projection, or generated semantic mirror.
-
-## Characterize verification
-
-Run the repository's existing verification commands. Record each result as `pass`,
-`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.
-
-## Converge
-
-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.
-
-Recommend `ultra-change` for subsequent work and stop; public skills do not invoke one
-another.
+Report the preserved files, repository boundary, candidate evidence, and unresolved
+questions. Recommend Research and stop; public workflows never invoke one another.