aw-spec-cli 0.1.22 → 0.1.24

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

@@ -119,6 +119,7 @@ vars:
   lanes_declared: "false"
   be_declared: "false"
   fe_declared: "false"
+  fe_excluded: "false"        # this feature records no surface in the declared frontend lane (feature-lanes)
   be_lane_id: ""
   fe_lane_id: ""
   active_change: ""
@@ -235,6 +236,23 @@ workflow:
       - { name: spec_file,   from: "$.spec_file" }
       - { name: spec_exists, from: "$.spec_exists" }
 
+  # THIS FEATURE'S LANES. lane_resolve above read the REPO's declaration; one feature may
+  # own no part of a lane's surface — adopt records `lanes: [backend]` in
+  # active_version.json for a service-only slice in a repo that also has a UI. Re-read with
+  # --feature-dir so a lane the feature records no surface in is absent here: never
+  # scaffolded, bootstrapped or delta-planned for it. With no feature resolved the argument
+  # is dropped and the repo's answer stands.
+  - id: feature_lanes
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: be_declared, from: "$.backend_declared" }
+      - { name: fe_declared, from: "$.frontend_declared" }
+      - { name: fe_excluded, from: "$.frontend_feature_excluded" }
+
   # The BOUNDED CONTEXT's domain model — where the aggregate root, its entities and its
   # invariants (BR-n) live. The spec cites them by id; this phase records where each is
   # ENFORCED, so the model has to be in context or the instruction to "follow it exactly"
@@ -1135,6 +1153,7 @@ outputs:
   bounded_context: "{{context}}"
   backend_plan: "{{backend_plan}}"      # empty when no backend lane is declared
   frontend_plan: "{{frontend_plan}}"    # empty when no frontend lane is declared
+  frontend_excluded: "{{fe_excluded}}" # true = a frontend lane is declared and this feature records no surface in it (feature-lanes)
   domain_model: "{{domain_model}}"
   plan_mode: "{{plan_mode}}"
   plan_target: "{{plan_target}}"

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

@@ -80,4 +80,6 @@ outputs:
   domain_rule_bindings: "{{map_path}}"
   domain_rule_bindings_exists: "{{map_exists}}"
   note: "Active project '{{domain}}' persisted to .appweaver/domain.json. It selects TWO rule maps under guardrails/projects/{{domain}}/ — domain-rule-bindings.md (DOMAIN rules; read by constitution + specify only, because the spec is the pivot) and tech-rule-bindings.md (TECHNICAL rules; read by 10 workflows incl. design, implement, build and run). The rule FILES themselves live in shared corpora — guardrails/technology/<stack>/ and guardrails/domain/<industry>/ — and the maps are what bind this project to them, so two projects can share a corpus and differ only in their maps and their own three requirements files. domain_rule_bindings_exists reports the domain half only. A map that is absent, or a command with no heading in one, loads nothing for that class and SOFT-CONTINUES — an absent heading is a valid state, never a failure."
-  next: "/appweaver select-feature   (then specify — the per-feature path). Re-run /appweaver select-domain any time to switch projects; it rebinds both maps at once."
+  # constitution comes BEFORE select-feature: it reads the domain rule map this
+  # workflow just bound, and specify declares its domain half as REQUIRED context.
+  next: "/appweaver constitution → select-feature → specify. /appweaver constitution authors the constitution halves from the domain rule map this run just bound — specify declares constitution.domain.md as REQUIRED context, and plan and implement read constitution.technical.md (plus constitution.ui.md on a frontend lane), so it runs before the first feature rather than after. /appweaver select-feature then picks the feature to build; every stage from specify onward reads that active feature and stops without it. Re-run /appweaver select-domain any time to switch projects; it rebinds both maps at once, and /appweaver constitution picks the new bindings up on its next run."

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

@@ -28,11 +28,11 @@
 #
 #   list-features (specs/ ∪ features the OKF concepts serve) → user_select (existing | "+ create new") → [ask name] → set-feature
 #
-# Persists .appweaver/feature.json {"feature_directory":"specs/<Feature>"} so every
-# later command operates on it: the forward loop (specify/plan/analyze-plan/implement/
-# build/analyze-slice/run/deploy) and the CR loop (analyze-plan-delta/implement/
-# finalize-delta/close-delta — the standalone `cr` is retired; specify and design author
-# the delta docs themselves).
+# Persists .appweaver/feature.json {"feature_directory":"specs/[<Context>/]<Feature>"} so
+# every later command operates on it: the forward loop (specify/plan/analyze-plan/
+# implement/build/analyze-slice/run/deploy), brownfield's adopt, and the CR loop
+# (specify/plan/analyze-plan-delta/implement/build/analyze-slice-delta/finalize-delta/
+# analyze-slice/close-delta — specify and plan author the delta docs themselves).
 #
 # Launch:
 #   /appweaver select-feature                 # interactive: list + add-new

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

