@joshuafolkken/kit 1.872.0

package/scripts/lint/cspell-cached.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { CSPELL_CACHE_FILE, CSPELL_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { lane_cache_run } from '#scripts/lane/lane-cache-run'
+import { buffered_process, FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
+
+const ARGV_START = 2
+// `--no-progress` turns off cspell's per-file `N/1607 <path> cached` line (joshuafolkken/kit#2296).
+// Those lines ran to 1,607 of them — the whole output past the 8,000-character tool cap — so a gate
+// that failed on one unknown word buried the failure under progress and a run could read only the
+// first of several failures. The summary and the issue lines it prints are untouched; only the
+// progress reporter is silenced.
+const CSPELL_NO_PROGRESS = '--no-progress'
+const CSPELL_ARGS = [
+	'exec',
+	'cspell',
+	'.',
+	'--dot',
+	CSPELL_NO_PROGRESS,
+	...CSPELL_CACHE_FLAGS,
+] as const
+
+// The wrapper puts cache transfer directly around cspell rather than around the whole gate (#2060),
+// so a later failing check cannot prevent a completed cache from reaching the primary checkout.
+async function run(extra_arguments: ReadonlyArray<string> = []): Promise<number> {
+	const result = await lane_cache_run.run(
+		CSPELL_CACHE_FILE,
+		async () => await buffered_process.run_buffered_process([...CSPELL_ARGS, ...extra_arguments]),
+	)
+	if (result.output) process.stdout.write(result.output)
+
+	return buffered_process.is_process_failed(result) ? FAIL_EXIT_CODE : 0
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_START))
+}
+
+const cspell_cached = { run }
+
+export { CSPELL_ARGS, cspell_cached }

package/scripts/lint/lint-parallel.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { ESLINT_CACHE_FILE, ESLINT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { lane_cache_run } from '#scripts/lane/lane-cache-run'
+import {
+	buffered_process,
+	FAIL_EXIT_CODE,
+	type BufferedProcessResult,
+} from '#scripts/lib/buffered-process'
+
+const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
+// This — not the `lint:eslint` map entry — is the eslint invocation `josh gate` reaches, so the
+// cache flags come from the same constant the ignore rules are asserted against
+// (joshuafolkken/kit#1256). A copy here would keep writing the old location the day that constant
+// moves, with every test still green.
+const ESLINT_ARGS = ['exec', 'eslint', '.', ...ESLINT_CACHE_FLAGS] as const
+
+async function run_eslint(
+	eslint_args: ReadonlyArray<string>,
+	cache_file: string,
+): Promise<BufferedProcessResult> {
+	return await lane_cache_run.run(
+		cache_file,
+		async () => await buffered_process.run_buffered_process(eslint_args),
+	)
+}
+
+function write_output(result: BufferedProcessResult): void {
+	if (result.output) process.stdout.write(result.output)
+}
+
+function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcessResult): number {
+	return buffered_process.is_process_failed(prettier) || buffered_process.is_process_failed(eslint)
+		? FAIL_EXIT_CODE
+		: 0
+}
+
+// The two checks are run from here whether they were pointed at the whole tree or at one change's
+// files, so `josh lint:related` reaches prettier and eslint through the same buffering, the same
+// "one failure does not abort the other" reading, and the same exit code (joshuafolkken/kit#1298).
+async function run_lint_checks(
+	prettier_args: ReadonlyArray<string>,
+	eslint_args: ReadonlyArray<string>,
+	eslint_cache_file: string = ESLINT_CACHE_FILE,
+): Promise<number> {
+	const [prettier, eslint] = await Promise.all([
+		buffered_process.run_buffered_process(prettier_args),
+		run_eslint(eslint_args, eslint_cache_file),
+	])
+
+	write_output(prettier)
+	write_output(eslint)
+
+	return lint_exit_code(prettier, eslint)
+}
+
+async function run_lint_parallel_checks(): Promise<number> {
+	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS)
+}
+
+// `process.exitCode` rather than `process.exit()`: both reports are buffered and written here in
+// one go, and `process.exit()` truncates a piped stdout at its buffer size — which is exactly how
+// this command is read when `josh gate` runs it as one of four concurrent checks. Setting the code
+// lets the writes drain and the process end on its own, which it can, since both children have
+// already exited by here.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_lint_parallel_checks()
+}
+
+const lint_parallel = { run_lint_checks, run_lint_parallel_checks }
+
+export { ESLINT_ARGS, lint_parallel }

package/scripts/lint/lint-related-scope.ts

@@ -0,0 +1,128 @@
+import path from 'node:path'
+import {
+	changed_file_scope,
+	type ChangedFileScope,
+	type ScopeInputs,
+	type ScopeVocabulary,
+} from '#scripts/git/changed-file-scope'
+import { ESLINT_RELATED_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+
+// joshuafolkken/kit#1298: `josh lint` read the whole repository on every call, and an
+// implementation loop calls it after every few edits. Measured across four runs with
+// `pnpm josh time`, that came to 47–188 seconds per run — 18% of #1292's 1,043-second
+// implementation phase, spent re-reading files the change never touched.
+//
+// **This narrowing is added in front of the whole check, never in place of it.** `josh gate` still
+// runs `josh lint` over everything before the commit: a formatting rule can be broken by a file the
+// change did not name (a shared config, a generated snapshot), and only the whole-tree run sees
+// that. What the narrowing replaces is the repeat calls in between.
+//
+// The decision this file makes is which extensions the two linters read, and how each of them is
+// asked about a file list instead of a directory. Everything it shares with `josh test:related` —
+// reading the change, dropping what the tree no longer holds, and the two fallbacks — is
+// `changed-file-scope.ts`.
+
+// What prettier or eslint reads in a kit project. A changed image, font or archive is dropped
+// rather than passed through: neither linter has anything to say about it, so a run narrowed to one
+// of them would check nothing while reporting success.
+//
+// **A lock file is not dropped here** — `.yaml` and `.json` are on this list because a hand-written
+// config of either kind is prettier's to check. `pnpm-lock.yaml` therefore reaches both children
+// and is skipped by each on its own terms: `.prettierignore` names it, and eslint has no
+// configuration matching it. That is the same treatment the whole-tree `josh lint` gives it.
+const LINTABLE_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+	'.vue',
+	'.md',
+	'.mdx',
+	'.json',
+	'.jsonc',
+	'.json5',
+	'.yaml',
+	'.yml',
+	'.css',
+	'.scss',
+	'.less',
+	'.html',
+	'.graphql',
+	'.gql',
+])
+
+const NOTHING_LINTABLE_REASON = 'no changed file is one prettier or eslint reads'
+
+const COMMAND_NAME = 'lint:related'
+const COMMAND_LABEL = `josh ${COMMAND_NAME}`
+
+const VOCABULARY: ScopeVocabulary = {
+	label: COMMAND_LABEL,
+	fallback_suffix: 'checking the whole tree instead',
+	narrowed_suffix: 'checking only them',
+}
+
+// `--ignore-unknown` is what lets one file list go to prettier whole: a `.svelte` file prettier has
+// no plugin for, or an extension it does not parse, is skipped rather than failing the run. Without
+// it, prettier exits non-zero on the first file it cannot read, which is a failure about the file
+// list rather than about the code.
+const PRETTIER_ARGS = ['exec', 'prettier', '--check', '--ignore-unknown'] as const
+// `--no-warn-ignored` is the counterpart on the eslint side. A changed `.md` or a file under an
+// `ignores` entry is passed in with the rest, and eslint warns once per such file when it is named
+// explicitly — noise that would bury the findings the run exists to show.
+const ESLINT_ARGS = ['exec', 'eslint'] as const
+const ESLINT_SCOPED_FLAGS = ['--no-warn-ignored'] as const
+
+function is_lintable(file_path: string): boolean {
+	return LINTABLE_EXTENSIONS.has(path.extname(file_path))
+}
+
+// The three inputs that make the shared narrowing this command's, handed over as one value so the
+// CLI and the function below cannot disagree about any of them.
+function scope_inputs(is_present: (file_path: string) => boolean): ScopeInputs {
+	return { is_present, is_selectable: is_lintable, nothing_reason: NOTHING_LINTABLE_REASON }
+}
+
+function describe_scope(scope: ChangedFileScope, root: string): string {
+	return changed_file_scope.describe_scope(scope, root, VOCABULARY)
+}
+
+function prettier_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
+	return [...PRETTIER_ARGS, ...files]
+}
+
+// The cache file is this command's own rather than the gate's, because the two run at the same time
+// (joshuafolkken/kit#1347). `josh gate` lints the whole tree beside the review while an
+// implementation loop calls this command between edits, and each eslint run rewrites its cache file
+// whole from the copy it loaded at start-up — so on one file the run that finished last discarded
+// the other's entries, and a narrowed run finishing during a whole-tree run rolled the cache back to
+// its pre-gate state.
+//
+// **The earlier comment here claimed the opposite and was reasoning about the wrong thing.** It said
+// sharing let a narrowed run warm the gate's cache, since eslint leaves the entries a run did not
+// visit alone; that holds for pruning and says nothing about two writers. It is the same judgement
+// joshuafolkken/kit#1332 made for the edit hook, applied to the second place it was needed.
+//
+// **What is narrowed is still only the target list, never the gate.** `josh gate` runs `josh lint`
+// over the whole tree before any commit; this file decides which files a repeat call reads.
+function eslint_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
+	return [...ESLINT_ARGS, ...files, ...ESLINT_RELATED_CACHE_FLAGS, ...ESLINT_SCOPED_FLAGS]
+}
+
+const lint_related_scope = {
+	COMMAND_LABEL,
+	COMMAND_NAME,
+	NOTHING_LINTABLE_REASON,
+	describe_scope,
+	eslint_arguments,
+	is_lintable,
+	prettier_arguments,
+	scope_inputs,
+}
+
+export { lint_related_scope }

