wdi-method 0.5.13 → 0.6.0

package/kit/.constitution/method/document/templates/questions.md

@@ -1,76 +1,100 @@
----
-type: questions
-list: blocking           # blocking · assumptions · external · answered
-status: draft            # draft · reviewed · locked · superseded
-created: '{YYYY-MM-DD}'
-updated: '{YYYY-MM-DD}'
----
-
-# {Blocking Questions | Assumptions | Waiting on an Outside Party | Answered}
-
-<!-- TEMPLATE GUIDE — act on these comments, then delete them.
-
-     ONE template, four lists, all in .control/questions/. `list:` decides which row shape below
-     survives; delete the other three.
-
-     THE SPLIT IS BY WHAT THE READER HAS TO DO — not by subject and not by severity. That is the whole
-     design, and it is what the single old list could not express: it reached OQ-146 and the majority
-     of its weight was answered entries.
-
-       blocking     holds a gate. Read at every gate. Target <=3 per Product Component
-       assumptions  the DEFAULT class. Swept once per gate; MAY be skipped. Holds nothing
-       external     waiting on a file, an action, or a credential from outside. Holds GO-LIVE ONLY,
-                    never a design gate. Owner and `Sebelum` required on every row
-       answered     archive. Closed in place, never deleted
-
-     WHY oq.md IS NOT THIS: oq.md is the shape of ONE question whose discussion outgrew a line, and it
-     lives beside these four as OQ-NNN-<slug>.md with a one-line pointer from the list. This is the
-     shape of the four LISTS.
-
-     A ROW MOVES BETWEEN FILES WHEN ITS CLASS CHANGES, and it MUST NOT be copied into a second one.
-
-     Ids stay OQ-, allocated from the highest ever used including closed ones. An id MUST NOT be
-     reused. The prose inside the tables follows the product's `doc_language`; a machine-facing
-     marker such as `[NEEDS CONFIRMATION]` stays English wherever it appears — `language-guide.md`
-     owns that split. -->
-
-## The class test
-
-<!-- Keep this block in blocking.md and assumptions.md; delete it from the other two.
-
-     A question is filed in `assumptions` unless it passes one of three tests. One is enough:
-
-       1. It touches money, personal data, or a legal obligation.
-       2. It changes the wording of an FR's promise.
-       3. Answering it wrong forces a rewrite of more than one Product Component.
-
-     Failing all three, the agent takes the answer itself and records it as one line.
-
-     A question MUST NOT be filed as blocking "to be safe". That habit is what produced 146 ids. -->
-
-## Open
-
-<!-- list: blocking · external -->
-
-| id | Question | Blocks | Owner | Before |
-|---|---|---|---|---|
-
-<!-- list: assumptions — keep this shape instead
-| id | Assumption | Cost if wrong | Taken | By |
-|---|---|---|---|---|---|
--->
-
-<!-- An empty list is a legitimate state and MUST be written as one, with the date and one line
-     saying why. An empty table with no sentence reads as an unfinished file. -->
-
-## Answered
-
-<!-- list: answered only.
-
-     | id | Question | Answer | Date | By |
-
-     The answer is written beside the question, not in place of it. The record of what was once
-     uncertain is what stops the same question being asked again in three months.
-
-     An answer amounting to a decision that is expensive to reverse MUST also go to wdi-decision. This
-     list records that an answer arrived; a DEC- records what was chosen and what it cost. -->
+---
+type: questions
+list: blocking           # blocking · assumptions · external · answered
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+---
+
+# {Blocking Questions | Assumptions | Waiting on an Outside Party | Answered}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     ONE template, four lists, all in .control/questions/. `list:` decides which row shape below
+     survives; delete the other three.
+
+     THE SPLIT IS BY WHAT THE READER HAS TO DO — not by subject and not by severity. That is the whole
+     design, and it is what the single old list could not express: it reached OQ-146 and the majority
+     of its weight was answered entries.
+
+       blocking     holds a gate. Read at every gate. Target <=3 per Product Component
+       assumptions  the DEFAULT class. Swept once per gate; MAY be skipped. Holds nothing
+       external     waiting on a file, an action, or a credential from outside. Holds GO-LIVE ONLY,
+                    never a design gate. Owner and `Sebelum` required on every row
+       answered     archive. Closed in place, never deleted
+
+     WHY oq.md IS NOT THIS: oq.md is the shape of ONE question whose discussion outgrew a line, and it
+     lives beside these four as OQ-NNN-<slug>.md with a one-line pointer from the list. This is the
+     shape of the four LISTS.
+
+     A ROW MOVES BETWEEN FILES WHEN ITS CLASS CHANGES, and it MUST NOT be copied into a second one.
+
+     Ids stay OQ-, allocated from the highest ever used including closed ones. An id MUST NOT be
+     reused. The prose inside the tables follows the product's `doc_language`; a machine-facing
+     marker such as `[NEEDS CONFIRMATION]` stays English wherever it appears — `language-guide.md`
+     owns that split. -->
+
+## The class test
+
+<!-- Keep this block in blocking.md and assumptions.md; delete it from the other two.
+
+     A question is filed in `assumptions` unless it passes one of three tests. One is enough:
+
+       1. It touches money, personal data, or a legal obligation.
+       2. It changes the wording of an FR's promise.
+       3. Answering it wrong forces a rewrite of more than one Product Component.
+
+     Failing all three, the agent takes the answer itself — and then THE RECORDING THRESHOLD decides
+     whether it becomes a row at all. Read `Cost if wrong` first: if it is *one setting changes*, *one
+     default changes*, or *a shortcut is added later*, with no rework and nothing built on it, then
+     there is NO ROW. The shipping default is the record, and the code says it more reliably than a
+     line here. wdi-question owns the rule.
+
+     The threshold never applies to the three tests above. Those always win.
+
+     A question MUST NOT be filed as blocking "to be safe". That habit is what produced 146 ids. -->
+
+## Open
+
+<!-- list: blocking · external -->
+
+| id | Question | Blocks | Whose | Owner | Before |
+|---|---|---|---|---|---|
+
+<!-- external.md drops `Whose`: sitting in that file already says who acts. Its shape is
+     | id | Question | Waiting on | Since | -->
+
+<!-- list: assumptions — keep this shape instead
+| id | Assumption | Cost if wrong | Whose | Taken | By |
+|---|---|---|---|---|---|
+-->
+
+<!-- `Whose` says who acts, and whether anyone may act yet. Three values, and no others:
+
+       owner            a judgement only the owner can make, and it can be made NOW
+       run: <what>      the answer comes from running or measuring something — the AGENT's, not the
+                        owner's. It MUST name what to run; "needs testing" is not a value
+       frozen: DEC-NNN  an applied decision forbids answering it yet, planning included. When that
+                        DEC- lifts or is superseded, the row becomes `owner` with no re-triage
+
+     Without this column the four files still hand the owner one flat pile: in one real corpus, 25 open
+     lines of which only 6 were the owner's and answerable. wdi-question MUST report only `owner` rows
+     to the owner, and the rest as counts. -->
+
+<!-- An empty list is a legitimate state and MUST be written as one, with the date and one line
+     saying why. An empty table with no sentence reads as an unfinished file. -->
+
+## Answered
+
+<!-- list: answered only.
+
+     | id | Question | Answer | Date | By |
+
+     The answer is written beside the question, not in place of it. The record of what was once
+     uncertain is what stops the same question being asked again in three months.
+
+     An answer amounting to a decision that is expensive to reverse MUST also go to wdi-decision. This
+     list records that an answer arrived; a DEC- records what was chosen and what it cost.
+
+     A FOSSIL IS CLOSED, NOT ANSWERED. A row questioning a rule, a layer, or a validator that has since
+     been repealed cannot bite again — it moves here with the repeal as its answer, and it MUST NOT be
+     put to the owner as a decision. Check for these FIRST when a list has grown long; they are free. -->

