aw-spec-cli 0.1.15 → 0.1.17

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

@@ -6,7 +6,7 @@
 # and emit an aggregate-organized OKF v0.1 knowledge bundle + a migration
 # backlog. Each candidate aggregate is a future specs/<Feature>/ vertical slice —
 # this bundle is the BASE the forward brownfield steps read to reverse-engineer
-# spec.md + design.md per slice.
+# spec.md + backend-plan.md per slice.
 #
 #   INVENTORY  → adopt → (fidelity) → characterize → [ forward pipeline ]   ← you are here
 #
@@ -17,14 +17,14 @@
 #   2. an ENRICHMENT agent that turns that substrate into the OKF bundle,
 #      organized BY AGGREGATE ROOT, then a conformance gate (validate_okf.py).
 #
-# It does NOT author spec.md / design.md (that is /appweaver adopt per slice)
+# It does NOT author spec.md / backend-plan.md (that is /appweaver adopt per slice)
 # and does NOT touch source code — all writes stay inside the bundle dir.
 #
 # Launch:  /appweaver inventory [strategy] [focus/scope hints]
 # =============================================================================
 
 name: aw-spec-inventory
-description: Scan a brownfield codebase and produce an aggregate-organized OKF v0.1 knowledge bundle plus a migration backlog — the base for reverse-engineering spec.md + design.md per aggregate/vertical slice. Deterministic scan + enrichment agent + conformance gate; never modifies source.
+description: Scan a brownfield codebase and produce an aggregate-organized OKF v0.1 knowledge bundle plus a migration backlog — the base for reverse-engineering spec.md + backend-plan.md per aggregate/vertical slice. Deterministic scan + enrichment agent + conformance gate; never modifies source.
 version: 1.1.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
@@ -235,4 +235,4 @@ outputs:
   aggregate_count: "{{aggregate_count}}"
   concepts: "{{concepts}}"
   warnings: "{{okf_warnings}}"
-  next: "Review {{bundle_dir}} (start with architecture/overview.md and migration-backlog.md). Then adopt a slice: /appweaver adopt <Aggregate> reverse-engineers its spec.md + design.md from the bundle, and the forward pipeline carries it from there."
+  next: "Review {{bundle_dir}} (start with architecture/overview.md and migration-backlog.md). Then adopt a slice: /appweaver adopt <Aggregate> reverse-engineers its spec.md + backend-plan.md from the bundle, and the forward pipeline carries it from there."

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

@@ -22,7 +22,7 @@
 #      each with the slice's own evidence (BR-/CN-/DC-/IC- ids) when that feature is
 #      developed — the "created here, updated when taking each slice" contract.
 #
-#   ONBOARD  →  adopt <Feature> (JIT)  →  specify → design → analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta   ← you are here
+#   ONBOARD  →  adopt <Feature> (JIT)  →  specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta   ← you are here
 #
 # Establishing the PROJECT-scoped constitution here (whole-repo vantage) — not from a
 # single adopted slice — is deliberate: it keeps governance project-scoped from day
@@ -76,9 +76,10 @@
 #       service pair is reverse-engineered from the service code. The lane is governed by a
 #       different constitution half and implemented by different commands, so it gets its own
 #       design document rather than a section inside the service design; the only thing that
-#       crosses between them is the design contract. Their consumers (⌛ ui-design,
-#       ui-implement) are not built yet — the templates are written now because the
-#       whole-repo evidence for them exists exactly once, at onboard.
+#       crosses between them is the design contract. Their consumers are the FRONTEND LANES
+#       of `plan` and `implement` — one command each, covering both lanes — and the templates
+#       are written here because the whole-repo evidence for them exists exactly once, at
+#       onboard.
 # RUN /appweaver select-stack FIRST. It is the first command of the brownfield
 # sequence and this workflow REFUSES to run without it, because it needs to be told three
 # things before it can start: which lanes this project has, where each lane's source is,
@@ -844,9 +845,9 @@ workflow:
       - { path: "{{bundle_dir}}/architecture/frontend.md", optional: true }            # SECONDARY (shallow): the OKF as-built frontend note — corroborate, don't rely on alone
   - id: author_ui
     action: agent_author
-    tools: Read   # EVIDENCE = THE UI CODE ITSELF; the inventory inlines the file LISTS, not the files
     condition: "{{ui_lane}} == true"
     include_standards: false
