aw-spec-cli 0.1.3 → 0.1.5

package/assets/.aw-spec/orchestrator/workflows/aw-spec-analyze-slice.orch.yaml

@@ -0,0 +1,425 @@
+# =============================================================================
+# aw-spec-analyze-slice (orchestrator) — the design↔code conformance GATE
+#
+# The second of the two discrete conformance gates on the forward path, and the
+# sibling of analyze-design:
+#   analyze-design  gates spec ↔ design   — STATIC,  before implement
+#   analyze-slice   gates design ↔ slice  — DYNAMIC, after  build
+# "Slice" is the unit under analysis: the aggregate's code, its paired tests, and
+# its OKF knowledge concept. Three passes over it —
+#   1. BEHAVIOUR   run the tests (paired to the spec's acceptance criteria by the
+#                  design docs); on red, fix up to 3×.
+#   2. CONFORMANCE check the code against the domain gate overlays (validate-only).
+#   3. KNOWLEDGE   refresh + review the slice's OKF concept (advisory).
+# Every fix made here is recorded in that concept, which is also where the slice's
+# file list is READ from (2.3.0 — `aw-xref concept-paths`, replacing the retired
+# `design-paths` scan for ```lang path=… fences that the tech-agnostic design.md no
+# longer carries; the paired `design-reconcile` write-back is retired with it, its job
+# already done by the concept-upsert --merge steps in pass 3).
+#
+# TWO POSITIONS, one gate — and in BOTH the master spec.md is the whole truth:
+#   BOOTSTRAP  implement → build → analyze-slice → run
+#   CHANGE     implement-delta → build → finalize-delta → analyze-slice → close-delta
+# On the CHANGE path this gate deliberately runs AFTER finalize-delta, which has already
+# merged the delta into spec.md + design.md — so the master carries the change and needs
+# no delta-awareness here. It runs BEFORE close-delta, so the change is still OPEN: a red
+# result is recoverable ("fix and re-run"), not a defect on an already-shipped version.
+# The only thing this gate reads the open change for is where to send you next.
+#
+# Launch:  /aw-spec-orch analyze-slice [strategy]
+# Prereq:  /aw-spec-orch build   (compiled code for the active feature).
+# =============================================================================
+
+name: aw-spec-analyze-slice
+description: The design↔code conformance gate — run the slice's tests against its acceptance criteria, check the code against the domain gate overlays, verify the change did not break any referring aggregate (the OKF referrer blast radius) and write a triage report before stopping if it did, refresh + review its OKF concept, and record every fix in it. Sits after finalize-delta on the change path, so the master spec it scores against already carries the change, and before close-delta, so a red gate leaves the change open and recoverable.
+version: 2.3.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+scripts:
+  actions:
+    sh:  .aw-spec/scripts/bash/aw-spec-actions.sh
+    ps1: .aw-spec/scripts/powershell/aw-spec-actions.ps1
+  xref:
+    sh:  .aw-spec/scripts/bash/aw-xref.sh
+    ps1: .aw-spec/scripts/powershell/aw-xref.ps1
+
+# No hardcoded technical standards seed. The technical rule files the code/conformance
+# passes check against (testing + coding-standards) are now CONFIGURATION, loaded per-
+# command from docs/domainspecs/<domain>/commandtechrulemap.md under "## /aw-spec-analyze-slice"
+# by the tech-select module (see the tech_select step below). The DOMAIN gate overlays are
+# still loaded separately, as before (resolve_gate_overlays → load_gate_overlays). This gate
+# does not reference constitution.technical.md. (analyze-slice had no ai-rules seed — kept so.)
+standards: []
+
+vars:
+  test_ok: "false"
+  conformance_ok: "false"
+  # NAVIGATION ONLY. Whether a change is open decides where this gate sends you next
+  # (close-delta vs run) — nothing else in this workflow reads them. On the CHANGE path
+  # finalize-delta has already merged the delta into the master docs, so the delta files
+  # are redundant here and are deliberately NOT loaded into any context.
+  active_change: ""
+  has_change: "false"
+  # Integrity pass (referrer blast radius) defaults — safe values if xref/test-run is
+  # skipped or errors, so the gate reads a real verdict rather than an empty var.
+  integrity_ok: "false"
+  referrer_csv: ""
+  referrer_count: "0"
+  referrer_names: ""
+  # Pass-3 (OKF) reporting defaults — the knowledge pass is advisory, so these stay
+  # readable in the outputs even when a step is skipped or errors out.
+  okf_ok: "unknown"
+  okf_orphans: "0"
+
+workflow:
+
+  # 0. TECHNICAL rule files → sticky standards (configuration, not hardcoded).
+  #    tech-select reads docs/domainspecs/<domain>/commandtechrulemap.md under
+  #    "## /aw-spec-analyze-slice" and loads that set (testing + coding-standards) into
+  #    the sticky standards the conformance query reads (include_standards: true). The
+  #    DOMAIN gate overlays are loaded separately below. No blocking gate: an unconfigured
+  #    project soft-continues (the gate then checks only the domain overlays).
+  - id: tech_select
+    action: include
+    module: .aw-spec/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-analyze-slice }
+
+  - 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: spec_file,   from: "$.spec_file" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature. Run /aw-spec-orch select-feature first (pick or create the aggregate, e.g. Order), then re-run analyze-slice."
+
+  # Is a change OPEN on this feature? Read for NAVIGATION only — see the vars note. Safe
+  # on the bootstrap path: with no active_version.json, version-read returns
+  # active_change="" / has_change=false and exits 0, so nothing here is conditional on it.
+  - id: read_change
+    action: execute_script
+    script: { ref: actions }
+    subcommand: version-read
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: active_change, from: "$.active_change" }
+      - { name: has_change,    from: "$.has_change" }
+
+  # The slice's source files, from its OKF concept — the context all three passes below
+  # work over (test fix loop, integrity triage, conformance). Replaces the retired
+  # `design-paths` fence scan: design.md is tech-agnostic prose with no ```lang path=…
+  # code blocks, so that scan returned nothing and every pass ran on an EMPTY file list.
+  # Read-only, exits 0 with paths=[] when there is no concept yet; on_error: continue so
+  # a missing bundle degrades the gate to its pre-existing (empty) behaviour, never blocks.
+  - id: concept_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-paths
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: all_paths,     from: "$.paths" }
+      - { name: paths_missing, from: "$.missing" }
+
+  - id: resolve_pre_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_analyze_slice"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    hooks_from_variable: before_hooks
+
+  # ═══════ PASS 1 — BEHAVIOUR: the slice's tests vs the spec's acceptance criteria ═══════
+  # Run tests → (if red) fix → re-run, up to 3×.
+  - id: test_loop
+    action: loop
+    while: "{{test_ok}} != true"
+    max_iterations: 3
+    steps:
+      - id: run_tests
+        action: execute_script
+        on_error: continue
+        script: { ref: actions }
+        subcommand: test-run
+        # scope=slice: run ONLY this feature's tests in the fix loop. The loop EDITS code
+        # to make tests pass, and it can only repair THIS feature (its design + spec are
+        # what is in context) — so referring aggregates are deliberately NOT in this run;
+        # they are verified read-only by the integrity gate below.
+        args: ["--feature-dir", "{{feature_dir}}", "--scope", "slice"]
+        outputs:
+          - { name: test_ok,      from: "$.fence_green" }
+          - { name: test_tool,    from: "$.tool" }
+          - { name: test_log,     from: "$.log_tail" }
+          - { name: test_matched, from: "$.matched" }
+      - id: green_break
+        action: break
+        condition: "{{test_ok}} == true"
+      - id: ctx_fix
+        action: build_context
+        vars:
+          test_log: "{{test_log}}"
+        context:
+          - { path: "{{spec_file}}" }
+        context_from: all_paths
+      - id: fix
+        action: agent_generate
+        tools: "Read,Write,Edit,Bash"
+        permission_mode: acceptEdits
+        task: |
+          Tests failed. Make them pass by fixing the code (or a genuinely wrong
+          test) in the files in context, keeping behaviour aligned with the spec's
+          acceptance criteria (spec in context). Test log:
+          {{test_log}}
+        outputs:
+          - { name: fixed_files, from: "$.files" }
+
+  - id: test_gate
+    action: verify_context
+    require_true: test_ok
+    on_false: stop
+    on_false_message: "Slice tests not green after 3 fix attempts (scope=slice, matched={{test_matched}}). If matched=false the name filter selected ZERO tests for this feature — the test names don't contain the aggregate name — which the fence treats as a failure, not a vacuous pass. Last log: {{test_log}}"
+
+  # ═══════ PASS 2 — DOMAIN CONFORMANCE: code vs the gate overlay checklist (validation) ═══════
+  # With tests green, scan the feature's CODE against the domain gate overlays (the
+  # forbidden-patterns / refusal conditions / CI gates). The overlays load as the
+  # checklist — VALIDATION only, never an authoring input to feature code. No-op for a
+  # non-domain project. Fix violations (bounded 2×); the gate stops if any remain.
+  - id: resolve_gate_overlays
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-domain
+    args: ["--command", "aw-spec-gate"]
+    outputs:
+      - { name: gate_overlays, from: "$.candidates" }
+  - id: load_gate_overlays
+    action: load_standards
+    files_from_variable: gate_overlays
+    optional: true
+
+  - id: conformance_loop
+    action: loop
+    while: "{{conformance_ok}} != true"
+    max_iterations: 2
+    steps:
+      - id: ctx_conformance
+        action: build_context
+        context:
+          - { path: "{{spec_file}}" }
+        context_from: all_paths
+      - id: check_overlays
+        action: agent_query
+        include_standards: true            # the gate overlays (checklist) are in the standards
+        schema: { ok: true, violations: [ { rule: "<overlay rule / id>", where: "<file:symbol>", issue: "<what is violated>" } ] }
+        mock: { ok: true, violations: [] }
+        task: |
+          The domain gate checklist is loaded in the standards (the overlay
+          forbidden-patterns, refusal conditions, and CI gates). Check the feature's
+          generated code + tests (in context) against EACH checklist rule and list
+          EVERY violation, e.g.: a hard delete of a retention-protected aggregate /
+          version history / audit record; a second write path bypassing the aggregate
+          or interop adapter; an invented/free-text coded value where a validated code
+          is required; a missing or weakened audit emission on an audited operation; a
+          data-classification-restricted field exposed on the public surface or written
+          to logs/metrics/traces. Also confirm the constraint TESTS exist (audit is
+          emitted, a restricted field is not exposed, an interop projection round-trips).
+          ok=true ONLY when no checklist rule is violated.
+        outputs:
+          - { name: conformance_ok,         from: "$.ok" }
+          - { name: conformance_violations, from: "$.violations" }
+      - id: conformance_break
+        action: break
+        condition: "{{conformance_ok}} == true"
+      - id: fix_violations
+        action: agent_generate
+        tools: "Read,Write,Edit,Bash"
+        permission_mode: acceptEdits
+        task: |
+          Fix these domain-conformance violations in the feature's code (in context),
+          following the gate checklist rules (in the standards) and keeping the design's
+          behaviour intact. Do NOT weaken or delete a test to hide a violation — fix the
+          code. After fixing, re-run the tests (Bash) to confirm they stay green.
+          Violations: {{conformance_violations}}
+        outputs:
+          - { name: conformance_fixes, from: "$.files" }
+
+  - id: conformance_gate
+    action: verify_context
+    require_true: conformance_ok
+    on_false: stop
+    on_false_message: "Code violates the domain gate checklist after 2 fix attempts (violations: {{conformance_violations}}). These are the domain constraints design/implement must satisfy — fix the code, or if the constraint itself is wrong, correct it upstream (/aw-spec-orch specify → design)."
+
+  # ═══════ INTEGRITY — did this feature's change break any aggregate that USES it? ═══════
+  # The slice is green + domain-conformant on its own. But a change to a feature can break
+  # any OTHER aggregate that references it. Ask the OKF Cross-References index "who refers to
+  # me?" (the transitive referrer closure — C→B→A all count), then RE-RUN the feature's tests
+  # PLUS every referrer's tests as one read-only fence. Unlike PASS 1 this NEVER edits code:
+  # analyze-slice cannot repair a referrer (that is the referrer's own slice's job), so a
+  # broken referrer STOPS the gate for a human to resolve, it is not auto-fixed here.
+  # Empty referrer set (a leaf feature, or the only aggregate in the repo) → the fence is just
+  # the feature's own tests again → passes trivially, blocks nothing.
+  - id: xref_referrers
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: list
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: referrer_csv,   from: "$.referrer_closure_csv" }
+      - { name: referrer_count, from: "$.referrer_closure_count" }
+      - { name: referrer_names, from: "$.referrer_closure" }
+
+  - id: run_integrity
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: test-run
+    args: ["--feature-dir", "{{feature_dir}}", "--scope", "slice", "--also", "{{referrer_csv}}"]
+    outputs:
+      - { name: integrity_ok,  from: "$.fence_green" }
+      - { name: integrity_log, from: "$.log_tail" }
+
+  # On a RED fence, author a durable triage report BEFORE stopping — a broken referrer
+  # means someone must go fix ANOTHER slice, so this is a record, not scrollback (mirrors
+  # characterize's drifted-tests.md). Context is built unconditionally (cheap, no model
+  # call); the authoring model call is gated on failure, so a green run spends nothing.
+  # The report self-dates and is regenerated on each failing run — a later green fence
+  # supersedes it (no gate points here when integrity_ok is true).
+  - id: ctx_broken_referrers
+    action: build_context
+    vars:
+      referrer_names: "{{referrer_names}}"
+      referrer_count: "{{referrer_count}}"
+      integrity_log: "{{integrity_log}}"
+    context:
+      - { path: "{{spec_file}}" }
+    context_from: all_paths
+  - id: write_broken_referrers
+    action: agent_author
+    condition: "{{integrity_ok}} != true"
+    include_standards: false                       # a triage report, not generated code
+    output_target: { type: file, path: "{{feature_dir}}/broken-referrers.md" }
+    task: |
+      Author the BROKEN-REFERRER integrity report for this slice: the aggregates that
+      REFER to this feature whose tests went red when this feature's change was run
+      against them. This is a triage record for a human — analyze-slice does NOT fix a
+      referrer (that is the referrer's own slice's job). Referrer blast radius
+      ({{referrer_count}}): {{referrer_names}}. Failing test log:
+      {{integrity_log}}
+      Write markdown, in this order:
+      - `# Broken Referrers — <feature>` and a one-line statement of what this file is:
+        aggregates that USE this feature and whose tests went red when this feature's
+        change was run against them, found by analyze-slice's integrity gate. Add a line
+        stamping when + why it was generated (integrity fence RED for this feature), and
+        that it is regenerated on every FAILING analyze-slice run — a later green fence
+        supersedes it.
+      - A SUMMARY line: total referrers in the blast radius, and how many have a failing
+        test in the log.
+      - One `##` section per REFERRER that has a failing test — attribute a failure to a
+        referrer by matching the failing test names in the log to the referrer's name.
+        Under it, on their own labelled lines: the referrer aggregate, the failing
+        test(s) named in the log, what broke (as far as the log shows), and a RESOLUTION
+        line — either this feature's change broke the referrer's expected contract (fix
+        belongs in the referrer's OWN slice, or reconsider this feature's contract change)
+        or the referrer test is stale (correct it in that slice). Recommend one; do not
+        claim certainty the log does not support.
+      - A closing `## How to use this file`: resolve each finding in the referrer's own
+        slice (or via a CR on this feature's contract), then re-run
+        /aw-spec-orch analyze-slice; do not edit this file in place.
+      Attribute only what the log supports; invent no failures. Do NOT propose an edit to
+      THIS feature's production code to silence a referrer — that would hide a real
+      contract break.
+    outputs:
+      - { name: broken_report_file, from: "$.files" }
+
+  - id: integrity_gate
+    action: verify_context
+    require_true: integrity_ok
+    on_false: stop
+    on_false_message: "Integrity check failed — this feature's change breaks a test in an aggregate that REFERS to it. Referrer blast radius ({{referrer_count}}): {{referrer_names}}. Triage written to {{feature_dir}}/broken-referrers.md — resolve each in the referrer's own slice (or reconsider this feature's contract change), then re-run. Last log: {{integrity_log}}"
+
+  # ═══════ PASS 3 — OKF KNOWLEDGE: keep the slice's concept true to what now exists ═══════
+  # analyze-slice is the LAST stage that changes a greenfield slice's files: both fix loops
+  # above run with Write/Edit, and the conformance loop is explicitly asked to ADD missing
+  # constraint tests. Those files did not exist when implement wrote the OKF concept, so its
+  # source_files list is stale by the time we get here. Merge them in (UNION — never replace:
+  # the concept holds the full set implement recorded, these two vars hold only what the fix
+  # loops touched), then report cross-reference drift.
+  #
+  # These two steps are now the WHOLE write-back: the former `design-reconcile` step that
+  # preceded them was deleted (it copied on-disk file bodies into path-tagged design fences
+  # — meaningless once design.md became tech-agnostic prose, and it read the same
+  # fixed_files/paths these steps already own). Recording the files in the concept IS the
+  # current reconcile.
+  #
+  # Deliberately NOT re-running `record`: the Depends-On/Cross-References edges derive from
+  # design.md §1 + its External integrations table, and no step in this stage edits
+  # design.md — the edge sources
+  # cannot have moved here. `--origin` is likewise omitted: concept-upsert setdefaults it,
+  # so an adopted (brownfield) slice keeps its `reverse-engineered` provenance instead of
+  # being restamped greenfield.
+  #
+  # Advisory by design (on_error: continue, no gate): a green, domain-conformant slice is
+  # never failed over its knowledge index — drift is reported in the outputs and fixed by
+  # `aw-xref validate --prune` / re-running the owning slice's `record`.
+  - id: okf_merge_test_fixes
+    action: execute_script
+    condition: "{{fixed_files}}"
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-upsert
+    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{fixed_files}}", "--merge"]
+    outputs:
+      - { name: okf_concept, from: "$.concept" }
+
+  - id: okf_merge_conformance_fixes
+    action: execute_script
+    condition: "{{conformance_fixes}}"
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-upsert
+    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{conformance_fixes}}", "--merge"]
+    outputs:
+      - { name: okf_concept, from: "$.concept" }
+
+  - id: okf_review
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: validate
+    outputs:
+      - { name: okf_ok,      from: "$.ok" }
+      - { name: okf_orphans, from: "$.orphan_count" }
+
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_analyze_slice"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    hooks_from_variable: after_hooks
+
+outputs:
+  feature_dir: "{{feature_dir}}"
+  test_tool: "{{test_tool}}"
+  referrer_count: "{{referrer_count}}"
+  referrer_blast_radius: "{{referrer_names}}"
+  okf_concept: "{{okf_concept}}"
+  okf_index_ok: "{{okf_ok}}"
+  okf_orphans: "{{okf_orphans}}"
+  # Declared in the concept but absent on disk — advisory index drift, never gated.
+  stale_source_files: "{{paths_missing}}"
+  active_change: "{{active_change}}"
+  next: "CHANGE OPEN ({{active_change}}): /aw-spec-orch close-delta — the slice is green, domain-conformant and did not break a referrer, and its delta is already merged into the master docs, so the change may now be archived and the version bumped. NO OPEN CHANGE: /aw-spec-orch run."

