From 90808a15f3aa9806b712e00c6b4cac508d6141e3 Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Mon, 9 Nov 2026 07:28:40 +0530 Subject: [PATCH 1/4] feat(kin): APPR-11 memory-repo rulesets mode KIN_REPOS gives each Kin repo a kind. A memory repo gets one kin-main ruleset (no bypass, memory-check required, zero approvals with code-owner review, squash only) and a CODEOWNERS check that accepts the template's owner-less Kin paths while still requiring * @owner and codeowners/errors. Refs #12 Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/github/KinRulesets.ts | 167 ++++++++++++------ .../src/kin/github/rulesetsSetup.test.ts | 118 +++++++++++-- apps/server/src/kin/github/rulesetsSetup.ts | 60 ++++--- apps/server/src/kin/memory/lint.ts | 3 +- docs/kin/specs/approvals.md | 2 + docs/kin/specs/triggers.md | 2 +- ops/kin/memory-repo/README.md | 2 +- 7 files changed, 260 insertions(+), 94 deletions(-) diff --git a/apps/server/src/kin/github/KinRulesets.ts b/apps/server/src/kin/github/KinRulesets.ts index c11c0e439a4a..6df3812c9626 100644 --- a/apps/server/src/kin/github/KinRulesets.ts +++ b/apps/server/src/kin/github/KinRulesets.ts @@ -1,13 +1,26 @@ // Pure: the approvals spec section 10 rulesets and CODEOWNERS rule. Apply, `--check` and the // tests all read `kinRulesets`, so there is one definition of what GitHub should hold. +import { kinOnlyPaths } from "../memory/lint.ts"; /** - * Required status check contexts per Kin repository; other repos pass `--status-check`. Its keys - * count as Kin repositories even when `KIN_GITHUB_REPOS` leaves them out. + * `code` repos hold Kin's source; a `memory` repo is the deny-by-default memory repo (triggers + * spec, memory repo guard rails), where PRs touching only Kin's own paths merge without review. */ -export const KIN_REPO_REQUIRED_CHECKS: Readonly>> = { +export type KinRepoKind = "code" | "memory"; + +export interface KinRepo { + readonly kind: KinRepoKind; + readonly requiredChecks: ReadonlyArray; +} + +/** + * Kin repositories with their kind and required status check contexts; other repos pass + * `--status-check` and are `code`. Its keys count as Kin repositories even when + * `KIN_GITHUB_REPOS` leaves them out. + */ +export const KIN_REPOS: Readonly> = { // ci.yml's `Check` job fails unless every other CI job passed or was skipped as not needed. - "GLDRoger/t3code": ["Check"], + "GLDRoger/t3code": { kind: "code", requiredChecks: ["Check"] }, }; /** @@ -35,58 +48,94 @@ export interface KinRuleset { readonly rules: ReadonlyArray; } -/** @public The rulesets for one repository, given its required status check contexts. */ -export const kinRulesets = (requiredChecks: ReadonlyArray): ReadonlyArray => [ - { - name: "kin-main", - target: "branch", - enforcement: "active", - bypass_actors: [], - conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } }, - rules: [ - { type: "deletion" }, - { type: "non_fast_forward" }, - { - type: "pull_request", - parameters: { - required_approving_review_count: 1, - require_code_owner_review: true, - dismiss_stale_reviews_on_push: true, - // Stale dismissal ignores diff-neutral pushes, so a bot commit added then reverted would - // keep the owner's approval. Upstream syncs end with a bot push for this (spec section 10). - require_last_push_approval: true, - required_review_thread_resolution: true, - // `merge` is for the owner's upstream syncs; the executor squashes bot PRs. - allowed_merge_methods: ["squash", "merge"], +const requiredStatusChecks = (requiredChecks: ReadonlyArray): KinRulesetRule => ({ + type: "required_status_checks", + parameters: { + strict_required_status_checks_policy: true, + do_not_enforce_on_create: false, + required_status_checks: requiredChecks.map((context) => ({ + context, + integration_id: GITHUB_ACTIONS_INTEGRATION_ID, + })), + }, +}); + +const defaultBranch = { + name: "kin-main", + target: "branch", + enforcement: "active", + bypass_actors: [], + conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } }, +} as const; + +/** @public The rulesets for one repository, given its kind and required status check contexts. */ +export const kinRulesets = ( + requiredChecks: ReadonlyArray, + kind: KinRepoKind = "code", +): ReadonlyArray => + kind === "memory" + ? [ + { + ...defaultBranch, + rules: [ + { type: "deletion" }, + { type: "non_fast_forward" }, + { + type: "pull_request", + parameters: { + // Zero, so a PR touching only CODEOWNERS' owner-less Kin paths merges on + // `memory-check` alone; code-owner review still gates every other path. + required_approving_review_count: 0, + require_code_owner_review: true, + dismiss_stale_reviews_on_push: true, + // Squash only, so an unreviewed commit can't land in history behind an approval + // that a diff-neutral push kept, which is what last-push approval guards against. + require_last_push_approval: false, + required_review_thread_resolution: true, + allowed_merge_methods: ["squash"], + }, + }, + requiredStatusChecks(requiredChecks), + ], }, - }, - { - type: "required_status_checks", - parameters: { - strict_required_status_checks_policy: true, - do_not_enforce_on_create: false, - required_status_checks: requiredChecks.map((context) => ({ - context, - integration_id: GITHUB_ACTIONS_INTEGRATION_ID, - })), + ] + : [ + { + ...defaultBranch, + rules: [ + { type: "deletion" }, + { type: "non_fast_forward" }, + { + type: "pull_request", + parameters: { + required_approving_review_count: 1, + require_code_owner_review: true, + dismiss_stale_reviews_on_push: true, + // Stale dismissal ignores diff-neutral pushes, so a bot commit added then reverted would + // keep the owner's approval. Upstream syncs end with a bot push for this (spec section 10). + require_last_push_approval: true, + required_review_thread_resolution: true, + // `merge` is for the owner's upstream syncs; the executor squashes bot PRs. + allowed_merge_methods: ["squash", "merge"], + }, + }, + requiredStatusChecks(requiredChecks), + ], }, - }, - ], - }, - { - name: "kin-release", - target: "tag", - enforcement: "active", - bypass_actors: [], - // `*` stops at `/`, so `v*/**` covers tags like `v1/rc`. - conditions: { ref_name: { include: ["refs/tags/v*", "refs/tags/v*/**"], exclude: [] } }, - rules: [ - { type: "creation" }, - { type: "update", parameters: { update_allows_fetch_and_merge: false } }, - { type: "deletion" }, - ], - }, -]; + { + name: "kin-release", + target: "tag", + enforcement: "active", + bypass_actors: [], + // `*` stops at `/`, so `v*/**` covers tags like `v1/rc`. + conditions: { ref_name: { include: ["refs/tags/v*", "refs/tags/v*/**"], exclude: [] } }, + rules: [ + { type: "creation" }, + { type: "update", parameters: { update_allows_fetch_and_merge: false } }, + { type: "deletion" }, + ], + }, + ]; /** The fields of a GitHub ruleset that `diffRuleset` reads. */ export interface LiveRuleset { @@ -191,9 +240,14 @@ export function diffRuleset( /** * Why `content` (the default branch's `.github/CODEOWNERS`) fails to make `owner` the sole code * owner of every path; empty when it passes. A `*` rule must exist, and every rule must name - * exactly the owner, so no later rule can hand a path to someone else or to no one. + * exactly the owner, so no later rule can hand a path to someone else or to no one. In a `memory` + * repo, Kin's own paths (`kinOnlyPaths`) may name no one instead, as the template does. */ -export function codeownersProblems(content: string, owner: string): ReadonlyArray { +export function codeownersProblems( + content: string, + owner: string, + kind: KinRepoKind = "code", +): ReadonlyArray { const problems: Array = []; const expected = `@${owner}`.toLowerCase(); let coversAll = false; @@ -209,6 +263,7 @@ export function codeownersProblems(content: string, owner: string): ReadonlyArra const [pattern, ...owners] = commentAt === -1 ? tokens : tokens.slice(0, commentAt); if (pattern === undefined) return; if (pattern === "*") coversAll = true; + if (kind === "memory" && owners.length === 0 && kinOnlyPaths.includes(pattern)) return; if (owners.length !== 1 || owners[0]!.toLowerCase() !== expected) { problems.push( `line ${index + 1}: "${pattern}" is owned by ${owners.length === 0 ? "no one" : owners.join(" ")}, not only @${owner}`, diff --git a/apps/server/src/kin/github/rulesetsSetup.test.ts b/apps/server/src/kin/github/rulesetsSetup.test.ts index 7d8426c62d3e..2f0b48430f55 100644 --- a/apps/server/src/kin/github/rulesetsSetup.test.ts +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -1,3 +1,4 @@ +import * as NodeFS from "node:fs"; import { RepoSlug } from "@t3tools/contracts"; import { assert, it } from "@effect/vitest"; import * as Effect from "effect/Effect"; @@ -5,7 +6,7 @@ import * as Redacted from "effect/Redacted"; import * as Schema from "effect/Schema"; import { describe } from "vite-plus/test"; -import { codeownersProblems, kinRulesets } from "./KinRulesets.ts"; +import { codeownersProblems, kinRulesets, type KinRepoKind } from "./KinRulesets.ts"; import * as Rulesets from "./rulesetsSetup.ts"; import { isKinBlock, type KinBlock } from "./rulesetsTest23.ts"; import { fakeGitHub, type FakeAnswer, type RecordedRequest } from "./testFakes.ts"; @@ -211,8 +212,19 @@ const writes = (requests: ReadonlyArray) => requests.filter((request) => request.method !== "GET"); const checks = ["Check"]; -const apply = (t = target()) => Rulesets.applyRepo(t, { requiredChecks: checks }); -const check = (t = target()) => Rulesets.checkRepo(t, { requiredChecks: checks, rulesets: true }); +const memoryChecks = ["memory-check"]; +const memoryCodeowners = NodeFS.readFileSync( + new URL("../../../../../ops/kin/memory-repo/CODEOWNERS.template", import.meta.url), + "utf8", +).replace("* @OWNER", "* @GLDRoger"); +const apply = (t = target(), kind: KinRepoKind = "code") => + Rulesets.applyRepo(t, { requiredChecks: kind === "memory" ? memoryChecks : checks, kind }); +const check = (t = target(), kind: KinRepoKind = "code") => + Rulesets.checkRepo(t, { + requiredChecks: kind === "memory" ? memoryChecks : checks, + kind, + rulesets: true, + }); describe("kin-rulesets apply", () => { it.effect("creates both rulesets, then a second apply writes nothing and --check passes", () => { @@ -237,6 +249,52 @@ describe("kin-rulesets apply", () => { }).pipe(Effect.provide(github.layer)); }); + it.effect("gives a memory repo one branch ruleset that frees Kin's paths, with no bypass", () => { + const github = githubRepo({ codeowners: memoryCodeowners }); + return Effect.gen(function* () { + const applied = yield* apply(target(), "memory"); + assert.isTrue(applied.ok, applied.lines.join("\n")); + assert.include(applied.lines, "CODEOWNERS: ok (@GLDRoger owns every path but Kin's own)"); + assert.deepStrictEqual( + github.rulesets.map(({ name, target, bypass_actors }) => ({ name, target, bypass_actors })), + [{ name: "kin-main", target: "branch", bypass_actors: [] }], + ); + assert.deepStrictEqual(ruleParameters(github.rulesets, "pull_request"), { + required_approving_review_count: 0, + require_code_owner_review: true, + dismiss_stale_reviews_on_push: true, + require_last_push_approval: false, + required_review_thread_resolution: true, + allowed_merge_methods: ["squash"], + }); + assert.deepStrictEqual( + ruleParameters(github.rulesets, "required_status_checks").required_status_checks, + [{ context: "memory-check", integration_id: 15368 }], + ); + assert.strictEqual((yield* check(target(), "memory")).lines.at(-1), "PASS: no drift."); + ruleParameters(github.rulesets, "pull_request").require_code_owner_review = false; + const drifted = yield* check(target(), "memory"); + assert.isFalse(drifted.ok); + assert.include( + drifted.lines, + " FAIL rules.pull_request.require_code_owner_review: expected true, got false", + ); + }).pipe(Effect.provide(github.layer)); + }); + + it.effect("checks a code repo's rulesets as drift on a memory repo", () => { + const github = githubRepo({ codeowners: memoryCodeowners.replace(/\n\/.*/g, "") }); + return Effect.gen(function* () { + assert.isTrue((yield* apply()).ok); + const result = yield* check(target(), "memory"); + assert.isFalse(result.ok); + assert.include( + result.lines, + " FAIL rules.pull_request.required_approving_review_count: expected 0, got 1", + ); + }).pipe(Effect.provide(github.layer)); + }); + it.effect("refuses to apply, and writes nothing, while CODEOWNERS is missing", () => { const github = githubRepo({ codeowners: null }); return Effect.gen(function* () { @@ -365,12 +423,17 @@ describe("kin-rulesets --check", () => { describe("kin-rulesets CODEOWNERS", () => { it.each([ - ["# Kin\n* @gldroger # owner\n", []], - ["*\t@GLDRoger\r\n", []], - ["", ['no "* @GLDRoger" rule, so some paths have no code owner']], - ["* @priya\n", ['line 1: "*" is owned by @priya, not only @GLDRoger']], - ["* @GLDRoger @priya\n", ['line 1: "*" is owned by @GLDRoger @priya, not only @GLDRoger']], + ["code", "# Kin\n* @gldroger # owner\n", []], + ["code", "*\t@GLDRoger\r\n", []], + ["code", "", ['no "* @GLDRoger" rule, so some paths have no code owner']], + ["code", "* @priya\n", ['line 1: "*" is owned by @priya, not only @GLDRoger']], [ + "code", + "* @GLDRoger @priya\n", + ['line 1: "*" is owned by @GLDRoger @priya, not only @GLDRoger'], + ], + [ + "code", "* @GLDRoger\n/docs/ @priya\n/apps/\n", [ 'line 2: "/docs/" is owned by @priya, not only @GLDRoger', @@ -378,6 +441,7 @@ describe("kin-rulesets CODEOWNERS", () => { ], ], [ + "code", "* @GLDRoger\n* @GLDRoger @priya\n* @GLDRoger\u000B@priya\n", [ 'no "* @GLDRoger" rule, so some paths have no code owner', @@ -386,8 +450,31 @@ describe("kin-rulesets CODEOWNERS", () => { "line 3: has a non-ASCII or control character (or a BOM)", ], ], - ] as const)("judges %j", (content, problems) => { - assert.deepStrictEqual(codeownersProblems(content, "GLDRoger"), problems); + [ + "code", + memoryCodeowners, + ["/commitments/", "/deferrals/", "/claims/", "/journal/", "/INDEX.md"].map( + (path, index) => `line ${index + 6}: "${path}" is owned by no one, not only @GLDRoger`, + ), + ], + ["memory", memoryCodeowners, []], + [ + "memory", + `${memoryCodeowners}/rules.md\n`, + ['line 11: "/rules.md" is owned by no one, not only @GLDRoger'], + ], + [ + "memory", + memoryCodeowners.replace("* @GLDRoger", "*"), + ['line 5: "*" is owned by no one, not only @GLDRoger'], + ], + [ + "memory", + memoryCodeowners.replace("/journal/", "/journal/ @priya"), + ['line 9: "/journal/" is owned by @priya, not only @GLDRoger'], + ], + ] as const)("judges %s %j", (kind, content, problems) => { + assert.deepStrictEqual(codeownersProblems(content, "GLDRoger", kind), problems); }); it.effect("fails when GitHub reports CODEOWNERS syntax errors", () => { @@ -395,6 +482,7 @@ describe("kin-rulesets CODEOWNERS", () => { return Effect.gen(function* () { const result = yield* Rulesets.checkRepo(target(), { requiredChecks: checks, + kind: "code", rulesets: false, }); assert.isFalse(result.ok); @@ -670,7 +758,10 @@ const runTest23 = (slug = scratch) => }); const test23 = () => Effect.gen(function* () { - yield* Rulesets.applyRepo(target(OWNER_TOKEN, scratch), { requiredChecks: ["ci"] }); + yield* Rulesets.applyRepo(target(OWNER_TOKEN, scratch), { + requiredChecks: ["ci"], + kind: "code", + }); return yield* runTest23(); }); @@ -820,7 +911,10 @@ describe("security test 23 (kin-rulesets --test-23)", () => { ] as const)("refuses, writing nothing, when GitHub %s", ([, fullName, reason]) => { const github = scratchRepo({ fullName }); return Effect.gen(function* () { - yield* Rulesets.applyRepo(target(OWNER_TOKEN, scratch), { requiredChecks: ["ci"] }); + yield* Rulesets.applyRepo(target(OWNER_TOKEN, scratch), { + requiredChecks: ["ci"], + kind: "code", + }); const before = github.requests.length; const error = yield* Effect.flip(runTest23()); assert.include(error.message, reason); diff --git a/apps/server/src/kin/github/rulesetsSetup.ts b/apps/server/src/kin/github/rulesetsSetup.ts index eb2d816ab23c..5a5b2976f085 100644 --- a/apps/server/src/kin/github/rulesetsSetup.ts +++ b/apps/server/src/kin/github/rulesetsSetup.ts @@ -17,10 +17,11 @@ import * as Keychain from "./Keychain.ts"; import * as KinGitHubApp from "./KinGitHubApp.ts"; import { KIN_CODEOWNERS_PATH, - KIN_REPO_REQUIRED_CHECKS, + KIN_REPOS, codeownersProblems, diffRuleset, kinRulesets, + type KinRepoKind, type KinRuleset, } from "./KinRulesets.ts"; import { KinGitHubScope } from "./KinGitHubScope.ts"; @@ -150,6 +151,7 @@ type VerifiedOwner = Effect.Success>; export const checkCodeowners = Effect.fn("kinRulesets.checkCodeowners")(function* ( target: RepoTarget, defaultBranch: string, + kind: KinRepoKind, ) { const client = yield* HttpClient.HttpClient; const ref = `ref=${encodeURIComponent(defaultBranch)}`; @@ -176,7 +178,7 @@ export const checkCodeowners = Effect.fn("kinRulesets.checkCodeowners")(function }); return [ ...syntax.body.errors.map((error) => `line ${error.line}: GitHub reports ${error.kind}`), - ...codeownersProblems(content, target.owner), + ...codeownersProblems(content, target.owner, kind), ]; }); @@ -234,27 +236,36 @@ const driftLines = (desired: ReadonlyArray, live: ReadonlyMap, owner: string) => +const codeownersLines = (problems: ReadonlyArray, owner: string, kind: KinRepoKind) => problems.length === 0 - ? [`CODEOWNERS: ok (@${owner} owns every path)`] + ? [`CODEOWNERS: ok (@${owner} owns every path${kind === "memory" ? " but Kin's own" : ""})`] : ["CODEOWNERS: FAIL", ...problems.map((problem) => ` FAIL ${problem}`)]; +interface ApplyInput { + readonly requiredChecks: ReadonlyArray; + readonly kind: KinRepoKind; +} +interface CheckInput extends ApplyInput { + readonly rulesets: boolean; +} + const checkVerified = Effect.fn("kinRulesets.checkVerified")(function* ( target: RepoTarget, { login, defaultBranch }: VerifiedOwner, - input: { readonly requiredChecks: ReadonlyArray; readonly rulesets: boolean }, + input: CheckInput, ) { - const problems = yield* checkCodeowners(target, defaultBranch); + const problems = yield* checkCodeowners(target, defaultBranch, input.kind); const lines = [ `${target.repo} (default branch ${defaultBranch}), checked as ${login}`, - ...codeownersLines(problems, target.owner), + ...codeownersLines(problems, target.owner, input.kind), ]; let ok = problems.length === 0; + const desired = kinRulesets(input.requiredChecks, input.kind); const live = input.rulesets - ? yield* readRulesets(target, kinRulesets(input.requiredChecks)) + ? yield* readRulesets(target, desired) : new Map(); if (input.rulesets) { - for (const result of driftLines(kinRulesets(input.requiredChecks), live)) { + for (const result of driftLines(desired, live)) { ok &&= result.ok; lines.push(...result.lines); } @@ -266,7 +277,7 @@ const checkVerified = Effect.fn("kinRulesets.checkVerified")(function* ( /** `--check` and `--codeowners`: nothing is written. */ export const checkRepo = Effect.fn("kinRulesets.check")(function* ( target: RepoTarget, - input: { readonly requiredChecks: ReadonlyArray; readonly rulesets: boolean }, + input: CheckInput, ) { const { ok, lines } = yield* checkVerified(target, yield* verifyOwnerCredential(target), input); return { ok, lines } satisfies RulesetsResult; @@ -275,21 +286,21 @@ export const checkRepo = Effect.fn("kinRulesets.check")(function* ( /** Apply: creates or replaces each ruleset by name, writes nothing when it already matches. */ export const applyRepo = Effect.fn("kinRulesets.apply")(function* ( target: RepoTarget, - input: { readonly requiredChecks: ReadonlyArray }, + input: ApplyInput, ) { const client = yield* HttpClient.HttpClient; const { login, defaultBranch } = yield* verifyOwnerCredential(target); - const problems = yield* checkCodeowners(target, defaultBranch); + const problems = yield* checkCodeowners(target, defaultBranch, input.kind); const lines = [ `${target.repo} (default branch ${defaultBranch}), applying as ${login}`, - ...codeownersLines(problems, target.owner), + ...codeownersLines(problems, target.owner, input.kind), ]; // Without CODEOWNERS, require_code_owner_review is met by anyone's approval. if (problems.length > 0) { lines.push("FAIL: fix CODEOWNERS on the default branch first; no ruleset was changed."); return { ok: false, lines } satisfies RulesetsResult; } - const desired = kinRulesets(input.requiredChecks); + const desired = kinRulesets(input.requiredChecks, input.kind); const before = yield* readRulesets(target, desired); for (const ruleset of desired) { const live = before.get(ruleset.name); @@ -342,10 +353,7 @@ export function scratchRepoProblem(repo: string, kinRepos: ReadonlyArray } /** The repositories test 23 must never touch: `KIN_GITHUB_REPOS` and the known Kin ones. */ -export const kinRepos = (scoped: ReadonlyArray) => [ - ...scoped, - ...Object.keys(KIN_REPO_REQUIRED_CHECKS), -]; +export const kinRepos = (scoped: ReadonlyArray) => [...scoped, ...Object.keys(KIN_REPOS)]; /** * Security test 23 on a scratch repository. The owner is checked once, and the repository GitHub @@ -378,6 +386,7 @@ export const runTest23 = Effect.fn("kinRulesets.test23Run")(function* (inp const desired = kinRulesets(input.requiredChecks); const check = yield* checkVerified(target, owner, { requiredChecks: input.requiredChecks, + kind: "code", rulesets: true, }); if (!check.ok) { @@ -422,6 +431,7 @@ export const runTest23 = Effect.fn("kinRulesets.test23Run")(function* (inp // The change probes sent the desired bodies, so drift here means something else wrote to them. const after = yield* checkVerified(target, owner, { requiredChecks: input.requiredChecks, + kind: "code", rulesets: true, }); const ok = probes.ok && after.ok; @@ -539,19 +549,23 @@ export const kinRulesetsCommand = Command.make( `--owner ${owner} differs from KIN_GITHUB_OWNER_LOGIN (${scope.ownerLogin}), which ${input.test23 ? "test 23" : repo} must use.`, ); } - const known = Object.entries(KIN_REPO_REQUIRED_CHECKS).find( + const known = Object.entries(KIN_REPOS).find( ([slug]) => slug.toLowerCase() === repo.toLowerCase(), )?.[1]; - const requiredChecks = input.statusCheck.length > 0 ? input.statusCheck : (known ?? []); + const requiredChecks = + input.statusCheck.length > 0 ? input.statusCheck : (known?.requiredChecks ?? []); + const kind = known?.kind ?? "code"; if (requiredChecks.length === 0 && !input.codeowners) { return yield* refuse( `${repo} has no default required checks; pass --status-check .`, ); } const target = { repo, owner, token: yield* ownerToken } satisfies RepoTarget; - if (input.codeowners) return yield* checkRepo(target, { requiredChecks, rulesets: false }); - if (input.check) return yield* checkRepo(target, { requiredChecks, rulesets: true }); - if (!input.test23) return yield* applyRepo(target, { requiredChecks }); + if (input.codeowners) { + return yield* checkRepo(target, { requiredChecks, kind, rulesets: false }); + } + if (input.check) return yield* checkRepo(target, { requiredChecks, kind, rulesets: true }); + if (!input.test23) return yield* applyRepo(target, { requiredChecks, kind }); const appConfig = Option.match(input.appId, { onNone: () => KinGitHubApp.KinGitHubAppConfig.layer, onSome: (appId) => Layer.succeed(KinGitHubApp.KinGitHubAppConfig, { appId }), diff --git a/apps/server/src/kin/memory/lint.ts b/apps/server/src/kin/memory/lint.ts index 599806d7af16..4166ba2b0e57 100644 --- a/apps/server/src/kin/memory/lint.ts +++ b/apps/server/src/kin/memory/lint.ts @@ -23,7 +23,8 @@ export interface MemoryTreeEntry { } const codeowners = ".github/CODEOWNERS"; -const kinOnlyPaths = ["/commitments/", "/deferrals/", "/claims/", "/journal/", "/INDEX.md"]; +/** The CODEOWNERS patterns Kin writes alone; everything else in the memory repo is the owner's. */ +export const kinOnlyPaths = ["/commitments/", "/deferrals/", "/claims/", "/journal/", "/INDEX.md"]; const kinOnlyRoots = kinOnlyPaths.map((pattern) => pattern.slice(1).replace(/\/$/, "")); const regularModes = ["100644", "100755"]; diff --git a/docs/kin/specs/approvals.md b/docs/kin/specs/approvals.md index 4090b57c024b..32922a228999 100644 --- a/docs/kin/specs/approvals.md +++ b/docs/kin/specs/approvals.md @@ -446,6 +446,8 @@ These probes assume GitHub checks a fine-grained token's permission before it lo - The required check for `GLDRoger/t3code` is `Check`, the `ci.yml` job that fails unless every other job passed or was skipped as not needed. Other repos pass `--status-check`. - The script reads `KinGitHubScope`. The owner is `KIN_GITHUB_OWNER_LOGIN`; `--owner` may name someone else only for a repository outside Kin, and is refused for `KIN_GITHUB_REPOS`, `GLDRoger/t3code` and `--test-23`. It takes the owner's own sign-in (`GH_TOKEN` or a hidden prompt) and refuses anything else before writing: an installation token (`ghs_`, refused before any request), a credential `GET /user` rejects or reports as a bot, a login other than the owner's, and a credential without admin on the repo (GitHub hides `bypass_actors` from those, so drift could go unseen). `--check` reports every drifted field, including any bypass actor, a rule someone added or removed, and changed parameters; parameters GitHub adds that the spec doesn't set are not compared. Apply creates or replaces each ruleset by name, writes nothing when it already matches, and re-reads to confirm no drift. +**Memory repo mode.** `KIN_REPOS` gives each Kin repo a `kind`; a `memory` repo (triggers spec, memory repo guard rails) gets only `kin-main`, still with no bypass actors and `memory-check` as its required check, but with `required_approving_review_count: 0` so a PR touching only CODEOWNERS' owner-less Kin paths merges on the check alone while code-owner review gates every other path, squash only, and `require_last_push_approval` off: with squash only, a diff-neutral push can't land an unreviewed commit in history, and last-push approval could block those review-free PRs. Its CODEOWNERS check still calls `codeowners/errors` and still requires `* @`, but lets the template's `kinOnlyPaths` lines (from the memory lint) name no one; any other owner-less line fails. There is no tag ruleset, and `--test-23` stays on code repos. + `kinRulesets` targets `~DEFAULT_BRANCH`. On `GLDRoger/t3code` that is `kin`, where PRs land; `main` is the upstream mirror and is held by a hand-made "main: upstream mirror" ruleset with an admin bypass that `--check` doesn't read. Bringing `main` under `kinRulesets` is open. **Upstream syncs (proposed resolution of open question 2, owner to confirm).** The bot can't carry a sync: an upstream merge changes `.github/workflows`, which its missing Workflows permission rejects, and squashing would flatten the merge so the next sync conflicts. So the owner carries it, and Kin only opens the PR: diff --git a/docs/kin/specs/triggers.md b/docs/kin/specs/triggers.md index 2d8292d3c459..1655cd23b31d 100644 --- a/docs/kin/specs/triggers.md +++ b/docs/kin/specs/triggers.md @@ -399,7 +399,7 @@ The builder takes item heads (optionally marked `misleading` by the caller), las GitHub then blocks a bad auto-merge even if Kin's classifier is wrong. -**Daytime lead writes (decided).** Because `main` requires PRs, LEAD's daytime memory writes land as PRs that Kin auto-merges once `memory-check` passes; a write touching an owner path waits for the owner's review like any other PR. APPR-8 (#44) and APPR-11 (#46) have merged; the TRIG-15 follow-up is the `MemoryWriter` PR path and running APPR-11's rulesets in a memory-repo mode, since its CODEOWNERS check expects every line to name the owner (lane A and lane C coordinate on #12). +**Daytime lead writes (decided).** Because `main` requires PRs, LEAD's daytime memory writes land as PRs that Kin auto-merges once `memory-check` passes; a write touching an owner path waits for the owner's review like any other PR. APPR-8 (#44) and APPR-11 (#46) have merged; the TRIG-15 follow-up is the `MemoryWriter` PR path and adding the memory repo to APPR-11's `KIN_REPOS` with `kind: "memory"` (approvals spec section 10, memory repo mode; lane A and lane C coordinate on #12). ### Secret scan before memory commits (gap 5) diff --git a/ops/kin/memory-repo/README.md b/ops/kin/memory-repo/README.md index 6b5f431fe23d..ff3291d40cde 100644 --- a/ops/kin/memory-repo/README.md +++ b/ops/kin/memory-repo/README.md @@ -16,7 +16,7 @@ Templates for the private memory repo (`kin-memory`). This public repo holds onl To pick up new lint or scanner rules, bump `T3CODE_REF` in a reviewed PR. The lint code and the gitleaks config always come from that commit, never from the PR's own files, which the job reads only as data. -The ruleset on `main` (PRs required, code-owner review, `memory-check` required, no bypass for Kin's bot) comes in the TRIG-15 follow-up with the `MemoryWriter` PR path. APPR-8 and APPR-11 have merged, but APPR-11's ruleset setup needs a memory-repo mode first: its CODEOWNERS check expects every line to name the owner, and this file's Kin lines name none. +The ruleset on `main` (PRs required, code-owner review, `memory-check` required, no bypass for Kin's bot) comes in the TRIG-15 follow-up with the `MemoryWriter` PR path. `scripts/kin-rulesets.ts` applies it once the memory repo is in `KIN_REPOS` with `kind: "memory"`, which accepts this file's owner-less Kin lines. ## Cost From e77452353477a18bdc7c9877cdb8b149b0c7babe Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Mon, 9 Nov 2026 07:32:26 +0530 Subject: [PATCH 2/4] test(kin): allow the sync template read in the rulesets test Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/github/rulesetsSetup.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/server/src/kin/github/rulesetsSetup.test.ts b/apps/server/src/kin/github/rulesetsSetup.test.ts index 2f0b48430f55..1aa2584ec746 100644 --- a/apps/server/src/kin/github/rulesetsSetup.test.ts +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -1,3 +1,4 @@ +// @effect-diagnostics nodeBuiltinImport:off - the CODEOWNERS table reads the real template synchronously. import * as NodeFS from "node:fs"; import { RepoSlug } from "@t3tools/contracts"; import { assert, it } from "@effect/vitest"; From 6ce739b50c5085061c99ccf433d76ea57b952824 Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Mon, 9 Nov 2026 08:17:46 +0530 Subject: [PATCH 3/4] docs(kin): document owner PRs, workflow trust and scratch checks for kin-memory The owner can't approve their own PR to an owned memory path, so section 10 and the memory-repo README now route those changes through the sync flow and say nothing automates it yet. They also note that the memory-check pin trusts every Actions workflow, and list the scratch-repo checks to run before the mode goes on. The CODEOWNERS table gains near-miss rows for each Kin-only folder. Co-Authored-By: Claude Opus 5.5 --- .../src/kin/github/rulesetsSetup.test.ts | 10 ++++++++ docs/kin/specs/approvals.md | 4 +++ ops/kin/memory-repo/README.md | 25 ++++++++++++++++++- 3 files changed, 38 insertions(+), 1 deletion(-) diff --git a/apps/server/src/kin/github/rulesetsSetup.test.ts b/apps/server/src/kin/github/rulesetsSetup.test.ts index 1aa2584ec746..1ecab446d073 100644 --- a/apps/server/src/kin/github/rulesetsSetup.test.ts +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -474,6 +474,16 @@ describe("kin-rulesets CODEOWNERS", () => { memoryCodeowners.replace("/journal/", "/journal/ @priya"), ['line 9: "/journal/" is owned by @priya, not only @GLDRoger'], ], + ...["/commitments/", "/deferrals/", "/claims/", "/journal/"].flatMap((folder, index) => + [folder.slice(0, -1), `${folder}**`].map( + (nearMiss) => + [ + "memory", + memoryCodeowners.replace(folder, nearMiss), + [`line ${index + 6}: "${nearMiss}" is owned by no one, not only @GLDRoger`], + ] as const, + ), + ), ] as const)("judges %s %j", (kind, content, problems) => { assert.deepStrictEqual(codeownersProblems(content, "GLDRoger", kind), problems); }); diff --git a/docs/kin/specs/approvals.md b/docs/kin/specs/approvals.md index 32922a228999..ece2e6ed0b3a 100644 --- a/docs/kin/specs/approvals.md +++ b/docs/kin/specs/approvals.md @@ -448,6 +448,10 @@ These probes assume GitHub checks a fine-grained token's permission before it lo **Memory repo mode.** `KIN_REPOS` gives each Kin repo a `kind`; a `memory` repo (triggers spec, memory repo guard rails) gets only `kin-main`, still with no bypass actors and `memory-check` as its required check, but with `required_approving_review_count: 0` so a PR touching only CODEOWNERS' owner-less Kin paths merges on the check alone while code-owner review gates every other path, squash only, and `require_last_push_approval` off: with squash only, a diff-neutral push can't land an unreviewed commit in history, and last-push approval could block those review-free PRs. Its CODEOWNERS check still calls `codeowners/errors` and still requires `* @`, but lets the template's `kinOnlyPaths` lines (from the memory lint) name no one; any other owner-less line fails. There is no tag ruleset, and `--test-23` stays on code repos. +The owner is the memory repo's only code owner and can't approve their own PR, so an owner change to an owned path (a `T3CODE_REF` bump, a hand edit to `rules.md`) uses the upstream sync flow below: the owner pushes a branch, the bot adds the same-tree commit and opens the PR, and the owner approves as code owner and squash-merges. Nothing implements that flow yet, for either kind of repo. When the diff touches `.github/workflows`, as every `T3CODE_REF` bump does, confirm by hand that GitHub accepts the bot's same-tree commit without the Workflows permission. With last-push approval off, the bot authoring the PR is what makes the approval count, so the bot can open it from the owner's head if that commit is refused. + +`memory-check`'s pin to app 15368 trusts every Actions workflow in the repo, not just `memory-check.yml`. Keep the memory repo's Actions workflow permissions read-only and never grant the App Workflows there. A ruleset `workflows` rule requiring `memory-check.yml` from a pinned ref is planned. The scratch-repo checks to run before switching the mode on are in `ops/kin/memory-repo/README.md`. + `kinRulesets` targets `~DEFAULT_BRANCH`. On `GLDRoger/t3code` that is `kin`, where PRs land; `main` is the upstream mirror and is held by a hand-made "main: upstream mirror" ruleset with an admin bypass that `--check` doesn't read. Bringing `main` under `kinRulesets` is open. **Upstream syncs (proposed resolution of open question 2, owner to confirm).** The bot can't carry a sync: an upstream merge changes `.github/workflows`, which its missing Workflows permission rejects, and squashing would flatten the merge so the next sync conflicts. So the owner carries it, and Kin only opens the PR: diff --git a/ops/kin/memory-repo/README.md b/ops/kin/memory-repo/README.md index ff3291d40cde..9f9f354f703a 100644 --- a/ops/kin/memory-repo/README.md +++ b/ops/kin/memory-repo/README.md @@ -18,13 +18,36 @@ To pick up new lint or scanner rules, bump `T3CODE_REF` in a reviewed PR. The li The ruleset on `main` (PRs required, code-owner review, `memory-check` required, no bypass for Kin's bot) comes in the TRIG-15 follow-up with the `MemoryWriter` PR path. `scripts/kin-rulesets.ts` applies it once the memory repo is in `KIN_REPOS` with `kind: "memory"`, which accepts this file's owner-less Kin lines. +### The owner's own changes + +The owner is the only code owner, and GitHub never lets an author approve their own PR, so a PR the owner opens on an owned path (a `T3CODE_REF` bump, a hand edit to `rules.md`) can never merge. Use the code repo's sync flow ([approvals spec, section 10](../../../docs/kin/specs/approvals.md#10-github-the-bot-app-the-owners-review-rulesets)) instead: + +1. The owner pushes a branch with the change, using their own credential, never the Kin host's. +2. The bot adds one same-tree commit on top (`POST /git/commits` with the owner's tree and commit as its only parent, then the ref update) and opens the PR, after checking that `head^` is the SHA the owner pushed and `head^{tree}` is its tree. +3. The owner approves as code owner, which counts because the bot authored the PR, and squash-merges in the GitHub UI. + +Nothing automates this yet: Kin has no code that adds the same-tree commit or opens the PR, for this repo or the code repo. When the diff touches `.github/workflows` (every `T3CODE_REF` bump does), check by hand that GitHub accepts the bot's same-tree commit, because the App has no Workflows permission. With `require_last_push_approval` off here, the bot opening the PR is what makes the approval count, so if GitHub refuses that commit, the bot can open the PR from the owner's head as it is. + +### Workflow permissions + +`memory-check` is pinned to the GitHub Actions App (15368), which trusts any Actions workflow in the repo, not just `memory-check.yml`. A workflow that anyone pushes could post a passing `memory-check` on another PR. So keep the repo's Actions workflow permissions read-only, and never grant the Kin App Workflows permission on this repo. A ruleset `workflows` rule that requires `memory-check.yml` from a pinned ref is planned to close the gap. + +### Before switching it on + +The memory mode is tested only against a fake GitHub. In memory mode on a scratch repo, check: + +- [ ] A PR that touches only `journal/` shows `mergeable_state: "clean"` once `memory-check` passes, with no review. +- [ ] A PR that touches `decisions/` shows `blocked` until the owner approves. +- [ ] After the owner approves, a bot push that changes `decisions/` dismisses the approval. +- [ ] A rename from `decisions/x.md` into `journal/` stays gated on the owner's review. + ## Cost Each run checks out `t3code` at the pinned commit without `.repos/`, installs the server's dependencies with `vp install --frozen-lockfile --ignore-scripts --filter=t3...` and runs the lint with Node. The install dominates: 881 packages, which took 19 s from an empty store on a fast connection, so budget about a minute per run on a hosted runner, plus Vite+ and Node setup. Nothing is cached between runs, so a PR can't seed a cache the check later trusts. Gitleaks is a 7 MB release binary, checked against its sha256 before it runs, and scans the tree plus the new commits in seconds. ## Things to know -- GitHub runs a PR's own copy of this workflow, so a PR could rewrite the check. The `*` line in `CODEOWNERS`, which also covers `.github/`, is what stops that: such a PR needs the owner's review. An org ruleset that requires this workflow from a pinned ref would remove the gap; consider it with the ruleset. +- GitHub runs a PR's own copy of this workflow, so a PR could rewrite the check. The `*` line in `CODEOWNERS`, which also covers `.github/`, is what stops that: such a PR needs the owner's review. A ruleset `workflows` rule that requires this workflow from a pinned ref would remove the gap; it is planned (see Workflow permissions above). - A `.gitleaksignore` anywhere in the memory repo fails the check, because gitleaks would honour it. `gitleaks:allow` comments are ignored. - A false positive the owner allowed in `kin_secret_allow` still fails gitleaks, which has no allowlist. Reword the text; whether the owner may merge past the check is settled with the ruleset. - `CODEOWNERS` denies by default, so a new root file such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.mcp.json` or `.codex/` needs the owner's review before the lead's read checkout loads it. The lint fails if the file still names `@OWNER` or frees any path beyond Kin's own. From a900ddfb565bdc52f0ca714937961843e462565f Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:24:17 +0530 Subject: [PATCH 4/4] fix(kin): wire memory-repo ruleset mode and correct its trust and purge docs Adds GLDRoger/kin-memory to KIN_REPOS as memory kind. Docs now say read-only workflow permissions don't cap a pushed workflow and the workflows rule is org-only, so Kin must verify the check's workflow and SHA before merging; the purge runs in an owner window instead of needing a bypass actor; the host README's key containment is 'every ref except main'. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/github/KinRulesets.ts | 1 + apps/server/src/kin/github/rulesetsSetup.test.ts | 1 + docs/kin/specs/approvals.md | 2 +- docs/kin/specs/triggers.md | 2 +- docs/operations/kin-memory-purge.md | 8 ++++++++ ops/kin/host/README.md | 2 +- ops/kin/memory-repo/README.md | 4 ++-- 7 files changed, 15 insertions(+), 5 deletions(-) diff --git a/apps/server/src/kin/github/KinRulesets.ts b/apps/server/src/kin/github/KinRulesets.ts index 6df3812c9626..0a8f0ae41a9c 100644 --- a/apps/server/src/kin/github/KinRulesets.ts +++ b/apps/server/src/kin/github/KinRulesets.ts @@ -21,6 +21,7 @@ export interface KinRepo { export const KIN_REPOS: Readonly> = { // ci.yml's `Check` job fails unless every other CI job passed or was skipped as not needed. "GLDRoger/t3code": { kind: "code", requiredChecks: ["Check"] }, + "GLDRoger/kin-memory": { kind: "memory", requiredChecks: ["memory-check"] }, }; /** diff --git a/apps/server/src/kin/github/rulesetsSetup.test.ts b/apps/server/src/kin/github/rulesetsSetup.test.ts index 1ecab446d073..1f1f3a6abb19 100644 --- a/apps/server/src/kin/github/rulesetsSetup.test.ts +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -905,6 +905,7 @@ describe("security test 23 (kin-rulesets --test-23)", () => { it.effect.each([ ["a Kin repository in another case", "gldroger/t3code", "is a Kin repository"], + ["the memory repository", "GLDRoger/kin-memory", "is a Kin repository"], ["a repository not named scratch", "GLDRoger/sandbox", 'has no "scratch" in its name'], ] as const)("refuses %s before any request", ([, slug, reason]) => { const github = scratchRepo(); diff --git a/docs/kin/specs/approvals.md b/docs/kin/specs/approvals.md index 470e20a30706..4fb1e5545516 100644 --- a/docs/kin/specs/approvals.md +++ b/docs/kin/specs/approvals.md @@ -451,7 +451,7 @@ These probes assume GitHub checks a fine-grained token's permission before it lo The owner is the memory repo's only code owner and can't approve their own PR, so an owner change to an owned path (a `T3CODE_REF` bump, a hand edit to `rules.md`) uses the upstream sync flow below: the owner pushes a branch, the bot adds the same-tree commit and opens the PR, and the owner approves as code owner and squash-merges. Nothing implements that flow yet, for either kind of repo. When the diff touches `.github/workflows`, as every `T3CODE_REF` bump does, confirm by hand that GitHub accepts the bot's same-tree commit without the Workflows permission. With last-push approval off, the bot authoring the PR is what makes the approval count, so the bot can open it from the owner's head if that commit is refused. -`memory-check`'s pin to app 15368 trusts every Actions workflow in the repo, not just `memory-check.yml`. Keep the memory repo's Actions workflow permissions read-only and never grant the App Workflows there. A ruleset `workflows` rule requiring `memory-check.yml` from a pinned ref is planned. The scratch-repo checks to run before switching the mode on are in `ops/kin/memory-repo/README.md`. +`memory-check`'s pin to app 15368 trusts every Actions workflow in the repo, not just `memory-check.yml`, and the read-only workflow-permissions setting is only a default that a pushed workflow can raise. A ruleset `workflows` rule exists only for organization rulesets, so it isn't available on `GLDRoger/kin-memory`. Kin therefore trusts a passing `memory-check` only after checking that the PR head is the SHA Kin pushed and that the check came from a `pull_request` run of `.github/workflows/memory-check.yml` at that SHA (TRIG-15 writer PR path). Never grant the App Workflows there. The scratch-repo checks to run before switching the mode on are in `ops/kin/memory-repo/README.md`. `kinRulesets` targets `~DEFAULT_BRANCH`. On `GLDRoger/t3code` that is `kin`, where PRs land; `main` is the upstream mirror and is held by a hand-made "main: upstream mirror" ruleset with an admin bypass that `--check` doesn't read. Bringing `main` under `kinRulesets` is open. diff --git a/docs/kin/specs/triggers.md b/docs/kin/specs/triggers.md index 78c31a98c301..08f010941132 100644 --- a/docs/kin/specs/triggers.md +++ b/docs/kin/specs/triggers.md @@ -445,7 +445,7 @@ Before anything runs, the stored plan must re-serialize to the same bytes and ma 3. For `drop_file`, checks that no reachable commit touches the paths, then commits a tombstone on the default branch for each item path present at the old head: the original `id` and the folder's kind, `title: Purged item`, `status: cancelled`, `invalid_at: now`, `source: kin-action:`, `said_by` the approving owner, body "Purged on by the owner (action )". Memory still shows that something was there. Journal and other non-item paths get no tombstone. 4. Reads every blob ever introduced at every path, merge sides included, every commit object and every tag object (tagger idents survive `--replace-message`). It fails if a redacted pattern remains, then runs `KinSecretScan` over all of it and fails closed on **any** finding: findings carry no fingerprint, so the purge can't prove one unrelated, and a copy under an older path would otherwise survive. Allowlisted fingerprints don't count. 5. Records the tombstones' blob ids in `purge-plans/.tombstones.json`, writes the durable marker `//purge-in-flight` (plan digest, action id, old head, the plan itself and the tombstone ids), and deletes the writer and read checkouts, any half-finished `memory.clone-*` and the dream scratch `/dreams/`, before the push. A push can land and still report failure (a timeout, a crash, a restart), and those checkouts hold the old history: `Memory.preserve` would push it back as a `kin/conflict/*` branch, and a dream as `dream/`. While the marker exists, `ensureCheckouts` and `recover` won't clone (until the push lands the remote still has the old history), and `preserve`, the wake-up merge, `commitWakeup`, `commitDream` and `deleteDreamBranch` refuse to push. Only the purge's own reclone clones. -6. Force-pushes the changed `refs/heads/*` and `refs/tags/*` in one atomic push, each leased at its cloned value, through `KinPurgePush`. Failures are classified from `--porcelain` output (`lease_rejected`, `remote_rejected`, `auth`, `network`, `timeout`) without the cause, so neither the URL nor helper output is logged. This needs the owner as a bypass actor on the memory repo's ruleset. Closing open dream PRs that touch the paths waits on the GitHub client. +6. Force-pushes the changed `refs/heads/*` and `refs/tags/*` in one atomic push, each leased at its cloned value, through `KinPurgePush`. Failures are classified from `--porcelain` output (`lease_rejected`, `remote_rejected`, `auth`, `network`, `timeout`) without the cause, so neither the URL nor helper output is logged. `kin-main` has no bypass actors and blocks force-pushes, so the purge runs in an owner window instead: with their own credential, on their own device (never a stored owner credential on the Kin host), the owner sets `kin-main` to `enforcement: disabled`; step 6 pushes; the owner re-applies with `scripts/kin-rulesets.ts --repo GLDRoger/kin-memory`, and `--check` must pass before the queue resumes. Closing open dream PRs that touch the paths waits on the GitHub client. 7. Re-lists and re-mirrors the remote and runs the same history check as `reconcile`; a ref created during the purge that still holds the content fails at the push stage with `queueHeld: true`. Then reclones: clones fresh, records the rewritten anchors without preserving the old ones, rebuilds the read checkout, cache and `INDEX.md`, clears the marker, and resumes the queue. A failure or interruption before step 5 resumes the queue with nothing changed; from step 5 on, any failure, defect or interruption leaves `KinPurgeFailed` with `queueHeld: true` and the queue paused. 8. Returns the `execution_finished` audit input (grant `jti`, key thumbprint, new head; APPR-10 adds the device label from the key) with the paths, old head, new head and rewritten refs; APPR-10 writes it as a `KinAuditEntry`. 9. Tells the owner what a purge can't reach: GitHub keeps `refs/pull/*` (read-only, so the clone leaves them out and `reconcile` doesn't wait on them) and cached PR diffs (removing those needs a GitHub Support request); forks, local backups (Time Machine) and the chat database keep their copies. It won't rewrite `refs/notes/*` or custom refs such as `refs/custom/*` either: their presence fails the purge in step 2 and makes `reconcile` answer `unknown`, so the owner deletes them on the remote first. A leaked credential must be rotated whatever happens. diff --git a/docs/operations/kin-memory-purge.md b/docs/operations/kin-memory-purge.md index d1f160b5ea11..e42ff8ae18d8 100644 --- a/docs/operations/kin-memory-purge.md +++ b/docs/operations/kin-memory-purge.md @@ -22,3 +22,11 @@ Delete the marker by hand only when `reconcile` keeps answering `unknown` and yo Then confirm with `git log --branches --tags -p` on a fresh clone, and `git ls-remote` for refs outside heads, tags and pulls, whether the purged content is still on the remote. If it is, run the purge again from a new owner-approved action; if it's gone, the next wake-up clones the rewritten history. Last, resume the org's queue. Until LEAD-11 builds the org pause there is no operator path to resume it: the purge can't run then either, because `KinPurgeQueue.pause` fails by default, so a stuck marker can only come from a host running LEAD-11's pause. + +## The ruleset window + +`kin-main` on the memory repo has no bypass actors and blocks force-pushes, so a purge's push needs an owner window. Do it with your own credential on your own device, never with an owner credential stored on the Kin host: + +1. Set `kin-main` to `enforcement: disabled` (repo Settings, Rules, Rulesets). +2. Let the purge push. +3. Re-apply with `node scripts/kin-rulesets.ts --repo GLDRoger/kin-memory`, then run it with `--check`. The queue resumes only once `--check` passes; a leftover `disabled` shows as drift. diff --git a/ops/kin/host/README.md b/ops/kin/host/README.md index 533bc6de14f6..db8f8b678675 100644 --- a/ops/kin/host/README.md +++ b/ops/kin/host/README.md @@ -59,7 +59,7 @@ KIN_MEMORY_SSH_COMMAND="ssh -i /home/kin/.config/kin/kin-memory-deploy-key -o Id Point `KIN_MEMORY_REPOSITORIES` at the SSH URL (`git@github.com:/.git`), make sure `~/.ssh/known_hosts` holds GitHub's host key, and restart `kin-server`. The key stays out of `~/.ssh` because the approvals credential check tries every key there against GitHub, and a deploy key's greeting names a repo instead of the bot, so the check fails with `non_bot_identity` and privileged actions stop. **The key is not contained.** Agents run as `kin` and can read the file, so a prompt-injected lead or worker can push to the memory repo directly, around Kin's memory writer and its rules (owner-only `rules.md`, server-set trust, secret scanning, L0 writes only on `kin/shadow/*`). Until Kin runs memory git as a separate OS user, contain it on GitHub: -- While every lead is at L0, protect `main` in the memory repo with a ruleset that requires a pull request and the `memory-check` workflow, with no bypass for this deploy key. The key can then only update `kin/shadow/*` and `kin/conflict/*`. +- While every lead is at L0, protect `main` in the memory repo with a ruleset that requires a pull request and the `memory-check` workflow, with no bypass for this deploy key. The key can then update every ref except `main`, so a branch it pushes is never trusted on its own (see `ops/kin/memory-repo/README.md`, Workflow permissions). - Don't raise any lead to L1 (which writes `main` directly) until memory git runs as a separate OS user whose key agents can't read. This is the same gap as the approval key (approvals spec, section 12) and has the same fix. **HTTPS.** Set `KIN_MEMORY_CREDENTIAL_HELPER` to a git credential helper's name or absolute path, with an `https://` repo URL. There is no GitHub App installation-token helper yet, so this route has nothing to point at until one is written. diff --git a/ops/kin/memory-repo/README.md b/ops/kin/memory-repo/README.md index 9f9f354f703a..97c9a37d6d49 100644 --- a/ops/kin/memory-repo/README.md +++ b/ops/kin/memory-repo/README.md @@ -30,7 +30,7 @@ Nothing automates this yet: Kin has no code that adds the same-tree commit or op ### Workflow permissions -`memory-check` is pinned to the GitHub Actions App (15368), which trusts any Actions workflow in the repo, not just `memory-check.yml`. A workflow that anyone pushes could post a passing `memory-check` on another PR. So keep the repo's Actions workflow permissions read-only, and never grant the Kin App Workflows permission on this repo. A ruleset `workflows` rule that requires `memory-check.yml` from a pinned ref is planned to close the gap. +`memory-check` is pinned to the GitHub Actions App (15368), which trusts any Actions workflow in the repo, not just `memory-check.yml`. A workflow pushed to any branch could post a passing `memory-check` on another PR. The repo's read-only workflow-permissions setting doesn't stop this: anyone with write access, which includes the memory deploy key that agents can read, can raise a workflow's own `permissions:`. A ruleset `workflows` rule would close the gap, but it exists only in organization rulesets, and `GLDRoger` is a user account. So a passing `memory-check` alone is not trusted: before merging a PR, Kin checks that it merges the SHA it pushed itself, and that the passing check came from a `pull_request` run of `.github/workflows/memory-check.yml` on that SHA (TRIG-15 writer PR path). Never grant the Kin App Workflows permission on this repo. ### Before switching it on @@ -47,7 +47,7 @@ Each run checks out `t3code` at the pinned commit without `.repos/`, installs th ## Things to know -- GitHub runs a PR's own copy of this workflow, so a PR could rewrite the check. The `*` line in `CODEOWNERS`, which also covers `.github/`, is what stops that: such a PR needs the owner's review. A ruleset `workflows` rule that requires this workflow from a pinned ref would remove the gap; it is planned (see Workflow permissions above). +- GitHub runs a PR's own copy of this workflow, so a PR could rewrite the check. The `*` line in `CODEOWNERS`, which also covers `.github/`, is what stops that: such a PR needs the owner's review. A ruleset `workflows` rule isn't available on a user-owned repo, so Kin checks the check's workflow and SHA itself before merging (see Workflow permissions above). - A `.gitleaksignore` anywhere in the memory repo fails the check, because gitleaks would honour it. `gitleaks:allow` comments are ignored. - A false positive the owner allowed in `kin_secret_allow` still fails gitleaks, which has no allowlist. Reword the text; whether the owner may merge past the check is settled with the ruleset. - `CODEOWNERS` denies by default, so a new root file such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.mcp.json` or `.codex/` needs the owner's review before the lead's read checkout loads it. The lint fails if the file still names `@OWNER` or frees any path beyond Kin's own.