aw-spec-cli 0.1.9 → 0.1.11

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

@@ -6,47 +6,54 @@
 # 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).
 #
+# 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
+# specify story-blind is what stops the spec->story rule having two implementations.
+#
 # Auto-detects first-vs-subsequent from spec.md:
-#   • BOOTSTRAP (no spec.md)  → author the MASTER spec (US-1) + init active_version.json.
-#   • DELTA (spec.md exists)  → delegate to the delta-spec module: open a change (cr-setup)
-#     and author the delta-spec ONLY. The master spec.md is left UNTOUCHED — the change
-#     stays OPEN; finalize-delta merges the delta into spec.md + design.md, and the
-#     change is not closed until close-delta at the end of the chain.
-#     (The former standalone `cr` capture's spec half now lives here.)
+#   • BOOTSTRAP (no spec.md)  → author the spec from the template + init active_version.
+#   • EXTEND (spec.md exists) → edit spec.md IN PLACE: add the requirements the input
+#     describes, and amend the ones it changes. No delta document, no open change, no
+#     merge — the spec is the living truth and this is a write to it.
+#
+# Both paths then run ONE converge block — checklist + clarify + validate — over
+# spec.md, and both finish by re-baselining the ledger hash.
 #
-# Both paths then run ONE converge block — checklist + clarify + validate — over the
-# document THIS invocation authored, never the other one:
-#   • BOOTSTRAP → the master spec, graded by the spec checklist.
-#   • DELTA     → the delta-spec, graded by a DELTA-SHAPED checklist written inside
-#                 changes/<cr-id>/. The master is not read, not graded, NOT written.
-# The pairing is bound from create-checklist's own output (checklist_file + target →
-# quality_target), so the checklist and the document it grades can never diverge.
-# Why it matters: the delta is authored relative to the master, so a "quality" rewrite
-# of the master mid-change would leave the delta computed against a stale baseline —
-# and in brownfield it would silently edit an adopted, code-derived spec that nothing
-# downstream re-checks for fidelity. Narrow rewrites run include_standards:false.
-# Accuracy of the delta AGAINST the master (id continuity, conflicts) stays where it
-# belongs: /appweaver analyze-delta-design.
+# THE LEDGER. spec.md's `## Change History` is the sync anchor between the contract and
+# its backlog: each row names the requirement ids that version touched, and each story
+# records the version it last synced at, so "is this story stale" is one integer
+# comparison. Three properties of how this workflow writes it are load-bearing:
 #
-# Forward paths:
-#   NEW    : specify → design → analyze-design → implement
-#   CHANGE : specify (delta-spec) → design (delta-design) → analyze-delta-design →
-#            implement-delta → build → finalize-delta → analyze-slice → close-delta
+#   1. The row is COMPUTED, not declared, on BOTH paths. An extend snapshots spec.md before
+#      authoring and diffs requirement ids after the converge loop has finished with it; a
+#      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.
+#   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
+#      no row is the ledger's one silent failure, and running specify over the top would
+#      bury that edit under a version bump that never named it.
 #
-# Launch:  /appweaver specify [strategy] <what the feature/change does>
+# 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)
 # =============================================================================
 
 name: aw-spec-specify
-description: Author the specification of the ACTIVE feature (aggregate). First call writes the master spec (US-1); a later call (spec.md exists) delegates to the delta-spec module to author a delta-spec ONLY (master spec.md untouched — finalize-delta merges it) and leaves the change OPEN. The checklist/clarify/validate loops grade whichever document the call authored, using a delta-shaped checklist on the change path. Spec phase only — design is separate.
-version: 2.3.0
+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.
+version: 3.4.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
 inputs:
   user_input:
-    description: What the feature (first call) or the change (later calls) should do, in natural language.
+    description: What the feature should do (first call), or what is being added or changed (later calls), in natural language.
     required: true
     bind: USER_INPUT
 
@@ -74,14 +81,44 @@ vars:
   spec_all_pass: "false"     # validation-loop guard, flipped by the validate query
   checklist_total: "0"       # bound by checklist-read
   checklist_passed: "0"      # stays 0 when the checklist has no items to score
-  cr_id: ""                  # set on the DELTA path only
-  cr_dir: ""                 # set on the DELTA path only — changes/<cr-id>/
-  quality_target: ""         # the document the converge loops grade AND rewrite:
-                             # spec.md (bootstrap) | delta-spec.md (delta). Bound from
-                             # create-checklist's own output so it always agrees with
-                             # the checklist. NEVER hand-set to spec_file on the delta
-                             # path — that is what silently drifts an adopted spec.
   version: ""                # current active_version.json version (for the report)
+  ledger_ok: "true"          # entry tripwire result; the bootstrap path has no ledger to check
+  ledger_state: "bootstrap"  # clean | unstamped | ledgered_edit | unledgered_edit | rollback | delta_open
+  ledger_error: ""
+  open_change: ""            # a delta change open on this feature — reported, and only
+                             # blocking once its delta-spec has actually been authored
+  snapshot: ""               # pre-authoring copy of spec.md; the diff's "before"
+  changed_csv: ""            # the ids this run actually touched — what the ledger row records
+  story_ids_csv: ""          # changed, narrowed to FR-/BR- — the only classes a story can cite
+  removed_csv: ""            # ids this run DELETED — every story citing one is orphaned (E1)
+  modified_csv: ""           # ids amended in place, as distinct from added or removed
+  disturbing_csv: ""         # modified ∪ removed — the ids an existing story could feel
+  change_count: "0"          # 0 on an extend that changed no requirement: no row is written
+  ledger_version: ""         # the version the row was written at
+  covered_csv: ""            # ids with OPEN stories, read before authoring as a preference
+  covered_note: ""           # that preference, WORDED for the case at hand — see ext_covered_*
+  disturbed_any: "false"     # did this run move a requirement someone is building against
+  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
+  may_change: ""             # the requirements the author approved for amendment
+  approved_csv: ""           # the same, normalised
+  preserve_csv: ""           # disturbed minus approved — restored and re-expressed additively
+  preserve_count: "0"        # 0 = everything was approved, so nothing is re-authored
+  marker_count: "0"          # [NEEDS CLARIFICATION] markers, counted before the model is asked
+  clarifications: []         # what the model made of them; empty when there were none to make
+  reissued_csv: ""           # ids this run re-used after the ledger had already spent them
+  held_csv: ""               # the preserved ids the restore actually put back
+  violated_csv: ""           # the preserved ids it did not — amended without approval
+  quality_accept: ""         # the author's answer when the spec ships still failing
+  readdit_pass: "false"      # guard for the restore's own quality loop
+  readdit_failing: ""        # what that loop found wanting in the requirements it minted
+  readdit_verdict: "true"    # that loop's verdict, or "nothing was re-authored" when it never ran
+  readdit_accept: ""         # the author's answer when the re-authored spec ships still failing
+  boot_row_version: ""       # non-empty once the v1.0 row has actually been written
+  stamp_hold: "false"        # true = do not re-baseline the hash; the document is unfinished
+  uncovered_csv: ""          # requirements with no story at all — nobody is building these
 
 workflow:
 