package/kit/.constitution/method/document/templates/rules.md

@@ -1,47 +1,46 @@
----
-type: rules
-scope: global            # global · component — decides the home and the id prefix
-component: '{pc}'        # omit entirely when scope: global
-status: draft            # draft · reviewed · locked · superseded
-created: '{YYYY-MM-DD}'
-updated: '{YYYY-MM-DD}'
----
-
-# Business Rules — {the product | Product Component}
-
-<!-- TEMPLATE GUIDE — act on these comments, then delete them.
-
-     ONE template, two scopes, and the scope decides everything about where this file lives:
-
-       scope: global     -> .what/business-rules.md          born at G3, by wdi-blueprint
-       scope: component  -> .what/<pc>/02-rules/rules-<pc>.md born at G4, from mode: outline up
-
-     THE TEST IS REACH, NOT IMPORTANCE. A rule binding more than one Product Component is global; a
-     rule binding only one is that component's. A rule written locally that turns out to bind a
-     second component MUST be PROMOTED to the global file, never copied. Two copies of one rule is
-     how components start disagreeing about the same policy.
-
-     A rule MUST be checkable. If a reviewer cannot tell whether the behaviour obeys it, it is not a
-     rule yet — it is an intention, and it belongs in the SRS prose.
-
-     A rule MUST NOT state a mechanism. "The turn is not consumed until commitment" is a rule; "a
-     row is written to the queue table" is a mechanism and belongs to .how/.
-
-     Ids are allocated GLOBALLY and never restart. A retired rule keeps its id and is marked retired
-     with what replaced it — never deleted, because documents still cite it. -->
-
-## Rules
-
-| id | Rule | Binds | Source | Status |
-| --- | --- | --- | --- | --- |
-| BR-{n} | {one checkable sentence, present tense} | {which components, or `all`} | {FR-n · DEC-n · UC-n · a person and a date} | active |
-
-<!-- `Source` MUST name where the rule came from. A rule with no source is an assumption in
-     disguise, and it goes through wdi-question instead.
-
-     `Status`: active · retired. A retired row states what replaced it in the Rule column. -->
-
-## Retired
-
-<!-- Rows moved here keep their ids. Each MUST name what replaced it and the date it stopped
-     holding. This section MAY be absent until the first rule retires. -->
+---
+type: rules
+scope: global            # global · component — decides the home and the id prefix
+component: '{pc}'        # omit entirely when scope: global
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+---
+
+# Business Rules — {the product | Product Component}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     ONE template, two scopes, and the scope decides everything about where this file lives:
+
+       scope: global     -> .what/business-rules.md          born at G3, by wdi-blueprint
+       scope: component  -> .what/<pc>/02-rules/rules-<pc>.md born at G4, from mode: outline up
+
+     THE TEST IS REACH, NOT IMPORTANCE. A rule binding more than one Product Component is global; a
+     rule binding only one is that component's. A rule written locally that turns out to bind a
+     second component MUST be PROMOTED to the global file, never copied. Two copies of one rule is
+     how components start disagreeing about the same policy.
+
+     A rule MUST be checkable. If a reviewer cannot tell whether the behaviour obeys it, it is not a
+     rule yet — it is an intention, and it belongs in the SRS prose.
+
+     A rule MUST NOT state a mechanism. "The turn is not consumed until commitment" is a rule; "a
+     row is written to the queue table" is a mechanism and belongs to .how/.
+
+     Ids are allocated GLOBALLY and never restart. A retired rule keeps its id and is marked retired
+     with what replaced it — never deleted, because documents still cite it. -->
+
+## Rules
+
+| id | Rule | Binds | Source | Status |
+| --- | --- | --- | --- | --- |
+| BR-{n} | {one checkable sentence, present tense} | {which components, or `all`} | {FR-n · DEC-n · UC-n · a person and a date} | active |
+
+<!-- `Source` MUST name where the rule came from. A rule with no source is an assumption in
+     disguise, and it goes through wdi-question instead.
+
+     `Status`: active · retired. A retired row states what replaced it in the Rule column. -->
+
+## Retired
+
+<!-- Rows moved here keep their ids. Each MUST name what replaced it and the date it stopped
+     holding. This section MAY be absent until the first rule retires. -->

