aw-spec-cli 0.1.15 → 0.1.16

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

@@ -4,7 +4,8 @@
 # Spec-anchored pipeline, spec phase. The spec is the CONTRACT and a story is an
 # execution SLICE over it. The two directions between them each have their own
 # workflow and neither is shared: sync-stories carries the SPEC forward into the
-# backlog; /appweaver update-spec folds a hand-edited STORY back into the contract.
+# backlog; /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 them apart is what stops the spec->story rule having two implementations.
 #
 # WHAT THIS READS. The spec's `## Change History` — the version ledger. Each row names
@@ -110,7 +111,7 @@
 # =============================================================================
 
 name: aw-spec-sync-stories
-description: "Raise and refresh the story backlog of the ACTIVE feature from its spec. Reads the spec's Change History ledger to find the requirements that have moved since the backlog was last in step, groups them into execution slices, asks before disturbing a story someone already has open, and writes one story per slice — creating, updating in place, or minting a follow-on where a story plan already exists. Slicing is steered by an opening strategy word: `single-run` puts the whole work set into ONE story, splitting it along its dependencies only where that story could not be picked up as one piece, and reporting the split either way; omitted, the number of slices is decided from the requirements. The grouping declares which slices stand behind which, and the kit computes DELIVERY WAVES from those edges — wave N holds the stories whose every dependency sits below it, so stories sharing a wave have no ordering between them and may be picked up in parallel. Writes `depends_on:` and `wave:` into each story's frontmatter, breaks any declared cycle deterministically, and regenerates the spec's Story Coverage block. Writes no requirements — /appweaver specify and /appweaver update-spec own the contract."
+description: "Raise and refresh the story backlog of the ACTIVE feature from its spec. Reads the spec's Change History ledger to find the requirements that have moved since the backlog was last in step, groups them into execution slices, asks before disturbing a story someone already has open, and writes one story per slice — creating, updating in place, or minting a follow-on where a story plan already exists. Slicing is steered by an opening strategy word: `single-run` puts the whole work set into ONE story, splitting it along its dependencies only where that story could not be picked up as one piece, and reporting the split either way; omitted, the number of slices is decided from the requirements. The grouping declares which slices stand behind which, and the kit computes DELIVERY WAVES from those edges — wave N holds the stories whose every dependency sits below it, so stories sharing a wave have no ordering between them and may be picked up in parallel. Writes `depends_on:` and `wave:` into each story's frontmatter, breaks any declared cycle deterministically, and regenerates the spec's Story Coverage block. Writes no requirements — /appweaver specify and /appweaver sync-spec own the contract."
 version: 1.1.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
@@ -342,6 +343,19 @@ workflow:
       for what the LAST row named and leave the hand edit unnamed and unreconciled.
       Resolve the state above, then re-run. (State: {{ledger_state}}.)
 
+  # 3a. THE TWO STATES THAT PASS `ok` AND SHOULD NOT PASS HERE. spec-check's decisive branch
+  #     asks only whether a version ROW sits above the version the kit last recorded, and
+  #     never opens the body — so `ledgered_edit` and `header_behind` are ok:true with a
+  #     document nobody has re-baselined, and every LATER edit lands inside that same window
+  #     and passes the same test. Syncing from there raises a backlog from rows that are
+  #     recorded and a body that is not. The module is shared with plan, plan-ui,
+  #     analyze-design, story-plan, analyze-slice and both implements — the fence is the
+  #     same wherever spec.md is read and not stamped.
+  - id: spec_state_guard
+    action: include
+    module: .appweaver/orchestrator/modules/spec-state-gate.orch.yaml
+    with: { command: "/appweaver sync-stories" }
+
   # 4. THE WORK SET. See the header for why it spans versions rather than reading the
   #    newest row alone, and for the v1.0 case.
   - id: ledger_read
@@ -363,6 +377,9 @@ workflow:
       - { name: synced_floor,      from: "$.synced_floor" }
       - { name: floor_source,      from: "$.floor_source" }
       - { name: latest_version,    from: "$.latest_version" }
