aw-spec-cli 0.1.14 → 0.1.16

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

@@ -3,7 +3,7 @@
 #
 # feature = AGGREGATE (e.g. Order). This is the FIRST step of the spec-anchored
 # pipeline: it fixes the aggregate boundary BEFORE any spec/design exists, so the
-# feature's single spec.md + design.md and every command (CreateOrder/UpdateOrder =
+# feature's single spec.md + its per-lane plans and every command (CreateOrder/UpdateOrder =
 # user stories) hang off one directory. It replaces guessing the aggregate out of prose in
 # `specify` — that is why finding #1 (feature=aggregate) is enforced here, not hoped for.
 #
@@ -19,7 +19,7 @@
 #   list-features (specs/ ∪ OKF aggregates) → user_select (existing | "+ create new") → [ask name] → set-feature
 #
 # Persists .appweaver/feature.json {"feature_directory":"specs/<Feature>"} so every
-# later command operates on it: the forward loop (specify/design/analyze-design/implement/
+# later command operates on it: the forward loop (specify/plan/analyze-design/implement/
 # build/analyze-slice/run/deploy) and the CR loop (analyze-delta-design/implement-delta/
 # finalize-delta/close-delta — the standalone `cr` is retired; specify and design author
 # the delta docs themselves).
@@ -124,5 +124,5 @@ outputs:
   feature_dir: "{{feature_dir}}"
   created: "{{created}}"
   spec_exists: "{{spec_exists}}"
-  note: "Active feature set in .appweaver/feature.json — the aggregate boundary for its single spec.md + design.md."
+  note: "Active feature set in .appweaver/feature.json — the aggregate boundary for its single spec.md and the per-lane plans derived from it (backend-plan.md / frontend-plan.md)."
   next: "/appweaver specify <what this feature does>   (authors {{feature_dir}}/spec.md; each operation = a user story)"

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

@@ -4,13 +4,14 @@
 # Spec-anchored pipeline, spec phase. feature = AGGREGATE (picked/created by
 # /appweaver select-feature, which sets .appweaver/feature.json). specify does
 # NOT guess or create the feature — it CONSUMES the active one, and is phase-pure
-# (spec side only; the single design.md is the `design` phase).
+# (spec side only; the per-lane plans are the `plan` / `plan-ui` phases).
 #
 # specify writes ONE artifact: spec.md, plus the Change History row that records what
 # it wrote. It does not touch stories/. The spec is the CONTRACT; a story is an
 # execution SLICE over it, and the two directions between them each have their own
-# workflow — /appweaver update-stories refreshes the backlog after the spec moves,
-# /appweaver update-spec folds a hand-edited story back into the contract. Keeping
+# workflow — /appweaver sync-stories refreshes the backlog after the spec moves,
+# /appweaver sync-spec (⌛ not yet built — .appweaver/SPEC-EDIT-PROTOCOL.md is the hand
+# route meanwhile) folds a hand-edited story back into the contract. Keeping
 # specify story-blind is what stops the spec->story rule having two implementations.
 #
 # Auto-detects first-vs-subsequent from spec.md:
@@ -32,7 +33,7 @@
 #      bootstrap diffs the finished document against nothing, which yields every id it
 #      carries and is exactly the v1.0 row's content. A row the model declared could omit a
 #      requirement the quality loop rewrote on its way past, and an omitted id is silent —
-#      update-stories would never learn it moved.
+#      sync-stories would never learn it moved.
 #   2. The row and the hash are written by ONE call (ledger-append), so a row can never
 #      exist without the hash that proves the body it describes.
 #   3. The ledger is checked on ENTRY, not only stamped on exit. A spec hand-edited with
@@ -42,11 +43,11 @@
 # Launch:  /appweaver specify [strategy] <what the feature needs, or what changes>
 #   e.g.  /appweaver specify Customers place an order for one or more items
 # Prereq:  /appweaver select-feature   (sets the active aggregate)
-# Next:    /appweaver update-stories   (turns the new/changed requirements into stories)
+# Next:    /appweaver sync-stories   (turns the new/changed requirements into stories)
 # =============================================================================
 
 name: aw-spec-specify
