projectkeeper 0.0.0-stage → 1.0.0

package/src/keeper/organize/skills.ts

@@ -0,0 +1,116 @@
+/**
+ * The clerk method's skills (D99; Spec §3.3 "每个阶段一份 skill"): the method is given to the Keeper's agent as one pi
+ * SKILL.md per stage of the main agent, per kind of lane, one for the synthesis (D103: a job of its own, whose prompt
+ * starts with it) and one for the independent spot-check — not as tasks the program cuts. They live in the install's `skills/clerk/<name>/SKILL.md`, in pi's format (frontmatter `name` and
+ * `description`), and reach an agent two ways (E148 D-b): pi loads the folder natively for the clerk round's jobs
+ * (runtime.ts `additionalSkillPaths`) and lists them in its system prompt, and the text itself is put in front of the
+ * agent — `pk_stage` returns the stage's skill, and a lane's prompt starts with its lane's skill — since GLM does not
+ * always open a skill file by itself.
+ *
+ * The folder is resolved from the running install, relative to this module's own file, never from the project's
+ * working directory: ProjectKeeper's own skills folder is also project material when the Keeper organizes its own
+ * repository, and the resident install is a separate checkout (build plan §4 "自指"). Reads of this folder are left out of what a
+ * round counts as read (`isClerkSkillPath`).
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { isAbsolute, join } from 'node:path';
+import { stripFrontmatter } from '@earendil-works/pi-coding-agent';
+import type { ClerkStage, LaneKind } from '../../model/k-types.ts';
+import { isWithin, normalizePath } from '../../util/paths.ts';
+
+/** The skill of each stage of the main agent's session (D103: the synthesis is no stage of it; `SYNTHESIS_SKILL`). */
+export const STAGE_SKILLS: Readonly<Record<Exclude<ClerkStage, 'synthesis'>, string>> = {
+  orientation: 'orientation',
+  skeleton: 'skeleton-dispatch',
+  reconcile: 'reconcile',
+  dig: 'deepen-dispatch',
+  coverage: 'coverage',
+  'cross-check': 'cross-check',
+};
+
+/** The synthesis' skill (D103): the head of the synthesis job's prompt. */
+export const SYNTHESIS_SKILL = 'synthesis';
+
+/** The skill of each kind of lane. */
+export const LANE_SKILLS: Readonly<Record<LaneKind, string>> = {
+  slot: 'lane-slot',
+  plan: 'lane-plan',
+  topic: 'lane-topic',
+  'follow-up': 'lane-follow-up',
+};
+
+/** The independent spot-check's skill. */
+export const SPOT_CHECK_SKILL = 'spot-check';
+
+/** Every clerk skill, by folder name. */
+export const CLERK_SKILL_NAMES: readonly string[] = [...Object.values(STAGE_SKILLS), SYNTHESIS_SKILL, ...Object.values(LANE_SKILLS), SPOT_CHECK_SKILL];
+
+/** The folder of the clerk method's skills in the running install (`<install>/skills/clerk`). */
+export function clerkSkillsDir(): string {
+  return normalizePath(fileURLToPath(new URL('../../../skills/clerk/', import.meta.url)));
+}
+
+/** The SKILL.md of one clerk skill in the running install. */
+export function clerkSkillFile(name: string): string {
+  return join(clerkSkillsDir(), name, 'SKILL.md');
+}
+
+const bodies = new Map<string, string>();
+
+/** A skill's body, without its frontmatter. Read once per process: the install does not change under a running Keeper. */
+function skillBody(name: string): string {
+  let body = bodies.get(name);
+  if (body === undefined) {
+    const file = clerkSkillFile(name);
+    let raw: string;
+    try { raw = readFileSync(file, 'utf8'); } catch (e) { throw new Error(`the clerk skill "${name}" is missing from the install (${file}): ${(e as Error).message}`); }
+    body = stripFrontmatter(raw).trim();
+    bodies.set(name, body);
+  }
+  return body;
+}
+
+/** The skill of a stage of the main agent's session, without frontmatter (what `pk_stage` returns). */
+export function stageSkill(stage: ClerkStage): string {
+  const name = (STAGE_SKILLS as Readonly<Record<string, string>>)[stage];
+  if (!name) throw new Error(`no clerk skill for the stage "${stage}"`);
+  return skillBody(name);
+}
+
+/** The synthesis' skill, without frontmatter (the head of the synthesis job's prompt, D103). */
+export function synthesisSkill(): string {
+  return skillBody(SYNTHESIS_SKILL);
+}
+
+/** The skill of a kind of lane, without frontmatter (the head of a lane's prompt). */
+export function laneSkill(kind: LaneKind): string {
+  const name = LANE_SKILLS[kind];
+  if (!name) throw new Error(`no clerk skill for the lane kind "${kind}"`);
+  return skillBody(name);
+}
+
+/** The independent spot-check's skill, without frontmatter. */
+export function spotCheckSkill(): string {
+  return skillBody(SPOT_CHECK_SKILL);
+}
+
+/** The job kinds of a clerk round that pi loads the clerk skills for (D99, D103): the main agent, its lanes, the synthesis, the spot-check. */
+export const SKILLED_STEP_KINDS: ReadonlySet<string> = new Set(['main', 'lane', 'synthesis', 'spot-check']);
+
+/** The extra skill paths pi's resource loader gets for a job: the clerk skills folder for a clerk round's jobs, else none. */
+export function clerkSkillPathsFor(stepKind: string | null | undefined): string[] {
+  return stepKind && SKILLED_STEP_KINDS.has(stepKind) ? [clerkSkillsDir()] : [];
+}
+
+/**
+ * Whether a path is in the install's clerk skills folder — an agent reading its own method, not the project's material,
+ * so a round's read tally and coverage leave it out (W5, W8). A relative path is taken against `cwd` when given, else
+ * it is not the skills folder (the install is never addressed relative to a project).
+ */
+export function isClerkSkillPath(path: string, cwd?: string): boolean {
+  const p = path.trim();
+  if (!p) return false;
+  if (!isAbsolute(p) && !cwd) return false;
+  try { return isWithin(clerkSkillsDir(), isAbsolute(p) ? p : join(cwd!, p)); } catch { return false; }
+}