+      - { name: non_story_csv,     from: "$.non_story_csv" }
+      - { name: non_story_any,     from: "$.non_story_any" }
+      - { name: work_kind,         from: "$.work_kind" }
 
   # 4a. AN EMPTY LEDGER STOPS THE RUN. The table is there and carries no version row, which
   #     means the spec has never been versioned. There is no "since" to sync from, and
@@ -382,17 +399,48 @@ workflow:
       /appweaver sync-stories. (If the spec was written by hand, add a row naming the
       requirement ids it introduced and re-run spec-stamp.)
 
+  # 4a-bis. WHAT MOVED THAT NO STORY CAN BE RAISED FOR. Constraints and success criteria
+  #     travel in the same version rows as requirements, and this workflow can act on
+  #     neither: a story's `exercises:` is FR-/BR- only, because those are DELIVERED, while a
+  #     CN-/DC-/IC-/UX- is MET and an SC- is SCORED. Until now that meant a row naming only
+  #     those produced an empty work set and a run that stopped with "the backlog is already
+  #     in step" — about the exact ids story-plan-check had just reported as stale.
+  #
+  #     BEFORE the work gate and INDEPENDENT of it, on purpose. A row naming FR-001 AND
+  #     CN-001 has real story work, so the gate below passes and the run continues — and
+  #     branching this notice on "no work" would then have said nothing at all about the
+  #     constraint, which is the same silence one case over. It fires on the ids, never on
+  #     the shape of the run.
+  - id: non_story_notice
+    condition: "{{non_story_csv}} != ''"
+    action: verify_context
+    require_value: non_story_csv
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: >
+      ALSO MOVED, AND NOT SLICEABLE: {{non_story_csv}}. These are carried by stories, not
+      delivered by them, so this run raises nothing for them and none of the writes below
+      touches them.
+      • CN-/DC-/IC-/UX- are BOUNDS. Every open story is built to satisfy the feature's whole
+        constraint set, so a moved bound touches all of them: re-run /appweaver story-plan on
+        each open story to design against the new wording, and see .appweaver/SPEC-EDIT-PROTOCOL.md
+        §4.2 for the by-hand reconciliation until /appweaver sync-spec ships.
+      • SC- are feature-level OUTCOMES, scored at /appweaver analyze-slice against the whole
+        feature — no story claims one, and none should.
+
   # 4b. NOTHING TO DO IS NOT AN ERROR. Every version row is at or below the oldest open
   #     story's stamp: the backlog is already in step. Stopping here rather than running an
-  #     empty grouping keeps the no-op cheap and the message honest.
+  #     empty grouping keeps the no-op cheap and the message honest. Left as `work_any`
+  #     (FR-/BR- only) deliberately — the non-story notice above has already fired by the
+  #     time this is reached, so a constraint-only row now stops with its reason SAID.
   - id: work_gate
     action: verify_context
     require_true: work_any
     on_false: stop
     on_false_message: >
-      The backlog is already in step with {{spec_file}} at {{latest_version}} — every
-      requirement a version row names has either been delivered by a closed story or is
-      already carried by an open one synced past it. Nothing was written. ({{work_note}}.)
+      No story work: every requirement a version row names has either been delivered by a
+      closed story or is already carried by an open one synced past it, so the backlog is in
+      step with {{spec_file}} at {{latest_version}}. Nothing was written. ({{work_note}}.)
 
   # 4c. A REMOVED REQUIREMENT IS A DECISION, NOT A DEFAULT (E1). A row names what a version
   #     TOUCHED, and that includes ids it deleted. Those leave the work set — there is no
@@ -618,7 +666,8 @@ workflow:
     on_mismatch_message: >
       The grouping left these requirements out of every slice: {{unplaced_csv}}. No story
       will be written for them by this run. Re-run /appweaver sync-stories to place them,
