@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # do-paths.sh — deterministic path/feature resolver for the doflow chain.
 #
 # Emits a single JSON object describing the ACTIVE feature so doflow skills
@@ -34,6 +35,9 @@ mode="json"
 require=""
 slug_override=""
 prev=""
+# Shared argument rule: `--flag value` is read like `--flag=value` for the flags named here (do-args.sh).
+_da="$(dirname "$0")/do-args.sh"
+if [ -r "$_da" ]; then . "$_da"; doflow_normalize_args "--slug" "$@"; set -- ${DOFLOW_ARGS[@]+"${DOFLOW_ARGS[@]}"}; fi
 for arg in "$@"; do
   case "$arg" in
     --json)         mode="json" ;;
@@ -160,6 +164,31 @@ if [ -n "$feature_slug" ]; then
   fi
 fi
 
+# ── main checkout (IC-005) ────────────────────────────────────────────────────
+# Prints the main working tree's path when this checkout is a linked worktree of it, else nothing.
+# Same rule as the pre-implementation gate's checkouts(): the first `git worktree list --porcelain`
+# entry; a bare main, a main whose directory is gone and a DoFlow sandbox (.doflow-worktree-base at
+# the current checkout's root) never count. Read-only.
+main_checkout() {
+  [ "$is_git_repo" = true ] || return 0
+  [ -e "$repo_root/.doflow-worktree-base" ] && return 0
+  local list first bare=false line here main_real
+  list="$(git -C "$repo_root" worktree list --porcelain 2>/dev/null)" || return 0
+  first=""
+  while IFS= read -r line; do
+    case "$line" in
+      "worktree "*) [ -n "$first" ] && break; first="${line#worktree }" ;;
+      bare) bare=true ;;
+    esac
+  done <<< "$list"
+  [ -n "$first" ] && [ "$bare" = false ] || return 0
+  main_real="$(cd -P "$first" 2>/dev/null && pwd)" || return 0
+  here="$(cd -P "$repo_root" 2>/dev/null && pwd)" || return 0
+  [ "$main_real" = "$here" ] && return 0
+  printf '%s' "$main_real"
+}
+
+feature_root="$repo_root"
 feature_dir=""; requirement=""; design=""; specs=""; data_model=""; plan=""; state=""; audit=""
 decisions=""; decisions_register=""; has_decisions=false
 has_requirement=false; has_design=false; has_plan=false; has_specs=false; has_data_model=false
@@ -167,7 +196,14 @@ layout="legacy"
 intention_next_round=""; design_next_round=""; plan_next_round=""
 if [ -n "$feature_slug" ]; then
   feature_dir="$specs_rel/$feature_slug"
-  abs="$repo_root/$feature_dir"
+  # The checkout that holds the folder: this one when it has it, else the main checkout when a linked
+  # worktree does not, else this one (a new feature). The artifact flags and round scans below read
+  # that checkout; every emitted path stays relative to repo_root.
+  if [ ! -d "$repo_root/$feature_dir" ]; then
+    main_root="$(main_checkout)"
+    if [ -n "$main_root" ] && [ -d "$main_root/$feature_dir" ]; then feature_root="$main_root"; fi
+  fi
+  abs="$feature_root/$feature_dir"
   state="$feature_dir/state.md"; audit="$feature_dir/audit.md"
   decisions="$feature_dir/decisions.md"; decisions_register="$feature_dir/decisions/register.json"
   [ -f "$abs/decisions/register.json" ] && has_decisions=true
@@ -280,7 +316,7 @@ if [ "$require" = "feature" ] && [ -z "$feature_slug" ]; then
       '{error:"ambiguous-feature",
         branch:(if $branch=="" then null else $branch end),
         candidate_slugs:$candidate_slugs,
