aw-spec-cli 0.1.27 → 0.1.28

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

@@ -129,11 +129,12 @@ migration is needed (yes/no); any contract change other systems couple to.]
 <!-- What this change adds to or alters in the service's PUBLISHED surface — the
      only part of this document the frontend lane may bind against. `None` when
      the surface is unchanged. Omit the section entirely where the code has no
-     frontend lane. -->
+     frontend lane. The operation id is the endpoint's name in the published API
+     document; an endpoint that already has one keeps it. -->
 
-| Contract | Change | Shape | Serves |
-|---|---|---|---|
-| `[contract]` | [added / changed] | [request → response field shapes] | IC-[nnn] |
+| Operation id | Contract | Change | Shape | Serves |
+|---|---|---|---|---|
+| `[OperationId]` | `[contract]` | [added / changed] | [request → response field shapes] | IC-[nnn] |
 
 ## Other open deltas
 

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

@@ -169,7 +169,9 @@
      the titles are the code's answer — the slots below are illustrative
      positions, not a required set. In each: the components that live there,
      their behaviour in signature form, and the contracts they expose or
-     require. -->
+     require. A component that PUBLISHES an endpoint names it with its route, verb
+     and operation id — the endpoint's name in the published API document, which
+     the frontend plan cites and implement looks the endpoint up by. -->
 
 ### 2.1 [PROJECT_STRUCTURAL_AXIS_NAME]
 

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

@@ -1,8 +1,8 @@
 <!--
   rev-templates/domain-rule-bindings.skeleton.md — SHAPE-ONLY reference for the project's
   domain-rule-bindings.md (resolve-domain reads it by that exact name — the symmetric
-  twin of tech-rule-bindings.md, which resolve-tech reads). It shows the five per-command headings, the RULE PARTITION (plan +
-  implement get NO domain file), the bullet shape, and the quick-reference
+  twin of tech-rule-bindings.md, which resolve-tech reads). It shows the seven headings (plan and
+  implement keyed per lane), the RULE PARTITION (neither lane of plan or implement gets a domain file), the bullet shape, and the quick-reference
   table. It lists NO real rule files — every bullet is a placeholder for a file
   the author actually generated from THIS project's evidence.
 
@@ -35,11 +35,17 @@ domain-model.md. This is the rule partition; preserve it exactly.
      into the spec's CN-/DC-/IC- (plan/implement never see these files). -->
 - guardrails/[project]/domain/[each generated domain rule file].md
 
-## /aw-spec-plan
-_None — plan loads no domain file. Domain reaches plan through the spec and the context's domain-model.md._
+## /aw-spec-plan-backend
+_None — the service lane of plan loads no domain file. Domain reaches it through the spec and the context's domain-model.md._
 
-## /aw-spec-implement
-_None — implement loads no domain file. Domain reaches implement through the lane plans and the context's domain-model.md._
+## /aw-spec-plan-frontend
+_None — the frontend lane of plan loads no domain file. Domain reaches it through the spec and the context's domain-model.md._
+
+## /aw-spec-implement-backend
+_None — the service lane of implement loads no domain file. Domain reaches it through backend-plan.md and the context's domain-model.md._
+
+## /aw-spec-implement-frontend
+_None — the frontend lane of implement loads no domain file. Domain reaches it through frontend-plan.md and the context's domain-model.md._
 
 ## /aw-spec-gate
 <!-- Conformance checklist for the gates (analyze-plan · analyze-slice): the domain-derived
@@ -54,6 +60,8 @@ _None — implement loads no domain file. Domain reaches implement through the l
 |---|---|---|
 | /aw-spec-constitution | [n] | domain principles |
 | /aw-spec-specify | [n] | author into spec (lift → CN-/DC-/IC-) |
