@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

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

@@ -14,8 +14,12 @@
 #
 # Usage: doflow-run <verb> [args...]
 #   enforcement --harness <id> --policy <id> [--profile <id>] [--json]
+#   context-emit --event launch|prompt|delta --cwd <dir> [--session <id>] [--harness <id>]
+#     [--nudge nudge|suppress|none] [--max-bytes <n>] [--task-id <id>] [--slug <slug>] [--peek] [--json]
+#   context-grant --summary <summaryId|pending> --to-run <id> --to-lineage <id>
+#     [--from-worktree <dir>] [--from-run <id>] [--from-lineage <id>] [--max-bytes <n>] [--json]
 #   Every verb accepts --json. Exit 0 = success, 1 = an actionable finding, 2 = usage or
-#   resolution error, 3 = context-pack overflow. Arguments, stdin and exit status pass through the
+#   resolution error, 3 = context-pack overflow or context-emit refusal. Arguments, stdin and exit status pass through the
 #   dispatcher unmodified —
 #   `sync-context` reads its block body from stdin, so anything that buffered or consumed it here
 #   would break that verb rather than merely inconvenience it.
@@ -30,29 +34,61 @@ set -euo pipefail
 # `set -euo pipefail` never stops on it; nothing in it can reach the dispatcher's own options or
 # variables. Appends one JSON line of at most 1000 bytes (longer appends from concurrent writers can
 # interleave) and never rotates: rotation is done by the Node writers only (IC-015, DEC-019). It is
-# a no-op when no failure home can be resolved (HOME unset, or XDG_CONFIG_HOME relative) and while
-# capture is off (the `off` sentinel file wins; DOFLOW_FAILURE_CAPTURE=off|0|false|no also turns it
-# off). The line carries only names from DoFlow's own tables and the working directory: never an
-# argument, stdin or the environment.
+# a no-op when there is no config home (neither XDG_CONFIG_HOME nor HOME is set to an absolute path;
+# doflow_config_home below, the rule of src/runtime/config-home.ts) and while capture is off
+# (DOFLOW_FAILURE_CAPTURE=off|0|false|no, the `off` sentinel file, or a `failure.capture` value other
+# than "on" in <config home>/settings.json, read by doflow_lex_capture below). The line carries only
+# names from DoFlow's own tables and the working directory: never an argument, stdin or the
+# environment.
 #   capture_failure <command> <kind> <exit status>
 CAPTURE_VERB=""
 
