ultra-builder-pro-cli 0.10.0 → 0.12.1

package/.ultra-template/specs/product.md

@@ -1,223 +1,67 @@
 # Product Specification
 
-> **Source of Truth**: This document defines WHAT the system does and WHO it's for.
-> Generated by `/ultra-research` Steps 10-22
-> Technical HOW belongs in `architecture.md`.
+This document defines accepted product behavior and scope. It is a durable contract,
+not a research transcript or a task list.
 
----
+## Scope
 
-## §1 Problem Statement
+- Product or repository boundary:
+- Intended outcome:
+- Explicit non-goals:
 
-### Core Problem
-[NEEDS CLARIFICATION] — One paragraph describing the problem, grounded in discovery.md §0
+## Observed
 
-### Who It Affects
-[NEEDS CLARIFICATION] — Brief overview connecting problem to specific user types
+Record confirmed current behavior and externally visible constraints. For an existing
+project, cite source, test, runtime, or maintained documentation evidence.
 
-### Current Impact
-- **Time cost**: [NEEDS CLARIFICATION] — Hours/week wasted on workarounds
-- **Money cost**: [NEEDS CLARIFICATION] — $ lost to inefficiency
-- **Opportunity cost**: [NEEDS CLARIFICATION] — What they can't do because of this problem
+| Behavior or constraint | Evidence reference | Status |
+|---|---|---|
+| | | |
 
----
+## Decisions
 
-## §2 User Personas
+Record accepted product decisions and the evidence or owner decision behind them.
 
-### Persona 1: [NEEDS CLARIFICATION] (Primary)
+| Decision | Rationale | Acceptance impact | Owner |
+|---|---|---|---|
+| | | | |
 
-**Role**: Job title / context
-**Context**: Where they work, team dynamics, industry
+## Unknowns
 
-**Goals**:
-1. [NEEDS CLARIFICATION] — Primary goal (what gets them promoted)
-2. Secondary goal (daily care)
-3. Tertiary goal (nice to have)
+| Unknown | Blocking | Owner | Resolution evidence |
+|---|---|---|---|
+| | | | |
 
-**Pain Points**:
-1. [NEEDS CLARIFICATION] — Connects to Opportunity O# from discovery.md §1
-2. Connects to Opportunity O#
-3. Source: URL or user quote
+## Actors and Entry Points
 
-**Current Workflow**:
-> Step-by-step description of how they solve this today
-> Tools used: List of current tools/processes
-> Time spent: X hours/week
+Include actors only when they are supported by evidence. Describe the public entry
+point through which each actor reaches the behavior.
 
-**Success Metric**: How they measure their own success
-**Adoption Trigger**: What would make them try our solution
-**Objections**: Why they might resist
+| Actor or system | Need | Entry point | Evidence |
+|---|---|---|---|
+| | | | |
 
-### Persona 2: [NEEDS CLARIFICATION] (Secondary)
+## Behavior Contracts
 
-**Role**: [NEEDS CLARIFICATION]
-**Context**: [NEEDS CLARIFICATION]
+Give each required behavior a stable identifier. State preconditions, observable
+result, failure behavior, and recovery where relevant.
 
-**Goals**:
-1. [NEEDS CLARIFICATION]
+### Behavior: pending
 
-**Pain Points**:
-1. [NEEDS CLARIFICATION]
+- Trigger:
+- Preconditions:
+- Observable result:
+- Failure behavior:
+- Recovery:
+- Evidence or decision:
 
-**Current Workflow**:
-> [NEEDS CLARIFICATION]
+## Acceptance
 
-**Success Metric**: [NEEDS CLARIFICATION]
-**Adoption Trigger**: [NEEDS CLARIFICATION]
-**Objections**: [NEEDS CLARIFICATION]
+| Behavior | Acceptance evidence | Public seam | Verification |
+|---|---|---|---|
+| | | | |
 
-### Persona Prioritization
+## Documentation Impact
 
