ultra-builder-pro-cli 0.14.0 → 0.16.0

package/skills/ultra-plan/references/semantic-preflight.md

@@ -0,0 +1,18 @@
+# Semantic planning preflight
+
+Before task decomposition, read the normalized Change Contract and the current
+change-bound research records.
+
+1. Resolve every blocking `unresolved_decision` or return to `ultra-change`.
+2. When research is recorded, verify one completed run has the same mode and selected
+   step set. Re-run stale or missing evidence through `ultra-research`.
+3. Build a coverage ledger from Change acceptance ids to task acceptance ids.
+4. Bind every task to an accepted id, semantic record id, semantic source ref, or real
+   Markdown anchor through `trace_to`.
+5. Check that every task reaches a public consumer and owns its error, documentation,
+   verification, and recovery obligations.
+6. Validate dependencies and ensure a quick profile contains exactly one task.
+
+Treat the MCP completion result as the final planning gate. It derives the coverage
+matrix from durable records and rejects unresolved decisions, missing research,
+uncovered acceptance, orphan tasks, incomplete contracts, or invalid topology.

package/skills/ultra-research/SKILL.md

@@ -1,75 +1,117 @@
 ---
 name: ultra-research
-description: Turn uncertain product or architecture intent into evidence-backed baseline specifications with explicit decisions and traceable acceptance. Use when an Ultra project has unresolved requirements that are not ready for planning.
+description: Establish or extend an evidence-backed Ultra product and architecture baseline through the complete semantic research workflow, with resumable step state and traceable outputs. Use when initialization routes to research, baseline evidence is incomplete, or the owner explicitly requests bounded research for an active change.
 ---
 
-# Build a validated baseline
+# Establish research authority without overwhelming the owner
 
-Research only the uncertainty that blocks a durable product, architecture, or delivery
-decision. Do not force a fixed discovery ceremony onto a well-defined change.
+Use host reasoning to discover facts and synthesize artifacts. Use Ultra MCP for run
+position, decision authority, output digests, blockers, and convergence. Read
+`../ultra-think/references/decision-dialogue.md` before asking any owner question.
+Never ask MCP to generate research content.
 
-## Preflight
+## Bind the run
 
-1. Require an initialized `.ultra/specs/` directory and call `baseline.get`. Route to
-   `ultra-init` when state or the baseline is absent. Preserve its mode and id.
-2. Read the current specification files and repository evidence before asking the
-   user to repeat known facts.
-3. Define the intended deliverable, unresolved decisions, and evidence standard.
-4. Select only the research lanes that the uncertainty requires:
-   - problem and product: `references/problem-product.md`;
-   - users and scope: `references/users-scope.md`;
-   - architecture: `references/architecture.md`;
-   - quality and delivery: `references/quality-delivery.md`;
-   - final traceability: `references/synthesis.md`.
+1. Call `baseline.get`. Route absent, migrated, unreadable, or corrupt authority to
+   `ultra-init` or `ultra-doctor` as reported.
+2. Call `workflow.list` for `kind: "research"` and the bound baseline or change. Resume
+   the active, blocked, or ready run; use `workflow.get` before doing more work.
+3. When no run exists:
+   - start `full` for an initial greenfield baseline;
+   - start `adoption` for a brownfield baseline;
+   - use `product`, `feature`, `architecture`, or `custom` only when the owner
+     explicitly selected that bounded scope for an active change.
 
-Read a reference completely only when its lane is selected. Do not load all lanes by
-default.
+Never infer an MVP, reduced product posture, skipped step, or release phase. Full and
+adoption modes execute all seventeen semantic steps. A custom run records every
+excluded step and its selection reason in DB.
 
-## Evidence discipline
+## Preserve complete semantic coverage
 
-- Prefer the current checkout and existing project artifacts for repository facts.
-- Browse only when a claim is external, unstable, or requires primary-source support.
-- Prefer official and primary sources; cite each consequential external claim near the
-  statement it supports.
-- Separate observed facts, evidence-backed inferences, user decisions, and unresolved
-  assumptions.
-- Do not manufacture confidence percentages, market numbers, personas, competitors,
-  or options when evidence does not support them.
+Read only the reference matching `workflow.next_step.step_id`:
 