+# BEGIN doflow-config-home v1 (rule: src/runtime/config-home.ts; checked by test/guards/settings.test.js)
+doflow_config_home() {
+  DOFLOW_HOME=""
+  case "${XDG_CONFIG_HOME:-}" in
+    /*) DOFLOW_HOME="${XDG_CONFIG_HOME}/doflow"; return 0 ;;
+    [A-Za-z]:[\\/]*) case "${OSTYPE:-}" in msys*|cygwin*|win32*) DOFLOW_HOME="${XDG_CONFIG_HOME}/doflow"; return 0 ;; esac ;;
+  esac
+  case "${HOME:-}" in
+    /*) DOFLOW_HOME="${HOME}/.config/doflow" ;;
+    [A-Za-z]:[\\/]*) case "${OSTYPE:-}" in msys*|cygwin*|win32*) DOFLOW_HOME="${HOME}/.config/doflow" ;; esac ;;
+  esac
+  return 0
+}
+# END doflow-config-home v1
+
+# BEGIN doflow-settings-lexical v1 (rule: src/runtime/settings/lexical.ts; checked by test/guards/settings.test.js)
+doflow_lex_capture() {
+  local f="${1:-}" text="" rest="" d=""
+  local re='"failure\.capture"[[:space:]]*:[[:space:]]*("[^"]*"|[^,}"[:space:]]*)'
+  DOFLOW_LEX_CAPTURE=""
+  if [ ! -e "$f" ]; then
+    # Missing is no setting, unless the folder holding it cannot be searched (Node: EACCES is off).
+    d="${f%/*}"
+    if [ -n "$d" ] && [ "$d" != "$f" ] && [ -d "$d" ] && [ ! -x "$d" ]; then DOFLOW_LEX_CAPTURE="off"; fi
+    return 0
+  fi
+  if [ ! -f "$f" ] || [ ! -r "$f" ]; then DOFLOW_LEX_CAPTURE="off"; return 0; fi
+  IFS= read -r -d '' text < "$f" || true
+  rest="$text"
+  while [[ $rest =~ $re ]]; do
+    if [ "${BASH_REMATCH[1]}" = '"on"' ]; then DOFLOW_LEX_CAPTURE="${DOFLOW_LEX_CAPTURE:-on}"; else DOFLOW_LEX_CAPTURE="off"; fi
+    rest="${rest#*"${BASH_REMATCH[0]}"}"
+  done
+  return 0
+}
+# END doflow-settings-lexical v1
+
+
 capture_failure_write() {
   local command="${1:-}" kind="${2:-}" status="${3:-}"
   local home="" setting="" version="" candidate="" project="" harness="" at="" line="" cwd="" hp=""
   export LC_ALL=C
 
-  if [ -n "${XDG_CONFIG_HOME:-}" ]; then
-    case "$XDG_CONFIG_HOME" in
-      /*) home="$XDG_CONFIG_HOME/doflow/failures" ;;
-      *) return 0 ;;
-    esac
-  else
-    case "${HOME:-}" in
-      /*) home="$HOME/.config/doflow/failures" ;;
-      *) return 0 ;;
-    esac
-  fi
+  doflow_config_home
+  [ -n "$DOFLOW_HOME" ] || return 0
+  home="$DOFLOW_HOME/failures"
 
   # Case-insensitive, whitespace trimmed at the ends only: the same reading the Node writer has.
   setting="$(printf '%s' "${DOFLOW_FAILURE_CAPTURE:-}" | tr '[:upper:]' '[:lower:]')" || return 0
@@ -62,6 +98,8 @@ capture_failure_write() {
     off|0|false|no) return 0 ;;
   esac
   [ -f "$home/off" ] && return 0
+  doflow_lex_capture "$DOFLOW_HOME/settings.json"
+  [ "$DOFLOW_LEX_CAPTURE" = off ] && return 0
 
   # The command is a verb the dispatcher has already matched against its own tables, or `dispatcher`.
   [[ "$command" =~ ^[a-z][a-z0-9-]{0,39}$ ]] || command="dispatcher"
@@ -114,14 +152,15 @@ capture_failure() {
 
 # After a verb ran: a status outside {0, 1, 2} is a crash worth recording (a signal, a runtime that
 # died), minus what is not DoFlow's fault (DEC-031): 127 (command not found), 130, 141 and 143
-# (interrupted, broken pipe, terminated), task-not-found status 3 of `task-brief`, and overflow
-# status 3 of `context-pack`. A Node crash exits 1 and is recorded by the CLI itself, so it is
+# (interrupted, broken pipe, terminated), task-not-found status 3 of `task-brief`, overflow
+# status 3 of `context-pack`, refused status 3 of `context-emit`, and over-budget status 3 of
+# `context-grant`. A Node crash exits 1 and is recorded by the CLI itself, so it is
 # never counted twice.
 capture_exit_status() {
   local verb="${1:-}" status="${2:-0}"
   case "$status" in
     0|1|2|127|130|141|143) return 0 ;;
-    3) case "$verb" in task-brief|context-pack) return 0 ;; esac ;;
+    3) case "$verb" in task-brief|context-pack|context-emit|context-grant) return 0 ;; esac ;;
   esac
   capture_failure "$verb" "exit-$status" "$status"
   return 0
@@ -165,8 +204,13 @@ resolve_config_dir() {
   dir="$(pwd -P 2>/dev/null || pwd)"
   while [ -n "$dir" ] && [ "$dir" != "/" ]; do
     if [ -d "$dir/.doflow" ]; then
-      printf '%s' "$dir/.doflow"
-      return 0
+      case "$dir/" in
+        */.doflow/*) ;;
+        *)
+          printf '%s' "$dir/.doflow"
+          return 0
+          ;;
+      esac
     fi
     dir="$(dirname "$dir")"
   done
@@ -353,7 +397,9 @@ Workflow and evidence:
   workflow         resolve stages, dependencies and gates for a class
   orchestrate      start/resume a run: complete stages, skip optional ones, decide gates
   research-request  open, list or resolve a feature-stage research question
-  task-attempt     claim, finish, release or read the attempts on a plan's tasks
+  task-attempt     claim, finish, release, start, pause, cancel, resume, inspect, reopen or report-usage on a plan's task attempts
+  worker           discover, probe, describe, select, run, status or cancel an external headless worker on a claimed task
+  dispatch         run a feature's task graph: start, step, run, submit, spawn, pause, inspect, cancel, takeover or resume
   retrieve         BM25 search over the installed guidance tree (auto-refreshing index)
   model-role       resolve an abstract model role to ranked, availability-annotated providers
   route            resolve an information need to a healthy provider
@@ -361,6 +407,8 @@ Workflow and evidence:
   claim            record or update a claim and its support state
   readiness        evaluate readiness; return state and missing items
   context-pack     emit the compiled context pack for a stage
+  context-emit     decide and render one launch, prompt or delta emission (launcher entry)
+  context-grant    grant one compacted summary to a launched run and lineage
   retrieval-plan   declare the needs a stage will resolve, attempt each need, then report every declared item
   outcome          record a task's terminal state with its basis, or show what was recorded
   scaffold         emit the code scaffold the active feature's artifacts imply
@@ -369,6 +417,17 @@ Workflow and evidence:
   lifecycle        overview, init, status, release or merged: follow-ups and feature tracking for the project
   goal             add, check, link, list or close a goal and its checklist
   failure          list, settle or switch off the failures DoFlow captured on this machine
+  roadmap          session-driven autopilot runner: render or status the roadmap table
+  plan-check       check a plan's task lines the way the task-attempt ledger reads them
+  review           validate a feature's review/findings.json, print counts and advisories (review-package assembles the payload)
+  protocol         print the review and debate protocol presets, or the one a run would use (read-only)
+  rules            print the values the runtime owns for this project, each with its source (read-only)
+  primary          resolve which harness and model the main session runs (read-only)
+  fleet            list the projects this machine knows (read-only)
+  transcript       read an agent's recent events, or the project's traffic (read-only)
+  package          list the contribution points a package may fill, check a package directory, list/show packages (read-only), add/update a local package (a plan, then --plan applies it), or enable/disable/trust/exempt/revoke/verify/remove one
+  slot             named machine-wide queue: run a command as its one holder, list or release
+  models           synchronize, list, or inspect observed models across workers (--action sync|list|describe)
 
 Verification and recovery:
   verify           compile the contract, run checks, emit the report
@@ -376,7 +435,7 @@ Verification and recovery:
   leak-scan        report DoFlow-internal identifiers in shipped files
 
 Observability:
-  trace            current run trajectory
+  trace            current run trajectory; trace spans: the span view; trace analyze: its detectors; trace export: OTLP/HTTP export
   stats            aggregate run usage
   indicators       per-stage and per-gate timings from the orchestration record
   discover         missed opportunities in recorded runs
@@ -384,6 +443,7 @@ Observability:
   capabilities     provider resolution
   enforcement      verified lifecycle policy coverage
   doctor           installation and provider health
+  config           list effective settings and their origins
   storage          report stored data and its retention bounds
 EOF
 }
@@ -439,12 +499,23 @@ now_ms() {
 #
 # Tracing never changes what a verb returned. Every step is failure-tolerant and the function
 # always succeeds: an unwritable state directory degrades observability, not the run.
+#
+# Session identity (082 IC-035, DEC-012, DEC-031, DEC-042): `run`, `lineage` and `attempt` come
+# from the environment only, each written quoted when it matches identity.ts's pattern (ERE, held in
+# a variable so `[[ =~ ]]` reads it unquoted, which bash 3.2 supports) and `null` otherwise. A value
+# that passes holds no quote, backslash or control character, so quoting it cannot break the line.
+# `[[ ]]` is a builtin: the trace starts no process beyond `mkdir` and `date` (NFR-007).
 trace_run() {
   local verb="$1" code="$2" duration="$3" argc="$4" started_at="$5"
   local runs_dir="$CONFIG_DIR/state/runs"
+  local id_re='^[A-Za-z0-9][A-Za-z0-9_-]{0,55}$' attempt_re='^[1-9][0-9]{0,3}$'
+  local run_v=null lineage_v=null attempt_v=null
+  if [[ "${DOFLOW_RUN_ID:-}" =~ $id_re && "${DOFLOW_RUN_ID}" != local ]]; then run_v="\"${DOFLOW_RUN_ID}\""; fi
+  if [[ "${DOFLOW_LINEAGE_ID:-}" =~ $id_re ]]; then lineage_v="\"${DOFLOW_LINEAGE_ID}\""; fi
+  if [[ "${DOFLOW_ATTEMPT:-}" =~ $attempt_re ]]; then attempt_v="\"${DOFLOW_ATTEMPT}\""; fi
   mkdir -p "$runs_dir" 2>/dev/null || return 0
-  printf '{"timestamp":"%s","verb":"%s","exit_code":%s,"duration_ms":%s,"arg_count":%s}\n' \
-    "$started_at" "$verb" "$code" "$duration" "$argc" \
+  printf '{"timestamp":"%s","verb":"%s","exit_code":%s,"duration_ms":%s,"arg_count":%s,"run":%s,"lineage":%s,"attempt":%s}\n' \
+    "$started_at" "$verb" "$code" "$duration" "$argc" "$run_v" "$lineage_v" "$attempt_v" \
     >>"$runs_dir/$(date -u +%Y-%m-%d).jsonl" 2>/dev/null || return 0
   return 0
 }
@@ -481,8 +552,8 @@ shell_helper_for() {
 # command list; an unbuilt verb is dispatched and the CLI answers for itself.
 is_node_verb() {
   case "$1" in
-    classify|workflow|route|evidence|claim|readiness|context-pack|retrieval-plan|outcome|scaffold|decision|followup|lifecycle|goal|failure|verify|recover|leak-scan|\
-trace|stats|indicators|discover|inventory|capabilities|enforcement|doctor|orchestrate|research-request|task-attempt|retrieve|model-role|storage|brief-tools|advise) return 0 ;;
+    classify|workflow|route|evidence|claim|readiness|context-pack|context-emit|context-grant|retrieval-plan|outcome|scaffold|decision|followup|lifecycle|goal|failure|verify|recover|leak-scan|\
+trace|stats|indicators|discover|inventory|capabilities|enforcement|doctor|config|orchestrate|research-request|task-attempt|worker|dispatch|retrieve|model-role|storage|brief-tools|advise|roadmap|plan-check|review|protocol|rules|primary|fleet|transcript|package|slot|models) return 0 ;;
     *) return 1 ;;
   esac
 }
@@ -502,7 +573,7 @@ dispatch_shell() {
 
 dispatch_node() {
   local verb="$1"; shift
-  local marker tmpfile rc first_line
+  local marker tmpfile outfile registry_msg rc first_line runtime_root second_line trimmed_second first_val total_errs more
   if ! resolve_node_cli; then
     if marker="$(has_doflow_marker_nearby)"; then
       fail 2 "unlinked-checkout" \
@@ -514,17 +585,40 @@ dispatch_node() {
   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"
-    case "$NODE_CLI_SOURCE" in
-      project-runtime|global-runtime)
+    case "$NODE_CLI_SOURCE:$verb" in
+      # `slot run` streams its command's output and holds the queue for as long as the command
+      # runs, so its stderr is never held back for the stale-runtime check below.
+      *:slot)
+        node "$NODE_CLI_PATH" "$verb" "$@"
+        ;;
+      project-runtime:*|global-runtime:*)
         # These two sources are a *projected copy* of the runtime, not the checkout itself, so
         # they can drift out of sync with the working tree's registry. Stdout still streams
         # directly; only stderr is captured, so a version-drift crash can be told apart from a
         # verb legitimately reporting a finding (e.g. readiness's NEEDS_EVIDENCE) before either
         # reaches the caller.
         tmpfile="$(mktemp)"
-        trap 'rm -f "$tmpfile" 2>/dev/null || true' EXIT
+        outfile=""
+        # `worker` and `dispatch` catch the registry error themselves and, under --json, report it as
+        # a JSON body on stdout (error "registry-invalid") with nothing on stderr; the other verbs let
+        # it reach stderr. Only those two have stdout held back (their --json body is a single
+        # document written at the end), so the same stale-runtime report can be built for them.
+        case "$verb" in
+          worker|dispatch) if [ "$wants_json" = true ]; then outfile="$(mktemp)"; fi ;;
+        esac
+        trap 'rm -f "$tmpfile" "$outfile" 2>/dev/null || true' EXIT
         rc=0
-        node "$NODE_CLI_PATH" "$verb" "$@" 2>"$tmpfile" || rc=$?
+        if [ -n "$outfile" ]; then
+          node "$NODE_CLI_PATH" "$verb" "$@" >"$outfile" 2>"$tmpfile" || rc=$?
+          if [ "$rc" -eq 2 ]; then
+            registry_msg="$(node -e 'try{const o=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));if(o&&o.error==="registry-invalid"&&typeof o.message==="string")process.stdout.write(o.message)}catch{}' "$outfile" 2>/dev/null)" || registry_msg=""
+            if [ -n "$registry_msg" ]; then
+              printf '[ERROR] %s\n' "$registry_msg" >"$tmpfile"
+            fi
+          fi
+        else
+          node "$NODE_CLI_PATH" "$verb" "$@" 2>"$tmpfile" || rc=$?
+        fi
         if [ "$rc" -ne 0 ]; then
           first_line=""
           IFS= read -r first_line <"$tmpfile" || true
@@ -533,13 +627,34 @@ dispatch_node() {
           # anchored match against the registry loader's raw prefix never fires in practice.
           case "$first_line" in
             *"Invalid DoFlow registry:"*)
+              runtime_root="$(dirname "$(dirname "$NODE_CLI_PATH")")"
+              second_line=""
+              {
+                read -r _
+                IFS= read -r second_line || true
+              } <"$tmpfile"
+              second_line="${second_line%$'\r'}"
+              trimmed_second="${second_line#"${second_line%%[![:space:]]*}"}"
+              first_val="${trimmed_second#- }"
+              if [ -z "$first_val" ]; then
+                first_val="${first_line#*Invalid DoFlow registry:}"
+                first_val="${first_val#"${first_val%%[![:space:]]*}"}"
+              fi
+              first_val="${first_val%$'\r'}"
+              total_errs="$(grep -c '^[[:space:]]*- ' "$tmpfile" || true)"
+              case "$total_errs" in *[!0-9]*|"") total_errs=0 ;; esac
+              more=""
+              if [ "$total_errs" -gt 1 ]; then
+                more=" ($(( total_errs - 1 )) more)"
+              fi
               fail 2 "stale-runtime" \
-                "verb '$verb' failed against $NODE_CLI_PATH, which appears out of date relative to the working checkout; reinstall or re-run the doflow installer to refresh it"
+                "verb '$verb' failed: the registry at $runtime_root/core/registry is invalid: $first_val$more; reinstall DoFlow if this runtime was projected from another version"
               ;;
           esac
         fi
+        if [ -n "$outfile" ]; then cat "$outfile"; fi
         cat "$tmpfile" >&2
-        rm -f "$tmpfile"
+        rm -f "$tmpfile" "$outfile"
         trap - EXIT
         return "$rc"
         ;;

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

@@ -18,7 +18,7 @@ Universal command dispatcher, task decomposer, capability router, and developmen
 
 1. **Session & Command Dispatch**:
    - If invoked with no arguments or `--help`, announce DoFlow session status and display the core command reference.
-   - If `$1` matches a known `/do-*` skill (`do-flow`, `do-brainstorm`, `do-design`, `do-plan`, `do-execute-plan`, `do-test`, `do-code-review`, `do-git`, `do-constitution`, `do-diagnose`, `do-document`, `do-implement`), forward to that skill directly.
+   - If `$1` matches a `/do-*` skill in the Core Command Reference table below, forward to that skill directly.
    - Otherwise, resolve the runtime seam **once** and reuse `$DOFLOW` for every later call here:
 
 ```bash
@@ -38,14 +38,18 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      `doflow-run lifecycle --action overview --maintain --since T --json` (`doflow-run` is the
      `$DOFLOW` resolved above), and settle each pending item with the question tool through the
      `doflow-run followup`, `doflow-run goal` or `doflow-run failure` command its `next` lines give.
+     Advice on a follow-up: `references/advice_calls.md`, followup-triage.
      Rerun with the same `--since T` until nothing is pending. A product problem the user reports
      goes to `doflow-run followup --action report`; a large goal they state, to
      `doflow-run goal --action add`. It edits no source file.
+   - `/do program <goal>`, or an ask larger than one feature: follow `references/program_mode.md`, researching per
+     `../do-document/references/deep_research.md` at the tiers the guidance tree's `references/MODEL_SELECTION.md` gives.
+   - `/do package <idea>` or "make this a DoFlow extension/package/plugin": run `"$DOFLOW" package --action points --json`; stop if a needed point is not open. Ask up to 3 questions (what/why, id, points) via the question tool; run `"$DOFLOW" package --action new --id <id> --points <point[:local],...>`; follow `next` lines. No evidence batch; never write `grants.jsonl`, add remote sources or create a feature folder.
 
 2. **Multi-Part / Ambiguous Request Routing (`--depth`)**:
    - When a request bundles 2+ unrelated asks across different files or domains, verify referenced files exist first.
    - Decompose into independent or sequenced work packages, then propose **one task class per
-     package** and let the runtime validate each: `"$DOFLOW" classify --task-class "<proposed>" --calling-skill do [--request <shell-escaped argument> | --request-file <file>] --json`. Prefer `--request-file`: create a temporary UTF-8 file with `mktemp`, write the verbatim request as the body of a single-quoted heredoc whose delimiter does not occur on any request line, pass only its path, and install cleanup traps plus explicit removal. Never interpolate raw request text into a shell command or word; use `--request` only as one safely shell-escaped argument, and omit the optional opinion if safe transport is unavailable. The flags are mutually exclusive.
+     package** and let the runtime validate each: `"$DOFLOW" classify --task-class "<proposed>" --calling-skill do (--request-file <file> | --request <shell-escaped argument>) --json`. Always pass the request. Prefer `--request-file`: create a temporary UTF-8 file with `mktemp`, write the verbatim request as the body of a single-quoted heredoc whose delimiter does not occur on any request line, pass only its path, and install cleanup traps plus explicit removal. Never interpolate raw request text into a shell command or word; use `--request` only as one safely shell-escaped argument, and omit the optional opinion if safe transport is unavailable. The flags are mutually exclusive.
 
      When the JSON carries `secondOpinion.status: "answered"` with `agrees: false`, tell the user the decision model picked a different class, in one line naming both; the verdict stands, and no other action follows from it.
 
@@ -64,17 +68,14 @@ Route each package to the accepted workflow's first stage. A workflow whose `sta
 that does the package's work is a misclassification — re-propose the class rather than routing the
 package under one the runtime accepted for a different kind of task.
 
+   Advice on a worker's tier: `references/advice_calls.md`, tier.
+
    - For detailed decomposition and dependency graph formatting, consult this skill's own
-     `references/pm_routing.md`.
+     `references/pm_routing.md`; before dispatching agents, read the guidance tree's
+     `references/ORCHESTRATION.md` and `references/MODEL_SELECTION.md`.
 
 3. **Capability & Tool Selection**:
-   - Before routing, check what recorded runs already show — run `"$DOFLOW" discover --json`
-     (reuse `$DOFLOW` resolved in step 1). **It exits 1 when there is a finding — that is signal,
-     not failure; never treat that exit code as an error.** When the analysis cannot be settled
-     from the recorded metadata, `discover` reports `UNKNOWN` rather than "clear"; surface `UNKNOWN`
-     as undetermined and never round it up to "no missed opportunities". `do` surfaces the finding
-     to the user — it takes no automatic action on it, and no finding is ever rendered as a number,
-     a percentage, or a confidence.
+   - Before routing, run `"$DOFLOW" discover --json` to check recorded runs. Exit 1 signals a finding, not an error. When metadata cannot settle the analysis, surface `UNKNOWN` as undetermined, never clear. Show findings to the user; take no automatic action. Never render findings as a number, percentage or confidence.
    - Routing an information need to a tool is unconditional, not a mode this skill can be asked
      for: whenever a search, graph, or testing need arises, query the Capability Router — run `"$DOFLOW" capabilities` (add `--json` to parse, `--check` for a deep
      smoke check), or `"$DOFLOW" route --intent <intent> --json` to resolve one need end to end. It
@@ -82,6 +83,7 @@ package under one the runtime accepted for a different kind of task.
      Ripgrep when absent, and a static table cannot know that.
    - Consult this skill's own `references/tool_matrix.md` for the intent→capability map and the two
      fallback layers. Treat the router's output as authoritative when the two disagree.
+   - Advice on an MCP server's trigger: `references/advice_calls.md`, mcp-need.
 
 4. **Scope & Effort Estimation (`--estimate`)**:
    - When asked for sizing, complexity, or timeline estimates, produce a range anchored against git history and file scope, stating the assumptions that set its width and the unknowns that would narrow it. Never attach a numeric or percentage certainty to the range — the assumptions are the honest expression of what is not yet known.

package/core/shared/skills/do/references/advice_calls.md

@@ -0,0 +1,26 @@
+# Advice calls
+
+Optional. Skip a call and its outcome call unless `status` is `answered`; on `agrees: false` say so in one line and keep your judgement. `classify` asks `task-class` itself.
+
+## tier
+
+```bash
+"$DOFLOW" advise --kind tier --state "<the package>" --static "<light|standard|frontier>" --task-id "<task id>" --json
+"$DOFLOW" advise --action outcome --pick-id "<pickId>" --actual "<tier used>"
+```
+
+## mcp-need
+
+```bash
+"$DOFLOW" advise --kind mcp-need --server <id> --state "<the stage>" --static <yes|no> --task-id "<task id>" --json
+"$DOFLOW" advise --action outcome --pick-id "<pickId>" --actual "<yes|no: server used>"
+```
+
+## followup-triage
+
+No `--static`; the pick is input to the question.
+
+```bash
+"$DOFLOW" advise --kind followup-triage --state "<its text>" --task-id "<its id>" --json
+"$DOFLOW" advise --action outcome --pick-id "<pickId>" --actual "<now|later|dismiss>"
+```

package/core/shared/skills/do/references/pm_routing.md

@@ -7,8 +7,7 @@ Decomposition depth guidelines when `/do` processes multi-part, cross-domain req
   Produce a flat table: Part | Domain | Target Skill / Agent | Completion Gate
 - `--depth normal` (Shared context or sequence dependencies):
   Produce the shallow table plus an explicit dependency check (e.g., API contract before UI binding).
-- `--depth deep` (Multi-service / complex initiatives):
-  Full Epic $\rightarrow$ Story $\rightarrow$ Task hierarchy ready for `/do-plan`.
+- `--depth deep` (programme-sized: more than one feature): program mode, `program_mode.md`.
 
 ## Delegation Matrix
 - Feature discovery $\rightarrow$ `/do-brainstorm`

package/core/shared/skills/do/references/program_mode.md

@@ -0,0 +1,31 @@
+# Program mode
+
+For an ask larger than one feature: research, offer roadmap shapes, hand over a checked draft. It
+writes no roadmap row and edits no source.
+
+1. **Enter.** `/do program <goal>` enters. An ask naming more than one independently shippable
+   outcome may enter: name the signal in one line and ask with the question tool (program mode
+   first, "one feature" second) before any research. Anything else routes as before.
+2. **Contract.** Write the sub-questions the roadmap needs (users, scope edges, existing surfaces,
+   ordering risks), at most 6. Task id: `program-<kebab-of-goal>`.
+3. **Research.** One broad round over the whole goal, then one targeted round per sub-question, per
+   `../do-document/references/deep_research.md` (no report file), at most 6 sources each. Run
+   independent sub-questions as parallel subagents where the harness has them, else in turn, at the
+   tier the guidance tree's `references/MODEL_SELECTION.md` gives: `light` to scout or extract,
+   `standard` to research, `frontier` to judge and pick shapes. Mark each finding sourced (with its
+   locator) or inferred. Stop when every sub-question has an answer or a stated gap and the last
+   round added nothing; report the gaps. Record one evidence batch and one claim per conclusion
+   under this task id with SKILL.md step 5's commands, per the guidance tree's
+   `references/EVIDENCE_LEDGER.md`.
+4. **Shapes.** Offer two or three roadmap shapes through the question tool, recommended first: rows
+   in outline, order and the main trade-off. One viable shape: say why the others fell.
+5. **Draft.** Write the chosen shape as `{"schema":1,"rows":[...]}`: per row `id`, `slug`, `title`,
+   `class`, `needs`, a rough `writeSet`, one-line `intent`, at most 8 `acceptance` lines; nothing a
+   row's own chain decides later. New rows go to `agent-docs/roadmap/draft.json` with ids above the
+   store's highest; changes to rows not started go to `agent-docs/roadmap/draft-amend.json`. Ask
+   before overwriting either file.
+6. **Check.** Run `"$DOFLOW" roadmap seed --action check --draft <path> --json` per draft. Fix the
+   findings and re-check, at most 3 times; every row of a draft must carry the same `change`. Show
+   the result line, overlaps, `alone` rows and gaps. A draft with findings is not ready.
+7. **Hand over.** Show the person the `land` command `check` printed and stop. Landing is the
+   person's act: never run it, and never hand it to a subagent, a policy or autopilot.

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

@@ -18,23 +18,8 @@ session-end without a separate save step.
 /do-brainstorm [topic/idea] [--intent <path>] [--depth shallow|normal|deep]
 ```
 
-**`--intent <path>`** seeds this stage from a pre-branch intent. An intent lives at
-`agent-docs/intent/<kebab-description>.md`, outside the branch-coupled tree, and is written before any
-branch or feature exists — so it is the one input this skill may be given that did not come from the
-conversation. When the flag is present:
-
-- Read the file. Carry its Problem, Proposed outcome, Affected and Constraints into the requirement you
-  write, in §1, §2 and §4 respectively. Treat its **Open questions** as ambiguities for step 3's
-  clarification loop — they are the originator saying what they did not know, not answers to fold in.
-- Fill `requirement.md`'s `**Intent:**` header field with the path you read, so a reader can see where
-  the problem statement came from and judge whether it was reinterpreted.
-- Never move, rename, delete or rewrite the intent. It records what was asked; `requirement.md` records
-  what the project decided to do about it, and the two are allowed to diverge.
-- A path that does not exist is a mistake, not an absence: say so and stop, rather than proceeding as
-  though no intent had been named.
-
-Without the flag, nothing below changes and no intent is owed — discovery starting from a conversation
-alone is the ordinary case.
+**`--intent <path>`** seeds this stage from a pre-branch intent at `agent-docs/intent/`. When the flag is
+present, read `references/intent_seed.md` before step 1. Without the flag, no intent is owed.
 
 ## Behavioral Flow
 
@@ -63,7 +48,7 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
    If `feature_slug` is `null` **and** `candidate_slugs` is non-empty (a non-git root — e.g.
    doflow installed at a multi-service container root — with 2+ `agent-docs/doflow/` feature dirs
    and no branch to disambiguate), this is NOT "no active feature" — it's an unresolved choice.
-   Ask via `AskUserQuestion`, one option per `candidate_slugs` entry, before continuing to step 3;
+   Ask via the question tool, one option per `candidate_slugs` entry, before continuing to step 3;
    never fall through to step 4's fresh-feature path on an ambiguous result, that would create a
    duplicate feature dir. Re-resolve with `"$DOFLOW" paths --json --slug="<chosen>"` and
    use that slug for the rest of this flow. If `/do-flow` already disambiguated and is invoking this skill
@@ -99,30 +84,22 @@ workflow never reads.
      fact → verify it per `MCP_Context7.md`, read-only, never a tech choice.
    - MCP `sequential-thinking`: a round's open ambiguity spans 2+ components, actors or FRs →
      reason it per `MCP_Sequential.md`.
-   After each dialogue round, before moving to the next round, partition any ambiguities
-   surfaced that round into: *independent* ones (answerable without knowing another's answer) —
-   up to 4 — batched into one `AskUserQuestion` call (the tool's 4-question max); *dependent*
-   ones (whose options depend on a prior answer) — asked as their own individual `AskUserQuestion`
-   call, in dependency order, after the dependency resolves; never batched with something it
-   depends on. Every question built for this loop MUST include an explicit "Decide for me" choice
-   among its listed options (on top of the tool's automatic "Other" free-text escape), so the
-   defer path below is actually selectable. Any question where the user picks that "Decide for
-   me" option (distinct from the general "Other" free-text escape) resolves via a recorded
-   assumption rather than by re-prompting — see Step 5 for where that assumption is recorded.
+   After each dialogue round, partition surfaced ambiguities into: *independent* ones (answerable
+   without knowing another's answer) — up to 4 batched into one question-tool call (the tool's 4-question max);
+   *dependent* ones — asked individually in dependency order after the prior answer resolves.
+   Every question must include an explicit "Decide for me" choice (on top of "Other" free-text escape);
+   picking it resolves via a recorded assumption (see Step 5).
+
+### Structured Multiple-Choice Format
+When asking clarifying questions:
+- Use structured multiple-choice options — never bury free-form questions in prose.
+- Present 2–4 meaningful, mutually-exclusive options covering the realistic scenarios.
+- Lead with the recommended default choice; provide an "Other" free-text escape as the final choice.
+
 **Stop when** every ambiguity the contract names has an answer or a stated gap, **and** the last round produced no new ambiguity. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing.
    The loop's posture — how deep to question, what a round is for — is the Behavioral Posture read
    below, not a second rule stated here.
-   **Log each round.** One file per round, never appended to a prior round's file:
-   `agent-docs/doflow/<slug>/intention/brainstorm-<NN>-question.md`, shaped by
-   `templates/doflow/question-log-template.md` (same install path resolution as the requirement
-   template in step 5) — every question as asked, the options offered, and the answer given, with a
-   "Decide for me" pick recorded as the assumption it becomes rather than as an answer. `<NN>` is
-   zero-padded to two digits and starts at step 1's `intention_next_round` — never hand-counted:
-   the resolver already scanned the subdir, and this session's second round is that value plus one,
-   its third plus two. Write the round's file as soon as its answers land, `mkdir -p` the
-   `intention/` directory first. If `feature_slug` was still null at step 1 (a trunk branch with no
-   feature picked yet), there is no directory to write into until step 4 resolves one — hold the
-   rounds and write them all, in round order, immediately after step 4's `mkdir`.
+   **Log each round** to its own file, per `references/round_log.md`: read it before the first round ends.
 4. **Pick the feature** — if `feature_slug` is non-null (branch-derived, auto-selected from a
    single non-git candidate, or resolved via step 1's disambiguation), use it. If still null
    (genuinely no active feature: trunk branch, or a non-git root with zero existing feature dirs),
@@ -156,7 +133,7 @@ The template is `templates/doflow/requirement-template.md` in the install step 1
    with a one-line rationale.
    The `[NEEDS CLARIFICATION]` marker syntax remains only as a fallback for a session aborted
    mid-loop, not for a completed artifact. Populate the `**Ticket:**` header field only if the user
-   referenced a PBI/epic/ticket ID during the dialogue (confirm the exact ID via `AskUserQuestion`
+   referenced a PBI/epic/ticket ID during the dialogue (confirm the exact ID via the question tool
    if it was ambiguous) — otherwise write `none`; do not add a new forced question to every
    brainstorm session just to fill this field.
 Structure the artifact per the guidance tree's `references/ARTIFACT_FORMAT.md` — read it before filling the template; it names which of this artifact's sections take an index-then-detail table.
@@ -189,39 +166,8 @@ Item schema, provenance rules, and the refused-field list: the guidance tree's `
    "$DOFLOW" orchestrate --action handoff --task-id "<slug>" --task-class "<class>" --calling-skill do-brainstorm --note "<requirement path written; §7 marker count>" --mcp-outcome "context7=<outcome>" --mcp-outcome "sequential-thinking=<outcome>" --json
    ```
    `<slug>` is step 1's `feature_slug`; `<class>` is step 2's accepted class.
-   Branch on the response's `disposition`, not the exit code:
-   - **`completed`** — this stage was recorded normally; check `awaitingGate` below.
-   - **`annotated`** — this stage was already recorded on an earlier run of this skill (a
-     re-invocation to amend `requirement.md`, say); the rerun note was appended, no gate to recheck.
-   - **`deferred`** — a gate ahead of this stage, an unfinished mutating stage, or a rejected run
-     prevented the handoff. Discovery is the chain's first stage, so nothing before it can open a
-     gate; report `reason` plainly and stop rather than resolving something that is not this
-     stage's.
-   - **`standalone`** — no workflow applies; there is nothing further to record here.
-
-   Then the gate anchored to this stage, read directly off the same response rather than re-derived
-   from `workflow.gates[]`. A non-null `awaitingGate` carries the `gateId`, `name` and `prompt`
-   (`gate-0`, "Unresolved clarifications", in the `feature` workflow); a null one means no gate
-   follows this stage in this workflow and there is nothing to decide. `gate-0` is
-   `clarification`-kind and its `unresolved-clarifications` trigger is exactly what step 9 already
-   checks — so this stage resolves it rather than leaving a mechanically-answerable gate for a
-   human. When §7 genuinely carries zero markers, approve it plainly — this is the routine path,
-   never a forced one:
-   ```bash
-   "$DOFLOW" orchestrate --action decide-gate --task-id "<slug>" --gate "<awaitingGate.gateId>" --decision approve --note "requirement.md §7 carries zero markers" --json
-   ```
-   In the rare aborted-session case where markers remain, do **not** decide the gate at all: leave
-   the run `AWAITING_GATE` and say so — resolving it is a human's call, and approving it anyway
-   would be a forced override this stage has no reason to make. Finish by rendering the trail. The
-   `--slug` value attaches with an `=`; a space-separated one is rejected with an error rather than
-   silently rendering the wrong feature's trail:
-   ```bash
-   "$DOFLOW" render-audit --slug="<slug>" --json
-   ```
-   Every call in this step is advisory to the trail, not to the artifact. If one fails for a reason
-   outside this flow's control (an unwritable local state directory, say), report the failure plainly and
-   continue — a missing `audit.md` entry degrades the record, it does not make `requirement.md`
-   wrong. None of these calls is a gate on finishing this skill.
+   Then read `references/handoff_branches.md` and branch on `disposition` and `awaitingGate` as it says;
+   every call in this step is advisory to the trail.
 9. **Stop** — report the requirement path and confirmation that §7 has zero remaining
    `[NEEDS CLARIFICATION]` markers (or, in the rare aborted-session case, whatever markers remain).
 
@@ -233,7 +179,7 @@ so skipping the read silently drops the posture it defines.
 
 ## Embedded feature research
 
-For an external fact gap or explicit request, follow the conditional protocol in `../do-document/references/embedded-research.md` before stage completion.
+Run the ideation pass of `../do-document/references/embedded-research.md` before the first question round and its gap-or-request protocol on a gap; a skip says `ideation: skipped (<reason>)` at handoff.
 
 ## Boundaries
 **Will:** propose a task class and have the runtime validate it, run Socratic discovery, log each

package/core/shared/skills/do-brainstorm/references/handoff_branches.md

@@ -0,0 +1,35 @@
+# Step 8: branching on the handoff
+
+Steps named here are SKILL.md's.
+
+Branch on the response's `disposition`, not the exit code:
+- **`completed`** — this stage was recorded normally; check `awaitingGate` below.
+- **`annotated`** — this stage was already recorded on an earlier run of this skill (a
+  re-invocation to amend `requirement.md`, say); the rerun note was appended, no gate to recheck.
+- **`deferred`** — a gate ahead of this stage, an unfinished mutating stage, or a rejected run
+  prevented the handoff. Discovery is the chain's first stage, so nothing before it can open a
+  gate; report `reason` plainly and stop rather than resolving something that is not this
+  stage's.
+- **`standalone`** — no workflow applies; there is nothing further to record here.
+
+Then the gate anchored to this stage, read directly off the same response rather than re-derived
+from `workflow.gates[]`. A non-null `awaitingGate` carries the `gateId`, `name` and `prompt`
+(`gate-0`, "Unresolved clarifications", in the `feature` workflow); a null one means no gate
+follows this stage in this workflow and there is nothing to decide. `gate-0` is
+`clarification`-kind and its `unresolved-clarifications` trigger is exactly what step 9 already
+checks — so this stage resolves it rather than leaving a mechanically-answerable gate for a
+human. When §7 genuinely carries zero markers, approve it plainly — this is the routine path,
+never a forced one:
+```bash
+"$DOFLOW" orchestrate --action decide-gate --task-id "<slug>" --gate "<awaitingGate.gateId>" --decision approve --note "requirement.md §7 carries zero markers" --json
+```
+In the rare aborted-session case where markers remain, do **not** decide the gate at all: leave
+the run `AWAITING_GATE` and say so — resolving it is a human's call, and approving it anyway
+would be a forced override this stage has no reason to make. Finish by rendering the trail. The
+`--slug` value attaches with an `=`; a space-separated one is rejected with an error rather than
+silently rendering the wrong feature's trail:
+```bash
+"$DOFLOW" render-audit --slug="<slug>" --json
+```
+Every call in this step is advisory to the trail. If one fails, report it plainly and continue;
+trail logging issues do not invalidate `requirement.md` or block finishing this skill.