@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/fresh-machine/fresh-machine-run.ts

@@ -0,0 +1,215 @@
+import {
+	appendFileSync,
+	chmodSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { execa, type Options } from 'execa'
+import { z } from 'zod'
+import { fresh_machine_docker, type ContainerRun } from './fresh-machine-docker'
+import { fresh_machine_image } from './fresh-machine-image'
+import { fresh_machine_log } from './fresh-machine-log'
+import { fresh_machine_script } from './fresh-machine-script'
+import type { Scenario } from './fresh-machine-spec'
+
+// The I/O of `josh fresh:run`: build the machine, stage what the container may read, run the
+// scenario, and put every line of all three into one log.
+
+const DOCKER = 'docker'
+const PNPM = 'pnpm'
+const FAILURE_EXIT_CODE = 1
+const STAGE_PREFIX = 'josh-fresh-machine-'
+// The container's user is not the host's, so what it reads has to be readable by anyone — whatever
+// the host's umask gave the seed files and the tarball `pnpm pack` wrote.
+const SHARED_DIRECTORY_MODE = 0o755
+const SHARED_FILE_MODE = 0o644
+const TARBALL_EXTENSION = '.tgz'
+const MANIFEST_SCHEMA = z.object({ name: z.string() })
+
+interface RunRequest {
+	scenario: Scenario
+	run_name: string
+	log_path: string
+	package_version: string | undefined
+	// Variable name → value, each passed into the container by name and replaced in every line.
+	secrets: Readonly<Record<string, string>>
+	is_rebuild: boolean
+}
+
+interface Stage {
+	root: string
+	seed_directory: string
+	pack_directory: string
+}
+
+type Write = (line: string) => void
+
+function logger(request: RunRequest): Write {
+	const secrets = Object.values(request.secrets)
+
+	return function write(line: string): void {
+		const safe = fresh_machine_log.redact(line, secrets)
+
+		console.info(safe)
+		appendFileSync(request.log_path, `${safe}\n`)
+	}
+}
+
+// One host command, its output streamed line by line into the log. A command that could not start
+// (no docker on the machine) has no exit code, and its reason is the only line there is to log.
+async function stream(
+	file: string,
+	arguments_: Array<string>,
+	options: Options,
+	write: Write,
+): Promise<number> {
+	const subprocess = execa(file, arguments_, { ...options, all: true, reject: false })
+	const lines = subprocess.iterable({ from: 'all' })
+
+	for await (const line of lines) write(String(line))
+
+	const result = await subprocess
+
+	if (result.exitCode === undefined) write(result.shortMessage ?? `${file} did not start`)
+
+	return result.exitCode ?? FAILURE_EXIT_CODE
+}
+
+function staged_directory(root: string, name: string): string {
+	const directory = path.join(root, name)
+
+	mkdirSync(directory)
+
+	return directory
+}
+
+function stage(scenario: Scenario): Stage {
+	const root = mkdtempSync(path.join(os.tmpdir(), STAGE_PREFIX))
+	const seed_directory = staged_directory(root, 'seed')
+
+	for (const [file, content] of Object.entries(scenario.files)) {
+		const target = path.join(seed_directory, file)
+
+		mkdirSync(path.dirname(target), { recursive: true })
+		writeFileSync(target, content)
+	}
+
+	return { root, seed_directory, pack_directory: staged_directory(root, 'pack') }
+}
+
+// Run once everything is staged, so the tarball is covered as well as the seed. The root itself stays
+// as private as `mkdtemp` made it: a bind mount never enters a source through its parent, and on a
+// shared host an open root would let every other user read the tarball for the length of the run.
+function share(root: string): void {
+	const entries = readdirSync(root, { withFileTypes: true, recursive: true })
+
+	for (const entry of entries) {
+		const mode = entry.isDirectory() ? SHARED_DIRECTORY_MODE : SHARED_FILE_MODE
+
+		chmodSync(path.join(entry.parentPath, entry.name), mode)
+	}
+}
+
+// `pnpm pack` runs the checkout's own `prepack`, so the tarball holds what a release of this tree
+// would.
+async function pack(pack_directory: string, write: Write): Promise<string> {
+	const pack_arguments = ['pack', '--pack-destination', pack_directory]
+
+	write(`$ ${PNPM} ${pack_arguments.join(' ')}`)
+	await stream(PNPM, pack_arguments, { cwd: PROJECT_ROOT }, write)
+
+	const tarball = readdirSync(pack_directory).find((file) => file.endsWith(TARBALL_EXTENSION))
+
+	if (tarball === undefined) throw new Error('pnpm pack produced no tarball')
+
+	return tarball
+}
+
+function package_name(): string {
+	const manifest = readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8')
+
+	return MANIFEST_SCHEMA.parse(JSON.parse(manifest)).name
+}
+
+// The published version is always written out in the log and the install command, so a run can be
+// repeated against the same release; without `--package-version` it is the registry's latest.
+async function published_version(requested: string | undefined): Promise<string> {
+	if (requested !== undefined) return requested
+
+	const { stdout } = await execa(PNPM, ['view', package_name(), 'version'], { cwd: PROJECT_ROOT })
+
+	return stdout.trim()
+}
+
+async function container_run(
+	request: RunRequest,
+	staged: Stage,
+	write: Write,
+): Promise<ContainerRun> {
+	const { scenario } = request
+	const is_tarball = scenario.package_source === 'tarball'
+
+	return {
+		image: fresh_machine_image.tag(scenario.requires_github),
+		run_name: request.run_name,
+		script: fresh_machine_script.build(scenario),
+		seed_directory: staged.seed_directory,
+		pack_directory: staged.pack_directory,
+		tarball: is_tarball ? await pack(staged.pack_directory, write) : undefined,
+		package_version: is_tarball ? undefined : await published_version(request.package_version),
+		secret_names: Object.keys(request.secrets),
+	}
+}
+
+async function build_image(request: RunRequest, write: Write): Promise<number> {
+	const { scenario } = request
+	const image = fresh_machine_image.tag(scenario.requires_github)
+	const build_arguments = fresh_machine_docker.build_arguments(image, request.is_rebuild)
+	const input = fresh_machine_image.dockerfile(scenario.requires_github)
+
+	write(`$ ${DOCKER} ${build_arguments.join(' ')}`)
+
+	return await stream(DOCKER, build_arguments, { input }, write)
+}
+
+async function run_container(request: RunRequest, staged: Stage, write: Write): Promise<number> {
+	const container = await container_run(request, staged, write)
+
+	share(staged.root)
+	write(`$ ${DOCKER} run ${container.image} — ${request.run_name}`)
+	write(`# package: ${container.tarball ?? container.package_version ?? ''}`)
+
+	return await stream(
+		DOCKER,
+		fresh_machine_docker.run_arguments(container),
+		{ env: request.secrets },
+		write,
+	)
+}
+
+async function run(request: RunRequest): Promise<number> {
+	const write = logger(request)
+	const build_code = await build_image(request, write)
+
+	if (build_code !== 0) return build_code
+
+	const staged = stage(request.scenario)
+
+	try {
+		return await run_container(request, staged, write)
+	} finally {
+		rmSync(staged.root, { recursive: true, force: true })
+	}
+}
+
+const fresh_machine_run = { run }
+
+export { fresh_machine_run }
+export type { RunRequest }

package/scripts/fresh-machine/fresh-machine-script.ts

@@ -0,0 +1,45 @@
+import type { Scenario } from './fresh-machine-spec'
+
+// The script one container runs. Every command is printed before it runs and its exit status after,
+// so the log reads as a terminal session; the first failing command ends the run, and the probes
+// that follow a clean run are recorded whatever they exit with.
+
+const SEED_MOUNT = '/seed'
+const PACK_MOUNT = '/pack'
+const COPY_SEED = `cp -R ${SEED_MOUNT}/. .`
+const PROBES_HEADING = '# probes — recorded, never failing the run'
+const ESCAPED_QUOTE = String.raw`'\''`
+const PREAMBLE = [
+	String.raw`step() { printf '\n$ %s\n' "$1"; eval "$1"; local code=$?; printf '[exit %s]\n' "$code"; return "$code"; }`,
+	'mkdir -p "$HOME/$RUN_NAME" && cd "$HOME/$RUN_NAME" || exit 1',
+]
+
+function quote(command: string): string {
+	const escaped = command.split("'").join(ESCAPED_QUOTE)
+
+	return `'${escaped}'`
+}
+
+function required(command: string): string {
+	return `step ${quote(command)} || exit $?`
+}
+
+function probe_lines(probes: ReadonlyArray<string>): Array<string> {
+	if (probes.length === 0) return []
+
+	return [
+		String.raw`printf '\n%s\n' ${quote(PROBES_HEADING)}`,
+		...probes.map((probe) => `step ${quote(probe)}`),
+	]
+}
+
+function build(scenario: Scenario): string {
+	const seed = Object.keys(scenario.files).length > 0 ? [COPY_SEED] : []
+	const commands = [...seed, ...scenario.commands].map((command) => required(command))
+
+	return [...PREAMBLE, ...commands, ...probe_lines(scenario.probes), 'exit 0', ''].join('\n')
+}
+
+const fresh_machine_script = { build, SEED_MOUNT, PACK_MOUNT }
+
+export { fresh_machine_script }

package/scripts/fresh-machine/fresh-machine-spec.ts

@@ -0,0 +1,57 @@
+import path from 'node:path'
+import { z } from 'zod'
+
+// A scenario is everything one `josh fresh:run` needs to know: the files that are in the project
+// before anything is installed, the commands a person would type, and the probes recorded after
+// them. kit's own six patterns and a consumer toolkit's spec file are the same shape, so the machine
+// and the log are shared and nothing about them is kit's alone (joshuafolkken/kit#3714).
+//
+// Inside the container a command reads `$RUN_NAME` (the numbered project and repository name),
+// `$PACKAGE_TARBALL` (the packed checkout, for `package_source: tarball`) and `$PACKAGE_VERSION`
+// (the published version, for `package_source: published`).
+
+function is_project_relative(file: string): boolean {
+	const normalized = path.posix.normalize(file)
+
+	return !path.posix.isAbsolute(normalized) && !normalized.startsWith('..')
+}
+
+const COMMAND_SCHEMA = z.string().min(1)
+const SCENARIO_SCHEMA = z.strictObject({
+	name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/u),
+	// A GitHub scenario runs on the image that also has git and gh, and receives the host's token.
+	requires_github: z.boolean().default(false),
+	// A Claude Code scenario receives the host's long-lived token as `CLAUDE_CODE_OAUTH_TOKEN`.
+	requires_claude: z.boolean().default(false),
+	package_source: z.enum(['tarball', 'published']).default('tarball'),
+	files: z.record(z.string().refine(is_project_relative), z.string()).default({}),
+	// A failing command ends the run; a failing probe is only recorded.
+	commands: z.array(COMMAND_SCHEMA).min(1),
+	probes: z.array(COMMAND_SCHEMA).default([]),
+})
+
+type Scenario = z.infer<typeof SCENARIO_SCHEMA>
+type ScenarioInput = z.input<typeof SCENARIO_SCHEMA>
+
+function define(input: ScenarioInput): Scenario {
+	return SCENARIO_SCHEMA.parse(input)
+}
+
+function problems(error: z.ZodError): string {
+	return error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')
+}
+
+// A spec file is written by hand in another repository, so a mistake is reported as the fields that
+// are wrong rather than as a stack trace.
+function parse(json: string): Scenario {
+	const result = SCENARIO_SCHEMA.safeParse(JSON.parse(json))
+
+	if (!result.success) throw new Error(`Invalid scenario spec — ${problems(result.error)}`)
+
+	return result.data
+}
+
+const fresh_machine_spec = { define, parse }
+
+export { fresh_machine_spec }
+export type { Scenario, ScenarioInput }

