aw-spec-cli 0.1.13 → 0.1.15

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

@@ -1,382 +0,0 @@
-# =============================================================================
-# aw-spec-design (orchestrator) — the spec-anchored Design phase (delta-aware)
-#
-# Authors ONE high-level design document per feature — specs/<Aggregate>/design.md
-# — the tech-agnostic HLD that MEDIATES between the spec and the code. It covers all
-# four clean-architecture layers as SECTIONS (Domain · Application · API · Infra),
-# carries structure/behaviour/contracts/decisions + the Assumptions and Workarounds
-# ledgers, but NO complete code. `implement` GENERATES the code from spec + design.md
-# (model-driven, not a deterministic extract). See .appweaver/DESIGN-FORMAT.md +
-# .appweaver/templates/design-template.md.
-#
-# TEMPLATE-DRIVEN AUTHORING (greenfield-safe). The master-authoring step follows the
-# structure of whichever design template is ACTIVE, chosen deterministically:
-#   • GREENFIELD (default) — the four-layer template (Domain·Application·API·Infra).
-#     This path and its prompt are UNCHANGED.
-#   • BROWNFIELD — when /appweaver onboard has GENERATED the code-derived
-#     `design-template` override (reverse-engineered from the repo's own structure;
-#     override_active), a NEW feature added to an existing repo (NO adopt) is authored
-#     with the code-derived structure instead, consistent with the as-built architecture.
-# The two are separate steps selected by a single `design_mode` var, so greenfield
-# authoring never sees the brownfield guidance and vice-versa.
-#
-# AUTHORS only — the gates are SEPARATE stages. SELF-DETECTS the branch from
-# design.md's OWN existence (symmetric with how specify keys off spec.md):
-#   • BOOTSTRAP (no design.md yet) → author the MASTER design.md. Version stays as-is.
-#     Next: /appweaver analyze-design (spec↔design gate) → implement.
-#   • DELTA (design.md exists) → delegate to the delta-design module: author the
-#     DELTA-DESIGN record ONLY; the master design.md is left UNTOUCHED (finalize-delta
-#     merges it later). The change stays OPEN. On the delta path design is DECOUPLED
-#     from specify: it JOINS the change specify opened when one is open, or OPENS its
-#     OWN when none is — a DESIGN-ONLY change (the design's realisation of EXISTING spec
-#     ids changes without any spec delta). Next: the CR chain —
-#     /appweaver analyze-delta-design → implement-delta → build → finalize-delta →
-#     analyze-slice → close-delta.
-# Because the trigger is design.md-exists (not an open change), re-running design after
-# the bootstrap is a DELTA, not a re-bootstrap — to regenerate the master, delete
-# design.md first.
-# The forward paths are explicit:
-#   NEW    : specify → design → analyze-design → implement
-#   CHANGE : specify (delta-spec) → design (delta-design) → analyze-delta-design →
-#            implement-delta → build → finalize-delta → analyze-slice → close-delta
-# (The former standalone `cr` capture is RETIRED — its delta-spec / delta-design
-# authoring now lives in specify / design via the delta-spec / delta-design modules.)
-#
-# Feature = the aggregate; commands (CreateOrder/UpdateOrder) are user stories on
-# this same design.md — a later one is a delta here, never a separate design doc.
-#
-# Launch:  /appweaver design [strategy] [guidance]
-# Prereq:  /appweaver specify   (bootstrap authors US-1; a later specify opens a change + delta-spec)
-# =============================================================================
-
-name: aw-spec-design
-description: "Author the single high-level design.md from the spec (bootstrap when no design.md yet), or author a delta-design (when design.md already exists) — self-detecting on design.md, symmetric with specify's spec.md trigger. On the delta path it delegates to the delta-design module: JOIN the change specify opened or OPEN its own (a design-only change), author the delta-design ONLY (master design.md untouched — finalize-delta merges it). Tech-agnostic HLD that mediates spec → code. Master authoring is template-driven — greenfield four-layer by default, or the code-derived brownfield structure when onboard has installed it as the design-template override. Authoring only — bootstrap gates at analyze-design; a change ships via analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta."
-version: 3.4.0
-agent_agnostic: true
-dialect: aw-spec.orchestrator/v1
-
-inputs:
-  user_input:
-    description: Optional design guidance (architectural constraints, trade-off preferences).
-    required: false
-    bind: USER_INPUT
-
-scripts:
-  actions:
-    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
-    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
-
-# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The
-# TECHNICAL/architecture 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 the
-# DOMAIN rule files are loaded by domain-select. Per the rule-partition, design still
-# loads NO domain file — the tech map lists only technical files; domain reaches
-# design solely as spec ids (BR-/CN-/DC-/IC-). The technology base itself arrives via
-# constitution.technical.md (referred to directly, as-is — NOT mapped). DDD stays in
-# specify; coding-standards in implement. (missing files skipped at assembly time)
-standards:
-  - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
-
-vars:
-  active_change: ""
-  has_change: "false"
-  version: ""
-  brownfield_design: "false"   # set from design-scaffold.override_active (onboard installed the code-derived template)
-  design_created: "false"      # set from design-scaffold.created — true ⇒ design.md was ABSENT (just scaffolded) ⇒ bootstrap
-  design_exists: "false"       # NOT design_created ⇒ design.md pre-existed ⇒ this is a DELTA
-  design_no_change: "true"     # NOT has_change ⇒ no change open yet ⇒ on the delta path design opens its OWN (design-only)
-  need_new_change: "false"     # design_mode==delta AND design_no_change ⇒ design must open a change here
-  design_mode: "bootstrap_gf"  # resolved below → bootstrap_gf | bootstrap_bf | delta
-
-workflow:
-
-  # 0. TECHNICAL rule files → sticky standards (configuration, not hardcoded).
-  #    tech-select reads guardrails/projects/<project>/tech-rule-bindings.md under
-  #    "## /aw-spec-design" and loads that set. No domain rule file is loaded here —
-  #    the tech map lists only technical files, so design still authors from the spec
-  #    + technical standards (rule-partition intact). No blocking gate: an unconfigured
-  #    project soft-continues (constitution.technical.md still carries the tech base).
-  - id: tech_select
-    action: include
-    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-design }
-
-  # 1. Resolve the current feature and require its spec.
-  - 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 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 first."
-
-  # 3. Read the open change (set by specify). has_change picks the branch below.
-  - 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" }
-      - { name: version,       from: "$.version" }
-
-  # 3b. Whether a change is already OPEN (specify opened it). Drives join-vs-open on the
-  #     delta path: an open change ⇒ design JOINS it; none ⇒ design opens its OWN.
-  - id: flag_change_open
-    condition: "{{has_change}} == true"
-    action: set
-    vars: { design_no_change: "false" }
-
-  # 4. Scaffold the single design.md from design-template.md (idempotent — returns
-  #    the existing path when it already exists, e.g. on the delta path).
-  - id: design_scaffold
-    action: execute_script
-    script: { ref: actions }
-    subcommand: design-scaffold
-    args: ["--feature-dir", "{{feature_dir}}"]
-    outputs:
-      - { name: design_doc,        from: "$.design_doc" }
-      - { name: brownfield_design, from: "$.override_active" }   # true ⇒ onboard installed the code-derived template
-      - { name: design_created,    from: "$.created" }           # true ⇒ design.md was ABSENT (just scaffolded) ⇒ bootstrap
-
-  # 4a. Self-detect the DELTA trigger from design.md's OWN existence (symmetric with
-  #     specify's spec.md trigger). Scaffold reports created=true only when it had to
-  #     CREATE design.md (i.e. it was absent) — so created=false ⇒ it pre-existed ⇒ delta.
-  - id: mark_design_exists
-    condition: "{{design_created}} == false"
-    action: set
-    vars: { design_exists: "true" }
-
-  # 4b. Resolve the authoring MODE deterministically (the condition evaluator supports
-  #     only single == / != comparisons, so collapse the booleans into ordered sets).
-  #       bootstrap_gf (default) → greenfield master authoring (four-layer template)
-  #       bootstrap_bf           → brownfield master authoring (code-derived template)
-  #       delta                  → design.md ALREADY EXISTS (delta authoring)
-  #     Order matters: the brownfield override flips the greenfield default; an EXISTING
-  #     design.md flips either into a delta (a delta is a delta regardless of template).
-  - id: mode_brownfield
-    condition: "{{brownfield_design}} == true"
-    action: set
-    vars: { design_mode: "bootstrap_bf" }
-  - id: mode_delta
-    condition: "{{design_exists}} == true"
-    action: set
-    vars: { design_mode: "delta" }
-
-  # 4c. On the delta path, does design need to OPEN its own change? Yes iff no change is
-  #     already open (design_no_change). This collapses (design_mode==delta AND
-  #     design_no_change) into one var: it takes design_no_change's value only in delta
-  #     mode, and stays false in either bootstrap mode.
-  - id: flag_need_new_change
-    condition: "{{design_mode}} == delta"
-    action: set
-    vars: { need_new_change: "{{design_no_change}}" }
-
-  # 5. Pre-execution hooks.
-  - id: resolve_pre_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "before_design"]
-    outputs:
-      - { name: before_hooks, from: "$.hooks" }
-  - id: dispatch_pre_hooks
-    action: dispatch_hooks
-    hooks_from_variable: before_hooks
-
-  # ══════════════════ BOOTSTRAP — no open change (author design.md) ═══════════
-  # Author the whole HLD in one pass: all four layers as sections, tech-agnostic,
-  # traced to the spec. build_context REPLACES the per-request envelope; sticky
-  # standards stay prepended. The ENGINE writes design_doc.
-  - id: ctx_design
-    condition: "{{design_mode}} == bootstrap_gf"
-    action: build_context
-    context:
-      - { path: "{{design_doc}}" }              # the copied template = section structure
-      - { path: "{{spec_file}}" }               # the source of truth (FR/BR/CN/DC/IC/US/SC)
-      - { path: .appweaver/DESIGN-FORMAT.md }      # the HLD contract
-      - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain (domain enters via the spec)
-  - id: gen_design
-    condition: "{{design_mode}} == bootstrap_gf"
-    action: agent_author
-    output_target: { type: file, path: "{{design_doc}}" }
-    task: |
-      Author the MASTER high-level design (the target design.md in context) for this
-      aggregate by filling out the template, based on the feature spec + the loaded
-      technical/architecture standards. This is the MEDIATOR between the spec and the
-      generated code. Guidance: {{USER_INPUT}}
-      Rules:
-      - THE SPEC IS THE ONLY DOMAIN INPUT. You have the spec + technical standards, and
-        NO domain rule files. The domain arrives as spec ids only — realise them, and
-        invent no domain rule the spec omits (an unavoidable new concept → §7 DA-n).
-      - Cover the four layers as sections: Domain (§1), Application (§2), API (§3),
-        Infrastructure (§4). Keep the template's section order and headings.
-      - The DOMAIN layer (§1) MUST follow spec.md EXACTLY: entities & value objects
-        are the spec's Key Entities (SAME names), invariants are the spec's Business
-        Rules (BR-nnn — cite each), the aggregate boundary is the spec's Aggregate
-        Boundary, and states are the lifecycle the spec describes. Elaborate with
-        domain events / state machines / behaviour signatures ONLY to realise spec
-        behaviour; do NOT invent or contradict. Any unavoidable new concept goes in
-        §7 as a DA-n assumption.
-      - REALISE THE LIFTED CONSTRAINTS (each cites its spec id):
-        • Constraints & NFRs (CN-) → structural ones (immutability, append-only audit,
-          no-hard-delete) as §1 invariants/events; retention/performance/audit as §5
-          Cross-Cutting rows or §4 persistence.
-        • Data Classification (DC-) → §5 data-protection + the §2/§3 projection surface
-          (what MUST NOT be exposed in API/logs/traces).
-        • Integration Contracts (IC-) → §4.2 External integrations (one port/adapter row
-          per IC-), realising the obligation the spec named.
-      - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded technical constitution, NOT
-        the spec): a NON-NEGOTIABLE technical principle you must apply that has NO
-        per-feature spec id. APPLY it (it is non-negotiable), and because it is not
-        spec-derived, LOG it as a §7 DA-n whose basis cites the mandating principle
-        ("per Const. §<n>"); set the corresponding §5 row's "Serves" to that DA-n. Do
-        NOT fabricate a spec CN- for it, and do NOT leave it uncited — an uncited
-        non-spec element reads as spec over-reach at the analyze gate.
-      - TECHNOLOGY-AGNOSTIC: express behaviour as signatures + pre/post/invariant/
-        raises pseudocode and contracts as field shapes — NEVER language code. Use
-        conceptual types. The stack is bound only at `implement` time. Do NOT include
-        code-generation mechanics or the layering/dependency rule — those are
-        solution-wide rules applied in `implement` / the constitution, not per feature.
-      - Every design element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/US-/SC-); the
-        whole spec traces DOWN — fill §6 Traceability completely, with a row for EVERY
-        CN-/DC-/IC- so no lifted constraint is silently dropped.
-      - Fill the two ledgers: §7 Assumptions (DA-n, to clarify later) and §8
-        Workarounds (WA-n, to clear later). Empty → "None (as of v1.0)".
-      - Physical persistence schema is OUT OF SCOPE (defer to the technical-data-model).
-      - This is v1.0: set the initial Change History row + keep US-1's mapping.
-      - Omit a LAYER section only if the aggregate genuinely has nothing there
-        (state why); never write "N/A". No complete code anywhere.
-
-  # ═══════ BOOTSTRAP (BROWNFIELD) — code-derived template, NEW feature, no adopt ═══
-  # Same contract as the greenfield bootstrap above (tech-agnostic HLD, spec is the only
-  # domain input, full §Traceability + the two ledgers), with ONE difference: the design
-  # STRUCTURE follows the code-derived brownfield template + the project's AS-BUILT
-  # architecture, not the fixed four layers — so a new feature added to an existing repo
-  # is consistent with the code already there. Runs only when onboard generated the
-  # code-derived design-template override (design_mode == bootstrap_bf).
-  - id: ctx_design_brownfield
-    condition: "{{design_mode}} == bootstrap_bf"
-    action: build_context
-    context:
-      - { path: "{{design_doc}}" }              # the scaffolded BROWNFIELD template = code-derived section structure
-      - { path: "{{spec_file}}" }               # the source of truth (FR/BR/CN/DC/IC/US/SC)
-      - { path: .appweaver/DESIGN-FORMAT.md }      # the HLD contract (see its Brownfield variant note)
-      - { path: knowledge/architecture/overview.md, optional: true }  # the project's AS-BUILT architecture (onboard) — align to it
-      - { path: knowledge/architecture/platform.md, optional: true }  # the as-built technology base / cross-cutting reality
-      - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain (domain enters via the spec)
-  - id: gen_design_brownfield
-    condition: "{{design_mode}} == bootstrap_bf"
-    action: agent_author
-    output_target: { type: file, path: "{{design_doc}}" }
-    task: |
-      Author the MASTER high-level design (the target design.md in context — it is the
-      code-derived BROWNFIELD template) for this NEW feature being added to an EXISTING
-      codebase, by filling the template from the spec + the loaded technical/architecture
-      standards. It is the MEDIATOR between the spec and the code `implement` will
-      generate. Guidance: {{USER_INPUT}}
-      Rules:
-      - THE SPEC IS THE ONLY DOMAIN INPUT. You have the spec + technical standards + the
-        project's as-built architecture references, and NO domain rule files. The domain
-        arrives as spec ids only — realise them, invent no domain rule the spec omits (an
-        unavoidable new concept → a §5 DA-n assumption).
-      - STRUCTURE FOLLOWS THE TEMPLATE + THE PROJECT'S AS-BUILT ARCHITECTURE, NOT the four
-        greenfield layers. Keep the template's own section order and headings (§0 Overview
-        + ubiquitous language; §1 Architecture Context & Domain Model; §2 Component &
-        Behaviour Design; §3 Cross-Cutting; §4 Traceability; §5 Assumptions; §6
-        Deviations). Fill §1.1 (As-Built Architecture) by ALIGNING this feature to the
-        project's existing style/patterns/folders — read knowledge/architecture/
-        overview.md + platform.md (in context) and MATCH them, so the new feature slots
-        into the codebase as-built. Create ONE §2 subsection per structural axis THIS
-        feature actually needs (its use-cases, endpoints/UI, persistence, external
-        adapters, jobs) — titled after the project's OWN module/folder conventions, not a
-        fixed Domain/Application/API/Infrastructure layering. A component that fits no
-        textbook layer gets its own section; a layer the feature does not need does NOT
-        appear.
-      - KEEP THE NEUTRAL ANCHORS (the template pins them): §1.2 is the domain/data MODEL
-        and MUST follow spec.md EXACTLY — entities & value objects are the spec's Key
-        Entities (SAME names), invariants are the spec's Business Rules (BR-nnn, cite
-        each), the boundary is the spec's Aggregate Boundary, states are its lifecycle;
-        cross-slice references-by-id live here. One §2 subsection is the EXTERNAL
-        INTEGRATIONS table (its heading contains "Integration") — one port/adapter row
-        per IC-, realising the obligation the spec named.
-      - REALISE THE LIFTED CONSTRAINTS (each cites its spec id): CN- → structural ones
-        (immutability, append-only audit, no-hard-delete) as §1.2 invariants/events;
-        retention/performance/audit as §2 persistence or §3 Cross-Cutting rows. DC- → §3
-        data-protection + the projection surface (what MUST NOT be exposed in
-        API/logs/traces).
-      - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded technical constitution, NOT
-        the spec): a NON-NEGOTIABLE technical principle with no per-feature spec id —
-        APPLY it, and LOG it as a §5 DA-n whose basis cites the mandating principle
-        ("per Const. §<n>"); do NOT fabricate a spec CN- for it, and do NOT leave it
-        uncited.
-      - TECHNOLOGY-AGNOSTIC: signatures + pre/post/invariant/raises pseudocode and
-        field-shape contracts — NEVER language code. Conceptual types only; the stack is
-        bound at `implement` time. Do NOT include code-generation mechanics or the
-        layering/dependency rule (those are solution-wide / constitution rules).
-      - Every design element traces UP to a spec id; fill §4 Traceability completely (a
-        row for EVERY FR/BR/CN/DC/IC/US/SC so no lifted constraint is dropped). Fill the
-        §5 Assumptions (DA-n) and §6 Deviations (WA-n) ledgers — "None (as of v1.0)" if
-        empty. §6 records only genuine deviations, not "organised unlike a reference
-        architecture" (that is the as-built shape, §1.1).
-      - This is v1.0: set the initial Change History row + keep US-1's mapping. Omit a
-        section only if the feature genuinely has nothing there (state why); no complete
-        code anywhere.
-
-  # ══════════════════ DELTA — design.md exists (delegate to delta-design) ═══════
-  # design.md exists ⇒ delta. Delegate to the delta-design module: it JOINs the change
-  # specify opened (need_new_change=false) or OPENs its own (a design-only change —
-  # spec unchanged), then authors the delta-design ONLY — the master design.md is left
-  # UNTOUCHED. The change stays OPEN; finalize-delta merges the delta into design.md
-  # later. Runs in this context (shares vars + the technical sticky standards). The
-  # former standalone `cr` capture's design half now lives here.
-  - id: delta_design_module
-    condition: "{{design_mode}} == delta"
-    action: include
-    module: .appweaver/orchestrator/modules/delta-design.orch.yaml
-
-  # ═══════════ HANDOFF — authoring only; the gates are SEPARATE stages ═══════
-  # Design AUTHORS only.
-  #   • BOOTSTRAP → /appweaver analyze-design (spec↔design conformance gate) →
-  #     implement. No open change.
-  #   • DELTA → the change stays OPEN with a filled delta-design. Ship it via the CR
-  #     chain: /appweaver analyze-delta-design (delta-design ↔ delta-spec coherence)
-  #     → implement-delta (delta code + regression tests) → build (compile) →
-  #     finalize-delta (downstream fence, then merge the delta into spec.md + design.md;
-  #     the change stays OPEN) → analyze-slice (verify the slice against the merged
-  #     master) → close-delta (archive the change, bump the minor version).
-
-  # 6. Post-execution hooks.
-  - id: resolve_post_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "after_design"]
-    outputs:
-      - { name: after_hooks, from: "$.hooks" }
-  - id: dispatch_post_hooks
-    action: dispatch_hooks
-    hooks_from_variable: after_hooks
-
-outputs:
-  feature_dir: "{{feature_dir}}"
-  design_doc: "{{design_doc}}"
-  version: "{{version}}"
-  active_change: "{{active_change}}"
-  next: "BOOTSTRAP (new design.md): /appweaver analyze-design (spec↔design gate) → implement. DELTA (change {{active_change}} open, delta-design authored): /appweaver analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta (finalize-delta merges the delta into spec.md + design.md but leaves the change open; analyze-slice verifies the slice against the merged master; close-delta archives the change and bumps the minor version)."