-      or raise them by hand with /appweaver user-story.
+      or raise them by hand from .appweaver/templates/story-template.md (/appweaver add-story,
+      which mints the id and stamps the frontmatter, is ⌛ not yet built).
 
   - id: repeated_notice
     condition: "{{repeated_csv}} != ''"
@@ -708,7 +757,8 @@ workflow:
         the grouping produced no slice for any of them ({{work_count}} requirement(s) went
         in, {{group_count}} group(s) came out). Nothing was declined and nothing was
         written — re-run /appweaver sync-stories, and if it comes back empty again, raise
-        the stories by hand with /appweaver user-story
+        the stories by hand from .appweaver/templates/story-template.md (/appweaver add-story
+        is ⌛ not yet built)
 
   - id: nothing_declined
     condition: "{{skipped_csv}} != ''"
@@ -828,7 +878,8 @@ workflow:
           - THE SPEC IS THE CONTRACT AND THIS IS A SLICE OF WORK OVER IT. Nothing here
             changes it. If writing this story exposes something the spec gets wrong or
             leaves out, say so in Notes and leave the requirement alone — the contract
-            moves through /appweaver update-spec, never through a story.
+            moves through /appweaver sync-spec (⌛ not yet built — until it is, the hand
+            route is .appweaver/SPEC-EDIT-PROTOCOL.md), never through a story.
           - Frontmatter: set `id:` to {{p.story}}, `exercises:` to exactly
             [{{p.requirements_csv}}], `status: open`, and `spec_version:` to
             {{latest_version}}. Give it a `title:` that names the OUTCOME a reviewer would
@@ -845,18 +896,19 @@ workflow:
           - "## Requirements delivered": one line per id, saying what THIS story delivers
             OF that requirement. A story rarely delivers a whole requirement; name the
             part. Quote no requirement in full — the spec is the wording.
-          - "## Constraints" IS NOT OPTIONAL AND IS THE HALF MOST OFTEN LOST. Read the
-            spec's Constraints & NFRs (CN-), Data Classification (DC-), Integration
-            Contracts (IC-) and Experience Standards (UX-) sections, and its Experience
-            Scope, and carry BY ID every entry that binds this slice — with one line each
-            saying what this slice has to do about it. Where the slice has a user-facing
-            surface, the UX- standards and the device / browser / assistive-technology
-            floors apply and MUST be listed: prototype, design-ui and implement-ui author
-            from the spec and the story, so a standard not carried here is a standard this
-            slice will be built without. Do NOT add these ids to `exercises:` — that field
-            is FR-/BR- only, because it is the delivery relation, and a constraint is not
-            delivered, it is met. Write "None" only for a class the spec genuinely leaves
-            empty or that genuinely does not touch this slice.
+          - "## Constraints" — THE IDS ARE STAMPED FOR YOU; WRITE THE LINE EACH. The kit
+            lifts every CN-, DC-, IC- and UX- the spec declares into this story's
+            `constraints:` frontmatter, because they are declared aggregate-wide and so the
+            feature's whole set binds every slice of it. That field is the gate surface;
+            this section is what makes it READABLE. Write one line per id saying what THIS
+            slice has to do about it, and where one genuinely does not apply here, say so
+            plainly in its line — do not omit it. An omission used to be indistinguishable
+            from a bound nobody noticed, which is exactly how a slice gets built without one.
+            Carry the Experience Scope floors (device / browser / assistive technology) in
+            the same way wherever this slice has a UI surface: implement-ui authors from the
+            spec and the story, so a floor not stated here is one it will be built without.
+            Do NOT add these ids to `exercises:` — that field is FR-/BR- only, because it is
+            the delivery relation, and a constraint is not delivered, it is met.
           - "## Acceptance": checkable statements in the spec's vocabulary, covering every
             requirement in `exercises:` and every constraint listed above that this slice
             can be observed to meet. These are what analyze-slice pairs tests against, so
