aw-spec-cli 0.1.9 → 0.1.11

package/assets/.appweaver/stack-profiles/java-spring.json

@@ -6,9 +6,9 @@
   "ecosystem": "java",
   "root": "src/main/java/",
   "run_from": "root",
-  "build": "./mvnw package -DskipTests",
-  "test": "./mvnw test",
-  "run": "./mvnw spring-boot:run",
+  "build": "./mvn clean install",
+  "test": "./mvn test",
+  "run": "./mvn spring-boot:run",
   "detect": [
     "pom.xml",
     "build.gradle"

package/assets/.appweaver/templates/spec-template.md

@@ -13,10 +13,18 @@
 <!--
   AGGREGATE = FEATURE. This spec covers ONE aggregate (e.g. Order) and is the
   single LIVING source of truth for its whole lifecycle. Every operation on it
-  (CreateOrder, UpdateOrder, …) is a USER STORY below — NOT a separate feature.
-  A later requirement is a new US-n added here as a delta (see .appweaver/changes/
-  and delta-spec-template.md), never a new spec folder. One spec + one design.md
-  (specs/[Aggregate]/design.md) — the DESIGN derives from THIS document.
+  (CreateOrder, UpdateOrder, …) is a REQUIREMENT below (FR-n) — NOT a separate
+  feature and NOT a user story. A later requirement is a new FR-n added here,
+  never a new spec folder. One spec + one design.md (specs/[Aggregate]/design.md)
+  — the DESIGN derives from THIS document.
+
+  THIS DOCUMENT HOLDS NO USER STORIES. A story is an execution SLICE over this
+  spec and lives beside it in stories/, citing the FR-/BR- ids it delivers. This
+  spec is authored ONCE and stories never merge back into it: when a story needs
+  the contract itself to change, update-spec folds it back through specify's
+  validate loop and appends a Change History row. Design and code trace to the
+  FR-/BR- ids here, never to a story id — which is what lets the backlog churn
+  without disturbing the design.
 
   Section order is intentional: establish the business need and scope, then the
   stable core the aggregate IS (requirements → rules → constraints → entities →
@@ -215,10 +223,10 @@
   State each as CHECKABLE, and cite the rule or principle it was lifted from.
 -->
 
-- **UX-001**: [Accessibility conformance — e.g. every user-facing surface MUST meet [standard, level]; every task in the User Stories is completable keyboard-only. — lifted from UX-II, ux/accessibility-standards.md]
+- **UX-001**: [Accessibility conformance — e.g. every user-facing surface MUST meet [standard, level]; every task the requirements above describe is completable keyboard-only. — lifted from UX-II, ux/accessibility-standards.md]
 - **UX-002**: [Interaction states — e.g. every asynchronous operation MUST present its loading, empty, partial-failure, recovery and success states; no state leaves the user without a next action. — lifted from UX-IV, ux/interaction-states.md]
 - **UX-003**: [Content and language — e.g. user-facing text uses the ubiquitous language of Key Entities; every error names what happened and what to do next; regulated wording is reproduced verbatim. — lifted from UX-V, ux/content-design.md]
-- **UX-004**: [Journey integrity — e.g. each US-n is completable without leaving this aggregate's surface; destructive actions are confirmed and reversible. — lifted from ux/journey-mapping.md]
+- **UX-004**: [Journey integrity — e.g. each FR-n is completable without leaving this aggregate's surface; destructive actions are confirmed and reversible. — lifted from ux/journey-mapping.md]
 - **UX-005**: [Responsiveness-as-a-limit — e.g. an interaction acknowledges input within [n] ms and shows progress past [n] s. A front-end bound; the server-side budget it depends on is CN-nnn.]
 
 ## Edge Cases & Exceptional Scenarios
@@ -232,54 +240,6 @@
 - What happens when [boundary condition, e.g., the same order is submitted twice]?
 - How does the system handle [error scenario, e.g., a referenced product no longer exists]?
 
-## User Stories *(prioritized)*
-
-<!--
-  Prioritized user journeys (P1 = most critical). Each MUST be INDEPENDENTLY
-  TESTABLE — implementing just one still yields a viable slice of value that can be
-  developed, tested, deployed, and demonstrated on its own.
-
-  Give each a STABLE id (US-1, US-2, …); design sections trace to these ids. Each
-  story exercises specific System Requirements / Business Rules — cite them so the
-  spine (US ↔ FR/BR ↔ design ↔ code) stays exact. On this living spec, note when a
-  story entered or changed: "Added: vX.Y (CR-…)" / "Modified: vX.Y (CR-…)".
--->
-
-### US-1 - [Brief Title] (Priority: P1)   ·   _Added: v1.0_
-
-[Describe this user journey in plain language.]
-
-**Why this priority**: [The value and why it ranks here.]
-
-**Exercises**: [FR-001, FR-003, BR-001]
-
-**Acceptance Criteria**:
-
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
-2. **Given** [initial state], **When** [action], **Then** [expected outcome]
-
-**Independent Test**: [How this story is verified on its own and the value it delivers.]
-
----
-
-### US-2 - [Brief Title] (Priority: P2)   ·   _Added: v1.0_
-
-[Describe this user journey in plain language.]
-
-**Why this priority**: [The value and why it ranks here.]
-
-**Exercises**: [FR-…, BR-…]
-
-**Acceptance Criteria**:
-
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
-
-**Independent Test**: [How this story is verified on its own.]
-
----
-
-[Add more user stories as needed (US-3, US-4, …), each with a priority and a stable id.]
-
 ## Success Criteria *(mandatory)*
 
 <!--
@@ -294,16 +254,67 @@
 - **SC-003**: [User-satisfaction metric, e.g., "90% of first-time users complete an order without assistance."]
 - **SC-004**: [Business metric, e.g., "Reduce order-related support tickets by 50%."]
 
+## Story Coverage
+
+<!--
+  GENERATED — DO NOT HAND-EDIT. Everything between the two AW:COVERAGE markers is
+  rewritten wholesale from the stories/ directory, which is the source of truth: each
+  story's `exercises:` frontmatter says which requirements it delivers, and this table is
+  that relation read the other way round. Hand-edit it and your edit is gone at the next
+  write; change who delivers what by editing the story.
+
+  It answers the question the contract cannot answer about itself — who is building this,
+  and what is nobody building. A requirement with no story is a requirement nobody has
+  started; a requirement whose stories are all closed is DELIVERED, which is the rule
+  analyze-code and the pre-deploy gate key on. "Delivered" is never "a story closed" —
+  a follow-on may still carry the remainder.
+
+  Scoped to FR- and BR-, because those are the ids a story cites. The lifted sections
+  (CN-/DC-/IC-/UX-) are constraints the design and the gates trace, not slices of work.
+
+  Fenced out of the ledger ON PURPOSE. The sha256 that guards this document covers the
+  CONTRACT, and this section is not contract — it is a projection of the backlog. Were it
+  inside the hash, creating a story would look like an unledgered spec edit and refuse the
+  next update-stories; were it visible to the diff, adding a story would read as a
+  requirement change and mint a version row. So spec-check, spec-diff and ledger-append
+  all cut this block out before they look at anything.
+-->
+
+<!-- AW:COVERAGE:BEGIN -->
+| Requirement | Open stories | Closed / cancelled |
+|-------------|--------------|--------------------|
+| _(none yet — run /appweaver update-stories to raise the backlog)_ | | |
+<!-- AW:COVERAGE:END -->
+
 ## Change History
 
 <!--
-  The living-truth ledger. Every applied change request appends a row here, carrying
-  the version it ships as. finalize-delta writes the row when it merges the delta;
-  close-delta then archives the CR, bumps the minor version in active_version.json and
-  stamps that same number into this document's **Version** header — one mechanism, one
-  stage, so header, row and active_version.json never disagree. Newest last.
+  The living-truth ledger, and the sync anchor between this spec and its story backlog.
+
+  Each row names the requirement ids that version touched. Every story records the spec
+  version it last synced at (spec_version: in its frontmatter), so a story is stale when
+  some row above its version names an id that story cites — one version comparison, no
+  per-requirement content hashing. update-stories reads the rows to refresh the backlog;
+  update-spec appends one when it folds a hand-edited story back into this document.
+
+  The ledger is hand-written, so it is guarded. active_version.json carries a sha256 of
+  this whole file as of the last ledger-aware write. A body that has changed while the
+  version stands still is a hand edit that skipped the ledger: update-stories and
+  check-stories refuse until a row is added, because otherwise every affected story goes
+  quietly stale and nothing says so.
+
+  Version numbers have a single writer, so the header, the newest row and
+  active_version.json never disagree: close-delta bumps the minor version in
+  active_version.json and stamps that same number into this document's **Version**
+  header. Newest last.
+
+  THE "Requirements changed" CELL IS GENERATED. specify computes it from a diff of the
+  document it just wrote — including the v1.0 row below, whose placeholder ids are
+  replaced with the ones the finished spec actually carries. A row that names the ids
+  somebody believed it changed is worth nothing to a story trying to find out whether it
+  is stale; only a row derived from the document is.
 -->
 
-| Version | Date | Change | User stories | CR |
-|---------|------|--------|--------------|-----|
-| v1.0 | [DATE] | Initial specification | US-1 | — |
+| Version | Date | Change | Requirements changed | Stories |
+|---------|------|--------|----------------------|---------|
+| v1.0 | [DATE] | Initial specification | FR-001…FR-00n, BR-001…BR-00n | — |

package/assets/.appweaver/templates/story-template.md

@@ -0,0 +1,107 @@
+---
+id: [Feature-NNN]
+type: functional
+status: open
+title: [one line — the outcome this story delivers]
+exercises: []
+spec_version: [vN.N]
+depends_on: []
+follows:
+work_item:
+created: [DATE]
+---
+
+<!--
+  USER STORY  —  one execution slice over a feature's spec.
+
+  Canonical home: specs/<Feature>/stories/<Feature-NNN>.md
+  Execution artefacts, once story-spec has run: specs/<Feature>/stories/<Feature-NNN>/
+
+  A story is a slice of work over a spec that is already written. It is NEVER a proposal
+  to change the spec — nothing here merges back into spec.md. When a story genuinely
+  needs the contract to change, update-spec folds it back through specify's
+  checklist -> clarify -> validate loop, and the spec's Change History gains a row.
+
+  ONE STORY, ONE FEATURE. A story whose design touches a second feature is failed by
+  analyze-story-design. Cross-feature ordering goes in depends_on, not in a second story.
+
+  FRONTMATTER — every field the gates read lives here, so checking the backlog is a
+  directory scan rather than a markdown parse.
+
+    id            Minted by the kit: the feature name plus the next free number in
+                  stories/. user-story refuses to write over an existing file, so a
+                  collision is an add/add git conflict, never a silent overwrite.
+                  change-story-id corrects it while it is still legal — see below.
+
+    type          functional | technical
+                  functional  delivers requirement ids; exercises must be non-empty.
+                  technical   a refactor, dependency upgrade or performance fix. Changes
+                              no requirement, so exercises stays empty and the EXISTING
+                              TEST SUITE is the oracle: analyze-slice fails the story if
+                              any test was MODIFIED, not only if a test is red. A test
+                              that had to change means behaviour changed, and the work
+                              was a functional story citing an FR-. Technical stories
+                              deliver no requirement and do not count toward the
+                              "no open stories" completeness rule.
+
+    status        open | closed | cancelled
+                  cancelled is what keeps "open" meaningful — abandoned work that stays
+                  open blocks its requirement from ever reading as delivered.
+
+    exercises     The FR-/BR- ids this story delivers, e.g. [FR-003, BR-002]. This is the
+                  behavioural anchor: design and code trace to these ids, never to a story
+                  id. A requirement is DELIVERED when it has NO OPEN STORIES — not when a
+                  particular story closed, because a follow-on may carry the remainder.
+
+    spec_version  The spec version this story last synced at. A row above this version
+                  naming an id in exercises means the story is stale; check-stories
+                  reports it and update-stories acts on it. Restamped on every sync.
+
+    depends_on    Story ids that must land first, e.g. [Payment-004]. About CODE ordering,
+                  not spec: implement warns on an open dependency, which is where calling
+                  into code that does not exist starts to cost something. close-story
+                  warns but does not block — a dependency still being open does not make
+                  this story's own work wrong. A cycle is rejected at authoring time.
+
+    follows       On a follow-on only: the story id this one carries the remainder of.
+                  When the spec moves under a story that already has a story-spec,
+                  update-stories leaves that story untouched and mints a follow-on
+                  instead. There is no superseded status; the link is the whole record.
+
+    work_item     Optional tracker id (JIRA-1234). The kit's id and the tracker's id stay
+                  separate so the kit depends on no particular tracker.
+
+  CHANGE-STORY-ID IS LEGAL only while the story is open and stories/<ID>/ does not exist.
+  After story-spec runs, the id is in that directory, in the story-spec and story-design,
+  in the OKF log, in commit messages and branch names — most of which the kit cannot
+  rewrite.
+
+  stories.md beside this file is a GENERATED index. Never hand-edit it; it is rebuilt
+  from this directory, which is what keeps close-story conflict-free.
+-->
+
+# [Feature-NNN] — [Title]
+
+## Story
+
+As a [role], I want [capability], so that [outcome].
+
+## Requirements delivered
+
+<!-- One line per id in exercises:, saying what THIS story delivers of it. A story
+     rarely delivers a whole requirement; say which part. Empty for a technical story. -->
+
+- **[FR-00n]** — [the part of this requirement this story delivers]
+
+## Acceptance
+
+<!-- Checkable statements, in the spec's vocabulary. These are what analyze-slice pairs
+     tests against. For a technical story, state the no-behaviour-change invariant here
+     and name the suite that proves it. -->
+
+- [ ] [observable outcome]
+
+## Notes
+
+<!-- Optional: sequencing, risks, what is deliberately out of this slice. Anything that
+     belongs to the CONTRACT belongs in spec.md via update-spec, not here. -->