+    tools: Read   # EVIDENCE = THE UI CODE ITSELF; the inventory inlines the file LISTS, not the files
     output_target: { type: file, path: "{{constitution_ui_file}}" }
     task: |
       Scaffold the USER EXPERIENCE constitution — the FRONTEND LANE's half (the target
@@ -1191,10 +1192,10 @@ workflow:
       nothing):
         - `## /aw-spec-specify`         — EXACTLY ONE bullet: `service/domain-modelling.md`, the modelling methodology. NEVER an architecture / persistence / codegen / security file here — specify is the domain phase and any technology rule under this heading breaks its domain purity. Omit the heading only if you did not write domain-modelling.md.
         - `## /aw-spec-plan`          — the as-built architecture / cross-cutting rules the design author mediates the spec against.
-        - `## /aw-spec-implement`        — the code-generation / convention set the generator builds against (from design.md).
-        - `## /aw-spec-implement-delta`  — the same code-generation set, scoped to a change's delta-design.
+        - `## /aw-spec-implement`        — the code-generation / convention set the SERVICE lane's generator builds against (from backend-plan.md).
+        - `## /aw-spec-implement-delta`  — the same set for the service lane on the DELTA path. `implement` is one command that keys this heading when it is generating a change's delta plan and the one above when it is generating the master, so a project that wants the same rules on both paths repeats them here.
         - `## /aw-spec-build`            — the layering + convention rules the compile-fixer respects.
