aw-spec-cli 0.1.23 → 0.1.25

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

@@ -39,13 +39,14 @@ refers to it directly, as-is.
 ## /aw-spec-specify
 <!-- MODELLING METHODOLOGY ONLY — exactly one file. HOW this codebase expresses a domain model
      (what marks an aggregate root, entity vs value object, where invariants live, the context
-     boundary), NOT what the model is (that is the domain set's domain-driven-design.domain.md,
-     wired via domain-rule-bindings). No technology rule may appear under this heading. -->
+     boundary), NOT what the model is (that is the domain set's domain-model.domain.md, wired
+     via domain-rule-bindings). No technology rule may appear under this heading. -->
 - guardrails/projects/[project]/service/domain-modelling.md
 
 ## /aw-spec-plan
-<!-- The as-built architecture / cross-cutting technical rules the design author mediates the spec
-     against. NO domain file here — domain reaches design only as spec ids. -->
+<!-- The as-built architecture / cross-cutting technical rules the SERVICE lane's plan author
+     mediates the spec against. NO domain file here — domain reaches plan only as spec ids and
+     the context's domain-model.md. -->
 - guardrails/projects/[project]/service/[as-built-architecture].md
 - guardrails/projects/[project]/service/[each generated architecture/cross-cutting rule].md
 
@@ -65,12 +66,13 @@ refers to it directly, as-is.
 - guardrails/projects/[project]/service/[as-built-architecture].md
 
 ## /aw-spec-analyze-slice
-<!-- The design↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
+<!-- The plan↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
 - guardrails/projects/[project]/service/[testing/convention rule to validate against].md
 
 ## /aw-spec-adopt
-<!-- Brownfield reverse-engineering: the technical REFERENCE set the reversed design mediates the
-     reversed spec ↔ existing code against — the CODE wins, these are reference only. -->
+<!-- Brownfield reverse-engineering: the technical REFERENCE set the reversed BACKEND plan
+     mediates the reversed spec ↔ existing code against — the CODE wins, these are reference
+     only. A slice's reversed frontend-plan.md is authored under `## /aw-spec-plan-ui`. -->
 - guardrails/projects/[project]/service/[architecture/cross-cutting reference rule].md
 
 ## /aw-spec-constitution
@@ -89,13 +91,22 @@ 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
 
-<!-- ## /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.
+<!-- THE FRONTEND LANE'S THREE HEADINGS. They are NOT written by the step that authors this
+     map; onboard's frontend rule-set step APPENDS them here, after the technical headings and
+     before the quick-reference table, and only where a UI lane is declared. A backend-only
+     repo never gets them.
+       ## /aw-spec-ui-constitution — the ratifiable lane standards (frontend/ui-constitution.md
+          first). 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.
+       ## /aw-spec-plan-ui         — the lane rules the FRONTEND lane of `plan` authors
+          frontend-plan.md against: composition, navigation, client state, interaction states,
+          forms, accessibility, the published-surface binding. `adopt` reverses a slice's
+          frontend-plan.md under the same set.
+       ## /aw-spec-implement-ui    — the lane rules the FRONTEND lane of `implement` generates
+          code against, on both the master and the delta path: component conventions, state and
+          data fetching, styling, forms, testing.
+     A file carrying both a planning half and a generating half is listed under both; the lane
+     base file frontend/ui-constitution.md sits under ## /aw-spec-ui-constitution only.
 
      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
@@ -109,11 +120,11 @@ refers to it directly, as-is.
 | Command | Technical rule files | Role |
 |---|---|---|
 | /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-plan | [n] | as-built architecture the service lane's plan author mediates the spec against |
 | /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 design↔code gate validates against |
-| /aw-spec-adopt | [n] | technical reference set for the reversed design (brownfield) |
+| /aw-spec-analyze-slice | [n] | conformance rules the plan↔code gate validates against |
+| /aw-spec-adopt | [n] | technical reference set for the reversed backend plan (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) |

package/assets/.appweaver/orchestrator/rev-templates/technical-constitution.skeleton.md

@@ -3,10 +3,10 @@
   rev-templates/technical-constitution.skeleton.md — SHAPE-ONLY reference.
 
   This file is the FORMAT + VOCABULARY reference for the reverse-engineered
