aw-spec-cli 0.1.8 → 0.1.9

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

@@ -0,0 +1,727 @@
+# =============================================================================
+# aw-spec-constitution (orchestrator) — create/update the SPLIT project constitution
+#
+# Authors up to THREE files. Each ratifies its own MAPPED rule set. The two maps live in
+# the ACTIVE PROJECT (guardrails/projects/<project>/); the files they list live in the
+# shared corpora (guardrails/technology/<stack>/, guardrails/domain/<industry>/), except
+# the three the project's own team authors:
+#   .appweaver/memory/constitution.technical.md  ← "## /aw-spec-constitution" in
+#       tech-rule-bindings.md: the stack corpus's technology-constitution.md + its
+#       standard technical rules + the project's service/technical-requirements.md.
+#       The technology base's own principle set, domain-agnostic. STANDING input to
+#       DESIGN + IMPLEMENT (not specify).
+#   .appweaver/memory/constitution.ui.md         ← "## /aw-spec-ui-constitution" in
+#       tech-rule-bindings.md: the lane corpus's ui-constitution.md + the project's
+#       frontend/ui-requirements.md. The FRONTEND LANE's base (UX-*), domain-agnostic
+#       too. Standing input to UI-DESIGN + UI-IMPLEMENT. Authored ONLY where a
+#       frontend lane exists; otherwise not even created.
+#   .appweaver/memory/constitution.domain.md     ← "## /aw-spec-constitution" in
+#       domain-rule-bindings.md: the industry corpus's domain-constitution.md + its
+#       standard industry rules + the project's domain/domain-requirements.md. Its
+#       principles RESUME the technical half's numbering from wherever that half ended —
+#       the boundary is derived per project, never a fixed number, because a technology
+#       base may carry any number of principles.
+#       SPECIFY-only + gate checklist; deliberately NOT loaded by design/implement.
+# A deterministic `compose-constitution` then concatenates the authored halves into
+# .appweaver/memory/constitution.md (human/compat view only; the pipeline loads the
+# halves directly).
+#
+# SOURCES ARE MAPPED, NEVER HARDCODED. Each authoring step's `context:` is exactly the
+# half it is filling — no extra document, no hardcoded workspace path, nothing the two
+# maps do not list. Its sources arrive in the sticky standards, which each set's
+# tech-select / domain-select include appends to. Each set is the same shape: the tier's
+# constitution, then the STANDARD rules the mapped corpus shares, then the
+# ONE file the project team supplies (that last one optional — a project that has not
+# authored it ratifies the standard set alone). Changing what a half ratifies is a MAP
+# edit, never a workflow edit.
+#
+# The standards set is CUMULATIVE — load_standards appends and nothing clears it — so a
+# later half also carries the earlier halves' rules: technical sees 1 set, UI sees 2,
+# domain sees 3. That is why the seam is stated as a one-way ordering rule and not as
+# per-step scoping: what matters is that NO DOMAIN file can reach the two domain-free
+# halves, and domain-select running last is what guarantees it. Each `task:` names the
+# set that half may draw on, and the two domain-free halves are told to stand alone
+# rather than cite each other.
+#
+# WHY SPLIT: the old single constitution embedded the domain (principles XVI–XX)
+# and was standing input to every phase — a domain side-channel into design that
+# broke "design's only domain input is the spec." Splitting keeps design/implement
+# domain-free while specify still gets the full picture.
+#
+# The seam is enforced by ORDER: both domain-free halves are authored BEFORE
+# domain-select runs, so their context can never contain a domain file. The domain
+# half is authored after, from the mapped industry corpus's own constitution source. The UI half
+# sits between them for exactly that reason — it is the frontend lane's counterpart
+# to the technical base, not a third tier of governance, so the same seam has to
+# hold for it.
+#
+# WHEN THE UI HALF IS AUTHORED. Three independent signals, any one of which is
+# enough, checked in `ui_probe` + `ui_tech_select` below:
+#   1. RULES — the active project maps `## /aw-spec-ui-constitution`. Authoritative,
+#      and the only signal that also SUPPLIES the lane's rules.
+#   2. DECLARATION — a frontend lane in .appweaver/stacks.json.
+#   3. REQUEST — the invocation names a UI stack ("… react …").
+# None of them is REQUIRED, so no ordering constraint is created: a project whose
+# project carries the headings gets its UI half whether or not select-stack ever ran.
+# With none of them present the half is SKIPPED with a warning naming all three
+# fixes — never an error, because a backend-only project is the common case and
+# must behave exactly as it did before the lane model existed.
+#
+# Each authored half is then linted by the deterministic `constitution-verify`
+# SCRIPT (residual [ALL_CAPS] placeholders, body-vs-report version, ISO dates) with
+# a bounded self-correction loop (max 3) — so the whole skill works under every
+# strategy (sdk/sdk-apply/spawn/agent), --checkpoint, or headless.
+#
+# NOT part of the per-feature pipeline. Project-level, run-once / amend-on-change.
+#
+# Launch:  /appweaver constitution [strategy] [principles or values…]
+# Action semantics: .appweaver/ORCH-DIALECT.md
+# =============================================================================
+
+name: aw-spec-constitution
+description: Create or update the split project constitution — constitution.technical.md (technology base) + constitution.ui.md (the frontend lane's base, only where a lane exists) + constitution.domain.md (active domain addenda), each version-bumped with a Sync Impact Report, then composed into constitution.md. Project-level, run-once/amend — not a per-feature phase.
+version: 2.4.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Principles or values for the project constitution (optional).
+    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 technology-
+# constitution base the TECHNICAL half ratifies is no longer hardcoded here — it is now
+# CONFIGURATION, loaded per-command from guardrails/projects/<project>/tech-rule-bindings.md
+# under "## /aw-spec-constitution" by the tech-select module (see the tech_select step
+# below). tech_select runs BEFORE the technical half AND before domain-select, so the
+# technical author still sees only the technology base + ai-rules — NO domain file: the
+# seam is preserved. The constitution OUTPUT files (constitution.technical.md /
+# constitution.ui.md / constitution.domain.md) are referred to directly elsewhere,
+# never mapped. (missing skipped)
+standards:
+  - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
+
+vars:
+  technical_ok: "false"   # technical-half validation-loop guard, flipped by constitution-verify
+  domain_ok: "false"      # domain-half validation-loop guard, flipped by constitution-verify
+  ui_ok: "false"          # UI-half validation-loop guard, flipped by constitution-verify
+  ui_lane: "false"        # set by the three-signal probe below; gates the whole UI block
+
+workflow:
+
+  # 0a. WHICH LANES DOES THIS PROJECT HAVE. The declaration in .appweaver/stacks.json is
+  #     the answer, and it answers for BOTH halves: a half is a lane's standing
+  #     governance, so a lane the project declined gets no half and no file. That is
+  #     what makes `(none)` in select-stack a real declaration rather than a shrug.
+  #
+  #     --allow-missing-root because nothing here reads the subtree: constitution
+  #     ratifies rules, and a greenfield project's source path does not exist until
+  #     implement creates it. The on-disk check belongs to the phases that read code.
+  - id: lane_model
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-verify
+    args: ["--allow-missing-root", "--command", "/appweaver constitution"]
+    outputs:
+      - { name: lane_model_ok,      from: "$.ok" }
+      - { name: lane_model_issues,  from: "$.message" }
+      - { name: lane_kinds,         from: "$.kinds" }
+      - { name: be_lane_declared,   from: "$.backend_declared" }
+      - { name: be_lane_id,         from: "$.backend_lane_id" }
+      - { name: be_lane_profile,    from: "$.backend_profile" }
+      - { name: be_lane_root,       from: "$.backend_source_path" }
+      - { name: fe_lane_declared,   from: "$.frontend_declared" }
+      - { name: fe_lane_id,         from: "$.frontend_lane_id" }
+      - { name: fe_lane_profile,    from: "$.frontend_profile" }
+      - { name: fe_lane_root,       from: "$.frontend_source_path" }
+
+  - id: lane_model_gate
+    action: verify_context
+    require_true: lane_model_ok
+    on_false: stop
+    on_false_message: >
+      /appweaver constitution cannot run: {{lane_model_issues}}
+      Which lanes a project has decides which constitution halves it ratifies, so the
+      declaration has to exist before the halves are authored. Run
+      /appweaver select-stack first — it is the first command of both the greenfield
+      and the brownfield sequence.
+
+  - id: lane_kinds_gate
+    action: verify_context
+    require_non_empty: lane_kinds
+    on_empty: stop
+    on_empty_message: >
+      No lane is declared — .appweaver/stacks.json exists but declares neither a service
+      nor a UI lane, so there is nothing for a constitution to govern. Re-run
+      /appweaver select-stack and declare at least one lane.
+
+  # 0b. Does the SERVICE lane exist? The technical half is that lane's standing
+  #     authority — the base loaded by design and implement — so a project that
+  #     declared no service lane authors no technical half and no service rules.
+  #     Ordered override rather than a branch: the engine has no boolean expressions,
+  #     so state the declined case and let the declaration turn it back on.
+  #     `setup_tech_flag` carries the decision to EVERY setup-constitution call in this
+  #     workflow, the UI one included: that command creates the always-present halves as
+  #     a side effect of whatever else it is asked to do, so a later call without the
+  #     flag silently recreates the half an earlier call was told to skip.
+  - id: svc_lane_absent
+    action: set
+    vars: { svc_lane: "false", setup_tech_flag: "--no-technical" }
+  - id: svc_lane_declared
+    action: set
+    condition: "{{be_lane_declared}}"
+    vars: { svc_lane: "true", setup_tech_flag: "" }
+
+  # 0. TECHNICAL rule files → sticky standards (configuration, not hardcoded). tech-select
+  #    reads guardrails/projects/<project>/tech-rule-bindings.md under "## /aw-spec-constitution"
+  #    and loads the technology-constitution base into the sticky standards the TECHNICAL
+  #    half ratifies. Placed FIRST — before the technical half AND before domain-select — so
+  #    the technical author sees only technical files: the seam that keeps it domain-free is
+  #    preserved. No blocking gate: an unconfigured project soft-continues (ai-rules seed only).
+  - id: tech_select
+    action: include
+    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-constitution }
+
+  # 1. Ensure the halves this project's LANES call for exist (copy each template in if
+  #    missing). Rewrite-in-place only — never creates a second template. The domain
+  #    half is always created: domain is not a lane, it addends whichever halves the
+  #    project has. The UI half is created on demand at step 11, and the technical half
+  #    is skipped outright where no service lane was declared — an unauthored template
+  #    left in memory/ is indistinguishable from a half somebody forgot to fill in.
+  #    Composed constitution.md is produced later by compose-constitution.
+  - id: setup_constitution
+    action: execute_script
+    script: { ref: actions }
+    subcommand: setup-constitution
+    args: ["{{setup_tech_flag}}"]
+    outputs:
+      - { name: constitution_technical_file, from: "$.constitution_technical_file" }
+      - { name: constitution_domain_file,    from: "$.constitution_domain_file" }
+      - { name: technical_created,           from: "$.technical_created" }
+      - { name: domain_created,              from: "$.domain_created" }
+
+  # 1b. No service lane ⇒ nothing for the technical validation loop to check, so its
+  #     guard is satisfied rather than left at its "not yet verified" default. A false
+  #     here would report a half that was deliberately not authored as one that failed
+  #     to validate.
+  - id: technical_skipped
+    action: set
+    condition: "{{svc_lane}} == false"
+    vars: { technical_ok: "true" }
+
+  - id: svc_lane_warning
+    action: verify_context
+    require_true: svc_lane
+    on_false: continue
+    on_false_message: >
+      No service lane in .appweaver/stacks.json — skipping the TECHNICAL constitution half
+      (constitution.technical.md is not created). This is the correct outcome for a
+      UI-only project: the technical half is the service lane's standing authority, read
+      by design and implement, and neither runs here. The domain half opens the
+      roman-numeral sequence at I instead of continuing one. To author it, run
+      /appweaver select-stack and declare a backend stack, then re-run.
+
+  # 2. Pre-execution hooks: resolve (script) then dispatch (invoking agent).
+  - id: resolve_pre_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_constitution"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    hooks_from_variable: before_hooks
+
+  # ── TECHNICAL HALF ─────────────────────────────────────────────────────────
+  # Authored FIRST, while the sticky set holds only the technology base + ai-rules
+  # (domain-select has not run yet). This ordering is what guarantees the technical
+  # constitution is domain-free.
+
+  # 3. Context: the technical half being filled / amended, and nothing else. Its
+  #    sources arrive as MAPPED rule files in the sticky standards from step 0. Every
+  #    half is authored this way: the target file plus its mapped set, never a doc the
+  #    map does not list.
+  - id: gen_technical_ctx
+    action: build_context
+    condition: "{{svc_lane}} == true"
+    context:
+      - { path: "{{constitution_technical_file}}" }
+
+  # 4. Author the TECHNICAL constitution (rewrite-in-place).
+  - id: gen_technical
+    action: agent_author
+    condition: "{{svc_lane}} == true"
+    output_target: { type: file, path: "{{constitution_technical_file}}" }
+    task: |
+      Update the TECHNICAL project constitution (the target file in context). It is
+      a TEMPLATE with [ALL_CAPS] placeholder tokens. This is the domain-AGNOSTIC half.
+      Principles/values supplied by the user: {{USER_INPUT}}
+      Steps:
+      - Fill EVERY placeholder with concrete text; leave no unexplained [BRACKET]
+        tokens (justify any intentionally deferred as TODO(<FIELD>): reason).
+      - Derive values from the technical rule files in the standards — the set the active
+        project maps for this command: its technology base, the standard technical rules, and
+        the project team's own technical-requirements — plus the user input, ai-rules and
+        repo context. Where the project file and a standard rule disagree, the project file
+        is the DEVIATION and MUST be ratified as one, naming the rule it departs from and
+        who approved it. Do NOT invent principles, and do NOT reach for a rule file the map
+        did not supply. If NO technical rule file was loaded, say so in the Sync Impact
+        Report and keep the principles to what the user input and repo context actually
+        support: a thin, honest half a later run can extend is correct, an invented one is
+        not.
+      - Author ONLY technology-base principles — the base's FULL set, as many as it
+        defines and no more — plus base folder structure,
+        base conventions/AI rules, and base governance. The count is whatever the mapped
+        technology base carries: do not pad the list to reach a familiar length, and do
+        not stop short of its last principle. Number them consecutively from I, and note
+        the final number in the Sync Impact Report — the domain half resumes from there.
+        Do NOT add any domain-specific
+        principle, identifier, terminology, regulatory, or interoperability rule — those
+        belong to the paired constitution.domain.md and MUST NOT appear here.
+      - Bump CONSTITUTION_VERSION by semver (MAJOR incompatible; MINOR new/expanded;
+        PATCH clarifications). This half versions independently of the domain half.
+      - Dates ISO YYYY-MM-DD: RATIFICATION_DATE = original adoption (TODO if unknown);
+        LAST_AMENDED_DATE = today when changed.
+      - Preserve heading hierarchy exactly. Principles declarative and testable.
+      - PREPEND a "Sync Impact Report" as an HTML comment at the very top: version
+        old→new, modified/added/removed principles, dependent artifacts (✅/⚠) + TODOs.
+      Return the complete updated technical constitution content only.
+
+  # 5. Deterministic validation loop for the technical half (max 3 patch passes).
+  - id: technical_validation_loop
+    action: loop
+    condition: "{{svc_lane}} == true"
+    while: "{{technical_ok}} != true"
+    max_iterations: 3
+    steps:
+      - id: tech_lint
+        action: execute_script
+        script: { ref: actions }
+        subcommand: constitution-verify
+        args: ["--file", "{{constitution_technical_file}}"]
+        outputs:
+          - { name: technical_ok,     from: "$.ok" }
+          - { name: technical_issues, from: "$.issues" }
+      - id: tech_lint_break
+        action: break
+        condition: "{{technical_ok}} == true"
+      - id: patch_technical
+        action: agent_author
+        context: ["{{constitution_technical_file}}"]
+        include_standards: false        # rewrite-in-place: only the technical half
+        output_target: { type: file, path: "{{constitution_technical_file}}" }
+        task: |
+          Fix these mechanical defects in the technical constitution (target file in
+          context), changing NOTHING else — preserve every principle, the heading
+          hierarchy, and the Sync Impact Report. Fill any listed [ALL_CAPS] placeholder
+          with concrete text (or a justified TODO(<FIELD>): reason); make the body's
+          version line AGREE with the Sync Impact Report's new version; ISO YYYY-MM-DD dates.
+          Defects: {{technical_issues}}
+          Return the complete updated technical constitution content only.
+
+  # ── UI HALF (frontend lane only) ───────────────────────────────────────────
+  # Placed HERE deliberately: AFTER the technical half, so the lane's rule files
+  # cannot leak into it, and BEFORE domain-select, so no domain file can leak into
+  # this one. The UI half is the frontend lane's counterpart to the technical base
+  # and has to be domain-free for the same reason — domain reaches the UI lane
+  # through the spec, exactly as it reaches the service lane.
+
+  # 6. Clear the shared module's mode before re-entering it. tech-select keeps its
+  #    tg_* vars in the caller's scope, so a stale `all` from the step-0 include
+  #    would otherwise survive into a run where no UI selection box ever appears.
+  - id: ui_tech_reset
+    action: set
+    vars: { tg_mode: "" }
+
+  # 7. THE UI LANE'S RULES. The project's `## /aw-spec-ui-constitution` heading
+  #    supplies what governs the lane; empty candidates ⇒ tech-select soft-continues
+  #    and nothing is loaded, the same no-map path an unconfigured project takes.
+  #
+  #    It no longer decides that the lane EXISTS. That question was answered by three
+  #    OR'd heuristics — this heading, a frontend lane in stacks.json, and a UI stack
+  #    named in the request — and a heuristic OR can only ever turn the half ON. It had
+  #    no way to express "this project has no UI", so a stale heading or the word
+  #    "react" in a request authored a ratified governance file for a lane that does not
+  #    exist. The declaration answers in both directions, which is why it is now the
+  #    only signal read: a project that answered `(none)` in select-stack has answered,
+  #    and it is the same file build, implement and onboard are held to.
+  - id: ui_tech_select
+    action: include
+    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-ui-constitution }
+  - id: ui_rule_signal
+    action: set
+    vars: { ui_rule_files: "{{tg_candidates}}" }
+
+  # 8. The lane, from the declaration. Ordered override rather than a branch: the
+  #    engine has no conditional binding, so state the declined case and let a declared
+  #    frontend lane turn it on.
+  - id: ui_lane_absent
+    action: set
+    vars:
+      ui_lane: "false"
+      ui_stack: ""
+      ui_evidence: ""
+  - id: ui_lane_declared
+    action: set
+    condition: "{{fe_lane_declared}}"
+    vars:
+      ui_lane: "true"
+      ui_stack: "{{fe_lane_profile}}"
+      ui_evidence: "lane '{{fe_lane_id}}' ({{fe_lane_profile}}) is declared in .appweaver/stacks.json, owning the source path {{fe_lane_root}}"
+
+  # 9. A mapped UI rule set with no lane to govern. Not fatal and not a reason to
+  #    author the half — the declaration decides that — but worth saying out loud,
+  #    because the two most likely causes have opposite fixes: a lane that was retired
+  #    and left its mapping behind, or a lane somebody forgot to declare.
+  - id: ui_rules_orphan_warning
+    action: verify_context
+    require_true: ui_lane
+    on_false: continue
+    on_false_message: >
+      The active project maps ## /aw-spec-ui-constitution to {{ui_rule_files}}, but no
+      frontend lane is declared in .appweaver/stacks.json — those rules govern nothing and
+      the UI half is NOT authored. Either run /appweaver select-stack and declare the
+      UI lane, or drop the mapping if the lane was retired.
+    condition: "{{ui_rule_files}}"
+
+  # 10. No UI lane ⇒ WARN and skip. Never an error: a backend-only project is the
+  #     common case, and no UI half is authored and no file created. Gated on the empty
+  #     evidence string rather than on ui_lane, because require_true logs "gate failed"
+  #     and this is a soft path, not a failure.
+  - id: ui_lane_warning
+    action: verify_context
+    require_non_empty: ui_evidence
+    on_empty: continue
+    on_empty_message: >
+      No frontend lane in .appweaver/stacks.json — skipping the UI constitution half
+      (constitution.ui.md is not created). This is the expected path for a backend-only
+      project. To author it, run `/appweaver select-stack`, pick a UI stack and give
+      it a source path, then re-run `/appweaver constitution`. Mapping
+      `## /aw-spec-ui-constitution` in guardrails/projects/<project>/tech-rule-bindings.md
+      supplies the rules that half ratifies, but no longer creates the lane on its own —
+      a lane exists because the project declared it.
+
+  # 11. Create the UI half from its template — on demand, unlike the other two.
+  #     Its ABSENCE is meaningful, so a project with no lane never gets the file.
+  - id: setup_ui_constitution
+    action: execute_script
+    condition: "{{ui_lane}} == true"
+    script: { ref: actions }
+    subcommand: setup-constitution
+    args: ["--ui", "{{setup_tech_flag}}"]
+    outputs:
+      - { name: constitution_ui_file, from: "$.constitution_ui_file" }
+      - { name: ui_created,           from: "$.ui_created" }
+
+  # 12. Context for the UI half: the file being filled/amended, and nothing else. The
+  #     lane's UI rule set arrives as mapped rule files in the sticky standards from
+  #     step 7 — including its declared lane, stack and root, so the Declared Lane
+  #     section is authored from the mapping rather than inferred.
+  - id: gen_ui_ctx
+    action: build_context
+    condition: "{{ui_lane}} == true"
+    context:
+      - { path: "{{constitution_ui_file}}" }
+
+  # 13. Author the UI constitution (rewrite-in-place).
+  - id: gen_ui
+    action: agent_author
+    condition: "{{ui_lane}} == true"
+    output_target: { type: file, path: "{{constitution_ui_file}}" }
+    task: |
+      Update the USER EXPERIENCE constitution — the FRONTEND LANE's half (the target
+      file in context). It is a TEMPLATE with [ALL_CAPS] placeholder tokens. This half
+      is domain-AGNOSTIC, like the technical base it runs parallel to.
+      Principles/values supplied by the user: {{USER_INPUT}}
+      Why this lane was detected: {{ui_evidence}}
+      Declared UI stack (may be empty): {{ui_stack}}
+      Steps:
+      - Fill EVERY placeholder with concrete text; leave no unexplained [BRACKET]
+        tokens (justify any intentionally deferred as TODO(<FIELD>): reason).
+      - Derive values from the UI rule files in the standards — the set the active project
+        maps for this command: its frontend base and the project team's own
+        ui-requirements — plus the user input, the declared stack and repo context. Where
+        the project file and a standard rule disagree, the project file is the DEVIATION
+        and MUST be ratified as one, naming the principle it departs from and who approved
+        it. The technical rule files are also in the standards because the set is
+        cumulative; they belong to the OTHER lane and are NOT a source for this half. Do
+        NOT invent principles. If NO UI rule file was loaded, say so in the Sync Impact
+        Report and keep the principles to what the user input and the declared stack
+        actually support: a thin, honest half that a later run can extend is correct, an
+        invented one is not.
+      - Number the principles as a UX-* series (UX-I, UX-II, …). Do NOT continue the
+        technical half's numbering or the domain half's — this half is parallel to
+        the technical base, not a continuation of it, and its series is therefore
+        unaffected by how many principles that base carries.
+      - Author ONLY experience/frontend-lane material: accessibility, design system,
+        interaction states, client data + cache policy, performance budget,
+        internationalization, the lane's folder structure under its own root, and
+        the lane's quality gates. This half stands ALONE as the frontend lane's base:
+        it neither restates the service lane's principles nor cites them by number.
+        Add NO domain-specific principle, identifier, terminology or regulatory rule
+        — those belong to constitution.domain.md.
+      - Keep every path under the lane's own root. This half never adds to the
+        service lane's folder structure.
+      - Bump CONSTITUTION_VERSION by semver (MAJOR incompatible; MINOR new/expanded;
+        PATCH clarifications). This half versions independently of the other two.
+      - Dates ISO YYYY-MM-DD: RATIFICATION_DATE = original adoption (TODO if unknown);
+        LAST_AMENDED_DATE = today when changed.
+      - Preserve heading hierarchy exactly. Principles declarative and testable.
+      - PREPEND a "Sync Impact Report" as an HTML comment at the very top: version
+        old→new, modified/added/removed principles, dependent artifacts (✅/⚠) + TODOs.
+      Return the complete updated UI constitution content only.
+
+  # 14. Deterministic validation loop for the UI half (max 3 patch passes).
+  - id: ui_validation_loop
+    action: loop
+    condition: "{{ui_lane}} == true"
+    while: "{{ui_ok}} != true"
+    max_iterations: 3
+    steps:
+      - id: ui_lint
+        action: execute_script
+        script: { ref: actions }
+        subcommand: constitution-verify
+        args: ["--file", "{{constitution_ui_file}}"]
+        outputs:
+          - { name: ui_ok,     from: "$.ok" }
+          - { name: ui_issues, from: "$.issues" }
+      - id: ui_lint_break
+        action: break
+        condition: "{{ui_ok}} == true"
+      - id: patch_ui
+        action: agent_author
+        context: ["{{constitution_ui_file}}"]
+        include_standards: false        # rewrite-in-place: only the UI half
+        output_target: { type: file, path: "{{constitution_ui_file}}" }
+        task: |
+          Fix these mechanical defects in the UI constitution (target file in context),
+          changing NOTHING else — preserve every principle, the UX-* numbering, the
+          heading hierarchy, and the Sync Impact Report. Fill any listed [ALL_CAPS]
+          placeholder with concrete text (or a justified TODO(<FIELD>): reason); make the
+          body's version line AGREE with the Sync Impact Report's new version;
+          ISO YYYY-MM-DD dates.
+          Defects: {{ui_issues}}
+          Return the complete updated UI constitution content only.
+
+  # ── DOMAIN HALF ────────────────────────────────────────────────────────────
+  # 15. Resolve the active domain + load its rule files into the sticky set (D3).
+  #    Gate Continue/Exit when no domain/domain-rule-bindings; then Select all/subset/none.
+  #    Runs AFTER the technical half is done, so it cannot leak into it.
+  - id: domain_select
+    action: include
+    module: .appweaver/orchestrator/modules/domain-select.orch.yaml
+    with: { command: aw-spec-constitution }
+
+  # 16. Context for the domain half: the file being filled/amended, and nothing else.
+  #    Its sources are the project's domain constitution set, which domain-select has just
+  #    put into the sticky standards. Skipped when no active domain.
+  - id: gen_domain_ctx
+    action: build_context
+    condition: "{{dg_rulemap_exists}} == true"
+    context:
+      - { path: "{{constitution_domain_file}}" }
+      # The authored technical half, for its NUMBERING only. The domain principles
+      # resume from the number after its last one, and that number is a property of
+      # the mapped technology base — a base with eight principles ends at VIII, one
+      # with twenty ends at XX — so it cannot be stated as a constant here. Optional:
+      # a run whose technical half was skipped still authors the domain half, and the
+      # task text says what to do when this file is absent. It is NOT a content source;
+      # the domain half never restates a technical principle.
+      - { path: "{{constitution_technical_file}}", optional: true }
+
+  # 17. Author the DOMAIN addenda (rewrite-in-place). Only when a domain is active.
+  - id: gen_domain
+    action: agent_author
+    condition: "{{dg_rulemap_exists}} == true"
+    output_target: { type: file, path: "{{constitution_domain_file}}" }
+    task: |
+      Update the DOMAIN ADDENDA constitution for domain '{{domain}}' (the target file
+      in context). It is a TEMPLATE with [ALL_CAPS] placeholder tokens. This half carries
+      ONLY domain-specific material. Principles/values supplied by the user: {{USER_INPUT}}
+      Steps:
+      - Fill EVERY placeholder with concrete text; leave no unexplained [BRACKET] tokens
+        (justify deferrals as TODO(<FIELD>): reason). NO residual placeholder may remain.
+      - Derive values from the domain rule files in the standards — the set the active project
+        maps for this command: its domain constitution, the standard industry rules, and the
+        project team's own domain-requirements (optional; a project may not have authored it).
+        Where the project file and a standard rule disagree, the project file is the DEVIATION
+        and MUST be ratified as one, naming the rule it departs from and who approved it. The
+        technical and frontend rule files are also in the standards because the set is
+        cumulative; they are the OTHER halves' sources and NOT a source for this one. Do NOT
+        invent principles, and do NOT reach for a rule file the map did not supply. If NO
+        domain rule file was loaded, say so in the Sync Impact Report and keep the principles
+        to what the user input actually supports.
+      - Author ONLY the domain layer: the adopted modelling standard, the domain
+        principles, domain folder additions, regulatory posture & security addenda, and
+        domain governance overrides. For each domain principle, state which technical
+        principle it EXTENDS. Do NOT restate the technical half's principles or the base
+        governance — reference them. Where constitution.technical.md is absent from
+        context the project declared no service lane and there is no technical half to
+        extend: state each principle on its own terms and say so in the Sync Impact
+        Report, rather than naming a principle that does not exist.
+      - ADOPTED MODELLING STANDARD: name the methodology the technical half actually
+        mandates and cite that principle BY ITS ACTUAL NUMERAL, read from
+        constitution.technical.md in context. The numeral is a property of THIS project's
+        technology base — never a fixed value carried over from another constitution. If
+        the technical half mandates no modelling methodology — or is absent because the
+        project declared no service lane — say so plainly rather than supplying one;
+        specify loads this file and not the technical half, so whatever this section
+        claims is what specify will treat as ratified.
+      - NUMBER the domain principles by RESUMING the technical half's series. Read
+        constitution.technical.md in context, find its LAST principle number, and start
+        at the next one: a technical half ending at XII starts the domain at XIII, one
+        ending at XX starts it at XXI. Do NOT assume XVI — that is only where the
+        shipped sample corpora happen to land, and a project's technology base may define
+        any number of principles. Numbering must run unbroken across the two halves:
+        no gap, no restart, and NO number used by both. If constitution.technical.md is
+        absent from context, say so in the Sync Impact Report and start the domain
+        principles at I, so the gap is visible rather than silently guessed.
+      - Bump CONSTITUTION_VERSION by semver; this half versions independently of the
+        technical half. Dates ISO YYYY-MM-DD.
+      - Preserve heading hierarchy exactly. PREPEND a "Sync Impact Report" HTML comment:
+        version old→new, changed domain principles, dependent artifacts (✅/⚠) + TODOs.
+      Return the complete updated domain addenda content only.
+
+  # 18. Deterministic validation loop for the domain half (max 3). Skipped if no domain.
+  - id: domain_validation_loop
+    action: loop
+    condition: "{{dg_rulemap_exists}} == true"
+    while: "{{domain_ok}} != true"
+    max_iterations: 3
+    steps:
+      - id: dom_lint
+        action: execute_script
+        script: { ref: actions }
+        subcommand: constitution-verify
+        args: ["--file", "{{constitution_domain_file}}"]
+        outputs:
+          - { name: domain_ok,     from: "$.ok" }
+          - { name: domain_issues, from: "$.issues" }
+      - id: dom_lint_break
+        action: break
+        condition: "{{domain_ok}} == true"
+      - id: patch_domain
+        action: agent_author
+        context: ["{{constitution_domain_file}}"]
+        include_standards: false        # rewrite-in-place: only the domain half
+        output_target: { type: file, path: "{{constitution_domain_file}}" }
+        task: |
+          Fix these mechanical defects in the domain addenda constitution (target file in
+          context), changing NOTHING else — preserve every principle, the heading hierarchy,
+          and the Sync Impact Report. Fill any listed [ALL_CAPS] placeholder (or a justified
+          TODO(<FIELD>): reason); make the body version AGREE with the Sync Impact Report;
+          ISO YYYY-MM-DD dates.
+          Defects: {{domain_issues}}
+          Return the complete updated domain addenda content only.
+
+  # 19. Compose the authored halves into the human/compat constitution.md (deterministic).
+  #     Order technical → domain → ui. Any half that is missing or still an unauthored
+  #     template is skipped, so this needs no conditions of its own.
+  - id: compose_constitution
+    action: execute_script
+    script: { ref: actions }
+    subcommand: compose-constitution
+    outputs:
+      - { name: composed_file,     from: "$.composed_file" }
+      - { name: domain_included,   from: "$.domain_included" }
+      - { name: ui_included,       from: "$.ui_included" }
+      - { name: numbering_ok,      from: "$.numbering_ok" }
+      - { name: numbering_issues,  from: "$.issues" }
+      - { name: technical_last,    from: "$.technical_last" }
+      - { name: domain_first,      from: "$.domain_first" }
+
+  # 19b. Numbering gate. Composition is the only place both roman-numeral halves are
+  #      read together, so it is where a collision between them surfaces. Announce and
+  #      continue: the halves are authored and the composed view shows the clash, which
+  #      is what the reader needs to fix it — deleting that would help nobody.
+  #      Ordered override: the var holds "ok" unless the check reported a problem,
+  #      because require_non_empty reports on EMPTY.
+  - id: numbering_default
+    action: set
+    vars: { numbering_gate: "ok" }
+  - id: numbering_detect
+    action: set
+    condition: "{{numbering_ok}} == false"
+    vars: { numbering_gate: "" }
+  - id: numbering_warning
+    action: verify_context
+    require_non_empty: numbering_gate
+    on_empty: continue
+    on_empty_message: >
+      Principle numbering does not run cleanly across the halves: {{numbering_issues}}
+      (technical half ends at {{technical_last}}, domain half starts at {{domain_first}}).
+      The domain half must resume at the number FOLLOWING the technical half's last
+      principle — that boundary is a property of the mapped technology base, not a fixed
+      value, so a base of any length is legal and only the continuation matters. Renumber
+      the domain half in .appweaver/memory/constitution.domain.md and re-run; the composed
+      constitution.md was still written so the clash is visible.
+
+  # 20. A UI half composed in on a run that found no lane means the lane was retired
+  #     after the half was authored. Warn, and change nothing: a ratified governance
+  #     file is never deleted automatically, and retiring a lane is a decision.
+  #     Ordered override again, inverted — the var holds "ok" except on the stale path,
+  #     because require_non_empty reports on EMPTY.
+  - id: ui_stale_default
+    action: set
+    vars: { ui_stale_ok: "ok" }
+  - id: ui_stale_detect
+    action: set
+    condition: "{{ui_included}} == true"
+    vars: { ui_stale_ok: "" }
+  - id: ui_stale_clear
+    action: set
+    condition: "{{ui_lane}} == true"
+    vars: { ui_stale_ok: "ok" }
+  - id: ui_stale_warning
+    action: verify_context
+    require_non_empty: ui_stale_ok
+    on_empty: continue
+    on_empty_message: >
+      .appweaver/memory/constitution.ui.md exists and was composed into constitution.md,
+      but this run found no frontend lane — the lane was most likely retired after the
+      half was authored. Nothing was deleted: a ratified governance file is never
+      removed automatically. Delete that file by hand if the lane is gone for good and
+      re-run; otherwise restore the lane's signal.
+
+  # 21. Post-execution hooks.
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_constitution"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    hooks_from_variable: after_hooks
+
+outputs:
+  constitution_technical_file: "{{constitution_technical_file}}"
+  constitution_domain_file: "{{constitution_domain_file}}"
+  constitution_ui_file: "{{constitution_ui_file}}"
+  composed_file: "{{composed_file}}"
+  domain_included: "{{domain_included}}"
+  ui_included: "{{ui_included}}"
+  technical_validation_ok: "{{technical_ok}}"
+  technical_validation_issues: "{{technical_issues}}"
+  domain_validation_ok: "{{domain_ok}}"
+  domain_validation_issues: "{{domain_issues}}"
+  service_lane: "{{svc_lane}}"
+  service_lane_declared: "{{be_lane_id}} ({{be_lane_profile}}) at {{be_lane_root}}"
+  ui_lane: "{{ui_lane}}"
+  ui_lane_evidence: "{{ui_evidence}}"
+  ui_rule_files: "{{ui_rule_files}}"
+  ui_validation_ok: "{{ui_ok}}"
+  ui_validation_issues: "{{ui_issues}}"
+  note: "Split constitution authored, one half per LANE the project declared in .appweaver/stacks.json. service_lane / ui_lane report which lanes were found there, and the declaration is the ONLY signal read: a half is a lane's standing governance, so a lane declared `(none)` in select-stack gets no half AND no file. constitution.technical.md is the service lane's base (standing input to design + implement); constitution.ui.md is the UI lane's UX-* base (standing input to ui-design + ui-implement); constitution.domain.md is the domain addenda (standing input to specify + a gate checklist), and it is always authored because domain is not a lane — it addends whichever halves exist. All are composed into constitution.md, which now tolerates an absent technical half: a UI-only project's domain half opens the roman-numeral sequence at I instead of continuing one, and numbering_checked reports false because that check has no subject rather than because it silently passed. Mapping ## /aw-spec-ui-constitution supplies the rules the UI half ratifies but no longer creates the lane on its own — a mapped rule set with no declared lane produces a warning naming both fixes. ui_lane false with ui_included true means a lane was retired after its half was authored: the file is left alone and the log says so, because a ratified governance file is never deleted automatically. If a validation_ok is false, the matching validation_issues lists what still needs a manual touch. See each half's Sync Impact Report for its version bump. Suggested commit: 'docs: amend split constitution'."
+  next: "Loaded per concern — /appweaver specify loads constitution.domain.md; design + implement load constitution.technical.md; ui-design + ui-implement load constitution.ui.md. Re-run /appweaver constitution to amend, including to pick up a lane declared or dropped after this run — re-run /appweaver select-stack first to change which lanes exist."