@@ -2,7 +2,7 @@
 # aw-spec-select-stack (orchestrator) — declare the project's LANES
 #
 # THE FIRST COMMAND OF EVERY SEQUENCE. Greenfield runs it before constitution;
-# brownfield runs it before onboard. What it writes decides which constitution
+# brownfield runs it before inventory. What it writes decides which constitution
 # halves are authored, which rule sets are generated, which subtree each phase may
 # write into, and — in brownfield — which subtree onboard reverse-engineers. It
 # answers one question per lane, twice:
@@ -317,4 +317,4 @@ outputs:
   ui_detected: "{{ui_detected}}"
   prototype: "{{prototype}}"
   note: "Lanes persisted to .appweaver/stacks.json. Each lane carries a STACK and a SOURCE PATH, and both are load-bearing. The SOURCE PATH is ownership: implement's service lane writes its code only under the service lane's and its frontend lane only under the UI lane's, build/test/run act on it, and onboard reverse-engineers out of it. Each lane also owns a TEST PATH, taken from its stack profile — tests/ beside a .NET src/, the source path itself for a stack that keeps its tests inside — and implement writes the lane's tests there. Overlapping paths of either kind are refused here rather than discovered later as two generators writing one file. The build/test/run commands are project-supplied strings the engine shells out to, which is how it stays stdlib-only and stack-ignorant. api_detected / ui_detected report what this repo's own files pointed at, whether or not it was chosen, as "<stack> at <path>" — or "nothing detected" on a greenfield repo with nothing to detect. A source path that does not exist yet is NORMAL here and reported rather than refused: greenfield declares src/ before implement creates it. The on-disk check runs in the phases that read the subtree — implement, build, run and onboard all call lane-verify and STOP with the fix named. Declining a lane with (none) is a real declaration and removes any lane of that kind a previous run left behind; it is also what stops that lane's constitution half and rule files being authored. `prototype` is not a lane — it has a root and a run command so an operator can open it, and nothing else. Re-run this workflow any time to re-stack a lane, move a source path, or drop a lane with (none); it is the only workflow that may write this file."
-  next: "GREENFIELD: /appweaver foundation — once per lane, to scaffold a compiling project into each source path declared here (skip it for a lane whose code already exists, or scaffold with the stack's own tooling) — then /appweaver select-domain → constitution → select-feature → specify. BROWNFIELD: /appweaver onboard — it reverse-engineers out of the source paths declared here and generates the project (no select-domain; onboard derives and activates it from the code). Run this workflow FIRST in either sequence: foundation unpacks into the source paths declared here, constitution reads the declaration to decide which halves to author, and onboard reads it to decide what to scan."
+  next: "GREENFIELD: /appweaver foundation — once per lane, to scaffold a compiling project into each source path declared here (skip it for a lane whose code already exists, or scaffold with the stack's own tooling) — then /appweaver select-domain → constitution → select-feature → specify. BROWNFIELD: /appweaver inventory — it scans the source paths declared here and proposes the bounded contexts and features as specs/proposed-inventory.md; edit that map, run /appweaver inventory apply, then /appweaver onboard <Context> once per bounded context, which reverse-engineers the governance out of the same source paths and activates it (no select-domain; onboard derives it from the code). Run this workflow FIRST in either sequence: foundation unpacks into the source paths declared here, constitution reads the declaration to decide which halves to author, and inventory and onboard read it to decide what to scan."

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

@@ -771,4 +771,7 @@ outputs:
   checklist_file: "{{checklist_file}}"
   checklist_quality: "{{checklist_passed}}/{{checklist_total}} items passing"
   note: "Behaviour and structure were authored together: the spec says what the system must do, {{domain_model}} says what the domain IS. The aggregate root, its entities and its invariants (BR-n) live in the model and are cited from the spec by id — never restated there, because several specs act on one aggregate and a per-spec copy drifts. On the DELTA path neither master was touched: this run wrote changes/{{cr_id}}/delta-spec.md and {{delta_model}}, and that model delta sits BESIDE the master where every other open delta can see it while being authored. WAVE {{wave}} is its parallel-development level — deltas sharing a wave are independent, a higher wave is implemented only after the lower ones land. The wave is DERIVED from the model delta's `## Depends on`: one above the highest delta named there, stamped into both halves as soon as it was authored ({{wave_message}}). To move it, correct that section and re-run `.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id {{cr_id}} --stamp`; finalize-delta refuses a change whose wave contradicts it. {{open_count}} change(s) are open on this feature."