-| Persona | Urgency | Willingness to Pay | Reachability | Priority |
-|---------|---------|-------------------|-------------|----------|
-| P1 | [NEEDS CLARIFICATION] | | | **Primary** |
-| P2 | | | | **Secondary** |
-
----
-
-## §3 User Scenarios
-
-### Scenario Overview
-
-| # | Scenario | Persona | Frequency | Pain | Value | Score |
-|---|----------|---------|-----------|------|-------|-------|
-| S1 | [NEEDS CLARIFICATION] | P1 | /5 | /5 | /5 | |
-| S2 | | | | | | |
-| S3 | | | | | | |
-
-> Priority Score = Frequency × Pain × Value
-
-### Scenario 1: [NEEDS CLARIFICATION] — Primary
-
-**Persona**: [NEEDS CLARIFICATION]
-**Frequency**: Daily / Weekly / Monthly
-
-**Trigger**: What event causes this scenario
-**Context**: Where, when, device, time pressure
-
-**Current Flow** (painful):
-1. [NEEDS CLARIFICATION] — What they do today
-2. Where friction occurs
-3. Workaround they use
-4. Outcome and time wasted
-
-**Desired Flow** (with our product):
-1. [NEEDS CLARIFICATION] — Trigger detected
-2. Streamlined action
-3. Fast resolution
-4. Outcome achieved in less time
-
-**Success Outcome**: [NEEDS CLARIFICATION] — Specific and measurable
-**Failure Outcome**: [NEEDS CLARIFICATION] — Consequences
-**Emotional Arc**: Frustration → Discovery → Relief
-
-### Scenario 2: [NEEDS CLARIFICATION]
-
-[Same structure as Scenario 1]
-
-### Scenario 3: [NEEDS CLARIFICATION]
-
-[Same structure as Scenario 1]
-
----
-
-## §4 User Stories & Features
-
-### Story Map Overview
-
-| ID | Story | Persona | Scenario | Priority | Complexity |
-|----|-------|---------|----------|----------|-----------|
-| US-01 | [NEEDS CLARIFICATION] | P1 | S1 | Must | S/M/L |
-| US-02 | | | | | |
-| US-03 | | | | | |
-
-### Must-Have Stories
-
-#### US-01: [NEEDS CLARIFICATION]
-**As a** [Persona], **I want** [action], **so that** [benefit].
-
-**Acceptance Criteria**:
-- [ ] Given [context], when [action], then [result]
-- [ ] Given [context], when [edge case], then [result]
-
-**Traces to**: Scenario S#, Opportunity O#
-**Complexity**: S/M/L
-
-### Should-Have Stories
-
-#### US-04: [NEEDS CLARIFICATION]
-[Same structure]
-
-### Could-Have Stories
-
-#### US-07: [NEEDS CLARIFICATION]
-[Same structure]
-
----
-
-## §5 Feature Scope
-
-### Features In (MVP)
-
-#### Feature 1: [NEEDS CLARIFICATION]
-- **Description**: What this feature does
-- **Stories**: US-01, US-02
-- **User value**: What user can do with this
-- **Priority**: Must-Have
-- **Complexity**: S/M/L
-
-### Features In (v2 — Planned)
-
-#### Feature 4: [NEEDS CLARIFICATION]
-- **Description**: What this feature does
-- **Stories**: US-07, US-08
-- **Rationale for deferral**: Why not MVP
-- **Trigger to build**: When to reconsider
-
-### Features Out (Explicitly Excluded)
-
-| Feature | Rationale | Reconsider When | Alternative |
-|---------|-----------|----------------|-------------|
-| [NEEDS CLARIFICATION] | Why excluded (ref strategy §4) | Condition | What users do instead |
-
-### Scope Summary
-- **MVP features**: [NEEDS CLARIFICATION] features, stories
-- **v2 features**: features, stories
-- **Excluded features**: features
-
----
-
-## §6 Success Metrics
-
-### North Star Metric
-- **Metric**: [NEEDS CLARIFICATION]
-- **Definition**: Exactly what is measured
-- **Current baseline**: Current state or industry benchmark
-- **Target**: Specific number
-- **Timeline**: When to achieve
-- **Measurement method**: How to collect this data
-
-### Business Metrics
-
-| Metric | Baseline | Target (M3) | Target (M6) | Target (M12) | How Measured |
-|--------|----------|-------------|-------------|--------------|-------------|
-| [NEEDS CLARIFICATION] | | | | | |
-
-### User Metrics
-
-| Metric | Baseline | Target | How Measured |
-|--------|----------|--------|-------------|
-| Task completion rate | [NEEDS CLARIFICATION] | | |
-| Time on task | | | |
-| User satisfaction (NPS) | | | |
-| Feature adoption | | | |
-
-### Anti-Metrics (What NOT to Optimize)
-
-| Anti-Metric | Why Not | What It Could Sacrifice |
-|------------|---------|------------------------|
-| [NEEDS CLARIFICATION] | | |
-
----
-
-**Document Status**: Draft
-**Last Updated**: [Date]
+List maintained documents that must stay consistent with this contract, or record a
+specific reason why no documentation change is required.

package/.ultra-template/tasks/contexts/TEMPLATE.md