package/kit/.constitution/method/document/templates/sdd.md

@@ -3,10 +3,9 @@ type: sdd
 component: '{pc}'
 status: draft            # draft · reviewed · locked · superseded
 created: '{YYYY-MM-DD}'
-updated: '{YYYY-MM-DD}'
 realizes: []             # UC ids this design realizes, from usecases.yaml
 binds: []                # AD ids from the spine that bind here
-reviewed:                # V13. Filled only after wdi-review has actually run
+reviewed:                # `review-trace`. Filled only after wdi-review has actually run
   date: ''               # '{YYYY-MM-DD}'
   sha: ''                # commit it was reviewed at; without the SHA, staleness cannot be measured
   lenses: []             # the set risk_accepted names — NOT a fixed list
@@ -19,7 +18,7 @@ reviewed:                # V13. Filled only after wdi-review has actually run
 
 <!-- NOT an HLD, and NOT a one-shot LLD. What the system consists of belongs to C4 L1-L2; architecture
      constraints belong to ARCHITECTURE-SPINE.md; deployment topology belongs to the devops repository.
-     This document is LIVING: one per Product Component, amended every wave. -->
+     This document is LIVING: one per Product Component, amended every spec. -->
 
 <!-- EVERY SECTION MARKS THE MINIMUM `mode` THAT DEMANDS IT. Below that minimum it MUST NOT be written
      to fill a slot; above it, it is required. Read the component's mode from its row in
