jackherd 1.7.0 → 1.8.0

package/src/settled/board-row.ts

@@ -0,0 +1,133 @@
+import { sectionStart } from '../plan-format/markdown'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+
+/** One settled question as the board records it; `time` is when the coordinator settled it. */
+export type SettledEntry = {
+  time: Date
+  lane: string
+  question: string
+  answer: string
+  evidence: string
+  /** The state of the cited file: a short commit, or `uncommitted` when the checkout differs from it. */
+  evidenceVersion: string
+  wayBack: string | null
+}
+
+/** A local time split into the parts the board writes, each already two digits except the year. */
+type TimeParts = { year: number; month: string; day: string; clock: string }
+
+type BoardTexts = { heading: string; header: readonly string[]; notSent: string; time: (parts: TimeParts) => string }
+
+const BOARD_TEXTS: Record<PlanLanguage, BoardTexts> = {
+  [PLAN_LANGUAGE.de]: {
+    heading: 'Selbst beantwortet',
+    header: ['Zeit', 'Spur', 'Frage (ein Satz)', 'Antwort', 'Beleg', 'Rückweg'],
+    notSent: 'nicht gesendet',
+    time: ({ day, month, clock }) => `${day}.${month}. ${clock}`,
+  },
+  [PLAN_LANGUAGE.en]: {
+    heading: 'Settled',
+    header: ['Time', 'Lane', 'Question (one sentence)', 'Answer', 'Evidence', 'Way back'],
+    notSent: 'not sent',
+    time: ({ year, month, day, clock }) => `${year}-${month}-${day} ${clock}`,
+  },
+}
+
+const NO_WAY_BACK = '–'
+const SECTION_HEADING = /^##\s/
+
+/** The heading of the board section, in the board's language. */
+const settledHeading = (language: PlanLanguage): string => BOARD_TEXTS[language].heading
+
+/** Whether the line at `index` lies in a settled section, in any language: the nearest `## ` heading above names it. */
+export const isInSettledSection = (lines: readonly string[], index: number): boolean => {
+  const headings = Object.values(BOARD_TEXTS).map(({ heading }) => `## ${heading}`)
+  const above = lines
+    .slice(0, index + 1)
+    .reverse()
+    .find((line) => SECTION_HEADING.test(line))
+  return above !== undefined && headings.includes(above.trim())
+}
+
+const twoDigits = (value: number): string => String(value).padStart(2, '0')
+
+/** Local time as the board writes it: `DD.MM. hh:mm` in German, `YYYY-MM-DD hh:mm` in English. */
+export const settledTime = (time: Date, language: PlanLanguage): string =>
+  BOARD_TEXTS[language].time({
+    year: time.getFullYear(),
+    month: twoDigits(time.getMonth() + 1),
+    day: twoDigits(time.getDate()),
+    clock: `${twoDigits(time.getHours())}:${twoDigits(time.getMinutes())}`,
+  })
+
+/** Text that stays inside one table cell: on one line, with its pipes escaped. */
+const cell = (text: string): string => terminalSafe(text.replace(/\s+/g, ' ')).trim().replaceAll('|', '\\|')
+
+const tableLine = (cells: readonly string[]): string => `| ${cells.join(' | ')} |`
+
+/** The row: time, lane, question, answer, evidence, way back; a missing way back reads as a dash. */
+export const settledRow = (entry: SettledEntry, language: PlanLanguage): string =>
+  tableLine([
+    settledTime(entry.time, language),
+    `\`${cell(entry.lane)}\``,
+    cell(entry.question),
+    cell(entry.answer),
+    `\`${cell(`${entry.evidence}@${entry.evidenceVersion}`)}\``,
+    entry.wayBack === null ? NO_WAY_BACK : cell(entry.wayBack),
+  ])
+
+/** The entry with the failed send noted after its answer, in the board's language. */
+export const withSendFailure = (entry: SettledEntry, error: string, language: PlanLanguage): SettledEntry => ({
+  ...entry,
+  answer: `${entry.answer} (${BOARD_TEXTS[language].notSent}: ${error})`,
+})
+
+const tableHead = (language: PlanLanguage): string[] => {
+  const { header } = BOARD_TEXTS[language]
+  return [tableLine(header), `|${header.map((name) => '-'.repeat(name.length + 2)).join('|')}|`]
+}
+
+const withoutTrailingBlanks = (lines: readonly string[]): string[] => {
+  let end = lines.length
+  while (end > 0 && lines[end - 1].trim() === '') end -= 1
+  return lines.slice(0, end)
+}
+
+/** The board with a new section at its end that holds only the header and the row. */
+const withNewSection = (board: string, row: string, language: PlanLanguage): string => {
+  const head = withoutTrailingBlanks(board.split('\n'))
+  return [...head, '', `## ${settledHeading(language)}`, '', ...tableHead(language), row, ''].join('\n')
+}
+
+/** Index of the line after the section's first table, or -1 when the section has no table. */
+const afterFirstTable = (lines: readonly string[], start: number, end: number): number => {
+  const first = lines.findIndex((line, index) => index >= start && index < end && line.startsWith('|'))
+  if (first === -1) return -1
+  const after = lines.findIndex((line, index) => index > first && !line.startsWith('|'))
+  return after === -1 || after > end ? end : after
+}
+
+/**
+ * The board with the row appended to the section's table: after its last row, or, in a section without a table,
+ * as a new table at the end of the section. A board without the section gets it at its end.
+ */
+export const withSettledRow = (board: string, row: string, language: PlanLanguage): string => {
+  const start = sectionStart(board, settledHeading(language))
+  if (start === -1) return withNewSection(board, row, language)
+  const lines = board.split('\n')
+  const next = lines.findIndex((line, index) => index >= start && SECTION_HEADING.test(line))
+  const end = next === -1 ? lines.length : next
+  const insertAt = afterFirstTable(lines, start, end)
+  if (insertAt !== -1) return [...lines.slice(0, insertAt), row, ...lines.slice(insertAt)].join('\n')
+  const content = withoutTrailingBlanks(lines.slice(0, end))
+  return [...content, '', ...tableHead(language), row, '', ...lines.slice(end)].join('\n')
+}
+
+/** The board with `row` (the last line that equals it) replaced; appended as a new row when it is gone. */
+export const withReplacedRow = (board: string, row: string, replacement: string, language: PlanLanguage): string => {
+  const lines = board.split('\n')
+  const index = lines.lastIndexOf(row)
+  if (index === -1) return withSettledRow(board, replacement, language)
+  return [...lines.slice(0, index), replacement, ...lines.slice(index + 1)].join('\n')
+}

