aw-spec-cli 0.1.21 → 0.1.22

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

@@ -107,6 +107,14 @@ standards:
 
 vars:
   spec_all_pass: "false"     # validation-loop guard, flipped by the validate query
+  nn_count: "0"              # ratified NON-NEGOTIABLE principles, from principles-list.
+                             # 0 = a project that ratified none, which skips the gate.
+  nn_titles: ""              # those principles, for the judge's prompt
+  nn_compliant: "false"      # per-clarification verdict. DEFAULTS TO REFUSE: the gate
+                             # reads it, so a judge that never answered stops the run
+                             # rather than passing an unexamined answer through.
+  nn_principle: ""           # the principle a departing answer was judged against
+  nn_why: ""                 # what it requires and what the answer does instead
   checklist_total: "0"       # bound by checklist-read
   checklist_passed: "0"      # stays 0 when the checklist has no items to score
   cr_id: ""                  # set on the DELTA path only
@@ -520,6 +528,23 @@ workflow:
 
   # 6. Resolve [NEEDS CLARIFICATION] markers interactively (≤3). Non-interactive
   #    runs answer with the first/recommended option (a documented default).
+  #
+  #    THE DEFAULT IS WHY THIS IS GOVERNED. A non-interactive run answers with options[0],
+  #    so whatever the extraction listed first becomes project policy unattended — and a
+  #    clarification is asked at exactly the altitude where a ratified principle already
+  #    has an answer. The constitution halves ARE in context here (build_context put them
+  #    in the envelope, which include_standards: false does not touch), but nothing told
+  #    the extraction that a principle outranks a question, and nothing checked the answer
+  #    afterwards. Both halves of that are below: the ordering rule in the task, and the
+  #    per-answer gate inside the loop.
+  - id: nn_principles
+    action: execute_script
+    script: { ref: actions }
+    subcommand: principles-list
+    outputs:
+      - { name: nn_count,  from: "$.count" }
+      - { name: nn_titles, from: "$.titles_csv" }
+
   - id: extract_clarifications
     action: agent_query
     context: ["{{quality_target}}"]