-  next: "/appweaver plan — BOOTSTRAP authors backend-plan.md from the spec + the domain model; a DELTA (this run opened change {{cr_id}}, wave {{wave}}) authors the delta plans for it. A change then flows: analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta (finalize-delta merges the delta into spec.md + domain-model.md — not the lane plans, which are derived from those two — but leaves the change open; analyze-slice verifies the slice against the merged master; close-delta archives the change and bumps the version). ⚠️ With more than one change open, plan, analyze-plan-delta and implement ASK which one they are for (pass the id as the argument to skip the prompt) and activate the answer; finalize-delta and close-delta still act on whichever change is active — so finish or close the others deliberately."
+  # Both paths spell out their WHOLE remaining chain. The bootstrap path named only
+  # `plan` and stopped there, which left a first greenfield run with no successor at
+  # the exact point the delta path was fully documented.
+  next: "/appweaver plan — BOOTSTRAP authors backend-plan.md from the spec + the domain model (plus frontend-plan.md where a UI lane is declared); a DELTA (this run opened change {{cr_id}}, wave {{wave}}) authors the delta plans for it. BOOTSTRAP then flows: plan → analyze-plan → implement → build → analyze-slice → run → deploy (analyze-plan is the spec↔plan gate and it repairs and stops only while NO change is open). A change instead flows: analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta (finalize-delta merges the delta into spec.md + domain-model.md — not the lane plans, which are derived from those two — but leaves the change open; analyze-slice verifies the slice against the merged master; close-delta archives the change and bumps the version). ⚠️ With more than one change open, plan, analyze-plan-delta and implement ASK which one they are for (pass the id as the argument to skip the prompt) and activate the answer; finalize-delta and close-delta still act on whichever change is active — so finish or close the others deliberately."

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

@@ -52,11 +52,29 @@ workflow:
     outputs:
       - { name: feature,        from: "$.feature" }
       - { name: feature_dir,    from: "$.feature_dir" }
-      - { name: feature_slug,   from: "$.feature_slug" }
+      - { name: feature_slug,   from: "$.feature_slug" }   # kebab-case route segment
       - { name: spec_file,      from: "$.spec_file" }
       - { name: spec_exists,    from: "$.spec_exists" }
-      - { name: domain,         from: "$.domain" }
-      - { name: prototype_root, from: "$.prototype_root" }
+
+  # domain and prototype_root have their OWN resolvers — feature-paths answers for the
+  # feature's documents and nothing else, so binding them here left both empty and the
+  # emptiness reached the prompts as a blank path segment rather than an error.
+  - id: resolve_domain
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: resolve-domain
+    args: ["--command", "/aw-spec-ui-model"]
+    outputs:
+      - { name: domain, from: "$.domain" }
+
+  - id: resolve_prototype_lane
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: prototype_root, from: "$.prototype.root" }
 
   - id: require_feature
     action: verify_context
@@ -92,10 +110,14 @@ workflow:
     vars:
       feature_name: "{{feature}}"
       feature_dir: "{{feature_dir}}"
+      domain: "{{domain}}"
       user_preferences: "{{USER_INPUT}}"
     context:
       - "{{feature_dir}}/ui/workflow-model.md"
       - "{{spec_file}}"
+      - { path: "guardrails/projects/{{domain}}/frontend/design.md", optional: true }
+      - { path: "guardrails/projects/{{domain}}/frontend/DESIGN.md", optional: true }
+      - { path: "guardrails/projects/{{domain}}/frontend/ui-requirements.md", optional: true }
       - { path: ".appweaver/templates/ui-model-template.md", optional: true }
       - { path: ".appweaver/memory/constitution.ui.md", optional: true }
 
@@ -117,9 +139,15 @@ workflow:
          - Define supported interaction states per surface (`Loading`, `Empty`, `Populated`, `Filtered / Searched`, `Validation Error`, `Submitting`, `Success`, `Error`).
          - Specify interactive controls, form fields, action buttons, and table/card layouts.
          - Map explicit navigation & transition triggers (`On Action -> Opens Surface X`).
-      3. Remember the core rule: **Workflow != Single Screen**. A workflow can span multiple surfaces or reuse surfaces with state changes.
-      4. Format output according to `.appweaver/templates/ui-model-template.md`.
-      5. Write the authored markdown content to `{{feature_dir}}/ui/ui-model.md`.
+      3. **Natural Product Naming & Simplicity**:
+         - Use clean, concise, consumer-grade/modern B2B titles for all surfaces and actions (e.g. "Projects List", "New Project", "Project Details", "Edit Project", "Change Status").
+         - Avoid bloated, academic, or bureaucratic phrasing (do NOT write "Project Directory & Portfolio Catalog Surface", "Execute Lifecycle Status Transition Dialog", or "Update Project Metadata & Schedule Modal").
+      4. **Progressive Disclosure Architecture**:
+         - Structure primary views (cards, tables) to display only essential high-signal data points.
+         - Relegate deep governance details, audit logs, and technical metadata to secondary tabs, detail views, or slide-over drawers.
+      5. Remember the core rule: **Workflow != Single Screen**. A workflow can span multiple surfaces or reuse surfaces with state changes.
+      6. Format output according to `.appweaver/templates/ui-model-template.md`.
+      7. Write the authored markdown content to `{{feature_dir}}/ui/ui-model.md`.
 
       User Guidance:
       {{user_preferences}}

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