-| /aw-spec-plan | 0 | none — the spec and the domain model carry the domain |
-| /aw-spec-implement | 0 | none — the lane plans and the domain model carry the domain |
+| /aw-spec-plan-backend | 0 | none — the spec and the domain model carry the domain |
+| /aw-spec-plan-frontend | 0 | none — the spec and the domain model carry the domain |
+| /aw-spec-implement-backend | 0 | none — backend-plan.md and the domain model carry the domain |
+| /aw-spec-implement-frontend | 0 | none — frontend-plan.md and the domain model carry the domain |
 | /aw-spec-gate | [n] | conformance checklist (validate, don't author) |

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

@@ -27,6 +27,10 @@ refers to it directly, as-is.
 
 - All paths are workspace-relative and live in `guardrails/[project]/service/`.
 - `resolve-tech --command <name>` collects the `- ` bullets under `## /<name>`.
+- `plan`, `implement` and `adopt` are keyed per lane, not per command: the service lane's set
+  sits under `## /aw-spec-<command>-backend`, the frontend lane's under
+  `## /aw-spec-<command>-frontend` (adopt reverses a frontend plan under
+  `## /aw-spec-plan-frontend`, so it has no frontend heading of its own).
 - **`## /aw-spec-specify` is the MODELLING-METHODOLOGY slot** — exactly one file,
   `service/domain-modelling.md`: HOW this code expresses a domain model. Never an architecture /
   persistence / codegen / security file; those would break specify's domain purity. Every other
@@ -43,22 +47,16 @@ refers to it directly, as-is.
      via domain-rule-bindings). No technology rule may appear under this heading. -->
 - guardrails/[project]/service/domain-modelling.md
 
-## /aw-spec-plan
+## /aw-spec-plan-backend
 <!-- 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/[project]/service/[as-built-architecture].md
 - guardrails/[project]/service/[each generated architecture/cross-cutting rule].md
 
-## /aw-spec-implement
+## /aw-spec-implement-backend
 <!-- The framework / code-generation rule set the SERVICE lane's generator builds against
-     (from backend-plan.md). -->
-- guardrails/[project]/service/[each generated codegen/convention rule].md
-
-## /aw-spec-implement-delta
-<!-- 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. -->
+     (from backend-plan.md), on both the master and the delta path. -->
 - guardrails/[project]/service/[each generated codegen/convention rule].md
 
 ## /aw-spec-build
@@ -69,10 +67,10 @@ refers to it directly, as-is.
 <!-- The plan↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
 - guardrails/[project]/service/[testing/convention rule to validate against].md
 
-## /aw-spec-adopt
+## /aw-spec-adopt-backend
 <!-- 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`. -->
+     only. A slice's reversed frontend-plan.md is authored under `## /aw-spec-plan-frontend`. -->
 - guardrails/[project]/service/[architecture/cross-cutting reference rule].md
 
 ## /aw-spec-constitution
@@ -95,14 +93,14 @@ refers to it directly, as-is.
      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
+       ## /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
+       ## /aw-spec-plan-frontend        — 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
+       ## /aw-spec-implement-frontend   — 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
@@ -120,11 +118,10 @@ 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 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-plan-backend | [n] | as-built architecture the service lane's plan author mediates the spec against |
+| /aw-spec-implement-backend | [n] | code-generation set the service lane builds against (from backend-plan.md), both paths |
 | /aw-spec-build | [n] | layering + convention rules the compile-fixer respects |
 | /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-adopt-backend | [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/ui-delta-design-template.skeleton.md

@@ -80,11 +80,14 @@ it serves.]
 
 <!-- New screens, components, state, interactions or contract bindings.
      "Section" names a section of THIS project's master frontend plan — the same
-     section titles the generated frontend plan template carries. -->
+     section titles the generated frontend plan template carries. A binding row's
+     element LEADS with the operation id the service names the endpoint by — implement
+     checks it against the exported API document. -->
 
 | Section (§ in frontend-plan.md) | Element | Kind | Serves |
 |---|---|---|---|
 | [§ of the master's own structure] | `[element]` | [screen / component / state / binding] | US-[n] · FR-[nnn] |
+| Contract Binding (§5) | `[OperationId]` · `[VERB] [/route]` | binding | IC-[nnn] |
 
 ## MODIFIED — existing UI elements
 

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

@@ -222,11 +222,13 @@ does none.]
      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. -->
+     record that as a §8 assumption. The OPERATION ID is the endpoint's name in the
+     service's published API document (as backend-plan.md records it) — implement
+     finds the endpoint by it; `—` where none is named yet. -->
 