-description: Author or extend the specification of the ACTIVE feature (aggregate). The first call writes spec.md from the template; a later call edits spec.md in place, adding the requirements the input describes and amending the ones it changes. Both paths run the checklist/clarify/validate converge loop over spec.md. An extend appends a Change History row whose requirement ids are COMPUTED from a before/after diff, and re-baselines the ledger hash. Writes no stories — /appweaver update-stories owns the backlog. Spec phase only; design is separate.
+description: Author or extend the specification of the ACTIVE feature (aggregate). The first call writes spec.md from the template; a later call edits spec.md in place, adding the requirements the input describes and amending the ones it changes. Both paths run the checklist/clarify/validate converge loop over spec.md. An extend appends a Change History row whose requirement ids are COMPUTED from a before/after diff, and re-baselines the ledger hash. Writes no stories — /appweaver sync-stories owns the backlog. Spec phase only; design is separate.
 version: 3.4.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
@@ -101,7 +102,7 @@ vars:
   disturbed_csv: ""          # which of them
   disturbed_ids: ""          # the same, as a list — the options of the per-requirement ask
   disturbed_stories: ""      # the open stories citing those ids
-  disturbed_flying: ""       # the subset already past story-spec — a follow-on, not an edit
+  disturbed_flying: ""       # the subset already past story-plan — a follow-on, not an edit
   may_change: ""             # the requirements the author approved for amendment
   approved_csv: ""           # the same, normalised
   preserve_csv: ""           # disturbed minus approved — restored and re-expressed additively
@@ -239,7 +240,7 @@ workflow:
         story, never an "As a … I want …" block, never a Given/When/Then acceptance
         scenario, and never a section for any of those. A story is an execution slice
         that lives beside this file in stories/ and cites the ids below; it is written
-        by /appweaver update-stories, not here. Design and code trace to the ids in
+        by /appweaver sync-stories, not here. Design and code trace to the ids in
         this document, which is what lets the backlog churn without disturbing them.
       - SPECIFY IS THE ONLY PHASE THAT READS THE DOMAIN RULES. Design and implement
         work from the spec/design, never the domain docs — so this spec is the SOLE
@@ -291,7 +292,7 @@ workflow:
         read this section — so a bound the SERVICE must meet stays a CN-, cross-referenced.
         HIGH-LEVEL ONLY, and this is the rule that matters most: every entry is a standard
         the whole product holds to, checkable on ANY surface. NEVER a screen, page, layout,
-        navigation model, component or visual-design choice — the prototype and design.ui.md
+        navigation model, component or visual-design choice — the prototype and frontend-plan.md
         settle those, and an entry satisfiable only one way is a design decision smuggled
         into the spec. A per-feature interaction BEHAVIOUR stays an EARS FR-n; only the
         standard that governs every such behaviour is a UX-n.
@@ -301,7 +302,7 @@ workflow:
         "Requirements changed" cell as the template has them. The kit rewrites that row
         from the finished document, so ids listed here are discarded — the same rule that
         makes every later version row an observation rather than a claim. Leave its Stories cell as "—";
-        update-stories fills that in when it raises the backlog.
+        sync-stories fills that in when it raises the backlog.
       - LEAVE THE "## Story Coverage" BLOCK ALONE, placeholder row and all. Everything
         between the AW:COVERAGE markers is generated from the stories/ directory after
         this step; anything written there by hand is discarded at the next write.
@@ -328,7 +329,7 @@ workflow:
   #
   #      unledgered_edit  spec.md was hand-edited and no Change History row was added.
   #                       Appending this run's row would bump the version past that edit
-  #                       without ever naming its ids, so update-stories could not
+  #                       without ever naming its ids, so sync-stories could not
   #                       reconcile it and every story citing it stays silently stale.
   #      delta_open       a change is open AND its delta-spec has been authored, so a delta
   #                       is measured against this master. Temporary — the guard retires with
@@ -392,6 +393,12 @@ workflow:
   #     nothing. Fed to the author as a preference, then checked against the diff below —
   #     the preference is a nudge, the check after the fact is the detector.
   #     Empty until the backlog exists, which degrades to "no preference, no ask".
