ultra-builder-pro-cli 0.13.0 → 0.15.0

package/.ultra-template/docs/research/README.md

@@ -3,16 +3,19 @@
 Store durable research evidence here only when it is too detailed for the baseline
 specification. Baseline decisions and accepted behavior remain in `.ultra/specs/`.
 
-## When to create a report
+## Required step reports
 
-Create a report for external facts, repository investigations, experiments, runtime
-observations, or decision evidence that must remain inspectable. Use a descriptive
-file name and include the observation date when freshness matters.
+Every selected `ultra-research` step writes one immutable report at
+`.ultra/docs/research/<workflow-id>/<step-id>.md`. Full and adoption research therefore
+produce seventeen reports. The shared specifications are updated during research but
+do not replace these per-step evidence records.
 
 ## Report contract
 
 Record:
 
+- a Markdown title and the exact sections `Evidence`, `Specification updates`, and
+  `Decisions and unknowns`;
 - scope and the decision the evidence informs;
 - observed facts with source references and dates;
 - verification commands or runtime evidence;
@@ -25,6 +28,7 @@ copying memory, code-graph payloads, or large source material into Ultra.
 
 ## Completion
 
-Update the affected baseline specification, include the report in `baseline.record`
-evidence when material, and record unresolved work in the authoritative gap ledger.
-Do not create a condensed duplicate of the baseline.
+Update the affected baseline specification, record the report through `workflow.step`,
+include it in `baseline.record` evidence when material, and record unresolved work in
+the authoritative gap ledger. The final synthesis also binds the three specifications
+and research distillate. Do not create a condensed duplicate of the baseline.

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

@@ -1,51 +1,54 @@
 # Architecture Specification
 
-This document defines the accepted system boundaries and implementation constraints.
-Describe the architecture that evidence requires; do not impose a framework or module
-shape that the project does not use.
+Define accepted system boundaries, authority, runtime paths, operational behavior, and
+implementation constraints. Describe observed architecture before proposed changes.
 
 ## Scope
 
 - Repository or system boundary:
 - Product contracts supported:
-- Revision or environment inspected:
+- Revision and environments inspected:
 
 ## Observed
 
-Record current components, dependencies, data paths, runtime behavior, and operational
-constraints confirmed by source or runtime evidence.
-
-| Architectural fact | Evidence reference | Consumer or impact |
+| Architectural fact | Source or runtime evidence | Consumer or impact |
 |---|---|---|
 | | | |
 
 ## Decisions
 
-Record an architecture decision only when it has been accepted. Describe alternatives
-only when a real choice was evaluated and the tradeoff matters for maintenance.
-
-| Decision | Constraint or evidence | Consequence | Owner |
+| Decision | Driver and evidence | Consequence and recovery | Owner |
 |---|---|---|---|
 | | | | |
 
 ## Unknowns
 
-| Unknown | Risk if unresolved | Blocking | Owner or next check |
+| Unknown | Consequence | Blocking | Owner or next check |
 |---|---|---|---|
 | | | | |
 
-## System Boundaries
+## 30 Architecture Context
 
-| Boundary | Responsibility | Inputs and outputs | Authority | Consumers |
+| Boundary or external system | Responsibility | Inputs and outputs | Trust or authority | Consumers |
 |---|---|---|---|---|
 | | | | | |
 
-## Runtime Paths
+Record material quality goals, technical and organizational constraints, data
+sensitivity, permissions, and compliance boundaries with evidence.
+
+## 31 Solution Strategy
+
+| Accepted direction | Existing pattern or constraint | Consequence | Compatibility or recovery |
+|---|---|---|---|
+| | | | |
+
+## 32 Building Blocks and Runtime Paths
 
-Trace the important behavior from a live entry point through state and side effects.
-Include failure and recovery paths when they are part of the contract.
+| Building block | Responsibility | Authority and contract | Dependencies | Consumers |
+|---|---|---|---|---|
+| | | | | |
 
-| Path | Entry point | State or dependency | Observable result | Recovery |
+| Runtime path | Entry point | State and side effects | Observable result | Failure and recovery |
 |---|---|---|---|---|
 | | | | | |
 
@@ -55,27 +58,24 @@ Include failure and recovery paths when they are part of the contract.
 |---|---|---|---|---|
 | | | | | |
 
-## Quality and Operational Constraints
+## 40 Deployment and Operations
 
-Include only constraints that are evidenced or explicitly accepted. Give each one a
-verification method rather than an arbitrary score.
-
-| Constraint | Source | Verification | Failure response |
-|---|---|---|---|
-| | | | |
-
-## Security and Permissions
+| Environment or operation | Entry point | Configuration or migration | Observation | Rollback or recovery |
+|---|---|---|---|---|
+| | | | | |
 