@@ -95,6 +132,11 @@ workflow:
       - { name: feature_dir, from: "$.feature_dir" }
       - { name: spec_file,   from: "$.spec_file" }
       - { name: spec_exists, from: "$.spec_exists" }
+      # needs_bootstrap = no spec.md, OR a first run that never finished. version-init raises
+      # a marker and only ledger-ids lowers it, so a bootstrap that died after writing spec.md
+      # is RE-RUN rather than mistaken for a spec to extend (which re-applied the same input
+      # over an unfinished v1.0 and bumped it to v1.1).
+      - { name: needs_bootstrap, from: "$.needs_bootstrap" }
 
   - id: require_feature
     action: verify_context
@@ -134,23 +176,30 @@ workflow:
     hooks_from_variable: before_hooks
 
   # ═══════════════════════ BOOTSTRAP — no spec.md yet ═══════════════════════
-  # Copy the spec template into the (already-existing) feature dir + init version.
-  - id: boot_scaffold
-    condition: "{{spec_exists}} == false"
+  # Init the version state, THEN copy the spec template into the (already-existing)
+  # feature dir. That order is the point: --bootstrap raises the unfinished-first-draft
+  # marker, and raising it BEFORE spec.md exists means no crash can leave a document on
+  # disk that the next fresh run mistakes for a spec to extend. Scaffolding first left a
+  # window of exactly two calls wide in which a bare template was on disk with no marker
+  # beside it — and a bare template is `unstamped`, which the entry tripwire passes.
+  # --bootstrap is specify's, not the primitive's: adopt inits the same file after
+  # reversing a real spec out of code, and must not be marked unfinished.
+  - id: boot_version_init
+    condition: "{{needs_bootstrap}} == true"
     action: execute_script
     script: { ref: actions }
-    subcommand: scaffold
-    args: ["--feature-dir", "{{feature_dir}}", "--allow-existing"]
+    subcommand: version-init
+    args: ["--feature-dir", "{{feature_dir}}", "--bootstrap"]
 
-  - id: boot_version_init
-    condition: "{{spec_exists}} == false"
+  - id: boot_scaffold
+    condition: "{{needs_bootstrap}} == true"
     action: execute_script
     script: { ref: actions }
-    subcommand: version-init
-    args: ["--feature-dir", "{{feature_dir}}"]
+    subcommand: scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--allow-existing"]
 
   - id: boot_ctx
-    condition: "{{spec_exists}} == false"
+    condition: "{{needs_bootstrap}} == true"
     action: build_context
     context:
       - "{{spec_file}}"                      # the copied template = section structure
@@ -173,18 +222,25 @@ workflow:
                                                      # no file and no ux/ rules mapped, the section resolves to
                                                      # "None" and the spec is unchanged from a backend-only one.
   - id: boot_generate
-    condition: "{{spec_exists}} == false"
+    condition: "{{needs_bootstrap}} == true"
     action: agent_author
     output_target: { type: file, path: "{{spec_file}}" }
     task: |
-      Author the MASTER specification for this aggregate by filling out the
-      template in context. This is the first user story, US-1. Base everything on:
+      Author the specification for this aggregate by filling out the template in
+      context. Base everything on:
 
       {{USER_INPUT}}
 
       Rules for the content you generate:
-      - The feature IS the aggregate; set the Aggregate field and keep US-1's id.
+      - The feature IS the aggregate; set the Aggregate field.
       - Preserve the template's section order and headings.
+      - THIS DOCUMENT HOLDS NO USER STORIES. Every operation on the aggregate
+        (CreateOrder, UpdateOrder, …) is a REQUIREMENT (FR-n) here — never a user
+        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
+        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
         carrier of the domain into the pipeline. Model the domain COMPLETELY here, or
@@ -205,7 +261,10 @@ workflow:
         but never how the adapter is built.
       - Write for non-technical business stakeholders.
       - Write System Requirements in EARS as the template shows (THE SYSTEM SHALL
-        / WHEN…/ IF…THEN / WHILE…/ WHERE…) — each atomic and testable.
+        / WHEN…/ IF…THEN / WHILE…/ WHERE…) — each atomic and testable. An EARS
+        requirement IS its own acceptance criterion; do not add a separate one.
+      - Give every requirement a STABLE id, numbered from 001 in its own class. Ids are
+        permanent: they are what stories cite and what design traces to.
       - Capture always-true BUSINESS invariants as Business Rules (BR-n), and state
         the aggregate boundary (what it owns vs references by id, and out of scope).
         Record reasonable defaults in Assumptions.
@@ -238,91 +297,253 @@ workflow:
         standard that governs every such behaviour is a UX-n.
         Where neither a UI constitution nor ux/ rules are in context there is nothing to
         lift: write "None (as of v1.0)" in both — never delete either section.
-      - This is v1.0: fill the initial Change History row's date and keep US-1's
-        "Added: v1.0" marker.
+      - This is v1.0: leave the initial Change History row's version, date and
+        "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.
+      - 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.
       - ALWAYS include a "## Success Criteria" section with 2-4 measurable,
-        technology-agnostic, verifiable SC-nnn outcomes derived from the acceptance
-        criteria. It is MANDATORY — never drop it; when a metric must be inferred,
-        state a reasonable, testable target rather than omitting the section.
+        technology-agnostic, verifiable SC-nnn outcomes derived from the requirements.
+        It is MANDATORY — never drop it; when a metric must be inferred, state a
+        reasonable, testable target rather than omitting the section.
       - Add at most 3 "[NEEDS CLARIFICATION: <question>]" markers, and only for
         choices that materially affect scope/UX and have no reasonable default.
       - Every section the template marks *(mandatory)* — at minimum System
-        Requirements and Success Criteria — plus Business Need, User Stories, and
-        the Change History row MUST be present and populated. The four lift sections
-        (Constraints & NFRs, Data Classification, Integration Contracts, Experience
-        Standards) and Experience Scope MUST also be present — populated when their rules
-        apply, else "None (as of v1.0)". You may
-        omit only a genuinely inapplicable OPTIONAL item (e.g. the WHERE optional-feature
-        requirement, or an empty Assumptions list) — never a mandatory section, and
-        never write "N/A".
+        Requirements and Success Criteria — plus Business Need and the Change History
+        row MUST be present and populated. The four lift sections (Constraints & NFRs,
+        Data Classification, Integration Contracts, Experience Standards) and Experience
+        Scope MUST also be present — populated when their rules apply, else
+        "None (as of v1.0)". You may omit only a genuinely inapplicable OPTIONAL item
+        (e.g. the WHERE optional-feature requirement, or an empty Assumptions list) —
+        never a mandatory section, and never write "N/A".
       - Do NOT embed any checklist and NO design/implementation.
 