-  TECHNICAL half (constitution.technical.md). It is loaded as a `standards:`
-  entry for the technical-half author (include_standards:true). It carries the
-  AppWeaver principle-heading style, the Sync-Impact-Report shape, the
-  evidence-line pattern, and the section skeleton — and NOTHING ELSE.
+  TECHNICAL half (constitution.technical.md). onboard hands it to the
+  technical-half author in that step's context. It carries the AppWeaver
+  principle-heading style, the Sync-Impact-Report shape, the evidence-line
+  pattern, and the section skeleton — and NOTHING ELSE.
 
   IT DELIBERATELY CONTAINS NO PRINCIPLE SET. There is no fixed I–XV list to
   inherit. Every [BRACKET] token below is a slot the author fills from evidence
@@ -14,18 +14,19 @@
 
   DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
   here to leak):
-    • EVIDENCE-FIRST — author a principle ONLY for a technology trait the
-      adopted design.md files + the OKF overview/platform note actually
-      evidence. If the code does not show it, it is not a principle.
+    • EVIDENCE-FIRST — author a principle ONLY for a technology trait the code
+      evidences: the OKF overview and platform note, and any adopted plans and
+      source-maps that exist. If the code does not show it, it is not a principle.
     • CITE inline — every principle ends with an `(evidence: …)` line naming a
-      design section, a concrete type / port / persistence context / config, or
-      an OKF stack line. A principle with no groundable evidence does not belong.
+      concrete type / port / persistence context / config path, a plan section,
+      or an OKF stack line. A principle with no groundable evidence does not
+      belong.
     • AS-BUILT LEVEL — state a partial / stubbed / optional trait at the level
       the code actually reaches; never the aspirational ideal.
     • OMIT pure aspiration — a trait the code shows zero of is not softened into
-      a principle; it is left out.
-    • ROUTE gaps — an unmet ideal / stub / inactive-optional concern goes into
-      the "As-Built Debt → migration backlog" list below, never asserted.
+      a principle; it is left out, and named with the reason in the Sync Impact
+      Report's "deliberately omitted" list. There is no debt or backlog sink:
+      this is the development flow, and migration is a separate later phase.
     • VARIABLE LENGTH — number sequentially from I with no gaps and no padding
       to a fixed count. The final numeral is the domain half's continuation
       point.
@@ -40,11 +41,8 @@ Sync Impact Report
   I   [PRINCIPLE_TITLE]
   II  [PRINCIPLE_TITLE]
   …   (only traits the code evidences — no fixed count)
-- Template ideals DELIBERATELY OMITTED (lack of as-built evidence):
-  - [IDEAL] — [why the code does not evidence it]
-  - …
-- As-Built Debt → migration backlog (see knowledge/migration-backlog.md; do not restate the table):
-  - [gap / stub / inactive-optional concern] — [where it is tracked]
+- Traits DELIBERATELY OMITTED (lack of as-built evidence):
+  - [TRAIT] — [why the code does not evidence it]
   - …
 - Dependent artifacts:
   - constitution.domain.md — ⚠ authored next; continues at [N+1]
@@ -54,9 +52,9 @@ Sync Impact Report
 -->
 # [PROJECT_NAME] Constitution — Technical Base
 
-> Reverse-engineered, **as-built**, domain-agnostic technical half. Authority for DESIGN and
-> IMPLEMENT. Domain principles live in `constitution.domain.md` (continues at **[N+1]**).
-> This file asserts only technology traits evidenced by the adopted designs + OKF overview/platform.
+> Reverse-engineered, **as-built**, domain-agnostic technical half. Authority for the service
+> lane of PLAN and IMPLEMENT. Domain principles live in `constitution.domain.md` (continues at
+> **[N+1]**). This file asserts only technology traits the code evidences.
 
 ## Core Principles
 
@@ -64,9 +62,9 @@ Sync Impact Report
      Replace the bracketed text; keep the `### <numeral>. <title>` + rule + `(evidence: …)` shape. -->
 
 ### I. [PRINCIPLE TITLE] [(NON-NEGOTIABLE)?]
-[One declarative, testable rule the adopted designs actually evidence. State it at the level the
-code reaches — partial/stubbed/optional traits are stated as partial, not as the ideal.]
-(evidence: [design §X.Y named type / port / persistence context / config; or OKF overview Tech-stack line])
+[One declarative, testable rule the code actually evidences. State it at the level the code
+reaches — partial/stubbed/optional traits are stated as partial, not as the ideal.]
+(evidence: [named type / port / persistence context / config path; a plan section; or an OKF overview Tech-stack line])
 
 ### II. [PRINCIPLE TITLE] [(NON-NEGOTIABLE)?]
 […]