@@ -141,6 +141,9 @@ workflow:
       - { path: "{{domain_model}}", optional: true }
       - { path: "{{feature_dir}}/ui/workflow-model.md", optional: true }
       - { path: "{{feature_dir}}/ui/ui-model.md", optional: true }
+      - { path: "guardrails/projects/{{domain}}/frontend/design.md", optional: true }
+      - { path: "guardrails/projects/{{domain}}/frontend/DESIGN.md", optional: true }
+      - { path: "guardrails/projects/{{domain}}/frontend/ui-requirements.md", optional: true }
       - { path: ".appweaver/memory/constitution.domain.md", optional: true }
       - { path: ".appweaver/memory/constitution.ui.md", optional: true }
       - { path: "{{feature_dir}}/changes/{{active_change}}/delta-spec.md", optional: true }
@@ -197,6 +200,10 @@ workflow:
       - The persona/role switcher must be styled and framed as a normal in-app affordance
         (e.g. an account/role menu a real user of this kind of app would plausibly have),
         not as an obvious dev/testing control bolted onto the UI.
+      - **Simplicity of language and visual calmness**:
+        - Use simple, everyday product language (e.g. "Projects", "Status", "Dates", "Budget").
+        - Avoid architectural meta-language or bureaucratic phrasing (e.g. do NOT say "Initiative Lifecycle Distribution", "Workspace Governance & Audit Stream", "Optimistic Concurrency Version").
+        - Keep dashboards clean and focused with 3–4 high-signal metrics and concise cards, not dense walls of text or redundant explanatory paragraphs.
 
       **Styling must actually render — this is not optional:**
       - Install and fully configure **Tailwind CSS** (latest stable version, matching whatever
@@ -247,6 +254,7 @@ workflow:
       The feature specification is taken directly from the bounded context directory and feature path defined in `.appweaver/feature.json`:
       `{{spec_file}}` (Bounded Context: `{{context_name}}`, Feature: `{{feature_name}}`).
       Read this specification strictly from `{{spec_file}}`, along with the bounded context's canonical domain model (`{{domain_model}}`),
+      the project Design System if present (`guardrails/projects/{{domain}}/frontend/design.md` or `DESIGN.md`, or `{{feature_dir}}/ui/design.md`),
       and when available, the Workflow Model (`{{feature_dir}}/ui/workflow-model.md`) and UI Model (`{{feature_dir}}/ui/ui-model.md`), plus `{{prototype_root}}/lib/screens-registry.ts` / `screens.json`.
       If `workflow-model.md` and `ui-model.md` are not provided, derive all UI surfaces, workflows, and interaction states directly from `{{spec_file}}`.
 
@@ -266,9 +274,24 @@ workflow:
            see the actual working application screen, fully styled and populated, matching
            spec.md as if it shipped this way.
          - Never surface "prototype/mock/demo/sample" language, or raw spec/traceability IDs
-           (`REQ-###`, `SPEC-SCREEN-###`, etc.) anywhere in this screen's rendered UI (titles,
+           (`REQ-###`, `SPEC-SCREEN-###`, `BR-###`, `FR-###`, `CN-###`, `DC-###`, `UX-###`) anywhere in this screen's rendered UI (titles,
            headers, empty states, tooltips, button copy). Keep all such labeling out of
            user-visible text entirely.
+         - **Natural product language over spec jargon**:
+           - Translate formal architectural and domain-driven design terms into clean, everyday product vocabulary:
+             - Say "Projects" (or simple domain noun) rather than "Portfolio Initiatives" or "Domain Aggregate".
+             - Say "Status" rather than "Governance State" or "Lifecycle Progression".
+             - Say "Timeline" or "Dates" rather than "Target Timeline Trajectory Bounds".
+             - Say "Budget" rather than "Allocated Capital Valuation".
+             - Say "Change Status" rather than "Execute Lifecycle Status Transition".
+             - Say "New Project" rather than "Create Initiative".
+             - Say "Activity" or "History" rather than "Immutable Governance Audit Stream".
+           - Avoid robotic, academic, or overly bureaucratic copy. Write like modern, top-tier SaaS products (e.g. Linear, Stripe, Notion).
+         - **Progressive disclosure and scannable information density**:
+           - Do NOT dump every requirement, invariant, and metadata attribute onto primary cards or lists.
+           - Keep primary cards and table rows clean and scannable — display only 3–5 essential, high-signal data points (e.g. Name, Status, Dates, Owner, Key Metric).
+           - Place deep operational details (audit histories, concurrency tokens, classification codes, full event trails) behind secondary inspection tabs, modals, or slide-over drawers — never on primary summary cards.
+           - Keep interfaces free of long instructional text blocks, redundant help banners, or cluttering meta-labels.
 
       2. **Integrate this screen into the app like a real feature, not a spec entry**:
          - `{{feature_name}}` and any spec title/ID are internal identifiers for you to read —