package/scripts/lint/lint-related.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env tsx
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { document_byte_check } from '#scripts/document/document-byte-check'
+import { scoped_green } from '#scripts/gate/scoped-green'
+import { changed_file_scope, type ChangedFileScope } from '#scripts/git/changed-file-scope'
+import { ESLINT_RELATED_CACHE_FILE } from '#scripts/josh/josh-command-types'
+import { review_stamps } from '#scripts/review/review-stamps'
+import { lint_parallel } from './lint-parallel'
+import { lint_related_scope } from './lint-related-scope'
+
+// `josh lint:related` — the lint check an implementation loop runs between edits
+// (joshuafolkken/kit#1298). The narrowing itself is `lint-related-scope.ts` over the shared
+// decision in `changed-file-scope.ts`; this is the process around it — how the run reaches the same
+// two child processes `josh lint` runs.
+
+// Flags are named rather than forwarded. `josh test:related` forwards them because it has one
+// child; this has two, and prettier and eslint take different ones — `--fix` means something to
+// eslint and nothing to `prettier --check`. Sending a flag to both would fail the run over the
+// argument list, and dropping it silently would run a check the caller did not ask for, so the run
+// says which arguments it ignored.
+function report_ignored_flags(command_arguments: ReadonlyArray<string>): void {
+	const flags = changed_file_scope.flags_of(command_arguments)
+
+	if (flags.length === 0) return
+
+	process.stdout.write(
+		`${lint_related_scope.COMMAND_LABEL}: ignored — prettier and eslint take different flags: ${flags.join(' ')}\n`,
+	)
+}
+
+// A fallback to the whole project is a superset of the changed files, so it vouches for them too —
+// which is why the record below is written from either arm rather than only from the narrow one.
+async function lint_exit_code(scope: ChangedFileScope): Promise<number> {
+	if (scope.mode === 'all') return await lint_parallel.run_lint_parallel_checks()
+
+	return await lint_parallel.run_lint_checks(
+		lint_related_scope.prettier_arguments(scope.files),
+		lint_related_scope.eslint_arguments(scope.files),
+		ESLINT_RELATED_CACHE_FILE,
+	)
+}
+
+// The byte check over the same scope the lint just ran: the resolved file list when narrowed, and
+// the whole budget when lint fell back to the whole tree — so the byte check is a superset in the
+// fallback exactly as lint is, never an empty list that would pass silently (joshuafolkken/kit#2176).
+function byte_check_exit_code(scope: ChangedFileScope, root: string): number {
+	if (scope.mode === 'all') return document_byte_check.check_all(root)
+
+	return document_byte_check.check_files(root, scope.files)
+}
+
+// The lint result folded together with the fast byte-ceiling check (joshuafolkken/kit#2176): the
+// same check the gate's `document-byte-budget.test.ts` runs, brought forward to this between-edits
+// path so a mandated documentation update over its ceiling surfaces in seconds. It reads no change
+// of its own — it takes the files this run already resolved, so the git contract is the lint
+// command's alone. A lint failure is reported as-is; only a green lint runs the byte check, so the
+// two never race to the exit code, and a green tree here is green on both — which is what the record
+// below then vouches for.
+async function scoped_exit_code(scope: ChangedFileScope, root: string): Promise<number> {
+	const lint_exit = await lint_exit_code(scope)
+	if (lint_exit !== 0) return lint_exit
+
+	return byte_check_exit_code(scope, root)
+}
+
+// The narrowing line is printed before either child starts, so a scoped run is never read as a
+// whole one, and a fallback says which of the two it was rather than looking like a narrow run
+// that found nothing.
+//
+// **A green run leaves a record of the tree it was green on** (joshuafolkken/kit#1511), so
+// `josh review:brief` can tell a tree this check has read from one it has not. What the record means,
+// and the three states in which it is withheld, are `scoped-green.ts`.
+async function run_related_lint(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const root = await changed_file_scope.repository_root_or_cwd()
+	const scope = await changed_file_scope.resolve_command_scope({
+		command_arguments,
+		root,
+		inputs: lint_related_scope.scope_inputs(existsSync),
+	})
+
+	changed_file_scope.report_unusable_arguments(
+		command_arguments,
+		scope,
+		lint_related_scope.COMMAND_LABEL,
+	)
+	report_ignored_flags(command_arguments)
+	process.stdout.write(`${lint_related_scope.describe_scope(scope, root)}\n`)
+
+	const before = await scoped_green.read_before(command_arguments)
+	const exit_code = await scoped_exit_code(scope, root)
+
+	await scoped_green.record_if_green(review_stamps.lint_related_stamp, { before, exit_code })
+
+	return exit_code
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_related_lint(process.argv.slice(changed_file_scope.ARGV_START))
+}
+
+const lint_related = { report_ignored_flags, run_related_lint }
+
+export { lint_related }

package/scripts/managed-marker/index.ts

@@ -0,0 +1,5 @@
+// The public surface a downstream distribution package imports to stamp the workflows it writes.
+// Exported rather than left internal because the alternative is every distributor re-implementing
+// the header, and a second implementation that spells the token differently or stacks a duplicate
+// silently breaks the check that reads it (joshuafolkken/kit#844).
+export { managed_marker_logic } from './managed-marker-logic'

package/scripts/managed-marker/managed-marker-logic.ts

@@ -0,0 +1,67 @@
+import { is_workflow_destination } from '#scripts/claude/workflow-destination'
+
+// Which package overwrites a given workflow is a question only that package can answer, and the
+// answer has to survive being copied on: a consumer of a consumer receives `ci.yml` from kit and
+// `dast.yml` from app-kit, and neither distributor knows what the other manages. So the answer is
+// written into the artifact rather than kept in a list beside it — every distributor stamps its own
+// output, and the auto-merge workflow reads the stamp off the very file it is asking about
+// (joshuafolkken/kit#844).
+//
+// A list cannot reach that far. kit's write time is the only moment kit controls, and at that moment
+// it knows nothing of what app-kit distributes; whichever sync ran last would decide the list, and
+// the list would drift from the files it claims to describe — which is exactly the defect #844
+// reports, one distribution tier below the loop #836 closed.
+//
+// The stamp also draws the line the old list could only describe in prose. `deploy-vps.yml` is
+// patched by sync but written directly rather than through this transform, so it is never stamped
+// and a bump to its own pins still merges — a property of how the file is written, not of anyone
+// remembering to leave it out of a list.
+// The note names no command, because the package on the line above is not always this one: a
+// package built on kit distributes its own workflows through its own `sync`, and stamps them with
+// its own name through this same function.
+const MARKER_TOKEN = 'josh-managed-workflow:'
+const MARKER_PREFIX = `# ${MARKER_TOKEN}`
+const MARKER_NOTE = 'Overwritten on every sync of that package. Edit it there, not here.'
+
+function marker_block(package_name: string): string {
+	return `${MARKER_PREFIX} ${package_name}\n# ${MARKER_NOTE}\n`
+}
+
+// Recognized by the first line rather than by the token appearing anywhere, because the auto-merge
+// workflow declares the token in its own `env` to match on — a substring test would read that
+// template as already stamped and skip it, leaving the one file that performs the check unmarked.
+function is_marked(text: string): boolean {
+	return text.startsWith(MARKER_PREFIX)
+}
+
+// `package_name` is the distributor's own name, so a package built on kit stamps its files as its
+// own rather than mis-attributing them to kit. The auto-merge workflow matches the token, not any
+// particular name, so every tier's stamp is recognized by the same check.
+//
+// An already-stamped file is left alone whoever stamped it, because the name is for the human who
+// opens the file and the check does not read it. Re-attributing a file one distributor stamped and
+// another later overwrote is a real question, but not one with a consumer yet — it belongs with the
+// package that first does it, not with a guess made here.
+function apply_marker_for_destination(
+	destination: string,
+	text: string,
+	package_name: string,
+): string {
+	if (!is_workflow_destination(destination)) return text
+	if (is_marked(text)) return text
+
+	return `${marker_block(package_name)}${text}`
+}
+
+// `marker_block` stays out of the published surface: it composes a header unconditionally, so a
+// distributor reaching for it instead of `apply_marker_for_destination` would stack a second one on
+// every sync. The token and prefix are published because a consumer may want to match on them, and
+// `is_marked` because that is the matching rule itself.
+const managed_marker_logic = {
+	MARKER_TOKEN,
+	MARKER_PREFIX,
+	is_marked,
+	apply_marker_for_destination,
+}
+
+export { managed_marker_logic }