@@ -29,13 +28,21 @@ reviewed:                # V13. Filled only after wdi-review has actually run
      That is a FINISHED state, not an unfinished one: G4 is skipped at catalog, and the code is written
      from the use case catalogue, the three inventories, and C4.
 
+     `reviewed.lenses` carries what ACTUALLY ran at that sha. The risk-mandated set applies to a first
+     review and a gate-opening review; a re-review runs the lighter set over the delta only.
+
      `reviewed.lenses` MUST match what risk_accepted names, NOT what `mode` says. One component MAY sit
      at catalog and still be reviewed the hardest. -->
 
 ## Decision Summary · [outline]
 
 <!-- <=1 page, business language. What this component is built as, and the one or two choices that cost
-     the most to reverse. This is what the Product Owner reads at G4. -->
+     the most to reverse. This is what the Product Owner reads at G4.
+
+     NO DERIVED FACT. `mode`, `risk_accepted`, which `DEC-` bind this file — "none yet" included —
+     how many UC or FR there are, and which slots exist are all held elsewhere and MUST NOT be
+     stated here. `corpus-guide.md` § A derived fact has exactly one home says where each lives, and
+     that the remedy for one already written is DELETION, not correction. -->
 
 ## Structure · [outline]
 
@@ -43,7 +50,7 @@ reviewed:                # V13. Filled only after wdi-review has actually run
      rule, not decoration.
 
      Every LC named here MUST be registered in .control/registry/components.yaml, and the registration
-     is checked WHEN THE WAVE CLOSES — V12 — not before a story is ready-for-dev. The old timing
+     is checked WHEN THE SPEC CLOSES — `lc-registered` — not before a ticket is picked up. The old timing
      demanded the answer at the moment the information was thinnest. -->
 
 | LC | type | Responsibility |
@@ -51,15 +58,18 @@ reviewed:                # V13. Filled only after wdi-review has actually run
 
 ## Inherited Constraints · [guarded]
 
-<!-- Every AD-N from ARCHITECTURE-SPINE.md that reaches this component, QUOTED VERBATIM under its
-     ORIGINAL id. A paraphrase drifts, and the drift is invisible because both texts read reasonably.
+<!-- The AD-N ids from ARCHITECTURE-SPINE.md that reach this component, and how each lands HERE.
+     IDS ONLY — never the rule's text. `AD-` is a living rule edited in place, so a copy of its text
+     goes stale the moment the spine changes and nothing sees it. The rendered SDD
+     (`.how-rendered/<pc>/SDD-<pc>.md`) shows every invariant with its current text, pulled from the
+     spine, and marks which ones bind this component.
 
      A local choice contradicting one is a conflict to surface through wdi-decision, never an override
      made here. Below `guarded` this section is absent and the AD-N still binds — an invariant does not
      stop holding because a document is thin. -->
 
-| AD | Quoted rule | How it lands here |
-| --- | --- | --- |
+| AD | How it lands here |
+| --- | --- |
 
 ## Failure Behaviour · [guarded]
 
@@ -139,8 +149,13 @@ reviewed:                # V13. Filled only after wdi-review has actually run
                        a third party. Lane order is fixed once for the project in
                        ../../../project/codebase-conventions-guide.md; the No-op lane rule is REPEALED
 