-        hint:"multiple agent-docs/doflow/ feature dirs exist and no git branch disambiguates them — ask which one via AskUserQuestion, then re-run with --slug=<chosen>"}'
+        hint:"multiple agent-docs/doflow/ feature dirs exist and no git branch disambiguates them — ask which one with the user question tool, then re-run with --slug=<chosen>"}'
   else
     jq -n --arg branch "$branch" \
       '{error:"no-active-feature",
@@ -293,6 +329,7 @@ fi
 # ── emit resolver JSON ────────────────────────────────────────────────────────
 jq -n \
   --arg repo_root "$repo_root" \
+  --arg feature_root "$feature_root" \
   --argjson is_git_repo "$is_git_repo" \
   --arg branch "$branch" \
   --arg feature_slug "$feature_slug" \
@@ -314,6 +351,7 @@ jq -n \
   --arg branch_class "$branch_class" \
   '{
     repo_root:          $repo_root,
+    feature_root:       $feature_root,
     is_git_repo:        $is_git_repo,
     branch:             (if $branch=="" then null else $branch end),
     feature_slug:       (if $feature_slug=="" then null else $feature_slug end),

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # do-prereqs.sh — doflow implement-phase prerequisite gate (prompt-level PRIMARY).
 #
 # Called as step 1 of /do-execute-plan. With --require-plan it exits 2 (and prints an
@@ -48,7 +49,7 @@ if [ "$require_plan" = true ]; then
   if [ -z "$slug" ]; then
     if [ "$candidate_slugs" != "[]" ]; then
       echo "$json" | jq '{ok:false, error:"ambiguous-feature", candidate_slugs:.candidate_slugs,
-                          hint:"multiple agent-docs/doflow/ feature dirs exist and no git branch disambiguates them — ask which one via AskUserQuestion, then re-run do-prereqs.sh --require-plan --slug=<chosen>"}'
+                          hint:"multiple agent-docs/doflow/ feature dirs exist and no git branch disambiguates them — ask which one with the user question tool, then re-run do-prereqs.sh --require-plan --slug=<chosen>"}'
     else
       echo "$json" | jq '{ok:false, error:"no-active-feature", hint:"run /do-brainstorm to start a feature"}'
     fi

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # do-review-package.sh — write one commit range's review package to a file.
 #
 # Commit list, stat summary, and the diff with extended context, in one file a
@@ -25,6 +26,9 @@
 set -uo pipefail
 
 task_id=""; base=""; head_ref=""; slug_override=""
+# Shared argument rule: `--flag value` is read like `--flag=value` for the flags named here (do-args.sh).
+_da="$(dirname "$0")/do-args.sh"
+if [ -r "$_da" ]; then . "$_da"; doflow_normalize_args "--task --base --head --slug" "$@"; set -- ${DOFLOW_ARGS[@]+"${DOFLOW_ARGS[@]}"}; fi
 for arg in "$@"; do
   case "$arg" in
     --task=*) task_id="${arg#--task=}" ;;

package/core/shared/scripts/doflow/bash/do-task-brief.sh

@@ -10,7 +10,7 @@
 #   requirements       requirement.md §3 FR detail for the FRs the task's [US#] traces
 #   why                requirement.md §2 story text for that [US#]
 #   global constraints requirement.md §4 — ALL NFR detail; NFRs bind every task
-#   component boundary design.md §3 detail for components serving those FRs
+#   component boundary design.md "Components & Boundaries" detail for components serving those FRs
 #   verification bar   plan.md §7 rows for those FRs + the phase's Checkpoints line
 #   interface contracts specs.md §1 in full — only when the resolver reports has_specs
 #
@@ -28,8 +28,9 @@
 # task line's `owner:` and `tier:`, calls the dispatcher once per brief and writes the block plus
 # the `*-brief.json` record (IC-018) beside the brief. It names no tool, provider, server or tier.
 # It fails open (IC-019): a missing dispatcher, a non-zero exit or output that is not the expected
