projectkeeper 0.0.0-stage → 1.0.0

package/src/keeper/own-keys.ts

@@ -0,0 +1,114 @@
+/**
+ * The owner's own keys (Spec §6.10 "key、模型与路由", §3.1; D105; CKC-03 AC-33).
+ *
+ * A key the owner enters in `Keeper` → `Model provider` is kept on this machine, in ProjectKeeper's own home
+ * (`<home>/keys.json`), beside `workspace.json` and outside every project: it belongs to no project, it is there after a
+ * restart, and every project can choose it. Its value is written in that one file and nowhere else — not in a project's
+ * files, not in the project's ProjectKeeper folder, its assets, exports, trace, session records or context packs, and not
+ * in a log (the grep test in own-keys.test.ts). Nothing this module returns to a caller outside the runtime carries the
+ * value: `publicKey` is what the workbench sees, with a full mask (U98: not one character shown).
+ *
+ * Each key runs under a provider id of its own (`<provider>~<n>`), registered with pi like an extra key (runtime.ts
+ * `registerOwnKeys`), so it has its own lanes, its own quota window and its own place in a project's backup order.
+ */
+import { readJson, writeJsonAtomic } from '../store/json-file.ts';
+import { ensureHome } from '../store/paths.ts';
+import { chmodSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface OwnKey {
+  /** The provider id the key runs under in pi, e.g. `deepseek~1`. */
+  readonly id: string;
+  /** The provider whose endpoint and models it uses, e.g. `deepseek`. */
+  readonly provider: string;
+  readonly name: string;
+  readonly value: string;
+  readonly addedAt: string;
+  readonly replacedAt: string | null;
+}
+
+/** What the workbench is told of a key: never the value. */
+export interface PublicOwnKey {
+  readonly id: string;
+  readonly provider: string;
+  readonly name: string;
+  readonly mask: string;
+  readonly addedAt: string;
+  readonly replacedAt: string | null;
+}
+
+/** The mask shown for a saved key: the same for every key, so not one character of it shows (U98). */
+export const KEY_MASK = '••••••••••••';
+
+interface KeysFile { readonly version: 1; readonly keys: readonly OwnKey[] }
+
+export const keysFile = (home: string): string => join(home, 'keys.json');
+/** The key file is its owner's alone on macOS and Linux, like any credentials file (`~/.ssh`, pi's own `auth.json`). */
+const KEYS_FILE_MODE = 0o600;
+
+export const publicKey = (k: OwnKey): PublicOwnKey => ({ id: k.id, provider: k.provider, name: k.name, mask: KEY_MASK, addedAt: k.addedAt, replacedAt: k.replacedAt });
+
+/** A key value as pasted: one line, no surrounding space or quotes. Refused when empty or when it has inner spaces. */
+export function cleanKeyValue(raw: unknown): string {
+  if (typeof raw !== 'string') throw new Error('The key is missing');
+  const value = raw.trim().replace(/^["'`]+|["'`]+$/g, '').trim();
+  if (!value) throw new Error('The key is empty');
+  if (/\s/.test(value)) throw new Error('A key is one word without spaces or line breaks: paste only the key');
+  return value;
+}
+
+export class OwnKeyStore {
+  private keys: OwnKey[];
+  private readonly home: string;
+  constructor(home: string) {
+    this.home = home;
+    // A key file written before it was kept to its owner (or copied in) is closed to other accounts as it is read.
+    if (process.platform !== 'win32') { try { if (statSync(keysFile(home)).mode & 0o077) chmodSync(keysFile(home), KEYS_FILE_MODE); } catch { /* no key file yet */ } }
+    this.keys = [...readJson<KeysFile>(keysFile(home), { version: 1, keys: [] }).keys];
+  }
+
+  list(): readonly OwnKey[] { return this.keys; }
+  get(id: string): OwnKey | undefined { return this.keys.find((k) => k.id === id); }
+
+  /** A new key for `provider`. Several keys of one provider each get an id of their own. */
+  add(provider: string, name: string | null, value: string, now = new Date().toISOString()): OwnKey {
+    let n = 1;
+    while (this.keys.some((k) => k.id === `${provider}~${n}`)) n++;
+    const sameProvider = this.keys.filter((k) => k.provider === provider).length;
+    const key: OwnKey = { id: `${provider}~${n}`, provider, name: name?.trim() || (sameProvider ? `${provider} key ${sameProvider + 1}` : `${provider} key`), value, addedAt: now, replacedAt: null };
+    this.keys = [...this.keys, key];
+    this.save();
+    return key;
+  }
+
+  /** A new value for a saved key (and a new name, when given): it keeps its id, so the routes that name it stand. */
+  replace(id: string, value: string | null, name: string | null = null, now = new Date().toISOString()): OwnKey {
+    const at = this.keys.findIndex((k) => k.id === id);
+    if (at < 0) throw new Error(`No key ${id}`);
+    const old = this.keys[at]!;
+    const next: OwnKey = { ...old, ...(value ? { value, replacedAt: now } : {}), ...(name?.trim() ? { name: name.trim() } : {}) };
+    this.keys = this.keys.map((k, i) => (i === at ? next : k));
+    this.save();
+    return next;
+  }
+
+  remove(id: string): OwnKey | null {
+    const old = this.get(id) ?? null;
+    if (!old) return null;
+    this.keys = this.keys.filter((k) => k.id !== id);
+    this.save();
+    return old;
+  }
+
+  /** Text with every saved key's value taken out (a provider's error message may quote what it was sent). */
+  redact(text: string): string {
+    let out = text;
+    for (const k of this.keys) if (k.value.length >= 6) out = out.split(k.value).join(KEY_MASK);
+    return out;
+  }
+
+  private save(): void {
+    ensureHome(this.home);
+    writeJsonAtomic(keysFile(this.home), { version: 1, keys: this.keys } satisfies KeysFile, KEYS_FILE_MODE);
+  }
+}

package/src/keeper/owner-text.ts

@@ -0,0 +1,165 @@
+/**
+ * The form of text the owner reads, checked by the program (Spec §4.2, §6.13; D105; CKC-08 AC-26, AC-27). The owner, of
+ * a note whose body carried a store id, a lane report's section number and a run of decision numbers, and that opened
+ * with no question: 「这个可读性太差了。」
+ *
+ * Two checks, each a refusal that costs the model one retry rather than a rule it has to keep in mind:
+ *
+ * 1. **No internal identifiers** in a note, a round's Result, or any other text written for the owner: ProjectKeeper's
+ *    own store ids (`mark_…`, `ref_…`, `rule_…`, `note_…` and the rest the store mints), a lane named as a lane, and a
+ *    lane report's or brief's section reference. The project's own numbers (D13, CKC-08, E151) are the project's words
+ *    and pass. The refusal names each one found and says where the evidence goes instead: the sources and links.
+ * 2. **A `For your decision` note opens with the question and gives the options**: the first sentence is the question
+ *    the owner is asked to decide; at least two options, each with what follows from it.
+ *
+ * What the program cannot tell — whether a numbered thing is said in plain words before its number is used — stays with
+ * the skill and the spot-check (U96).
+ */
+import type { NoteOption } from '../model/types.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+
+/**
+ * The prefixes the store mints ids with (model/ids.ts `newId`, `stableId`; every call site in src/). A test holds this
+ * list against those call sites, so a new collection's ids are recognised too.
+ */
+export const STORE_ID_PREFIXES = [
+  'mark', 'ref', 'rule', 'note', 'thread', 'rel', 'sb', 'bp', 'rdoc', 'draft', 'job', 'gen', 'terr', 'crd',
+  'scope', 'scopeq', 'scopej', 'src', 'fact', 'chg', 'jdg', 'item', 'step', 'link', 'st', 'msg', 'auth', 'patch', 'merge',
+  'layer', 'knum', 'area', 'req', 'ctx',
+] as const;
+
+/**
+ * A store id as it is minted: the prefix, an underscore, then hex (a stable id: 16 of them) or base36 time and hex (a
+ * new id), at least twelve characters with a digit among them — so `rule_based` or `thread_safety` is no id.
+ */
+const STORE_ID = new RegExp(`(?<![A-Za-z0-9_])(?:${[...STORE_ID_PREFIXES].sort((a, b) => b.length - a.length).join('|')})_(?=[0-9a-z]*[0-9])[0-9a-z]{12,}(?![A-Za-z0-9])`, 'g');
+
+/** `§3`, `§ 一`, `section 2.1`, `第三节`: a section of a document. */
+const SECTION = String.raw`(?:§\s*[0-9一二三四五六七八九十百]+(?:\.[0-9]+)*|[Ss]ection\s+[0-9]+(?:\.[0-9]+)*|第\s*[0-9一二三四五六七八九十百]+\s*[节章])`;
+/** A lane's report or brief, named as such: `路报告`, `路的任务书`, `lane report`, `lane's brief`. */
+const LANE_DOCUMENT = String.raw`(?:路(?:的)?(?:报告|任务书)|[Ll]anes?(?:['’]s)?\s+(?:report|brief))`;
+/** A lane report's or brief's section: the document named as a lane's, then the section within a few characters. */
+const LANE_SECTION = new RegExp(`${LANE_DOCUMENT}[^\\n。；;，,]{0,12}?${SECTION}`, 'g');
+
+const escaped = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** The names of the lanes this project's rounds sent (their briefs and reports are filed under them): internal names. */
+export function laneNamesOf(store: ProjectStore): string[] {
+  const names = new Set<string>();
+  for (const r of store.clerkRounds.all()) {
+    for (const p of r.paths) names.add(p);
+    for (const s of r.sweepsAdded ?? []) names.add(s.path);
+  }
+  for (const d of store.roundDocs.all()) if (d.path) names.add(d.path);
+  return [...names].map((n) => n.trim()).filter((n) => n.length >= 3).sort((a, b) => b.length - a.length);
+}
+
+export interface InternalRef {
+  readonly kind: 'store id' | 'lane report section' | 'lane name';
+  /** The text found, as written. */
+  readonly text: string;
+  /** Which part of the writing holds it: `title`, `preview`, `currentView`, `facts[2]` … */
+  readonly where: string;
+}
+
+/**
+ * The internal identifiers in a piece of writing, part by part. `laneNames` are the names the project's rounds gave
+ * their lanes: one is found where it is used as a lane (`<name> 路`, `the <name> lane`) or as the owner of a report or a
+ * brief (`<name> 报告 §6`), never as an ordinary word of the sentence.
+ */
+export function internalRefs(parts: Readonly<Record<string, string | null | undefined>>, laneNames: readonly string[] = []): InternalRef[] {
+  const found: InternalRef[] = [];
+  const seen = new Set<string>();
+  const add = (kind: InternalRef['kind'], text: string, where: string) => {
+    const key = `${kind}\n${text}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    found.push({ kind, text: text.trim(), where });
+  };
+  const names = laneNames.map(escaped);
+  const edge = String.raw`[A-Za-z0-9_-]`;
+  const laneSection = names.length ? new RegExp(`(?<!${edge})(?:${names.join('|')})(?!${edge})[^\\n。；;，,]{0,10}?(?:报告|任务书|[Rr]eport|[Bb]rief)[^\\n。；;，,]{0,12}?${SECTION}`, 'g') : null;
+  const laneName = names.length ? new RegExp(`(?<!${edge})(?:${names.join('|')})(?!${edge})\\s*(?:路(?![由径线])|\\s(?:lane|sweep)\\b)|\\b(?:lane|sweep)\\s+(?:${names.join('|')})(?!${edge})`, 'g') : null;
+  for (const [where, value] of Object.entries(parts)) {
+    const text = value ?? '';
+    if (!text) continue;
+    for (const m of text.matchAll(STORE_ID)) add('store id', m[0], where);
+    // A section reference found both ways (`路报告 §一`, `generations 路报告 §一`) is said once, by the longer.
+    const all = [LANE_SECTION, laneSection].flatMap((re) => (re ? [...text.matchAll(re)].map((m) => m[0]) : []));
+    const sections = all.filter((s) => !all.some((o) => o !== s && o.includes(s)));
+    for (const s of sections) add('lane report section', s, where);
+    // A lane named inside a section reference is said by that reference.
+    if (laneName) for (const m of text.matchAll(laneName)) if (!sections.some((s) => s.includes(m[0].trim()))) add('lane name', m[0], where);
+  }
+  return found;
+}
+
+const KIND_WORDS: Record<InternalRef['kind'], string> = {
+  'store id': 'a ProjectKeeper store id',
+  'lane report section': 'a section of a lane’s report or brief',
+  'lane name': 'the name of a lane',
+};
+
+/** The found identifiers in one sentence: each as written, with what it is and where. */
+function refsSentence(refs: readonly InternalRef[]): string {
+  const shown = refs.slice(0, 10).map((r) => `“${r.text}” in ${r.where} (${KIND_WORDS[r.kind]})`);
+  return `${shown.join('; ')}${refs.length > 10 ? `; and ${refs.length - 10} more` : ''}`;
+}
+
+/** The first sentence of a text: up to its first sentence mark or line break. A leading `[As far as read — …]` is the program's stamp, not the sentence. */
+export function firstSentence(text: string): string {
+  const bare = text.replace(/^\[As far as read — [^\]]*\]\s*/, '').trim();
+  const m = /^[\s\S]*?(?:[？?！!。]|\.(?=\s|$)|\n|$)/.exec(bare);
+  return (m ? m[0] : bare).trim();
+}
+
+const isQuestion = (sentence: string) => /[?？]$/.test(sentence);
+
+export interface OwnerNoteText {
+  readonly ask: string;
+  readonly title: string;
+  readonly preview: string;
+  /** The rest of the note the owner reads, by part: `currentView`, `facts[0]` … */
+  readonly body: Readonly<Record<string, string | null | undefined>>;
+  readonly options: readonly NoteOption[];
+}
+
+/**
+ * Why a note may not be written in this form, or null: everything wrong with it in one answer, so one retry sets it
+ * right. `how` says how the note is written again (the tool and its id), for the last sentence.
+ */
+export function noteFormRefusal(n: OwnerNoteText, laneNames: readonly string[], how = 'Write it again'): string | null {
+  const problems: string[] = [];
+  const optionParts = Object.fromEntries(n.options.flatMap((o, i) => [[`options[${i}].option`, o.option], [`options[${i}].then`, o.then]]));
+  const refs = internalRefs({ title: n.title, preview: n.preview, ...n.body, ...optionParts }, laneNames);
+  if (refs.length) {
+    problems.push(`It carries ${refs.length === 1 ? 'an internal identifier' : `${refs.length} internal identifiers`}, which the owner cannot read: ${refsSentence(refs)}. Say what each thing is — its name, or the project’s own number (a decision, contract or task number) after saying what that is — and leave these out. The evidence goes in the note’s sources and links, not in its sentences: sourceIds on the facts, the objects it hangs on (mountIds), looked, changeIds, codeAnomalies.`);
+  }
+  if (n.ask === 'For your decision') {
+    const first = firstSentence(n.preview);
+    if (!isQuestion(first)) {
+      problems.push(`A For your decision note opens with the question: the first sentence of preview is what the owner is asked to decide, as one clear question ending in a question mark. This one opens with “${first.length > 140 ? `${first.slice(0, 140)}…` : first}”. Put the question first; what happened and why it comes up now follows in the body, in plain words.`);
+    }
+    const whole = n.options.filter((o) => o.option.trim() && o.then.trim());
+    if (whole.length < 2) {
+      problems.push(`A For your decision note gives the owner the options: at least two in options, one per choice, each with what follows from it (then) — what is changed and where; what happens if it is left alone is an option too. This one gives ${whole.length}${n.options.length > whole.length ? ` (${n.options.length - whole.length} without option or then)` : ''}.`);
+    }
+  }
+  if (problems.length === 0) return null;
+  return `The owner reads this note, and it is not in the form a note is read in. ${problems.join(' ')} ${how}. Nothing was written.`;
+}
+
+/** A decision note's options as lines, one per choice with what follows from it (§4.2): for the places that show a note as text. */
+export function optionsLines(options: readonly NoteOption[] | undefined): string[] {
+  return (options ?? []).map((o) => `- ${o.option} — ${o.then}`);
+}
+
+/**
+ * Why a text written for the owner that is no note — a round's Result — may not be written, or null: it carries
+ * internal identifiers. The reader reaches an object by its name on the workbench; the round's records keep the ids.
+ */
+export function ownerTextRefusal(what: string, parts: Readonly<Record<string, string | null | undefined>>, laneNames: readonly string[]): string | null {
+  const refs = internalRefs(parts, laneNames);
+  if (refs.length === 0) return null;
+  return `${what} is read by the owner, and it carries ${refs.length === 1 ? 'an internal identifier' : `${refs.length} internal identifiers`}: ${refsSentence(refs)}. Name each object by what it is — its title, or the project’s own number — and say what the lanes found without naming a lane or a section of its report: the workbench opens an object from its name, and the round’s own records (the reports, the adoption record, the handover) keep the ids. Write it again without them. Nothing was written.`;
+}

package/src/keeper/project-folder.ts

@@ -0,0 +1,334 @@
+/**
+ * The one owner-authorized folder in a project (Spec §1.14, §1.17; CKC-26 AC-7–AC-11).
+ * The Markdown below is also exported for the workbench, so it need not maintain a second rendition.
+ */
+import { execFileSync } from 'node:child_process';
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, writeFileSync, type Stats } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import type { SemanticPatch, EvidenceRef, Occurred } from '../model/k-types.ts';
+import type { Authorization, Project, ReferenceItem, Source } from '../model/types.ts';
+import { newId } from '../model/ids.ts';
+import { anchorLabel } from '../sources/anchor.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import { git, gitToplevel, LONG_PATHS, type GitResult } from '../util/git.ts';
+import { canonicalPath, gitPathLimit, nameForm } from '../util/paths.ts';
+
+const FILES = ['README.md', 'semantic-patches.md', 'keeper-numbers.md', 'owner-decisions.md'] as const;
+/** The Keeper's commits name it as their author (D89: the Keeper commits the folder itself), so the ledger and `git log`
+ *  tell them from the owner's work; the committer stays the repository's own identity and no configuration is written.
+ *  Where git knows no identity at all (a machine with no `user.name` and `user.email`), the Keeper is the committer too,
+ *  for that one commit, so the commit does not fail. */
+const KEEPER_NAME = 'ProjectKeeper';
+const KEEPER_EMAIL = 'keeper@projectkeeper.invalid';
+export const KEEPER_AUTHOR = `${KEEPER_NAME} <${KEEPER_EMAIL}>`;
+const now = (): string => new Date().toISOString();
+const sortBy = <T>(items: readonly T[], key: (item: T) => string): T[] =>
+  [...items].sort((a, b) => key(a).localeCompare(key(b), 'en'));
+const inline = (value: string): string => value.replace(/\s+/g, ' ').trim();
+const block = (value: string): string => value.trim().replace(/\r\n?/g, '\n') || 'Not recorded';
+
+function statIfPresent(path: string): Stats | null {
+  try { return lstatSync(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function inside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/** Resolve a folder, never a project root, hidden folder, git metadata path or path outside the project's first root. */
+export function projectFolderPath(project: Project, requested = 'projectkeeper'): string {
+  const location = project.locations[0];
+  if (!location) throw new Error('The project has no root location');
+  // The root in the file system's own spelling (short names expanded, links resolved): the one git reports the
+  // repository in, so the folder is found inside it when the commit is made.
+  const root = canonicalPath(location);
+  if (!lstatSync(root).isDirectory()) throw new Error('The project root is not a directory');
+  if (!requested.trim() || requested.includes('\0') || /^[A-Za-z]:[^\\/]/.test(requested) || requested.split(/[\\/]/).some((part) => part === '..' || part === '.')) throw new Error('Invalid project folder path');
+  // Spelled as it will stay: Windows drops a trailing dot or space from a name, so such a name would write somewhere
+  // other than the path shown and granted (QC AW-2). The owner gives the path relative to the root (the grant checks);
+  // the authorization keeps it resolved, and every write checks that resolved path again here.
+  if (requested.split(/[\\/]/).some((part) => /[. ]$/.test(part))) throw new Error('Invalid project folder path: a name ending in a dot or a space is not kept as written');
+  const folder = resolve(root, requested);
+  if (!inside(root, folder)) throw new Error('The project folder must be inside the project root');
+  const parts = relative(root, folder).split(sep);
+  if (parts.some((part) => part.startsWith('.'))) throw new Error('The project folder must not be hidden or inside .git');
+  let cursor = root;
+  for (const part of parts) {
+    const parent = cursor;
+    cursor = join(cursor, part);
+    const stat = statIfPresent(cursor);
+    if (!stat) continue;
+    // An existing name is used exactly as it is on disk: another case or an 8.3 short alias would name the same folder
+    // under a spelling the grant never showed (QC AW-2).
+    // (Asked in the form names are kept in: on a Mac the listing may give the other Unicode form of the same name.)
+    if (!readdirSync(parent).map((name) => nameForm(name)).includes(nameForm(part))) throw new Error(`Invalid project folder path: ${part} names an existing folder spelled differently on disk`);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`Unsafe project folder component: ${cursor}`);
+    if (!inside(root, realpathSync(cursor))) throw new Error(`Project folder escapes through a link: ${cursor}`);
+  }
+  const entries = statIfPresent(folder) ? readdirSync(folder) : [];
+  if (entries.length) {
+    const readme = join(folder, 'README.md');
+    const readmeStat = statIfPresent(readme);
+    if (!readmeStat?.isFile() || readmeStat.isSymbolicLink() || !readFileSync(readme, 'utf8').includes('This folder is maintained by ProjectKeeper')) {
+      throw new Error('The chosen folder already contains project files and is not a ProjectKeeper folder');
+    }
+    if (entries.some((entry) => !(FILES as readonly string[]).includes(entry))) throw new Error('The ProjectKeeper folder contains files outside its managed set');
+  }
+  return folder;
+}
+
+export interface ProjectFolderAuthorizationInput {
+  readonly path?: string;
+  readonly commits?: boolean;
+  readonly quote: string;
+  readonly sourceId?: string;
+}
+
+/** The route supplies an explicit owner statement; no model or project material can create this authorization. */
+export function grantProjectFolderAuthorization(store: ProjectStore, project: Project, input: ProjectFolderAuthorizationInput): Authorization {
+  if (store.projectId !== project.id) throw new Error('The project and asset store do not match');
+  if (!input.quote.trim()) throw new Error('The owner authorization quote is required');
+  // The owner names the folder relative to the project root (QC AW-2): an absolute path, even one inside the project,
+  // is refused rather than silently taken as the same folder.
+  if (input.path !== undefined && isAbsolute(input.path)) throw new Error('Invalid project folder path: give it relative to the project root');
+  if (store.authorizations.find((a) => a.projectFolder != null && !a.revokedAt)) throw new Error('An active Project folder authorization already exists; revoke it before changing the folder');
+  if (input.sourceId) {
+    const source = store.sources.get(input.sourceId);
+    if (!source || source.anchor.kind !== 'session' || source.said?.by === 'agent') throw new Error(`Invalid owner source: ${input.sourceId}`);
+  }
+  const path = projectFolderPath(project, input.path);
+  const commits = input.commits ?? true;
+  const authorization: Authorization = {
+    id: newId('auth'), projectId: project.id,
+    scope: `ProjectKeeper may maintain ${path} and ${commits ? 'make path-limited commits for that folder' : 'leave its changes uncommitted'}; it will not push or edit other project files.`,
+    sourceId: input.sourceId ?? '', quote: input.quote.trim(), at: now(), revokedAt: null,
+    projectFolder: { path, commits, lastWrite: null },
+  };
+  store.authorizations.put(authorization, { jobId: null, basisSourceIds: input.sourceId ? [input.sourceId] : [], summary: 'Owner authorized the ProjectKeeper project folder' });
+  return authorization;
+}
+
+function occurrence(when: Occurred): string {
+  const main = when.undated ? `Undated; first observed ${when.at}` : when.at;
+  // Spec §2.11: a second time the material gives is kept beside the first ("另记"), not judged a conflict.
+  const other = when.other ? `; also recorded ${when.other.at} (${when.other.basis}${when.other.anchor ? `, ${when.other.anchor}` : ''})` : '';
+  return `${main} (${when.basis}${when.anchor ? `, ${when.anchor}` : ''}${other})`;
+}
+
+function evidence(ref: EvidenceRef | null): string {
+  if (!ref) return 'Not recorded';
+  const line = ref.line ? `; original: ${inline(ref.line)}` : '';
+  return `${ref.label} [${ref.kind}: ${ref.id}]${line}`;
+}
+
+function patchEntry(patch: SemanticPatch): string {
+  return [
+    `## ${inline(patch.number)} · ${inline(patch.title)}`,
+    '',
+    `- **Workbench object:** \`${patch.id}\``,
+    `- **Status:** ${patch.status}${patch.partial ? ' · partial (the remainder stays current)' : ''}`,
+    `- **Occurred:** ${occurrence(patch.occurred)}`,
+    `- **Invalidated part:** ${block(patch.invalidated)}`,
+    `- **Replacement:** ${block(patch.replacedBy)}`,
+    `- **Affected objects:** ${patch.affects.length ? sortBy(patch.affects, (id) => id).map((id) => `\`${id}\``).join(', ') : 'None identified'}`,
+    `- **Affected in words:** ${block(patch.affectsText)}`,
+    `- **Must no longer pass as current:** ${block(patch.mustNotPassAsCurrent)}`,
+    `- **Old source:** ${evidence(patch.oldAnchor)}`,
+    `- **New source:** ${evidence(patch.newAnchor)}`,
+    `- **Replacing decision or commit:** ${evidence(patch.decision)}`,
+    `- **Explicit replacement record:** ${evidence(patch.candidate)}`,
+    '',
+  ].join('\n');
+}
+
+function ownerSource(s: Source): boolean {
+  return s.anchor.kind === 'session' && s.said?.by !== 'agent';
+}
+
+function ownerDecisions(store: ProjectStore): { item: ReferenceItem; sessions: Source[]; documents: Source[] }[] {
+  return store.reference.all().filter((item) => item.projectId === store.projectId && item.category === 'Decision').flatMap((item) => {
+    const sources = item.sourceIds.map((id) => store.sources.get(id)).filter((s): s is Source => s !== undefined);
+    const sessions = sources.filter(ownerSource);
+    if (!sessions.length || (item.attribution.author.kind !== 'owner' && !sessions.some((s) => s.said?.by === 'owner'))) return [];
+    const documents = sources.filter((s) => s.anchor.kind === 'file' || s.anchor.kind === 'revision');
+    return [{ item, sessions, documents }];
+  });
+}
+
+function numberProvenance(store: ProjectStore, objectId: string): string {
+  const reference = store.reference.get(objectId);
+  const thread = store.threads.get(objectId);
+  const patch = store.patches.get(objectId);
+  if (patch) return `${evidence(patch.candidate)}; numbered object \`${patch.id}\``;
+  const ids = reference?.sourceIds ?? thread?.inputs?.sourceIds ?? [];
+  const sources = ids.map((id) => store.sources.get(id)).filter((source): source is Source => source !== undefined);
+  return sources.length
+    ? sortBy(sources, (source) => source.id).map((source) => `${anchorLabel(source.anchor)} [source: ${source.id}]`).join('; ')
+    : `Workbench object \`${objectId}\`; the number record has no separate source anchor`;
+}
+
+/** Stable filenames and bytes for both the on-disk folder and its workbench rendering. */
+export function renderProjectFolder(store: ProjectStore, project: Project): Readonly<Record<(typeof FILES)[number], string>> {
+  const patches = sortBy(store.patches.filter((p) => p.projectId === project.id && p.status !== 'Rejected'), (p) => `${p.occurred.at}\0${p.number}\0${p.id}`);
+  const numbers = sortBy(store.numbers.filter((n) => n.projectId === project.id && !(n.objectKind === 'patch' && store.patches.get(n.objectId)?.status === 'Rejected')), (n) => `${n.at}\0${n.number}\0${n.id}`);
+  const decisions = sortBy(ownerDecisions(store), ({ item, sessions }) => `${sessions.map((s) => s.anchor.kind === 'session' ? s.anchor.at ?? '' : '').sort()[0] ?? ''}\0${item.id}`);
+  const patchText = patches.map(patchEntry).join('\n');
+  const numberText = numbers.map((n) => [
+    `## ${inline(n.projectNumber ?? n.number)} · ${inline(n.objectKind)}`,
+    '',
+    `- **Workbench number object:** \`${n.id}\``,
+    `- **Object:** \`${n.objectId}\` (${n.objectKind})`,
+    `- **Keeper number:** \`${n.number}\`${n.projectNumber ? ' (alias)' : ' (current)'}`,
+    `- **Project number:** ${n.projectNumber ? `\`${n.projectNumber}\`` : 'Not assigned'}`,
+    `- **Occurred:** ${n.at}`,
+    `- **Source:** ${numberProvenance(store, n.objectId)}`,
+    '',
+  ].join('\n')).join('\n');
+  const decisionText = decisions.map(({ item, sessions, documents }) => {
+    const first = sortBy(sessions, (s) => `${s.anchor.kind === 'session' ? s.anchor.at ?? '\uffff' : '\uffff'}\0${s.id}`)[0]!;
+    const occurred = first.anchor.kind === 'session' ? first.anchor.at ?? 'Undated in session' : 'Undated in session';
+    const quote = item.quote ?? (first.said?.by === 'owner' ? first.excerpt.slice(first.said.wordsFrom) : null);
+    return [
+      `## ${inline(item.name || item.id)}`,
+      '',
+      `- **Workbench object:** \`${item.id}\``,
+      `- **Validity:** ${item.validity}`,
+      `- **Occurred:** ${occurred}`,
+      `- **Owner's words:** ${quote ? block(quote) : 'Original quote unavailable in this record'}`,
+      `- **Decision as recorded:** ${block(item.text)}`,
+      `- **Session source:** ${sortBy(sessions, (s) => s.id).map((s) => `${anchorLabel(s.anchor)} [source: ${s.id}]`).join('; ')}`,
+      `- **Also documented at:** ${documents.length ? sortBy(documents, (s) => s.id).map((s) => `${anchorLabel(s.anchor)} [source: ${s.id}]`).join('; ') : 'Not yet in a project document'}`,
+      '',
+    ].join('\n');
+  }).join('\n');
+  return {
+    'README.md': `# ProjectKeeper records for ${inline(project.name)}\n\nThis folder is maintained by ProjectKeeper with the project owner's standing authorization. It contains the same identified records shown in the ProjectKeeper workbench; use the object IDs below to open the same entries there. Project documents outside this folder remain owned by the project.\n\n- [Semantic patches](semantic-patches.md): explicit changes to the meaning of project documents.\n- [Keeper numbers](keeper-numbers.md): IDs assigned where the project had none; project IDs take precedence.\n- [Owner decisions from sessions](owner-decisions.md): owner decisions first recorded in conversation, with links to later project documentation when available.\n`,
+    'semantic-patches.md': `# Semantic patches\n\n${patchText || 'No non-rejected semantic patches are recorded.\n'}`,
+    'keeper-numbers.md': `# Keeper numbers\n\n${numberText || 'No Keeper numbers are recorded.\n'}`,
+    'owner-decisions.md': `# Owner decisions from sessions\n\n${decisionText || 'No owner decisions with a session source are recorded.\n'}`,
+  };
+}
+
+export interface ProjectFolderSyncResult {
+  readonly status: 'not-authorized' | 'unchanged' | 'written';
+  readonly path: string | null;
+  readonly changedFiles: readonly string[];
+  readonly commit: string | null;
+  readonly reason: string | null;
+}
+
+/** Unlike util/git.ts, these two operations must take git's index lock and write a commit. */
+/**
+ * The project's own git hooks never run for the Keeper's commits (QC AW-2): a pre-commit or commit-msg hook can change
+ * files outside the folder, and a post-commit hook can push, which would break "only this folder, never pushed" (D89).
+ * `--no-verify` is not enough (prepare-commit-msg and post-commit still run), so each write points `core.hooksPath` at
+ * an empty directory of its own, for that one command; the repository's configuration is never written.
+ */
+let noHooksDir: string | null = null;
+const noHooks = (): string => (noHooksDir ??= mkdtempSync(join(tmpdir(), 'pk-no-hooks-')));
+
+function gitWrite(cwd: string, args: readonly string[], env: NodeJS.ProcessEnv = {}): GitResult {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      const out = execFileSync('git', ['--no-pager', '-c', 'core.fsmonitor=false', '-c', `core.hooksPath=${noHooks()}`, ...LONG_PATHS, '-C', cwd, ...args], {
+        encoding: 'utf8', env: { ...process.env, GIT_OPTIONAL_LOCKS: '1', GIT_TERMINAL_PROMPT: '0', ...env },
+        timeout: 20_000, maxBuffer: 16_000_000, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      return { ok: true, out, err: '' };
+    } catch (error) {
+      const e = error as { stdout?: string; stderr?: string; message?: string };
+      const result = { ok: false, out: e.stdout ?? '', err: (e.stderr || e.message || String(error)).trim() };
+      if (!/index\.lock/i.test(result.err) || attempt === 3) return result;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 150 * (attempt + 1));
+    }
+  }
+  return { ok: false, out: '', err: 'Git write retry exhausted' };
+}
+
+/** The committer of the Keeper's commit: the repository's own identity when git has one (nothing is passed), the Keeper otherwise. */
+function committerEnv(repo: string): NodeJS.ProcessEnv {
+  return git(repo, ['var', 'GIT_COMMITTER_IDENT']).ok ? {} : { GIT_COMMITTER_NAME: KEEPER_NAME, GIT_COMMITTER_EMAIL: KEEPER_EMAIL };
+}
+
+function recordIssue(store: ProjectStore, authorizationId: string, message: string): void {
+  store.trace({ collection: 'authorizations', id: authorizationId, op: 'put', jobId: null, summary: `Project folder sync: ${message}` });
+}
+
+/** Write only the four managed files, then optionally make a commit whose pathspec is only this folder. */
+export function syncProjectFolder(store: ProjectStore, project: Project): ProjectFolderSyncResult {
+  const authorization = sortBy(store.authorizations.filter((a) => a.projectFolder != null && !a.revokedAt), (a) => a.at).at(-1);
+  if (!authorization?.projectFolder) return { status: 'not-authorized', path: null, changedFiles: [], commit: null, reason: null };
+  const folder = projectFolderPath(project, authorization.projectFolder.path);
+  const rendered = renderProjectFolder(store, project);
+  const root = canonicalPath(project.locations[0]!);
+  if (!inside(root, folder)) throw new Error('Project folder escaped the project root');
+  mkdirSync(folder, { recursive: true });
+  if (!inside(root, realpathSync(folder))) throw new Error('Project folder escaped through a link');
+  const changedFiles: string[] = [];
+  for (const name of FILES) {
+    const target = join(folder, name);
+    const stat = statIfPresent(target);
+    if (stat && (stat.isSymbolicLink() || !stat.isFile())) throw new Error(`Unsafe project folder file: ${target}`);
+    if (stat && readFileSync(target, 'utf8') === rendered[name]) continue;
+    writeFileSync(target, rendered[name], 'utf8');
+    changedFiles.push(name);
+  }
+
+  let commit: string | null = null;
+  let reason: string | null = null;
+  if (authorization.projectFolder.commits) {
+    const repo = gitToplevel(root);
+    // A repository git cannot open because its path is too long is not "no repository": the reason says which it is.
+    const tooLong = repo ? null : gitPathLimit(root);
+    if (tooLong) reason = `The project folder's files were written without a commit. ${tooLong}`;
+    else if (!repo || !inside(repo, folder)) reason = 'The project folder is not in a git repository; files were written without a commit.';
+    else {
+      const pathspec = relative(repo, folder).split(sep).join('/');
+      const status = git(repo, ['status', '--porcelain', '--untracked-files=all', '--', pathspec]);
+      if (!status.ok) reason = `Could not inspect git status: ${status.err}`;
+      else if (!status.out.trim() && changedFiles.length) reason = 'Git did not see the written files; the folder may be ignored.';
+      else if (status.out.trim()) {
+        const added = gitWrite(repo, ['add', '--', pathspec]);
+        if (!added.ok) reason = `Git add failed: ${added.err}`;
+        else {
+          const staged = git(repo, ['diff', '--cached', '--name-only', '--', pathspec]);
+          if (!staged.ok) reason = `Could not inspect staged folder changes: ${staged.err}`;
+          else if (staged.out.trim()) {
+            const summary = changedFiles.length ? changedFiles.join(', ') : staged.out.trim().split(/\r?\n/).map((path) => basename(path)).join(', ');
+            const committed = gitWrite(repo, ['commit', `--author=${KEEPER_AUTHOR}`, '-m', `ProjectKeeper: update ${summary}`, '--', pathspec], committerEnv(repo));
+            if (!committed.ok) reason = `Git commit failed: ${committed.err}`;
+            else {
+              const head = git(repo, ['rev-parse', 'HEAD']);
+              commit = head.ok ? head.out.trim() : null;
+              if (!commit) reason = `Commit succeeded but its hash could not be read: ${head.err}`;
+            }
+          }
+        }
+      }
+    }
+  }
+  if (reason) recordIssue(store, authorization.id, reason);
+  if (changedFiles.length || commit) {
+    const at = changedFiles.length ? now() : authorization.projectFolder.lastWrite?.at ?? now();
+    store.authorizations.put({ ...authorization, projectFolder: { ...authorization.projectFolder, lastWrite: { at, commit } } }, {
+      jobId: null, summary: `ProjectKeeper project folder ${changedFiles.length ? 'written' : 'committed'}${commit ? ` at ${commit}` : ''}`,
+    });
+    for (const patch of store.patches.filter((p) => p.projectId === project.id && p.status !== 'Rejected')) {
+      if (patch.writtenToFolder?.path === folder && patch.writtenToFolder.commit === commit && !changedFiles.length) continue;
+      store.patches.put({ ...patch, writtenToFolder: { path: folder, commit, at } });
+    }
+  }
+  for (const patch of store.patches.filter((p) => p.projectId === project.id && p.status === 'Rejected' && p.writtenToFolder?.path === folder)) {
+    store.patches.put({ ...patch, writtenToFolder: null });
+  }
+  return {
+    status: changedFiles.length || commit ? 'written' : 'unchanged', path: folder, changedFiles, commit,
+    reason,
+  };
+}