package/scripts/fresh-machine/specs/kit-test-backlogrun-python.json

@@ -0,0 +1,34 @@
+{
+	"name": "kit-test-backlogrun-python",
+	"requires_github": true,
+	"package_source": "tarball",
+	"requires_claude": true,
+	"files": {
+		"pyproject.toml": "[project]\nname = \"greeting\"\nversion = \"0.1.0\"\nrequires-python = \">=3.9\"\n",
+		"main.py": "def main() -> None:\n    print(\"Hello\")\n\n\nif __name__ == \"__main__\":\n    main()\n"
+	},
+	"commands": [
+		"gh auth setup-git",
+		"git config --global user.name kit-test && git config --global user.email kit-test@example.com",
+		"printf '{ \"private\": true }\\n' > package.json",
+		"cp \"$PACKAGE_TARBALL\" . && pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver \"./$(basename \"$PACKAGE_TARBALL\")\"",
+		"pnpm exec josh start --yes --github",
+		"pnpm josh profile | grep -x 'profile: basic (package.json josh.profile)'",
+		"grep -q '\"workflow\": \"github\"' package.json && test -f .claude/settings.json",
+		"curl -fsSL https://claude.ai/install.sh | bash && export PATH=\"$HOME/.local/bin:$PATH\" && claude --version",
+		"gh issue create --title 'Print a greeting with a name in main.py' --body 'Make main.py print \"Hello, Josh\" instead of \"Hello\".' --label auto-ok --label run:lane",
+		"timeout 60 pnpm josh backlogrun > \"$HOME/backlogrun.out\" 2>&1; cat \"$HOME/backlogrun.out\"; grep -q '^backlogrun: started' \"$HOME/backlogrun.out\"",
+		"pnpm josh run:event --from 0 | grep 'starting session'",
+		"for i in $(seq 1 90); do pnpm josh run:event --from 0 | grep -q 'dispatching' && break; sleep 10; done; pnpm josh run:event --from 0 | grep 'dispatching'",
+		"for i in $(seq 1 120); do test \"$(gh pr list --state all --json number --jq length)\" -gt 0 && break; sleep 10; done; pnpm josh run:board --chat",
+		"pnpm josh backlogrun --stop"
+	],
+	"probes": [
+		"tail -n 40 \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\" | cut -c1-400",
+		"grep -c 'requires approval' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
+		"grep -c 'run:carry --begin' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
+		"tail -n 40 /tmp/josh-lane-dispatch-*.log | cut -c1-400",
+		"cat /tmp/josh-lane-dispatch-*.log | grep -c 'requires approval'",
+		"gh pr list --state all"
+	]
+}

