aw-spec-cli 0.1.16 → 0.1.17

package/assets/.appweaver/orchestrator/rev-templates/tech-rule-bindings.skeleton.md

@@ -50,11 +50,14 @@ refers to it directly, as-is.
 - guardrails/projects/[project]/service/[each generated architecture/cross-cutting rule].md
 
 ## /aw-spec-implement
-<!-- The framework / code-generation rule set the generator builds against (from design.md). -->
+<!-- The framework / code-generation rule set the SERVICE lane's generator builds against
+     (from backend-plan.md). -->
 - guardrails/projects/[project]/service/[each generated codegen/convention rule].md
 
 ## /aw-spec-implement-delta
-<!-- The CR analog of implement — same code-generation set, scoped to the delta-design. -->
+<!-- The same set for the service lane on the DELTA path. `implement` is one command: it keys
+     this heading when it is generating a change's delta plan and the one above when it is
+     generating the master, so repeat the bullets here to keep both paths identical. -->
 - guardrails/projects/[project]/service/[each generated codegen/convention rule].md
 
 ## /aw-spec-build
@@ -62,7 +65,7 @@ refers to it directly, as-is.
 - guardrails/projects/[project]/service/[as-built-architecture].md
 
 ## /aw-spec-analyze-slice
-<!-- The spec↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
+<!-- The design↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
 - guardrails/projects/[project]/service/[testing/convention rule to validate against].md
 
 ## /aw-spec-adopt
@@ -86,34 +89,13 @@ refers to it directly, as-is.
      a runtime/hosting concern file. NOT data-migration (migration is the deferred later phase). -->
 - guardrails/projects/[project]/service/[runtime/hosting rule].md
 
-<!-- THE FRONTEND LANE'S THREE HEADINGS. None of them is written by the step that authors
-     this map; onboard's frontend rule-set step APPENDS all three here, after the technical
-     headings and before the quick-reference table, and ONLY where the scan found a UI in the
-     code. A backend-only repo never gets any of them, which is correct and not an omission.
-
-     ## /aw-spec-ui-constitution — the ratifiable lane standards, frontend/ui-constitution.md
-       first. It is also the authoritative signal that this project HAS a frontend lane: a
-       later /appweaver constitution reads it to decide whether to author constitution.ui.md
-       at all.
-     ## /aw-spec-plan-ui       — the DESIGN set /appweaver plan-ui works from when it authors
-       or conforms frontend-plan.md: composition, routing, client state, interaction states,
-       forms, accessibility, i18n, performance — whichever of those the generated set holds.
-     ## /aw-spec-implement-ui  — the CODE-GENERATION set /appweaver implement-ui builds
-       against: conventions, the client/service pairing, styling, forms, accessibility, i18n,
-       performance, testing — again, whichever exist.
-
-     THE TWO PHASE SETS OVERLAP ON PURPOSE. A concern like forms, accessibility, i18n or
-     performance carries a DESIGN half and an IMPLEMENT half of one rule — the design decides
-     the states, affordances and targets; implement realises them. A rule mapped under only
-     one heading loses the pairing, and the half that goes unread is the half that goes
-     unbuilt. Map such a file under BOTH.
-
-     WHY ALL THREE AND NOT JUST THE FIRST. `## /aw-spec-ui-constitution` alone wires the lane
-     for re-ratification and NOTHING else: with no `## /aw-spec-plan-ui`, plan-ui loads zero
-     mapped frontend rules and designs the experience from constitution.ui.md alone, while the
-     files it needed sit on disk unreferenced — and because an absent heading soft-continues,
-     nobody is told. Both phases ship (/appweaver plan-ui, /appweaver implement-ui), so both
-     headings are claims the kit CAN honour.
+<!-- ## /aw-spec-ui-constitution — the FRONTEND LANE's heading. It is NOT written by the step
+     that authors this map; onboard's frontend rule-set step APPENDS it here, after the technical
+     headings and before the quick-reference table, but only where the scan found a UI in the
+     code. It maps the generated frontend/ lane rules (frontend/ui-constitution.md first), and
+     it is also the authoritative signal that this project HAS a frontend lane — a later
+     /appweaver constitution reads it to decide whether to author constitution.ui.md at all.
+     A backend-only repo simply never gets the heading.
 
      Do NOT add /aw-spec-characterize or /aw-spec-parity in the DEV flow — characterize is
      opt-on-touch and parity is deferred to the migration phase. Add any other heading later
