aw-spec-cli 0.1.23 → 0.1.25

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-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-ui-model.orch.yaml

@@ -110,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 }
 
@@ -135,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

@@ -123,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,6 +52,8 @@
 #   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-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[]}
@@ -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=""
@@ -4997,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"

package/assets/.appweaver/scripts/powershell/aw-spec-actions.ps1

@@ -631,6 +631,9 @@ function Invoke-LaneResolve {
     for ($i = 0; $i -lt $Rest.Count; $i++) {
         switch ($Rest[$i]) {
             { $_ -in '--kind','--id' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            # 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' { $v = $Rest[++$i]; if ($v) { $fwd += '--feature-dir'; $fwd += $v } }
             default { Write-Error "lane-resolve: unknown arg '$($Rest[$i])'"; exit 1 }
         }
     }
@@ -1084,6 +1087,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
@@ -1183,6 +1211,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)
@@ -1194,10 +1223,10 @@ print(json.dumps(out))
 '@
 
 function Invoke-ActiveVersion {
-    param([string]$FeatureDir, [string]$Op, [string]$CrId = '', [string]$Force = '', [string]$Boot = '')
+    param([string]$FeatureDir, [string]$Op, [string]$CrId = '', [string]$Force = '', [string]$Boot = '', [string]$Lanes = '')
     $py = Get-Py; if (-not $py) { Write-Error "version-$Op`: python3 required"; exit 1 }
     $env:AW_FD = $FeatureDir; $env:AW_OP = $Op; $env:AW_CR = $CrId; $env:AW_FORCE = $Force
-    $env:AW_BOOT = $Boot
+    $env:AW_BOOT = $Boot; $env:AW_LANES = $Lanes
     # CrId names the change on BOTH open and close: many may be open at once, so a close
     # has to say which one it is closing rather than assuming the only one.
     $PyActiveVersion | & $py -
@@ -1216,6 +1245,32 @@ function Invoke-VersionState {   # op in read|init (feature-dir only)
     Invoke-ActiveVersion -FeatureDir $fd -Op $Op -Boot $boot
 }
 
+# The lane kinds this feature has a surface in, recorded in its active_version.json. Twin
+# of bash cmd_feature_lanes: 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.
+function Invoke-FeatureLanes {
+    param([string[]]$Rest)
+    $fdArg = ''; $lanes = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] }
+            '--set'   { $lanes = $Rest[++$i] }
+            '--clear' { $lanes = 'all' }
+            default { Write-Error "feature-lanes: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'feature-lanes: no feature set and no --feature-dir'; exit 1 }
+    $out = Invoke-ActiveVersion -FeatureDir $fd -Op 'lanes' -Lanes $lanes
+    $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.
+    $res = $out | ConvertFrom-Json
+    if (-not $res.ok) { [Console]::Error.WriteLine("feature-lanes: $($res.error)"); exit 1 }
+}
+
 
 
 # ─────────────────────────── feature-paths ─────────────────────────────────
@@ -4403,6 +4458,7 @@ switch ($sub) {
     'version-read'     { Invoke-VersionState 'read'  $rest }
     'version-init'     { Invoke-VersionState 'init'  $rest }
     'version-bootstrap-done' { Invoke-VersionState 'bootstrap-done' $rest }
+    'feature-lanes'    { Invoke-FeatureLanes     -Rest $rest }
     'feature-paths'    { Invoke-FeaturePaths     -Rest $rest }
     'design-scaffold'  { Invoke-DesignScaffold   -Rest $rest }
     # The plan phase's name for the same op. Both spellings reach one implementation: