aw-spec-cli 0.1.14 → 0.1.16

package/assets/.appweaver/STACK-PROFILES.md

@@ -443,7 +443,7 @@ they are content the kit cannot invent:
 | `{{backend_ecosystem}}` / `{{frontend_ecosystem}}` | that lane's `ecosystem` |
 
 ```md
-## /aw-spec-design
+## /aw-spec-plan
 - guardrails/technology/{{stack}}/persistence.md
 - guardrails/technology/{{frontend_stack}}/ui-constitution.md
 ```

package/assets/.appweaver/orchestrator/modules/spec-state-gate.orch.yaml

@@ -0,0 +1,87 @@
+# =============================================================================
+# spec-state-gate (orchestrator) — the ledger tripwire, gated on STATE
+#
+# Included by every phase that READS spec.md as an oracle and does not stamp it.
+# It answers one question before that phase starts doing work:
+#
+#     is spec.md's version an honest name for spec.md's contents?
+#
+# WHY THE `ok` BOOLEAN IS NOT ENOUGH. spec-check's decisive branch asks only "is
+# there a version ROW above the version the kit last recorded", and never opens the
+# body. Two of its states are therefore ok:true with a body nobody has re-baselined:
+#
+#   ledgered_edit   a row exists above the recorded version — the edit was RECORDED,
+#                   but the kit has not re-hashed, so every LATER edit lands inside
+#                   the same window and passes the same test. Verified: a requirement
+#                   DELETED with no row naming it passes.
+#   header_behind   the same, with the document's header not yet caught up.
+#
+# Both are legitimate transient states and both have the same remedy — spec-stamp,
+# which re-baselines the hash and closes the window. That remedy is already named in
+# these phases' own refusal messages and in SPEC-EDIT-PROTOCOL.md.
+#
+# WHY NOT FLIP `ok` INSTEAD. Because specify is the stamper. It MUST keep accepting
+# both states — it is the command that resolves them — so making spec-check refuse
+# them would wedge the one workflow that can fix them. The distinction belongs at the
+# consumer, which is what this module is.
+#
+# WHAT IT DOES NOT DO. It never stamps, never edits and never repairs. Every state
+# spec-check already refuses (unrowed_edit, unledgered_edit, rollback, no_ledger,
+# delta_open) still stops on `ok`, with spec-check's own message.
+#
+# Inputs (via include `with`):
+#   command  — the phase being gated, quoted back in the failure message
+#
+# Produces: spec_ok / spec_state (the raw answers) and spec_current (true when the
+# state is one this phase may read from), for a caller that wants to say more.
+# =============================================================================
+
+name: spec-state-gate
+dialect: aw-spec.orchestrator/v1
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+workflow:
+
+  - id: spec_guard_read
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-check
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: spec_ok,    from: "$.ok" }
+      - { name: spec_state, from: "$.state" }
+
+  # The states spec-check itself refuses. Kept first and kept separate: its own error
+  # text says which one and why, and this module has nothing to add to it.
+  - id: spec_guard
+    action: verify_context
+    require_true: spec_ok
+    on_false: stop
+    on_false_message: "{{command}} cannot run: spec.md has moved outside the ledger (state: {{spec_state}}), so its version no longer names its contents and nothing read from it can be trusted. Record what changed in a Change History row naming the ids, then re-run spec-stamp to re-baseline — or, when the edit touched no requirement at all, spec-stamp alone (see .appweaver/SPEC-EDIT-PROTOCOL.md)."
+
+  # The two states that pass `ok` and still leave the body un-baselined. Ordered sets
+  # rather than a compound condition — the evaluator takes single comparisons only, so
+  # the refusal is the default and each acceptable state lifts it.
+  - id: spec_state_default
+    action: set
+    vars: { spec_current: "false" }
+  - id: spec_state_clean
+    condition: "{{spec_state}} == clean"
+    action: set
+    vars: { spec_current: "true" }
+  # A pre-ledger spec the kit has never stamped. Legitimate: nothing has been recorded
+  # against it, so there is no window between a row and a baseline to fall into.
+  - id: spec_state_unstamped
+    condition: "{{spec_state}} == unstamped"
+    action: set
+    vars: { spec_current: "true" }
+
+  - id: spec_state_gate
+    action: verify_context
+    require_true: spec_current
+    on_false: stop
+    on_false_message: "{{command}} cannot run: spec.md is in state '{{spec_state}}' — the edit is recorded in a Change History row, but the kit has not re-baselined the document, so its recorded hash still describes the text before the edit. Until it does, every FURTHER edit passes the same tripwire unnoticed, including a requirement deleted with no row naming it. Run /appweaver specify (which stamps), or re-run spec-stamp to re-baseline directly, then re-run {{command}}."

package/assets/.appweaver/orchestrator/orchestrator.py

@@ -1345,6 +1345,11 @@ class Orchestrator:
                 raise Stop(f"loop '{loop_id}': 'over' is not a list: {step.get('over')}")
             for idx, item in enumerate(items):
                 if max_it is not None and idx >= max_it:
+                    # Says so, the way the while branch does. A foreach that stops early
+                    # drops the tail of its list, and a run that drops work in silence
+                    # reports the same success as one that did all of it.
+                    self.emit(f"[loop] {loop_id} hit max_iterations={max_it} — "
+                              f"{len(items) - max_it} item(s) not run")
                     break
                 self.vars[as_name] = item
                 self.vars[as_name + "_index"] = idx

package/assets/.appweaver/orchestrator/rev-templates/domain-rule-bindings.skeleton.md

@@ -35,8 +35,15 @@ partition; preserve it exactly.
      into the spec's CN-/DC-/IC- (design/implement never see these files). -->
 - guardrails/projects/[project]/domain/[each generated domain rule file].md
 
-## /aw-spec-design
-_None — design loads no domain file. Domain reaches design only through the spec (BR-/CN-/DC-/IC-)._
+## /aw-spec-plan
+_None — the service lane's design loads no domain file. Domain reaches it only through the spec
+(BR-/CN-/DC-/IC-)._
+
+## /aw-spec-plan-ui
+_None — the frontend lane's design loads no domain file either: domain reaches frontend-plan.md
+as spec ids (UX-/CN-/DC-/IC-). Written out rather than left absent, because an absent heading and
+an empty one behave identically and only one of them is a decision. Keep this heading even in a
+backend-only repo — it costs nothing and records the partition._
 
 ## /aw-spec-implement
 _None — implement loads no domain file. Domain reaches implement only through design.md._
@@ -54,6 +61,6 @@ _None — implement loads no domain file. Domain reaches implement only through
 |---|---|---|
 | /aw-spec-constitution | [n] | domain principles |
 | /aw-spec-specify | [n] | author into spec (lift → CN-/DC-/IC-) |
-| /aw-spec-design | 0 | none — spec is the only domain input |
+| /aw-spec-plan | 0 | none — spec is the only domain input |
 | /aw-spec-implement | 0 | none — design is the only domain input |
 | /aw-spec-gate | [n] | conformance checklist (validate, don't author) |

package/assets/.appweaver/orchestrator/rev-templates/tech-rule-bindings.skeleton.md

@@ -43,7 +43,7 @@ refers to it directly, as-is.
      wired via domain-rule-bindings). No technology rule may appear under this heading. -->
 - guardrails/projects/[project]/service/domain-modelling.md
 
-## /aw-spec-design
+## /aw-spec-plan
 <!-- The as-built architecture / cross-cutting technical rules the design author mediates the spec
      against. NO domain file here — domain reaches design only as spec ids. -->
 - guardrails/projects/[project]/service/[as-built-architecture].md
@@ -62,7 +62,7 @@ refers to it directly, as-is.
 - guardrails/projects/[project]/service/[as-built-architecture].md
 
 ## /aw-spec-analyze-slice
-<!-- The design↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
+<!-- The spec↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
 - guardrails/projects/[project]/service/[testing/convention rule to validate against].md
 
 ## /aw-spec-adopt
@@ -86,13 +86,34 @@ refers to it directly, as-is.
      a runtime/hosting concern file. NOT data-migration (migration is the deferred later phase). -->
 - guardrails/projects/[project]/service/[runtime/hosting rule].md
 
