pi-canon 0.2.3 → 0.2.4

package/README.md

@@ -8,12 +8,38 @@ Canonical project memory for the [Pi coding agent](https://pi.dev). Every asset
 
 ## Install
 
+### Pi
+
 ```
 pi install npm:pi-canon
 ```
 
 Or clone this repo into `~/.pi/agent/extensions/`. Node 22.18 or later, Pi 0.83 or later on the 0.x line. Nothing to configure: the store is created on first write at `<project>/.canon`. The package imports `node:fs` and `node:path` and nothing else, makes no network calls, runs no git, and loads under plain node with no build step.
 
+### Codex
+
+The repository is a Codex marketplace. Add it once, then install the plugin at user scope:
+
+```sh
+codex plugin marketplace add shaneconner/pi-canon
+codex plugin add pi-canon@pi-canon
+```
+
+For a local checkout under development, replace `shaneconner/pi-canon` with its absolute path. Start a new Codex thread after installing or updating it.
+
+### Claude Code
+
+The same repository is also a Claude Code marketplace:
+
+```sh
+claude plugin marketplace add shaneconner/pi-canon --scope user
+claude plugin install pi-canon@pi-canon --scope user
+```
+
+Again, an absolute checkout path works for local development. Start a new Claude Code session after installing or updating it.
+
+Both plugins launch the same dependency-free MCP server and expose the same `pi_canon` actions as Pi. Codex surfaces after each tool result. Claude Code deduplicates one capsule packet across each parallel tool batch, immediately before the next model request, which avoids repeated message framing without delaying the agent's next decision. Both give one write-after reminder before the agent stops. An article surfaces at most once per compaction cycle: a compact starts a new cycle, while resuming the same uncompacted session does not. One session may contain several compaction cycles. Compaction discards prior touch state and replays nothing. After it, only a fresh tool-input path can surface that asset's exact or nearest-ancestor article; children and unrelated articles do not ride along. The hooks are inert in projects without `.canon/articles`, and they never create a store merely because a session opened. Review and approve the plugin hooks when the client asks. Journal entries written through the MCP server carry explicit `harness` provenance and a session identifier when the client exposes one.
+
 ## The first article
 
 A session is not greeted: through 0.2.0 every session opened with an orientation line. A 2x2 experiment with an inert implementation found significant negative main effects for both that line and the tool schema, but their 19/32 versus 21/32 comparison did not resolve which component cost more. Study 3 detected no benefit loss when the line was removed, so 0.2.1 deleted it. The tool description carries the doctrine instead. The first article takes one tool call:
@@ -171,6 +197,7 @@ Held by the runtime:
 - Once a path is in hand it resolves to exactly one article, walking to the nearest ancestor that has one, or to nothing at all.
 - An article surfaces whole, with no character count able to truncate it or hold it back.
 - An article with a presence mark surfaces at most once while that mark remains in the context the provider receives. Presence is read from that projection rather than remembered, so folding or compaction returns a marked article to surfacing; an untestably short delivery or a harness that reports no projection degrades to at most once per session.
+- The Codex and Claude Code hooks cannot inspect that projection. They use an explicit compaction cycle instead: session start, context clear, and compaction discard prior touch state; resume does not. None of those events surfaces an article. A later asset touch does. Codex delivers after each tool result; Claude Code combines the current parallel batch into one packet before the next model request.
 - Reading an article through the tool withdraws its staged capsule before the message goes out.
 
 Asked of the agent, and checked by nothing:
@@ -240,10 +267,11 @@ That is development evidence over two arms of one run and it carries no confirma
 
 ## More
 
-- The paper, with the per-cell artifact trail: [doi:10.5281/zenodo.21890647](https://doi.org/10.5281/zenodo.21890647).
+- The 0.2 paper, with its six-study per-cell artifact trail: [doi:10.5281/zenodo.21960350](https://doi.org/10.5281/zenodo.21960350).
+- The first paper, with its end-to-end per-cell artifact trail: [doi:10.5281/zenodo.21890647](https://doi.org/10.5281/zenodo.21890647).
 - The benchmark, drivers, frozen protocol, and the verifier that recomputes the paper's quantitative claims from the artifacts: [canon-bench](https://github.com/shaneconner/canon-bench).
 - Interactive versions of every figure and the full measurement story: [shaneconner.com/projects/pi-canon](https://shaneconner.com/projects/pi-canon/).
 - The narrative version: [My agents' wiki was written faster than it was read](https://medium.com/@shane.conner/my-agents-wiki-was-written-faster-than-it-was-read-and-what-was-read-sold-me-back-debt-i-had-a8085319c68b).
 - [pi-fold](https://github.com/shaneconner/pi-fold), a separate optional package serving the working tier. pi-canon ships the two persistent tiers of the same four-tier stack: the journal is the episodic tier, the canon the semantic tier. The two compose, neither requires the other, and neither knows what the other has spent.
 
-MIT. In a clone of this repo, `node tests/verify.mjs` runs the gate suite: every invariant prints by name and the run must end `all N gates green`, 142 of them at this release.
+MIT. In a clone of this repo, `node tests/verify.mjs` runs the gate suite: every invariant prints by name and the run must end `all N gates green`, 149 of them at this release.

package/extensions/lib/store.ts

@@ -263,7 +263,12 @@ export class CanonStore {
   /* Journal entries are immutable: a fresh dated file per entry, wx so nothing is
      ever overwritten. EEXIST is the retry signal, so concurrent writers each land
      on their own file instead of one losing its entry. */
-  journal(entry: { body: string; slug?: string; subject?: string[] }): string {
+  journal(entry: {
+    body: string;
+    slug?: string;
+    subject?: string[];
+    provenance?: { harness: string; sessionId?: string };
+  }): string {
     const slug =
       (entry.slug ?? "entry").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "entry";
     mkdirSync(this.journalDir, { recursive: true });
@@ -277,6 +282,8 @@ export class CanonStore {
     const front = [
       entry.subject?.length ? `subject: [${entry.subject.map(scalar).join(", ")}]` : "",
       `logged: ${stamp}`,
+      entry.provenance?.harness ? `harness: ${scalar(entry.provenance.harness)}` : "",
+      entry.provenance?.sessionId ? `session: ${scalar(entry.provenance.sessionId)}` : "",
     ].filter(Boolean).join("\n");
     const text = `---\n${front}\n---\n${entry.body.trimEnd()}\n`;
     for (let n = 1; ; n += 1) {

package/extensions/lib/tool.ts

@@ -14,6 +14,57 @@ export interface CanonRuntime {
   cwd: string;
   mounts: Mount[];
   retrieval: string;
+  provenance?: { harness: string; sessionId?: string };
+}
+
+export const CANON_TOOL_PARAMETERS = {
+  type: "object",
+  properties: {
+    action: { type: "string", enum: ["read", "write", "journal", "map", "search"] },
+    path: {
+      type: "string",
+      description: "Article address, e.g. src/core/config. Required for read and write; optional filter for map.",
+    },
+    body: {
+      type: "string",
+      description:
+        "write: the full article body; specifics beat summaries (who consumes what, exact " +
+        "limits, what breaks). journal: the event text, source details intact.",
+    },
+    capsule: { type: "string", description: "write: one dense line injected when the asset is touched." },
+    query: { type: "string", description: "search: words to look for, across articles and the journal." },
+    scope: {
+      type: "string",
+      enum: ["rule", "asset"],
+      description:
+        "write: 'rule' when this article names a cross-cutting rule instead of governing an " +
+        "asset, so it is a rule on purpose rather than an article whose asset went missing; " +
+        "'asset' to take that back, when the article governs an asset after all.",
+    },
+    subject: {
+      type: "array",
+      items: { type: "string" },
+      description: "journal: article addresses this event concerns.",
+    },
+    slug: { type: "string", description: "journal: short name for the entry file." },
+  },
+  required: ["action"],
+} as const;
+
+export function canonToolDescription(retrieval = "none"): string {
+  return (
+    "Canonical project memory. Every asset has at most one governing article at its own address " +
+    "(src/core/config, lake/prices). read the governing article before working on an asset; " +
+    "write it after real changes. journal appends an immutable event entry: record the source " +
+    "as it happened, names and exact numbers included, because articles distill and only the " +
+    "journal keeps the original, so distil the prose but carry exact values through verbatim: " +
+    "ids, keys, names, counts, limits and durations, every member of a named set and not " +
+    "just the one you are working on. A rule without its values is worth nothing to the " +
+    "session that needs it. map lists articles with their capsules. " +
+    "Creation is rare: prefer updating the article that already governs. " +
+    "File a constraint at the asset it governs, or the shared parent when it spans assets, not " +
+    "the asset you happened to edit. " + filingTail(retrieval)
+  );
 }
 
 /* A path routes to the mount it names (lake:prices), the mount whose directory
@@ -50,51 +101,8 @@ export function buildCanonTool(ready: (ctx: unknown) => CanonRuntime, retrieval
   return {
     name: "pi_canon",
     label: "pi-canon",
-    description:
-      "Canonical project memory. Every asset has at most one governing article at its own address " +
-      "(src/core/config, lake/prices). read the governing article before working on an asset; " +
-      "write it after real changes. journal appends an immutable event entry: record the source " +
-      "as it happened, names and exact numbers included, because articles distill and only the " +
-      "journal keeps the original, so distil the prose but carry exact values through verbatim: " +
-      "ids, keys, names, counts, limits and durations, every member of a named set and not " +
-      "just the one you are working on. A rule without its values is worth nothing to the " +
-      "session that needs it. map lists articles with their capsules. " +
-      "Creation is rare: prefer updating the article that already governs. " +
-      "File a constraint at the asset it governs, or the shared parent when it spans assets, not " +
-      "the asset you happened to edit. " + filingTail(retrieval),
-    parameters: {
-      type: "object",
-      properties: {
-        action: { type: "string", enum: ["read", "write", "journal", "map", "search"] },
-        path: {
-          type: "string",
-          description: "Article address, e.g. src/core/config. Required for read and write; optional filter for map.",
-        },
-        body: {
-          type: "string",
-          description:
-            "write: the full article body; specifics beat summaries (who consumes what, exact " +
-            "limits, what breaks). journal: the event text, source details intact.",
-        },
-        capsule: { type: "string", description: "write: one dense line injected when the asset is touched." },
-        query: { type: "string", description: "search: words to look for, across articles and the journal." },
-        scope: {
-          type: "string",
-          enum: ["rule", "asset"],
-          description:
-            "write: 'rule' when this article names a cross-cutting rule instead of governing an " +
-            "asset, so it is a rule on purpose rather than an article whose asset went missing; " +
-            "'asset' to take that back, when the article governs an asset after all.",
-        },
-        subject: {
-          type: "array",
-          items: { type: "string" },
-          description: "journal: article addresses this event concerns.",
-        },
-        slug: { type: "string", description: "journal: short name for the entry file." },
-      },
-      required: ["action"],
-    },
+    description: canonToolDescription(retrieval),
+    parameters: CANON_TOOL_PARAMETERS,
     async execute(
       _toolCallId: string,
       params: Record<string, unknown>,
@@ -102,7 +110,7 @@ export function buildCanonTool(ready: (ctx: unknown) => CanonRuntime, retrieval
       _onUpdate: unknown,
       ctx: unknown,
     ) {
-      const text = run(ready(ctx), params);
+      const text = runCanon(ready(ctx), params);
       return { content: [{ type: "text", text }], details: {} };
     },
   };
@@ -211,7 +219,7 @@ function excerpt(body: string): string {
   return flat.length > 160 ? `${flat.slice(0, 157)}...` : flat;
 }
 
-function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
+export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>): string {
   const { surfacer } = runtime;
   const action = String(params.action ?? "");
   const { mount, path } = typeof params.path === "string" ? route(runtime, params.path) : { mount: runtime.mounts[0], path: "" };
@@ -293,6 +301,7 @@ function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
         body,
         subject,
         slug: typeof params.slug === "string" ? params.slug : undefined,
+        provenance: runtime.provenance,
       });
       /* The article was written before this entry (agents write then journal), so this
          is the first moment both exist. Report what the source kept and the article did

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-canon",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Canonical project memory for the Pi coding agent: one article per asset at a knowable address, an append-only journal beneath it.",
   "type": "module",
   "exports": {