aw-spec-cli 0.1.18 → 0.1.19

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

@@ -18,38 +18,77 @@
 # once the slice is green, domain-conformant and has not broken a referrer.
 #
 # This stage AUTHORS nothing and generates NO code — no model is invoked. It moves
-# changes/<id>/ into changes/archive/, bumps the minor version, clears active_change,
-# and STAMPS that version into the `**Version**:` header of spec.md + backend-plan.md — the
+# changes/<id>/ into changes/archive/, bumps the minor version, clears active_change, and
+# STAMPS that version into the `**Version**:` header of spec.md + backend-plan.md and into
+# the change's own Change History row, which finalize-delta left reading `(pending)` — the
 # single irreversible act of the CR loop, deliberately isolated in a stage of its own.
 #
-# THE VERSION SPINE LIVES HERE, AND ONLY HERE. The number has three carriers — spec.md's
-# header, backend-plan.md's header, active_version.json — and all three move in this one step
-# by one deterministic mechanism. Before, backend-plan.md's header was bumped by the MODEL at
-# finalize-delta (a stage early, and guessing the target since the number was never
-# passed into the merge prompt) while spec.md's header was bumped by nobody at all,
-# leaving the "living truth" document permanently at v1.0. finalize-delta now writes
-# spec.md's Change History row using version-read's `next_version` — the same bump()
-# authority this stage applies — and touches neither header. It no longer merges the lane
-# plans at all (they are derived from spec.md + domain-model.md), so a plan header stamped
-# here is stating the version the slice ships as, not that the plan was re-derived for it.
+# TWO SPINES, NOT ONE. The feature's version records what THIS feature shipped. The
+# bounded context's version records the shared domain-model.md, which every feature in the
+# context reads — so a change to it is a change to all of them and no single feature's
+# number can carry it. This stage owns both, and moves the context's ONLY when the closing
+# change actually merged a model delta: a behaviour-only change leaves domain-model.md
+# alone at finalize and leaves its version alone here. The model's `**Context version**:`
+# header has always declared itself script-stamped, and specify forbids the authoring model
+# from writing it; this is the step that makes both of those statements true.
+#
+# ⌛ The model's own Change History table is still not written by anything. Its columns are
+# deterministic except the summary, which needs a sentence about the change — and this
+# stage invokes no model by design. Left unwritten rather than half-filled.
+#
+# THE VERSION SPINE LIVES HERE, AND ONLY HERE. The number has FOUR carriers — spec.md's
+# header, backend-plan.md's header, spec.md's Change History row, and active_version.json —
+# and all four move in this one step by one deterministic mechanism. Before, backend-plan.md's
+# header was bumped by the MODEL at finalize-delta (a stage early, and guessing the target
+# since the number was never passed into the merge prompt) while spec.md's header was bumped
+# by nobody at all, leaving the "living truth" document permanently at v1.0.
+#
+# THE CHANGE HISTORY ROW IS THE FOURTH CARRIER, and it joined the spine for the same reason
+# the headers did. finalize-delta appends the row when it MERGES — a stage before this number
+# exists — and used to write version-read's `next_version` into it: a PREDICTION of the bump.
+# A change that merged and never closed (an abandoned run, a red analyze-slice) then left
+# spec.md asserting a version nothing ever issued. The merge now writes `(pending)` and
+# version-stamp --cr-id fills it here, so the row and its number land together. That is the
+# rule domain-model.md was always held to, and spec.md was the document breaking it.
+#
+# This stage no longer merges the lane plans at all (they are derived from spec.md +
+# domain-model.md), so a plan header stamped here is stating the version the slice ships as,
+# not that the plan was re-derived for it.
 #
 # NOTE: nothing MECHANICALLY proves analyze-slice ran green before this point — the
-# stage boundary is operator-driven, as everywhere else in this pipeline. What IS
-# enforced is the reverse: while a change is open, `specify` refuses to open another on
-# the same feature (_active_version's open-guard), so a forgotten close-delta blocks the
-# next change rather than passing silently.
+# stage boundary is operator-driven, as everywhere else in this pipeline. And nothing
+# backstops a forgotten close either: MANY changes may be open at once, so `specify`
+# opens a new one rather than refusing while an earlier one is unclosed. A change that is
+# merged but never closed therefore sits in the open set indefinitely, holding the version
+# back — it is found by `cr-list` (every stage that asks which change shows it), not by
+# the next command refusing.
 #