-# JSON gives a "Not generated" line and a static report-format block, a `missing[]` note, no
-# record, and the exit status the brief would otherwise have had.
+# JSON gives a "Not generated" line, the must-carry rules (read from the rule ledger,
+# `core/registry/rules.json`, whatever the task line's owner) and a static report-format block, a
+# `missing[]` note, no record, and the exit status the brief would otherwise have had.
 #
 # Usage:
 #   do-task-brief.sh --task=<id> [--harness=<id>] [--slug=<slug>] [--json]
@@ -47,6 +48,9 @@ slug_override=""
 harness=""
 mode=""
 
+# Shared argument rule: `--flag value` is read like `--flag=value` for the flags named here (do-args.sh).
+_da="$(dirname "$0")/do-args.sh"
+if [ -r "$_da" ]; then . "$_da"; doflow_normalize_args "--task --group --tasks --slug --harness" "$@"; set -- ${DOFLOW_ARGS[@]+"${DOFLOW_ARGS[@]}"}; fi
 for arg in "$@"; do
   case "$arg" in
     --task=*)
@@ -192,7 +196,7 @@ task_field() { # task_field <task line> <name>
 }
 
 # Sets bt_md and bt_record on success, bt_reason on every failure; never exits.
-bt_call() { # bt_call <owner> <tier> <heading level> <task ids>
+bt_verb() { # bt_verb <owner> <tier> <heading level> <task ids>
   bt_md=""; bt_record=""; bt_reason=""
   local dispatcher="$script_dir/../bin/doflow-run" out rc
   if [ -z "$1" ]; then bt_reason="the task line names no owner"; return 0; fi
@@ -210,7 +214,43 @@ bt_call() { # bt_call <owner> <tier> <heading level> <task ids>
   return 0
 }
 
-# The block for the brief: the verb's markdown, or the static fallback (no tool names).
+# 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. Empty when none exists.
+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
+}
+
+# Sets bt_rules to the "Rules that apply to you" block (the mustCarry lines of the rule ledger, as
+# src/runtime/brief-rules.js renders them) when the verb did not produce the brief block, which
+# already carries it; names the reason in missing[] when the ledger cannot be read. Never exits.
+bt_rules_load() { # bt_rules_load <heading level>
+  bt_rules=""
+  [ -z "$bt_md" ] || return 0
+  local h="##" file lines
+  [ "$1" = "3" ] && h="###"
+  file="$(registry_file rules.json)"
+  if [ -z "$file" ]; then missing+=("brief-rules: core/registry/rules.json is missing"); return 0; fi
+  lines="$(jq -r 'if (.mustCarry | type) == "array" and (.mustCarry | length) > 0 and (.mustCarry | all(type == "string")) then .mustCarry[] | "- " + . else empty end' "$file" 2>/dev/null)"
+  if [ -z "$lines" ]; then missing+=("brief-rules: core/registry/rules.json has no mustCarry array"); return 0; fi
+  bt_rules="$(printf '%s Rules that apply to you\n\n%s\n' "$h" "$lines")"
+}
+
+# The tier and tools block, the rules and the report format the task line's owner and tier give.
+bt_call() { # bt_call <owner> <tier> <heading level> <task ids>
+  bt_verb "$@"
+  bt_rules_load "$3"
+}
+
+# The block for the brief: the verb's markdown, or the rules and the static fallback (no tool names).
 bt_emit() { # bt_emit <heading level>
   local h="##" who="your report"
   if [ "$1" = "3" ]; then h="###"; who="each task's report"; fi
@@ -218,9 +258,11 @@ bt_emit() { # bt_emit <heading level>
     printf '%s\n' "$bt_md"
     return 0
   fi
+  [ -z "$bt_rules" ] || printf '%s\n\n' "$bt_rules"
   printf '%s Tier and tools\n\nNot generated: %s. Name the tier and tools in the dispatch.\n\n' "$h" "$bt_reason"
-  printf '%s Report format\n\nEnd %s with one line naming every tool and MCP server you used:\n' "$h" "$who"
+  printf '%s Report format\n\nPut one line naming every tool and MCP server you used just before the final status line:\n' "$h"
   printf '%s\n' '`Tools used: <name>[=used|nothing-usable|unavailable|skipped:<reason>], ...`'
+  printf 'End %s with one line `Status: <status>`, where the status is one of `done`, `done-with-concerns`, `needs-context`, `blocked`.\n' "$who"
 }
 
 # Writes the record beside the brief with its tasks filled in; sets record_out to its path, or to ""
@@ -286,8 +328,8 @@ if [ "$mode" = "task" ]; then
   components=""
   if [ -n "$frs" ] && [ -f "$des_abs" ]; then
     components="$(for fr in $frs; do
-      section "$des_abs" '^## 3[.]' | awk -F'|' -v fr="$fr" '
-        /^\| *CMP/ { if ($5 ~ fr) { id = $2; gsub(/^[ \t]+|[ \t]+$/, "", id); print id } }'
+      section "$des_abs" '^## [0-9]+[.] Component' | awk -F'|' -v fr="$fr" '
+        /^\| *(CMP|C[0-9]+)/ { if ($5 ~ fr) { id = $2; gsub(/^[ \t]+|[ \t]+$/, "", id); print id } }'
     done | sort -u)"
   fi
 
@@ -342,7 +384,7 @@ if [ "$mode" = "task" ]; then
       echo "## Component boundary"
       echo
       printf '%s\n' "$components" | while read -r cmp; do
-        [ -n "$cmp" ] && detail_for "$des_abs" '^## 3[.]' "$cmp"
+        [ -n "$cmp" ] && detail_for "$des_abs" '^## [0-9]+[.] Component' "$cmp"
       done
       echo
     fi
@@ -352,7 +394,7 @@ if [ "$mode" = "task" ]; then
       echo
       # §1 IN FULL, deliberately unfiltered: an IC-### entry carries no FR or component
       # linkage field, so there is nothing to filter it by the way "component boundary"
-      # above filters design.md §3 rows on the FRs they name.
+      # above filters design.md Components & Boundaries rows on the FRs they name.
       section "$specs_abs" '^## 1[.]' | awk 'NF { p = 1 } p'
       echo
     fi
@@ -457,8 +499,8 @@ else
   # Union of components serving those FRs
   if [ -n "$all_frs" ] && [ -f "$des_abs" ]; then
     all_comps_raw="$(for fr in $all_frs; do
-      section "$des_abs" '^## 3[.]' | awk -F'|' -v fr="$fr" '
-        /^\| *CMP/ { if ($5 ~ fr) { id = $2; gsub(/^[ \t]+|[ \t]+$/, "", id); print id } }'
+      section "$des_abs" '^## [0-9]+[.] Component' | awk -F'|' -v fr="$fr" '
+        /^\| *(CMP|C[0-9]+)/ { if ($5 ~ fr) { id = $2; gsub(/^[ \t]+|[ \t]+$/, "", id); print id } }'
     done | sort -u)"
   fi
 