+  #     CARRIED, NOT COVERED. `covered_csv` is the DELIVERY relation — the FR-/BR- ids open
+  #     stories are delivering — and a story also CARRIES the bounds it is built to satisfy.
+  #     Amending or removing a CN-/DC-/IC-/UX- moves ground somebody is standing on exactly
+  #     as amending an FR- does, and reading the narrower set here meant it raised no ask at
+  #     all and printed "nobody has open work" while stories were being built against it.
+  #     `carried_csv` is exercises: ∪ the `constraints:` frontmatter story-stamp lifts.
   - id: ext_story_context
     condition: "{{needs_bootstrap}} == false"
     action: execute_script
@@ -401,18 +408,21 @@ workflow:
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
       - { name: covered_csv, from: "$.covered_csv" }
+      - { name: carried_csv, from: "$.carried_csv" }
+      - { name: backlog_scanned, from: "$.ok" }
 
   # 6b-bis. WORD THE PREFERENCE FOR THE CASE AT HAND. The rule below is an argument for
   #     preferring an ADDITION over an amendment, and it only makes sense while somebody is
-  #     actually building. Interpolating covered_csv straight into it left a spec with no
+  #     actually building. Interpolating the carried set straight into it left a spec with no
   #     backlog reading an eight-line case for adding requirements under a blank list — the
   #     logic was vacuous ("one of those" names nothing) but the rhetoric was not, and the
   #     first extend of a spec nobody has stories against is exactly where amending in place
-  #     is the honest thing to do. Two ordered sets rather than a compound condition, the
-  #     same idiom as readdit_verdict_na/_real: the no-backlog wording is the default, and
-  #     the preference replaces it only when there is open work to protect.
-  #     Safe on the bootstrap path too — ext_story_context is skipped there, so covered_csv
-  #     is empty and the second step cannot fire.
+  #     is the honest thing to do. THREE ORDERED SETS rather than a compound condition, the
+  #     same idiom as readdit_verdict_na/_real: the no-backlog wording is the default, the
+  #     preference replaces it where there is open work to protect, and the scan-failed
+  #     wording is last so it wins over both.
+  #     Safe on the bootstrap path too — ext_story_context is skipped there, so nothing is
+  #     bound and only the default can fire.
   - id: ext_covered_none
     action: set
     vars:
@@ -424,11 +434,13 @@ workflow:
         without inventing a companion requirement to avoid touching anything.
 
   - id: ext_covered_some
-    condition: "{{covered_csv}} != ''"
+    condition: "{{carried_csv}} != ''"
     action: set
     vars:
       covered_note: >
-        THESE REQUIREMENTS ARE BEING BUILT RIGHT NOW: {{covered_csv}}. Where the change can
+        THESE REQUIREMENTS AND BOUNDS ARE BEING BUILT AGAINST RIGHT NOW: {{carried_csv}}.
+        (FR-/BR- are what open stories DELIVER; CN-/DC-/IC-/UX- are what they are built to
+        MEET — moving either moves ground someone is standing on.) Where the change can
         be expressed EITHER as an amendment to one of those or as a new requirement
         alongside it, prefer the new requirement — an amendment moves ground someone is
         standing on, and a requirement that gains a companion leaves their work correct as
@@ -438,6 +450,21 @@ workflow:
         Requirements NOT in that list have no open work against them: amend those in place
         wherever the change genuinely belongs to them.
 
+  # THE SCAN ITSELF CAN FAIL, and ext_story_context carries `on_error: continue` because a
+  # spec must stay editable when its backlog cannot be read. What it must not do is answer
+  # as though the scan had run and found nothing: nothing binds, ext_covered_some cannot
+  # fire, and the unconditional default above then tells the author NOBODY HAS OPEN WORK —
+  # the strongest claim available, on no evidence at all.
+  - id: ext_covered_unknown
+    condition: "{{backlog_scanned}} != true"
+    action: set
+    vars:
+      covered_note: >
+        THE BACKLOG COULD NOT BE READ THIS RUN, so this run does not know who is building
+        what. Treat every requirement as possibly under way: prefer adding a requirement to
+        amending one, and where you must amend, say in the Change History row exactly what
+        moved so the next sync can find every story that carries it.
+
   - id: ext_ctx
     condition: "{{needs_bootstrap}} == false"
     action: build_context