package/src/keeper/organize/slots.ts

@@ -0,0 +1,85 @@
+/**
+ * The workbench's slots, and the ones no lane holds (DB; Spec §3.3 "工作台是一道填空题").
+ *
+ * The program knows the slots and which lane holds which. When a first usable round's skeleton lanes are sent
+ * (`pk_send_lanes`, lane-tools.ts), a slot no lane holds is listed back before anything is sent: the main agent gives it
+ * to a lane, or says in one line why the project has nothing for it. The reason is kept on the round (`emptySlots`) and
+ * shown to the next spot-check; the program refuses nothing more and does not judge the reason. On the DeepSeek run
+ * (2026-10-04) no lane was given the Boundary slot, and the workbench held no boundary although the PRD had a section on
+ * what the product does not include — the two runs before it held 18 and 34.
+ */
+import type { ClerkRound, EmptySlot, SlotKind } from '../../model/k-types.ts';
+import type { ProjectStore } from '../../store/project-store.ts';
+import { REFERENCE_CATEGORY } from '../../model/vocab.ts';
+
+/** What each reference category holds, in words a main agent can match against the project's documents. */
+const REFERENCE_HOLDS: Readonly<Record<(typeof REFERENCE_CATEGORY)[number], string>> = {
+  "Owner's words": 'the owner’s own lines, verbatim',
+  Product: 'what the product is',
+  Goal: 'the goals the product serves',
+  Area: 'the modules or areas of the product',
+  Requirement: 'the requirements: what the product must do',
+  Design: 'the designs: how it is built, section by section',
+  Decision: 'the decisions and their records',
+  Plan: 'the plans: increments, phases, batches, milestones',
+  Boundary: 'what the product does not include: non-goals, out of scope, limits it states',
+};
+
+/**
+ * The slots a first usable round's skeleton fills by lane, each with what it holds: every reference category, the work
+ * items, their process links, the code territories, the earlier generations. `patches` and `relations` are not among
+ * them: reconcile drafts the supersession lines no lane drafted, and relations tie the items of the other slots — neither
+ * is a position left empty because no lane held it.
+ */
+export const SKELETON_SLOTS: readonly { readonly slot: SlotKind; readonly holds: string }[] = [
+  ...REFERENCE_CATEGORY.map((c) => ({ slot: `reference:${c}` as SlotKind, holds: REFERENCE_HOLDS[c] })),
+  { slot: 'threads', holds: 'the work items: contracts, tickets, tasks, issues' },
+  { slot: 'links', holds: 'what ties work to its delivery: dispatches, deliveries, merges, checks' },
+  { slot: 'territories', holds: 'the code as it stands, by area' },
+  { slot: 'generations', holds: 'earlier generations of the plan: archived or superseded plan, contract and module sets' },
+];
+
+/** A slot as it is compared: the apostrophe as typed, any case. */
+export const slotKey = (s: string): string => s.replace(/[’‘`]/g, "'").trim().toLowerCase();
+
+/** The skeleton's slot a name stands for, or undefined. */
+export const skeletonSlot = (name: string) => SKELETON_SLOTS.find((s) => slotKey(s.slot) === slotKey(name));
+
+/** The slots of the skeleton that neither a lane holds nor a recorded reason accounts for. */
+export function slotsUnheld(held: readonly string[], reasons: readonly Pick<EmptySlot, 'slot'>[]): { readonly slot: SlotKind; readonly holds: string }[] {
+  const taken = new Set([...held, ...reasons.map((r) => r.slot)].map(slotKey));
+  return SKELETON_SLOTS.filter((s) => !taken.has(slotKey(s.slot)));
+}
+
+/** Whether the workbench holds anything in a slot now. */
+export function slotHolds(store: ProjectStore, slot: string): boolean {
+  const key = slotKey(slot);
+  if (key.startsWith('reference:')) return store.reference.find((r) => `reference:${r.category}`.toLowerCase() === key && r.validity !== 'Removed') !== undefined;
+  if (key === 'threads') return store.threads.size > 0;
+  if (key === 'links') return store.links.size > 0;
+  if (key === 'territories') return store.territories.size > 0;
+  if (key === 'generations') return store.generations.size > 0;
+  return true;
+}
+
+/** Every recorded reason of the project, oldest round first, each with its round and whether the slot holds anything now. */
+export function emptySlotsOf(store: ProjectStore): (EmptySlot & { readonly round: string; readonly holdsNow: boolean })[] {
+  return store.clerkRounds.all().sort((a, b) => a.startedAt.localeCompare(b.startedAt))
+    .flatMap((r) => (r.emptySlots ?? []).map((e) => ({ ...e, round: `${r.kind} round ${r.number}`, holdsNow: slotHolds(store, e.slot) })));
+}
+
+/**
+ * What a round's spot-check is shown of the slots left to no lane: the reasons recorded since the last spot-check of an
+ * earlier round began, whichever round recorded them — a first usable round has no spot-check of its own — for the slots
+ * that still hold nothing. Null when there is none.
+ */
+export function emptySlotsBlock(store: ProjectStore, round: Pick<ClerkRound, 'id'>): string | null {
+  const lastCheck = store.jobs.filter((j) => j.step?.kind === 'spot-check' && j.step.roundId !== round.id).map((j) => j.queuedAt).sort().at(-1) ?? '';
+  const standing = emptySlotsOf(store).filter((e) => e.at > lastCheck && !e.holdsNow);
+  if (!standing.length) return null;
+  return [
+    `=== Slots no lane held (${standing.length}; the main agent’s reasons, which the program does not check)`,
+    'The skeleton gave these workbench slots to no lane, and the main agent said why the project has nothing for them; the workbench still holds nothing there. Check each reason against the project’s documents: a section or a table that states such material makes it wrong. Say in your Spot check document which reasons hold and which do not, each wrong one with where the material is (path and line), so the next round gives that slot to a lane.',
+    ...standing.map((e) => `- ${e.slot} (${skeletonSlot(e.slot)?.holds ?? 'a workbench slot'}) · ${e.round}: “${e.why}”`),
+  ].join('\n');
+}

package/src/keeper/organize/stage-gate.ts

@@ -0,0 +1,175 @@
+/**
+ * What the main agent and its lanes may write, decided at call time by the job's effective stage (D99; E148 D-a).
+ *
+ * pi cannot change a session's tools halfway through, so the main job is offered every stage's writers at once
+ * (`STAGE_WRITERS`, clerk-steps.ts) and each writer refuses outside the stages that list it: the main job's effective
+ * stage is the stage its round is in (`ClerkRound.stage`). A lane is offered the writers of the slots it was given
+ * (`SLOT_WRITERS`) and its Report; its effective stage is `lane`, and `reference:<category>` is checked by category too.
+ * So one matter is still written once, by the one that owns it (Spec §3.3 "谁写什么"), without new sessions per stage.
+ *
+ * D103: once the main agent has handed the round over to the synthesis (`handedOver`), its session writes nothing more;
+ * the synthesis job writes by its own step's table (roles.ts `STEP_WRITES.synthesis`), not by a stage.
+ */
+import type { ClerkRound, ClerkStage, RoundDocKind, RoundStepKind, SlotKind } from '../../model/k-types.ts';
+import type { KeeperJob } from '../../model/types.ts';
+import type { ProjectStore } from '../../store/project-store.ts';
+import { DOCS_BY_STAGE, LANE_ALWAYS, LANE_DOCS, MAIN_ALWAYS, ROUND_STAGES, SLOT_WRITERS, STAGE_WRITERS } from '../clerk-steps.ts';
+
+type Step = NonNullable<KeeperJob['step']>;
+
+/**
+ * The judgements only a Follow up round's cross-check makes (Spec §5.5; roles.ts `FOLLOW_UP_WRITES`): the main agent of a
+ * Follow up round is offered them and writes them in its cross-check stage.
+ */
+export const MAIN_FOLLOW_UP_WRITES: readonly string[] = ['pk_write_change', 'pk_judge_object', 'pk_set_propagation', 'pk_set_propagations', 'pk_write_modification_request', 'pk_mark_request_handled', 'pk_round_pending'];
+
+/** The stage the main agent is in: the round's, or its first stage before it has moved (a round started before it said). */
+export function stageOfRound(round: Pick<ClerkRound, 'kind' | 'stage'>): ClerkStage {
+  return round.stage ?? ROUND_STAGES[round.kind][0]!;
+}
+
+/**
+ * Whether the main agent handed the round over to the synthesis (D103): its handover is recorded — or, on a round
+ * recorded before D103, it had moved into the synthesis stage, which the synthesis job now holds.
+ */
+export function handedOver(round: Pick<ClerkRound, 'stage' | 'handover'>): boolean {
+  return !!round.handover || round.stage === 'synthesis';
+}
+
+/** The main agent's last stage in a round of this kind: the one it hands over from. */
+export function lastStageOf(kind: ClerkRound['kind']): ClerkStage {
+  const order = ROUND_STAGES[kind];
+  return order[order.length - 1]!;
+}
+
+const HANDED_OVER = `the main agent handed this round over to the synthesis, which runs in a session of its own: the main agent's work is done, and its session writes nothing more`;
+
+export type EffectiveStage =
+  | { readonly kind: 'main'; readonly stage: ClerkStage; readonly round: ClerkRound }
+  | { readonly kind: 'lane'; readonly name: string; readonly slots: readonly SlotKind[]; readonly round: ClerkRound | null };
+
+/** Who a job writes as (D99): the main job in its round's stage, a lane with its slots; null for any other job. */
+export function effectiveStage(store: ProjectStore, step: Step | null | undefined): EffectiveStage | null {
+  if (!step) return null;
+  const round = store.clerkRounds.get(step.roundId) ?? null;
+  if (step.kind === 'main') return round ? { kind: 'main', stage: stageOfRound(round), round } : null;
+  if (step.kind === 'lane') return { kind: 'lane', name: step.path ?? '', slots: step.lane?.slots ?? [], round };
+  return null;
+}
+
+/**
+ * The step kind whose rules a stage-dependent writer applies (a patch is a draft before the cross-check, a link is
+ * confirmed and a send-back limited in the cross-check): the main job's stage by the step it replaces, `lane` for a lane,
+ * the job's own step kind otherwise.
+ */
+export function stepKindAs(store: ProjectStore, step: Step | null | undefined): RoundStepKind | 'lane' | null {
+  if (!step) return null;
+  const eff = effectiveStage(store, step);
+  if (!eff) return step.kind;
+  if (eff.kind === 'lane') return 'lane';
+  const as: Readonly<Record<ClerkStage, RoundStepKind>> = { orientation: 'orientation', skeleton: 'skeleton', reconcile: 'skeleton', dig: 'dig', coverage: 'dig', 'cross-check': 'cross-check', synthesis: 'synthesis' };
+  return as[eff.stage];
+}
+
+const either = (list: readonly string[]): string => (list.length <= 1 ? list.join('') : `${list.slice(0, -1).join(', ')} or ${list[list.length - 1]}`);
+const slotBase = (slot: string): string => (slot.startsWith('reference:') ? 'reference' : slot.split(':')[0]!);
+const text = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+/** The stages whose writers list a tool. */
+export function stagesWriting(tool: string): ClerkStage[] {
+  return (Object.keys(STAGE_WRITERS) as ClerkStage[]).filter((s) => STAGE_WRITERS[s].includes(tool));
+}
+
+/** The slot kinds whose writers list a tool (`reference` standing for every `reference:<category>`). */
+export function slotsWriting(tool: string): string[] {
+  return Object.entries(SLOT_WRITERS).filter(([, tools]) => tools.includes(tool)).map(([slot]) => (slot === 'reference' ? 'reference:<category>' : slot));
+}
+
+/** The reference category a call writes, when it writes reference items: given, or the one of the item it updates. */
+function referenceCategory(store: ProjectStore, tool: string, args: Record<string, unknown> | null): { readonly writes: 'reference' | 'threads' | null; readonly category: string | null } {
+  if (!args) return { writes: null, category: null };
+  if (tool === 'pk_write_reference') {
+    const given = text(args.category);
+    const id = text(args.id);
+    return { writes: 'reference', category: given || (id ? store.reference.get(id)?.category ?? null : null) };
+  }
+  // DA: judging the owner's lines is the Owner's words slot's, like the items it writes.
+  if (tool === 'pk_judge_owner_lines') return { writes: 'reference', category: "Owner's words" };
+  if (tool === 'pk_fill_from_table') return text(args.into) === 'threads' ? { writes: 'threads', category: null } : { writes: 'reference', category: text(args.category) || null };
+  if (tool === 'pk_fill_from_headings' || tool === 'pk_fill_from_bold') return { writes: 'reference', category: text(args.category) || null };
+  return { writes: null, category: null };
+}
+
+/**
+ * Why the main job or a lane may not make this call now, or null (D99): the main job writes only what its stage lists (and
+ * in a Follow up's cross-check the round's judgements), a lane only what its slots and every lane may write. Any other job
+ * is not decided here.
+ */
+export function writeRefusal(store: ProjectStore, step: Step | null | undefined, tool: string, args: Record<string, unknown> | null = null): string | null {
+  const eff = effectiveStage(store, step);
+  if (!eff) return null;
+  if (eff.kind === 'main') {
+    if ((MAIN_ALWAYS as readonly string[]).includes(tool)) return null;
+    if (handedOver(eff.round)) return `${tool}: ${HANDED_OVER}. Nothing was written. End with a short summary of what you handed over.`;
+    if (STAGE_WRITERS[eff.stage].includes(tool)) return null;
+    if (eff.round.kind === 'Follow up' && MAIN_FOLLOW_UP_WRITES.includes(tool)) {
+      return eff.stage === 'cross-check' ? null : `${tool} judges into the Follow up round's record, which the main agent does in its cross-check stage; you are in the ${eff.stage} stage, so nothing was written.`;
+    }
+    const stages = stagesWriting(tool);
+    if (stages.length) return `${tool} is written in the ${either(stages)} stage of the main agent's session (each stage writes its own positions); this round is in the ${eff.stage} stage, so nothing was written. Move to that stage with pk_stage when this one is done, or give the write to a lane whose slot it is.`;
+    const slots = slotsWriting(tool);
+    return `${tool} is not the main agent's to write in any stage${slots.length ? `: a lane with the slot ${either(slots)} writes it (send one with pk_send_lanes)` : ''}, so nothing was written.`;
+  }
+  if ((LANE_ALWAYS as readonly string[]).includes(tool)) return null;
+  const own = eff.slots.filter((s) => (SLOT_WRITERS[slotBase(s) as keyof typeof SLOT_WRITERS] ?? []).includes(tool));
+  const given = eff.slots.length ? eff.slots.join(', ') : 'none';
+  if (!own.length) {
+    const slots = slotsWriting(tool);
+    return `${tool} writes ${slots.length ? `the slot ${either(slots)}` : 'a position no lane writes'}; this lane (${eff.name}) writes ${given} (a lane writes only the slots its brief gives it), so nothing was written. Put what you found in your Report for the main agent.`;
+  }
+  const ref = referenceCategory(store, tool, args);
+  if (ref.writes === 'threads') return eff.slots.includes('threads') ? null : `${tool} into threads writes work items, the slot threads; this lane (${eff.name}) writes ${given}, so nothing was written.`;
+  if (ref.writes === 'reference') {
+    if (!ref.category) return `${tool} writes reference items, and a lane writes those only in the categories its slots name (reference:<category>): give the category. Nothing was written.`;
+    const want = `reference:${ref.category}`.toLowerCase();
+    if (eff.slots.some((s) => s.toLowerCase() === want)) return null;
+    const cats = eff.slots.filter((s) => s.startsWith('reference:'));
+    return `${tool} would write a ${ref.category} reference item, the slot reference:${ref.category}; this lane (${eff.name}) writes ${cats.length ? cats.join(', ') : 'no reference category'}, so nothing was written. Put it in your Report for the main agent.`;
+  }
+  return null;
+}
+
+/** Why the main job or a lane may not write a round document of this kind now, or null (D99; `DOCS_BY_STAGE`, `LANE_DOCS`). */
+export function roundDocRefusal(store: ProjectStore, step: Step | null | undefined, kind: RoundDocKind): string | null {
+  const eff = effectiveStage(store, step);
+  if (!eff) return null;
+  if (eff.kind === 'lane') return LANE_DOCS.includes(kind) ? null : `A lane writes its own ${either([...LANE_DOCS])}; a ${kind} is the main agent's. Nothing was written.`;
+  if (handedOver(eff.round)) return `A ${kind}: ${HANDED_OVER}. Nothing was written.`;
+  if (kind === 'Handover') return `The handover is written as you hand the round over: pk_stage({ to: "synthesis", handover: { settled, open, first } }) once the ${lastStageOf(eff.round.kind)} stage is done. Nothing was written.`;
+  const allowed = DOCS_BY_STAGE[eff.stage];
+  if (allowed.includes(kind)) return null;
+  const stages = (Object.keys(DOCS_BY_STAGE) as ClerkStage[]).filter((s) => DOCS_BY_STAGE[s].includes(kind));
+  const where = stages.length ? `in the ${either(stages)} stage` : LANE_DOCS.includes(kind) ? 'by a lane, as its own report' : kind === 'Result' ? 'by the synthesis, in a session of its own' : 'by the spot-check';
+  return `In the ${eff.stage} stage the main agent writes ${allowed.length ? either([...allowed]) : 'no round document'}; a ${kind} is written ${where}. Nothing was written.`;
+}
+
+type Result = { content: { type: 'text'; text: string }[]; details: Record<string, never>; isError?: boolean };
+type Executable = { readonly name: string; execute?: (...args: never[]) => unknown };
+
+/**
+ * The same tool, refusing at call time what `refusal` refuses (the main job's stage, a lane's slots). The refusal comes
+ * back the way a writer's own refusal does, so the model reads it as a refused call and nothing is written.
+ */
+export function gatedTool<T extends Executable>(tool: T, refusal: (tool: string, args: Record<string, unknown> | null) => string | null): T {
+  const run = tool.execute as ((...args: unknown[]) => Promise<unknown>) | undefined;
+  if (typeof run !== 'function') return tool;
+  return {
+    ...tool,
+    execute: async (...args: unknown[]) => {
+      const params = args[1] && typeof args[1] === 'object' ? args[1] as Record<string, unknown> : null;
+      const why = refusal(tool.name, params);
+      if (why) return { content: [{ type: 'text', text: `ERROR: ${why}` }], details: {}, isError: true } satisfies Result;
+      return run.apply(tool, args);
+    },
+  } as T;
+}