@joshuafolkken/kit 1.872.0

package/scripts/rules/test-declared-commit.ts

@@ -0,0 +1,51 @@
+import { test_declared_changed } from '#scripts/test/test-declared-changed'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { run_tail } from './run-tail'
+
+// The trigger and the delivered text behind the `test-declared` row of `delivered-rules.ts`
+// (joshuafolkken/kit#2118). It lives beside `run-tail.ts` and the other per-rule modules rather than
+// inline in the enumeration, so the enumeration stays a list of rows.
+//
+// **A commit whose code change carries no test, refused at the commit stage `run-tail` already
+// matches.** `CLAUDE.md` mandated a test for ALL code changes in three places and refused it in none;
+// the input is mechanical — the changed paths, the test-file spelling, the exempt-path enumeration —
+// so it is a delivered rule rather than resident prose.
+//
+// **No new delivery path.** The command half is `run_tail.is_push_step_call`, reused verbatim, and the
+// only thing added is the world-read: the working-tree verdict `pnpm josh test:declared` prints. Like
+// `pre-gate-cut`, the command test comes first and the git read second, so an ordinary `Bash` call
+// pays nothing and only a `pnpm josh git -y` spawns `git status`.
+//
+// **Once per run, because the exemption is a person's judgement a synchronous guard cannot read.** The
+// non-executable-config and cosmetic-asset arms of `CLAUDE.md`'s "Non-runtime updates" exception stay
+// `required` by the classifier, and a person declares them in the Step 0 work summary — which no label
+// or transcript tail records. So a row that fired every time would wedge exactly that declared-exempt
+// commit; refusing once and passing the reissue is the same safe direction `issue-comments` takes, and
+// a compliant reissue that adds a test flips the verdict to `satisfied` and stops matching anyway.
+function is_untested_commit(call: GuardedCall): boolean {
+	if (!run_tail.is_push_step_call(call)) return false
+
+	return test_declared_changed.current_verdict() === 'required'
+}
+
+const REASON =
+	'⛔ test declared: this commits a runtime code change with no test beside it — `pnpm josh ' +
+	'test:declared` reads the working tree as `required` (a changed file that is neither a test — ' +
+	'`*.test.ts` / `*.e2e.ts` — nor a mechanically-exempt non-runtime path). `CLAUDE.md` → Code ' +
+	'Change Rules requires a test for ALL code changes: a bug fix gets a regression test, a refactor ' +
+	'gets tests pinning behavior first, logic gets a unit test, an observable UI/timing change gets an ' +
+	'E2E. Add the declared test and reissue this commit. **If the change genuinely touches no ' +
+	'executable runtime path** it is the pre-approved non-runtime exception — declare it in your Step ' +
+	'0 work summary with the reason it is exempt (non-executable config, a cosmetic asset swap) and ' +
+	'reissue; the exception is a presentation, not a stop. Run `pnpm josh test:declared` to see the ' +
+	'files it names. The procedure is `prompts/collaboration-workflow/rule-delivery.md` → ' +
+	'"配送されている規則". This fires once per run, so reissuing will not repeat on the call in hand.'
+
+// The enumeration row itself, so `delivered-rules.ts` spreads one entry rather than restating the
+// trigger and reason it already single-sources here. Once per run (the default delivery) for the
+// reason above.
+const ROW = { id: 'test-declared', is_trigger: is_untested_commit, reason: REASON }
+
+const test_declared_commit = { REASON, ROW, is_untested_commit }
+
+export { test_declared_commit }

package/scripts/rules/third-party-write.ts

