aw-spec-cli 0.1.18 → 0.1.19

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

@@ -0,0 +1,319 @@
+# =============================================================================
+# aw-spec-recall-delta (orchestrator) — WITHDRAW a change that never shipped
+#
+# The escape hatch of the CR loop, and the counterpart of close-delta:
+#   close-delta    the change SHIPPED  — archive it and bump the version
+#   recall-delta   the change is WITHDRAWN — archive it and bump NOTHING
+#
+#   specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta
+#       → finalize-delta → analyze-slice → close-delta
+#       └─ recall-delta may end it anywhere BEFORE finalize-delta ────────────┘
+#
+# WHY IT EXISTS. Changes get abandoned: the requirement was dropped, the approach was
+# wrong, a wider refactor swallowed it. Until this stage there was no way to say so. The
+# only mechanism that took a change out of the open set was `cr-archive`, which archives
+# AND bumps the version in one act, so withdrawing one meant either burning a version
+# number on work that shipped nothing or deleting the directory by hand and editing
+# active_version.json — an operation with no record, no gate, and nothing to stop it being
+# done to the wrong change. The archive and the bump are now separable (`cr-archive
+# --recall`), and this stage is the supported way to reach that half.
+#
+# A RECALL IS NOT A ROLLBACK. It withdraws the change's DOCUMENTS — its delta-spec, its
+# delta plans and its model delta, all archived intact under changes/archive/<id>/ beside a
+# RECALLED.md that records the date and the reason. It does NOT revert code: a change that
+# reached /appweaver implement has already generated source files, and reverting those is
+# git's job, not this pipeline's. The output and the marker both say so, because a stage
+# that half-undoes something while sounding like it undid all of it is worse than no stage.
+#
+# TWO REFUSALS, BOTH MECHANICAL AND BOTH READ OFF DISK.
+#
+#   MERGED — finalize-delta has already folded this change into spec.md and the context's
+#   domain-model.md, and appended a Change History row carrying its id. The masters now
+#   describe behaviour that includes it, so withdrawing the change would leave them
+#   describing work no open change accounts for. The remedy for a merged change that should
+#   not have landed is a NEW change that reverses it. Detected from the id's presence in
+#   spec.md, which is that Change History row.
+#
+#   ⏭️ THE UN-MERGE IS DELIBERATELY NOT BUILT (decision, 2026-09-11 — not a missing piece).
+#   Both prerequisites now exist: finalize-delta snapshots both masters to
+#   changes/<id>/pre-merge/, and cr-merge-check can prove no other delta landed in between,
+#   which is exactly the window a restore would be safe in. It is still not built, because a
+#   restore is a whole-file overwrite of two long-lived hand-curated documents, and what it
+#   would NOT roll back is the rest of what finalize-delta did — the OKF cross-reference
+#   edges and the re-authored concept Overview. A command that restores the masters while
+#   leaving the knowledge layer describing the withdrawn change is the kind of half-undo
+#   this stage's own header refuses to be. The snapshot is kept regardless: it is the record
+#   of what the masters said, and an operator who needs it can read it.
+#
+#   DEPENDANTS — a wave is a dependency level. Same wave means independent; a HIGHER wave
+#   means planned and built on top of the lower ones. Withdrawing a lower-wave change
+#   therefore strands every open change above it, so this stage refuses and names them.
+#   `depends_on` is stamped nowhere yet (⌛ with the rest of the parallel-delta merge
+#   fence), so the wave is the only dependency signal that actually exists — and it is the
+#   conservative one, since same-wave siblings are never counted.
+#
+# THE VERSION DOES NOT MOVE. That is the entire point of the stage and the one invariant
+# worth stating twice: a version records what a change SHIPPED as, and a recalled change
+# shipped nothing. Nothing here stamps a header, appends a Change History row, or touches
+# active_version.json's `version` field.
+#
+# Launch:  /appweaver recall-delta [CR-id]   (a bare id skips the prompt)
+# Prereq:  an OPEN change on the active feature that finalize-delta has NOT merged.
+# =============================================================================
+
+name: aw-spec-recall-delta
+description: "Withdraw an open change that will not ship — archive changes/<id>/ and its model delta into changes/archive/<id>/ beside a RECALLED.md recording the date and reason, and drop it from active_version.json's open set WITHOUT bumping the version. Refuses a change finalize-delta already merged into the masters (the remedy there is a new change that reverses it) and one that a higher-wave open change is built on top of. Withdraws documents only — code already generated by implement is not reverted. Invokes no model and generates no code."
+version: 1.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: "Optional CR id of the change to withdraw. A bare id selects it and skips the prompt; anything else is ignored and the menu is shown."
+    required: false
+    bind: USER_INPUT
+
+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
+
+# No standards seed and no domain/tech rule selection: this stage authors nothing, so it
+# has no prompt to govern. It is bookkeeping over changes/ + active_version.json, plus the
+# two refusals.
+standards: []
+
+vars:
+  has_changes: "false"
+  cr_choice: ""
+  cr_id: ""
+  merged: "false"
+  merge_evidence: ""
+  has_dependants: "false"
+  dependant_ids: ""
+  dependant_count: "0"
+  # The two refusal flags, both DOWN by default and raised only by the good state — see
+  # the gates below for why fail-closed is the right default here.
+  not_merged: "false"
+  no_dependants: "false"
+  recall_confirmed: "false"
+  recalled: "false"
+  archived_dir: ""
+  recall_marker: ""
+  open_count: "0"
+
+workflow:
+
+  # 1. Resolve the active feature.
+  - 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,     from: "$.feature" }
+      - { name: feature_dir, from: "$.feature_dir" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature. Run /appweaver select-feature first (pick or create the aggregate, e.g. Order), then re-run recall-delta."
+
+  # 2. WHICH CHANGES ARE OPEN — the evidence is changes/<CR-id>/ on disk. No synthetic
+  #    rows: `main` is not a change and there is nothing to open here, so the menu is the
+  #    real changes and nothing else. `matched_label` resolves a CR id passed as the
+  #    argument to the whole option string, which is how a bare `recall-delta CR-…` skips
+  #    the prompt entirely.
+  - id: cr_list
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-list
+    args: ["--feature-dir", "{{feature_dir}}", "--preselect", "{{USER_INPUT}}"]
+    outputs:
+      - { name: change_options, from: "$.select_options" }
+      - { name: matched_label,  from: "$.matched_label" }
+      - { name: has_changes,    from: "$.has_changes" }
+      - { name: change_count,   from: "$.count" }
+
+  - id: require_changes
+    action: verify_context
+    require_true: has_changes
+    on_false: stop
+    on_false_message: "No open change on this feature — nothing to withdraw. A change is opened by /appweaver specify; one that already shipped was archived by /appweaver close-delta and is under changes/archive/, where a recall does not reach it."
+
+  # 3. WHICH ONE. single_option_confirm so a feature with exactly one open change still
+  #    confirms the id out loud — this stage archives documents, and picking silently is
+  #    how the wrong change gets withdrawn on a feature the operator has two open on.
+  - id: pick_change
+    action: user_select
+    prompt: "Which open change is being WITHDRAWN? Its delta-spec, delta plans and model delta are archived under changes/archive/ and it leaves the open set — with no version bump, because a recalled change ships nothing. Code that /appweaver implement already generated for it is NOT reverted; that is a git operation."
+    options_from_variable: change_options
+    preselect_from: matched_label
+    single_option_confirm: true
+    outputs:
+      - { name: cr_choice, from: selection }
+
+  # 3b. That change's documents, and the clean id back out of the label the pick returned.
+  - id: cr_paths
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-paths
+    args: ["--cr-id", "{{cr_choice}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: cr_id,            from: "$.cr_id" }
+      - { name: cr_dir,           from: "$.cr_dir" }
+      - { name: delta_spec,       from: "$.delta_spec" }
+      - { name: delta_model,      from: "$.delta_model" }
+      - { name: wave,             from: "$.wave" }
+
+  # 4. THE TWO REFUSALS, both answered from disk in one call — see the header for why each
+  #    one is a stop rather than a warning.
+  - id: recall_check
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-recall-check
+    args: ["--cr-id", "{{cr_choice}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: merged,          from: "$.merged" }
+      - { name: merge_evidence,  from: "$.merge_evidence" }
+      - { name: has_dependants,  from: "$.has_dependants" }
+      - { name: dependant_ids,   from: "$.dependant_ids" }
+      - { name: dependant_count, from: "$.dependant_count" }
+
+  # Each refusal is a RAISE then a gate, not a conditional gate: the raise fires only on
+  # the good state, so a value that never arrived (the script errored, the field was
+  # renamed) leaves the flag down and the stage refuses. Fail-closed is the only safe
+  # default for a gate in front of an archive.
+  - id: not_merged_raise
+    condition: "{{merged}} == false"
+    action: set
+    vars: { not_merged: "true" }
+
+  - id: refuse_merged
+    action: verify_context
+    require_true: not_merged
+    on_false: stop
+    on_false_message: "Change {{cr_id}} has already been MERGED — /appweaver finalize-delta folded it into spec.md and the context's domain-model.md, and the spec's Change History carries it: {{merge_evidence}}. The masters now describe behaviour that includes this change, so withdrawing it would leave them describing work no open change accounts for. A recall cannot un-merge, and this stage will not pretend otherwise. If the change should not have landed, finish it (/appweaver analyze-slice → close-delta) and then open a NEW change that reverses it with /appweaver specify — that keeps both the landing and the reversal in the ledger, which is what a reader of the spec needs to see."
+
+  - id: no_dependants_raise
+    condition: "{{has_dependants}} == false"
+    action: set
+    vars: { no_dependants: "true" }
+
+  - id: refuse_dependants
+    action: verify_context
+    require_true: no_dependants
+    on_false: stop
+    on_false_message: "Change {{cr_id}} is at wave {{wave}} and {{dependant_count}} open change(s) sit at a HIGHER wave: {{dependant_ids}}. A higher wave means planned and built ON TOP of the lower ones, so withdrawing this one strands them — their delta plans were authored against a predecessor that would no longer exist. Withdraw the higher-wave change(s) first (/appweaver recall-delta <CR-id>), or re-plan them against the lower waves that remain (/appweaver plan <CR-id>) before recalling this one. Same-wave changes are independent and are not counted here."
+
+  # 5. CONFIRM. Ordered no-first against the kit's usual yes-first convention, and
+  #    deliberately: act_ask takes options[0] non-interactively, so an unattended run
+  #    DECLINES rather than archiving a change nobody was watching. The reason is asked
+  #    for in the same breath because it is what the marker records — a withdrawn change
+  #    with no stated reason is a directory in an archive that nobody can account for later.
+  - id: confirm_recall
+    action: ask
+    prompt: "Withdraw {{cr_id}} (wave {{wave}})? Its documents — {{delta_spec}}, its delta plans and {{delta_model}} — move to changes/archive/{{cr_id}}/ and it leaves the open set. The version does NOT move: this change ships nothing. Any code implement already generated for it stays on disk; revert that with git if it should not remain. Answer no to stop with everything untouched."
+    options: ["no", "yes"]
+    answer_var: recall_answer
+
+  - id: recall_go
+    condition: "{{recall_answer}} == yes"
+    action: set
+    vars: { recall_confirmed: "true" }
+
+  - id: require_confirm
+    action: verify_context
+    require_true: recall_confirmed
+    on_false: stop
+    on_false_message: "Stopped — {{cr_id}} is untouched and still open. Nothing was archived and no version moved. Re-run and answer yes to withdraw it, or carry on with it: /appweaver plan {{cr_id}} to (re)author its delta plans, or /appweaver implement {{cr_id}} to build it."
+
+  - id: ask_reason
+    action: ask
+    prompt: "Why is {{cr_id}} being withdrawn? One line — it is written into changes/archive/{{cr_id}}/RECALLED.md, which is the only record of why this work stopped."
+    options: ["superseded by another change", "requirement dropped", "approach was wrong"]
+    answer_var: recall_reason
+
+  # 6. Pre-execution hooks.
+  - id: resolve_pre_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_recall_cr"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    hooks_from_variable: before_hooks
+
+  # 7. THE RECALL. --recall is what separates this from close-delta: the same archive of
+  #    the directory and of the model delta that lives beside the master, plus the
+  #    RECALLED.md marker, and NO version bump. The script refuses an id the ledger does
+  #    not carry and leaves everything in place when it does, so a refusal here is a no-op
+  #    rather than a half-archived change.
+  - id: recall
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-archive
+    args: ["--feature-dir", "{{feature_dir}}", "--cr-id", "{{cr_choice}}", "--recall", "--reason", "{{recall_reason}}"]
+    outputs:
+      - { name: recall_ok,      from: "$.ok" }
+      - { name: recalled,       from: "$.recalled" }
+      - { name: archived_dir,   from: "$.archived_dir" }
+      - { name: archived_model, from: "$.archived_model" }
+      - { name: recall_marker,  from: "$.recall_marker" }
+      - { name: version,        from: "$.version" }
+      - { name: active_change,  from: "$.active_change" }
+      - { name: open_count,     from: "$.open_count" }
+
+  - id: verify_recalled
+    action: verify_context
+    require_true: recall_ok
+    on_false: stop
+    on_false_message: "The withdrawal of {{cr_id}} did not complete and nothing was moved — active_version.json does not carry it as an open change. That happens when the change was already closed or recalled, or when its directory exists on disk but was never registered by /appweaver specify. Check {{feature_dir}}/active_version.json against {{feature_dir}}/changes/."
+
+  # 8. Anchor the WITHDRAWAL in the OKF bundle's freshness journal (log.md, OKF §7).
+  #    close-delta logs the ship; this logs the stop, which is exactly as much a part of
+  #    the feature's history. Best-effort + git-aware: a no-op when there is no bundle.
+  - id: xref_log
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: log
+    args: ["--note", "CR {{cr_id}} RECALLED — withdrawn before merge ({{recall_reason}}), archived to {{archived_dir}}, version unchanged at {{version}}"]
+    outputs:
+      - { name: xref_log, from: "$.log" }
+
+  # 9. Post-execution hooks.
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_recall_cr"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    hooks_from_variable: after_hooks
+
+outputs:
+  feature: "{{feature}}"
+  feature_dir: "{{feature_dir}}"
+  cr_id: "{{cr_id}}"
+  wave: "{{wave}}"
+  reason: "{{recall_reason}}"
+  archived_dir: "{{archived_dir}}"
+  archived_model: "{{archived_model}}"
+  recall_marker: "{{recall_marker}}"
+  # The number BEFORE and after are the same number — stated as an output because "nothing
+  # moved" is the result this stage exists to produce, and an absent field would read as
+  # an unanswered question rather than an answered one.
+  version: "{{version}}"
+  open_changes_remaining: "{{open_count}}"
+  active_change: "{{active_change}}"
+  note: "Change {{cr_id}} WITHDRAWN — its delta-spec, delta plans and model delta are archived intact at {{archived_dir}}, with the reason recorded in {{recall_marker}}. The version did NOT move and stands at {{version}}: this change shipped nothing, so no number was spent on it. spec.md and the context's domain-model.md never carried it and were not touched. Code that /appweaver implement generated for this change is still on disk — a recall withdraws documents, not source; revert it with git if it should not stay."
+  next: "{{open_count}} change(s) still open on this feature. Carry on with one of them (/appweaver plan <CR-id> → analyze-plan-delta → implement), or with none left the feature is back on its masters: /appweaver plan main re-derives the lane plans from spec.md and the domain model, and /appweaver specify opens a fresh change."

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

@@ -15,7 +15,14 @@
 # assert different rules for it and nothing arbitrates. Authoring both here is also what
 # keeps the model in step with the spec version: it never waits for plan or implement.
 #
-# Auto-detects first-vs-subsequent from spec.md:
+# Auto-detects first-vs-subsequent from feature-paths' needs_bootstrap — NOT from spec.md's
+# presence. The two differ on one state and it is the one that corrupts: a first run that
+# wrote spec.md and then died leaves the file on disk with the unfinished-bootstrap marker
+# still up, and the file alone reads as a finished spec to EXTEND. version-init raises that
+# marker (--bootstrap, which adopt must never pass — a finished reversal is not a crashed
+# draft) and version-bootstrap-done lowers it AFTER the converge block, so the whole
+# authoring window is recoverable. An interrupted draft ASKS before it is overwritten,
+# because a deliberate stop and a crash look identical from here:
 #   • BOOTSTRAP (no spec.md)  → author the MASTER spec (US-1) + the context's MASTER
 #     domain model + init active_version.json. On the context's second feature the model
 #     already exists and gains a section rather than being replaced.
@@ -33,11 +40,12 @@
 # defaults a new delta to the wave already in flight (parallel by default); `cr-wave`
 # raises one that turns out to build on another.
 #
-# ⚠️ finalize-delta and close-delta still resolve "the" change through
-# active_version.json.active_change — the most recently opened. plan, analyze-plan-delta
-# and implement ASK which change and re-activate the answer, so the choice reaches those
-# two; threading an explicit --cr-id through the whole chain is the next step and is not
-# done yet.
+# EVERY DELTA STAGE NOW ASKS WHICH CHANGE. plan, analyze-plan-delta, implement,
+# recall-delta, finalize-delta and close-delta all list what is open, ask, and activate the
+# answer, with a bare CR id as the argument doubling as the answer. None of them takes
+# active_version.json's `active_change` on trust — which matters most here, because THIS
+# phase overwrites that field on every run: a bare finalize used to merge whichever change
+# was opened last, and `cr-setup` scaffolds a delta-spec stub the moment it opens one.
 #
 # Both paths then run ONE converge block — checklist + clarify + validate — over the
 # document THIS invocation authored, never the other one:
@@ -66,7 +74,7 @@
 
 name: aw-spec-specify
 description: Author the ACTIVE feature's specification AND its bounded context's domain model, together. The aggregate root, its entities, events and invariants (BR-n) live in specs/<Context>/domain-model.md — the one canonical definition every spec in the context cites by id and never restates. First call writes the master spec (US-1) plus the master model; a later call opens its OWN change (many may be open at once) and writes that change's delta-spec and delta-domain-model, leaving both masters untouched for finalize-delta to merge. Each change carries a WAVE — deltas sharing one are independent and developable in parallel, a higher wave is implemented after the lower ones land — and its model delta sits beside the master so every other open delta can see it while being authored. Spec phase only — plan/design is separate.
-version: 3.0.0
+version: 3.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -115,6 +123,19 @@ vars:
                              # the checklist. NEVER hand-set to spec_file on the delta
                              # path — that is what silently drifts an adopted spec.
   version: ""                # current active_version.json version (for the report)
+  bootstrap_cleared: "false" # whether THIS run lowered the unfinished-first-draft marker
+  # THE BOOTSTRAP BRANCH AND ITS CRASH-RESUME. is_bootstrap is what every branch below
+  # reads; it starts from feature-paths' needs_bootstrap, which is `no spec.md` OR `a first
+  # draft is still marked unfinished`. The second half is the crash case, and it is the one
+  # that used to become a delta against a v1.0 nobody finished.
+  spec_exists: "false"
+  needs_bootstrap: "true"    # defaulted to BOOTSTRAP: with no answer, authoring a first
+                             # draft is recoverable, while extending a spec that may not
+                             # exist is not
+  bootstrap_pending: "false"
+  is_bootstrap: "false"
+  resume_bootstrap: "false"  # bootstrap_pending AND spec.md on disk ⇒ a draft was interrupted
+  resume_choice: ""
 
 workflow:
 
@@ -129,6 +150,14 @@ workflow:
       - { name: feature_dir, from: "$.feature_dir" }
       - { name: spec_file,   from: "$.spec_file" }
       - { name: spec_exists, from: "$.spec_exists" }
+      # WHICH BRANCH THIS RUN TAKES. needs_bootstrap, not spec_exists — the two differ on
+      # exactly one state, and it is the one that corrupts: a FIRST run that wrote spec.md
+      # and then died leaves the file on disk with the unfinished-bootstrap marker still up,
+      # and branching on the file alone reads that as a finished spec to EXTEND. The next
+      # call then opens a change against a v1.0 nobody finished. feature-paths already
+      # computed this in both shells; nothing read it.
+      - { name: needs_bootstrap,    from: "$.needs_bootstrap" }
+      - { name: bootstrap_pending,  from: "$.bootstrap_pending" }
 
   - id: require_feature
     action: verify_context
@@ -185,27 +214,78 @@ workflow:
     action: dispatch_hooks
     hooks_from_variable: before_hooks
 
-  # ═══════════════════════ BOOTSTRAP — no spec.md yet ═══════════════════════
+  # ═══════════ WHICH BRANCH — and the one case where it is ASKED ═══════════
+  # is_bootstrap takes needs_bootstrap's answer. Two states reach it:
+  #   no spec.md                       → an ordinary first run. Nothing is asked.
+  #   spec.md + the marker still up    → a first draft was INTERRUPTED. Re-authoring is
+  #                                      the designed recovery, but it OVERWRITES what is
+  #                                      on disk, and a deliberate stop is indistinguishable
+  #                                      from a crash. So that case, and only that case,
+  #                                      asks before it writes.
+  - id: branch_from_bootstrap
+    action: set
+    vars: { is_bootstrap: "{{needs_bootstrap}}" }
+
+  # The AND, as an ordered assignment (the engine has no compound conditions): under a
+  # raised marker, take spec.md's presence as the answer. A marker with no spec.md is a
+  # first run that died before writing anything — there is nothing to overwrite and
+  # nothing to ask.
+  - id: flag_resume
+    condition: "{{bootstrap_pending}} == true"
+    action: set
+    vars: { resume_bootstrap: "{{spec_exists}}" }
+
+  - id: ask_resume
+    condition: "{{resume_bootstrap}} == true"
+    action: ask
+    prompt: |
+      A FIRST DRAFT of this feature's spec.md was started and never finished — the
+      unfinished-bootstrap marker in active_version.json is still up, which means the last
+      run wrote the file and then stopped before completing it.
+
+      Re-author it (the draft is replaced from your input, and the domain model with it), or
+      treat what is on disk as the finished v1.0 and open a CHANGE against it instead?
+
+      Re-authoring OVERWRITES specs/…/spec.md. Treat-as-finished keeps it exactly as it is
+      and clears the marker, so this is asked once either way.
+    options: ["Re-author the first draft", "Treat it as finished"]
+    answer_var: resume_choice
+
+  # Taking it as finished is a decision about the DOCUMENT, so it clears the marker and
+  # hands the run to the delta path — the same path an ordinary later specify takes.
+  - id: accept_draft
+    condition: "{{resume_choice}} == Treat it as finished"
+    action: set
+    vars: { is_bootstrap: "false" }
+
+  - id: accept_draft_clear
+    condition: "{{resume_choice}} == Treat it as finished"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: version-bootstrap-done
+    args: ["--feature-dir", "{{feature_dir}}"]
+
+  # ═══════════════════════ BOOTSTRAP — no finished spec.md yet ══════════════
   # Copy the spec template into the (already-existing) feature dir + init version.
   - id: boot_scaffold
-    condition: "{{spec_exists}} == false"
+    condition: "{{is_bootstrap}} == true"
     action: execute_script
     script: { ref: actions }
     subcommand: scaffold
     args: ["--feature-dir", "{{feature_dir}}", "--allow-existing"]
 
   - id: boot_version_init
-    condition: "{{spec_exists}} == false"
+    condition: "{{is_bootstrap}} == true"
     action: execute_script
     script: { ref: actions }
     subcommand: version-init
-    args: ["--feature-dir", "{{feature_dir}}"]
+    args: ["--feature-dir", "{{feature_dir}}", "--bootstrap"]
 
   # Copy the domain-model template into the CONTEXT (not the feature) when the context
   # has no model yet. Idempotent and non-destructive: the second feature in a context
   # finds the model already there and adds its aggregate to it rather than replacing it.
   - id: boot_model_scaffold
-    condition: "{{spec_exists}} == false"
+    condition: "{{is_bootstrap}} == true"
     action: execute_script
     script: { ref: actions }
     subcommand: model-scaffold
@@ -215,7 +295,7 @@ workflow:
       - { name: model_was_created, from: "$.created" }
 
   - id: boot_ctx
-    condition: "{{spec_exists}} == false"
+    condition: "{{is_bootstrap}} == true"
     action: build_context
     context:
       - "{{spec_file}}"                      # the copied template = section structure
@@ -241,7 +321,7 @@ workflow:
                                                      # no file and no ux/ rules mapped, the section resolves to
                                                      # "None" and the spec is unchanged from a backend-only one.
   - id: boot_generate
-    condition: "{{spec_exists}} == false"
+    condition: "{{is_bootstrap}} == true"
     action: agent_author
     output_target: { type: file, path: "{{spec_file}}" }
     task: |
@@ -334,7 +414,7 @@ workflow:
   # which a frontend-only project has as much as any other; where an invariant is
   # ENFORCED is a plan concern and is recorded in backend-plan.md.
   - id: boot_model_ctx
-    condition: "{{spec_exists}} == false"
+    condition: "{{is_bootstrap}} == true"
     action: build_context
     context:
       - "{{domain_model}}"                   # the model (template on a first feature, populated on a later one)
@@ -343,7 +423,7 @@ workflow:
       - { path: .appweaver/memory/constitution.ui.md, optional: true }
 
   - id: boot_model_generate
-    condition: "{{spec_exists}} == false"
+    condition: "{{is_bootstrap}} == true"
     action: agent_author
     output_target: { type: file, path: "{{domain_model}}" }
     task: |
@@ -379,15 +459,18 @@ workflow:
 
   # ═════════════════════════ DELTA — spec.md exists ═════════════════════════
   # A later requirement = a new user story on the SAME aggregate. Delegate to the
-  # delta-spec module: it opens the change (cr-setup, single-active-change guarded) and
-  # authors the delta-spec ONLY — the master spec.md is left UNTOUCHED. The change
-  # stays OPEN; finalize-delta merges the delta into spec.md later in the chain. Runs in
-  # this context (shares vars + the DDD + domain sticky standards). The former standalone
-  # `cr` capture's spec half now lives here. Downstream: plan (the delta plans) →
+  # delta-spec module: it opens the change (cr-setup) and authors BOTH of the change's
+  # halves — the delta-spec under changes/<cr-id>/ and the model delta beside the context's
+  # master model — leaving the master spec.md and domain-model.md UNTOUCHED. MANY changes
+  # may be open at once: every call on an established feature opens its own, the wave is
+  # what orders them, and the single-active-change guard that used to refuse a second one
+  # is gone. The change stays OPEN; finalize-delta merges both halves later in the chain.
+  # Runs in this context (shares vars + the DDD + domain sticky standards). The former
+  # standalone `cr` capture's spec half now lives here. Downstream: plan (the delta plans) →
   # analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice →
   # close-delta (close-delta is what finally archives the change and bumps the version).
   - id: delta_spec_module
-    condition: "{{spec_exists}} == true"
+    condition: "{{is_bootstrap}} == false"
     action: include
     module: .appweaver/orchestrator/modules/delta-spec.orch.yaml
 
@@ -404,7 +487,7 @@ workflow:
   #    content; note it rewrites the file, so it is deliberately scoped to the path that
   #    authored the document (a delta run no longer resets the master's scored boxes).
   - id: create_checklist
-    condition: "{{spec_exists}} == false"
+    condition: "{{is_bootstrap}} == true"
     action: execute_script
     script: { ref: actions }
     subcommand: create-checklist
@@ -418,7 +501,7 @@ workflow:
   # checklist's items assume a full spec and would mis-fire here, which is exactly why
   # this is a separate checklist rather than the same one re-pointed.
   - id: create_delta_checklist
-    condition: "{{spec_exists}} == true"
+    condition: "{{is_bootstrap}} == false"
     action: execute_script
     script: { ref: actions }
     subcommand: create-checklist
@@ -526,6 +609,24 @@ workflow:
     outputs:
       - { name: checklist_passed, from: "$.after_checked" }
 
+  # 7b. THE FIRST DRAFT IS FINISHED — lower the marker. Placed HERE, after the converge
+  #     block, because that is the last thing the bootstrap path does to the document: a
+  #     run that died inside the checklist or the clarify loop left a spec.md that is
+  #     present but not yet what it will be, and clearing earlier would certify exactly the
+  #     half-written state the marker exists to catch. Everything between version-init
+  #     --bootstrap and this step is the window a crash is recoverable in.
+  #
+  #     Idempotent: clearing a marker that is already down is the ordinary outcome of a
+  #     re-run and is not an error, so this needs no guard beyond the branch.
+  - id: boot_done
+    condition: "{{is_bootstrap}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: version-bootstrap-done
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: bootstrap_cleared, from: "$.cleared" }
+
   # 8. Read the current version for the report (both paths).
   - id: version_read
     action: execute_script