jackherd 1.6.1 → 1.7.1

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

@@ -33,16 +33,16 @@ Skip this when the request already carries its decisions (a plan for a bug fix w
 
 **Structure:** copy the template in [`references/template-{{kit.planLanguage}}.md`](references/template-{{kit.planLanguage}}.md) and fill it in. Every section stays, in its order, with its heading verbatim.
 
-The closing documentation section reads `## N — …` with rows `N.1` to `N.5`: replace `N` with the number of that phase (`## 10 — …`, `10.1`). A literal `N` is no phase to the plans view, which shows it as "not in the plan".
+The closing documentation section reads `## N — …` with rows `N.1` to `N.5`: replace `N` with the number of that phase (`## 10 — …`, `10.1`). A literal `N` is no phase to the herd, which shows it as "not in the plan".
 
-A checkbox moved on purpose to a later phase stays where it is, unticked, and ends in the target: `- [ ] Update the documentation → P9`. The plans view counts it neither as open nor as done in its own phase and lists it as open in phase 9, so a phase whose only open box was moved on reads as finished. The arrow counts only at the end of the line; `jh check` refuses an open box in a changed plan that carries it anywhere else (`- [ ] → P9 Update …`). Once a phase's tasks are ticked on the base branch and the change does not tick it further, every box still open in it, gate boxes included, is ticked or moved on this way: `jh check` warns on a changed plan that leaves one.
+A checkbox moved on purpose to a later phase stays where it is, unticked, and ends in the target: `- [ ] Update the documentation → P9`. The herd counts it neither as open nor as done in its own phase and lists it as open in phase 9, so a phase whose only open box was moved on reads as finished. The arrow counts only at the end of the line; `jh check` refuses an open box in a changed plan that carries it anywhere else (`- [ ] → P9 Update …`). Once a phase's tasks are ticked on the base branch and the change does not tick it further, every box still open in it, gate boxes included, is ticked or moved on this way: `jh check` warns on a changed plan that leaves one.
 
 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.
 - **Dependencies and parallelization** (from three phases) — `/implement` reads it and starts every phase whose dependencies are done and that shares no written path with another, at the same time.
   - **{{kit.heading.dependsOn}}:** phases of this plan (numbers) or external gates (`User: mockups`). A phase is ready when everything here is done.
-  - **{{kit.heading.writes}}:** the directories or files the phase creates or changes, as narrow as possible. Shared files many phases touch (barrels, translation files, `package.json`, generated types, architecture docs) are listed explicitly, so the overlap is visible.
+  - **{{kit.heading.writes}}:** the directories or files the phase creates or changes, as narrow as possible. Shared files many phases touch (barrels, translation files, `package.json`, generated types, architecture docs) are listed explicitly, so the overlap is visible. Write each path in full from the repository root: paths are compared as written, so `src/watch/` and `packages/app/src/watch/` do not overlap.
   - **{{kit.heading.serialMarker}}:** `Migration`, `<collection> schema bump`, `Event <type>`, a generator run. Two phases with a migration never run at the same time; neither do two that bump the same schema.
 
 ### 3. Architecture Review
@@ -66,7 +66,7 @@ Every phase gets the review gate block from the template at its end. Add the rev
 - **Shared code checked:** For every planned component it is documented why it is built new instead of reused or extended.
 - **Tests defined:** The tests section is filled in or carries an explicit rationale why none are needed (decision tree in `.claude/rules/kit/testing.md`).
 - **Model recommendations defined:** `## {{kit.heading.implementation}}` starts with the model table, one row per phase, justified by error cost × complexity.
-- **Parallelism defined (3+ phases):** the dependencies table follows it. Check it against the phase bodies: every migration, schema bump and new event in a phase appears as a serial marker; every shared file appears under {{kit.heading.writes}}. A dependency that exists only in your head lets `/implement` start two phases that collide.
+- **Parallelism defined (3+ phases):** the dependencies table follows it. Check it against the phase bodies: every migration, schema bump and new event in a phase appears as a serial marker; every shared file appears under {{kit.heading.writes}}. A dependency that exists only in your head lets `/implement` start two phases that collide. Every phase gets a row, a phase added later too: `jh check` warns about a phase without one.
 - **arc42 check (after the plan exists):** apply the filter in `.claude/rules/kit/arc42.md` to the finished plan and **ask the user concretely** which sections should be extended. On "yes", add a concrete task to `## {{kit.heading.documentation}}`.
 - **Architecture check (after the plan exists):** apply the filter in `.claude/rules/kit/architecture-files.md` — new ownership, a new invariant or an accepted risk each trigger a concrete question about the unit's `ARCHITECTURE.md`.
 - **arc42 closing phase (3+ phases or a new service/package):** end the plan with the architecture documentation phase from the template. Add arc42 sections beyond it only when they deliver real value.
@@ -97,7 +97,7 @@ Derive the rows from the dependencies table and the model table, nothing else:
 - **Port:** `–`; the coordinator sets it when the lane starts, unless the project supplement assigns ports here.
 
 Show the rows as the table they become: `## {{kit.heading.lanes}}` with the columns lane, port, plan, phases, starts
-after, model, in this order and headed in {{kit.planLanguage}} (the plans view reads them by position). Then ask
+after, model, in this order and headed in {{kit.planLanguage}} (the herd reads them by position). Then ask
 where they go:
 
 - **The newest board**, by name: the newest `{{kit.planDirectory}}/{{kit.board.pattern}}/{{kit.board.file}}`. The

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

@@ -14,7 +14,7 @@ Show this to the user, shortened to what fits on one screen:
 
 - Describe a task. `/plan` writes the plan in `{{kit.planDirectory}}/` and, when asked, a board for parallel lanes.
 - Build it in one session with `/implement`, or run the board's lanes side by side with `/orchestrate` inside herdr.
-- Follow progress with `jh plans`. Inside herdr, `/orchestrate` opens the plan view in a herdr pane beside the coordinator and beside each lane.
+- Follow progress with `jh herd`. Inside herdr, `/orchestrate` opens the herd in a herdr pane beside the coordinator and beside each lane.
 - `/follow <item>` has the watcher report changes of a ticket, issue or status page outside GitHub.
 - herdr is optional, needed only for parallel lanes. The first setup (`jh init`, which the installer runs) offers its installer when it is missing, on Linux and macOS and only when it can ask.
 
@@ -36,7 +36,7 @@ Report a short list, one line per item, marked present or missing. For each miss
 - Session outside herdr: start Claude Code from a herdr pane.
 - `gh`: install the GitHub CLI (`gh`), then run `gh auth login`.
 
-State plainly that herdr is only needed to run parallel lanes with `/orchestrate`. `/plan`, `/implement` and `jh plans` work without it.
+State plainly that herdr is only needed to run parallel lanes with `/orchestrate`. `/plan`, `/implement` and `jh herd` work without it.
 
 ## 3. Offer the first step
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "keywords": [
     "claude-code",
     "coding-agents",
@@ -45,8 +45,11 @@
     "!src/test-support",
     "schemas",
     "docs",
+    "!docs/gen",
     "assets",
+    "!assets/icons/build.ts",
     "README.md",
+    "INSTALL.md",
     "CHANGELOG.md",
     "LICENSE",
     "NOTICE",

package/schemas/jackherd.schema.json

@@ -317,9 +317,7 @@
           "additionalProperties": false
         },
         "feedback": {
-          "default": {
-            "ignore": []
-          },
+          "default": {},
           "anyOf": [
             {
               "type": "boolean",
@@ -335,12 +333,34 @@
                     "type": "string",
                     "minLength": 1
                   }
+                },
+                "noFindingTemplates": {
+                  "default": [
+                    "## Code review\n\nNo issues found. Checked for bugs and CLAUDE.md compliance."
+                  ],
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
                 }
               },
               "additionalProperties": false
             }
           ]
         },
