aw-spec-cli 0.1.16 → 0.1.17

package/assets/.appweaver/orchestrator/workflows/aw-spec-analyze-delta-design.orch.yaml

@@ -1,251 +0,0 @@
-# =============================================================================
-# aw-spec-analyze-delta-design (orchestrator) — the delta-spec↔delta-design GATE
-#
-# The CR analog of analyze-design, scoped to the OPEN change. The delta spec is the
-# ANCHOR: confirm delta-design.md STRICTLY realises delta-spec.md (+ the domain gate
-# overlays as a backstop), and that every MODIFIED element names a real element in
-# the master design.md. On drift, REPORT the gaps and ASK whether to repair, then
-# UPDATE delta-design.md to conform (the delta spec wins). This stage VALIDATES the
-# delta only — it does NOT touch spec.md / design.md and does NOT close the change
-# (finalize-delta merges the delta later; close-delta closes it at the very end).
-#
-#   specify → design → ⟨review⟩ → analyze-delta-design   ← you are here
-#       → implement-delta → build → finalize-delta → analyze-slice → close-delta
-#
-# Launch:  /appweaver analyze-delta-design [strategy]
-# Prereq:  /appweaver specify (delta-spec) + design (delta-design) — an OPEN change with both delta docs.
-# =============================================================================
-
-name: aw-spec-analyze-delta-design
-description: The delta-spec↔delta-design conformance gate for an open change — confirm delta-design.md realises delta-spec.md (delta spec is the anchor; domain overlays are a backstop; MODIFIED elements must exist in the master design) and, with approval, repair it. Does not modify the master docs or close the change.
-version: 1.0.0
-agent_agnostic: true
-dialect: aw-spec.orchestrator/v1
-
-scripts:
-  actions:
-    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
-    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
-
-standards:
-  - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
-
-vars:
-  analyze_ok: "false"
-  active_change: ""
-  has_change: "false"
-
-workflow:
-
-  # 1. Resolve the current feature + its spec; require the spec (delta context base).
-  - 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" }
-      - { name: spec_exists, from: "$.spec_exists" }
-
-  - id: require_feature
-    action: verify_context
-    require_non_empty: feature_dir
-    on_empty: stop
-    on_empty_message: "No active feature. Run /appweaver select-feature first (pick or create the aggregate, e.g. Order), then re-run analyze-delta-design."
-
-  - id: verify_spec
-    action: verify_context
-    require_true: spec_exists
-    on_false: stop
-    on_false_message: "No spec.md for the current feature. Run /appweaver specify (and design) first."
-
-  # 1b. Read the OPEN change (opened by cr). A CR gate needs a change to gate.
-  - 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" }
-
-  - id: require_change
-    action: verify_context
-    require_true: has_change
-    on_false: stop
-    on_false_message: "No open change on this feature. Run /appweaver specify <change> (opens the change + delta-spec) then /appweaver design (delta-design) first — analyze-delta-design gates an open change's delta docs."
-
-  # 2. Ensure the master design.md exists (idempotent) — the base the delta MODIFIED
-  #    elements must refer to. Delta doc paths are derived from the open change id.
-  - id: design_scaffold
-    action: execute_script
-    script: { ref: actions }
-    subcommand: design-scaffold
-    args: ["--feature-dir", "{{feature_dir}}"]
-    outputs:
-      - { name: design_doc, from: "$.design_doc" }
-
-  # 2b. Load the domain GATE overlays (the domain-rule-bindings `/aw-spec-gate` checklist) as
-  #     the conformance checklist — VALIDATION input only, NEVER authoring. analyze sees
-  #     them (include_standards: true); reconcile does NOT (the delta conforms to the
-  #     delta SPEC, not to the overlays). Empty/no-op for a non-domain project.
-  - 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
-
-  # 3. Pre-execution hooks.
-  - id: resolve_pre_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "before_analyze_cr"]
-    outputs:
-      - { name: before_hooks, from: "$.hooks" }
-  - id: dispatch_pre_hooks
-    action: dispatch_hooks
-    hooks_from_variable: before_hooks
-
-  # 4. Conformance + REPAIR loop (the delta spec is the anchor): check → REPORT gaps +
-  #    ASK → Repair on approval → re-check; "Report and Skip" writes the report + stops.
-  #    Bounded (3×). Delta docs live under changes/<open change>/.
-  - id: analyze_loop
-    action: loop
-    while: "{{analyze_ok}} != true"
-    max_iterations: 3
-    steps:
-      - id: analyze
-        action: agent_query
-        context:
-          - "{{feature_dir}}/changes/{{active_change}}/delta-spec.md"
-          - "{{feature_dir}}/changes/{{active_change}}/delta-design.md"
-          - "{{spec_file}}"
-          - "{{design_doc}}"
-        include_standards: true            # the gate overlays (checklist) are in the standards
-        schema: { ok: true, gaps: [ { severity: "high", spec_ref: "<delta FR/BR/CN/DC/IC/US or overlay or —>", where: "<delta-design section>", gap: "<how it drifts>" } ] }
-        mock: { ok: true, gaps: [] }
-        task: |
-          delta-spec.md is the ANCHOR for this change. Check that delta-design.md
-          (in context) STRICTLY realises the delta spec (in context) and list EVERY
-          drift as a gap:
-          (1) every ADDED / MODIFIED delta-spec item — FR / BR / CN- / DC- / IC- /
-          user story — has a home in the delta design (an ADDED or MODIFIED design
-          element that serves it). A delta-spec item with no delta-design element is
-          a HIGH gap;
-          (2) every MODIFIED delta-design element names a REAL element that exists in
-          the master design.md (also in context) — you cannot MODIFY what the master
-          does not define (that would be an ADD). A dangling MODIFIED reference is a
-          HIGH gap;
-          (3) the delta design introduces NOTHING beyond the delta spec — any design
-          element with no delta-spec basis is a drift (unless logged as a delta DA-n);
-          (4) shared elements have ONE owning definition (no duplicate path=/element);
-          the layers stay coherent (Application→Domain, API→Application, Infra→ports)
-          and technology-agnostic;
-          (5) OVERLAY BACKSTOP — the domain gate checklist is loaded in the standards.
-          For each constraint it states (retention, immutability, append-only audit,
-          data-exposure, interop obligation, etc.) that this CHANGE touches, confirm
-          the delta realises it via a delta CN-/DC-/IC-. If the change touches such a
-          constraint but it is in NEITHER the delta spec nor the delta design, it is a
-          HIGH gap — set spec_ref to the overlay name and PREFIX the gap text with
-          "LIFT-FAILURE:" (re-run /appweaver specify to lift it into the delta spec; do
-          NOT fabricate it in the delta design).
-          (If delta-design.md is still the empty template, treat the WHOLE delta spec
-          as gaps.) Set ok=true ONLY when delta-design.md fully realises the delta spec
-          AND no touched checklist constraint is unaccounted for.
-        outputs:
-          - { name: analyze_ok,   from: "$.ok" }
-          - { name: analyze_gaps, from: "$.gaps" }
-      - id: conform_break
-        action: break
-        condition: "{{analyze_ok}} == true"
-      - id: ask_repair
-        action: ask
-        prompt: |
-          analyze-delta-design found delta-spec↔delta-design gaps (the delta spec is the anchor):
-          {{analyze_gaps}}
-          Repair delta-design.md to conform to the delta spec now, or report the gaps and stop?
-        options: ["Repair", "Report and Skip"]
-        answer_var: repair_choice
-      - id: write_report
-        condition: "{{repair_choice}} == Report and Skip"
-        action: agent_author
-        context: ["{{feature_dir}}/changes/{{active_change}}/delta-design.md"]
-        include_standards: false
-        output_target: { type: file, path: "{{feature_dir}}/changes/{{active_change}}/delta-design-analyze-report.md" }
-        task: |
-          Write a Delta Design Analyze Report to the output from these
-          delta-spec↔delta-design conformance gaps (the delta spec is the ANCHOR; the
-          user chose to skip repair):
-          {{analyze_gaps}}
-          Markdown format:
-          - "# Delta Design Analyze Report — {{active_change}}" plus today's date.
-          - A verdict line: "verdict: GAPS ✗ · <n> gap(s)".
-          - "## Gaps" as a table: | # | severity | delta-spec ref | delta-design location | gap |.
-          - "## How to resolve": the delta spec is the anchor — update delta-design.md
-            to realise it for each gap (out of band; a "LIFT-FAILURE:" gap means re-run
-            /appweaver specify to lift the constraint into the delta spec), then re-run
-            /appweaver analyze-delta-design to clear the report.
-          Return the complete report markdown only.
-      - id: skip_break
-        action: break
-        condition: "{{repair_choice}} == Report and Skip"
-      - id: reconcile
-        action: agent_author
-        context:
-          - "{{feature_dir}}/changes/{{active_change}}/delta-spec.md"
-          - "{{feature_dir}}/changes/{{active_change}}/delta-design.md"
-          - "{{design_doc}}"
-        include_standards: false           # rewrite-in-place: the delta spec anchors — NOT the overlays
-        output_target: { type: file, path: "{{feature_dir}}/changes/{{active_change}}/delta-design.md" }
-        task: |
-          delta-spec.md is the ANCHOR — update delta-design.md (in context) to REALISE
-          it, closing these gaps (the delta spec WINS every time):
-          {{analyze_gaps}}
-          - Add a delta-design element for each uncovered ADDED/MODIFIED delta-spec
-            FR/BR/CN/DC/IC/US, in the correct layer section, serving that spec id.
-          - Ensure every MODIFIED element names a REAL element from the master
-            design.md (in context); if the master does not define it, make it an ADDED
-            element instead.
-          - REMOVE, or move to a delta DA-n note, any delta-design element with no
-            delta-spec basis — never keep design that exceeds the delta spec.
-          - A "LIFT-FAILURE:" gap you CANNOT close — the constraint is not in the delta
-            spec, and you must NOT invent a domain rule it omits. Leave it open and add
-            a note "lift-failure: <constraint> — re-run /appweaver specify to lift it into
-            the delta spec". (The gate will stop and direct the user to cr.)
-          - Keep the technology-agnostic form (signatures + pre/post/invariant, field
-            shapes — NO code). Preserve every already-conformant section VERBATIM. Do
-            NOT change the delta spec or the master design.md.
-          Return the COMPLETE updated delta-design.md content only.
-
-  - id: analyze_gate
-    action: verify_context
-    require_true: analyze_ok
-    on_false: stop
-    on_false_message: "delta-design.md does not realise the delta spec (gaps: {{analyze_gaps}}) — repair was skipped (see changes/{{active_change}}/delta-design-analyze-report.md), or it could not be reconciled in 3 passes. A 'LIFT-FAILURE:' gap means a domain constraint from the gate checklist was never lifted into the delta spec — re-run /appweaver specify to add it (CN-/DC-/IC-). Otherwise fix out of band, or re-run and choose Repair."
-
-  # 5. Post-execution hooks.
-  - id: resolve_post_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "after_analyze_cr"]
-    outputs:
-      - { name: after_hooks, from: "$.hooks" }
-  - id: dispatch_post_hooks
-    action: dispatch_hooks
-    hooks_from_variable: after_hooks
-
-outputs:
-  feature_dir: "{{feature_dir}}"
-  cr_id: "{{active_change}}"
-  conformant: "{{analyze_ok}}"
-  gaps: "{{analyze_gaps}}"
-  next: "/appweaver implement-delta → build → finalize-delta → analyze-slice → close-delta   (the delta design realises the delta spec; the change stays OPEN through finalize-delta's merge and analyze-slice's verification, and only close-delta archives it and bumps the version)"