-  # ═════════════════════════ DELTA — spec.md exists ═════════════════════════
-  # A later requirement = a new user story on the SAME aggregate. Delegate to the
-  # delta-spec module: it opens the change (cr-setup, single-active-change guarded) and
-  # authors the delta-spec ONLY — the master spec.md is left UNTOUCHED. The change
-  # stays OPEN; finalize-delta merges the delta into spec.md later in the chain. Runs in
-  # this context (shares vars + the DDD + domain sticky standards). The former standalone
-  # `cr` capture's spec half now lives here. Downstream: design (delta-design) →
-  # analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice →
-  # close-delta (close-delta is what finally archives the change and bumps the version).
-  - id: delta_spec_module
-    condition: "{{spec_exists}} == true"
-    action: include
-    module: .appweaver/orchestrator/modules/delta-spec.orch.yaml
-
-  # ══════ CONVERGE — checklist + clarify + validate, ON THE DOCUMENT JUST WRITTEN ══════
-  # These loops run on WHICHEVER document this invocation authored — the master spec on
-  # the bootstrap path, the delta-spec on the change path. They must NEVER write the
-  # master while a change is open: the delta is authored relative to the master, so
-  # mutating the master here would leave the delta computed against a stale baseline
-  # AND (brownfield) silently edit an adopted, code-derived spec that no downstream
-  # stage re-checks for fidelity. Hence quality_target — bound from the SAME script call
-  # that creates the checklist, so the checklist and the graded document cannot diverge.
+  # ═══════════════════════ EXTEND — spec.md already exists ═══════════════════
+  # 5. THE ENTRY TRIPWIRE. Before writing a word, establish that the document on disk is
+  #    the one the ledger describes. Two states stop the run, and both are states where
+  #    writing would destroy information rather than add it:
   #
-  # 5. Quality checklist (shared script — static content, NO model). Idempotent in
-  #    content; note it rewrites the file, so it is deliberately scoped to the path that
-  #    authored the document (a delta run no longer resets the master's scored boxes).
-  - id: create_checklist
-    condition: "{{spec_exists}} == false"
+  #      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
+  #                       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
+  #                       the delta family — but while both exist it is the one silent way
+  #                       the two ways of changing a spec collide. Narrowed to an AUTHORED
+  #                       delta because cr-setup scaffolds a delta-spec for every change it
+  #                       opens: gating on the open flag alone refused every extend for the
+  #                       whole life of a DESIGN-only change, which strands nothing, and the
+  #                       refusal named a chain the operator may be retiring. The message now
+  #                       also names the way OUT (cr-archive) rather than only the way through.
+  #
+  #    `unstamped` and `ledgered_edit` both pass: the first is a spec that predates the
+  #    ledger, the second is a hand edit that did write its row. Both are re-baselined by
+  #    the spec-stamp at the end of the run.
+  # No `on_error: continue`: spec-check reports every ledger STATE through its JSON with a
+  # zero exit, so a non-zero exit is the script itself failing. Continuing past that bound
+  # the gate's vars to nothing and produced the refusal message with its reason blanked out
+  # ("cannot write spec.md:  (State: .)"), which is the right decision told unreadably.
+  - id: ext_ledger_check
+    condition: "{{needs_bootstrap}} == false"
     action: execute_script
     script: { ref: actions }
