Skip to content

Add researched context playbooks and a verified handoff exercise - #18

Merged
sdcarlson merged 2 commits into
mainfrom
docs/context-management
Sep 6, 2026
Merged

sdcarlson merged 2 commits into
mainfrom
docs/context-management

Conversation

@sdcarlson

@sdcarlson sdcarlson commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

Relay needs a durable guide for handing job research and reviewed drafts between assistants without losing evidence, job identity, or acceptance state.

Adds 21 primary sources checked September 5, 2026; provider-specific playbooks; task/checkpoint templates; and twelve proposed model evaluation cases. A fictional native packet, evidence bundle, sample paragraph, and checkpoint make the first exercise concrete. Experimental research and API capabilities are distinguished from implemented Relay features.

Validation: all local Markdown links resolve; git diff whitespace checks pass; all 47 existing local tests pass. The real grok-draft file adapter preserved job identity and exact text, marked review required, and refused overwrite. The generated result passed matching-job validation and was rejected for stale and wrong-job targets.

No application source, dependencies, schema, or workflows changed. The example paragraph is manually authored. No model quality benchmark, paid provider call, browser journey, or submission was performed. The initial docs-only automated review found no actionable defects; the added example requires review on the latest head.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Review (docs-only)

No actionable defects on head 7303e65 (still matches refs/pull/18/head). Documentation only: 9 Markdown files, no runtime, schema, migration, or workflow changes. Human approval remains mandatory.

Relay-behavior claims that were checked against adjacent contracts match the current checkout:

  • Packet shape and validation (schema, job.key / job.version / job.url, nonempty facts, character limits) match validatePacket in integrations/connectors.mjs.
  • Claude path is a single Messages request, returns draft text only, and accepts only end_turn — consistent with draftClaude and the playbook’s compaction-pause warning.
  • Exact-text acceptance, stale version reconciliation, imported Ready as evidence (not local acceptance), and “accepted ≠ submitted” match REVIEW.md / root README. Templates are explicitly not relay.packet.v1 imports and tell receivers not to rewrite identity/version to bypass a stale packet.
  • No OpenAI / Gemini / local-model connector; Grok Bot remains a command/file adapter, not xAI compaction.

Provider-doc spot-checks (opened pages, not live API calls) supported the named fields: OpenAI context_management / compact_threshold / /responses/compact and GPT-5.6 vs earlier cache controls; Claude compact-2026-01-12 / compact_20260112 / pause_after_compaction; xAI /v1/responses/compact and chat.compact(); Gemini Interactions implicit vs Generate Content explicit caching (page updated 2026-09-02). Sampled source URLs resolved (including arXiv 2608.22752). Relative Markdown links in the changed files resolve.

AGENTS.md and docs/threat-model.md are not in this repository. No prior review threads to reconcile.

Ran: git diff --stat on 2372771...7303e65; full read of the 9 changed files; validatePacket / draftClaude and db/schema.ts job/acceptance fields; relative-link check; git ls-remote head confirmation; selected official-doc fetches.

Inspected only: existing .github/workflows/grokcell.yml permissions (contents: read) — this PR does not touch workflows. Did not run pnpm test, apply migrations, or execute PR code.

Open in Web View Automation 

Sent by Cursor Automation: RELAY pull request review

@sdcarlson sdcarlson changed the title Document evidence-based context management for Relay Add researched context playbooks and a verified handoff exercise Sep 6, 2026
@sdcarlson
sdcarlson enabled auto-merge (squash) September 6, 2026 00:00

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Review (subsequent push)

No actionable defects on head a699662 (still matches refs/pull/18/head). This push adds a fictional handoff fixture only. No runtime, schema, migration, or workflow files changed. The prior review on 7303e65 had no findings to re-check. Human approval remains mandatory.

The new fixture matches the adjacent contracts I loaded:

  • packet.json passes validatePacket: relay.packet.v1, nonempty facts (547 chars), integer version 4, and jobKey(url) === key. Extra job.id / job.name match the download shape in app/connections.tsx. Seed jobs use different example.com keys, so this identity does not collide.
  • The documented grok-draft command matches integrations/relay.mjs: packet + draft.txt + exclusive-create output, copies packet.job, sets reviewRequired: true, and does not call a model.
  • For a grok-bot result, draftFromResult accepts only matching job.key + version + URL identity and returns the exact trimmed sample paragraph. Version 5 or a different key is rejected. Packet draft is empty; draft.txt is a separate reference; the checkpoint states no acceptance or submission. Relabeling a future version 5 packet is explicitly forbidden.
  • Relative Markdown links in the changed tree resolve (41 checked).

