ultra-builder-pro-cli 0.10.0 → 0.12.1

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

@@ -1,250 +1,81 @@
-# Architecture Design
+# Architecture Specification
 
-> **Purpose**: This document defines HOW the system is built. Based on arc42 template.
-> Generated by `/ultra-research` Steps 30-41
-> **Reference**: [arc42.org](https://arc42.org)
+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.
 
----
+## Scope
 
-## §1 Quality Goals
+- Repository or system boundary:
+- Product contracts supported:
+- Revision or environment inspected:
 
-| Priority | Quality Attribute | Scenario | Metric |
-|----------|------------------|----------|--------|
-| 1 | [NEEDS CLARIFICATION] | Concrete scenario | Measurable target |
-| 2 | | | |
-| 3 | | | |
+## Observed
 
----
+Record current components, dependencies, data paths, runtime behavior, and operational
+constraints confirmed by source or runtime evidence.
 
-## §2 Constraints
+| Architectural fact | Evidence reference | Consumer or impact |
+|---|---|---|
+| | | |
 
-### Technical Constraints
+## Decisions
 
-| Constraint | Rationale | Impact |
-|-----------|-----------|--------|
-| [NEEDS CLARIFICATION] | Why this exists | What it limits |
+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.
 
-### Organizational Constraints
+| Decision | Constraint or evidence | Consequence | Owner |
+|---|---|---|---|
+| | | | |
 
-| Constraint | Rationale | Impact |
-|-----------|-----------|--------|
-| [NEEDS CLARIFICATION] | Why this exists | What it limits |
+## Unknowns
 
-### Regulatory Constraints
+| Unknown | Risk if unresolved | Blocking | Owner or next check |
+|---|---|---|---|
+| | | | |
 
-| Constraint | Rationale | Impact |
-|-----------|-----------|--------|
-| [NEEDS CLARIFICATION] | Why this exists | What it limits |
+## System Boundaries
 
----
+| Boundary | Responsibility | Inputs and outputs | Authority | Consumers |
+|---|---|---|---|---|
+| | | | | |
 
-## §3 System Context
+## Runtime Paths
 
-### Users
-- [NEEDS CLARIFICATION]: How they interact
+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.
 
-### External Systems
+| Path | Entry point | State or dependency | Observable result | Recovery |
+|---|---|---|---|---|
+| | | | | |
 
-| System | Direction | Data | Protocol | Notes |
-|--------|-----------|------|----------|-------|
-| [NEEDS CLARIFICATION] | Inbound/Outbound | What data | REST/gRPC | |
+## Data and State Authority
 
-### Data Flows
-- [User] → [System] → [External]: [NEEDS CLARIFICATION]
+| State | Authoritative owner | Writers | Readers | Consistency or migration rule |
+|---|---|---|---|---|
+| | | | | |
 
----
+## Quality and Operational Constraints
 
-## §4 Solution Strategy
+Include only constraints that are evidenced or explicitly accepted. Give each one a
+verification method rather than an arbitrary score.
 
-### Technology Decisions
+| Constraint | Source | Verification | Failure response |
+|---|---|---|---|
+| | | | |
 
-#### Language & Runtime
-- **Chosen**: [NEEDS CLARIFICATION]
-- **Alternatives considered**: Option B, Option C
-- **Rationale**: Why — reference §1 quality goals
-- **Trade-off**: What we give up
-- **Source**: URL
+## Security and Permissions
 
-#### Web Framework
-- **Chosen**: [NEEDS CLARIFICATION]
-- **Alternatives considered**:
-- **Rationale**:
-- **Source**:
+Document trust boundaries, authorization sources, sensitive data handling, and audit
+requirements that apply to this scope.
 
-#### Database
-- **Chosen**: [NEEDS CLARIFICATION]
-- **Alternatives considered**:
-- **Rationale**:
-- **Source**:
+## Deployment and Recovery
 
-#### Authentication
-- **Chosen**: [NEEDS CLARIFICATION]
-- **Alternatives considered**:
-- **Rationale**:
-- **Source**:
+Record the environments and release or rollback paths that are actually used. Link to
+external operational sources instead of duplicating their live contents.
 
-#### Hosting & Infrastructure
-- **Chosen**: [NEEDS CLARIFICATION]
-- **Alternatives considered**:
-- **Rationale**:
-- **Estimated cost**: $/month at launch scale
-- **Source**:
+## Product Traceability
 
-### Tech Stack Summary
-
-| Layer | Technology | Version | Purpose |
-|-------|-----------|---------|---------|
-| Frontend | [NEEDS CLARIFICATION] | | |
-| Backend | | | |
-| Database | | | |
-| Cache | | | |
-| Auth | | | |
-| Hosting | | | |
-| CI/CD | | | |
-| Monitoring | | | |
-
----
-
-## §5 Building Block View
-
-### Module Decomposition
-
-| Module | Layer | Responsibility | Dependencies |
-|--------|-------|---------------|-------------|
-| [NEEDS CLARIFICATION] | Domain | Pure logic | None |
-| | Application | Orchestration | Domain |
-| | Infrastructure | IO handling | Application |
-
-### Code Organization
-
-```
-src/
-├── domain/           # Functional Core (pure logic)
-│   ├── entities/     # Domain objects
-│   ├── values/       # Value objects
-│   └── services/     # Domain services (pure functions)
-├── application/      # Use cases (orchestration)
-│   └── usecases/     # One file per use case
-├── infrastructure/   # Imperative Shell (IO)
-│   ├── http/         # HTTP handlers/routes
-│   ├── persistence/  # Database repositories
-│   └── external/     # External API clients
-└── config/           # Configuration
-```
-
-### Feature → Module Mapping
-
-| Feature | Domain | Application | Infrastructure |
-|---------|--------|------------|---------------|
-| [NEEDS CLARIFICATION] | Entities | UseCases | Handlers, Repos |
-
----
-
-## §6 Runtime Scenarios
-
-### Scenario 1: [NEEDS CLARIFICATION] (from product.md S1)
-
-**Trigger**: User action
-**Flow**:
-1. User sends request to endpoint
-2. Handler validates input, maps to DTO
-3. UseCase orchestrates: loads Entity via Repository
-4. DomainService applies business logic (pure)
-5. Repository persists result
-6. Handler returns response
-
-**Error paths**: [NEEDS CLARIFICATION]
-
-### Scenario 2: [NEEDS CLARIFICATION]
-
-[Same structure]
-
----
-
-## §7 Deployment View
-
-### Environments
-
-| Environment | Purpose | Infrastructure | URL Pattern |
-|------------|---------|---------------|-------------|
-| Development | Local dev | [NEEDS CLARIFICATION] | localhost |
-| Staging | Pre-prod | | staging.X |
-| Production | Live | | X.com |
-
-### Production Topology
-- **Compute**: [NEEDS CLARIFICATION]
-- **Database**: [NEEDS CLARIFICATION]
-- **Cache**: [NEEDS CLARIFICATION]
-- **CDN**: [NEEDS CLARIFICATION]
-
----
-
-## §8 Crosscutting Concerns
-
-### Logging
-- **Format**: Structured JSON
-- **Fields**: timestamp, level, service, traceId, message, context
-- **Tool**: [NEEDS CLARIFICATION]
-
-### Authentication
-- **Method**: [NEEDS CLARIFICATION]
-- **Provider**: [NEEDS CLARIFICATION]
-- **Session**: [NEEDS CLARIFICATION]
-
-### Error Handling
-- **Pattern**: Result/Either in domain, global handler in infrastructure
-- **Alerting**: [NEEDS CLARIFICATION]
-
----
-
-## §9 Cost Estimate
-
-| Service | Monthly Cost | Annual Cost | Source |
-|---------|-------------|------------|--------|
-| Compute | [NEEDS CLARIFICATION] | | |
-| Database | | | |
-| Other | | | |
-| **Total** | | | |
-
-_Assumptions: user count, traffic, storage_
-
----
-
-## §10 Quality Scenarios
-
-| # | Quality Attribute | Scenario | Stimulus | Expected Response | Metric |
-|---|------------------|---------|----------|------------------|--------|
-| Q1 | Performance | [NEEDS CLARIFICATION] | | | |
-| Q2 | Scalability | | | | |
-| Q3 | Security | | | | |
-| Q4 | Availability | | | | |
-
----
-
-## §11 Risks & Technical Debt
-
-### Risk Register
-
-| # | Risk | Category | Probability | Impact | Score | Mitigation | Contingency |
-|---|------|----------|------------|--------|-------|-----------|-------------|
-| R1 | [NEEDS CLARIFICATION] | Technical | | | | | |
-| R2 | | Business | | | | | |
-
-### Known Technical Debt
-
-| # | Debt Item | Reason for Deferral | Impact if Not Addressed | Address By |
-|---|----------|--------------------|-----------------------|-----------|
-| TD1 | [NEEDS CLARIFICATION] | | | |
-
----
-
-## §12 Architecture Decision Records
-
-| # | Decision | Context | Options | Chosen | Rationale |
-|---|---------|---------|---------|--------|-----------|
-| ADR-1 | [NEEDS CLARIFICATION] | Why needed | A, B, C | Choice | Why |
-
----
-
-**Document Status**: Draft
-**Last Updated**: [Date]
+| Product behavior | Architecture path | Verification evidence |
+|---|---|---|
+| | | |

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

@@ -1,248 +1,51 @@
-# Product Discovery & Strategy
+# Discovery Record
 
-> Generated by `/ultra-research` Steps 00-05
-> Status: [NEEDS CLARIFICATION]
+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.
 
----
+## Scope
 
-## §0 Problem Validation Summary
+- Repository or product area:
+- Decision this research must unlock:
+- Evidence freshness boundary:
 
-### Product Stage
-- **Stage**: [NEEDS CLARIFICATION] — Pre-product / Has users / Has paying customers / Engineering-Infra
-- **Evidence**: [NEEDS CLARIFICATION]
+## Observed
 
-### Demand Signal
-- **Strength**: [NEEDS CLARIFICATION] — Strong / Moderate / Weak / Unvalidated
-- **Evidence**: [NEEDS CLARIFICATION] — Specific behaviors observed
-- **Risk**: [NEEDS CLARIFICATION] — What could invalidate this demand
+Record directly observed behavior, user input, repository facts, and sourced external
+facts. Identify the source and observation date.
 
-### Status Quo Analysis
-- **Current solutions**: [NEEDS CLARIFICATION] — What users do today
-- **Cost of workaround**: [NEEDS CLARIFICATION] — Time, money, friction
-- **Switching motivation**: [NEEDS CLARIFICATION] — Why they'd change
+| Evidence | Source or reference | Finding | Freshness |
+|---|---|---|---|
+| | | | |
 
-### Target User Profile
-- **Primary**: [NEEDS CLARIFICATION] — Specific role/person description
-- **Stakes**: [NEEDS CLARIFICATION] — What gets them promoted / fired
-- **Pain frequency**: [NEEDS CLARIFICATION] — Daily / Weekly / Occasional
+## Decisions
 
-### Narrowest Wedge
-- **MVP scope**: [NEEDS CLARIFICATION] — Single feature/workflow
-- **Willingness to pay**: [NEEDS CLARIFICATION]
-- **Ship timeline**: [NEEDS CLARIFICATION] — Days / Weeks / Months
+Record only accepted decisions. Include the reason, evidence, owner, and the contract
+or specification affected.
 
-### Validation Confidence
-- **Overall**: [NEEDS CLARIFICATION]%
-- **Strongest signal**: [NEEDS CLARIFICATION]
-- **Biggest risk**: [NEEDS CLARIFICATION]
-- **Recommended next step**: [NEEDS CLARIFICATION] — Proceed / Investigate further / Pivot
+| Decision | Reason and evidence | Owner | Affected contract |
+|---|---|---|---|
+| | | | |
 
----
+## Unknowns
 
-## §1 Opportunity Space
+Separate blocking unknowns from questions that are outside the accepted scope.
 
-### Desired Outcome
-- **Outcome**: [NEEDS CLARIFICATION] — Single measurable outcome
-- **Metric**: [NEEDS CLARIFICATION] — How we measure it
-- **Timeline**: [NEEDS CLARIFICATION] — When we expect movement
+| Unknown | Why it matters | Blocking | Owner or next evidence |
+|---|---|---|---|
+| | | | |
 
-### Opportunity Map
+## Current Behavior Notes
 
-| # | Opportunity (Customer Framing) | Importance | Satisfaction | Score | Source |
-|---|-------------------------------|-----------|-------------|-------|--------|
-| O1 | [NEEDS CLARIFICATION] | | | | |
-| O2 | | | | | |
-| O3 | | | | | |
+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.
 
-> Opportunity Score = Importance × (1 - Satisfaction)
+## Traceability
 
-### Prioritized Opportunities (Top 3)
+Link each consequential finding to the product or architecture section it informs.
 
-#### Opportunity 1: [NEEDS CLARIFICATION]
-- **Importance**: /10
-- **Current satisfaction**: — How users cope today
-- **Score**:
-- **Evidence**: Source URL
-
-**Solution Approaches:**
-1. **PM approach**: [NEEDS CLARIFICATION]
-2. **Design approach**: [NEEDS CLARIFICATION]
-3. **Engineering approach**: [NEEDS CLARIFICATION]
-
-### Key Insight
-[NEEDS CLARIFICATION] — Non-obvious insight from opportunity analysis
-
----
-
-## §2 Market Assessment
-
-### Market Sizing Summary
-
-| Metric | Current Estimate | 2-3 Year Projection | Source |
-|--------|-----------------|---------------------|--------|
-| TAM | [NEEDS CLARIFICATION] | | |
-| SAM | [NEEDS CLARIFICATION] | | |
-| SOM | [NEEDS CLARIFICATION] | | |
-
-### Top-Down Analysis
-
-#### TAM: [NEEDS CLARIFICATION]
-- **Definition**: Market category
-- **Source**: Report name + URL
-- **Growth**: CAGR
-
-#### SAM: [NEEDS CLARIFICATION]
-- **TAM filter 1**: Geographic
-- **TAM filter 2**: Segment
-- **TAM filter 3**: Technology fit
-
-#### SOM: [NEEDS CLARIFICATION]
-- **Realistic capture**: % of SAM
-- **Basis**: Why achievable
-- **Comparable**: Similar company reference
-
-### Bottom-Up Analysis
-
-| Variable | Value | Source |
-|----------|-------|--------|
-| Target customers | [NEEDS CLARIFICATION] | |
-| Conversion rate | [NEEDS CLARIFICATION] | |
-| ARPU (annual) | [NEEDS CLARIFICATION] | |
-| Retention rate | [NEEDS CLARIFICATION] | |
-| **Year 1 Revenue** | **Calculated** | |
-| **Year 3 Revenue** | **Calculated** | |
-
-### Cross-Validation
-- **Top-down SOM**: [NEEDS CLARIFICATION]
-- **Bottom-up Year 3**: [NEEDS CLARIFICATION]
-- **Ratio**: x
-- **Assessment**: [NEEDS CLARIFICATION]
-
-### Growth Drivers
-
-| # | Driver | Direction | Impact | Timeline | Source |
-|---|--------|-----------|--------|----------|--------|
-| 1 | [NEEDS CLARIFICATION] | | | | |
-
----
-
-## §3 Competitive Landscape
-
-### Competitive Overview
-
-| Dimension | Us | Competitor A | Competitor B | Do Nothing |
-|-----------|-----|-------------|-------------|------------|
-| Core value prop | [NEEDS CLARIFICATION] | | | Status quo |
-| Target segment | | | | Everyone |
-| Pricing | | | | Free |
-| Key strength | | | | Familiar |
-| Key weakness | | | | Inefficient |
-| Traction | | | | N/A |
-
-### Direct Competitors
-
-#### [NEEDS CLARIFICATION]
-- **What they do**:
-- **Strengths**:
-- **Weaknesses**: — Source: URL
-- **Pricing**: — Source: URL
-- **Traction**: — Source: URL
-- **Threat level**: High / Medium / Low
-
-### Indirect Competitors & Alternatives
-- [NEEDS CLARIFICATION]
-- **Do Nothing**: Cost of inaction
-
-### Porter's Five Forces Summary
-
-| Force | Rating | Assessment |
-|-------|--------|-----------|
-| Supplier power | [1-5] | [NEEDS CLARIFICATION] |
-| Buyer power | [1-5] | |
-| New entrant threat | [1-5] | |
-| Substitute threat | [1-5] | |
-| Rivalry intensity | [1-5] | |
-
-### Our Competitive Edge
-- **Where we can win**: [NEEDS CLARIFICATION]
-- **Where we cannot win**: [NEEDS CLARIFICATION]
-- **Unfilled gap**: [NEEDS CLARIFICATION]
-
----
-
-## §4 Product Strategy
-
-### Vision
-[NEEDS CLARIFICATION] — 2-3 sentences, inspiring, specific, ambitious
-
-### Target Segments
-
-#### Primary: [NEEDS CLARIFICATION]
-- **Description**: Defined by problem/JTBD
-- **Why them**: Why most urgent
-- **Value Proposition**: When [situation], they want [motivation], so they can [outcome]
-
-#### Explicitly NOT Serving
-- [NEEDS CLARIFICATION]: Why not
-
-### Strategic Trade-offs
-
-| # | We Choose | Over | Because |
-|---|-----------|------|---------|
-| 1 | [NEEDS CLARIFICATION] | | |
-| 2 | | | |
-| 3 | | | |
-
-### Defensibility
-
-| Moat Type | Applicable | Strength (1-5) | Timeline |
-|-----------|-----------|----------------|----------|
-| Network effects | [NEEDS CLARIFICATION] | | |
-| Data advantage | | | |
-| Switching costs | | | |
-| Brand / trust | | | |
-| Technical IP | | | |
-
----
-
-## §5 Key Assumptions & Validation Plan
-
-### Assumption Inventory
-
-| # | Assumption | Category | Impact | Uncertainty | Priority |
-|---|-----------|----------|--------|-------------|----------|
-| A1 | [NEEDS CLARIFICATION] | Value | | | |
-| A2 | | Viability | | | |
-| A3 | | GTM | | | |
-| A4 | | Feasibility | | | |
-| A5 | | Usability | | | |
-
-### Leap-of-Faith Assumptions (Top 3)
-
-#### A1: [NEEDS CLARIFICATION]
-- **Category**: Value / Viability / GTM
-- **Why it matters**: What happens if wrong
-- **Current evidence**: From steps 00-04
-
-**Validation Experiment:**
-- **Method**: [NEEDS CLARIFICATION]
-- **Success criteria**: Measurable outcome
-- **Failure criteria**: Measurable outcome
-- **Effort**: Hours/days
-- **Timeline**: When results expected
-
-**Decision Framework:**
-- If validated → Proceed to Round 1
-- If invalidated → Pivot / Investigate / Kill
-- If ambiguous → Additional experiment
-
-### Validation Roadmap
-
-| Week | Experiment | Assumption | Expected Result |
-|------|-----------|-----------|----------------|
-| 1 | [NEEDS CLARIFICATION] | A1 | |
-
----
-
-**Document Status**: Draft
-**Last Updated**: [Date]
+| Finding | Target specification | Status |
+|---|---|---|
+| | | |