-     supplements/ is REPEALED along with the ANX- concept it existed for. -->
+     supplements/ is REPEALED along with the ANX- concept it existed for.
+
+     THIS SECTION EXPLAINS THE CLASSIFICATION, NOT THE CONTENTS. It MUST NOT say which slots exist,
+     which are empty, or which are "not written yet" — that is `.control/structure-document.md`,
+     derived from the tree on disk. -->
 
 ## Open Items
 
-<!-- Unresolved design questions, each pointing at its row in .control/questions/. -->
+<!-- A POINTER, not a copy: ids only. Whether an OQ- is still open is held by .control/questions/,
+     and restating its status here creates a second answer on a slower clock. -->

package/kit/.constitution/method/document/templates/srs.md

@@ -3,9 +3,8 @@ type: srs
 component: '{pc}'
 status: draft            # draft · reviewed · locked · superseded
 created: '{YYYY-MM-DD}'
-updated: '{YYYY-MM-DD}'
-satisfies: []            # FR / NFR ids this component carries, from requirements.yaml
-reviewed:                # V13. Filled only after wdi-review has actually run
+satisfies: []            # FR / NFR ids this component carries, from requirements-<slug>.yaml
+reviewed:                # `review-trace`. Filled only after wdi-review has actually run
   date: ''               # '{YYYY-MM-DD}'
   sha: ''                # commit it was reviewed at; without the SHA, staleness cannot be measured
   lenses: []             # the set risk_accepted names — NOT a fixed list
@@ -18,7 +17,7 @@ reviewed:                # V13. Filled only after wdi-review has actually run
      left in English per the controlled vocabulary. -->
 
 <!-- NOT a one-shot document. Despite the IEEE name, this SRS is LIVING: one per Product Component,
-     amended every wave, never signed off and frozen. -->
+     amended every spec, never signed off and frozen. -->
 
 <!-- TWO SKILLS WRITE IT, AT TWO GATES, and every section below says which:
        [G3]  wdi-blueprint intent `catalog`. Exists at EVERY mode, including catalog
@@ -28,12 +27,21 @@ reviewed:                # V13. Filled only after wdi-review has actually run
      what is absent there is 04-usecases/UC-<n>-<slug>.md — the step-by-step flows.
 
      `reviewed.lenses` MUST match what this component's risk_accepted names in components.yaml —
-     edge-case-hunter at low and medium, structure + prose at high. It is NOT read off `mode`. -->
+     edge-case-hunter at low and medium, structure + prose at high. It is NOT read off `mode`.
+
+     That set is what a FIRST review and a gate-opening review carry. A later re-review runs
+     structure + prose, covers only the delta since `sha`, and puts edge-case-hunter back when that
+     delta touches money, personal data, an irreversible action, or a third party. wdi-review owns it. -->
 
 ## Decision Summary · [G3]
 
 <!-- <=1 page, business language, no jargon lacking a Glossary entry. What the Product Owner reads.
-     A summary that cannot be read inside the gate's time budget IS the finding. -->
+     A summary that cannot be read inside the gate's time budget IS the finding.
+
+     NO DERIVED FACT. `mode`, `risk_accepted`, which `DEC-` bind this file — "none yet" included —
+     how many UC or FR there are, and which slots exist are all held elsewhere and MUST NOT be
+     stated here. `corpus-guide.md` § A derived fact has exactly one home says where each lives, and
+     that the remedy for one already written is DELETION, not correction. -->
 
 ## Why · [G3]
 
@@ -52,21 +60,17 @@ reviewed:                # V13. Filled only after wdi-review has actually run
 
 ## UC Catalogue · [G3]
 
-<!-- THE use case list, and at mode: catalog it is the whole use-case record. One line each, and the
-     line is the artifact — not a placeholder waiting for a file.
-
-     A title MUST be a sentence a user would say, never a system term. G3 asks this as a starred
-     question.
+UC Catalogue — see `.control/registry/usecases.yaml`, rows where `component: {pc}`.
 