@@ -966,11 +1018,11 @@ workflow:
           - WHERE AN ID IT ALREADY CITED HAS CHANGED WORDING, restate what this story
             delivers of it and re-check every acceptance line that depended on the old
             reading. That is the whole reason this story is being touched.
-          - "## Constraints" is re-derived, not preserved: read the spec's CN-/DC-/IC-/UX-
-            sections and its Experience Scope again and carry by id what binds the slice as
-            it now stands. A constraint that has left the spec leaves this section; one that
-            has arrived is added, with the acceptance line that shows it is met. Never add
-            these ids to `exercises:`.
+          - "## Constraints" — the ids are re-stamped into `constraints:` for you from the
+            spec as it now stands; this section's LINES are yours. A bound that has left the
+            spec leaves this section; one that has arrived gets its line, with the acceptance
+            line that shows it is met. Say plainly where one does not apply to this slice
+            rather than dropping it. Never add these ids to `exercises:`.
           - NO IMPLEMENTATION DETAIL, and nothing here changes the spec. If the change
             reveals a problem with the contract, note it and leave the requirement alone.
 
@@ -988,7 +1040,36 @@ workflow:
         # the sync sees one feature's spec, and an edge added by hand may name work outside
         # it. `--wave` is set outright — it is derived from the union, so re-deriving it is
         # the only way it stays true.
-        args: ["--feature-dir", "{{feature_dir}}", "--story", "{{p.story}}", "--ids", "{{p.requirements_csv}}", "--version", "{{latest_version}}", "--follows", "{{p.follows}}", "--title", "{{p.group_title}}", "--depends-on", "{{p.depends_on_csv}}", "--wave", "{{p.wave}}"]
+        # `--constraints` is a BARE FLAG: the op has the feature dir, so it lifts the ids
+        # from spec.md itself. Nothing here enumerates them, because there is nothing to
+        # decide — spec constraints are declared aggregate-wide ("must ALWAYS hold for the
+        # aggregate, independent of any single operation"), so the feature's whole set binds
+        # every slice of it. This is what makes `constraints:` a gate surface the KIT
+        # writes; the body's "## Constraints" section keeps the per-slice prose and is
+        # reconciled against the field, never overwritten by it.
+        args: ["--feature-dir", "{{feature_dir}}", "--story", "{{p.story}}", "--ids", "{{p.requirements_csv}}", "--version", "{{latest_version}}", "--follows", "{{p.follows}}", "--title", "{{p.group_title}}", "--depends-on", "{{p.depends_on_csv}}", "--wave", "{{p.wave}}", "--constraints"]
+        outputs:
+          - { name: stamped_constraints_csv, from: "$.constraints_csv" }
+          - { name: constraints_unlined_csv, from: "$.unlined_csv" }
+
+      # 10e. THE RECONCILE REPORT. The stamp owns the ID SET and the model owns the LINE
+      #      each id gets — "what this slice has to do about it" is the reason the section
+      #      is worth reading, and a script cannot write it. So a bound that is now in the
+      #      frontmatter with no line in the body is announced rather than silently added:
+      #      the gate surface is already closed by the field, and this is only so the
+      #      missing sentence is loud.
+      - id: constraints_reconcile_notice
+        condition: "{{constraints_unlined_csv}} != ''"
+        action: verify_context
+        require_value: constraints_unlined_csv
+        equals: ""
+        on_mismatch: continue
+        on_mismatch_message: >
+          {{p.story}} is bound by {{stamped_constraints_csv}} — the ids are stamped into its
+          `constraints:` frontmatter, which is what implement, implement-ui and analyze-slice
+          read. These have no line under "## Constraints" saying what this slice does about
+          them: {{constraints_unlined_csv}}. Add one each, or say plainly that it does not
+          apply here. The bound holds either way; what is missing is the reader's half.
 
   # 11. THE RELATION, READ THE OTHER WAY ROUND. Every story declares what it delivers in
   #     its own `exercises:`; the spec's Story Coverage block is that relation viewed from