-# Launch:  /appweaver close-delta [strategy]
+# WHICH CHANGE IS CLOSED IS ASKED, NEVER INFERRED. MANY changes may be open at once, and
+# active_version.json's `active_change` is only the most recently opened or activated —
+# every /appweaver specify overwrites it. Taking that field as "the" change is how a bare
+# close archives and version-bumps a change nobody merged while the merged one stays open.
+# This stage opens with the same list → pick → activate sequence as finalize-delta, plan,
+# implement, analyze-plan-delta and recall-delta, and the argument doubles as the answer
+# (`close-delta CR-…` skips the prompt). The pick is confirmed even when only one change is
+# open: this is the stage that spends a version number, and that is not undone.
+#
+# Launch:  /appweaver close-delta [CR-id]   (a bare id skips the prompt)
 # Prereq:  an OPEN change whose delta was merged by finalize-delta and whose slice
 #          passed /appweaver analyze-slice.
 # =============================================================================
 
 name: aw-spec-close-delta
-description: Close the open change — archive changes/<id>/ into changes/archive/, bump the minor version, clear active_change, and stamp that version into the feature's master headers (spec.md, backend-plan.md, and frontend-plan.md where the feature has a UI half), then anchor the close in the OKF freshness log. The final CR stage, run after finalize-delta merged the delta and analyze-slice verified the slice. The sole owner of the version spine; invokes no model and generates no code.
-version: 1.1.0
+description: Close ONE chosen open change — archive changes/<id>/ into changes/archive/, bump the minor version, clear active_change, and stamp that version into the feature's master headers (spec.md, backend-plan.md, and frontend-plan.md where the feature has a UI half), then anchor the close in the OKF freshness log. ASKS which change (a bare CR id as the argument skips the prompt) and confirms even a lone one, rather than taking whichever was last opened. The final CR stage, run after finalize-delta merged the delta and analyze-slice verified the slice. The sole owner of the version spine; invokes no model and generates no code.
+version: 1.4.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
+inputs:
+  user_input:
+    description: "Optional CR id of the change to close. 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
@@ -65,10 +104,21 @@ standards: []
 
 vars:
   active_change: ""
-  has_change: "false"
+  cr_choice: ""         # the LABEL the pick returns ("CR-… · wave 2 · title"); scripts take its first token
+  has_changes: "false"  # from cr-list — the DIRECTORY's answer to "is anything open", not the ledger's
   version: ""
   stamped_docs: ""      # which master headers version-stamp actually rewrote
   stamped_count: "0"
+  history_filled: "false"   # whether the merge's `(pending)` Change History row was completed here
+  # The CONTEXT's spine, moved only when the closing change carried a model delta.
+  # Defaulted so the outputs read a real value on a behaviour-only close, where the step
+  # runs and correctly declines to bump.
+  delta_model_exists: "false"
+  context_bumped: "false"
+  context_version: ""
+  context_version_before: ""
+  context_bump_reason: ""
+  bounded_context: ""
 
 workflow:
 
@@ -88,23 +138,76 @@ workflow:
     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 close-delta."
 