@@ -319,6 +342,9 @@ workflow:
            Tailwind/CSS config from the shell is intact. If it's missing or broken, fix it
            as part of this run and note that in your final summary; don't build a styled-looking
            screen on top of a broken/absent styling pipeline.
+         - If a project visual design system is present in context (`guardrails/projects/{{domain}}/frontend/design.md` or `DESIGN.md`),
+           apply its visual design tokens (colors, accent, surface, border, typography, card elevation, and status states)
+           consistently across all cards, badges, buttons, forms, and headers on this screen.
          - Use the shell's existing design tokens and Tailwind utility classes (or whatever
            styling system the shell uses) rather than inline style objects or
            ad-hoc CSS that bypasses the shared system — inline styles that "look fine" in
@@ -356,6 +382,17 @@ workflow:
            original spec title/ID for traceability, add it as a separate non-rendered field
            (e.g. `specRef`) rather than reusing `title` for it.
 
+      10. **Structured UI Specification Output (`ui-spec.md`)**:
+          - Generate or update `{{feature_dir}}/ui/ui-spec.md` alongside the prototype code.
+          - Format as a markdown document with a brief title and capture intro, followed by a SINGLE fenced `json` code block adhering strictly to the JSON schema defined in `skill/references/output-ui-spec.md`:
+            - `screen`: user-facing screen name and route
+            - `captureNotes`: viewport width, CSS px, DPR, and design system token origin (`guardrails/projects/{{domain}}/frontend/DESIGN.md` or `design.md`)
+            - `regions`: ordered list of UI regions (nav-bar, header, step-card, content, dialogs, drawers) with `layout` (`position`, `wrap`, `direction`) and `elements` array
+            - `elements`: each element detailing `id`, `kind` (`text`, `button`, `badge`, `avatar`, `card`, `input`, etc.), verbatim `content`, `style` (`shape`, `colorToken`, `typographyToken`, `spacingPx`), `state` (`default`, `active`, `hover`), and `fields`
+            - `navigation`: ordered nav items, activeItem, activeStyle
+            - `openQuestions`: roll-up of ambiguities, edge cases, and responsive variations
+          - Ensure all `colorToken` and `typographyToken` values reference design tokens from the domain design system.
+
       User Preferences / Guidance:
       {{user_preferences}}
 
@@ -367,6 +404,7 @@ workflow:
         "feature": "{{feature_name}}",
         "slug": "{{feature_slug}}",
         "route": "/{{feature_slug}}",
+        "ui_spec": "{{feature_dir}}/ui/ui-spec.md",
         "prototype_root": "{{prototype_root}}",
         "launch_command": "cd {{prototype_root}} && npm run dev"
       }
@@ -380,6 +418,7 @@ outputs:
   context_dir: "{{context_dir}}"
   feature: "{{feature}}"
   spec_file: "{{spec_file}}"
+  ui_spec_file: "{{feature_dir}}/ui/ui-spec.md"
   route: "/{{feature_slug}}"
   prototype_root: "{{prototype_root}}"
   launch_hint: "First time: cd {{prototype_root}} && npm install && npm run dev — after that, just rerun ui-prototype per feature and refresh the browser."

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

@@ -49,11 +49,29 @@ workflow:
     outputs:
       - { name: feature,        from: "$.feature" }
       - { name: feature_dir,    from: "$.feature_dir" }
-      - { name: feature_slug,   from: "$.feature_slug" }
+      - { name: feature_slug,   from: "$.feature_slug" }   # kebab-case route segment
       - { name: spec_file,      from: "$.spec_file" }
       - { name: spec_exists,    from: "$.spec_exists" }
-      - { name: domain,         from: "$.domain" }
-      - { name: prototype_root, from: "$.prototype_root" }
+
+  # domain and prototype_root have their OWN resolvers — feature-paths answers for the
+  # feature's documents and nothing else, so binding them here left both empty and the
+  # emptiness reached the prompts as a blank path segment rather than an error.
+  - id: resolve_domain
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: resolve-domain
+    args: ["--command", "/aw-spec-workflow-model"]
+    outputs:
+      - { name: domain, from: "$.domain" }
+
+  - id: resolve_prototype_lane
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: prototype_root, from: "$.prototype.root" }
 
   - id: require_feature
     action: verify_context
@@ -105,8 +123,9 @@ workflow:
       1. Read the feature specification (`spec.md` + active `delta-spec.md`) in context.
       2. Identify ALL discrete user workflows required to fulfill the feature's capabilities, functional requirements (FRs), business rules (BRs), and user personas.
       3. For EACH user workflow (WF-1, WF-2, ...), detail:
