Classify adapter lifecycle states in digests

.claude/rules/alias-subtrees.md

@@ -10,8 +10,17 @@ Add an alias subtree whenever the entity has a natural human-readable lookup key
 - `by-title` / `by-name` — for entities whose human-readable label changes independently of the ID.
 - `by-key` — for entities with a provider-issued short key (e.g. Jira `ENG-42`, Linear identifier `ENG-42`).
 - `by-state` / `by-status` — when the consumer cares about the lifecycle bucket (`open`, `closed`, `in-progress`, ...).
+- `by-assignee` — when work items have a current owner/assignee.
+- `by-creator` — when work items track the user who opened or created them.
+- `by-priority` — when work items expose a native priority or a conventional priority label.
 - `by-parent` — when the entity has a single natural parent (issues -> project, pages -> space).
 
+The enforced category matrix lives in `docs/digest-layout-contract.md` and is
+checked by `npm run test:digest-contracts`. If a resource belongs to a matrix
+category such as issue-tracking, add the required aliases (`by-state`,
+`by-assignee`, `by-creator`, and `by-priority` for issue-tracking, `by-status`
+for CI/deploy) in the same change as the layout, emitter, and tests.
+
 Do NOT add an alias for a key that already matches the canonical filename one-to-one — it would be redundant.
 
 ## Path shape
@@ -21,9 +30,13 @@ Do NOT add an alias for a key that already matches the canonical filename one-to
 ```
 
 For `by-state`, group records under a state subdirectory:
+For `by-assignee`, `by-creator`, and `by-priority`, use the same grouped shape.
 
 ```text
 /<provider>/<resource>/by-state/<state>/<id>.json
