aw-spec-cli 0.1.13 → 0.1.15

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

@@ -1,33 +1,57 @@
 # =============================================================================
-# aw-spec-implement (orchestrator) — model-driven code generation from the DESIGN
+# aw-spec-implement (orchestrator) — code generation from ONE STORY'S DESIGN
 #
-# The spec-anchored Implement phase: GENERATE the source files + paired tests for
-# the aggregate STRICTLY from its single high-level design.md — the mediator between
-# spec and code. Implement does NOT read spec.md: `analyze` already guaranteed the
-# design conforms to the spec (spec is the anchor), so the design is the complete,
-# authoritative source for WHAT to build. The target STACK is bound here from the
-# constitution + the active stack profile (the design is technology-agnostic).
-# Prereqs: run /appweaver design then analyze-design first (the gate conforms the
-# design to the spec + closes any open change), and scaffold the project once —
-# implement GENERATES into that project tree, so with no project there is nowhere
-# to place the files. /appweaver foundation unpacks one where a bundle ships for the
-# stack; a stack with no bundle scaffolds with its own tooling instead, and the gate
-# below accepts either, since it tests for a project rather than for a bundle.
+# The executable end of the story loop: GENERATE the service lane's source files and
+# paired tests for ONE STORY, strictly from the LATEST design pass in that story's own
+# service design — specs/<F>/stories/<ID>/story-backend-plan.md.
 #
-# Next: Build (compile + fix; reconcile only high-level variations into design.md).
+# IT BUILDS A SLICE, NOT A FEATURE. The old contract generated the whole aggregate from
+# the feature design every run, which is only correct once: the second run rewrites the
+# first story's code from a document that has since moved. A story design names the
+# files it changes, so this phase edits an existing tree — creating only what the pass
+# says is new — and its OKF write is a MERGE, never a replace.
 #
-# Launch:  /appweaver implement [strategy] [guidance]
+# DESIGN-ONLY, AND THE DESIGN IS THE STORY'S. spec.md is deliberately NOT a generation
+# input: generating from the spec routes around every gate between them and makes the
+# design advisory without anyone deciding that it should. The spec appears once, AFTER
+# the code exists, in a read-only acceptance check that reports and never repairs.
+#
+# THE LATEST PASS WINS, AND A HAND EDIT TO IT IS HONOURED. Passes append; earlier ones
+# are superseded history. The pass this run builds from is named in the prompt and in
+# the outputs, so "which design produced this code" has one answer.
+#
+# INPUT CHANNELS, each with one job:
+#   story-backend-plan.md   the LATEST pass = the complete WHAT for this slice
+#   stories/<ID>.md         the story's acceptance criteria — what "done" means
+#   current code (OKF)      what EXISTS, per lane, so this run edits rather than recreates
+#   interfaces.md           the PUBLISHED surface the generated code must match
+#   adr.md                  what was DECIDED — binding unless a pass supersedes it
+#   constitution + rules    HOW to build it (stack, layout, standards)
+# backend-plan.md is NOT a generation input. The pass was designed inside it and is the
+# concrete form of it; re-reading the plan here would let code drift from the pass back
+# toward the architecture, with no gate between the two. It is read for two DERIVED
+# facts only — the aggregate's cross-slice edges and its Overview prose — both of which
+# are feature-level properties no single story can state.
+#
+# GATES (all loud, all before any write): the service lane declared with its source path;
+# a scaffolded project under that path; an active feature; an OPEN story; and that story
+# having a service design at all. A design behind the current spec, or a story the spec
+# has moved past, is ANNOUNCED — never refused: the story is legitimately in flight, and
+# the spec may have moved on ids it does not carry. The route out of both is named.
+#
+# Launch:  /appweaver implement [<story-id>] [guidance]     (asks when ambiguous)
+# Prereq:  /appweaver story-plan (the story's design)  ·  Next: /appweaver build
 # =============================================================================
 
 name: aw-spec-implement
-description: Generate the aggregate's source files and paired tests STRICTLY from its design.md, bound to the project's stack. Model-driven, design-only (does not read the spec — analyze already conformed the design to it).
-version: 2.1.0
+description: "Generate the service lane's source files and paired tests for ONE STORY, strictly from the LATEST design pass in stories/<ID>/story-backend-plan.md, bound to the declared backend stack and written only under that lane's source path. Model-driven and design-only — the spec is never a generation input; it appears once afterwards in a read-only acceptance check that reports and never repairs. Incremental by contract: it edits the feature's existing tree, creating only what the pass names as new, and MERGES the files it wrote into the feature's OKF concept rather than replacing the list."
+version: 3.0.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
 inputs:
   user_input:
-    description: Optional implementation guidance (stack hints, focus area).
+    description: Optional story id and/or implementation guidance (e.g. "Order-001 keep the mapper hand-written").
     required: false
     bind: USER_INPUT
 
@@ -39,74 +63,220 @@ scripts:
     sh:  .appweaver/scripts/bash/aw-xref.sh
     ps1: .appweaver/scripts/powershell/aw-xref.ps1
 
-# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The
-# FRAMEWORK / code-generation rule files are no longer hardcoded here — they are now
-# CONFIGURATION, loaded per-command from guardrails/projects/<project>/tech-rule-bindings.md
-# by the tech-select module (see the workflow's tech_select step), exactly as design's
-# technical rules are. Per the rule-partition, implement still generates from design.md +
-# these HOW-to-build standards and loads NO domain rule file — the tech map lists only
-# technical files. The architecture principles come via constitution.technical.md
-# (referred to directly, as-is — NOT mapped); the structure via design.md. Component
-# rule docs are NOT loaded here — implement codes against a component's PORT; adding the
-# component itself is a separate step, /appweaver add-component. (missing files skipped)
+# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The FRAMEWORK /
+# code-generation rule files are CONFIGURATION, loaded per-command from
+# guardrails/projects/<project>/tech-rule-bindings.md under "## /aw-spec-implement" by
+# the tech-select module. Per the rule-partition this phase loads NO domain rule file —
+# the domain reached it through spec → feature plan → the story's design pass. The
+# architecture principles arrive via constitution.technical.md (referred to directly,
+# as-is — NOT mapped). Component rule docs are NOT loaded here: implement codes against
+# a component's PORT, and installing the component is /appweaver add-component.
 standards:
   - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
 
+vars:
+  feature_dir: ""
+  spec_file: ""
+  be_plan: ""
+  be_plan_exists: "false"
+  # story resolution
+  any_open: "false"
+  open_ids: "[]"
+  digest: ""
+  resolved: "false"
+  needs_pick: "false"
+  pick_reason: ""
+  picked_story: ""
+  story: ""
+  story_path: ""
+  story_open: "false"
+  status_msg: ""
+  story_title: ""
+  exercises_csv: ""
+  constraints_csv: ""
+  current_version: ""
+  stale_csv: ""
+  stale_note: ""
+  story_dir: ""
+  adr_path: ""
+  if_path: ""
+  # the story's SERVICE design
+  design_doc: ""
+  design_exists: "false"
+  design_pass: "0"
+  design_spec_version: ""
+  design_stale: "false"
+  # the feature's current code, per lane (OKF)
+  okf_concept: ""
+  coverage_digest: ""
+  be_source_csv: ""
+  be_source_count: "0"
+  fe_source_count: "0"
+  # generation + enrichment
+  files: ""
+  xref_wrote: ""
+  xref_edge_count: "0"
+  okf_overview: ""
+  accept_ok: "true"
+  accept_gaps: ""
+  accept_note: ""
+
 workflow:
 
   # 0. TECHNICAL rule files → sticky standards (configuration, not hardcoded).
-  #    tech-select reads guardrails/projects/<project>/tech-rule-bindings.md under
-  #    "## /aw-spec-implement" and loads that set into the sticky standards the
-  #    agent_generate step ALWAYS prepends. No domain rule file is loaded here — the
-  #    tech map lists only technical files (rule-partition intact). No blocking gate:
-  #    an unconfigured project soft-continues (constitution.technical.md still carries
-  #    the tech base, referred to directly below).
+  #    No blocking gate: an unconfigured project soft-continues, because
+  #    constitution.technical.md still carries the technology base.
   - id: tech_select
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
     with: { command: aw-spec-implement }
 
-  # 1. Resolve the current feature + its design; require the DESIGN (implement's
-  #    only input). No spec — analyze already conformed the design to the spec.
+  # 1. The active feature. spec.md and backend-plan.md are resolved here but neither is
+  #    a generation input — see the header for what each is actually used for.
   - id: feature_paths
     action: execute_script
     on_error: continue      # never crash raw on 'no feature set' — the gate below explains it
     script: { ref: actions }
     subcommand: feature-paths
     outputs:
-      - { name: feature_dir,   from: "$.feature_dir" }
-      - { name: design_doc,    from: "$.design_file" }
-      - { name: design_exists, from: "$.design_exists" }
-
+      - { name: feature_dir,    from: "$.feature_dir" }
+      - { name: spec_file,      from: "$.spec_file" }
+      - { name: be_plan,        from: "$.backend_plan_file" }
+      - { name: be_plan_exists, from: "$.backend_plan_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 (pick or create the aggregate, e.g. Order), then re-run implement."
 
-  - id: verify_design
+  # 2. WHICH STORY. Same resolution story-plan uses: an explicit id in the input wins,
+  #    anything else (nothing named, an unknown id, several) becomes a pick from the open
+  #    backlog. One scan returns every fact the gates below read.
+  - id: story_scan
+    action: execute_script
+    script: { ref: actions }
+    subcommand: story-plan-check
+    args: ["--feature-dir", "{{feature_dir}}", "--input", "{{USER_INPUT}}"]
+    outputs:
+      - { name: any_open,            from: "$.any_open" }
+      - { name: open_ids,            from: "$.open_ids" }
+      - { name: digest,              from: "$.digest" }
+      - { name: resolved,            from: "$.resolved" }
+      - { name: needs_pick,          from: "$.needs_pick" }
+      - { name: pick_reason,         from: "$.pick_reason" }
+      - { name: story,               from: "$.story" }
+      - { name: story_path,          from: "$.story_path" }
+      - { name: story_open,          from: "$.story_open" }
+      - { name: status_msg,          from: "$.status_msg" }
+      - { name: story_title,         from: "$.story_title" }
+      - { name: exercises_csv,       from: "$.exercises_csv" }
+      - { name: constraints_csv,     from: "$.constraints_csv" }
+      - { name: current_version,     from: "$.current_version" }
+      - { name: stale_csv,           from: "$.stale_csv" }
+      - { name: stale_note,          from: "$.stale_note" }
+      - { name: story_dir,           from: "$.story_dir" }
+      - { name: adr_path,            from: "$.adr_path" }
+      - { name: if_path,             from: "$.if_path" }
+      - { name: design_doc,          from: "$.be_doc_path" }
+      - { name: design_exists,       from: "$.be_doc_exists" }
+      - { name: design_pass,         from: "$.be_last_pass" }
+      - { name: design_spec_version, from: "$.be_doc_spec_version" }
+      - { name: design_stale,        from: "$.be_doc_stale" }
+  - id: require_open_backlog
+    action: verify_context
+    require_true: any_open
+    on_false: stop
+    on_false_message: "No open stories for this feature — there is nothing to implement. Stories are minted by /appweaver specify (bootstrap) and /appweaver sync-stories (when the spec moves)."
+  - id: ask_story
+    condition: "{{needs_pick}} == true"
+    action: ask
+    prompt: |
+      Which story is this implementation for? ({{pick_reason}})
+
+      {{digest}}
+    options_from: "{{open_ids}}"
+    answer_key: picked_story
+    answer_var: picked_story
+  - id: story_pick_check
+    condition: "{{needs_pick}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: story-plan-check
+    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{picked_story}}"]
+    outputs:
+      - { name: resolved,            from: "$.resolved" }
+      - { name: story,               from: "$.story" }
+      - { name: story_path,          from: "$.story_path" }
+      - { name: story_open,          from: "$.story_open" }
+      - { name: status_msg,          from: "$.status_msg" }
+      - { name: story_title,         from: "$.story_title" }
+      - { name: exercises_csv,       from: "$.exercises_csv" }
+      - { name: constraints_csv,     from: "$.constraints_csv" }
+      - { name: stale_csv,           from: "$.stale_csv" }
+      - { name: stale_note,          from: "$.stale_note" }
+      - { name: story_dir,           from: "$.story_dir" }
+      - { name: design_doc,          from: "$.be_doc_path" }
+      - { name: design_exists,       from: "$.be_doc_exists" }
+      - { name: design_pass,         from: "$.be_last_pass" }
+      - { name: design_spec_version, from: "$.be_doc_spec_version" }
+      - { name: design_stale,        from: "$.be_doc_stale" }
+  - id: require_story
+    action: verify_context
+    require_true: resolved
+    on_false: stop
+    on_false_message: |
+      Could not resolve a story from '{{picked_story}}'. Open stories:
+      {{digest}}
+      Re-run implement naming one of them.
+  - id: require_open_story
+    action: verify_context
+    require_true: story_open
+    on_false: stop
+    on_false_message: "{{status_msg}}"
+
+  # 3. THE STORY MUST HAVE A SERVICE DESIGN. This phase generates from a design pass and
+  #    from nothing else, so an undesigned story has no input — and the fix is one
+  #    command, not a judgement call.
+  - id: require_design
     action: verify_context
     require_true: design_exists
     on_false: stop
-    on_false_message: "No design.md for the current feature. Run /appweaver design then /appweaver analyze-design first — implement generates STRICTLY from the conformed design."
+    on_false_message: "Story {{story}} has no service design — {{story_dir}}/story-backend-plan.md does not exist. Run /appweaver story-plan {{story}} first: it designs the slice against the feature's backend plan, the current code and the published interfaces. implement generates from that pass and has no other input."
 
-  # 1a. Require the SERVICE LANE and its source path. Implement writes code, and
-  #     the lane's root is the subtree it is allowed to write into — so this runs
-  #     before the foundation gate, which searches that subtree for a project.
+  # 3a. A design behind the spec is ANNOUNCED, not refused. The story is legitimately in
+  #     flight and the spec may have moved on ids it does not carry; stale_csv below is
+  #     the sharper signal, because it names only the ids THIS story actually carries.
+  - id: design_stale_notice
+    condition: "{{design_stale}} == true"
+    action: verify_context
+    require_value: design_stale
+    equals: "false"
+    on_mismatch: continue
+    on_mismatch_message: "Design pass {{design_pass}} was written against spec {{design_spec_version}} and the spec is now at {{current_version}}. Generating from it is not wrong — the move may not touch this story — but if it does, the code inherits a contract that no longer holds. Re-run /appweaver story-plan {{story}} to design against the current spec, or check the ids named below."
+  # stale_csv is a STRING, so require_value/equals compares cleanly and needs no
+  # condition. design_stale above is a JSON boolean, which require_value stringifies as
+  # 'True' — it can never equal 'false', so that one is gated by `condition:` and the
+  # value gate is only the vehicle that prints (law 43).
+  - id: story_stale_notice
+    action: verify_context
+    require_value: stale_csv
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: "The spec has moved on ids THIS story carries: {{stale_csv}}. Whatever this run generates for them realises superseded wording. Consider /appweaver sync-stories to bring the backlog back in step, then /appweaver story-plan {{story}}, before building."
+
+  # 4. THE SERVICE LANE and its source path. This phase writes code, and the lane's root
+  #    is the only subtree it may write into — so this runs before the project gate,
+  #    which searches that subtree.
   - id: lane_gate
     action: include
     module: .appweaver/orchestrator/modules/lane-gate.orch.yaml
     with: { require: backend, command: "/appweaver implement" }
 
-  # 1b. Require the PROJECT — a scaffolded, compiling tree — to be present. Implement
-  #     GENERATES the aggregate's code INTO it; with no project there is nowhere to place
-  #     the files. Deterministic structure gate: searches the LANE'S OWN subtree for an
-  #     ecosystem manifest (.sln/.csproj, pom.xml, build.gradle, package.json, go.mod,
-  #     Cargo.toml, pyproject.toml), falling back to the whole repo for the layout that
-  #     keeps its manifest beside the lane root rather than inside it, and ignoring the
-  #     framework/spec/guardrails/foundations dirs — never trusts the model for this.
-  #     How the project got there is not asked: `foundation` unpacked it, or the team
-  #     scaffolded it with the stack's own tooling.
+  # 5. Require the PROJECT — a scaffolded, compiling tree. Implement GENERATES into it;
+  #    with no project there is nowhere to place the files. Deterministic structure gate:
+  #    searches the LANE'S OWN subtree for an ecosystem manifest, falling back to the
+  #    whole repo for the layout that keeps its manifest beside the lane root rather than
+  #    inside it. How the project got there is not asked.
   - id: detect_foundation
     action: execute_script
     script: { ref: actions }
@@ -116,14 +286,30 @@ workflow:
       - { name: foundation_present, from: "$.scaffolded" }
       - { name: project_markers,    from: "$.markers" }
       - { name: project_scope,      from: "$.scope" }
-
   - id: foundation_gate
     action: verify_context
     require_true: foundation_present
     on_false: stop
-    on_false_message: "No project found under the {{lane_id}} lane's source path `{{lane_source_path}}`, nor anywhere else in this repository. Implement GENERATES the aggregate's code into an existing project tree, so one has to be scaffolded first: run /appweaver foundation <FoundationName> <AppName> where a foundation bundle ships for this stack, or create the project with the stack's own tooling under that path. Any ecosystem manifest marks it — .sln/.csproj, pom.xml, build.gradle(.kts), package.json, go.mod, Cargo.toml or pyproject.toml."
+    on_false_message: "No project found under the {{lane_id}} lane's source path `{{lane_source_path}}`, nor anywhere else in this repository. Implement GENERATES this story's code into an existing project tree, so one has to be scaffolded first: run /appweaver foundation <FoundationName> <AppName> where a foundation bundle ships for this stack, or create the project with the stack's own tooling under that path. Any ecosystem manifest marks it — .sln/.csproj, pom.xml, build.gradle(.kts), package.json, go.mod, Cargo.toml or pyproject.toml."
 
-  # 2. Pre-execution hooks.
+  # 6. WHAT ALREADY EXISTS, from the feature's OKF concept, split by lane. This is what
+  #    makes the run incremental: the pass names the files it changes, and this names the
+  #    files that are there to change. Advisory — the first story of a greenfield feature
+  #    has no concept and generates into a clean tree.
+  - id: coverage
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-coverage
+    args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{exercises_csv}}"]
+    outputs:
+      - { name: okf_concept,     from: "$.concept" }
+      - { name: coverage_digest, from: "$.digest" }
+      - { name: be_source_csv,   from: "$.backend_csv" }
+      - { name: be_source_count, from: "$.backend_count" }
+      - { name: fe_source_count, from: "$.frontend_count" }
+
+  # 7. Pre-execution hooks.
   - id: resolve_pre_hooks
     action: execute_script
     script: { ref: actions }
@@ -135,74 +321,111 @@ workflow:
     action: dispatch_hooks
     hooks_from_variable: before_hooks
 
-  # 3. Model-driven generation: design.md → source files + paired tests.
-  #    The design constrains WHAT to build; the constitution/stack profile fixes HOW.
-  #    The spec is deliberately NOT in context — the design is the single source here.
+  # ═══════════════════ GENERATION — one story's slice, from one pass ═══════════
+  # The pass constrains WHAT to build; the constitution, the lane and the loaded
+  # standards fix HOW. spec.md is deliberately absent: the design is the single source
+  # here, and the acceptance check below is where the spec gets its say.
   - id: ctx_generate
     action: build_context
+    vars:
+      story_id: "{{story}}"
+      story_title: "{{story_title}}"
+      exercises_csv: "{{exercises_csv}}"
+      constraints_csv: "{{constraints_csv}}"
+      pass_number: "{{design_pass}}"
+      coverage_digest: "{{coverage_digest}}"
+      source_files_csv: "{{be_source_csv}}"
+      source_file_count: "{{be_source_count}}"
+      stale_note: "{{stale_note}}"
     context:
-      - { path: "{{design_doc}}" }
+      - { path: "{{design_doc}}" }                   # the story's SERVICE design — the LATEST pass is the input
+      - { path: "{{story_path}}" }                   # the story's acceptance criteria — what "done" means
+      - { path: "{{if_path}}", optional: true }      # the PUBLISHED surface this code must match
+      - { path: "{{adr_path}}", optional: true }     # ratified decisions — binding unless a pass supersedes them
       - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain
   - id: generate
     action: agent_generate
-    tools: "Read,Write,Edit"
+    tools: "Read,Write,Edit"       # the existing code arrives as {{source_files_csv}} paths, not inlined
     permission_mode: acceptEdits
     task: |
-      Generate the production code AND paired tests for this aggregate STRICTLY from
-      its design.md (in context). The design is the complete, authoritative source of
-      WHAT to build — do NOT consult or infer from the spec; `analyze` already
-      conformed the design to the spec. This phase is the HOME of the
-      technology-specific, solution-wide code-generation rules. Guidance: {{USER_INPUT}}
+      Implement story {{story_id}} — {{story_title}} — in the service lane, from
+      "## Design pass {{pass_number}}" of the story design in context. Guidance: {{USER_INPUT}}
+
+      THAT PASS IS THE ONLY SOURCE OF WHAT TO BUILD. It is the LAST pass in the
+      document; every earlier pass is superseded history, and any of them may carry
+      hand edits that were deliberate. Read the last one and build exactly it. Do NOT
+      consult or infer from spec.md — it is not in context on purpose: the design
+      already went through the gates that conform it, and generating from the spec
+      routes around all of them.
+
+      THIS IS ONE SLICE OF AN EXISTING FEATURE, NOT THE WHOLE FEATURE.
+      - The pass's "### Changes" section names, file by file, what to create and what
+        to modify. Create ONLY the files it names as new; modify the named existing
+        files IN PLACE. Every other file in this feature belongs to work that is
+        already done — do not regenerate, reformat or "tidy" it.
+      - The story delivers {{exercises_csv}} and must satisfy {{constraints_csv}}.
+        Anything outside those ids is another story's work, even if you can see it is
+        missing. If the slice genuinely cannot be built without touching shared
+        structure, make the smallest change that works and SAY SO in your summary.
+      - The code that already exists for this feature, per lane, is below. The service
+        files ({{source_file_count}} on disk) are yours to read before you edit; the UI
+        list is there so you do not change a surface that already has a client.
+
+      {{coverage_digest}}
+
+          {{source_files_csv}}
+
+      BIND THE STACK: this lane is `{{lane_id}}` — {{lane_title}}, language
+      {{lane_language}} ({{lane_ecosystem}}), declared in .appweaver/stacks.json and
+      compiled with `{{lane_build}}`, tested with `{{lane_test}}`. Generate in THAT
+      language and framework and no other, using its idioms, its project layout and its
+      test framework. Take persistence, messaging and the remaining technology choices
+      from the constitution's technology base + the loaded standards; the design is
+      technology-agnostic, so do not re-decide anything already fixed there. If the
+      loaded standards describe a DIFFERENT stack than the one above, the lane wins on
+      language and layout — follow the standards' INTENT and STOP to surface the
+      mismatch in your summary.
+
+      WRITE ONLY UNDER `{{lane_source_path}}` — the source path the `{{lane_id}}` lane
+      declares. That subtree is this lane's; a file outside it belongs to another lane
+      or to no lane at all. Do not create a parallel source tree because the layout
+      inside it is unfamiliar; if the pass needs a place this subtree has no home for,
+      STOP and surface it.
+
       Rules:
-      - THE DESIGN IS THE ONLY DOMAIN INPUT. You have design.md + framework/code
-        standards, and NO domain rule files. Introduce NO domain rule, identifier,
-        terminology, or behaviour that the design does not state — everything domain
-        already passed through spec → design. If a domain specific seems missing, STOP
-        and surface it; never invent it from memory.
-      - BIND THE STACK: this lane is `{{lane_id}}` — {{lane_title}}, language
-        {{lane_language}} ({{lane_ecosystem}}), declared in .appweaver/stacks.json and
-        compiled with `{{lane_build}}`, tested with `{{lane_test}}`. Generate in THAT
-        language and framework and no other, using its idioms, its project layout and
-        its test framework. Take persistence, messaging and the remaining technology
-        choices from the constitution's technology base + the loaded standards; the
-        design is technology-agnostic, so do not re-decide anything already fixed there.
-        If the loaded standards describe a DIFFERENT stack than the one above, the lane
-        wins on language and layout — the standards' stack-specific mechanics do not
-        apply, so follow their INTENT and STOP to surface the mismatch in your summary.
-      - WRITE ONLY UNDER `{{lane_source_path}}` — the source path the `{{lane_id}}`
-        lane declares in .appweaver/stacks.json. That subtree is this lane's, and a file
-        outside it belongs to another lane or to no lane at all. Do not create a
-        parallel source tree because the layout inside it is unfamiliar; if the design
-        needs a place this subtree has no home for, STOP and surface it.
+      - THE PASS IS THE ONLY DOMAIN INPUT. You have it, the story, and framework/code
+        standards — and NO domain rule files. Introduce NO domain rule, identifier,
+        terminology or behaviour the pass does not state. If a domain specific seems
+        missing, STOP and surface it; never invent it from memory.
       - Follow the project's folder/layer convention + the loaded coding-standards,
-        dependency-policy and testing standards for HOW to structure, name, and place
-        files WITHIN that subtree — the design says WHAT to build; these standards
-        (identical for every feature) say HOW.
-      - COMPONENTS: when the design's External Integrations table depends on a framework
-        component (e.g. `IEmailService`, `IJobScheduler`), code against that component's
-        ABSTRACTION / port as the design declares — do NOT hand-roll it. Installing the
-        component into the project (packages, provider wiring, config) is a SEPARATE step:
-        /appweaver add-component <Component>. If the port isn't present yet, code to
-        it and note add-component as the prerequisite; do not load component rule docs here.
-      - Realise EVERY design element as code, changing nothing about WHAT it specifies:
-        one file per Domain type / Application use-case / API endpoint / Infrastructure
-        adapter, placed by layer. Preserve the ubiquitous-language names verbatim.
-      - Enforce EXACTLY as the design states: every Domain invariant, Application
-        handler orchestration, and API error contract; the cross-cutting constraints in
-        the Cross-Cutting Concerns table (audit / retention / data-exposure — the
-        CN-/DC- realisations); and each integration contract (IC-) in the External
-        Integrations table. Implement every port the design declares.
-      - Author a paired test for every design behaviour / use-case / endpoint; derive
-        the cases from the design's pre/post/invariant contracts and cite the spec id
-        (FR / BR / CN / DC / IC / US) from the design's Traceability section. Include tests
-        for the constraints — e.g. an audit record is emitted, a DC-restricted field is
-        NOT exposed on the public surface, an IC- projection round-trips.
-      - Do NOT add behaviour the design does not state, and do NOT omit any it does.
-        If the design looks wrong or incomplete, STOP and surface it (it is fixed in
-        design/analyze) — never compensate from the spec or from memory.
-      - This aggregate OWNS its files; never regenerate a file another feature owns.
-      - Where generated code depends on a design Assumption (DA-n) or Workaround
-        (WA-n), mark it with a comment citing that id so it is easy to revisit later.
+        dependency-policy and testing standards for HOW to structure, name and place
+        files WITHIN that subtree — the pass says WHAT to build; these say HOW.
+      - Realise the pass's "### Approach" and "### Changes" exactly, changing nothing
+        about WHAT they specify, and preserve every ubiquitous-language name verbatim.
+      - INTERFACES: where the pass's "### Interfaces" describes a published surface,
+        the entry in interfaces.md (in context) is the contract — match its route,
+        shape and semantics. Where the log and the pass disagree, the pass is the
+        newer word and the log entry it supersedes is named in it; if neither says
+        which, STOP and surface it rather than picking.
+      - COMPONENTS: where the pass depends on a framework component (e.g.
+        `IEmailService`, `IJobScheduler`), code against that component's ABSTRACTION /
+        port as the pass declares — do NOT hand-roll it. Installing the component into
+        the project (packages, provider wiring, config) is a SEPARATE step:
+        /appweaver add-component <Component>. If the port is not present yet, code to
+        it and note add-component as the prerequisite.
+      - ADRs are DECIDED — follow them. The pass may propose a superseding one; a
+        proposal is not yet ratified, so follow the pass and change nothing else.
+      - Author a paired test for every acceptance criterion in the story and every
+        behaviour the pass's "### Tests" section names, and cite the requirement id
+        ({{exercises_csv}}) each test exists for. Include the constraint tests the
+        pass names ({{constraints_csv}}) — e.g. an audit record is emitted, a
+        restricted field is NOT exposed on the public surface.
+      - Do NOT add behaviour the pass does not state, and do NOT omit any it does. If
+        the pass looks wrong or incomplete, STOP and surface it — it is fixed by
+        re-running /appweaver story-plan, never compensated for here from the spec or
+        from memory.
+      - This feature OWNS its files; never regenerate a file another feature owns.
+      {{stale_note}}
     outputs:
       - { name: files, from: "$.files" }
 
@@ -210,63 +433,146 @@ workflow:
     action: verify_context
     require_non_empty: files
     on_empty: stop
-    on_empty_message: "No files generated. Ensure /appweaver design produced a filled design.md (not the empty template) and passed analyze, then re-run."
-
-  # 3b. OKF knowledge + cross-references (deterministic, design-derived). Greenfield's
-  #     entry into the shared OKF bundle: author THIS aggregate's concept (its source_files
-  #     = the files just generated), then record its cross-slice edges — write a
-  #     Cross-References row into every SIBLING aggregate it uses (from design.md §1
-  #     References-by-id + its External integrations table), reconcile-on-write so a dropped
-  #     dependency self-heals and a used sibling with no concept yet is stubbed. Finally
-  #     author the concept's Overview prose (3c). This is enrichment downstream of a
-  #     successful generate — it never re-decides WHAT was built.
+    on_empty_message: "No files generated for story {{story}}. Check that design pass {{design_pass}} in {{design_doc}} actually describes changes (a pass whose '### Changes' section is empty has nothing to build), then re-run — or re-run /appweaver story-plan {{story}} to design the slice properly first."
+
+  # 8. OKF — MERGE, never replace. This run wrote ONE STORY's files; the feature's
+  #    other stories wrote the rest, and a replace would erase them the moment a second
+  #    story implements. --lane backend puts them in `source_files`, the service lane's
+  #    key, leaving `ui_source_files` for implement-ui.
+  #    Known limit: a file the slice DELETED stays in the list; concept-coverage reports
+  #    it as declared-but-missing drift rather than silently carrying it as real.
   - id: xref_concept
     action: execute_script
     script: { ref: xref }
     subcommand: concept-upsert
-    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{files}}", "--origin", "greenfield"]
+    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{files}}", "--merge", "--lane", "backend", "--origin", "greenfield"]
     outputs:
       - { name: okf_concept, from: "$.concept" }
 
+  # 8a. Cross-slice edges are a FEATURE property, not a story's: which sibling
+  #     aggregates this one references is stated by the feature plan's domain model,
+  #     and no single slice can answer it. So this reads backend-plan.md — the one
+  #     derived fact it takes from the plan — and reconciles on write, so a dropped
+  #     dependency self-heals out of the used aggregate's Cross-References. Skipped
+  #     with no plan on disk: there is then nothing to derive edges from.
   - id: xref_record
+    condition: "{{be_plan_exists}} == true"
     action: execute_script
+    on_error: continue
     script: { ref: xref }
     subcommand: record
-    args: ["--feature-dir", "{{feature_dir}}", "--design", "{{design_doc}}", "--origin", "greenfield"]
+    args: ["--feature-dir", "{{feature_dir}}", "--design", "{{be_plan}}", "--origin", "greenfield"]
     outputs:
       - { name: xref_wrote,      from: "$.wrote" }
       - { name: xref_edge_count, from: "$.edge_count" }
 
-  # 3c. The concept's Overview — the ONE part of the OKF concept a deterministic script
-  #     cannot produce (prose distilled from design.md §1). The model authors the text
-  #     only; concept-overview splices it into the `## Overview` section alone, so the
-  #     Cross-References rows other slices own are structurally out of reach.
+  # 8b. The concept's Overview — the one part a deterministic script cannot produce.
+  #     It describes the AGGREGATE, which is the feature plan's subject: distilling it
+  #     from one story's slice would name whatever that slice happened to touch. The
+  #     model authors prose only; concept-overview splices it into `## Overview` alone,
+  #     so the Cross-References rows other slices own are structurally out of reach.
+  #     build_context, not a step-level `context:`: the engine REPLACES the envelope on
+  #     build_context and only ADDS to it on a step-level list, so naming the plan alone
+  #     there would have left generation's whole payload — this story's slice included —
+  #     underneath a prompt that says "describe the whole aggregate, not one story".
+  - id: ctx_overview
+    condition: "{{be_plan_exists}} == true"
+    action: build_context
+    context:
+      - { path: "{{be_plan}}" }
   - id: okf_overview
+    condition: "{{be_plan_exists}} == true"
     action: agent_query
-    context: ["{{design_doc}}"]
     include_standards: false
     schema: { overview: "<2-4 sentences of prose>" }
     mock: { overview: "" }
     task: |
-      Write the OKF knowledge-concept Overview for the aggregate that design.md (in
-      context) describes. 2-4 sentences of PROSE, distilled from §1 Domain Model:
+      Write the OKF knowledge-concept Overview for the aggregate that the backend plan
+      (in context) describes. 2-4 sentences of PROSE, distilled from §1 Domain Model:
       - name the aggregate ROOT and what the aggregate IS;
-      - state the INVARIANTS it guards (from §1 / the design's business rules);
+      - state the INVARIANTS it guards;
       - state its TRANSACTION BOUNDARY — what it OWNS inside the boundary vs what it
         only REFERENCES by id.
       Plain prose only: no headings, no bullets, no code fences, no file paths, and no
       restating of the dependency edges (those live in the Depends-On / Cross-References
-      tables). Describe only what the design states — invent nothing.
+      tables). Describe only what the plan states — invent nothing, and describe the
+      whole aggregate rather than the one story that happens to be building now.
     outputs:
       - { name: okf_overview, from: "$.overview" }
-
   - id: okf_overview_write
+    condition: "{{be_plan_exists}} == true"
     action: execute_script
     script: { ref: xref }
     subcommand: concept-overview
     args: ["--feature-dir", "{{feature_dir}}", "--text", "{{okf_overview}}"]
 
-  # 4. Post-execution hooks.
+  # ═══════════════ ACCEPTANCE — the ONE place the spec is read ═════════════════
+  # Generation is design-only by contract; this is the check that the design was not
+  # the wrong design. READ-ONLY and REPORT-ONLY: it never edits code, never edits the
+  # pass, and never stops the run. A gap here means one of two documents is wrong, and
+  # which one is a human decision — the message names both routes.
+  - id: ctx_accept
+    action: build_context
+    vars:
+      story_id: "{{story}}"
+      exercises_csv: "{{exercises_csv}}"
+      constraints_csv: "{{constraints_csv}}"
+      files_csv: "{{files}}"
+    context:
+      - { path: "{{story_path}}" }    # the acceptance criteria
+      - { path: "{{spec_file}}" }     # the contract — the ONLY step in this workflow that reads it
+      - { path: "{{design_doc}}" }    # what was designed
+  - id: accept_check
+    action: agent_query
+    tools: Read                       # the generated files arrive as paths, not inlined
+    include_standards: false
+    schema: { ok: "<true|false>", gaps: "<one line per gap, or empty>" }
+    mock: { ok: "true", gaps: "" }
+    task: |
+      Story {{story_id}} was just implemented. Judge ONLY this: does the code that now
+      exists satisfy the requirements the story delivers, AS THE SPEC WORDS THEM?
+
+      In scope: {{exercises_csv}} (delivered) and {{constraints_csv}} (must hold).
+      Resolve each id's wording from spec.md in context — that wording, not the design's
+      restatement of it, is what the code is measured against.
+
+      Read the files this run wrote:
+          {{files_csv}}
+      plus anything they call that you need to follow. Do not modify a single file.
+
+      Report a gap ONLY where the code fails to deliver an in-scope id as the spec words
+      it, or breaks an in-scope constraint. These are NOT gaps, and reporting them is
+      noise that hides the real ones:
+      - a requirement no story has claimed yet, or one another story delivers;
+      - style, naming, structure or test-coverage opinions — other gates own those;
+      - anything the design pass deliberately deferred and named under its risks.
+
+      One line per gap: the id, what the spec requires, and what the code does instead.
+      Set ok=false only when you found at least one. If the SPEC and the DESIGN disagree
+      about an in-scope id, that IS a gap — say which document you believe is wrong and
+      why, because the two routes out of it are different commands.
+    outputs:
+      - { name: accept_ok,   from: "$.ok" }
+      - { name: accept_gaps, from: "$.gaps" }
+  - id: accept_notice
+    condition: "{{accept_ok}} != true"
+    action: verify_context
+    require_value: accept_ok
+    equals: "true"
+    on_mismatch: continue
+    on_mismatch_message: |
+      ACCEPTANCE — story {{story}} does not yet satisfy the spec wording of the ids it delivers:
+
+      {{accept_gaps}}
+
+      Nothing was changed to fix this: the code follows design pass {{design_pass}}, so a gap
+      here means either the design was wrong or the spec has moved. Route by which it is —
+      the design is wrong: /appweaver story-plan {{story}} (a new pass supersedes this one);
+      the spec is wrong: /appweaver sync-spec, then sync-stories, then story-plan.
+      Run /appweaver build either way — a design that is right and code that does not compile
+      is a third thing, and build is where that one surfaces.
+
+  # 9. Post-execution hooks.
   - id: resolve_post_hooks
     action: execute_script
     script: { ref: actions }
@@ -279,9 +585,12 @@ workflow:
     hooks_from_variable: after_hooks
 
 outputs:
-  feature_dir: "{{feature_dir}}"
-  design_doc: "{{design_doc}}"
+  story: "{{story}}"
+  built_from: "{{design_doc}} — design pass {{design_pass}} (designed against spec {{design_spec_version}}; spec now {{current_version}})"
+  requirements: "{{exercises_csv}}"
   files: "{{files}}"
-  okf_concept: "{{okf_concept}}"
-  xref_edge_count: "{{xref_edge_count}}"
-  next: "/appweaver build  (OKF concept authored at {{okf_concept}}; {{xref_edge_count}} cross-slice edge(s) recorded into sibling aggregates)"
+  lane: "{{lane_id}} → {{lane_source_path}}"
+  okf_concept: "{{okf_concept}} (this run's files MERGED into source_files; {{xref_edge_count}} cross-slice edge(s) recorded into sibling aggregates)"
+  acceptance: "ok={{accept_ok}} · gaps: {{accept_gaps}}"
+  stale_ids: "{{stale_csv}}"
+  next: "/appweaver build — it compiles every declared lane. Then /appweaver analyze-slice (spec ↔ code, through the design), and /appweaver implement-ui if this story has a UI design. The story stays OPEN until /appweaver close-story ratifies its ADRs, flips its interface entries live and archives the passes."