@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/josh/josh-commands-development.ts

@@ -28,6 +28,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.lint,
+		memory_mb: core_budget.MEMORY_MB.lint,
 	},
 	'lint:related': {
 		script: 'scripts/lint/lint-related.ts',
@@ -35,6 +36,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.lint,
+		memory_mb: core_budget.MEMORY_MB.lint,
 	},
 	lines: {
 		script: 'scripts/lines/lines-command.ts',
@@ -42,6 +44,21 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: [REQUIRED_FILE_ARGUMENTS, 'developer', ['none']],
 		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+	},
+	metrics: {
+		script: 'scripts/metrics/metrics-command.ts',
+		description:
+			'Print repository-wide quality totals and durations, and fail when a total grew past the merge-base or a duration past its baseline',
+		category: 'Development',
+		reference: [
+			'[--no-startup | --totals-only | --accept --reason "<why>"]',
+			'developer',
+			['files'],
+		],
+		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		is_kit_only: true,
 	},
 	'refactor:scan': {
 		script: 'scripts/refactor/refactor-scan-cli.ts',
@@ -50,6 +67,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['', 'automation', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
 	},
 	bytes: {
 		script: 'scripts/lines/bytes-command.ts',
@@ -65,6 +83,13 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[--refresh]', 'developer', ['files']],
 	},
+	'rule:list': {
+		script: 'scripts/rules/rule-list.ts',
+		description:
+			"Print the trigger-delivered rules — each one's source, firing call and silent turn — from the guard rows",
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+	},
 	format: {
 		script: 'scripts/lint/format.ts',
 		description: 'Format code with prettier and eslint (skips a tool a basic project lacks)',
@@ -86,8 +111,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		// **No `tsx_arguments`, deliberately.** `JOSH_BATCH_GUARD` is a per-machine preference kept in
 		// `.env`, which every other command reads through `OPTIONAL_ENV_FILE_FLAGS` — but declaring any
 		// `tsx_arguments` disqualifies a command from in-process dispatch (`josh-in-process.ts`), and
-		// this one runs before every `Bash` call. That is the hot path joshuafolkken/kit#1342 took a
-		// second ~0.16 s tsx start off. The script calls `process.loadEnvFile` itself instead, which is
+		// this one runs before every `Bash` call, where a second ~0.16 s tsx start is not affordable.
+		// The script calls `process.loadEnvFile` itself instead, which is
 		// node's own `--env-file` parser with node's own precedence.
 	},
 	'pretool:guard': {
@@ -114,7 +139,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'session:lang': {
 		script: 'scripts/josh/session-language-cli.ts',
 		description:
-			'Claude Code hook: print the resolved JOSH_SESSION_LANG (defaults to ja) for the session context',
+			'Claude Code hook: print a non-default JOSH_SESSION_LANG for the session context, and the run:board reply rule while a backlogrun is live (otherwise nothing)',
 		category: 'Development',
 		reference: ['', 'automation', ['none']],
 		// **No `tsx_arguments`, deliberately**, the same as `batch:guard` above: this runs on every
@@ -128,7 +153,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['<pretool|posttool>', 'automation', ['none']],
 		// The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
-		// bundle name (joshuafolkken/kit#3184). **No `tsx_arguments`**, the same as `pretool:guard`
+		// bundle name. **No `tsx_arguments`**, the same as `pretool:guard`
 		// above: it runs before every guarded Codex call.
 	},
 	'cspell:dot': {
@@ -137,6 +162,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.spell_check,
+		memory_mb: core_budget.MEMORY_MB.spell_check,
 	},
 	behavior: {
 		script: 'scripts/behavior/behavior-cli.ts',
@@ -159,6 +185,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
 		core_weight: gate_plan.direct_unit_weight,
+		memory_mb: gate_plan.direct_unit_memory,
 	},
 	'test:related': {
 		script: 'scripts/test/test-related.ts',
@@ -166,6 +193,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
 		core_weight: gate_plan.direct_unit_weight,
+		memory_mb: gate_plan.direct_unit_memory,
 	},
 	'test:declared': {
 		script: 'scripts/test/test-declared.ts',
@@ -213,6 +241,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['[arguments...]', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.type_check,
+		memory_mb: core_budget.MEMORY_MB.type_check,
 	},
 	port: {
 		script: 'scripts/ports/port-command.ts',

package/scripts/josh/josh-commands-document.ts

@@ -1,10 +1,10 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The document-reading and -editing command registry, split out of `josh-commands-ai.ts` so that file
-// stays under its 300-code-line limit, exactly as `SPLIT_COMMANDS` was for the same reason
-// (joshuafolkken/kit#2162, joshuafolkken/kit#2218, joshuafolkken/kit#2366). It is spread into
+// stays under its 300-code-line limit, exactly as `SPLIT_COMMANDS` was for the same reason.
+// It is spread into
 // `AI_COMMANDS` so the commands stay grouped under the 'AI tools' category. `read:files` and
-// `edit:files` are the read/write halves of the round-trip fold (joshuafolkken/kit#2202 / #2366).
+// `edit:files` are the read/write halves of the round-trip fold.
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const DOCUMENT_COMMANDS: Record<string, CommandEntry> = {

package/scripts/josh/josh-commands-guard.ts

@@ -1,11 +1,11 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The `PreToolUse` guard registry, split out of `josh-commands-ai.ts` so that file stays under its
-// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason
-// (joshuafolkken/kit#2162, joshuafolkken/kit#2218, joshuafolkken/kit#2298). It is spread into
+// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason.
+// It is spread into
 // `AI_COMMANDS` so the guards stay grouped with the other AI tools.
 //
-// **None declare `tsx_arguments`, for the reason `batch:guard` declares none** (joshuafolkken/kit#1342):
+// **None declare `tsx_arguments`, for the reason `batch:guard` declares none**:
 // declaring any disqualifies a command from in-process dispatch, and these run in front of every read
 // or shell call. Each script calls `process.loadEnvFile` itself instead, through `hook-decision.ts`.
 

package/scripts/josh/josh-commands-issue.ts

@@ -1,7 +1,7 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The issue-reading and issue-citation commands, split out of `josh-commands-ai.ts` when the mandated
-// `issue:cite` section pushed that file past its 300-line ceiling (joshuafolkken/kit#2220) — the same
+// `issue:cite` section pushed that file past its 300-line ceiling — the same
 // group-per-file shape `LANE_COMMANDS` and `SPLIT_COMMANDS` already take. `COMMAND_MAP` spreads this
 // in, so nothing downstream sees where an entry lives.
 
@@ -33,8 +33,7 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'defect:rate': {
 		script: 'scripts/issue/defect-rate-cli.ts',
-		description:
-			'Print the defect rate of merged work: defects filed per behavior change completed',
+		description: 'Print the defect rate of merged work: defects filed per enhancement completed',
 		category: 'AI tools',
 		reference: ['[--days <n>]', 'automation', ['network']],
 	},
@@ -66,14 +65,21 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 	'issue:file': {
 		script: 'scripts/issue/issue-file-cli.ts',
 		description:
-			'File an Issue with every filing step: lint, Origin, WIP cap, duplicate scout, labels, then epic:bundle',
+			'File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle',
 		category: 'AI tools',
 		reference: [
-			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]',
+			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]',
 			'automation',
 			['network'],
 		],
 	},
+	'issue:release': {
+		script: 'scripts/issue/issue-release-cli.ts',
+		description:
+			"Link an Issue to the repository's open release Issue as its blocker, filing one when none is open",
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 

package/scripts/josh/josh-commands-lane.ts

@@ -1,7 +1,7 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
 // The `lane:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its line
-// limit (joshuafolkken/kit#2162). One script answers `lane:open` / `lane:close` / `lane:list` /
+// limit. One script answers `lane:open` / `lane:close` / `lane:list` /
 // `lane:prune` / `lane:output` / `lane:dispatch` / `lane:await`, told apart by the verb below;
 // `lane:launch` is the composite that opens, pops-and-installs on the first lane, and dispatches.
 const LANE_SCRIPT = 'scripts/lane/lane-cli.ts'
@@ -39,7 +39,8 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'lane:prune': {
 		...LANE_ARGUMENTS,
-		description: 'Close every lane an interruption left without its work tree',
+		description:
+			'Close every lane an interruption left without its work tree, then sweep unregistered leftovers under the lanes root',
 		category: 'AI tools',
 		reference: ['', 'automation', ['files', 'git']],
 		default_script_arguments: ['prune'],
@@ -73,12 +74,22 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
 	},
-	// The lane-limit measurement (joshuafolkken/kit#3355): `.env` is read so `lane:stats` labels the row
+	// A live run's lane limit: `.env` is read so the bare form reports the
+	// `JOSH_LANE_LIMIT` a person set there when no override stands.
+	'lane:limit': {
+		script: 'scripts/lane/lane-limit-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Change a live backlogrun’s lane limit without stopping it, or print the limit, lanes in use and free lanes',
+		category: 'AI tools',
+		reference: ['[<limit>] [--reset]', 'developer', ['files']],
+	},
+	// The lane-limit measurement: `.env` is read so `lane:stats` labels the row
 	// with the `JOSH_LANE_LIMIT` a person set there.
 	'lane:sample': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Record the machine load (load average, swap, free memory, working lanes) to the lane ledger',
+			'Record the machine load (load average, swap, free memory, working lanes) to the lane ledger — a backlogrun samples itself, this is for a reading outside one',
 		category: 'AI tools',
 		reference: ['[--every <seconds>]', 'maintainer', ['files']],
 		default_script_arguments: ['sample'],
@@ -86,7 +97,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period',
+			'Print one table row of lane throughput, gate duration and machine load over a period, and the per-stage durations of a lane under it',
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],

package/scripts/josh/josh-commands-lint.ts

@@ -1,6 +1,6 @@
 import type { CommandEntry } from './josh-command-types'
 
-// The linters for the fixed-shape artifacts a run writes by hand (joshuafolkken/kit#2123). They are
+// The linters for the fixed-shape artifacts a run writes by hand. They are
 // `AI tools` by category, like every other automation command, but live in their own file so
 // `josh-commands-ai.ts` stays under its line ceiling.
 

package/scripts/josh/josh-commands-maintenance.ts

@@ -45,9 +45,9 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		shell: [
 			'sh',
 			'-c',
-			'export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:corepack && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:scope --record',
+			'export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:corepack && pnpm josh latest:scope --record',
 		],
-		description: 'Update pnpm, dependencies, and run security audit',
+		description: 'Update dependencies, run security audit, then update pnpm',
 		category: 'Maintenance',
 		reference: ['', 'developer', ['files', 'network', 'processes']],
 		argument_targets: ['latest:corepack', 'latest:update', 'audit'],

package/scripts/josh/josh-commands-run.ts

@@ -1,9 +1,9 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
 // The run-lifecycle registry (`run:hold` through `run:step`), split out of `josh-commands-ai.ts` so
-// that file stays under its 300-code-line limit, as `BACKLOG_COMMANDS` and `LANE_COMMANDS` were
-// (joshuafolkken/kit#2992). It is spread into `AI_COMMANDS` at the place the entries used to sit, so
-// the generated catalog keeps their order.
+// that file stays under its 300-code-line limit, as `BACKLOG_COMMANDS` and `LANE_COMMANDS` are. It
+// is spread into `AI_COMMANDS` at the place the entries belong, so the generated catalog keeps their
+// order.
 
 // One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
 const RUN_HOLD_SCRIPT = 'scripts/run/hold/run-hold-cli.ts'
@@ -32,12 +32,18 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 	'run:carry': {
 		script: 'scripts/run/carry/run-carry-cli.ts',
 		// `--stopped` sends the stop confirmation, so the Telegram credentials come from `.env` as for
-		// `run:wake` below (joshuafolkken/kit#3357).
+		// `run:wake` below.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description: 'Carry one invocation’s budget across its own session cuts',
 		category: 'AI tools',
 		reference: ['<operation> [arguments...]', 'automation', ['files']],
 	},
+	'run:add': {
+		script: 'scripts/run/add/run-add-cli.ts',
+		description: 'Add issues to a live backlogrun, ahead of the queue unless --no-priority',
+		category: 'AI tools',
+		reference: ['<issue...> [--no-priority]', 'automation', ['network', 'files']],
+	},
 	'run:wake': {
 		script: 'scripts/run/wake/run-wake-cli.ts',
 		// `.env` rather than the ambient environment:
@@ -76,18 +82,26 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 			['files'],
 		],
 	},
+	'run:board': {
+		script: 'scripts/run/board/run-board-cli.ts',
+		// `--every` pushes its frame as a Telegram, so the credentials come from `.env` as for `run:carry`.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description: 'Draw a live board of the running backlogrun, redrawn every second',
+		category: 'AI tools',
+		reference: ['[--once | --chat | --every <minutes>]', 'automation', ['files', 'network']],
+	},
 	'run:prep': {
 		script: 'scripts/run/run-prep-cli.ts',
 		description: 'Bundle a run’s pre-edit reads: body, comments, state, dependency scope',
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['network']],
 	},
-	// The entry sequence a lane opened on, folded into one call (joshuafolkken/kit#2372): claim the tree,
+	// The entry sequence a lane opened on, folded into one call: claim the tree,
 	// read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
 	// `cost --cut`, `run:prep` and `run:step` were four round trips re-billing a lane's full context each.
 	'run:entry': {
 		script: 'scripts/run/entry/run-entry-cli.ts',
-		// A `busy` hold or an `over` budget sends the stop confirmation (joshuafolkken/kit#3357).
+		// A `busy` hold or an `over` budget sends the stop confirmation.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:
 			'Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step',

package/scripts/josh/josh-commands-split.ts

@@ -1,8 +1,7 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The `split:assess` command registry, split out of `josh-commands-ai.ts` so that file stays under its
-// 300-code-line limit, exactly as `LANE_COMMANDS` was for the same reason (joshuafolkken/kit#2162,
-// joshuafolkken/kit#2218). It is spread into `AI_COMMANDS` so the command stays grouped with the other
+// 300-code-line limit, exactly as `LANE_COMMANDS` was for the same reason. It is spread into `AI_COMMANDS` so the command stays grouped with the other
 // decision oracles under the 'AI tools' category.
 
 /* eslint-disable @typescript-eslint/naming-convention */

package/scripts/josh/josh-commands-versioning.ts

@@ -24,16 +24,16 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Versioning',
 		reference: ['', 'developer', ['network']],
 	},
-	// The one place that decides a version (joshuafolkken/kit#1169). A `script` entry for the same
+	// The one place that decides a version. A `script` entry for the same
 	// reason `ranges` is one: script paths resolve against the kit package root, so it keeps working
 	// from a consumer repository where the file lives under node_modules.
 	release: {
 		script: 'scripts/release/release-cli.ts',
 		description: 'Release the merges main has taken since the version last changed',
 		category: 'Versioning',
-		reference: ['[version]', 'maintainer', ['git', 'network', 'release']],
+		reference: ['[--dry-run]', 'maintainer', ['git', 'network', 'release']],
 	},
-	// The read-only half of the one above (joshuafolkken/kit#1582). `release --dry-run` cannot
+	// The read-only half of the one above. `release --dry-run` cannot
 	// answer this question: it refuses off the default branch and on a dirty tree, which is every
 	// position a run asks it from. A `script` entry for the same reason `release` is one.
 	'release:scope': {
@@ -42,8 +42,8 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Versioning',
 		reference: ['[--json]', 'automation', ['none']],
 	},
-	// Run by the release workflows, kit's and the one sync distributes, after a tag has published
-	// (joshuafolkken/kit#3007). Settings come from the environment, so the workflow decides them.
+	// Run by the release workflows, kit's and the one sync distributes, after a tag has published.
+	// Settings come from the environment, so the workflow decides them.
 	'release:github': {
 		script: 'scripts/release/github-release-cli.ts',
 		description: 'Create the GitHub Release for a published tag, with generated notes',

package/scripts/josh/josh-commands-workflow.ts

@@ -20,20 +20,17 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<message>', 'developer', ['network']],
 		default_script_arguments: ['-y', '--skip-commit', '--skip-push'],
 	},
-	// **The optional form, on both** (joshuafolkken/kit#1564). These two were the last commands
-	// passing the mandatory `--env-file=.env`, which node resolves before the script's first line: on
-	// a machine with no `.env` they died as `.env: not found` with exit code 9, even where
-	// `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` existed as real environment variables — a cloud
-	// session, and `followup` with them the merge step of every `fullrun` there. `doctor` was moved to
-	// this form for the same reason in joshuafolkken/kit#869.
+	// **The optional form, on both**. The mandatory `--env-file=.env` is resolved by node before the
+	// script's first line: on a machine with no `.env` it dies as `.env: not found` with exit code 9,
+	// even where `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` exist as real environment variables — a
+	// cloud session, and `followup` with them the merge step of every `fullrun` there.
 	//
 	// Nothing is lost by relaxing it: both scripts already load `.env` through `josh_environment_file`
 	// themselves, so the file is read either way and node's precedence — an existing environment
 	// variable wins over the file — is node's own in both spellings.
 	//
-	// **What the mandatory flag was accidentally providing was noise**, and that is replaced rather
-	// than dropped: `telegram_notify.send` now throws on missing credentials and on a failed send, so
-	// `josh notify` exits non-zero instead of warning and answering 0.
+	// **A missing credential still fails loudly**: `telegram_notify.send` throws on missing credentials
+	// and on a failed send, so `josh notify` exits non-zero instead of warning and answering 0.
 	followup: {
 		script: 'scripts/followup/git-followup-workflow.ts',
 		description: 'Follow-up git workflow',
@@ -49,11 +46,23 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/notify/telegram-test.ts',
 		description: 'Send Telegram notification',
 		category: 'Workflow',
-		reference: ['--task-type <type> --body <text>', 'automation', ['notifications']],
+		reference: [
+			'[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]',
+			'automation',
+			['notifications'],
+		],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
-	// The observation ledger's commit path for the lines no run's own commit carried
-	// (joshuafolkken/kit#1756, joshuafolkken/kit#2763): a lane's lines sit in the primary checkout, which
+	// One observation-ledger sighting: the key's count, the append and the second-sighting verdict,
+	// which a run used to type as a `cat | grep -c` and judge by hand.
+	'observation:record': {
+		script: 'scripts/observations/observation-record-cli.ts',
+		description: 'Record an observation sighting and answer whether it is now filed',
+		category: 'Workflow',
+		reference: ['<key> <depth> <where> <what> [--checkout <path>]', 'automation', ['files']],
+	},
+	// The observation ledger's commit path for the lines no run's own commit carried:
+	// a lane's lines sit in the primary checkout, which
 	// its commit cannot see, and the recurrence count the promotion rule reads is a count of main.
 	'observations:flush': {
 		script: 'scripts/observations/observations-flush-cli.ts',
@@ -61,8 +70,8 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Workflow',
 		reference: ['', 'automation', ['git', 'network']],
 	},
-	// The one write path for a `/code-review` round's findings (joshuafolkken/kit#2325), plus the
-	// `--check` gate `followup` runs before it merges (joshuafolkken/kit#2343). It appends a `- rf:`
+	// The one write path for a `/code-review` round's findings, plus the
+	// `--check` gate `followup` runs before it merges. It appends a `- rf:`
 	// line per finding — or one zero-finding line for a clean round — to the observation ledger, so
 	// `observations:flush` commits them and the recurrence count survives the run.
 	'review:record': {
@@ -70,12 +79,12 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Record a review round’s findings, or check a round was recorded',
 		category: 'Workflow',
 		reference: [
-			'--issue <N> [<category>:<severity>:<file> ...] | --check --issue <N>',
+			'--issue <N> [--comment] [<category>:<severity>:<file> ...] | --check --issue <N>',
 			'automation',
-			['files'],
+			['files', 'network'],
 		],
 	},
-	// The reader over what `review:record` wrote (joshuafolkken/kit#2325): each recurring category’s
+	// The reader over what `review:record` wrote: each recurring category’s
 	// count, and the number of zero-finding rounds that distinguishes a quiet category from an unwatched one.
 	'review:findings': {
 		script: 'scripts/review/review-findings-cli.ts',
@@ -84,7 +93,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['files']],
 	},
 	// After a behavior-change Issue merges, re-run its declared baseline and print before/after; a value
-	// that did not move appends a refuted-premise line to the observation ledger (joshuafolkken/kit#2212).
+	// that did not move appends a refuted-premise line to the observation ledger.
 	'measure:rerun': {
 		script: 'scripts/issue/measure-rerun-cli.ts',
 		description: 'Re-run a merged issue’s baseline command and print the before/after pair',
@@ -92,7 +101,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<issue-number>', 'automation', ['network', 'processes', 'files']],
 	},
 	// A script rather than an `sh -c` chain, because it has a precondition to enforce: run inside a
-	// linked work tree it would hijack the default branch from every other one (joshuafolkken/kit#1535).
+	// linked work tree it would hijack the default branch from every other one.
 	'main:sync': {
 		script: 'scripts/git/main-sync.ts',
 		description:
@@ -101,9 +110,8 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['git', 'network']],
 	},
 	// A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