@@ -0,0 +1,36 @@
+<!-- Body template only. The projector owns authoritative YAML frontmatter. -->
+
+# Task {id}: {title}
+
+## Outcome
+
+[Describe the observable result this task must produce.]
+
+## Required context
+
+- `[project-relative reference]` — [why it is required]
+
+## Execution contract
+
+- Public seam: [reachable entry point or observable boundary]
+- Verification command: `[exact deterministic command]`
+- Documentation impact: [required paths or a specific no-change rationale]
+
+## Constraints
+
+- [Confirmed constraint with its evidence source]
+
+## Acceptance evidence
+
+- [Expected behavior and the evidence that will verify it]
+
+## Traceability
+
+- Change: [change id or initial baseline]
+- Specification: [project-relative section reference]
+
+## Completion evidence
+
+- Commit: [verified commit when applicable]
+- Tests: [command and result]
+- Summary: [delivered behavior]

package/.ultra-template/tasks/tasks.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": "4.5",
+  "generated_at": "1970-01-01T00:00:00.000Z",
+  "source": ".ultra/state.db",
+  "tasks": []
+}

package/CHANGELOG.md

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.1] — 2026-07-18
+
+### Fixed
+
+- Fixed the published project scaffold so its task projection and neutral context
+  template are tracked on fresh checkouts instead of being hidden by a broad ignore
+  rule; the seed projection now uses the authoritative v4.5 state contract.
+
+## [0.12.0] — 2026-07-18
+
+### Added
+
+- Added schema 11.0 project baselines and four `baseline.*` MCP contracts for
+  greenfield initialization, brownfield adoption, evidence recording, explicit
+  approval, re-adoption history, and archive reconciliation.
+- Added automatic new/existing repository detection, neutral baseline templates,
+  metadata-only provider references, and cross-host baseline status/doctor output.
+
+### Changed
+
+- Reclassified file count, token estimate, and context-share limits as advisory
+  attention warnings. Necessary incident context and active work are no longer
+  rejected or repaired by arbitrarily raising a threshold.
+- Made incomplete or stale baseline state advisory during an active bounded change,
+  requiring approved adoption at `change.converge` and complete revision/spec
+  reconciliation in the atomic archive transaction.
+- Changed the Stop hook from a workflow-completion denial into a lifecycle advisory;
+  direct writes to the authoritative task projection remain blocked.
+
+### Fixed
+
+- Prevented old projects from being initialized as empty greenfield products or
+  using generated `tasks.json` as project metadata authority.
+- Updated Claude Code, Codex, OpenCode, and Kimi presentation so hooks expose
+  warnings without turning them into edit, stop, or workflow refusal gates.
+- Removed the convergence deadlock where normal HEAD or tracked-spec changes made by
+  the active change were rejected before archive could reconcile them; incomplete
+  archive declarations now fail with full state and artifact rollback.
+
+## [0.11.0] — 2026-07-18
+
+### Added
+
+- Added a portable Skill authoring contract aligned with OpenAI Skills guidance
+  and the Agent Skills progressive-disclosure model, plus regression coverage for
+  source prompts, commands, agents, generated runtimes, and package contents.
+- Added an independent `review-spec` worker and the `ultra-review-findings-v2` /
+  `ultra-review-summary-v2` evidence contracts so specification fidelity and
+  engineering standards remain separate release-gate axes.
+- Added focused research and code-review references that are loaded only when the
+  active workflow needs them.
+
+### Changed
+
+- Rewrote the nineteen packaged source Skills as concise, English, host-neutral
+  procedures with portable `name` and `description` frontmatter. Runtime metadata,
+  invocation policy, and MCP dependencies now belong to host adapters.
+- Reduced all eleven command documents to thin workflow launchers and rewrote the
+  bundled workers as bounded, evidence-based roles without arbitrary confidence,
+  coverage, severity, or option-count thresholds.
+- Simplified Claude Code, Codex, OpenCode, and Kimi Code adaptation by removing
+  stale prompt rewriting branches while preserving each host's native invocation,
+  MCP, hook, and agent contracts.
+
+### Fixed
+
+- Made the review waiter validate exact named v2 artifacts, reject partial or stale
+  schemas, derive severity counts from evidence, and fail inconsistent two-axis
+  summaries closed.
+- Isolated read-only collaboration commands from user configuration and repository
+  rules, and passed the review schema by an explicit absolute path instead of
+  guessing an installed plugin root.
+- Prevented Python caches and retired prompt/runtime artifacts from entering the npm
+  tarball.
+
+### Removed
+
+- Removed the duplicate `ai-collab-base` prompt framework, the seventeen-step
+  research prompt tree, redundant review checklists, learned-Skill placeholder, and
+  obsolete v1 verdict updater.
+
 ## [0.10.0] — 2026-07-18
 
 ### Added
