feat: add PAM 0.5.0 file-only coverage gate

CHANGELOG.md

@@ -2,7 +2,46 @@
 
 ## Unreleased
 
-## 0.4.0 - 2026-05-28
+## 0.5.0 - 2026-05-27
+
+PAM 0.5.0 adds a measurable file-only retrieval gate for agents that cannot use
+semantic memory search. The graph schema remains `pam-graph-v1`; this release
+also includes the migration-enforcement tooling introduced after 0.3.0.
+
+### Added
+
+- `memory:graph:coverage` CLI for graph-first coverage reports.
+- Default file-only coverage scenario at `benchmarks/file-only-coverage.json`.
+- Migration guide for 0.4.0 users adopting file-only coverage.
+- Runtime guidance requiring graph-first lookup before broad corpus scans.
+
+### Improved
+
+- Graph memory now includes aliases and nodes for the coverage scenario.
+- Coverage output reports aggregate read volume, targeted source counts, hit
+  rate, and `PASS` / `PARTIAL` / `BLOCKED` status without raw source text or
+  absolute paths.
+- README documents the default 5-file / 100 KB graph-first budget and 80% hit
+  rate target.
+
+### Compatibility
+
+- `memoryFormat` remains `graph-v1`.
+- `graphSchemaVersion` remains `pam-graph-v1`.
+- Existing 0.4.0 graph JSONL files remain valid.
+
+### Added: Kimi Code CLI integration
+
+- `tools/kimi/install-mcp.mjs` registers the PAM MCP server with Kimi Code CLI
+  by writing an absolute-path entry into `~/.kimi/mcp.json`.
+- `tools/kimi/templates/mcp.fragment.json` is the config template used by the
+  installer.
+- `tools/kimi/docs/pam-kimi-layer.md` covers install, verify, uninstall, and
+  ad-hoc `--mcp-config-file` usage.
+- `npm run kimi:mcp:install` shortcut for the installer.
+- `docs/mcp-server.md` and `AGENT_BOOTSTRAP.md` gain Kimi-specific sections.
+
+## 0.4.0 - 2026-05-21
 
 PAM 0.4.0 ships the optional agent layer end-to-end: a local stdio MCP
 server, the curator and scribe reference subagents, and a Claude Code
@@ -64,18 +103,6 @@ existing 0.3.0 graph-v1 workspaces work without modification.
 - `tools/claude/install-statusline.mjs` (`npm run claude:statusline:install`) for
   users who want only the statusline without the full plugin.
 
-### Added: Kimi Code CLI integration
-
-- `tools/kimi/install-mcp.mjs` registers the PAM MCP server with Kimi Code
-  CLI by writing an absolute-path entry into `~/.kimi/mcp.json`.
-- `tools/kimi/templates/mcp.fragment.json` is the config template used by
-  the installer.
-- `tools/kimi/docs/pam-kimi-layer.md` covers install, verify, uninstall,
-  and ad-hoc `--mcp-config-file` usage.
-- `npm run kimi:mcp:install` shortcut for the installer.
-- `docs/mcp-server.md` and `AGENT_BOOTSTRAP.md` gain Kimi-specific
-  sections.
-
 ### Added: Docs and tests
 
 - `docs/mcp-server.md` (generic MCP docs), `tools/claude/docs/curator-agent.md`,
@@ -88,10 +115,9 @@ existing 0.3.0 graph-v1 workspaces work without modification.
 
 ### Compatibility
 
-The markdown + JSONL contract is unchanged; the new layer is additive
-runtime. Existing 0.3.1 graph-v1 workspaces work unchanged, including agents
-that read `memory/` by hand without the MCP server. See
-`migrations/0.3.1-to-0.4.0-agent-layer.md` for the version-bump checklist.
+No migration required. The markdown + JSONL contract is unchanged; the new
+layer is additive runtime. Existing 0.3.0 graph-v1 workspaces work unchanged,
+including agents that read `memory/` by hand without the MCP server.
 
 ### Privacy
 

README.md

@@ -57,6 +57,9 @@ The important pieces are:
 - [tools/memory-maintenance.mjs](tools/memory-maintenance.mjs): optional
   maintenance CLI for rotating logs, rebuilding archive indexes, and refreshing
   summaries.
+- [benchmarks/file-only-coverage.json](benchmarks/file-only-coverage.json):
+  default smoke scenario for testing graph-first retrieval with file-only
+  agents.
 
 ## Who It Is For
 