-<!-- ## /aw-spec-ui-constitution — the FRONTEND LANE's heading. It is NOT written by the step
-     that authors this map; onboard's frontend rule-set step APPENDS it here, after the technical
-     headings and before the quick-reference table, but only where the scan found a UI in the
-     code. It maps the generated frontend/ lane rules (frontend/ui-constitution.md first), and
-     it is also the authoritative signal that this project HAS a frontend lane — a later
-     /appweaver constitution reads it to decide whether to author constitution.ui.md at all.
-     A backend-only repo simply never gets the heading.
+<!-- THE FRONTEND LANE'S THREE HEADINGS. None of them is written by the step that authors
+     this map; onboard's frontend rule-set step APPENDS all three here, after the technical
+     headings and before the quick-reference table, and ONLY where the scan found a UI in the
+     code. A backend-only repo never gets any of them, which is correct and not an omission.
+
+     ## /aw-spec-ui-constitution — the ratifiable lane standards, frontend/ui-constitution.md
+       first. It is also the authoritative signal that this project HAS a frontend lane: a
+       later /appweaver constitution reads it to decide whether to author constitution.ui.md
+       at all.
+     ## /aw-spec-plan-ui       — the DESIGN set /appweaver plan-ui works from when it authors
+       or conforms frontend-plan.md: composition, routing, client state, interaction states,
+       forms, accessibility, i18n, performance — whichever of those the generated set holds.
+     ## /aw-spec-implement-ui  — the CODE-GENERATION set /appweaver implement-ui builds
+       against: conventions, the client/service pairing, styling, forms, accessibility, i18n,
+       performance, testing — again, whichever exist.
+
+     THE TWO PHASE SETS OVERLAP ON PURPOSE. A concern like forms, accessibility, i18n or
+     performance carries a DESIGN half and an IMPLEMENT half of one rule — the design decides
+     the states, affordances and targets; implement realises them. A rule mapped under only
+     one heading loses the pairing, and the half that goes unread is the half that goes
+     unbuilt. Map such a file under BOTH.
+
+     WHY ALL THREE AND NOT JUST THE FIRST. `## /aw-spec-ui-constitution` alone wires the lane
+     for re-ratification and NOTHING else: with no `## /aw-spec-plan-ui`, plan-ui loads zero
+     mapped frontend rules and designs the experience from constitution.ui.md alone, while the
+     files it needed sit on disk unreferenced — and because an absent heading soft-continues,
+     nobody is told. Both phases ship (/appweaver plan-ui, /appweaver implement-ui), so both
+     headings are claims the kit CAN honour.
 
      Do NOT add /aw-spec-characterize or /aw-spec-parity in the DEV flow — characterize is
      opt-on-touch and parity is deferred to the migration phase. Add any other heading later
@@ -106,11 +127,17 @@ refers to it directly, as-is.
 | Command | Technical rule files | Role |
 |---|---|---|
 | /aw-spec-specify | 1 | the as-built modelling methodology the domain model is expressed in — no technology |
-| /aw-spec-design | [n] | as-built architecture the design author mediates the spec against |
+| /aw-spec-plan | [n] | as-built architecture the design author mediates the spec against |
 | /aw-spec-implement | [n] | code-generation set the generator builds against (from design.md) |
 | /aw-spec-implement-delta | [n] | same code-generation set, scoped to the open change's delta-design |
 | /aw-spec-build | [n] | layering + convention rules the compile-fixer respects |
-| /aw-spec-analyze-slice | [n] | conformance rules the design↔code gate validates against |
+| /aw-spec-analyze-slice | [n] | conformance rules the spec↔code gate validates against |
 | /aw-spec-adopt | [n] | technical reference set for the reversed design (brownfield) |
 | /aw-spec-constitution | [n] | the standards the technical constitution half is re-ratified from |
 | /aw-spec-run | [n] | runtime/execution conventions the app-run step honors (only if evidenced) |
+
+<!-- The frontend lane's rows are appended by the same step that appends its headings, and
+     only where the lane exists:
+| /aw-spec-ui-constitution | [n] | the ratifiable lane standards the UI constitution half is re-ratified from |
+| /aw-spec-plan-ui | [n] | the as-built experience rules plan-ui authors frontend-plan.md against |
+| /aw-spec-implement-ui | [n] | the as-built code-generation set implement-ui builds the UI against | -->

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

@@ -637,7 +637,8 @@ workflow:
         spec.md (a resolved [NEEDS CLARIFICATION] / Assumption) or log a deviation.
         Review items: {{review_items}}
       - "## How to proceed": resolve blocking gaps first; then the slice is a normal
-        feature — run /appweaver analyze-design (spec↔design gate) if desired, then
+        feature — run /appweaver plan (which renames this design.md to backend-plan.md and
+        conforms it) and then /appweaver analyze-design (the spec↔plan gate), then
         drive every change through the CR delta loop. If a change edits untested legacy
         behaviour with blast radius, characterize just that surface first (optional
         on-touch fence) — it is not a required phase.