+        "checks": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "failedTestPattern": {
+              "default": "^\\(fail\\) (.+?)(?: \\[[\\d.]+m?s\\])?$",
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        },
         "previews": {
           "type": "object",
           "properties": {
@@ -410,11 +430,13 @@
                   },
                   "author": {
                     "type": "string"
+                  },
+                  "status": {
+                    "type": "string"
                   }
                 },
                 "required": [
-                  "id",
-                  "updatedAt"
+                  "id"
                 ],
                 "additionalProperties": {
                   "type": "string"
@@ -438,6 +460,9 @@
                 "type": "string",
                 "minLength": 1
               },
+              "ticket": {
+                "type": "boolean"
+              },
               "reportOn": {
                 "minItems": 1,
                 "maxItems": 10,
@@ -490,6 +515,19 @@
             }
           },
           "additionalProperties": false
+        },
+        "approvals": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "waitMinutes": {
+              "default": 8,
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 9
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/src/check/command.ts

@@ -1,13 +1,14 @@
 import { spawnSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import { findProjectRoot, globalConfigPath, locateConfigFile } from '../config/location'
 import { readRepositoryFacts } from '../config/repository-facts'
 import { baseRefOf } from '../plans/settings'
 import { type ChangedFile, parsePorcelain, STATUS_COMMAND } from './changes'
 import { deferralArrowCheck } from './deferral-arrows'
 import { runCheck, runProcess } from './execute'
+import { parallelArgument, parallelReportLines } from './parallel-report'
 import { type CheckPlan, type Filesystem, isSlow, planChecks } from './plan'
 import { planStructureChecks } from './plan-structure-check'
 import { publicContentCheck } from './public-content-check'
@@ -69,6 +70,26 @@ const loadSettings = (configPath: string, root: string): CheckSettings | string
   }
 }
 