@@ -0,0 +1,90 @@
+import { repo_party } from '#scripts/discovery/repo-party'
+import { bash_triggers } from './bash-triggers'
+import { gh_api } from './gh-api'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `third-party-write` row of `delivered-rules.ts`
+// (joshuafolkken/kit#2122). A `gh api` write to a repository whose owner is not this session's — a
+// tracker we do not own — is Tier C: `CLAUDE.md` → "Third-party repositories are Tier C" and
+// `upstream-interrupt.md` forbid it without explicit current-turn user instruction, and a correct
+// diagnosis is not that instruction.
+//
+// **What the deny list could not express.** A glob keys on a literal, and "the owner in this path is
+// not the session's owner" is not one — it is a comparison against the session's own remote. Reading
+// the command's `repos/<owner>/<repo>` path and computing the party is what makes the judgement
+// independent of the spelling, the same move `git-force.ts` makes for a force push.
+//
+// **It fires on every occurrence, not once per run.** Publishing to another owner's tracker is
+// irreversible every time, so refused-once-and-free-after would put the second write back on the
+// run's self-restraint — the disposition `git-force.ts` and `file-body.ts` take for the same reason.
+//
+// **A read passes untouched; only a write is refused.** `gh api …/repos/other/repo/issues/5` with no
+// field flag is a `GET`, which reads someone else's tracker without changing it — no rule of ours
+// forbids that. The trigger asks `gh_api.is_write`, so it is silent on every read.
+
+// A third-party write means all three: a `gh api` call, a write, and a repository target whose owner
+// the classification calls third-party. `unknown` (an unreadable session remote, an unparseable path)
+// is not third-party — the rule stays silent rather than refusing a write it cannot prove is external.
+function is_third_party_write_segment(segment: string, session_owner: string | undefined): boolean {
+	if (!gh_api.is_gh_api(segment) || !gh_api.is_write(segment)) return false
+
+	const target = gh_api.repo_target(segment)
+
+	if (target === undefined) return false
+
+	return repo_party.classify(session_owner, target.owner) === repo_party.THIRD_PARTY
+}
+
+// The session owner is read only when a segment is actually a `gh api` write to a repository — so an
+// ordinary shell line, and every read, pays nothing for the local config read. `resolve_owner` is
+// injected so the suite fixes the owner without touching the real remote, the way `file-body.ts`
+// injects `has_file`. Each segment is judged on its own, so a `gh api` write quoted inside another
+// command's argument is read as the write it is not, exactly as every other trigger here reads its own.
+function writes_third_party(
+	command: string,
+	resolve_owner: () => string | undefined = repo_party.current_owner,
+): boolean {
+	const targets = shell_segments
+		.segments_of(command)
+		.filter((segment) => gh_api.is_gh_api(segment) && gh_api.is_write(segment))
+
+	if (targets.length === 0) return false
+
+	const session_owner = resolve_owner()
+
+	return targets.some((segment) => is_third_party_write_segment(segment, session_owner))
+}
+
+// The instruction in the shape a refusal can carry: what the command does, why it is Tier C, and what
+// to do instead. The command that computes the party is handed over, because the whole point of this
+// Issue is that the test is computed rather than judged.
+const THIRD_PARTY_WRITE_REASON =
+	'⛔ third-party write: this `gh api` call writes to a repository whose owner is not this session — ' +
+	'a tracker we do not own is Tier C, and every write there (Issue, comment, PR, Discussion, review) ' +
+	'needs explicit current-turn user instruction; typing the target, or holding a correct diagnosis, ' +
+	'is not that instruction (`CLAUDE.md` → "Third-party repositories are Tier C", ' +
+	'`prompts/collaboration-workflow/upstream-interrupt.md`). Confirm the party with ' +
+	'`pnpm josh repo:party <owner/repo>` — owner equality, computed not judged. A read (`-X GET`, or no ' +
+	'field flag) passes untouched; only a write (`-f`/`-F`/`--field`/`--raw-field`/`--input`, or ' +
+	'`-X POST|PATCH|PUT|DELETE`) is refused. Record the finding on our own Issue and draft the artifact ' +
+	'for a person to post — do not publish it yourself. **This rule fires on every occurrence, not once ' +
+	'per run.**'
+
+// `decide` returns true so it refuses every occurrence; it declares no `keeps` — not writing to
+// another owner's tracker is the absence of a call, not a call, so the row is reported unmeasured
+// rather than scored on an act that does not exist (`git-force.ts`).
+const ROW = {
+	id: 'third-party-write',
+	is_trigger: bash_triggers.on_bash_command((command: string) => writes_third_party(command)),
+	reason: THIRD_PARTY_WRITE_REASON,
+	decide: (): boolean => true,
+}
+
+const third_party_write = {
+	ROW,
+	THIRD_PARTY_WRITE_REASON,
+	is_third_party_write_segment,
+	writes_third_party,
+}
+
+export { third_party_write }

package/scripts/rules/top-level-scripts-guard.ts