@@ -78,7 +76,7 @@ code reaches — partial/stubbed/optional traits are stated as partial, not as t
 
 ## Mandatory Folder Structure (base)
 
-- [Solution projects / module layout AS INVENTORIED — from the OKF overview + designs, not an ideal.]
+- [Solution projects / module layout AS INVENTORIED — from the code and the OKF overview, not an ideal.]
 - [Cross-cutting host files that stay at their template levels.]
 - Domain-specific folder additions (if any) are declared only in the domain constitution half.
 

package/assets/.appweaver/orchestrator/rev-templates/technical-rule-file.skeleton.md

@@ -18,7 +18,7 @@ concern: "[concern-slug]"
   root, entity vs value object, where invariants live, the context boundary). It is
   the only file wired under `## /aw-spec-specify`, and it carries NO business
   vocabulary: HOW this code models, never WHAT it models (that is the domain set's
-  domain-driven-design.domain.md). Same shape as below — cite code coordinates.
+  domain-model.domain.md). Same shape as below — cite code coordinates.
 
   Every rule below MUST cite a CODE COORDINATE (a real file/folder path or named
   type) and, where it maps, the technical-constitution principle numeral it

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

@@ -7,7 +7,8 @@
   .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
   lane. It carries the classification triple, the impact and regression
-  sections, the two ledgers and the close contract, and NOTHING ELSE.
+  sections, the two ledgers and what happens to the record at merge, 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 frontend plan template generated
@@ -15,11 +16,12 @@
   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, 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.
+  produces a service delta AND this one; `finalize-delta` merges the spec and the
+  domain model once for both — never either plan, which `plan main` re-derives
+  from them — 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.
 
   DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
   here to leak):
@@ -49,8 +51,12 @@
 
 <!--
   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
+  specs/[Context]/[Feature]/frontend-plan.md — never a new document. It does not
+  touch the master, and neither does finalize-delta: the master is DERIVED from
+  spec.md and domain-model.md, so `plan main` re-derives it rather than patching
+  it from this file, and a UX- item of this change reaches it through the spec's
+  Experience Standards. close-delta archives this document as the record of how
+  the change was built. 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. `implement`'s frontend lane
@@ -73,8 +79,8 @@ it serves.]
 ## 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" names a section of THIS project's master frontend plan — the same
+     section titles the generated frontend plan template carries. -->
 
 | Section (§ in frontend-plan.md) | Element | Kind | Serves |
 |---|---|---|---|
@@ -105,8 +111,9 @@ it serves.]
 
 ## Contract impact
 
-[What this change needs from the service lane, taken from the change's contract
-projection: bindings added, changed or no longer used. Anything the experience
+[What this change needs from the service lane, bound against its published surface —
+the delta-spec's IC- ids and the service delta's "Contract deltas for the frontend
+lane" table: bindings added, changed or no longer used. Anything the experience
 requires that the contract does not offer is raised back to the service lane —
 never worked around in the client. Or `None`.]
 
@@ -130,15 +137,18 @@ shared state container or a navigation edge changed.]
 
 ## New assumptions / deviations (from this change)
 
-<!-- Anything this change defers — folds into the master's DA-n / WA-n ledgers
-     on apply. -->
+<!-- Anything this change defers. It stays this document's record — the master's
+     DA-n / WA-n ledgers are re-derived with the rest of the master plan, not
+     patched from here. -->
 
 - **DA-[n]**: [assumption to clarify later] — or `None`
 - **WA-[n]**: [deviation to clear later] — or `None`
 
-## On close
+## On merge
 
-`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/`.
+`finalize-delta` merges the change's SPEC half into `spec.md` and its MODEL half into the
+context's `domain-model.md`, in one transaction, and leaves the change OPEN. It does NOT
+merge this document: the master plan is derived from those two, so `plan main` re-derives
+it rather than patching it. `close-delta` archives this file with the change and bumps the
+ONE version both lanes share. None of it is this document's job — it records the change,
+it does not apply it.

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

@@ -19,8 +19,8 @@
   LANE'S OWN CODE.
 
   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