@@ -224,6 +227,7 @@ Commands:
 ```bash
 npm test
 npm run memory:graph:validate
+npm run memory:graph:coverage -- --json
 npm run memory:graph:query -- --q PAM --json
 npm run memory:detect -- --json
 npm run benchmark:current
@@ -259,6 +263,28 @@ The optional `memory:graph:*` scripts validate and query this data, but agents
 can also use plain text search or any JSONL parser. Node is not required to read
 or manually update the memory.
 
+### File-Only Coverage
+
+PAM 0.5.0 adds a file-only coverage check for agents that do not have semantic
+memory search. It compares the graph-first read path against a broad corpus
+scan and verifies that realistic queries resolve through aliases/nodes before
+opening long source files.
+
+```bash
+npm run memory:graph:coverage -- --json
+```
+
+The default budget is:
+
+- maximum 5 graph files before source fallback;
+- maximum 100 KB before source fallback;
+- maximum 1 targeted source file per query;
+- at least 80% `PASS` results in the scenario.
+
+Add project-specific queries to a JSON scenario and pass it with
+`--scenario <path>`. The coverage output is aggregate-only: it reports paths,
+byte counts, statuses, and node ids, not raw source text.
+
 ## Benchmarks
 
 The benchmark tool records aggregate public metrics only: file counts, bytes,
@@ -290,6 +316,17 @@ The benchmark is a read-volume proxy, not a model billing report. It estimates
 the amount of text an agent needs to inspect for the same generic memory lookup
 path before and after graph-v1.
 
+## OpenClaw Daily Graph Maintenance
+
+For OpenClaw-style workspaces, recurring PAM maintenance should keep the graph
+useful as a compact knowledge map. It should validate the graph, scan recent
+durable memory, promote safe source-traced records, update the catalog, and
+write a concise maintenance report.
+
+It should not be only an installation acceptance-criteria checklist. See
+[docs/openclaw-daily-graph-maintenance.md](docs/openclaw-daily-graph-maintenance.md)
+for the reusable runbook.
+
 ## Maintenance Safety Model
 
 The maintenance tool is conservative:

benchmarks/file-only-coverage.json

@@ -0,0 +1,26 @@
+{
+  "name": "PAM file-only coverage smoke",
+  "description": "Queries an agent should route through graph files before opening long sources.",
+  "queries": [
+    {
+      "q": "PAM",
+      "expectedId": "project:pam"
+    },
+    {
+      "q": "runtime guide",
+      "expectedId": "doc:runtime"
+    },
+    {
+      "q": "graph cli",
+      "expectedId": "tool:graph"
+    },
+    {
+      "q": "markdown migration",
+      "expectedId": "migration:markdown-to-graph-v1"
+    },
+    {
+      "q": "agent-facing runbooks",
+      "expectedId": "principle:agent-facing-runbooks"
+    }
+  ]
+}

docs/openclaw-daily-graph-maintenance.md

@@ -0,0 +1,111 @@
+# OpenClaw Daily Graph Maintenance
+
+Use this runbook when PAM is installed in an OpenClaw-style workspace and the
+runtime supports scheduled agent jobs.
+
+The maintenance job must keep the PAM graph useful as a compact, source-traced
+knowledge map. It must not degrade into an installation acceptance checklist.
+Acceptance criteria are useful during setup and audits, but daily maintenance is
+about validating, scanning, and promoting safe graph updates.
+
+## Scope
+
+Default writable paths:
+
+```text
+memory/graph/catalog.json
+memory/graph/nodes.jsonl
+memory/graph/edges.jsonl
+memory/graph/aliases.jsonl
+memory/maintenance/
+```
+
+Do not rewrite OpenClaw-owned or project-owned sources by default, including:
+
+```text
+MEMORY.md
+memory/**/*.md
+compiled wiki pages
+AGENTS.md
+project-specific memory conventions
+```
+
+If a useful update requires a non-PAM-owned write, report it as blocked and ask
+for explicit approval.
+
+## Daily job flow
+
+1. Read local policy first, then `memory/pam.version.json`,
+   `memory/agent-memory/pam-runtime.md`, `memory/agent-memory/pam-openclaw.md`,
+   and `memory/graph/catalog.json`.
+2. Validate `memory/graph/*.jsonl`.
+3. Read the latest PAM maintenance report to establish the previous state.
+4. Do a bounded scan of recent durable memory since the previous run, usually
+   the last 24-48 hours.
+5. Promote only stable, useful, non-sensitive records into the graph:
+   projects, systems, decisions, tasks, risks, blockers, packages,
+   repositories, policies, and automations.
+6. Upsert records with stable ids such as `project:*`, `system:*`,
+   `decision:*`, `risk:*`, `blocker:*`, `task:*`, `package:*`, `repo:*`, and
+   `automation:*`.
+7. Keep every node and edge compact and source-traced.
+8. Update `catalog.json` counts and health.
+9. Validate again.
+10. Write `memory/maintenance/pam-daily-maintenance-YYYY-MM-DD.md` with graph
+    changes, highlights, skipped candidates, blockers, validation status, and next
+    action.
+
+## Highlights
+
+Every scheduled report should include a short highlights section summarizing the
+important memories found during the scan. Highlights are for the human reader,
+not for schema bookkeeping.
+
+Good highlights are:
+
+- 3-7 bullets;
+- public-safe and non-sensitive;
+- focused on durable meaning: decisions, blockers, risks, project state,
+  published artifacts, or changed operational posture;
+- sourced by the same scanned memory used for graph promotion.
+
+Avoid highlights that expose raw private messages, secrets, webhook values, full
+paths to secret stores, or noisy implementation minutiae. If nothing meaningful
+was found, say that directly and name the bounded scan window.
+
+## Safety rules
+
+- Do not store secrets, credentials, tokens, webhook URLs, cookies, private
+  keys, raw private chat, or secret-store paths.
+- Prefer source pointers over copied detail.
+- Treat chronological logs and transcripts as source material, not graph content
+  by default.
+- In shared contexts, avoid private profile/preference details unless the user
+  explicitly approves them.
+- If validation fails, fix only PAM-owned files or roll back the PAM-owned
+  change and report `BLOCKED`.
+
+## Report format
+
+Use a concise human-facing report. Example:
+
+```text
+PAM daily maintenance — YYYY-MM-DD HH:mm UTC
+Status: 🟢 OK | 🟡 WARNING | 🔴 BLOCKED
+
+Highlights:
+- Approval policy was promoted as an active project memory.
+- Chat ingestion remains blocked by platform access.
+- A runtime security posture item remains a P1 risk.
+
+Checks:
+- 🟢 Graph validation — passed, 0 errors / 0 warnings.
+- 🟢 Graph updates — added 3 nodes, 4 edges, 2 aliases.
+- 🟡 Recent memory scan — skipped 2 private or unstable candidates.
+- 🟢 Safety — wrote only PAM-owned paths; no secrets or raw chat stored.
+- Next action: review `blocker:example` before tomorrow's run.
+```
+
+Do not make the daily report an acceptance-criteria-only checklist. Acceptance
+criteria are secondary health evidence; real graph maintenance is the primary
+job.

memory/agent-memory/pam-openclaw.md

@@ -135,6 +135,35 @@ If uncertain, report `unknown` or `partial`; do not force OpenClaw specializatio
 9. Report the PAM installation acceptance criteria one by one before claiming completion.
 
 
+## Runtime-native graph maintenance
+
+When OpenClaw cron or another runtime-native scheduler is configured for PAM,
+the recurring job SHOULD perform real graph maintenance, not only repeat the
+installation acceptance criteria.
+
+Daily or near-daily maintenance should:
+
+1. Validate `memory/graph/*.jsonl`.
+2. Read the latest PAM maintenance report to identify the previous state.
+3. Do a bounded scan of recent durable memory, usually the last 24-48 hours or
+   since the previous maintenance run.
+4. Promote only stable, useful, non-sensitive records into PAM-owned graph files.
+5. Prefer entities and relations such as projects, systems, decisions, tasks,
+   risks, blockers, packages, repositories, policies, dependencies, and
+   automations.
+6. Keep every graph record compact and source-traced.
+7. Update `catalog.json`, validate again, and write a concise report under
+   `memory/maintenance/`.
+8. Include a short highlights section with 3-7 public-safe bullets summarizing
+   the most important memories found, promoted, skipped, or blocked.
+
+The daily report may include acceptance/status checks, but those checks are
+secondary. It should also include human-readable highlights. If no graph
+candidates were found, the report should say what was scanned and why nothing
+was promoted.
+
+For a reusable job runbook, see `docs/openclaw-daily-graph-maintenance.md`.
+
 ## OpenClaw-specific installation acceptance criteria
 
 In addition to the generic PAM installation criteria, an OpenClaw workspace must

memory/agent-memory/pam-runtime.md

@@ -16,6 +16,29 @@ completion.
 6. If `memory/agent-memory/pam-openclaw.md` exists and the workspace has
    OpenClaw-style memory, read it before proposing memory writes or migrations.
 
+## File-Only Efficiency Gate
+
+When the agent has only file read/search tools, PAM should still reduce
+retrieval cost. For memory, project, task, decision, or procedure questions:
+
+- Use the graph-first path above before scanning broad markdown corpora.
+- Keep initial routing to `memory/pam.version.json`, `memory/graph/catalog.json`,
+  `aliases.jsonl`, `nodes.jsonl`, and `edges.jsonl`.
+- Follow at most one source file from the best matching node before falling
+  back to a wider search.
+- Treat missing aliases, stale statuses, and broad fallback as coverage gaps to
+  record in the next maintenance pass.
+
+Validate this behavior with:
+
+```bash
+npm run memory:graph:coverage -- --json
+```
+
+Default acceptance target: at least 80% of realistic queries should route to
+the expected node with no more than 5 graph files and 100 KB read before source
+fallback.
+
 ## Direct JSONL Fallback
 
 Node tools are optional. Without Node, use any text search or JSONL parser:

memory/graph/aliases.jsonl

@@ -7,6 +7,11 @@
 {"a":"maintenance cli","id":"tool:maintenance"}
 {"a":"graph cli","id":"tool:graph"}
 {"a":"benchmark cli","id":"tool:benchmark"}
+{"a":"file-only coverage","id":"tool:file-only-coverage"}
+{"a":"coverage cli","id":"tool:file-only-coverage"}
+{"a":"file-only agent benchmark","id":"tool:file-only-coverage"}
 {"a":"markdown migration","id":"migration:markdown-to-graph-v1"}
+{"a":"0.5.0 migration","id":"migration:0.5-file-only-coverage"}
+{"a":"PAM 0.5.0","id":"migration:0.5-file-only-coverage"}
 {"a":"agent-facing runbooks","id":"principle:agent-facing-runbooks"}
 {"a":"runbook quality gate","id":"principle:agent-facing-runbooks"}

memory/graph/catalog.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": "pam-graph-v1",
-  "generatedAt": "2026-05-21T18:13:47.933Z",
-  "nodeCount": 12,
-  "edgeCount": 13,
-  "aliasCount": 12,
+  "generatedAt": "2026-05-22T16:17:27.591Z",
+  "nodeCount": 14,
+  "edgeCount": 17,
+  "aliasCount": 17,
   "sourceFiles": [
     "memory/graph/nodes.jsonl",
     "memory/graph/edges.jsonl",

memory/graph/edges.jsonl

@@ -5,9 +5,13 @@
 {"f":"project:pam","r":"has-tool","t":"tool:maintenance","st":"confirmed","c":"high","u":"2026-05-05","src":"package.json"}
 {"f":"project:pam","r":"has-tool","t":"tool:graph","st":"confirmed","c":"high","u":"2026-05-05","src":"package.json"}
 {"f":"project:pam","r":"has-tool","t":"tool:benchmark","st":"confirmed","c":"high","u":"2026-05-05","src":"package.json"}
+{"f":"project:pam","r":"has-tool","t":"tool:file-only-coverage","st":"confirmed","c":"high","u":"2026-05-22","src":"package.json"}
+{"f":"tool:file-only-coverage","r":"tests-format","t":"format:graph-v1","st":"confirmed","c":"high","u":"2026-05-22","src":"tools/memory-graph.mjs"}
 {"f":"project:pam","r":"keeps-compatible-log","t":"log:conversation","st":"confirmed","c":"high","u":"2026-05-05","src":"memory/index.md"}
 {"f":"project:pam","r":"keeps-compatible-log","t":"log:knowledge","st":"confirmed","c":"high","u":"2026-05-05","src":"memory/index.md"}
 {"f":"format:graph-v1","r":"migrates-from","t":"migration:markdown-to-graph-v1","st":"confirmed","c":"high","u":"2026-05-05","src":"migrations/markdown-v0-to-graph-v1.md"}
+{"f":"format:graph-v1","r":"keeps-schema-for","t":"migration:0.5-file-only-coverage","st":"confirmed","c":"high","u":"2026-05-22","src":"migrations/0.4.0-to-0.5.0-file-only-coverage.md"}
 {"f":"doc:runtime","r":"prefers","t":"format:graph-v1","st":"confirmed","c":"high","u":"2026-05-05","src":"memory/agent-memory/pam-runtime.md"}
+{"f":"doc:runtime","r":"recommends","t":"tool:file-only-coverage","st":"confirmed","c":"high","u":"2026-05-22","src":"memory/agent-memory/pam-runtime.md"}
 {"f":"project:pam","r":"has-principle","t":"principle:agent-facing-runbooks","st":"confirmed","c":"high","u":"2026-05-07","src":"memory/agent-memory/pam.md"}
 {"f":"doc:pam-contract","r":"defines-principle","t":"principle:agent-facing-runbooks","st":"confirmed","c":"high","u":"2026-05-07","src":"memory/agent-memory/pam.md"}