@@ -128,16 +110,10 @@ refers to it directly, as-is.
 |---|---|---|
 | /aw-spec-specify | 1 | the as-built modelling methodology the domain model is expressed in — no technology |
 | /aw-spec-plan | [n] | as-built architecture the design author mediates the spec against |
-| /aw-spec-implement | [n] | code-generation set the generator builds against (from design.md) |
-| /aw-spec-implement-delta | [n] | same code-generation set, scoped to the open change's delta-design |
+| /aw-spec-implement | [n] | code-generation set the service lane builds against (from backend-plan.md) |
+| /aw-spec-implement-delta | [n] | the same set for the service lane when implement is generating a change's delta plan |
 | /aw-spec-build | [n] | layering + convention rules the compile-fixer respects |
-| /aw-spec-analyze-slice | [n] | conformance rules the spec↔code gate validates against |
+| /aw-spec-analyze-slice | [n] | conformance rules the design↔code gate validates against |
 | /aw-spec-adopt | [n] | technical reference set for the reversed design (brownfield) |
 | /aw-spec-constitution | [n] | the standards the technical constitution half is re-ratified from |
 | /aw-spec-run | [n] | runtime/execution conventions the app-run step honors (only if evidenced) |
-
-<!-- The frontend lane's rows are appended by the same step that appends its headings, and
-     only where the lane exists:
-| /aw-spec-ui-constitution | [n] | the ratifiable lane standards the UI constitution half is re-ratified from |
-| /aw-spec-plan-ui | [n] | the as-built experience rules plan-ui authors frontend-plan.md against |
-| /aw-spec-implement-ui | [n] | the as-built code-generation set implement-ui builds the UI against | -->

package/assets/.appweaver/orchestrator/rev-templates/ui-delta-design-template.skeleton.md

@@ -2,7 +2,7 @@
   ═══════════════════════════════════════════════════════════════════════════
   rev-templates/ui-delta-design-template.skeleton.md — SHAPE-ONLY reference.
 
-  This file is the FORMAT reference for the reverse-engineered UI DELTA-design
+  This file is the FORMAT reference for the reverse-engineered UI DELTA PLAN
   TEMPLATE that onboard installs at
   .appweaver/templates/overrides/ui-delta-design-template.md — the frontend lane's
   twin of delta-design-template.skeleton.md, written only where the CODE has a
@@ -10,14 +10,14 @@
   sections, the two ledgers and the close contract, and NOTHING ELSE.
 
   IT NAMES NO FRAMEWORK AND NO FIXED UI TAXONOMY. The "Section" column is a
-  SLOT, filled with the ACTUAL sections of the UI design template generated
+  SLOT, filled with the ACTUAL sections of the frontend plan template generated
   alongside this one — including whatever composition axes §3 turned out to
   carry. A change is classified against the document it amends.
 
   ONE CHANGE, TWO LANES, ONE VERSION. A change request that touches both lanes
   produces a service delta AND this one; `finalize-delta` merges the three
-  masters (spec.md, design.md, design.ui.md) and the change closes on ONE
-  version bump. This record never opens a second UI design document, and it
+  masters (spec.md, backend-plan.md, frontend-plan.md) and the change closes on ONE
+  version bump. This record never opens a second plan document, and it
   never restates the service delta — where the change starts in the service
   contract, this document records only what the EXPERIENCE does with it.
 
@@ -30,24 +30,31 @@
     • STATES ARE PART OF THE CHANGE — a new interaction that ships without its
       loading, empty, error and permission-denied states is an incomplete delta,
       not a later refinement.
+    • WAVE ORDERS THE OPEN CHANGES — a lower wave may be built on, a same wave
+      is visible but never assumed.
     • TECHNOLOGY-AGNOSTIC — responsibilities, field shapes and events, no code.
   ═══════════════════════════════════════════════════════════════════════════
 -->