@@ -474,7 +501,7 @@ workflow:
       - {{covered_note}}
       - THIS DOCUMENT HOLDS NO USER STORIES. Do not add an "As a … I want …" block, a
         Given/When/Then acceptance scenario, or a section for either. Stories live in
-        stories/ beside this file and are written by /appweaver update-stories.
+        stories/ beside this file and are written by /appweaver sync-stories.
       - DO NOT TOUCH the "**Version**" header or the "## Change History" table, and leave everything between the AW:COVERAGE markers exactly as it is. Both are
         written by the kit after this step, from a diff of what you actually changed —
         editing them here produces a duplicate row and a version nothing agrees on.
@@ -651,7 +678,7 @@ workflow:
   #     Asked, not decided, and RECORD IS FIRST on purpose. spec.md is already written by this
   #     point: a run that refuses the ledger row leaves a document with no row, which is the
   #     `unledgered_edit` state the next run refuses outright. Recording a red spec is honest
-  #     and recoverable — the row names what moved, so update-stories still works, and the
+  #     and recoverable — the row names what moved, so sync-stories still works, and the
   #     failures are in the checklist file. Stopping is the safer-feeling option that costs
   #     more, so the prompt says what it costs and how to undo it.
   - id: quality_ask
@@ -691,7 +718,7 @@ workflow:
   #     diff for the reason this file opens with: a row the model DECLARED can omit an id it
   #     moved, and an omitted id is silent. v1.0 was the one exception — written by the
   #     author from a template whose placeholder reads "FR-001…FR-00n", so nothing
-  #     downstream could trust it and update-stories had to be told to enumerate from the
+  #     downstream could trust it and sync-stories had to be told to enumerate from the
   #     document instead. Diffing against no snapshot yields every id the finished spec
   #     carries, which is exactly the v1.0 row's content, so the first row is now derived
   #     the same way as the rest and the special case downstream goes away.
@@ -755,6 +782,26 @@ workflow:
       - { name: disturbing_csv,  from: "$.disturbing_csv" }
       - { name: reissued_csv,    from: "$.reissued_csv" }
       - { name: change_count,    from: "$.change_count" }
+      - { name: diff_warnings,   from: "$.warnings_note" }
+
+  # 10a-bis. IDS THE LEDGER CANNOT KEY TO A DEFINITION. The diff keys an id to the line that
+  #      DEFINES it and hashes the block under it; three authoring forms fall outside that,
+  #      and each one is silent — the requirement moves, change_count stays 0, no row is
+  #      appended, and the stamp below re-baselines the new body as clean. A standing
+  #      property of the document rather than a verdict on this run, so it is reported every
+  #      time until the requirement is rewritten in the shape the template uses.
+  - id: diff_warning_notice
+    condition: "{{diff_warnings}} != ''"
+    action: verify_context
+    require_value: diff_warnings
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: >
+      THE LEDGER CANNOT SEE PART OF THIS SPEC. {{spec_file}} states requirements in a form
+      the version diff cannot key to a definition, so an edit to one of them raises no
+      Change History row and no story citing it is ever told: {{diff_warnings}}. Rewrite them
+      in the template's shape — `- **FR-001**: …`, defined ABOVE the Change History table,
+      with any continuation on the lines directly under the id and no blank line between.
 
   # 10b. DID THIS MOVE GROUND SOMEONE IS STANDING ON? The diff is fact, so this is the
   #      detector the pre-authoring preference lacked: of the requirements this run
@@ -784,7 +831,7 @@ workflow:
   #      two outcomes differ sharply for the people downstream —
   #
   #        amend    the contract moves. Every open story citing it goes stale, and
-  #                 update-stories reconciles them: edited in place if no story-spec
+  #                 sync-stories reconciles them: edited in place if no story plan
   #                 exists yet, carried by a follow-on if one does (§5.5).
   #        add      the amended requirements go back to how they read, and the change is
   #                 expressed as new requirements alongside them. Nobody's work goes
