aw-spec-cli 0.1.13 → 0.1.15

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

@@ -0,0 +1,688 @@
+# =============================================================================
+# aw-spec-plan (orchestrator) — the spec-anchored Plan phase (service lane)
+#
+# Authors and MAINTAINS one high-level plan per feature and lane. This workflow owns
+# the SERVICE lane's document — specs/<Aggregate>/backend-plan.md — the tech-agnostic
+# HLD that MEDIATES between the spec and the code (formerly design.md; the scaffold
+# migrates a legacy design.md by renaming it). The frontend lane's twin,
+# frontend-plan.md, is owned by /appweaver plan-ui — a SEPARATE command because the
+# two lanes are governed by different rule sets (tech-rule-bindings gives each lane
+# its own set; one command would hand this phase both lanes' whole rule surface).
+# `implement` GENERATES the code from spec + plan (model-driven, not a deterministic
+# extract). See .appweaver/DESIGN-FORMAT.md + .appweaver/templates/design-template.md.
+# (`plan` re-uses the name of a long-retired phase whose plan.md had zero consumers.)
+#
+# WHERE IT SITS. specify/sync-spec move the spec; the developer then runs plan, which
+# conforms this feature's design to what moved. Story designs (/appweaver story-plan)
+# READ this document for the ids they carry and NEVER write back — nothing merges into
+# it, so it keeps exactly one writer and cannot be silently rewritten. It is the
+# FEATURE-LEVEL ARCHITECTURAL CONFIRMATION: what the feature's structure IS to be,
+# tech-agnostic, with the concrete file-level work left to the per-story passes.
+#
+# IT READS THE CODE. concept-paths resolves the feature's OKF concept to the source
+# files realising it and the authoring steps declare `tools: Read`, so a plan over an
+# existing codebase ADJUSTS to the shape that is actually there. The code is the
+# what-exists authority; the spec stays the only authority on behaviour and the only
+# domain input. source_count 0 = greenfield, and the phase never blocks on it.
+#
+# IT PUBLISHES THE INTERFACES. The feature's published surface lives in
+# specs/<Aggregate>/interfaces.md — APPEND-ONLY, script-numbered (IF-nnn, dated,
+# status: proposed). This phase writes it and §3 of the plan cites the ids; /appweaver
+# plan-ui and the FE story designs CONSUME the latest entry per id. A changed interface
+# is a superseding entry, never an edit — one wording, one lifecycle, no second copy.
+#
+# THREE MODES, resolved deterministically (self-detecting on the plan doc's own
+# existence, symmetric with how specify keys off spec.md):
+#   • bootstrap_gf (default) — no backend-plan.md yet: author the master from the
+#     whole spec, four-layer greenfield template (Domain·Application·API·Infra).
+#   • bootstrap_bf — same, but onboard installed the code-derived design-template
+#     override: author with the project's AS-BUILT structure instead.
+#   • update — backend-plan.md exists: conform it to what the spec's Change History
+#     ledger says moved SINCE THIS PLAN WAS LAST DERIVED, and nothing else. This
+#     replaces the former delta-design branch (delta-design + finalize-delta merge);
+#     in the story flow the spec moves via sync-spec and the plan follows here.
+#
+# TRACKING (the lockstep made real). Every write ends with plan-stamp, which is the
+# only writer of the plan's version identity:
+#   • the doc's **Version** header := the spec version this plan now derives from,
+#   • an update appends the plan's own Change History row naming the conformed ids,
+#   • .aw-plan-track.backend-plan.json (beside the spec) records {spec_version,
+#     sha256} — one track file per plan document, so the two lanes never contend.
+# plan-check reads that record back: BEHIND (ledger rows above the derived version →
+# the exact ids to conform), EDITED (hash mismatch — the doc was hand-edited since
+# the stamp; refused unless accept_manual folds the edits in), UNTRACKED (a migrated
+# legacy design.md with no baseline — the update reconciles the WHOLE plan once and
+# baselines it). The model writes NO version anywhere; the script stamps.
+#
+# LANE-AWARE. Lanes come from .appweaver/stacks.json (select-stack declares them):
+#   • backend lane declared → author backend-plan.md. This is a REQUIREMENT, not a
+#     default: with no backend stack declared the phase stops and says so, because a
+#     service plan written against no declared service invents its own stack.
+#   • frontend lane also declared → the handoff names /appweaver plan-ui.
+#   • frontend-only, or nothing declared at all → stop, each with its own message.
+#
+# AUTHORS only — the gates are SEPARATE stages: /appweaver analyze-design proves
+# spec ↔ plan conformance after every bootstrap AND every update.
+#
+# Launch:  /appweaver plan [guidance]           (accept_manual:true folds hand edits in)
+# Prereq:  /appweaver specify
+# =============================================================================
+
+name: aw-spec-plan
+description: "Author or update the service lane's high-level plan — specs/<Feature>/backend-plan.md — from the spec. Self-detects: no plan yet ⇒ bootstrap the master (greenfield four-layer template, or the code-derived structure when onboard installed the design-template override); plan exists ⇒ UPDATE — conform exactly the sections serving the ids the spec's Change History moved since this plan's derivation stamp, preserving the Assumptions/Workarounds/Change History ledgers. Tracking is script-owned: plan-stamp moves the **Version** header to the derived spec version, appends the plan's history row and records the body hash; plan-check refuses hand-edited documents unless accept_manual folds them in. Reads the CODE as well as the spec (concept-paths + tools: Read), so a plan over an existing codebase conforms to the as-built shape; the spec remains the only domain and behaviour authority. Publishes the feature's PUBLISHED SURFACE to the append-only interfaces.md (script-assigned IF-nnn, status: proposed) — the anchor /appweaver plan-ui and the FE story designs consume; the plan's API section cites those ids rather than restating the contract. Lane-aware via stacks.json — a declared frontend lane routes its twin to /appweaver plan-ui; frontend-only projects are refused. Authoring only — gate every write at /appweaver analyze-design."
+version: 4.1.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional plan guidance (architectural constraints, trade-off preferences).
+    required: false
+    bind: USER_INPUT
+  accept_manual:
+    description: "true ⇒ a hand-edited plan (tracking state edited/edited_behind) is folded in instead of refused: the update keeps the manual edits' intent, reconciles them with the spec, and the stamp re-baselines."
+    required: false
+    bind: ACCEPT_MANUAL
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+  xref:
+    sh:  .appweaver/scripts/bash/aw-xref.sh
+    ps1: .appweaver/scripts/powershell/aw-xref.ps1
+
+# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The TECHNICAL/
+# architecture rule files are CONFIGURATION, loaded per-command from
+# guardrails/projects/<project>/tech-rule-bindings.md under "## /aw-spec-plan" by the
+# tech-select module. No domain rule file is loaded here — domain reaches the plan
+# solely as spec ids (BR-/CN-/DC-/IC-). The technology base itself arrives via
+# constitution.technical.md (referred to directly, as-is — NOT mapped).
+standards:
+  - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
+
+vars:
+  lanes_declared: "false"
+  be_declared: "false"
+  fe_declared: "false"
+  be_gate_msg: "No backend lane is declared in .appweaver/stacks.json, so there is no service to plan. Run /appweaver select-stack and declare the backend stack plus its source path, then re-run plan. A project that is genuinely UI-only plans the frontend lane alone with /appweaver plan-ui."
+  brownfield_plan: "false"     # design-scaffold.override_active — onboard installed the code-derived template
+  plan_created: "false"        # scaffold.created — true ⇒ the doc was absent ⇒ bootstrap
+  plan_migrated: "false"       # scaffold renamed a legacy design.md into backend-plan.md this run
+  plan_mode: "bootstrap_gf"    # resolved below → bootstrap_gf | bootstrap_bf | update
+  track_state: ""              # plan-check → fresh | untracked | clean | behind | edited | edited_behind
+  derived_version: ""          # the spec version the plan last derived from (empty when untracked)
+  current_version: ""          # the spec's current ledger version
+  changed_csv: ""              # ids the ledger moved above the derived version
+  changed_summary: ""          # the moved rows' summaries, for the update prompt
+  manual_ok: "true"            # false ⇒ hand edits present and accept_manual not given
+  plan_stale: "true"           # false ⇒ update mode with nothing to do (clean) — friendly stop
+  stamp_ok: "false"
+  stamp_error: ""
+  fe_next: ""                  # filled when a frontend lane is declared — the plan-ui handoff
+  source_csv: ""               # concept-paths — the feature's source files, as a PATH LIST
+  source_count: "0"            # 0 ⇒ greenfield: no code realises this feature yet
+  okf_concept: ""              # the feature's OKF concept doc (use-case log, source map)
+  if_ok: "true"                # log-append — the interface publication
+  if_error: ""
+  if_appended: "0"
+  if_ids_csv: ""
+  if_unknown_csv: ""
+  if_badsup_csv: ""
+
+workflow:
+
+  # 0. TECHNICAL rule files → sticky standards (configuration, not hardcoded).
+  #    tech-select reads tech-rule-bindings.md under "## /aw-spec-plan". 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-plan }
+
+  # 1. The BACKEND LANE MUST EXIST. This phase writes a service design document, so
+  #    it asks the declaration whether there is a service lane at all — not the
+  #    lane-gate module, whose on-disk check would refuse a greenfield project that
+  #    has declared `src/` but not scaffolded it yet. A plan is authored before the
+  #    code exists; that is the point of planning. Two distinct refusals (the
+  #    evaluator takes single comparisons only, so the message is picked by an
+  #    ordered set): nothing declared at all, vs a frontend-only project.
+  - id: lane_resolve
+    action: execute_script
+    on_error: continue      # never crash raw on an undeclared lane — the gate below explains it
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: lanes_declared, from: "$.declared" }
+      - { name: be_declared,    from: "$.backend_declared" }
+      - { name: fe_declared,    from: "$.frontend_declared" }
+  - id: lane_msg_frontend_only
+    condition: "{{fe_declared}} == true"
+    action: set
+    vars: { be_gate_msg: "Frontend-only project: a frontend lane is declared in .appweaver/stacks.json, a backend lane is not. There is no service to plan here, and authoring backend-plan.md anyway would invent one. Run /appweaver plan-ui for frontend-plan.md; if a service lane does exist, declare it with /appweaver select-stack and re-run plan." }
+  - id: require_backend_lane
+    action: verify_context
+    require_true: be_declared
+    on_false: stop
+    on_false_message: "{{be_gate_msg}}"
+  - id: fe_handoff
+    condition: "{{fe_declared}} == true"
+    action: set
+    vars: { fe_next: "A frontend lane is declared — run /appweaver plan-ui to author/refresh frontend-plan.md against this same spec version." }
+
+  # 2. 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 plan."
+
+  - 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. The spec's own ledger tripwire. A plan derived from an unratified contract is
+  #    conformance theatre: an edit that skipped the Change History has no version, so
+  #    the derivation stamp this run writes would claim a baseline the ledger cannot
+  #    name. spec-check's only ok:false is exactly that case.
+  - id: spec_guard_read
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-check
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: spec_ok,    from: "$.ok" }
+      - { name: spec_state, from: "$.state" }
+  - id: spec_guard
+    action: verify_context
+    require_true: spec_ok
+    on_false: stop
+    on_false_message: "spec.md has moved outside the ledger (state: {{spec_state}}). Record what changed in a Change History row (or fold it back through /appweaver sync-spec), re-run spec-stamp to re-baseline, then re-run plan — a plan derived from an unledgered spec stamps a baseline the ledger cannot name."
+
+  # 4. Scaffold backend-plan.md (idempotent). --lane backend resolves the pair
+  #    design-template → backend-plan.md, and MIGRATES a legacy design.md by renaming
+  #    it (created=false, migrated=true) — one document, never two side by side.
+  - id: plan_scaffold
+    action: execute_script
+    script: { ref: actions }
+    subcommand: design-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "backend"]
+    outputs:
+      - { name: plan_doc,        from: "$.design_doc" }
+      - { name: brownfield_plan, from: "$.override_active" }   # true ⇒ onboard installed the code-derived template
+      - { name: plan_created,    from: "$.created" }           # true ⇒ the doc was ABSENT (just scaffolded) ⇒ bootstrap
+      - { name: plan_migrated,   from: "$.migrated" }          # true ⇒ a legacy design.md became backend-plan.md this run
+
+  # 4a. Resolve the MODE (ordered override — the evaluator has no compound
+  #     conditions): greenfield default; the code-derived override flips it; an
+  #     EXISTING document flips either into an update.
+  - id: mode_brownfield
+    condition: "{{brownfield_plan}} == true"
+    action: set
+    vars: { plan_mode: "bootstrap_bf" }
+  - id: mode_update
+    condition: "{{plan_created}} == false"
+    action: set
+    vars: { plan_mode: "update" }
+
+  # 5. Tracking. plan-check diffs the doc's derivation record against the spec's
+  #    ledger: WHAT moved since this plan was derived (the update's exact work list),
+  #    and whether the doc itself was hand-edited since its stamp.
+  - id: plan_track
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-check
+    args: ["--feature-dir", "{{feature_dir}}", "--doc", "{{plan_doc}}"]
+    outputs:
+      - { name: track_state,     from: "$.state" }
+      - { name: derived_version, from: "$.derived_version" }
+      - { name: current_version, from: "$.current_version" }
+      - { name: changed_csv,     from: "$.changed_csv" }
+      - { name: changed_summary, from: "$.changed_summary" }
+
+  # 5a. Hand-edit fence (LOUD, and unblockable by design): a hash mismatch means the
+  #     document moved outside this workflow. Refuse — unless accept_manual:true asks
+  #     the update to fold the edits in, which keeps their intent, reconciles them
+  #     with the spec, and re-baselines at the stamp.
+  - id: manual_flag_edited
+    condition: "{{track_state}} == edited"
+    action: set
+    vars: { manual_ok: "false" }
+  - id: manual_flag_edited_behind
+    condition: "{{track_state}} == edited_behind"
+    action: set
+    vars: { manual_ok: "false" }
+  - id: manual_accept
+    condition: "{{ACCEPT_MANUAL}} == true"
+    action: set
+    vars: { manual_ok: "true" }
+  - id: manual_fence
+    action: verify_context
+    require_true: manual_ok
+    on_false: stop
+    on_false_message: "backend-plan.md was hand-edited since its last stamp (tracking state: {{track_state}}). Re-run plan with accept_manual:true to fold the edits in (kept, reconciled with the spec, recorded in the ledgers, re-baselined) — or restore the document to its stamped state."
+
+  # 5b. Idempotence: an update with nothing to update stops here, friendly.
+  - id: clean_flag
+    condition: "{{track_state}} == clean"
+    action: set
+    vars: { plan_stale: "false" }
+  - id: clean_stop
+    action: verify_context
+    require_true: plan_stale
+    on_false: stop
+    on_false_message: "backend-plan.md is in step with spec {{current_version}} — nothing to update."
+
+  # 5b. THE CODE. The plan is an architectural confirmation, so it must know what the
+  #     feature already looks like on disk: concept-paths resolves the feature's OKF
+  #     concept to the source files realising it, and the authoring steps declare
+  #     `tools: Read` so they can open the ones that matter. A PATH LIST, not inlined
+  #     content — a real codebase does not fit a payload (E60). on_error: continue,
+  #     because a greenfield feature has no concept doc and must not be blocked by it:
+  #     source_count 0 is the greenfield signal the tasks read.
+  - id: concept_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-paths
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: source_csv,   from: "$.csv" }
+      - { name: source_count, from: "$.count" }
+      - { name: okf_concept,  from: "$.concept" }
+
+  # 6. Pre-execution hooks. (Phase keys keep their historical names — they are the
+  #    hooks CONFIG contract, orthogonal to the command's name.)
+  - 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 (GREENFIELD) — author the master ══════════════
+  # 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 plan_doc; plan-stamp then baselines it.
+  - id: ctx_plan
+    condition: "{{plan_mode}} == bootstrap_gf"
+    action: build_context
+    context:
+      - { path: "{{plan_doc}}" }                # the copied template = section structure
+      - { path: "{{spec_file}}" }               # the source of truth (FR/BR/CN/DC/IC/SC)
+      - { path: .appweaver/DESIGN-FORMAT.md }      # the HLD contract
+      - { path: "{{feature_dir}}/interfaces.md", optional: true }   # the published surface — cite these IF- ids in §3; absent on a first run
+      - { path: "{{okf_concept}}", optional: true }                 # the feature's OKF concept: use-case log + source map
+      - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain (domain enters via the spec)
+  - id: gen_plan
+    condition: "{{plan_mode}} == bootstrap_gf"
+    action: agent_author
+    tools: Read   # the current code arrives as {{source_csv}} paths, not inlined
+    output_target: { type: file, path: "{{plan_doc}}" }
+    task: |
+      Author the MASTER service plan (the target backend-plan.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).
+      - THE CODE IS THE WHAT-EXISTS AUTHORITY, and it is a DIFFERENT authority from the
+        spec. {{source_count}} source file(s) realise this feature today; read the
+        ones that bear on the structure you are deciding, and ADJUST this plan to the
+        shape that is actually there rather than to an idealised one. An empty list is
+        greenfield — design from a clean slate and say so. The code NEVER overrides the
+        spec on behaviour and may not introduce a domain rule the spec omits: code that
+        contradicts the spec is reported (§7 DA-n) and designed to the SPEC, never
+        quietly blessed. A deliberate divergence from the as-built shape is a §8 WA-n
+        with its revisit trigger.
+          {{source_csv}}
+      - THE PUBLISHED SURFACE IS CITED, NOT RESTATED. Every endpoint, published event
+        and externally consumed contract belongs to `interfaces.md`, the feature's
+        append-only interface log — the anchor /appweaver plan-ui and the FE story
+        designs read. §3 here is the INDEX: cite the IF- id of an interface the log
+        already carries (it is in context on an update run), and for one being
+        published for the FIRST time write a one-line description with `(this run)` in
+        the id cell. NEVER invent an IF- number — the script is the only id authority,
+        and a later step publishes what you describe. Changing a published interface
+        means a SUPERSEDING entry, never an edit to an existing one.
+      - 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 plan element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/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. NO STORY IDS ANYWHERE:
+        this plan traces to requirements, which is what keeps it stable while the
+        backlog churns.
+      - 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).
+      - LEAVE the template's initial Change History row as it stands and write NO
+        version anywhere — plan-stamp owns the **Version** header and every row.
+      - 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 (tech-agnostic HLD, spec is the only
+  # domain input, full §Traceability + the two ledgers), with ONE difference: the plan
+  # 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 (plan_mode == bootstrap_bf).
+  - id: ctx_plan_brownfield
+    condition: "{{plan_mode}} == bootstrap_bf"
+    action: build_context
+    context:
+      - { path: "{{plan_doc}}" }                # the scaffolded BROWNFIELD template = code-derived section structure
+      - { path: "{{spec_file}}" }               # the source of truth (FR/BR/CN/DC/IC/SC)
+      - { path: .appweaver/DESIGN-FORMAT.md }      # the HLD contract (see its Brownfield variant note)
+      - { path: "{{feature_dir}}/interfaces.md", optional: true }   # the published surface — cite these IF- ids in §3; absent on a first run
+      - { path: "{{okf_concept}}", optional: true }                 # the feature's OKF concept: use-case log + source map
+      - { 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_plan_brownfield
+    condition: "{{plan_mode}} == bootstrap_bf"
+    action: agent_author
+    tools: Read   # the current code arrives as {{source_csv}} paths, not inlined
+    output_target: { type: file, path: "{{plan_doc}}" }
+    task: |
+      Author the MASTER service plan (the target backend-plan.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).
+      - THE CODE IS THE WHAT-EXISTS AUTHORITY, and it is a DIFFERENT authority from the
+        spec. {{source_count}} source file(s) realise this feature today; read the
+        ones that bear on the structure you are deciding, and ADJUST this plan to the
+        shape that is actually there rather than to an idealised one. An empty list is
+        greenfield — design from a clean slate and say so. The code NEVER overrides the
+        spec on behaviour and may not introduce a domain rule the spec omits: code that
+        contradicts the spec is reported (§5 DA-n) and designed to the SPEC, never
+        quietly blessed. A deliberate divergence from the as-built shape is a §6 WA-n
+        with its revisit trigger.
+          {{source_csv}}
+      - THE PUBLISHED SURFACE IS CITED, NOT RESTATED. Every endpoint, published event
+        and externally consumed contract belongs to `interfaces.md`, the feature's
+        append-only interface log — the anchor /appweaver plan-ui and the FE story
+        designs read. the EXTERNAL-facing §2 subsection here is the INDEX: cite the IF- id of an interface the log
+        already carries (it is in context on an update run), and for one being
+        published for the FIRST time write a one-line description with `(this run)` in
+        the id cell. NEVER invent an IF- number — the script is the only id authority,
+        and a later step publishes what you describe. Changing a published interface
+        means a SUPERSEDING entry, never an edit to an existing one.
+      - 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 plan element traces UP to a spec id; fill §4 Traceability completely (a
+        row for EVERY FR/BR/CN/DC/IC/SC so no lifted constraint is dropped). NO STORY
+        IDS ANYWHERE — this plan traces to requirements. 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).
+      - LEAVE the template's initial Change History row as it stands and write NO
+        version anywhere — plan-stamp owns the **Version** header and every row.
+        Omit a section only if the feature genuinely has nothing there (state why); no
+        complete code anywhere.
+
+  # ══════════════════ UPDATE — conform the existing plan to the moved spec ═════
+  # The work list is COMPUTED, never guessed: the ledger rows above this plan's
+  # derivation stamp name exactly the ids to conform. Everything else stays
+  # byte-identical — the analyze gate reads an unrelated "improvement" as drift.
+  - id: ctx_plan_update
+    condition: "{{plan_mode}} == update"
+    action: build_context
+    context:
+      - { path: "{{plan_doc}}" }                # the CURRENT plan — the document being conformed
+      - { path: "{{spec_file}}" }               # the source of truth at {{current_version}}
+      - { path: .appweaver/DESIGN-FORMAT.md }      # the HLD contract
+      - { path: "{{feature_dir}}/interfaces.md", optional: true }   # the published surface — cite these IF- ids in §3; absent on a first run
+      - { path: "{{okf_concept}}", optional: true }                 # the feature's OKF concept: use-case log + source map
+      - { path: knowledge/architecture/overview.md, optional: true }   # brownfield repos: the as-built architecture
+      - { path: knowledge/architecture/platform.md, optional: true }
+      - { path: .appweaver/memory/constitution.technical.md, optional: true }
+  - id: gen_plan_update
+    condition: "{{plan_mode}} == update"
+    action: agent_author
+    tools: Read   # the current code arrives as {{source_csv}} paths, not inlined
+    output_target: { type: file, path: "{{plan_doc}}" }
+    task: |
+      UPDATE the master service plan (the target backend-plan.md in context) so it
+      conforms to the CURRENT spec. Tracking state: {{track_state}}. The spec moved
+      from {{derived_version}} (this plan's derivation) to {{current_version}}; the
+      ledger rows above the derivation name what moved:
+        ids:     {{changed_csv}}
+        changes: {{changed_summary}}
+      Guidance: {{USER_INPUT}}
+      Rules:
+      - SCOPE IS THE COMPUTED WORK LIST. Rework ONLY the sections and rows that realise
+        the ids above — their §1 invariants/entities, the §2/§3 elements serving them,
+        the §4.2 integration rows, the §5 cross-cutting rows and the §6 traceability
+        rows. Every other line stays BYTE-IDENTICAL; an unrelated "improvement" is
+        drift the analyze gate will fail. EXCEPTION — tracking state `untracked`: this
+        document has no baseline (a migrated legacy design.md), so reconcile the WHOLE
+        plan to the spec once; the stamp then baselines it.
+      - accept_manual: {{ACCEPT_MANUAL}}. When true, the document carries hand edits
+        that were deliberately accepted: KEEP their intent, reconcile them with the
+        spec, and record each kept deviation honestly — a new concept as a §7 DA-n, a
+        deliberate shortcut as a §8 WA-n. Never silently revert a hand edit.
+      - AN ID THE SPEC NO LONGER DEFINES LOSES ITS REALISATION: remove the elements
+        that existed only to serve it (and their §6 rows). An id whose wording moved
+        is re-realised from the spec's CURRENT text — the spec is the wording.
+      - THE SPEC IS THE ONLY DOMAIN INPUT, same as at bootstrap: realise ids, invent
+        nothing; an unavoidable new concept is a §7 DA-n.
+      - THE CODE IS THE WHAT-EXISTS AUTHORITY, and it is a DIFFERENT authority from the
+        spec. {{source_count}} source file(s) realise this feature today; re-read the
+        ones the moved ids touch (code state is read FRESH every run, never assumed), and ADJUST this plan to the
+        shape that is actually there rather than to an idealised one. An empty list is
+        greenfield — design from a clean slate and say so. The code NEVER overrides the
+        spec on behaviour and may not introduce a domain rule the spec omits: code that
+        contradicts the spec is reported (§7 DA-n) and designed to the SPEC, never
+        quietly blessed. A deliberate divergence from the as-built shape is a §8 WA-n
+        with its revisit trigger.
+          {{source_csv}}
+      - THE PUBLISHED SURFACE IS CITED, NOT RESTATED. `interfaces.md` is in context:
+        §3 cites the IF- id of every interface the log already carries. A moved id that
+        CHANGES a published interface is described in §3 with `(this run)` in the id
+        cell — a later step publishes it as a SUPERSEDING entry, and the next update
+        cites the new id. Never invent an IF- number and never edit the log by hand.
+      - PRESERVE THE LEDGERS: §7 Assumptions, §8 Workarounds and §9 Change History
+        keep every existing entry and their numbering — append, never rewrite. Write
+        NO version numbers anywhere and ADD NO Change History row: the stamp step
+        appends the row and moves the **Version** header.
+      - §6 TRACEABILITY STAYS COMPLETE both ways — every CN-/DC-/IC- still has a row
+        after the update; no element without a spec reason.
+      - TECHNOLOGY-AGNOSTIC, no complete code, same contract as at bootstrap.
+
+  # 7. STAMP — the only writer of the plan's version identity, and the ledger-survival
+  #    check: it REFUSES (no baseline written) if the update dropped the Change History
+  #    section, so a lost ledger can never be silently baselined over.
+  - id: stamp_bootstrap
+    condition: "{{plan_mode}} != update"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-stamp
+    args: ["--feature-dir", "{{feature_dir}}", "--doc", "{{plan_doc}}", "--no-row"]
+    outputs:
+      - { name: stamp_ok,        from: "$.ok" }
+      - { name: stamp_error,     from: "$.error" }
+      - { name: current_version, from: "$.version" }
+  - id: stamp_update
+    condition: "{{plan_mode}} == update"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-stamp
+    args: ["--feature-dir", "{{feature_dir}}", "--doc", "{{plan_doc}}", "--ids", "{{changed_csv}}", "--note", "Conformed to spec {{current_version}}"]
+    outputs:
+      - { name: stamp_ok,    from: "$.ok" }
+      - { name: stamp_error, from: "$.error" }
+  - id: stamp_fence
+    action: verify_context
+    require_true: stamp_ok
+    on_false: stop
+    on_false_message: "plan-stamp refused: {{stamp_error}} — backend-plan.md has been written but NOT baselined. Restore the missing ledger section, then re-run plan (or plan-stamp) to record the baseline."
+
+  # ═══════════ PUBLISH THE SURFACE — the interface log (payload-only) ════════
+  # §3 of the plan describes this feature's published surface; this pair turns what it
+  # newly describes into APPEND-ONLY log entries. Separate steps so the script stays the
+  # only id authority: entries arrive as IF-NEW blocks and log-append assigns IF-nnn,
+  # the date and status: proposed. It runs AFTER the stamp — the log lives in its own
+  # file, so appending to it cannot invalidate the baseline just recorded.
+  #
+  # This is the BE→FE contract anchor: /appweaver plan-ui and the FE story designs read
+  # the latest entry per id. A changed interface is published as a SUPERSEDING entry,
+  # never an edit — which is why the log is append-only and the plan cites ids.
+  - id: ctx_if
+    action: build_context
+    vars:
+      derived_version: "{{current_version}}"
+    context:
+      - { path: "{{plan_doc}}" }                                    # the plan as just written — §3 is the source
+      - { path: "{{feature_dir}}/interfaces.md", optional: true }   # existing entries — what a change supersedes
+  - id: gen_if
+    action: agent_author
+    output_target: { type: file, path: "{{feature_dir}}/.aw-if-new.tmp.md" }
+    task: |
+      From the plan document in context, extract this feature's PUBLISHED SURFACE into
+      formal interface-log entries: the endpoints, published events and externally
+      consumed contracts its API/published-surface section describes.
+
+      Output ONLY entries that are NOT ALREADY in the interface log in context, or that
+      SUPERSEDE an entry there because the plan now describes them differently. An
+      interface the log already carries unchanged is NOT re-published. If there is
+      nothing to publish — no published surface, or every one already logged unchanged
+      — output exactly:
+      none
+
+      Otherwise output ONE block per interface, nothing else:
+
+      ## IF-NEW — <METHOD /route, or the event name>
+
+      serves: <the FR-/BR- ids from the spec this interface exists for>
+      supersedes: <the IF-nnn id it replaces from the log in context, or none>
+
+      <the contract: request/response or payload shapes, auth, status codes and the
+      error contract — shapes, not implementations>
+
+      Every block starts with "## IF-NEW — " exactly: the script assigns the real ids,
+      the date and status: proposed. Describe only what the plan actually contains —
+      invent no interface the plan does not describe.
+  - id: append_if
+    action: execute_script
+    on_error: continue   # a malformed extraction is reported LOUDLY but must not undo a
+                         # plan that already landed and baselined: the temp file survives
+                         # for a hand-run of log-append; if_error carries the refusal
+    script: { ref: actions }
+    subcommand: log-append
+    args: ["--feature-dir", "{{feature_dir}}", "--log", "interfaces", "--entries-file", "{{feature_dir}}/.aw-if-new.tmp.md"]
+    outputs:
+      - { name: if_ok,          from: "$.ok" }
+      - { name: if_error,       from: "$.error" }
+      - { name: if_appended,    from: "$.appended" }
+      - { name: if_ids_csv,     from: "$.ids_csv" }
+      - { name: if_unknown_csv, from: "$.unknown_ids_csv" }
+      - { name: if_badsup_csv,  from: "$.bad_supersedes_csv" }
+
+  # 8. 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}}"
+  plan_doc: "{{plan_doc}}"
+  plan_mode: "{{plan_mode}}"
+  migrated_legacy_design: "{{plan_migrated}}"
+  derived_from_spec: "{{current_version}}"
+  conformed_ids: "{{changed_csv}}"
+  interfaces_published: "{{if_ids_csv}}"
+  interfaces_error: "{{if_error}}"
+  source_files_read: "{{source_count}}"
+  next: "Gate this write: /appweaver analyze-design (spec ↔ plan conformance) — after EVERY bootstrap and EVERY update. Then the backlog and the stories: /appweaver sync-stories, then /appweaver story-plan <id>, which READS this plan and refuses to design against one the spec has moved past. {{fe_next}} READ THE FIELDS ABOVE FIRST: interfaces_published are the IF- ids this run appended to interfaces.md as status:proposed — cite them in the plan's API section on the next update, and never edit the log by hand; interfaces_error non-empty means the extraction was refused and .aw-if-new.tmp.md is still beside the plan for a hand-run of log-append, so THIS RUN PUBLISHED NOTHING; source_files_read 0 means no code was found for this feature, so the plan was written greenfield. NOTE while the pipeline is mid-rename: migrated_legacy_design=true means design.md is now backend-plan.md, and stages not yet rebuilt for the rename (implement, the delta chain) still look for design.md — rebuild or point them at backend-plan.md before relying on them."