package/scripts/observations/observation-ledger-home.ts

@@ -0,0 +1,32 @@
+import path from 'node:path'
+import { repo_discovery } from '#scripts/discovery/repo-discovery'
+import { OBSERVATION_LEDGER_PATH } from './observation-ledger'
+
+// Where the observation ledger is read and written, whichever work tree a command runs in
+// (joshuafolkken/kit#2419).
+//
+// **The ledger lives in the primary checkout, never in a lane.** A lane is a linked work tree that is
+// closed once its branch merges, and the ledger is excluded from ordinary staging — so a line appended
+// in a lane had no route to the default branch: `pnpm josh followup`'s flush needs `pnpm josh ms`,
+// which a lane refuses, and `lane:close` does not carry the file. Resolving the ledger to the primary
+// checkout at every reader and writer puts the line where the flush already works, rather than adding
+// a second route that moves it there afterwards.
+//
+// The primary checkout is `repo_discovery.main_worktree`'s answer, reused rather than spelled again;
+// in an ordinary checkout it is the given directory itself, so nothing outside a lane changes.
+
+function ledger_root(cwd: string = process.cwd()): string {
+	return repo_discovery.main_worktree(cwd)
+}
+
+function is_lane(cwd: string = process.cwd()): boolean {
+	return path.resolve(ledger_root(cwd)) !== path.resolve(cwd)
+}
+
+function ledger_path(cwd: string = process.cwd()): string {
+	return path.join(ledger_root(cwd), OBSERVATION_LEDGER_PATH)
+}
+
+const observation_ledger_home = { is_lane, ledger_path, ledger_root }
+
+export { observation_ledger_home }

