projectkeeper 0.0.0-stage → 1.0.0

package/src/keeper/roles.ts

@@ -0,0 +1,259 @@
+/**
+ * Which pk_* tools a Keeper job is offered (Spec §3.3).
+ *
+ * A step of a clerk-method round gets its step's tools: pi's built-ins, every read, every ledger query, and the writes
+ * its step owns (`stepToolsFor`; "跨对象的记录由哪一步写"), so one matter is written once, by the step that owns it. Any
+ * other job is either a subagent — an investigation another job sent — which reads, and writes only what concerns its own
+ * material, or other work — the owner's conversation, an answer, a request, a re-look — which is offered every tool except
+ * those only a round's step has a round for (`toolsFor`).
+ *
+ * This is kept by the tools a job is given, not by asking the model: a subagent is never offered a tool that writes across
+ * objects. When several kinds of independent job wrote the work items at once, the same work came out several times,
+ * because nothing held the round (Spec §3.3, D62 background).
+ *
+ * The D59 method — a round claimed by one main job, whose role and round kind gated its tools — was replaced by the clerk
+ * method (Spec v3.0 §3.3); its gating is gone. `roundKindOf` still recognises such a job for the two readers outside this
+ * file that ask (see there).
+ */
+import type { KeeperJob } from '../model/types.ts';
+import type { ClerkRound, RoundStepKind } from '../model/k-types.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import { clerkWritersOf, LANE_ALWAYS, MAIN_ALWAYS, SLOT_WRITERS, STAGE_WRITERS, SYNTHESIS_ALWAYS, SYNTHESIS_WRITERS } from './clerk-steps.ts';
+import { gatedTool, MAIN_FOLLOW_UP_WRITES, stageOfRound } from './organize/stage-gate.ts';
+
+/** The kinds of round of the D59 method: the takeover's first round, a deepening round, a Follow up. */
+export type RoundKind = 'frame' | 'deepen' | 'follow-up';
+export type JobRole = 'subagent' | 'other';
+
+interface RoundExtra { readonly kind?: string; readonly round?: string; readonly roundId?: string }
+const extraOf = (job: Pick<KeeperJob, 'task'> | null | undefined): RoundExtra | null => ((job?.task as { extra?: RoundExtra } | null)?.extra ?? null);
+
+/** The rounds of the D59 method, by the kind their jobs carry (`task.extra.kind`). */
+export const REPLACED_ROUND_KINDS: ReadonlySet<string> = new Set(['takeover', 'round', 'materials']);
+/** A job of a D59 round: the clerk method replaced them, and their prompts name tools that no longer exist. */
+export const isReplacedRound = (job: Pick<KeeperJob, 'task' | 'step'>): boolean => !job.step && REPLACED_ROUND_KINDS.has(extraOf(job)?.kind ?? '');
+
+/**
+ * The kind of D59 round a job is the main job of, or null. No code creates such a job any more: the clerk method replaced
+ * them, a waiting one is stopped when the Keeper starts, and a stopped or failed one is not continued (runtime.ts
+ * `stopReplacedRounds`, `restartJob`). What still asks, every path of it dead in the running program:
+ * - organize/service.ts `relookAfterRequest` (a re-look waits while such a round runs) and round-tools.ts
+ *   `pk_ask_owner_about_rules` (a D59 main job's rules note), through `isRoundMain`;
+ * - tools.ts `roundOf` (a D59 Follow up main job judging and writing `pk_write_round_result`), and this file's
+ *   `judgesFollowUp` and `takeoverRoundOf`. The judgement tests still judge through such a job (adjustment-rules,
+ *   propagation-rules, round-owner, takeover-judgement, tools-validation, replaced-rounds, frame-subagent, method-tools),
+ *   so these stay until those tests judge through a clerk round's cross-check.
+ */
+export function roundKindOf(job: Pick<KeeperJob, 'task' | 'parentJobId'> | null | undefined): RoundKind | null {
+  if (!job || job.parentJobId) return null;
+  const x = extraOf(job);
+  if (x?.kind === 'round') return 'follow-up';
+  if (x?.kind === 'takeover') return x.round === 'deepen' ? 'deepen' : 'frame';
+  return null;
+}
+
+export const isRoundMain = (job: Pick<KeeperJob, 'task' | 'parentJobId'> | null | undefined): boolean => roundKindOf(job) !== null;
+
+/**
+ * The clerk-method round a job belongs to (Spec v3.0 §3.3): a step's own round, or the round whose root job this is.
+ * Null for work outside the clerk method.
+ */
+export function clerkRoundOfJob(store: ProjectStore, job: Pick<KeeperJob, 'task' | 'step'> | null | undefined): ClerkRound | null {
+  const x = extraOf(job);
+  const id = job?.step?.roundId ?? (x?.kind === 'clerk-round' || x?.kind === 'clerk-step' ? x.roundId : undefined);
+  return id ? store.clerkRounds.get(id) ?? null : null;
+}
+
+/**
+ * The Follow up round record (`store.rounds`) a job judges in by the clerk method (Spec v3.0 §3.3, §5.5): a Follow up
+ * round opens its record when it begins, and its cross-check records each piece of work's net change and judges each
+ * object the changes reached, once, into that record. The round's one result is counted when the round closes. Null
+ * for every other step and for work outside the clerk method.
+ */
+export function clerkFollowUpRecordOf(store: ProjectStore, job: Pick<KeeperJob, 'task' | 'step'> | null | undefined): string | null {
+  const round = clerkRoundOfJob(store, job);
+  // D99: the main job judges in its cross-check stage (its effective stage).
+  const crossCheck = job?.step?.kind === 'cross-check' || (job?.step?.kind === 'main' && !!round && stageOfRound(round) === 'cross-check');
+  return round?.kind === 'Follow up' && crossCheck ? round.followUpRoundId : null;
+}
+
+/**
+ * Whether a job judges in a Follow up round: the round's cross-check (§5.5). A D59 Follow up main job still counts here,
+ * for tools.ts's round and request paths — no such job runs any more; the tests that judge through one are listed in
+ * `roundKindOf`'s note.
+ */
+export function judgesFollowUp(store: ProjectStore, job: Pick<KeeperJob, 'task' | 'parentJobId' | 'step'> | null | undefined): boolean {
+  return roundKindOf(job) === 'follow-up' || clerkFollowUpRecordOf(store, job) !== null;
+}
+
+/** A job with a parent is a subagent of the work that sent it, whatever it was sent to do. A step of a round has its
+ *  round's root as parent, and gets its step's tools instead (`stepToolsFor`). */
+export function jobRole(job: Pick<KeeperJob, 'task' | 'parentJobId'>): JobRole {
+  return job.parentJobId ? 'subagent' : 'other';
+}
+
+/**
+ * Whether a job is part of taking the project over: a step of the first usable round or of a deepening, or anything under
+ * one. Such a job never opens or joins a Follow up round (§5.5: propagation is judged in the Follow up after the takeover).
+ */
+export function isTakeoverWork(store: ProjectStore, jobId: string | null | undefined): boolean {
+  return takeoverRoundOf(store, jobId) !== null;
+}
+
+/**
+ * The takeover round a job belongs to — the clerk round of the first usable picture or of a deepening (or, before the
+ * clerk method, a takeover round's main job) — or null for work outside the takeover. What such work writes names this
+ * round, never a Follow up round.
+ */
+export function takeoverRoundOf(store: ProjectStore, jobId: string | null | undefined): string | null {
+  let job = jobId ? store.jobs.get(jobId) : undefined;
+  for (let depth = 0; job && depth < 8; depth++) {
+    const clerk = clerkRoundOfJob(store, job);
+    if (clerk) return clerk.kind === 'Follow up' ? null : clerk.id;
+    if (job.scope.kind === 'takeover' || extraOf(job)?.kind === 'takeover') return job.id;
+    job = job.parentJobId ? store.jobs.get(job.parentJobId) : undefined;
+  }
+  return null;
+}
+
+/**
+ * What a subagent may use: reading the assets and the sources, recording how a source is used, and the fact records
+ * of its own material. An allowlist on purpose: a tool added later that writes across objects is kept from subagents
+ * until someone decides otherwise. A subagent sends no subagents of its own: subagents do not wait on one another
+ * (§3.3), and what else needs reading is for the job that sent it to hand out.
+ */
+export const SUBAGENT_TOOLS: ReadonlySet<string> = new Set([
+  'pk_project_overview', 'pk_list_sources', 'pk_read_source', 'pk_read_assets', 'pk_find_references', 'pk_set_used_as', 'pk_write_fact_record',
+  // Version history is read like any material; what it records is a History only source of that reading alone.
+  'pk_history_log', 'pk_history_read', 'pk_history_deleted',
+  // A claim is checked against the code by the subagent that read the report, and the check is recorded next to the
+  // claim in that report's fact record (Spec §2.4; CKC-06 AC-23).
+  'pk_record_code_check',
+]);
+/**
+ * What only a Follow up round's cross-check does (§2.10, §3.3, §5.5; CKC-11 AC-25): one state per object per round, and
+ * what its own changes reached. The owner's conversation, an answer, a request or a re-look has no round of its own: a
+ * judgement from one of them used to open a round, judge in it and close it with a result beside the round. An owner's
+ * correction is recorded on the object itself and judged by the next Follow up round; the owner who wants that now
+ * presses Follow up (§3.8). `pk_write_round_result` is offered to no job at all: the clerk method counts the round's one
+ * result when the round closes (organize/clerk.ts); the tool stays for the tests that judge through a D59 main job.
+ */
+export const FOLLOW_UP_TOOLS: ReadonlySet<string> = new Set(['pk_judge_object', 'pk_set_propagation', 'pk_set_propagations', 'pk_round_pending', 'pk_write_round_result']);
+/** Putting the rules the round inferred to the owner in the round's one note (§3.9): only a round's synthesis has a
+ *  round to write that note for. */
+export const ROUND_SYNTHESIS_TOOLS: ReadonlySet<string> = new Set(['pk_ask_owner_about_rules']);
+
+/**
+ * The tools a job that is not a step of a round is offered. pi's own tools (read, grep, bash …) are not pk_* tools and
+ * pass through (§3.1). A subagent reads, and writes only its own material's fact records; other work gets every pk_* tool
+ * except those only a round's step has a round for.
+ */
+export function toolsFor<T extends { readonly name: string }>(tools: readonly T[], role: JobRole): T[] {
+  return tools.filter((t) => {
+    if (!t.name.startsWith('pk_')) return true;
+    // The ledger's tools only read (§1.16): a subagent asks them as any step does (CKC-03 AC-26).
+    if (role === 'subagent') return SUBAGENT_TOOLS.has(t.name) || t.name.startsWith('pk_ledger_');
+    return !FOLLOW_UP_TOOLS.has(t.name) && !ROUND_SYNTHESIS_TOOLS.has(t.name);
+  }).map((t) => (t.name === OWNER_WORDS_TOOL ? countedOwnerWords(t) : t));
+}
+
+// ───────────────────────── how much of the owner's words a job read (Spec §3.7; D37; CKC-13 AC-25) ─────────────────────────
+
+const OWNER_WORDS_TOOL = 'pk_owner_utterances';
+
+type ToolResult = { content?: { type: string; text?: string }[] } & Record<string, unknown>;
+
+/**
+ * pk_owner_utterances with how much it read leading its answer: "Read 50 of the owner’s 60 messages (9000 of 11000
+ * characters)". The first round's owner's-words step is evidence for D37 — how long it took and how much the owner
+ * said — and the job's steps are where the runtime keeps each call, so the count is put where the step keeps it. The
+ * answer itself follows unchanged.
+ */
+function countedOwnerWords<T extends { readonly name: string }>(tool: T): T {
+  const run = (tool as unknown as { execute?: (...args: unknown[]) => Promise<ToolResult> }).execute;
+  if (typeof run !== 'function') return tool;
+  return {
+    ...tool,
+    execute: async (...args: unknown[]) => {
+      const result = await run.apply(tool, args);
+      const first = result?.content?.[0];
+      if (!first || typeof first.text !== 'string') return result;
+      let page: { utterances?: { chars?: number; text?: string }[]; total?: number; totalChars?: number };
+      try { page = JSON.parse(first.text) as typeof page; } catch { return result; }
+      if (!Array.isArray(page.utterances)) return result;
+      const chars = page.utterances.reduce((n, u) => n + (typeof u.chars === 'number' ? u.chars : (u.text ?? '').length), 0);
+      const line = `Read ${page.utterances.length} of the owner’s ${page.total ?? page.utterances.length} messages (${chars} of ${page.totalChars ?? chars} characters)`;
+      return { ...result, content: [{ ...first, text: `${line} ${first.text}` }, ...(result.content ?? []).slice(1)] };
+    },
+  } as T;
+}
+
+// ───────────────────────── the clerk method: what each step may write (Spec v3.0 §3.3) ─────────────────────────
+
+/**
+ * Reading is open to every step (CKC-23 AC-5): every pk_* read tool and every ledger tool (`pk_ledger_*`), besides pi's
+ * built-ins, which are never filtered here. What a step may write follows §3.3 "跨对象的记录由哪一步写": orientation the
+ * layers, rules, generations and the round's questions and briefs; the skeleton the trunk, numbers and patch drafts; a
+ * deep sweep only its report; the cross-check the positions it has checked; the synthesis the notes, send-backs, the
+ * six things, area understanding and the round's Result (D103: in a job of its own, after the main agent's handover);
+ * the spot-check its corrections and its record. So one matter is written once, by the step that owns it.
+ */
+const PK_READ_TOOLS: ReadonlySet<string> = new Set([
+  'pk_project_overview', 'pk_list_sources', 'pk_read_source', 'pk_read_assets', 'pk_find_references', 'pk_owner_utterances',
+  'pk_history_log', 'pk_history_read', 'pk_history_deleted', 'pk_scope_items',
+]);
+const TRUNK_WRITES = ['pk_write_reference', 'pk_write_thread', 'pk_write_area', 'pk_relate', 'pk_write_mark', 'pk_merge_work_items', 'pk_record_carry_out', 'pk_check_decisions', 'pk_set_used_as'];
+const FOLLOW_UP_WRITES = ['pk_write_change', 'pk_judge_object', 'pk_set_propagation', 'pk_set_propagations', 'pk_write_modification_request', 'pk_mark_request_handled', 'pk_round_pending'];
+/** The writers from before the clerk method, by step; the clerk method's own writers come from their one table. */
+const EARLIER_WRITES: Readonly<Record<RoundStepKind, readonly string[]>> = {
+  ledger: [],
+  // D99 (W1+W2): the main agent is offered every stage's writers, gated by its stage; a lane by its slots.
+  main: [],
+  lane: [],
+  'session-drafts': [],
+  orientation: ['pk_write_rule', 'pk_classify_scope', 'pk_set_used_as', 'pk_write_organizing_plan'],
+  skeleton: TRUNK_WRITES,
+  dig: [],
+  'cross-check': [...TRUNK_WRITES, 'pk_write_rule'],
+  process: [],
+  // The round's result is its Result document; a Follow up's counted result is closed with the round (clerk.ts).
+  // D103: the synthesis is a job of its own again; what it is offered is one table (`SYNTHESIS_WRITERS`), with where the
+  // round stands (`SYNTHESIS_ALWAYS`).
+  synthesis: [...SYNTHESIS_WRITERS, ...SYNTHESIS_ALWAYS],
+  'spot-check': [...TRUNK_WRITES, 'pk_write_note'],
+};
+export const STEP_WRITES: Readonly<Record<string, ReadonlySet<string>>> = Object.fromEntries(
+  (Object.entries(EARLIER_WRITES) as [RoundStepKind, readonly string[]][]).map(([step, earlier]) => [step, new Set([...earlier, ...clerkWritersOf(step)])]),
+);
+
+/**
+ * What the main job (D99) and a lane write, offered whole to their one session (E148 D-a): the main job every stage's
+ * writers, and in a Follow up round the round's judgements; a lane its slots' writers and its Report.
+ */
+// D103: the main agent is no longer offered what only the synthesis writes — `STAGE_WRITERS.synthesis` is empty.
+function d99Writes(step: string, round: 'First usable' | 'Deepen' | 'Follow up', slots: readonly string[]): Set<string> {
+  if (step === 'main') return new Set([...MAIN_ALWAYS, ...Object.values(STAGE_WRITERS).flat(), ...(round === 'Follow up' ? MAIN_FOLLOW_UP_WRITES : [])]);
+  const base = (s: string) => (s.startsWith('reference:') ? 'reference' : s.split(':')[0]!);
+  return new Set([...LANE_ALWAYS, ...slots.flatMap((s) => SLOT_WRITERS[base(s) as keyof typeof SLOT_WRITERS] ?? [])]);
+}
+
+/**
+ * The tools a step of a clerk-method round is offered: pi's built-ins, every read, and the writes its step owns. The main
+ * job and a lane (D99) are offered what they write in any stage or slot; `gate` then refuses at call time what the job's
+ * effective stage does not allow (stage-gate.ts `writeRefusal`), so each writer still writes only where it belongs.
+ */
+export function stepToolsFor<T extends { readonly name: string }>(tools: readonly T[], step: string, round: 'First usable' | 'Deepen' | 'Follow up',
+  lane: { readonly slots: readonly string[] } | null = null, gate: ((tool: string, args: Record<string, unknown> | null) => string | null) | null = null): T[] {
+  const d99 = step === 'main' || step === 'lane';
+  const writes = d99 ? d99Writes(step, round, lane?.slots ?? []) : STEP_WRITES[step] ?? new Set<string>();
+  const followUp = round === 'Follow up' && step === 'cross-check';
+  return tools.filter((t) => {
+    if (!t.name.startsWith('pk_')) return true;
+    if (t.name.startsWith('pk_ledger_') || PK_READ_TOOLS.has(t.name)) return true;
+    return writes.has(t.name) || (followUp && FOLLOW_UP_WRITES.includes(t.name));
+  }).map((t) => {
+    const counted = t.name === OWNER_WORDS_TOOL ? countedOwnerWords(t) : t;
+    const reads = !t.name.startsWith('pk_') || t.name.startsWith('pk_ledger_') || PK_READ_TOOLS.has(t.name);
+    return d99 && gate && !reads ? gatedTool(counted as T & { execute?: (...args: never[]) => unknown }, gate) : counted;
+  });
+}