package/scripts/fresh-machine/specs/kit-test-backlogrun.json

@@ -0,0 +1,31 @@
+{
+	"name": "kit-test-backlogrun",
+	"requires_github": true,
+	"package_source": "tarball",
+	"requires_claude": true,
+	"files": {
+		"index.html": "<!doctype html><html><body><h1>Hello</h1></body></html>\n"
+	},
+	"commands": [
+		"gh auth setup-git",
+		"git config --global user.name kit-test && git config --global user.email kit-test@example.com",
+		"printf '{ \"private\": true }\\n' > package.json",
+		"cp \"$PACKAGE_TARBALL\" . && pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver \"./$(basename \"$PACKAGE_TARBALL\")\"",
+		"pnpm exec josh start --yes --github",
+		"gh label list --limit 100 --json name --jq '.[].name' > \"$HOME/labels.txt\"; grep -xE 'auto-ok|needs-decision|needs-human-review|already-done|review-round2-skipped|bug' \"$HOME/labels.txt\"; test \"$(grep -cxE 'auto-ok|needs-decision|needs-human-review|already-done|review-round2-skipped|bug' \"$HOME/labels.txt\")\" -eq 6",
+		"curl -fsSL https://claude.ai/install.sh | bash && export PATH=\"$HOME/.local/bin:$PATH\" && claude --version",
+		"gh issue create --title 'Add a heading to index.html' --body 'Add an h2 under the h1.' --label auto-ok --label run:lane",
+		"timeout 60 pnpm josh backlogrun > \"$HOME/backlogrun.out\" 2>&1; cat \"$HOME/backlogrun.out\"; grep -q '^backlogrun: started' \"$HOME/backlogrun.out\"",
+		"pnpm josh run:event --from 0 | grep 'starting session'",
+		"for i in $(seq 1 90); do pnpm josh run:event --from 0 | grep -q 'dispatching' && break; sleep 10; done; pnpm josh run:event --from 0 | grep 'dispatching'",
+		"for i in $(seq 1 120); do test \"$(gh pr list --state all --json number --jq length)\" -gt 0 && break; sleep 10; done; pnpm josh run:board --chat",
+		"pnpm josh backlogrun --stop"
+	],
+	"probes": [
+		"tail -n 40 \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\" | cut -c1-400",
+		"grep -c 'requires approval' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
+		"tail -n 40 /tmp/josh-lane-dispatch-*.log | cut -c1-400",
+		"cat /tmp/josh-lane-dispatch-*.log | grep -c 'requires approval'",
+		"gh pr list --state all"
+	]
+}