@@ -803,10 +850,10 @@ workflow:
       This change MODIFIED or REMOVED requirements that people have open stories against.
         Requirements:   {{disturbed_csv}}
         Open stories:   {{disturbed_stories}}
-        Already in flight (story-spec exists): {{disturbed_flying}}
+        Already in flight (story plan exists): {{disturbed_flying}}
       Pick the ones this change MAY alter. Each one you pick moves the contract: its open
-      stories go stale, and update-stories reconciles them — editing a story in place, or
-      minting a follow-on where a story-spec already exists. Each one you LEAVE OUT is put
+      stories go stale, and sync-stories reconciles them — editing a story in place, or
+      minting a follow-on where a story plan already exists. Each one you LEAVE OUT is put
       back exactly as it read, and the change it was carrying is expressed as a new
       requirement alongside it, so the work already under way stays correct.
       Which may be changed?
@@ -1024,7 +1071,7 @@ workflow:
   #      It announces rather than stops. spec.md is already written by this point, so a stop
   #      here leaves a document on disk with no ledger row, which is the state the next run's
   #      tripwire refuses. Announcing keeps the ledger row honest — the violated ids ARE in
-  #      it, so update-stories still reconciles their stories — and moves them out of the
+  #      it, so sync-stories still reconciles their stories — and moves them out of the
   #      "preserved" column of the report into a column that says what actually happened.
   - id: ext_restore_check
     condition: "{{preserve_count}} != 0"
@@ -1045,7 +1092,7 @@ workflow:
     on_false_message: >
       The re-authoring did NOT restore {{violated_csv}} — you declined to change these and
       they moved anyway. They are recorded in this version's Change History row, so
-      /appweaver update-stories will reconcile the stories citing them rather than leaving
+      /appweaver sync-stories will reconcile the stories citing them rather than leaving
       them silently stale; check that the wording it landed on is one you can live with.
 
   # 10h. Re-read the affected stories from the FINAL document. After a restore, the
@@ -1065,6 +1112,23 @@ workflow:
     args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{disturbing_csv}}"]
     outputs:
       - { name: disturbed_stories, from: "$.story_csv" }
+      - { name: final_refs_ok,     from: "$.ok" }
+
+  # 10h-bis. THE SAME HONESTY THE PRE-AUTHORING SCAN NOW HAS. This step carries
+  #      `on_error: continue` so a failed re-scan cannot strand a written document, and on
+  #      failure disturbed_stories binds to nothing — which the post-restore report (law 45)
+  #      then reads as "nobody was disturbed", the one claim it must not make on no evidence.
+  - id: final_refs_unknown_notice
+    condition: "{{final_refs_ok}} != true"
+    action: verify_context
+    require_value: final_refs_ok
+    equals: "true"
+    on_mismatch: continue
+    on_mismatch_message: >
+      The final backlog re-scan did not complete, so the disturbed-stories list below is
+      NOT a list of nobody — it is unknown. The requirements this run moved are
+      {{disturbing_csv}}; run /appweaver sync-stories to find and reconcile the stories
+      carrying them.
 
   # 10i. AN ID THE LEDGER HAS ALREADY SPENT. Ids are permanent: re-issuing a retired one
   #      silently re-points stories, designs and code that have already shipped, which is
@@ -1087,7 +1151,7 @@ workflow:
   # 11. One call writes the row, bumps the version, stamps the header and re-hashes, so
   #     a row cannot exist without the hash that proves the body it describes. Skipped
   #     when the run changed no requirement — a version that names no ids is a bump
-  #     update-stories can do nothing with.
+  #     sync-stories can do nothing with.
   - id: ext_ledger_append
     condition: "{{change_count}} != 0"
     action: execute_script
@@ -1097,6 +1161,29 @@ workflow:
     outputs:
       - { name: ledger_version, from: "$.version" }
 
