aw-spec-cli 0.1.26 → 0.1.27

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

@@ -0,0 +1,381 @@
+# =============================================================================
+# foundation-spec (orchestrator) — build ONE lane's project from a spec
+#
+# Included by foundation-lane when the operator picks a `[spec]` entry (a bundle's
+# *.spec.txt) or `[manual spec]` (a file path or text they give at the prompt). Where a
+# pack is a verified project unpacked byte-for-byte, a spec DESCRIBES the project and an
+# agent builds it in the lane — so the three things a pack guarantees by construction are
+# made explicit here instead:
+#
+#   WHERE   the whole project — build files, source and tests — goes inside the lane
+#           root folder, the way a pack holds it, and the agent may write nothing outside it.
+#           That is checked, not trusted: the repo is recorded before the build and
+#           compared after it, and a build that touched anything outside the lane root
+#           folder is not accepted, with what it created there removed again.
+#           foundation-lane only gets here for a lane that runs its commands in that
+#           folder and keeps its tests there, so the project builds where it is created.
+#   HOW     the technical rules mapped for this command (`## /aw-spec-foundation-backend`
+#           or `## /aw-spec-foundation-frontend` in the active project's
+#           tech-rule-bindings.md) load as standards through tech-select, so the scaffold
+#           agrees with the rules plan and implement apply to the same lane later.
+#   PROOF   the lane must hold a project of its ecosystem afterwards (the check implement
+#           gates on), and its own build command can be run on it.
+#
+# The spec actually used is copied to .appweaver/foundation/<lane>.spec.md — the record of
+# what the project was built from.
+#
+# Every refusal RETURNS rather than stops, with the reason in fl_status, so the run
+# carries on with the next lane.
+#
+# Inputs (shared vars, set by foundation-lane):
+#   fl_route (spec | manual), fl_spec_file (the bundle spec, route spec), fl_overwrite,
+#   fl_files_summary, app, fl_kind, fl_lane_id, fl_title, fl_language, fl_profile,
+#   fl_ecosystem, fl_source_path, fl_test_path, fl_workdir, fl_build
+# Produces: fl_status, fl_spec_path, fl_files, and the fs_* details.
+# =============================================================================
+
+name: foundation-spec
+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. Shared vars: the second lane must not read the first lane's answers.
+  - id: fs_reset
+    action: set
+    vars:
+      fs_spec_input: ""
+      fs_overwrite_how: ""
+      fs_existing_note: "The lane root folder is empty."
+      fs_ok: ""
+      fs_spec_path: ""
+      fs_source: ""
+      fs_title: ""
+      fs_rules_ack: ""
+      fs_rules_why: ""
+      fs_rules_line: "none"
+      fs_proceed: ""
+      fs_snapshot_path: ""
+      fs_files: []
+      fs_summary: ""
+      fs_inside_only: ""
+      fs_outside_summary: ""
+      fs_found: ""
+      fs_build_ack: ""
+      fs_build_ok: ""
+      fs_build_note: "build not run — /appweaver build compiles it and repairs compile errors"
+
+  # 1. A lane that already had files reaches this module only when the operator agreed, in
+  #    foundation-lane, to overwrite them. The agent is told so, with what that means for
+  #    the lane's kind: a backend generator needs its overwrite flag; a frontend generator
+  #    refuses a non-empty folder outright and leaves node_modules out of step with the new
+  #    package.json. The engine has no AND, so the kind's text is chosen first and only
+  #    used when the lane is being overwritten.
+  - id: fs_overwrite_backend
+    action: set
+    condition: "{{fl_kind}} == backend"
+    vars:
+      fs_overwrite_how: >-
+        If a generator refuses to write over existing files (for example `dotnet new`
+        without `--force`), use that generator's own overwrite flag.
+
+  - id: fs_overwrite_frontend
+    action: set
+    condition: "{{fl_kind}} == frontend"
+    vars:
+      fs_overwrite_how: >-
+        Scaffolding tools that refuse a non-empty directory (create-next-app, npm create
+        vite, ng new) must run in a temporary directory OUTSIDE the repository — the only
+        place outside the lane root folder you may write — with the result copied into
+        {{fl_source_path}} and the temporary directory removed afterwards; or write the
+        files directly. Then reinstall the dependencies, so node_modules matches the new
+        package.json.
+
+  - id: fs_overwrite_noted
+    action: set
+    condition: "{{fl_overwrite}} == yes"
+    vars:
+      fs_existing_note: >-
+        THE LANE ALREADY HOLDS FILES ({{fl_files_summary}}) and the operator agreed to
+        overwrite them. Replace a file only where the project you build needs that path;
+        leave every other file where it is, and delete nothing. {{fs_overwrite_how}}
+
+  # 2. The spec. A bundle spec is already named; a manual one is asked for here.
+  - id: fs_ask_spec
+    action: ask
+    condition: "{{fl_route}} == manual"
+    prompt: >
+      Give the spec for the {{fl_kind}} project in lane `{{fl_lane_id}}` ({{fl_title}}):
+      either the path of a file that holds it (e.g. docs/{{fl_kind}}-foundation.md), or the
+      spec text itself — what to create, with which tools and packages, the folder layout,
+      and the starter files. foundations/foundation.spec.template.txt shows the shape.
+    answer_var: fs_spec_input
+
+  - id: fs_capture_bundle
+    action: execute_script
+    condition: "{{fl_route}} == spec"
+    script: { ref: actions }
+    subcommand: foundation-spec-capture
+    args: ["--lane", "{{fl_lane_id}}", "--kind", "{{fl_kind}}", "--file", "{{fl_spec_file}}"]
+    outputs:
+      - { name: fs_ok,        from: "$.ok" }
+      - { name: fs_spec_path, from: "$.spec_path" }
+      - { name: fs_source,    from: "$.source" }
+      - { name: fs_title,     from: "$.title" }
+      - { name: fs_reason,    from: "$.reason" }
+
+  - id: fs_capture_manual
+    action: execute_script
+    condition: "{{fl_route}} == manual"
+    script: { ref: actions }
+    subcommand: foundation-spec-capture
+    args: ["--lane", "{{fl_lane_id}}", "--kind", "{{fl_kind}}", "--input", "{{fs_spec_input}}"]
+    outputs:
+      - { name: fs_ok,        from: "$.ok" }
+      - { name: fs_spec_path, from: "$.spec_path" }
+      - { name: fs_source,    from: "$.source" }
+      - { name: fs_title,     from: "$.title" }
+      - { name: fs_reason,    from: "$.reason" }
+
+  - id: fs_capture_gate
+    action: verify_context
+    require_true: fs_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not built — {{fs_reason}}"
+
+  # 3. The technical rules mapped for this command, loaded as standards. `replace` resets
+  #    the set to the workflow's seed first, so the frontend lane is never handed the
+  #    backend lane's rules. tg_mode/tg_subset are cleared because tech-select only asks
+  #    when the map has candidates — a stale answer from the other lane would otherwise
+  #    load that lane's subset here.
+  - id: fs_rules
+    action: include
+    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
+    with:
+      command: "aw-spec-foundation-{{fl_kind}}"
+      replace: "true"
+      tg_mode: ""
+      tg_subset: []
+
+  - id: fs_rules_why_project
+    action: set
+    condition: "{{tech_domain}} == "
+    vars: { fs_rules_why: "no project is named in .appweaver/domain.json — run /appweaver select-domain, or set \"domain\" to a folder under guardrails/ (project-specific by default)" }
+
+  - id: fs_rules_why_heading
+    action: set
+    condition: "{{tech_domain}} != "
+    vars: { fs_rules_why: "guardrails/{{tech_domain}}/tech-rule-bindings.md maps no file that exists under `## /aw-spec-foundation-{{fl_kind}}`" }
+
+  - id: fs_no_rules_ask
+    action: ask
+    condition: "{{tg_candidates}} == []"
+    prompt: "No technical rules apply to this build: {{fs_rules_why}}. Without them the agent builds from the spec alone, and the project may not follow the rules plan and implement apply to this lane later. Continue?"
+    options: ["continue without them", "stop — leave this lane"]
+    answer_var: fs_rules_ack
+
+  - id: fs_no_rules_gate
+    action: verify_context
+    condition: "{{tg_candidates}} == []"
+    require_value: fs_rules_ack
+    equals: "continue without them"
+    on_mismatch: return
+    message_var: fl_status
+    on_mismatch_message: "not built — no technical rules apply ({{fs_rules_why}}); spec kept at {{fs_spec_path}}"
+
+  - id: fs_rules_line_none
+    action: set
+    condition: "{{tg_candidates}} == []"
+    vars: { fs_rules_line: "none — {{fs_rules_why}}" }
+
+  - id: fs_rules_line_all
+    action: set
+    condition: "{{tg_mode}} == all"
+    vars: { fs_rules_line: "{{tg_candidates}}" }
+
+  - id: fs_rules_line_subset
+    action: set
+    condition: "{{tg_mode}} == subset"
+    vars: { fs_rules_line: "{{tg_subset}}" }
+
+  - id: fs_rules_line_declined
+    action: set
+    condition: "{{tg_mode}} == none"
+    vars: { fs_rules_line: "none — declined at the selection" }
+
+  # 4. Confirm the build plan.
+  - id: fs_confirm
+    action: ask
+    prompt: |
+      Build the {{fl_kind}} lane from a spec
+      Spec:      {{fs_spec_path}}  (from {{fs_source}}: {{fs_title}})
+      App name:  {{app}}
+      Lane:      {{fl_lane_id}} — {{fl_title}}, {{fl_language}}
+      Folder:    {{fl_source_path}}     <- the whole project: build files, source and tests
+      Tests:     {{fl_test_path}}
+      Commands:  `{{fl_build}}` runs in {{fl_workdir}}
+      Rules:     {{fs_rules_line}}
+      The agent follows the spec with the stack's own tooling, and writes nothing outside
+      these paths. Proceed?
+    options: ["yes", "no"]
+    answer_var: fs_proceed
+
+  - id: fs_confirm_gate
+    action: verify_context
+    require_value: fs_proceed
+    equals: "yes"
+    on_mismatch: return
+    message_var: fl_status
+    on_mismatch_message: "not built — declined at the confirmation; the spec is kept at {{fs_spec_path}}"
+
+  # 5. Build it. agent_generate: the agent has write tools and Bash, so it can run the
+  #    stack's scaffolding CLI. The spec reaches it as context; the mapped rules are
+  #    already in the standards. The repo is recorded first, so what the build does outside
+  #    the lane root folder can be found afterwards (6).
+  - id: fs_snapshot
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-snapshot
+    args: ["--out", ".appweaver/orchestrator/.state/foundation-{{fl_lane_id}}.snapshot.json"]
+    outputs:
+      - { name: fs_snapshot_path, from: "$.snapshot" }
+
+  - id: fs_generate
+    action: agent_generate
+    context: ["{{fs_spec_path}}"]
+    task: |
+      Create the base project for the {{fl_kind}} lane `{{fl_lane_id}}` — {{fl_title}}
+      ({{fl_language}}, stack profile `{{fl_profile}}`) — exactly as the spec in
+      {{fs_spec_path}} (in your context) describes. Name it after `{{app}}`, in the form
+      this stack uses for a project name.
+
+      WHERE YOU MAY WRITE — {{fl_source_path}}, the lane root folder, and nothing else, ever.
+      The WHOLE project goes inside it, complete: its build files (solution, workspace or
+      package manifest, build props, wrapper scripts), its source, and its tests — the
+      tests at {{fl_test_path}}, inside the same folder. Create the folder if absent. The
+      lane's commands run in that folder (`{{fl_build}}` runs in {{fl_workdir}}), so
+      nothing the build needs may sit outside it. Never write under .appweaver/,
+      guardrails/, foundations/ or specs/, at the repository root, or into another lane
+      root folder. This is checked when you finish: if anything outside the lane root
+      folder was created, changed or deleted, the lane is not accepted and what you
+      created there is removed.
+
+      WHAT IS THERE ALREADY: {{fs_existing_note}}
+
+      HOW:
+        - Follow the spec. Where it is silent, follow the technical rules in your standards;
+          where the spec and a rule disagree, follow the spec and name the conflict in your
+          summary.
+        - Where the spec names a scaffolding tool (dotnet new, npm create, mvn archetype,
+          …), run it so its output lands in the lane root folder itself — not a new folder
+          inside or beside it.
+        - This is the lane's BASE project. Business features are generated later by
+          /appweaver implement from the plans, so add none the spec does not ask for.
+        - The project must build with `{{fl_build}}` run in {{fl_workdir}}. Restore or
+          install what that needs; run the build once if you can and fix what it reports.
+        - Do not commit, push, or change git configuration.
+
+      List every file you created or changed in `files` (paths relative to the repository
+      root; for a tool that generated many files, list the manifest and entry points).
+    outputs:
+      - { name: fs_files,   from: "$.files" }
+      - { name: fs_summary, from: "$.summary" }
+
+  # 6. Did the build stay inside its lane root folder? Compared with the snapshot: anything
+  #    created, changed or deleted elsewhere — the repository root, another lane, the kit's
+  #    own folders — and the lane is not accepted. What the build created out there is
+  #    removed again; what it changed or deleted is listed, since there is no copy to put
+  #    back. Checked before anything else, so a build that wrote nothing in the lane still
+  #    has its stray files found.
+  - id: fs_outside
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-outside
+    args: ["--snapshot", "{{fs_snapshot_path}}", "--lane", "{{fl_source_path}}", "--undo"]
+    outputs:
+      - { name: fs_inside_only,     from: "$.clean" }
+      - { name: fs_outside_summary, from: "$.summary" }
+
+  - id: fs_outside_gate
+    action: verify_context
+    require_true: fs_inside_only
+    on_false: return
+    message_var: fl_status
+    on_false_message: "NOT accepted — the spec build wrote outside its lane root folder {{fl_source_path}}: {{fs_outside_summary}}. The spec is kept at {{fs_spec_path}}"
+
+  - id: fs_files_gate
+    action: verify_context
+    require_non_empty: fs_files
+    on_empty: return
+    message_var: fl_status
+    on_empty_message: "NOT built — the spec build reported no file that exists on disk; the spec is kept at {{fs_spec_path}}"
+
+  # 6. Proof: a project of this lane's ecosystem now sits INSIDE the lane — the same
+  #    check implement gates on. A repo-scope hit (another lane's manifest) does not count.
+  - id: fs_detect
+    action: execute_script
+    script: { ref: actions }
+    subcommand: detect-project
+    args: ["--root", "{{fl_source_path}}", "--ecosystem", "{{fl_ecosystem}}"]
+    outputs:
+      - { name: fs_scope,     from: "$.scope" }
+      - { name: fs_eco_match, from: "$.ecosystem_match" }
+      - { name: fs_markers,   from: "$.markers" }
+
+  - id: fs_found_in_lane
+    action: set
+    condition: "{{fs_scope}} == lane"
+    vars: { fs_found: "true" }
+
+  - id: fs_found_wrong_eco
+    action: set
+    condition: "{{fs_eco_match}} == false"
+    vars: { fs_found: "" }
+
+  - id: fs_found_gate
+    action: verify_context
+    require_true: fs_found
+    on_false: return
+    message_var: fl_status
+    on_false_message: "NOT usable — the spec build ran ({{fs_summary}}) but no {{fl_ecosystem}} project manifest is under {{fl_source_path}} (searched at scope `{{fs_scope}}`, found {{fs_markers}}); implement will skip this lane until one is there. The spec is kept at {{fs_spec_path}}"
+
+  # 7. Optionally run the lane's own build on it. It may need the network (restore /
+  #    install), which is why it is asked rather than assumed.
+  - id: fs_ask_build
+    action: ask
+    prompt: "Run this lane's build now to confirm the project compiles — `{{fl_build}}` in {{fl_workdir}}? It may download packages."
+    options: ["yes — build it now", "no — I'll build later"]
+    answer_var: fs_build_ack
+
+  - id: fs_build
+    action: execute_script
+    condition: "{{fs_build_ack}} == yes — build it now"
+    on_error: continue
+    script: { ref: actions }
+    subcommand: build-compile
+    args: ["--kind", "{{fl_kind}}"]
+    outputs:
+      - { name: fs_build_ok,   from: "$.ok" }
+      - { name: fs_build_tail, from: "$.failing_excerpt" }
+
+  - id: fs_build_passed
+    action: set
+    condition: "{{fs_build_ok}} == true"
+    vars: { fs_build_note: "build passed (`{{fl_build}}`)" }
+
+  - id: fs_build_failed
+    action: set
+    condition: "{{fs_build_ok}} == false"
+    vars: { fs_build_note: "build FAILED — run /appweaver build, which repairs compile errors: {{fs_build_tail}}" }
+
+  - id: fs_done
+    action: set
+    vars:
+      fl_spec_path: "{{fs_spec_path}}"
+      fl_files: "{{fs_files}}"
+      fl_status: "built from the spec in {{fs_spec_path}} (from {{fs_source}}) into {{fl_source_path}} — {{fs_summary}}; {{fs_build_note}}"

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