+/<provider>/<resource>/by-assignee/<assignee>/<id>.json
+/<provider>/<resource>/by-creator/<creator>/<id>.json
+/<provider>/<resource>/by-priority/<priority>/<id>.json
 ```
 
 ## Collision handling
@@ -32,13 +45,21 @@ Always use `aliasCollisionSuffix` from `packages/core/src/alias-slug.ts` (an 8-c
 
 ## Alias file content
 
-Each alias file is a minimal pointer, not a full copy of the record:
+Alias files may use either of these shapes, but the choice must be consistent
+within a resource and covered by tests:
+
+- Minimal pointer:
 
 ```json
 { "id": "<id>", "canonicalPath": "/<provider>/<resource>/<slug>__<id>.json", "title": "<optional>" }
 ```
 
-Readers follow `canonicalPath` to get the full record. This keeps the cost of adding alias views low and means the canonical record is the single source of truth.
+- Materialized canonical mirror: the same provider envelope as the canonical
+  record, written to the alias path for direct reads.
+
+For minimal pointers, readers follow `canonicalPath` to get the full record. For
+materialized mirrors, readers can use the alias body directly. Do not mix pointer
+and mirror files under the same resource subtree.
 
 ## Read pattern
 

.claude/rules/layout-md.md

@@ -37,7 +37,7 @@ Indexes are sorted by \`updated\` descending.
 - By id: \`/foo/<resource>/by-id/<id>.json\`.
 - By <natural key>: \`/foo/<resource>/by-<key>/<slug>__<id>.json\`.
 
-Alias files are minimal pointers (\`{ id, canonicalPath, title? }\`); follow \`canonicalPath\` for the full record. Collisions get a deterministic 8-char hash suffix.
+Alias files are either minimal pointers (\`{ id, canonicalPath, title? }\`) or materialized canonical mirrors; document the choice and keep it consistent within a resource. Collisions get a deterministic 8-char hash suffix.
 
 ## JSONL And Querying
 

.claude/rules/relayfile-integration-digests.md

@@ -0,0 +1,41 @@
+---
+description: Provider adapters must keep Relayfile digests and lifecycle state wired
+paths:
+  - packages/*/src/**
+  - packages/*/test/**
+  - packages/*/src/**/__tests__/**
+---
+
+# Relayfile integration digests
+
+Relayfile digests are part of the adapter contract. If an adapter writes
+provider records that agents can read, the adapter must also make those records
+summarizable in the activity digest.
+
+## Required for adapters
+
+- Export a real `digest` handler from `src/digest.ts` and the package `src/index.ts`.
+- The digest handler must use `ctx.changeEvents({ providers: [ctx.provider] })`
+  and return deterministic bullets sorted by event time and id.
+- Lifecycle verbs must be provider-aware. Explicitly classify terminal-state
+  actions such as `closed`, `merged`, `archived`, `completed`, `canceled`, and
+  `resolved`.
+- Webhook ingestion must preserve terminal lifecycle state as record data.
+  Do not convert `closed`/`merged`/`archived`/`completed` into deletion unless
+  the upstream object was actually deleted.
+- Add tests for create/update, terminal state, delete, deterministic ordering,
+  and empty windows.
+- Keep the provider layout aligned with the category matrix in
+  `docs/digest-layout-contract.md`. For example, issue-tracking resources must
+  expose `by-state`, `by-assignee`, `by-creator`, and `by-priority`; CI/deploy
+  resources must expose `by-status` unless the matrix documents an explicit
+  exception.
+- Run `npm run test:digest-contracts` whenever adding or materially changing an
+  adapter, digest handler, layout manifest, or category matrix entry.
+
+## No-op handlers
+
+A digest handler that returns `null` is a temporary placeholder, not a pattern.
+Do not add new no-op digest handlers for providers that expose records in
+Relayfile. If a provider intentionally has no digest output, document that
+choice and test the exclusion.

.claude/rules/testing.md

@@ -15,7 +15,7 @@ It must be green before the PR opens. Do not bypass git hooks; if the pre-commit
 ## What each helper needs covered
 
 - **Path-mapper helpers** — round-trip tests: compose with the helper, parse the result back to its inputs, assert equality. Cover at least one ASCII-clean case, one case with characters that the slugifier collapses, and one case with an empty / missing slug input.
-- **Alias subtrees** — collision test: emit two entities whose slugs collide, assert that both alias paths are distinct and deterministic (re-emitting produces the same paths), and that each alias file points at a different `canonicalPath`.
+- **Alias subtrees** — collision test: emit two entities whose slugs collide, assert that both alias paths are distinct and deterministic (re-emitting produces the same paths), and assert the resource's alias strategy. Minimal pointer aliases must point at different `canonicalPath` values; materialized canonical mirrors must match the canonical provider envelope/body for each entity.
 - **`LAYOUT.md` emitter** — non-empty content test asserting:
   - `file.path === '/<provider>/LAYOUT.md'`.
   - `file.contentType === 'text/markdown; charset=utf-8'`.

.github/workflows/ci.yml

@@ -34,4 +34,4 @@ jobs:
         run: npx turbo typecheck
 
       - name: Test
-        run: npx turbo test
+        run: npm test

.github/workflows/publish.yml

@@ -72,6 +72,7 @@ jobs:
         id: resolve
         env:
           INPUT_PACKAGE: ${{ github.event.inputs.package }}
+          INPUT_VERSION: ${{ github.event.inputs.version }}
         run: |
           node scripts/resolve-publish-targets.mjs "$INPUT_PACKAGE" >> "$GITHUB_OUTPUT"
 

.trajectories/index.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "lastUpdated": "2026-05-12T01:36:53.866Z",
+  "lastUpdated": "2026-05-15T13:10:33.804Z",
   "trajectories": {
     "traj_q7vhb9378uqk": {
       "title": "Wire Jira privacy-safe adapter storage",
@@ -334,6 +334,83 @@
       "startedAt": "2026-05-12T01:29:12.191Z",
       "completedAt": "2026-05-12T01:36:53.740Z",
       "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_16jy5n5ejwmn.json"
+    },
+    "traj_26dxjcy6eeao": {
+      "title": "Implement Tier-2 buildSummary adapters for Salesforce, HubSpot, Stripe, Zendesk, and Asana",
+      "status": "completed",
+      "startedAt": "2026-05-12T07:43:30.336Z",
+      "completedAt": "2026-05-12T07:51:21.689Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_26dxjcy6eeao.json"
+    },
+    "traj_653cvqi7c650": {
+      "title": "Address PR 67 feedback",
+      "status": "abandoned",
+      "startedAt": "2026-05-12T10:04:48.218Z",
+      "completedAt": "2026-05-12T10:19:47.488Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_653cvqi7c650.json"
+    },
+    "traj_aad65ivnpfxj": {
+      "title": "Address PR 68 feedback",
+      "status": "completed",
+      "startedAt": "2026-05-12T10:24:14.001Z",
+      "completedAt": "2026-05-15T10:22:52.332Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_aad65ivnpfxj.json"
+    },
+    "traj_d8xc6lop46pt": {
+      "title": "Track G: Tier-3 buildSummary (9 providers)",
+      "status": "completed",
+      "startedAt": "2026-05-12T08:09:19.612Z",
+      "completedAt": "2026-05-12T08:28:28.057Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_d8xc6lop46pt.json"
+    },
+    "traj_et4ghsuda3uz": {
+      "title": "Finish relayfile adapter lifecycle digest sweep",
+      "status": "completed",
+      "startedAt": "2026-05-15T10:36:32.907Z",
+      "completedAt": "2026-05-15T10:37:12.092Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_et4ghsuda3uz.json"
+    },
+    "traj_vy46it87lscw": {
+      "title": "Implement Tier-2 buildSummary adapters for Salesforce, HubSpot, Stripe, Zendesk, and Asana",
+      "status": "completed",
+      "startedAt": "2026-05-12T06:28:57.987Z",
+      "completedAt": "2026-05-12T06:37:06.442Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_vy46it87lscw.json"
+    },
+    "traj_gp710tis5d5b": {
+      "title": "Address relayfile-adapters PR 97 review comments",
+      "status": "completed",
+      "startedAt": "2026-05-15T11:47:53.245Z",
+      "completedAt": "2026-05-15T11:58:11.229Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_gp710tis5d5b.json"
+    },
+    "traj_9tel0oqwwd1y": {
+      "title": "Add issue-tracking digest category aliases",
+      "status": "completed",
+      "startedAt": "2026-05-15T12:01:17.105Z",
+      "completedAt": "2026-05-15T12:16:08.421Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_9tel0oqwwd1y.json"
+    },
+    "traj_2jcdbcpmirqj": {
+      "title": "Review issue-tracking digest alias coverage",
+      "status": "completed",
+      "startedAt": "2026-05-15T12:23:07.386Z",
+      "completedAt": "2026-05-15T12:26:39.246Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_2jcdbcpmirqj.json"
+    },
+    "traj_r1g8avti0ax8": {
+      "title": "Review and tighten relayfile-adapters PR 97",
+      "status": "completed",
+      "startedAt": "2026-05-15T12:49:18.431Z",
+      "completedAt": "2026-05-15T12:57:44.735Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_r1g8avti0ax8.json"
+    },
+    "traj_a1zqsgk4yiah": {
+      "title": "Final comprehensive self-review of relayfile-adapters PR 97",
+      "status": "completed",
+      "startedAt": "2026-05-15T13:05:27.270Z",
+      "completedAt": "2026-05-15T13:10:33.685Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/completed/2026-05/traj_a1zqsgk4yiah.json"
     }
   }
 }

AGENTS.md

@@ -7,7 +7,7 @@ Every adapter under `packages/<name>` MUST:
 - Export a `path-mapper.ts` with typed helpers for every canonical record path it emits. Importing the helper is the only supported way to compute a path; consumers must not construct paths by string concatenation.
 - Emit a provider-specific `LAYOUT.md` at the root of its provider tree (e.g. `/<provider>/LAYOUT.md`) of at least ~1000 bytes describing the tree, naming convention, indexes, aliases, and copy-pasteable `jq`/`ls` examples. The 250-300 byte generic fallback is not acceptable for any shipping adapter.
 - Emit `_index.json` files at each resource root listing all materialized records. The row schema MUST include `{ id, title, updated }` at a minimum; additional fields are encouraged when they enable filterless reads (e.g. `state`, `key`, `is_bot`, `parent_id`).
-- Provide `by-*` alias subtree views when the underlying entity has a natural human-readable lookup key distinct from its stable ID (titles, names, keys, statuses, parents). Each alias path resolves to the canonical record; alias content is the minimal pointer `{ id, canonicalPath, ...minimal pointer fields }`.
+- Provide `by-*` alias subtree views when the underlying entity has a natural human-readable lookup key distinct from its stable ID (titles, names, keys, statuses, parents). Each alias path must resolve to the same record as the canonical path. Alias content may be either a minimal pointer `{ id, canonicalPath, ...minimal pointer fields }` or a materialized canonical mirror, but the choice must be consistent within a resource and covered by tests.
 - Use `packages/core/src/alias-slug.ts` (`slugifyAlias`, `aliasCollisionSuffix`) for slug normalization and collision suffixes. Provider-local alias modules should re-export those helpers for backward compatibility. NEVER write a new slugifier.
 
 ### Generated adapter path templates are not authoritative
@@ -52,7 +52,7 @@ ID format: whatever the provider's stable ID is (UUID, numeric, string key). Do
 
 - Path shape: `/<provider>/<resource>/by-<key>/<slug>__<id>.json` (e.g. `/notion/pages/by-title/my-page__a1b2c3d4.json`).
 - Collisions: append a deterministic short hash of the ID via `aliasCollisionSuffix`. NEVER pick "first writer wins" — collision handling must be deterministic across sync runs.
-- Each alias file contains a minimal pointer: `{ id, canonicalPath, title? }`. Do not duplicate the full record — readers follow `canonicalPath`.
+- Alias files are either minimal pointers (`{ id, canonicalPath, title? }`) or materialized canonical mirrors. Keep the choice consistent within each resource, and document/test it so readers know whether to follow `canonicalPath` or read the alias body directly.
 
 ### Versioning
 
@@ -315,3 +315,29 @@ Your trajectory helps others understand:
 
 Future agents can query past trajectories to learn from your decisions.
 <!-- prpm:snippet:end @agent-workforce/trail-snippet@1.1.2 -->
+
+# Relayfile Integration Digest Contract
+
+Every adapter that exposes provider records to Relayfile must also expose a
+usable digest contract. When adding or materially changing an adapter:
+
+- Add or update `src/digest.ts` and export it from the package barrel.
+- Classify lifecycle actions explicitly. Terminal states such as `closed`,
+  `merged`, `archived`, `completed`, `canceled`, and `resolved` must not fall
+  through to a generic "updated" line unless the provider has no terminal
+  concept.
+- Do not model terminal lifecycle states as deletion in adapter webhook
+  handling. Only actual upstream deletes should produce delete semantics.
+- Add digest tests beside the adapter tests. Cover at least create/update,
+  terminal state, delete, deterministic sorting, and empty-window behavior.
+- If an adapter intentionally does not participate in digests, document why in
+  the package README or PR and keep the no-op handler covered by a test.
+- Keep digest behavior and layout aliases aligned with the category matrix in
+  `docs/digest-layout-contract.md`. Issue-tracking resources must expose
+  `by-state`, `by-assignee`, `by-creator`, and `by-priority` unless the matrix
+  documents an explicit exception; status-driven build/deploy resources must
+  expose `by-status`.
+- Run `npm run test:digest-contracts` after adding or changing an adapter,
+  digest handler, layout manifest, or category matrix entry.
+
+Full rule: `.claude/rules/relayfile-integration-digests.md`.

docs/digest-layout-contract.md

@@ -0,0 +1,62 @@
+# Relayfile Digest And Layout Contract
+
+Relayfile adapters expose provider records as an agent-facing filesystem. A
+record that can be written, synced, or received through a webhook must also be
+discoverable through the activity digest and through the provider's natural
+lookup aliases.
+
+Run the contract check with:
+
+```bash
+npm run test:digest-contracts
+```
+
+## Baseline Digest Contract
+
+Every provider package under `packages/<provider>` must:
+
+- Export `src/digest.ts` from `src/index.ts`.
+- Scope digest reads with `ctx.changeEvents({ providers: [ctx.provider] })`.
+- Return deterministic bullets sorted by event time and id.
+- Test create/update behavior, provider lifecycle behavior, delete or terminal
+  behavior, deterministic ordering, and empty windows.
+- Preserve terminal lifecycle state in webhook ingestion unless the upstream
+  object was actually deleted.
+
+No-op digest handlers are not a shipping pattern. A provider that intentionally
+does not appear in digests must document the exception and keep that exclusion
+covered by a test.
+
+Append-only providers are a narrow exception to the delete-or-terminal portion
+of lifecycle coverage. Segment is currently the only enforced exception:
+records are immutable once written, so its digest contract must explicitly
+classify append/upsert activity and document the append-only behavior in
+`src/digest.ts`.
+
+## Category Matrix
+
+These category rules are enforced by `scripts/digest-layout-contracts.mjs`.
+
+| Category | Providers/resources | Required lookup | Rationale |
+| --- | --- | --- | --- |
+| issue-tracking | GitHub issues and pull requests, GitLab issues and merge requests, Jira issues, Linear issues | `by-state/<state>/<id>.json`, `by-assignee/<assignee>/<id>.json`, `by-creator/<creator>/<id>.json`, `by-priority/<priority>/<id>.json` | Agents often ask for open, closed, merged, completed, canceled, assigned, created-by, or priority-scoped work without already knowing an id. |
+| task-management | Asana tasks, ClickUp tasks | `by-state/<state>/<id>.json`, `by-assignee/<assignee>/<id>.json`, `by-creator/<creator>/<id>.json`, `by-priority/<priority>/<id>.json` | Task systems expose the same operational questions as issue trackers: what is open or completed, who owns it, who created it, and what priority bucket it sits in. |
+| ci-deploy | GitLab pipelines and deployments | `by-status/<status>/<id>.json` | Status is the primary lifecycle bucket for build and deploy resources. |
+| knowledge | Confluence pages | `by-state/<state>/<id>.json` | Pages can be current, archived, trashed, restored, or deleted and must remain discoverable by lifecycle bucket. |
+
+Resources outside this matrix still need digest coverage. They only need a
+`by-state`, `by-status`, `by-assignee`, `by-creator`, or `by-priority` alias
+when the resource exposes a durable bucket that agents naturally browse by. Add
+the resource to the matrix when that is true; do not rely on prose alone.
+
+## Review Checklist
+
+When adding or materially changing an adapter:
+
+1. Update the adapter digest handler and tests.
+2. Update the layout manifest when the provider exposes a category lookup such
+   as state, status, parent, key, name, or title.
+3. Add the provider/resource to the category matrix above and to
+   `scripts/digest-layout-contracts.mjs` when the category behavior should be
+   enforced across future work.
+4. Run `npm run test:digest-contracts` before opening or updating the PR.