-  # 2. There must be a change to close. On the BOOTSTRAP path (implement → build →
-  #    analyze-slice) there is none and this stage does not apply at all.
+  # 2. WHICH CHANGE IS BEING CLOSED. The evidence is changes/<CR-id>/ on disk; a change
+  #    already closed has moved to changes/archive/. On the BOOTSTRAP path (implement →
+  #    build → analyze-slice) there is none and this stage does not apply at all.
+  #    `matched_label` resolves a CR id passed as the argument to the whole option string,
+  #    which is how a bare `close-delta CR-…` skips the prompt.
+  - 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 close. A change is opened by /appweaver specify and merged by /appweaver finalize-delta before it can be closed here. If you have not merged yet, run /appweaver finalize-delta → analyze-slice first. A change already closed is under changes/archive/."
+
+  # single_option_confirm so a feature with exactly one open change still confirms the id
+  # out loud. This is the stage that spends a version number and archives the change's
+  # documents, and neither is undone.
+  - id: pick_change
+    action: user_select
+    prompt: "Which open change is being CLOSED? Close the change finalize-delta MERGED and analyze-slice then verified — closing one that was never merged archives its delta documents and spends a version number on work the masters do not carry. To withdraw an unmerged change instead, stop and run /appweaver recall-delta, which archives it and bumps nothing."
+    options_from_variable: change_options
+    preselect_from: matched_label
+    single_option_confirm: true
+    outputs:
+      - { name: cr_choice, from: selection }
+
+  # Make the chosen change the ACTIVE one, and VALIDATE it in the same call: cr-activate
+  # refuses an id the ledger does not carry, which here means a directory with no ledger row
+  # — cr-archive would find nothing to drop from the open set and the version would move for
+  # a change the ledger never knew about.
+  - id: activate
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-activate
+    args: ["--cr-id", "{{cr_choice}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: active_change, from: "$.active_change" }
+
+  # 2a. The version BEFORE the bump, for the log line below. cr-archive computes and
+  #     returns the new one; this is no longer the selector.
   - id: read_change
     action: execute_script
     script: { ref: actions }
     subcommand: version-read
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: active_change, from: "$.active_change" }
-      - { name: has_change,    from: "$.has_change" }
       - { name: version,       from: "$.version" }
 