@@ -1,12 +1,12 @@
 # =============================================================================
-# lane-gate (orchestrator) — shared LANE + SOURCE PATH gate
+# lane-gate (orchestrator) — shared LANE + LANE ROOT FOLDER gate
 #
 # Included by every phase that reads or writes a lane's subtree. It answers one
 # question before that phase starts doing work:
 #
-#     is there a lane of the kind I need, and is its source path really there?
+#     is there a lane of the kind I need, and is its lane root folder really there?
 #
-# WHY A GATE AND NOT A FALLBACK. A phase that cannot find a source path has two
+# WHY A GATE AND NOT A FALLBACK. A phase that cannot find a lane root folder has two
 # options: guess, or stop. Guessing is what the kit did before the lane model —
 # `build` sniffed for a .sln, `run-migrate` hardcoded `src/`, and `implement` let
 # the model decide where files should go. Each of those is right on the layout the
@@ -27,7 +27,7 @@
 #              needs a declaration to work from but no particular kind of one — `build`
 #              compiles every declared lane, so a frontend-only project is as buildable
 #              as a backend-only one. It narrows nothing else: no lane declared at all, a
-#              lane with no source path, a source path that is not on disk and two lanes
+#              lane with no lane root folder, a lane root folder that is not on disk and two lanes
 #              claiming overlapping subtrees all still stop the run. The required kind's
 #              fields below then bind from the backend block, which an empty-require
 #              caller reads none of.