-| Screen / component | Operation (from the contract) | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
-|---|---|---|---|---|---|
-| `[Screen]` | `[operation]` | [field: type, …] | [field: type, …] | [§4 state] | FR-00X · IC-00X |
+| Screen / component | Operation id | Operation (from the contract) | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
+|---|---|---|---|---|---|---|
+| `[Screen]` | `[OperationId]` | `[operation]` | [field: type, …] | [field: type, …] | [§4 state] | FR-00X · IC-00X |
 
 **Contract deltas needed**: [anything the experience requires that the contract
 does not offer — raised back to the service lane, never worked around in the

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

@@ -111,7 +111,7 @@ scripts:
 # Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The TECHNICAL/
 # architecture set for the reversed DESIGN step (mirrors aw-spec-design) is no longer
 # hardcoded here — it is now CONFIGURATION, loaded per-command from
-# guardrails/<project>/tech-rule-bindings.md under "## /aw-spec-adopt" by the
+# guardrails/<project>/tech-rule-bindings.md under "## /aw-spec-adopt-backend" by the
 # tech-select module (see the tech_select step below). The reversed SPEC step runs
 # include_standards:false and takes its domain frame from constitution.domain.md via
 # build_context — so design never sees a domain rule file (rule partition preserved); the
@@ -366,7 +366,7 @@ workflow:
     on_false_message: "No active governance for adopt to work against — run /appweaver onboard first. onboard establishes the PROJECT constitution + guardrails/<project>/ rule set (provisional-from-scan) and activates it. Reversing '{{feature_name}}' without that scaffold would author the spec and design against no code-derived rules at all, and leave them with no governance home."
 
   # TECHNICAL rule files → sticky standards (configuration, not hardcoded). tech-select
-  # reads guardrails/<project>/tech-rule-bindings.md under "## /aw-spec-adopt" and
+  # reads guardrails/<project>/tech-rule-bindings.md under "## /aw-spec-adopt-backend" and
   # loads that reference set into the sticky standards for reverse_plan
   # (include_standards:true) — the reversed SPEC and MODEL steps turn it off
   # (include_standards:false), keeping them free of architecture (rule partition). No domain
@@ -377,7 +377,7 @@ workflow:
   - id: tech_select
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-adopt }
+    with: { command: aw-spec-adopt-backend }
 
   # 2. Scaffold the living docs. The SPEC reuses the forward spec-template (it is
   #    tech-agnostic WHAT/WHY — no architectural bias). The BACKEND PLAN scaffolds from the
@@ -821,13 +821,13 @@ workflow:
   # THE FRONTEND'S RULES REPLACE THE BACKEND'S before the lane's plan is authored — the
   # swap the forward `plan` makes at the same boundary. Sticky standards only accumulate,
   # so without it the UI plan was authored under the service rule set and none of the
-  # lane's own. `## /aw-spec-plan-ui` is the set the forward plan authors this same
+  # lane's own. `## /aw-spec-plan-frontend` is the set the forward plan authors this same
   # document under, so a reversed frontend plan and a planned one answer to one rule set.
   - id: tech_select_ui
     condition: "{{ui_lane}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-plan-ui, replace: "true" }
+    with: { command: aw-spec-plan-frontend, replace: "true" }
 
   - id: ctx_reverse_ui_plan
     condition: "{{ui_lane}} == true"
@@ -1058,6 +1058,7 @@ workflow:
     action: agent_generate
     tools: "Read,Write,Edit"
     permission_mode: acceptEdits
+    include_standards: false                       # the lane rule sets are for the plans; the concept is the aggregate's, in neither lane
     task: |
       COMPLETE the OKF concept of the aggregate '{{aggregate_primary}}' at {{concept_path}} —
       the aggregate this run adopted the feature '{{feature_name}}' over. onboard wrote it
@@ -1351,4 +1352,4 @@ outputs:
   composed_file: "{{composed_file}}"
   technical_reconcile_ok: "{{technical_ok}}"
   domain_reconcile_ok: "{{domain_ok}}"
