@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

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,14 +407,30 @@ 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
   decision         register, list or compact the active feature's decisions
+  intake           sort, preview, undo, list or file prompt text for the feature's additional-context folder
   followup         record, list, take, settle, promote or report what a feature left unfinished
   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)
+  worktree         remove a merged feature's worktree and branch, never by force (--action cleanup --slug <slug>)
+  attendance       say whether a person is watching a stage (read-only; --task-id <slug> [--run <id>])
 
 Verification and recovery:
   verify           compile the contract, run checks, emit the report
@@ -376,7 +438,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 +446,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 +502,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 +555,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|intake|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|worktree|attendance) return 0 ;;
     *) return 1 ;;
   esac
 }
@@ -502,7 +576,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 +588,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 +630,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
@@ -35,21 +35,25 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
 ```
 
    - `/do maintain` (`$1` is `maintain`): note the start time `T`, run
-     `doflow-run lifecycle --action overview --maintain --since T --json` (`doflow-run` is the
+     `doflow-run lifecycle --action overview --maintain --since T --view brief --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>) --view brief --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.
 
-Branch on the returned `outcome` field, not the exit code.
+Branch on `outcome`, not the exit code.
 - **`ACCEPTED`** — the returned `workflow` is this run's plan of record; read `stages`, `gates` and `handoff` off it rather than from memory.
 - **`REJECTED`** — **stop.** Print `message` verbatim (it already names `validClasses` and any `suggestions`), ask the user to choose from `validClasses`, then re-validate. Never substitute `feature`.
   A rejection may be about **you** rather than the class (`reason: caller-not-a-stage`). Then the fix is to propose one of the classes in `fit.hostingClasses`, or to hand the work to the skill this class names for the stage you meant — not to re-propose the same class.
@@ -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.