-     `critical` is yes ONLY when the use case touches money, personal data, or an irreversible action.
-     Nothing else. If more than a third of this component's use cases are marked, the definition was
-     misapplied — derive it again rather than negotiating it.
+<!-- A POINTER, not a table. The catalogue's one home is `usecases.yaml`; this section used to carry a
+     second copy, and `uc-catalogue-matches` existed only to keep the two agreeing — it once caught 26
+     rows that had drifted. The rendered SRS (`.what-rendered/<pc>/SRS-<pc>.md`) and the blueprint
+     both show the table, from the registry.
 
-     `critical` decides something only at mode: deep, where every critical UC gets a full flow. -->
-
-| id | Use case | Actor | Satisfies | critical |
-| --- | --- | --- | --- | --- |
-| UC-{n} | {a sentence a user would say} | {from the Actor Register} | {FR-n} | no |
+     What is still decided HERE, when wdi-blueprint lands the rows: a title MUST be a sentence a user
+     would say, never a system term — G3 asks this as a starred question. `critical` is yes ONLY when
+     the use case touches money, personal data, or an irreversible action; more than a third marked
+     means the definition was misapplied. -->
 
 ## Constraints · [G3]
 
@@ -108,12 +112,21 @@ reviewed:                # V13. Filled only after wdi-review has actually run
 
 <!-- The gate questions as they apply to THIS component, answered yes / no / change. The full list
      lives in delivery-flow-guide.md and MUST NOT be copied here. At mode: catalog only the starred
-     questions are asked. -->
+     questions are asked.
+
+     An answer MUST NOT carry a COUNT of registry rows — "all four use cases are covered" is a claim
+     about usecases.yaml that a fifth UC falsifies without touching this file. Answer the question. -->
 
 ## Design Reference · [G3]
 
-<!-- One line pointing at the paired SDD, plus any AD-N or applied DEC- that binds this component.
-     Nothing else — solution shape MUST NOT appear in this document: no framework, no table, no
+<!-- One line pointing at the paired SDD, plus any AD-N that binds this component — the spine's
+     `binds:` is authored, not derived, so an AD-N citation belongs here.
+
+     APPLIED `DEC-` DO NOT. They are derived from `touches:` and live in .control/generated/decisions.md;
+     point at it. A line saying "no applied DEC- binds this component yet" is the worst version — true
+     the day it is written, silently false forever after, and it looks like diligence.
+
+     Nothing else: solution shape MUST NOT appear in this document — no framework, no table, no
      endpoint, no class, no queue, no file path. -->
 
 ---
@@ -141,9 +154,17 @@ reviewed:                # V13. Filled only after wdi-review has actually run
      05-scenarios/   SCN-<nn>-<slug>.md, long branches hanging off one UC. From mode: deep only
 
      01-requirements/ and supplements/ are REPEALED. The first was permanently empty — FR live in the
-     PRD and this document cites them by id. The second existed for the ANX- concept, which is gone. -->
+     PRD and this document cites them by id. The second existed for the ANX- concept, which is gone.
+
+     THIS SECTION EXPLAINS THE SHAPE, NOT THE CONTENTS. It MUST NOT say which slots exist, which are
+     empty, or which are "not written yet". That is `.control/structure-document.md`, derived from the
+     tree on disk. One real SDD claimed four of its five slots unwritten while one of them held 223
+     lines. -->
 
 ## Open Items
 
-<!-- Anything still unresolved, each pointing at its row in .control/questions/. An assumption left
-     here with no id is the failure wdi-question exists to prevent. -->
+<!-- A POINTER, not a copy. Ids only, and the id is enough: whether an OQ- is still open is held by
+     .control/questions/, so restating its status here creates a second answer on a slower clock.
+
+     An assumption left here with no id is the failure wdi-question exists to prevent. An id listed
+     here that has been answered for weeks is the failure this rule exists to prevent. -->

package/kit/.constitution/method/document/templates/uc.md

@@ -2,7 +2,7 @@
 type: uc
 id: UC-{NN}                  # allocated from .control/registry/usecases.yaml
 component: '{pc}'
-satisfies: []                # FR ids — V2 checks every FR has at least one UC
+satisfies: []                # FR ids — `fr-has-uc` checks every FR has at least one UC
 critical: false              # true ONLY when it touches money, personal data, or an irreversible
                              # action. Nothing else — the two elastic criteria are repealed
 created: '{YYYY-MM-DD}'