package/scripts/gate/gate-report.ts

@@ -2,6 +2,7 @@ import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { josh_verdict } from '#scripts/josh/josh-verdict'
 import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
 import { status_icons } from '#scripts/lib/status-icons'
+import { NOT_USED_MARKER, NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
 import { test_unit_guard } from '#scripts/test/test-unit-guard'
 import { gate_log } from './gate-log'
 import { gate_plan } from './gate-plan'
@@ -11,7 +12,7 @@ import { gate_plan } from './gate-plan'
 // about what is printed changes in the move: the four blocks, the log notice and the verdict come out
 // exactly as before, with one addition — the per-failure action lines below.
 
-const { FAIL_ICON, PASS_ICON } = status_icons
+const { FAIL_ICON, PASS_ICON, WARN_ICON } = status_icons
 
 interface GateStep {
 	label: string
@@ -76,16 +77,56 @@ function has_warnings(result: GateStepResult): boolean {
 // other line still withholds.
 const SAFE_CHAIN_BANNER = 'safe-chain is not available'
 
+function checker_lines(result: GateStepResult): ReadonlyArray<string> {
+	return result.output.split('\n').filter((line) => !line.includes(SAFE_CHAIN_BANNER))
+}
+
 function has_checker_warning(result: GateStepResult): boolean {
 	if (!gate_plan.WARNING_CHECKER_LABELS.includes(result.label)) return false
 
-	return result.output
-		.split('\n')
-		.some(
-			(line) =>
-				!line.includes(SAFE_CHAIN_BANNER) &&
-				WARNING_MARKERS.some((marker) => line.includes(marker)),
-		)
+	return checker_lines(result).some((line) =>
+		WARNING_MARKERS.some((marker) => line.includes(marker)),
+	)
+}
+
+// The record's counterpart to `is_skip_notice`, narrower for the reason `has_checker_warning` is
+// narrower than `has_warnings`: a skip of a tool the project does not use (`NOT_USED_MARKER`) left
+// nothing unverified, so only another skip line withholds the green record.
+function is_unverified_skip(result: GateStepResult): boolean {
+	return checker_lines(result).some(
+		(line) => line.includes(test_unit_guard.SKIP_MARKER) && !line.includes(NOT_USED_MARKER),
+	)
+}
+
+// **A check the verdict counts as skipped said nothing but that it checked nothing.** `is_skip_notice`
+// asks whether a check carries a skip notice, which is the right question for printing its body; it is
+// the wrong one for a count, twice over. A check can skip half of
+// itself — a `basic` project's `lint` runs Prettier and skips eslint — and calling it skipped would
+// have the verdict say nothing ran on a gate that checked the formatting. And a check can run with
+// nothing of the project's to look at — `exports` in a consumer, `behavior` with no transcript — which
+// is no skip, and still left an empty `basic` project reading `2 ran`. A line that is neither notice is
+// something a tool printed, so the check ran. A tool that ran clean and silent beside a skipped one is
+// given a line of its own by the check (`project_checks.ran_notice`), so the reading holds for it too.
+//
+// **pnpm's script header is not something the check printed.** Every check is spawned as
+// `pnpm josh <target>`, and where the project declares a `josh` script — `josh init` writes one — pnpm
+// opens the captured output with `$ josh <target>`. Counted as a line, it made every spawned check one
+// that ran, and `not verified` unreachable in the very project it was written for.
+const IDLE_MARKERS: ReadonlyArray<string> = [test_unit_guard.SKIP_MARKER, NOTHING_TO_CHECK_MARKER]
+const PNPM_SCRIPT_HEADER = '$ '
+
+function is_idle_line(line: string): boolean {
+	return IDLE_MARKERS.some((marker) => line.includes(marker))
+}
+
+function is_tool_line(line: string): boolean {
+	return line.trim() !== '' && !line.startsWith(PNPM_SCRIPT_HEADER)
+}
+
+function is_idle(result: GateStepResult): boolean {
+	const lines = checker_lines(result).filter((line) => is_tool_line(line))
+
+	return lines.length > 0 && lines.every((line) => is_idle_line(line))
 }
 
 function should_print_body(result: GateStepResult, is_verbose: boolean): boolean {
@@ -144,10 +185,7 @@ function format_failure_actions(failed: ReadonlyArray<GateStepResult>): string {
 
 // **A check that started past the core budget is said in the summary, not only in the log**.
 // The wait cap admits a check that waited two minutes whatever the budget says,
-// so a gate that ran over-subscribed would otherwise look exactly like one that fitted. The icon is
-// local rather than in `status-icons.ts` because nothing reads this line back.
-const WARN_ICON = '⚠'
-
+// so a gate that ran over-subscribed would otherwise look exactly like one that fitted.
 function format_budget_notes(results: ReadonlyArray<GateStepResult>): string {
 	const lines = results.flatMap((result) =>
 		result.budget_note === undefined
@@ -158,6 +196,24 @@ function format_budget_notes(results: ReadonlyArray<GateStepResult>): string {
 	return lines.length === 0 ? '' : `${lines.join('\n')}\n`
 }
 
+// **The verdict counts what ran apart from what was skipped, and a gate that ran nothing does not say
+// `passed`.** It printed the planned number of checks whatever happened to them, so a `basic` project
+// whose every check skipped read `passed (6 checks)` — the same last line as a gate that ran them all,
+// and the skip this module keeps visible in the bodies was invisible in the one line a `tail` keeps.
+//
+// **A gate with no skip keeps the line it always printed.** A check with nothing to check is counted
+// apart only beside a skip: `exports` says so in every consumer, and counting it alone would reword the
+// verdict of every gate that skipped nothing.
+function format_green_verdict(results: ReadonlyArray<GateStepResult>, total: string): string {
+	const has_skip = results.some((result) => is_skip_notice(result))
+	const skipped = has_skip ? results.filter((result) => is_idle(result)).length : 0
+	const ran = results.length - skipped
+
+	if (ran === 0) return josh_verdict.format_gate_unverified(skipped, total)
+
+	return josh_verdict.format_gate_passed({ ran, skipped }, total)
+}
+
 // The total is wall-clock for the whole command, not the sum of the four — they run concurrently,
 // so a sum would report about three times what the caller waited.
 //
@@ -172,7 +228,7 @@ function print_gate_summary(
 	const total = format_seconds(report.elapsed_ms)
 	const verdict =
 		failed.length === 0
-			? josh_verdict.format_gate_passed(report.step_count, total)
+			? format_green_verdict(results, total)
 			: josh_verdict.format_gate_failed(failed.map((result) => result.label).join(', '), total)
 	const notes = format_budget_notes(results)
 
@@ -185,7 +241,6 @@ interface GateReport {
 	is_verbose: boolean
 	log_path: string | undefined
 	elapsed_ms: number
-	step_count: string
 }
 
 // Everything a finished run says, in the order a reader meets it: the four blocks, then the log the
@@ -213,7 +268,7 @@ const gate_report = {
 	format_failure_actions,
 	has_checker_warning,
 	is_gate_step_failed,
-	is_skip_notice,
+	is_unverified_skip,
 	report_gate_steps,
 }
 

package/scripts/gate/project-checks.ts

@@ -5,7 +5,7 @@ import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { project_profile } from '#scripts/init/project-profile'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { json_value } from '#scripts/lib/json-value'
-import { SKIP_MARKER } from '#scripts/test/skip-marker'
+import { NOT_USED_MARKER, SKIP_MARKER } from '#scripts/test/skip-marker'
 import { z } from 'zod'
 
 const PACKAGE_JSON = 'package.json'
@@ -126,8 +126,17 @@ function missing_tool_reason(
 	return `${package_name} is not installed`
 }
 
+// Every skip reason here names a tool the project does not use — undeclared, or with no files or no
+// configuration to read — so the notice says so (`NOT_USED_MARKER`).
 function skip_notice(check: string, reason: string): string {
-	return `josh ${check}: ${reason} ${SKIP_MARKER} ${check}.`
+	return `josh ${check}: ${reason} ${SKIP_MARKER} ${check}, ${NOT_USED_MARKER}.`
+}
+
+// **A tool that ran clean beside a skipped one says that it ran.** A clean eslint prints nothing, so a
+// `lint` whose Prettier was skipped read as nothing but a skip notice — the same output as a `lint`
+// that ran neither — and the gate's verdict counted a check that linted the whole tree as skipped.
+function ran_notice(check: string): string {
+	return `josh ${check}: ran and reported no problems.`
 }
 
 // Shared by `josh check` and the gate's type-check step, so neither reaches `tsc` on a basic
@@ -173,6 +182,8 @@ const project_checks = {
 	is_kit_repository,
 	prettier_skip_reason,
 	project_root,
+	ran_notice,
+	read_manifest,
 	skip_notice,
 	type_check_skip_reason,
 }

package/scripts/gate/scoped-green.ts

@@ -64,7 +64,8 @@ interface ScopedSources {
 }
 
 // **`test:related` is required only where it can ever answer**. In a project
-// whose unit guard skips — vitest absent, or a basic project with no test file — `test:related` runs
+// whose unit guard skips — vitest absent with no project test script to run in its place, or a basic
+// project with no test file — `test:related` runs
 // nothing and so writes no record, and requiring one refused the gate forever with no way through.
 // The guard's own decision is asked rather than re-derived, so the writer and this reader agree; a
 // project with a unit suite still needs the record, and a run that executed nothing still writes none.

package/scripts/gate/verification-gate.ts

@@ -63,7 +63,9 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 // passed *without running* — `test-unit-guard` exits 0 with a notice when vitest is absent or the
 // project has no tests — must not become "the unit tests all passed": the gate keeps that skip
 // visible on the console, and a record erasing it would have the brief tell a review agent not to
-// re-run tests that never ran. A step that passed **with a checker's warnings** is withheld for the
+// re-run tests that never ran. A skip of a tool the project does not use (`NOT_USED_MARKER` — eslint
+// with no ESLint configuration) is not one: nothing went unverified, so it withholds nothing
+// (`gate_report.is_unverified_skip`). A step that passed **with a checker's warnings** is withheld for the
 // same reason one place further on: since the record is reused instead of the checks being re-run, a
 // warning printed once would never be printed again on that tree, and hiding an eslint or
 // svelte-check finding is the same failure as hiding a skip. It is `has_checker_warning`, not
@@ -80,7 +82,7 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 // The destination is a parameter so a test can exercise the record without overwriting the one a
 // real run may be relying on — `josh gate` and `josh review:brief` share one path by design.
 function has_nothing_to_say(result: GateStepResult): boolean {
-	return !gate_report.is_skip_notice(result) && !gate_report.has_checker_warning(result)
+	return !gate_report.is_unverified_skip(result) && !gate_report.has_checker_warning(result)
 }
 
 async function record_green_gate(
@@ -362,7 +364,6 @@ async function settle_gate(
 		is_verbose: options.is_verbose ?? false,
 		log_path: options.log_path,
 		elapsed_ms,
-		step_count: String(plan.checks.length),
 	})
 	const is_passed = failed_labels.length === 0
 

package/scripts/gh/gh-author-association.ts

@@ -0,0 +1,14 @@
+// Whose words kit acts on: the `author_association` REST reports with an issue or a comment, and the
+// ones that can write to the repository. On a public repository anyone can file an issue or comment,
+// so a body kit runs (`josh measure:rerun`) or copies into the ledger (`review:record`) is taken only
+// from an author with write access — and an unknown author is not a trusted one.
+const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
+const TRUSTED_LIST = [...TRUSTED_ASSOCIATIONS].join(' / ')
+
+function is_trusted(association: string | null | undefined): boolean {
+	return typeof association === 'string' && TRUSTED_ASSOCIATIONS.has(association)
+}
+
+const gh_author_association = { TRUSTED_LIST, is_trusted }
+
+export { gh_author_association }