@@ -409,7 +490,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.1...HEAD
+[0.12.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.0...v0.12.1
+[0.12.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.7.0...v0.8.0

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.10.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.12.1-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
@@ -27,7 +27,7 @@ authoritative `.ultra/state.db`.
   Install and uninstall are symmetric on every supported host; `ubp --doctor`
   verifies the installed asset hashes and host entry points without mutation.
 - **Shares state across runtimes.** `.ultra/state.db` (SQLite + WAL) is the
-  authoritative source for changes, tasks, sessions, events, incidents,
+  authoritative source for baselines, changes, tasks, sessions, events, incidents,
   projection jobs, and telemetry. `tasks.json` and context markdown are
   generated projections, not handwritten.
 - **Keeps memory ownership explicit.** Ultra Builder Pro does not collect
@@ -37,12 +37,16 @@ authoritative `.ultra/state.db`.
   `.ultra/execution-plan.json` → parallel worktree sessions → auto-merge back.
 - **Keeps daily work convergent.** `/ultra-change` creates a bounded delta and
   Context Manifest v2; the Context Spine assigns a role/gate, verifies required
-  references and fresh-context budget, exposes one DB-derived breadcrumb, and
+  references, reports fresh-context budget pressure as advisory warnings, exposes one DB-derived breadcrumb, and
   routes a single next action. `/ultra-deliver` requires applied specification
   learning plus docs/test/two-axis review evidence before archive. `/ultra-doctor` reports incidents,
   projection lag, orphan sessions, and backup-first mechanical recovery.
   Incident changes additionally require a five-section `diagnosis.md` covering
   reproduction, hypotheses, root cause, regression test, and recovery.
+- **Adopts existing repositories without pretending they are new.** `ultra-init`
+  auto-detects greenfield versus brownfield work. Brownfield adoption records
+  current specifications, repository/runtime evidence, known-red verification,
+  unknowns, and explicit approval without rewriting application code.
 - **Keeps external context external.** Memory and code-graph providers retain
   their own content; Ultra stores only provider/project/revision/status metadata
   references in a compiled change context.
@@ -82,6 +86,14 @@ install or update.
 See [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md)
 for per-runtime capabilities.
 
+Start with `ultra-init` in both new and existing projects. An empty project opens
+a `draft` greenfield baseline. An existing codebase opens an `adopting`
+brownfield baseline; inspect current behavior, call `baseline.record`, then
+approve it through `baseline.converge` before normal planning or delivery. An
+urgent active fix may continue while adoption or context-size warnings are
+visible. `change.converge` requires approved adoption, while normal HEAD/spec drift
+from that change is declared and health-checked atomically by `change.archive`.
+
 ## Three-layer architecture
 
 | Layer | Purpose | When it's used |
@@ -93,7 +105,7 @@ for per-runtime capabilities.
 The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
 tool: continuous change mutations are MCP-only and fail closed. See
 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full contract and
-[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 32 live contracts.
+[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 36 live contracts.
 Review, impact discovery, skill resolution, and user interaction stay on each
 Host's native surfaces; the generated Codex capability map documents those
 replacements without advertising non-existent MCP tools.
@@ -121,11 +133,11 @@ Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.m
 ## Typical workflow
 
 ```bash
-# 1. Initialize a project (writes .ultra/ skeleton and initializes state.db)
-ultra-tools task init-project --name myapp
+# 1. Initialize a new project or adopt an existing repository automatically
+ultra-tools task init-project --project-name myapp --mode auto
 
-# 2. Turn a PRD into a task graph + execution plan (human-gate via dry-run)
-#    (invoked by /ultra-plan skill or via MCP task.parse_prd + plan.export)
+# 2. Record and converge the greenfield/brownfield baseline, then turn accepted
+#    behavior into a task graph (normally driven by ultra-init/research/plan)
 
 # 3. Run the plan — parallel sessions, auto-merge back to main on success
 ubp-orchestrator run
@@ -138,7 +150,7 @@ ultra-tools system doctor
 ```
 
 Or let the skills drive it. In Codex, invoke
-`$ultra-builder-pro:ultra-plan` → `$ultra-builder-pro:ultra-dev` →
+`$ultra-builder-pro:ultra-init` → `$ultra-builder-pro:ultra-plan` → `$ultra-builder-pro:ultra-dev` →
 `$ultra-builder-pro:ultra-test` → `$ultra-builder-pro:ultra-review` →
 `$ultra-builder-pro:ultra-deliver`; after the baseline is delivered, daily work
 starts with `$ultra-builder-pro:ultra-change`, while