@khoavu882/doflow 2.0.1 → 2.0.2

package/core/shared/scripts/doflow/bash/do-git-state.sh

@@ -111,10 +111,14 @@ is_dirty() {
 # means anything. The local branch was used unconditionally, so a develop that had not been pulled
 # made every distance wrong by however stale it was — observed live at 22 reported against 32.
 #
-# The remote-tracking ref is preferred where it exists; the local branch is the fallback for a
-# repository with no remote or one never fetched. Preferring it does not make the answer *fresh* —
-# origin/develop is only as current as the last fetch — so the third field reports how far the
-# local branch trails, which is non-zero exactly when a `git fetch` would change the answer.
+# The remote-tracking ref is preferred where it exists, unless the local branch is strictly ahead
+# of it (origin/<branch> is an ancestor of the branch and they differ): then the local branch holds
+# integrated work the remote has not seen yet, and measuring from origin would count that work as
+# the caller's own. An equal, behind or diverged local branch keeps the remote preference; the local
+# branch is the fallback for a repository with no remote or one never fetched. Preferring the remote
+# does not make the answer *fresh* — origin/develop is only as current as the last fetch — so the
+# third field reports how far the local branch trails, which is non-zero exactly when a `git fetch`
+# would change the answer.
 #
 # Echoes: "<ref> <kind> <local-behind-remote>"
 resolve_integration_ref() {
@@ -125,6 +129,10 @@ resolve_integration_ref() {
     kind="remote-tracking"
     if git rev-parse --verify --quiet "refs/heads/${branch}" >/dev/null 2>&1; then
       behind="$(git rev-list --count "${branch}..origin/${branch}" 2>/dev/null || echo 0)"
+      if [ "$behind" = "0" ] && [ "$(git rev-list --count "origin/${branch}..${branch}" 2>/dev/null || echo 0)" -gt 0 ]; then
+        ref="$branch"
+        kind="local"
+      fi
     fi
   fi
   printf '%s %s %s\n' "$ref" "$kind" "$behind"

package/core/shared/scripts/doflow/bash/do-parallel-check.sh

@@ -12,6 +12,10 @@ case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; th
 # reducing dispatch overhead. The script forms groups from `owner:` fields, computes union
 # file sets per group, and reports overlaps across groups (`group_overlaps[]`).
 #
+# Owner and files are read from the whole task block: the task line and a `Verify:` line under it. A task
+# that declares no `files:` (`files: none` is a declaration), or declares different sets, is named in
+# `files_missing[]` / `files_conflict[]`, and while one exists `parallel_safe` is `null`, never `true`.
+#
 # Advisory by design: it reports overlaps and grouping decisions; the calling skill decides
 # to serialize or group dispatch. It never edits the plan and never dispatches anything.
 #
@@ -67,7 +71,70 @@ plan_abs="$repo_root/$plan_rel"
 
 # Pipeline: awk outputs tab-separated values (one per line), jq reads raw lines as strings,
 # aggregates them into an array, then processes each row.
+#
+# A task is its whole block: the `- [ ] <id>` line and the indented lines under it, up to the next task or
+# heading. `owner:` and `files:` are read from the task line and from a `Verify:` line (the layout plans
+# written with a verification line use); each is the text after the line's first em dash. A task that
+# declares files twice must declare the same set twice: a different set is `conflict`, and a task that
+# declares none is `missing`. `files: none` is a declaration of an empty set, not a missing one.
 awk -v want="$phase" '
+  # Sorted, de-duplicated, comma-joined form of a comma list, so two spellings of one set compare equal.
+  function normalize(list,    n, parts, i, j, t, out, last) {
+    n = split(list, parts, ",")
+    for (i = 1; i <= n; i++) { gsub(/^[ \t]+|[ \t]+$/, "", parts[i]) }
+    for (i = 2; i <= n; i++) {
+      t = parts[i]
+      for (j = i - 1; j >= 1 && parts[j] > t; j--) parts[j + 1] = parts[j]
+      parts[j + 1] = t
+    }
+    out = ""; last = "\001"
+    for (i = 1; i <= n; i++) {
+      if (parts[i] == "" || parts[i] ~ /^none/ || parts[i] == last) continue
+      out = out (out == "" ? "" : ",") parts[i]
+      last = parts[i]
+    }
+    return out
+  }
+  # Reads one line'"'"'s owner:/files: fields into the current task.
+  function declare(line,    dash_pos, section, o, f) {
+    dash_pos = index(line, "—")
+    if (dash_pos == 0) return
+    section = substr(line, dash_pos + length("—"))
+    if (match(section, /owner:[^;]*/)) {
+      o = substr(section, RSTART + 7, RLENGTH - 7)
+      gsub(/^[ \t]+|[ \t]+$/, "", o)
+      if (o != "") {
+        if (owner == "") owner = o
+        else if (owner != o) conflict = 1
+      }
+    }
+    if (match(section, /files:[^;]*/)) {
+      f = substr(section, RSTART + 6, RLENGTH - 6)
+      gsub(/^[ \t]+|[ \t]+$/, "", f)
+      if (f == "") return
+      declared++
+      set = normalize(f)
+      if (declared == 1) first = set
+      else if (set != first) conflict = 1
+      m = split(set, items, ",")
+      for (k = 1; k <= m; k++) if (items[k] != "" && !(items[k] in seen)) { seen[items[k]] = 1; order[++norder] = items[k] }
+    }
+  }
+  function flush(    status, k) {
+    if (id == "") return
+    status = conflict ? "conflict" : (declared == 0 ? "missing" : "ok")
+    if (norder == 0) print id "\t" par "\t" owner "\t\t" status
+    for (k = 1; k <= norder; k++) print id "\t" par "\t" owner "\t" order[k] "\t" status
+    id = ""
+  }
+  function start(line) {
+    id = substr(line, RSTART + 6, RLENGTH - 6)
+    par = (line ~ /^- \[[ x]\] [^ ]+ \[P\]/) ? "P" : "S"
+    owner = ""; declared = 0; conflict = 0; first = ""; norder = 0
+    delete seen; delete order
+    declare(line)
+  }
+  /^#+ / { flush() }
   /^### Phase / {
     inphase = ($3 == want)
     next
@@ -75,43 +142,22 @@ awk -v want="$phase" '
   /^### / { inphase = 0; next }
   !inphase { next }
   /^- \[[ x]\] / {
-    line = $0
-    if (match(line, /^- \[[ x]\] [^ ]+/) == 0) next
-    id = substr(line, RSTART + 6, RLENGTH - 6)
-    par = (line ~ /^- \[[ x]\] [^ ]+ \[P\]/) ? "P" : "S"
-    # Extract only the portion after em-dash for owner:/files: parsing
-    dash_pos = index(line, "—")
-    if (dash_pos == 0) {
-      print id "\t" par "\t\t"
-      next
-    }
-    field_section = substr(line, dash_pos + length("—"))
-    owner = ""
-    if (match(field_section, /owner:[^;]*/)) {
-      owner = substr(field_section, RSTART + 7, RLENGTH - 7)
-      gsub(/^[ \t]+|[ \t]+$/, "", owner)
-    }
-    if (match(field_section, /files:[^;]*/)) {
-      files = substr(field_section, RSTART + 6, RLENGTH - 6)
-      n = split(files, parts, ",")
-      emitted = 0
-      for (i = 1; i <= n; i++) {
-        f = parts[i]
-        gsub(/^[ \t]+|[ \t]+$/, "", f)
-        if (f == "" || f ~ /^none/) continue
-        print id "\t" par "\t" owner "\t" f
-        emitted = 1
-      }
-      if (!emitted) print id "\t" par "\t" owner "\t"
-    } else {
-      print id "\t" par "\t" owner "\t"
-    }
+    flush()
+    if (match($0, /^- \[[ x]\] [^ ]+/) == 0) next
+    start($0)
+    next
   }
+  id != "" && /^[ \t]*[-*]?[ \t]*\**Verify\**:/ { declare($0) }
+  END { flush() }
 ' "$plan_abs" | jq -R . | jq -s --arg phase "$phase" '
   # Convert array of tab-separated strings to array of objects
   map(split("\t")) |
-  map({id: .[0], par: .[1], owner: (.[2] // ""), file: (.[3] // "")}) |
+  map({id: .[0], par: .[1], owner: (.[2] // ""), file: (.[3] // ""), meta: (.[4] // "missing")}) |
   . as $rows |
+
+  # Tasks whose file metadata cannot establish anything: none declared, or declarations that disagree
+  ([.[] | select(.meta == "missing") | .id] | unique) as $files_missing |
+  ([.[] | select(.meta == "conflict") | .id] | unique) as $files_conflict |
   
   # Separate by parallel/sequential
   ([.[] | select(.par == "P") | .id] | unique)   as $par |
@@ -200,8 +246,15 @@ awk -v want="$phase" '
     # a non-empty `group_overlaps` naming the very file two groups both write. `do-execute-plan`
     # tells the reader to branch on this field and never on the exit code, so either shape
     # authorises concurrent writes to one file.
+    #
+    # A task with no `files:` (or two that disagree) has an unknown write set, so a phase containing one
+    # is never reported safe: `null` (unknown, run serially) unless a real overlap already makes it `false`.
     parallel_safe: (if (($par | length) == 0 and ($seq | length) == 0) then null
-                    else (($overlaps | length) == 0 and ($final_group_overlaps | length) == 0) end),
+                    elif (($overlaps | length) > 0 or ($final_group_overlaps | length) > 0) then false
+                    elif (($files_missing | length) > 0 or ($files_conflict | length) > 0) then null
+                    else true end),
+    files_missing: $files_missing,
+    files_conflict: $files_conflict,
     serialize: ([$overlaps[] | .tasks[]] | unique),
     groups: $final_groups,
     group_overlaps: $final_group_overlaps,

package/core/shared/scripts/doflow/bash/do-review-package.sh

@@ -21,7 +21,10 @@ case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; th
 # Usage:
 #   do-review-package.sh --task=<id> --base=<sha> --head=<sha> [--slug=<slug>] [--json]
 #
-# Emits: {path, commits, bytes, base, head}
+# Emits: {path, commits, bytes, base, head}, plus missing[] when the rules block could not be built.
+#
+# Between the title and the commit list the package carries the "Rules that apply to you" block: the
+# mustCarry lines of the rule ledger (core/registry/rules.json), as the task and group briefs print them.
 
 set -uo pipefail
 
@@ -96,10 +99,40 @@ if [ "${commits:-0}" -eq 0 ]; then
   exit 2
 fi
 
+# The registry file `core/registry/<name>` of the runtime this script belongs to: next to the checkout or
+# projected runtime found above this script, else the global projected runtime (as do-task-brief.sh).
+registry_file() { # registry_file <name>
+  local d="$script_dir" c
+  while [ -n "$d" ] && [ "$d" != "/" ]; do
+    for c in "$d/core/registry/$1" "$d/runtime/core/registry/$1"; do
+      if [ -f "$c" ]; then printf '%s' "$c"; return 0; fi
+    done
+    d="$(dirname "$d")"
+  done
+  c="${HOME:-}/.doflow/runtime/core/registry/$1"
+  if [ -f "$c" ]; then printf '%s' "$c"; fi
+  return 0
+}
+
+missing='[]'
+rules_block=""
+rules_file="$(registry_file rules.json)"
+if [ -z "$rules_file" ]; then
+  missing='["brief-rules: core/registry/rules.json is missing"]'
+else
+  rule_lines="$(jq -r 'if (.mustCarry | type) == "array" and (.mustCarry | length) > 0 and (.mustCarry | all(type == "string")) then .mustCarry[] | "- " + . else empty end' "$rules_file" 2>/dev/null)"
+  if [ -z "$rule_lines" ]; then
+    missing='["brief-rules: core/registry/rules.json has no mustCarry array"]'
+  else
+    rules_block="$(printf '## Rules that apply to you\n\n%s\n' "$rule_lines")"
+  fi
+fi
+
 write_ok=1
 {
   echo "# Review package: $base7..$head7"
   echo
+  if [ -n "$rules_block" ]; then printf '%s\n\n' "$rules_block"; fi
   echo "## Commits"
   git log --oneline "$base..$head_ref"
   echo
@@ -127,5 +160,6 @@ jq -n \
   --argjson commits "${commits:-0}" \
   --argjson bytes "${bytes:-0}" \
   --arg base "$base7" --arg head "$head7" \
-  '{path:$path, commits:$commits, bytes:$bytes, base:$base, head:$head}'
+  --argjson missing "$missing" \
+  '{path:$path, commits:$commits, bytes:$bytes, base:$base, head:$head} + (if ($missing | length) > 0 then {missing:$missing} else {} end)'
 exit 0

package/core/shared/scripts/doflow/bin/doflow-run

@@ -339,6 +339,23 @@ resolve_node_cli() {
   return 1
 }
 
+# A checkout found from the caller's cwd may be older than its local develop branch. Keep this
+# advisory on stderr so the selected CLI's stdout and exit status remain untouched.
+warn_checkout_pwd_behind_develop() {
+  local cwd head counts head_only develop_only
+  [ "$NODE_CLI_SOURCE" = "checkout-pwd" ] || return 0
+  cwd="$(pwd -P 2>/dev/null || pwd)"
+  head="$(git -C "$cwd" rev-parse --verify HEAD 2>/dev/null)" || return 0
+  git -C "$cwd" show-ref --verify --quiet refs/heads/develop || return 0
+  counts="$(git -C "$cwd" rev-list --left-right --count HEAD...refs/heads/develop 2>/dev/null)" || return 0
+  read -r head_only develop_only <<EOF
+$counts
+EOF
+  case "$head_only:$develop_only" in
+    0:[1-9]* ) printf 'doflow-run: warning: selected runtime %s at %s is behind local develop\n' "$NODE_CLI_PATH" "$head" >&2 ;;
+  esac
+}
+
 # ---------------------------------------------------------------------------------- reporting
 
 wants_json=false
@@ -585,6 +602,7 @@ dispatch_node() {
     fail 2 "cli-not-found" \
       "verb '$verb' is served by the Node CLI, which could not be located; set DOFLOW_CLI to a doflow.js path, install the package (npm i -g @khoavu882/doflow), or run from a checkout"
   fi
+  warn_checkout_pwd_behind_develop
   if [ "$NODE_CLI_KIND" = "script" ]; then
     command -v node >/dev/null 2>&1 || fail 2 "node-not-found" \
       "verb '$verb' needs node on PATH to run $NODE_CLI_PATH"

package/core/shared/skills/do-design/SKILL.md

@@ -136,6 +136,10 @@ a `design.md` for it invents an artifact its workflow never reads.
    create one: fill Data Model and Sequence / Data Flow in `design.md` — the content
    `specs.md`'s former §2 and the template's old §6 carried — exactly as the old two-file
    convention did, and leave that dir's layout alone — this feature migrates nothing.
+   Otherwise fill `data-model.md` §1 to §9. Read `references/data_model_example.md` only while filling it.
+   Each table row ends in a Source tag; copy every `proposed` row to `design.md` Open Points for
+   Review. `design.md` Journeys keep user-visible states only and link to `./data-model.md` §3 for
+   the entity states.
 The template is `templates/doflow/design-template.md` in the install step 1 resolved: take `constitution_base` from that JSON and swap its trailing `guidance/references/CONSTITUTION_BASE.md` for that path.
    Fill `[REQUIREMENT_PATH]` with step 1's own resolved `requirement` field, verbatim
    (repo-root-relative, exactly as the resolver returns it) — never hand-compute it, which is only
@@ -167,8 +171,8 @@ Filling the C4 levels, read the guidance tree's `references/DIAGRAM_GUIDE.md` fi
    ```
    Run it a second time against the specs path when step 6 wrote one — `specs.md`'s §1 Interface
    Contracts is an indexed section, so it is checked the same way. Run it a third time against the
-   data-model path when step 6 wrote one — `data-model.md`'s §3 History is its one indexed section,
-   checked the same way, even though its §1/§2 stay free-form. Surface findings verbatim; a
+   data-model path when step 6 wrote one — `data-model.md`'s §9 History is its one indexed section,
+   checked the same way, even though its §1-§8 stay free-form. Surface findings verbatim; a
    non-zero exit is advisory and does not halt the chain.
 8. **Batch this stage's evidence** — one pass here at the stage boundary, never one call per fact.
    `<task id>` is the unit these stores key on: the plan task id once `plan.md` exists, otherwise

package/core/shared/skills/do-design/references/data_model_example.md

@@ -0,0 +1,167 @@
+# Data Model: Order checkout (worked example)
+
+**Feature:** 000-order-checkout · **Design:** ./design.md · **Maturity:** Draft · **Created:** 2025-01-01
+
+> Worked example of a filled `data-model.md`. Read it only while filling the template; the domain
+> is invented. FR-001, FR-002, NFR-001 and IC-001 stand for requirement and contract IDs of that feature.
+
+## 1. Data Model
+
+### Domain inventory
+
+| Domain | Entities | Stateful | Owner | Source |
+|---|---|---|---|---|
+| Ordering | Order | yes | order-service | FR-001 |
+| Ordering | OrderLine | no | order-service | FR-001 |
+
+### Conceptual domain map
+
+```mermaid
+flowchart LR
+    O["Order"] -->|"contains"| L["OrderLine"]
+```
+
+#### ER view: ordering
+
+```mermaid
+erDiagram
+    ORDER ||--|{ ORDERLINE : "contains"
+    ORDER {
+        uuid id PK
+        string status
+        timestamp placed_at
+    }
+    ORDERLINE {
+        uuid id PK
+        uuid order_id FK
+        int quantity
+    }
+```
+
+### Data dictionary
+
+#### Dictionary: Order
+
+| Field | Type | Null | Rule | PII class | Source |
+|---|---|---|---|---|---|
+| id | uuid | no | generated once | none | code:src/orders/order.ts:12 |
+| status | string | no | one of New, Paid, Shipped, Closed | none | FR-001 |
+| placed_at | timestamp | no | set at creation | none | proposed |
+
+#### Dictionary: OrderLine
+
+| Field | Type | Null | Rule | PII class | Source |
+|---|---|---|---|---|---|
+| id | uuid | no | generated once | none | code:src/orders/line.ts:8 |
+| order_id | uuid | no | references Order.id | none | FR-001 |
+| quantity | int | no | at least 1 | none | FR-002 |
+
+### Database Schemas (ORM / DDL)
+
+| Table | Purpose | Primary Key | Foreign Keys & Relations | Key Indexes | Schema / ORM File |
+|---|---|---|---|---|---|
+| `orders` | One customer order | `id` | none | `status` | src/orders/order.ts |
+| `order_lines` | Items of an order | `id` | `order_id` → `orders(id)` | `order_id` | src/orders/line.ts |
+
+### UX / UI Specifications
+- **Design Tokens & Cues:** status badge per state (New, Paid, Shipped, Closed)
+- **Component States:** loading, empty cart, populated, payment error
+
+## 2. Sequence / Data Flow
+
+### Interaction: place and pay
+
+A shopper submits a cart; the flow ends with a paid order or a refused payment.
+
+```mermaid
+sequenceDiagram
+    actor Shopper
+    participant SVC as order-service
+    participant DB as orders-db
+
+    Shopper->>SVC: submit cart
+    SVC->>DB: insert Order (New)
+    alt payment refused
+        SVC-->>Shopper: payment error
+    else payment accepted
+        SVC->>DB: update Order (Paid)
+        SVC-->>Shopper: confirmation
+    end
+```
+
+### Swimlane flows
+
+#### Flow: place-order
+
+![End-to-end flow: place-order](design/c4/flow-place-order.png)
+
+A shopper submits a cart; the flow ends with a paid order handed to fulfilment.
+
+## 3. Lifecycles
+
+> **Authoritative:** this section governs the states of Order and the moves between them.
+
+#### Lifecycle: Order
+
+```mermaid
+stateDiagram-v2
+    [*] --> New
+    New --> Paid: pay
+    New --> Closed: cancel
+    Paid --> Shipped: ship
+    Shipped --> Closed: confirm delivery
+```
+
+**Transitions**
+
+| From | Event | Guard | Actor | Side effect | To | Emitted event | Source |
+|---|---|---|---|---|---|---|---|
+| New | pay | payment accepted | Shopper | stock reserved | Paid | OrderPaid | FR-001 |
+| New | cancel | none | Shopper | none | Closed | OrderClosed | proposed |
+| Paid | ship | stock picked | Warehouse | tracking number set | Shipped | OrderShipped | IC-001 |
+| Shipped | confirm delivery | carrier scan | System | none | Closed | OrderClosed | UNKNOWN -> Open Point |
+
+**Illegal transitions**
+
+- Closed → any state: a closed order is final.
+- Shipped → Paid: payment cannot be undone after dispatch.
+
+**Terminal states:** Closed
+
+#### Lifecycle: OrderLine
+
+N/A: stateless, a line is fixed when the order is placed and follows its Order.
+
+## 4. Cross-entity coupling
+
+N/A: one actor-owned entity changes state; OrderLine has no state to couple.
+
+## 5. Invariants
+
+| Invariant | Holds over | Enforced by | Source |
+|---|---|---|---|
+| An Order has at least one OrderLine | Order, OrderLine | check at placement | FR-002 |
+| A Closed order never changes | Order | code path rejects updates | NFR-001 |
+
+## 6. Ownership / CRUD matrix
+
+| Entity | Owner | Create | Read | Update | Delete | Source |
+|---|---|---|---|---|---|---|
+| Order | order-service | Shopper | Shopper, Warehouse | order-service | none | IC-001 |
+| OrderLine | order-service | Shopper | Shopper, Warehouse | none | none | proposed |
+
+## 7. Event catalogue
+
+| Event | Emitted by | Payload | Consumers | Source |
+|---|---|---|---|---|
+| OrderPaid | order-service | order id, total | warehouse | IC-001 |
+| OrderShipped | order-service | order id, tracking number | notifier | proposed |
+| OrderClosed | order-service | order id, reason | reporting | proposed |
+
+## 8. Retention, PII and migration
+
+N/A: no personal data is stored in these entities and the tables are new.
+
+## 9. History
+
+None — initial version.