-## Workflow
+| Step | Reference |
+|---|---|
+| `00-problem-validation` | `references/00-problem-validation.md` |
+| `01-opportunity-discovery` | `references/01-opportunity-discovery.md` |
+| `02-market-assessment` | `references/02-market-assessment.md` |
+| `03-competitive-landscape` | `references/03-competitive-landscape.md` |
+| `04-product-strategy` | `references/04-product-strategy.md` |
+| `05-assumptions-validation` | `references/05-assumptions-validation.md` |
+| `10-user-personas` | `references/10-user-personas.md` |
+| `11-user-scenarios` | `references/11-user-scenarios.md` |
+| `20-user-stories` | `references/20-user-stories.md` |
+| `21-features-scope` | `references/21-features-scope.md` |
+| `22-success-metrics` | `references/22-success-metrics.md` |
+| `30-architecture-context` | `references/30-architecture-context.md` |
+| `31-solution-strategy` | `references/31-solution-strategy.md` |
+| `32-building-blocks` | `references/32-building-blocks.md` |
+| `40-deployment` | `references/40-deployment.md` |
+| `41-quality-risks` | `references/41-quality-risks.md` |
+| `99-synthesis` | `references/99-synthesis.md` |
 
-1. Build a short research agenda from the selected lanes and the decisions they must
-   unlock.
-2. Gather evidence before recommending a direction. Ask one concise question when a
-   user decision is load-bearing; batch independent low-impact questions only when it
-   improves flow.
-3. Present material tradeoffs before recording a decision. Comparisons are appropriate
-   only when real alternatives share meaningful criteria.
-4. Update the relevant baseline specification sections. Preserve source links,
-   decisions, rejected alternatives when useful, acceptance criteria, and explicit
-   open questions. Do not duplicate the same narrative across several files.
-5. Validate cross-document consistency and trace each required behavior from problem
-   or constraint to acceptance and architecture.
-6. Use `references/synthesis.md` for the completion check.
-7. Record unresolved evidence as the baseline gap ledger: `baseline_blocker`,
-   `documentation_drift`, `known_defect`, `technical_debt`, `unknown`, or
-   `future_change`. Keep accepted non-blocking work out of the implementation backlog
-   until the owner selects it.
-8. Call `baseline.record` with the complete current specification list, bounded evidence
-   references, actual verification results, provider metadata, explicit unknowns,
-   classification, and the full gap ledger. Use the returned repository revision for
-   convergence.
-9. Present the baseline, open gaps, dirty-worktree state, and any known-red verification
-   to the owner. After explicit approval, call `baseline.converge`, setting acceptance
-   flags only for the exact known-red or dirty snapshot approved by the owner. Resolve
-   deterministic blockers before routing.
+The seventeen steps are an internal completeness contract, not a questionnaire or the
+default user interface. For each selected step:
 
-## Completion gate
+1. Read only its reference and inspect repository, specification, runtime, tests, and
+   current primary-source evidence. Do not ask the owner to repeat observable facts.
+2. Separate `Observed`, `Verified`, `Decided`, and `Unknown`. Resolve evidence-answerable
+   unknowns autonomously and record evidence-backed `not_applicable` results.
+3. If a load-bearing owner decision remains, start or resume one decision thread bound
+   to this research workflow. Open the earliest dependent decision, present only that
+   question, and STOP. Do not update specifications or complete the workflow step while
+   its checkpoint is unconfirmed.
+4. After a coherent decision cluster, prepare one checkpoint. Present the compact
+   shared understanding and affected specifications, obtain approval, and apply the
+   accepted decisions.
+5. Update only the relevant baseline specification or active-change research artifact.
+   Preserve evidence, decisions, drift, and unknowns without copying conversation text.
+   Write the accepted cluster to the stable
+   `.ultra/docs/decisions/<thread-id>.md` projection and confirm its checkpoint with
+   that digest. Do not bind an intermediate shared specification that later research
+   steps are expected to extend.
+6. Write one immutable step report at
+   `.ultra/docs/research/<workflow-id>/<step-id>.md`. It must have a title and the
+   sections `Evidence`, `Specification updates`, and `Decisions and unknowns`. Link
+   specification anchors and external sources; do not copy transcripts or provider
+   payloads.
+7. Call `workflow.step` with `completed`, bounded evidence references, that step report
+   as `research-step-report`, material decisions, and one or more `semantic_records`.
+   Each record has a stable `id`, the step-specific `kind` and `attributes` named in
+   its reference, a status (`observed`, `verified`, `decided`, `accepted`, `unknown`,
+   or `not_applicable`), a concise summary, evidence refs, optional typed links, and a
+   project-relative `source_ref` using `path#anchor`. Use the immutable step report as
+   the source when later edits could change a shared specification. MCP verifies the
+   anchor and stores its digest; `not_applicable` requires an evidence-backed rationale.
+8. For `99-synthesis` in `full` or `adoption` mode, also bind the current
+   `discovery.md`, `product.md`, `architecture.md`, and `research-distillate.md` as
+   outputs. This freezes the exact researched baseline without making the reports a
+   second specification authority.
+9. If evidence or owner authority is missing, call `workflow.step` with `blocked` and
+   specific blocker codes. Resume that same step after resolution; never skip a
+   required step to obtain a ready state.
 