package/src/keeper/round-tools.ts

@@ -0,0 +1,227 @@
+/**
+ * Round tools besides the pk_* asset tools (Spec §3.3): what a Follow up round still has to judge (pk_round_pending), a
+ * claim checked against the code (pk_record_code_check), and the rules a round inferred, put to the owner
+ * (pk_ask_owner_about_rules). Which job is offered which tool is decided in roles.ts.
+ */
+import { Type } from 'typebox';
+import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import type { CodeCheck, JudgementRecord, Note, NoteVersion, Source, Statement } from '../model/types.ts';
+import { newId } from '../model/ids.ts';
+import type { ToolContext } from './tools.ts';
+import { clerkRoundOfJob, isRoundMain } from './roles.ts';
+import { cameFromFor } from './note-origin.ts';
+import { laneNamesOf, ownerTextRefusal } from './owner-text.ts';
+import { deriveGraph } from './organize/graph.ts';
+import { pendingForRound } from './organize/follow-up.ts';
+import { projectRelPath } from './organize/materials.ts';
+import { isDocumentPath } from '../scope/skip.ts';
+
+/** The order claims about the code are checked in (Spec §2.4, D63; CKC-06 AC-23) — an order, not a limit. */
+export const CHECK_TIER = ["Owner's words or red line", 'Done or verified', 'Other'] as const;
+/** What a check of a claim against the code found. */
+export const CHECK_RESULT = ['Consistent', 'Inconsistent', 'Partly consistent'] as const;
+const CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|kts|swift|c|cc|cpp|cxx|h|hh|hpp|cs|rb|php|scala|sh|bash|ps1|psm1|sql|vue|svelte|dart|lua|m|mm|r|jl|ex|exs|erl|hs|clj|fs|ml|zig|nim|sol|proto|gradle|json|jsonc|ya?ml|toml|ini|cfg|conf|xml|html?|css|scss|less)$/i;
+/** Code, tests and the configuration they read: what a claim about the code's behaviour is checked against. */
+function isCode(s: Source): boolean {
+  if (s.usedAs === 'Code' || s.usedAs === 'Test') return true;
+  const path = s.anchor.kind === 'file' || s.anchor.kind === 'revision' ? s.anchor.path : null;
+  return path !== null && CODE_EXT.test(path) && !isDocumentPath(path);
+}
+const squash = (s: string) => s.replace(/\s+/g, ' ').trim().toLowerCase();
+
+const text = (v: unknown, fallback = ''): string => (typeof v === 'string' ? v : fallback);
+const arr = <T>(v: unknown): T[] => (Array.isArray(v) ? (v as T[]) : []);
+const ok = (value: unknown) => ({ content: [{ type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value, null, 1) }], details: {} });
+const fail = (message: string) => ({ content: [{ type: 'text' as const, text: `ERROR: ${message}` }], details: {}, isError: true });
+
+export function roundTools(ctx: ToolContext): ToolDefinition[] {
+  return [
+    defineTool({
+      name: 'pk_round_pending', label: 'What this round still has to judge',
+      description: 'After recording the changes of this round\'s material (pk_write_change), the objects they reached are found by rule. This lists every object the round still has to judge — the ones given with the round and the ones your changes reached — each with the items that reached it and what it still lacks. Objects already judged in this round are not listed again.',
+      parameters: Type.Object({}),
+      execute: async () => {
+        // The downstream of a change is seeded when the graph is derived, which otherwise happens only after a job
+        // ends: without this, what the round's own changes reached would wait for the next round.
+        deriveGraph(ctx.store, ctx.project);
+        const pending = pendingForRound(ctx.store);
+        return ok(pending.objects ? `${pending.objects} object${pending.objects === 1 ? '' : 's'} still to judge in this round:\n${pending.text}` : 'Nothing is left to judge in this round.');
+      },
+    }),
+    codeCheckTool(ctx),
+    rulesToOwnerTool(ctx),
+  ];
+}
+
+/**
+ * `pk_record_code_check` (Spec §2.4, D63; CKC-06 AC-23): a claim about what the code does, checked by reading the code,
+ * recorded next to the claim in the report's fact record — an Observed statement anchored to the code (repository,
+ * commit, file, lines), with which claim it checks, in which order and what it found. The claim itself stays as it
+ * was reported. How many claims were checked, in which order and how many did not hold is counted from these.
+ * Checking the same claim again replaces the earlier check.
+ *
+ * Where a check hangs is not settled by the PA yet (asked); this is the most conservative reading: on the fact record
+ * that holds the claim, beside it, changing nothing else. What spans objects — the contradicts relation, the Suspected
+ * stale mark on the status that rests on the claim — is the main job's to write, and the result tells it so.
+ */
+function codeCheckTool(ctx: ToolContext): ToolDefinition {
+  const { store } = ctx;
+  return defineTool({
+    name: 'pk_record_code_check', label: 'Record a claim checked against the code',
+    description: `Record the check of one claim against the code, next to the claim, in the fact record that holds it. Read the code only — never run tests, re-do QC or grade anyone. Give the fact record, the claim (its statement id, or its text as recorded), its tier in the order claims are checked (${CHECK_TIER.join(' → ')}), the result (${CHECK_RESULT.join(', ')}), the code sources you read (codeSourceIds), the lines, and what the code does, in one or two sentences. The commit is the one the source was read at unless you name another. It is written as an Observed statement anchored to the code; the claim stays Claimed. Checking the same claim again replaces the earlier check.`,
+    parameters: Type.Object({
+      factRecordId: Type.String({ description: 'the fact record that holds the claim (the report’s)' }),
+      claim: Type.String({ description: 'the claim: its statement id, or its text as the fact record has it' }),
+      tier: Type.String({ description: CHECK_TIER.join(' | ') }),
+      result: Type.String({ description: CHECK_RESULT.join(' | ') }),
+      codeSourceIds: Type.Array(Type.String(), { description: 'the sources of the code you read' }),
+      lines: Type.String({ description: 'the lines you read, e.g. 40-58' }),
+      observed: Type.String({ description: 'what the code does, in one or two sentences' }),
+      file: Type.Optional(Type.String({ description: 'the file, when it is not the first code source’s own' })),
+      commit: Type.Optional(Type.String({ description: 'the commit you read the code at, when it is not the one the source was read at' })),
+    }),
+    execute: async (_id, p) => {
+      const record = store.facts.get(text(p.factRecordId).trim());
+      if (!record) return fail(`${text(p.factRecordId)} is not a fact record; give the id of the fact record that holds the claim (the report’s).`);
+      const given = text(p.claim).trim();
+      const claims = record.statements.filter((s) => s.type === 'Claimed');
+      const claim = claims.find((s) => s.id === given) ?? claims.find((s) => squash(s.text) === squash(given));
+      if (!claim) {
+        return fail(`No claim in ${record.id} reads “${given.slice(0, 160)}”. Name one of its Claimed statements by id or by its text as recorded${claims.length ? `: ${claims.slice(0, 12).map((s) => `${s.id} “${s.text.slice(0, 80)}”`).join('; ')}` : ' — it has none: what a report says it did is written there as Claimed first (pk_write_fact_record)'}.`);
+      }
+      if (!(CHECK_TIER as readonly string[]).includes(text(p.tier))) return fail(`tier must be one of ${CHECK_TIER.join(', ')} — the order claims are checked in: first what bears on the owner’s words and red lines, then what a Done or verified status rests on, then the rest.`);
+      if (!(CHECK_RESULT as readonly string[]).includes(text(p.result))) return fail(`result must be one of ${CHECK_RESULT.join(', ')}.`);
+      const ids = [...new Set(arr<string>(p.codeSourceIds).map((id) => text(id).trim()).filter(Boolean))];
+      if (ids.length === 0) return fail('Name the code you read (codeSourceIds): the source ids of the code files the check rests on.');
+      const sources: Source[] = [];
+      for (const id of ids) {
+        const s = store.sources.get(id);
+        if (!s) return fail(`codeSourceIds: unknown source ${id}`);
+        if (!isCode(s)) return fail(`${id} (${s.title}) is not code: a claim about what the code does is checked against the code itself; a document that describes it is another claim.`);
+        sources.push(s);
+      }
+      const lines = text(p.lines).trim();
+      if (!lines) return fail('Say which lines you read (lines, e.g. 40-58): the check is anchored to commit, file and lines.');
+      const observed = text(p.observed).trim();
+      if (!observed) return fail('Say what the code does (observed), in one or two sentences: that is the observation the check records.');
+      const first = sources[0]!;
+      const a = first.anchor;
+      const repo = a.kind === 'revision' ? a.repo : ctx.project.scope.find((i) => i.id === first.scopeItemId && (i.category === 'Repository' || i.category === 'Worktree'))?.path ?? ctx.project.locations[0] ?? null;
+      const file = text(p.file).trim() || (a.kind === 'revision' ? a.path : a.kind === 'file' ? projectRelPath(ctx.project, a.path).split('\\').join('/') : first.title);
+      const commit = text(p.commit).trim() || (a.kind === 'revision' ? a.commit : first.version.commit) || null;
+      const check: CodeCheck = { of: claim.id, tier: text(p.tier), result: text(p.result), anchor: { repo, commit, file, lines } };
+      const earlier = record.statements.findIndex((s) => s.check?.of === claim.id);
+      const statement: Statement = {
+        id: earlier >= 0 ? record.statements[earlier]!.id : newId('st'), type: 'Observed',
+        text: `${observed} (${file}:${lines}${commit ? ` at ${commit.slice(0, 10)}` : ''}; checks claim ${claim.id}: ${check.result})`,
+        sourceIds: ids, check,
+      };
+      const statements = earlier >= 0 ? record.statements.map((s, i) => (i === earlier ? statement : s)) : [...record.statements, statement];
+      store.facts.put({ ...record, statements, updatedAt: new Date().toISOString() }, { jobId: ctx.jobId, basisSourceIds: [...ids, ...claim.sourceIds], summary: `Code check of claim ${claim.id} (${check.tier}): ${check.result}` });
+      ctx.onSaved?.('facts', record.id, `Code check: ${check.result}`);
+      const held = check.result === 'Consistent';
+      return ok({
+        factRecordId: record.id, statementId: statement.id, claim: claim.id, tier: check.tier, result: check.result, anchor: check.anchor, replacedEarlierCheck: earlier >= 0,
+        next: held
+          ? 'The claim holds as far as this code shows: the check is its observation, and the claim stays as reported.'
+          : `The claim does not hold${check.result === 'Partly consistent' ? ' in full' : ''}: the main job writes contradicts from the code source to the report’s source (the claim quoted in the relation’s claim), puts Suspected stale on the status that rests on it — its progress stays as reported — and adds the claim and this check to that work item’s executionFacts. Say it in your report.`,
+      });
+    },
+  });
+}
+
+/**
+ * `pk_ask_owner_about_rules` (Spec §1.15, §3.9; CKC-21 AC-5): the rules a round inferred from what the project does
+ * that change how an agent works, put to the owner in the round's one `For your decision` note — each with the records
+ * it rests on and what it changes. A later call in the same round adds to that note; a rule the project writes down,
+ * one the owner confirmed, or one an earlier round inferred is refused with the reason.
+ */
+function rulesToOwnerTool(ctx: ToolContext): ToolDefinition {
+  const { store } = ctx;
+  return defineTool({
+    name: 'pk_ask_owner_about_rules', label: 'Put the rules this round inferred to the owner',
+    description: 'The rules you inferred in this round from what the project does (basis Inferred) that change how an agent works on the project, put to the owner in the round’s one For your decision note: each rule with the records it rests on and what it changes for an agent. Call it at the end of the round with all of them; a later call in the same round adds to the same note. Until the owner confirms a rule it stays marked as your inference.',
+    parameters: Type.Object({
+      rules: Type.Array(Type.Object({ ruleId: Type.String(), changes: Type.String({ description: 'what the rule changes in how an agent works on the project, in one sentence' }) })),
+    }),
+    execute: async (_id, p) => {
+      const job = store.jobs.get(ctx.jobId);
+      // By the clerk method the synthesis puts the round's inferred rules to the owner: the rules its orientation and
+      // cross-check wrote are this round's (Spec v3.0 §3.3, §3.9). Before it, a round's main job did, with its own.
+      const synthesis = job?.step?.kind === 'synthesis' || (job?.step?.kind === 'main' && clerkRoundOfJob(store, job)?.stage === 'synthesis');
+      const clerk = synthesis ? clerkRoundOfJob(store, job) : null;
+      if (!job || (!isRoundMain(job) && !clerk)) return fail('Only a round’s synthesis (or, before the clerk method, a round’s main job) puts the rules the round inferred to the owner, in the round’s one note; outside a round there is no round note to put them in. Name them in your reply instead.');
+      const roundJobs = clerk ? new Set(store.jobs.filter((j) => j.step?.roundId === clerk.id).map((j) => j.id)) : new Set([ctx.jobId]);
+      const asked = arr<Record<string, unknown>>(p.rules).map((r) => ({ ruleId: text(r.ruleId).trim(), changes: text(r.changes).trim() }));
+      if (asked.length === 0) return fail('Name the rules you inferred in this round: rules: [{ ruleId, changes }].');
+      for (const q of asked) {
+        const rule = store.rules.get(q.ruleId);
+        if (!rule) return fail(`${q.ruleId} is not one of the project’s rules; use the id pk_write_rule returned.`);
+        if (rule.ownerConfirmation) return fail(`${rule.id} is already confirmed by the owner: there is nothing to ask.`);
+        if (rule.basis === 'Explicit') return fail(`${rule.id} is written in the project (basis Explicit): the project’s own rule needs no confirmation. Only the rules you inferred from what the project does are put to the owner.`);
+        if (rule.validity !== 'Current') return fail(`${rule.id} is ${rule.validity}: only a rule in force is put to the owner.`);
+        if (!roundJobs.has(rule.jobId ?? '')) return fail(`${rule.id} was not inferred in this round: a round puts to the owner the rules it inferred itself; an earlier round’s rules went into that round’s note.`);
+        if (!q.changes) return fail(`Say for ${rule.id} what it changes for an agent working on the project (changes).`);
+      }
+      const at = new Date().toISOString();
+      const noteId = `note_rules-${clerk ? clerk.id : ctx.jobId}`;
+      const previous = store.notes.get(noteId);
+      // The owner reads this note (§4.2, §6.13; D105): what a rule changes is said without the store's ids.
+      const unreadable = ownerTextRefusal('The note that puts the inferred rules to the owner', Object.fromEntries(asked.map((q, i) => [`rules[${i}].changes`, q.changes])), laneNamesOf(store));
+      if (unreadable) return fail(unreadable);
+      // One fact per rule: a rule asked about again takes the new wording, the others stay as they were. Which rule a
+      // fact is about is its link (`ruleId`), not a part of its sentence; a note written before D105 named the rule's id
+      // in the sentence, which is read once more here and left out of what is written.
+      const factOf = (ruleId: string, changes: string) => {
+        const r = store.rules.get(ruleId)!;
+        return { text: `${r.summary} — for an agent this means: ${changes} (applies to ${r.appliesTo.join('; ')}; inferred from the records cited)`, sourceIds: [...r.sourceIds], inferred: true, ruleId: r.id };
+      };
+      const facts = new Map<string, { text: string; sourceIds: string[]; inferred: boolean; ruleId: string }>();
+      for (const f of previous?.versions[previous.versions.length - 1]?.body.facts ?? []) {
+        const id = f.ruleId ?? /\(rule ([^;)\s]+)/.exec(f.text)?.[1];
+        if (id) facts.set(id, { text: f.text.replace(/\(rule [^;)\s]+; /, '('), sourceIds: [...f.sourceIds], inferred: f.inferred, ruleId: id });
+      }
+      for (const q of asked) facts.set(q.ruleId, factOf(q.ruleId, q.changes));
+      const ruleIds = [...facts.keys()];
+      let judgementId = ctx.judgementId && store.judgements.has(ctx.judgementId) ? ctx.judgementId : previous?.versions[0]?.judgementRecordId ?? '';
+      if (!store.judgements.has(judgementId)) {
+        const judgement: JudgementRecord = {
+          id: newId('jdg'), projectId: ctx.project.id, jobId: ctx.jobId, at,
+          scope: { kind: 'rules', ids: ruleIds, label: `Rules inferred in ${job.scope.label}` },
+          inputs: { referenceIds: [], threadIds: [], areaIds: [], relationIds: [], keyEvidenceSourceIds: [...new Set([...facts.values()].flatMap((f) => f.sourceIds))], conflictingSourceIds: [], previousNoteIds: [], investigations: [] },
+          excluded: [], outcome: { noteIds: [], assessments: [], reconsideredOnly: false },
+        };
+        store.judgements.put(judgement, { jobId: ctx.jobId, summary: `Inputs recorded: ${judgement.scope.label}` });
+        judgementId = judgement.id;
+      }
+      const n = ruleIds.length;
+      const version: NoteVersion = {
+        version: (previous?.versions.length ?? 0) + 1, at,
+        title: `Do the rules inferred from how the project works hold?`,
+        // The first sentence is the question (§4.2, D105); the title says the same.
+        preview: `${n === 1 ? 'Does the rule' : `Do the ${n} rules`} this round inferred from the project’s records hold? ${n === 1 ? 'It' : 'Each'} would change how an agent works on the project. Until you confirm ${n === 1 ? 'it, it stays' : 'them, they stay'} marked as the Keeper’s inference.`,
+        body: {
+          options: [
+            { option: 'Confirm a rule', then: 'it becomes the project’s rule, with your words as its source' },
+            { option: 'Correct or reject a rule', then: 'it is recorded as you say, and agents are no longer given the inferred wording' },
+            { option: 'Leave them', then: 'each stays in force for agents, marked as the Keeper’s inference' },
+          ],
+          currentView: `Inferred in ${job.scope.label}. Each rule is listed below with what it changes for an agent and the records it rests on.`,
+          whyItMatters: 'An agent working on the project follows the project’s rules. An inferred rule is shown everywhere as the Keeper’s inference, never as the project’s or your rule, until you confirm it.',
+          facts: [...facts.values()], otherExplanations: null, keepAdjust: null,
+          whatWouldSettleIt: 'Your word in the conversation on each rule: confirmed, it becomes the project’s rule with your words as its source; corrected or rejected, it is recorded as you say.',
+        },
+        ask: 'For your decision', judgementRecordId: judgementId,
+        reason: previous ? `More rules inferred in the same round (${asked.length})` : 'The rules a round infers are put to the owner once per round',
+      };
+      const note: Note = previous
+        ? { ...previous, versions: [...previous.versions, version], status: 'Current', updatedAt: at }
+        : { id: noteId, projectId: ctx.project.id, mount: { kind: 'project', ids: [] }, status: 'Current', ownerResponse: null, versions: [version], discussion: [], followUps: [], author: { agent: 'pi', model: ctx.model }, resolvedReason: null, withdrawnReason: null, delegatedTo: null, cameFrom: cameFromFor(store, job, []), language: ctx.project.language, updatedAt: at };
+      store.notes.put(note, { jobId: ctx.jobId, basisSourceIds: [...new Set(version.body.facts.flatMap((f) => f.sourceIds))], summary: `${previous ? `Note v${version.version}` : 'Note'}: ${version.title}` });
+      const j = store.judgements.get(judgementId)!;
+      store.judgements.put({ ...j, outcome: { ...j.outcome, noteIds: [...new Set([...j.outcome.noteIds, noteId])] } });
+      ctx.onSaved?.('notes', noteId, `Note: ${version.title}`);
+      return ok({ noteId, version: version.version, rules: ruleIds });
+    },
+  });
+}