+  project's frontend plan TEMPLATE — [PLACEHOLDER] tokens and authoring comments
+  intact — which the frontend lane of `plan` then fills once per feature into
   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
@@ -39,9 +39,12 @@
   no error states gets a section saying so, not a section quietly omitted.
 
   §5 IS THE LANE BOUNDARY. Contract binding is the only place the service lane
-  enters: the UI design reads the WHOLE spec but only a PROJECTION of the
-  service design (⌛ specs/<Feature>/design-contract.md). The requirement is
-  shared and must not fork; the implementation is not shared and must not leak.
+  enters: the frontend plan reads the WHOLE spec but only the service's
+  PUBLISHED SURFACE — the spec's IC- ids and the API contracts backend-plan.md
+  states. (⌛ `plan` will emit that surface as a design-contract.md projection;
+  the rule does not change when it does, only what §5 reads.) The requirement
+  is shared and must not fork; the implementation is not shared and must not
+  leak.
 
   DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
   here to leak):
@@ -57,24 +60,24 @@
       ids, exactly as it reaches the service design.
   ═══════════════════════════════════════════════════════════════════════════
 -->
-# UI Design: [AGGREGATE]
+# Frontend Plan: [FEATURE]
 
-**Feature**: `[Feature]`
+**Feature**: `[Feature]`  <!-- the capability scope the developer chose; the aggregate(s) it acts on are the spec's "Acts on aggregate(s)" line -->
 
 **Plan home**: `specs/[Context]/[Feature]/frontend-plan.md`
 
-**Source spec**: `specs/[Aggregate]/spec.md`
+**Source spec**: `specs/[Context]/[Feature]/spec.md`
 
-**Contract**: `specs/[Aggregate]/design-contract.md`
+**Lane**: `[lane id]` — the frontend lane declared in `.appweaver/stacks.json`
 
-**Version**: v1.0
+**Version**: v1.0   <!-- moves in lockstep with spec.md and backend-plan.md; one change closes on ONE bump -->
 
 **Status**: Draft
 
 <!--
   WHAT THIS DOCUMENT IS
   =====================
-  The single, living high-level UI design for ONE feature's experience — the
+  The single, living high-level plan for ONE feature's experience — the
   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.
@@ -88,8 +91,8 @@
     reads a second authority, the context's domain-model.md, because it realises
     the aggregate's structure. This lane consumes the published surface at §5, not
     the domain, so the model is not in its context.)
-  - THE CONTRACT IS THE ONLY SERVICE INPUT (§5). Read the design contract, never
-    the service design.
+  - THE PUBLISHED SURFACE IS THE ONLY SERVICE INPUT (§5) — the spec's IC- ids and
+    the API contracts backend-plan.md states, never the service's internals.
 
   STRUCTURE FOLLOWS THIS LANE'S CODE
   - [GENERATED_LANE_STRUCTURE_NOTE] — form: one or two sentences naming the
@@ -215,10 +218,11 @@ does none.]
 ## 5. Contract Binding
 
 <!-- THE LANE BOUNDARY. One row per service operation this feature's UI depends
-     on, taken from ⌛ specs/[Aggregate]/design-contract.md — the projection the
-     service design emits. Read the contract, never the service design. Where no
-     contract document exists yet, bind against the spec's own IC-/FR- surface
-     and record that as a §8 assumption. -->
+     on, bound against the service's PUBLISHED SURFACE — the spec's IC- ids and
+     the API contracts backend-plan.md states — never its internals: no table,
+     handler or persistence assumption crosses this line. Where the surface does
+     not name an operation yet, bind against the spec's own IC-/FR- surface and
+     record that as a §8 assumption. -->
 
 | Screen / component | Operation (from the contract) | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
 |---|---|---|---|---|---|
@@ -287,9 +291,12 @@ client. Or `None`.]
 
 ## Change History
 
-<!-- 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. -->
+<!-- A row is appended when this plan is RE-DERIVED to carry a change: the plan is
+     derived from spec.md (its UX- Experience Standards) and the context's
+     domain-model.md, and finalize-delta merges a change into those two, never
+     into this one (`plan main` re-derives it). close-delta bumps the ONE version
+     both lanes share and stamps it into the header, so a header ahead of the
+     newest row means the plan has not been re-derived since. Newest last. -->
 
 | Version | Date | Change | User stories | CR |
 |---------|------|--------|--------------|-----|