-Document trust boundaries, authorization sources, sensitive data handling, and audit
-requirements that apply to this scope.
+## 41 Quality Scenarios and Risks
 
-## Deployment and Recovery
+| Trigger and condition | Expected response | Measurement | Failure response | Owner |
+|---|---|---|---|---|
+| | | | | |
 
-Record the environments and release or rollback paths that are actually used. Link to
-external operational sources instead of duplicating their live contents.
+| Risk or debt | Evidence | Consequence | Mitigation and verification | Status |
+|---|---|---|---|---|
+| | | | | |
 
 ## Product Traceability
 
-| Product behavior | Architecture path | Verification evidence |
-|---|---|---|
-| | | |
+| Product requirement | Architecture path | Public seam | Verification evidence |
+|---|---|---|---|
+| | | | |

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

@@ -1,61 +1,74 @@
-# Discovery Record
+# Discovery Evidence
 
-Use this document for evidence that affects product scope or a baseline decision.
-Leave unsupported sections empty. Link to durable sources instead of copying large
-external payloads.
+Record product evidence and accepted decisions. Link to durable sources instead of
+copying provider payloads or research transcripts.
 
 ## Scope
 
-- Repository or product area:
-- Decision this research must unlock:
-- Evidence freshness boundary:
+- Repository or product boundary:
+- Baseline id and revision:
+- Decision this evidence must unlock:
+- Freshness boundary:
 
 ## Observed
 
-Record directly observed behavior, user input, repository facts, and sourced external
-facts. Identify the source and observation date.
-
-| Evidence | Source or reference | Finding | Freshness |
+| Fact or current behavior | Evidence reference | Observed at | Affected section |
 |---|---|---|---|
 | | | | |
 
 ## Decisions
 
-Record only accepted decisions. Include the reason, evidence, owner, and the contract
-or specification affected.
-
-| Decision | Reason and evidence | Owner | Affected contract |
+| Decision | Evidence and rationale | Owner | Affected contract |
 |---|---|---|---|
 | | | | |
 
 ## Unknowns
 
-Separate blocking unknowns from questions that are outside the accepted scope.
+| Unknown | Consequence | Blocking | Owner or next evidence |
+|---|---|---|---|
+| | | | |
+
+## 00 Problem Validation
 
-| Unknown | Why it matters | Blocking | Owner or next evidence |
+- Problem and affected actor:
+- Current workaround and consequence:
+- Demand or usage evidence:
+- Accepted problem boundary:
+
+## 01 Opportunity Discovery
+
+| Desired outcome | Opportunity | Evidence | Constraint or dependency |
 |---|---|---|---|
 | | | | |
 
-## Baseline Gaps
+## 02 Market Assessment
 
-Reference the authoritative gap ids recorded in `.ultra/state.db`. Use one of
-`baseline_blocker`, `documentation_drift`, `known_defect`, `technical_debt`,
-`unknown`, or `future_change`.
+Record only market, regulatory, commercial, or operational facts that affect a
+decision. Include source date, segment, geography, and assumptions when applicable.
 
-| Gap id | Category | Status | Evidence reference | Owner |
-|---|---|---|---|---|
-| | | | | |
+## 03 Alternatives
 
-## Current Behavior Notes
+| Current alternative | Evidence | Meaningful difference | Strategy implication |
+|---|---|---|---|
+| | | | |
+
+## 04 Product Strategy
+
+- Intended actors and outcome:
+- Value delivered through observable behavior:
+- Accepted tradeoffs:
+- Explicit constraints or exclusions:
+
+## 05 Assumptions and Validation
 
-For an existing project, describe only behavior confirmed from source, tests, runtime,
-or maintained documentation. For a new project, record the accepted problem and
-constraints without inventing current behavior.
+| Assumption | Current evidence | Validation signal | Decision rule | Owner |
+|---|---|---|---|---|
+| | | | | |
 
-## Traceability
+## Baseline Gaps
 
-Link each consequential finding to the product or architecture section it informs.
+Reference authoritative gap ids from `.ultra/state.db`.
 
-| Finding | Target specification | Status |
-|---|---|---|
-| | | |
+| Gap id | Category | Status | Evidence | Owner |
+|---|---|---|---|---|
+| | | | | |

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

@@ -1,27 +1,22 @@
 # Product Specification
 
