@fingerskier/augment 0.4.0 → 0.5.0

package/docs/verify-memory-flow.md

@@ -1,131 +1,132 @@
-# Verifying the auto-memory flow
-
-Augment now *enforces* the memory loop through host lifecycle hooks rather than
-relying on the agent to remember to call the MCP tools:
-
-| Event              | Hook command                       | Effect |
-| ------------------ | ---------------------------------- | ------ |
-| `SessionStart`     | `augment hook session-start`       | Warms the daemon and registers the project. |
-| `UserPromptSubmit` | `augment hook user-prompt-submit`  | Recalls relevant memory and injects it as `additionalContext` **before** the model sees the prompt. |
-| `PreToolUse`       | `augment hook pre-tool-use`        | Recalls **additional** memory keyed to the matched tool action (the edited file / the Bash command) and injects it as `additionalContext`. Matcher-scoped to `Edit\|Write\|Bash` to bound the hot path; injection-only (never blocks, gates, or rewrites a tool call). Uses a raised relevance floor (`min_score` 0.45 — above the 0.4 search default, calibrated on the real model because tool queries are command/path-shaped, not prose) and injects each distinct query at most once per session. |
-| `Stop`             | `augment hook stop`                | Blocks the turn **once** with a directive to upsert a memory, then allows the stop (loop-guarded per turn). |
-
-`PreToolUse` fires before **every matched** tool call, so it is the only hook with a tool-name
-`matcher` (the others fire once per prompt/turn). Two host nuances: on Claude the injected text
-rides alongside the *tool result* on the next model request (it supplements, rather than precedes,
-the action); on Codex builds older than ~0.124.0 `PreToolUse` `additionalContext` is rejected and
-silently dropped (the tool still runs). It is purely additive — `UserPromptSubmit` remains the
-guaranteed memory path on both hosts.
-
-The same `hooks/hooks.json` ships in both the Claude Code and Codex plugins
-(Codex copied Claude's event names + stdin/stdout contract), so one set of
-handlers serves both hosts.
-
-This doc is the test process. Run the layers top-to-bottom; each is cheaper and
-more isolated than the one below it.
-
-## 1. Automated (no network, no host) — `npm test`
-
-```sh
-npm test
-```
-
-Covers:
-- `test/hooks.test.ts` — the stdin→stdout contract of every hook event
-  (UserPromptSubmit envelope, PreToolUse tool-query derivation + injection-only
-  envelope + 0.45 floor + per-session dedupe, Stop block-once loop guard,
-  fail-open paths).
-- `test/recall.test.ts` — recall degrades to `""` on any failure (a hook must
-  never break the agent).
-- `test/cli.test.ts` — the `recall` and `hook` CLI commands.
-- `test/install.test.ts` — the installer writes `hooks/hooks.json` for both hosts.
-- `test/integration/memory-flow.test.ts` — a planted memory flows
-  upsert → index → `recall()` → UserPromptSubmit **and** PreToolUse envelopes, against a **real**
-  `AugmentService` (real store + sqlite index), using the deterministic hash
-  embedder. Proves the wiring end-to-end without a model download.
-
-## 2. CLI smoke (real daemon + real embeddings, one machine)
-
-Build first, then drive the real daemon by hand. Use a throwaway memory root so
-you don't pollute your real memories:
-
-```sh
-npm run build
-export AUGMENT_MEMORY_ROOT="$(mktemp -d)"      # PowerShell: $env:AUGMENT_MEMORY_ROOT = (New-Item -ItemType Directory -Path $env:TEMP\augver -Force).FullName
-
-# Plant a memory (project_id 1 after the first init), then recall it.
-node ./dist/bin/augment.js recall "the deploy pipeline"      # prints recalled text (empty until something is stored)
-
-# Exercise the hook handlers exactly as a host would (JSON on stdin):
-echo '{"user_input":"fix the deploy pipeline","cwd":"."}' | node ./dist/bin/augment.js hook user-prompt-submit
-#   -> {"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
-
-# PreToolUse keys the query off the tool action (Bash -> command, Edit/Write -> file_path):
-echo '{"tool_name":"Bash","tool_input":{"command":"deploy the pipeline"},"cwd":"."}' | node ./dist/bin/augment.js hook pre-tool-use
-#   -> {"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
-echo '{"tool_name":"Read","tool_input":{"file_path":"x"}}' | node ./dist/bin/augment.js hook pre-tool-use
-#   -> (empty)  Read isn't in the installed matcher; even if invoked it derives a query but stays injection-only
-
-echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
-#   -> {"decision":"block","reason":"Before ending this turn, record durable memory ..."}
-echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
-#   -> (empty)  second stop for the same turn is allowed — proves the loop guard
-```
-
-The first `recall`/`hook user-prompt-submit` call auto-starts the daemon and, on
-a cold machine, downloads the bge-small model — so the very first run is slow.
-This is real-model retrieval; ranking quality (not just wiring) is what you're
-eyeballing here.
-
-Two footnotes on the examples: they omit `session_id`, which deliberately skips
-the PreToolUse once-per-session dedupe — include one to demo it. And the Stop
-loop-guard marker persists in the OS tmpdir, so re-running the stop example
-later with the same `session_id`/`prompt_id` yields empty on the *first* call
-too — use fresh ids per run.
-
-For a binding version of the ranking-quality check, `npm run test:model` runs
-the pinned real-bge abstention/recall tripwires
-(`test/real-model-abstention.model.ts`) — what this layer can otherwise only
-eyeball.
-
-## 3. Real project (host-level hook firing)
-
-1. Install into a repo (or user scope):
-   ```sh
-   npm exec --yes --package @fingerskier/augment -- augment install all --scope repo --memory-root "<your shared memory root>"
-   ```
-2. Confirm the plugin is actually installed/enabled — hooks only fire when the
-   plugin is active:
-   - **Claude Code:** `/plugin` → `augment` listed and enabled. The installer
-     best-effort-registers it via the `claude` CLI; if that was skipped, run the
-     printed `/plugin marketplace add … && /plugin install …` commands.
-   - **Codex:** plugin-shipped hooks need a **one-time trust** — run `/hooks` and
-     approve the augment hooks. (Managed/enterprise distribution can pre-trust;
-     a plain plugin install cannot.)
-3. Observe the loop on a real task:
-   - **Inject:** start a session and give a task that matches something in your
-     memory. The recalled block ("## Augment memory (recalled for this task)")
-     should appear in the model's context — confirm it influenced the answer.
-   - **Capture:** finish the task. The Stop hook should prompt the agent to
-     `upsert` a WORK/ARCH/ISSUE/TODO/SPEC memory; confirm a new file appears under
-     your memory root and that `augment recall` surfaces it next time.
-
-## Known caveats (logged, not blockers)
-
-- **Hook startup cost (resolved).** Hooks now invoke the install-time-provisioned
-  runtime directly (`node <prefix>/node_modules/@fingerskier/augment/dist/bin/augment.js
-  hook <event>`, tens of milliseconds) — the old `npm exec --yes` form paid a
-  multi-second npm bootstrap per event. Residual caveat: provisioning is
-  best-effort. If npm was missing at install time the installer prints a manual
-  `npm install --prefix <prefix> @fingerskier/augment` command and hooks fail
-  open (silent no-ops) until it is run. The MCP server itself still launches via
-  `npm exec`; only the hook hot path changed.
-- **Claude hook activation depends on plugin install.** The MCP server is also
-  direct-registered (so the tools always exist), but the hooks live in the plugin;
-  if the plugin isn't installed, the loop degrades to the CLAUDE.md prose guidance.
-- **Retrieval floor calibration (resolved).** The `(cos+1)/2` mis-normalization
-  is fixed by an empirically-anchored cosine rescale (`SEMANTIC_COSINE_BASELINE`
-  0.33), and abstention is now proven on the real model by `npm run test:model`.
-  Remaining retrieval-quality follow-ups (Phase 2 dogfood tally, credential-warn,
-  HF revision pin) are tracked in `.council/memory/retrieval-quality-roadmap.md`
-  and [ROADMAP.md](../ROADMAP.md).
+# Verifying the auto-memory flow
+
+Augment now *enforces* the memory loop through host lifecycle hooks rather than
+relying on the agent to remember to call the MCP tools:
+
+| Event              | Hook command                       | Effect |
+| ------------------ | ---------------------------------- | ------ |
+| `SessionStart`     | `augment hook session-start`       | Warms the daemon and registers the project. |
+| `UserPromptSubmit` | `augment hook user-prompt-submit`  | Recalls relevant memory and injects it as `additionalContext` **before** the model sees the prompt. |
+| `PreToolUse`       | `augment hook pre-tool-use`        | Recalls **additional** memory keyed to the matched tool action (the edited file / the Bash command) and injects it as `additionalContext`. Matcher-scoped to `Edit\|Write\|Bash` to bound the hot path; injection-only (never blocks, gates, or rewrites a tool call). Uses a raised relevance floor (`min_score` 0.45 — above the 0.4 search default, calibrated on the real model because tool queries are command/path-shaped, not prose) and injects each distinct query at most once per session. |
+| `Stop`             | `augment hook stop`                | Blocks the turn **once** with a directive to upsert a memory, then allows the stop (loop-guarded per turn). |
+
+`PreToolUse` fires before **every matched** tool call, so it is the only hook with a tool-name
+`matcher` (the others fire once per prompt/turn). Two host nuances: on Claude the injected text
+rides alongside the *tool result* on the next model request (it supplements, rather than precedes,
+the action); on Codex builds older than ~0.124.0 `PreToolUse` `additionalContext` is rejected and
+silently dropped (the tool still runs). It is purely additive — `UserPromptSubmit` remains the
+guaranteed memory path on both hosts.
+
+The same `hooks/hooks.json` ships in both the Claude Code and Codex plugins
+(Codex copied Claude's event names + stdin/stdout contract), so one set of
+handlers serves both hosts.
+
+This doc is the test process. Run the layers top-to-bottom; each is cheaper and
+more isolated than the one below it.
+
+## 1. Automated (no network, no host) — `npm test`
+
+```sh
+npm test
+```
+
+Covers:
+- `test/hooks.test.ts` — the stdin→stdout contract of every hook event
+  (UserPromptSubmit envelope, PreToolUse tool-query derivation + injection-only
+  envelope + 0.45 floor + per-session dedupe, Stop block-once loop guard,
+  fail-open paths).
+- `test/recall.test.ts` — recall degrades to `""` on any failure (a hook must
+  never break the agent).
+- `test/cli.test.ts` — the `recall` and `hook` CLI commands.
+- `test/install.test.ts` — the installer writes `hooks/hooks.json` for both hosts.
+- `test/integration/memory-flow.test.ts` — a planted memory flows
+  upsert → index → `recall()` → UserPromptSubmit **and** PreToolUse envelopes, against a **real**
+  `AugmentService` (real store + sqlite index), using the deterministic hash
+  embedder. Proves the wiring end-to-end without a model download.
+
+## 2. CLI smoke (real daemon + real embeddings, one machine)
+
+Build first, then drive the real daemon by hand. Use a throwaway memory root so
+you don't pollute your real memories:
+
+```sh
+npm run build
+export AUGMENT_MEMORY_ROOT="$(mktemp -d)"      # PowerShell: $env:AUGMENT_MEMORY_ROOT = (New-Item -ItemType Directory -Path $env:TEMP\augver -Force).FullName
+
+# Plant a memory (project_id 1 after the first init), then recall it.
+node ./dist/bin/augment.js recall "the deploy pipeline"      # prints recalled text (empty until something is stored)
+
+# Exercise the hook handlers exactly as a host would (JSON on stdin):
+echo '{"user_input":"fix the deploy pipeline","cwd":"."}' | node ./dist/bin/augment.js hook user-prompt-submit
+#   -> {"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
+
+# PreToolUse keys the query off the tool action (Bash -> command, Edit/Write -> file_path):
+echo '{"tool_name":"Bash","tool_input":{"command":"deploy the pipeline"},"cwd":"."}' | node ./dist/bin/augment.js hook pre-tool-use
+#   -> {"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
+echo '{"tool_name":"Read","tool_input":{"file_path":"x"}}' | node ./dist/bin/augment.js hook pre-tool-use
+#   -> (empty)  Read isn't in the installed matcher; even if invoked it derives a query but stays injection-only
+
+echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
+#   -> {"decision":"block","reason":"Before ending this turn, record durable memory ..."}
+echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
+#   -> (empty)  second stop for the same turn is allowed — proves the loop guard
+```
+
+The first `recall`/`hook user-prompt-submit` call auto-starts the daemon and, on
+a cold machine, downloads the bge-small model — so the very first run is slow.
+This is real-model retrieval; ranking quality (not just wiring) is what you're
+eyeballing here.
+
+Two footnotes on the examples: they omit `session_id`, which deliberately skips
+the PreToolUse once-per-session dedupe — include one to demo it. And the Stop
+loop-guard marker persists in the OS tmpdir, so re-running the stop example
+later with the same `session_id`/`prompt_id` yields empty on the *first* call
+too — use fresh ids per run.
+
+For a binding version of the ranking-quality check, `npm run test:model` runs
+the pinned real-bge abstention/recall tripwires
+(`test/real-model-abstention.model.ts`) — what this layer can otherwise only
+eyeball.
+
+## 3. Real project (host-level hook firing)
+
+1. Install into a repo (or user scope):
+   ```sh
+   npm exec --yes --package @fingerskier/augment -- augment install all --scope repo --memory-root "<your shared memory root>"
+   ```
+2. Confirm the plugin is actually installed/enabled — hooks only fire when the
+   plugin is active:
+   - **Claude Code:** `/plugin` → `augment` listed and enabled. The installer
+     best-effort-registers it via the `claude` CLI; if that was skipped, run the
+     printed `/plugin marketplace add … && /plugin install …` commands.
+   - **Codex:** plugin-shipped hooks need a **one-time trust** — run `/hooks` and
+     approve the augment hooks. (Managed/enterprise distribution can pre-trust;
+     a plain plugin install cannot.)
+3. Observe the loop on a real task:
+   - **Inject:** start a session and give a task that matches something in your
+     memory. The recalled block ("## Augment memory (recalled for this task)")
+     should appear in the model's context — confirm it influenced the answer.
+   - **Capture:** finish the task. The Stop hook should prompt the agent to
+     `upsert` a WORK/ARCH/ISSUE/TODO/SPEC memory; confirm a new file appears under
+     your memory root and that `augment recall` surfaces it next time.
+
+## Known caveats (logged, not blockers)
+
+- **Hook startup cost (resolved).** Hooks now invoke the install-time-provisioned
+  runtime directly (`node <prefix>/node_modules/@fingerskier/augment/dist/bin/augment.js
+  hook <event>`, tens of milliseconds) — the old `npm exec --yes` form paid a
+  multi-second npm bootstrap per event. Residual caveat: provisioning is
+  best-effort. If npm was missing at install time the installer prints a manual
+  `npm install --prefix <prefix> @fingerskier/augment` command and hooks fail
+  open (silent no-ops) until it is run. The MCP server itself still launches via
+  `npm exec`; only the hook hot path changed.
+- **Claude hook activation depends on plugin install.** The MCP server is also
+  direct-registered (so the tools always exist), but the hooks live in the plugin;
+  if the plugin isn't installed, the loop degrades to the CLAUDE.md prose guidance.
+- **Retrieval floor calibration (resolved).** The `(cos+1)/2` mis-normalization
+  is fixed by an empirically-anchored cosine rescale (`SEMANTIC_COSINE_BASELINE`
+  0.33), and abstention is now proven on the real model by `npm run test:model`.
+  Remaining retrieval-quality follow-ups (ordinary-upsert credential warnings
+  and HF revision pinning) are tracked in
+  `.council/memory/retrieval-quality-roadmap.md` and
+  [ROADMAP.md](../ROADMAP.md).

package/integrations/claude/skills/augment-decoction/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: augment-decoction
+description: Distill recurring cross-project memory into generic SPEC/ARCH records and optionally remove fully subsumed originals. Use when the user asks to "decoct", "glean", generalize, or clean up repeated memories across projects.
+---
+
+# Augment Decoction
+
+Decoction extracts durable, project-independent knowledge from recurring
+memories. It is separate from sleep: sleep consolidates settled work within one
+project, while decoction finds patterns across projects and writes them under
+`.generic/`.
+
+1. Call `decoction_glean` with `action: "discover"`. If no cluster spans at
+   least four distinct projects, report that and stop.
+2. Pick a cluster and `read` every source. Synthesize one generic record:
+   - use SPEC for a reusable contract or rule;
+   - use ARCH for a reusable decision or tradeoff;
+   - retain only claims supported across the projects;
+   - put every source used in `derived_from`.
+3. Suggest source removal only when the generic preserves the original's entire
+   durable content. Do not suggest a source that also contains project-specific
+   facts, history, caveats, or unresolved work.
+4. Call `decoction_glean` with `action: "write"`, the complete draft, and the
+   reasoned `suggested_removals`. For an existing generic, read it fresh and
+   pass both of its expected hashes.
+5. Report the generic path and any warnings. Warnings are advisory and do not
+   block the write.
+6. Show each suggested cleanup path and reason verbatim. Ask for explicit user
+   approval of the exact paths; never infer approval from approval of the
+   generic itself.
+7. Only after approval, call `decoction_cleanup` with the generic path and the
+   approved source paths. Report every deletion and any failure.
+
+Cleanup hard-deletes the selected originals after retargeting inbound links to
+the generic. It has no journal or rollback. The user may approve a subset or
+decline cleanup entirely.

package/integrations/claude/skills/augment-dream/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: augment-dream
+description: Explore globally recalled Augment memories and propose speculative memories or links for explicit user approval. Use when the user asks to "dream" over memory, imagine hypotheses, or surface hidden connections across the current, generic, or foreign projects.
+---
+
+# Augment Dream
+
+Dreams are hypotheses, not established facts. Discover and draft freely, but
+never mutate the corpus before the user explicitly approves a named proposal.
+Use a real project as the active project; `.generic` is inspiration or a link
+target only.
+
+1. Call `search` separately for each exploratory query, always passing the
+   active `project_name` and the singular `query` argument. Use normal global
+   results as ranked: the current project receives its normal priority, while
+   generic and foreign memories remain eligible.
+   Do not reserve a generic quota or add a generic fallback.
+2. Call `read` with each useful result's numeric memory id, and retain its
+   returned relative path for provenance. Imagine 1-5 coherent candidates:
+   - dream memory: a new record in the active project, with `derived_from`
+     equal to the exact inspiration paths;
+   - dream link: a link from an active-project memory to any current, generic,
+     or foreign memory.
+   Generic-only and foreign-only inspiration are valid.
+3. Call `dream_propose` for each worthwhile candidate. State the speculation
+   plainly in the content and rationale; do not present it as settled truth.
+4. Show each proposal to the user. Only after explicit approval call
+   `dream_apply` with its filename. Call `dream_reject` when the user rejects
+   it. If approval is unclear, leave the proposal pending.
+5. Report the applied speculative memory or link and its `dream:` commit.
+
+Keep evidence and conjecture distinguishable. Do not invent supporting source
+paths, and do not rewrite a foreign memory: foreign projects are inspiration
+and link targets only.

package/integrations/claude/skills/augment-dream/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Augment Dream"
+  short_description: "Propose speculative memory connections"
+  default_prompt: "Use $augment-dream to explore memory and propose speculative memories or links for my approval."

package/integrations/codex/SKILL.md

@@ -52,6 +52,39 @@ After creating or updating a memory:
 2. Prefer linking new `WORK` notes to the `SPEC`, `ARCH`, `ISSUE`, or `TODO`
    they address.
 
+## Decoction
+
+When the user asks to decoct, glean, or generalize cross-project memory:
+
+1. Call `decoction_glean` with `action: "discover"`, then read every source in
+   the selected cluster.
+2. Draft one reusable SPEC or ARCH under `.generic/`, keeping only claims
+   supported across the projects and listing every source in `derived_from`.
+3. Suggest removal only for originals whose entire durable content the generic
+   preserves. Call `decoction_glean` with `action: "write"`; report advisory
+   warnings without treating them as write failures. When updating an existing
+   generic, read it fresh and pass both expected hashes.
+4. Show the exact suggested paths and reasons. Call `decoction_cleanup` only
+   after explicit approval of those paths; the hard deletes have no rollback.
+
+Decoction is separate from sleep: sleep consolidates settled work inside one
+project, while decoction extracts reusable knowledge across projects.
+
+## Dreaming
+
+When the user asks to dream over memory or surface speculative connections:
+
+1. Search globally with the current project context, then read the relevant
+   current, generic, and foreign memories.
+2. Call `dream_propose` for each candidate memory or link. Dream memories land
+   in the current real project (`.generic` is never active); dream links start
+   there but may target another project. State what evidence inspired the idea
+   and what remains unverified.
+3. Present each editable proposal. Call `dream_apply` only after explicit user
+   approval; otherwise call `dream_reject`.
+
+Never present a dream as established fact.
+
 ## Session Finish
 
 For almost every session that did real work (skip only pure Q&A, read-only

package/integrations/pi/skills/augment-decoction/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: augment-decoction
+description: Distill recurring cross-project Augment memory into generic SPEC/ARCH records and optionally remove fully subsumed originals from Pi. Use when the user asks to "decoct", "glean", generalize, or clean up repeated memories across projects.
+---
+
+# Augment Decoction for Pi
+
+Decoction extracts durable, project-independent knowledge from recurring
+memories. It is separate from sleep: sleep consolidates settled work within one
+project, while decoction finds patterns across projects and writes them under
+`.generic/`.
+
+1. Call `augment_decoction_glean` with `action: "discover"`. If no cluster
+   spans at least four distinct projects, report that and stop.
+2. Pick a cluster and call `augment_read_memory` for every source. Synthesize
+   one generic record:
+   - use SPEC for a reusable contract or rule;
+   - use ARCH for a reusable decision or tradeoff;
+   - retain only claims supported across the projects;
+   - put every source used in `derived_from`.
+3. Suggest source removal only when the generic preserves the original's entire
+   durable content. Do not suggest a source that also contains project-specific
+   facts, history, caveats, or unresolved work.
+4. Call `augment_decoction_glean` with `action: "write"`, the complete draft,
+   and the reasoned `suggested_removals`. For an existing generic, read it fresh
+   and pass both of its expected hashes.
+5. Report the generic path and any warnings. Warnings are advisory and do not
+   block the write.
+6. Show each suggested cleanup path and reason verbatim. Ask for explicit user
+   approval of the exact paths; never infer approval from approval of the
+   generic itself.
+7. Only after approval, call `augment_decoction_cleanup` with the generic path
+   and the approved source paths. Report every deletion and any failure.
+
+Cleanup hard-deletes the selected originals after retargeting inbound links to
+the generic. It has no journal or rollback. The user may approve a subset or
+decline cleanup entirely.

package/integrations/pi/skills/augment-dream/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: augment-dream
+description: Explore globally recalled Augment memories and propose speculative memories or links for explicit user approval. Use when the user asks to "dream" over memory, imagine hypotheses, or surface hidden connections across the current, generic, or foreign projects.
+---
+
+# Augment Dream
+
+Dreams are hypotheses, not established facts. Discover and draft freely, but
+never mutate the corpus before the user explicitly approves a named proposal.
+Use a real project as the active project; `.generic` is inspiration or a link
+target only.
+
+1. Call `augment_search` separately for each exploratory query, always passing
+   the active `project_name` and singular `query` argument. Use normal global
+   results as ranked: the current project receives its normal priority, while
+   generic and foreign memories remain eligible. Do not reserve a generic
+   quota or add a generic fallback.
+2. Call `augment_read_memory` with each useful result's numeric memory id, and
+   retain its returned relative path for provenance. Imagine 1-5 coherent
+   candidates:
+   - dream memory: a new record in the active project, with `derived_from`
+     equal to the exact inspiration paths;
+   - dream link: a link from an active-project memory to any current, generic,
+     or foreign memory.
+   Generic-only and foreign-only inspiration are valid.
+3. Call `augment_dream_propose` for each worthwhile candidate. State the
+   speculation plainly in the content and rationale; do not present it as
+   settled truth.
+4. Show each proposal to the user. Only after explicit approval call
+   `augment_dream_apply` with its filename. Call `augment_dream_reject` when
+   the user rejects it. If approval is unclear, leave the proposal pending.
+5. Report the applied speculative memory or link and its `dream:` commit.
+
+Keep evidence and conjecture distinguishable. Do not invent supporting source
+paths, and do not rewrite a foreign memory: foreign projects are inspiration
+and link targets only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fingerskier/augment",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Local RAG memory system for coding agents",
   "keywords": [
     "pi-package",
@@ -38,7 +38,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "clean": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
     "test": "node --import tsx --test \"test/**/*.test.ts\"",
     "test:model": "node --import tsx --import ./test/setup-real-model.mjs --test \"test/**/*.model.ts\"",
     "check": "npm run build && npm test",

package/dist/tally.d.ts

@@ -1,46 +0,0 @@
-/**
- * Phase-2 dogfood tally (council 2026-06-30): ~30 human-scored datapoints over
- * ~2 weeks of real use, per injection surface, never a CI gate. Data lives as
- * JSONL under `<stateDir>/tally/` — deliberately OUTSIDE the memory corpus so
- * the corpus Phase 2 measures stays clean.
- */
-export declare const TALLY_TARGET = 30;
-export declare const TALLY_VERDICTS: readonly ["helpful", "harmless", "harmful", "correct-abstention"];
-export type TallyVerdict = (typeof TALLY_VERDICTS)[number];
-/** One human rating of a recall outcome. */
-export interface TallyRating {
-    ts: string;
-    verdict: TallyVerdict;
-    /** Injection surface being rated: user-prompt-submit | pre-tool-use | mcp-search | cli-recall | unknown. */
-    surface: string;
-    note?: string;
-}
-/** One automatically-logged injection event (what search actually returned). */
-export interface TallyEvent {
-    ts: string;
-    surface: string;
-    project?: string;
-    /** Query text, truncated by the writer — context for later audit, not for ranking. */
-    query: string;
-    abstained: boolean;
-    result_count: number;
-    top_score?: number;
-    /** Durable relative paths of the memories injected. */
-    paths: string[];
-}
-export interface TallySummary {
-    total: number;
-    target: number;
-    by_verdict: Record<TallyVerdict, number>;
-    by_surface: Record<string, number>;
-    first_at?: string;
-    last_at?: string;
-}
-export declare function isTallyVerdict(value: unknown): value is TallyVerdict;
-export declare function ratingsPath(stateDir: string): string;
-export declare function eventsPath(stateDir: string): string;
-export declare function appendTallyRating(stateDir: string, rating: TallyRating): Promise<void>;
-export declare function appendTallyEvent(stateDir: string, event: TallyEvent): Promise<void>;
-export declare function readTallyRatings(stateDir: string): Promise<TallyRating[]>;
-export declare function summarizeTally(ratings: TallyRating[]): TallySummary;
-export declare function renderTallySummary(summary: TallySummary): string;

package/dist/tally.js

@@ -1,94 +0,0 @@
-import { appendFile, mkdir, readFile } from "node:fs/promises";
-import path from "node:path";
-/**
- * Phase-2 dogfood tally (council 2026-06-30): ~30 human-scored datapoints over
- * ~2 weeks of real use, per injection surface, never a CI gate. Data lives as
- * JSONL under `<stateDir>/tally/` — deliberately OUTSIDE the memory corpus so
- * the corpus Phase 2 measures stays clean.
- */
-export const TALLY_TARGET = 30;
-export const TALLY_VERDICTS = ["helpful", "harmless", "harmful", "correct-abstention"];
-export function isTallyVerdict(value) {
-    return typeof value === "string" && TALLY_VERDICTS.includes(value);
-}
-export function ratingsPath(stateDir) {
-    return path.join(stateDir, "tally", "ratings.jsonl");
-}
-export function eventsPath(stateDir) {
-    return path.join(stateDir, "tally", "events.jsonl");
-}
-async function appendLine(file, record) {
-    await mkdir(path.dirname(file), { recursive: true });
-    await appendFile(file, `${JSON.stringify(record)}\n`, "utf8");
-}
-export async function appendTallyRating(stateDir, rating) {
-    await appendLine(ratingsPath(stateDir), rating);
-}
-export async function appendTallyEvent(stateDir, event) {
-    await appendLine(eventsPath(stateDir), event);
-}
-export async function readTallyRatings(stateDir) {
-    let raw;
-    try {
-        raw = await readFile(ratingsPath(stateDir), "utf8");
-    }
-    catch {
-        return [];
-    }
-    const ratings = [];
-    for (const line of raw.split("\n")) {
-        if (!line.trim()) {
-            continue;
-        }
-        try {
-            const parsed = JSON.parse(line);
-            if (isTallyVerdict(parsed.verdict)) {
-                ratings.push(parsed);
-            }
-        }
-        catch {
-            // A corrupt line loses one datapoint, never the tally.
-        }
-    }
-    return ratings;
-}
-export function summarizeTally(ratings) {
-    const by_verdict = {
-        helpful: 0,
-        harmless: 0,
-        harmful: 0,
-        "correct-abstention": 0,
-    };
-    const by_surface = {};
-    for (const rating of ratings) {
-        by_verdict[rating.verdict] += 1;
-        by_surface[rating.surface || "unknown"] = (by_surface[rating.surface || "unknown"] ?? 0) + 1;
-    }
-    return {
-        total: ratings.length,
-        target: TALLY_TARGET,
-        by_verdict,
-        by_surface,
-        ...(ratings.length > 0
-            ? { first_at: ratings[0].ts, last_at: ratings[ratings.length - 1].ts }
-            : {}),
-    };
-}
-export function renderTallySummary(summary) {
-    const lines = [
-        `Dogfood tally: ${summary.total}/${summary.target} datapoints`,
-        `  helpful: ${summary.by_verdict.helpful}  harmless: ${summary.by_verdict.harmless}  ` +
-            `harmful: ${summary.by_verdict.harmful}  correct-abstention: ${summary.by_verdict["correct-abstention"]}`,
-    ];
-    const surfaces = Object.entries(summary.by_surface)
-        .map(([surface, count]) => `${surface}:${count}`)
-        .join("  ");
-    if (surfaces) {
-        lines.push(`  by surface: ${surfaces}`);
-    }
-    if (summary.first_at && summary.last_at) {
-        lines.push(`  window: ${summary.first_at} .. ${summary.last_at}`);
-    }
-    return lines.join("\n");
-}
-//# sourceMappingURL=tally.js.map

package/dist/tally.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tally.js","sourceRoot":"","sources":["../src/tally.ts"],"names":[],"mappings":"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"}