package/src/settled/check.ts

@@ -0,0 +1,129 @@
+import { isAbsolute, posix } from 'node:path'
+import { matchesAnyGlob } from '../check/glob'
+import { isInSettledSection } from './board-row'
+import { ALLOWED_TOPICS, isForbiddenTopic, isSettledTopic, type SettledTopic } from './topics'
+
+/** A lane question the coordinator answers itself, as `jh settled` received it; evidence and topic may be absent. */
+export type SettledRequest = {
+  lane: string
+  question: string
+  answer: string
+  /** `file:line`, relative to the checkout the command runs in. */
+  evidence: string | null
+  topic: string | null
+  wayBack: string | null
+}
+
+export type Evidence = { path: string; line: number }
+
+/** A request that passed every check: the topic is an allowed one, the evidence a line inside the checkout. */
+export type CheckedRequest = Omit<SettledRequest, 'evidence' | 'topic'> & { evidence: Evidence; topic: SettledTopic }
+
+export const REFUSAL = {
+  topicMissing: 'topicMissing',
+  topicUnknown: 'topicUnknown',
+  topicForbidden: 'topicForbidden',
+  evidenceMissing: 'evidenceMissing',
+  evidenceFormat: 'evidenceFormat',
+  evidenceOutside: 'evidenceOutside',
+  fileMissing: 'fileMissing',
+  lineMissing: 'lineMissing',
+  lineWithoutDecision: 'lineWithoutDecision',
+  evidenceSelfReference: 'evidenceSelfReference',
+} as const
+
+export type RefusalReason = (typeof REFUSAL)[keyof typeof REFUSAL]
+
+export type Refusal = { reason: RefusalReason; detail: string }
+
+export type CheckResult = { refusal: Refusal } | { checked: CheckedRequest }
+
+/** Reads a file by its path relative to the checkout; null when there is none. */
+export type EvidenceReader = (path: string) => string | null
+
+/**
+ * Files whose every line is evidence: they are rules an agent follows, written for that purpose. Fixed in the
+ * package, not a config key: a project that could widen this list could turn any file into evidence.
+ */
+const RULE_AND_SKILL_FILES: readonly string[] = [
+  '.claude/rules/**/*.md',
+  '.claude/skills/*/SKILL.md',
+  '.claude/project/*.md',
+  'CLAUDE.md',
+]
+
+const EVIDENCE = /^(.+):([1-9]\d*)$/
+const DATE = /\b\d{4}-\d{2}-\d{2}\b|\b\d{1,2}\.\d{1,2}\./
+const USER = /\bUser\b/
+
+/** `file:line` split at the last colon; null when the line is not a positive whole number. */
+export const parseEvidence = (text: string): Evidence | null => {
+  const match = EVIDENCE.exec(text.trim())
+  return match ? { path: match[1], line: Number(match[2]) } : null
+}
+
+export const isRuleOrSkillFile = (path: string): boolean => matchesAnyGlob(path, RULE_AND_SKILL_FILES)
+
+/** A line that records a decision of the user: a date and the word `User`, as plans and boards write it. */
+export const carriesUserDecision = (line: string): boolean => DATE.test(line) && USER.test(line)
+
+/** The path normalised inside the checkout; null when it is absolute or leaves the checkout. */
+const insideCheckout = (path: string): string | null => {
+  if (isAbsolute(path)) return null
+  const normalised = posix.normalize(path)
+  return normalised === '..' || normalised.startsWith('../') ? null : normalised
+}
+
+const topicCheck = (topic: string | null): Refusal | SettledTopic => {
+  if (topic === null)
+    return { reason: REFUSAL.topicMissing, detail: `--topic is required: ${ALLOWED_TOPICS.join(', ')}` }
+  if (!isSettledTopic(topic))
+    return { reason: REFUSAL.topicUnknown, detail: `unknown topic ${topic}; one of ${ALLOWED_TOPICS.join(', ')}` }
+  return isForbiddenTopic(topic)
+    ? { reason: REFUSAL.topicForbidden, detail: `${topic} is the user's decision, never settled in a lane's place` }
+    : topic
+}
+
+const lineRefusal = (evidence: Evidence, text: string): Refusal | null => {
+  const lines = text.split('\n')
+  if (evidence.line > lines.length)
+    return { reason: REFUSAL.lineMissing, detail: `${evidence.path} has ${lines.length} lines, not ${evidence.line}` }
+  if (isInSettledSection(lines, evidence.line - 1))
+    return {
+      reason: REFUSAL.evidenceSelfReference,
+      detail: `${evidence.path}:${evidence.line} is a settled answer itself, not the decision it rests on`,
+    }
+  if (isRuleOrSkillFile(evidence.path) || carriesUserDecision(lines[evidence.line - 1])) return null
+  return {
+    reason: REFUSAL.lineWithoutDecision,
+    detail: `${evidence.path}:${evidence.line} carries no date with "User" and is no rule or skill file`,
+  }
+}
+
+const evidenceCheck = (text: string | null, read: EvidenceReader): Refusal | Evidence => {
+  if (text === null) return { reason: REFUSAL.evidenceMissing, detail: '--evidence <file:line> is required' }
+  const parsed = parseEvidence(text)
+  if (!parsed) return { reason: REFUSAL.evidenceFormat, detail: `${text} is not <file>:<line>` }
+  const path = insideCheckout(parsed.path)
+  if (path === null) return { reason: REFUSAL.evidenceOutside, detail: `${parsed.path} lies outside the checkout` }
+  const content = read(path)
+  if (content === null) return { reason: REFUSAL.fileMissing, detail: `${path} does not exist` }
+  const evidence = { path, line: parsed.line }
+  return lineRefusal(evidence, content) ?? evidence
+}
+
+const isRefusal = (value: Refusal | Evidence | SettledTopic): value is Refusal =>
+  typeof value === 'object' && 'reason' in value
+
+/**
+ * The request ready to settle, or why the coordinator may not settle it itself. The topic is checked first, so a
+ * forbidden topic is refused before any file is read; then the evidence: the file exists in the checkout, the line
+ * exists, and it records a dated decision of the user unless the file is a rule or skill file.
+ */
+export const checkSettled = (request: SettledRequest, read: EvidenceReader): CheckResult => {
+  const topic = topicCheck(request.topic)
+  if (isRefusal(topic)) return { refusal: topic }
+  const evidence = evidenceCheck(request.evidence, read)
+  if (isRefusal(evidence)) return { refusal: evidence }
+  return { checked: { ...request, topic, evidence } }
+}