-Research is complete when the selected scope has enough evidence for planning, every
-material decision is recorded, required acceptance is testable, architecture respects
-known constraints, and unresolved items are either blocking or explicitly outside the
-accepted scope.
+## Converge
 
-Route a converged baseline to `ultra-plan`. Do not create business tasks, write raw
-SQLite, or maintain a second condensed specification that can drift from the baseline.
+When all selected steps are ready, call `workflow.complete` and read the completed run
+back. Missing or stale output blocks completion.
+
+For initial or adoption research, call `baseline.record` with discovery, product, and
+architecture specification refs; current repository revision and scope; bounded source,
+docs, runtime, test, deployment, and external evidence; actual verification commands
+and results; unknowns; the complete gap ledger; classification; and external provider
+metadata references. Do not store prompts, transcripts, memory, or graph content.
+
+Present the recorded revision, worktree snapshot, known failures, blockers, and gaps.
+Only after explicit owner approval call `baseline.converge`. Reuse the final research
+checkpoint approval when it names this exact recorded revision, worktree snapshot,
+known failures, blockers, and gaps; do not ask for an equivalent approval again. If
+that snapshot changed, prepare one refreshed checkpoint instead. Accept known-red or a
+dirty worktree only when that exact snapshot was approved. Convergence must verify the
+completed full/adoption research run and current output digests.
+
+Return a compact checkpoint: workflow id, completed/selected semantic coverage,
+current decision or blocker, baseline state, open gaps, approval state, and one route.
+Do not print all seventeen report paths unless requested; they remain discoverable
+through workflow state. A ready initial baseline routes to `ultra-change`; bounded
+change research returns to its breadcrumb and then `ultra-plan` when ready.

package/skills/ultra-research/references/00-problem-validation.md

@@ -0,0 +1,36 @@
+# Problem validation
+
+Use for workflow step `00-problem-validation`.
+
+## Objective
+
+Establish the problem, affected actor, current workaround, consequence, and available
+demand evidence. In brownfield adoption, describe the behavior the current system
+already serves before discussing future intent.
+
+## Evidence
+
+- Inspect existing product documents, user-facing entry points, support evidence, and
+  runtime behavior before asking the owner for facts already present.
+- Treat an owner statement as a decision or claim, not as observed user evidence.
+- Record absent evidence as `Unknown`; do not invent demand, urgency, or a target user.
+- Use external research only when a consequential claim depends on current facts.
+
+## Record
+
+Update `discovery.md` with `Observed`, `Verified`, `Decided`, and `Unknown` entries for:
+
+- problem and affected actor;
+- current workaround and consequence;
+- demand or usage evidence;
+- the narrowest owner-approved problem boundary;
+- unresolved validation needs.
+
+Link the updated specification anchor from the immutable step report required by the
+orchestrator. A missing load-bearing fact becomes a blocker or baseline gap, not a
+guessed answer.
+
+## Semantic record
+
+Use kind `problem`. Record `actor`, `current_workaround`, `consequence`, and
+`evidence_status`.

package/skills/ultra-research/references/01-opportunity-discovery.md