package/assets/.aw-spec/orchestrator/workflows/aw-spec-build.orch.yaml

@@ -0,0 +1,188 @@
+# =============================================================================
+# aw-spec-build (orchestrator) — compile + fix + reconcile
+#
+# Compile the materialized code; on failure, fix the source files (the slice's own
+# source files as context, design intent as reference) up to 3×; then record whatever
+# the fix loop touched in the slice's OKF concept. Run after /aw-spec-orch implement.
+#
+# 1.1.0 — the slice's file list now comes from the OKF concept's `source_files`
+# (`aw-xref concept-paths`) instead of the retired `design-paths` scan for
+# ```lang path=… fences, a convention the tech-agnostic design.md no longer carries;
+# and the tail step records fix-loop files in that concept instead of copying file
+# bodies back into design fences (`design-reconcile`, likewise retired).
+#
+# 1.2.0 — TECHNICAL RULES ONLY: the `domain-select` include is REMOVED. Build repairs
+# compile errors against design intent — a purely technical job — and the domain never
+# reaches this stage anyway (specify is the domain's sole carrier into the pipeline;
+# build reads code and design.md, never the spec or the domain docs). The include was
+# also inert: no shipped comandrulemap.md carries a "## /aw-spec-build" heading, so
+# `resolve-domain` — which keys `rulemap_exists` off the FILE, not the heading —
+# returned `candidates: []` and every load step skipped. On a CONFIGURED project it was
+# a silent no-op; on an UNCONFIGURED one it was worse, firing domain-select's
+# interactive "continue or exit?" gate on every build to load rules that could never
+# have been found. Removing it makes greenfield `build` non-interactive.
+#
+# Launch:  /aw-spec-orch build [strategy]
+# =============================================================================
+
+name: aw-spec-build
+description: Compile the feature, fix compile errors against the design intent, then record the touched files in the slice's knowledge concept. Loads TECHNICAL rules only (commandtechrulemap) — no domain rules reach this stage.
+version: 1.2.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+scripts:
+  actions:
+    sh:  .aw-spec/scripts/bash/aw-spec-actions.sh
+    ps1: .aw-spec/scripts/powershell/aw-spec-actions.ps1
+  xref:
+    sh:  .aw-spec/scripts/bash/aw-xref.sh
+    ps1: .aw-spec/scripts/powershell/aw-xref.ps1
+
+# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The technical
+# rule files (the compile/fix reference set) are CONFIGURATION, loaded per-command from
+# docs/domainspecs/<domain>/commandtechrulemap.md by the tech-select module (see the
+# tech_select step below). Technical rules ONLY — build loads no domain rules and does
+# not reference constitution.technical.md. A required file that is missing is reported
+# at assembly time (`[system] MISSING (required)`), an `optional:` one is skipped.
+standards:
+  - { path: docs/glossary/ai-rules.md, optional: true }
+
+vars:
+  build_ok: "false"
+
+workflow:
+
+  # Rule files → sticky standards: TECHNICAL only, via tech-select, read from
+  # docs/domainspecs/<domain>/commandtechrulemap.md under "## /aw-spec-build".
+  # NO domain-select here — see the header: build repairs compile errors, a purely
+  # technical job, and the domain never reaches this stage anyway (specify is its sole
+  # carrier; build reads code and design intent, not spec).
+  - id: tech_select
+    action: include
+    module: .aw-spec/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-build }
+
+  - 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" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature. Run /aw-spec-orch select-feature first (pick or create the aggregate, e.g. Order), then re-run build."
+
+  # The slice's source files, from its OKF concept — what the fix loop below is handed.
+  # This replaces the retired `design-paths` fence scan: the tech-agnostic design.md
+  # carries no ```lang path=… code blocks, so that scan returned nothing and the fixer
+  # was told to "fix the source files in context" with an EMPTY context. `source_files`
+  # is the maintained answer (implement writes it, analyze-slice merges fixes into it).
+  # Advisory: read-only, exits 0 with paths=[] when there is no concept yet, and
+  # on_error: continue so an unreadable bundle can never block a compile.
+  - id: concept_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-paths
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: all_paths,     from: "$.paths" }
+      - { name: paths_missing, from: "$.missing" }
+
+  - id: resolve_pre_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_build"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    hooks_from_variable: before_hooks
+
+  # Compile → (if red) fix the source files → recompile, up to 3×.
+  - id: build_loop
+    action: loop
+    while: "{{build_ok}} != true"
+    max_iterations: 3
+    steps:
+      - id: compile
+        action: execute_script
+        on_error: continue
+        script: { ref: actions }
+        subcommand: build-compile
+        args: ["--feature-dir", "{{feature_dir}}"]
+        outputs:
+          - { name: build_ok,   from: "$.ok" }
+          - { name: build_tool, from: "$.tool" }
+          - { name: build_log,  from: "$.log_tail" }
+      - id: green_break
+        action: break
+        condition: "{{build_ok}} == true"
+      - id: ctx_fix
+        action: build_context
+        vars:
+          build_log: "{{build_log}}"
+        context_from: all_paths
+      - id: fix
+        action: agent_generate
+        tools: "Read,Write,Edit,Bash"
+        permission_mode: acceptEdits
+        task: |
+          The build failed. Fix the COMPILE errors in the source files provided in
+          context, honoring the loaded standards and the design intent. Change only
+          what the errors require — do not alter behaviour. Build log:
+          {{build_log}}
+        outputs:
+          - { name: fixed_files, from: "$.files" }
+
+  - id: build_gate
+    action: verify_context
+    require_true: build_ok
+    on_false: stop
+    on_false_message: "Build still failing after 3 fix attempts. Last log: {{build_log}}"
+
+  # Record what the fix loop touched in the slice's OKF concept. This replaces the retired
+  # `design-reconcile` step, which copied on-disk file bodies back into the design doc's
+  # path-tagged fences — meaningless now that design.md describes contracts, not code (and
+  # a silent no-op for as long as that has been true). The fix loop can CREATE files that
+  # implement never recorded, so the knowledge index, not the design prose, is what has to
+  # be caught up. UNION (--merge), never replace: fixed_files holds only what this loop
+  # touched, while the concept holds the slice's full set.
+  #
+  # Advisory by design (condition + on_error: continue, no gate): a green build is never
+  # failed over its knowledge index — same stance as analyze-slice's OKF pass.
+  - id: okf_merge_build_fixes
+    action: execute_script
+    condition: "{{fixed_files}}"
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-upsert
+    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{fixed_files}}", "--merge"]
+    outputs:
+      - { name: okf_concept, from: "$.concept" }
+
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_build"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    hooks_from_variable: after_hooks
+
+outputs:
+  feature_dir: "{{feature_dir}}"
+  build_tool: "{{build_tool}}"
+  okf_concept: "{{okf_concept}}"
+  # Declared in the concept but absent on disk — index drift worth an operator's eye
+  # (a file moved or deleted without re-running the owning slice). Advisory, never gated.
+  stale_source_files: "{{paths_missing}}"
+  next: "/aw-spec-orch analyze-slice"