@@ -490,8 +532,8 @@ else
     t_comps=""
     if [ -n "$t_frs" ] && [ -f "$des_abs" ]; then
       t_comps="$(for fr in $t_frs; do
-        section "$des_abs" '^## 3[.]' | awk -F'|' -v fr="$fr" '
-          /^\| *CMP/ { if ($5 ~ fr) { id = $2; gsub(/^[ \t]+|[ \t]+$/, "", id); print id } }'
+        section "$des_abs" '^## [0-9]+[.] Component' | awk -F'|' -v fr="$fr" '
+          /^\| *(CMP|C[0-9]+)/ { if ($5 ~ fr) { id = $2; gsub(/^[ \t]+|[ \t]+$/, "", id); print id } }'
       done | sort -u)"
     fi
 
@@ -541,7 +583,7 @@ else
         echo "## Component boundary"
         echo
         printf '%s\n' "$t_comps" | while read -r cmp; do
-          [ -n "$cmp" ] && detail_for "$des_abs" '^## 3[.]' "$cmp"
+          [ -n "$cmp" ] && detail_for "$des_abs" '^## [0-9]+[.] Component' "$cmp"
         done
         echo
       fi
@@ -590,7 +632,7 @@ else
         echo "### Component boundary"
         echo
         printf '%s\n' "$all_comps_raw" | while read -r cmp; do