-    subcommand: create-checklist
+    subcommand: spec-check
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: ledger_ok,    from: "$.ok" }
+      - { name: ledger_state, from: "$.state" }
+      - { name: ledger_error, from: "$.error" }
+      - { name: open_change,  from: "$.open_change" }
+      - { name: version,      from: "$.version" }
+
+  - id: ext_ledger_gate
+    condition: "{{needs_bootstrap}} == false"
+    action: verify_context
+    require_true: ledger_ok
+    on_false: stop
+    on_false_message: >
+      /appweaver specify cannot write spec.md: {{ledger_error}}
+      The Change History is how a story learns that a requirement it cites has moved —
+      a version that does not name the ids it changed leaves every affected story
+      stale with nothing to detect it. Resolve the state above, then re-run specify.
+      (State: {{ledger_state}}.)
+
+  # 6. Snapshot the document as it stands. This is the diff's "before", and it is what
+  #    lets the Change History row be computed from what the run actually did rather than
+  #    from what it claimed. Taken BEFORE authoring and consumed AFTER the converge loop,
+  #    so a requirement the quality pass rewrote in passing is still recorded.
+  - id: ext_snapshot
+    condition: "{{needs_bootstrap}} == false"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-snapshot
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: snapshot, from: "$.snapshot" }
+
+  # 6b. WHO IS BUILDING WHAT. A read-only scan of stories/ for the requirements that have
+  #     open stories against them. specify writes no stories, but it is about to change a
+  #     contract other people may already be building against, and knowing which ids those
+  #     are is the difference between an amendment that costs a re-sync and one that costs
+  #     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".
+  - id: ext_story_context
+    condition: "{{needs_bootstrap}} == false"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: story-refs
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: checklist_file,  from: "$.checklist_file" }
-      - { name: quality_target,  from: "$.target" }      # → spec.md
-
-  # Delta twin: a DELTA-SHAPED checklist (ADDED/MODIFIED/REMOVED completeness, merge
-  # readiness) written INSIDE changes/<cr-id>/, grading the delta-spec. The master
-  # checklist's items assume a full spec and would mis-fire here, which is exactly why
-  # this is a separate checklist rather than the same one re-pointed.
-  - id: create_delta_checklist
-    condition: "{{spec_exists}} == true"
+      - { name: covered_csv, from: "$.covered_csv" }
+
+  # 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
+  #     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.
+  - id: ext_covered_none
+    action: set
+    vars:
+      covered_note: >
+        NOBODY HAS OPEN WORK AGAINST ANY REQUIREMENT IN THIS SPEC. No story cites any id in
+        this document, so nothing you do here can strand work already under way. Amend an
+        existing requirement where the change genuinely belongs to it, and add a new one
+        where the change is genuinely new — let the contract read the way it should read,
+        without inventing a companion requirement to avoid touching anything.
+
+  - id: ext_covered_some
+    condition: "{{covered_csv}} != ''"
+    action: set
+    vars:
+      covered_note: >
+        THESE REQUIREMENTS ARE BEING BUILT RIGHT NOW: {{covered_csv}}. 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
+        written. This is a preference, not a prohibition: when the change genuinely
+        contradicts what one of them says, amend it. A contract that states two
+        incompatible things to avoid disturbing someone is worse than the disturbance.
+        Requirements NOT in that list have no open work against them: amend those in place
+        wherever the change genuinely belongs to them.
+
+  - id: ext_ctx
+    condition: "{{needs_bootstrap}} == false"
+    action: build_context
+    context:
+      - "{{spec_file}}"                                # the living spec — edited in place
+      - .appweaver/memory/constitution.domain.md       # same domain frame as the bootstrap path
+      - { path: .appweaver/memory/constitution.ui.md, optional: true }
+
+  - id: ext_generate
+    condition: "{{needs_bootstrap}} == false"
+    action: agent_author
+    output_target: { type: file, path: "{{spec_file}}" }
+    task: |
+      Update the specification in context — the living contract for this aggregate —
+      to carry this change:
+
+      {{USER_INPUT}}
+
+      Return the COMPLETE updated document. Rules:
+      - EDIT IN PLACE. This is the living spec, not a change document. Add what the
+        input describes; amend what it changes; leave everything else EXACTLY as it is,
+        character for character. Do not restate, reword, reorder or "improve" a
+        requirement the input did not touch — an unrelated edit here reads downstream
+        as a contract change and pulls stories into rework for nothing.
+      - NEW requirements take the NEXT FREE id in their class. Ids are permanent and
+        are NEVER re-issued: if FR-004 was removed at some point, the next functional
+        requirement is still FR-006 and not FR-004. Stories, designs and code cite
+        these ids, so a reused id silently re-points work that has already shipped.
+      - NEVER RENUMBER an existing requirement. If a requirement is genuinely obsolete,
+        remove it and say so — do not renumber the ones after it to close the gap.
+      - AMEND, don't duplicate. When the input changes existing behaviour, edit that
+        requirement where it stands. Adding a second requirement that contradicts the
+        first leaves the aggregate with two answers and no way to tell which holds.
+      - {{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.
+      - 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.
+      - Keep every section, in order. A section with nothing to say keeps its "None"
+        text; never delete one, and never write "N/A".
+      - Everything the bootstrap rules require of this document still holds: EARS form
+        for functional requirements, business-facing language, no implementation
+        mechanics, the domain lift into CN-/DC-/IC- and the experience lift into UX-,
+        stable ids throughout, and Success Criteria present and measurable.
+      - Where the change genuinely leaves an open question, mark it
+        "[NEEDS CLARIFICATION: <question>]" (at most 3, scope/UX/security only).
+
+  # ══════ CONVERGE — checklist + clarify + validate, over spec.md, both paths ══════
+  # One target now that the delta document is gone, so the checklist, the clarify loop
+  # and the validation loop all read and rewrite the same file the run authored. The
+  # loops may touch any part of the spec; that is deliberate and safe, because the
+  # Change History row is computed from a diff taken AFTER they finish rather than from
+  # a declaration made before they start.
+  #
+  # 6c. DROP THE AUTHORING ENVELOPE. build_context sets a STICKY context that every later
+  #      model step carries in front of its own, so the two constitutions the author needed
+  #      were re-sent with all ~10 converge calls — a checklist grading pass paying for the
+  #      domain rules on every iteration. The converge steps each declare what they read, so
+  #      emptying the envelope here costs nothing; the two that genuinely judge the domain
+  #      lift (validate and its patch) name the constitutions themselves.
+  - id: converge_ctx
+    action: build_context
+    context: []
+
+  # 7. Quality checklist (shared script — static content, NO model). Idempotent in content.
+  - id: create_checklist
     action: execute_script
     script: { ref: actions }
     subcommand: create-checklist
-    args: ["--feature-dir", "{{feature_dir}}", "--kind", "delta", "--change-dir", "{{cr_dir}}"]
+    args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: checklist_file,  from: "$.checklist_file" }
-      - { name: quality_target,  from: "$.target" }      # → changes/<cr-id>/delta-spec.md
+      - { name: checklist_file, from: "$.checklist_file" }
 
-  # 6. Resolve [NEEDS CLARIFICATION] markers interactively (≤3). Non-interactive
+  # 8. Resolve [NEEDS CLARIFICATION] markers interactively (≤3). Non-interactive
   #    runs answer with the first/recommended option (a documented default).
+  #
+  #    Counted by a script before the model is asked. Most runs leave no marker, and asking
+  #    a model to confirm that costs a round trip per run to be told "none" — the model's
+  #    real work is turning a marker into a question with answerable options, which is only
+  #    worth paying for once there is a marker to turn.
+  - id: spec_markers
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-markers
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: marker_count, from: "$.marker_count" }
+
   - id: extract_clarifications
+    condition: "{{marker_count}} != 0"
     action: agent_query
-    context: ["{{quality_target}}"]
+    context: ["{{spec_file}}"]
     include_standards: false
     task: |