@@ -528,6 +553,15 @@ workflow:
       Extract up to 3 unresolved "[NEEDS CLARIFICATION: <question>]" markers from
       the document in context (a feature spec, or one change's delta-spec), most
       scope/security/UX-impacting first. Return {"clarifications":[]} if there are none.
+
+      A RATIFIED PRINCIPLE IS NOT A QUESTION. The constitution halves in context carry
+      principles marked (NON-NEGOTIABLE). Where one of them already settles a marker,
+      it is not a clarification: DROP it from the list — the answer is the principle,
+      and the document is corrected to match it in the quality loop. Offering it as a
+      choice invites a project to vote on something already ratified.
+      For a marker that merely TOUCHES such a principle, every option you list must be
+      compatible with it, and the most compliant option must be FIRST — an unattended
+      run takes the first one.
     schema: { clarifications: [ { id: c1, question: "<the question>", options: ["<answer A>", "<answer B>", "<answer C>"] } ] }
     mock: { clarifications: [] }
     outputs:
@@ -545,6 +579,72 @@ workflow:
         options_from: "{{c.options}}"
         answer_key: "{{c.id}}"
         answer_var: c_answer
+
+      # THE ANSWER IS CHECKED BEFORE IT IS WRITTEN IN. Placed between the ask and the
+      # rewrite on purpose: once resolve_clar has folded the answer into a requirement it
+      # is ordinary spec prose, and catching it then means unpicking a document rather
+      # than declining an answer. Judged one answer at a time so the stop can quote the
+      # question that caused it.
+      #
+      # The agent judges ONLY against the principles nn_principles found — a citation
+      # outside that list is visibly wrong, which is the point of enumerating them with a
+      # script instead of asking one agent to both find the principle and object to it.
+      #
+      # ASKED IN THE POSITIVE, AND RESET FIRST. The gate below reads nn_compliant, so an
+      # answer the judge never delivered — a malformed reply, a step that did not run —
+      # leaves "false" standing and STOPS. Asking "does it contradict?" would invert that:
+      # the same silence would read as no contradiction found. The reset is what makes it
+      # per-iteration; vars outlive a loop pass, so without it the second clarification
+      # would inherit the first one's verdict.
+      - id: governance_reset
+        action: set
+        vars:
+          nn_compliant: "false"
+          nn_principle: ""
+          nn_why: ""
+
+      # Skipped where a project ratified no NON-NEGOTIABLE principle: with nothing to
+      # depart from there is nothing to ask, and the gate is skipped on the same
+      # condition rather than reading the "false" this reset just wrote.
+      - id: governance_check
+        condition: "{{nn_count}} != 0"
+        action: agent_query
+        context: ["{{quality_target}}"]
+        include_standards: false
+        task: |
+          The constitution halves in context ratify these NON-NEGOTIABLE principles:
+            {{nn_titles}}
+          A question was raised about this specification and has just been answered:
+            Question: {{c.question}}
+            Answer:   {{c_answer}}
+          Is that answer COMPLIANT with those principles — that is, can the specification
+          be amended to say it without asserting something a principle forbids or omitting
+          something a principle requires?
+          Judge only against the principles listed above, and when it is not compliant
+          cite the one it departs from by its id. A principle the question does not engage
+          is not a departure, and neither is an answer a principle simply does not speak
+          to; where none is engaged the answer is compliant. Report a departure only where
+          you can state what the principle requires and what the answer does instead.
+        schema: { compliant: true, principle: "<id, or empty>", why: "<one sentence, or empty>" }
+        mock: { compliant: true, principle: "", why: "" }
+        outputs:
+          - { name: nn_compliant,  from: "$.compliant" }
+          - { name: nn_principle,  from: "$.principle" }
+          - { name: nn_why,        from: "$.why" }
+
+      # FAIL CLOSED. The constitution's own Governance says a deviation with no named
+      # approver is a defect, not a decision — and this answer has no approver at all: it
+      # was settled in the run, by an operator picking from a menu or by a non-interactive
+      # default. Recording it and carrying on is how an unapproved departure from a
+      # NON-NEGOTIABLE principle reaches code, so the run stops here and the choice goes
+      # back to a human who can either comply or amend the constitution properly.
+      - id: governance_gate
+        condition: "{{nn_count}} != 0"
+        action: verify_context
+        require_true: nn_compliant
+        on_false: stop
+        on_false_message: "The answer to \"{{c.question}}\" departs from NON-NEGOTIABLE principle {{nn_principle}}: {{nn_why}}. That principle is ratified in .appweaver/memory/ and this answer has no approver — it was settled in this run, not by a domain owner, and the constitution's Governance section holds that a deviation with no named approver is a defect rather than a decision. Re-run specify and answer in a way the principle allows; if the project genuinely intends to depart from it, amend the constitution through its own amendment process FIRST (which names the approver the departure needs) and re-run. Nothing was written to {{quality_target}} for this clarification."
+
       - id: resolve_clar
         action: agent_author
         context: ["{{quality_target}}"]

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

@@ -0,0 +1,141 @@
+# =============================================================================
+# aw-spec-ui-model (orchestrator) — Derive UI Model from Workflow Model
+#
+# Stage 3 of the 4-Stage Spec-Driven UI Generation Pipeline.
+# Consumes `specs/<Feature>/ui/workflow-model.md` and maps workflows into concrete UI surfaces
+# (Pages, Sub-Pages, Drawers, Modals, Dialogs), interaction states (Loading, Empty, Populated, Filtered, Error, Success),
+# user actions, and surface transitions.
+# Writes output artifact to `specs/<Feature>/ui/ui-model.md`.
+#
+# Launch:
+#   /appweaver ui-model [strategy] [guidance]
+# =============================================================================
+
+name: aw-spec-ui-model
+description: Derive the UI Model (specs/<Feature>/ui/ui-model.md) from workflow-model.md, specifying UI surfaces (pages, dialogs, drawers, modals), routes, interaction states, actions, and navigation transitions.
+version: 1.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional UI layout or surface guidance.
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  feature: ""
+  feature_dir: ""
+  feature_slug: ""
+  spec_file: ""
+  spec_exists: "false"
+  workflow_model_file: ""
+  workflow_model_exists: "false"
+  active_change: ""
+  has_change: "false"
+  domain: ""
+  prototype_root: ""
+
+workflow:
+
+  # 1. Resolve active feature and paths
+  - id: feature_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: feature-paths
+    outputs:
+      - { name: feature,        from: "$.feature" }
+      - { name: feature_dir,    from: "$.feature_dir" }
+      - { name: feature_slug,   from: "$.feature_slug" }
+      - { name: spec_file,      from: "$.spec_file" }
+      - { name: spec_exists,    from: "$.spec_exists" }
+      - { name: domain,         from: "$.domain" }
+      - { name: prototype_root, from: "$.prototype_root" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature selected. Run /appweaver select-feature first."
+
+  - id: require_spec
+    action: verify_context
+    require_true: spec_exists
+    on_false: stop
+    on_false_message: "No specification found for this feature. Run /appweaver specify first."
+
+  # 2. Check workflow-model.md existence
+  - id: check_workflow_model
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: path-exists
+    args: ["--path", "{{feature_dir}}/ui/workflow-model.md"]
+    outputs:
+      - { name: workflow_model_exists, from: "$.exists" }
+
+  - id: require_workflow_model
+    action: verify_context
+    require_true: workflow_model_exists
+    on_false: stop
+    on_false_message: "No Workflow Model found at specs/{{feature}}/ui/workflow-model.md. Run /appweaver workflow-model first."
+
+  # 3. Assemble workflow model & template context
+  - id: ctx_ui_model
+    action: build_context
+    vars:
+      feature_name: "{{feature}}"
+      feature_dir: "{{feature_dir}}"
+      user_preferences: "{{USER_INPUT}}"
+    context:
+      - "{{feature_dir}}/ui/workflow-model.md"
+      - "{{spec_file}}"
+      - { path: ".appweaver/templates/ui-model-template.md", optional: true }
+      - { path: ".appweaver/memory/constitution.ui.md", optional: true }
+
+  # 4. Generate UI Model Artifact (specs/<Feature>/ui/ui-model.md)
+  - id: generate_ui_model
+    action: agent_generate
+    tools: "Read,Write,Edit,Bash"
+    permission_mode: acceptEdits
+    task: |
+      You are authoring Stage 3 (UI Model) of the 4-Stage Spec-Driven UI Pipeline for feature `{{feature_name}}`.
+
+      Target Artifact Path: `{{feature_dir}}/ui/ui-model.md`
+
+      Instructions:
+      1. Read `specs/{{feature}}/ui/workflow-model.md` and `spec.md` in context.
+      2. Translate EVERY workflow (WF-1, WF-2, ...) into explicit **UI Surfaces**:
+         - Determine the appropriate UI surface type for each workflow step: `Page`, `Sub-Page`, `Dialog`, `Drawer`, `Modal`, `View`.
+         - Map routes or component mount paths (e.g. `/{{feature_slug}}`, `/{{feature_slug}}/create`, modal dialog triggers).
+         - 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`.
+
+      User Guidance:
+      {{user_preferences}}
+
+      End your final reply with a summary and a ```json fence:
+      ```json
+      {
+        "status": "ok",
+        "feature": "{{feature_name}}",
+        "ui_model_path": "{{feature_dir}}/ui/ui-model.md"
+      }
+      ```
+    outputs:
+      - { name: result, from: "$" }
+
+outputs:
+  feature: "{{feature}}"
+  ui_model_path: "{{feature_dir}}/ui/ui-model.md"
+  next: "Run /appweaver ui-prototype to generate the executable Next.js prototype application."

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

@@ -0,0 +1,386 @@
+# =============================================================================
+# aw-spec-ui-prototype (orchestrator) — Next.js UI prototype per domain
+#
+# Scaffolds a single shared Next.js prototype app per domain (prototypes/<domain>/),
+# then on every subsequent run adds or regenerates just the active feature's screen/route inside it,
+# driven by that feature's spec.md (+ any active delta-spec.md).
+#
+# Launch:
+#   /appweaver ui-prototype [strategy] [guidance]
+# =============================================================================
+
+name: aw-spec-ui-prototype
+description: Generate or update a single screen/route inside a domain Next.js UI prototype, driven by the active feature's specification (referencing workflow-model.md and ui-model.md if available, or directly from spec.md).
+version: 3.7.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional UI styling or behavior preferences (e.g. dark mode, Tailwind aesthetic, specific mock data).
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  feature: ""
+  feature_dir: ""
+  feature_slug: ""
+  spec_file: ""
+  spec_exists: "false"
+  context: ""
+  context_dir: ""
+  domain_model: ""
+  domain_model_exists: "false"
+  active_change: ""
+  has_change: "false"
+  domain: ""
+  prototype_root: "prototype"
+  project_exists: "false"
+
+workflow:
+
+  # 1. Resolve active feature and its spec directly from .appweaver/feature.json
+  #    which points to the bounded context directory and then the feature (specs/<BoundedContext>/<Feature>/)
+  - id: feature_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: feature-paths
+    outputs:
+      - { name: feature,        from: "$.feature" }
+      - { name: feature_slug,   from: "$.feature_slug" }   # kebab-case route segment
+      - { name: feature_dir,    from: "$.feature_dir" }
+      - { name: spec_file,      from: "$.spec_file" }
+      - { name: spec_exists,    from: "$.spec_exists" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature. Run /appweaver select-feature first, then re-run ui-prototype."
+
+  - id: require_spec
+    action: verify_context
+    require_true: spec_exists
+    on_false: stop
+    on_false_message: "No specification found for this feature at {{spec_file}}. Run /appweaver specify first to create spec.md."
+
+  # 2. Resolve the bounded context containing this feature and its canonical domain model
+  - id: context_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: context-paths
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: context,             from: "$.context" }
+      - { name: context_dir,         from: "$.context_dir" }
+      - { name: domain_model,        from: "$.domain_model" }
+      - { name: domain_model_exists, from: "$.domain_model_exists" }
+
+  # 3. Resolve active domain
+  - id: resolve_domain
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: resolve-domain
+    args: ["--command", "/aw-spec-ui-prototype"]
+    outputs:
+      - { name: domain, from: "$.domain" }
+
+  # 4. Resolve prototype root from stacks declaration (.appweaver/stacks.json)
+  - id: resolve_prototype_lane
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: prototype_root, from: "$.prototype.root" }
+
+  # 5. Check for active change requests (feature-level)
+  - id: version_read
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: version-read
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: active_change, from: "$.active_change" }
+      - { name: has_change,    from: "$.has_change" }
+
+  # 6. Check whether the domain prototype project already exists at prototype_root
+  - id: check_project
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: path-exists
+    args: ["--path", "{{prototype_root}}/package.json"]
+    outputs:
+      - { name: project_exists, from: "$.exists" }
+
+  # 7. Assemble specification, bounded context domain model, optional UI artifacts, and rules context
+  - id: ctx_prototype
+    action: build_context
+    vars:
+      feature_name: "{{feature}}"
+      feature_slug: "{{feature_slug}}"
+      feature_dir: "{{feature_dir}}"
+      context_name: "{{context}}"
+      context_dir: "{{context_dir}}"
+      domain: "{{domain}}"
+      prototype_root: "{{prototype_root}}"
+      project_exists: "{{project_exists}}"
+      user_preferences: "{{USER_INPUT}}"
+    context:
+      - "{{spec_file}}"
+      - { path: "{{domain_model}}", optional: true }
+      - { path: "{{feature_dir}}/ui/workflow-model.md", optional: true }
+      - { path: "{{feature_dir}}/ui/ui-model.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 }
+      - { path: "{{prototype_root}}/screens.json", optional: true }
+
+  # 5a. First run only: scaffold the domain Next.js prototype shell if missing
+  - id: scaffold_project
+    action: agent_generate
+    condition: "{{project_exists}} == false"
+    tools: "Read,Write,Edit,Bash"
+    permission_mode: acceptEdits
+    task: |
+      There is no prototype project for domain `{{domain}}` yet. Scaffold ONE reusable Next.js application
+      shell for domain `{{domain}}` at `{{prototype_root}}/`. This project will be reused and extended by every
+      subsequent feature run for `{{domain}}` — do not build any single feature's screen content here.
+
+      Build only the shared shell:
+      1. `package.json`, Next.js App Router baseline (`app/layout.tsx`), global styles/design
+         tokens, and client-side state/provider pattern screens will share
+         (e.g. a lightweight context for active persona/role).
+      2. A shared nav/shell component (sidebar or top nav) that lists available screens by
+         reading dynamically from `lib/screens-registry.ts`. It renders each entry's
+         `title` field verbatim as the visible label — later screen runs are responsible for
+         putting a natural, product-appropriate name there (see the per-screen task), not
+         a raw spec title.
+      3. A shared persona/role-switcher component — its initial role and persona options
+         are populated directly from the actors/personas specified in `spec.md` (under `Actors` /
+         `Experience Scope` / `User Stories`) and `ui-model.md`, and registered in `lib/screens-registry.ts`.
+      4. `lib/screens-registry.ts` — an empty typed registry (array of
+         `{ slug, title, route, specVersion, roles }`) plus a `screens.json` mirror for
+         non-JS tooling. This file is APPENDED TO by screen runs.
+      5. A clean, production-feeling home page (`app/page.tsx`) for the domain application —
+         shared nav and an overview relevant to the domain — using the domain's real product
+         name (derive one from `{{domain}}`/spec/constitution, e.g. "Acme" not "Acme Prototype").
+         This home page is the app's actual dashboard/landing experience — the entry point a
+         real user of this product would land on — not a menu of "screens" or a list mirroring
+         spec structure.
+
+      Do not create the route for `{{feature_name}}` yet — that happens in the next step.
+      Ensure `npm install && npm run dev` works with just this shell.
+
+      **This must read as one coherent real application, never as a list of specs:**
+      - Never render the words "prototype", "mock", "demo", "scaffold", "shell", "sample",
+        or similar anywhere a user can see them — not in the page title, `<title>`/metadata,
+        headers, nav labels, empty states, placeholder copy, button text, or console-visible
+        UI. Those words are fine in code comments, filenames, or `PROTOTYPE_NOTES.md`, but
+        never in rendered UI.
+      - Never render raw spec/traceability identifiers anywhere in the UI — no `REQ-###`,
+        `SPEC-SCREEN-###`, `SPEC-COMP-###`, `MOCKDATA-###`, `FEEDBACK-###`, `CHANGE-###`, or
+        literal spec section titles/filenames. Those are internal authoring artifacts, not
+        product language a real user would ever see.
+      - The home page, nav, and browser tab title should use the actual product/domain name
+        as if this were the shipping application, not a label describing what this project is.
+      - 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.
+
+      **Styling must actually render — this is not optional:**
+      - Install and fully configure **Tailwind CSS** (latest stable version, matching whatever
+        the installed Next.js version's official setup docs specify — App Router's Tailwind
+        setup has changed across versions, e.g. `tailwind.config.ts`/PostCSS config differs
+        between Tailwind v3 and v4). Do not stop at `npm install tailwindcss` — verify the
+        PostCSS config, content globs, and `@tailwind base/components/utilities` (or v4's
+        `@import "tailwindcss"`) directives are all present and correct for the version installed.
+      - Create `app/globals.css` with the Tailwind directives plus any design-token CSS
+        variables (colors, spacing, radii, fonts), and **explicitly `import "./globals.css"`
+        at the top of `app/layout.tsx`.** A missing import here is the most common cause of
+        a fully unstyled app — verify it's present before finishing.
+      - After scaffolding, actually run `npm run dev` (or `next build`) and confirm no
+        Tailwind/PostCSS errors appear in the output before ending this step. Don't just
+        assume the config is correct because the files exist.
+      - If `constitution.ui.md` or USER_INPUT specifies a different styling approach
+        (CSS Modules, a specific component library with its own styling, styled-components,
+        etc.), follow that instead of Tailwind — but whichever system is chosen, the same
+        rule applies: install it fully, wire it into the root layout, and verify it actually
+        renders styled output, not just that the packages are present in `package.json`.
+
+      **Always use the latest versions and current best practices:**
+      - Scaffold against the latest stable Next.js (App Router) and React releases available
+        at the time of this run — do not pin to or reproduce an older remembered baseline.
+        Resolve versions with `npm view <package> version` (or `npm install <package>@latest`)
+        rather than assuming a version from memory.
+      - Use current, non-deprecated APIs and patterns for whatever is scaffolded (routing,
+        data fetching, styling setup). If a pattern you'd default to has since been superseded
+        (e.g. an older config format, a deprecated hook/API), use the current replacement.
+      - If a UI/component library or design-token approach is implied by
+        `constitution.ui.md`, USER_INPUT, or the spec, install its latest published version
+        and use its current component APIs — check the library's current docs/changelog
+        rather than relying on a possibly-stale remembered API surface.
+      - Note the resolved major versions of Next.js/React and any UI library in a short
+        comment at the top of `package.json` or in a `PROTOTYPE_NOTES.md`, so later screen
+        runs and reviewers know what "latest" resolved to at scaffold time.
+
+  # 5b. Every run: generate/update this feature's screen inside the existing domain prototype
+  - id: generate_screen
+    action: agent_generate
+    tools: "Read,Write,Edit,Bash"
+    permission_mode: acceptEdits
+    task: |
+      You are adding or regenerating ONE screen inside the existing Next.js prototype for domain `{{domain}}`
+      at `{{prototype_root}}/`. Do NOT touch project scaffolding, `package.json`, shared layout,
+      or other features' routes/components except where explicitly instructed below.
+
+      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}}`),
+      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}}`.
+
+      **SPEC-DRIVEN PROTOTYPE GENERATION (STAGE 4 EXECUTION)**:
+      Your goal is to build the executable Next.js application surfaces defined in the spec and UI/workflow models (when available):
+      - Implement ALL UI surfaces (Primary Page `/{{feature_slug}}`, sub-routes, modal dialogs, drawers, forms, data grids/cards).
+      - Realize all user workflows (`WF-1`, `WF-2`, `WF-3`...) with realistic interactive behavior, persona role-switching, and surface navigation transitions.
+      - Handle all specified UI states (`Loading`, `Empty`, `Populated`, `Filtered / Searched`, `Validation Error`, `Submitting`, `Success`, `Error`).
+
+      1. **Multi-Surface & Route Implementation**:
+         - Create or fully regenerate `{{prototype_root}}/app/{{feature_slug}}/page.tsx`
+           (and any screen-scoped components under
+           `{{prototype_root}}/app/{{feature_slug}}/components/`).
+         - Treat this route as regenerated wholesale each run — don't hand-patch it.
+         - Build the full, finished screen the spec describes — not a wireframe, stub,
+           "coming soon," or reduced placeholder version. A user landing on this route should
+           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,
+           headers, empty states, tooltips, button copy). Keep all such labeling out of
+           user-visible text entirely.
+
+      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 —
+           never repeat them verbatim as the nav label, page heading, or route's display name.
+           Derive a natural, user-facing name the way a real product would phrase it (e.g. a
+           spec called "Project Creation Screen" surfaces as a "Projects" nav entry whose
+           content includes creating a project — not a nav item literally labeled
+           "Project Creation Screen").
+         - Decide where this screen naturally belongs in the app's information architecture
+           based on what the spec describes, the same way a product designer would: a
+           top-level nav item, a sub-page reached by an action on another already-generated
+           screen (e.g. a "New Project" button on the dashboard or on a "Projects" list),
+           or an entry point added to the shared dashboard — whichever fits how a real user
+           would discover and reach this functionality. Don't default to "flat nav item per
+           spec" if the spec's own content implies a more natural entry point (e.g. reached
+           via a button/action from another screen rather than the top-level nav).
+         - If the natural entry point is from another already-generated screen or the
+           dashboard, update that screen/dashboard minimally to add the real link/button/card
+           that leads here — don't leave this screen orphaned and reachable only by URL.
+
+      3. **Specification-driven behavior**:
+         - Derive all behavior exclusively from the active specification for this feature.
+         - Implement all functional requirements, business rules, invariants, validations,
+           constraints, state transitions, and workflows explicitly defined in spec.md.
+         - Do not invent business rules absent from the spec. Use reasonable UI defaults only
+           for presentation/interaction mechanics.
+
+      4. **Roles, personas, and permission rules from spec**:
+         - Derive all roles/personas directly from `spec.md` (under `Actors` / `Experience Scope` / `User Stories`) and `ui-model.md`.
+         - Ensure every role defined in the specification exists in the SHARED persona/role-switcher context.
+         - Wire the UI controls dynamically so switching persona demonstrates role-based visibility, disabled inputs, and permission workflows (e.g. PM vs PMO vs Delivery Head) strictly as specified.
+
+      5. **Mock data**:
+         - Place this feature's mock data under
+           `{{prototype_root}}/lib/mock-data/{{feature_slug}}.ts`, isolated from other screens.
+         - Data values should read as realistic, plausible content for this domain (real-sounding
+           names, dates, amounts, statuses) — not "Lorem ipsum," "Test User 1," "Sample Item,"
+           or other obviously-fake placeholder text. The screen should look fully populated and
+           real, even though the data behind it is static.
+
+      6. **Reuse, don't duplicate**:
+         - Reuse existing shared components (nav shell, buttons, layout primitives, design
+           tokens) from the shell in the project.
+
+      7. **Styling must render on this screen too**:
+         - Before writing this screen, confirm the shell's styling setup is actually wired
+           up — `app/globals.css` exists and is imported in `app/layout.tsx`, and the
+           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.
+         - 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
+           isolation are usually the sign the shared pipeline isn't actually being used.
+         - If this screen needs a component from a UI library not yet installed in the shell
+           (e.g. a data table, date picker), install it into the shell's `package.json` (latest
+           version, per below) and ensure its required CSS/theme setup is added to
+           `app/globals.css` or its own import — a component library added without its styles
+           wired in is another common source of unstyled output.
+
+      8. **Always use the latest UI, components, and libraries**:
+         - Any new dependency added for this screen (UI library, icon set, chart/table/form
+           component, date picker, etc.) must be the latest stable published version —
+           resolve it with `npm view <package> version` or install via `@latest` rather than
+           writing a version from memory.
+         - When reusing shared components from the shell, check whether the shell's installed
+           versions are current; if `{{prototype_root}}/PROTOTYPE_NOTES.md` or `package.json`
+           indicates they're stale relative to what's now available, flag it in your final
+           summary rather than silently building on outdated components — don't upgrade
+           shared/shell dependencies yourself from a screen run.
+         - Prefer each library's current, non-deprecated component API and patterns
+           (e.g. current shadcn/ui component structure, current Next.js Image/Link/Font APIs)
+           over older remembered forms of the same API.
+         - Do not introduce a second library that duplicates something the shell or an
+           earlier screen already standardized on — "latest" applies to versions, not to
+           swapping in a different library each run.
+
+      9. **Registry update**:
+         - Add or update this feature's entry in `lib/screens-registry.ts` and `screens.json`:
+           `{ slug: "{{feature_slug}}", title: "<natural product-facing name from step 2, NOT
+           the raw spec title>", route: "/{{feature_slug}}", specVersion: <from spec.md if
+           present>, roles: [...] }`.
+         - `title` here drives the visible nav label — it must be the naturalized name from
+           step 2, never `{{feature_name}}` or a spec ID verbatim. If you need to retain the
+           original spec title/ID for traceability, add it as a separate non-rendered field
+           (e.g. `specRef`) rather than reusing `title` for it.
+
+      User Preferences / Guidance:
+      {{user_preferences}}
+
+      End your final reply with a summary of what was added/changed and a ```json code block:
+      ```json
+      {
+        "status": "ok",
+        "domain": "{{domain}}",
+        "feature": "{{feature_name}}",
+        "slug": "{{feature_slug}}",
+        "route": "/{{feature_slug}}",
+        "prototype_root": "{{prototype_root}}",
+        "launch_command": "cd {{prototype_root}} && npm run dev"
+      }
+      ```
+    outputs:
+      - { name: result, from: "$" }
+
+outputs:
+  domain: "{{domain}}"
+  context: "{{context}}"
+  context_dir: "{{context_dir}}"
+  feature: "{{feature}}"
+  spec_file: "{{spec_file}}"
+  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."
+  next: "Visit http://localhost:3000/{{feature_slug}} to review this screen, or / for the full screen list."