-          [ -n "$cmp" ] && detail_for "$des_abs" '^## 3[.]' "$cmp"
+          [ -n "$cmp" ] && detail_for "$des_abs" '^## [0-9]+[.] Component' "$cmp"
         done
         echo
       fi

package/core/shared/scripts/doflow/bash/render-audit.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # render-audit.sh — projects the orchestrator's own journal into a human-readable audit.md.
 #
 # audit.md is generated, never hand-authored: this script deterministically OVERWRITES it in full
@@ -76,13 +77,36 @@ fi
 [ "$rc" -eq 0 ] || note "resolver-error"
 
 repo_root=$(printf '%s' "$resolved_json" | jq -r '.repo_root // empty')
+feature_root=$(printf '%s' "$resolved_json" | jq -r '.feature_root // empty')
+[ -n "$feature_root" ] || feature_root="$repo_root"
 feature_slug=$(printf '%s' "$resolved_json" | jq -r '.feature_slug // empty')
 audit_rel=$(printf '%s' "$resolved_json" | jq -r '.audit // empty')
 [ -n "$feature_slug" ] || note "no-active-feature"
 
 # WorkflowOrchestrator's own stateDir/runFile convention (workflow-orchestrator.ts):
 #   stateDir = <root>/.doflow/state/orchestration ; runFile = <stateDir>/<taskId>.json
-journal_file="$repo_root/.doflow/state/orchestration/$feature_slug.json"
+#
+# The run is read from the MAIN checkout first (IC-004): a linked worktree's task records live there.
+# Main is the first `git worktree list --porcelain` entry, the pre-implementation gate's rule: a bare
+# main, a vanished main and a DoFlow sandbox (.doflow-worktree-base at this checkout's root) do not
+# count. Main holding no copy, or this being the main checkout, falls back to this checkout's own.
+main_checkout() {
+  [ -e "$repo_root/.doflow-worktree-base" ] && return 0
+  local list first="" is_bare=false line
+  list="$(git -C "$repo_root" worktree list --porcelain 2>/dev/null)" || return 0
+  while IFS= read -r line; do
+    case "$line" in
+      "worktree "*) [ -n "$first" ] && break; first="${line#worktree }" ;;
+      bare) is_bare=true ;;
+    esac
+  done <<< "$list"
+  [ -n "$first" ] && [ "$is_bare" = false ] && cd -P "$first" 2>/dev/null && pwd
+  return 0
+}
+journal_rel=".doflow/state/orchestration/$feature_slug.json"
+journal_file="$repo_root/$journal_rel"
+main_root="$(main_checkout)"
+if [ -n "$main_root" ] && [ -f "$main_root/$journal_rel" ]; then journal_file="$main_root/$journal_rel"; fi
 [ -f "$journal_file" ] || note "no orchestration run recorded yet"
 
 jq -e '.history | type == "array"' "$journal_file" >/dev/null 2>&1 || note "journal-unreadable"
@@ -93,7 +117,7 @@ jq -e '.history | type == "array"' "$journal_file" >/dev/null 2>&1 || note "jour
 # reading it from the resolver rather than recomputing it here still means a future resolver change
 # has one place to land, not two that can drift apart.
 [ -n "$audit_rel" ] || note "resolver-missing-audit-path"
-audit_file="$repo_root/$audit_rel"
+audit_file="$feature_root/$audit_rel"
 
 # Render to a temp file first, then move it into place. `>"$audit_file"` truncates the target
 # before the group runs, and with no `-e` a mid-stream jq abort (a malformed or hand-corrupted

