aw-spec-cli 0.1.18 → 0.1.20

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

@@ -1,8 +1,9 @@
 # =============================================================================
 # aw-spec-specify (orchestrator) — author the SPEC for the ACTIVE feature
 #
-# Spec-anchored pipeline, spec phase. feature = AGGREGATE (picked/created by
-# /appweaver select-feature, which sets .appweaver/feature.json). specify does
+# Spec-anchored pipeline, spec phase. The feature is a capability scope the developer
+# picked/created with /appweaver select-feature (.appweaver/feature.json); it may act on
+# several aggregates, and several features may act on one. specify does
 # NOT guess or create the feature — it CONSUMES the active one, and is phase-pure
 # (spec side only; the single backend-plan.md is the `design` phase).
 #
@@ -15,7 +16,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 +41,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 +75,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 +124,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,12 +151,20 @@ 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
     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 specify."
+    on_empty_message: "No active feature. Run /appweaver select-feature first (pick or create the feature, e.g. Order or PatientRegistration), then re-run specify."
 
   # 1b. Resolve the BOUNDED CONTEXT's domain model — the canonical home of the aggregate
   #     root, its entities and its invariants, which this spec references and never
@@ -185,27 +215,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 +296,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,17 +322,21 @@ 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: |
-      Author the MASTER specification for this aggregate by filling out the
+      Author the MASTER specification for the feature `{{feature}}` by filling out the
       template in context. This is the first user story, US-1. Base everything on:
 
       {{USER_INPUT}}
 
       Rules for the content you generate:
-      - The feature IS the aggregate slice; set the Aggregate field and keep US-1's id.
+      - The feature is a CAPABILITY SCOPE the developer chose; set the Feature field to
+        `{{feature}}` and keep US-1's id. It may act on several aggregates, and other
+        features may act on the same ones: name every aggregate its requirements act on
+        in the Domain Model Reference's `**Acts on aggregate(s)**:` line, each in
+        backticks — every later command finds this feature's part of the model there.
       - Preserve the template's section order and headings.
       - SPECIFY IS THE ONLY PHASE THAT READS THE DOMAIN RULES. Design and implement
         work from the spec + the domain model, never the domain docs — so this pair is
@@ -334,7 +419,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 +428,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: |
@@ -356,11 +441,14 @@ workflow:
         section per root: its boundary (owns / references by id / out of scope), entities,
         value objects, domain events, and its invariants as stable BR-nnn ids. The spec
         cites those ids; this document defines them.
-      - IF THE MODEL ALREADY HAS CONTENT, this is the context's SECOND (or later) feature.
-        ADD this feature's aggregate as a new section and EXTEND the ubiquitous language.
-        Do NOT rewrite, renumber or "tidy" the aggregates already there — other specs cite
-        their ids, and a renumbered BR breaks every citation silently. Add `{{feature}}` to
-        the `Serving specs` line of any existing aggregate this feature also acts on.
+      - IF THE MODEL ALREADY HAS CONTENT, this is the context's SECOND (or later) feature,
+        and the aggregates it acts on may already be there. An aggregate that already has
+        a section is EXTENDED in place — add what this feature's requirements need, and add
+        `{{feature}}` to its `Serving specs` line — never duplicated, and never given a
+        second section named after the feature. Only an aggregate the model does not have
+        yet gets a new section. EXTEND the ubiquitous language. Do NOT rewrite, renumber
+        or "tidy" what is already there — other specs cite those ids, and a renumbered BR
+        breaks every citation silently.
       - DDD IS THE RATIFIED MODELLING STANDARD (NON-NEGOTIABLE → the modelling-methodology
         standard in the sticky standards, wired per-project via tech-rule-bindings
         "## /aw-spec-specify", plus the domain's own DDD overlay): a consistent ubiquitous
@@ -379,15 +467,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 +495,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 +509,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 +617,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

package/assets/.appweaver/scripts/bash/aw-inventory.sh

@@ -11,6 +11,21 @@
 #                            [--service-root <p>] [--ui-root <p>]   (the declared lane paths:
 #                            backend signals come from outside the UI subtree, frontend
 #                            signals from inside it, so neither carries the other's files)
+#   aw-inventory.sh propose  [--root <dir>] [--service-root <p>] [--ui-root <p>]
+#                            [--strategy structure|reference|persistence] [--out <md>] [--map <json>]
+#                            (Pass A+B+C: writes the editable specs/proposed-inventory.md
+#                            and the machine map onboard reads)
+#   aw-inventory.sh apply    [--root <dir>] [--proposal <md>] [--map <json>]
+#                            (validates the operator's edits to the proposal and
+#                            regenerates the machine map; reports the row it cannot resolve)
+#   aw-inventory.sh scaffold-context --context <Name> [--root <dir>] [--map <json>]
+#                            (creates specs/<Context>/<Feature>/ for every feature the map
+#                            assigns to that context — directories only, no documents)
+#   aw-inventory.sh concept  --bundle <dir> --aggregate <Name>
+#   aw-inventory.sh list-aggregates --bundle <dir> [--context <Name>] [--root <dir>] [--map <json>]
+#                            (--context drops concepts stamped with a DIFFERENT bounded
+#                            context; unstamped concepts are always kept. `pickable` offers
+#                            each concept as the features the map puts on it)
 #   aw-inventory.sh validate --bundle <dir> [--repo-root <dir>]
 set -euo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"