AGENTS.md and docs/threat-model.md are not in this repository. No prior review threads to reconcile.

Ran: git ls-remote head confirmation; full read of the 7-file delta; executed validatePacket and jobKey on the example packet; relative-link check; contract read of draftFromResult, grok-draft, job/acceptance fields in db/schema.ts, and seed keys.

Inspected only: first-commit docs (claims unchanged); existing .github/workflows (untouched by this PR). Did not execute the grok-draft CLI or pnpm test (this environment is Node 22 without node_modules; the repo requires Node 24). Did not apply migrations or run PR code with secrets.

Open in Web View Automation 

Sent by Cursor Automation: RELAY pull request review

@cursor
cursor Bot force-pushed the docs/context-management branch from a699662 to fc01c2b Compare September 6, 2026 00:19
@cursor
cursor Bot requested a review from sykosyber as a code owner September 6, 2026 00:19

@sykosyber sykosyber left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rebased onto the #14 squash (e037ebf). Unique delta is still the researched context-management guide and the GrokCell README pointer. No application, schema, or workflow changes. Approving the latest push so this can squash-merge once CI is green.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review (subsequent push / rebase)

No actionable defects on head fc01c2ba1617bb29fbb3fcba49d0be2cc9666153 (still matches refs/pull/18/head). Documentation and a fictional fixture only: no runtime, schema, migration, or workflow files changed. Prior reviews on 7303e65 and a699662 had no findings to re-check. No prior inline threads. Human approval remains mandatory.

This head is a rewritten two-commit history onto e037ebf (CI/CD). The latest commit is the same fictional handoff exercise previously reviewed. Adjacent contracts still match:

  • packet.json passes validatePacket: relay.packet.v1, nonempty facts (547 chars), integer version 4, jobKey(url) === key. Extra job.id / job.name match the download shape in app/connections.tsx. Seed keys do not collide.
  • Documented grok-draft argv matches integrations/relay.mjs: packet + draft.txt + exclusive-create output, copies packet.job, sets reviewRequired: true, no model call.
  • For a grok-bot result, draftFromResult accepts only matching job.key + version + URL identity and returns the exact trimmed sample paragraph. Version 5 or a different key is rejected. Packet draft is empty; checkpoint states no acceptance or submission.
  • Playbook claims remain scoped: Claude is one Messages call / end_turn / draft text only; no OpenAI, Gemini, or local-model connector; Grok Bot is a file adapter, not xAI compaction. Templates are not relay.packet.v1 imports.
  • Relative Markdown links in the changed tree resolve (44 checked). AGENTS.md / docs/threat-model.md are on the new base and were read; this PR does not weaken those controls.

Ran: git ls-remote head confirmation; full read of the 15-file PR and the 7-file latest-commit delta; executed real validatePacket + jobKey on the fixture; relative-link check; contract read of draftFromResult, grok-draft, job/acceptance fields, and seed keys.

Inspected only: existing .github/workflows (untouched; CI contents: read). Did not execute the grok-draft CLI or pnpm test (Node 22 here, no node_modules; repo requires Node 24). Did not apply migrations or run PR code with secrets.

Open in Web View Automation 

Sent by Cursor Automation: RELAY pull request review

@sdcarlson
sdcarlson merged commit e0f69c9 into main Sep 6, 2026
17 of 19 checks passed
@sdcarlson
sdcarlson deleted the docs/context-management branch September 6, 2026 00:24
@sdcarlson

Copy link
Copy Markdown
Contributor Author

Merge cleanup inspected the failed Integration (production) job 101399741147 on fc01c2b, run 34001003131, including artifact 9979480944. The failure is scripts/ci/run-production.mjs:222: expected successful owner save 200, received 503. Artifact server log ends after the preceding intentional 403 origin rejection, without a logged successful save. This resembles the previously recorded #13 attempt-1 failure, but root cause is unconfirmed; the docs delta does not change runtime code. Keep the required check blocking until diagnosed or an explicitly recorded unchanged-head rerun passes; do not weaken the save assertion. I have not changed this approved PR head.

