projectkeeper 0.0.0-stage → 1.0.0

package/src/keeper/capabilities.ts

@@ -0,0 +1,136 @@
+/**
+ * The Keeper agent's capability table (Spec §8.1, §8.3; CKC-03 AC-1, AC-14, AC-25–AC-31), shown in `Keeper` → `Keeper
+ * agent`. It says what the program on this build does, not what is planned: each row names what provides it — pi as it
+ * comes, a ProjectKeeper tool, the ledger, the TypeScript language service, or ProjectKeeper's own adapter around pi — and a
+ * row that is not available says which steps that affects. Nothing here is claimed that pi does not have: what
+ * ProjectKeeper adds says so in `provider` and `source`, and `native` says what `Open in pi` (the pi installed on the
+ * machine, without ProjectKeeper's tools or patch) has of it.
+ */
+import { LEFT_NOTE } from './bounds/shell-write-guard.ts';
+
+export type CapabilityProvider = 'pi built-in' | 'ProjectKeeper tool' | 'The ledger' | 'TypeScript language service' | 'ProjectKeeper adapter' | 'Not provided';
+
+export interface Capability {
+  readonly name: string;
+  /** Where it is used in the workbench, and by which steps. */
+  readonly workbench: string;
+  /** What native pi (`Open in pi`) has of it. */
+  readonly native: string;
+  readonly available: boolean;
+  /** What provides it, in one of the fixed words (CKC-03 AC-31). */
+  readonly provider: CapabilityProvider;
+  /** How it is provided, in a sentence; the table shows it after the name. */
+  readonly source: string;
+  /** For a row that is not available: which steps that affects, and how. */
+  readonly affects: string | null;
+}
+
+/** The model jobs of a round as D99 runs it (clerk.ts `ROUND_STEPS`), as the table names them. */
+const EVERY_STEP = 'every job — each job of a round (the session drafts, the main agent through its stages, each lane it sends, the synthesis, the spot-check), investigations, answers, requests and re-looks';
+
+export const PI_CAPABILITIES: readonly Capability[] = [
+  // ── pi as it comes (Spec §8.1's first table) ──
+  { name: 'Conversation: streaming output, tool calls', workbench: 'Keeper conversation', native: 'Native', available: true, provider: 'pi built-in', source: 'pi, as it comes', affects: null },
+  {
+    name: 'Built-in tools: read, write, edit, bash (and PowerShell on Windows), grep, find, ls',
+    workbench: `All on in ${EVERY_STEP}; none removed. Autonomous work that changes project content is shown in the Keeper view`,
+    native: 'Native; grep, find and ls are off in pi\'s own defaults',
+    available: true, provider: 'pi built-in',
+    source: 'pi\'s own tools, all turned on for every job (settings defaultTools). ProjectKeeper\'s adapter keeps them inside the project: a read boundary on read, grep, find, ls and edit, shell commands checked before they run and their changes to the project undone as the shell row says, shell without credential variables',
+    affects: null,
+  },
+  {
+    name: 'Shell commands on the project: what the boundary refuses, and what it undoes on a live project and on a controlled trial',
+    workbench: `Every shell command in ${EVERY_STEP}. A refused command, and one whose changes were undone, is a step marked as an error with the reason and the paths; when something changed while a command ran, not by it, the step's result starts with “${LEFT_NOTE}” and the paths it left`,
+    native: 'Not in native pi: Open in pi runs shell commands as they are given',
+    available: true, provider: 'ProjectKeeper adapter',
+    source: 'ProjectKeeper\'s shell boundary. Refused before a command runs: reading outside the project; a path that cannot be worked out beforehand (a variable, a command substitution, eval, code piped into an interpreter); redirecting into the project, and writing into it with tee, cp, mv, rm, touch, mkdir, rmdir, truncate or sed -i, projectkeeper/ included; git commands that change the repository; Git-ignored and Excluded paths. '
+      + 'Undone after it runs, on a live project (a home that watches its projects, where the owner and agents write at the same time): only what the command itself names as its writes — its redirection targets, the value of an output option (--output, sort -o …), the operands of the commands above — and every other change is left as it is and named on the step, including one the command made through a program or a script, which cannot be told from another writer\'s. '
+      + 'On a controlled trial (settings.watchProjects false: nobody else writes there): every change to the working tree that git status or the directory scan shows. '
+      + 'Never, on either: the index, HEAD, refs or anything else in .git, nor what a commit made while the command ran',
+    affects: null,
+  },
+  { name: 'Sessions: save, resume, name', workbench: 'Session switch in the conversation', native: 'Native', available: true, provider: 'pi built-in', source: 'pi, as it comes', affects: null },
+  { name: 'Branching: tree navigation, fork, clone', workbench: 'Branch in the conversation', native: 'Native', available: true, provider: 'pi built-in', source: 'pi, as it comes', affects: null },
+  { name: 'Compaction: automatic and manual', workbench: 'Long sessions continue', native: 'Native', available: true, provider: 'pi built-in', source: 'pi, as it comes', affects: null },
+  { name: 'Steering, queued follow-ups, abort', workbench: 'Send while answering; Stop', native: 'Native', available: true, provider: 'pi built-in', source: 'pi, as it comes', affects: null },
+  { name: 'Model and thinking level; provider login or API key', workbench: 'Keeper → Model provider', native: 'Native (/login, /model)', available: true, provider: 'pi built-in', source: 'pi, as it comes; backups and extra keys are ProjectKeeper\'s settings', affects: null },
+  { name: 'Project instruction files, skills, prompt templates, extensions, pi packages', workbench: 'Loaded the native way for the project directory', native: 'Native', available: true, provider: 'pi built-in', source: 'pi, as it comes', affects: null },
+  { name: 'Themes', workbench: 'Not applicable', native: 'Native', available: true, provider: 'pi built-in', source: 'pi, as it comes', affects: null },
+  { name: 'Usage and cost reporting', workbench: 'Usage, Keeper activity', native: 'Native', available: true, provider: 'pi built-in', source: 'pi\'s session statistics', affects: null },
+
+  // ── what the clerk method needs (Spec §8.1 "书记员需要的能力"; CKC-03 AC-25–AC-31) ──
+  {
+    name: 'Querying the ledger: commits and merges, document versions and their sections, supersession lines, numbers, verdicts, execution arrangements, a word across all history, file references, sessions and the owner\'s words, how something got here',
+    workbench: `The pk_ledger_* tools, in ${EVERY_STEP}; a round's first step brings the ledger up to date`,
+    native: 'Not in native pi',
+    available: true, provider: 'The ledger',
+    source: 'The project\'s ledger (one SQLite file in its assets, rebuilt from git, the documents and the session logs), read through the pk_ledger_* tools',
+    affects: null,
+  },
+  {
+    name: 'Code references in TypeScript and JavaScript: file level, and symbol level (references, implementations, callers, callees)',
+    workbench: `File-level dependencies of every file in the ledger; symbol level on demand with pk_ledger_symbol, compiler-exact, in ${EVERY_STEP}. Project scope says the same level per language`,
+    native: 'Not in native pi',
+    available: true, provider: 'TypeScript language service',
+    source: 'File level: the ledger, through the TypeScript pre-parser. Symbol level: the TypeScript language service over the current checkout',
+    affects: null,
+  },
+  {
+    name: 'Code references in every other language the code engine reads (Dart, Python, Kotlin, Swift, Go, Java, C/C++ and the rest): file level, and symbol level (references, implementations, callers, callees)',
+    workbench: `File-level dependencies of every such file in the ledger; symbol level on demand with pk_ledger_symbol, each hit with how it was resolved and whether it counts, in ${EVERY_STEP}. Nothing to set up in the project. Project scope and pk_ledger_coverage say per language what was resolved and where references went unresolved; a residue judged by references there is recorded Inferred (pk_write_territory)`,
+    native: 'Not in native pi',
+    available: true, provider: 'The ledger',
+    source: 'The ledger\'s general code engine, @colbymchenry/codegraph (pinned), indexing a snapshot of the current version kept next to the ledger — never in the project; only references it resolved through an import, a path, a qualified name, a function reference or an instance method count',
+    affects: null,
+  },
+  {
+    name: 'Code references in languages neither reads (CSS, HTML, shell scripts, SQL …)',
+    workbench: 'The file tree and sizes only; no dependencies. Project scope lists each language with its level',
+    native: 'Not in native pi',
+    available: false, provider: 'Not provided',
+    source: 'Neither the TypeScript compiler nor the code engine reads their references',
+    affects: 'On such code, the code-state sweep and the cross-check read dependencies by hand; a residue judged by references there is recorded Inferred (pk_write_territory)',
+  },
+  {
+    name: 'Each job of a round and each lane in a fresh session, in parallel',
+    workbench: 'A round\'s main agent, each lane it sends, the session drafts and the spot-check run as jobs of their own in new pi sessions — the lanes as many at once as the keys allow (Parallel jobs per key); they hand over through the workbench\'s positions and the round\'s documents, never a shared session',
+    native: 'One session at a time',
+    available: true, provider: 'ProjectKeeper adapter',
+    source: 'The Keeper runtime: a new pi session per job, nothing forked from another',
+    affects: null,
+  },
+  {
+    name: 'Delegating a local investigation (sub-agent)',
+    workbench: 'The conversation, answers, requests, product re-looks and a round\'s synthesis send focused investigations',
+    native: 'Not in native pi (pi has no sub-agents of its own)',
+    available: true, provider: 'ProjectKeeper tool',
+    source: 'pk_investigate: a focused pi session of its own whose conclusion and sources return to the job that sent it; it is a child of that job in Keeper activity',
+    affects: null,
+  },
+  {
+    name: 'Model and thinking level per step',
+    workbench: 'Keeper → Model provider, for each model step of a round (session drafts, the main agent, each lane, the synthesis — which, left unset, runs on what the main agent is set to — and the spot-check; and for rounds of the earlier method, where each step was a job of its own: orientation, skeleton, sweeps, cross-check); the model and the thinking level a job actually ran on are in Keeper activity',
+    native: 'One model per session (/model)',
+    available: true, provider: 'ProjectKeeper adapter',
+    source: 'The workspace setting steps, applied when a step\'s pi session is created; the thinking level the model accepted is recorded',
+    affects: null,
+  },
+  {
+    name: 'Long output: long judgements and tool calls with long arguments',
+    workbench: `In ${EVERY_STEP}: long tool arguments stream in whole; a call whose arguments did not arrive as complete JSON never runs — any tool, pi's write included — and the model is told to send it again; a last reply cut at the output limit, or the same call refused the same way in 8 turns in a row with nothing else run in them, ends the job Failed with the step and the reason in Keeper activity (calls refused together in one turn count once each); the reply is kept as written`,
+    native: 'Upstream behaviour: Open in pi runs the pi installed on the machine, without ProjectKeeper\'s patch',
+    available: true, provider: 'ProjectKeeper adapter',
+    source: 'ProjectKeeper\'s patch of pi-ai 0.87.1 (scripts/apply-pi-streaming-patch.ts, applied at npm install) and the runtime\'s rules for how a job ends',
+    affects: null,
+  },
+  {
+    name: 'Time and usage per step',
+    workbench: 'Keeper activity and the round tree: each job\'s time split into generation, tools, queue, parse & retry and other, and its tokens; a round sums its steps',
+    native: 'Usage per session',
+    available: true, provider: 'ProjectKeeper adapter',
+    source: 'The Keeper runtime stamps pi\'s events as they arrive (StepTimer); usage from pi\'s session statistics',
+    affects: null,
+  },
+  { name: 'MCP servers', workbench: 'Not provided by pi itself; an extension may add it', native: 'Only through an extension', available: false, provider: 'Not provided', source: 'pi has no built-in MCP; nothing in ProjectKeeper adds it', affects: 'No step and no workbench control depends on it' },
+];

