pi-canon 0.2.2 → 0.2.4

package/README.md

@@ -8,15 +8,41 @@ 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, and a 2x2 experiment with an inert implementation priced that line at more first-pass correctness than the whole tool schema, so 0.2.1 deleted it. The tool description carries the doctrine instead. The first article takes one tool call:
+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:
 
 ```json
 { "action": "write",
@@ -82,7 +108,7 @@ pi-canon is an increment on the pattern rather than a replacement for it, and it
 
 **A spine**, the addressing convention. An article's address is computed from the asset instead of searched for, and nothing has to be configured for that mapping to hold, which makes the spine a convention rather than a mode. It is also why nothing in the RECALL path searches: when a touch already decided the address, there is nothing to find. The `search` action exists for the opposite direction, the agent that wants to ask, and it never runs unasked.
 
-**Surfacing**, push rather than pull. When a tool call is detected touching a governed asset, that article's capsule is staged for the session, at most once per article, so nobody has to think to ask. Detection of a path inside a tool call is best effort. Resolution, once a path is in hand, is not.
+**Surfacing**, push rather than pull. When a tool call is detected touching a governed asset, that article's capsule is staged for the session, at most once per article while it stays in context (see Surfacing), so nobody has to think to ask. Detection of a path inside a tool call is best effort. Resolution, once a path is in hand, is not.
 
 The evaluation below does not test that lineage argument: no evaluated arm is a search-driven LLM wiki, so nothing here shows pi-canon beats a disciplined one.
 
@@ -96,7 +122,7 @@ A rename is a file move you make yourself. pi-canon does not watch the filesyste
 
 An article matching no asset is ordinary free knowledge. The spine guarantees an address for the assets a project already has; it does not confine the store to them. The tradeoff is worth stating in the same breath: surfacing is asset-scoped, so an off-spine article is reached by a link or an explicit read rather than pushed on a touch, or by relevance when a retriever is configured.
 
-Such an article may say so, with `scope: rule` on the write. Nothing filters on it, because a declaration the agent forgot must never cost it the only mechanism that can reach it. What it buys is that the two populations stop being one number: an article off the asset path is either a cross-cutting rule filed exactly where the doctrine asked for it, or an article whose asset was deleted under it, and those want opposite things. `scope: asset` takes the declaration back.
+Such an article may say so, with `scope: rule` on the write. Forgetting the declaration never excludes an off-spine article from retrieval. Declaring it separates a rule filed on purpose from an article whose asset disappeared, and keeps that rule in the retrieval corpus if an asset later appears at the same address. `scope: asset` takes the declaration back.
 
 ## The tool
 
@@ -120,7 +146,7 @@ One lint line is different in kind. When a write supplies a body and an article
 
 ## Surfacing
 
-A tool call stages the governing article for whatever it touched and sends nothing. Each turn end flushes everything staged as a single message, because pi's steering queue drains one message per provider round trip and a message per tool call would buy every nudge its own model call. An article surfaces at most once per session, and nothing about that persists: a new session re-surfaces everything.
+A tool call stages the governing article for whatever it touched and sends nothing. Each turn end flushes everything staged as a single message, because pi's steering queue drains one message per provider round trip and a message per tool call would buy every nudge its own model call. An article with a presence mark surfaces at most once while that mark remains in the context the provider receives; one folded or compacted away returns to surfacing and rides again on its asset's next touch (the `resurface` option below). Delivered text shorter than 24 normalized characters cannot be tested safely and conservatively stays seen for the session. Nothing persists across sessions: a new session re-surfaces everything.
 
 No character count decides any of this. A capsule is written to fit 1,000 characters, and that is a target handed to the agent at write time, not a gate at read time: an article whose governing asset a turn touched surfaces whole or does not surface. Earlier versions charged capsule text against a session allowance and degraded the overflow to bare pointers. That allowance was removed in 2.0. It was a constant guessing at a policy nobody had measured, and what it decided was how much an agent got to see. What stands in its place is measurement: every surfaced line records what it cost the window, so context taken can be read against relevance afterwards instead of a constant ruling on it in advance. The one remaining reason a line is not capsule text is an article that has no capsule, which surfaces as a pointer naming the address and telling the agent to read it.
 
@@ -147,10 +173,10 @@ Six keys, and any other throws at registration by name, because everything else
 
 - **`root`** places the store. Absolute is used as given, relative joins the project cwd. Default `<project>/.canon`.
 - **`surface: false`** silences the per-turn flush and the settle reminder. The `pi_canon` tool and `/pi-canon` stay registered and working.
-- **`resurface: false`** returns an article to surfacing at most once per session however long ago it left the window. The default is `true`: an article counts as seen only while it is still in the context the provider receives, so one folded or compacted away surfaces again the next time its asset is touched. A fresh touch is what brings it back, so nothing re-surfaces on its own.
-- **`retrieval`** ranks the articles that govern no asset, the one category the address spine can never reach, against what the agent is doing. The default is `"none"`, which ranks nothing and surfaces nothing unaddressed: the spine alone, exactly as 1.0. `"lexical"` is BM25 over the standard library, no dependency and no model. Anything that needs a model is supplied here as `{ name, score, index? }`, so this package never carries one and never decides which you run. With a retriever configured the tool's filing rule changes with it, because the advice costs knowledge in either direction. On the default it says knowledge filed off the asset path never surfaces, which is true and is why you should not file it there. With a retriever it says the opposite: a constraint governing many assets and owning none belongs at its own address naming the rule, because the only parent unrelated packages share is the root and a root article surfaces on every touch of anything.
+- **`resurface: false`** returns an article to surfacing at most once per session however long ago it left the window. The default is `true`: an article with a presence mark counts as seen only while that mark remains in the context the provider receives, so one folded or compacted away surfaces again the next time its asset is touched. Text shorter than 24 normalized characters has no safe mark and conservatively retains the once-per-session behavior. A fresh touch is what brings a marked article back, so nothing re-surfaces on its own.
+- **`retrieval`** ranks the retrieval corpus against what the agent is doing: every off-spine article, plus any article declared `scope: rule` so a rule stays reachable if an asset later appears at its address. Ordinary asset-scoped articles stay out because the address spine already reaches them. The default is `"none"`, which ranks and surfaces nothing by relevance: the spine alone, exactly as 1.0. `"lexical"` is BM25 over the standard library, no dependency and no model. Anything that needs a model is supplied here as `{ name, score, index? }`, so this package never carries one and never decides which you run. With a retriever configured the tool's filing rule changes with it, because the advice costs knowledge in either direction. On the default it says knowledge filed off the asset path never surfaces, which is true and is why you should not file it there. With a retriever it says the opposite: a constraint governing many assets and owning none belongs at its own address naming the rule, because the only parent unrelated packages share is the root and a root article surfaces on every touch of anything.
 
-- **`standout`** is how far the best-ranked article must beat the best one that will not ride anyway, meaning the fourth, the one the three-per-message cap was already going to leave behind. A multiple, not a score: `standout: 1.5` asks for the best to score half again what the first held-back rival scored. Default `1.4`, an operating point priced by a 120-cell benchmark rather than picked: it matched the uncut channel's delivery to within that benchmark's own noise floor while cutting suggestions from 26 a session to 3, raised the rate at which the agent acted on one from 0.17 to 0.82, and never fired at all on a store with nothing relevant to say, 0 rankings of 139. Precision is the side to protect, though the measured argument is tokens rather than attention: the same benchmark found good suggestions opened at the same rate buried among twenty-seven as one of four, so what the cutoff saves is the context it declines to spend on lines that were never going to be read. The other side has a price too, and the same benchmark paid it: a cutoff set past what a decisive ranking reaches silences the channel, and at 2.0 it delivered nothing and gave back everything the channel had won. `standout: 1` is no cutoff, the measurement setting for reading your own store's trace. Below `1` throws at registration, because it asks for the best article to be worse than its rival and is what a caller writes who is still thinking in scores.
+- **`standout`** is how far the best-ranked article must beat the best one that will not ride anyway, meaning the fourth, the one the three-per-message cap was already going to leave behind. A multiple, not a score: `standout: 1.5` asks for the best to score half again what the first held-back rival scored. Default `1.4`, an operating point priced by a 120-cell benchmark rather than picked: its n=15 comparison with the uncut channel differed by -0.07 rule facts at p=1.0 while cutting suggestions from 26 a session to 3, raised the rate at which the agent acted on one from 0.17 to 0.82, and never fired at all on a store with nothing relevant to say, 0 rankings of 139. That small observed contrast is not a general detection bound. Precision is the side to protect, though the measured argument is tokens rather than attention: a companion 124-cell study found good suggestions opened at similar rates buried among twenty-seven as one of four, so what the cutoff saves is the context it declines to spend on lines that were never going to be read. The other side has a price too, and the same benchmark paid it: a cutoff set past what a decisive ranking reaches silences the channel, and at 2.0 it delivered nothing and gave back everything the channel had won. `standout: 1` is no cutoff, the measurement setting for reading your own store's trace. Below `1` throws at registration, because it asks for the best article to be worse than its rival and is what a caller writes who is still thinking in scores.
 
   **It is a ratio because a score is not the same quantity twice.** `lexical` normalizes against a saturation ceiling computed from the query, so a score is a fraction of the best match POSSIBLE for that query rather than of the best match available in your store, and it falls as the agent says more. On a 380-article store the same article at the same relevance scored 0.68 against a short question and 0.16 with a hundred words of tool output around it. Across two benchmark runs it was worse than unstable, it inverted: keeping the answers on one corpus needed a cutoff below 0.11, and silencing the other needed one above 0.73. Dividing by another score from the same query cancels both.
 
@@ -170,14 +196,15 @@ Held by the runtime:
 - A journal entry is created with the exclusive-create flag, so pi_canon never rewrites or deletes one, and a name collision increments a suffix rather than losing an entry. The files stay ordinary Markdown, so any other tool can still rewrite or delete one: append-only is a property of the tool, not of the filesystem.
 - 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 surfaces at most once while it is present in the context the provider receives. Presence is read from that projection rather than remembered, so folding or compaction returns the article to surfacing; a harness that reports no projection degrades to at most once per session.
+- 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:
 
 - Read the governing article before working on an asset, and update it after real changes. No write is gated on a prior read, and the settle reminder is a message rather than a gate.
 - Record the source as it arrived, names and exact numbers included, because articles distill and only the journal keeps the original.
-- File the entry under the right subject, and file a constraint at the asset it governs rather than the asset you happened to edit. Knowledge filed off the asset path never surfaces.
+- File the entry under the right subject, and file a constraint at the asset it governs rather than the asset you happened to edit. On the default `retrieval: "none"`, knowledge filed off the asset path never surfaces; with a retriever configured, a cross-cutting rule can instead live at its own declared address and surface by relevance.
 - Open the article when a capsule or a pointer says there is one. A line in the context is not a read.
 - Decide whether a dropped constraint still holds. Then follow the rule, against a live prompt asking for something else.
 
@@ -186,14 +213,14 @@ Nothing in the package can compel an agent to keep a line it has decided to cut.
 What the package does not do, stated so nothing above reads as more than it is:
 
 - No search that runs unasked. `search` is an action the agent calls; touches resolve to articles by exact address or the ancestor walk, never by ranking, and no query ever fires on the agent's behalf.
-- No embeddings and no model. `retrieval: "lexical"` builds a BM25 index over the articles that govern no asset, and nothing else is ranked ever; any other ranker is a function the caller supplies.
+- No embeddings and no model. `retrieval: "lexical"` builds a BM25 index over off-spine articles plus declared rules, and ordinary asset-scoped articles are never ranked; any other ranker is a function the caller supplies.
 - No filesystem watching, and no staleness detection: `updated` is the date of the last write and is never compared against the asset.
 - No delete and no rename. Removing or moving an article is a file operation you perform.
 - Articles are last write wins, with no lock, no merge, and no warning that someone else changed the file. Only journal entries get the collision retry.
 - No duplicate detection. One canonical address per asset is structural, not checked.
 - Nothing writes, summarizes, or compacts on its own, and nothing filters what goes in: no secrets scanning and no redaction. Every line pi-canon wrote came from an explicit tool call.
 - Nothing about surfacing persists between sessions. A new session re-surfaces everything.
-- Presence is tested by looking for the article's capsule in the projection, so a capsule too short to be distinctive is never expired, and a digest that does not carry the capsule counts as absent.
+- Presence is tested against both the article address and the tail of what it actually placed in the provider projection. Any delivery shorter than 24 normalized characters has no safe mark and is conservatively kept present; that can be a tiny read, write, or exceptionally short surfaced line. For marked deliveries, a digest without the delivered tail counts as absent.
 
 ## Evidence
 
@@ -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/canon.ts

@@ -12,8 +12,9 @@ export interface CanonOptions {
   root?: string;
   /* Surface governing articles as tool calls touch assets. Default: true. */
   surface?: boolean;
-  /* Treat an article as seen only while it is still in the live context window, so one
-     folded or compacted away surfaces again the next time its asset is touched.
+  /* Treat an article with a presence mark as seen only while that mark remains in the
+     live context window, so one folded or compacted away surfaces again on the next
+     touch. Untestably short delivered text has no mark and conservatively stays seen.
      Default: true. Set false for 1.0 behavior, where a surfaced article is never
      surfaced again however long ago it left the window. */
   resurface?: boolean;
@@ -21,18 +22,21 @@ export interface CanonOptions {
      assets, addressed by basename: mounts: ["/data/lake"] serves lake:prices.
      Workspaces that mount the same directory share its knowledge. */
   mounts?: string[];
-  /* How articles that govern no asset are ranked against what the agent is doing, the
-     one category the address spine can never reach. "none" is the default and is the
-     1.0 behavior exactly: nothing is ranked and nothing unaddressed ever surfaces.
-     "lexical" is BM25 over the standard library. Anything needing a model is supplied
-     here as { name, score, index? }, so this package never depends on one. */
+  /* How the retrieval corpus is ranked against what the agent is doing: every
+     off-spine article plus any declared rule, so a rule remains reachable if an asset
+     later appears at its address. Ordinary addressed articles stay out because the
+     spine already reaches them. "none" is the default and is the 1.0 behavior exactly:
+     nothing is ranked or surfaced by relevance. "lexical" is BM25 over the standard
+     library. Anything needing a model is supplied here as { name, score, index? }, so
+     this package never depends on one. */
   retrieval?: RetrievalOption;
   /* How far the best-ranked article must stand out from the rest of what this same
      query touched before it may ride a message. A multiple, not a score: 2 means the
      best must score twice the best article that will not ride, the one just past the
-     per-turn cap. Default 1.4, the operating point a 120-cell study priced: it
-     matched the uncut channel's delivery to within that study's own noise floor at a
-     ninth of the suggestion volume. 1 is no cutoff and is the 1.0 behavior exactly.
+     per-turn cap. Default 1.4, the operating point a 120-cell study priced: its n=15
+     comparison with the uncut channel differed by -0.07 rule facts at p=1.0 while
+     using a ninth of the suggestion volume. That small observed contrast is not a
+     general detection bound. 1 is no cutoff and is the 1.0 behavior exactly.
 
      Relative rather than absolute because an absolute cutoff is not the same quantity
      twice. A lexical score is a fraction of the query's whole idf mass, so it falls as
@@ -44,10 +48,10 @@ export interface CanonOptions {
      and a number never did.
 
      Raising it trades recall for precision, and precision is the side to protect,
-     though the measured argument is tokens rather than attention: the same study
-     found good suggestions opened at the same rate buried among twenty-seven as one
-     of four, so what the cutoff declines to spend is context on lines that were
-     never going to be read. Ignored when retrieval is "none". */
+     though the measured argument is tokens rather than attention: a companion
+     124-cell study found good suggestions opened at similar rates buried among
+     twenty-seven as one of four, so what the cutoff declines to spend is context on
+     lines that were never going to be read. Ignored when retrieval is "none". */
   standout?: number;
 }
 
@@ -114,10 +118,10 @@ export function registerPiCanon(pi: any, options: CanonOptions = {}): void {
   pi.registerTool(buildCanonTool(ready, retriever.name));
 
   /* session_start only resets per-session state. Through 0.2.0 it also delivered an
-     orientation line; a 2x2 with an inert implementation priced that line at more
-     first-pass correctness than the whole tool schema, and the study that removed it
-     found nothing the benefit side could see. The doctrine rides the tool
-     description, which every session carries anyway. */
+     orientation line. A 2x2 with an inert implementation found significant negative
+     main effects for both that line and the tool schema, but did not resolve which
+     component cost more. Study 3 detected no benefit loss from removing the line. The
+     doctrine rides the tool description, which every session carries anyway. */
   pi.on("session_start", (_event: unknown, ctx: any) => {
     runtime = undefined;
     ready(ctx);

package/extensions/lib/retrieval.ts

@@ -1,11 +1,11 @@
-/* Retrieval: the seam for knowledge the spine cannot address.
+/* Retrieval: the seam for knowledge the ordinary spine cannot address.
 
-   The spine answers every asset-scoped question deterministically and for free, and
-   nothing here changes that. Retrieval runs over the RESIDUE, the articles whose
-   address matches no asset, which is the category 1.0 named and left open ("knowledge
-   filed off the asset path never surfaces"). That scoping is what makes an expensive
-   ranker affordable: the corpus to rank is what has no home, not the whole store, and
-   it stays small precisely because everything with a home is answered without ranking.
+   The spine answers ordinary asset-scoped questions deterministically and for free,
+   and nothing here changes that. Retrieval runs over the RESIDUE: every article whose
+   address matches no asset, plus an article declared `scope: rule` even if an asset
+   later appears at its address. That scoping completes the spine without competing
+   with it: ordinary addressed articles are answered without ranking, while a declared
+   cross-cutting rule cannot disappear because of a filesystem name collision.
 
    Two built-ins ship. `none` is 1.0 exactly and is the experiment's control. `lexical`
    is BM25 with nothing but the standard library. Anything that needs a model is
@@ -25,8 +25,9 @@ export interface Candidate {
   capsule: string;
   body: string;
   updated: string;
-  /* Whether this article SAID it is a cross-cutting rule, rather than being inferred
-     into the corpus by having no asset. See residue below. */
+  /* Whether this article SAID it is a cross-cutting rule. A declared rule qualifies
+     independently of the filesystem; an undeclared article qualifies only off-spine.
+     See residue below. */
   declared: boolean;
 }
 
@@ -290,24 +291,19 @@ export function buildRetriever(option: RetrievalOption | undefined): Retriever {
   );
 }
 
-/* The residue: articles the spine can never surface, because surfacing is triggered by
-   touching an asset and there is nothing here to touch. Everything else is already
-   answered for free and must not be ranked, or retrieval would compete with the address
-   instead of completing it.
-
-   Membership is still decided by having no asset, and that is deliberate: an article
-   unreachable by address has exactly one mechanism left, and dropping it from that
-   mechanism would lose it outright. But the set has always held two populations, and
-   until now nothing could tell them apart (Codex, 2026-08-12). One is the deliberate
-   cross-cutting rule the doctrine asks for, filed at an address naming the rule. The
-   other is an accident: a typo in an address, or an article whose asset was deleted
-   under it. Defining the corpus only by what it is not made those the same thing.
-
-   So an article may DECLARE itself with `scope: rule`, and every candidate carries
-   whether it did. Nothing here filters on it, because a declaration the agent forgot
-   must not cost it the only mechanism that can reach it. What the flag buys is honesty:
-   a declared article is a rule on purpose, an undeclared one is a question, and the two
-   stop being counted as one number. */
+/* The residue completes the spine. Every off-spine article qualifies because an asset
+   touch cannot surface it, and dropping it from retrieval would lose its only automatic
+   path. A declared `scope: rule` also qualifies if an asset later appears at the same
+   address, because the declaration says the article is cross-cutting rather than
+   governed by that coincident asset. Ordinary addressed articles stay out, or retrieval
+   would compete with deterministic address resolution.
+
+   The off-spine set itself holds two populations. One is the deliberate cross-cutting
+   rule the doctrine asks for, filed at an address naming the rule. The other is an
+   accident: a typo in an address, or an article whose asset was deleted under it. Every
+   candidate therefore carries whether it declared itself. Forgetting the declaration
+   never excludes an off-spine article; the flag makes the distinction visible and keeps
+   a declared rule eligible across a later filesystem collision. */
 export function residue(store: CanonStore, dir: string): Candidate[] {
   const out: Candidate[] = [];
   for (const path of store.list()) {

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/surfacing.ts

@@ -1,6 +1,6 @@
 /* Surfacing: tool calls stage the articles governing what they touch; the staged
-   lines flush as ONE message per turn, once per article per session. One message per
-   turn matters: pi's steering queue drains one message per provider round trip, so
+   lines flush as ONE message per turn, once while a testable presence mark remains.
+   One message per turn matters: pi's steering queue drains one message per provider round trip, so
    a message per tool call would buy each nudge its own extra LLM call.
 
    Nothing here is bounded by a character count. A session budget used to cap the
@@ -44,17 +44,16 @@ const PATHLIKE = /(?:^|[\s"'`=:,([{])(\/?[\w.@-]+(?:\/[\w.@-]+)+)/g;
    JSON escaping, whitespace rewrapping, and quoting differences between however the
    projection is rendered and however we wrote it. A short mark is not distinctive enough
    to test, so it is never expired; failing to expire only costs a re-surface that does
-   not happen, while a false expiry would spam the window. A surfaced line always carries
-   its own address and so is always long enough; only a read of a very small article is
-   not.
+   not happen, while a false expiry would spam the window. The same floor applies to
+   surfaced lines, reads, and writes; an exceptionally terse value in any path stays seen.
 
    A mark has two parts and BOTH must be in the projection.
 
    IDENTITY is the article's own address, which is in the window whichever way the
    article got there: the surfaced line reads "path: capsule" and a read prints the
    address as its title. LIVENESS is the tail of whatever actually entered, the caller
-   passing the whole of it. A surfaced line is its capsule and is held to the capsule;
-   a read is capsule plus body and is held to the body.
+   passing the whole of it. A surfaced line is held to the tail of that exact line; a
+   read is capsule plus body and is held to the body.
 
    Both parts are needed because either alone is wrong in a way that matters. Identity
    alone cannot tell a one-line nudge from the full article, which is the defect that
@@ -143,9 +142,10 @@ export class Surfacer {
 
   /* How far the best must beat the rest of the same query before anything rides. See
      retrieve(). The default is an operating point priced by a 120-cell study rather than
-     picked: at 1.4 a session kept every rule fact the uncut channel delivered at a ninth
-     of the suggestion volume, and a store with nothing relevant never reached it. 1 turns
-     the cutoff off. */
+     picked: at 1.4 the n=15 comparison with the uncut channel differed by -0.07 rule
+     facts at p=1.0 while using a ninth of the suggestion volume, and a store with nothing
+     relevant never reached it. That small observed contrast is not a general detection
+     bound. 1 turns the cutoff off. */
   private standout: number;
 
   constructor(mounts: Mount[], retriever: Retriever = NONE, resurface = true, standout = 1.4) {
@@ -282,7 +282,7 @@ export class Surfacer {
   /* This turn's intent, one entry per tool call. Kept separate from `collect` because
      they answer different questions: collect asks what asset was touched, which the
      spine answers by address, and this asks what the agent is trying to do, which is
-     the only thing an unaddressed article can be ranked against. */
+     what every article in the retrieval corpus is ranked against. */
   noteIntent(toolName: unknown, input: unknown): void {
     if (typeof toolName === "string" && toolName) this.intent.push({ toolName, input });
   }
@@ -321,8 +321,10 @@ export class Surfacer {
      ceiling it means "at least one query term appears in this article at all", which is
      a property of the query rather than a constant someone picked. `standout` is the
      tuned one. A 120-cell study priced it on a corpus with something worth finding in
-     its residue, and 1.4 held every fact the uncut channel delivered at a ninth of the
-     volume; that is the default, and the caller moves it against their own trace.
+     its residue. At 1.4 the n=15 comparison with the uncut channel differed by -0.07
+     rule facts at p=1.0 while using a ninth of the volume; that is the default, and the
+     caller moves it against their own trace. The small contrast is an observation from
+     this study, not a general detection bound.
 
      There used to be an absolute threshold here, on the grounds that a study session was
      handed 28 ranked lines and opened 5, and the scores of the opened and the ignored
@@ -571,10 +573,10 @@ export class Surfacer {
          Both are the same mistake, which is testing presence against something other than
          what was delivered.
 
-         This also retires the workaround the short-capsule case needed. A line always
-         carries its own address, so it always clears MARK_MINIMUM: `Cache.` fingerprints to
-         5 characters and its line to 39. The guard still earns its place on the other call
-         site, where a read of a tiny article really can be too short to test. */
+         This also retires the workaround the short-capsule case needed. The address and
+         date make ordinary lines testable: `Cache.` fingerprints to 5 characters and the
+         `src/core/terse` line to 39. The valid shortest case, address `a` and capsule `x`,
+         reaches only 22 and therefore keeps the conservative short-text behavior. */
       this.remember(path, line);
       this.lastFlush.set(path, entry);
       this.staged.delete(path);

package/extensions/lib/tool.ts

@@ -1,5 +1,5 @@
-/* The pi_canon tool: one tool, four verbs. Read and update over create; the journal
-   for events; map to orient. */
+/* The pi_canon tool: one tool, five verbs. Read and update over create; the journal
+   for events; map to orient; search when the agent asks. */
 
 import { existsSync } from "node:fs";
 import { basename, join } from "node:path";
@@ -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.2",
+  "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": {