-# UI Delta Design — [CR-ID]: [TITLE]
+# Delta Frontend Plan — [CR-ID]: [TITLE]
 
-**Feature (aggregate)**: [Aggregate]
+**Feature (aggregate slice)**: [Feature]
 
 **Base version**: [vX.Y]
 
-**Service delta**: [the companion delta-design for this CR, or `None — experience-only change`]
+**Wave**: [N]   <!-- script-stamped; same wave = developable in parallel, higher wave = after -->
+
+**Delta spec**: `changes/[CR-ID]/delta-spec.md`
+
+**Service delta**: [`changes/[CR-ID]/delta-backend-plan.md`, or `None — experience-only change`]
 
 <!--
-  This delta applies to the SINGLE master UI design at
-  specs/[Aggregate]/design.ui.md — never a new document. Classify every change
+  This delta applies to the SINGLE master plan at
+  specs/[Context]/[Feature]/frontend-plan.md — never a new document, and never the
+  master itself: finalize-delta merges it later in the chain. Classify every change
   ADDED / MODIFIED / REMOVED against the current master, per the MASTER'S OWN
   SECTIONS, in the same technology-agnostic form: responsibilities, inputs as
-  field shapes, events and states — no code. After this delta is applied,
-  ⌛ `ui-implement-delta` regenerates the touched UI and regression re-verifies
+  field shapes, events and states — no code. `implement`'s frontend lane
+  generates the touched UI from this document and regression re-verifies
   every screen that shares a changed component or state.
 -->
 
@@ -56,13 +63,20 @@
 [One paragraph: what the experience change is and which user story / spec delta
 it serves.]
 
+## Depends on
+
+<!-- Other OPEN changes this plan builds on. Every entry MUST be in a LOWER wave.
+     "None — stands alone" is the common and preferred answer. -->
+
+- `[CR-ID]` (wave [N-1]) — [what this plan assumes from it]
+
 ## ADDED — new UI elements
 
 <!-- New screens, components, state, interactions or contract bindings.
      "Section" names a section of THIS project's master UI design — the same
      section titles the generated UI design template carries. -->
 
-| Section (§ in design.ui.md) | Element | Kind | Serves |
+| Section (§ in frontend-plan.md) | Element | Kind | Serves |
 |---|---|---|---|
 | [§ of the master's own structure] | `[element]` | [screen / component / state / binding] | US-[n] · FR-[nnn] |
 
@@ -71,7 +85,7 @@ it serves.]
 <!-- Edits to elements the master already defines. A shared component or a
      shared state container is modified here, in place — never copied. -->
 
-| Section (§ in design.ui.md) | Element | What changes | Why |
+| Section (§ in frontend-plan.md) | Element | What changes | Why |
 |---|---|---|---|
 | [§ of the master's own structure] | `[element]` | [the edit] | US-[n] |
 
@@ -102,6 +116,13 @@ never worked around in the client. Or `None`.]
 touched; navigation edges added or removed; any screen in ANOTHER feature that
 depends on a changed shared element.]
 
+## Other open deltas
+
+<!-- Which OTHER open changes touch the same screens, shared components or state
+     containers. `None` when this change stands clear of everything in flight. -->
+
+- `[CR-ID]` (wave [N]) — [what overlaps, and how this plan stays clear of it]
+
 ## Regression targets
 
 [Existing user stories / screens to re-verify because a shared component, a
@@ -117,7 +138,7 @@ shared state container or a navigation edge changed.]
 
 ## On close
 
-`finalize-delta` merges this record into the master design.ui.md alongside the
-spec and service-design merges, and appends the Change History row;
-`close-delta` bumps the ONE version both lanes share and archives the change
-under `changes/archive/`.
+`finalize-delta` merges this record into the master frontend-plan.md alongside the
+spec, service-plan and domain-model merges and leaves the change OPEN;
+`close-delta` bumps the ONE version both lanes share, writes the Change History
+rows and archives the change under `changes/archive/`.

package/assets/.appweaver/orchestrator/rev-templates/ui-design-template.skeleton.md