package/core/shared/scripts/doflow/bash/render-diagrams.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # render-diagrams.sh — renders a chain artifact's fenced mermaid blocks to image files.
 #
 # A FAITHFUL render: the same nodes, the same edges, the same labels. The committed markdown is the

package/core/shared/scripts/doflow/bash/render-puml.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # render-puml.sh — renders a feature's authored PlantUML sources and projects them into its artifact.
 #
 # ONE verb doing BOTH derived views, deliberately (035 design R6): reading the source once means the
@@ -150,7 +151,7 @@ for src in "${sources[@]}"; do
     fi
   fi
 
-  # One source feeds design.md §2's inline block; the others render only to images.
+  # One source feeds design.md System Overview (C4)'s inline block; the others render only to images.
   if [ "$src" = "$block_src" ]; then
     # stdout only is the block: the splice writes it into authored prose, so anything the projector
     # (or Node) prints on stderr, an ExperimentalWarning for one, must never become part of it.

package/core/shared/scripts/doflow/bash/validate-artifacts.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # validate-artifacts.sh — advisory consistency checker for doflow chain artifacts.
 #
 # Checks that an artifact's index tables agree with the detail beside them. This is a CONSISTENCY
@@ -18,6 +19,9 @@
 #   unknown    a line outside History, comments and code fences cites a DEC-### that is not in the
 #              feature's decision register. Inert without a register.
 #   rollup     plan.md's phase rollup counts match its task checklist
+#   task-graph plan.md's task lines parse as the task-attempt ledger reads them: one finding per
+#              problem the read-only `plan-check` verb reports. Fail-soft: with the dispatcher,
+#              node or jq unavailable it prints one `note:` line on stderr and adds no finding.
 #
 # Grammar (see guidance/references/ARTIFACT_FORMAT.md) — deliberately prefix-agnostic, so
 # FR/NFR/C/D/A and any future prefix work with no change here:
@@ -81,10 +85,10 @@ refuse_invalid_slug() {
 }
 
 # ── locate targets ────────────────────────────────────────────────────────────────────────────
+script_dir="$(cd "$(dirname "$0")" && pwd)"
 if [ "${#targets[@]}" -eq 0 ]; then
   command -v jq >/dev/null 2>&1 || note "jq-absent"
 
-  script_dir="$(cd "$(dirname "$0")" && pwd)"
   RESOLVER="$script_dir/do-paths.sh"
   [ -f "$RESOLVER" ] || RESOLVER="${DOFLOW_CONFIG_DIR:+$DOFLOW_CONFIG_DIR/scripts/doflow/bash/do-paths.sh}"
   [ -f "$RESOLVER" ] || note "resolver-absent"
@@ -95,7 +99,9 @@ if [ "${#targets[@]}" -eq 0 ]; then
   [ "$rc" -eq 2 ] && refuse_invalid_slug "$json"
   [ "$rc" -eq 0 ] || note "resolver-error"
 
-  root=$(printf '%s' "$json" | jq -r '.repo_root // empty')
+  # The feature folder's checkout: a linked worktree that has not yet got the folder reads it from
+  # main. Resolvers from before feature_root exist carry only repo_root, which is then the answer.
+  root=$(printf '%s' "$json" | jq -r '.feature_root // .repo_root // empty')
   [ -n "$(printf '%s' "$json" | jq -r '.feature_slug // empty')" ] || note "no-active-feature"
 
   # data-model.md is a default target only for a feature that has a decision register, so a folder
@@ -110,7 +116,6 @@ if [ "${#targets[@]}" -eq 0 ]; then
 elif command -v jq >/dev/null 2>&1; then
   # Explicit paths skip discovery, but the stale rule still needs the feature's register. Resolve
   # quietly: any failure here only leaves the rule inert, never changes what was asked for.
-  script_dir="$(cd "$(dirname "$0")" && pwd)"
   RESOLVER="$script_dir/do-paths.sh"
   [ -f "$RESOLVER" ] || RESOLVER="${DOFLOW_CONFIG_DIR:+$DOFLOW_CONFIG_DIR/scripts/doflow/bash/do-paths.sh}"
   json=""