+const readPlanFile = (file: string): string | null => {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/** `jh check --parallel <plan>`: the groups of phases that can run side by side, read from the plan as it is on disk. */
+const printParallel = (path: string, settings: CheckSettings): number => {
+  const file = resolve(process.cwd(), path)
+  const markdown = path === '' ? null : readPlanFile(file)
+  if (markdown === null) {
+    console.error(`--parallel needs the path of a readable plan file, got "${path}"`)
+    return 1
+  }
+  print(parallelReportLines(markdown, settings.planLanguage))
+  return 0
+}
+
 const changedFiles = async (root: string): Promise<ChangedFile[] | string> => {
   const status = await runProcess(STATUS_COMMAND, root)
   return status.ok ? parsePorcelain(status.output) : status.output
@@ -91,7 +112,7 @@ const executePlan = async (
 
 /**
  * Runs the configured checks over the files `git status` reports. Exit code 1 when any check fails
- * or the configuration cannot be read.
+ * or the configuration cannot be read. With `--parallel <plan>` it runs no check and prints the plan's parallel groups.
  */
 export const run = async (args: string[], home: string = homedir()): Promise<number> => {
   const target = resolveCheckTarget(process.cwd(), home, existsSync, gitTopLevelOf)
@@ -101,9 +122,15 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
   }
   const { root, configPath } = target
   const settings = loadSettings(configPath, root)
+  if (typeof settings === 'string') {
+    console.error(settings)
+    return 1
+  }
+  const parallel = parallelArgument(args)
+  if (parallel !== null) return printParallel(parallel, settings)
   const files = await changedFiles(root)
-  if (typeof settings === 'string' || typeof files === 'string') {
-    console.error(typeof settings === 'string' ? settings : files)
+  if (typeof files === 'string') {
+    console.error(files)
     return 1
   }
   print(settings.notes)

package/src/check/deferral-arrows.ts

@@ -23,7 +23,7 @@ const deferralArrowResult = (findings: readonly DeferralFinding[], plans: number
 })
 
 /**
- * Open checkboxes in the changed plans whose `→ P<n>` is not at the end of the line, where the plans view reads
+ * Open checkboxes in the changed plans whose `→ P<n>` is not at the end of the line, where the herd reads
  * it. Plans outside the diff are not read. Null when no plan changed.
  */
 export const deferralArrowCheck = (

package/src/check/parallel-report.ts

@@ -0,0 +1,23 @@
+import { parallelGroupsOfPlan, phasesText } from '../plan-format'
+import type { PlanLanguage } from '../vocabulary'
+
+/** The flag by which `jh check` prints the parallel groups of one plan instead of running the checks. */
+export const PARALLEL_FLAG = '--parallel'
+
+/** The plan path after `--parallel`: empty when it is missing, null when the flag is absent. */
+export const parallelArgument = (args: readonly string[]): string | null => {
+  const index = args.indexOf(PARALLEL_FLAG)
+  return index === -1 ? null : (args[index + 1] ?? '')
+}
+
+/**
+ * What `jh check --parallel <plan>` prints: one line per group of phases that can run side by side (the first group
+ * can start now), or the reason there is none.
+ */
+export const parallelReportLines = (markdown: string, language: PlanLanguage): string[] => {
+  const groups = parallelGroupsOfPlan(markdown, language)
+  if (groups === null) return ['no dependency table']
+  return groups.length === 0
+    ? ['no phase is ready']
+    : groups.map((group, index) => `group ${index + 1}: ${phasesText(group)}`)
+}

package/src/check/plan-structure-check.ts

@@ -2,15 +2,21 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import {
   boardRowsWithoutPhase,
+  boardRowsWithProse,
   hasLanesTable,
   type MergedPhaseWithOpenBoxes,
   mergedPhasesWithOpenBoxes,
   newPhasesWithoutReviewGate,
+  PHASE_CELL_LIMIT,
   type PhaseWithoutGate,
+  type PhaseWithoutRow,
   PLAN_VOCABULARY,
   type PlanLanguage,
+  PROSE_REASON,
   phaseIdsOfPlan,
+  phasesWithoutDependencyRow,
   type RowWithoutPhase,
+  type RowWithProse,
 } from '../plan-format'
 import { changedPlansOf } from './deferral-arrows'
 import { CHECK_STATUS, type CheckResult } from './result'
@@ -31,60 +37,97 @@ export type PlanCheckInput = {
   baseOf: ContentAt
 }
 
-type Changed = { path: string; current: string; previous: string | null; base: string | null; board: boolean }
+type Changed = {
+  path: string
+  current: string
+  previous: string | null
+  previousLines: ReadonlySet<string>
+  base: string | null
+  board: boolean
+}
 
 type Found<T> = T & { path: string }
 
-const gateResult = (
-  findings: readonly Found<PhaseWithoutGate>[],
-  plans: number,
-  language: PlanLanguage,
+type Report<T> = {
+  name: string
+  noun: 'plan' | 'board'
+  /** What the check asks of each changed file, as the command column reads after the count. */
+  rule: string
+  /** The status of a check with findings. */
+  unmet: typeof CHECK_STATUS.fail | typeof CHECK_STATUS.warn
+  text: (found: Found<T>) => string
+  clean: string
+}
+
+const changedCount = (count: number, noun: string): string => `${count} changed ${count === 1 ? noun : `${noun}s`}`
+
+const findingsResult = <T>(
+  { name, noun, rule, unmet, text, clean }: Report<T>,
+  findings: readonly Found<T>[],
+  files: number,
   durationMs: number,
 ): CheckResult => ({
-  name: 'Plan review gates',
-  command: `${plans} changed ${plans === 1 ? 'plan' : 'plans'}, new phases need a review gate`,
-  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.fail,
-  detail:
-    findings
-      .map(
-        ({ path, line, id, title }) =>
-          `${path}:${line} Phase ${id} ${title} has tasks but no review gate; add one, or a **${PLAN_VOCABULARY[language].noReviewGate}:** line with the reason`,
-      )
-      .join('\n') || 'every new phase has a review gate',
+  name,
+  command: `${changedCount(files, noun)}, ${rule}`,
+  status: findings.length === 0 ? CHECK_STATUS.pass : unmet,
+  detail: findings.map(text).join('\n') || clean,
   durationMs,
 })
 
-const rowResult = (findings: readonly Found<RowWithoutPhase>[], boards: number, durationMs: number): CheckResult => ({
-  name: 'Board rows without a phase',
-  command: `${boards} changed ${boards === 1 ? 'board' : 'boards'}, changed lane rows name a phase`,
-  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.warn,
-  detail:
-    findings
-      .map(
-        ({ path, line, lane, phases }) =>
-          `${path}:${line} lane ${lane}: "${phases}" names no phase (P<n>), so the view cannot tie the step to one`,
-      )
-      .join('\n') || 'every changed lane row names a phase',
-  durationMs,
+const gateReport = (language: PlanLanguage): Report<PhaseWithoutGate> => ({
+  name: 'Plan review gates',
+  noun: 'plan',
+  rule: 'new phases need a review gate',
+  unmet: CHECK_STATUS.fail,
+  text: ({ path, line, id, title }) =>
+    `${path}:${line} Phase ${id} ${title} has tasks but no review gate; add one, or a **${PLAN_VOCABULARY[language].noReviewGate}:** line with the reason`,
+  clean: 'every new phase has a review gate',
 })
 
-const mergedResult = (
-  findings: readonly Found<MergedPhaseWithOpenBoxes>[],
-  plans: number,
-  durationMs: number,
-): CheckResult => ({
+const rowReport: Report<RowWithoutPhase> = {
+  name: 'Board rows without a phase',
+  noun: 'board',
+  rule: 'changed lane rows name a phase',
+  unmet: CHECK_STATUS.warn,
+  text: ({ path, line, lane, phases }) =>
+    `${path}:${line} lane ${lane}: "${phases}" names no phase (P<n>), so the herd cannot tie the step to one`,
+  clean: 'every changed lane row names a phase',
+}
+
+const proseText = ({ reason, length }: RowWithProse): string =>
+  reason === PROSE_REASON.sideOrder
+    ? 'the phase cell records a side order of the user'
+    : `the phase cell has ${length} characters (limit ${PHASE_CELL_LIMIT})`
+
+const proseReport: Report<RowWithProse> = {
+  name: 'Board rows with prose',
+  noun: 'board',
+  rule: 'changed lane rows name the phase only',
+  unmet: CHECK_STATUS.warn,
+  text: (found) =>
+    `${found.path}:${found.line} lane ${found.lane}: ${proseText(found)}; it belongs as a task in the plan`,
+  clean: 'every changed lane row names the phase only',
+}
+
+const mergedReport: Report<MergedPhaseWithOpenBoxes> = {
   name: 'Merged phases with open boxes',
-  command: `${plans} changed ${plans === 1 ? 'plan' : 'plans'}, a merged phase ticks or moves on its open boxes`,
-  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.warn,
-  detail:
-    findings
-      .map(
-        ({ path, line, id, title, openLines }) =>
-          `${path}:${line} Phase ${id} ${title} is merged but has open boxes at ${openLines.join(', ')}; tick them or end them with → P<n>`,
-      )
-      .join('\n') || 'no merged phase has an open box left',
-  durationMs,
-})
+  noun: 'plan',
+  rule: 'a merged phase ticks or moves on its open boxes',
+  unmet: CHECK_STATUS.warn,
+  text: ({ path, line, id, title, openLines }) =>
+    `${path}:${line} Phase ${id} ${title} is merged but has open boxes at ${openLines.join(', ')}; tick them or end them with → P<n>`,
+  clean: 'no merged phase has an open box left',
+}
+
+const unlistedReport: Report<PhaseWithoutRow> = {
+  name: 'Phases without a dependency row',
+  noun: 'plan',
+  rule: 'every phase has a row in the dependency table',
+  unmet: CHECK_STATUS.warn,
+  text: ({ path, line, id, title }) =>
+    `${path}:${line} Phase ${id} ${title} has no row in the dependency table; add one with its dependencies, writes and serial marker`,
+  clean: 'every phase has a row in the dependency table',
+}
 
 const withPath =
   <T>(path: string) =>
@@ -95,25 +138,38 @@ const gatesOf = ({ path, current, previous }: Changed, language: PlanLanguage):
     withPath(path),
   )
 
-const rowsOf = ({ path, current, previous }: Changed, language: PlanLanguage): Found<RowWithoutPhase>[] =>
-  boardRowsWithoutPhase(current, language, new Set(previous?.split('\n') ?? [])).map(withPath(path))
+const rowsOf = ({ path, current, previousLines }: Changed, language: PlanLanguage): Found<RowWithoutPhase>[] =>
+  boardRowsWithoutPhase(current, language, previousLines).map(withPath(path))
+
+const proseOf = ({ path, current, previousLines }: Changed, language: PlanLanguage): Found<RowWithProse>[] =>
+  boardRowsWithProse(current, language, previousLines).map(withPath(path))
 
 const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Found<MergedPhaseWithOpenBoxes>[] =>
   base ? mergedPhasesWithOpenBoxes(current, base, language).map(withPath(path)) : []
 
+const unlistedOf = ({ path, current }: Changed, language: PlanLanguage): Found<PhaseWithoutRow>[] | null =>
+  phasesWithoutDependencyRow(current, language)?.map(withPath(path)) ?? null
+
 const changedContents = ({ root, previousOf, baseOf, language }: PlanCheckInput, plans: readonly string[]): Changed[] =>
   plans
     .filter((path) => existsSync(join(root, path)))
     .map((path) => {
       const current = readFileSync(join(root, path), 'utf8')
-      return { path, current, previous: previousOf(path), base: baseOf(path), board: hasLanesTable(current, language) }
+      const previous = previousOf(path)
+      const previousLines = new Set(previous?.split('\n') ?? [])
+      return { path, current, previous, previousLines, base: baseOf(path), board: hasLanesTable(current, language) }
     })
 
 /**
- * The structure of the changed plans and boards: a phase the change added (against `HEAD`) with tasks and without
- * a review gate fails; a lane row the change added or edited that names no phase warns; a phase whose tasks are
- * all ticked on the base branch and that still has open boxes without `→ P<n>` warns. Empty when no plan changed;
- * the row result is left out when no changed file has a lanes table, the merged result when every one has.
+ * The structure of the changed plans and boards:
+ * - a phase the change added (against `HEAD`) with tasks and without a review gate fails;
+ * - a lane row the change added or edited that names no phase warns, and so does one whose phases cell is longer
+ *   than `PHASE_CELL_LIMIT` or records a side order of the user;
+ * - a phase whose tasks are all ticked on the base branch and that still has open boxes without `→ P<n>` warns;
+ * - a phase of a plan with a dependency table that has no row in it warns.
+ *
+ * Empty when no plan changed. The row and prose results are left out when no changed file has a lanes table, the
+ * merged result when every one has, the dependency result when no changed plan has the table.
  */
 export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
   const files = changedPlansOf(input.paths, input.planDirectory)
@@ -123,13 +179,24 @@ export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
   const changed = changedContents(input, files)
   const boards = changed.filter(({ board }) => board)
   const plans = changed.filter(({ board }) => !board)
+  const unlistedPerPlan = plans.map((file) => unlistedOf(file, language)).filter((found) => found !== null)
   const gates = changed.flatMap((file) => gatesOf(file, language))
   const rows = boards.flatMap((file) => rowsOf(file, language))
+  const prose = boards.flatMap((file) => proseOf(file, language))
   const merged = plans.flatMap((file) => mergedOf(file, language))
+  const unlisted = unlistedPerPlan.flat()
   const durationMs = Date.now() - started
   return [
-    gateResult(gates, files.length, language, durationMs),
-    ...(boards.length > 0 ? [rowResult(rows, boards.length, durationMs)] : []),
-    ...(plans.length > 0 ? [mergedResult(merged, plans.length, durationMs)] : []),
+    findingsResult(gateReport(language), gates, files.length, durationMs),
+    ...(boards.length > 0
+      ? [
+          findingsResult(rowReport, rows, boards.length, durationMs),
+          findingsResult(proseReport, prose, boards.length, durationMs),
+        ]
+      : []),
+    ...(plans.length > 0 ? [findingsResult(mergedReport, merged, plans.length, durationMs)] : []),
+    ...(unlistedPerPlan.length > 0
+      ? [findingsResult(unlistedReport, unlisted, unlistedPerPlan.length, durationMs)]
+      : []),
   ]
 }

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { pathToFileURL } from 'node:url'
+import { HERD_COMMAND } from './plans/herd-command'
 import { locateKit } from './sync/kit-source'
 import { CLI_NAME } from './version/release'
 
@@ -12,13 +13,17 @@ export type Resolution =
   | { kind: 'version' }
   | { kind: 'usage'; exitCode: number; message: string }
 
+/** Commands that stay callable but are not advertised in the usage line. */
+const ALIASES = new Set<string>([HERD_COMMAND.alias])
+
 /** One line per command; each entry lazily imports the module that exports its `run`. */
 export const COMMANDS: CommandTable = {
   check: () => import('./check/command'),
   config: () => import('./config/command'),
   context: () => import('./context/command'),
+  [HERD_COMMAND.name]: () => import('./plans/command'),
   init: () => import('./sync/init-command'),
-  plans: () => import('./plans/command'),
+  [HERD_COMMAND.alias]: () => import('./plans/command'),
   sync: () => import('./sync/command'),
   update: () => import('./update/command'),
   watch: () => import('./watch/command'),
@@ -27,7 +32,8 @@ export const COMMANDS: CommandTable = {
 export const resolveCommand = (argv: string[], table: CommandTable): Resolution => {
   const [name, ...args] = argv
   const names = Object.keys(table)
-  const usage = `Usage: ${CLI_NAME} <command> [args]\n       ${CLI_NAME} --version\nCommands: ${names.length > 0 ? names.join(', ') : '(none yet)'}`
+  const advertised = names.filter((entry) => !ALIASES.has(entry))
+  const usage = `Usage: ${CLI_NAME} <command> [args]\n       ${CLI_NAME} --version\nCommands: ${advertised.length > 0 ? advertised.join(', ') : '(none yet)'}`
   if (name === '--version' || name === '-v') return { kind: 'version' }
   if (!name || name === '--help' || name === '-h') return { kind: 'usage', exitCode: name ? 0 : 1, message: usage }
   if (!names.includes(name)) return { kind: 'usage', exitCode: 1, message: `Unknown command: ${name}\n${usage}` }

package/src/config/legacy-names.ts

@@ -21,6 +21,14 @@ export const PROJECT_LEGACY_FILES: readonly Rename[] = [
   { from: LEGACY_MANIFEST_PATH, to: `${TOOL_DIRECTORY}/${MANIFEST_FILE}` },
 ]
 
+/** The lock files that mark a project install in `root`, the old name counting until 2.0.0 like the old config. */
+export const projectLockCandidates = (root: string): string[] =>
+  [`${TOOL_DIRECTORY}/${MANIFEST_FILE}`, LEGACY_MANIFEST_PATH].map((path) => join(root, path))
+
+/** True when `root` holds a project install. A lock counts when it exists; a broken one is the sync's to report. */
+export const hasProjectInstall = (root: string, exists: (path: string) => boolean): boolean =>
+  projectLockCandidates(root).some(exists)
+
 export const PUBLIC_CONTENT_PATH = `${TOOL_DIRECTORY}/public-content.json`
 
 /** Where the public-content facts lay before the rename: below `XDG_CONFIG_HOME`, else `~/.config`. */

package/src/config/nested-quantifier.ts

@@ -0,0 +1,73 @@
+type Group = { repeats: boolean; branches: string[] }
+
+const GROUP_PREFIX = /^\?(?::|=|!|<=|<!|<[^>]+>)/
+const BRACES = /^\{(\d+)(?:(,)(\d*))?\}/
+
+/** Length of an unbounded or repeating quantifier (`*`, `+`, `{n,}`, `{n,m}` with m above 1) at `index`, else 0. */
+const repeatingLengthAt = (pattern: string, index: number): number => {
+  if (pattern[index] === '*' || pattern[index] === '+') return 1
+  const braces = pattern.slice(index).match(BRACES)
+  const [text, , comma, max] = braces ?? []
+  return text !== undefined && comma && (max === '' || Number(max) > 1) ? text.length : 0
+}
+
+const classEnd = (pattern: string, start: number): number => {
+  let index = start + 1
+  while (index < pattern.length && pattern[index] !== ']') index += pattern[index] === '\\' ? 2 : 1
+  return index
+}
+
+const overlapsAnother = (branches: readonly string[]): boolean =>
+  branches.some((branch, index) =>
+    branches.some((other, otherIndex) => index !== otherIndex && other.startsWith(branch)),
+  )
+
+const NESTED = -1
+
+const appendTo = (group: Group, text: string): void => {
+  group.branches[group.branches.length - 1] += text
+}
+
+const prefixLengthAt = (pattern: string, index: number): number =>
+  pattern.slice(index + 1).match(GROUP_PREFIX)?.[0].length ?? 0
+
+/** Closes the group at `index`; NESTED when it repeats and holds a repeat or branches that begin alike. */
+const closeGroup = (pattern: string, index: number, groups: Group[]): number => {
+  const closed = groups.pop() as Group
+  const repeated = repeatingLengthAt(pattern, index + 1) > 0
+  if (repeated && (closed.repeats || overlapsAnother(closed.branches))) return NESTED
+  groups[groups.length - 1].repeats ||= closed.repeats
+  return index + 1
+}
+
+/** Reads the token at `index` into the open groups and returns the index after it, or NESTED. */
+const stepAt = (pattern: string, index: number, groups: Group[]): number => {
+  const top = groups[groups.length - 1]
+  const char = pattern[index]
+  const literalEnd = char === '\\' ? index + 2 : classEnd(pattern, index) + 1
+  const quantifierLength = repeatingLengthAt(pattern, index)
+  if (char === '\\' || char === '[') appendTo(top, pattern.slice(index, literalEnd))
+  else if (char === '(') groups.push({ repeats: false, branches: [''] })
+  else if (char === ')' && groups.length > 1) return closeGroup(pattern, index, groups)
+  else if (char === '|') top.branches.push('')
+  else if (quantifierLength > 0) top.repeats = true
+  else appendTo(top, char)
+  if (char === '\\' || char === '[') return literalEnd
+  if (char === '(') return index + 1 + prefixLengthAt(pattern, index)
+  return index + Math.max(quantifierLength, 1)
+}
+
+/**
+ * Whether a regular expression repeats a group that repeats inside itself, the shape of catastrophic backtracking:
+ * `(a+)+`, `(\w*)*`, `(x+y)+z`, and with alternation whose branches begin alike, `(a|aa)+`. A best-effort scan of the
+ * source, not a proof: it misses overlaps it cannot see in the text (`(a|a?)+`), and it flags a few harmless ones.
+ */
+export const hasNestedQuantifier = (pattern: string): boolean => {
+  const groups: Group[] = [{ repeats: false, branches: [''] }]
+  let index = 0
+  while (index < pattern.length) {
+    index = stepAt(pattern, index, groups)
+    if (index === NESTED) return true
+  }
+  return false
+}

package/src/config/repository-directory.ts

@@ -0,0 +1,11 @@
+import { isAbsolute } from 'node:path'
+
+const segmentsOf = (path: string): string[] =>
+  path.split(/[\\/]/).filter((segment) => segment !== '' && segment !== '.')
+
+/**
+ * A directory below the repository root: relative, not the root itself and without a `..` segment. The approval gate
+ * hook applies the same rule (`kit/hooks/hooks/approval-gate/settings.ts`), which this package does not import.
+ */
+export const isRepositoryDirectory = (value: string): boolean =>
+  !isAbsolute(value) && segmentsOf(value).length > 0 && !segmentsOf(value).includes('..')