-        - `## /aw-spec-analyze-slice`    — the conformance rules the spec↔code gate validates against.
+        - `## /aw-spec-analyze-slice`    — the conformance rules the design↔code gate validates against.
         - `## /aw-spec-adopt`            — the technical reference set the reversed design mediates against (a subset of design's).
         - `## /aw-spec-constitution`     — the standards a later `/appweaver constitution` re-ratifies the TECHNICAL half from. You authored that half from code evidence before these files existed; this heading is what makes a re-run author from THIS project's rules rather than from an empty set. Ratifiable standards only, no worked `examples/` sample, no domain file.
         - `## /aw-spec-run`              — the runtime / execution conventions the app-run step honors (add ONLY if the code evidences a runtime/hosting concern file; NOT data-migration — migration is the deferred later phase).
@@ -1316,33 +1317,22 @@ workflow:
 
       WIRE THE MAP — EDIT guardrails/projects/{{domain_slug}}/tech-rule-bindings.md IN PLACE.
       It already exists and carries the technical headings you wrote; PRESERVE all of them
-      byte-for-byte. Add THREE headings, in this order, after the last technical heading and
-      BEFORE the closing quick-reference table, then their three rows in that table (same
-      format as the existing rows). Every bullet is a workspace-relative path
-      `- guardrails/projects/{{domain_slug}}/frontend/<file>` naming a file you JUST
-      GENERATED — never a greenfield rule, never a service-lane file, never an example.
-      Precede each heading with a short HTML comment saying what that phase loads and why.
-        1. `## /aw-spec-ui-constitution` — the RATIFIABLE lane standards,
-           `frontend/ui-constitution.md` FIRST. Say in its comment that the heading is also
+      byte-for-byte. Make exactly two additions:
+        1. A `## /aw-spec-ui-constitution` section, placed after the last technical heading
+           and BEFORE the closing quick-reference table. Bullet ONLY the frontend files you
+           just generated, `frontend/ui-constitution.md` first, each as a workspace-relative
+           path `- guardrails/projects/{{domain_slug}}/frontend/<file>`. Ratifiable lane
+           standards only — no domain file, no technical file, no example. Precede them with
+           a short HTML comment saying what this half ratifies and that the heading is also
            the authoritative signal that the project has a frontend lane.
-        2. `## /aw-spec-plan-ui` — the DESIGN set /appweaver plan-ui works from when it
-           authors or conforms frontend-plan.md: the generated files covering composition,
-           routing/navigation, client state, interaction states, forms, accessibility,
-           internationalization and performance — whichever of those you actually wrote.
-        3. `## /aw-spec-implement-ui` — the CODE-GENERATION set /appweaver implement-ui
-           builds against: conventions, the client/service pairing, styling/design system,
-           forms, accessibility, internationalization, performance and UI testing — again,
-           whichever you actually wrote.
-      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. Map such a file under BOTH
-      headings. A rule read by only one phase loses the pairing, and the half that goes unread
-      is the half that goes unbuilt.
-      MAP ONLY WHAT YOU GENERATED. A heading with no matching generated file is omitted
-      entirely rather than bulleted with a path that does not exist — an absent heading
-      soft-continues, a broken bullet is reported as missing on every later run.
-      Do NOT add `## /aw-spec-characterize` or `## /aw-spec-parity`: characterize is
-      opt-on-touch and parity belongs to the deferred migration phase.
+        2. Its row in the quick-reference table, in the same format as the existing rows.
+      Do NOT add `## /aw-spec-plan-ui` or `## /aw-spec-implement-ui` — the frontend lane's
+      headings in `plan` and `implement`. ⌛ Both phases DO exist now, but those two headings
+      are a different TIER from the one you just wrote: `## /aw-spec-ui-constitution` maps the
+      lane's RATIFIABLE standards, and those two map its per-phase authoring and
+      code-generation sets. The files above have not been separated into those tiers, and
+      mapping one file under a heading of the wrong tier is what makes a generator obey a
+      standard nobody ratified. Splitting them is the UI lane's own follow-up.
 
       Write ONLY inside guardrails/projects/{{domain_slug}}/ (frontend/ + the map edit); modify
       no source. Report the files written, the concerns you found present with the code paths
@@ -1384,55 +1374,6 @@ workflow:
       project as backend-only. Add the heading after the last technical one, bulleting
       frontend/ui-constitution.md first, then the rest of the frontend/ set.
 
-  # The lane's two PHASE headings, probed the same way and for the same reason. Ratifying
-  # the lane is not the same as governing it: with `## /aw-spec-ui-constitution` alone the
-  # generated frontend/ rules reach /appweaver constitution and NOTHING else, so plan-ui
-  # designs the experience from constitution.ui.md alone and implement-ui generates against
-  # nothing — while the rules sit on disk unreferenced. An absent heading soft-continues, so
-  # without these probes that gap is invisible on every run. Announce, don't stop: the files
-  # are written and each heading is one edit away.
-  - id: probe_ui_plan_wiring
-    action: execute_script
-    condition: "{{ui_lane}} == true"
-    on_error: continue
-    script: { ref: actions }
-    subcommand: resolve-tech
-    args: ["--command", "aw-spec-plan-ui"]
-    outputs:
-      - { name: ui_plan_rules, from: "$.candidates" }
-  - id: warn_ui_plan_wiring
-    action: verify_context
-    condition: "{{ui_lane}} == true"
-    require_non_empty: ui_plan_rules
-    on_empty: continue
-    on_empty_message: >
-      guardrails/projects/{{domain_slug}}/tech-rule-bindings.md maps nothing under
-      `## /aw-spec-plan-ui`, so /appweaver plan-ui will author frontend-plan.md with NO
-      code-derived experience rules — only constitution.ui.md — while the files this run
-      generated at guardrails/projects/{{domain_slug}}/frontend/ go unread. Add the heading
-      after `## /aw-spec-ui-constitution`, bulleting the generated composition, routing,
-      client-state, interaction-state, forms, accessibility, i18n and performance rules.
-  - id: probe_ui_impl_wiring
-    action: execute_script
-    condition: "{{ui_lane}} == true"
-    on_error: continue
-    script: { ref: actions }
-    subcommand: resolve-tech
-    args: ["--command", "aw-spec-implement-ui"]
-    outputs:
-      - { name: ui_impl_rules, from: "$.candidates" }
-  - id: warn_ui_impl_wiring
-    action: verify_context
-    condition: "{{ui_lane}} == true"
-    require_non_empty: ui_impl_rules
-    on_empty: continue
-    on_empty_message: >
-      guardrails/projects/{{domain_slug}}/tech-rule-bindings.md maps nothing under
-      `## /aw-spec-implement-ui`, so /appweaver implement-ui will generate UI code against no
-      code-derived conventions. Add the heading bulleting the generated conventions, service
-      pairing, styling, forms, accessibility, i18n, performance and UI-testing rules — the
-      ones that also serve the design phase belong under BOTH headings.
-
   # ═══════════ LANE DECLARATION — read back, never written ═══════════════════════
   # onboard does not declare lanes. It used to: before select-stack was the first
   # command of this sequence, a repo could arrive here with no declaration at all, so
@@ -1677,11 +1618,11 @@ workflow:
   # derives from the lane's source is what goes IN those sections — the real composition
   # axes, the state and styling conventions, the screen vocabulary.
   #
-  # THE CONSUMERS ARE ⌛ NOT BUILT (B-14 / B-15: ui-design, ui-implement, the three-master
-  # merge in finalize-delta). The templates are written now anyway, and deliberately: the
-  # evidence for them is the whole-repo vantage that exists exactly once, at onboard, and
-  # resolve_template finds them by name the day those commands land. Nothing reads them
-  # before then, and nothing breaks for their absence in a repo that never onboarded.
+  # THE CONSUMERS ARE BUILT: the frontend lane of `plan` scaffolds from this override when
+  # onboard installed one (plan-scaffold reports override_active), and the frontend lane of
+  # `implement` generates from the plan it produced. The templates are written HERE because
+  # the evidence for them is the whole-repo vantage that exists exactly once, at onboard, and
+  # nothing breaks for their absence in a repo that never onboarded.
   - id: ctx_ui_design_template
     action: build_context
     condition: "{{ui_lane}} == true"
@@ -1724,8 +1665,8 @@ workflow:
       names NO framework, router, state library, component library, design system or styling
       approach. That omission is deliberate and you MUST preserve it: the generated template
       stays technology-agnostic even though you derived it from a real stack, because the
-      framework binds later at ⌛ `ui-implement` from constitution.ui.md plus that command's
-      rule set. Describe a component by its RESPONSIBILITY, its INPUTS as field shapes, the
+      framework binds later in the FRONTEND LANE of `implement`, from constitution.ui.md plus
+      that lane's rule set. Describe a component by its RESPONSIBILITY, its INPUTS as field shapes, the
       EVENTS it raises and the STATES it can be in — never by a framework's own vocabulary.
 
       Identify the RECURRING composition convention across the lane's screens (how screens
@@ -1884,4 +1825,4 @@ outputs:
   ui_delta_design_template_files: "{{ui_delta_design_template_files}}"
   technical_validation_ok: "{{technical_ok}}"
   domain_validation_ok: "{{domain_ok}}"
-  next: "Onboarded {{project_name}}: a high-level feature map at {{bundle_dir}} + a PROVISIONAL project governance scaffold, domain {{active_domain}} ACTIVATED, and — reverse-engineered from THIS code alone — the rule tiers wired per-workflow: the DOMAIN set (guardrails/projects/{{domain_slug}}/domain/*.domain.md + domain-rule-bindings.md) always, and each LANE's set where that lane is declared. ONE HALF AND ONE RULE SET PER LANE: service_lane / ui_lane report which lanes .appweaver/stacks.json declared, and the declaration is what decided. A declared service lane gets constitution.technical.md, guardrails/projects/{{domain_slug}}/service/*.md + tech-rule-bindings.md, and the service design/delta-design template overrides; a declared UI lane gets constitution.ui.md, guardrails/projects/{{domain_slug}}/frontend/*.md mapped under ## /aw-spec-ui-constitution, and its own template pair. A lane declared (none) in select-stack gets none of it, which is the correct outcome and not an omission. LANE DECLARATION: read, never written — select-stack is its sole writer, and this run scanned the source paths it named (scanned_service_root / scanned_ui_root). The scan was SCOPED by them, so the backend substrate excludes the UI subtree and the frontend substrate is that subtree: scanned_backend_files / scanned_ui_files report each. ui_source_evidence_found false means the UI lane's declared path held nothing a scan recognises as UI, so its governance is thin — move the source path with /appweaver select-stack and re-run. The build/test/run commands on each lane are that PROFILE's defaults and may not match a legacy layout — review them, and re-run /appweaver select-stack to correct any lane. Because the domain is activated, resolve-domain + resolve-tech now route the WHOLE forward pipeline AND adopt to these code-derived rules — never another project's rules as a fallback. Code-derived design + delta-design templates are installed as the project template overrides (.appweaver/templates/overrides/) so a NEW feature is developed against the as-built architecture with NO adopt — every section derived from a NEUTRAL skeleton plus this repo's own structure, with no greenfield template in context. Where the lane exists, the SAME pair is generated for it (ui-design-template.md + ui-delta-design-template.md) from the UI source; ui-design-template.md is consumed by /appweaver adopt, which reverses a slice's design.ui.md from it wherever that slice owns part of the lane's surface; ui-delta-design-template.md still waits, since ui-design / ui-implement are not built yet. Develop an EXISTING feature just-in-time: /appweaver adopt <Feature> reverse-engineers its spec.md + design.md + source-map.md and completes that feature's OKF concept; its governance reconcile is currently HELD, so the scaffold this run wrote stays as it is. Develop a NEW feature straight through the forward pipeline (/appweaver specify → design → implement). 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 validation_ok is false, its constitution half needs a manual touch (see its Sync Impact Report)."
+  next: "Onboarded {{project_name}}: a high-level feature map at {{bundle_dir}} + a PROVISIONAL project governance scaffold, domain {{active_domain}} ACTIVATED, and — reverse-engineered from THIS code alone — the rule tiers wired per-workflow: the DOMAIN set (guardrails/projects/{{domain_slug}}/domain/*.domain.md + domain-rule-bindings.md) always, and each LANE's set where that lane is declared. ONE HALF AND ONE RULE SET PER LANE: service_lane / ui_lane report which lanes .appweaver/stacks.json declared, and the declaration is what decided. A declared service lane gets constitution.technical.md, guardrails/projects/{{domain_slug}}/service/*.md + tech-rule-bindings.md, and the service design/delta-design template overrides; a declared UI lane gets constitution.ui.md, guardrails/projects/{{domain_slug}}/frontend/*.md mapped under ## /aw-spec-ui-constitution, and its own template pair. A lane declared (none) in select-stack gets none of it, which is the correct outcome and not an omission. LANE DECLARATION: read, never written — select-stack is its sole writer, and this run scanned the source paths it named (scanned_service_root / scanned_ui_root). The scan was SCOPED by them, so the backend substrate excludes the UI subtree and the frontend substrate is that subtree: scanned_backend_files / scanned_ui_files report each. ui_source_evidence_found false means the UI lane's declared path held nothing a scan recognises as UI, so its governance is thin — move the source path with /appweaver select-stack and re-run. The build/test/run commands on each lane are that PROFILE's defaults and may not match a legacy layout — review them, and re-run /appweaver select-stack to correct any lane. Because the domain is activated, resolve-domain + resolve-tech now route the WHOLE forward pipeline AND adopt to these code-derived rules — never another project's rules as a fallback. Code-derived design + delta-design templates are installed as the project template overrides (.appweaver/templates/overrides/) so a NEW feature is developed against the as-built architecture with NO adopt — every section derived from a NEUTRAL skeleton plus this repo's own structure, with no greenfield template in context. Where the lane exists, the SAME pair is generated for it (ui-design-template.md + ui-delta-design-template.md) from the UI source; ui-design-template.md is consumed by /appweaver adopt, which reverses a slice's design.ui.md from it wherever that slice owns part of the lane's surface; ui-delta-design-template.md is consumed by the frontend lane of /appweaver plan on its DELTA path, and the plan it produces is generated by the frontend lane of /appweaver implement. Develop an EXISTING feature just-in-time: /appweaver adopt <Feature> reverse-engineers its spec.md + design.md + source-map.md and completes that feature's OKF concept; its governance reconcile is currently HELD, so the scaffold this run wrote stays as it is. Develop a NEW feature straight through the forward pipeline (/appweaver specify → plan → implement). 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 validation_ok is false, its constitution half needs a manual touch (see its Sync Impact Report)."

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

@@ -27,7 +27,7 @@
 # never forces a match by breaking the candidate.
 #
 # Launch:  /appweaver parity [strategy] [focus/guidance]
-# Prereq:  /appweaver adopt (spec.md + design.md + source-map.md) + a running
+# Prereq:  /appweaver adopt (spec.md + backend-plan.md + source-map.md) + a running
 #          candidate, and the legacy system reachable.
 # =============================================================================
 
@@ -107,7 +107,7 @@ workflow:
     action: verify_context
     require_true: design_exists
     on_false: stop
-    on_false_message: "No design.md for the current feature. Run /appweaver adopt <Aggregate> (or /appweaver design) first."
+    on_false_message: "No backend-plan.md for the current feature. Run /appweaver adopt <Aggregate> (or /appweaver plan) first."
 
   - id: set_source_map
     action: set