-	// the caller's git configuration: the `git pull` this replaced aborted with `Need to specify how
-	// to reconcile divergent branches` on exactly the diverged branch the command exists for
-	// (joshuafolkken/kit#1659).
+	// the caller's git configuration: a bare `git pull` aborts with `Need to specify how to reconcile
+	// divergent branches` on exactly the diverged branch the command exists for.
 	'main:merge': {
 		script: 'scripts/git/main-merge.ts',
 		description: 'Merge origin default branch into the current branch',

package/scripts/josh/josh-environment-file.ts

@@ -4,7 +4,7 @@ import { ENV_FILE_NAME } from '#ports'
 //
 // **The flag form is what most commands use, and it is not free.** Declaring any `tsx_arguments`
 // disqualifies a command from in-process dispatch (`josh-in-process.ts`), which puts a second
-// ~0.16 s tsx start in front of every call — the hot path joshuafolkken/kit#1342 took it off. A
+// ~0.16 s tsx start in front of every call. A
 // command a hook fires on every `Bash` call, or one an unattended `epicrun` polls every sixty
 // seconds, cannot pay that, so it reads the file itself instead.
 //

package/scripts/josh/josh-in-process.ts

@@ -5,8 +5,8 @@ import type { CommandEntry } from './josh-command-types'
 
 // `pnpm josh <script command>` started tsx twice — once for this dispatcher, once for the script it
 // spawned. Measured on 2026-09-04, the second start was about 0.16 s of the 0.55 s a
-// `pnpm josh format:edited` took, and the edit/Bash hook pays it 60–90 times in a single run
-// (joshuafolkken/kit#1342). The script is ordinary TypeScript and a TypeScript loader is already
+// `pnpm josh format:edited` took, and the edit/Bash hook pays it 60–90 times in a single run.
+// The script is ordinary TypeScript and a TypeScript loader is already
 // installed by the time this file runs, so the dispatcher evaluates the script itself instead.
 const TYPESCRIPT_EXTENSION = '.ts'
 const JAVASCRIPT_EXTENSION = '.js'
@@ -21,7 +21,7 @@ function is_typescript_dispatcher(dispatcher_url: string): boolean {
 }
 
 // A command marked `is_bundled` is pre-built to `dist/commands/<script basename>.js` by
-// `scripts/build/build-commands.ts` (joshuafolkken/kit#3328). The path is derived here, in a module
+// `scripts/build/build-commands.ts`. The path is derived here, in a module
 // the dispatcher bundle already carries, so the build and the dispatcher cannot name two locations.
 function bundled_script_path(package_directory: string, script: string): string {
 	const name = `${path.basename(script, TYPESCRIPT_EXTENSION)}${JAVASCRIPT_EXTENSION}`

package/scripts/josh/josh-logic.ts

@@ -59,7 +59,7 @@ function resolve_tsx_executable(): string {
 
 // Locating the CLI entry through tsx's own manifest never consults pnpm's generated shim, which
 // hardcodes a store path a later bump prunes. The resolution itself is `resolve_package_bin` —
-// shared with the format hook's eslint route rather than written twice (joshuafolkken/kit#1259).
+// shared with the format hook's eslint route rather than written twice.
 function resolve_tsx_cli_entry(): string | undefined {
 	for (const base_directory of [PACKAGE_DIR, process.cwd()]) {
 		const cli_entry = resolve_package_bin(base_directory, TSX_PACKAGE, TSX_BIN)
@@ -157,7 +157,7 @@ function format_help(is_all = false, is_consumer = false): string {
 }
 
 // Every name a user could type — the canonical commands and their aliases — ranked by edit distance
-// so `josh gat` points at `gate` (joshuafolkken/kit#1928).
+// so `josh gat` points at `gate`.
 function all_command_names(): Array<string> {
 	return [...Object.keys(COMMAND_MAP), ...Object.keys(ALIASES)]
 }
@@ -219,7 +219,7 @@ function spawn_script_entry(
 
 // Only the in-process branch is genuinely asynchronous; the spawning one answers the moment the
 // child exits. Both are reported as a promise so every caller has one shape to handle, and
-// `josh.ts` awaits it either way (joshuafolkken/kit#1342).
+// `josh.ts` awaits it either way.
 async function run_script_entry(
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
@@ -242,8 +242,7 @@ function github_prerequisite_exit(resolved: string, is_consumer: boolean): numbe
 }
 
 // The exit a command answers with before it runs, or `undefined` to go ahead: a consumer is refused a
-// kit-only command with guidance, and a composite command rejects extra arguments
-// (joshuafolkken/kit#1988).
+// kit-only command with guidance, and a composite command rejects extra arguments.
 function pre_dispatch_exit(
 	resolved: string,
 	entry: CommandEntry,
@@ -279,25 +278,26 @@ async function run_entry(
 	return await run_script_entry(entry, subcommand_arguments)
 }
 
-function command_weight(entry: CommandEntry): number | undefined {
-	return typeof entry.core_weight === 'function' ? entry.core_weight() : entry.core_weight
+function declared(value: number | (() => number) | undefined): number | undefined {
+	return typeof value === 'function' ? value() : value
 }
 
-// **Every command passes through here, so this is where a declared weight is reserved**
-// (joshuafolkken/kit#3345). A heavy command run directly, outside `josh gate`, used to start its tools
+// **Every command passes through here, so this is where a declared weight is reserved**.
+// A heavy command run directly, outside `josh gate`, used to start its tools
 // without claiming a place. A command under a parent that already holds its cores claims nothing:
 // `core_budget.with_command_reservation` reads the mark that parent set.
 async function dispatch_entry(
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
 ): Promise<number> {
-	const weight = command_weight(entry)
+	const weight = declared(entry.core_weight)
 
 	if (weight === undefined) return await run_entry(entry, subcommand_arguments)
 
 	return await core_budget.with_command_reservation(
 		weight,
 		async () => await run_entry(entry, subcommand_arguments),
+		{ memory_mb: declared(entry.memory_mb) },
 	)
 }
 

package/scripts/josh/josh-run.ts

@@ -1,6 +1,6 @@
 import { execa } from 'execa'
 
-// One captured `pnpm josh` subprocess (joshuafolkken/kit#2162). A composite command that collapses a
+// One captured `pnpm josh` subprocess. A composite command that collapses a
 // sequence of `pnpm josh` calls into one — `run:merge`, `backlog:offer`, `lane:launch` — reads each
 // step's output back rather than inheriting it, so the step's own report logic is reused rather than
 // cloned and only the composite's own token reaches the caller's stdout. This is that read, single-
@@ -11,11 +11,11 @@ import { execa } from 'execa'
 // a person sees it, so a composite streams it through; `run:merge` keeps it piped, because it composes
 // its own report from the captured values instead.
 //
-// **Forwarded stderr is captured as well** (joshuafolkken/kit#2462): a composite that writes a report
+// **Forwarded stderr is captured as well**: a composite that writes a report
 // of its own — `run:tail` — puts a failed step's reason in that report, where a detached run's log
 // otherwise showed only pnpm's `ELIFECYCLE` line.
 //
-// **`timeout_ms` bounds a read made from inside a loop** (joshuafolkken/kit#2503): the step is killed and
+// **`timeout_ms` bounds a read made from inside a loop**: the step is killed and
 // its exit reads as a failure, so a hung network call ends a pass instead of the loop around it.
 
 const PNPM = 'pnpm'