@mmerterden/multi-agent-pipeline 17.3.0 → 17.5.0

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -17,9 +17,10 @@
  *
  * v16.0.0 removed the four dev-* modes. Depth is no longer a command name: the
  * Phase 0 Step 7.5 picker asks Full or Short and sets `state.onlyDevelop`. That
- * answer arrives long after the tracker boots at Step -1, so a Short run
- * registers its full set and flips Phases 1 and 2 to `skipped` when it learns.
- * A generated phase set is therefore per-COMMAND, never per-depth.
+ * answer arrives long after the tracker boots at Step -1, so v17.5.0 splits
+ * registration for the two modes that ask it (`full`, `local`): Phase 0 at Step -1,
+ * the rest once depth has named them. Everything else still registers its whole
+ * set up front, and a generated phase set is per-COMMAND, never per-depth.
  *
  * Companion smoke `smoke-mode-dispatch-drift.sh` regenerates the section for
  * each mode file, diffs against the on-disk content, and fails on drift.
@@ -60,10 +61,10 @@ const PHASE_NAMES_NO_TEST = PHASE_NAMES.filter((p) => p !== "5:Test");
  */
 const MODES = {
   autopilot: { phases: PHASE_NAMES_NO_TEST, local: false, autopilot: true },
-  full: { phases: PHASE_NAMES, local: false, autopilot: false },
-  local: { phases: PHASE_NAMES_NO_TEST, local: true, autopilot: false },
+  full: { phases: PHASE_NAMES, local: false, autopilot: false, depth: true },
+  local: { phases: PHASE_NAMES_NO_TEST, local: true, autopilot: false, depth: true },
   "local-autopilot": { phases: PHASE_NAMES_NO_TEST, local: true, autopilot: true },
-  "full-local": { phases: PHASE_NAMES_NO_TEST, local: true, autopilot: false },
+  "full-local": { phases: PHASE_NAMES_NO_TEST, local: true, autopilot: false, depth: true },
   // Analysis produces a document, not code: no Dev, no Test, and Phase 6
   // publishes instead of committing. Same 8-phase contract, four of them
   // reinterpreted.
@@ -81,8 +82,6 @@ if (!spec) {
   process.exit(2);
 }
 
-const phaseLoop = spec.phases.map((p) => `"${p}"`).join(" ");
-
 const ALL_PHASE_IDS = PHASE_NAMES.map((p) => p.split(":")[0]);
 const activeIds = spec.phases.map((p) => p.split(":")[0]);
 const skippedIds = ALL_PHASE_IDS.filter((id) => !activeIds.includes(id));
@@ -104,7 +103,7 @@ const skipNote =
     ? `${modeLabel} mode does NOT TaskCreate phases ${skippedIds.join("/")}  -  those are not part of the ${modeLabel} phase set (\`${spec.phases.join(" ")}\`). Only register tiles for the active set.`
     : `${modeLabel} mode TaskCreates all 8 phases (no phase is skipped).`;
 
-const orderingNote = `**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For ${modeLabel} that means: ${phaseSequence}. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".`;
+const orderingNote = `**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For ${modeLabel} that means: ${spec.depth ? `Phase 0 at Step -1, then the rest in ascending order at Step 7.5 (${phaseSequence} minus whatever the depth answer drops)` : phaseSequence}. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".`;
 
 const localCaveat = spec.local
   ? `\n> **Local mode:** no worktree is created, work happens on the current branch. Phase 0 Init still calls \`init\`  -  the \`--local\` flag is stored in tracker-state.json, and \`:resume\` restores the correct CWD.\n`
@@ -114,6 +113,32 @@ const banner = spec.autopilot
   ? `\n> **Autopilot mode:** user confirmations are skipped. The tracker is still mandatory  -  autopilot agent calls cannot skip it; skipping breaks \`smoke-tracker-contract.sh\`.\n`
   : "";
 
+// Registration shape. A mode that asks the depth question does not know its phase
+// set at Step -1 (the answer needs taskType, which needs the fetched issue and the
+// branch), so it registers Phase 0 there and the rest at Step 7.5. Drawing eight
+// tiles beside the question that decides whether two of them run is the failure this
+// split exists to remove.
+const fullSet = spec.phases.filter((p) => p !== "0:Init");
+const shortSet = fullSet.filter((p) => Number(p.split(":")[0]) >= 3);
+const loopFor = (list) =>
+  `for p in ${list.map((x) => `"${x}"`).join(" ")}; do\n  bash $HOME/.claude/scripts/phase-tracker.sh add "\${p%%:*}" "\${p#*:}"\ndone`;
+
+const initLoop = spec.depth
+  ? 'bash $HOME/.claude/scripts/phase-tracker.sh add 0 "Init"\nbash $HOME/.claude/scripts/phase-tracker.sh tiles'
+  : `${loopFor(spec.phases)}`;
+
+const deferredBlock = spec.depth
+  ? `
+# Phase 0 Step 7.5, immediately after the depth answer - the first moment this
+# mode knows its phase set. Full:
+${loopFor(fullSet)}
+# Short (Analysis and Planning are not run, so they get no tile at all):
+${loopFor(shortSet)}
+# Then the widget, narrowed to the phases that do not have a tile yet:
+bash $HOME/.claude/scripts/phase-tracker.sh tiles --new
+`
+  : "";
+
 const out = `## Required: Phase Tracker Contract
 
 **The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [\`$HOME/.claude/multi-agent-refs/tracker-contract.md\`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
@@ -126,11 +151,9 @@ Two channels run in parallel at every phase boundary:
 \`\`\`bash
 # Phase 0, very first shell call (every CLI):
 bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
-for p in ${phaseLoop}; do
-  bash $HOME/.claude/scripts/phase-tracker.sh add "\${p%%:*}" "\${p#*:}"
-done
+${initLoop}
 bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
-
+${deferredBlock}
 # Every phase boundary (every CLI):
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
@@ -142,11 +165,11 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. \`1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐\`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered.${spec.depth ? " This mode registers in two batches (Step -1, then Step 7.5), so `tiles --new` narrows the second one and the Phase 0 tile is never created twice." : ""} The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. \`1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐\`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".
 
 \`\`\`text
-# Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
-for each phase in ${spec.phases.join(", ")}:
+# Register one tile per phase, capture the taskId, persist it:
+for each phase in ${spec.depth ? `0:Init at Step -1, then ${fullSet.join(", ")} (Full) or ${shortSet.join(", ")} (Short) at Step 7.5` : spec.phases.join(", ")}:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
   bash $HOME/.claude/scripts/phase-tracker.sh meta <N> tasklist_id "<taskId>"

package/pipeline/scripts/git-path.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * @file git-path.mjs  -  undo git's C-style path quoting, in one place.
+ *
+ * With `core.quotePath` on (the default), git quotes any path containing a
+ * non-ASCII byte or an unusual character: a Turkish filename comes out of
+ * `diff --name-only` as `"G\303\266r\303\274n\303\274m.swift"`, quotes and all.
+ * A consumer that treats that string as a path sees a name that matches no
+ * glob, resolves to no file, and simply DISAPPEARS from whatever it was
+ * feeding - which is how every non-ASCII-named file was once silently dropped
+ * from risk scoring.
+ *
+ * Shared rather than copied because the failure is silent on every axis that
+ * uses it: a dropped file is not an error anywhere, it is an absence.
+ *
+ * @module pipeline/scripts/git-path
+ */
+
+/**
+ * Reverse git's C-style quoting: octal byte escapes (`\NNN`, one per raw byte,
+ * so a multi-byte UTF-8 character is several consecutive triplets) plus the
+ * standard `\\ \" \t \n \r` escapes.
+ *
+ * @param {string} s the INNER text, without the surrounding quotes
+ * @returns {string}
+ */
+export function unquoteGitPath(s) {
+  const bytes = [];
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\") {
+      const octal = s.slice(i + 1, i + 4);
+      if (/^[0-7]{3}$/.test(octal)) {
+        bytes.push(parseInt(octal, 8));
+        i += 3;
+        continue;
+      }
+      const simple = { "\\": 92, '"': 34, t: 9, n: 10, r: 13 };
+      const next = s[i + 1];
+      if (next in simple) {
+        bytes.push(simple[next]);
+        i += 1;
+        continue;
+      }
+    }
+    bytes.push(s.charCodeAt(i));
+  }
+  return Buffer.from(bytes).toString("utf-8");
+}
+
+/**
+ * Unquote a path only if git actually quoted it. An unquoted path is returned
+ * untouched, so this is safe to run over every line of any git path listing.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function unquotePathIfNeeded(s) {
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    return unquoteGitPath(s.slice(1, -1));
+  }
+  return s;
+}

package/pipeline/scripts/glob-match.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * @file glob-match.mjs  -  the one glob matcher, so two denominators cannot drift.
+ *
+ * `skill-conformance.mjs` matches a changed file against a rule's declared
+ * scope; `review-file-filter.mjs` matches the same file against the exclusion
+ * list. Those two answers decide what is reviewed and what it was measured
+ * against, so a second implementation is not a duplication of code but a
+ * duplication of MEANING: the day they disagree, a file is excluded from the
+ * review and still counted in the conformance denominator, and nothing says so.
+ *
+ * Deliberately minimal - the `**\/x`, `*.ext`, `dir/**` shapes the pattern
+ * lists actually use. No brace expansion, no extglob, no character classes: a
+ * pattern that needs them belongs in a list nobody can read either.
+ *
+ * @module pipeline/scripts/glob-match
+ */
+
+/**
+ * Compile a glob to an anchored RegExp.
+ *
+ * `**` followed by `/` matches zero or more path segments, so `**\/x` matches
+ * a bare `x` at the root as well as `a/b/x`. A bare `*` never crosses `/`.
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+export function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        if (glob[i + 2] === "/") {
+          re += "(?:.*/)?";
+          i += 2;
+        } else {
+          re += ".*";
+          i += 1;
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") re += "[^/]";
+    else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * True when `file` matches any glob, or when the list is empty - an unscoped
+ * rule applies everywhere.
+ *
+ * @param {string} file
+ * @param {string[]} globs
+ * @returns {boolean}
+ */
+export function matchesAnyGlob(file, globs) {
+  if (!globs || globs.length === 0) return true;
+  return globs.some((g) => globToRegExp(g).test(file));
+}

package/pipeline/scripts/graph-mermaid.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-mermaid.mjs  -  draw the blast radius that was already measured.
+ *
+ * The PR body's Impact Analysis asks, in part 3, which symbols and files a
+ * change reaches. `graph-affected.mjs` answers exactly that question
+ * deterministically, from a graph pinned to a commit - and until now the answer
+ * was re-typed as prose by a model while the measurement sat unused on disk.
+ *
+ * This emits the same answer as a mermaid `flowchart`. Mermaid because GitHub
+ * renders it natively in pull requests, issues and markdown files, so the
+ * diagram costs no renderer, no plugin and no dependency: the output is text.
+ * Jira is deliberately NOT a target - its wiki renderer turns a mermaid fence
+ * into a literal `{code:mermaid}` block, so a diagram there is worse than the
+ * prose it replaced.
+ *
+ * Traversal is not reimplemented here. `findByName` and `affected` come from
+ * graph-affected.mjs, so the diagram and the text report can never disagree
+ * about what is affected - they are the same call.
+ *
+ * Inputs:
+ *   "<symbol>"          Symbol name; comma-separate for several seeds. Required.
+ *   --graph <path>      Graph file. Default: the same default graph-query uses
+ *   --depth N           Reverse traversal depth. Default: 2
+ *   --kind K[,K]        Restrict to these edge kinds
+ *   --max-nodes N       Node ceiling. Default: 25
+ *   --direction LR|TD   Flowchart direction. Default: LR
+ *   --json              Emit {mermaid, nodes, edges, truncated, baseCommit}
+ *
+ * Exit codes (same family as graph-affected.mjs, on purpose):
+ *   0   -  drawn, possibly with nothing affected
+ *   1   -  graph missing or unreadable; the reason goes to stderr and the
+ *          caller records it as a gap rather than inventing a diagram
+ *   64  -  usage error
+ *
+ * @module pipeline/scripts/graph-mermaid
+ */
+
+import { resolve } from "node:path";
+import { parseFlags } from "./graph-build.mjs";
+import { loadGraph, defaultGraphPath } from "./graph-query.mjs";
+import { findByName, affected } from "./graph-affected.mjs";
+
+const DEFAULT_MAX_NODES = 25;
+
+/**
+ * A mermaid-safe identifier for a graph node id.
+ *
+ * Graph ids carry `:`, `/`, `#` and `.`, all of which mermaid reads as syntax.
+ * Rather than escaping them, ids are positional (`n0`, `n1`) and the real name
+ * travels in the quoted label, where mermaid only needs `"` handled.
+ *
+ * @param {number} i
+ * @returns {string}
+ */
+export function nodeKey(i) {
+  return `n${i}`;
+}
+
+/**
+ * The label a reader sees. Paths are shown basename-first because a column of
+ * identical directory prefixes is the fastest way to make a diagram unreadable,
+ * and the full path is already in the text report beside it.
+ *
+ * @param {object} node
+ * @returns {string}
+ */
+export function label(node) {
+  // A symbol is known by its name; a file by its basename. Using the path for
+  // both printed the DEFINING FILE as the label of every symbol, which drew a
+  // diagram where the thing that changed appeared to be something else.
+  const base =
+    node.kind === "file" || node.kind === "module"
+      ? (node.path || node.name || node.id).split("/").pop()
+      : node.name || node.id;
+  const where = node.kind !== "file" && node.path ? ` - ${node.path.split("/").pop()}` : "";
+  return `${base}${where}`.replace(/"/g, "'");
+}
+
+/**
+ * Build the diagram model: which nodes survive the ceiling, which edges connect
+ * them, and how many were left out.
+ *
+ * Over the ceiling the highest-degree nodes are kept, because they are the ones
+ * a reviewer most needs to see, and the count of the rest is REPORTED. Silently
+ * dropping them would draw a small blast radius for a large change, which is
+ * the one failure a diagram must not have.
+ *
+ * @param {object} graph
+ * @param {{id: string, dist: number}[]} hits
+ * @param {string[]} seedIds
+ * @param {number} maxNodes
+ * @returns {{nodes: object[], edges: object[], truncated: number}}
+ */
+export function buildModel(graph, hits, seedIds, maxNodes) {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const wanted = new Map();
+
+  for (const id of seedIds) {
+    const n = byId.get(id);
+    if (n) wanted.set(id, { node: n, dist: 0 });
+  }
+  for (const h of hits) {
+    if (wanted.has(h.id)) continue;
+    const n = byId.get(h.id);
+    if (n) wanted.set(h.id, { node: n, dist: h.dist });
+  }
+
+  // Seeds are never dropped - a diagram without the thing that changed is not a
+  // smaller diagram, it is a different question. Order the rest by distance
+  // first (near blast radius before far), then by degree, then by id so the
+  // output is byte-stable across runs.
+  const seeds = [...wanted.values()].filter((e) => e.dist === 0);
+  const rest = [...wanted.values()]
+    .filter((e) => e.dist !== 0)
+    .sort(
+      (a, b) =>
+        a.dist - b.dist ||
+        (b.node.degree || 0) - (a.node.degree || 0) ||
+        a.node.id.localeCompare(b.node.id),
+    );
+
+  const room = Math.max(0, maxNodes - seeds.length);
+  const kept = [...seeds, ...rest.slice(0, room)];
+  const truncated = rest.length - Math.min(rest.length, room);
+
+  const keptIds = new Set(kept.map((e) => e.node.id));
+  const edges = graph.edges
+    .filter((e) => keptIds.has(e.from) && keptIds.has(e.to))
+    .sort(
+      (a, b) =>
+        a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind),
+    );
+
+  return { nodes: kept.map((e) => ({ ...e.node, dist: e.dist })), edges, truncated };
+}
+
+/**
+ * Render the model as mermaid text.
+ *
+ * @param {{nodes: object[], edges: object[], truncated: number}} model
+ * @param {{direction?: string, baseCommit?: string}} [opts]
+ * @returns {string}
+ */
+export function render(model, opts = {}) {
+  const dir = opts.direction || "LR";
+  const idx = new Map(model.nodes.map((n, i) => [n.id, nodeKey(i)]));
+  const L = [`flowchart ${dir}`];
+
+  for (const n of model.nodes) {
+    const key = idx.get(n.id);
+    // Seeds are the thing that changed; everything else is downstream of it.
+    L.push(n.dist === 0 ? `  ${key}["${label(n)}"]` : `  ${key}("${label(n)}")`);
+  }
+  for (const e of model.edges) {
+    L.push(`  ${idx.get(e.from)} -->|${e.kind}| ${idx.get(e.to)}`);
+  }
+  if (model.truncated > 0) {
+    L.push(`  more["+${model.truncated} more, not drawn"]`);
+  }
+  return L.join("\n");
+}
+
+function main() {
+  // Same argument contract as graph-affected.mjs, deliberately: positional parts
+  // are one name. Several seeds are comma-separated inside that name, so a PR
+  // touching three symbols draws one diagram rather than three.
+  const { flags, positional } = parseFlags(process.argv.slice(2));
+  const name = positional.join(" ").trim();
+  if (!name) {
+    console.error('graph-mermaid: a symbol name is required, e.g. graph-mermaid "Flight"');
+    process.exit(64);
+  }
+  const symbols = name
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  const graphPath = flags.graph && flags.graph !== true ? resolve(flags.graph) : defaultGraphPath();
+  let graph;
+  try {
+    graph = loadGraph(graphPath);
+  } catch {
+    // Not an error to shout about: a repo with no graph yet simply has no
+    // diagram, and the caller records the reason instead of drawing nothing and
+    // calling it empty.
+    console.error(`graph-mermaid: no code graph at ${graphPath} - run /multi-agent:graph first`);
+    process.exit(1);
+  }
+
+  const depth = Number(flags.depth && flags.depth !== true ? flags.depth : 2);
+  // A Set, not an array: `affected` calls `kinds.has(...)`, and an array there
+  // silently matches nothing rather than failing.
+  const kinds = flags.kind && flags.kind !== true ? new Set(String(flags.kind).split(",")) : null;
+  const maxNodes = Number(
+    flags["max-nodes"] && flags["max-nodes"] !== true ? flags["max-nodes"] : DEFAULT_MAX_NODES,
+  );
+  const direction = flags.direction === "TD" ? "TD" : "LR";
+
+  const seedNodes = symbols.flatMap((s) => findByName(graph, s));
+  if (seedNodes.length === 0) {
+    console.error(`graph-mermaid: no node named ${symbols.join(", ")} in ${graphPath}`);
+    process.exit(1);
+  }
+  // `affected` takes node OBJECTS, not ids - it reads `n.id` off each seed.
+  // Passing ids made every traversal start from `undefined` and return nothing,
+  // which looks exactly like "nothing depends on this".
+  const seen = new Set();
+  const seeds = seedNodes.filter((n) => !seen.has(n.id) && seen.add(n.id));
+  const hits = affected({ graph, seeds, depth, kinds });
+  const model = buildModel(
+    graph,
+    hits,
+    seeds.map((n) => n.id),
+    maxNodes,
+  );
+  const mermaid = render(model, { direction });
+
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        {
+          mermaid,
+          nodes: model.nodes.map((n) => n.id),
+          edges: model.edges.map((e) => ({ from: e.from, to: e.to, kind: e.kind })),
+          truncated: model.truncated,
+          baseCommit: graph.baseCommit || null,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  console.log("```mermaid");
+  console.log(mermaid);
+  console.log("```");
+  // The pin, printed beside the diagram rather than inside it: a graph built at
+  // an older commit draws an older blast radius, and a reader who cannot see
+  // which commit it came from has no way to notice.
+  if (graph.baseCommit) {
+    console.log("");
+    console.log(`_Graph at \`${String(graph.baseCommit).slice(0, 12)}\`._`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/pipeline/scripts/phase-tracker.sh

@@ -681,8 +681,17 @@ EOF
 # a subject is a task title and travels through surfaces that are not a terminal.
 subjects() {
   need_jq
-  local state want="${1:-}"
+  local state want="${1:-}" new_only=""
+  # `--new` narrows to phases that have no tile yet, which is how a deferred
+  # registration batch (Phase 0 at Step -1, the rest once depth is known) avoids
+  # asking the host to create a tile it already has. A phase whose tasklist_id was
+  # never recorded has, as far as anything can tell, no tile.
+  if [ "$want" = "--new" ]; then new_only=1; want=""; fi
   state=$(load_state)
+  local new_ids=""
+  if [ -n "$new_only" ]; then
+    new_ids=" $(echo "$state" | jq -r '[.phases[]? | select(((.meta.tasklist_id // "") | tostring) == "") | .id] | join(" ")') "
+  fi
   local prices_json='{"prices":{}}'
   if [ -f "$COST_TABLE" ]; then
     prices_json=$(cat "$COST_TABLE" 2>/dev/null) || prices_json='{"prices":{}}'
@@ -704,6 +713,9 @@ subjects() {
   while IFS=$'\x1f' read -r pid pname pstatus p_start p_end pmodel ptok pusd; do
     [ -n "$pid" ] || continue
     [ -z "$want" ] || [ "$want" = "$pid" ] || continue
+    if [ -n "$new_only" ]; then
+      case "$new_ids" in *" $pid "*) ;; *) continue ;; esac
+    fi
     local line="Phase $pid $pname"
     [ -n "$pmodel" ] && line="$line - $pmodel"
     local s_ep e_ep el=""
@@ -755,10 +767,33 @@ subjects() {
 # already does for a different reason.
 tiles_script() {
   need_jq
+  local new_only="${1:-}"
   local state; state=$(load_state)
   local has_subs
   has_subs=$(echo "$state" | jq '[.phases[]?.subs[]?] | length')
 
+  # A list carrying sub-steps has to be rebuilt whole, so the rebuild wins over a
+  # narrowed batch: appending to it would land the new rows after Phase 7.
+  [ "${has_subs:-0}" -gt 0 ] && new_only=""
+
+  if [ -n "$new_only" ]; then
+    local pending_new
+    pending_new=$(subjects --new)
+    if [ -z "$pending_new" ]; then
+      printf 'Every registered phase already has a tile - nothing to create.\n'
+      return 0
+    fi
+    printf 'REQUIRED  -  create one native tile per phase below, in this exact order.
+'
+    printf 'Tiles already created keep their place; every phase here is numbered
+'
+    printf 'above them, so the widget stays in phase order.
+
+'
+    printf '%s\n' "$pending_new" | sed 's/^/  TaskCreate(subject: "/; s/$/")/'
+    return 0
+  fi
+
   if [ "${has_subs:-0}" -gt 0 ]; then
     printf 'The tile list has sub-steps now, and the widget orders by CREATION.
 '
@@ -1346,6 +1381,8 @@ EOF
 
   tiles)
     need_jq
+    tiles_new=""
+    [ "${1:-}" = "--new" ] && tiles_new=1
     tiles_state=$(load_state)
     tiles_count=$(echo "$tiles_state" | jq '[.phases[]?] | length')
     [ "${tiles_count:-0}" -gt 0 ] || {
@@ -1368,7 +1405,7 @@ EOF
         # tools it has. And the fallback is not enough on its own: a user looking
         # at a missing widget needs the one command that brings it back, which is
         # why the opt-in is printed next to it.
-        tiles_script
+        tiles_script "$tiles_new"
         echo
         echo "At every phase boundary re-run \`phase-tracker.sh subjects <id>\` and"
         echo "pass that line as the subject of the TaskUpdate. The subject is the only"