-      Extract up to 3 unresolved "[NEEDS CLARIFICATION: <question>]" markers from
-      the document in context (a feature spec, or one change's delta-spec), most
-      scope/security/UX-impacting first. Return {"clarifications":[]} if there are none.
+      Extract up to 3 unresolved "[NEEDS CLARIFICATION: <question>]" markers from the
+      feature spec in context, most scope/security/UX-impacting first. Return
+      {"clarifications":[]} if there are none.
     schema: { clarifications: [ { id: c1, question: "<the question>", options: ["<answer A>", "<answer B>", "<answer C>"] } ] }
     mock: { clarifications: [] }
     outputs:
       - { name: clarifications, from: "$.clarifications" }
 
   - id: clarify_loop
+    condition: "{{marker_count}} != 0"
     action: loop
     over: "{{clarifications}}"
     as: c
@@ -336,18 +557,18 @@ workflow:
         answer_var: c_answer
       - id: resolve_clar
         action: agent_author
-        context: ["{{quality_target}}"]
-        include_standards: false           # rewrite-in-place: the graded document only
+        context: ["{{spec_file}}"]
+        include_standards: false           # rewrite-in-place: the spec only
         task: |
-          Replace the matching "[NEEDS CLARIFICATION]" marker in the document in
-          context with this answer and update the affected requirement/section
-          accordingly. Preserve structure and headings. If it is a delta-spec, stay
-          within the delta — keep every item's ADDED / MODIFIED / REMOVED placement.
+          Replace the matching "[NEEDS CLARIFICATION]" marker in the spec in context
+          with this answer and update the affected requirement/section accordingly.
+          Preserve structure, headings and every requirement id. Do not touch the
+          "**Version**" header or the "## Change History" table, and leave everything between the AW:COVERAGE markers exactly as it is.
             Question: {{c.question}}
             Answer:   {{c_answer}}
-        output_target: { type: file, path: "{{quality_target}}" }
+        output_target: { type: file, path: "{{spec_file}}" }
 
-  # 7. Spec-quality validation loop — evaluate the spec against the checklist,
+  # 9. Spec-quality validation loop — evaluate the spec against the checklist,
   #    fix failing items, re-check (max 3), then score the checklist file.
   - id: checklist_read
     action: execute_script
@@ -364,15 +585,22 @@ workflow:
     steps:
       - id: validate
         action: agent_query
-        context: ["{{checklist_file}}", "{{quality_target}}"]
+        # The domain and UI constitutions ride along HERE and nowhere else in the converge
+        # block: the Domain Lift and Experience Lift items ask whether the spec carries what
+        # those files impose, and that is not judgeable from the spec alone. Optional, not
+        # required — ext_ctx/boot_ctx already announce a missing domain constitution once,
+        # and repeating that announcement per iteration is noise, not signal.
+        context:
+          - "{{checklist_file}}"
+          - "{{spec_file}}"
+          - { path: .appweaver/memory/constitution.domain.md, optional: true }
+          - { path: .appweaver/memory/constitution.ui.md, optional: true }
         include_standards: false
         task: |
-          Evaluate the document under review (in context) against each checklist item
-          (in context, 1-based in order). The checklist's own title states which kind
-          of document it grades — a feature spec, or one change's delta-spec; judge it
-          as that kind and nothing more. An item passes when the document satisfies it.
-          (An item about remaining [NEEDS CLARIFICATION] markers passes once none
-          remain.) In "failing", quote the offending/absent part per failed item.
+          Evaluate the feature spec (in context) against each checklist item (in
+          context, 1-based in order). An item passes when the spec satisfies it. (An
+          item about remaining [NEEDS CLARIFICATION] markers passes once none remain.)
+          In "failing", quote the offending/absent part per failed item.
         schema: { all_pass: false, results: { "1": true, "2": false }, failing: [ { n: 2, issue: "<quote>" } ] }
         mock: { all_pass: true, results: {}, failing: [] }
         outputs:
@@ -382,41 +610,552 @@ workflow:
       - id: pass_break
         action: break
         condition: "{{spec_all_pass}} == true"
+      # Only while another pass remains. The loop is validate -> break-if-pass -> patch, so
+      # hitting max_iterations always landed on a PATCH nobody re-read: the document shipped
+      # with ungraded text and score_checklist wrote the pre-patch verdict into the checklist
+      # file. Skipping the last patch costs one model call less and makes the last thing that
+      # happened to the document a grading.
       - id: patch_spec
+        condition: "{{iteration}} != 2"
         action: agent_author
-        context: ["{{quality_target}}"]
+        context:
+          - "{{spec_file}}"
+          - { path: .appweaver/memory/constitution.domain.md, optional: true }
+          - { path: .appweaver/memory/constitution.ui.md, optional: true }
         include_standards: false
         task: |
-          Fix these quality failures in the document in context, preserving its
-          section order and headings. Do NOT add implementation detail; keep it
-          business-facing and testable.
-          If the document is a DELTA-SPEC: it describes one change, not the whole
-          feature. Fix it AS a delta — keep the ADDED / MODIFIED / REMOVED structure,
-          never expand it into a full specification, never copy in unchanged master
-          content to satisfy an item, and never edit the master spec.
+          Fix these quality failures in the spec in context, preserving its section
+          order, headings and every requirement id. Do NOT add implementation detail;
+          keep it business-facing and testable. Do NOT add user stories or acceptance
+          scenarios — this document holds neither. Do NOT touch the "**Version**"
+          header or the "## Change History" table, and leave everything between the AW:COVERAGE markers exactly as it is.
             Failures: {{spec_failing}}
-        output_target: { type: file, path: "{{quality_target}}" }
+        output_target: { type: file, path: "{{spec_file}}" }
 
   - id: score_checklist
     action: execute_script
     condition: "{{checklist_total}} != 0"
     script: { ref: actions }
     subcommand: checklist-apply
-    args: ["--file", "{{checklist_file}}", "--results", "{{spec_results}}"]
+    # --all-pass because the per-item map is the model's and a pass routinely comes back
+    # with a partial map or none at all, which scored a passing spec as "0/25 items passing".
+    args: ["--file", "{{checklist_file}}", "--results", "{{spec_results}}", "--all-pass", "{{spec_all_pass}}"]
     outputs:
       - { name: checklist_passed, from: "$.after_checked" }
 
-  # 8. Read the current version for the report (both paths).
-  - id: version_read
+  # 9b. THE SPEC STILL FAILS. The loop grades, patches, and grades again; when it runs out of
+  #     iterations the document is left failing and every step after here would have carried
+  #     on as if it had passed — appending a version row for a spec the run itself judged red,
+  #     with a checklist score beside it that need not agree.
+  #
+  #     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
+  #     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
+    condition: "{{spec_all_pass}} != true"
+    action: ask
+    prompt: |
+      The spec still fails checklist items after the quality loop gave up
+      ({{checklist_passed}}/{{checklist_total}} passing). The failures are listed in
+      {{checklist_file}}.
+        Outstanding: {{spec_failing}}
+      spec.md is ALREADY WRITTEN either way — the only question is whether this run records
+      what it changed.
+    options:
+      - "Record it — the version row is what keeps the stories in step; fix the spec next"
+      - "Stop — write no version row, and repair spec.md by hand first"
+    answer_key: quality_accept
+    answer_var: quality_accept
+
+  - id: quality_gate
+    condition: "{{spec_all_pass}} != true"
+    action: verify_context
+    require_value: quality_accept
+    equals: "Record it — the version row is what keeps the stories in step; fix the spec next"
+    on_mismatch: stop
+    on_mismatch_message: >
+      Stopped at your request with no version row written. The quality failures are listed in
+      {{checklist_file}}.
+      On a FIRST spec nothing else is needed: the bootstrap is still marked unfinished, so the
+      next specify re-authors it rather than extending it.
+      On an EXISTING spec, spec.md HAS been rewritten and the next specify will refuse it as an
+      unledgered edit until one of two things is true — add a Change History row naming the ids
+      you changed and re-run spec-stamp, or revert the document from the copy taken before this
+      run, which is beside it at {{snapshot}}.
+
+  # ═══════════════ THE FIRST LEDGER ROW — bootstrap only ═════════════════════
+  # 9b. The v1.0 row, OBSERVED. Every other version row is computed from a before/after
+  #     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
+  #     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.
+  #
+  #     on_error: continue — spec.md is already written, and a spec so empty that the diff
+  #     found no id at all must not be stranded on disk with no ledger row. It keeps what
+  #     the author wrote and says so in the run log.
+  - id: boot_diff
+    condition: "{{needs_bootstrap}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-diff
+    args: ["--feature-dir", "{{feature_dir}}", "--snapshot", ""]
+    outputs:
+      - { name: changed_csv,  from: "$.changed_csv" }
+      - { name: story_ids_csv, from: "$.story_ids_csv" }
+      - { name: change_count, from: "$.change_count" }
+
+  #     The hold is the other half of that on_error. spec-stamp runs on every path and
+  #     re-baselines the hash, so a soft-failed ledger-ids used to leave a first draft with
+  #     NO version row and a hash saying the document was in step — the next run's tripwire
+  #     reads `clean` and every tool that trusts the hash believes the spec is finished.
+  #     Held here and released only by a row that actually landed, so a bootstrap that did
+  #     not complete stays unstamped AND still marked pending: an honest re-author.
+  - id: boot_stamp_hold
+    condition: "{{needs_bootstrap}} == true"
+    action: set
+    vars: { stamp_hold: "true", version: "v1.0 (draft — no version row yet)" }
+
+  - id: boot_ledger_ids
+    condition: "{{needs_bootstrap}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: ledger-ids
+    args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{changed_csv}}"]
+    outputs:
+      - { name: boot_row_version, from: "$.version" }
+
+  - id: boot_stamp_release
+    condition: "{{boot_row_version}} != ''"
+    action: set
+    vars: { stamp_hold: "false" }
+
+  # ═════════════════════════ THE LEDGER ROW — extend only ════════════════════
+  # 10. What changed, observed. Diffing the finished document against the snapshot taken
+  #     before authoring gives the requirement ids this run added, amended or removed —
+  #     including any the converge loop touched on its way past, which is the whole
+  #     reason the diff is taken here and not before the loop.
+  - id: ext_diff
+    condition: "{{needs_bootstrap}} == false"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-diff
+    args: ["--feature-dir", "{{feature_dir}}", "--snapshot", "{{snapshot}}"]
+    outputs:
+      - { name: changed_csv,     from: "$.changed_csv" }
+      - { name: story_ids_csv,   from: "$.story_ids_csv" }
+      - { name: removed_csv,     from: "$.removed_csv" }
+      - { name: modified_csv,    from: "$.modified_csv" }
+      - { name: disturbing_csv,  from: "$.disturbing_csv" }
+      - { name: reissued_csv,    from: "$.reissued_csv" }
+      - { name: change_count,    from: "$.change_count" }
+
+  # 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
+  #      MODIFIED or REMOVED, which have open stories against them. An ADDED requirement
+  #      is never in this set — no story cites an id that did not exist a moment ago.
+  #      NO `on_error: continue` here, unlike the pre-authoring scan above. That one is a
+  #      preference and degrades honestly to "no preference"; this one is the only thing
+  #      standing between an amendment and the people building against it. Continuing past a
+  #      failure bound disturbed_any to nothing, which is falsy, which SKIPS the ask — the
+  #      check designed to stop a silent amendment failing open into a silent amendment.
+  - id: ext_disturbed
+    condition: "{{change_count}} != 0"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: story-refs
+    args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{disturbing_csv}}"]
+    outputs:
+      - { name: disturbed_any,   from: "$.any" }
+      - { name: disturbed_csv,   from: "$.affected_csv" }
+      - { name: disturbed_ids,   from: "$.affected_ids" }
+      - { name: disturbed_stories, from: "$.story_csv" }
+      - { name: disturbed_flying,  from: "$.in_flight_csv" }
+
+  # 10c. THE ASK. Changing a requirement someone is building against is a decision with a
+  #      cost the machine cannot weigh: it may be the only honest way to state the new
+  #      contract, or it may be an amendment that could equally have been an addition. The
+  #      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
+  #                 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
+  #                 stale, because nothing they cite has moved, and the new requirements
+  #                 become new stories.
+  #
+  #      Asked rather than decided, for the same reason §5.4 asks on indirect impact:
+  #      there is no oracle for "should this have been additive", and a wrong silent
+  #      answer either strands work or splits one contract across two requirements.
+  #      Amend is first, so a non-interactive run keeps what the author actually wrote.
+  - id: ask_disturb
+    condition: "{{disturbed_any}} == true"
+    action: ask
+    multi: true
+    prompt: |
+      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}}
+      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
+      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?
+    options_from: "{{disturbed_ids}}"
+    answer_key: may_change
+    answer_var: may_change
+
+  # 10d. The complement: disturbed minus approved is what must go back. Computed by a
+  #      script because the orchestrator binds values and never computes them.
+  - id: ext_preserve
+    condition: "{{disturbed_any}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-preserve
+    args: ["--disturbing", "{{disturbed_csv}}", "--approved", "{{may_change}}"]
+    outputs:
+      - { name: preserve_csv,   from: "$.preserve_csv" }
+      - { name: preserve_count, from: "$.preserve_count" }
+      - { name: approved_csv,   from: "$.approved_csv" }
+
+  # 10e. Restore what was not approved. The snapshot is still on disk, so both versions
+  #      are in context: put those requirements back exactly as they read, and carry what
+  #      they were expressing in new requirements instead. Requirements the author DID
+  #      approve stay amended — this is per requirement, not all-or-nothing.
+  - id: ext_readdit
+    condition: "{{preserve_count}} != 0"
+    action: agent_author
+    # The constitutions its own grader and patcher already read. Minting requirements
+    # without them meant the step that WRITES the new contract was the only one in the
+    # chain flying blind, and the two steps after it then graded and patched what it
+    # produced against rules it had never seen.
+    context:
+      - "{{spec_file}}"
+      - "{{snapshot}}"
+      - { path: .appweaver/memory/constitution.domain.md, optional: true }
+      - { path: .appweaver/memory/constitution.ui.md, optional: true }
+    include_standards: false
+    output_target: { type: file, path: "{{spec_file}}" }
+    task: |
+      Two versions of this specification are in context: the CURRENT one at
+      {{spec_file}}, and the SNAPSHOT of it taken before this run edited it, at
+      {{snapshot}}. Some of the requirements this run changed
+      were NOT approved for change, because people have open stories against them.
+
+      Restore, and re-express additively: {{preserve_csv}}
+      Leave amended as they now stand:    {{approved_csv}}
+
+      Return the COMPLETE document. Rules:
+      - Restore each requirement in the FIRST list to EXACTLY its snapshot wording. If one
+        was removed, put it back where it was, with its original id.
+      - Carry whatever those restored requirements were expressing in NEW requirements
+        instead, each taking the next free id in its class. Where a new requirement
+        narrows, extends or supersedes a restored one, say so in its text and name the
+        id — the pair has to read as one coherent contract, not two rules that contradict
+        each other.
+      - Requirements in the SECOND list were approved for change. Leave them exactly as
+        the current document has them; do not restore them and do not re-express them.
+      - Where a restored requirement's change genuinely cannot be expressed without
+        contradicting it, leave that ONE amended as it now stands and add a note naming
+        it. A contract that states two incompatible things is worse than an amendment
+        somebody has to reconcile.
+      - Every other part of the document stays exactly as it currently reads. Do not
+        touch the "**Version**" header or the "## Change History" table, and leave everything between the AW:COVERAGE markers exactly as it is.
+
+  # 10f. GRADE WHAT THE RESTORE WROTE. ext_readdit runs after the converge loop has
+  #      finished, so the requirements it mints to carry the change would otherwise be the
+  #      only ones in the document never checked for EARS form, testability or coherence —
+  #      the additive path would produce weaker requirements than the ordinary one, which
+  #      is precisely backwards, since it is the path taken when people are already
+  #      building against this contract.
+  #
+  #      Graded over the WHOLE document rather than only the new ids, because the point of
+  #      a restored requirement plus its new companion is that the pair reads as ONE
+  #      contract; only a whole-document pass can see that they do. Two iterations, and
+  #      the patch is forbidden from touching either the restored or the approved
+  #      requirements — otherwise the fix could re-disturb what the author just protected.
+  - id: readdit_check_loop
+    condition: "{{preserve_count}} != 0"
+    action: loop
+    while: "{{readdit_pass}} != true"
+    max_iterations: 2
+    steps:
+      - id: readdit_validate
+        action: agent_query
+        # The same sources the main validate gets. Without them this pass could not judge the
+        # Domain Lift or Experience Lift items at all, so the requirements minted by the
+        # ADDITIVE path — the path taken precisely when people are already building against
+        # this contract — were graded more thinly than the ones the ordinary path writes.
+        context:
+          - "{{checklist_file}}"
+          - "{{spec_file}}"
+          - { path: .appweaver/memory/constitution.domain.md, optional: true }
+          - { path: .appweaver/memory/constitution.ui.md, optional: true }
+        include_standards: false
+        task: |
+          The spec in context was just re-authored: some requirements were restored to
+          their earlier wording, and NEW requirements were added to carry the change they
+          were expressing. That happened after the quality pass, so the new requirements
+          have never been graded.
+            Restored (must read exactly as they did):  {{preserve_csv}}
+            Amended with approval:                     {{approved_csv}}
+          Evaluate the document against each checklist item (in context, 1-based in
+          order), paying particular attention to the requirements added by the
+          re-authoring: EARS form, atomic and testable, stable ids, no implementation
+          mechanics. Judge also whether each restored requirement and the new one carrying
+          its change read as ONE coherent contract rather than two rules that contradict
+          each other. In "failing", quote the offending part per failed item.
+        schema: { all_pass: false, failing: [ { n: 2, issue: "<quote>" } ] }
+        mock: { all_pass: true, failing: [] }
+        outputs:
+          - { name: readdit_pass,    from: "$.all_pass" }
+          - { name: readdit_failing, from: "$.failing" }
+      - id: readdit_break
+        action: break
+        condition: "{{readdit_pass}} == true"
+      # Same reason as patch_spec: max_iterations is 2, so iteration 1 grades and stops.
+      - id: readdit_patch
+        condition: "{{iteration}} != 1"
+        action: agent_author
+        context:
+          - "{{spec_file}}"
+          - { path: .appweaver/memory/constitution.domain.md, optional: true }
+          - { path: .appweaver/memory/constitution.ui.md, optional: true }
+        include_standards: false
+        task: |
+          Fix these quality failures in the spec in context.
+            Failures: {{readdit_failing}}
+          Constraints that override the failures if they ever conflict:
+          - Do NOT modify these restored requirements — their wording is deliberate and
+            people are building against it: {{preserve_csv}}
+          - Do NOT modify these approved requirements either: {{approved_csv}}
+          - Fix the NEW requirements instead: put them in EARS form, make them atomic and
+            testable, and keep each one's stated relationship to the requirement whose
+            change it carries.
+          - Preserve section order, headings and every requirement id. Do not touch the
+            "**Version**" header or the "## Change History" table, and leave everything
+            between the AW:COVERAGE markers exactly as it is.
+        output_target: { type: file, path: "{{spec_file}}" }
+
+  # 10f-bis. THE RESTORE'S SPEC STILL FAILS. Same shape, and the same stakes, as the ask
+  #      after the main quality loop — with one difference that makes it matter more: this
+  #      is the path taken when people are ALREADY BUILDING against these requirements, and
+  #      what the loop grades is the brand-new text minted to carry a change the author
+  #      refused to make in place. Without this, a red restore appended a version row and
+  #      told those authors their work was reconciled.
+  #
+  #      Two ordered sets rather than a compound condition: the verdict is "nothing to
+  #      grade" by default, and becomes the loop's own answer only on the path where the
+  #      loop actually ran. Record is first for the reason it is first above — spec.md is
+  #      written by now, and a run that refuses the row leaves the unledgered_edit state.
+  - id: readdit_verdict_na
+    action: set
+    vars: { readdit_verdict: "true" }
+  - id: readdit_verdict_real
+    condition: "{{preserve_count}} != 0"
+    action: set
+    vars: { readdit_verdict: "{{readdit_pass}}" }
+
+  - id: readdit_ask
+    condition: "{{readdit_verdict}} != true"
+    action: ask
+    prompt: |
+      The re-authored spec still fails its quality pass. These requirements were restored
+      to their earlier wording and NEW ones were minted to carry the change instead, and
+      the grader is not satisfied with the result:
+        Restored: {{preserve_csv}}
+        Failing:  {{readdit_failing}}
+      spec.md is ALREADY WRITTEN either way — the only question is whether this run records
+      what it changed.
+    options:
+      - "Record it — the version row is what keeps the stories in step; fix the spec next"
+      - "Stop — write no version row, and repair spec.md by hand first"
+    answer_key: readdit_accept
+    answer_var: readdit_accept
+
+  - id: readdit_gate
+    condition: "{{readdit_verdict}} != true"
+    action: verify_context
+    require_value: readdit_accept
+    equals: "Record it — the version row is what keeps the stories in step; fix the spec next"
+    on_mismatch: stop
+    on_mismatch_message: >
+      Stopped at your request with no version row written. What the grader found is above,
+      and the checklist is at {{checklist_file}}.
+      spec.md HAS been rewritten, so the next specify will refuse it as an unledgered edit
+      until one of two things is true — add a Change History row naming the ids you changed
+      and re-run spec-stamp, or revert the document from the copy taken before this run,
+      which is beside it at {{snapshot}}.
+
+  # 10g. Re-diff after re-authoring AND its quality pass, so the ledger row records what
+  #      finally landed rather than what the first pass wrote. Skipped when everything was
+  #      approved. Must run after the gate above: a patch there can add or reword a
+  #      requirement, and a row computed before it would miss that.
+  - id: ext_rediff
+    condition: "{{preserve_count}} != 0"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-diff
+    args: ["--feature-dir", "{{feature_dir}}", "--snapshot", "{{snapshot}}"]
+    outputs:
+      - { name: changed_csv,    from: "$.changed_csv" }
+      - { name: story_ids_csv,  from: "$.story_ids_csv" }
+      - { name: removed_csv,    from: "$.removed_csv" }
+      - { name: modified_csv,   from: "$.modified_csv" }
+      - { name: disturbing_csv, from: "$.disturbing_csv" }
+      - { name: reissued_csv,   from: "$.reissued_csv" }
+      - { name: change_count,   from: "$.change_count" }
+
+  # 10g-bis. DID THE RESTORE HOLD. ext_readdit is a model asked to put requirements back to
+  #      their earlier wording, and until now nothing checked that it did. The re-diff is the
+  #      proof: a requirement the author refused to move must have dropped out of the
+  #      disturbing set. One still in it was amended WITHOUT approval — and the run would
+  #      otherwise close by telling that author, in the same sentence, that it was left alone.
+  #
+  #      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
+  #      "preserved" column of the report into a column that says what actually happened.
+  - id: ext_restore_check
+    condition: "{{preserve_count}} != 0"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: spec-preserve
+    args: ["--verify", "--preserved", "{{preserve_csv}}", "--disturbing", "{{disturbing_csv}}"]
+    outputs:
+      - { name: held_csv,     from: "$.held_csv" }
+      - { name: violated_csv, from: "$.violated_csv" }
+      - { name: restore_ok,   from: "$.restore_ok" }
+
+  - id: ext_restore_gate
+    condition: "{{preserve_count}} != 0"
+    action: verify_context
+    require_true: restore_ok
+    on_false: continue
+    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
+      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
+  #      requirements that were put back disturb nobody any more, and their stories must
+  #      drop out of the report — otherwise the run tells people to go and reconcile work
+  #      that this run deliberately left alone. Same call as 10b, over what actually landed.
+  # Keyed on disturbed_any, not change_count: a restore that put everything back can leave
+  # the run with nothing changed at all, and on that path a change_count gate skipped this
+  # step and left the report naming the stories from BEFORE the restore — telling people to
+  # go and reconcile work this run deliberately left alone.
+  - id: ext_final_refs
+    condition: "{{disturbed_any}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: story-refs
+    args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{disturbing_csv}}"]
+    outputs:
+      - { name: disturbed_stories, from: "$.story_csv" }
+
+  # 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
+  #      why every authoring prompt forbids it — and until now nothing checked. Announced,
+  #      not blocked, for the same reason as the restore gate: the document is written by
+  #      the time this is visible, and refusing here would strand it. Deciding WHAT to do
+  #      about a re-issued id is still the author's, and is not yet automated.
+  - id: ext_reissue_gate
+    condition: "{{change_count}} != 0"
+    action: verify_context
+    require_value: reissued_csv
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: >
+      {{reissued_csv}} was introduced by this run, but the Change History has already
+      spent it. An id is permanent — whatever cited it before now points at something
+      else. Renumber the new requirement to the next free id in its class before anyone
+      builds against it.
+
+  # 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.
+  - id: ext_ledger_append
+    condition: "{{change_count}} != 0"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: ledger-append
+    args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{changed_csv}}", "--summary", "{{USER_INPUT}}"]
+    outputs:
+      - { name: ledger_version, from: "$.version" }
+
+  # ═══════════════ 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
+  #      stored once, in the story; this is that relation the other way round, which is
+  #      why the block is regenerated wholesale and hand edits to it are discarded.
+  #
+  #      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
+  #      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.
+  #
+  #      Run on the bootstrap path as well, where it lists every requirement as uncovered:
+  #      a new spec that nobody is building yet is exactly what it should say.
+  - id: coverage_refresh
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: spec-coverage
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: uncovered_csv, from: "$.uncovered_csv" }
+
+  # ═══════════════════ RE-BASELINE — both paths, always last ═════════════════
+  # 12. Record the finished document's hash. Everything above may have rewritten spec.md
+  #     after the ledger row was appended (the converge loop on the bootstrap path, and
+  #     nothing on the extend path — but the order is what guarantees that), so the hash
+  #     is taken here, once, over the document as it will be read next. Without this the
+  #     next run's entry tripwire would see a changed body and refuse a spec that is
+  #     perfectly in step.
+  #     Skipped when the bootstrap's v1.0 row never landed: a hash is a claim that the
+  #     document on disk is the one the ledger describes, and there is no ledger row to
+  #     describe it. Leaving it unstamped keeps that honest and costs nothing — the
+  #     bootstrap marker is still up, so the next run re-authors rather than extends.
+  - id: spec_stamp
+    condition: "{{stamp_hold}} != true"
     action: execute_script
     script: { ref: actions }