+         - **Workflow Title**: Name concisely after real, plain-English user actions (e.g. "WF-1: Browse Projects", "WF-2: Create Project", "WF-3: View Project Details", "WF-4: Edit Project", "WF-5: Change Status" — avoid bureaucratic or formal titles like "Execute Lifecycle Status Transition").
          - **Actor / Persona**: Which role executes this flow (e.g. Project Manager, Delivery Head).
-         - **Goal**: Clear statement of user goal.
+         - **Goal**: Clear statement of user goal in natural language.
          - **Preconditions**: Initial system state, permissions, or prerequisite conditions.
          - **Primary Flow**: Step-by-step numbered interaction steps from start to completion.
          - **Decision Points & Alternative Paths**: Clear branch logic (e.g. If user cancels, If user requests correction).

package/assets/.appweaver/scripts/bash/aw-rev-constitution.sh

@@ -6,7 +6,7 @@
 # ONCE in ../python/aw-rev-constitution.py; this wrapper exists only so the
 # orchestrator's execute_script (sh:/ps1: dispatch) can invoke it. Args pass through.
 #
-#   aw-rev-constitution.sh list-adopted [--root <dir>] [--specs <dir>] [--bundle <dir>]
+#   aw-rev-constitution.sh project-context [--root <dir>] [--bundle <dir>]
 #   aw-rev-constitution.sh project-setup --name <domain> [--fallback <name>] [--root <dir>]
 set -euo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

package/assets/.appweaver/scripts/bash/aw-spec-actions.sh

@@ -35,9 +35,12 @@
 #                    [--build <c>] [--test <c>] [--run <c>] [--prototype-root <p>] [--prototype-run <c>] [--no-prototype]
 #                                                  -> {declared, lane, lanes[], lane_count, source_path, root_exists, prototype, written}
 #                    (SOLE WRITER of .appweaver/stacks.json; callers = select-stack, onboard)
-#   lane-resolve     [--kind <k>] [--id <lane>]    -> {declared, lanes[], found, lane, root, source_path, build, test, run,
-#                                                      backend_*/frontend_* (declared, root, source_path, root_exists, build, test, run), prototype}
-#                    (absence is a valid state: no stacks.json -> declared:false, exit 0)
+#   lane-resolve     [--kind <k>] [--id <lane>] [--feature-dir <path>]
+#                                                  -> {declared, lanes[], found, lane, root, source_path, build, test, run,
+#                                                      backend_*/frontend_* (declared, root, source_path, root_exists, build, test, run,
+#                                                      feature_excluded), feature_lanes[], prototype}
+#                    (absence is a valid state: no stacks.json -> declared:false, exit 0;
+#                     --feature-dir reports a lane the feature records no surface in as not declared)
 #   lane-verify      [--require backend|frontend]… [--allow-missing-root] [--command <phase>]
 #                                                  -> {ok, declared, issues[], issue_count, message, backend_*/frontend_*}
 #                    (the GATE: is the declaration usable for the phase about to run.
@@ -49,7 +52,9 @@
 #   version-read     [--feature-dir <path>]        -> {feature, version, active_change, exists, bootstrap_pending}
 #   version-init     [--feature-dir <path>] [--bootstrap]  -> {…, created, bootstrap_pending}   (create active_version.json v1.0; --bootstrap marks a FIRST draft in progress)
 #   version-bootstrap-done [--feature-dir <path>]  -> {…, cleared}   (the ONLY clearer of the --bootstrap marker; call it when the first draft is finished)
-#   feature-paths                                  -> {feature, feature_dir, spec_file, backend_plan, frontend_plan, *_exists,
+#   feature-lanes    [--feature-dir <path>] [--set backend|frontend|backend,frontend] [--clear]  -> {…, lanes[]}
+#                    (the declared lanes this feature has a surface in; empty = every declared lane)
+#   feature-paths                                  -> {feature, feature_slug, feature_dir, spec_file, backend_plan, frontend_plan, *_exists,
 #                                                      design_file/ui_design_file (aliases of the two plans), spec_exists, bootstrap_pending, needs_bootstrap}
 #   checklist-read   --file <path>                 -> {exists, total, checked, items[]}
 #   checklist-apply  --file <path> --results <json>-> {exists, before_checked, after_checked, total, newly_passing[], regressions[]}
@@ -798,7 +803,10 @@ cmd_lane_resolve() {
     while [ $# -gt 0 ]; do
         case "$1" in
             --kind|--id) fwd+=("$1" "$2"); shift 2 ;;
-            --help|-h) echo "lane-resolve [--kind backend|frontend] [--id <lane>]"; return 0 ;;
+            # An EMPTY --feature-dir is dropped: a workflow renders the argument whole, and a
+            # feature that is not resolved yet means "the repo's declaration as it stands".
+            --feature-dir) if [ -n "$2" ]; then fwd+=("--feature-dir" "$2"); fi; shift 2 ;;
+            --help|-h) echo "lane-resolve [--kind backend|frontend] [--id <lane>] [--feature-dir <path>]"; return 0 ;;
             *) echo "lane-resolve: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -1470,15 +1478,15 @@ _resolve_feature_dir() {   # $1 = --feature-dir arg (may be empty), $2 = repo_ro
     printf '%s' "$fd"
 }
 