@@ -0,0 +1,47 @@
+import { readdirSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// `scripts/` is grouped into domain subdirectories (joshuafolkken/kit#2013). A file placed directly
+// under `scripts/` is what this guard forbids: flat files are hard to find, coarsen the changed-file
+// scope, and inflate an agent's investigation reads. The scripts root is one level above this rule's
+// own directory.
+const SCRIPTS_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+// The extensions a top-level file would carry — every executable script is one of these. A stray
+// `.md` or `.json` at the root is not what the layout is about, so it is not guarded.
+const GUARDED_EXTENSIONS: ReadonlyArray<string> = ['.ts', '.sh']
+
+// Files permitted directly under `scripts/`. Empty today — every script lives in a domain
+// subdirectory — so a new top-level file is a mistake until someone adds it here with a reason.
+const TOP_LEVEL_ALLOWLIST: ReadonlySet<string> = new Set<string>()
+
+function is_guarded_file(name: string): boolean {
+	return GUARDED_EXTENSIONS.some((extension) => name.endsWith(extension))
+}
+
+// The guarded top-level names that are not allowlisted. Kept pure over a plain listing so its own
+// unit test can exercise it without touching the filesystem.
+function top_level_offenders(
+	entries: ReadonlyArray<string>,
+	allowlist: ReadonlySet<string> = TOP_LEVEL_ALLOWLIST,
+): Array<string> {
+	return entries.filter((name) => is_guarded_file(name) && !allowlist.has(name))
+}
+
+// The real names sitting directly under `scripts/`, files only — subdirectories are the whole point
+// of the layout, so they are never offenders.
+function read_top_level_entries(): Array<string> {
+	return readdirSync(SCRIPTS_ROOT, { withFileTypes: true })
+		.filter((entry) => entry.isFile())
+		.map((entry) => entry.name)
+}
+
+const top_level_scripts_guard = {
+	SCRIPTS_ROOT,
+	TOP_LEVEL_ALLOWLIST,
+	top_level_offenders,
+	read_top_level_entries,
+}
+
+export { top_level_scripts_guard }

package/scripts/rules/worktree-guard.ts

@@ -0,0 +1,130 @@
+import { bash_triggers } from './bash-triggers'
+import { git_argv } from './git-argv'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `worktree-mutation` row of `delivered-rules.ts`
+// (joshuafolkken/kit#2120). Group 2 of the three Bash-string gaps: a working-tree change made outside
+// the authorized routes.
+//
+// **The deny list does not cover these at all.** `git checkout -- <path>` and `git restore <path>`
+// discard uncommitted work, and `git stash` mutates a stack every work tree of the repository shares —
+// none of the three is a deny entry, so the prohibition lived only in prose (`operating-rules.md`).
+//
+// **Authorized stash calls are told apart by the message, not by the launcher.** The Issue's premise —
+// that every authorized caller is node-routed and so invisible here — does not hold: at least eight
+// distributed flows (`fullrun`, `halfrun`, `backlogrun`, `upstream-interrupt`, `latest-gate`,
+// `plan-comment`, …) push with a **raw** `git stash push -u -m "<message>"`. The message is what makes
+// that stash findable and poppable by `pnpm josh stash:pop`, which is the whole of `operating-rules.md`'s
+// safety argument; the forms it warns against are the *positional/bare* ones. So `git stash push -m`
+// (with or without `-u`) and the read-only `git stash list` / `show` pass, and everything else — bare
+// `git stash`, a message-less push, `pop` / `apply` / `drop` / `save` / `clear` — is refused.
+//
+// **It fires on every occurrence**, for the reason `git-force.ts` does: discarding the working tree is
+// destructive each time it is issued.
+
+const CHECKOUT_SUBCOMMAND = 'checkout'
+const RESTORE_SUBCOMMAND = 'restore'
+const STASH_SUBCOMMAND = 'stash'
+
+// `git checkout -- <path>` discards the working-tree copy of a path. The `--` separator is what marks
+// the pathspec form; `git checkout <branch>` and `git checkout -b <name>` carry no `--` and are left
+// alone.
+const PATHSPEC_SEPARATOR = '--'
+
+function is_worktree_checkout(args: ReadonlyArray<string>): boolean {
+	return args.includes(PATHSPEC_SEPARATOR)
+}
+
+// `git restore <path>` discards working-tree changes. `--staged` / `-S` alone is an index restore —
+// that is the deny list's territory (`git restore --staged*` / `-S*`), so a pure index restore is not
+// refused twice. Anything touching the worktree (the default, or an explicit `--worktree` / `-W`) is.
+const STAGED_LONG = '--staged'
+const STAGED_LETTER = 'S'
+const WORKTREE_LONG = '--worktree'
+const WORKTREE_LETTER = 'W'
+
+function touches_worktree(args: ReadonlyArray<string>): boolean {
+	const is_staged = args.some(
+		(argument) => argument === STAGED_LONG || git_argv.short_cluster_has(argument, STAGED_LETTER),
+	)
+	const is_worktree = args.some(
+		(argument) =>
+			argument === WORKTREE_LONG || git_argv.short_cluster_has(argument, WORKTREE_LETTER),
+	)
+
+	return !is_staged || is_worktree
+}
+
+// A stash `push` carrying a message is the authorized form. `-m` / `--message` / `--message=…`, or a
+// short cluster carrying `m`, all count.
+const PUSH_STASH = 'push'
+const MESSAGE_LONG = '--message'
+const MESSAGE_SHORT_LETTER = 'm'
+const READ_ONLY_STASH: ReadonlySet<string> = new Set(['list', 'show'])
+
+function has_message(args: ReadonlyArray<string>): boolean {
+	return args.some(
+		(argument) =>
+			argument === MESSAGE_LONG ||
+			argument.startsWith(`${MESSAGE_LONG}=`) ||
+			git_argv.short_cluster_has(argument, MESSAGE_SHORT_LETTER),
+	)
+}
+
+// `args[0]` is the stash subcommand — `push`, `pop`, `list`, … — or `undefined` for a bare `git stash`,
+// which is a message-less push and therefore unauthorized.
+function is_unauthorized_stash(args: ReadonlyArray<string>): boolean {
+	const [stash_subcommand, ...rest] = args
+
+	if (stash_subcommand === undefined) return true
+	if (READ_ONLY_STASH.has(stash_subcommand)) return false
+	if (stash_subcommand === PUSH_STASH) return !has_message(rest)
+
+	return true
+}
+
+function is_unauthorized_segment(segment: string): boolean {
+	const call = git_argv.parse(segment)
+
+	if (call === undefined) return false
+	if (call.subcommand === CHECKOUT_SUBCOMMAND) return is_worktree_checkout(call.args)
+	if (call.subcommand === RESTORE_SUBCOMMAND) return touches_worktree(call.args)
+
+	return call.subcommand === STASH_SUBCOMMAND && is_unauthorized_stash(call.args)
+}
+
+function is_unauthorized_worktree_change(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => is_unauthorized_segment(segment))
+}
+
+// The instruction in the shape a refusal can carry: what the command touches, the authorized route,
+// and — for a stash — the message form that is allowed. `pnpm josh git` and `pnpm josh stash:pop` are
+// invisible to this trigger, so a run that uses them is never refused.
+const WORKTREE_MUTATION_REASON =
+	'⛔ unauthorized working-tree change: `git checkout -- <path>`, `git restore <path>` and an ' +
+	'unauthorized `git stash` mutate the working tree or the repository-wide stash every work tree ' +
+	'shares, and none is on the `.claude/settings.json` deny list (`operating-rules.md`). Do not run ' +
+	'them on your own judgement. A commit goes through `pnpm josh git`; a stash pop goes through `pnpm ' +
+	'josh stash:pop "<message>"`, never a positional `git stash pop` a shared stack lets another lane ' +
+	'divert. A stash push is authorized only inside a documented flow and only with a findable message ' +
+	'— `git stash push -u -m "<message>"` — which this row allows; a bare `git stash`, a message-less ' +
+	'push, or `pop` / `apply` / `drop` is refused. **This rule fires on every occurrence, not once per ' +
+	'run.**'
+
+const ROW = {
+	id: 'worktree-mutation',
+	is_trigger: bash_triggers.on_bash_command(is_unauthorized_worktree_change),
+	reason: WORKTREE_MUTATION_REASON,
+	decide: (): boolean => true,
+}
+
+const worktree_guard = {
+	ROW,
+	WORKTREE_MUTATION_REASON,
+	is_unauthorized_stash,
+	is_unauthorized_worktree_change,
+	is_worktree_checkout,
+	touches_worktree,
+}
+
+export { worktree_guard }