-    subcommand: version-read
+    subcommand: spec-stamp
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: version,        from: "$.version" }
-      - { name: active_change,  from: "$.active_change" }
+      - { name: version, from: "$.version" }
+
+  # 13. Post-execution hooks: resolve (script) then dispatch (invoking agent).
+  # 12b. Say so when it was held. Everything downstream reads `version`, and a first draft
+  #      with no row and no hash is not a baseline anything should build on.
+  - id: boot_incomplete_notice
+    condition: "{{stamp_hold}} == true"
+    action: verify_context
+    require_value: stamp_hold
+    equals: "false"
+    on_mismatch: continue
+    on_mismatch_message: >
+      The first draft was written to {{spec_file}}, but its v1.0 Change History row could not
+      be added — so the document is deliberately left UNSTAMPED and still marked an unfinished
+      bootstrap. Do not treat it as a baseline. Re-run /appweaver specify with the same input
+      (it re-authors the draft rather than extending it), or add the v1.0 row by hand naming
+      the requirement ids and re-run spec-stamp.
 
-  # 9. Post-execution hooks: resolve (script) then dispatch (invoking agent).
   - id: resolve_post_hooks
     action: execute_script
     script: { ref: actions }
@@ -432,8 +1171,16 @@ outputs:
   feature_directory: "{{feature_dir}}"
   spec_file: "{{spec_file}}"
   version: "{{version}}"
-  change_id: "{{cr_id}}"
-  authored_document: "{{quality_target}}"   # spec.md (bootstrap) | delta-spec.md (delta)
+  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_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
+  requirements_not_restored: "{{violated_csv}}"  # declined, but moved anyway
+  requirements_reissued: "{{reissued_csv}}"      # ids the ledger had already spent
+  open_change: "{{open_change}}"                # a delta change open on this feature, if any
+  requirements_uncovered: "{{uncovered_csv}}"
+  stories_disturbed: "{{disturbed_stories}}"
   checklist_file: "{{checklist_file}}"
   checklist_quality: "{{checklist_passed}}/{{checklist_total}} items passing"
-  next: "/appweaver design — BOOTSTRAP authors design.md from the spec; a DELTA (this run opened change {{cr_id}}) authors the delta-design for it. A change then flows: analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta (finalize-delta merges the delta into spec.md + design.md but leaves the change open; analyze-slice verifies the slice against the merged master; close-delta archives the change and bumps the version)."
+  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."