aw-spec-cli 0.1.16 → 0.1.17

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

@@ -1,178 +0,0 @@
----
-id: [Feature-NNN]
-type: functional
-status: open
-title: [one line — the outcome this story delivers]
-exercises: []
-constraints: []
-spec_version: [vN.N]
-depends_on: []
-wave: 1
-follows:
-designed_lanes: []
-dropped_lanes: []
-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-plan has run: specs/<Feature>/stories/<Feature-NNN>/
-  (story-backend-plan.md and story-frontend-plan.md — the ephemeral designs, one per
-  declared lane; every run appends a pass to each lane in scope, the latest pass wins,
-  and a hand edit to that pass is what implement builds)
-
-  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, sync-spec (⌛ not built yet — the hand route is
-  .appweaver/SPEC-EDIT-PROTOCOL.md) 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
-  analysis. 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/. The writer refuses to overwrite 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.
-
-    constraints   The spec-level bounds this slice must satisfy: the CN-/DC-/IC-/UX- ids,
-                  lifted from spec.md by the kit and never typed by hand. Spec constraints
-                  are declared aggregate-wide, so the feature's WHOLE set binds every slice
-                  of it and there is nothing to choose. This field is the gate surface —
-                  implement, implement-ui and analyze-slice read it — and the "## Constraints"
-                  section below is where each id gets the line saying what THIS slice does
-                  about it. Stamped by sync-stories; a story written before this field
-                  existed has no key at all, and its readers fall back to the section.
-
-    spec_version  The spec version this story last synced at. A row above this version
-                  naming an id in exercises OR constraints means the story is stale;
-                  check-stories reports it and sync-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.
-                  sync-stories writes this as a UNION with what is already here, so an
-                  edge added by hand — including one naming another feature's story — is
-                  never lost to a re-sync.
-
-    wave          The dependency LEVEL this story sits at, computed by sync-stories from
-                  depends_on:. Wave 1 means nothing has to land before it; wave N means
-                  every story in depends_on: sits in a wave below N. STORIES SHARING A WAVE
-                  HAVE NO ORDERING BETWEEN THEM and can be picked up in parallel — which is
-                  why it is a wave and not an order or a priority. A rank would have to
-                  invent a difference between two stories that genuinely have none, and the
-                  fact that they are equal is the useful half.
-
-                  It says when a story becomes ELIGIBLE, not when anyone should start it.
-                  Nothing waits for a whole wave to finish: a story is startable the moment
-                  its own dependencies are done, whatever else shares its wave. A story
-                  raised by hand floors at 1 — nothing is KNOWN to come first.
-
-    designed_lanes  Which lanes story-plan actually designed, e.g. [backend, frontend].
-    dropped_lanes   Which lanes it DROPPED, and why the pair exists: a story with no UI
-                  design either has no user-facing surface or had its UI lane dropped when
-                  it was designed — an undeclared frontend lane, or a frontend-plan.md
-                  missing or behind the spec — and one field cannot say which. Written by
-                  story-plan (never by sync-stories: stories are not designed there);
-                  designed accumulates across passes, dropped holds what has been dropped
-                  and not since designed. Both absent on a story that predates them, which
-                  implement-ui reports as exactly that rather than guessing.
-
-    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 plan,
-                  sync-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-plan runs, the id is in that directory's name, in the OKF log, in commit
-  messages and branch names — most of which the kit cannot rewrite. (The story plan's
-  TEXT never carries the id; its directory is its identity.)
-
-  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]
-
-## Constraints
-
-<!-- The spec-level bounds this slice must satisfy, carried BY ID from spec.md and never
-     restated — the spec is the wording, this is the subset that binds this story:
-
-       CN-  constraints & NFRs        DC-  data classification
-       IC-  integration contracts     UX-  experience standards
-
-     Plus the Experience Scope floors (device / browser / assistive technology) wherever
-     this slice has a UI surface. UX- and the floors are what stop a story being built to
-     a standard the product does not hold, and they are the half most often lost: they
-     reach no UI phase except through the story.
-
-     THE IDS ARE STAMPED FOR YOU into `constraints:` above — the kit lifts every one the
-     spec declares, because spec constraints bind the aggregate rather than a single
-     operation. This section is where each gets its LINE. Write one per id saying what
-     this slice has to do about it, and where one genuinely does not apply, say so in its
-     line rather than dropping it: an omission used to be indistinguishable from a bound
-     nobody noticed, which is how a slice gets built without one.
-
-     These are NOT in `exercises:`. That field is FR-/BR- only, because it is the
-     delivery relation — what this story DELIVERS — and a constraint is not delivered,
-     it is met. story-plan carries these ids into its design pass; analyze-slice
-     traces it. -->
-
-- **[UX-00n]** — [what this slice must satisfy of it]
-
-## 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 sync-spec, not here. -->