@@ -0,0 +1,33 @@
+# Opportunity discovery
+
+Use for workflow step `01-opportunity-discovery`.
+
+## Objective
+
+Connect the validated problem to desired outcomes and evidence-backed opportunities.
+Describe opportunities from the actor's perspective rather than as a feature list.
+
+## Evidence
+
+- Derive current outcomes from observed workflows, existing behavior, interviews, or
+  owner decisions.
+- Preserve causal links between a problem, an unmet outcome, and its evidence.
+- Do not force rankings, solution brainstorming, or a fixed number of opportunities.
+- Record opportunities that lack evidence as unknown or future research.
+
+## Record
+
+Update `discovery.md` with:
+
+- desired outcomes and their evidence;
+- opportunity statements and affected actors;
+- constraints or dependencies;
+- owner-decided priority when one exists;
+- rejected or deferred opportunities only when that decision is durable.
+
+Complete the step with the evidence used and the updated output path.
+
+## Semantic record
+
+Use kind `opportunity`. Record `actor`, `desired_outcome`, and `evidence_status`. Link
+the record to its problem when that relation is established.

package/skills/ultra-research/references/02-market-assessment.md

@@ -0,0 +1,30 @@
+# Market assessment
+
+Use for workflow step `02-market-assessment`.
+
+## Objective
+
+Record only market facts that materially affect product scope, economics, regulation,
+or delivery. For an internal tool or a brownfield system with no market decision, state
+that boundary and retain the evidence supporting it.
+
+## Evidence
+
+- Prefer current primary sources, filings, official statistics, and directly observed
+  commercial data.
+- Preserve source date, geography, segment definition, and calculation assumptions.
+- Do not manufacture TAM, growth rates, pricing, or false numeric precision.
+- Separate externally verified facts from owner targets and estimates.
+
+## Record
+
+Update `discovery.md` with relevant segment boundaries, commercial or operational
+constraints, source-backed measurements, assumptions, and unknowns. Include a sizing
+model only when the decision genuinely depends on one and the inputs are defensible.
+
+Link source references and the updated specification anchor from the immutable step
+report required by the orchestrator.
+
+## Semantic record
+
+Use kind `market_constraint`. Record `constraint`, `decision_impact`, and `freshness`.

package/skills/ultra-research/references/03-competitive-landscape.md

@@ -0,0 +1,31 @@
+# Competitive landscape
+
+Use for workflow step `03-competitive-landscape`.
+
+## Objective
+
+Identify the alternatives actors actually use and the consequences for strategy.
+Alternatives may include direct products, adjacent tools, manual workflows, or doing
+nothing.
+
+## Evidence
+
+- Use current product documentation, pricing, repositories, filings, or observed user
+  workflows.
+- Evaluate only criteria that change the decision at hand.
+- Do not create a ceremonial matrix, fixed competitor count, or unsupported claim of
+  superiority.
+- Distinguish a verified capability from marketing language and inference.
+
+## Record
+
+Update `discovery.md` with the relevant alternatives, evidence, meaningful differences,
+switching constraints, and durable strategy implications. Record an unknown when a
+credible alternative cannot be verified.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `alternative`. Record `category`, `switching_constraint`, and
+`strategy_implication`.

package/skills/ultra-research/references/04-product-strategy.md

@@ -0,0 +1,32 @@
+# Product strategy
+
+Use for workflow step `04-product-strategy`.
+
+## Objective
+
+Turn accepted evidence into a product direction, target boundary, value proposition,
+and explicit tradeoffs.
+
+## Evidence and decisions
+
+- Derive constraints from prior research and current system behavior.
+- Ask the owner when a scope, customer, business, or risk decision is load-bearing.
+- Do not infer an MVP, reduced scope, release phase, or commercial posture.
+- Record exclusions only when the owner or an accepted constraint establishes them.
+
+## Record
+
+Update `discovery.md` with:
+
+- product direction and intended actors;
+- value delivered through observable behavior;
+- chosen tradeoffs and their rationale;
+- constraints, exclusions, and unresolved decisions;
+- any defensibility claim with its supporting evidence.
+
+Complete the step with decision and evidence references plus the updated output path.
+
+## Semantic record
+
+Use kind `strategy_decision`. Record `tradeoff` and `rationale`, then link the decision
+to the problems, opportunities, or constraints that support it.

package/skills/ultra-research/references/05-assumptions-validation.md