-# Shared reader/mutator: op in {read,init,bootstrap-done,open,activate,close}. Prints one
+# Shared reader/mutator: op in {read,init,bootstrap-done,lanes,open,activate,close}. Prints one
 # JSON object.
 # MANY CHANGES MAY BE OPEN ON ONE FEATURE. open_changes[] is the record; active_change is
 # the most recently opened OR the one a later stage activated, and is kept correct for
 # every stage that still resolves "the" change through it. `force` is accepted and unused
 # on open — the guard it overrode is gone — and is kept so existing callers do not have to
 # change.
-_active_version() {   # $1 = abs feature_dir, $2 = op, $3 = cr_id (open/close), $4 = force (accepted, inert), $5 = bootstrap ("1", init only)
-    AW_FD="$1" AW_OP="$2" AW_CR="${3:-}" AW_FORCE="${4:-}" AW_BOOT="${5:-}" python3 - <<'PY'
+_active_version() {   # $1 = abs feature_dir, $2 = op, $3 = cr_id (open/close), $4 = force (accepted, inert), $5 = bootstrap ("1", init only), $6 = lanes (lanes only)
+    AW_FD="$1" AW_OP="$2" AW_CR="${3:-}" AW_FORCE="${4:-}" AW_BOOT="${5:-}" AW_LANES="${6:-}" python3 - <<'PY'
 import json, os, re, datetime, sys
 fd = os.environ["AW_FD"]; op = os.environ["AW_OP"]; cr = os.environ.get("AW_CR", "")
 force = os.environ.get("AW_FORCE", "")
@@ -1529,6 +1537,31 @@ elif op == "init":
         d["bootstrap_pending"] = True
     save(d)
     out["created"] = (not existed)
+elif op == "lanes":
+    # WHICH DECLARED LANES THIS FEATURE HAS A SURFACE IN. Absent means every lane the repo
+    # declares, which is the ordinary case and needs no record. A feature that genuinely has
+    # no part of one lane's surface — a job-only or shared-kernel slice in a repo that also
+    # has a UI — records the kinds it does have, and `lane-resolve --feature-dir` then reports
+    # the other lane as not declared FOR THIS FEATURE, so no phase plans, gates or builds a
+    # surface the feature does not own. `all` removes the record; an empty value only reads.
+    # Refuses to create the file: init is its one creator, and a record with no version
+    # spine would read as a feature nobody specified.
+    want = os.environ.get("AW_LANES", "").strip()
+    if want and not existed:
+        out["ok"] = False
+        out["error"] = "no active_version.json for this feature yet — it is created by specify or adopt"
+    elif want == "all":
+        d.pop("lanes", None)
+        save(d)
+    elif want:
+        kinds = [k.strip() for k in want.split(",") if k.strip()]
+        bad = [k for k in kinds if k not in ("backend", "frontend")]
+        if bad or not kinds:
+            out["ok"] = False
+            out["error"] = "lanes takes backend, frontend or both (comma-separated), or all; got '%s'" % want
+        else:
+            d["lanes"] = [k for k in ("backend", "frontend") if k in kinds]
+            save(d)
 elif op == "bootstrap-done":
     # THE ONLY THING THAT CLEARS THE MARKER, called by the phase that raised it once the
     # first draft is actually finished. It is a separate op, not a side effect of writing
@@ -1628,6 +1661,7 @@ elif op == "close":
     out["previous"] = prev; out["closed_change"] = closed
     out["open_changes"] = opens; out["open_count"] = len(opens)
 out["bootstrap_pending"] = bool(d.get("bootstrap_pending"))
+out["lanes"] = list(d.get("lanes") or [])   # empty = every declared lane
 out["has_change"] = bool(out.get("active_change", ""))   # clean branch signal for design
 # What a close from THIS state would produce. One bump() authority, read by BOTH
 # finalize-delta (to write the right number into the Change History rows it appends)
@@ -1642,6 +1676,33 @@ PY
 cmd_version_read()  { _version_cmd "read"  "$@"; }
 cmd_version_init()  { _version_cmd "init"  "$@"; }
 cmd_version_bootstrap_done() { _version_cmd "bootstrap-done" "$@"; }
+
+# The lane kinds this feature has a surface in, recorded in its active_version.json. adopt
+# records `backend` for a slice that owns no part of a declared frontend's surface, and
+# `lane-resolve --feature-dir` reads it back. No argument reads; --clear drops the record so
+# the feature follows every declared lane again.
+cmd_feature_lanes() {
+    local fd_arg="" lanes=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --set) lanes="$2"; shift 2 ;;
+            --clear) lanes="all"; shift ;;
+            --help|-h) echo "feature-lanes [--feature-dir <path>] [--set backend|frontend|backend,frontend] [--clear]"; return 0 ;;
+            *) echo "feature-lanes: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "feature-lanes: no feature set and no --feature-dir" >&2; return 1; }
+    local out; out=$(_active_version "$fd" "lanes" "" "" "" "$lanes")
+    printf '%s\n' "$out"
+    # A refused write is a failure the caller has to see: the orchestrator reports a
+    # failed script from stderr, so the reason goes there too.
+    if printf '%s' "$out" | grep -q '"ok": false'; then
+        printf '%s' "$out" | python3 -c 'import json,sys; print("feature-lanes: " + json.load(sys.stdin).get("error", "refused"), file=sys.stderr)'
+        return 1
+    fi
+}
 _version_cmd() {   # $1 = op (read|init), then --feature-dir arg
     local op="$1"; shift
     local fd_arg="" boot=""
@@ -1676,6 +1737,16 @@ cmd_feature_paths() {
     fi
     [[ "$fd" != /* ]] && fd="$repo_root/$fd"
     local feature; feature=$(basename "$fd")   # the aggregate name (feature = specs/<Feature>)
+    # feature_slug is the URL-safe form of that name, and it is what the UI stages use
+    # as a route segment and a directory name (app/<slug>/page.tsx). It is derived here
+    # rather than per workflow so every reader gets the same segment for one feature.
+    # CamelCase splits on the case boundary before the non-alphanumeric squeeze, so
+    # OrderManagement and "Order Management" both reach order-management.
+    local feature_slug
+    feature_slug=$(printf '%s' "$feature" \
+        | sed -E 's/([a-z0-9])([A-Z])/\1-\2/g; s/([A-Z]+)([A-Z][a-z])/\1-\2/g' \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')
     # The master documents of a feature: spec.md (WHAT/WHY) + one LANE PLAN per declared
     # lane (each lane's HOW) — backend-plan.md for the service lane, frontend-plan.md for
     # the frontend lane. `plan` writes them; nothing else does.
@@ -1708,8 +1779,8 @@ cmd_feature_paths() {
     local needs_bootstrap=false
     [ "$spec_exists" = false ] && needs_bootstrap=true
     [ "$bootstrap_pending" = true ] && needs_bootstrap=true
-    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","backend_plan":"%s","frontend_plan":"%s","backend_plan_exists":%s,"frontend_plan_exists":%s,"design_file":"%s","ui_design_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s,"bootstrap_pending":%s,"needs_bootstrap":%s}\n' \
-        "$(json_escape "$feature")" "$(json_escape "$fd")" "$(json_escape "$spec")" \
+    printf '{"feature":"%s","feature_slug":"%s","feature_dir":"%s","spec_file":"%s","backend_plan":"%s","frontend_plan":"%s","backend_plan_exists":%s,"frontend_plan_exists":%s,"design_file":"%s","ui_design_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s,"bootstrap_pending":%s,"needs_bootstrap":%s}\n' \
+        "$(json_escape "$feature")" "$(json_escape "$feature_slug")" "$(json_escape "$fd")" "$(json_escape "$spec")" \
         "$(json_escape "$design")" "$(json_escape "$ui_design")" "$design_exists" "$ui_design_exists" \
         "$(json_escape "$design")" "$(json_escape "$ui_design")" "$spec_exists" "$design_exists" "$ui_design_exists" \
         "$bootstrap_pending" "$needs_bootstrap"
@@ -4987,6 +5058,7 @@ case "$sub" in
     version-read)     cmd_version_read "$@" ;;
     version-init)     cmd_version_init "$@" ;;
     version-bootstrap-done) cmd_version_bootstrap_done "$@" ;;
+    feature-lanes)    cmd_feature_lanes "$@" ;;
     feature-paths)    cmd_feature_paths "$@" ;;
     design-scaffold)  cmd_design_scaffold "$@" ;;
     # The plan phase's name for the same op. Both spellings reach one implementation:

package/assets/.appweaver/scripts/powershell/aw-rev-constitution.ps1

@@ -5,7 +5,7 @@
 # ONCE in ..\python\aw-rev-constitution.py; this wrapper exists only so the
 # orchestrator's execute_script (sh:/ps1: dispatch) can invoke it. Args pass through.
 #
-#   aw-rev-constitution.ps1 list-adopted [--root <dir>] [--specs <dir>] [--bundle <dir>]
+#   aw-rev-constitution.ps1 project-context [--root <dir>] [--bundle <dir>]
 #   aw-rev-constitution.ps1 project-setup --name <domain> [--fallback <name>] [--root <dir>]
 $ErrorActionPreference = "Stop"
 $core = Join-Path $PSScriptRoot "..\python\aw-rev-constitution.py"