@@ -12,8 +12,8 @@
   IT NAMES NO FRAMEWORK, ROUTER, STATE LIBRARY, COMPONENT LIBRARY, DESIGN
   SYSTEM OR STYLING APPROACH. "Component", "screen", "route" and "state
   container" are CONCEPTUAL here — the same way the service design says
-  "repository" without naming an ORM. The framework binds later, at
-  ⌛ `ui-implement`, from constitution.ui.md plus that command's rule set. A
+  "repository" without naming an ORM. The framework binds later, in the
+  FRONTEND LANE of `implement`, from constitution.ui.md plus that lane's rule set. A
   named example in a skeleton becomes law in a lane it does not fit, and the
   frontend is where that risk is highest. Every [BRACKET] is filled FROM THE
   LANE'S OWN CODE.
@@ -21,10 +21,10 @@
   THIS IS A TEMPLATE OF A TEMPLATE. What onboard generates from it is the
   project's UI design TEMPLATE — [PLACEHOLDER] tokens and authoring comments
   intact — which ⌛ `ui-design` then fills once per feature into
-  specs/<Feature>/design.ui.md. Onboard replaces the STRUCTURE, not the content.
+  specs/<Context>/<Feature>/frontend-plan.md. Onboard replaces the STRUCTURE, not the content.
 
   THE SECTION LIST IS RATIFIED, NOT INVENTED. §1–§9 below are the sections
-  aw-spec specifies for design.ui.md (Navigation & screen structure · Client
+  aw-spec specifies for frontend-plan.md (Navigation & screen structure · Client
   state · Component structure · Interaction & flow · Contract binding ·
   Cross-cutting · Traceability · DA-n · WA-n), keeping the neutral bones the
   service design earned. What the CODE supplies is what goes IN them — the
@@ -61,7 +61,7 @@
 
 **Aggregate (feature)**: `[Aggregate]`
 
-**Design home**: `specs/[Aggregate]/design.ui.md`
+**Plan home**: `specs/[Context]/[Feature]/frontend-plan.md`
 
 **Source spec**: `specs/[Aggregate]/spec.md`
 
@@ -75,8 +75,8 @@
   WHAT THIS DOCUMENT IS
   =====================
   The single, living high-level UI design for ONE feature's experience — the
-  MEDIATOR between spec.md (WHAT/WHY) and the frontend code ⌛ `ui-implement`
-  generates. It carries screens, navigation, state, composition, interaction
+  MEDIATOR between spec.md (WHAT/WHY) and the frontend code `implement`
+  generates in this lane. It carries screens, navigation, state, composition, interaction
   and the service binding; it is not code and it is not a visual comp.
 
   ANCHORING RULES
@@ -285,7 +285,7 @@ client. Or `None`.]
 
 ## Change History
 
-<!-- In lockstep with spec.md and design.md — a change that touches both lanes
+<!-- In lockstep with spec.md and backend-plan.md — a change that touches both lanes
      closes on ONE version bump. finalize-delta appends the row; close-delta
      bumps the version and stamps it into the header. Newest last. -->
 

package/assets/.appweaver/orchestrator/workflows/aw-spec-adopt.orch.yaml

@@ -13,7 +13,7 @@
 # Adopt is JUST-IN-TIME and per-feature: reverse ONLY the feature you are about to
 # develop, never the whole codebase (that scale is what onboard's shallow feature map
 # avoids). A NEW feature (no existing code) is NOT adopted — it is authored straight
-# through the forward pipeline (/appweaver specify → design → implement), which
+# through the forward pipeline (/appweaver specify → plan → implement), which
 # onboard already made brownfield-ready (the code-derived design template is the
 # project default). So adopt = reverse an EXISTING feature; the forward pipeline = a
 # new one. Both then evolve through the CR delta loop.
@@ -189,7 +189,7 @@ workflow:
     action: verify_context
     require_non_empty: guard_sentinel
     on_empty: stop
