jackherd 1.13.0 → 1.14.0

package/src/check/plan.ts

@@ -3,9 +3,10 @@ import { STACKS, type Stack, type StackProfile } from '../config/detect'
 import { agentTextReviewers } from './agent-text-reviewers'
 import { type ChangedFile, generatorOwnedFiles, stagedBuildArtifacts } from './changes'
 import { tokenize } from './command-line'
+import { hasNamedTest, isSourceFile, isTestFile, testStemsOf } from './file-kinds'
 import { matchesAnyGlob } from './glob'
 import { CHECK_KIND, type CheckKind } from './result'
-import { isUnder, looseDirectories, packageRootsFor } from './roots'
+import { isUnder, looseDirectories, nearestRootOf, packageRootOf, packageRootsFor } from './roots'
 import { projectChecksFor, publicContentReviewers, reviewersFor } from './routing'
 import type { CheckConfig, ProjectCheck } from './schema'
 
@@ -21,7 +22,7 @@ export type PlannedCheck = {
   kind: CheckKind
 }
 
-export type PackageCommands = Pick<JackherdConfig['commands'], 'test' | 'typecheck'>
+export type PackageCommands = Pick<JackherdConfig['commands'], 'test' | 'typecheck' | 'lint'>
 
 /** What the plan asks of the disk, by the markers of the stack (`checkStackOf`). */
 export type Filesystem = {
@@ -32,9 +33,11 @@ export type Filesystem = {
   /** Whether the directory holds a type marker of the stack (`tsconfig.json`, `phpstan.neon`). */
   hasTypeConfig: (dir: string) => boolean
   hasTests: (dir: string) => boolean
+  /** Every file of the repository that git tracks or does not ignore; read only for the name rule. */
+  repositoryFiles: () => readonly string[]
 }
 
-/** The stack as the check reads it; without a detected stack, every stack's markers and patterns together. */
+/** The stack as the check reads it; with none or several detected, every stack's markers and patterns together. */
 export type CheckStack = {
   rootMarkers: string[]
   typeMarkers: string[]
@@ -44,6 +47,14 @@ export type CheckStack = {
   lintGlobs: string[]
 }
 
+/** What the check reads only where no stack is detected at all (not where several are). */
+export type NoStackFallback = {
+  /** `check.roots` and the repository root `.`: a file no root marker holds belongs to the nearest one above it. */
+  roots: readonly string[]
+  /** `commands.lint`, run once from `.` where no `check.lintFilesCommand` is set. */
+  lintCommand?: string
+}
+
 /** What the plan reads from the settings: the test and type commands, the `check` block and the stack's patterns. */
 export type PlanInputs = {
   commands: PackageCommands
@@ -51,6 +62,8 @@ export type PlanInputs = {
   stack: Pick<CheckStack, 'lintGlobs' | 'sourceFile'>
   /** Repository paths of the kit's copies (`.jackherd/lock.json`); their tests run where the kit keeps the source. */
   kitCopies: readonly string[]
+  /** Null where a stack is detected, or several. */
+  noStackFallback: NoStackFallback | null
 }
 
 export type CheckPlan = {
@@ -63,8 +76,22 @@ export type CheckPlan = {
   checks: PlannedCheck[]
   /** The changed source files of the stack no planned test reaches, kit copies aside; a check without a test is no green. */
   untestedSources: string[]
+  /**
+   * Without a detected stack, the changed source files under a root found by `NoStackFallback.roots` that no test file
+   * of their name covers: a run from such a root reaches every file, so the name decides, and only as a warning.
+   */
+  sourcesWithoutNamedTest: string[]
 }
 
+/** The roots of a change: by root marker, and without a detected stack by `NoStackFallback.roots` for the rest. */
+type ChangeRoots = { roots: string[]; fallbackRoots: string[]; fallbackPaths: string[] }
+
+/** What reaches a changed file: a test run from a directory above it, or a fired project check of kind tests whose globs (or no globs) match it. */
+type TestReach = { dirs: readonly string[]; checks: readonly ProjectCheck[] }
+
+/** Which changed source files no test covers: the paths under marker roots by reach, the fallback paths by name. */
+type Coverage = Pick<CheckPlan, 'untestedSources' | 'sourcesWithoutNamedTest'>
+
 export const isSlow = (check: PlannedCheck): boolean =>
   check.kind === CHECK_KIND.types || check.kind === CHECK_KIND.tests
 
@@ -92,6 +119,36 @@ export const checkStackOf = (stack: Stack | null): CheckStack => {
 const lintedPaths = (paths: readonly string[], lintGlobs: readonly string[]): string[] =>
   lintGlobs.length === 0 ? [...paths] : paths.filter((path) => matchesAnyGlob(path, lintGlobs))
 
+/** A predicate from the configured globs, or the given one where none are configured. */
+const globsOr =
+  (globs: readonly string[] | undefined, fallback: (path: string) => boolean) =>
+  (path: string): boolean =>
+    globs === undefined ? fallback(path) : matchesAnyGlob(path, globs)
+
+/** Each path no root marker holds, with the nearest fallback root above it; paths without one are left out. */
+const fallbackRootsOf = (
+  paths: readonly string[],
+  fallback: readonly string[],
+  isProjectRoot: Filesystem['isProjectRoot'],
+): { path: string; root: string }[] =>
+  paths.flatMap((path) => {
+    const root = packageRootOf(path, isProjectRoot) === null ? nearestRootOf(path, fallback) : null
+    return root === null ? [] : [{ path, root }]
+  })
+
+const changeRootsOf = (
+  paths: readonly string[],
+  fallback: readonly string[],
+  { isProjectRoot, isWorkspaceRoot }: Pick<Filesystem, 'isProjectRoot' | 'isWorkspaceRoot'>,
+): ChangeRoots => {
+  const isTestable = (root: string) => !isWorkspaceRoot(root)
+  const fallbackPairs = fallbackRootsOf(paths, fallback, isProjectRoot)
+  const fallbackPaths = fallbackPairs.map(({ path }) => path)
+  const fallbackRoots = unique(fallbackPairs.map(({ root }) => root)).filter(isTestable)
+  const markerRoots = packageRootsFor(paths, isProjectRoot).filter(isTestable)
+  return { roots: unique([...markerRoots, ...fallbackRoots]), fallbackRoots, fallbackPaths }
+}
+
 /** No lint without a `lintFilesCommand`, none is guessed; none either when no changed file is the stack's to lint. */
 const lintChecks = (command: string | undefined, paths: readonly string[]): PlannedCheck[] =>
   command === undefined || paths.length === 0
@@ -106,6 +163,17 @@ const lintChecks = (command: string | undefined, paths: readonly string[]): Plan
         },
       ]
 
+/** Without a detected stack and a `lintFilesCommand`, the project's lint once from the repository root. */
+const projectLint = (command: string | undefined): PlannedCheck[] =>
+  command === undefined ? [] : [{ name: 'Lint', command, argv: tokenize(command), cwd: '.', kind: CHECK_KIND.lint }]
+
+const lintOf = (
+  lintFilesCommand: string | undefined,
+  noStackFallback: NoStackFallback | null,
+  paths: readonly string[],
+): PlannedCheck[] =>
+  lintFilesCommand === undefined ? projectLint(noStackFallback?.lintCommand) : lintChecks(lintFilesCommand, paths)
+
 const projectChecks = (fired: readonly ProjectCheck[]): PlannedCheck[] =>
   fired.map(({ name, command, kind }) => ({
     name,
@@ -127,18 +195,15 @@ const inDirectory = (kind: CheckKind, label: string, command: string, dir: strin
 const typeChecks = (
   roots: readonly string[],
   command: string | undefined,
-  hasTypeConfig: Filesystem['hasTypeConfig'],
+  isTypeRoot: (root: string) => boolean,
 ): PlannedCheck[] =>
   command === undefined
     ? []
-    : roots.filter(hasTypeConfig).map((root) => inDirectory(CHECK_KIND.types, 'Types', command, root))
+    : roots.filter(isTypeRoot).map((root) => inDirectory(CHECK_KIND.types, 'Types', command, root))
 
 const testChecks = (dirs: readonly string[], command: string | undefined): PlannedCheck[] =>
   command === undefined ? [] : dirs.map((dir) => inDirectory(CHECK_KIND.tests, 'Tests', command, dir))
 
-/** What reaches a changed file: a test run from a directory above it, or a fired project check of kind tests whose globs (or no globs) match it. */
-type TestReach = { dirs: readonly string[]; checks: readonly ProjectCheck[] }
-
 const isReached = (path: string, { dirs, checks }: TestReach): boolean =>
   dirs.some((dir) => isUnder(path, dir)) ||
   checks.some(({ globs }) => globs === undefined || matchesAnyGlob(path, globs))
@@ -147,8 +212,43 @@ const isReached = (path: string, { dirs, checks }: TestReach): boolean =>
 const untestedSourcesOf = (
   paths: readonly string[],
   reach: TestReach,
-  { sourceFile, kitCopies }: Pick<PlanInputs['stack'], 'sourceFile'> & Pick<PlanInputs, 'kitCopies'>,
-): string[] => paths.filter((path) => sourceFile.test(path) && !kitCopies.includes(path) && !isReached(path, reach))
+  { isSource, kitCopies }: { isSource: (path: string) => boolean; kitCopies: readonly string[] },
+): string[] => paths.filter((path) => isSource(path) && !kitCopies.includes(path) && !isReached(path, reach))
+
+/** The source files among `paths` with no test file of their name in the repository, read only when there are any. */
+const sourcesWithoutNamedTestOf = (
+  paths: readonly string[],
+  testChecks: readonly ProjectCheck[],
+  { check, kitCopies }: Pick<PlanInputs, 'check' | 'kitCopies'>,
+  repositoryFiles: Filesystem['repositoryFiles'],
+): string[] => {
+  const isTest = globsOr(check.testFiles, isTestFile)
+  const isNamedSource = globsOr(check.sourceFiles, isSourceFile)
+  const isSource = (path: string) => !isTest(path) && isNamedSource(path)
+  const candidates = untestedSourcesOf(paths, { dirs: [], checks: testChecks }, { isSource, kitCopies })
+  if (candidates.length === 0) return []
+  const testStems = testStemsOf(repositoryFiles(), isTest)
+  return candidates.filter((path) => !hasNamedTest(path, testStems))
+}
+
+const coverageOf = (
+  { paths, fallbackPaths }: { paths: readonly string[]; fallbackPaths: readonly string[] },
+  reach: TestReach,
+  { check, stack, kitCopies }: Pick<PlanInputs, 'check' | 'stack' | 'kitCopies'>,
+  repositoryFiles: Filesystem['repositoryFiles'],
+): Coverage => {
+  const markerPaths = paths.filter((path) => !fallbackPaths.includes(path))
+  const isSource = globsOr(check.sourceFiles, (path) => stack.sourceFile.test(path))
+  return {
+    untestedSources: untestedSourcesOf(markerPaths, reach, { isSource, kitCopies }),
+    sourcesWithoutNamedTest: sourcesWithoutNamedTestOf(
+      fallbackPaths,
+      reach.checks,
+      { check, kitCopies },
+      repositoryFiles,
+    ),
+  }
+}
 
 /** The reviewers a set of changed paths calls for, each named once: routed, public content and agent texts. */
 export const reviewersOf = (paths: readonly string[], config: CheckConfig): string[] => [
@@ -162,15 +262,17 @@ export const reviewersOf = (paths: readonly string[], config: CheckConfig): stri
 /**
  * Decides, without touching the disk or running anything, what a set of changed files calls for:
  * which package roots to type-check and test, which project checks fire, which reviewers to start,
- * and which changed source files no test covers. A root that gathers workspaces is never tested.
+ * and which changed source files no test covers. A root that gathers workspaces is never tested. Without a
+ * detected stack, a file no root marker holds is tested from its `NoStackFallback.roots` entry and judged by its name.
  */
 export const planChecks = (
   files: readonly ChangedFile[],
-  { commands, check: config, stack, kitCopies }: PlanInputs,
+  { commands, check: config, stack, kitCopies, noStackFallback }: PlanInputs,
   filesystem: Filesystem,
 ): CheckPlan => {
   const paths = files.map((file) => file.path)
-  const roots = packageRootsFor(paths, filesystem.isProjectRoot).filter((root) => !filesystem.isWorkspaceRoot(root))
+  const { roots, fallbackRoots, fallbackPaths } = changeRootsOf(paths, noStackFallback?.roots ?? [], filesystem)
+  const isTypeRoot = (root: string) => fallbackRoots.includes(root) || filesystem.hasTypeConfig(root)
   const loose = config.looseTests ? looseDirectories(paths, roots, filesystem.hasTests) : []
   const fired = projectChecksFor(paths, config.checks)
   const testDirs = commands.test === undefined ? [] : [...roots, ...loose]
@@ -178,9 +280,9 @@ export const planChecks = (
     paths.length === 0
       ? []
       : [
-          ...lintChecks(config.lintFilesCommand, lintedPaths(paths, stack.lintGlobs)),
+          ...lintOf(config.lintFilesCommand, noStackFallback, lintedPaths(paths, stack.lintGlobs)),
           ...projectChecks(fired),
-          ...typeChecks(roots, commands.typecheck, filesystem.hasTypeConfig),
+          ...typeChecks(roots, commands.typecheck, isTypeRoot),
           ...testChecks(testDirs, commands.test),
         ]
   const reach: TestReach = { dirs: testDirs, checks: fired.filter((check) => check.kind === CHECK_KIND.tests) }
@@ -191,6 +293,6 @@ export const planChecks = (
     generated: generatorOwnedFiles(paths, config.generatorOwned),
     artifacts: stagedBuildArtifacts(files, config.buildArtifacts),
     checks,
-    untestedSources: untestedSourcesOf(paths, reach, { sourceFile: stack.sourceFile, kitCopies }),
+    ...coverageOf({ paths, fallbackPaths }, reach, { check: config, stack, kitCopies }, filesystem.repositoryFiles),
   }
 }

package/src/check/report.ts

@@ -1,7 +1,8 @@
 import { STACKS, type StackDetection, stackOfCommand } from '../config/detect'
+import { PROJECT_CONFIG_PATH } from '../config/location'
 import { CLI_NAME } from '../version/release'
 import { type ChangedFile, STATUS_COMMAND } from './changes'
-import type { CheckPlan } from './plan'
+import type { CheckPlan, PackageCommands } from './plan'
 import { CHECK_STATUS, type CheckResult, type CheckStatus, RUN_MODE, type RunMode, SKIP_SLOW_FLAG } from './result'
 
 const STATUS_ICON = { pass: '✅', fail: '❌', warn: '⚠️ ', skipped: '⏭️ ' } as const
@@ -45,6 +46,48 @@ export const untestedResult = (sources: readonly string[], mode: RunMode): Check
         durationMs: 0,
       }
 
+/** Without a detected stack, the changed source files no test file of their name covers: a warning in every run mode. */
+export const namedTestResult = (sources: readonly string[]): CheckResult | null =>
+  sources.length === 0
+    ? null
+    : {
+        name: 'Tests by name',
+        command: 'check.testFiles',
+        status: CHECK_STATUS.warn,
+        detail: [
+          `no test file named like ${plural(sources.length, 'changed source file')}; add one, or name the test files in \`check.testFiles\``,
+          ...sources,
+        ].join('\n'),
+        durationMs: 0,
+      }
+
+/** Without a detected stack nothing derives `commands.test`, and a check without it tests nothing, so it fails. */
+export const missingTestCommandResult = (command: string | undefined, detection: StackDetection): CheckResult | null =>
+  command !== undefined || detection.kind !== 'none'
+    ? null
+    : {
+        name: 'Test command',
+        command: 'commands.test',
+        status: CHECK_STATUS.fail,
+        detail: `no stack detected and no \`commands.test\` set; set it in ${PROJECT_CONFIG_PATH} (\`${CLI_NAME} config test\` names the line, \`/jh-start\` proposes it from the CI)`,
+        durationMs: 0,
+      }
+
+/** Without a detected stack a missing type or lint command is a note, not a result: not every language has the step. */
+export const missingCommandNotes = (
+  commands: PackageCommands,
+  lintFilesCommand: string | undefined,
+  detection: StackDetection,
+): string[] => {
+  if (detection.kind !== 'none') return []
+  return [
+    ...(commands.typecheck === undefined ? [`${CLI_NAME}: no \`commands.typecheck\` set; no type check runs.`] : []),
+    ...(commands.lint === undefined && lintFilesCommand === undefined
+      ? [`${CLI_NAME}: neither \`check.lintFilesCommand\` nor \`commands.lint\` set; no lint runs.`]
+      : []),
+  ]
+}
+
 /** The lock files of known stacks the repository holds; none means it has not installed yet. */
 const presentLockFiles = (detection: StackDetection): readonly string[] => {
   if (detection.kind === 'found') return [detection.lockFile]

package/src/check/roots.ts

@@ -46,6 +46,15 @@ export const kitCopyPaths = (manifest: unknown): string[] => {
 /** Whether a test run from `root` reaches `path`; from `.` it reaches every path. */
 export const isUnder = (path: string, root: string): boolean => root === '.' || path.startsWith(`${root}/`)
 
+/**
+ * The deepest of `roots` above `path`; null when none is. Without a detected stack, a file no root marker holds
+ * belongs to the nearest `check.roots` entry, with the repository root `.` among them.
+ */
+export const nearestRootOf = (path: string, roots: readonly string[]): string | null =>
+  roots
+    .filter((root) => isUnder(path, root))
+    .reduce<string | null>((nearest, root) => (nearest === null || root.length > nearest.length ? root : nearest), null)
+
 /**
  * Directories with test files that belong to no package root, which would otherwise be tested by
  * nobody. The repository root `.` is excluded: a test run from there walks the whole repository.

package/src/check/schema.ts

@@ -20,6 +20,9 @@ const glob = nonEmpty.refine((value) => !/[{}[\]]/.test(value), 'Braces and brac
 
 const globs = z.array(glob).min(1)
 
+/** A directory from the repository root as the check compares it: `./crates/core/` reads as `crates/core`. */
+const directory = nonEmpty.transform((value) => value.replace(/^(\.\/)+/, '').replace(/\/+$/, '') || '.')
+
 /** Staged output that belongs to a build, never to a commit. */
 export const DEFAULT_BUILD_ARTIFACT_GLOBS = [
   '**/tsup.config.bundled_*',
@@ -88,6 +91,15 @@ export const checkConfigSchema = z.strictObject({
   skillBudgets: skillBudgets.optional(),
   /** Also run tests in directories that hold test files but belong to no package. */
   looseTests: z.boolean().default(false),
+  /**
+   * Package roots, as directories from the repository root, read only where no stack is detected: a changed file
+   * belongs to the nearest one above it, else to the repository root `.`.
+   */
+  roots: z.array(directory).min(1).optional(),
+  /** The files a test covers; replaces the stack's pattern, or the rule of thumb where no stack is detected. */
+  sourceFiles: globs.optional(),
+  /** The test files; replaces the stack's pattern, or the rule of thumb where no stack is detected. */
+  testFiles: globs.optional(),
 })
 
 export type CheckConfig = z.infer<typeof checkConfigSchema>

package/src/check/settings.ts

@@ -10,7 +10,7 @@ import {
 } from '../config/detect'
 import { PROJECT_CONFIG_PATH } from '../config/location'
 import type { PlanLanguage } from '../vocabulary'
-import type { PackageCommands } from './plan'
+import type { NoStackFallback, PackageCommands } from './plan'
 import { type CheckConfig, checkConfigSchema } from './schema'
 
 export const CONFIG_PATH = PROJECT_CONFIG_PATH
@@ -33,6 +33,10 @@ export type CheckSettings = {
 /** The stack a detection decided, by lock file or manifest; null for none or several, where the check reads every stack's markers. */
 export const stackOf = (detection: StackDetection): Stack | null => (isDecided(detection) ? detection.stack : null)
 
+/** Without any detected stack: `check.roots` and the repository root `.` as fallback roots, `commands.lint` from the root. */
+export const noStackFallbackOf = ({ stack, check, commands }: CheckSettings): NoStackFallback | null =>
+  stack.kind === 'none' ? { roots: [...(check.roots ?? []), '.'], lintCommand: commands.lint } : null
+
 const commandsSchema = jackherdConfigSchema.shape.commands
 const planDirectorySchema = jackherdConfigSchema.shape.planDirectory
 const planLanguageSchema = jackherdConfigSchema.shape.planLanguage
@@ -47,9 +51,9 @@ const worktreeDirectorySchema = jackherdConfigSchema.shape.worktreeDirectory
 export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckSettings => {
   const detected = withDetected(z.record(z.string(), z.unknown()).parse(raw), facts)
   const object = z.record(z.string(), z.unknown()).parse(detected.raw)
-  const { test, typecheck } = commandsSchema.parse(object.commands)
+  const { test, typecheck, lint } = commandsSchema.parse(object.commands)
   return {
-    commands: { test, typecheck },
+    commands: { test, typecheck, lint },
     check: checkConfigSchema.parse(object.check ?? {}),
     planDirectory: planDirectorySchema.parse(object.planDirectory),
     planLanguage: planLanguageSchema.parse(object.planLanguage),

package/src/check/skill-budget-defaults.ts

@@ -21,13 +21,14 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/implement/SKILL.md': 2190,
   // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
   // Plain words: no plan code without its words in a short question.
-  '.claude/skills/orchestrate/SKILL.md': 7920,
+  // Any language: a pointer in § 0 and a section in events.md for `plan missing`.
+  '.claude/skills/orchestrate/SKILL.md': 7929,
   '.claude/skills/orchestrate/references/acceptance.md': 200,
   '.claude/skills/orchestrate/references/close-lane.md': 250,
   '.claude/skills/orchestrate/references/coordinator-handover.md': 551,
   '.claude/skills/orchestrate/references/draft-review.md': 300,
   // P33: a source entry the user must read or decide becomes a row of what waits on them, and when it closes.
-  '.claude/skills/orchestrate/references/events.md': 1110,
+  '.claude/skills/orchestrate/references/events.md': 1166,
   '.claude/skills/orchestrate/references/herd.md': 299,
   '.claude/skills/orchestrate/references/lane-handover.md': 280,
   '.claude/skills/orchestrate/references/lane-session.md': 280,
@@ -40,10 +41,11 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/pre-commit/SKILL.md': 1003,
   '.claude/skills/review/SKILL.md': 319,
   '.claude/skills/security-audit/SKILL.md': 519,
-  '.claude/skills/start/SKILL.md': 607,
+  // Any language: step 3 points to proposing the missing commands from the CI; the proposal itself is a reference.
+  '.claude/skills/start/SKILL.md': 630,
   '.claude/skills/uncle-bob/SKILL.md': 466,
   // P33: grows with the skill above.
-  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8720,
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8729,
   '.claude/agents/devops.md': 104,
   '.claude/agents/explore.md': 132,
   '.claude/agents/implement.md': 303,

package/src/plans/lane-plans.ts

@@ -27,7 +27,8 @@ export type PlanSources = {
   parsed?: PlanRound
 }
 
-const isOutsideRepository = (path: string): boolean => path.startsWith('..')
+/** A repository path that a link resolved above the repository root. */
+export const isOutsideRepository = (path: string): boolean => path.startsWith('..')
 
 /** The file as the base ref has it; null when the ref lacks it or the path leaves the repository. */
 export const textAtBase = (base: BaseReader, path: string): string | null =>

package/src/watch/command.ts

@@ -113,6 +113,7 @@ import {
   noTaskSignalDutyLines,
   otherPullRequestsLine,
   parallelDutyLines,
+  planMissingDutyLines,
   sourceEventLines,
   sourceFailingStatusLine,
   watchEventLine,
@@ -136,6 +137,8 @@ import {
 import { mainCheckoutDutyLine } from './main-checkout'
 import { monitorToolAvailable } from './monitor-tool'
 import { parseWatchOptions, type WatchOptions } from './options'
+import type { PlanMissingEvent, PlanMissingState } from './plan-missing'
+import { readPlanMissingEvents } from './plan-missing-read'
 import {
   ENSURE_TRIGGER,
   type EnsureTrigger,
@@ -311,6 +314,8 @@ type Watching = {
   laneStalls: StallState
   /** The open artifact sends in their grace or already reported as `unlinked artifact`; persisted like the fingerprints. */
   unlinkedArtifacts: UnlinkedState
+  /** Per working lane, the plan last reported as `plan missing on base`; persisted like the fingerprints. */
+  planMissing: PlanMissingState
   /** The approval requests of the last poll; null before the first read, so the stored ids stay. */
   approvalRequests: ApprovalRequestFile[] | null
   /** The board's appointment table at the last poll and the time it was read at; null before the first read and while the board cannot be read. */
@@ -365,6 +370,7 @@ const recordedOf = (watch: Watch, watching: Watching): WatchState => {
     noTaskSignals: watching.noTaskSignals,
     laneStalls: watching.laneStalls,
     unlinkedArtifacts: watching.unlinkedArtifacts,
+    planMissing: watching.planMissing,
     approvals: watching.approvalRequests ? recordApprovals(watching.approvalRequests) : withReads.approvals,
     sources: recordWatchedSources(withReads.sources, watching.sourceRuns, watch.sources, watching.githubReadAt),
     appointments: watching.appointments
@@ -665,6 +671,7 @@ const reportOf = async (
     ...laneModelDutyLines(events, watch.texts),
     ...parallelDutyLines(events, watch.texts),
     ...noTaskSignalDutyLines(events, watch.texts),
+    ...planMissingDutyLines(events, watch.texts),
     ...approvalDutyLines(events, watch.texts),
   ]
   const status = await statusLinesOf(watch, watching, next)
@@ -1129,6 +1136,27 @@ const unlinkedArtifactEventsOf = (watch: Watch, watching: Watching): UnlinkedArt
   }
 }
 
+/**
+ * This heartbeat's `plan missing on base` events: the working lanes whose board row, as their worktree has it, links a
+ * plan the base ref lacks, each once; records the state in `watching`. Nothing when the boards or git cannot be read:
+ * the next heartbeat reads again.
+ */
+const planMissingEventsOf = (watch: Watch, watching: Watching): PlanMissingEvent[] => {
+  try {
+    const { events, state } = readPlanMissingEvents(
+      watch.root,
+      watch.settings,
+      watch.sprintFile,
+      workingLanes(watching),
+      watching.planMissing,
+    )
+    watching.planMissing = state
+    return events
+  } catch {
+    return []
+  }
+}
+
 /** The progress of the working lanes, with the pull requests of the last GitHub read; nothing while no lane works. */
 const workingProgressOf = async (watch: Watch, watching: Watching): Promise<Record<string, LaneProgress>> => {
   const working = workingLanes(watching)
@@ -1137,13 +1165,14 @@ const workingProgressOf = async (watch: Watch, watching: Watching): Promise<Reco
   return progress
 }
 
-/** The events a heartbeat of a report brings: the parallel-task proposals, the lanes without a task signal, the unlinked artifacts. */
+/** The events a heartbeat of a report brings: the parallel-task proposals, the lanes without a task signal, the unlinked artifacts, the plans missing on the base. */
 const heartbeatEventsOf = async (watch: Watch, watching: Watching, now: number): Promise<WatchEvent[]> => {
   const progress = await workingProgressOf(watch, watching)
   return [
     ...taskParallelEventsOf(watch, watching, now),
     ...noTaskSignalEventsOf(watch, watching, progress, now),
     ...unlinkedArtifactEventsOf(watch, watching),
+    ...planMissingEventsOf(watch, watching),
   ]
 }
 
@@ -1206,6 +1235,7 @@ const printStreamHeartbeat = async (watch: Watch, watching: Watching, now: numbe
     ...taskParallelEventsOf(watch, watching, now),
     ...noTaskSignalEventsOf(watch, watching, progress, now),
     ...unlinkedArtifactEventsOf(watch, watching),
+    ...planMissingEventsOf(watch, watching),
   ]
   for (const event of events) console.log(`${watchEventLine(event, null)}${hintFor(watch, eventReference(event))}`)
   return sent
@@ -1307,6 +1337,7 @@ const initialWatching = (
   noTaskSignals: start.state.noTaskSignals,
   laneStalls: start.state.laneStalls,
   unlinkedArtifacts: start.state.unlinkedArtifacts,
+  planMissing: start.state.planMissing,
   approvalRequests: null,
   appointments: null,
   reportQuestions: null,

package/src/watch/lane-progress.ts

@@ -48,7 +48,12 @@ export const watchedLaneProgress = async (
 }
 
 /** The repository path of the plan of a lane's newest row that links one; null without such a row. */
-const lanePlanPath = (root: string, settings: PlansSettings, boardFile: string, lane: SprintLane): string | null => {
+export const lanePlanPath = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  lane: SprintLane,
+): string | null => {
   const href = lane.steps.filter((step) => step.planHref !== null).at(-1)?.planHref
   return href ? resolvePlanPath(dirname(boardRepoPathOf(root, settings, boardFile)), href) : null
 }

package/src/watch/lane-report.ts

@@ -13,6 +13,7 @@ import type { LaneModelEvent } from './lane-model'
 import type { LaneParallelEvent } from './lane-parallel'
 import { laneStalledLine } from './lane-stalled'
 import { AGENT_STATUS, type LaneSnapshot, NO_AGENT } from './lane-watch'
+import { PLAN_MISSING_EVENT, type PlanMissingEvent, planMissingLine } from './plan-missing'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { SOURCE_FIELD } from './source-fields'
 import { type FieldChange, lineText, type SourceEvent } from './sources'
@@ -161,6 +162,7 @@ const laneEventLine = (event: WatchEvent): string | null => {
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${phasesText(event.phases)}`
   if (event.kind === WATCH_EVENT.noTaskSignal) return `=== ${terminalSafe(noTaskSignalLine(event))}`
   if (event.kind === WATCH_EVENT.laneStalled) return `=== ${terminalSafe(laneStalledLine(event))}`
+  if (event.kind === WATCH_EVENT.planMissing) return `=== ${planMissingLine(event)}`
   return null
 }
 
@@ -339,6 +341,14 @@ export const noTaskSignalDutyLines = (events: readonly WatchEvent[], texts: Watc
     .filter(isNoTaskSignal)
     .map(({ lane }) => `${terminalSafe(lane)} ${NO_TASK_SIGNAL_EVENT}: ${texts.noTaskSignalDuty}`)
 
+const isPlanMissing = (event: WatchEvent): event is PlanMissingEvent => event.kind === WATCH_EVENT.planMissing
+
+/** What a lane whose plan only its worktree has asks of the coordinator (`orchestrate` § 2 step 0): one line per such lane. */
+export const planMissingDutyLines = (events: readonly WatchEvent[], texts: WatchTexts): string[] =>
+  events
+    .filter(isPlanMissing)
+    .map(({ lane }) => `${terminalSafe(lane)} ${PLAN_MISSING_EVENT}: ${texts.planMissingDuty}`)
+
 const isApproval = (event: WatchEvent): event is ApprovalEvent => event.kind === WATCH_EVENT.approval
 
 /**

package/src/watch/plan-missing-read.ts

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parseSprintLanes } from '../plan-format'
+import { baseReaderAt, commitOf } from '../plans/git'
+import { isOutsideRepository } from '../plans/lane-plans'
+import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from '../plans/settings'
+import { lanePlanPath } from './lane-progress'
+import {
+  type PlanMissingEvent,
+  type PlanMissingReadings,
+  type PlanMissingState,
+  planMissingEvents,
+} from './plan-missing'
+
+/**
+ * The plan the lane's newest linking row names in the board as its worktree has it; null without a worktree board or
+ * row, or for a link that leaves the repository, which no base ref can hold.
+ */
+const worktreePlanOf = (root: string, settings: PlansSettings, boardFile: string, laneName: string): string | null => {
+  const file = join(worktreeOf(root, settings, laneName), boardRepoPathOf(root, settings, boardFile))
+  if (!existsSync(file)) return null
+  const lane = parseSprintLanes(readFileSync(file, 'utf8'), settings.planLanguage).find(({ name }) => name === laneName)
+  const path = lane === undefined ? null : lanePlanPath(root, settings, boardFile, lane)
+  return path === null || isOutsideRepository(path) ? null : path
+}
+
+/**
+ * This heartbeat's `plan missing on base` events and the state to keep, for the working lanes: the plan of each lane's
+ * row in its own worktree against the base ref, where a worktree made from the base would not find it. Nothing when
+ * the base ref does not resolve, which would make every plan look missing.
+ */
+export const readPlanMissingEvents = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  workingLanes: readonly string[],
+  previous: PlanMissingState,
+): { events: PlanMissingEvent[]; state: PlanMissingState } => {
+  const baseRef = baseRefOf(settings)
+  const commit = commitOf(root, baseRef)
+  if (commit === null) return { events: [], state: previous }
+  const base = baseReaderAt(root, commit)
+  const readings: PlanMissingReadings = Object.fromEntries(
+    workingLanes.map((lane) => [lane, worktreePlanOf(root, settings, boardFile, lane)]),
+  )
+  return planMissingEvents(previous, readings, (path) => base(path) !== null, baseRef)
+}

package/src/watch/plan-missing.ts

@@ -0,0 +1,43 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { isRecord } from '../shared/is-record'
+
+export const PLAN_MISSING_EVENT = 'plan missing on base'
+
+/** Per working lane: the plan its newest board row links, as its worktree has it; null without one. */
+export type PlanMissingReadings = Readonly<Record<string, string | null>>
+
+/** Per lane: the plan path last reported as missing on the base ref; a lane whose plan is there has no entry. */
+export type PlanMissingState = Record<string, string>
+
+export type PlanMissingEvent = { kind: typeof PLAN_MISSING_EVENT; lane: string; path: string; baseRef: string }
+
+/**
+ * One event per working lane whose board row, as its worktree has it, links a plan the base ref lacks (`existsAtBase`
+ * answers for a repository path). A plan is reported once while it stays missing: the state clears when it reaches the
+ * base or the row links another, and a lane without a reading (not at work) keeps what it had.
+ */
+export const planMissingEvents = (
+  previous: PlanMissingState,
+  readings: PlanMissingReadings,
+  existsAtBase: (path: string) => boolean,
+  baseRef: string,
+): { events: PlanMissingEvent[]; state: PlanMissingState } => {
+  const events: PlanMissingEvent[] = []
+  const state: PlanMissingState = { ...previous }
+  for (const [lane, planPath] of Object.entries(readings)) {
+    if (planPath === null || existsAtBase(planPath)) {
+      delete state[lane]
+      continue
+    }
+    if (previous[lane] !== planPath) events.push({ kind: PLAN_MISSING_EVENT, lane, path: planPath, baseRef })
+    state[lane] = planPath
+  }
+  return { events, state }
+}
+
+/** `lane <name> plan missing on <base ref>: <path>`. */
+export const planMissingLine = ({ lane, path, baseRef }: PlanMissingEvent): string =>
+  `lane ${terminalSafe(lane)} plan missing on ${terminalSafe(baseRef)}: ${terminalSafe(path)}`
+
+export const isPlanMissingState = (value: unknown): value is PlanMissingState =>
+  isRecord(value) && Object.values(value).every((path) => typeof path === 'string')