-This document defines accepted product behavior and scope. It is a durable contract,
-not a research transcript or a task list.
+Define accepted product behavior and scope. Keep current behavior distinct from
+proposed behavior; this is not a transcript or task list.
 
 ## Scope
 
 - Product or repository boundary:
 - Intended outcome:
-- Explicit non-goals:
+- Explicit non-goals or constraints:
 
 ## Observed
 
-Record confirmed current behavior and externally visible constraints. For an existing
-project, cite source, test, runtime, or maintained documentation evidence.
-
-| Behavior or constraint | Evidence reference | Status |
-|---|---|---|
-| | | |
+| Current behavior or constraint | Evidence reference | Status | Affected requirement |
+|---|---|---|---|
+| | | | |
 
 ## Decisions
 
-Record accepted product decisions and the evidence or owner decision behind them.
-
 | Decision | Rationale | Acceptance impact | Owner |
 |---|---|---|---|
 | | | | |
@@ -32,36 +27,50 @@ Record accepted product decisions and the evidence or owner decision behind them
 |---|---|---|---|
 | | | | |
 
-## Actors and Entry Points
+## 10 Actors and Jobs
 
-Include actors only when they are supported by evidence. Describe the public entry
-point through which each actor reaches the behavior.
+| Actor or system | Job and context | Entry point | Constraints | Evidence |
+|---|---|---|---|---|
+| | | | | |
 
-| Actor or system | Need | Entry point | Evidence |
-|---|---|---|---|
-| | | | |
+## 11 User Scenarios
 
-## Behavior Contracts
+| Scenario id | Actor and trigger | Flow | Observable outcome | Failure and recovery | Evidence |
+|---|---|---|---|---|---|
+| | | | | | |
 
-Give each required behavior a stable identifier. State preconditions, observable
-result, failure behavior, and recovery where relevant.
+## 20 Behavioral Requirements and Acceptance
 
-### Behavior: pending
+### Requirement: pending
 
-- Trigger:
+- Source scenario or constraint:
 - Preconditions:
+- Action:
 - Observable result:
-- Failure behavior:
-- Recovery:
-- Evidence or decision:
+- Error behavior and recovery:
+- Verification:
 
-## Acceptance
+## 21 Capability and Scope Boundary
 
-| Behavior | Acceptance evidence | Public seam | Verification |
+| Capability | Included requirements | Dependencies | Status and rationale |
 |---|---|---|---|
 | | | | |
 
+Scope status must reflect an explicit decision. Do not infer a reduced product posture.
+
+## 22 Outcomes and Measurements
+
+| Outcome or guardrail | Definition | Evidence source | Decision use | Owner |
+|---|---|---|---|---|
+| | | | | |
+
 ## Documentation Impact
 
-List maintained documents that must stay consistent with this contract, or record a
-specific reason why no documentation change is required.
+List maintained documents that must stay consistent, or record a specific no-change
+rationale.
+
+## Architecture Traceability
+
+| Requirement | Public seam | Architecture path | Verification evidence |
+|---|---|---|---|
+| | | | |

package/.ultra-template/specs/research-distillate.md

@@ -0,0 +1,48 @@
+# Research Traceability
+
+This file is a navigation and convergence artifact. Do not duplicate the baseline
+specifications' prose.
+
+## Scope
+
+- Baseline or change id:
+- Research workflow id and mode:
+- Repository revision:
+- Completed step set:
+
+## Observed
+
+| Claim | Evidence reference | Specification anchor |
+|---|---|---|
+| | | |
+
+## Decisions
+
+| Decision | Owner and approval | Specification anchor |
+|---|---|---|
+| | | |
+
+## Unknowns
+
+| Unknown or gap id | Blocking | Owner or next action |
+|---|---|---|
+| | | |
+
+## End-to-End Trace
+
+| Problem or constraint | Actor and scenario | Requirement and acceptance | Architecture path | Verification |
+|---|---|---|---|---|
+| | | | | |
+
+## Verification
+
+| Command or observation | Result | Evidence location | Freshness |
+|---|---|---|---|
+| | | | |
+
+## Planning Entry
+
+- Accepted scope and posture:
+- Required references:
+- Blocking gaps:
+- Exact next route:

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

@@ -1,36 +1,19 @@
-<!-- Body template only. The projector owns authoritative YAML frontmatter. -->
+<!-- The projector owns YAML frontmatter and the generated execution contract. -->
 
-# Task {id}: {title}
+# Task Notes
 
-## Outcome
+Use this body only for task-specific implementation discoveries that are not already
+authoritative task fields. Stable specification learning must follow the change
+approval workflow.
 
-[Describe the observable result this task must produce.]
+## Implementation Notes
 
