pm-context 2026.10.10 → 2026.10.12

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.10.12 - 2026-10-12
+
+### Added
+
+- pm context-usage: report which served context an agent actually used ([pm-context-ci6v](https://github.com/unbraind/pm-context/blob/main/.agents/pm/features/pm-context-ci6v.toon))
+
 ## 2026.10.5 - 2026-10-05
 
 ### Other

package/README.md

@@ -29,9 +29,9 @@ pm context-pack --id pm-1234 --max-items 10
 
 The command reads workspace data in-process through the typed pm SDK, so packs
 use the installed CLI's canonical query and relevance engines rather than a
-second parser. Normal pack and handoff runs record one best-effort context-usage
-serving event for the emitted items when an author is available; `--explain`
-does not write to the usage ledger.
+second parser. Normal pack and handoff runs attach a runtime receipt for their rendered facts
+and record a best-effort SDK serving event for visible items when an author is
+available. `--explain` stays observational and creates neither receipt nor event.
 
 ## Output
 
@@ -86,6 +86,8 @@ ceiling.
 
 Options:
 
+- `--session <id>` usage session (also available on `context-handoff`); defaults to
+  `PM_CONTEXT_SESSION`, then a fresh receipt id for each bundle
 - `--id <id>` repeatable item ids to focus
 - `--ids <id,id>` comma-separated focus item ids (alias for repeated `--id`)
 - `--status <status>` filter by status
@@ -104,7 +106,7 @@ Options:
   A breadth-first walk over the dependency relationship graph in both directions
   (`depends_on`/`blocked_by` edges and their reverse). `0` is equivalent to
   `--without-neighborhood`; the value is capped at `5`. Depth `1` is the historical
-  default and produces byte-identical packs to prior versions. Neighbors discovered
+  default and preserves the prior item selection. Neighbors discovered
   at deeper hops are still classified as neighbors (never focus), de-duplicated, and a
   focus item is never listed as its own neighbor.
 - `--compress` minimize output tokens (compact JSON, no blank lines)
@@ -120,46 +122,139 @@ Options:
 
 `pm context-usage`
 
-Reports which items `pm context` and `pm next` served, and which of those were
-actually touched afterwards — the feedback half of "project management = context
-management".
+Measures the context bundles generated by `context-pack` and `context-handoff`,
+with separate compatibility metrics from the host's `context`/`next` ledger.
+It reports facts served versus facts reported used per session and item, so
+agents can reduce unused context in their next request.
+
+### Agent usage protocol (v1)
+
+1. Choose a session id and set `PM_CONTEXT_SESSION`, or pass `--session` on each
+   serving and reporting command. Refreshing context creates a new receipt;
+   reusing a session aggregates those bundle impressions. Without a session,
+   each bundle's receipt id becomes its isolated session id.
+2. Read a pack or handoff. JSON adds `context_receipt` with `protocol`,
+   `receipt_id`, `session`, `author`, `served_at`, stable `sections` and `facts`.
+   Text annotates headings with `[s-…]` and content lines with `[f-…]`, and ends
+   with a receipt/session footer. Preserve those ids in the agent's context.
+3. Report facts that informed your work, using ids from that receipt. A section
+   citation reports all facts in that section. A post-mutation or file-edit hook
+   may instead submit touched item ids or edited repository-relative paths.
+   Invoke the hook **after successful work**, against the receipt used for it.
+4. Inspect the session report, then request fewer sections or items when the
+   retained evidence repeatedly shows unused context.
 
-pm maintains an append-only ledger at `<pm_root>/runtime/context-usage.jsonl`
-(a `serve` row per ranking, a `touch` row per mutation) and folds it into the
-`usage_affinity` signal of its built-in relevance model. Nothing surfaces the
-ledger itself, so an agent cannot ask *what was I shown, and did I use it?*
-This command answers that:
-
-- **conversion** — share of served items followed by a same-author touch
-- **waste** — served but never touched afterwards: context you paid tokens for and did not use
-- **misses** — touched but never served: work the ranking failed to surface
+```bash
+export PM_CONTEXT_SESSION=review-42
+pm context-pack --ids pm-1234,pm-5678 --section focus
+# Copy the actual receipt/fact identifiers from the returned bundle:
+pm context-usage --receipt RECEIPT_ID --cite FACT_ID --json
+pm context-usage --receipt RECEIPT_ID --cite SECTION_ID --json
+# A hook can report later successful mutations or edits:
+pm context-usage --receipt RECEIPT_ID --touch pm-1234 --edited-file src/example.ts
+pm context-usage --session review-42 --json
+pm context-usage --by agent-a --limit 50
+```
 
-An item counts as *served* only when pm marked it `included` — it actually made
-the pack. The per-item `ranked` column counts every appearance, so
-`ranked - serves` is how often the item lost to the token budget rather than to
-the ranking: tune the budget, not the query. An item that was only ever ranked
-and cut is never reported as waste, because the agent never saw it.
+`--cite`, `--touch`, and `--edited-file` accept repeated flags or comma-separated
+values and require `--receipt`. An unknown citation, unserved item/file, invalid
+path, expired receipt, or mismatched session rejects the entire submission.
+Repeated submissions are idempotent. Reports for the same fact can retain all
+three evidence categories without counting the fact as used more than once.
+When a session is supplied explicitly or through the environment it must match
+the selected receipt. Different receipts never inherit one another's evidence,
+even if their fact ids are identical. `--by` filters the recording author;
+the host-owned global `--author` sets invocation identity, not the report filter.
+
+A fact is one nonblank rendered text content line (including placeholders), or
+one top-level JSON field value/array entry. Generated timestamps and headings
+are framing. Facts are content-addressed by section, associated item ids, and
+rendered content; unchanged content in the same format keeps its id across
+refreshes. Changed content gets a new id. Repeated identical fragments in one
+section share an id with summed token cost. Section ids hash the rendered name.
+Markdown section filters, body truncation, handoff link limits and packing are
+applied **before** facts are identified. JSON reports all fields in the JSON
+bundle, as with the existing JSON serving format.
+
+Only visible item identifiers and visible linked file paths are associated with
+facts; excluded bodies, items and sections cannot receive usage credit. File
+paths are normalized to repository-relative POSIX paths. URLs and absolute or
+traversing paths cannot be reported as edited files. A fact spanning several
+items belongs to each item's rollup, so item totals can overlap; session and
+bundle totals count that fact once.
+
+The JSON report adds `bundles`, with `totals`, `sessions`, `items`, and `receipts`:
+
+- `precision = used_facts / served_facts` (`null` for no served facts).
+- `cited_facts`, `touch_facts`, and `edit_facts` separate explicit citations from
+  mutation/edit proxies. An uncited read can be reported explicitly by fact id.
+- `estimated_served_tokens` sums fact cost, estimated as `ceil(characters / 4)`
+  per rendered fragment. `unused_context_tokens` sums only unused facts.
+  These are estimates, not tokenizer measurements, billing, or cognitive-use proof.
+- `protocol_tokens` separately estimates receipt/annotation overhead; headings,
+  generated clocks and other framing are outside the fact-cost denominator.
+- `unused_fact_ids` identifies unused facts in each detailed receipt. Aggregate
+  metrics are computed before `--limit` truncates the detail arrays.
+
+Metrics describe the complete bundle handed to the command host or written to
+`--output`. The SDK does not expose a fact-level post-egress callback, so later
+host truncation, omitted responses, or an agent failing to read a saved file
+cannot be inferred. For complete delivery use `--output` and read the resulting
+file, or the host's unbounded output controls. Agents must submit evidence;
+silence means **unreported usage**, not proven irrelevance. Host ledger touches
+carry no session or fact ids and are never automatically credited to a receipt.
+
+### Runtime storage and failure handling
+
+Receipts live exclusively in the tracker's ignored
+`runtime/context-receipts/` directory. Each atomic JSON snapshot stores ids,
+associations, token estimates and deduplicated evidence, **no context text**.
+Rotation keeps the current receipt and the most recently written siblings, at
+most 200 snapshots of 256 KiB each (50 MiB maximum retained receipt data).
+Older receipts are deleted; their
+metrics leave the retained-window report. Successful evidence writes refresh a
+receipt's retention position. There is no tracked receipt file or schema change,
+and the host-owned `runtime/context-usage.jsonl` remains under SDK ownership.
+The receipt returned by the current serving call is protected during rotation,
+including when older snapshots have future modification times. The remaining
+199 slots retain the most recently written siblings.
+
+A directory lock serializes cooperating writers; contention fails a usage
+submission and can be retried. A process crash can leave `.lock`; an operator
+may remove that abandoned lock after ensuring no writer is running. Corrupt,
+oversized or partial snapshots are skipped and counted as `malformed_receipts`.
+Serving failures disclose `context_receipt_error` in JSON or a receipt-unavailable
+message in text and still return context. They do not claim measured usage.
+`--explain` creates no receipt. Failed output-file writes roll back their receipt.
+
+### Host ledger compatibility report
+
+The existing report still reads pm's bounded `runtime/context-usage.jsonl` and
+surfaces **conversion** (same-author serve followed by a touch), **waste**
+(served without a later touch), and **misses** (touched without a serve).
+It uses serve rows' `included` flags; `ranked - serves` identifies budget losses.
+Recognized delivery rows do not change that legacy denominator. This historical
+conversion is separate from the receipt/session metrics and cannot establish
+fact usage or final delivery. When `--by` is supplied, SDK-decayed affinity is
+shown when available; the package does not implement a competing relevance model.
 
 ```bash
-pm context-usage                          # markdown brief
-pm context-usage --json                   # raw report
-pm context-usage --surface next --since 7d
-pm context-usage --author agent-a --limit 50
+pm context-usage
+pm context-usage --surface next --since 7d --json
 ```
 
-Options:
+Report options:
 
-- `--author <author>` restrict to one recording author
-- `--surface <context|next>` restrict serve events to one surface
-- `--since <when>` drop events at or before an ISO timestamp or a day offset (`7d`, `-7d`, `7`)
-- `--limit <n>` maximum per-item rows (default `20`)
-- `--format <markdown|json>` output format (default `markdown`); pm's global `--json` also selects JSON
+- `--session <id>` filter bundle receipts (also reads `PM_CONTEXT_SESSION`)
+- `--receipt <id>` filter or submit evidence to one bundle receipt
+- `--cite <ids>`, `--touch <ids>`, `--edited-file <paths>` submit usage evidence
+- `--by <author>` filter both reports by recording author
+- `--surface <context|next>` filter only legacy host serve events
+- `--since <when>` drop serves at or before an ISO timestamp or day offset
+  (`7d`, `-7d`, `7`); bundle evidence is attributed to the receipt's serve time
+- `--limit <n>` maximum detail rows (default `20`)
+- `--format <markdown|json>`; the global `--json` also selects JSON
 
-The command is strictly read-only. The ledger is pm's file, with pm's schema and
-pm's pruning, and it deliberately reports only what the ledger states directly —
-it does **not** compute a competing affinity score, because pm owns the decay
-model and a second implementation could silently disagree with the ranking it
-purports to explain.
 
 ## Philosophy
 
@@ -183,3 +278,39 @@ itself lists each affected stream in its output; `pm history --verify <id>` spot
 content, so `reconcile` only re-greens the hash chain (no data loss) — see the authoritative
 [pm-cli merge-safety guide](https://github.com/unbraind/pm-cli/blob/main/docs/MERGE_SAFETY.md). The
 older blunt `pm history-repair --all` remains available as a lower-level primitive.
+
+The existing quality owner, `pm-context-3s5f`, remains open. The native coverage
+gate enforces 100% lines, branches and functions for six configured files; it
+does not expose an independent statement counter. A separate c8 observation
+includes all ten authored TypeScript/JavaScript executables. Neither measurement
+covers the shell alert helper, so passing the release command does not establish
+whole-source 100/100/100/100.
+
+| Authored executable | Native gate | Separate c8 observation |
+| --- | --- | --- |
+| `index.ts` | Included | Included |
+| `context-receipts.ts` | Included | Included |
+| `context-usage.ts` | Included | Included |
+| `scripts/coverage-gate.ts` | Included | Included |
+| `scripts/docstring-gate.ts` | Included | Included |
+| `scripts/verify-release-publish-attestation.ts` | Included | Included |
+| `scripts/main-invocation.ts` | Outside configured scope | Included |
+| `scripts/prepare-merge-driver.ts` | Outside configured scope | Included |
+| `scripts/verify-release-changelog-date.ts` | Outside configured scope | Included |
+| `.agents/pm/verify-release-yaml.mjs` | Outside configured scope | Included |
+| `scripts/alert-on-release-failure.sh` | Unmeasured | Unmeasured |
+
+Coverage reports are removed before configuration validation and on runner or
+inventory failures, preventing an earlier report from surviving a failed gate.
+The parsed-workflow verifier has disposable real-file acceptance and rejection
+fixtures in `test/release-workflow-verifier.test.ts`; those tests never contact
+GitHub or mutate release controls.
+
+The documentation launcher checks the pm-ops analyzer's selected declaration
+policy. It excludes anonymous callbacks and several internal declaration forms,
+so its passing count does not certify documentation of every authored declaration.
+The managed merge-driver launcher must remain byte-identical to the pinned
+pm-ops template; its internal callback is part of the outstanding documentation
+scope. The alert and workflow-verifier migration also requires coordinating the
+existing `pm-context-qu0a` ownership before migrating its linked paths. No helper
+has been marked removed while that dependency remains unresolved.

package/dist/context-receipts.d.ts

@@ -0,0 +1,115 @@
+/** Physical retention ceilings: at most 200 receipts of 256 KiB each. */
+export declare const RECEIPT_LIMITS: {
+    readonly count: 200;
+    readonly bytes: 262144;
+};
+/** Isolated, ignored tracker runtime directory used by this protocol. */
+export declare const RECEIPTS_RELATIVE_PATH: string;
+/** Explicit evidence categories; a touch or edit is a usage proxy, not a citation. */
+export type UsageSignal = "citation" | "touch" | "edit";
+/** One content-addressed unit that was present in the rendered bundle. */
+export interface ContextFact {
+    id: string;
+    section_id: string;
+    item_ids: string[];
+    files: string[];
+    estimated_tokens: number;
+}
+/** Stable section identifier and its rendered name. */
+export interface ContextSection {
+    id: string;
+    name: string;
+}
+/** Public receipt returned alongside the context; no context text is persisted. */
+export interface ContextReceipt {
+    protocol: "pm-context-usage/v1";
+    receipt_id: string;
+    session: string;
+    author: string;
+    served_at: string;
+    command: string;
+    sections: ContextSection[];
+    facts: ContextFact[];
+    protocol_tokens: number;
+}
+/** Item/file associations from the selected pack, intersected with rendered text. */
+export interface ReceiptAssociations {
+    item_ids: string[];
+    files: Array<{
+        itemId: string;
+        value: string;
+    }>;
+}
+/** Serving identity; an omitted session defaults to this bundle's receipt id. */
+export interface ReceiptIdentity {
+    session?: string;
+    author: string;
+    command: string;
+}
+/** Usage evidence submitted by an agent or its post-mutation/edit hook. */
+export interface ReceiptUsage {
+    receipt_id: string;
+    session?: string;
+    citations: string[];
+    touched_items: string[];
+    edited_files: string[];
+}
+/** Precision-style metrics over retained receipt/fact impressions. */
+export interface ReceiptMetrics {
+    served_facts: number;
+    used_facts: number;
+    cited_facts: number;
+    touch_facts: number;
+    edit_facts: number;
+    precision: number | null;
+    estimated_served_tokens: number;
+    unused_context_tokens: number;
+    protocol_tokens: number;
+}
+/** Filtered runtime report; limits affect detail rows, never the aggregate. */
+export interface ReceiptReport {
+    protocol: "pm-context-usage/v1";
+    retained_receipts: number;
+    malformed_receipts: number;
+    totals: ReceiptMetrics;
+    sessions: Array<ReceiptMetrics & {
+        session: string;
+    }>;
+    items: Array<ReceiptMetrics & {
+        id: string;
+    }>;
+    receipts: Array<ReceiptMetrics & {
+        receipt_id: string;
+        session: string;
+        unused_fact_ids: string[];
+    }>;
+}
+/** Narrow receipt reports by session, author, time, or one receipt identifier. */
+export interface ReceiptReportOptions {
+    session?: string;
+    author?: string;
+    since?: string;
+    receipt_id?: string;
+    limit: number;
+}
+/** Normalize only repository-relative file evidence, rejecting URLs and traversal. */
+export declare function normalizeReceiptFile(value: string): string;
+/**
+ * Build facts from exactly the rendered content, annotate text or attach a JSON
+ * manifest, and persist its receipt. Fact hashes exclude clocks and receipt ids.
+ * Write failures propagate so callers disclose that measurement is unavailable.
+ */
+export declare function serveContextReceipt(pmRoot: string, output: string, format: "json" | "text", associations: ReceiptAssociations, identity: ReceiptIdentity, outputPath?: string): {
+    output: string;
+    receipt: ContextReceipt;
+};
+/**
+ * Record explicit, receipt-scoped usage. Unknown ids reject the entire update;
+ * repeat reports are idempotent. Item/file proxies match only facts in this receipt.
+ */
+export declare function recordReceiptUsage(pmRoot: string, usage: ReceiptUsage): void;
+/** Read retained receipts, report skipped corruption, and aggregate before limiting detail. */
+export declare function reportContextReceipts(pmRoot: string, options: ReceiptReportOptions): ReceiptReport;
+/** Render the receipt denominator, usage proxies and unused estimated cost as a brief. */
+export declare function renderReceiptReport(report: ReceiptReport): string;
+//# sourceMappingURL=context-receipts.d.ts.map

package/dist/context-receipts.d.ts.map

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