jackherd 1.12.7 → 1.14.0

package/src/config/repository-values.ts

@@ -1,4 +1,14 @@
-import type { JackherdConfig } from './schema'
+import { CLI_NAME } from '../version/release'
+import {
+  type DetectedValues,
+  detectedValues,
+  frozenInstallCommand,
+  type RepositoryFacts,
+  STACKS,
+  stackOfCommand,
+} from './detect'
+import { PROJECT_CONFIG_PATH, unsetValueText } from './location'
+import { COMMAND_KEYS, type JackherdConfig } from './schema'
 
 /** The values each repository decides for itself, by the short name `jh config` and global skills use. */
 export const REPOSITORY_VALUE = {
@@ -9,6 +19,7 @@ export const REPOSITORY_VALUE = {
   install: 'install',
   dev: 'dev',
   lockFile: 'lockFile',
+  verifyInstall: 'verifyInstall',
   baseBranch: 'baseBranch',
 } as const
 
@@ -22,6 +33,7 @@ const PLACEHOLDER: Record<RepositoryValue, string> = {
   install: 'kit.command.install',
   dev: 'kit.command.dev',
   lockFile: 'kit.lanes.lockFile',
+  verifyInstall: 'kit.lanes.verifyInstall',
   baseBranch: 'kit.baseBranch',
 }
 
@@ -34,13 +46,158 @@ export const REPOSITORY_TOKENS: ReadonlyMap<string, string> = new Map(
   NAMES.map((name) => [PLACEHOLDER[name], `<${name}>`]),
 )
 
-export const repositoryValuesOf = (config: JackherdConfig): Record<RepositoryValue, string> => ({
-  ...config.commands,
-  lockFile: config.lanes.lockFile,
-  baseBranch: config.baseBranch,
+const UNSET_PATH: Record<RepositoryValue, string> = {
+  test: 'commands.test',
+  typecheck: 'commands.typecheck',
+  lint: 'commands.lint',
+  format: 'commands.format',
+  install: 'commands.install',
+  dev: 'commands.dev',
+  lockFile: 'lanes.lockFile',
+  verifyInstall: 'commands.install',
+  baseBranch: 'baseBranch',
+}
+
+/** What the config (after detection) sets for each value; undefined for one it leaves unset. */
+const rawRepositoryValues = ({
+  commands,
+  lanes,
+  baseBranch,
+}: JackherdConfig): Record<RepositoryValue, string | undefined> => ({
+  test: commands.test,
+  typecheck: commands.typecheck,
+  lint: commands.lint,
+  format: commands.format,
+  install: commands.install,
+  dev: commands.dev,
+  lockFile: lanes.lockFile,
+  verifyInstall: commands.install === undefined ? undefined : frozenInstallCommand(commands.install),
+  baseBranch,
 })
 
+/** A value the config leaves unset reads as the text saying where to set it, as in the kit texts. */
+export const repositoryValuesOf = (config: JackherdConfig): Record<RepositoryValue, string> => {
+  const raw = rawRepositoryValues(config)
+  return Object.fromEntries(NAMES.map((name) => [name, raw[name] ?? unsetValueText(UNSET_PATH[name])])) as Record<
+    RepositoryValue,
+    string
+  >
+}
+
+/** Whether the config (after detection) decides `name`; `repositoryValuesOf` words an unset one as where to set it. */
+export const isRepositoryValueSet = (config: JackherdConfig, name: RepositoryValue): boolean =>
+  rawRepositoryValues(config)[name] !== undefined
+
+/** Every kit placeholder a repository decides, as `[placeholder, value]` with `repositoryValuesOf`'s values. */
+export const repositoryPlaceholderValues = (config: JackherdConfig): [string, string][] => {
+  const values = repositoryValuesOf(config)
+  return NAMES.map((name) => [PLACEHOLDER[name], values[name]])
+}
+
 export const formatRepositoryValues = (values: Record<RepositoryValue, string>): string[] => {
   const width = Math.max(...NAMES.map((name) => name.length)) + 2
   return NAMES.map((name) => `${name.padEnd(width)}${values[name]}`)
 }
+
+const FINDING_SECTION = { commands: 'commands', lanes: 'lanes', check: 'check' } as const
+
+type FindingSection = (typeof FINDING_SECTION)[keyof typeof FINDING_SECTION]
+
+type FindingSubject = {
+  section: FindingSection
+  key: string
+  value: string | undefined
+  /** What the repository's stack would set here; undefined where it has no tool for it. */
+  detected: string | undefined
+}
+
+const findingSubjects = ({ commands, lanes, check }: JackherdConfig, facts: RepositoryFacts): FindingSubject[] => {
+  const detected: DetectedValues = detectedValues(facts)
+  return [
+    ...COMMAND_KEYS.map((key) => ({
+      section: FINDING_SECTION.commands,
+      key,
+      value: commands[key],
+      detected: detected.commands[key],
+    })),
+    {
+      section: FINDING_SECTION.lanes,
+      key: 'lockFile',
+      value: lanes.lockFile,
+      detected: detected.lanes.lockFile,
+    },
+    {
+      section: FINDING_SECTION.check,
+      key: 'lintFilesCommand',
+      value: check?.lintFilesCommand,
+      detected: detected.check.lintFilesCommand,
+    },
+  ]
+}
+
+/** The line to copy into the config: what the stack detected in the repository would set for `subject`. */
+const copyableLine = ({ section, key, detected }: FindingSubject): string => {
+  const scope = `under "${section}" in ${PROJECT_CONFIG_PATH}`
+  return detected === undefined
+    ? `Set ${JSON.stringify(key)} ${scope} yourself.`
+    : `Set ${JSON.stringify(key)}: ${JSON.stringify(detected)} ${scope}.`
+}
+
+/** A lock file of a known stack that the repository does not have; null for any other. */
+const lockFileContradiction = (lockFile: string, facts: RepositoryFacts): string | null => {
+  const known = Object.values(STACKS).some((stack) => stack.lockFiles.includes(lockFile))
+  return known && !facts.lockFiles.includes(lockFile) ? `${lockFile} does not exist` : null
+}
+
+/** A command of a known stack whose lock files the repository lacks; null for another command and in a repository without any lock file, which has not installed yet. */
+const commandContradiction = (command: string, facts: RepositoryFacts): string | null => {
+  const stack = stackOfCommand(command)
+  if (stack === undefined || facts.lockFiles.length === 0) return null
+  const { lockFiles } = STACKS[stack]
+  return lockFiles.some((file) => facts.lockFiles.includes(file))
+    ? null
+    : `\`${command}\` needs ${lockFiles.join(' or ')}, which is missing`
+}
+
+const contradiction = ({ section, value }: FindingSubject, facts: RepositoryFacts): string | null => {
+  if (value === undefined) return null
+  return section === FINDING_SECTION.lanes ? lockFileContradiction(value, facts) : commandContradiction(value, facts)
+}
+
+const findingOf = (subject: FindingSubject, facts: RepositoryFacts): string | null => {
+  const path = `${subject.section}.${subject.key}`
+  if (subject.value === undefined) return `${CLI_NAME}: ${path} is missing. ${copyableLine(subject)}`
+  const reason = contradiction(subject, facts)
+  return reason === null ? null : `${CLI_NAME}: ${path} contradicts the repository: ${reason}. ${copyableLine(subject)}`
+}
+
+/**
+ * One line for each command, `lanes.lockFile` and `check.lintFilesCommand` that is missing or that a package
+ * manager's lock file contradicts (a `bun` command beside only `composer.lock`; a known lock file that does not
+ * exist), each with the config line the repository's stack would set, or the note to set it by hand. A command of no
+ * known manager and a lock file of no known stack are the project's own and stay unchecked; so does every command
+ * in a repository without any lock file, which has not installed yet.
+ */
+export const commandFindings = (config: JackherdConfig, facts: RepositoryFacts): string[] =>
+  findingSubjects(config, facts).flatMap((subject) => findingOf(subject, facts) ?? [])
+
+/** The config key of the finding about `name`; `baseBranch` has none. */
+const FINDING_KEY: Record<RepositoryValue, { section: FindingSection; key: string } | null> = {
+  test: { section: FINDING_SECTION.commands, key: 'test' },
+  typecheck: { section: FINDING_SECTION.commands, key: 'typecheck' },
+  lint: { section: FINDING_SECTION.commands, key: 'lint' },
+  format: { section: FINDING_SECTION.commands, key: 'format' },
+  install: { section: FINDING_SECTION.commands, key: 'install' },
+  dev: { section: FINDING_SECTION.commands, key: 'dev' },
+  lockFile: { section: FINDING_SECTION.lanes, key: 'lockFile' },
+  verifyInstall: { section: FINDING_SECTION.commands, key: 'install' },
+  baseBranch: null,
+}
+
+/** The findings of `commandFindings` that are about `name` alone. */
+export const valueFindings = (config: JackherdConfig, facts: RepositoryFacts, name: RepositoryValue): string[] => {
+  const wanted = FINDING_KEY[name]
+  return findingSubjects(config, facts)
+    .filter(({ section, key }) => section === wanted?.section && key === wanted.key)
+    .flatMap((subject) => findingOf(subject, facts) ?? [])
+}

package/src/config/schema.ts

@@ -6,7 +6,7 @@ import { CONTENT_FIELDS, SOURCE_FIELD } from '../watch/source-fields'
 import { isSourcePath } from '../watch/source-path'
 import { BUN_FAILED_TEST_PATTERN, CLEAN_REVIEW_TEXT } from '../watch/watch-defaults'
 import { MAX_AUTO_WINDOW_DAYS, windowDays } from './auto-window'
-import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
+import { DEFAULT_BASE_BRANCH } from './base-branch'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
 import { hasNestedQuantifier } from './nested-quantifier'
 import { isRepositoryDirectory } from './repository-directory'
@@ -28,6 +28,15 @@ export const MODEL_ROLE = {
 
 export type ModelRole = (typeof MODEL_ROLE)[keyof typeof MODEL_ROLE]
 
+/** The model of each role when the config names none: a new project's, and one written by hand without `models`. */
+export const DEFAULT_MODELS: Record<ModelRole, string> = {
+  [MODEL_ROLE.plan]: 'claude-opus-5-5',
+  [MODEL_ROLE.implement]: 'claude-sonnet-5-5',
+  [MODEL_ROLE.review]: 'claude-sonnet-5-5',
+  [MODEL_ROLE.explore]: 'claude-sonnet-5-5',
+  [MODEL_ROLE.orchestrate]: 'claude-opus-5-5',
+}
+
 export const isTerminalAdapter = (value: string): value is TerminalAdapter =>
   (Object.values(TERMINAL_ADAPTER) as string[]).includes(value)
 
@@ -49,6 +58,26 @@ const command = z.string().min(1)
 
 const tokenCount = z.number().int().positive()
 
+/**
+ * The project's own commands. Each is optional: detection fills what the repository's stack decides, and a command
+ * nobody set stays out instead of a guessed one (a kit text then says where to set it).
+ */
+const commandsSchema = z.strictObject({
+  test: command.optional(),
+  typecheck: command.optional(),
+  lint: command.optional(),
+  format: command.optional(),
+  /** Installs a new lane's dependencies. */
+  install: command.optional(),
+  /** Starts a lane's dev server, run as `PORT=<port> <dev>`; a project supplement may name another. */
+  dev: command.optional(),
+})
+
+export type CommandKey = keyof z.infer<typeof commandsSchema>
+
+/** Every key of the `commands` block, as the schema names them. */
+export const COMMAND_KEYS = Object.keys(commandsSchema.shape) as CommandKey[]
+
 /** The window `plans.context.defaultWindow` assumes when the config leaves it out. */
 export const DEFAULT_CONTEXT_WINDOW = 200_000
 
@@ -450,28 +479,17 @@ export const jackherdConfigSchema = z.strictObject({
   skillPrefix: z
     .union([z.literal(''), z.string().regex(SKILL_PREFIX, 'lower-case letters and digits ending in a dash, e.g. kit-')])
     .default(''),
-  commands: z
-    .strictObject({
-      test: command.default(BUN_COMMANDS.test),
-      typecheck: command.default(BUN_COMMANDS.typecheck),
-      lint: command.default(BUN_COMMANDS.lint),
-      format: command.default(BUN_COMMANDS.format),
-      /** Installs a new lane's dependencies. */
-      install: command.default(BUN_COMMANDS.install),
-      /** Starts a lane's dev server, run as `PORT=<port> <dev>`; a project supplement may name another. */
-      dev: command.default(BUN_COMMANDS.dev),
-    })
-    .prefault({}),
+  commands: commandsSchema.prefault({}),
   /** How `/orchestrate` sets up a lane's worktree. */
   lanes: z
     .strictObject({
       /** Untracked files copied into every new worktree; empty means the files `.worktreeinclude` lists. */
       copy: z.array(laneCopyPath).default([]),
-      /** The dependency lock file a rebase takes from the base branch and regenerates, never merges by hand. */
-      lockFile: lockFilePath.default('bun.lock'),
+      /** The dependency lock file a rebase takes from the base branch and regenerates, never merges by hand; detected from the repository when left out. */
+      lockFile: lockFilePath.optional(),
     })
     .prefault({}),
-  models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId),
+  models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId).default(DEFAULT_MODELS),
   terminal: z
     .strictObject({ adapter: z.enum(Object.values(TERMINAL_ADAPTER)).default(TERMINAL_ADAPTER.none) })
     .prefault({}),

package/src/lane-prompt/texts.ts

@@ -50,7 +50,7 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
     report: (reportPath) =>
       `The report at the end of each step goes to \`${reportPath}\` in the worktree, in the short form: one line of diff stat, one line per check with its numbers, open points, questions as a text block under the heading \`## Questions\` (whatever the report’s language: the watcher finds the section by that word and shows it whole); everything else is in the plan, by reference.`,
     textBlock:
-      'Every question to the coordinator is a text block at the end of your turn, never a dialog (`AskUserQuestion`), also where a skill or a project rule asks for one, the commit confirmation of `/pre-commit` included: the question with the situation, the problem and what each option leads to, in everyday words (the user may not know your terms), the options, your recommendation, the evidence at `file:line`.',
+      'Every question to the coordinator is a text block at the end of your turn, never a dialog (`AskUserQuestion`), also where a skill or a project rule asks for one, the commit confirmation of `/pre-commit` included: the question with the situation, the problem and what each option leads to, in everyday words (the user may not know your terms; a plan code like `P7` appears only in brackets after the words), the options, your recommendation, the evidence at `file:line`.',
     secret:
       'A value only the user knows (a secret, password, token or one-time code) never passes through you, your arguments, your output or a file you write: ask the coordinator for the step as a question.',
     askRule:
@@ -84,7 +84,7 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
     report: (reportPath) =>
       `Den Bericht am Ende jedes Schritts schreibst du nach \`${reportPath}\` im Worktree, in der Kurzform: eine Zeile Diff-Stat, eine Zeile je Check mit seinen Zahlen, offene Punkte, Fragen als Textblock unter der Überschrift \`## Questions\` (in jeder Berichtssprache: der Watcher findet den Abschnitt an diesem Wort und zeigt ihn ganz); alles andere steht im Plan, per Verweis.`,
     textBlock:
-      'Jede Frage an den Koordinator ist ein Textblock am Ende deines Turns, nie ein Dialog (`AskUserQuestion`), auch wo ein Skill oder eine Projektregel einen verlangt, die Commit-Bestätigung von `/pre-commit` eingeschlossen: die Frage mit der Lage, dem Problem und wohin jede Option führt, in Alltagsworten (der User kennt deine Begriffe vielleicht nicht), die Optionen, deine Empfehlung, der Beleg als `datei:zeile`.',
+      'Jede Frage an den Koordinator ist ein Textblock am Ende deines Turns, nie ein Dialog (`AskUserQuestion`), auch wo ein Skill oder eine Projektregel einen verlangt, die Commit-Bestätigung von `/pre-commit` eingeschlossen: die Frage mit der Lage, dem Problem und wohin jede Option führt, in Alltagsworten (der User kennt deine Begriffe vielleicht nicht; ein Plan-Kürzel wie `P7` nur in Klammern hinter den Worten), die Optionen, deine Empfehlung, der Beleg als `datei:zeile`.',
     secret:
       'Ein Wert, den nur der User kennt (ein Geheimnis, Passwort, Token oder Einmalcode), läuft nie über dich, deine Argumente, deine Ausgabe oder eine Datei, die du schreibst: bitte den Koordinator mit einer Frage um diesen Schritt.',
     askRule:

package/src/plan-format/bare-codes.ts

@@ -0,0 +1,28 @@
+import { bareCodesOf } from '../../kit/hooks/hooks/shared/plan-codes'
+import { type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
+import { firstTableRows, firstTableWithHeader, sectionLines, sectionStart } from './markdown'
+
+/** A changed row of the waiting section (1-based line) whose item cell names `code` bare, outside brackets. */
+export type RowWithBareCode = { line: number; code: string }
+
+/**
+ * The changed rows under the board's waiting section whose item cell names a plan code bare (the first one per row):
+ * the user reads the words, the code stands at most in brackets after them. Rows the previous version had word for
+ * word stay. `codes` are the codes the board's plans define, or null to use the fallback pattern.
+ */
+export const boardRowsWithBareCodes = (
+  markdown: string,
+  language: PlanLanguage,
+  previousLines: ReadonlySet<string>,
+  codes: ReadonlySet<string> | null,
+): RowWithBareCode[] => {
+  const { heading, columns } = WAITING_VOCABULARY[language]
+  const start = sectionStart(markdown, heading)
+  const lines = sectionLines(markdown, heading)
+  const item = firstTableWithHeader(lines).header.indexOf(columns.item)
+  if (item === -1) return []
+  return firstTableRows(lines).flatMap(({ index, line, cells }) => {
+    const code = previousLines.has(line) ? undefined : bareCodesOf(cells[item] ?? '', codes)[0]
+    return code === undefined ? [] : [{ line: start + index + 1, code }]
+  })
+}

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/sync/command-context.ts

@@ -20,7 +20,7 @@ export type CommandContext = {
   locate: () => Promise<KitLocation>
   log: (line: string) => void
   /** Hooks the herdr plugin in and returns the line to print, if any. Must not throw: a failure is a line, not an error. */
-  linkHerdrPlugin: (packageRoot: string) => string | null
+  linkHerdrPlugin: (roots: { packageRoot: string; projectRoot: string }) => string | null
   /** A yes/no question to the user; null when there is no terminal to ask in. */
   ask: (question: string) => Promise<boolean | null>
   /** A choice among fixed answers; Enter takes `fallback`; null when there is no terminal to ask in. */
@@ -99,7 +99,9 @@ export const runWithKit = async (
   try {
     const location = await context.locate()
     const { notes, result } = await action(await readKitSource(location))
-    const herdrNote = dryRun ? null : context.linkHerdrPlugin(location.packageRoot)
+    const herdrNote = dryRun
+      ? null
+      : context.linkHerdrPlugin({ packageRoot: location.packageRoot, projectRoot: context.projectRoot })
     for (const note of herdrNote ? [...notes, herdrNote] : notes) context.log(note)
     context.log(formatReport(result))
     return dryRun ? driftExitCodeOf(result) : exitCodeOf(result)

package/src/sync/herdr-plugin.ts

@@ -1,6 +1,6 @@
 import { realpathSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { isLinkedWorktree } from '../plans/git'
+import { isLinkedWorktree, mainCheckout } from '../plans/git'
 import { herdrBinary, spawnTool, type ToolRun } from './tools'
 
 export const HERDR_PLUGIN_ID = 'crossdelta.jackherd'
@@ -115,7 +115,8 @@ const joinLines = (...lines: (string | null)[]): string | null => {
  * Hooks the kit's herdr plugin into herdr when `init` or `sync` runs inside herdr (`HERDR_ENV=1`), and links it
  * again when herdr's link points at another directory or herdr cannot read its manifest (`herdr plugin link`
  * replaces a plugin of the same id). What each copy may link:
- * - a checkout takes over any link, so a repository that develops the kit keeps its link;
+ * - a checkout takes over any link while it runs for its own repository (a worktree of it included), so a repository
+ *   that develops the kit keeps its link; run for another repository it acts like an installed package;
  * - an installed package only replaces a missing or unreadable link and leaves a working one standing, also one to
  *   another installed package: otherwise the global package and a project's dependency would take it from each other;
  * - a lane's worktree never links, since its path goes away with the lane, and only names a broken link.
@@ -160,16 +161,39 @@ const realPathOf = (path: string): string => {
   }
 }
 
+/** The repository a path belongs to (its main checkout, also from a linked worktree); null outside git. */
+const repositoryOf = (path: string): string | null => {
+  try {
+    return mainCheckout(path)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A checkout takes over only at home: when the project lies in the checkout's own repository. For another repository
+ * (or a project outside git) it acts like an installed package, so `init` there does not move the link.
+ */
+export const checkoutCopyFor = (projectRepository: string | null, packageRepository: string | null): PackageCopy =>
+  packageRepository === null || projectRepository === packageRepository ? PACKAGE_COPY.checkout : PACKAGE_COPY.installed
+
 /** A lane's worktree first, so a package installed into one never links either; a workspace link resolves to its checkout. */
-const packageCopyOf = (packageRoot: string): PackageCopy => {
+const packageCopyOf = (packageRoot: string, projectRoot: string): PackageCopy => {
   if (isLinkedWorktree(packageRoot)) return PACKAGE_COPY.laneWorktree
-  return isInstalledCopy(realPathOf(packageRoot)) ? PACKAGE_COPY.installed : PACKAGE_COPY.checkout
+  if (isInstalledCopy(realPathOf(packageRoot))) return PACKAGE_COPY.installed
+  return checkoutCopyFor(repositoryOf(projectRoot), repositoryOf(packageRoot))
 }
 
-export const linkHerdrPluginFrom = (packageRoot: string): string | null =>
+export const linkHerdrPluginFrom = ({
+  packageRoot,
+  projectRoot,
+}: {
+  packageRoot: string
+  projectRoot: string
+}): string | null =>
   linkHerdrPlugin({
     packageRoot,
     env: process.env,
     run: spawnHerdr(process.env),
-    copy: packageCopyOf(packageRoot),
+    copy: packageCopyOf(packageRoot, projectRoot),
   })

package/src/sync/init.ts

@@ -1,8 +1,8 @@
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { AGENTS_DIRECTORY, SKILLS_DIRECTORY } from '../claude/paths'
-import { type JackherdConfig, MODEL_ROLE, type ModelRole, parseJackherdConfig, type TerminalAdapter } from '../config'
-import { type RepositoryFacts, withDetected } from '../config/detect'
+import { type JackherdConfig, parseJackherdConfig, type TerminalAdapter } from '../config'
+import { type RepositoryFacts, STACKS, withDetected } from '../config/detect'
 import { CONFIG_FILE, CONFIG_SCHEMA_REFERENCE, TOOL_DIRECTORY } from '../config/location'
 import { readRepositoryFacts } from '../config/repository-facts'
 import type { KitSource } from './kit'
@@ -35,16 +35,6 @@ export type InitResult = {
   terminalAdapter: TerminalAdapter
 }
 
-// TODO: default model per role for a fresh project; the role list
-// itself is still a draft in config/schema.ts.
-export const DEFAULT_MODELS: Record<ModelRole, string> = {
-  [MODEL_ROLE.plan]: 'claude-opus-5-5',
-  [MODEL_ROLE.implement]: 'claude-sonnet-5-5',
-  [MODEL_ROLE.review]: 'claude-sonnet-5-5',
-  [MODEL_ROLE.explore]: 'claude-sonnet-5-5',
-  [MODEL_ROLE.orchestrate]: 'claude-opus-5-5',
-}
-
 /** What a global install, and a project that already has skills of kit names, puts before every kit name. */
 export const DEFAULT_SKILL_PREFIX = 'jh-'
 
@@ -64,13 +54,24 @@ export const collidingNames = (kit: KitSource, exists: (path: string) => boolean
     return agent ? [`${agent[1]} agent`] : []
   })
 
+/** Whether the repository holds the lock file of a stack that installs into `node_modules`, where `$schema` points. */
+const hasNodeLockFile = (facts: RepositoryFacts): boolean =>
+  Object.values(STACKS).some(
+    ({ installsIntoNodeModules, lockFiles }) =>
+      installsIntoNodeModules && lockFiles.some((file) => facts.lockFiles.includes(file)),
+  )
+
+/** The editor's `$schema` pointer, only where its target can exist; elsewhere it would point at nothing. */
+const schemaReference = (facts: RepositoryFacts): { $schema?: string } =>
+  hasNodeLockFile(facts) ? { $schema: CONFIG_SCHEMA_REFERENCE } : {}
+
 /**
  * The default config with every default spelled out, so the project sees what it can change; commands, lock file
- * and base branch as detected in the project.
+ * and base branch as detected in the project. A command detection could not decide stays out, never guessed.
  */
 const defaultConfigText = (facts: RepositoryFacts, skillPrefix: string, setup: SetupConfig | undefined): string => {
-  const config = parseJackherdConfig(withDetected({ models: DEFAULT_MODELS, skillPrefix, ...setup }, facts).raw)
-  return `${JSON.stringify({ $schema: CONFIG_SCHEMA_REFERENCE, ...config }, null, 2)}\n`
+  const config = parseJackherdConfig(withDetected({ skillPrefix, ...setup }, facts).raw)
+  return `${JSON.stringify({ ...schemaReference(facts), ...config }, null, 2)}\n`
 }
 
 /** What each repository decides for itself; a global config that spelled them out would set them for all. */
@@ -84,7 +85,7 @@ const withoutRepositoryValues = ({ baseBranch: _base, commands: _commands, lanes
  * lock file or base branch, so every repository gets its own detected ones.
  */
 const defaultGlobalConfigText = (setup: SetupConfig | undefined): string => {
-  const config = parseJackherdConfig({ models: DEFAULT_MODELS, skillPrefix: DEFAULT_SKILL_PREFIX, ...setup })
+  const config = parseJackherdConfig({ skillPrefix: DEFAULT_SKILL_PREFIX, ...setup })
   return `${JSON.stringify(withoutRepositoryValues(config), null, 2)}\n`
 }
 

package/src/sync/render.ts

@@ -1,5 +1,5 @@
 import type { JackherdConfig } from '../config'
-import { frozenInstallCommand } from '../config/detect'
+import { repositoryPlaceholderValues } from '../config/repository-values'
 import {
   ADDRESS_FORM,
   APPROVAL_TEXTS,
@@ -35,13 +35,10 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ['kit.responseAddress', ADDRESS_FORM[config.responseLanguage][config.responseAddress]],
     ['kit.planLanguage', LANGUAGE_NAME[config.planLanguage]],
     ['kit.planDirectory', config.planDirectory],
-    ['kit.baseBranch', config.baseBranch],
     ['kit.worktreeDirectory', config.worktreeDirectory],
     ...prefixed('model', config.models),
-    ...prefixed('command', config.commands),
+    ...repositoryPlaceholderValues(config),
     ['kit.lanes.copyCommand', laneCopyCommand(config.lanes.copy)],
-    ['kit.lanes.lockFile', config.lanes.lockFile],
-    ['kit.lanes.verifyInstall', frozenInstallCommand(config.commands.install)],
     ['kit.word.laneClosed', laneClosed],
     ['kit.word.openSubagents', openSubagents],
     ...prefixed('board', config.board),
@@ -62,7 +59,8 @@ export const listPlaceholders = (template: string): string[] =>
  * Fills the kit placeholders from the project config: `{{kit.model.<role>}}`,
  * `{{kit.command.<test|typecheck|lint|format|install|dev>}}`, `{{kit.lanes.<copyCommand|lockFile|verifyInstall>}}`, `{{kit.word.<laneClosed|openSubagents>}}`,
  * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
- * vocabulary, the two languages, `{{kit.responseAddress}}`, the plan and worktree directory and the base branch. Other
+ * vocabulary, the two languages, `{{kit.responseAddress}}`, the plan and worktree directory and the base branch. A
+ * command or lock file the config leaves unset renders as `unsetValueText`, never as a guessed default. Other
  * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project
  * file unrendered. `overrides` win over the config: a global kit renders what each repository decides as
  * `<name>` (`REPOSITORY_TOKENS`).

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
 }