package/scripts/observations/observation-ledger-line.ts

@@ -0,0 +1,93 @@
+// The observation ledger's line grammar (`.claude/skills/workflow-commands/observation-filing.md`)
+// is fixed — `- k:<slug> | d<n> | <YYYY-MM-DD> | <where> | <what>` — but the path was collected in
+// `observation-ledger.ts` without a line ever being parsed, so a malformed append rode a flush
+// through unremarked. This validates a ledger entry line and reports why a broken one is broken
+// (joshuafolkken/kit#2123). The grammar is the single source's, pinned by the document test.
+
+const KEY_PREFIX = '- k:'
+const FIELD_SEPARATOR = ' | '
+const FIELD_COUNT = 5
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u
+// `d1` and up — never `d0`, since a depth-0 observation goes straight to an issue rather than the
+// ledger.
+const DEPTH_PATTERN = /^d[1-9]\d*$/u
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u
+const SLUG_REASON = 'the slug must be lowercase words joined by `-`'
+const DEPTH_REASON = 'the depth must be `d1` or higher (never `d0`)'
+const DATE_REASON = 'the date must be `YYYY-MM-DD`'
+const WHERE_REASON = 'the `where` field is empty'
+const WHAT_REASON = 'the `what` field is empty'
+
+interface BrokenLine {
+	line: string
+	reason: string
+}
+
+// A ledger entry line, as opposed to prose or a heading — only these are held to the grammar.
+function is_ledger_entry_line(line: string): boolean {
+	return line.trimStart().startsWith(KEY_PREFIX)
+}
+
+function slug_of(first_field: string): string {
+	return first_field.trimStart().slice(KEY_PREFIX.length)
+}
+
+// The `?? ''` lives in these small helpers rather than in `field_reason`, so that function stays a
+// single lookup with no branching of its own.
+function is_present(field: string | undefined): boolean {
+	return (field ?? '').trim().length > 0
+}
+
+function matches(pattern: RegExp, field: string | undefined): boolean {
+	return pattern.test(field ?? '')
+}
+
+function slug_ok(key_field: string | undefined): boolean {
+	return SLUG_PATTERN.test(slug_of(key_field ?? ''))
+}
+
+// Each field's check paired with the reason it fails, so `field_reason` is a single lookup for the
+// first failing field rather than a chain of branches.
+function field_reason(fields: ReadonlyArray<string>): string | undefined {
+	const [key_field, depth, date, where, what] = fields
+	const checks: ReadonlyArray<readonly [boolean, string]> = [
+		[slug_ok(key_field), SLUG_REASON],
+		[matches(DEPTH_PATTERN, depth), DEPTH_REASON],
+		[matches(DATE_PATTERN, date), DATE_REASON],
+		[is_present(where), WHERE_REASON],
+		[is_present(what), WHAT_REASON],
+	]
+
+	return checks.find(([is_valid]) => !is_valid)?.[1]
+}
+
+// The reason a ledger entry line breaks the grammar, or `undefined` when it conforms. Too few fields
+// or a `|` inside `<what>` both land as the wrong field count, since a conforming `<what>` carries no
+// vertical bar.
+function line_reason(line: string): string | undefined {
+	const fields = line.split(FIELD_SEPARATOR)
+
+	if (fields.length !== FIELD_COUNT) {
+		return `expected ${String(FIELD_COUNT)} fields separated by " | " (a \`|\` in the last field is not allowed)`
+	}
+
+	return field_reason(fields)
+}
+
+// Every ledger entry line that breaks the grammar, paired with why; an empty array is a clean ledger.
+function broken_ledger_lines(content: string): ReadonlyArray<BrokenLine> {
+	return content
+		.split('\n')
+		.filter((line) => is_ledger_entry_line(line))
+		.map((line) => ({ line, reason: line_reason(line) }))
+		.filter((entry): entry is BrokenLine => entry.reason !== undefined)
+}
+
+const observation_ledger_line = {
+	broken_ledger_lines,
+	is_ledger_entry_line,
+	line_reason,
+}
+
+export type { BrokenLine }
+export { observation_ledger_line }