@@ -121,7 +126,7 @@ elif command -v jq >/dev/null 2>&1; then
     [ "$rc" -eq 2 ] && refuse_invalid_slug "$json"
     [ "$rc" -eq 0 ] || json=""
   fi
-  root=$(printf '%s' "$json" | jq -r '.repo_root // empty' 2>/dev/null)
+  root=$(printf '%s' "$json" | jq -r '.feature_root // .repo_root // empty' 2>/dev/null)
 fi
 
 # ── decision register (stale rule) ──────────────────────────────────────────────────────────────
@@ -155,6 +160,41 @@ if [ -n "$feat_abs" ] && [ "$(printf '%s' "$json" | jq -r '.has_decisions // fal
   fi
 fi
 
+# ── task-graph rule ───────────────────────────────────────────────────────────────────────────
+# Asks the plan-check verb about one plan.md and leaves its problems in tg_out as
+# `rule<TAB>id<TAB>message` records, the shape awk's finding() prints. It sets a global rather than
+# printing, so the once-per-run note flag survives the call. A plan-check that cannot answer adds
+# no finding: it prints one `note:` line per run on stderr instead. `plan-unreadable` adds nothing
+# either; the unreadable-file finding already says the file was not checked.
+tg_noted=0
+tg_note() {
+  [ "$tg_noted" -eq 1 ] && return 0
+  tg_noted=1
+  printf 'note: plan-check unavailable (%s); the task-graph rule did not run\n' "$1" >&2
+}
+tg_out=""
+task_graph_findings() { # task_graph_findings <plan file>
+  local dispatcher="$script_dir/../bin/doflow-run" tg
+  tg_out=""
+  command -v jq >/dev/null 2>&1 || { tg_note "jq-absent"; return 0; }
+  [ -f "$dispatcher" ] || { tg_note "dispatcher-absent"; return 0; }
+  tg=$(bash "$dispatcher" plan-check "$1" --json </dev/null 2>/dev/null)
+  if ! printf '%s' "$tg" | jq -e 'type == "object" and has("ok")' >/dev/null 2>&1; then
+    tg_note "no-json-from-plan-check"; return 0
+  fi
+  [ "$(printf '%s' "$tg" | jq -r '.error // empty')" = "plan-unreadable" ] && return 0
+  # jq prints `id<TAB>message`; awk adds the rule through the same finding() shape the checks use.
+  tg_out=$(printf '%s' "$tg" | jq -r '
+    .problems[]?
+    | [(if (.ids // [] | length) > 0 then (.ids | join(",")) else "-" end),
+       (.kind
+        + (if has("value") then " '"'"'" + (.value | tostring) + "'"'"'"
+           elif (.via // [] | length) > 0 then " via " + (.via | join(", "))
+           else "" end))]
+    | map(gsub("[\t\r\n]"; " ")) | join("\t")' 2>/dev/null \
+    | awk -F'\t' 'function finding(rule, id, msg) { print rule "\t" id "\t" msg } { finding("task-graph", $1, $2) }') || tg_out=""
+}
+
 # ── check each target ─────────────────────────────────────────────────────────────────────────
 # Findings accumulate as: <file>\t<rule>\t<id>\t<message>
 findings=""
@@ -481,6 +521,10 @@ for f in "${targets[@]}"; do
     findings="${findings}${f}"$'\t'"io"$'\t'"-"$'\t'"could not be parsed (awk exit ${awk_status}) — this file was NOT checked"$'\n'
     continue
   fi
+  if [ "$(basename "$f")" = "plan.md" ]; then
+    task_graph_findings "$f"
+    [ -n "$tg_out" ] && out="${out:+$out$'\n'}$tg_out"
+  fi
   if [ -n "$out" ]; then
     while IFS= read -r line; do
       [ -n "$line" ] && findings="${findings}${f}"$'\t'"${line}"$'\n'