jackherd 1.10.0 → 1.11.1

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.10.0"
+version = "1.11.1"
 min_herdr_version = "0.8.2"
 description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.10.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.11.1}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/open-question/run.ts

@@ -28,7 +28,8 @@ export const relevantLines = (text: string): string => {
  * Records the questions of the session's dialogs that ended without an answer, and closes the open records of every
  * session that a dialog in this transcript has answered since. The whole transcript is read, not the last turn: a
  * rejected dialog ends its turn without a Stop hook, so it is found at the end of the next turn. Claude Code's hook
- * input: `cwd`, `session_id`, `transcript_path`. Writes nothing on any failure.
+ * input: `cwd`, `session_id`, `transcript_path`. A question whose text has an open record already adds none, so asking
+ * it again and putting it off again leaves one. Writes nothing on any failure.
  */
 export const runOpenQuestion = (input: unknown, dependencies: OpenQuestionDependencies): void => {
   try {
@@ -44,8 +45,12 @@ export const runOpenQuestion = (input: unknown, dependencies: OpenQuestionDepend
       if (answer) dependencies.writeRecord(main, { ...record, closedAt: answer.answeredAt })
     }
     const known = new Set(stored.map(({ id }) => id))
-    for (const record of openQuestionsOf(entries, { cwd, session, answered, idOf: dependencies.idOf }))
-      if (!known.has(record.id)) dependencies.writeRecord(main, record)
+    const openTexts = new Set(stored.filter(({ closedAt }) => closedAt === null).map(({ question }) => question))
+    for (const record of openQuestionsOf(entries, { cwd, session, answered, idOf: dependencies.idOf })) {
+      if (known.has(record.id) || openTexts.has(record.question)) continue
+      openTexts.add(record.question)
+      dependencies.writeRecord(main, record)
+    }
   } catch {
     // A failed record is no record; the herd shows no question.
   }

package/kit/rules/rules/kit/pull-requests.md

@@ -42,6 +42,8 @@ Add a fenced ` ```mermaid ` block **when it removes reader effort**:
 
 Keep each diagram to one idea; two small diagrams beat one dense one. Small or single-file PRs need none.
 
+Write edge labels as `-->|"label"|` (`-- text -->` breaks on a `--` in it); `jh mermaid <body file>` must exit 0 before `gh pr create` or `gh pr edit`.
+
 ## Review order (large PRs)
 
 When a PR spans many files, add a short **suggested review order** — **pure/domain logic first, adapters next, UI and wiring last**. A `| # | Area | Start here | Why first |` table works well.

package/kit/workflow/skills/follow/SKILL.md

@@ -15,8 +15,8 @@ You add one entry to `watch.sources`, so that `jh watch` reports a new or change
 - **Service:** the services the recipe index lists, and "another command that prints JSON".
 - **What to follow:** the item the argument names (its comments, recommended) or a query over several items.
 - **Lane:** the lane the reports name, from the board's lanes table, or none.
-- **Ticket:** whether the entries are tickets (`ticket: true`, recommended for an issue tracker or a project board), which the herd shows as a badge beside the plan of their lane: the lane above, or the lane whose name, board row or plan names the ticket's id. A source of comments or messages is no ticket. The path of the status you find yourself in step 3.
-- **What reports:** a change of what the user reads (title, body, the latest comment; recommended), or a change of named fields such as a status (`reportOn` with those fields, mapped in `map`).
+- **Ticket:** whether the entries are tickets (`ticket: true`, recommended for an issue tracker or a project board), which the herd shows as a badge beside the plan of their lane: the lane above, or the lane whose name, board row or plan names the ticket's id. A source of comments or messages is no ticket; it shows in the herd's `Sources` block instead (a click opens the entry at `map.url`). The path of the status you find yourself in step 3.
+- **Tone:** for a non-ticket source, the colour of its `Sources` mark while its report is new (`tone`: amber, teal, grey, red, green, blue, magenta); recommended: no `tone`.- **What reports:** a change of what the user reads (title, body, the latest comment; recommended), or a change of named fields such as a status (`reportOn` with those fields, mapped in `map`).
 - **Own changes:** ignore the user's own account on that service (`ignoreAuthors`, needs an author in the map), or report everything.
 
 ## 2. Check, read only
@@ -30,7 +30,7 @@ Anything missing goes to the user as the command to run themselves (`! <command>
 
 Before filling, read the help of the installed CLI version for every command the recipe calls (`acli jira workitem search --help` and `workitem view --help`, `gh issue list --help`) and confirm that the fields and options the entry needs exist there. Read the provider's web documentation only when the help leaves it open or no recipe fits. A recipe is a starting point; the installed version decides.
 
-Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane`, `ignoreAuthors` and `ticket` where chosen. For a ticket source, find the path of the status in the output (from the CLI's help, or the dry run with `--raw`) and set it as `map.status`; the entry you show for approval in step 4 carries it, and without a status in the output the entry has none and the badge shows only the key. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it, from the recipe's script under `recipes/sources/`, to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]`. Script and direct command follow the index's **Rules every recipe follows**.
+Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane`, `ignoreAuthors`, `ticket` and `tone` where chosen, and a short `label` (e.g. `Error log · Checkout`; it prefixes the source's `Waiting for you` rows). For a ticket source, find the path of the status in the output (from the CLI's help, or the dry run with `--raw`) and set it as `map.status`; the entry you show for approval in step 4 carries it, and without a status in the output the entry has none and the badge shows only the key. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it, from the recipe's script under `recipes/sources/`, to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]`. Script and direct command follow the index's **Rules every recipe follows**.
 
 Write the entry as one JSON object to a draft file in the scratchpad and run, from the main checkout:
 

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -67,7 +67,7 @@ Each file under `references/` is read when its trigger fires: the step or the ev
 `jh lane prompt <lane> [--board <board>]` writes the lane prompt from the lane's board row and its plan, in
 the plan's language, to `.claude/handover/<lane>-prompt.md` and prints the path. It opens with a first line
 that names the lane, which the hooks and the project's rules read: keep that line as it is. Before you send
-it, add to the file with `Edit` the open questions that touch the lane and what the project
+it, add to the file with `Edit`, below the marker line at its end (it stays through every new writing), the open questions that touch the lane and what the project
 supplement adds to the lane prompt. Never paste the rules of this skill into a lane prompt. The lane asks you in text blocks at the end of its turn; answer them with
 `herdr agent prompt` (§ 2 step 8).
 
@@ -248,7 +248,7 @@ On wake-up:
 | `checks passed #<n>` | One line to the user: ready to merge, with the board's merge order |
 | `deploy …` | Result and target as the run states them, to the user; a target `unknown (…)` is reported as unknown, never guessed. A failed run goes to the user as an `AskUserQuestion`: read the logs now or later |
 | `due <when> · <action>` | An open appointment fell due (**An agreed time**, below); the action is cut to 160 characters, the board row holds it whole. Carry it out as agreed, under the approvals it needs (§ 5), then write the outcome into its status cell in the same turn |
-| `heartbeat` | One line of status to the user, also when nothing changed; a resting lane carries `waits on: <question>, <n> open questions` from its report, and `for you (<n>): …` names what still waits on the user (**Anything that waits on the user's answer**, below): remind the user of those items in that line |
+| `heartbeat` | One line of status to the user, also when nothing changed; a resting lane carries `waits on: <question>, <n> open questions` from its report, and `for you (<n>): …` names what still waits on the user (**Anything that waits on the user's answer**, below): the `for you` part of that line is the count only (`3 wait for you, see the herd`, in the language of the replies); the herd shows the items, and no reply of yours ends with a list of the rows of the board section |
 | `gh unavailable` | Tell the user once; herdr watching continues |
 | `lane <name> warn` | One line to the user: the lane's fill and that it hands over at a phase boundary if it rises further; no step in the lane |
 | `lane <name> alert` | § 8: send the lane once the request for its hand-over at the end of its current phase |
@@ -290,10 +290,18 @@ watcher reports an open row once when it falls due (`due`, above); an empty stat
 and a reworded or moved row is a new appointment and reports again. Close a reported row through its
 status cell.
 
+**Board grooming** is an appointment of its own, a row in that section whose action starts with
+`Board-Pflege` (`Board grooming`); a board without one gets it, due a week from now. When it reports:
+check that the open lane rows still serve the board's goal (a mismatch joins the bundled question), rewrite the
+board's `Als Nächstes` (`Next`) section (three lines at most, each with a date), clear finished lane
+rows, ask for outdated plans in one bundled question, then set its `When` a week after now and leave its status
+empty: this is the one appointment that is moved, not closed. The herd
+counts `groomed <n>d ago` from it and turns it amber at eight days.
+
 **Anything that waits on the user's answer** (a preview or a file sent to them, a question put to them, a
 report handed over for acceptance) goes into the board in the same turn you send it, in the section
 `## Wartet auf dich` (German plans) or `## Waiting for you` (English), one row `Since | Item | Origin | Status`
-(`Seit | Punkt | Herkunft | Stand`) with the time as in **An agreed time**. It survives a hand-over, which a
+(`Seit | Punkt | Herkunft | Stand`) with the time as in **An agreed time**; for a source's report the origin is the source's name, and the herd prefixes the row with its label. It survives a hand-over, which a
 message in this chat does not. Close a row in its status cell in the turn the user's answer arrives (also a
 "no"), or when the thing is withdrawn; an empty status counts as open. A file sent with `SendUserFile` and an
 Artifact you publish need no row (the kit hook `sent-file` records each): close them after the answer with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "keywords": [
     "claude-code",
     "coding-agents",
@@ -50,7 +50,6 @@
     "!docs/gen",
     "assets",
     "!assets/icons/build.ts",
-    "!assets/icons/version.ts",
     "!assets/branding/outline.ts",
     "recipes",
     "README.md",
@@ -68,6 +67,7 @@
     "dev": "tsup --watch",
     "clean": "rm -rf dist",
     "gen": "bun scripts/generate-schema.ts",
+    "pin:assets": "bun scripts/pin-readme-assets.ts --write",
     "lint": "biome check .",
     "format": "biome format --write .",
     "test": "bun test"

package/recipes/sources.md

@@ -60,6 +60,10 @@ A run that ends with an exit code other than 0, runs past 30 seconds (then its w
 
 **Show a ticket beside its plan.** `"ticket": true` marks a source's entries as tickets. The herd then shows each one as a badge in the 📎 line of its lane's plan, right after `📄 Plan`: `📡 T-123 · In Progress`, linked to the ticket. A ticket belongs to the source's `lane`, and also to any lane whose board row, name or plan names its id as a whole word (`T-12` is not found in `T-123`); so one source listing all your open tickets works without `lane`. `map.status` is the status the badge shows; without it the badge shows only the key. A ticket whose last reported change is less than a day old is amber, and a folded lane then shows `📡 <n>` in amber before its bar, linked to the first new ticket. A lane shows at most three tickets, new ones first, then `+<n>`; a link chip of the plan with the same URL gives way to the badge. For this the saved state keeps, of a marked source only, each entry of its last successful run with its URL, its status (stored like a `reportOn` value) and the time its last change was reported. The badges come from the watcher's state like the pull request badges: without a running watcher or with a state older than three minutes there are none, and the header says `watcher off` or `state 4 min old`, also without a pull request. The [GitHub Projects recipe](#user-content-recipes) is a ticket source with a status.
 
+**Show a source in the herd.** A source without `ticket` appears in the herd's `Sources` block, one row each: its name, when it last ran (`ran 12 min ago`), since when it fails (`failing since 3 h ago`, mark red) and its newest report (mark amber while that report is under a day old). A source with several entries is one folded row; a click opens its entries (up to five, then `+<n> more`), each with its title, `map.count` as `113×` and the time of its last change. A click on an entry opens its `url` (the watcher keeps it only as a checked `https:` URL of at most 200 characters, so map a short link), `[ask]` asks the coordinator to look at that entry. An entry that an open row of "Waiting for you" already asks about (the row's `Origin` names the source and its text the title) is dim and says `↑ asked`; the row is amber only for a new entry nobody asked about. The watcher keeps the last 20 entries of such a source. `tone` (amber, teal, grey, red, green, blue or magenta) sets the mark's colour while the report is new, instead of the tone of the role `new`; the roles `waiting`, `new`, `running` and `resting` take their tones from `plans.tones` in the config (defaults: amber, amber, teal, grey).
+
+**Name a source in "Waiting for you".** A row of the board's waiting section whose `Origin` cell is the name of a source (case ignored) shows `<label>: <row>` in the herd; `label` (one line, at most 40 characters) is optional, without it the source's name stands before the row. `/jh-follow` proposes a short label when it writes the entry.
+
 **How you hear about it.** The report goes to the coordinator, as a `=== source …` event of its watcher. It passes you one line with the entry, its gist and the link. A decision inside it, such as a product owner's answer, it takes over only after you confirmed it, since the text comes from outside. You hear of it only while the coordinator's session and its watcher run; what happened in between is reported at the next start. There is no desktop notification of its own: you get the one herdr shows for any lane that needs you. What a source reports is a change in the mapped content fields (`title`, `author`, `body`, `url`), or with `reportOn` a change of the fields it names, such as a status.
 
 **Try a source before the watcher runs it.** `jh watch source <name> --dry-run` runs a configured source once; a draft not yet in the config comes as a file (`jh watch source draft.json --dry-run`, one source object) or on stdin (`-`). It lists the entries (`<id> · <author> · <title>`), says that the watcher's first run of the source is a baseline and reports nothing, and shows one entry as a later report would print it; it neither reads nor changes the watcher's state. A field of `map` that is empty in every entry is named with its path (`map.updatedAt: in 23 of 23 entries empty (.fields.updated)`), read from the raw output, so a run that failed on a missing `id` or `updatedAt` names it too; the dry run then ends with exit code 1, as for a failed run, and `/jh-follow` does not write the source. Without entries it says `0 entries: map not checked`. `--raw` adds the command's output, for finding the paths of `items` and `map`:

package/schemas/jackherd.schema.json

@@ -297,6 +297,65 @@
             }
           },
           "additionalProperties": false
+        },
+        "tones": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "waiting": {
+              "default": "amber",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            },
+            "new": {
+              "default": "amber",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            },
+            "running": {
+              "default": "teal",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            },
+            "resting": {
+              "default": "grey",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -483,6 +542,9 @@
                   },
                   "status": {
                     "type": "string"
+                  },
+                  "count": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -506,6 +568,12 @@
                 "minimum": 1,
                 "maximum": 9007199254740991
               },
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 40,
+                "pattern": "^[^\\r\\n]+$"
+              },
               "lane": {
                 "type": "string",
                 "minLength": 1
@@ -513,6 +581,18 @@
               "ticket": {
                 "type": "boolean"
               },
+              "tone": {
+                "type": "string",
+                "enum": [
+                  "amber",
+                  "teal",
+                  "grey",
+                  "red",
+                  "green",
+                  "blue",
+                  "magenta"
+                ]
+              },
               "reportOn": {
                 "minItems": 1,
                 "maxItems": 10,

package/src/cli.ts

@@ -25,6 +25,7 @@ export const COMMANDS: CommandTable = {
   init: () => import('./sync/init-command'),
   [HERD_COMMAND.alias]: () => import('./plans/command'),
   lane: () => import('./lane/command'),
+  mermaid: () => import('./mermaid/command'),
   preview: () => import('./preview/command'),
   settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),

package/src/config/schema.ts

@@ -10,6 +10,7 @@ import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
 import { hasNestedQuantifier } from './nested-quantifier'
 import { isRepositoryDirectory } from './repository-directory'
+import { DEFAULT_TONES, TONE_NAMES } from './tones'
 
 export const TERMINAL_ADAPTER = { none: 'none', herdr: 'herdr' } as const
 
@@ -176,7 +177,7 @@ const sourcePath = z.string().refine(isSourcePath, 'not a source path: `.`, or `
 
 const SOURCE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/
 
-/** The seven known fields, and any further field (`priority`, `assignee`, …) whose name is a plain name, for `reportOn`. */
+/** The eight known fields, and any further field (`priority`, `assignee`, …) whose name is a plain name, for `reportOn`. */
 const sourceMapSchema = z
   .object({
     [SOURCE_FIELD.id]: sourcePath,
@@ -193,6 +194,8 @@ const sourceMapSchema = z
     [SOURCE_FIELD.author]: sourcePath.optional(),
     /** A ticket source's status, shown on its badge in the herd; also a field `reportOn` can name. */
     [SOURCE_FIELD.status]: sourcePath.optional(),
+    /** How often the entry happened (an error count), shown as `113×` beside the entry in the herd's `Sources` block. */
+    [SOURCE_FIELD.count]: sourcePath.optional(),
   })
   .catchall(sourcePath)
   .refine((map) => Object.keys(map).every((field) => SOURCE_FIELD_NAME.test(field)), {
@@ -203,6 +206,8 @@ const sourceMapSchema = z
 const canChange = ({ map, reportOn }: { map: Record<string, string | undefined>; reportOn?: string[] }): boolean =>
   map.updatedAt !== undefined || CONTENT_FIELDS.some((field) => map[field] !== undefined) || reportOn !== undefined
 
+const toneName = z.enum(TONE_NAMES)
+
 const sourceSchema = z
   .strictObject({
     /** Printed in every report of the source and the key of its saved state. */
@@ -218,6 +223,13 @@ const sourceSchema = z
     ignoreAuthors: z.array(z.string().min(1)).default([]),
     /** The most new or changed entries one report shows of this source; the rest is one line `+<n> more`. */
     reportLimit: z.number().int().min(1).default(5),
+    /** Shown before a row of "Waiting for you" that came from this source (`Error log · Checkout: …`); without it the source's name. */
+    label: z
+      .string()
+      .min(1)
+      .max(40)
+      .regex(/^[^\r\n]+$/, 'one line')
+      .optional(),
     /** The lane the source's reports name. */
     lane: z.string().min(1).optional(),
     /**
@@ -225,6 +237,8 @@ const sourceSchema = z
      * the lane above or the lane whose board row or plan names its id.
      */
     ticket: z.boolean().optional(),
+    /** The tone of the source's mark in the herd's `Sources` block while its newest report is new; without it the tone of the role `new`. */
+    tone: toneName.optional(),
     /**
      * The mapped fields whose change reports, with the old and the new value, in place of the content of `title`,
      * `author`, `body` and `url`; without it a change of that content reports.
@@ -383,6 +397,13 @@ const hintsSchema = z.strictObject({
 /** Minutes a lane works without a task signal before the watcher reports `no task signal`. */
 const DEFAULT_TASK_SIGNAL_MINUTES = 10
 
+const tonesSchema = z.strictObject({
+  waiting: toneName.default(DEFAULT_TONES.waiting),
+  new: toneName.default(DEFAULT_TONES.new),
+  running: toneName.default(DEFAULT_TONES.running),
+  resting: toneName.default(DEFAULT_TONES.resting),
+})
+
 const contextSchema = z
   .strictObject({
     /** Tokens in a lane's context from which its fill shows yellow and `/implement` offers a new chat. */
@@ -475,6 +496,8 @@ export const jackherdConfigSchema = z.strictObject({
         )
         .default(DEFAULT_LINK_KINDS.map((kind) => ({ ...kind }))),
       context: contextSchema.prefault({}),
+      /** The colour of each role in the herd, by name: what waits for you, what is new, what runs, what rests. */
+      tones: tonesSchema.prefault({}),
     })
     .prefault({}),
   /**

package/src/config/tones.ts

@@ -0,0 +1,27 @@
+/** The colours the herd paints with by name; the terminal's own palette decides how each looks, `grey` is the dimmed text colour. */
+export const TONE = {
+  amber: 'amber',
+  teal: 'teal',
+  grey: 'grey',
+  red: 'red',
+  green: 'green',
+  blue: 'blue',
+  magenta: 'magenta',
+} as const
+
+export type ToneName = (typeof TONE)[keyof typeof TONE]
+
+export const TONE_NAMES = Object.values(TONE)
+
+/** What a tone is for in the herd: what waits for you, what is new, what runs, what rests. */
+export const TONE_ROLE = { waiting: 'waiting', new: 'new', running: 'running', resting: 'resting' } as const
+
+export type ToneRole = (typeof TONE_ROLE)[keyof typeof TONE_ROLE]
+
+/** The tone of each role, as the herd looked before the tones were configurable. */
+export const DEFAULT_TONES: Record<ToneRole, ToneName> = {
+  [TONE_ROLE.waiting]: TONE.amber,
+  [TONE_ROLE.new]: TONE.amber,
+  [TONE_ROLE.running]: TONE.teal,
+  [TONE_ROLE.resting]: TONE.grey,
+}

package/src/lane-prompt/additions.ts

@@ -0,0 +1,14 @@
+/** The line that ends a written lane prompt; what the coordinator adds below it survives every new writing. */
+export const ADDITIONS_MARKER = '<!-- jackherd: additions below this line stay when the prompt is written again -->'
+
+/** What follows the marker line of a written prompt; empty for no file, no marker line or nothing below it. */
+export const additionsOf = (existing: string | null): string => {
+  if (existing === null) return ''
+  const lines = existing.split('\n')
+  const marker = lines.indexOf(ADDITIONS_MARKER)
+  return marker === -1 ? '' : lines.slice(marker + 1).join('\n')
+}
+
+/** `prompt` closed by the marker and by the additions of the file it replaces, so writing twice changes nothing. */
+export const withAdditions = (prompt: string, existing: string | null): string =>
+  `${prompt}\n${ADDITIONS_MARKER}\n${additionsOf(existing)}`

package/src/lane-prompt/command.ts

@@ -5,6 +5,7 @@ import { boardFor } from '../plans/board-pick'
 import { mainCheckout, worktreeRoot } from '../plans/git'
 import { boardRepoPathOf, readSettings, worktreeOf } from '../plans/settings'
 import { asksForHelp } from '../preview/options'
+import { withAdditions } from './additions'
 import { buildLanePrompt } from './build'
 import { type BoardSource, type LanePromptRequest, lanePromptInputOf, type ReadPlan } from './input'
 import { LANE_PROMPT_USAGE, type LanePromptOptions, parseLanePromptOptions } from './options'
@@ -53,15 +54,19 @@ const promptSourcesOf = (options: LanePromptOptions, cwd: string): PromptSources
   }
 }
 
+/** Writes `prompt` to `out`, closed by the marker and by the additions the file there already carries below it. */
 const writePrompt = (out: string, prompt: string): void => {
+  const existing = existsSync(out) ? readFileSync(out, 'utf8') : null
   mkdirSync(dirname(out), { recursive: true })
-  writeFileSync(out, prompt)
+  writeFileSync(out, withAdditions(prompt, existing))
 }
 
 /**
  * `jh lane prompt <lane> [--board <board.md>] [--out <file>] [--handover <file>]`: writes the lane's prompt, built
  * from its board row and its plan in the plan language, and prints the file's path, so the coordinator sends it with
- * `herdr agent prompt <lane> "$(cat <file>)"`. `--help` prints the usage. Exit 0 written, 1 refused or failed.
+ * `herdr agent prompt <lane> "$(cat <file>)"`. Below the marker line at the file's end the coordinator adds what the
+ * plan does not say; it stays through every new writing. A phase two open rows name is in no prompt and is reported on
+ * stderr. `--help` prints the usage. Exit 0 written, 1 refused or failed.
  */
 export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
   if (asksForHelp(args)) {
@@ -76,6 +81,7 @@ export const run = async (args: string[], cwd: string = process.cwd()): Promise<
       console.error(result.reason)
       return 1
     }
+    for (const notice of result.notices ?? []) console.error(notice)
     const out = options.out === null ? defaultPromptFile(root, options.lane) : resolve(cwd, options.out)
     writePrompt(out, buildLanePrompt(result.input))
     console.log(out)

package/src/lane-prompt/input.ts

@@ -17,7 +17,10 @@ export type BoardSource = { text: string; directory: string; path: string }
 /** A plan's text by its path from the repository root; null when it cannot be read. */
 export type ReadPlan = (path: string) => string | null
 
-export type LanePromptResult = { kind: 'prompt'; input: LanePromptInput } | { kind: 'refused'; reason: string }
+/** `notices` is absent unless the board needs fixing: a phase two open rows name is in neither prompt. */
+export type LanePromptResult =
+  | { kind: 'prompt'; input: LanePromptInput; notices?: string[] }
+  | { kind: 'refused'; reason: string }
 
 type PlanSteps = { path: string; ids: string[] }
 
@@ -90,6 +93,37 @@ const plansOf = (
   return { plans }
 }
 
+/** The other open lanes whose rows name the phase `id` of the plan at `path`, by name. */
+const otherNamersOf = (others: readonly SprintLane[], directory: string, path: string, id: string): string[] =>
+  others
+    .filter((lane) => planStepsOf(lane, directory).some((steps) => steps.path === path && steps.ids.includes(id)))
+    .map((lane) => lane.name)
+
+const withoutContested = (
+  plans: readonly LanePlan[],
+  lane: string,
+  others: readonly SprintLane[],
+  directory: string,
+): { plans: LanePlan[]; notices: string[] } => {
+  const judged = plans.map((plan) => ({
+    plan,
+    phases: plan.phases.map((phase) => ({ phase, namers: otherNamersOf(others, directory, plan.path, phase.id) })),
+  }))
+  const kept = judged.map(({ plan, phases }) => ({
+    ...plan,
+    phases: phases.filter(({ namers }) => namers.length === 0).map(({ phase }) => phase),
+  }))
+  const notices = judged.flatMap(({ plan, phases }) =>
+    phases
+      .filter(({ namers }) => namers.length > 0)
+      .map(
+        ({ phase, namers }) =>
+          `${plan.path} ${phaseLabel(phase.id)} is named by ${[lane, ...namers].sort().join(' and ')}, so it is in neither prompt; fix the board`,
+      ),
+  )
+  return { plans: kept.filter((plan) => plan.phases.length > 0), notices }
+}
+
 /**
  * What the lane's prompt is built from: its open row of the board's lanes table (port, plans, phases), each named
  * phase that is not finished, and the write set of each from its plan's dependency table. A plan is read from the lane
@@ -103,7 +137,8 @@ export const lanePromptInputOf = (
   readPlan: ReadPlan,
   readLanePlan: ReadPlan = () => null,
 ): LanePromptResult => {
-  const sprintLane = parseSprintLanes(board.text, request.language).find((candidate) => candidate.name === request.lane)
+  const lanes = parseSprintLanes(board.text, request.language)
+  const sprintLane = lanes.find((candidate) => candidate.name === request.lane)
   if (!sprintLane) return refused(`no row for lane ${request.lane} in ${board.path}`)
   if (sprintLane.closed) return refused(`lane ${request.lane} is closed in ${board.path}`)
   const steps = planStepsOf(sprintLane, board.directory)
@@ -112,5 +147,11 @@ export const lanePromptInputOf = (
   if ('reason' in found) return refused(found.reason)
   if (found.plans.length === 0) return refused(`every phase of lane ${request.lane} is finished`)
   const { lane, handover, language } = request
-  return { kind: 'prompt', input: { language, lane, plans: found.plans, port: sprintLane.port, handover } }
+  const others = lanes.filter((candidate) => candidate.name !== lane && !candidate.closed)
+  const { plans, notices } = withoutContested(found.plans, lane, others, board.directory)
+  if (plans.length === 0) {
+    return refused(`every open phase of lane ${lane} is also named by another lane: ${notices.join('; ')}`)
+  }
+  const input = { language, lane, plans, port: sprintLane.port, handover }
+  return notices.length === 0 ? { kind: 'prompt', input } : { kind: 'prompt', input, notices }
 }

package/src/lane-prompt/options.ts

@@ -13,6 +13,8 @@ const SUBCOMMAND = 'prompt'
 export const LANE_PROMPT_USAGE = `usage: ${CLI_NAME} lane prompt <lane> [--board <board.md>] [--out <file>] [--handover <file>]
 
 Writes the prompt that starts the lane, from its row in the board and its plan, and prints the file's path.
+What you add below the marker line at the end of the file stays when the prompt is written again.
+A phase that two open rows of the board name is in neither prompt; the command reports it.
   --board <board.md>   the board to read; without it the board is picked as for ${CLI_NAME} herd
   --out <file>         where to write the prompt; default .claude/handover/<lane>-prompt.md in the main checkout
   --handover <file>    a restart after a hand-over: the lane reads this file first and continues with its next step`

package/src/mermaid/command.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs'
+import { asksForHelp } from '../preview/options'
+import { CLI_NAME } from '../version/release'
+import { type MermaidProblem, mermaidProblems } from './problems'
+
+const USAGE = `usage: ${CLI_NAME} mermaid <file.md>
+
+Checks every \`\`\`mermaid block of the file for edge labels GitHub does not draw (a label between the dashes,
+a pipe label without quotes). Run it on a pull request body before gh pr create or gh pr edit.
+Exit 0 clean, 1 with problems or a wrong command line.`
+
+/** One line per problem, `file:line: reason`, then the offending text indented. */
+const problemLines = (file: string, problems: readonly MermaidProblem[]): string[] =>
+  problems.flatMap(({ line, reason, text }) => [`${file}:${line}: ${reason}`, `    ${text}`])
+
+export const run = (args: string[]): number => {
+  if (asksForHelp(args)) {
+    console.log(USAGE)
+    return 0
+  }
+  const [file, ...rest] = args
+  if (file === undefined || rest.length > 0) {
+    console.error(USAGE)
+    return 1
+  }
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    console.error(`cannot read ${file}`)
+    return 1
+  }
+  const problems = mermaidProblems(text)
+  for (const line of problemLines(file, problems)) console.error(line)
+  return problems.length === 0 ? 0 : 1
+}

package/src/mermaid/problems.ts

@@ -0,0 +1,48 @@
+/** A line of a Mermaid block that GitHub fails to draw: its 1-based line in the text, the line itself and why. */
+export type MermaidProblem = { line: number; text: string; reason: string }
+
+const FENCE = /^\s*(```|~~~)\s*(\S*)/
+const FLOWCHART = /^\s*(?:flowchart|graph)\b/
+/** A label written between the dashes of the link, `a -- text --> b`: a `--` inside the text ends the link early. */
+const LABEL_BETWEEN_DASHES = /\s(?:--|==)\s+\S.*?\s(?:-->|---|==>)(?:\s|$)/
+/** A pipe label that does not open with a quote: a comma, colon or parenthesis in it breaks the parser. */
+const UNQUOTED_PIPE_LABEL = /(?:-->|---|-\.->|==>)\|[^"|]/
+
+const REASON = {
+  betweenDashes: 'edge label between dashes: write -->|"label"|',
+  unquoted: 'edge label without quotes: write -->|"label"|',
+} as const
+
+const reasonOf = (text: string): string | null => {
+  if (LABEL_BETWEEN_DASHES.test(text)) return REASON.betweenDashes
+  return UNQUOTED_PIPE_LABEL.test(text) ? REASON.unquoted : null
+}
+
+/**
+ * The edge labels in the flowcharts of `markdown` that GitHub does not draw: ones written between the dashes and
+ * pipe labels without quotes. Only fenced blocks marked `mermaid` are read (a block never closed runs to the end of the
+ * text); the form that always parses is `-->|"label"|`.
+ */
+export const mermaidProblems = (markdown: string): MermaidProblem[] => {
+  const problems: MermaidProblem[] = []
+  let fence: string | null = null
+  let isFlowchart = false
+  markdown.split('\n').forEach((text, index) => {
+    const opening = FENCE.exec(text)
+    if (fence === null) {
+      if (opening?.[2] === 'mermaid') {
+        fence = opening[1] ?? '```'
+        isFlowchart = false
+      }
+      return
+    }
+    if (opening && opening[1] === fence && opening[2] === '') {
+      fence = null
+      return
+    }
+    if (FLOWCHART.test(text)) isFlowchart = true
+    const reason = isFlowchart ? reasonOf(text) : null
+    if (reason) problems.push({ line: index + 1, text: text.trim(), reason })
+  })
+  return problems
+}

package/src/plan-format/dependencies.ts

@@ -81,10 +81,10 @@ const dependsOf = (cell: string, language: PlanLanguage): Pick<PhaseDependency,
 /**
  * A path as the cell writes it, cut to the directory a glob character starts in (`scripts/*.ts` is `scripts`,
  * `.claude/**` is `.claude`, `*.md` is the root `''`) and without a trailing slash; null for a backticked entry with a
- * space in it, which is a command.
+ * space in it, which is a command, and for one with `[]`, which is a config key (`watch.sources[].label`) and no glob.
  */
 const pathOf = (entry: string): string | null => {
-  if (/\s/.test(entry)) return null
+  if (/\s/.test(entry) || entry.includes('[]')) return null
   const glob = entry.search(GLOB_CHARACTER)
   const literal = glob === -1 ? entry : entry.slice(0, Math.max(entry.lastIndexOf('/', glob), 0))
   const path = literal.replace(/^\.\//, '').replace(/\/+$/, '')