jackherd 1.11.2 → 1.12.1

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.11.2"
+version = "1.12.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.11.2}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.12.1}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

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

@@ -27,7 +27,7 @@ When the user asks for more than one phase:
 
 1. **Read the computed waves:** run `jh check --parallel <plan>`. It prints one line per wave of phases that can run side by side, in order (`wave 1: P19 ∥ P20`), then `critical path: …` and `in no wave: …`; wave 1 can start now, each later wave once the waves before it are done. A phase is ready once every `{{kit.heading.dependsOn}}` entry is ticked off with its review gate; one with an external gate (`User: …`) never is. Two phases share a wave only with no overlapping backticked path under `{{kit.heading.writes}}` (a `like N` entry adds that phase's set), no shared `{{kit.heading.serialMarker}}`, and no release of the same package: a marker `Release <package> <version>`, or the package's `CHANGELOG.md` or `package.json` under `{{kit.heading.writes}}`. `no dependency table`: the phases run one after the other. `no phase is ready`: every open phase waits, is done, or is in no wave.
 2. **Batch:** the requested phases in wave 1. A requested phase in a later wave waits, naming the phase it collides with. One in no wave is not ready for one of these reasons: it has an external gate (ask whether the gate holds), its `like N` entry names an unknown phase or runs in a cycle, its `{{kit.heading.writes}}` cell has no backticked path, or it depends on such a phase; say which. The command checks paths, markers and releases only: two phases that collide in content stay your judgement, so serialise them yourself.
-3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, description: …, prompt: …)` per phase, in the same checkout: the disjoint `{{kit.heading.writes}}` sets are the isolation. The `description` starts with the short name of the task the subagent works on, the first open one of its phase, then the phase: `<Name> · P<n>`; the herd puts its `▶` on that task. Without a short name, the phase alone. They may run in the background; a hand-over (Step 7) waits until all are back. Each prompt names its phase (`Phase P<n>` and the plan's path, as in Step 0) and its `{{kit.heading.writes}}` set as the **only** paths it may edit, besides ticking its own phase's task lines in the plan, and states that it ticks the task checkboxes of its own phase as it finishes each one (Plan Hygiene), and leaves the review gate, commits and `/pre-commit` to you — it reports changed files, test results and the gate items it ran.
+3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, description: …, prompt: …)` per phase, in the same checkout: the disjoint `{{kit.heading.writes}}` sets are the isolation. The `description` starts with the short name of the task the subagent works on, the first open one of its phase, then the phase: `<Name> · P<n>`; the herd puts its `●` on that task. Without a short name, the phase alone. They may run in the background; a hand-over (Step 7) waits until all are back. Each prompt names its phase (`Phase P<n>` and the plan's path, as in Step 0) and its `{{kit.heading.writes}}` set as the **only** paths it may edit, besides ticking its own phase's task lines in the plan, and states that it ticks the task checkboxes of its own phase as it finishes each one (Plan Hygiene), and leaves the review gate, commits and `/pre-commit` to you — it reports changed files, test results and the gate items it ran.
 4. **When the batch returns:** check each report against its set (`git diff --stat`; an edit outside the set is a finding; a ticked line outside its own phase is one too), tick what it left open, walk each review gate. Gate items that write outside a phase's set (documentation, a changelog entry, plan synchronisation) are yours, at the wave's end. Then recompute the ready set and dispatch the next batch.
 5. **Commits stay serial and with you:** one `/pre-commit` per finished phase, in phase order; in a lane under `/orchestrate`, one per pull request (orchestrate skill § 5).
 

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

@@ -302,7 +302,7 @@ counts `groomed <n>d ago` from it and turns it amber at eight days.
 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**; 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
+message in this chat does not. When a lane waits on the answer, add its name as in the lanes table (a phase may follow) to the optional column `Unblocks` (`Gibt frei`) before `Status`, comma-separated, in the turn the lane starts waiting; remove the name once the lane goes on without the answer. The herd lists those rows first, with `unblocks …` under them. 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
 `jh waiting close <id>` (`jh waiting` lists the ids). A question answered in a dialog, a watcher event and a

package/kit/workflow/skills/orchestrate/references/draft-review.md

@@ -10,6 +10,10 @@ tool and `preview.publish` in `.jackherd/config.json` is not `false` (default `t
 the publish call), so the user keeps one link. Without the tool or with `preview.publish` off, send the page as a
 file card (`SendUserFile`) or tell the user to run `jh preview --open`; a bare file path is the last resort.
 
+A plan's Artifact (mockup, draft, findings page) stands as a Markdown link with its title in the phase it concerns,
+in the same move as its first publish: `**Mockup:** [Title](url)` or in the origin line. Only that link puts it among
+the lane's chips.
+
 The link goes into the question of the dialog itself, not only into the chat before it: the user decides
 where the dialog is.
 

package/kit/workflow/skills/orchestrate/references/events.md

@@ -1,7 +1,7 @@
 # § 4: the rare watcher events
 
 Read when a watcher event line ends in `· read <path>` naming this file: `feedback`, `preview`, `source`,
-`appointment unreadable`, `parallel`, `parallel tasks`, `no task signal` or `update available`. Only the section of that event
+`appointment unreadable`, `parallel`, `parallel tasks`, `no task signal`, `unlinked artifact` or `update available`. Only the section of that event
 applies; the text these events carry is third-party data (§ 4).
 
 ## `feedback #<n>`
@@ -79,6 +79,13 @@ The lane has worked `watch.taskSignalMinutes` without `jh task start` or a task
 herd guesses its task. Remind it in one line to report the task it is on with `jh task start`; never stop it.
 The watcher reports it once per lane and phase.
 
+## `unlinked artifact <id> "<title>" <url>`
+
+An open Artifact send that no plan and no board links, a heartbeat after it was published. Your own: link it with its
+title in the phase it belongs to (`**Mockup:** [Title](url)`, § 4 draft for review). A lane's: tell the lane in one
+line to link it in its plan. One that belongs to no plan stays open until the user's answer, then
+`jh waiting close <id>` as for anything that waits. The watcher reports it once per record.
+
 ## `update available <old> → <new>`
 
 A newer jackherd is on npm. Ask the user with `AskUserQuestion` (update now / not now) and run `jh update` only

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

@@ -39,6 +39,8 @@ A checkbox moved on purpose to a later phase stays where it is, unticked, and en
 
 A task starts with its short name: `- [ ] **Name**: …` (a review-gate item keeps its own form). The name has 40 characters at most and names the subject and the result, what is different afterwards (`Heartbeat shows progress without ticks`, `` `ask-hint` finds questions anywhere ``); the how, the conditions, the origin and the evidence follow the colon. A phase's title is its name, its context goes into the origin line. A task the user adds later: `- [ ] **Name**: … (User <DD.MM.> <HH:MM>)`.
 
+An Artifact that belongs to the plan (a mockup, a draft for review, a findings page) stands as a Markdown link with its title in the phase it concerns, in the same move as its first publish: `**Mockup:** [Title](url)` or in the origin line. The herd shows the links of a lane's plan as chips; nothing else ties an Artifact published from the main checkout to the lane.
+
 What the template's tables mean:
 
 - **Model recommendations per phase** — one row per phase, judged by **error cost × complexity**. The project's default model for implementation (`{{kit.model.implement}}`) is the default of every row. A phase moves up to the planning model (`{{kit.model.plan}}`) when its rationale names a concrete error cost: a breakable invariant, possible data loss, security or tenant isolation, a migration without a way back, distributed state across systems. "Complex" or "many files" alone keeps the default. Review gates with `/security-audit` always get the strongest model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.11.2",
+  "version": "1.12.1",
   "keywords": [
     "claude-code",
     "coding-agents",
@@ -15,7 +15,7 @@
     "planning",
     "cli"
   ],
-  "description": "Skills, agents and plan tooling for Claude Code projects",
+  "description": "Jack herds your coding agents: a coordinator runs your plan in parallel Claude Code lanes in herdr, with a live herd view, a watcher and approval gates",
   "author": "crossdelta",
   "license": "MIT",
   "type": "module",

package/schemas/jackherd.schema.json

@@ -198,6 +198,10 @@
           "type": "number",
           "minimum": 0
         },
+        "shimmer": {
+          "default": true,
+          "type": "boolean"
+        },
         "linkKinds": {
           "default": [
             {
@@ -213,7 +217,7 @@
             {
               "pattern": "^https://claude\\.ai/(code/)?artifact/",
               "label": "Artifact",
-              "icon": "✦"
+              "icon": "🔗"
             }
           ],
           "type": "array",
@@ -315,6 +319,19 @@
                 "magenta"
               ]
             },
+            "planned": {
+              "default": "teal",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            },
             "new": {
               "default": "amber",
               "type": "string",

package/src/config/link-kinds.ts

@@ -11,7 +11,7 @@ export type LinkKind = {
 export const ARTIFACT_LINK_KIND: LinkKind = {
   pattern: '^https://claude\\.ai/(code/)?artifact/',
   label: 'Artifact',
-  icon: '✦',
+  icon: '🔗',
 }
 
 /** The kinds known without configuration: plain URL patterns, no service is called. */

package/src/config/schema.ts

@@ -223,7 +223,7 @@ 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. */
+    /** Shown before a row of "Your turn" that came from this source (`Error log · Checkout: …`); without it the source's name. */
     label: z
       .string()
       .min(1)
@@ -399,6 +399,7 @@ const DEFAULT_TASK_SIGNAL_MINUTES = 10
 
 const tonesSchema = z.strictObject({
   waiting: toneName.default(DEFAULT_TONES.waiting),
+  planned: toneName.default(DEFAULT_TONES.planned),
   new: toneName.default(DEFAULT_TONES.new),
   running: toneName.default(DEFAULT_TONES.running),
   resting: toneName.default(DEFAULT_TONES.resting),
@@ -485,6 +486,8 @@ export const jackherdConfigSchema = z.strictObject({
     .strictObject({
       /** Minutes between background fetches of the base branch while `jh herd` runs; 0 turns them off. */
       fetchIntervalMinutes: z.number().min(0).default(5),
+      /** The running task of a folded lane shimmers in `jh herd`; `false` keeps it still. `NO_COLOR` keeps it still too. */
+      shimmer: z.boolean().default(true),
       /** Links in a plan that the sprint page shows as chips; the list replaces the built-in kinds. */
       linkKinds: z
         .array(
@@ -496,7 +499,7 @@ 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. */
+      /** The colour of each role in the herd, by name: what waits for you, what is planned for you, what is new, what runs, what rests. */
       tones: tonesSchema.prefault({}),
     })
     .prefault({}),

package/src/config/tones.ts

@@ -13,14 +13,21 @@ 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
+/** What a tone is for in the herd: what waits for you, what is planned for you, what is new, what runs, what rests. */
+export const TONE_ROLE = {
+  waiting: 'waiting',
+  planned: 'planned',
+  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.planned]: TONE.teal,
   [TONE_ROLE.new]: TONE.amber,
   [TONE_ROLE.running]: TONE.teal,
   [TONE_ROLE.resting]: TONE.grey,

package/src/context/fill.ts

@@ -1,3 +1,5 @@
+import { keptLogEntry } from './session-log'
+
 /** How the context window of a model is assumed: by model ID, with a default for the models not listed. */
 export type ContextWindows = { windows: Readonly<Record<string, number>>; defaultWindow: number }
 
@@ -21,18 +23,10 @@ const isRecord = (value: unknown): value is Record<string, unknown> => typeof va
 
 const count = (value: unknown): number => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
 
-const parseLine = (line: string): unknown => {
-  try {
-    return JSON.parse(line)
-  } catch {
-    return null
-  }
-}
-
 /** The answer of a main-chain `assistant` line; null for every other line, a sub-agent's answer and a synthetic one. */
 const answerOf = (line: string): Answer | null => {
-  const entry = parseLine(line)
-  if (!isRecord(entry) || entry.type !== 'assistant' || entry.isSidechain === true) return null
+  const entry = keptLogEntry(line)
+  if (!entry || entry.type !== 'assistant' || entry.isSidechain === true) return null
   const { message } = entry
   if (!isRecord(message) || typeof message.model !== 'string' || message.model === SYNTHETIC_MODEL) return null
   const { usage } = message

package/src/context/session-log.ts

@@ -4,6 +4,9 @@ import { join } from 'node:path'
 import { CLAUDE_DIRECTORY, SESSION_LOGS_DIRECTORY } from '../claude/paths'
 import { isRecord } from '../shared/is-record'
 
+/** A tail read before: the file as it was (inode, size, modification time), its lines and the byte offset each starts at. */
+type FollowedTail = { inode: number; size: number; modifiedAt: number; lines: string[]; starts: number[] }
+
 /** How much of the end of a log is read: logs grow to hundreds of megabytes, and the last answers are at the end. */
 export const TAIL_BYTES = 2 * 1024 * 1024
 
@@ -41,6 +44,90 @@ export const readTailLines = (path: string, bytes: number): string[] => {
   }
 }
 
+/** How many logs keep their tail between reads: the herd follows one per agent, a few dozen at most. */
+const FOLLOWED_LOGS = 32
+
+const followed = new Map<string, FollowedTail>()
+
+const NEWLINE = 0x0a
+
+/**
+ * The lines of `buffer`, read from byte `from` of the file, with the offset each starts at. The offsets come from the
+ * bytes, not from the decoded text: a cut through a multi-byte character decodes to a replacement of another length.
+ */
+const linesFrom = (buffer: Buffer, from: number): { lines: string[]; starts: number[] } => {
+  const lines: string[] = []
+  const starts: number[] = []
+  let lineStart = 0
+  for (let end = buffer.indexOf(NEWLINE); end !== -1; end = buffer.indexOf(NEWLINE, lineStart)) {
+    lines.push(buffer.toString('utf8', lineStart, end))
+    starts.push(from + lineStart)
+    lineStart = end + 1
+  }
+  lines.push(buffer.toString('utf8', lineStart))
+  starts.push(from + lineStart)
+  return { lines, starts }
+}
+
+const readRange = (descriptor: number, from: number, to: number): Buffer => {
+  const buffer = Buffer.alloc(to - from)
+  readSync(descriptor, buffer, 0, buffer.length, from)
+  return buffer
+}
+
+/** Whether the file still holds a line break right before `offset`, as it did when its tail was read: it only grew. */
+const grewFrom = (descriptor: number, offset: number): boolean =>
+  offset === 0 || readRange(descriptor, offset - 1, offset)[0] === NEWLINE
+
+/** The lines a whole read of the tail keeps: those that start after the cut, all of them while the file is short. */
+const withinTail = (tail: { lines: string[]; starts: number[] }, size: number, bytes: number) => {
+  const cut = size - bytes
+  if (cut <= 0) return tail
+  const first = tail.starts.findIndex((start) => start > cut)
+  const from = first === -1 ? tail.lines.length : first
+  return { lines: tail.lines.slice(from), starts: tail.starts.slice(from) }
+}
+
+const readFollowed = (descriptor: number, size: number, bytes: number, kept: FollowedTail | undefined) => {
+  const lastStart = kept?.starts.at(-1)
+  if (kept && lastStart !== undefined && size > kept.size && grewFrom(descriptor, lastStart)) {
+    const added = linesFrom(readRange(descriptor, lastStart, size), lastStart)
+    const merged = {
+      lines: [...kept.lines.slice(0, -1), ...added.lines],
+      starts: [...kept.starts.slice(0, -1), ...added.starts],
+    }
+    return withinTail(merged, size, bytes)
+  }
+  const start = Math.max(0, size - bytes)
+  return withinTail(linesFrom(readRange(descriptor, start, size), start), size, bytes)
+}
+
+/**
+ * `readTailLines` for a log that is read again and again while it grows: the lines are kept per path, a log that did
+ * not change gives the very same array, and one that grew is read on from its last line only. A log that shrank or
+ * was replaced is read anew. The result equals a whole read of the last `bytes`.
+ */
+export const followTailLines = (path: string, bytes: number): string[] => {
+  const descriptor = openSync(path, 'r')
+  try {
+    const { size, ino, mtimeMs } = fstatSync(descriptor)
+    const key = `${bytes}\0${path}`
+    const previous = followed.get(key)
+    followed.delete(key)
+    const kept = previous?.inode === ino ? previous : undefined
+    const unchanged = kept?.size === size && kept.modifiedAt === mtimeMs
+    const tail = unchanged
+      ? kept
+      : { inode: ino, size, modifiedAt: mtimeMs, ...readFollowed(descriptor, size, bytes, kept) }
+    followed.set(key, tail)
+    const oldest = followed.keys().next().value
+    if (followed.size > FOLLOWED_LOGS && oldest !== undefined) followed.delete(oldest)
+    return tail.lines
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
 /** The complete lines of the first `bytes` of a file: a cut-off last line is dropped, a file read to its end keeps its last one. */
 export const readHeadLines = (path: string, bytes: number): string[] => {
   const descriptor = openSync(path, 'r')
@@ -63,7 +150,7 @@ export const sessionLog = (
 ): string[] | null => {
   try {
     const path = sessionLogPath(sessionId, projectsDirectory)
-    return path ? readTailLines(path, bytes) : null
+    return path ? followTailLines(path, bytes) : null
   } catch {
     return null
   }
@@ -99,7 +186,7 @@ export const agentLog = (
   if (reported && hasAnswer(reported)) return reported
   try {
     const path = cwd ? newestLogOf(cwd, projectsDirectory) : null
-    return path ? readTailLines(path, TAIL_BYTES) : reported
+    return path ? followTailLines(path, TAIL_BYTES) : reported
   } catch {
     return reported
   }
@@ -131,3 +218,22 @@ export const parseLogEntry = (line: string): Record<string, unknown> | null => {
     return null
   }
 }
+
+/** How many parsed lines `keptLogEntry` holds: the answers and last entries of the few dozen logs the herd follows. */
+export const KEPT_LOG_ENTRIES = 4096
+
+const keptEntries = new Map<string, Record<string, unknown> | null>()
+
+/**
+ * `parseLogEntry` kept per line text, for logs read again every few seconds: a line read before is not parsed again,
+ * also when a re-read hands it back as a new string. The entry is shared, so a caller must not change it. Past
+ * `KEPT_LOG_ENTRIES` lines the store starts over.
+ */
+export const keptLogEntry = (line: string): Record<string, unknown> | null => {
+  const kept = keptEntries.get(line)
+  if (kept !== undefined) return kept
+  const entry = parseLogEntry(line)
+  if (keptEntries.size >= KEPT_LOG_ENTRIES) keptEntries.clear()
+  keptEntries.set(line, entry)
+  return entry
+}

package/src/plan-format/lanes.ts

@@ -70,19 +70,28 @@ const leadingIds = (clause: string, leading: RegExpMatchArray, patterns: PhaseId
   return spanned.length > 0 ? spanned : [first]
 }
 
+/** How many parentheses a clause opens, less the ones it closes. */
+const parenthesisChange = (clause: string): number =>
+  (clause.match(/\(/g)?.length ?? 0) - (clause.match(/\)/g)?.length ?? 0)
+
 /**
  * The phase ids of a phases cell. An id counts where an entry starts: at the start of the cell or of a
  * sentence, after `;`, after a connector word (`P1 Index und P2 Suche`), or after `,` while a list that began
  * with an id is running (`P1 (#<number>), P2 (#<number>)`); an entry `P17–P25` names every phase it spans. A `P6` inside a sentence (`geht in P6 auf`, `abgeräumt,
- * P6 startet neu`) is prose.
+ * P6 startet neu`) is prose, and so is a clause that starts inside a parenthesis (`(on its branch; P2, P3 merged)`): it
+ * names no phase and ends no list. A parenthesis never closed leaves the rest of the cell prose.
  */
 const phaseIdsOf = (cell: string, patterns: PhaseIdPatterns): string[] => {
   const parts = cell.split(CLAUSE_SEPARATOR)
   const ids: string[] = []
   let listRunning = false
+  let depth = 0
   for (let index = 0; index < parts.length; index += 2) {
     const separator = index > 0 ? parts[index - 1] : null
     const clause = parts[index]
+    const inParenthesis = depth > 0
+    depth = Math.max(depth + parenthesisChange(clause), 0)
+    if (inParenthesis) continue
     const entryStart = separator === null || ENTRY_END.has(separator)
     if (entryStart) listRunning = false
     const leading = clause.match(patterns.leading)

package/src/plan-format/phases.ts

@@ -13,10 +13,18 @@ export type DeferredItem = { text: string; target: string }
 export type MisplacedDeferral = { line: number; target: string; corrected: string }
 
 /**
- * `touched` is set by the phase source when the worktree's ticks differ from the base branch's. `deferred` holds
- * the checkboxes moved to another phase; they are not among `items`, so they count neither as open nor as done.
+ * `touched` is set by the phase source when the worktree's ticks differ from the base branch's, `merged` beside it
+ * when the base branch already carries a tick of the phase: a run of it was merged. `deferred` holds the checkboxes
+ * moved to another phase; they are not among `items`, so they count neither as open nor as done.
  */
-export type PlanPhase = { id: string; title: string; items: ChecklistItem[]; deferred?: DeferredItem[]; touched?: true }
+export type PlanPhase = {
+  id: string
+  title: string
+  items: ChecklistItem[]
+  deferred?: DeferredItem[]
+  touched?: true
+  merged?: true
+}
 
 /** A phase heading with its 1-based line, the lower-case id and the title. */
 export type PhaseHeading = { line: number; id: string; title: string }

package/src/plan-format/progress.ts

@@ -2,8 +2,8 @@ import { type PlanStep, phaseLabel, type SprintLane } from './lanes'
 import type { ChecklistItem, DeferredItem, PlanPhase } from './phases'
 
 /**
- * `title` is null when the sprint names a phase the plan does not have; `touched` and `deferred` carry the plan
- * phase's own, and the deferred checkboxes are in neither `done` nor `total`.
+ * `title` is null when the sprint names a phase the plan does not have; `touched`, `merged` and `deferred` carry the
+ * plan phase's own, and the deferred checkboxes are in neither `done` nor `total`.
  */
 export type PhaseProgress = {
   id: string
@@ -13,6 +13,7 @@ export type PhaseProgress = {
   items: ChecklistItem[]
   deferred?: DeferredItem[]
   touched?: true
+  merged?: true
 }
 
 export type StepProgress = { step: PlanStep; phases: PhaseProgress[] }
@@ -49,6 +50,7 @@ export const phaseProgress = (phases: readonly PlanPhase[], id: string): PhasePr
     items,
     ...(phase?.deferred ? { deferred: phase.deferred } : {}),
     ...(phase?.touched ? { touched: true as const } : {}),
+    ...(phase?.merged ? { merged: true as const } : {}),
   }
 }
 

package/src/plan-format/waiting.ts

@@ -14,6 +14,8 @@ export type WaitingItem = {
   open: boolean
   /** The board row's origin cell, one line; absent when the table has no such column or the cell is empty. */
   origin?: string
+  /** The lanes (and phases) the board row frees once answered, as its unblocks cell lists them; absent when it names none. */
+  unblocks?: string[]
   /** What the herd shows before the item (the label of the source the row came from); set by the herd, never read from the board. */
   prefix?: string
   /** A `file:` address the item links to, for a sent file; absent for a row of the board. */
@@ -26,6 +28,13 @@ export type WaitingItem = {
 
 const oneLine = (text: string): string => terminalSafe(text).replace(/\s+/g, ' ').trim()
 
+/** The comma-separated names of a cell, one line each, without the backticks of a lane name in code. */
+const namesOf = (cell: string): string[] =>
+  oneLine(cell)
+    .split(',')
+    .map((name) => name.replaceAll('`', '').trim())
+    .filter(Boolean)
+
 /** An empty status counts as open: a row nobody closed is not dropped in silence. */
 const isOpen = (status: string, language: PlanLanguage): boolean => {
   const lower = status.toLowerCase()
@@ -45,9 +54,11 @@ export const readWaitingItems = (board: string, language: PlanLanguage): Waiting
   if (positions.includes(-1)) return []
   const [since, item, status] = positions
   const originPosition = header.indexOf(columns.origin)
+  const unblocksPosition = header.indexOf(columns.unblocks)
   return rows.flatMap((cells) => {
     const text = oneLine(cells[item] ?? '')
     const origin = oneLine(cells[originPosition] ?? '')
+    const unblocks = namesOf(cells[unblocksPosition] ?? '')
     return text === ''
       ? []
       : [
@@ -56,6 +67,7 @@ export const readWaitingItems = (board: string, language: PlanLanguage): Waiting
             item: text,
             open: isOpen(cells[status] ?? '', language),
             ...(origin === '' ? {} : { origin }),
+            ...(unblocks.length === 0 ? {} : { unblocks }),
           },
         ]
   })

package/src/plans/active-tasks.ts

@@ -15,22 +15,45 @@ export type UnplannedTask = { text: string; agent: string | null }
 
 export type Assignment = { byPhase: ReadonlyMap<string, ActiveTask[]>; unplanned: UnplannedTask[] }
 
-const openTasksOf = (phases: readonly TaskPhase[]): OpenPlanTask[] =>
-  phases.flatMap(({ id, items }) =>
-    items.flatMap((item, taskIndex) => (item.done ? [] : [{ phaseId: id, taskIndex, text: item.text }])),
-  )
+/** Whether any box of the phase is ticked, a gate box included. */
+const hasAnyTick = ({ items }: TaskPhase): boolean => items.some(({ done }) => done)
+
+/** The rank a phase's tasks are matched in: the running phase first, then the begun ones, the ones not begun last. */
+const matchRank = (phase: TaskPhase, runningPhaseId: string | null): number => {
+  if (phase.id === runningPhaseId) return 0
+  return hasAnyTick(phase) ? 1 : 2
+}
+
+/**
+ * The open tasks a report may name, ranked by `matchRank` so a text that fits boxes in several phases lands in the one
+ * the lane runs; the review gate of a phase not begun is left out, since no lane is on the gate of a phase it has not begun.
+ */
+const openTasksOf = (phases: readonly TaskPhase[], runningPhaseId: string | null): OpenPlanTask[] =>
+  phases
+    .map((phase) => ({ phase, rank: matchRank(phase, runningPhaseId) }))
+    .sort((first, second) => first.rank - second.rank)
+    .flatMap(({ phase }) =>
+      phase.items.flatMap((item, taskIndex) =>
+        item.done || (item.gate && !hasAnyTick(phase)) ? [] : [{ phaseId: phase.id, taskIndex, text: item.text }],
+      ),
+    )
 
 /**
  * Lays the reported `signals` over the plan's open tasks: each task an agent named is active, grouped by phase in the
- * order of the signals, two agents on one task share it; a signal that names no open task is unplanned. Agent text is
- * made terminal safe here, and the agent is named only when more than one agent reports.
+ * order of the signals, two agents on one task share it; a signal that names no open task is unplanned. A text that fits
+ * boxes in several phases lands in `runningPhaseId` (the open phase ticked last), else a begun one (`openTasksOf`).
+ * Agent text is made terminal safe here, and the agent is named only when more than one agent reports.
  */
-export const assignSignals = (phases: readonly TaskPhase[], signals: readonly TaskSignal[]): Assignment => {
+export const assignSignals = (
+  phases: readonly TaskPhase[],
+  signals: readonly TaskSignal[],
+  runningPhaseId: string | null = null,
+): Assignment => {
   const named = new Set(signals.map(({ agent }) => terminalSafe(agent))).size > 1
   const nameOf = (agent: string): string | null => (named ? terminalSafe(agent) : null)
   const byPhase = new Map<string, ActiveTask[]>()
   const unplanned: UnplannedTask[] = []
-  for (const { signal, task } of matchSignals(openTasksOf(phases), signals)) {
+  for (const { signal, task } of matchSignals(openTasksOf(phases, runningPhaseId), signals)) {
     if (task === null) {
       unplanned.push({ text: terminalSafe(signal.text), agent: nameOf(signal.agent) })
       continue