@@ -0,0 +1,31 @@
+# Assumptions and validation
+
+Use for workflow step `05-assumptions-validation`.
+
+## Objective
+
+Make load-bearing assumptions visible and define the smallest credible evidence needed
+to confirm or reject them.
+
+## Method
+
+- Extract assumptions from problem, opportunity, market, alternative, and strategy
+  claims.
+- Separate already verified facts from assumptions and owner decisions.
+- Prioritize by consequence and uncertainty only when prioritization affects the next
+  action; do not assign arbitrary scores.
+- Define a validation signal, evidence source, decision rule, owner, and recovery path.
+
+## Record
+
+Update `discovery.md` with the assumption ledger and validation state. Map unresolved
+load-bearing assumptions to blocking unknowns or gaps. Keep non-blocking future work
+out of the implementation task graph until the owner selects it.
+
+Link evidence and the updated specification anchor from the immutable step report
+required by the orchestrator.
+
+## Semantic record
+
+Use kind `assumption`. Record `category`, `consequence`, `validation_signal`,
+`success_rule`, `failure_rule`, and `ambiguous_rule`.

package/skills/ultra-research/references/10-user-personas.md

@@ -0,0 +1,29 @@
+# Actors and jobs
+
+Use for workflow step `10-user-personas`.
+
+## Objective
+
+Describe evidence-backed actors, their jobs, operating context, goals, constraints, and
+adoption barriers. A role or actor model is sufficient; do not invent demographic
+personas.
+
+## Evidence
+
+- Prefer observed workflows, access roles, support evidence, usage data, and owner
+  decisions.
+- Link each actor to a real entry point or intended behavior.
+- Mark unverified motivations and pain points as unknown.
+- In brownfield adoption, document the actors represented by current code and runtime,
+  even when product research is incomplete.
+
+## Record
+
+Update `product.md` with actor identity, job, context, current workflow, desired outcome,
+constraints, and evidence. Record priority only when it is an accepted decision.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `actor`. Record `job`, `current_workflow`, `goal`, and `constraint`.

package/skills/ultra-research/references/11-user-scenarios.md

@@ -0,0 +1,28 @@
+# User scenarios
+
+Use for workflow step `11-user-scenarios`.
+
+## Objective
+
+Trace the important current and intended journeys from trigger through outcome,
+including failure and recovery.
+
+## Method
+
+- Bind each scenario to an evidence-backed actor and entry point.
+- Describe the current path before proposing a changed path in brownfield adoption.
+- Include state changes, external systems, permissions, and observable outcomes.
+- Do not force a fixed scenario count or emotional narrative.
+
+## Record
+
+Update `product.md` with scenario id, actor, trigger, preconditions, current or intended
+flow, success outcome, failure outcome, recovery, and evidence. Mark gaps where runtime
+behavior and documentation disagree.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `scenario`. Record `actor_id`, `trigger`, `preconditions`, `flow`, `success`,
+`failure`, and `recovery`.

package/skills/ultra-research/references/20-user-stories.md

@@ -0,0 +1,30 @@
+# Behavioral requirements and acceptance
+
+Use for workflow step `20-user-stories`.
+
+## Objective
+
+Translate accepted scenarios into testable behavior without prematurely designing the
+implementation.
+
+## Method
+
+- Use stable requirement identifiers.
+- State preconditions, action, observable result, error behavior, and recovery where
+  relevant.
+- Trace every requirement to a scenario, constraint, or owner decision.
+- Preserve current delivered behavior separately from proposed behavior.
+- Do not use priority labels as a substitute for explicit scope decisions.
+
+## Record
+
+Update `product.md` with requirements and acceptance criteria that can map to an
+executable check or deliberate manual evidence. Record unknown behavior instead of
+writing vague acceptance.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `requirement`. Record `preconditions`, `action`, `observable_result`,
+`error_recovery`, and `verification`. Link it to its accepted scenario or decision.

package/skills/ultra-research/references/21-features-scope.md

@@ -0,0 +1,29 @@
+# Capability and scope boundary
+
+Use for workflow step `21-features-scope`.
+
+## Objective
+
+Group accepted behavior into coherent capabilities and record what is included,
+excluded, deferred, or unresolved.
+
+## Rules
+
+- Preserve the owner's stated product and release posture.
+- Never infer an MVP, reduced version, phase label, or omission from implementation
+  convenience.
+- Trace included capabilities to requirements and observable outcomes.
+- Record dependencies, migrations, compatibility, and operational obligations inside
+  the capability that owns them.
+- Keep speculative future ideas outside the active scope unless selected.
+
+## Record
+
+Update `product.md` with capability boundaries, included requirements, explicit
+exclusions and rationale, dependencies, and unresolved scope decisions.
+
+Complete the step with decision evidence and the updated output path.
+
+## Semantic record
+
+Use kind `capability`. Record `requirement_ids`, `scope_status`, and `rationale`.