+  # 11a-bis. A PROSE-ONLY EDIT RE-BASELINES WITH NO ROW, AND SAYS SO. ledger-append is
+  #      conditional on change_count, because law 5 requires a version row to NAME at least
+  #      one id and an edit that touched no requirement has none to give. The stamp below is
+  #      not conditional, so this run rewrites the baseline and the document's own history
+  #      records nothing — which is right, and was silent. Aggregate Boundary, Experience
+  #      Scope and the rest of the load-bearing prose are read by every later phase and have
+  #      no staleness signal of their own; the least this can do is say that the baseline
+  #      moved and nothing recorded why.
+  - id: prose_only_notice
+    condition: "{{change_count}} == 0"
+    action: verify_context
+    require_value: needs_bootstrap
+    equals: "true"
+    on_mismatch: continue
+    on_mismatch_message: >
+      This run changed {{spec_file}} but moved no requirement: the diff found no id added,
+      modified or removed, so no Change History row was appended — a row must name at least
+      one id, and there is none to name. The document is still RE-BASELINED below, so the
+      next run reads it as clean. Nothing else is: if the edit touched load-bearing prose
+      (Aggregate Boundary, Experience Scope, Scope & Assumptions), no story is stale, no
+      sync will notice, and the only record is this message and your commit. Say what moved
+      in the commit message.
+
   # ═══════════════ STORY COVERAGE — both paths, before the baseline ══════════
   # 11b. Rewrite the spec's AW:COVERAGE block: every FR-/BR- in the document and the
   #      stories delivering it, read out of the stories/ frontmatter. The relation is
@@ -1105,7 +1192,7 @@ workflow:
   #
   #      Deliberately OUTSIDE the ledger. The hash guards the CONTRACT, and coverage is a
   #      projection of the backlog — spec-check, spec-diff and ledger-append all cut this
-  #      block out before they look. That is what lets user-story and update-stories write
+  #      block out before they look. That is what lets add-story and sync-stories write
   #      it too without a story creation reading as an unledgered spec edit, or a story
   #      raised against FR-003 reading as FR-003 having changed.
   #
@@ -1172,7 +1259,7 @@ outputs:
   spec_file: "{{spec_file}}"
   version: "{{version}}"
   requirements_changed: "{{changed_csv}}"          # every class — what the ledger row records
-  requirements_for_stories: "{{story_ids_csv}}"    # the FR-/BR- subset — what update-stories acts on
+  requirements_for_stories: "{{story_ids_csv}}"    # the FR-/BR- subset — what sync-stories acts on
   requirements_removed: "{{removed_csv}}"
   requirements_amended: "{{modified_csv}}"   # what finally stands amended, ask or no ask
   requirements_preserved: "{{held_csv}}"        # the ones the restore actually put back
@@ -1183,4 +1270,4 @@ outputs:
   stories_disturbed: "{{disturbed_stories}}"
   checklist_file: "{{checklist_file}}"
   checklist_quality: "{{checklist_passed}}/{{checklist_total}} items passing"
-  next: "spec.md is at {{version}}. Run /appweaver update-stories — it raises or refreshes the backlog for the requirements this run touched that a story can cite ({{story_ids_csv}}), and nothing else keeps the contract and its stories in step. That is the FR-/BR- subset of requirements_changed on purpose: the ledger row records every class this run moved, but only these are slices of work. Then /appweaver design authors design.md from the spec. READ THE FIELDS ABOVE BEFORE YOU DO: requirements_removed orphans every story citing them and needs deciding by hand; requirements_not_restored moved despite you declining them; requirements_reissued point at something other than what cited them before; open_change will be merged into this document by finalize-delta; and checklist_quality is what the spec actually scored."
+  next: "spec.md is at {{version}}. Run /appweaver sync-stories — it raises or refreshes the backlog for the requirements this run touched that a story can cite ({{story_ids_csv}}), and nothing else keeps the contract and its stories in step. That is the FR-/BR- subset of requirements_changed on purpose: the ledger row records every class this run moved, but only these are slices of work. Then /appweaver plan authors or conforms backend-plan.md to this spec version, and names the /appweaver plan-ui follow-up when a frontend lane is declared. READ THE FIELDS ABOVE BEFORE YOU DO: requirements_removed orphans every story citing them and needs deciding by hand; requirements_not_restored moved despite you declining them; requirements_reissued point at something other than what cited them before; open_change will be merged into this document by finalize-delta; and checklist_quality is what the spec actually scored."