dflow-sdd-ddd 0.14.0 → 0.15.0

package/templates/common/references/flow-rationale-registry.md

@@ -0,0 +1,130 @@
+# Flow Rationale Registry
+
+Why the rules in the workflow flow files and templates are shaped the way they
+are. One entry per physical line, so one lookup returns the whole answer:
+
+```bash
+grep -E '^R-FF-BRANCH-02:' references/flow-rationale-registry.md
+```
+
+**Do not read this file whole.** It is a lookup table, not a document. Nothing
+here is needed to execute a flow. Look up an entry when a developer asks why a
+rule exists, or says a rule looks wrong.
+
+Every line reads `<id>: [<edition ·>? <file> · <step or section> · <the rule it
+belongs to>]` followed by the reason, so a keyword search finds the line when
+you do not have an id. **Search a short fragment — four to eight words — not a whole sentence.**
+The flow files are hard-wrapped, so most sentences there span a line break and
+carry an indent that this file's single long lines do not have; a long phrase
+copied out of a flow file will therefore match nothing here.
+
+**Do not add `-m 1`.** A bracket that opens with `gf ·` or `bf ·` applies to
+that edition only — usually one line per edition of the same rule, sometimes a
+rule only one edition has. A bracket with no edition marker applies to both. So
+a lookup can legitimately return two lines: read the one matching this project's
+edition, which the workflow bundle's own `.dflow-bundle-manifest.json` records
+in its `edition` field. Taking only the first would hand a Brownfield project
+the Greenfield answer — the `gf ·` line is always first.
+
+**Reviewers and future maintainers: read this before concluding that a check is
+under-specified.** Several of these rules look loose on their own and are
+bounded deliberately, with the boundary recorded here.
+
+## finish-feature-flow.md
+
+R-FF-MINSEL-01: [finish-feature-flow.md · Step 1 · What "Minimal host (zero-phase) only" selects, and what that does not prove] The routing rules are what keep the two apart in practice: a T1 never records into a minimal host, and a sealed minimal host cannot take anything further.
+
+R-FF-ORPHAN-01: [finish-feature-flow.md · Step 1 · "And the other direction, for every host shape"] The checks around this one walk rows → files, so a file no row names is otherwise never examined. Deliberately **not** scoped to a host shape: an unreferenced `phase-spec-*` is precisely what makes a host read as *phase-bearing* to the minimal-host selector below, so a shape-scoped version of this check could never be the one that sees it.
+
+R-FF-BRANCH-01: [finish-feature-flow.md · Step 1 · "The row must name *this* branch"] "An override happened once" would excuse closing out on any branch at all, which is not what the option sanctions; requiring the row to name where you actually are defeats that without over-blocking.
+
+R-FF-BRANCH-02: [finish-feature-flow.md · Step 1 · "You are on this host's branch — or on a branch this host recorded a sanctioned override for"] ⚠ **Deliberately not "the most recent override".** A host can override onto `develop` for one phase and onto `spike/x` for the next, then close out on `develop` — and closeout fires no branch gate of its own, so no newer row is ever written. Keying on the most recent row would block a branch this host recorded a sanctioned override for, which is the same false block this clause exists to remove.
+
+R-FF-BRANCH-03: [finish-feature-flow.md · Step 1 · "When it passes this way, say so in the conversation"] A gate that silently accepts an exception teaches the developer nothing about why it passed.
+
+R-FF-BRSNAP-01: [finish-feature-flow.md · Step 1 · "Current BR Snapshot table is non-empty", on a phase-bearing T1 whose phase-specs establish no BR delta] (genuinely new work is `/dflow:new-feature` "even with no new BR / Domain / schema", `AI-AGENT-GUIDE.md` § Ceremony Scaling step 0, and `new-feature-flow.md` Step 4 initialises the Snapshot from planned BRs that may legitimately be none)
+
+R-FF-BASELINE-01: [finish-feature-flow.md · Step 1 · "The `-w` is mandatory"] Without `-w`, `git hash-object` computes the id and never stores the blob, so the baseline's **content** is unrecoverable afterwards — `git cat-file -p` on that id fails with `Not a valid object name`, leaving Step 4 holding fingerprints for a comparison that needs the text. It is also what makes Step 1's "captured rather than remembered" true of the **content** and not only of the id. ⚠ **These blobs are unreferenced, and the ref does not change that.** A ref pointing at the list keeps *the list* reachable; the ids written inside it are text, not object pointers, so reachability does not follow them — measured: `git rev-list --objects --no-walk {list blob}` returns one object, and a `git gc --prune=now` after anchoring the ref removes the per-file blobs while the list survives. What bounds their lifetime is git's own prune grace (`gc.pruneExpire`, two weeks by default), which a closeout does not outlast even when it spans sessions. ⚠ The blobs most needed are the least covered: a path whose content is **unchanged** between Step 1 and the commit is reachable from the commit anyway, while `_index.md` — the one every ordered edit touches — is reachable from neither the commit nor the ref.
+
+R-FF-BASELINE-04: [finish-feature-flow.md · Step 1 · "Both halves of that command are load-bearing"] The capture has to name the same set `git add` will stage, and it can miss in **both** directions. An **ignored** file captured here enters the baseline as a path the span can never carry — `git add` skips it too — so it reads as a file deleted after Step 1. An **untracked but not ignored** file *omitted* here is the mirror image: `git add {dir}` does stage it, so it arrives in the span with no baseline entry and reads as a file added after Step 1. Both block, and neither is clearable — by the time either surfaces the host is archived and the closeout committed. `--cached --others --exclude-standard` is the set `git add` itself works from, so the two are the same predicate evaluated at two times rather than two sets that happen to agree. ⚠ The second direction is not hypothetical: greenfield's `aggregate-design.md` worksheet is ordered into the host by `AI-AGENT-GUIDE.md` § Ceremony Scaling and may never have been committed.
+
+R-FF-BASELINE-05: [finish-feature-flow.md · Step 1 · "That ref is the baseline"] The `-w` made the blobs durable but left the `path → blob` list — the only way to address them — stated in the conversation, two sentences after the same paragraph called that store unreliable. Closeout is expected to cross sessions: `templates/_index.md`'s Resume Pointer says to read it when continuing in a new conversation, and Step 2 writes a cursor for "the next session". A ref fixes the addressing rather than shrinking it: the name is **recomputed** from `{SPEC-ID}-{slug}`, which the next session already knows from the host it is closing, so nothing about the baseline has to survive the conversation. It also makes the list itself an object in the database rather than a conversational artefact. ⚠ **It does not extend reachability to the blobs it names** — see `R-FF-BASELINE-01` for what actually bounds those. `refs/dflow/**` is outside the default push, fetch and clone refspecs; an explicit refspec or `clone --mirror` does carry it, which is why the step says not to add one.
+
+R-FF-BASELINE-06: [finish-feature-flow.md · Step 4 · "First, confirm the baseline is still readable"] The post-commit item below reads the same ref, so this looks redundant — the difference is entirely **where the failure leaves you**. Below, the `git mv` has happened and the closeout is committed: the host is in `completed/`, the tree Step 1 read cannot be rebuilt, and the section's own "fix it and re-verify" has nothing to act on. Detected here the host is still in `active/` with nothing committed, so the remedy is one step. A check whose failure has no repair procedure is a report, not a gate; this moves the detection to where it is a gate.
+
+
+R-FF-BASELINE-08: [finish-feature-flow.md · Step 4 post-commit verification · "release the baseline anchor"] The ref is deleted rather than left behind because it is scaffolding, and an adopter repo should not accumulate one per closed feature. It is deleted **after** the items pass, not before: while it exists a failed item can be fixed and re-verified against the same evidence, and releasing it first would discard the only copy of what the comparison needs. Deleting a ref changes no file, so it is not a difference the comparison above could see and nothing there needs to admit it.
+
+R-FF-COMMITCELL-03: [finish-feature-flow.md · Step 4 post-commit verification · "An empty hosted `Commit` cell does not fail this item"] The obvious repair — have closeout check the cell it is reading anyway — is the wrong one. `references/pr-review-checklist.md`'s "Every Lightweight Changes row now carries a `Commit` hash" item states its own reason for existing as *"That is why closeout does not assert this for a phase-bearing host, and why it is checkable here"*, so making closeout assert it falsifies the other half of a documented division of labour and leaves the same rule written in two places. What was wrong was never the division; it was that the clause read as a **ruling** that an empty cell is acceptable, stated at the moment closeout is *entered*, while the item reading it runs against the **committed** blob after instruction 1 has already ordered the backfill.
+
+R-FF-CURSOR-01: [finish-feature-flow.md · Step 2 · "Also update the **Resume Pointer** — to the state closeout is actually in"] The terminal value used to be written here, four steps before closeout ends. While the host is still in `active/` the global scans do read this cursor, so a `none` written at Step 2 made the flow's own gate 3 → 4 ask the developer for `/dflow:next` — a command `AI-AGENT-GUIDE.md` requires to be refused when no workflow is active — and it disabled `/dflow:cancel` for a closeout that was genuinely still running. An honest in-progress value removes both and costs nothing: the field is a claim, and a claim that closeout has finished is false until it has.
+
+R-FF-CURSOR-02: [finish-feature-flow.md · Step 4 · "The `git mv` and this write are one uninterruptible pair"] Two decisions, and the second is a deliberate narrowing. **Why it is bound to the `git mv` rather than to the commit:** the archive is what moves the host out of `active/`, so from that instant the cursor is read by one reader (the PR reviewer `references/pr-review-checklist.md` sends to it) instead of by the global scans; writing before the Y / N prompt closes the only window where the host sits in `completed/` while the cursor still declares the workflow active, which is the window `/dflow:cancel` would act on. **Why closeout does not restore it when the commit is declined, fails, or post-commit verification reports `✗`:** a restore cannot buy back findability, because `git mv` is Step 4's first action and `/dflow:status` reads only `active/` — the host is already gone from the only place a restored cursor would be seen. The rule was written and then removed: it bought nothing and cost an index / working-tree synchronisation contract on three failure branches. The accepted residual risk is that a closeout failing after this point is visible only in `git status`.
+
+R-FF-GITMV-01: [finish-feature-flow.md · Step 4 · "`git mv` is mandatory — never use plain `mv` + `git add`"] This preserves git's directory rename detection so `git log --follow` / `git blame` / PR diff quality stays intact across the move.
+
+R-FF-SWEEPKEY-01: [gf · finish-feature-flow.md · Step 4 instruction 2 · "Key it on the flow that produced the change, never on the flow that opened the host"] Those differ, and keying on the host is how the deadlock came back: `modify-existing-flow.md` Step 1.6 opens a **phase-bearing** host for a T1 follow-up, and Step 5.4 puts a T1 new-phase or a T2 lightweight *inside* a host opened by `/dflow:new-feature` — each of those runs Step 5.3 as its own sweep. Ask "which flow opened this host" and a hosted **T2** on a phase-bearing **no-BC** host has no arm at all: half (a) is empty because Step 3 is skipped, and the `glossary.md` rename its Step 5.3 made belongs to a sweep the question refused to look at. Unstaged it fails the clean-tree item; staged it is attributable to nothing. Deriving from *this change's* flow is the fix — not widening the set to "anything dirty".
+
+R-FF-SWEEPKEY-01: [bf · finish-feature-flow.md · Step 4 instruction 2 · "Key it on the flow that produced the change, never on the flow that opened the host"] Those differ, and keying on the host is how the deadlock came back: `modify-existing-flow.md` Step 1.6 opens a **phase-bearing** host for a T1 follow-up, and Step 6.4 puts a T1 new-phase or a T2 lightweight *inside* a host opened by `/dflow:new-feature` — each of those runs Step 6.3 as its own sweep. Ask "which flow opened this host" and a hosted **T2** on a phase-bearing **no-BC** host has no arm at all: half (a) is empty because Step 3 is skipped, and the `glossary.md` rename its Step 6.3 made belongs to a sweep the question refused to look at. Unstaged it fails the clean-tree item; staged it is attributable to nothing. Deriving from *this change's* flow is the fix — not widening the set to "anything dirty".
+
+R-FF-SWEEPKEY-02: [finish-feature-flow.md · Step 4 instruction 2 · "do not go looking for a list that host never produced"] ⚠ Keying this on the minimal-host allow-list (`finish-feature-minimal-host.md`) is what deadlocked the one shape where both halves are empty: a **phase-bearing, no-BC** host that swept a global document has nothing from Step 3 *and* no Step 1 allow-list, while this instruction still requires the delta staged and the post-commit path check would then reject it as unpermitted — two mandatory requirements that could not both be met.
+
+R-FF-SPAN-01: [gf · finish-feature-flow.md · Step 4 post-commit verification · "The span is derived from what was staged, not from what the tables name"] Instruction 2 stages the archived directory **whole**, so a span built from the Phase Specs and Lightweight Changes rows is narrower than the commit — and Step 1 permits exactly one file no table names, the `aggregate-design.md` worksheet. Under the narrower span that file entered the commit and was compared against nothing. Keying on `git ls-tree` closes that for any such file, present or future, with no list to maintain.
+
+R-FF-SPAN-01: [bf · finish-feature-flow.md · Step 4 post-commit verification · "The span is derived from what was staged, not from what the tables name"] Instruction 2 stages the archived directory **whole**, so a span built from the Phase Specs and Lightweight Changes rows is narrower than the commit. Greenfield's Step 1 permits one such file by name (an `aggregate-design.md` worksheet); brownfield has no counterpart today, and keying on `git ls-tree` means it needs no edit if one ever appears.
+
+R-FF-BASELINE-02: [finish-feature-flow.md · Step 4 post-commit verification · "Blob ids alone answer only *same* / *different*"] The derived condition asks whether the committed blob differs from the baseline in **exactly** the ordered edits and nothing else, and id equality cannot express it: on the normal path the ids differ, because Step 2, Step 4's terminal Resume Pointer write and Step 4 instruction 1 all edit `_index.md` by design — so *different* is the expected reading and says nothing about **which** differences are present. Reading the delta is the only form that separates an ordered edit from edit fallout. Equality is still read, and it is not a pass on its own: identical ids mean that file was not touched at all — the ordinary case for the spec files in the host, and a failure for any path a step of this closeout ordered an edit to, because it says the ordered edit never landed.
+
+R-FF-BASELINE-03: [finish-feature-flow.md · Step 4 post-commit verification · "Compare the two path sets first, before any blob comparison"] The `git mv` makes the two sets line up only while no file was added or removed between Step 1 and the commit, so the alignment is the thing to establish rather than the thing to assume — and neither kind of mismatch is reachable by the per-path comparison that follows: a removed file is never visited, because the span comes from `git ls-tree` on the commit, and an added one has no baseline blob to diff against. The other half of this check does not catch them either: the spill item admits the archived host directory **whole**, so a file added inside it is a permitted path. Left unstated, a host file deleted during closeout passes both halves in silence — the coarsest form of the edit fallout this check exists to block.
+
+R-FF-POSTCOMMIT-01: [finish-feature-flow.md · Step 4 post-commit verification · "do not substitute `HEAD^`"] The parent commit is not the tree Step 1 read: the edits legitimately uncommitted at Step 1 would each surface as a difference no step ordered, and the check would block a correct closeout.
+
+R-FF-POSTCOMMIT-02: [finish-feature-flow.md · Step 4 post-commit verification · "`git show HEAD:<path>` for each"] Reading the **committed** blob is what catches "the rename carried stale content" and "the row never made it into the commit".
+
+R-FF-SPILL-01: [gf · finish-feature-flow.md · Step 4 post-commit verification · "The closeout commit contains only what closeout is allowed to write"] ⚠ **Keyed on instruction 2, and deliberately not on the minimal-host allow-list.** That allow-list exists only for a `Minimal host (zero-phase)` and lives in `finish-feature-minimal-host.md`; a phase-bearing host has none. Keying this item on it — with "plus whatever Step 3 wrote" as the other half — left a **phase-bearing, no-BC** host with **both** sources empty while instruction 2 still required its global sweep delta staged: stage it and this item rejected the path, skip it and the clean-tree item failed. Instruction 2 is the one statement that covers every host shape, which is why it is the source.
+
+R-FF-SPILL-01: [bf · finish-feature-flow.md · Step 4 post-commit verification · "The closeout commit contains only what closeout is allowed to write"] ⚠ **Keyed on instruction 2, and deliberately not on the minimal-host allow-list.** That allow-list exists only for a `Minimal host (zero-phase)` and lives in `finish-feature-minimal-host.md`; a phase-bearing host has none. Keying this item on it — with "plus whatever Step 3 wrote" as the other half — left a **phase-bearing, no-BC** host with **both** sources empty (Step 3 is skipped for a no-BC host and for a baseline host) while instruction 2 still required its global sweep delta staged: stage it and this item rejected the path, skip it and the clean-tree item failed. Instruction 2 is the one statement that covers every host shape, which is why it is the source.
+
+R-FF-SPILL-02: [finish-feature-flow.md · Step 4 post-commit verification · "Scope: this is a path-level spill check and nothing more"] A clean tree does not even cover the path level — it proves the changes were committed, not that only permitted ones were — and Step 4's staging instructions prove nothing on the developer-commit path.
+
+R-FF-DERIV-01: [finish-feature-flow.md · Step 5 · "First, print the closeout verification's derivation"] **Why this is here.** The verification derives its admitted set instead of reading a list — that is what keeps the list and its sources from drifting apart — but it also means a reader cannot see the set by looking at the checklist. Printing the derivation keeps the flow inspectable instead of a box that answers `✓` without showing its working.
+
+R-FF-INFLIGHT-01: [finish-feature-flow.md · Step 5 · "In-flight reminder"] Surfacing them at closeout is deliberate: attention is about to move elsewhere, and this is exactly where half-done work sinks.
+
+## finish-feature-minimal-host.md
+
+R-FF-COMMITCELL-01: [finish-feature-minimal-host.md · Step 1 · "Do not collapse the middle case into the first"] it is the one that reads as *filled* to every rule written against empty / non-empty, which is exactly why it survives elsewhere.
+
+R-FF-COMMITCELL-02: [finish-feature-minimal-host.md · Step 1 · "Deliberately not run on a phase-bearing host"] a hosted T3's row rides the host's *next* commit (`references/git-integration.md` § Commit checkpoints), and nothing requires a hosted row to declare implementation paths — so (c) has no defined input there, and demanding it would reject every hosted T3.
+
+R-FF-BASELINECAP-01: [bf · finish-feature-minimal-host.md · Step 1 · "a `spec-baseline` checkpoint and a `Tier = baseline` row imply each other"] `modify-existing-flow.md` Step 1.7 states the contract: a baseline capture is observation-only, *there is no implementation work*, which is why its checkpoint is not named `implementation`. (1) and (2) alone are the ledger talking about itself; (3) is what makes the claim true of the commit.
+
+R-FF-CKPTCOUNT-01: [finish-feature-minimal-host.md · Step 1 · "the Checkpoint Log carries exactly one row at this point"] ⚠ **Why this counts every row, with no exclusion for the `branch-override` record:** a minimal host cannot carry one. `references/modify-existing-flow.md` withholds the branch-gate override from exactly these hosts (Step 1.6's follow-up variant, Step 1.7, Step 1.8), because they assert branch equality against a `branch:` cut by change class.
+
+R-FF-CKPTCOUNT-02: [finish-feature-minimal-host.md · Step 1 · "the Checkpoint Log carries exactly one row at this point"] "Exactly two after closeout" follows from `finish-feature-flow.md` Step 4's post-commit read, which derives its admitted differences from Step 2, Step 4's terminal Resume Pointer write and Step 4 instruction 1, and admits nothing else.
+
+R-FF-FOLLOWUP-01: [finish-feature-minimal-host.md · Step 1 · "the reverse link was opened, not only closed"] Decidable from one commit and one blob per original, so it stays inside closeout's remit.
+
+R-FF-SUMMARY-01: [finish-feature-minimal-host.md · Step 5 · "Zero-phase minimal host — exact fields", on a no-BC host's `Related BR-IDs`] Forcing `none` here would erase a marker the approved zero-phase shape requires.
+
+## init-project-flow.md
+
+R-INIT-DEFERRED-01: [init-project-flow.md · Step 3.1 · "is NOT generated here", both bullets] Init creates neither a per-context `behavior.md` nor either `analysis.md`: an empty file created ahead of its content becomes a stale placeholder.
+
+## modify-existing-flow.md
+
+R-ME-BASELINE-01: [bf · modify-existing-flow.md · Step 2 · "Systematic Baseline Capture"] Baseline capture looks for system-level knowledge and records it in `analysis.md`, even though it runs only when the feature being modified has no prior spec: it is how a project that adopts Dflow midway gets its existing system into `analysis.md` in bulk, rather than one entry at a time. Every other entry point only records what the change in hand happens to touch; the observation-only route in Part A records without changing anything, but only what that observation reached.
+
+## new-phase-flow.md
+
+R-NP-ANALYSIS-01: [new-phase-flow.md · Step 2 · "System-level knowledge?"] Step 2 records into `analysis.md` on the spot rather than leaving it to closeout, because deferring needs two things this flow does not have: somewhere to hold the answer until closeout (the phase-spec template has no section for it), and a closeout step that always runs (a host with no bounded context skips `/dflow:finish-feature` Step 3 entirely). Each track's Step 7 carves these two paths out of its "remain `/dflow:finish-feature` responsibilities" sentence for the same reason. Step 6 re-checks what Step 2 recorded - what the phase was to add or change against what it built, what Step 2 uncovered in the existing system against the system as it now stands, since knowledge Step 2 uncovered was true before the phase began and does not stop being true because the phase built nothing for it - instead of leaving that to closeout as well: no closeout step is sure to reach the entry (`/dflow:new-feature` § 8.4 archives without `/dflow:finish-feature`), and by then a checkpoint has usually committed it, so no diff would show it.
+
+## templates/analysis.md
+
+R-ANALYSIS-PLACEMENT-01: [templates/analysis.md · Placement · "who owns what the entry describes"] This template fills two paths rather than one because the knowledge it holds splits that way in practice: a lifecycle, a derived figure and a mechanism usually have an owning context, while ordered flows across contexts and the function/role map are kept in the domain-root copy by policy, whoever owns what a given flow or row describes - a flow is read end to end across the contexts its steps belong to, and the index answers who reaches what across the whole system, which no one context's copy could show. Keeping all of it in one domain-root file would both deny the first three their owning context and make that single file grow with the whole system; asking who owns the thing an entry describes lets each copy grow with what it describes, and leaves a home for the cases that turn out to have no owner. A hotspot row goes with the knowledge it is stuck on - in whichever copy holds that knowledge, the ownership question deciding only when it is stuck on a business rule or on knowledge not recorded yet - so that whoever reads that knowledge also sees what the project is still working around in it. The per-context path costs little to enforce, because it is an ordinary BC-layer document to every closeout, no-BC and path check in the workflow - though the checks that enumerate those documents by name still name it.
+
+R-ANALYSIS-EVIDENCE-01: [templates/analysis.md · Lifecycles · "Evidence sits on the transitions"] The state list carries no Evidence column because it is the entry's vocabulary - what each value means and what it allows or blocks next - while each transition is a claim about how the system behaves now, which goes stale and must stay re-checkable. The cost is that the claim "these are all the values this field holds" cannot itself be re-checked from the table.
+
+R-ANALYSIS-QUESTIONS-01: [templates/analysis.md · Open Questions and Hotspots · "comes up while writing an entry here"] Questions are not routed into this file by subject: where a question belongs depends on the form its answer will take, and the two can disagree — "which role may approve a refund?" is about role reach, yet its answer is a business rule for the owning context's `rules.md`. An unanswered question therefore stays in the feature spec or in the Open Questions section of the document its answer belongs to; when that document is this template, the question goes in the copy that will hold the answer, whichever copy raised it, so that whoever comes to record the answer finds the question beside it - even where that means creating that copy for the question.
+
+R-ANALYSIS-IDCOL-01: [templates/analysis.md · the two tables with an ID column · "carries it there"] The ID column is placed after the name column, not first, because `dflow render` takes a table's first column as each card's title: with the id first, every card in these two tables would be titled `FN-01` or `HS-01` and the name or the hotspot itself would be demoted to a field. The flow table keeps `#` first because a step number is a reasonable card title.

package/templates/common/skill/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: dflow
 description: >
-  Dflow SDD/DDD workflow guardian for this project. PRIMARY: the canonical
-  /dflow:* commands (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
+  Dflow SDD/DDD workflow guardian. PRIMARY: the canonical /dflow:* commands
+  (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
   /dflow:new-phase, /dflow:finish-feature, /dflow:pr-review, /dflow:verify,
   /dflow:report-dflow-feedback, /dflow:status, /dflow:next, /dflow:cancel).
-  SECONDARY — engage ONLY for adding or changing product/user-facing/domain
-  behavior, a new requirement, a feature or bug-fix workflow, or spec-impacting
-  architecture/domain-model decisions. Includes indirect phrasings, e.g. "I want
-  to build/add ...", "let's add the ability to ...", "we need to support ...",
-  "can you implement ...", "users should be able to ...", "the app should also
-  ...". Do NOT engage for pure refactors, renames, infra/build chores,
-  formatting, dep bumps, or general code questions ("how does X work", "explain
-  this"). When engaged by natural language, DO NOT auto-enter a workflow: judge
-  the intent, suggest the matching /dflow: command, and wait for confirmation.
+  SECONDARY — engage for anything Dflow tracks: a product-visible change, or
+  one touching a machine-consumed contract (log/export/API/event, env
+  var/CLI flag/exit code), data structure, operational semantics
+  (security/CVE, safety, resilience, compliance, payment),
+  performance/resource/SLA, BR-ID, or architecture/domain model. Indirect
+  phrasings: "I want to build/add ...", "we need to support ...", "users
+  should be able to ...". Do NOT engage for behavior-preserving routine work
+  touching none of those — refactors, renames, chores, formatting, routine
+  dependency bumps — or code questions. When engaged by natural language, DO
+  NOT auto-enter a workflow: judge the intent, suggest the matching /dflow:
+  command, and wait for confirmation.
 ---
 
 <!-- dflow-generated: skill-adapter -->

package/templates/greenfield/references/drift-verification.md

@@ -165,6 +165,10 @@ Issues:
      remove the stale scenario reference from behavior.md
 ```
 
+When a remediation action adds or updates `rules.md` rows, follow the spec formatting convention:
+
+> **Table-cell formatting**: keep table cells concise — separate multiple short items with `<br>` (never chain them into one line with ；/; separators), and move long narrative detail out of the cell into a document section (full convention: the formatting comment at each spec doc's head).
+
 The optional domain-doc hygiene checks (below) append their non-blocking signals
 to this same report — the `events.md` cross-check as `⚠`, the `models.md`
 Code-Mapping check as `ℹ` — and never change the core pass / fail count.