sdcarlson pushed a commit that referenced this pull request Sep 6, 2026
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Problem and result

Closes #8
Closes #9
Closes #19

`main` already includes protected CI/CD (#14), context playbooks (#18),
session-expiry (#15 / #7), ChatGPT/Codex public-copy (#13), Apache 2.0
(#39 / #38), and tracker CSV (#11 / #17). This branch merges that tip
and keeps the remaining unique trees:

- Local-dev Node/port/sign-in, with a Windows-safe Node guard instead of
Bash (#12 / #19)
- Copy/paste draft handoffs, exact-acceptance actions, and
dirty-navigation guards (#24)
- Selected-job review history beyond the GET 200-event window (#8)
- Assistant packets for valid jobs with `url: null` (#9)
- Canonical public-copy listing for Tracker CSV (the #11 squash kept
that note outside the maintained block)

Head `4d8f007` merges `origin/main` (`256854b`, #11) into the previous
landing. Conflict resolution kept `void test` wrappers, history/null-URL
API coverage, and one Tracker CSV setup section.

The changes-requested review is on superseded `9e307b9`. Independent
preservation review of `8d6ba1a` retired the five original code
findings. These merges do not restore them.

Deferred, matching maintainer comments, and **not** in this PR:

- Profile calibration loop (#26)
- `shadcn` 4.20.1 (#32)
- Production 503 diagnostics (#22 / draft #40)
- Assistant research/next-task handoff (#37 / #41) — stacked on landed
#13, not this consolidation
- Unused UI-kit cut / competing review-loop draft (#42)

Keep #16 open: remaining development-tool advisories. Keep #21 open
until post-merge Pages verification. Keep #22 open. Cloudflare hosting
(#3), two-account isolation (#4), recruiting (#5), backup rehearsal
(#6), and Grok Bot VM command review (#20) still need human/environment
work.

## Evidence

- Local on `4d8f007`: `pnpm lint`, `pnpm typecheck`, `pnpm test` (98
passed), `pnpm public-copy:check`, `pnpm build`, `pnpm test:api`, `pnpm
test:e2e` (6 passed), `pnpm test:production` passed.
- GitHub CI on `4d8f007` ([run
34003847782](https://github.com/SyberLabs/relay/actions/runs/34003847782)):
quality, API, browser, production, CodeQL, dependency-security, and
bundled agent contracts were running or already green after this merge;
required `CI` still needs the remaining jobs.
- User-visible proof: copy/paste packet, Windows-safe
`scripts/ensure-node.mjs`, Load earlier review history, null-URL
packets. CSV import and ChatGPT/Codex prepare now come from `main`.
- Security, data migration, and rollback impact: no new D1 migration.
React trio stays at 19.2.8. CI Vinext still uses ephemeral ports when
`RELAY_CI_STATE` is set. Production integration keeps the original
request sequence.

## Review

- [ ] One issue owns this scope; unrelated changes are separate. This is
an explicit integration PR covering the remaining open merge train.
- [x] Tests exercise the changed behavior, including failure paths
(including compiled Workspace continuation and history-after-expiry
regressions).
- [x] No credentials, personal applications, or private research are
included.
- [x] Agent findings from the `9e307b9` review remain addressed.
- [ ] A maintainer other than the author will approve. **@sdcarlson must
approve the latest push** (`4d8f007`); prior reviews do not cover this
merge commit.
- [x] Public capabilities, integration limits and lead-engineer credit
match `docs/public-copy.json`; run `pnpm public-copy:check` and follow
`docs/PUBLIC-COPY.md` when these change.

After merge, close the superseded feature PRs (#12, #24) as landed here
rather than squash-merging them separately. #11, #13, #15, and #39 are
already merged. #26 and #32 stay closed as deferred. #40, #41, and #42
stay on their own tracks.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-3877d527-b5e4-46d7-8c5f-573418309ece?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-3877d527-b5e4-46d7-8c5f-573418309ece&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: sykosyber <sykosyber@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants