aw-spec-cli 0.1.26 → 0.1.28

package/assets/.appweaver/orchestrator/modules/foundation-lane.orch.yaml

@@ -0,0 +1,237 @@
+# =============================================================================
+# foundation-lane (orchestrator) — scaffold ONE declared lane
+#
+# Included by aw-spec-foundation once per lane kind — backend first, then frontend — with
+# that lane's fields passed through `with:`. It answers "what is this lane built from?"
+# and hands off:
+#
+#   1. Can the lane take a foundation — does it run its commands inside its lane root folder
+#      and keep its tests there? If not, it is reported and passed over. Then: does it
+#      already hold files? If so, ask to overwrite them; "no" skips the lane and nothing
+#      else is asked. Each lane is asked on its own.
+#   2. List what fits the lane: every pack and spec under foundations/<ecosystem>/ whose
+#      `# kind:` / `# profiles:` header admits this lane, then [manual spec] and [skip].
+#   3. Pick one. A fast-path name (`/appweaver foundation VerticalSlice App`) preselects
+#      its entry in whichever lane lists it.
+#   4. pack -> foundation-pack (unpack the verified bundle, as before)
+#      spec | manual spec -> foundation-spec (an agent builds the project from the spec)
+#      skip -> nothing is written.
+#
+# Every refusal in here and in the two route modules RETURNS rather than stops, so the
+# caller always reaches the next lane; the reason is in fl_status, which the caller
+# reports per lane at the end of the run.
+#
+# Inputs (via include `with:`):
+#   fl_kind, fl_lane_id, fl_profile, fl_title, fl_language, fl_ecosystem,
+#   fl_source_path, fl_test_path, fl_workdir, fl_build
+# Shared with the caller: USER_INPUT (the fast path) and `app` (asked once per run, the
+#   first time a lane needs it, and reused by the next lane).
+# Produces: fl_status, fl_route, fl_name, fl_spec_path, fl_files, and fl_overwrite ("yes"
+#   when the lane already had files and the operator agreed to overwrite them), which the
+#   two route modules read.
+# =============================================================================
+
+name: foundation-lane
+dialect: aw-spec.orchestrator/v1
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+workflow:
+
+  # 0. Vars are shared across the two includes; start this lane clean.
+  - id: fl_reset
+    action: set
+    vars:
+      fl_status: "not scaffolded"
+      fl_route: ""
+      fl_name: ""
+      fl_spec_file: ""
+      fl_spec_path: ""
+      fl_files: ""
+      fl_has_files: ""
+      fl_files_summary: ""
+      fl_self_contained: ""
+      fl_shape_reason: ""
+      fl_overwrite_answer: ""
+      fl_overwrite: ""
+      fl_overwrite_note: ""
+      fl_go: "true"
+      fl_spec_route: ""
+
+  - id: fl_has_root
+    action: verify_context
+    require_non_empty: fl_source_path
+    on_empty: return
+    message_var: fl_status
+    on_empty_message: "not scaffolded — lane `{{fl_lane_id}}` declares no lane root folder in .appweaver/stacks.json; re-run /appweaver select-stack and give it its lane root folder"
+
+  # 1. Does the lane already hold files? Any file in its lane root folder or test path counts,
+  #    whatever stack wrote it, and so do its build files where its commands run when that
+  #    is outside the lane (a .NET solution at the repo root). Asked BEFORE the pick list,
+  #    so "no" skips this lane with nothing else asked and the run moves on to the next one.
+  #    The first option is the non-interactive default, so an unattended run never
+  #    overwrites. The answer key carries the lane kind, so a scripted run answers each lane
+  #    on its own: --answer fl_overwrite_backend=yes --answer fl_overwrite_frontend=no.
+  - id: fl_files_check
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-lane-files
+    args: ["--source", "{{fl_source_path}}", "--test", "{{fl_test_path}}", "--workdir", "{{fl_workdir}}", "--profile", "{{fl_profile}}"]
+    outputs:
+      - { name: fl_has_files,      from: "$.has_files" }
+      - { name: fl_files_summary,  from: "$.summary" }
+      - { name: fl_self_contained, from: "$.self_contained" }
+      - { name: fl_shape_reason,   from: "$.shape_reason" }
+
+  # A foundation is a complete project that lands INSIDE the lane root folder — build files,
+  # source and tests — so the lane has to run its commands there and keep its tests there.
+  # A lane declared the classic way (code in src/, solution and tests/ at the repo root)
+  # suits existing code but would get a project its own build cannot find; it is reported
+  # here, before anything is asked, and the run moves on to the next lane.
+  - id: fl_shape_gate
+    action: verify_context
+    require_true: fl_self_contained
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not scaffolded — {{fl_shape_reason}}"
+
+  - id: fl_ask_overwrite
+    action: ask
+    condition: "{{fl_has_files}} == true"
+    prompt: >
+      {{fl_kind}} lane `{{fl_lane_id}}` ({{fl_profile}}) already has files — {{fl_files_summary}}.
+      Scaffolding it writes into these folders and replaces files with the same path; files
+      with other names stay, and nothing is deleted. Overwrite?
+    options: ["no — skip this lane", "yes — overwrite"]
+    answer_key: "fl_overwrite_{{fl_kind}}"
+    answer_var: fl_overwrite_answer
+
+  # The answer is free text from the launcher: the full option and a bare `yes` both count.
+  - id: fl_overwrite_option
+    action: set
+    condition: "{{fl_overwrite_answer}} == yes — overwrite"
+    vars: { fl_overwrite: "yes" }
+
+  - id: fl_overwrite_short
+    action: set
+    condition: "{{fl_overwrite_answer}} == yes"
+    vars: { fl_overwrite: "yes" }
+
+  - id: fl_overwrite_gate
+    action: verify_context
+    condition: "{{fl_has_files}} == true"
+    require_value: fl_overwrite
+    equals: "yes"
+    on_mismatch: return
+    message_var: fl_status
+    on_mismatch_message: "skipped — the lane already has files ({{fl_files_summary}}) and overwriting them was declined"
+
+  - id: fl_overwrite_noted
+    action: set
+    condition: "{{fl_overwrite}} == yes"
+    vars: { fl_overwrite_note: " It already has files, and you chose to overwrite them." }
+
+  # 2. What fits this lane.
+  - id: fl_list
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-list
+    args: ["--kind", "{{fl_kind}}", "--profile", "{{fl_profile}}", "--ecosystem", "{{fl_ecosystem}}", "--lane-id", "{{fl_lane_id}}", "--args", "{{USER_INPUT}}"]
+    outputs:
+      - { name: fl_options,   from: "$.options" }
+      - { name: fl_count,     from: "$.count" }
+      - { name: fl_all,       from: "$.all_foundations" }
+      - { name: fl_preselect, from: "$.preselect_option" }
+
+  # 3. Pick. There are always at least two options ([manual spec] and [skip]), so this
+  #    always asks unless the fast path named an entry this lane offers.
+  - id: fl_pick
+    action: user_select
+    prompt: >
+      {{fl_kind}} lane `{{fl_lane_id}}` — {{fl_title}} at {{fl_source_path}}.{{fl_overwrite_note}}
+      What should it be scaffolded from? A [pack] is a verified project unpacked as-is; a
+      [spec] describes a project the agent builds into the lane; [manual spec] lets you give
+      that description yourself; [skip] leaves the lane untouched.
+      ({{fl_count}} of the foundations shipped fit this lane; all of them: {{fl_all}})
+    options_from_variable: fl_options
+    preselect_from: fl_preselect
+    outputs:
+      - { name: fl_selection, from: selection }
+
+  - id: fl_choice
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-choice
+    args: ["--selection", "{{fl_selection}}", "--kind", "{{fl_kind}}", "--profile", "{{fl_profile}}", "--ecosystem", "{{fl_ecosystem}}"]
+    outputs:
+      - { name: fl_choice_ok,  from: "$.ok" }
+      - { name: fl_route,      from: "$.route" }
+      - { name: fl_name,       from: "$.name" }
+      - { name: fl_spec_file,  from: "$.file" }
+      - { name: fl_choice_msg, from: "$.reason" }
+
+  - id: fl_choice_gate
+    action: verify_context
+    require_true: fl_choice_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not scaffolded — {{fl_choice_msg}}"
+
+  - id: fl_skip
+    action: set
+    condition: "{{fl_route}} == skip"
+    vars: { fl_go: "" }
+
+  - id: fl_skip_gate
+    action: verify_context
+    require_true: fl_go
+    on_false: return
+    message_var: fl_status
+    on_false_message: "skipped — left as it is, by choice"
+
+  # 4. The project name — asked once per run, the first time a lane needs it, unless the
+  #    fast path gave it. The next lane reuses it.
+  - id: fl_ask_app
+    action: ask
+    condition: "{{app}} == "
+    prompt: >
+      Enter the project (application) name, e.g. AppWeaver.Health. A pack renames its
+      sentinel to it; a spec build names the project after it, in the form the stack uses.
+      It is asked once and used for every lane in this run.
+    answer_var: app_typed
+
+  - id: fl_app_from_typed
+    action: set
+    condition: "{{app}} == "
+    vars: { app: "{{app_typed}}" }
+
+  - id: fl_app_gate
+    action: verify_context
+    require_non_empty: app
+    on_empty: return
+    message_var: fl_status
+    on_empty_message: "not scaffolded — no project name was given"
+
+  # 5. Hand off. The engine has no OR, so the two spec routes set one flag.
+  - id: fl_route_spec
+    action: set
+    condition: "{{fl_route}} == spec"
+    vars: { fl_spec_route: "true" }
+
+  - id: fl_route_manual
+    action: set
+    condition: "{{fl_route}} == manual"
+    vars: { fl_spec_route: "true" }
+
+  - id: pack
+    action: include
+    condition: "{{fl_route}} == pack"
+    module: .appweaver/orchestrator/modules/foundation-pack.orch.yaml
+
+  - id: spec
+    action: include
+    condition: "{{fl_spec_route}} == true"
+    module: .appweaver/orchestrator/modules/foundation-spec.orch.yaml

package/assets/.appweaver/orchestrator/modules/foundation-pack.orch.yaml

@@ -0,0 +1,392 @@
+# =============================================================================
+# foundation-pack (orchestrator) — scaffold ONE lane by unpacking a foundation pack
+#
+# Included by foundation-lane when the operator picks a `[pack]` entry. Almost entirely
+# deterministic: locate the verified byte-for-byte bundle, confirm, dry-run for
+# collisions, unpack into the lane root folder exactly as packed with the sentinel renamed,
+# optionally add the reference sample on top, and check that no sentinel is left behind.
+#
+# Its LANE SETTINGS (<pack name>.lane.json beside the pack), when it has any, are recorded
+# on the lane once it is unpacked.
+#
+# Every file in a pack lands as packed, replacing a file already there — except the ones
+# its RULE FILE (<pack name>.rules.json beside the pack) says to merge. The model is used
+# ONLY for those merges: an `agent_author` (read-only generation, the ENGINE writes the
+# file) with include_standards: false and a two-file context — the file that was there
+# and the pack's version — following the rule's own instruction.
+#
+# Every refusal RETURNS rather than stops: the run carries on with the next lane, and the
+# reason lands in fl_status (message_var), which the caller reports per lane.
+#
+# Inputs (shared vars, set by foundation-lane):
+#   fl_name, app, fl_kind, fl_lane_id, fl_title, fl_language, fl_ecosystem,
+#   fl_source_path, fl_test_path, fl_overwrite
+# Produces: fl_status, fl_files (files written), and the fp_* details.
+# =============================================================================
+
+name: foundation-pack
+dialect: aw-spec.orchestrator/v1
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+workflow:
+
+  # 0. This module runs once per lane in the same run, and vars are shared — the second
+  #    lane must not inherit the first lane's overwrite answer or reference choice.
+  - id: fp_reset
+    action: set
+    vars:
+      fp_overwrite: "no"
+      fp_has_collisions: "false"
+      fp_want_reference: "no"
+      fp_has_reference: "false"
+      fp_merge_state: ".appweaver/orchestrator/.state/foundation-{{fl_lane_id}}.merge/"
+      fp_rules_ok: ""
+      fp_rules_reason: ""
+      fp_rules_file: ""
+      fp_merges: "[]"
+      fp_rules_note: ""
+      fp_ref_rules_ok: ""
+      fp_ref_rules_reason: ""
+      fp_ref_rules_file: ""
+      fp_ref_merges: "[]"
+      fp_ref_rules_note: ""
+      fp_ref_go: "no"
+      fp_ok: ""
+      fp_written: "0"
+      fp_tests_message: ""
+      fp_tests_note: ""
+      fp_ref_ok: ""
+      fp_ref_written: "0"
+      fp_ref_tests_message: ""
+      fp_ref_note: ""
+      fp_clean: ""
+      fp_residue: ""
+      fp_residue_note: "not checked"
+      fp_lane_found: "false"
+      fp_lane_file: ""
+      fp_lane_contract_run: ""
+      fp_lane_contract: ""
+      fp_lane_client: ""
+      fp_lane_recorded: ""
+      fp_lane_note: ""
+
+  # 1. Locate the bundle + its unpacker and read the (bounded) pack header: the sentinel,
+  #    the file count, and whether a Reference pack ships beside it.
+  - id: fp_locate
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-locate
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}"]
+    outputs:
+      - { name: fp_locate_ok,     from: "$.ok" }
+      - { name: fp_locate_msg,    from: "$.reason" }
+      - { name: fp_available,     from: "$.available" }
+      - { name: fp_sentinel,      from: "$.sentinel" }
+      - { name: fp_file_count,    from: "$.file_count" }
+      - { name: fp_has_reference, from: "$.has_reference" }
+
+  - id: fp_locate_gate
+    action: verify_context
+    require_true: fp_locate_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not scaffolded — {{fp_locate_msg}} (packs available: {{fp_available}})"
+
+  # 1b. The lane already had files and foundation-lane's overwrite question was answered
+  #     yes before the pick list: that answer stands, so the unpack overwrites and the
+  #     collision question below is not asked a second time.
+  - id: fp_overwrite_agreed
+    action: set
+    condition: "{{fl_overwrite}} == yes"
+    vars: { fp_overwrite: "yes" }
+
+  # 2. Confirm (checkpoint kind 'ask' under every strategy).
+  - id: fp_confirm
+    action: ask
+    prompt: |
+      Foundation: {{fl_name}} pack (sentinel {{fp_sentinel}}, {{fp_file_count}} files)
+      App name:   {{app}}
+      Lane:       {{fl_lane_id}} — {{fl_title}}, {{fl_language}} ({{fl_ecosystem}})
+      Folder:     {{fl_source_path}}     <- the pack unpacks here as packed: build files, source and tests
+      Tests:      {{fl_test_path}}
+      Overwrite:  {{fp_overwrite}}     <- yes: files the pack writes replace existing ones
+      The sentinel {{fp_sentinel}} is renamed to {{app}} in file contents and paths, as the
+      replacement contract in the pack's header describes. Proceed?
+    options: ["yes", "no"]
+    answer_var: fp_proceed
+
+  - id: fp_confirm_gate
+    action: verify_context
+    require_value: fp_proceed
+    equals: "yes"
+    on_mismatch: return
+    message_var: fl_status
+    on_mismatch_message: "not scaffolded — the {{fl_name}} pack was declined at the confirmation; nothing was written to {{fl_source_path}}"
+
+  # 3. Dry-run to surface collisions, then confirm overwrite if needed — only for a lane
+  #    that was empty: one that already had files was asked before the pick list (step 1b).
+  - id: fp_dry_run
+    action: execute_script
+    condition: "{{fl_overwrite}} != yes"
+    script: { ref: actions }
+    subcommand: foundation-unpack
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--dry-run"]
+    outputs:
+      - { name: fp_has_collisions, from: "$.has_collisions" }
+
+  - id: fp_ask_overwrite
+    action: ask
+    condition: "{{fp_has_collisions}} == true"
+    prompt: "Files the {{fl_name}} pack writes already exist under {{fl_source_path}}. Overwrite them?"
+    options: ["yes", "no"]
+    answer_var: fp_overwrite
+
+  - id: fp_overwrite_gate
+    action: verify_context
+    condition: "{{fp_has_collisions}} == true"
+    require_value: fp_overwrite
+    equals: "yes"
+    on_mismatch: return
+    message_var: fl_status
+    on_mismatch_message: "not scaffolded — files the {{fl_name}} pack writes already exist under {{fl_source_path}} and overwriting them was declined"
+
+  # 4. The pack's rule file: which of its files are merged with what the lane holds now.
+  #    Read before anything is written, so a broken rule file leaves the lane untouched;
+  #    the files to merge with are put aside under fp_merge_state.
+  - id: fp_rules
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-rules
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--state", "{{fp_merge_state}}"]
+    outputs:
+      - { name: fp_rules_ok,     from: "$.ok" }
+      - { name: fp_rules_reason, from: "$.reason" }
+      - { name: fp_rules_file,   from: "$.rules_file" }
+      - { name: fp_merges,       from: "$.merges" }
+      - { name: fp_rules_note,   from: "$.note" }
+
+  - id: fp_rules_gate
+    action: verify_context
+    require_true: fp_rules_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not scaffolded — {{fp_rules_reason}}; nothing was written to {{fl_source_path}}"
+
+  # 5. Unpack for real, and check it worked: an unpacker that refuses (existing files, a
+  #    bad name) exits non-zero with 0 files written, and reporting that as a scaffold is
+  #    how a lane with no project gets as far as implement.
+  - id: fp_unpack
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-unpack
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--test-path", "{{fl_test_path}}", "--force", "{{fp_overwrite}}"]
+    outputs:
+      - { name: fp_ok,            from: "$.ok" }
+      - { name: fp_written,       from: "$.written" }
+      - { name: fp_tests_message, from: "$.tests_message" }
+      - { name: fp_unpack_out,    from: "$.stdout" }
+
+  - id: fp_unpack_gate
+    action: verify_context
+    require_true: fp_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "NOT scaffolded — the {{fl_name}} unpacker failed and wrote {{fp_written}} file(s). Its output ends: {{fp_unpack_out}}"
+
+  # 5b. The pack's LANE SETTINGS (<pack name>.lane.json beside it): what only the pack
+  #     knows about the project it scaffolds — chiefly how its service is started on its
+  #     own so implement can export the API document. Recorded on the lane with lane-set;
+  #     a key the file leaves empty is not touched, and a pack with no such file leaves
+  #     the lane on its stack profile's values.
+  - id: fp_lane_settings
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: foundation-pack-lane
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}"]
+    outputs:
+      - { name: fp_lane_found,        from: "$.found" }
+      - { name: fp_lane_file,         from: "$.file" }
+      - { name: fp_lane_contract_run, from: "$.contract_run" }
+      - { name: fp_lane_contract,     from: "$.contract" }
+      - { name: fp_lane_client,       from: "$.client" }
+
+  - id: fp_lane_record
+    action: execute_script
+    condition: "{{fp_lane_found}} == true"
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-set
+    args: ["--id", "{{fl_lane_id}}", "--set", "contract_run={{fp_lane_contract_run}}", "--set", "contract={{fp_lane_contract}}", "--set", "client={{fp_lane_client}}"]
+    outputs:
+      - { name: fp_lane_recorded, from: "$.ok" }
+
+  - id: fp_lane_noted
+    action: set
+    condition: "{{fp_lane_recorded}} == true"
+    vars: { fp_lane_note: "; the pack's API-export settings ({{fp_lane_file}}) recorded on the {{fl_lane_id}} lane" }
+
+  # 6. The merges the rule file asks for: the file that was there (put aside) and the
+  #    pack's version (now on disk) become one, as the rule's instruction says.
+  - id: fp_merge
+    action: loop
+    over: "{{fp_merges}}"
+    as: m
+    steps:
+      - id: fp_merge_file
+        action: agent_author
+        context: ["{{m.existing}}", "{{m.target}}"]
+        include_standards: false
+        task: |
+          Merge two versions of {{m.target}} into one file.
+            EXISTING  {{m.existing}} — the file as it was in the lane before the {{fl_name}} pack was unpacked
+            INCOMING  {{m.target}} — the file as the pack ships it, with {{fp_sentinel}} renamed to {{app}}
+          The pack's rule file ({{fp_rules_file}}) says how, in its rule for {{m.rule}}:
+          {{m.instruction}}
+          Change nothing that instruction does not ask for.
+        output_target: { type: file, path: "{{m.target}}" }
+
+  - id: fp_rules_done
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-rules-done
+    args: ["--state", "{{fp_merge_state}}"]
+
+  # 7. Optional reference sample — offered only when the pack ships one. It goes on top
+  #    of the base project the same way: its own rule file, the unpack, its merges.
+  - id: fp_ask_reference
+    action: ask
+    condition: "{{fp_has_reference}} == true"
+    prompt: "The {{fl_name}} foundation also ships a reference sample ({{fl_name}}.Reference.pack.txt): worked example code unpacked on top of the base project. Include it?"
+    options: ["yes", "no"]
+    answer_var: fp_want_reference
+
+  - id: fp_ref_rules
+    action: execute_script
+    condition: "{{fp_want_reference}} == yes"
+    script: { ref: actions }
+    subcommand: foundation-rules
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--reference", "--state", "{{fp_merge_state}}"]
+    outputs:
+      - { name: fp_ref_rules_ok,     from: "$.ok" }
+      - { name: fp_ref_rules_reason, from: "$.reason" }
+      - { name: fp_ref_rules_file,   from: "$.rules_file" }
+      - { name: fp_ref_merges,       from: "$.merges" }
+      - { name: fp_ref_rules_note,   from: "$.note" }
+
+  # A broken rule file keeps the sample out but leaves the base project in place, so this
+  # reports and carries on rather than returning.
+  - id: fp_ref_rules_gate
+    action: verify_context
+    condition: "{{fp_want_reference}} == yes"
+    require_true: fp_ref_rules_ok
+    on_false: continue
+    message_var: fp_ref_note
+    on_false_message: "; the reference sample was NOT added — {{fp_ref_rules_reason}}"
+
+  - id: fp_ref_go
+    action: set
+    condition: "{{fp_ref_rules_ok}} == true"
+    vars: { fp_ref_go: "yes" }
+
+  - id: fp_reference_unpack
+    action: execute_script
+    condition: "{{fp_ref_go}} == yes"
+    script: { ref: actions }
+    subcommand: foundation-unpack
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--test-path", "{{fl_test_path}}", "--reference"]
+    outputs:
+      - { name: fp_ref_ok,            from: "$.ok" }
+      - { name: fp_ref_written,       from: "$.written" }
+      - { name: fp_ref_tests_message, from: "$.tests_message" }
+      - { name: fp_ref_out,           from: "$.stdout" }
+
+  # A failed reference sample does not undo the base project, so this reports and carries
+  # on to the residue check rather than returning.
+  - id: fp_reference_gate
+    action: verify_context
+    condition: "{{fp_ref_go}} == yes"
+    require_true: fp_ref_ok
+    on_false: continue
+    message_var: fp_ref_note
+    on_false_message: "; the reference sample FAILED to unpack ({{fp_ref_out}})"
+
+  - id: fp_reference_done
+    action: set
+    condition: "{{fp_ref_ok}} == true"
+    vars: { fp_ref_note: "; reference sample added ({{fp_ref_written}} file(s))" }
+
+  # The sample's own test tree is lifted onto the lane's test path like the base pack's;
+  # say what happened to it, or the lane line reports only the base pack's tests.
+  - id: fp_reference_tests_noted
+    action: set
+    condition: "{{fp_ref_tests_message}} != "
+    vars: { fp_ref_note: "{{fp_ref_note}} — its tests: {{fp_ref_tests_message}}" }
+
+  # The sample's merges: what the base project (or the lane before it) had, and the
+  # sample's version, become one as the sample's rule file says.
+  - id: fp_ref_merge
+    action: loop
+    condition: "{{fp_ref_ok}} == true"
+    over: "{{fp_ref_merges}}"
+    as: m
+    steps:
+      - id: fp_ref_merge_file
+        action: agent_author
+        context: ["{{m.existing}}", "{{m.target}}"]
+        include_standards: false
+        task: |
+          Merge two versions of {{m.target}} into one file.
+            EXISTING  {{m.existing}} — the file as it was in the lane before the {{fl_name}} reference sample was unpacked
+            INCOMING  {{m.target}} — the file as the reference sample ships it, with {{fp_sentinel}} renamed to {{app}}
+          The sample's rule file ({{fp_ref_rules_file}}) says how, in its rule for {{m.rule}}:
+          {{m.instruction}}
+          Change nothing that instruction does not ask for.
+        output_target: { type: file, path: "{{m.target}}" }
+
+  - id: fp_ref_merged_noted
+    action: set
+    condition: "{{fp_ref_ok}} == true"
+    vars: { fp_ref_note: "{{fp_ref_note}}{{fp_ref_rules_note}}" }
+
+  - id: fp_ref_rules_done
+    action: execute_script
+    condition: "{{fp_ref_go}} == yes"
+    script: { ref: actions }
+    subcommand: foundation-rules-done
+    args: ["--state", "{{fp_merge_state}}"]
+
+  # 8. Verify — sentinel residue must be zero in the generated tree.
+  - id: fp_verify
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-verify
+    args: ["--out", "{{fl_source_path}}", "--sentinel", "{{fp_sentinel}}"]
+    outputs:
+      - { name: fp_clean,   from: "$.clean" }
+      - { name: fp_residue, from: "$.residue" }
+
+  - id: fp_residue_clean
+    action: set
+    condition: "{{fp_clean}} == true"
+    vars: { fp_residue_note: "no sentinel left" }
+
+  - id: fp_residue_found
+    action: set
+    condition: "{{fp_clean}} == false"
+    vars: { fp_residue_note: "SENTINEL {{fp_sentinel}} STILL IN {{fp_residue}}" }
+
+  - id: fp_tests_noted
+    action: set
+    condition: "{{fp_tests_message}} != "
+    vars: { fp_tests_note: "; {{fp_tests_message}}" }
+
+  - id: fp_done
+    action: set
+    vars:
+      fl_files: "{{fp_written}}"
+      fl_status: "scaffolded from the {{fl_name}} pack — {{fp_written}} file(s) into {{fl_source_path}}{{fp_tests_note}}{{fp_rules_note}}{{fp_ref_note}}{{fp_lane_note}}; {{fp_residue_note}}"