-    on_empty_message: "specs/ already has a spec.md for {{feature_name}} — adopt is a one-time baseline. For a change to an adopted slice use the CR delta loop (/appweaver specify → design → analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta); to re-adopt from scratch, remove the feature dir first."
+    on_empty_message: "specs/ already has a spec.md for {{feature_name}} — adopt is a one-time baseline. For a change to an adopted slice use the CR delta loop (/appweaver specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta); to re-adopt from scratch, remove the feature dir first."
 
   # 1b. Resolve this aggregate's OKF bundle concept → its source_files (the code
   #     that IS the slice) + module dir. The INDEX adopt reverse-engineers FROM;
@@ -218,7 +218,7 @@ workflow:
     action: verify_context
     require_true: concept_exists
     on_false: stop
-    on_false_message: "No feature '{{feature_name}}' in the onboard feature map under {{bundle_dir}}. If you have not onboarded, run /appweaver onboard first, then use the exact feature name from {{bundle_dir}}/aggregates/index.md. If '{{feature_name}}' is a NEW feature (no existing code), do NOT adopt it — author it through the forward pipeline (/appweaver specify → design → implement), which onboard already made brownfield-ready."
+    on_false_message: "No feature '{{feature_name}}' in the onboard feature map under {{bundle_dir}}. If you have not onboarded, run /appweaver onboard first, then use the exact feature name from {{bundle_dir}}/aggregates/index.md. If '{{feature_name}}' is a NEW feature (no existing code), do NOT adopt it — author it through the forward pipeline (/appweaver specify → plan → implement), which onboard already made brownfield-ready."
 
   # Governance prerequisite: the reverse steps below are authored AGAINST the project
   # onboard established (the constitution halves + guardrails/projects/<project>/ rule set).
@@ -360,8 +360,8 @@ workflow:
       - { path: .appweaver/memory/constitution.ui.md, optional: true }         # the frontend lane's UX-* base — absent on a backend-only repo, which onboard leaves unwritten by design
   - id: reverse_spec
     action: agent_author
-    tools: Read   # the code arrives as a PATH LIST, not inlined — a legacy tree does not fit a payload
     include_standards: false                       # the technical/arch sticky set is for design, never the spec
+    tools: Read   # the code arrives as a PATH LIST, not inlined — a legacy tree does not fit a payload
     output_target: { type: file, path: "{{spec_file}}" }
     task: |
       Reverse-engineer the MASTER specification (the target spec.md in context)
@@ -436,8 +436,8 @@ workflow:
       - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain
   - id: reverse_design
     action: agent_author
-    tools: Read   # grounded in the CODE, which arrives as {{source_files}} paths
     include_standards: true                        # the technical/architecture sticky set (reference only — the CODE wins)