package/src/settled/command.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { TerminalAdapter } from '../config'
+import { boardFor, foundLanesOf } from '../plans/board-pick'
+import { fileGitFacts, mainCheckout, worktreeRoot } from '../plans/git'
+import { readSettings } from '../plans/settings'
+import { laneStatusSourceFor } from '../terminal'
+import { runHerdr } from '../terminal/herdr'
+import { evidenceVersionOf } from './evidence-version'
+import { parseSettledOptions } from './options'
+import { laneSenderFor } from './send'
+import { type SettleOutcome, type SettlePorts, settle } from './settle'
+
+const readFileIn =
+  (root: string) =>
+  (path: string): string | null => {
+    const file = join(root, path)
+    return existsSync(file) && statSync(file).isFile() ? readFileSync(file, 'utf8') : null
+  }
+
+const evidenceVersionIn =
+  (root: string) =>
+  (path: string): string =>
+    evidenceVersionOf(fileGitFacts(root, path))
+
+const portsFor = (checkout: string, boardFile: string, adapter: TerminalAdapter): SettlePorts => ({
+  readEvidence: readFileIn(checkout),
+  readBoard: () => readFileSync(boardFile, 'utf8'),
+  writeBoard: (text) => writeFileSync(boardFile, text),
+  send: laneSenderFor(adapter, runHerdr),
+  evidenceVersion: evidenceVersionIn(checkout),
+})
+
+const printOutcome = (outcome: SettleOutcome): void => {
+  for (const line of outcome.stdout) console.log(line)
+  for (const line of outcome.stderr) console.error(line)
+}
+
+/**
+ * `jh settled <lane> --question … --answer … --evidence <file:line> --topic <topic> [--way-back …] [--board …]`:
+ * the one way for the coordinator to answer a lane's question itself. Checks topic and evidence (in the checkout it
+ * runs in), appends the row to the board's settled section, sends the answer through `herdr agent prompt` and
+ * prints the line for the user's chat. Exit 0 settled, 1 refused or failed before anything was written, 2 written
+ * but not sent.
+ */
+export const run = async (args: string[]): Promise<number> => {
+  try {
+    const { request, boardPath } = parseSettledOptions(args)
+    const checkout = worktreeRoot(process.cwd())
+    const root = mainCheckout(process.cwd())
+    const settings = readSettings([checkout, root])
+    const terminal = laneStatusSourceFor(settings.adapter)
+    const board = boardFor(boardPath, [root, checkout], settings, () =>
+      foundLanesOf(root, settings, () => terminal.listAgents().map((agent) => agent.name)),
+    )
+    if (board.notice) console.error(board.notice)
+    const context = { now: new Date(), planLanguage: settings.planLanguage }
+    const outcome = settle(request, context, portsFor(checkout, board.file, settings.adapter))
+    printOutcome(outcome)
+    return outcome.exitCode
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/settled/evidence-version.ts

@@ -0,0 +1,14 @@
+import type { FileGitFacts } from '../plans/git'
+
+/** What the evidence cell says when the cited file is not as a commit holds it. */
+export const EVIDENCE_UNCOMMITTED = 'uncommitted'
+
+const SHORT_COMMIT = /^[0-9a-f]{7,64}$/
+
+/**
+ * The state of the evidence a settled row cites: the short commit that last changed the file, so the row can be
+ * checked against that version later, or `uncommitted` when the checkout differs from it or git cannot say
+ * (`status --porcelain` of the file and its last short commit, null when git failed).
+ */
+export const evidenceVersionOf = ({ status, commit }: FileGitFacts): string =>
+  status === '' && commit !== null && SHORT_COMMIT.test(commit) ? commit : EVIDENCE_UNCOMMITTED

package/src/settled/options.ts

@@ -0,0 +1,69 @@
+import { CLI_NAME } from '../version/release'
+import type { SettledRequest } from './check'
+
+/** The request to settle and the board `--board` names, null to let the board be picked. */
+export type SettledOptions = { request: SettledRequest; boardPath: string | null }
+
+const VALUE_OPTIONS = ['--question', '--answer', '--evidence', '--topic', '--way-back', '--board'] as const
+
+type ValueOption = (typeof VALUE_OPTIONS)[number]
+
+const LANE_NAME = /^[A-Za-z0-9._-]+$/
+
+const USAGE = `usage: ${CLI_NAME} settled <lane> --question <sentence> --answer <text> --evidence <file:line> --topic <topic> [--way-back <text>] [--board <board.md>]`
+
+const usageError = (message: string): Error => new Error(`${message}\n${USAGE}`)
+
+const isValueOption = (arg: string): arg is ValueOption => (VALUE_OPTIONS as readonly string[]).includes(arg)
+
+/** Splits the arguments into option values and the remaining words; throws on an unknown option or a missing value. */
+const splitArguments = (args: readonly string[]): { values: Map<ValueOption, string>; words: string[] } => {
+  const values = new Map<ValueOption, string>()
+  const words: string[] = []
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (!arg.startsWith('--')) {
+      words.push(arg)
+      continue
+    }
+    if (!isValueOption(arg)) throw usageError(`unknown option ${arg}`)
+    const value = args[i + 1]
+    if (value === undefined || value.startsWith('--')) throw usageError(`${arg} needs a value`)
+    values.set(arg, value)
+    i += 1
+  }
+  return { values, words }
+}
+
+const requiredText = (values: Map<ValueOption, string>, option: ValueOption): string => {
+  const value = values.get(option)?.trim()
+  if (!value) throw usageError(`${option} is required`)
+  return value
+}
+
+const laneOf = (words: readonly string[]): string => {
+  if (words.length === 0) throw usageError('the lane is required')
+  if (words.length > 1) throw usageError(`one lane at most, got ${words.join(' ')}`)
+  if (!LANE_NAME.test(words[0])) throw usageError(`${words[0]} is no lane name (letters, digits, . _ -)`)
+  return words[0]
+}
+
+/**
+ * Reads `<lane> --question … --answer … [--evidence …] [--topic …] [--way-back …] [--board …]` in any order. Lane,
+ * question and answer are required here; evidence and topic stay null when absent, so the check refuses them with
+ * its reason.
+ */
+export const parseSettledOptions = (args: readonly string[]): SettledOptions => {
+  const { values, words } = splitArguments(args)
+  return {
+    request: {
+      lane: laneOf(words),
+      question: requiredText(values, '--question'),
+      answer: requiredText(values, '--answer'),
+      evidence: values.get('--evidence') ?? null,
+      topic: values.get('--topic') ?? null,
+      wayBack: values.get('--way-back') ?? null,
+    },
+    boardPath: values.get('--board') ?? null,
+  }
+}

package/src/settled/send.ts

@@ -0,0 +1,27 @@
+import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
+import { errorText } from '../plans/error-text'
+import type { HerdrRunner } from '../terminal/herdr'
+
+/** Hands a text to a lane's agent; returns the error text, or null when the agent took it. */
+export type LaneSender = (lane: string, message: string) => string | null
+
+/**
+ * `herdr agent prompt <lane> <text>`, the way the coordinator prompts a lane: the text as one argument of the
+ * process, so no shell expands its backticks or `$(…)`.
+ */
+export const promptArguments = (lane: string, message: string): string[] => ['agent', 'prompt', lane, message]
+
+const NO_TERMINAL = `no terminal to reach the lane (terminal.adapter is ${TERMINAL_ADAPTER.none})`
+
+/** The sender for the configured terminal; without one (`none`) every send fails with the reason. */
+export const laneSenderFor =
+  (adapter: TerminalAdapter, run: HerdrRunner): LaneSender =>
+  (lane, message) => {
+    if (adapter === TERMINAL_ADAPTER.none) return NO_TERMINAL
+    try {
+      run(promptArguments(lane, message))
+      return null
+    } catch (error) {
+      return errorText(error)
+    }
+  }

package/src/settled/settle.ts

@@ -0,0 +1,87 @@
+import { errorText } from '../plans/error-text'
+import type { PlanLanguage } from '../vocabulary'
+import { type SettledEntry, settledRow, withReplacedRow, withSendFailure, withSettledRow } from './board-row'
+import { type CheckedRequest, checkSettled, type Evidence, type EvidenceReader, type SettledRequest } from './check'
+import type { LaneSender } from './send'
+
+/** The I/O `settle` drives. */
+export type SettlePorts = {
+  readEvidence: EvidenceReader
+  readBoard: () => string
+  writeBoard: (text: string) => void
+  send: LaneSender
+  /** The state of the cited file: a short commit, or `uncommitted`. */
+  evidenceVersion: (path: string) => string
+}
+
+/** When it runs and in which language the board is written; the lane is told in English. */
+export type SettleContext = { now: Date; planLanguage: PlanLanguage }
+
+export const SETTLE_EXIT = { settled: 0, refused: 1, notSent: 2 } as const
+
+export type SettleExit = (typeof SETTLE_EXIT)[keyof typeof SETTLE_EXIT]
+
+export type SettleOutcome = { exitCode: SettleExit; stdout: string[]; stderr: string[] }
+
+const evidenceText = ({ path, line }: Evidence): string => `${path}:${line}`
+
+/** What the lane receives: its question, the answer and the evidence, as written, in English words around them. */
+export const laneMessageOf = ({ question, answer, evidence }: CheckedRequest): string =>
+  `The coordinator’s answer to your question “${question}”: ${answer} (evidence: ${evidenceText(evidence)})`
+
+const entryOf = (request: CheckedRequest, now: Date, evidenceVersion: string): SettledEntry => ({
+  time: now,
+  lane: request.lane,
+  question: request.question,
+  answer: request.answer,
+  evidence: evidenceText(request.evidence),
+  evidenceVersion,
+  wayBack: request.wayBack,
+})
+
+/** The line for the user's chat, which the coordinator posts as it stands. */
+const chatLine = (request: CheckedRequest): string =>
+  `settled ${request.lane}: ${request.question} → ${request.answer} (evidence ${evidenceText(request.evidence)})`
+
+/**
+ * Notes the failed send in the row the board holds now, so rows written meanwhile stay. Returns why the note could
+ * not be written, or null; the send has failed either way, so a board error must not turn exit 2 into exit 1.
+ */
+const noteFailure = (entry: SettledEntry, error: string, context: SettleContext, ports: SettlePorts): string | null => {
+  const row = settledRow(entry, context.planLanguage)
+  const noted = settledRow(withSendFailure(entry, error, context.planLanguage), context.planLanguage)
+  try {
+    ports.writeBoard(withReplacedRow(ports.readBoard(), row, noted, context.planLanguage))
+    return null
+  } catch (noteError) {
+    return errorText(noteError)
+  }
+}
+
+const notSent = (request: CheckedRequest, error: string, noteError: string | null): SettleOutcome => ({
+  exitCode: SETTLE_EXIT.notSent,
+  stdout: [chatLine(request)],
+  stderr:
+    noteError === null
+      ? [`not sent to ${request.lane}: ${error}; the board row says so`]
+      : [`not sent to ${request.lane}: ${error}`, `board row not annotated: ${noteError}`],
+})
+
+/**
+ * Settles a lane question in an order that never does half of it: check topic and evidence, then write the board
+ * row, then send the answer to the lane. A refusal touches neither board nor lane. A send that fails after the row
+ * was written is said on stderr and noted in that row, so the board never claims an answer the lane did not get.
+ */
+export const settle = (request: SettledRequest, context: SettleContext, ports: SettlePorts): SettleOutcome => {
+  const result = checkSettled(request, ports.readEvidence)
+  if ('refusal' in result) {
+    const { reason, detail } = result.refusal
+    return { exitCode: SETTLE_EXIT.refused, stdout: [], stderr: [`refused (${reason}): ${detail}`] }
+  }
+  const { checked } = result
+  const entry = entryOf(checked, context.now, ports.evidenceVersion(checked.evidence.path))
+  ports.writeBoard(withSettledRow(ports.readBoard(), settledRow(entry, context.planLanguage), context.planLanguage))
+  const error = ports.send(checked.lane, laneMessageOf(checked))
+  if (error === null) return { exitCode: SETTLE_EXIT.settled, stdout: [chatLine(checked)], stderr: [] }
+  return notSent(checked, error, noteFailure(entry, error, context, ports))
+}

package/src/settled/topics.ts

@@ -0,0 +1,56 @@
+/**
+ * What a question the coordinator settles itself is about. A fixed vocabulary in the package, not a config value:
+ * a project that could add topics could also drop a forbidden one. The forbidden ones are part of the vocabulary so
+ * a refusal can name them instead of calling them unknown.
+ */
+export const SETTLED_TOPIC = {
+  scope: 'scope',
+  design: 'design',
+  followUp: 'follow-up',
+  naming: 'naming',
+  codeStyle: 'code-style',
+  test: 'test',
+  documentation: 'documentation',
+  board: 'board',
+  dependency: 'dependency',
+  merge: 'merge',
+  release: 'release',
+  publish: 'publish',
+  migration: 'migration',
+  money: 'money',
+  auth: 'auth',
+  rls: 'rls',
+  secrets: 'secrets',
+  stageWrite: 'stage-write',
+  productionWrite: 'production-write',
+  deletion: 'deletion',
+  push: 'push',
+} as const
+
+export type SettledTopic = (typeof SETTLED_TOPIC)[keyof typeof SETTLED_TOPIC]
+
+/** Topics the user decides every time; the coordinator never answers them in a lane's place. */
+export const FORBIDDEN_TOPICS: readonly SettledTopic[] = [
+  SETTLED_TOPIC.dependency,
+  SETTLED_TOPIC.merge,
+  SETTLED_TOPIC.release,
+  SETTLED_TOPIC.publish,
+  SETTLED_TOPIC.migration,
+  SETTLED_TOPIC.money,
+  SETTLED_TOPIC.auth,
+  SETTLED_TOPIC.rls,
+  SETTLED_TOPIC.secrets,
+  SETTLED_TOPIC.stageWrite,
+  SETTLED_TOPIC.productionWrite,
+  SETTLED_TOPIC.deletion,
+  SETTLED_TOPIC.push,
+]
+
+export const isForbiddenTopic = (topic: SettledTopic): boolean => FORBIDDEN_TOPICS.includes(topic)
+
+export const ALLOWED_TOPICS: readonly SettledTopic[] = Object.values(SETTLED_TOPIC).filter(
+  (topic) => !isForbiddenTopic(topic),
+)
+
+export const isSettledTopic = (value: string): value is SettledTopic =>
+  (Object.values(SETTLED_TOPIC) as string[]).includes(value)

package/src/sync/command.ts

@@ -1,4 +1,7 @@
-import { CLI_NAME } from '../version/release'
+import { existsSync } from 'node:fs'
+import { hasProjectInstall } from '../config/legacy-names'
+import { configCandidates } from '../config/location'
+import { CLI_NAME, PACKAGE_NAME } from '../version/release'
 import {
   type CommandContext,
   defaultContext,
@@ -62,6 +65,16 @@ export const parseSyncArgs = (args: string[]): SyncArgs => {
   return { ok: true, accept, global, ifChanged, check }
 }
 
+/**
+ * True when `root` has a project config but no project install: the config holds settings for the global install,
+ * and only `jh init` may turn it into a project install.
+ */
+const isConfigWithoutInstall = (root: string, exists: (path: string) => boolean): boolean =>
+  configCandidates(root).some(exists) && !hasProjectInstall(root, exists)
+
+const notInstalledLine = (root: string): string =>
+  `${CLI_NAME} sync: ${root} has a ${PACKAGE_NAME} config but no project install, so nothing was synced. \`${CLI_NAME} init\` installs the kit here; \`${CLI_NAME} sync ${GLOBAL_FLAG}\` updates the global kit.`
+
 const syncGlobal = (context: CommandContext, accept: string[]): Promise<number> =>
   runWithKit(context, 'sync', async (kit) => {
     const result = await runGlobalSync({ home: context.home, kit, accept, configHome: context.configHome })
@@ -98,6 +111,8 @@ export const runSyncCommand = async (
   const { accept, global, ifChanged, check: dryRun } = parsed
   if (ifChanged) return syncGlobalIfChanged(context, accept, check)
   if (global) return syncGlobal(context, accept)
+  if (isConfigWithoutInstall(context.projectRoot, existsSync))
+    return usageError(context, notInstalledLine(context.projectRoot))
   return runWithKit(
     context,
     'sync',

package/src/sync/render.ts

@@ -1,6 +1,13 @@
 import type { JackherdConfig } from '../config'
 import { frozenInstallCommand } from '../config/detect'
-import { ADDRESS_FORM, APPROVAL_TEXTS, LANGUAGE_NAME, PLAN_VOCABULARY, SELF_MERGE_LABEL } from '../vocabulary'
+import {
+  ADDRESS_FORM,
+  APPROVAL_TEXTS,
+  LANGUAGE_NAME,
+  PLAN_APPROVAL_LABELS,
+  PLAN_VOCABULARY,
+  SELF_MERGE_LABEL,
+} from '../vocabulary'
 
 const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
 
@@ -22,7 +29,7 @@ const prefixed = (prefix: string, values: Record<string, string>): [string, stri
 
 /** Every placeholder a kit file may use, with its value for this project. */
 const placeholderValues = (config: JackherdConfig): Map<string, string> => {
-  const { header, sections, columns, phase, laneClosed } = PLAN_VOCABULARY[config.planLanguage]
+  const { header, sections, columns, phase, laneClosed, openSubagents } = PLAN_VOCABULARY[config.planLanguage]
   return new Map([
     ['kit.responseLanguage', LANGUAGE_NAME[config.responseLanguage]],
     ['kit.responseAddress', ADDRESS_FORM[config.responseLanguage][config.responseAddress]],
@@ -36,9 +43,11 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ['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),
     ['kit.guard.selfMergeLabel', SELF_MERGE_LABEL[config.responseLanguage]],
     ['kit.guard.selfMerge', config.guard.selfMerge.offer ? 'offered' : 'not offered'],
+    ...prefixed('guard.planApproval', PLAN_APPROVAL_LABELS[config.responseLanguage]),
     ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
@@ -51,8 +60,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}}`,
- * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
+ * `{{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.planApproval.<approve|revoke>}}`, `{{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
  * `{{…}}` 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