package/scripts/observations/observation-ledger.ts

@@ -0,0 +1,35 @@
+// The observation ledger's one path, named here rather than inside any of the places that act on it
+// (joshuafolkken/kit#1756). `git-staging.ts` excludes it from every ordinary commit,
+// `hook-gate-reuse.ts` excludes it from what a hook calls a carried tree, and
+// `observations-flush.ts` is the only thing that stages it — so a literal in each would be three
+// answers to one question, and a rename reaching only some of them would silently restore the
+// contamination the exclusion exists to prevent.
+const OBSERVATION_LEDGER_PATH = 'docs/observations.md'
+
+// `git status --porcelain` prints `XY PATH`, so the path starts at the fourth character.
+const STATUS_PATH_INDEX = 3
+
+function status_path(line: string): string {
+	return line.slice(STATUS_PATH_INDEX).trim()
+}
+
+function is_ledger_line(line: string): boolean {
+	return status_path(line) === OBSERVATION_LEDGER_PATH
+}
+
+// **The one place that answers "does this working tree hold a pending observation append?"**
+// `observations-flush.ts`'s `has_ledger_change` and `pnpm josh followup`'s pre-flush short-circuit
+// both ask it (joshuafolkken/kit#1810), so a literal in each would be the clone the header above
+// warns against. A blank porcelain line carries no ledger path, so `is_ledger_line` answers false for
+// it and no filtering is needed.
+function has_pending_append(status_output: string): boolean {
+	return status_output.split('\n').some((line) => is_ledger_line(line))
+}
+
+const observation_ledger = {
+	has_pending_append,
+	is_ledger_line,
+	status_path,
+}
+
+export { OBSERVATION_LEDGER_PATH, observation_ledger }

package/scripts/observations/observations-flush-cli.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { observation_ledger_home } from './observation-ledger-home'
+import { observations_flush } from './observations-flush'
+
+const FAILURE_EXIT_CODE = 1
+
+function message_of(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+// **From a lane, the flush acts on the primary checkout** (joshuafolkken/kit#2419). That is where the
+// ledger lives (`observation-ledger-home.ts`), and a lane's own checkout is never the one a flush may
+// switch — so the process moves there first, and every refusal after it is about that checkout, which
+// the prefix names so a "run `pnpm josh ms` first" is read as advice for the primary checkout.
+function enter_ledger_home(): string {
+	if (!observation_ledger_home.is_lane()) return ''
+
+	const root = observation_ledger_home.ledger_root()
+
+	process.chdir(root)
+
+	return `The observation ledger lives in the primary checkout, so this flush acts on ${root}: `
+}
+
+// The refusals are the command's whole safety story, so they are printed as the message rather than
+// as a stack: "this checkout is on a feature branch" and "the tree holds somebody else's work" are
+// both things the person fixes in one step, and a trace hides the sentence that says which.
+async function main(): Promise<void> {
+	const prefix = enter_ledger_home()
+
+	try {
+		console.info(`${prefix}${await observations_flush.flush(new Date())}`)
+	} catch (error) {
+		console.error(`${prefix}${message_of(error)}`)
+		process.exit(FAILURE_EXIT_CODE)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { main }