-  - id: require_change
-    action: verify_context
-    require_true: has_change
-    on_false: stop
-    on_false_message: "No open change on this feature — nothing to close. A change is opened by /appweaver specify (or design) and merged by /appweaver finalize-delta before it can be closed here. If you have not merged yet, run /appweaver finalize-delta → analyze-slice first."
+  # 2b. DID THIS CHANGE TOUCH THE DOMAIN MODEL? Asked HERE, before the archive, because
+  #     cr-archive moves the change's model delta out from beside the master and into
+  #     changes/archive/<id>/ — after that the evidence is gone from where this question
+  #     looks for it. The answer decides whether the CONTEXT version moves at step 4c.
+  - id: cr_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-paths
+    args: ["--cr-id", "{{active_change}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: delta_model,        from: "$.delta_model" }
+      - { name: delta_model_exists, from: "$.delta_model_exists" }
+      - { name: context_dir,        from: "$.context_dir" }
 
   # 3. Pre-execution hooks.
   - id: resolve_pre_hooks
@@ -133,20 +236,53 @@ workflow:
       - { name: previous_version, from: "$.previous" }
       - { name: archived_dir,     from: "$.archived_dir" }
 
-  # 4b. STAMP the number just computed into the two master headers, so spec.md,
-  #     backend-plan.md and active_version.json all carry it from the same instant by the
-  #     same mechanism. Previously backend-plan.md's header was bumped by the MODEL back at
-  #     finalize-delta (guessing the target — the number was never passed to it) and
-  #     spec.md's header was bumped by nobody, so it sat at v1.0 for the life of the
-  #     feature. Deterministic and idempotent; only the header value moves.
+  # 4b. STAMP the number just computed into the two master headers AND into this change's
+  #     Change History row, so spec.md, backend-plan.md, the row and active_version.json all
+  #     carry it from the same instant by the same mechanism. Previously backend-plan.md's
+  #     header was bumped by the MODEL back at finalize-delta (guessing the target — the
+  #     number was never passed to it) and spec.md's header was bumped by nobody, so it sat
+  #     at v1.0 for the life of the feature.
+  #
+  #     --cr-id is what completes the row. finalize-delta appends it at MERGE time, a stage
+  #     before this number exists, so it writes `(pending)` in the Version cell rather than
+  #     version-read's prediction of the bump: a change that merged and never closed would
+  #     otherwise leave spec.md asserting a version nothing ever issued. The row is found by
+  #     its CR cell, and only a still-pending cell is written — a row already carrying a
+  #     number belongs to a change that closed, and rewriting it would rewrite history.
+  #     Deterministic and idempotent; only the values move.
   - id: stamp_version
     action: execute_script
     script: { ref: actions }
     subcommand: version-stamp
-    args: ["--feature-dir", "{{feature_dir}}", "--version", "{{version}}"]
+    args: ["--feature-dir", "{{feature_dir}}", "--version", "{{version}}", "--cr-id", "{{active_change}}"]
+    outputs:
+      - { name: stamped_docs,   from: "$.stamped" }
+      - { name: stamped_count,  from: "$.count" }
+      - { name: history_filled, from: "$.history_row_filled" }
+
+  # 4c. THE CONTEXT'S OWN VERSION, which is a DIFFERENT spine from the feature's. The
+  #     feature version says what this feature shipped; domain-model.md is shared by every
+  #     feature in the bounded context, so a change to it is a change to all of them and no
+  #     single feature's number can record it. The model's header has always declared
+  #     itself script-stamped and specify forbids the authoring model from writing it —
+  #     this is the step that makes both statements true.
+  #
+  #     Conditional on the change having carried a model delta: a behaviour-only change
+  #     leaves domain-model.md alone at finalize and must leave its version alone here.
+  #     `bumped: false` is a normal outcome, not a failure — most changes never touch the
+  #     model — so on_error: continue and the gate is the report, not a stop.
+  - id: bump_context_version
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: context-version-bump
+    args: ["--feature-dir", "{{feature_dir}}", "--cr-id", "{{active_change}}", "--touched-model", "{{delta_model_exists}}"]
     outputs:
-      - { name: stamped_docs,  from: "$.stamped" }
-      - { name: stamped_count, from: "$.count" }
+      - { name: context_bumped,          from: "$.bumped" }
+      - { name: context_version,         from: "$.version" }
+      - { name: context_version_before,  from: "$.previous" }
+      - { name: context_bump_reason,     from: "$.reason" }
+      - { name: bounded_context,         from: "$.context" }
 
   # 5. Anchor the CLOSE in the OKF bundle's freshness journal (log.md, OKF §7).
   #    finalize-delta logs the MERGE; this logs the SHIP — the version bump is the event
@@ -180,4 +316,11 @@ outputs:
   previous_version: "{{previous_version}}"
   archived_dir: "{{archived_dir}}"
   stamped_docs: "{{stamped_docs}}"
-  next: "Change {{active_change}} CLOSED — archived to {{archived_dir}}, version {{previous_version}} -> {{version}}, stamped into {{stamped_count}} master header(s) ({{stamped_docs}}). spec.md, backend-plan.md and active_version.json now all read {{version}} — and frontend-plan.md too where the feature has a UI half ({{stamped_docs}} names what was actually rewritten); the masters describe the shipped state and the feature is free to take a new change. Next: /appweaver run → deploy, or start the next change with /appweaver specify."
+  # The bounded context's own spine — a DIFFERENT number from the feature's, moved only
+  # when this change carried a model delta. context_bumped=false on a behaviour-only
+  # change is the correct outcome, not a skipped step.
+  bounded_context: "{{bounded_context}}"
+  context_version: "{{context_version}}"
+  context_version_bumped: "{{context_bumped}}"
+  model_touched: "{{delta_model_exists}}"
+  next: "Change {{active_change}} CLOSED — archived to {{archived_dir}}, version {{previous_version}} -> {{version}}, stamped into {{stamped_count}} master header(s) ({{stamped_docs}}) and into this change's Change History row (row completed={{history_filled}} — it read `(pending)` from the moment finalize-delta merged, because the number did not exist until now; false means it was already filled, which is the ordinary outcome of a re-run). spec.md, backend-plan.md, that row and active_version.json now all read {{version}} — and frontend-plan.md too where the feature has a UI half ({{stamped_docs}} names what was actually rewritten); the masters describe the shipped state and the feature is free to take a new change. Bounded context `{{bounded_context}}`: context version moved={{context_bumped}} ({{context_version_before}} -> {{context_version}}) — {{context_bump_reason}}. That number is the CONTEXT's, not this feature's: domain-model.md is shared by every feature in it, so only a change that merged a model delta moves it. THE LANE PLANS STILL STAND WHERE THEY WERE AUTHORED: finalize-delta merged this change into spec.md and domain-model.md only, because backend-plan.md / frontend-plan.md are DERIVED from those two and nothing derives them again on its own. Re-derive with /appweaver plan main (it carries DA-n / WA-n forward and asks before rewriting), then /appweaver analyze-plan re-anchors the spec↔plan gate — it repairs and stops only once NO change is open, and runs read-only until then. Next: /appweaver run → deploy, or start the next change with /appweaver specify."