package/assets/.appweaver/orchestrator/modules/tech-select.orch.yaml

@@ -2,10 +2,10 @@
 # tech-select (orchestrator) — shared TECHNICAL rule-file selection module
 #
 # The technical counterpart of domain-select. Where domain-select loads the
-# per-command DOMAIN rule files from guardrails/projects/<project>/domain-rule-bindings.md,
+# per-command DOMAIN rule files from guardrails/<project>/domain-rule-bindings.md,
 # this module loads the per-command TECHNICAL rule files — the project's mapped technical rules and
 # the worked examples/ samples that go with them — from
-#   guardrails/projects/<project>/tech-rule-bindings.md
+#   guardrails/<project>/tech-rule-bindings.md
 # Included (via `action: include`) by every technical-rule consumer so the set is
 # CONFIGURATION, not code — tune the map, not the workflow.
 #
@@ -87,7 +87,7 @@ workflow:
     on_mismatch_message: >
       Stopped before loading technical rules from {{tg_mismatched}} into a
       {{tg_declared_stacks}} repository. Point the `## /` headings in
-      guardrails/projects/{{tech_domain}}/tech-rule-bindings.md at a corpus for this
+      guardrails/{{tech_domain}}/tech-rule-bindings.md at a corpus for this
       stack, or write the corpus segment of the path as a stack PLACEHOLDER (see the
       header of resolve-tech) so one map resolves from .appweaver/stacks.json and serves
       every stack this project declares. A corpus