package/src/keeper/clerk-steps.ts

@@ -0,0 +1,151 @@
+/**
+ * Which step of a round of the clerk method writes which of the clerk method's own positions (Spec v3.0 §3.3
+ * “跨对象的记录由哪一步写”). One table for both sides: a writer refuses a step not listed for it (clerk-tools.ts), and
+ * a step is offered exactly the writers that list it (roles.ts `STEP_WRITES`), so a step is never offered a writer
+ * that then refuses it, nor denied a correction the writer allows. The spot-check corrects through the same writers,
+ * on records that already exist.
+ */
+import type { ClerkStage, RoundDocKind, RoundStepKind, SlotKind } from '../model/k-types.ts';
+
+/**
+ * The round documents each step writes; a round document is written by the step listed for its kind. The synthesis
+ * (D103: a job of its own) writes the round's Result; the spot-check, which checks every claim of it, corrects a Result
+ * that is there (clerk-tools.ts `pk_write_round_doc`).
+ */
+export const DOCS_BY_STEP: Readonly<Partial<Record<RoundStepKind, readonly RoundDocKind[]>>> = {
+  orientation: ['Questions', 'Brief', 'History map'],
+  dig: ['Report'],
+  'cross-check': ['Adoption'],
+  synthesis: ['Result'],
+  'spot-check': ['Spot check', 'Result'],
+};
+
+export const CLERK_WRITER_STEPS = {
+  pk_write_session_draft: ['session-drafts'],
+  pk_write_layers: ['orientation', 'spot-check'],
+  pk_write_generation: ['orientation', 'skeleton', 'cross-check', 'spot-check'],
+  pk_write_round_doc: Object.keys(DOCS_BY_STEP) as RoundStepKind[],
+  pk_write_patch: ['skeleton', 'cross-check', 'spot-check'],
+  pk_number: ['skeleton'],
+  pk_link_process: ['skeleton', 'cross-check'],
+  pk_confirm: ['cross-check', 'spot-check'],
+  pk_suggest_sendback: ['cross-check', 'synthesis'],
+  pk_tag_six: ['cross-check', 'synthesis', 'spot-check'],
+  pk_confirm_note: ['synthesis'],
+  pk_write_territory: ['cross-check', 'spot-check'],
+  pk_record_spot_check: ['spot-check'],
+} as const satisfies Readonly<Record<string, readonly RoundStepKind[]>>;
+
+export type ClerkWriter = keyof typeof CLERK_WRITER_STEPS;
+
+/** The clerk method's writers a step is offered. */
+export function clerkWritersOf(step: RoundStepKind | string): ClerkWriter[] {
+  return (Object.keys(CLERK_WRITER_STEPS) as ClerkWriter[]).filter((t) => (CLERK_WRITER_STEPS[t] as readonly string[]).includes(step));
+}
+
+/**
+ * The steps of a round in the method's order (§3.3); D99's main agent and its lanes last, so each has its own model setting
+ * (CKC-23 AC-11). D103: `synthesis` is a step of its own again; left unset, it runs on what `main` is set to (`STEP_SETTING_AS`).
+ */
+export const ROUND_STEP_KINDS = ['ledger', 'session-drafts', 'orientation', 'skeleton', 'dig', 'cross-check', 'process', 'synthesis', 'spot-check', 'main', 'lane'] as const satisfies readonly RoundStepKind[];
+/** The program's steps: the ledger (§1.16) and the process with its breakpoints (§2.12). Every other step runs a model. */
+export const PROGRAM_STEP_KINDS: readonly RoundStepKind[] = ['ledger', 'process'];
+export const MODEL_STEP_KINDS: readonly RoundStepKind[] = ROUND_STEP_KINDS.filter((k) => !PROGRAM_STEP_KINDS.includes(k));
+
+/**
+ * A step whose model setting, left unset, is another step's (D103): the synthesis runs on what the main agent is set to,
+ * so a home whose settings were written before the synthesis had a session of its own keeps running it on the same model.
+ */
+export const STEP_SETTING_AS: Readonly<Partial<Record<RoundStepKind, RoundStepKind>>> = { synthesis: 'main' };
+
+/** A step's model setting as it takes effect: its own, each part it leaves unset taken from the step it defaults to. */
+export function stepSettingOf<T extends { readonly model?: string; readonly thinking?: string }>(steps: Readonly<Partial<Record<string, T>>> | null | undefined, kind: RoundStepKind): { readonly model?: string; readonly thinking?: string } | undefined {
+  const own = steps?.[kind];
+  const as = STEP_SETTING_AS[kind];
+  const from = as ? steps?.[as] : undefined;
+  if (!own && !from) return undefined;
+  const model = own?.model ?? from?.model;
+  const thinking = own?.thinking ?? from?.thinking;
+  return { ...(model ? { model } : {}), ...(thinking ? { thinking } : {}) };
+}
+
+/** pi's thinking levels (`ThinkingLevel`), for the per-step setting (CKC-03 AC-29). */
+export const THINKING_LEVELS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+
+// ───────────────────────── D99: the main agent's stages and the lanes' slots (W0 contract) ─────────────────────────
+
+/** The trunk's writers from before the clerk method (roles.ts `TRUNK_WRITES`), named here for the D99 tables. */
+const TRUNK = ['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'] as const;
+
+/** Tools the main agent has in every stage (D99): moving between stages, where the round stands, its lanes. */
+export const MAIN_ALWAYS = ['pk_stage', 'pk_round_state', 'pk_lanes'] as const;
+
+/**
+ * What the main agent writes in each stage (D99; Spec §3.3 "谁写什么"). Its session is offered the union; a writer
+ * refuses outside the stages that list it (gate at call time, E148 D-a). Round documents by kind follow `DOCS_BY_STAGE`.
+ * D103: the main agent writes nothing in the synthesis — it hands over, and the synthesis job writes what the stage wrote
+ * (`SYNTHESIS_WRITERS`).
+ */
+export const STAGE_WRITERS: Readonly<Record<ClerkStage, readonly string[]>> = {
+  orientation: ['pk_write_rule', 'pk_classify_scope', 'pk_set_used_as', 'pk_write_organizing_plan', 'pk_write_layers', 'pk_write_generation', 'pk_generation_candidate', 'pk_write_round_doc'],
+  skeleton: ['pk_write_round_doc', 'pk_send_lanes', 'pk_fill_from_table', 'pk_fill_from_headings', 'pk_fill_from_bold', 'pk_account_entries'],
+  reconcile: [...TRUNK, 'pk_judge_owner_lines', 'pk_write_rule', 'pk_number', 'pk_link_process', 'pk_write_patch', 'pk_write_generation', 'pk_generation_candidate', 'pk_place_range', 'pk_fill_from_table', 'pk_fill_from_headings', 'pk_fill_from_bold', 'pk_account_entries'],
+  dig: ['pk_write_round_doc', 'pk_send_lanes'],
+  coverage: ['pk_coverage_check', 'pk_account_material', 'pk_account_entries', 'pk_write_round_doc', 'pk_send_lanes'],
+  'cross-check': [...TRUNK, 'pk_judge_owner_lines', 'pk_write_rule', 'pk_account_entries', 'pk_confirm', 'pk_link_process', 'pk_write_patch', 'pk_write_generation', 'pk_generation_candidate', 'pk_place_range', 'pk_suggest_sendback', 'pk_tag_six', 'pk_write_territory', 'pk_write_round_doc'],
+  synthesis: [],
+};
+
+/**
+ * What the synthesis job writes (D103; Spec §3.3 the stage table's 合成 row: note, the six things, `Suggested` send-backs,
+ * area understanding, the round's Result). What the main agent's synthesis stage wrote before it — the notes, the
+ * judgement record and relations it reached, the rules note, marks, an investigation, send-backs, the six things, the
+ * round's Result — and the two D103 gives the synthesis: area understanding (`pk_write_area`, which the stage did not
+ * offer), and `pk_confirm_note`, the result "still holds" for a note standing from an earlier round (standing-notes.ts).
+ * roles.ts offers exactly these (`STEP_WRITES.synthesis`).
+ */
+export const SYNTHESIS_WRITERS = ['pk_write_note', 'pk_close_note', 'pk_record_judgement', 'pk_assess_relation', 'pk_ask_owner_about_rules', 'pk_write_mark', 'pk_investigate', 'pk_suggest_sendback', 'pk_tag_six', 'pk_write_round_doc', 'pk_write_area', 'pk_confirm_note'] as const;
+/** What the synthesis job is offered besides its writers and the reads every step has: where the round stands, counted, and one list at a time. */
+export const SYNTHESIS_ALWAYS = ['pk_round_state'] as const;
+
+/** The round documents the main agent writes in each stage (D99). */
+export const DOCS_BY_STAGE: Readonly<Record<ClerkStage, readonly RoundDocKind[]>> = {
+  orientation: ['Questions', 'Brief', 'History map'],
+  skeleton: ['Brief'],
+  reconcile: [],
+  dig: ['Brief'],
+  coverage: ['Brief'],
+  'cross-check': ['Adoption'],
+  synthesis: [],
+};
+
+/** What a lane may write, by the slot kind it was given (D99, E148 D-d); `reference:<category>` is checked by category too. */
+export const SLOT_WRITERS: Readonly<Record<'reference' | Exclude<SlotKind, `reference:${string}`>, readonly string[]>> = {
+  // DA: `pk_judge_owner_lines` is the Owner's words lane's (stage-gate.ts checks the category, as for the items).
+  reference: ['pk_write_reference', 'pk_judge_owner_lines', 'pk_fill_from_table', 'pk_fill_from_headings', 'pk_fill_from_bold', 'pk_place_range'],
+  threads: ['pk_write_thread', 'pk_number', 'pk_merge_work_items', 'pk_record_carry_out', 'pk_fill_from_table', 'pk_place_range'],
+  links: ['pk_link_process'],
+  territories: ['pk_write_territory'],
+  patches: ['pk_write_patch'],
+  generations: ['pk_write_generation', 'pk_generation_candidate'],
+  relations: ['pk_relate', 'pk_place_range'],
+};
+
+/** What every lane may write whatever its slots (D99): its own Report, and where it looked for a missing step. */
+export const LANE_ALWAYS = ['pk_write_round_doc', 'pk_record_looked'] as const;
+/** The round document a lane writes. */
+export const LANE_DOCS: readonly RoundDocKind[] = ['Report'];
+
+/**
+ * The main agent's stages in each kind of round, in order (D99; Spec §3.3, §3.7, §3.8). D103: its session ends after its
+ * last check — the reconciling of a first usable round, the cross-check of a deepening and a Follow up — with a handover
+ * to the synthesis, which runs in a session of its own.
+ */
+export const ROUND_STAGES: Readonly<Record<'First usable' | 'Deepen' | 'Follow up', readonly ClerkStage[]>> = {
+  'First usable': ['orientation', 'skeleton', 'reconcile'],
+  Deepen: ['orientation', 'dig', 'coverage', 'cross-check'],
+  'Follow up': ['orientation', 'skeleton', 'reconcile', 'dig', 'coverage', 'cross-check'],
+};
+
+/** What the main agent hands the round over to with `pk_stage` once its last stage is done (D103): the synthesis. */
+export const HANDOVER_TO: ClerkStage = 'synthesis';