package/skills/ultra-research/references/22-success-metrics.md

@@ -0,0 +1,28 @@
+# Outcomes and measurements
+
+Use for workflow step `22-success-metrics`.
+
+## Objective
+
+Define how the owner will know the accepted behavior and product outcome are working,
+including signals that would reveal harmful optimization.
+
+## Method
+
+- Derive measurements from accepted outcomes and available instrumentation.
+- State definition, source, observation window, owner, and decision use.
+- Separate current measurements, target decisions, and unavailable telemetry.
+- Do not invent baselines, targets, or a single north-star metric.
+
+## Record
+
+Update `product.md` with outcome measures, operational measures, guardrails, evidence
+availability, and unresolved instrumentation needs. A metric that cannot be observed
+must be recorded as a gap or explicit future change.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `metric`. Record `definition`, `source`, `window`, `owner`, and
+`decision_use`.

package/skills/ultra-research/references/30-architecture-context.md

@@ -0,0 +1,30 @@
+# Architecture context
+
+Use for workflow step `30-architecture-context`.
+
+## Objective
+
+Establish current system boundaries, quality goals, constraints, actors, external
+systems, and data flows.
+
+## Evidence
+
+- Inspect code entry points, configuration, schemas, deployment assets, tests, and
+  runtime evidence.
+- Separate observed architecture from intended architecture.
+- Record permissions, data sensitivity, compliance, and organizational constraints
+  when they affect the design.
+- Do not infer a greenfield architecture over an existing system.
+
+## Record
+
+Update `architecture.md` with system context, external dependencies, trust boundaries,
+data flows, quality goals, constraints, and evidence. Record documentation drift when
+the current checkout contradicts an existing diagram or claim.
+
+Complete the step with source or runtime evidence and the updated output path.
+
+## Semantic record
+
+Use kind `architecture_context`. Record `boundary`, `inputs_outputs`,
+`trust_authority`, and `consumers`.

package/skills/ultra-research/references/31-solution-strategy.md

@@ -0,0 +1,28 @@
+# Solution strategy
+
+Use for workflow step `31-solution-strategy`.
+
+## Objective
+
+Record architecture decisions that satisfy accepted behavior and constraints while
+preserving current repository patterns where they remain valid.
+
+## Method
+
+- Search for existing implementations and dependencies before proposing new ones.
+- Evaluate alternatives only when more than one credible choice remains and the choice
+  materially affects the contract.
+- Record decision drivers, chosen direction, consequences, compatibility, and recovery.
+- Do not force a new stack, fixed option count, scoring model, or arbitrary preference.
+
+## Record
+
+Update `architecture.md` with accepted strategy decisions and their evidence. Preserve
+unresolved decisions as blockers rather than selecting on the owner's behalf.
+
+Complete the step with decision evidence and the updated output path.
+
+## Semantic record
+
+Use kind `architecture_decision`. Record `drivers`, `direction`, `consequences`,
+`compatibility`, and `recovery`.

package/skills/ultra-research/references/32-building-blocks.md

@@ -0,0 +1,28 @@
+# Building blocks and runtime paths
+
+Use for workflow step `32-building-blocks`.
+
+## Objective
+
+Map responsibilities, contracts, data ownership, consumers, and runtime behavior across
+the current or accepted architecture.
+
+## Method
+
+- Start from real modules and live entry points in brownfield adoption.
+- Define boundaries by responsibility and authority, not by an imposed layer diagram.
+- Trace key scenarios through validation, domain behavior, persistence, integrations,
+  observable output, failure, and recovery.
+- Identify unreachable scaffolding, duplicate authority, and undocumented coupling.
+
+## Record
+
+Update `architecture.md` with building blocks, public contracts, ownership, dependencies,
+runtime paths, error paths, and evidence. Link each proposed block to a consumer.
+
+Complete the step with source evidence and the updated output path.
+
+## Semantic record
+
+Use kind `runtime_path`. Record `entry_point`, `state_side_effects`,
+`observable_result`, `failure_recovery`, and `consumers`.