+    tools: Read   # grounded in the CODE, which arrives as {{source_files}} paths
     output_target: { type: file, path: "{{design_doc}}" }
     task: |
       Reverse-engineer the MASTER high-level design (the target design.md in
@@ -501,8 +501,8 @@ workflow:
   - id: reverse_ui_design
     condition: "{{ui_lane}} == true"
     action: agent_author
-    tools: Read   # same, for the lane's surface ({{ui_source_files}})
     include_standards: true                        # the lane's sticky technical set (reference only — the CODE wins)
+    tools: Read   # same, for the lane's surface ({{ui_source_files}})
     output_target: { type: file, path: "{{ui_design_doc}}" }
     task: |
       Reverse-engineer the FRONTEND LANE's high-level design (the target design.ui.md
@@ -548,8 +548,8 @@ workflow:
       - { path: "{{concept_path}}" }              # both file lists to map
   - id: source_map
     action: agent_author
-    tools: Read   # one row per legacy artefact; the artefacts are paths in the concept
     include_standards: false
+    tools: Read   # one row per legacy artefact; the artefacts are paths in the concept
     output_target: { type: file, path: "{{feature_dir}}/source-map.md" }
     task: |
       Author the source-map sidecar (the target in context) from the template,
@@ -580,7 +580,6 @@ workflow:
   # → written to an Adopt Review report and closed OUT OF BAND (Brownfield B1·R).
   - id: fidelity
     action: agent_query
-    tools: Read   # the check is spec/design vs CODE; with no code it degrades to spec vs design and certifies fabrication as ok
     context:
       - "{{spec_file}}"
       - "{{design_doc}}"
@@ -588,6 +587,7 @@ workflow:
       - "{{feature_dir}}/source-map.md"
       - "{{concept_path}}"
     include_standards: false
+    tools: Read   # the check is spec/design vs CODE; with no code it degrades to spec vs design and certifies fabrication as ok
     schema: { ok: true, report_needed: false, blocking_gaps: [ { severity: "high", artefact: "<source file / spec id / design element>", kind: "unmapped-code | fabricated-spec | fabricated-design", detail: "<why>" } ], review_items: [ { kind: "inferred | as-built-quirk | missing-invariant | confidence", where: "<spec/design/source-map location>", note: "<what to confirm out of band>" } ] }
     mock: { ok: true, report_needed: false, blocking_gaps: [], review_items: [] }
     task: |
@@ -637,8 +637,7 @@ workflow:
         spec.md (a resolved [NEEDS CLARIFICATION] / Assumption) or log a deviation.
         Review items: {{review_items}}
       - "## How to proceed": resolve blocking gaps first; then the slice is a normal
-        feature — run /appweaver plan (which renames this design.md to backend-plan.md and
-        conforms it) and then /appweaver analyze-design (the spec↔plan gate), then
+        feature — run /appweaver analyze-plan (spec↔design gate) if desired, then
         drive every change through the CR delta loop. If a change edits untested legacy
         behaviour with blast radius, characterize just that surface first (optional
         on-touch fence) — it is not a required phase.
@@ -937,4 +936,4 @@ outputs:
   composed_file: "{{composed_file}}"
   technical_reconcile_ok: "{{technical_ok}}"
   domain_reconcile_ok: "{{domain_ok}}"
-  next: "Adopted {{feature_name}} (spec.md + design.md + source-map.md, v1.0) and COMPLETED its OKF concept (deepened + linked the deep artifacts; {{xref_edge_count}} cross-slice edge(s) recorded). UI HALF: ui_lane={{ui_lane}} — where it is true this slice also has design.ui.md, reversed from the {{ui_count}} UI file(s) the feature map attributes to it; where it is false the repo declared no frontend lane, or this aggregate owns no part of its surface, and a service-only adoption is the correct outcome rather than a gap. The SHARED UI surface (app shell, layout, design system) belongs to no slice and stays in {{bundle_dir}}/architecture/frontend.md. NOTE — governance reconcile is currently HELD (reconcile_governance=false): this run did NOT modify the constitution halves or the guardrails/projects/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in specs/{{feature_name}}/adopt-review-report.md out of band. The slice is now a NORMAL feature: refine via /appweaver analyze-design, then drive every change through the CR delta loop (/appweaver specify → design → analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta). If a change edits untested legacy behaviour with blast radius, characterize just that surface first (optional on-touch fence). To restore governance reconcile, set reconcile_governance to \"true\" in the workflow vars."
+  next: "Adopted {{feature_name}} (spec.md + design.md + source-map.md, v1.0) and COMPLETED its OKF concept (deepened + linked the deep artifacts; {{xref_edge_count}} cross-slice edge(s) recorded). UI HALF: ui_lane={{ui_lane}} — where it is true this slice also has design.ui.md, reversed from the {{ui_count}} UI file(s) the feature map attributes to it; where it is false the repo declared no frontend lane, or this aggregate owns no part of its surface, and a service-only adoption is the correct outcome rather than a gap. The SHARED UI surface (app shell, layout, design system) belongs to no slice and stays in {{bundle_dir}}/architecture/frontend.md. NOTE — governance reconcile is currently HELD (reconcile_governance=false): this run did NOT modify the constitution halves or the guardrails/projects/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in specs/{{feature_name}}/adopt-review-report.md out of band. The slice is now a NORMAL feature: refine via /appweaver analyze-plan, then drive every change through the CR delta loop (/appweaver specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta). If a change edits untested legacy behaviour with blast radius, characterize just that surface first (optional on-touch fence). To restore governance reconcile, set reconcile_governance to \"true\" in the workflow vars."