-  next: "Adopted {{feature_name}} (spec.md + backend-plan.md + source-map.md, v1.0) and wrote {{aggregate_sections}} — the model section(s) for the aggregate(s) it acts on, resolved from the {{aggregate_source}} — in the bounded context `{{context}}`'s shared {{domain_model}}. The spec cites BR-nnn by id, the model carries their text, so this slice is checkable by the same gates as a greenfield one and analyze-plan's check 4 now has a model to check against. A section another feature over the same aggregate wrote first was EXTENDED, never duplicated; every other section is untouched. COMPLETED the OKF concept of {{aggregate_primary}} (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 frontend-plan.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. In the second case, where a frontend lane IS declared, the feature records lanes=[backend] in its active_version.json (feature_lanes shows it), so plan and the analyze gates treat the frontend lane as absent for THIS feature; run `aw-spec-actions feature-lanes --clear` if it later gains a UI. 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/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in {{feature_dir}}/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."
+  next: "Adopted {{feature_name}} (spec.md + backend-plan.md + source-map.md, v1.0) and wrote {{aggregate_sections}} — the model section(s) for the aggregate(s) it acts on, resolved from the {{aggregate_source}} — in the bounded context `{{context}}`'s shared {{domain_model}}. The spec cites BR-nnn by id, the model carries their text, so this slice is checkable by the same gates as a greenfield one and analyze-plan's check 4 now has a model to check against. A section another feature over the same aggregate wrote first was EXTENDED, never duplicated; every other section is untouched. COMPLETED the OKF concept of {{aggregate_primary}} (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 frontend-plan.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. In the second case, where a frontend lane IS declared, the feature records lanes=[backend] in its active_version.json (feature_lanes shows it), so plan and the analyze gates treat the frontend lane as absent for THIS feature; run `aw-spec-actions feature-lanes --clear` if it later gains a UI. 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/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in {{feature_dir}}/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."

package/assets/.appweaver/orchestrator/workflows/aw-spec-analyze-plan-delta.orch.yaml

@@ -458,7 +458,13 @@ workflow:
           UNRESOLVED by definition: report it so it is closed here rather than at
           integration;
           (d) a contract the service delta REMOVES or narrows that the master frontend plan
-          still uses is a HIGH gap — the experience delta has to carry the matching change.
+          still uses is a HIGH gap — the experience delta has to carry the matching change;
+          (e) OPERATION IDS MATCH. Every binding row the experience delta adds or changes
+          leads with an operation id, and that id is the one the service delta's table or
+          the master backend plan gives the endpoint, spelled exactly. A binding with no id,
+          or with an id neither names, is a HIGH `contract` gap on lane `frontend`; a
+          service-delta row with no operation id is one on lane `backend`. Implement finds
+          each endpoint by this id in the service's exported API document.
 
           CHECK 4 — THE EFFECTIVE MODEL. It is domain-model.md PLUS this change's model
           delta PLUS the model deltas of every LOWER-WAVE change in context (its

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

@@ -470,7 +470,13 @@ workflow:
           discovered at integration;
           (d) the frontend plan cites the service's published surface and does NOT restate,
           re-derive or contradict it, and states no server-side behaviour or persistence
-          assumption.
+          assumption;
+          (e) OPERATION IDS MATCH. Every §5 row's Operation id is the one the backend plan's
+          §3 gives that endpoint, spelled exactly, and every §3 endpoint has one, unique
+          across the plan. A §5 row with no id (`—` without a DA-n) or with an id §3 does not
+          name is a HIGH `contract` gap on lane `frontend`; a §3 endpoint with no id, or two
+          endpoints sharing one, is one on lane `backend`. Implement finds each endpoint by
+          this id in the service's exported API document.
 
           CHECK 4 — the plans → domain-model.md (when the model is in context; skip if it
           is not):

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

@@ -81,5 +81,5 @@ workflow:
 outputs:
   feature_dir: "{{feature_dir}}"
   deployed: "{{configured}}"
-  note: "Set .appweaver/deploy.json {\"command\": \"...\"} to enable an actual deploy; add smoke/rollback via before_deploy/after_deploy hooks."
+  note: 'Set .appweaver/deploy.json {"command": "..."} to enable an actual deploy; add smoke/rollback via before_deploy/after_deploy hooks.'
   next: "done"