-## Required context
+- [Evidence-backed note with a source reference]
 
-- `[project-relative reference]` — [why it is required]
+## Open Questions
 
-## Execution contract
+- [Question, consequence, owner, and next evidence]
 
-- Public seam: [reachable entry point or observable boundary]
-- Verification command: `[exact deterministic command]`
-- Documentation impact: [required paths or a specific no-change rationale]
+## Recovery Notes
 
-## 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]
+- [Current safe resume point and any external prerequisite]

package/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] — 2026-07-22
+
+### Added
+
+- Added schema 15 typed semantic records for all seventeen research steps, including
+  step-specific attributes, stable ids, evidence links, source anchors, stored source
+  digests, synthesis trace validation, and current-source health checks.
+- Added complete Change Contracts with executable acceptance, non-goals, public seams,
+  recovery, unresolved decisions, profile rationale/risk flags, and explicit bounded
+  research disposition.
+- Added plan acceptance coverage and traceability gates, one-task enforcement for quick
+  changes, verified specification-learning application, and a published
+  `ultra-baseline-reconciliation-v1` schema.
+- Added task/change/plan review modes and machine-validated worker selection or skip
+  provenance while preserving independent specification-fidelity and engineering axes.
+
+### Changed
+
+- Unified every greenfield, brownfield, migrated, and daily route through
+  `ultra-change` before planning. Initial planning can no longer bypass durable intent,
+  risk, research, recovery, or acceptance authority.
+- Reworked the workflow Skills into compact host-neutral execution contracts with
+  focused references for research semantics, Change profiles, planning preflight,
+  review modes, and delivery reconciliation.
+- Made context budgets advisory while keeping evidence, authority, acceptance,
+  specification freshness, review, and recovery gates deterministic and blocking.
+
+### Fixed
+
+- Fixed research completion that previously stored prose and file hashes without a
+  machine-consumable semantic index or stale-source detection.
+- Fixed planning that could complete without proving every Change acceptance criterion
+  had an executable owner or that each task traced to accepted evidence.
+- Fixed approved learning and delivery reconciliation that could record status without
+  verifying the applied target, before/after content, source anchor, and archive replay
+  provenance.
+- Fixed review artifacts that did not distinguish task, aggregate change, and plan
+  scope or preserve why each bounded worker was selected or skipped.
+- Fixed host review-prompt adaptation across intentional Markdown line wrapping and
+  excluded tests, test fixtures, and generated Python bytecode from installed and
+  published plugin payloads.
+
+## [0.14.0] — 2026-07-19
+
+### Added
+
+- Added one read-only JavaScript Context Spine reader and renderer for the
+  authoritative `.ultra/state.db`, plus a packaged breadcrumb CLI shared by
+  Claude Code, Codex, OpenCode, Kimi Code, and the MCP server.
+- Added cross-host regression coverage proving stale JSON projections and
+  context manifests cannot override the active database change or task.
+
+### Changed
+
+- Changed `task.parse_prd` and `task.expand` to validate and atomically persist
+  task objects derived by the active host model. Ultra MCP no longer starts a
+  second model client or requires an Anthropic, OpenAI, or other provider key.
+- Reduced Python lifecycle hooks and the generated OpenCode plugin to thin
+  adapters over the canonical breadcrumb reader. Checkpoint and resume data is
+  advisory recovery evidence rather than a second workflow authority.
+- Made collaboration and verification Skills host-neutral, kept the current
+  host responsible for delivery, and generated Codex metadata from the source
+  Skill instead of maintaining duplicated prompt bodies.
+
+### Fixed
+
+- Fixed authoritative-state and injected-prompt divergence caused by hooks
+  reading `.ultra/workflow-state.json` or context manifests after
+  `.ultra/state.db` had advanced.
+- Fixed stale or incomplete state routing: missing projects route to
+  `ultra-init`, prior schemas route to migration, and corrupt current schemas
+  route to `ultra-doctor` without fabricating active workflow context.
+- Fixed installed OpenCode context injection so it reads the bundled runtime
+  with the installer-selected Node executable and remains portable outside the
+  source checkout.
+- Fixed Codex collaboration invocation and generated metadata quoting while
+  preserving the bounded read-only advisor contract.
+
+### Removed
+
+- Removed the private LLM client, planner prompt builders, and the
+  `@anthropic-ai/sdk` and `openai` runtime dependencies.
+
 ## [0.13.0] — 2026-07-18
 
 ### Added
@@ -541,7 +624,9 @@ 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.13.0...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.1...v0.13.0
 [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